Narrative

The Narrative defines the application flow, which is enforced and controlled by the Narrator. The Narrative consists of one or more pages, each of which contains zero or more preActions and postActions. A preAction is anything that needs to occur before a user is allowed to access that page. A postAction is anything that needs to occur in order for a user to be allowed to leave the page. Finally, each page has a set of nextPages which define where a user can go, from the current page.

Using these controls, along with numerous other properties supported by the Narrative, you gain reliable and fine-grained control over how users interact with your form.

Defining a Narrative

Each Narrative is defined using JSON. The Narrative JSON for the example runtime Narrative (from the Narrator topic) might look like this.

{
    "name": "My Example Narrative",
    "version": "1.0.0",
    "initializeActions": [
        { "name": "Load Product Details", "version": "1.0.1" }
    ],
    "pages": [
        {
            "name": "About You",
            "preActions": [],
            "postActions": [
                { "name": "Call IDV Service", "version": "1.0.1" }
            ],
            "nextPages": [
                "Legal Disclosures"
            ]
        },
        {
            "name": "Legal Disclosures",
            "preActions": [
                { "name": "Load Legal Disclosures", "version": "1.0.1" }
            ],
            "postActions": [
                { "name": "Validate Signatures", "version": "1.0.1" }
            ],
            "nextPages": [
                "Primary Additional Information"
            ]
        },
        {
            "name": "Verification",
            "preActions": [],
            "postActions": [
                { "name": "Create New Account", "version": "1.0.1" }
            ],
            "nextPages": []
        }
    ]
}

note

In the example above, the version property is resolved to a specific active version for each service. When using Maven to build and deploy, the JSON source can use placeholder variables that are replaced with version values defined in pom-imports.xml. This ensures that all service versions and references are kept in sync.

For example,

"version": "${application-service-version-common}",

where application-service-version-common is defined in pom-import.xml:

<application-service-version-common>24.2.0</application-service-version-common>

To learn about the supported Narrative JSON properties, see Pages, Actions, and Expressions.

Initialize actions

You can use the initializeActions property to run an action as the Narrative is initialized. These actions run before the first page is evaluated, and run once only. That is, an initializeAction runs before the condition of the first page is evaluated, and before the pre-action for the first page is run.

Narrative history

To assist with debugging and to enable backward navigation, the Narrator keeps a history of a specific Txn's progress through its Narrative. This history lists each of the pages the Txn has visited and the order they were visited. Currently, the history acts as a stack: navigating forward in an application pushes a new page name onto the stack, and navigating backwards pops a page off the stack.