This field starts an instance of a workflow process when the page it is on is submitted. Values from the form are passed to the workflow engine as process variables.
You can manipulate the variables that are passed to the workflow, record a history of the form submission, and return information from the started process, like the business key, back to the form.
Properties
| Label | Description | Type Name |
|---|---|---|
| Process Definition | Pick the process that should be started when the form is submitted. You can pick a full workflow ID (a specific version to start) or always start the latest version | WFNAME |
| Success Message | The text to display when workflow starts successfully. The value of another field can be used by adding the field's name between # characters. #PROCESSID#, #BUSINESSKEY# are special tokens that will return the processID set in the modeller and the ID of the instance that started. #BUSINESSKEY# is often returned to the user as a reference number | SUCCESSMESSAGE |
| Failure Message | The text to display if the workflow fails to start. If you enable debug mode in the form settings you'll see the full error message from the Workflow worker | FAILUREMESSAGE |
| Ineligible Failure Message | The text that will be displayed if the current site user is not eligible to start the process (ie is not a candidate set in the workflow model) | INELIGIBLEFAILUREMESSAGE |
| Process Variables Function | A server-side JavaScript function that can manipulate the process variables generated by the form before the workflow is started. This is most commonly used to add or remove process variables. See below for some examples. Note that this function updates process variables, nothing else | VARIABLESFUNC |
| Record History | If true, a history will be created for the workflow and a history event will be recorded when the form is submitted. If this property is not enabled the workflow will not record any history | RECORDHISTORY |
| Store Form Data in History | If true, data submitted with the form will be stored in the first history event | STOREFORMDATA |
| History Event Settings | A server-side JavaScript function that can set the information stored in the history event. See below for more information | HISTORYEVENTFUNC |
| Create Self-service Summary | Generate a summary history event that may be used by the Self Service and User Requests products. For more information about summary events, see History Events and Summary Events. Summaries are only generated if "Record History" is enabled. The options for when summaries are generated are: start and end, start only, end only, none at all. Summaries may still be generated and added to the history by other user tasks in the workflow process. Summaries include a copy of the form data, including references to uploaded files in the file store | CREATESUMMARY |
| Summary Form Name | The form that will be used to display summary data for this workflow. Defaults to the name of the start form if not supplied. The fields of the summary form (whether this form or another one) also control whether or not the process variables the form creates are indexed in the search collection, ie only fields set as searchable also have the resulting process variables indexed | SUMMARYFORMNAME |
| Reporting Fields | Pick the fields that should be stored for reporting purposes. Selecting one or more fields generates a "reporting" history in addition to the standard history. See the Labelc Histories and Reporting Data article in the knowledge base for more information | REPORTINGFIELDS |
| Subject Description | The description property of the history's subject. The tokens | SUBJECTDESCRIPTION |
| Stop Processing on Error | If true, and an error is encountered, further action fields on the form won't be processed. See The Form Lifecycle: Control and Action Processing for more information | STOPPROCESSINGONERROR |
| Documentation | Add documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an example | DOCUMENTATION |
Action Results
The following can be accessed using .utilGetActionResults once the action has been processed.
"FIELDNAME": {
"processInstanceId": "130477",
"businessKey": "9824-8513-6759-4348",
"success": "true"
}
"FIELDNAME_CONF": {
"MESSAGE": "The process was started successfully, your reference is 9824-8513-6759-4348",
"success": "true"
}
When the start action completes successfully the process ID and business key can be accessed in the "success message" displayed to the user using
The process ID and business key are also returned to the form in a helper variable, which could be accessed in any server-side actions placed after the workflow start action in your form. This variable is made up of the field name suffixed by
"FIELDNAME_STARTED": {
"processId": "90211",
"businessKey": "2063-5248-5212-6230"
}
You could access this variable in the DATA function of the email action field:
And then add the result to the email body or PDF in the Handlebars template:
<table class="icmformdatapagetable">
<tbody>
<tr>
<td colspan="2" class="icmformdatacontainer">Label</td>
</tr>
<tr>
<td class="icmformdatalabel">Text 1</td>
<td class="icmformdatavalue">{{FIELD "TEXTINPUT"}}</td>
</tr>
<tr>
<td class="icmformdatalabel">Your Reference</td>
<td class="icmformdatavalue">{{DATA.businessKey}}</td>
</tr>
</tbody>
</table>
Which would generate:
History
When this field starts a process instance it can also create a record in the platform's history service. New events can be added to the history as your process runs its course.
If you tell this field to record history, and to create a self service summary, the history that gets written will look something like this (note that some properties, like timestamps and event positions, have been removed for simplicity):
{
"labela": "Example Process",
"labelb": "5061-3616-3420-1790",
"labelc": null,
"subject": {
"processDefinitionId": "example:4:40089",
"description": " Example Process",
"proxyUserId": null,
"userId": "TIMG",
"processDefinitionKey": "example"
},
"events": [{
"pos": [1, 2],
"event": {
"private": false,
"proxyUserId": null,
"description": "Process Started",
"event": "STARTWORKFLOW",
"userRole": "user",
"userId": "TIMG"
}
}, {
"pos": [2, 2],
"event": {
"private": false,
"historyDescription": "Example Process",
"description": "Summary",
"proxyUserId": null,
"formData": {
"data": {
"FIELD4": "TEST",
"RADIOGROUP": "1"
},
"formName": "WORKFLOWFORM1",
"typeName": "FORM_WORKFLOWFORM1",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "SUMMARY",
"userRole": "workflowengine",
"userId": null
}
}]
}
The history labels are the name of the process instance that started and its business key. Labelc is null.
The history subject is generated automatically. It includes the user who submitted the form, with other details taken from the workflow process.
The first event shows the standard properties that, by convention, we expect every history event to contain. You can manipulate what gets stored using the field's "History Event Settings" property. If you enable the "Store Form Data in History" setting, a copy of the form data will be stored, along with the name of this form, so the data can be shown in read-only views (eg the event lists in Self Service and User Requests).
The standard event properties (matching the history above) are:
The tokens
The second event is a summary event. Note that it always stores a copy of the form data. You can control when summaries are written using the "Create Self-service Summary" drop-down.
Reporting Histories
A reporting history is an additional history, written alongside the main history, designed to hold data that you might want to keep for long term reporting purposes. They mustn't contain any personal data, and could be limited to dates/times, perhaps a location, or a record of why the process was started. There more information about how we use these histories in Labelc Histories and Reporting Data.
If you don't pick any fields in the "Reporting Fields" property, one won't be written. If you do, the value of the chosen field is stored. The history will look like this:
{
"labela": "Chained Tasks",
"labelb": "5061-3616-3420-1790",
"labelc": "reporting",
"labeld": null,
"created": 1593170149697,
"sealed": false,
"subject": {
"description": "Chained Tasks"
},
"lastupdated": 1593170149697,
"events": [{
"pos": [1, 1],
"event": {
"formName": "WORKFLOWFORM1",
"description": "Workflow start",
"RADIOGROUP": "1"
},
"timestamp": 1593170149697
}]
}
Labels a and b are the same as the main history, labelc is "reporting". Note the simplified subject and how all user information has been removed from the subject and events.
Process Variables
By default the fields and values submitted with your form are passed to the workflow engine as process variables. The process variables function lets you manipulate the variables that are created.
For example, the following will remove a specific process variable from the map:
You can also create process variables. This example is taken from the GOSS Contribute product:
function(helper, processVars) {
processVars.CONFIGNAME = "contributeevent";
// Additional tasks
processVars.ADDITIONALTASKS = [{
"form": "CONTRIBUTE",
"name": "Contribute Event"
}, {
"form": "PRICES",
"name": "Default Prices"
}];
return processVars;
}
Data Types
Form fields always submit their values back to the server as strings, which means the values of your process variables will also be strings. Take care when manipulating process variables server-side or updating the values of fields using .setFieldValue - the values you set should also be strings.
Having said that, it is possible to create and pass JavaScript objects to a workflow process using the prefix
For example, this function would create two new variables.
function(helper, processVars) {
processVars.new = "test";
processVars.js_objectExample = {
"key": "value"
};
return processVars;
}
See Creating and Updating Process Variables in the workflow knowledge base for more information.
Search Indexing
Process variables are only indexed in the platform's search collections if the form fields that created them are set as "searchable" in the summary form used to display data for the process instance. In most cases that will be the same form that started the process (ie the form that has this field on it) but you can pick a different form in the start action field.
File References
By default, when a workflow starts, any files uploaded with the form are passed to the process instance as file references. See File Uploads and Email Attachments in Workflow for more information.
If you don't want the workflow to keep any file references (so they will only be available when processing the initial workflow action when the form is submitted) use the process variables function to set
Share this page
