The History service is designed for long term data storage. Anything capable of communicating with the API Server can potentially access the History worker and record data. It's most commonly used to store data during workflow processes.
What is a History?
A history is a log of events, with a unique id called a key. Each history has one packet of "Subject" data, written at the time the history is created. Histories can have any number of "Event" data packets. Events are added sequentially to the end of a history and cannot be edited or deleted once they have been added.
Histories can be "sealed". A sealed history is switched into a read only mode where no more events can be added.
Histories are immutable. Once data has been written it cannot be edited. While events cannot be edited or deleted, you could handle updates by writing later events that supercede the previous data, and when querying the history always look for the "latest" version. Alternatively a history could be deleted and rewritten as a new history.
How are Histories Created?
Histories are created by default when a workflow process starts. Each time a user interacts with the process, an event is generally added to the history.
You can create single stand-alone histories from form submissions using the History - Write Event action.
You could also use the History Service API directly.
What Data is Stored?
The settings of the Workflow - Start Action and Workflow - Complete Task Action form fields control what data is saved to a history when users interact with a workflow process via forms (by, for example, completing tasks). By default, they do not store a copy of the form submission (ie the form data), but can be set to do so.
There's also a workflow activity that writes directly to history. The data this action stores is set in your workflow process model and could include any data present in the process instance.
The information stored in each event is completely arbitrary. History events could include complete copies of form submissions, which will likely contain personal data from the user who submitted the form.
The conventions we use are summarised in the Conventions - Standardising History Data knowledge base article.
Example History
The history created during a simple workflow process could look something like this. It includes information about every step of our process instance:
- The subject and first event were written when the process was started by a form submission. The first event includes a copy of the form data
- Events two and three show a staff member, TIMADMIN, claiming the workflow task and submitting a response
- The fourth event records the process ending
Because this history collects data from form submissions there's the potential for personal data, even special category data (as defined by the GDPR), to be recorded.
{
"labela": "Example Process",
"labelb": "0717-6739-1689-9689",
"labelc": null,
"labeld": null,
"labele": null,
"created": 1652187829557,
"sealed": true,
"subject": {
"processDefinitionId": "exampleprocess:6:255004",
"description": "Example Process",
"proxyUserId": null,
"userId": "TIMG",
"processDefinitionKey": "exampleprocess"
},
"events": [{
"pos": [1, 4],
"event": {
"private": false,
"proxyUserId": null,
"description": "Process Started",
"formData": {
"data": {
"QUERY": "When is my parcel going to be delivered?",
"EMAIL": "support@gossinteractive.com",
"NAME": "Tim"
},
"formName": "STARTEXAMPLEPROCESS",
"typeName": "FORM_STARTEXAMPLEPROCESS",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "STARTWORKFLOW",
"userRole": "user",
"userId": "TIMG"
},
"timestamp": 1652187829557
}, {
"pos": [2, 4],
"event": {
"taskDefinitionKey": "staff-response-1",
"private": true,
"description": "Task 255033 claimed for user \"timadmin\"",
"proxyUserId": null,
"event": "CLAIMTASK",
"userRole": "workflowengine",
"userId": "TIMADMIN",
"taskId": "255033"
},
"timestamp": 1652187853983
}, {
"pos": [3, 4],
"event": {
"taskDefinitionKey": "staff-response-1",
"private": false,
"description": "Respond to: When is my parcel going to be delivered?",
"proxyUserId": null,
"formData": {
"data": {
"QUERY": "When is my parcel going to be delivered?",
"RESPONSE": "It's been shipped and should be with you on Tuesday afternoon"
},
"formName": "COMPLETEEXAMPLEPROCESS",
"typeName": "FORM_COMPLETEEXAMPLEPROCESS",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "COMPLETETASK",
"userRole": "user",
"userId": "TIMADMIN",
"taskId": "255033"
},
"timestamp": 1652187888643
}, {
"pos": [4, 4],
"event": {
"private": false,
"description": "Process Ended",
"proxyUserId": null,
"event": "PROCESSENDED",
"userRole": "workflowengine",
"userId": null
},
"timestamp": 1652187889610
}]
}
Share this page
