When you're working with workflow processes you'll generally start process instances by submitting a form that contains the start-workflow action field type.
It's possible to start instances in other ways too. Once deployed they can be started by timers, signals and messages.
In this example we'll look at how you can start a process instance via an end point using the Workflow worker's startProcess method.
The End Point
This end point provides a generic starting point that can be used to start a process instance. Many of the properties included in the processParams are not necessary, and probably don't make very much sense in this context. These are discussed below.
function( params, credentials ) {
let response = {success:false};
try{
var processParams = {
"variables": params.variables,
"userId": params.userName,
"fileReferences": {},
"replaceExistingFiles": false,
"historyRecording": {
"labels": {
"labela": "${PROCESSNAME}",
"labelb": "${BUSINESSKEY}"
},
"subject": {
"description": "${PROCESSDESCRIPTION}",
"userId": params.userName,
"proxyUserId": null
},
"event": {
"event": "STARTWORKFLOW",
"description": "Process Started",
"userRole": "user",
"userId": params.userName,
"proxyUserId": null,
"private": false
},
"storeFormData": false,
"formName": params.formName,
"logSubmission": true,
"logSummary": true
},
"processDefinition": params.processDefinition,
"credentials": null
};
let startProcessResponse = this.callWorkerMethod("workflow", "startProcess", processParams);
if (startProcessResponse.businessKey){
response.success = true;
response.businessKey = startProcessResponse.businessKey;
}
} catch (e){
response.message = "There has been a problem "+ JSON.stringify(e);
}
return response;
}
Supplied Parameters
The following parameters may be provided.
| Parameter | Type | Description |
|---|---|---|
| userName | String, required | Every process instance must be linked to a site user who started it. The startProcess method requires a userId, which is actually the website user's username |
| processDefinition | String, required | The name of the process definition, an instance of which you'd like to start (just providing the name will start the latest version) |
| formName | String, optional | When a form is used to start an instance its name is included in the _startForm process variable. It's also needed if we're storing the data of the form. As this instance isn't being started by a form, it can be left out (unless your intention is to create an instance that appears to have been started by a particular form) |
| variables | Object, optional | |
| variables._startPageURL | String, optional | When a form is used to start an instance its URL is recorded in the _startPageURL process variable |
| variables._startForm | String, optional | As per formName above |
| variables._summaryForm | String, optional | Summary forms are used by products like Self Service and User Requests to display summaries of form data. Provide a name here if you would like to view the process variables of your instance in these products. The names of your form fields will have to match those of the process variables you create. See History Events and Summary Events for more information |
| variables.form_N | String, optional | The values of form fields are stored as process variables named form_FIELDNAME. You can, of course, name your process variables however you'd like when starting a process instance via an end point |
For example, we could reduce the supplied parameters to:
{
"userName": "myUser",
"processDefinition": "myProcess",
"variables": {
"myVariable": "myValue",
"_summaryForm": "VIEWMYDATA"
}
}
fileReferences
In the example above an empty file references object has been included. A file reference object has the following format, with the id that generated by the filestore worker.
{
"form_FILEUPLOAD": [
{
"id": "8E8F9EE4-DAB8-4A34-BA7D-0D9648291CA0",
"filename": "handlebars.PNG"
}
],
"form_FILEUPLOAD2": [
{
"id": "4A243AED-FE57-4CDF-9982-6786D1F3E8E8",
"filename": "hot-air.jpg"
}
]
}
History
When a process instance starts it automatically creates a corresponding history. The example end point above conforms to our standard conventions.
As the instance is started and then the history is written, we're able to access the workflow process variables ${PROCESSNAME}, ${BUSINESSKEY} and ${PROCESSDESCRIPTION}.
Share this page
