JSON File Data Structure

JSON data files consist of a JSON array of data to be merged into the template. Each data file consists of multiple rows and each row contains the unique ID and merge fields to be processed. Each row is equal to one job run by High Volume Document Generation.

Required Elements:

Your file must contain the following elements:

• Id - The unique identifier for each row.

• EmailOptions - Necessary if you wish to deliver your generated documents via Email or Conga Sign.

• DocumentOptions - Specifies the name of the generated output document.

• Data - Contains the fields used to map information to the HTML template

The Id value is a required field and is the unique identifier of the row.

EmailOptions:

The properties such as the To, From, CC and BCC are optional, and are required if you are sending documents via email. When using EmailOptions, fill out the Address and DisplayName fields with the respective email address and recipient name.

DocumentOptions:

The OutputName value specifies the name of the generated document.

The Data structure will be merged into the document using standard Composer template tags, corresponding to the schema of template's data model. The related data options, such as Contact_Firstname and Account_Name will correspond with the merge fields from the data model of your Composer template. In the example below, values under the OppLineItems array are represented as repeated table data,and correspond to the merge fields set in the template so long as the nested data in the JSON is mapped to the document correctly. For more details, refer to the section below on Nested Table Merges.

ESignOptions:

If you are sending high volume merges through Conga Sign, the ESignOptions must be set to correspond with the Conga Sign values.

The Name value determines the name of the Transaction sent to the recipients. The Sender designates the sender's email address, while the Recipients array contains the FirstName, LastName and Email of the recipients, as well as the Role and RoutingOrder if they are necessary.

[
    {
        "Id": "a24c9f37-0456-4623-a2de-459b8f5e1221",
        "EmailOptions": {
            "From": {
                "Address": "qwalker@example.com",
                "DisplayName": "Quinn Walker"
            },
            "To": [
              {
                "Address": "ypatel@example.com",
                "DisplayName": "Yash Patel"
              },
              {
                "Address": "jjohnson@example.com",
                "DisplayName": "John Johnson"
              }
            ],
            "Cc": [],
            "Bcc": []
        },
        "DocumentOptions": {
            "OutputName": "contract"
        },
        "Data": {
            "CONTACT_FIRSTNAME": "Oliver",
            "OPPORTUNITY_NAME": "Cloud Solution Partnership",
            "ACCOUNT_NAME": "Acme Inc",
            "Conga_Doc_Link": "https://example.com/doc1",
            "USER_FIRSTNAME": "Daniel",
            "USER_NAME": "Daniel Smith",
            "USER_TITLE": "Senior Manager",
            "USER_CUSTOM_ORG_NAME": "Smith Consulting",
            "USER_PHONE": "555-123-4567",
            "USER_EMAIL": "daniel.smith@example.com",
            "OppLineItems": [
                {
                    "PRODUCT_NAME": "Service Plan",
                    "OPPORTUNITY_LINEITEM_UNITPRICE": "$200",
                    "OPPORTUNITY_LINEITEM_QUANTITY": 10,
                    "OPPORTUNITY_LINEITEM_TOTALPRICE": "$2000"
                },
                {
                    "PRODUCT_NAME": "Consultation",
                    "OPPORTUNITY_LINEITEM_UNITPRICE": "$500",
                    "OPPORTUNITY_LINEITEM_QUANTITY": 5,
                    "OPPORTUNITY_LINEITEM_TOTALPRICE": "$2500"
                }
            ]
        },
        "ESignOptions": {
            "Name": "Sign Transaction created by HVM API",
            "Sender": {
                "Email": "jjameson@example.com"
            },
            "Recipients": [
                {
                    "FirstName": "John",
                    "LastName": "Smith",
                    "Email": "JohnSmith@example.com",
                    "Role": "Signer",
                    "RoutingOrder": 1
                },
                {
                    "FirstName": "Emma",
                    "LastName": "Brown",
                    "Email": "EmmaBrown@example.com",
                    "Role": "Signer",
                    "RoutingOrder": 2
                },
                {
                    "FirstName": "Sophia",
                    "LastName": "Green",
                    "Email": "SophiaGreen@example.com"
                }
            ]
        }
    }
]

Nested Table Merges in JSON Data Structure

When creating a merge, you may want to access the data in your template where the data is in a table within a table. For example, a JSON structure like this:

{
  "test0": {
    "test1": {
      "test2": {
        "test3": {
          "test4": {
            "test5": "value5"
          }
        }
      }
    }
  }
}

To access the test5 value, the table in your template would be set as the following:

{{TableStart:test0_test1_test2_test3_test4}} {{test5}} {{TableEnd:test0_test1_test2_test3_test4}}

Dynamically Sized Tables

If you want to create a dynamically sized table that depends on the amount of entries in a JSON array, you can use the following example:

{
  "test0": [
    {
      "name": "Joe",
      "age": "25"
    },
    {
      "name": "Jim",
      "age": "26"
    },
    {
      "name": "Jeff",
      "age": "27"
    }
  ]
} 

To dynamically list out any item in the test0 array, format the values in the template this way: {{TableStart:test0}} {{name}} {{age}} {{TableEnd:test0}}.

If you want to ensure that this list is placed in a dynamically created HTML markup table, follow the following template example format : <figure class=\"table\"><table><tbody><tr><td>{{TableStart:test0}}{{name}}</td><td>{{age}}{{TableEnd:test0}}</td></tr></tbody></table></figure>.

The core component of the above example is: <tr>{{TableStart:test0}}{{name}}{{age}}{{TableEnd:test0}}</tr> for the merge to complete. The example listed above demonstrates a potential way to dynamically create the markup table.