History Events and Summary Events

The history records written by workflow processes, form fields, and directly using the API will have the same overall shape:

1. A key made up of up to five labels that identify the history
2. A packet of subject data
3. A series of events which may be public or private, and may be tagged as "summaries"

In this article we are going to focus on history events, summary events, and the data stored in them.

A History Event

Here's a typical history event. As you can see, it is a JSON object. This event was created when a form was submitted that contained the Workflow Start action field. The action field did not store any form data with the event.

{
    "pos": [1, 2],
    "event": {
        "private": false,
        "description": "Form Submitted",
        "proxyUserId": null,
        "event": "STARTWORKFLOW",
        "userRole": "user",
        "userId": "TIMG"
    },
    "fpos": [1, 2],
    "timestamp": {
        "epochmillis": 1500638230087,
        "readabledate": "2017-Jul-21",
        "readabletimeutc": "11:57:10"
    }
}

This is an event generated by the same form, but this time we did tell the action field to store form data. Note how the file upload is stored.

{
    "pos": [1, 2],
    "event": {
        "private": false,
        "description": "Form Submitted",
        "proxyUserId": null,
        "formData": {
            "data": {
                "TEXTFIELD": "Some text added to the form",
                "FILEUPLOAD": "file/1C23DF98-7AE4-45AA-81CD-C3AB9E486EC9/firstprocessmodel.PNG"
            },
            "formName": "STARTAPROCESS",
            "typeName": "FORM_STARTAPROCESS",
            "formDefinitionType": "FORMDEFINITIONEX"
        },
        "event": "STARTWORKFLOW",
        "userRole": "user",
        "userId": "TIMG"
    },
    "fpos": [1, 2],
    "timestamp": {
        "epochmillis": 1500638149480,
        "readabledate": "2017-Jul-21",
        "readabletimeutc": "11:55:49"
    }
}

The formName is the form that will be used to view this form data, either in a summary or when viewing details of this event in the Self Service and User Request templates (see below).

Summary Events

As well as standard history events, the Workflow Start and Workflow Complete Task action fields can also create and update "Self-Service Summaries".

Self service summaries are similar to regular events. Here's a summary event created by the same start action as the events above.

{
    "pos": [2, 2],
    "event": {
        "private": false,
        "historyDescription": "A model with a cancel message",
        "description": "Summary",
        "proxyUserId": null,
        "formData": {
            "data": {
                "TEXTFIELD": "Some text added to the form",
                "FILEUPLOAD": "file/1C23DF98-7AE4-45AA-81CD-C3AB9E486EC9/firstprocessmodel.PNG"
            },
            "formName": "STARTAPROCESS",
            "typeName": "FORM_STARTAPROCESS",
            "formDefinitionType": "FORMDEFINITIONEX"
        },
        "event": "SUMMARY",
        "userRole": "workflowengine",
        "userId": null
    },
    "fpos": [2, 2],
    "timestamp": {
        "epochmillis": 1500638149730,
        "readabledate": "2017-Jul-21",
        "readabletimeutc": "11:55:49"
    }
}

There are a few things to note:

1. Summary events include a full copy of all of the form data that has been submitted so far during the workflow
2. They are created by the workflowengine
3. They have the special event property "SUMMARY"
4. They include a historyDescription property which is inserted by the workflow engine

The form data added to a summary event is taken from all of the form_ process variables in the current process instance. This means that you can use workflow script activities to add new variables which will be added to your summary events. For example execution.setVariable("form_SETINSCRIPT", "This was set in a script activity");

Updating Summaries

Once an event has been written to a history, it is immutable - there is no way of editing or updating it. So why does the workflow action form fields have a property called "Update Self-service Summary"? 

A history generated by a workflow process will potentially contain multiple summaries. When we tell our form actions to "update" the summary, we are in fact creating a brand new summary event with a new copy of all of the form data that has been submitted so far. Templates, like Self Service and User Requests, look for the most recent summary event, and display that as the self service summary.

Retrieving Summary Events

The getHistory() and getHistories() functions have a "lastsummary" parameter. This instructs the worker to only retrieve the last summary event and is more efficient than writing event filters.

For this to work your summary events must include the "event": "SUMMARY" property.

Self Service and User Request Templates

Histories, events, and summary events can be displayed to users via the User Requests and Self Service templates. The workflow documentation looks at the different ways these templates can be set up.