Narrative

The Narrative defines the application flow, which is then 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": []
        }
    ]
}

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.