The History Service provides a very flexible way of storing data. So flexible that we decided to apply some standard conventions to the way we store history data from our solutions and applications.
As a general rule you can store additional data in any part of a history, but should should always include the properties listed below, even if left blank.
Key
Every history has a unique key. This key is made up of at least one, and up to five, parts, called labels. Developing a standard labelling convention makes writing and retrieving histories easier.
Each history label has a 50 character limit. In practice this means you can use 48 characters, as the value you write will be wrapped in quotes.
We've decided upon the following as a minimum:
Label A: The service name. If a workflow is called "Customer Enquiry" so is the first label in its history. By default histories written by a workflow process use the process name as the labela value. Histories written by the "Write Event" form action use the form name.
Label B: A unique identifier. In the case of a workflow, the process business key is used. Histories written by the form action can generate a unique identifier similar to a workflow business key using "#UNIQUE_ID#" in the labelb property of the field.
Labels C-E: These optional fields are free to be defined by the developer. Note that the Self Service and User Requests templates will only display histories that have labela and labelb values, and label c-e values that are null. This is to avoid duplicate entries appearing when following our Labelc Histories and Reporting Data conventions.
Subject
The subject data packet is only written once to a history. Further attempts to use the subject parameter when writing to a history that already exists will be ignored. Our standard subjects are made up of:
userId: The identity (site user account) of the user performing the action that created this history. This could be the initiator of a workflow process or a value from a form submission. In many cases this will be a GUID.
proxyUserId: If an action is being performed by an agent acting on behalf of another person using the Assisted Service template, the identity of the agent who is performing the action is recorded as the proxyUserId. The identity of the user in whose name the action is being performed is still stored as the userId.
description: A description of the history.
processDefinitionId: Only present when the history is created by a start workflow action. This is the complete ID of the process definition, including the deployment version.
processDefinitionKey: Only present when the history is created by a start workflow action. This is the "name" part of the process definition. It will be the same for all deployed versions of the process.
Further application specific fields could also be included.
Event Data
Event data is where the real flexibility of the History Service lies. It is possible to record any number of fields and values within each event data packet. As a minimum we recommend:
userId: The identity (site user account) of the user who triggered the event.
userRole: A string value defined in the workflow model to help identify the user. For example "Customer" or "Agent".
proxyUserId: If an action is being performed by an agent acting on behalf of another person using the Assisted Service template, the identity of the agent who is performing the action is recorded as the proxyUserId. The identity of the user in whose name the action is being performed is still stored as the userId.
uprn: If the event relates to a property, store the UPRN here. This can then be used to search for events that relate to a property.
event: A short one or two word phrase describing the event. For example, "created". We use the following:
- STARTWORKFLOW
- CLAIMTASK
- RELEASETASK
- COMPLETETASK
- SUMMARY
- WORKFLOWMESSAGE
- PROCESSENDED
description: A more detailed, human readable, description of the event. For example, "Bulky waste collection request approved".
historyDescription: This property is not required. If present, it is interpreted by the Self Service and User Requests templates as an update to the subject description.
private: This property is highly recommended but is not strictly required. If it is set to true, the event will not be displayed in the Self Service or User Requests templates unless the template is configured to show private events. Private events are used to record staff actions that shouldn't be seen by the user a history relates to.
Other event fields will be application specific. They could include details of emails, copies of data from form submissions, references to files held in the secure file store, or any other values that have been captured.
Storing Form Data
Form data can be stored in a history event using the History - Write Event field or the Workflow - Start Action and Workflow - Complete Task Action fields. However, these fields store data in different formats.
The stand-alone "write event" action field stores form data with information about the form and its pages:
"event": {
"event": "Form Submission",
"description": "Form: [History write event] submitted.",
"userRole": null,
"userId": "TIMG",
"proxyUserId": null,
"private": false,
"formData": {
"data": {
"PAGE1.TEXT1": "A value",
"FORMACTION.NEXT": "HISTORYWRITEEVENT_PAGE1_NEXT",
"PAGE2.TEXT2": "Another value",
"FORMACTION.FINISH": "HISTORYWRITEEVENT_PAGE2_SUBMIT"
},
"formName": "HISTORYWRITEEVENT",
"typeName": "FORM_HISTORYWRITEEVENT",
"formDefinitionType": "FORMDEFINITIONEX"
}
}
Whereas the workflow fields have a "flattened" data structure, matching the workflow process variables:
"event": {
"taskDefinitionKey": "sid-60141FC5-811F-4AE1-A522-B63F13C7D71D",
"private": false,
"description": "Staff response",
"proxyUserId": null,
"formData": {
"data": {
"QUESTION2": "",
"CLOSE2": "yes",
"DURATION2": "PT1M",
"CLOSE": "maybe",
"EMAIL2": "",
"EMAIL": "support@gossinteractive.com",
"QUESTION": "",
"DURATION": "PT1M"
},
"formName": "TIMSFORM",
"typeName": "FORM_TIMSFORM",
"formDefinitionType": "FORMDEFINITIONEX"
},
"event": "COMPLETETASK",
"userRole": "user",
"userId": "TIMG",
"taskId": "33485740"
}
Take care when storing form data. It's not possible to edit or remove form data once it has been written, nor can you delete particular events. If a user requests that any information about them is deleted, you'll have little option other than to delete the entire history that may only contain form data in one part. The Labelc Histories and Reporting Data article looks at this in more detail.
Share this page
