Data model

The Data model sub-tab of the Configuration tab describes the structure of the data that a template is built from. With a data model, a process creates a new template from this template and a set of data. Parts of the form, and recipients, are repeated for each item in a list of the data, for example once for each signer of a contract.

A process builds the template with the BuildTemplateFromData service. See Web Service. Building templates from data requires the data model to be included in your organization’s plan. It works with HTML and PDF templates, but not with hybrid templates.

Nodes

The data model is a tree of nodes. Each node is a value in the data, or a list of items. Each node has these settings:

Setting	What it is
Id	The ID of the node. At least 2 characters: letters, digits and underscores, starting with a letter. Two nodes at the same level can’t have the same ID.
Type	String, Number, Boolean, Attachment, Id or Array. An Array is a list: its child nodes describe each item of the list. An Id node identifies an item (see Aggregate recipients by id).
Source path	Where the value of the node is in the data. The list shows the paths of the data model, for example the paths from an uploaded file.

To build the tree:

• Click Add Node to add a node at the top level.
• On an Array node, click Add Row To List to add a child node. When you change a node’s type to Array, a first child node is added.
• To delete a node and its child nodes, click its trash icon.
• To delete all the nodes, click Clear All, and then Yes, Clear.

An ID that isn’t valid, or that is used twice at the same level, is marked with an error, and you can’t save the data model until you fix it.

Upload a data model

Instead of adding the nodes one by one, you can create them from a JSON file with sample data. Click Upload Data Model and select the file. The nodes in the file replace the current nodes.

The file has two lists:

• initial: values. Each value has an id and a sourcePath (the path as a list of names), and becomes a String node.
• initial_groups: lists. Each list has an id, a sourcePath and entries, and becomes an Array node. Its child nodes are created from the first item in entries, which has its own initial and initial_groups.

For example:

{
  "initial": [
    { "id": "contract_number", "sourcePath": ["contract", "number"] }
  ],
  "initial_groups": [
    {
      "id": "signers",
      "sourcePath": ["contract", "signers"],
      "entries": [
        {
          "initial": [
            { "id": "signer_name", "sourcePath": ["name"] },
            { "id": "signer_email", "sourcePath": ["email"] }
          ],
          "initial_groups": []
        }
      ]
    }
  ]
}

This file creates a String node contract_number with the source path contract.number, and an Array node signers with the source path contract.signers. The signers node has two child nodes, signer_name and signer_email, with the source paths contract.signers.name and contract.signers.email.

Entries that have no id or no sourcePath are skipped. If the file isn’t valid JSON, nothing changes.

Aggregate recipients by id

When a recipient is repeated for each item of a list (see Apply repeating model on the Workflow sub-tab), the same person can appear in several items. Turn on Aggregate recipients by id to merge the repeated recipients that have the same value in their Id node into one recipient. That recipient fills in the fields of all the merged recipients.

Save the data model

Click Save Data Model to save the data model right away. You don’t need to save the template. “Changes are not saved” is shown while you have changes that aren’t saved. Save Data Model is available when there are changes and no errors.

Use the data model

• In the HTML template editor, pages, sections and rows have Repeat and Repeat Model settings on their Data Model tab, to repeat them for each item of a list. See Repeat a page, section or row.
• On a field’s Repeater tab, Repeat Model links the field to a node of the data model, which fills the field. See Field settings.
• On the Workflow sub-tab, Apply repeating model repeats a recipient for each item of a list. The repeated recipients are named after the recipient, with a number: signer_1, signer_2 and so on.

When the template has a data model, the Workflow conditions, the process preview and Edit are not shown on the Workflow sub-tab.