Workflow Public API

+ More

Table of Contents

Overview Start Workflow Request URL attributes Headers POST body Response Status codes and errors Example 1: Start Approval Workflow Example 2: Start Workflow with complex Input parameters Resume Workflow Request URL attributes Headers Response Status codes and errors Example Terminate Workflow Request URL attributes Headers Response Cancel Workflow Request URL attributes Headers Response

Overview

The article introduces the present Public API methods for handling operation with the Workflows

Start Workflow

Begins the execution of a Workflow Instance. The operation executed asynchronously, what means the Workflow Instance is not created instantly during the method execution, but the start command sets to the Queue, and waits until the Workflow Engine has a capacity to process it.

Request

POST https://{server_name}/m42Services/api/workflow/start/{workflowid}

URL attributes

Argument Description Type Required
workflowId ID of the Workflow object to start. PLSLXamlComponentClassBase.[Expression-ObjectID]  Guide Required

Headers

For a list of available HTTP request headers see Web Services: REST API integration.

POST body

Input argument values for Workflow Instance, defined as JSON object, where each property represents the input argument

{
   "param1": "cf060d4d-5c47-462f-b5d1-7df6c865fd91",
   "arrayIntParam": [1, 2, 45]
}

If needed, it is possible to explicitly set IDs for the created Object or related fragments. If IDs are omitted in the Request, they are auto-generated.

Response

The operation returns the marker of the asynchronous operation, which could be used further for tracking the operation status

Element Description Type
OperationId Unique identifier of the asynchronous operation. The operation ID can be used in Service "GET api/backgroundprocess/{id}" to obtain the actual state of the operation Guide
OperationName Display name of the operation String
Completed Indicates the operation is completed already. 
Not present in a response when the value is 'False'		 Bool

Status codes and errors

Code Message
401 Unauthorized
415 The request Content-type is not defined
500 Internal Server Error. E.g. wrong reference, or mandatory attribute is missing 

Example 1: Start Approval Workflow

The example demonstrates how to start "1 Step Approval (Default Role) " Workflow (object ID = 43e6aa0d-d246-4798-a450-41b0399d37d6) to initiate the Approval process for a pair of bookings

var svchttp = new XMLHttpRequest();
svchttp.open('POST', 'http://{serverurl}/M42Services/api/workflow/start/43e6aa0d-d246-4798-a450-41b0399d37d6', true);
svchttp.setRequestHeader('Authorization', 'Bearer ' + {token});
svchttp.onreadystatechange = function() {
  if (this.readyState == 4 && this.status == 200) {
    if(this.responseText!==null){
        console.log(console.log('Not valid or disabled API token'));
    }
    else {
        console.log('Not valid or disabled API token')
    }
  }
};
svchttp.send('{bookings:['0E756F28-3A64-4430-9814-97CB9C42E05B', '091C8DC3-117C-4286-9E6A-47BF6B8E576A']}');

Example 2: Start Workflow with complex Input parameters 

By default, a Workflow accepts only simple data type parameters (such as String, Integer, DateTime, etc.) or arrays of simple data types.
An exception to this rule exists for certain known types, such as the ObjectActionContext parameter.

To work around this limitation, complex data can be passed to a Workflow as a JSON-formatted string, which can then be parsed within the Workflow into a JsonObject /JsonArray.

1. Send Request with string parameter in JSON format

POST https://{server}/m42Services/api/workflow/start/{workflow_id} HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/json;charset=UTF-8

{"jsonArg":"{\"Name\":1,\"Values\":[1,2,3]}"}

2. Parse Input parameter to JSON Object

Use the Variable or Assign Workflow activity to parse input argument to JsonObject

CType(JsonValue.Parse(jsonArg), JsonObject)

3.  Use JSON API to get data

CStr(jsonObjArgument("Name"))

Resume Workflow

Resumes execution of a previously suspended workflow instance.  The method could be used for resuming all kinds of instances regardless of the way it has been suspended, but it is more reasonable to use it for workflows suspended by "Create Bookmark" Activity, whereas use Public API Activity Close method (e.g. Close Task ) for Workflows that were suspended with "Wait For Activity"

Request

GET https://{server_name}/m42Services/api/workflow/resume?bookmarkid={bookmarkid}&inputdata={inputdata}&objectid={objectid}

URL attributes

Argument Description Type Required
ObjectId ID of the related Object, which refers to the object which is waited by the Workflow (e.g. Task object for 'Wait for Activity'). 
Either ObjectId or Bookmark must be specified.		 Guide  
BookmarkId Id of the Workflow Instance Bookmark (PLSLWorkflowBookmarkClassBase.ID). The BookmarkId can be implicitly set to "Create Bookmark" Activity, property Bookmark Key. And then can be used for resume. 
Optional, if the argument ObjectId is used.		 Guide  
InputData A data passed as a parameter to the Workflow Instance when the bookmark resumes. In case of "Create Bookmark" the InputData is assigned to property "Resumed Data" String  

Headers

For a list of available HTTP request headers, see Web Services: REST API integration

Response

Boolean. True, if the Workflow was successfully resumed.

Status codes and errors

Code Message
401 Unauthorized
415 The request Content-type is not defined
500 Internal Server Error. E.g. provided ObjectID or BookmarkID is not found 

Example

The example demonstrates how to resume a workflow that has been suspended with the Create Bookmark activity, and after receiving the custom data in the Workflow Instance after resume in variable ResumedData (2)

To locate the affected Workflow instance in the example we use the Bookmark which has been specified on suspend (1)

var svchttp = new XMLHttpRequest();
svchttp.open('GET', 'http://{serverurl}/M42Services/api/workflow/resume?bookingId=0E468CF3-5C92-47BD-9954-E65EEE238AA9&inputData=customData', true);
svchttp.setRequestHeader('Authorization', 'Bearer ' + JSON.parse(this.responseText).RawToken);
svchttp.send();

Terminate Workflow

Terminates the workflow instance. 

Request

PUT https://{server_name}/m42Services/api/workflowinstance/{instanceid}/terminate

URL attributes

Argument Description Type Required
instanceId Id of the Workflow Instance object PLSLWorkflowProcessInstanceClassBase.[Expression-ObjectID] Guid Required

Headers

For a list of available HTTP request headers see Web Services: REST API integration.

Response

Nothing.

Cancel Workflow

Cancels the workflow instance. 

Request

PUT https://{server_name}/m42Services/api/workflowinstance/{instanceid}/cancel

URL attributes

Argument Description Type Required
instanceId Id of the Workflow Instance object PLSLWorkflowProcessInstanceClassBase.[Expression-ObjectID] Guid Required

Headers

For a list of available HTTP request headers see Web Services: REST API integration.

Response

Nothing.

Related Articles