Repeating Page Data

This article describes the structure of the data from repeating pages when it is stored in the platform.

In each of the examples below, PAGE1 was a repeating page with two instances and two fields (NAME and AGE), and PAGE2 a single page with two fields (COLOUR and SIZE).

History

History Write Event Field

If you use the History - Write Event field to store form data, the fields on non-repeating pages are stored using keys with dot notation that include the page name. Each instance of a repeating page is stored as an object in an array, with the field names as the keys:

"formData": {
    "data": {
        "PAGE1": [{
            "NAME": "Tim",
            "AGE": "41"
        }, {
            "NAME": "Leo",
            "AGE": "40"
        }],
        "PAGE2.COLOUR": "Red",
        "PAGE2.SIZE": "Small",
        "FORMACTION.NEXT": "TIMSFORM_PAGE1_FIELD27",
        "FORMACTION.NEXTNOACTIONS": "TIMSFORM_PAGE1_FIELD8_ADD",
        "FORMACTION.FINISH": "TIMSFORM_PAGE2_FIELD30"
    },
    "formName": "TIMSFORM",
    "typeName": "FORM_TIMSFORM",
    "formDefinitionType": "FORMDEFINITIONEX"
}

History via Workflow Fields

Data written to history as part of the workflow related form fields (for example Workflow - Start Action) stores repeating page data in a similar way to the Write Event field. Note how, to maintain backwards compatibility with data and forms created before non-repeating pages were developed, data from non-repeating pages just use the field name:

"formData": {
    "data": {
        "PAGE1": [{
            "NAME": "Tim",
            "AGE": "41"
        }, {
            "NAME": "Leo",
            "AGE": "40"
        }],
        "SIZE": "Small",
        "COLOUR": "Red"
    },
    "formName": "TIMSFORM",
    "typeName": "FORM_TIMSFORM",
    "formDefinitionType": "FORMDEFINITIONEX"
}

Querying Repeating Page Form Data in History

A simple filter for querying a history with the form data above could look something like this:

"filter": {
    "AND": [{
        "key": "labela",
        "EQ": "WRITEHISTORY"
    }, {
        "EVENTEXISTSWHERE": {
            "key": "formData.data.COLOUR",
            "EQ": "Red"
        }
    }]
}

That filter targets the COLOUR field, which was a form field on a non-repeating page.

To filter by the form data of a repeating page, use the generic array index [*]:

"filter": {
    "AND": [{
        "key": "labela",
        "EQ": "WRITEHISTORY"
    }, {
        "EVENTEXISTSWHERE": {
            "key": "formData.data.PAGE1[*].AGE",
            "EQ": "41"
        }
    }]
}

This will match against the AGE key in any instance of PAGE1. It's not possible to target a specific instance in the array. For more information about how the data from repeating pages is logged, see log() in the History worker API.

Objects and Form Data

iCM objects created by form submissions (for example, using the Database Save action field) store the data for a non-repeating page as an object, for repeating pages as an array of objects. The keys in each are the field names:

"ObjectData": {
    "PAGE1": [{
        "AGE": 41,
        "NAME": "Tim"
    }, {
        "AGE": 40,
        "NAME": "Leo"
    }],
    "PAGE2": {
        "COLOUR": "Red",
        "SIZE": "Small"
    }
}

Workflow

When a process instance starts, process variables are created in the instance to hold the values of form fields. For non-repeating pages the variable names are the form field names, prefixed with form_.

The data from repeating pages is stored as an array of objects, named after the repeating page, prefixed with formPage_ (see formPage_PAGE1 in the snippet below). Each object in the array represents a page instance. The keys are the field names.

Using the API to return the process variables of an instance we can see the following, where PAGE1 was a repeating page with two fields (some variables not relevant to the example have been removed):

"processVariables": {
    "_businessKey": "5051-8043-1213-6532",
    "_startForm": "TIMSFORM",
    "form_COLOUR": "Red",
    "form_SIZE": "Small",
    "formPage_PAGE1": [{
        "NAME": "Tim",
        "AGE": "41"
    }, {
        "NAME": "Leo",
        "AGE": "40"
    }],
}

Workflow Activities and Updating Variables

If a workflow task form or message is used to update data for a repeating page, the existing formPage_ process variable is completely replaced. The new page data is not merged with the existing data.

If you do need to display the partial data for a repeating page (eg just a single instance of it) this could be worked around in your workflow model. A script task before the user task could create a new variable with just the data to pass to the form, and a script task following the user task could perform the merge.

Using Variables in Handlebars Templates

The data from repeating pages is held as an array of objects, which means standard Handlebars helpers can be used to iterate over it.

Using the example data above, a Handlebars template in an email activity could look like this:

{{#each formPage_PAGE1}}
    <ul>
        <li>Name: {{NAME}}</li>
        <li>Age: {{AGE}}</li>
    </ul>
{{/each}}

Search Indexed Process Instances

Similarly, when a process instance that has been indexed in the platform's search engine is returned using getQueryProcesses, the process variables of a repeating page are held in an array:

{
    "processVars": {
        "form_COLOUR": "Red",
        "form_SIZE": "Small",
        "formPage_PAGE1": [{
            "NAME": "Tim",
            "AGE": "41"
        }, {
            "NAME": "Leo",
            "AGE": "40"
        }]
    },
    "id": "327564",
    "type": "WorkflowProcessInstance",
    "businessKey": "7752-2151-7921-4178",
    "tasks": [{...}],
    "messageDefinitions": {},
    "startUserId": "anonymous",
    "startProxyUserId": null,
    "parentBusinessKey": null,
    "parentProcessId": null,
    "suspended": false
}