This action is used on task forms in a workflow. The data captured by the form is returned to the workflow engine (each field creates a process variable with the same name as the field) and the task is completed, progressing the execution to the next stage in the process.
Properties
| Label | Description | Type Name |
|---|---|---|
| Success message | The text to display when the task completes successfully | SUCCESSMESSAGE |
| Replace special characters | Protects against workflow property injection by replacing the special characters | REPLACESPECIALCHARACTERS |
| Failure message | The text to display if the workflow fails to start | FAILUREMESSAGE |
| Exclude read-only fields | Exclude read-only fields from the submitted process variables. When a form includes a workflow action, the fields on the form are included as process variables in the corresponding workflow process instance. If this property is set to true, read-only fields will not be included. This setting can be useful when you want to display some information on a workflow form that you don't want to be included in the resulting process instance | EXCLUDEREADONLYFIELDS |
| Exclude non-storing fields | Exclude non-storing fields from the submitted process variables, in the same way as read-only fields described above | EXCLUDENONSTORINGFIELDS |
| Process variables function | A server-side JavaScript function that can manipulate the process variables generated by the form before the workflow action is performed. This is most commonly used to dynamically create process variables. The function is executed server-side only. See below for some examples. Note that this function updates process variables, nothing else | VARIABLESFUNC |
| Keep file references | Controls whether or not the workflow retains references to any uploaded files. When a workflow form is rendered using the Forms Service and the form includes upload fields, the workflow process instance will, by default, retain references to any uploaded files so that they remain available to the workflow process for as long as it is running. If the same workflow form is submitted twice, the default behaviour is to release the reference to the file that was uploaded first. If both files should remain accessible to the workflow, select the "Keep references (add to existing)" setting for this field. 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) select "Don't keep references" | KEEPFILEREFERENCES |
| Record History | If true, a history will be created for the workflow and a history event will be recorded when the form is submitted | RECORDHISTORY |
| Event | A short one or two word phrase that describes the event. If no value is supplied the string "Form Submission" will be used. The value of another field can be used by adding the field's name between # characters, eg "#EMAILADDR#". This must be the complete field name when an external type definition is used. This can be obtained by hovering the mouse over the required field | EVENTEVENT |
| Event Description | A more detailed human readable description of the event. If no value is supplied form's description will be used. The value of another field can be used by adding the field's name between # characters. The tokens | EVENTDESCRIPTION |
| Event User Role | Name of the role the user was performing as when they triggered the event. For example, "customer". The value of another field can be used by adding the field's name between # characters | EVENTUSERROLE |
| Event Private | If true, this event will be marked as private. The Self Service and User Requests products contain configuration options that can show or hide private events. The value of another field can be used by adding the field's name between # characters | EVENTPRIVATE |
| Event Additional Properties | Optional. A function that can be used to either add new properties to, or overwrite existing properties within, the event object. To add additional properties, return a JSON object from this function. To override existing properties, return a JSON object that includes one or more elements with the same name as an existing property. See Adding and Overriding Properties below | EVENTADDITIONALPROPERTIES |
| Store Form Data | If true, data submitted with the form will be stored within the event. A form could later be populated with this data and displayed to the user as a summary | STOREFORMDATA |
| Form Name | If Store Form Data is true, this is the name of the form that will be used to display the data. Defaults to the name of the current form if not supplied | FORMNAME |
| Update Self-service Summary | Generate a new self service summary event for this history. See History Events and Summary Events for more information about summary events | UPDATESUMMARY |
| Reporting Fields | Select one or more fields to generate/update a "reporting" history. This is an additional history created alongside the standard history, with a labelc value of "reporting". You can write a reporting history even if the main "Record History" property is set as false Pick the fields whose values you'd like to store in the history. Do not pick any fields that may contain personally identifiable information - otherwise you'll invalidate the whole point of creating a "reporting" history. See the reference Labelc Histories and Reporting Data article for our conventions and below for an example | REPORTINGFIELDS |
| Debug mode | Whether to enable debug mode for this field. This is automatically enabled if the form debug panel is displayed. Set to true to display the actual error reported from the Workflow Worker instead of the standard failure message | DEBUG |
| 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": {
"success": "true"
}
"FIELDNAME_CONF": {
"MESSAGE": "Task completed successfully",
"success": "true"
}
Adding Additional History Properties
Rather than providing static values in the forms designer for event properties, you can instead build them programmatically. To add additional properties to the event written by this action, return a JSON object from the event additional properties function:
function(helper) {
var additionalProps = {};
additionalProps.additionalPropertyKey = "additionalPropertyValue";
additionalProps.totalCost = parseInt(helper.getFieldValue('PRICE')) * parseInt(helper.getFieldValue('QUANTITY'));
return additionalProps;
}
Overriding Properties
To override a standard property, include a property with the same name in your JSON object. The following property names can be overridden:
- event (the event name)
- description
- userRole
- userId
- proxyUserId
- historyDescription (used in SUMMARY events)
- private (note that this must be a boolean, not a string, so the value of another field cannot be used directly)
For example, to override a description with the value of a field:
function(helper) {
var additionalProps = {};
additionalProps.description = helper.getFieldValue("TEXT1");
return additionalProps;
}
Or to dynamically set the privacy setting of the event:
Manipulating 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.
Share this page
