Toggle menu

Start a Workflow from an End Point

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.

ParameterTypeDescription
userNameString, requiredEvery 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
processDefinitionString, requiredThe name of the process definition, an instance of which you'd like to start (just providing the name will start the latest version)
formNameString, optionalWhen 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)
variablesObject, optional 
variables._startPageURLString, optionalWhen a form is used to start an instance its URL is recorded in the _startPageURL process variable
variables._startFormString, optionalAs per formName above
variables._summaryFormString, optionalSummary 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_NString, optionalThe 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}.

Last modified on August 02, 2023

Share this page

Facebook icon Twitter icon email icon

Print

print icon