Skip to main content
Matrix42 Self-Service Help Center

Workflow Public API

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]  Guid 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 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 asynchronious operation. The operation ID can be used in Service "GET api/backgroundprocess/{id}" to obtain the actual state of the operation Guid
OperationName Display name of the operation String
Completed Indicates the operation is completed already. 
Not present in a response when 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

The example demonstrates how to start "1 Step Approval (Default Role) " Workflow (object ID = 43e6aa0d-d246-4798-a450-41b0399d37d6) to initiate 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']}');

Resume Workflow

Resumes execution of a previously suspended workflow instance.  The method could be used for resuming all kind of instances regardless on a way it has been suspended, but more reasonable use it for workflows suspended by "Create Bookmark" Activity,  whereas use  Public API Activity Close method (e.g. Close Task ) for Workflows were suspened 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.
Guid  
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.
Guid  
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 which has been suspended with the Create Bookmark activity, and after receive the custom data in the Workflow Instance after resume in variable ResumedData (2)

clipboard_ef823a69a11e079c5ba81a87fab984de4.png

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.

  • Was this article helpful?