This article looks at how data can be stored by the History Worker during the lifetime of a workflow process instance.
A very basic form starts the example workflow process. The process itself includes a mail task, a history task and a user task. The final user task completes the process.
You will be able to see how a history is created when the process starts, is written to after the mail task completes, and is updated when the final user task ends the execution. A full export of the history is included below.
You can read about the ways in which histories are displayed in some of our standard products in the History Events and Summary Events article.
The "Start" Form
Our form includes a single text field called TEXT1, a submit button and a Workflow - Start Action field.
The workflow action has the following settings.
| Property | Value | Notes |
|---|---|---|
| Record History | true | Setting this as true does two things. A history is created and an event is written to that history recording the form submission |
| Create Self-service Summary | true | This will create a self-service summary event when the form is submitted (you also need to have Record history: true for this to do anything). Summary events always store a full copy of the form data |
| Subject Additional Properties | blank | A JavaScript function that can add other properties to the subject data. There's information about including additional properties in the Recording History from Stand-Alone Forms article |
| Event | STARTWORKFLOW | The name of the start event that will be recorded in the history |
| Event Description | Process Started | The description of the start event that will be recorded in the history |
| Event User Role | user | History events can record the role of the user who generated them, which can later be used for filtering. Common values are "staff", "citizen", "user", "agent" |
| Event Private | false | Whether templates like Self Service and User Requests should treat this as a private event, hidden from users |
| Event Additional Properties | blank | A JavaScript function that can add other properties to the event |
| Store form data | true | The data from this form submission will be stored inside the history event. Storing this data means it can be displayed in products like the Self service and User Request templates |
| Form Name | blank | If you are storing form data then this form will be used to display the data when it is retrieved by the Self Service and User Requests templates. Leave blank to use the form that created the history |
The Process Model
In our model we have a simple mail task (which does not record history), an API Server history task, and a user task. The user task records a history event when its form is submitted via its Complete Task action field.
History Task
Leaving all the label values in the history task blank will add a new event to the history that was created when the process instance started. Setting new label values would create a new history.
The event in the history task is a JSON object which includes the standard properties recommended in Conventions - Standardising History Data, plus an additional property,
{
"userId": "#initiator#",
"proxyUserId": "#_initiatorProxy#",
"userRole": "customer",
"event": "Mail Sent",
"description": "The email has been sent",
"valueFromForm": "#form_TEXT1#",
"private": false
}
The Task Form
The user task form includes a Workflow - Complete Task action and a single text field called TEXT2. The action field has the following settings:
| Property | Value | Notes |
|---|---|---|
| Record History | true | We want to record this task as an event in the history |
| Event | COMPLETETASK | The name of the new event |
| Event Description | #TASKDESCRIPTION# | This token will record the task description set in the workflow model in the history |
| Event User Role | user | History events can record the role of the user who generated them, which can later be used for filtering. Common values are "staff", "citizen", "user", "agent" |
| Event Private | false | Whether templates like Self Service and User Requests should treat this as a private event, hidden from users |
| Event Additional Properties | blank | A JavaScript function that can add other properties to the event |
| Store form data | true | The data from this form submission will be stored inside the history event. Storing this data means it can be displayed in products like the Self service and User Request templates |
| Form Name | blank | If you are storing form data then this form will be used to display the data when it is retrieved by the Self Service and User Requests templates. Leave blank to use the form that created the history |
| Update Self-service Summary | true | Create a new summary event for this history. Updated summary events combine the form data saved in previous summary events with any new form data generated by the form submission |
The History
Below you can see the full history and the events created by the two form submissions and history task.
Key points to note are:
- labela and labelb - These are the name and the business key of the process instance
- subject - Subject data is written when the history is created. The properties in the example below are the defaults (the description is the name of the workflow process). Additional properties can be added via the Workflow - Start Action field
- sealed - True because the instance has completed. This would have been false while the instance was active
- events - Six events have been logged:
- The form submission that started the process, including the form data. Compare these values to the settings of the action field above
- The workflow history task. Note how the ## placeholders have been expanded
- A summary event, generated by the workflow engine because our start form was set to create a summary
- The user claiming the task. This private event is written by the workflow engine
- The user task form submission, written when the task was completed
- Another summary event. Note how the form data has combined the new form data and the previous summary
- The end event generated by the workflow engine. The default is "Process Ended" but can be set using the
_finalHistoryDescription process variable
Note how most of the events have "private" set as false. This means that all events will be visible on the Self Service and User Requests templates. Events can be set as
Private history events called CLAIMTASK and RELEASETASK are logged in the history each time a user claims or unclaims a task.
{
"id": "7e379730-0d12-4644-bbb6-cdbdbaa2bb15",
"labela": "Recording History",
"labelb": "5098-4776-2543-9371",
"labelc": null,
"labeld": null,
"labele": null,
"created": 1538038456333,
"lastupdated": 1538038490743,
"sealed": true,
"subject": {
"processDefinitionId": "recordinghistory:7:87504",
"description": "Recording History",
"proxyUserId": null,
"userId": "ANONYMOUS",
"processDefinitionKey": "recordinghistory"
},
"events": [{
"pos": [1, 7],
"event": {
"private": false,
"description": "Process Started",
"proxyUserId": null,
"formData": {
"data": {
"TEXT1": "Test text"
},
"formName": "FORMTOSTARTASIMPLEPROCESS",
"typeName": "FORM_FORMTOSTARTASIMPLEPROCESS",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "STARTWORKFLOW",
"userRole": "user",
"userId": "ANONYMOUS"
},
"fpos": [1, 7],
"timestamp": 1538038456487
}, {
"pos": [2, 7],
"event": {
"description": "The email has been sent",
"proxyUserId": "",
"valueFromForm": "Test text",
"event": "Mail Sent",
"userRole": "customer",
"userId": "anonymous"
},
"fpos": [2, 7],
"timestamp": 1538038458687
}, {
"pos": [3, 7],
"event": {
"private": false,
"historyDescription": "Recording History",
"description": "Summary",
"proxyUserId": null,
"formData": {
"data": {
"TEXT1": "Test text"
},
"formName": "FORMTOSTARTASIMPLEPROCESS",
"typeName": "FORM_FORMTOSTARTASIMPLEPROCESS",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "SUMMARY",
"userRole": "workflowengine",
"userId": null
},
"fpos": [3, 7],
"timestamp": 1538038459467
}, {
"pos": [4, 7],
"event": {
"taskDefinitionKey": "sid-98B2E11C-33A6-4C26-AAE3-16E8A8F6037E",
"private": true,
"description": "Task 87531 claimed for user \"TIMG2\"",
"proxyUserId": null,
"event": "CLAIMTASK",
"userRole": "workflowengine",
"userId": "TIMG2",
"taskId": "87531"
},
"fpos": [4, 7],
"timestamp": 1538038470080
}, {
"pos": [5, 7],
"event": {
"taskDefinitionKey": "sid-98B2E11C-33A6-4C26-AAE3-16E8A8F6037E",
"private": false,
"description": "Complete Process",
"proxyUserId": null,
"formData": {
"data": {
"TEXT2": "Test response"
},
"formName": "FORMTOENDASIMPLEPROCESS",
"typeName": "FORM_FORMTOENDASIMPLEPROCESS",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "COMPLETETASK",
"userRole": "user",
"userId": "TIMG2",
"taskId": "87531"
},
"fpos": [5, 7],
"timestamp": 1538038490080
}, {
"pos": [6, 7],
"event": {
"private": false,
"historyDescription": "Recording History",
"description": "Summary",
"proxyUserId": null,
"formData": {
"data": {
"TEXT1": "Test text",
"TEXT2": "Test response"
},
"formName": "FORMTOSTARTASIMPLEPROCESS",
"typeName": "FORM_FORMTOSTARTASIMPLEPROCESS",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "SUMMARY",
"userRole": "workflowengine",
"userId": null
},
"fpos": [6, 7],
"timestamp": 1538038490620
}, {
"pos": [7, 7],
"event": {
"private": false,
"description": "Process Ended",
"proxyUserId": null,
"event": "PROCESSENDED",
"userRole": "workflowengine",
"userId": null
},
"fpos": [7, 7],
"timestamp": 1538038490743
}]
}
Workflow Summary Events
In the example above all of the form actions were set to also create summaries events. These summaries are just history events, but they have an event name of SUMMARY. They include a record of the user-visible form variables (those that start
Summaries act as a record of the state of the workflow once a form submission has been processed, rather than a record of the form submission itself.
See History Events and Summary Events for more information.
Share this page
