History Events and Summary Events

iCM provides lots of tools that let you store information using the History Worker. Whether in your workflow processes, End Points, or forms, the history data you store 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 whether or not you should store form data 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 just like 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 always include a copy of the form data that created them
2. They are created by the workflowengine
3. They have the special event name SUMMARY
4. They include a historyDescription property which is inserted by the workflow engine

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 Complete Task action 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 all of the form data that has been submitted so far. Templates, like Self Service and User Requests, simply look for the most recent summary event, and display that as the self service summary.

Displaying Events and Summaries

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