Template Tags Reference

Template tags let you create document templates that automatically fill in with data. When you generate a document, Box Doc Gen finds the tags in your template, matches them to fields in your JSON input, and replaces each tag with the corresponding value.

Use template tags to dynamically generate: 

1. Text
2. Images
3. Tables
4. Lists
5. Conditions
6. Calculations
7. Box Sign template tags

1. Text tags

A text tag is any data field of type, string, number, or date. In the example below, you can turn id, date, customerId, customerName, currency, amount into text tags.

{
  "invoice":{
    "id": "Inv1203",
    "date": "13-03-2023",
    "customerId": "90158",
    "customerName": "Acme Inc",
    "currency": "$",
    "amount": 5060.50
  }
}

In the output document generated, all the template tags will be replaced with the input data.

Formatting text tags

Rich text

Box Doc Gen allows you to generate documents with rich text. If the input JSON data contains HTML tags such as bold, italic, underline, line breaks, paragraphs, anchors, or images, Doc Gen automatically interprets them as rich text and applies the relevant formatting. 

2. Image tags

Doc Gen enables you to embed any image file in Box into the generated document. To do this, you will need to follow the following steps:

1. Upload the image file to Box

The image file being used for Document Generation has to be uploaded to Box. 

Generating documents via API
If you are using a service account to generate the document via APIs, ensure the service account has access to the file.

2. Author the Doc Gen template

Doc Gen allows you to generate documents using images in the following ways 
 

• Generating documents from a placeholder image
• Generating documents with HTML images

Generating documents from a placeholder image:

Authoring a Doc Gen template using Add-in for Microsoft Word

To insert an Image tag using the add-in:

1. In the Box Doc Gen Template Creator add-in, create an image tag using your desired placeholder image
2. Navigate to the Document Tags > Image Tags.
3. In the document, select the area to insert an Image tag.
4. Double-click the image tag to insert it. 

The result is a placeholder image, which can be dynamically replaced by the input data from the Box Doc Gen API, or any other upstream systems. 

The dimensions, and alignments of the placeholder image can be altered using Microsoft Word functions. These properties are retained in the output document. 

The placeholder image has the following code added to the image under "Alt Text". To view it: Select the image -> Right Click -> View Alt Text

{
  "image-path": "singleImage",
  "alt-text": ""
}

Repeating images within a for-loop:

To generate a document with multiple images in a for-loop, ensure the image is wrapped in a For function as below,

{{ for item in multipleImages }}

{{ endfor }}

Repeating images within a table-loop:

To generate a document with multiple images in a table-loop, ensure the image is wrapped in a Table function as below,

Note: Ensure to include the image path in the ALT TEXT section of the image
{
"image-path": "singleImage",
"alt-text": ""
}

Generating documents with HTML images:

To generate a document with a HTML image from the JSON payload, include a Text tag in the template. 

For example: {{htmlImage}}

3. Create the JSON Payload to Generate the document

Generating documents from a placeholder image:

To generate a document with an image file in Box, use the following schema:

1. Key used in the Placeholder image (Ex: singleImage)
2. id - to pass the file id of the Image file in Box 
3. type - to signify that this is an image file to be embedded in the document

 {
 "singleImage": {
  "id": "1948600448426",
  "type": "image",
  "name": "Title for image 1"
 }

{
  "image-path": "singleImage",
  "alt-text": ""
}

Generating a document from a Placeholder with multiple images

To generate a document with multiple image files in Box, run an array of image schema as shown below,

{
 "multipleImages": [
                    {
                      "id": "1948600448426",
                      "type": "image",
                      "name": "Title for image 2"
                    },
                    {
                      "id": "1948600448427",
                      "type": "image",
                      "name": "Title for image 3"
                    },
                    {
                      "id": "1948600448428",
                      "type": "image",
                      "name": "Title for image 4"
                    }
                  ]
}

Generating documents with HTML images:

To include an image from Box in your document using an HTML image tag, define the JSON schema in the following format:

{
 "htmlImage": "<img src='file://2097093405102' alt='here is a sample image' height='500' width='500'/>"
}

In this example:

• file://2097093405102 refers to the file ID of the image stored in Box
• height and width define the display size of the image
• alt specifies the alternative text for the image

4. Make a Document Generation request

Doc Gen allows you to create documents with embedded images sourced directly from Box. You can include images in your generated documents using one of the following methods:

• Box Doc Gen API – Generate documents with images programmatically. Refer to the Box Doc Gen API documentation for step-by-step guidance.
• Box Doc Gen Web App – Create documents with embedded images through the web interface. See the documentation for detailed instructions.

Salesforce Integration – Generate documents with images by referencing a Box file ID. Ensure the required JSON schema pattern is followed. For setup and usage, refer to the Salesforce integration documentation.

3. Table tags

An array from the input data can be used to generate and dynamically format a table.

In the following example:

• items is an array that can be rendered as a dynamic table.
• id, name, quantity, price, amount are the variables within the array that can be rendered as individual columns to the dynamic table.

{
  "invoice":{
    "number": "Inv1203",
    "date": "13-03-2023",
    "customerId": "90158",
    "currency": "$",
    "amount": 5060.50,
    "items": [
      {
        "id": 1,
        "name": "A4 Papers",
        "quantity": 100,
        "price": 29,
        "amount": 2900
      },
      {
        "id": 2,
        "name": "Ink  Cartridge",
        "quantity": 40,
        "price": 39,
        "amount": 1560
      },
      {
        "id": 3,
        "name": "Adhesive tape",
        "quantity": 20,
        "price": 30,
        "amount": 600.50
      }
    ]
  }
}

Document Template

The document template with inserted tags will look as follows:

Output

Box Doc Gen automatically identifies the table tags added to the document template, matches them with the fields in the input JSON data, and performs a few iterations to generate a complete table for the input data.

The output table on the generated document will look as follows:

4. List tags

An array from the input data can be used to dynamically generate an ordered or unordered list.

In the following example:

• items is an array that can be rendered as a dynamic list.
• id, name, quantity, price, amount are the variables within the array that can be rendered as a repetitive field in the list.

{
  "invoice":{
    "number": "Inv1203",
    "date": "13-03-2023",
    "customerId": "90158",
    "currency": "$",
    "amount": 5060.50,
    "items": [
      {
        "id": 1,
        "name": "A4 Papers",
        "quantity": 100,
        "price": 29,
        "amount": 2900
      },
      {
        "id": 2,
        "name": "Ink  cartridge",
        "quantity": 40,
        "price": 39,
        "amount": 1560
      },
      {
        "id": 3,
        "name": "Adhesive tape",
        "quantity": 20,
        "price": 30,
        "amount": 600.50
      }
    ]
  }
 }

The input data can be used to generate different types of lists:

Formatting lists

Box Doc Gen templates support a wide range of custom codes that you can use in the document template. Taking the following JSON input data as an example, you can introduce different separators and delimiters.

{
  "items": ["A4 Papers", "Ink  cartridge", "Adhesive tape"]
}

5. Conditions

You can use conditions to add input to the output document. The Box Doc Gen Template Creator add-in can help you define these conditions within the document template.

Supported conditions and operators

The following JSON serves as input for defining conditions for the Box Doc Gen template. 

{
  "invoice":{
    "number": "Inv1203",
    "date": "13-03-2023",
    "customerId": "90158",
    "currency": "$",
    "amount": 5060.50,
    "paymentMethod": "Cheque",
    "paymentTerms": "Net60",
    "deliveryDate": "23-03-2023",
    "items": [
      {
        "id": 1,
        "name": "A4 Papers",
        "quantity": 100,
        "price": 29,
        "amount": 2900
      },
      {
        "id": 2,
        "name": "Ink cartridge",
        "quantity": 40,
        "price": 39,
        "amount": 1560
      },
      {
        "id": 3,
        "name": "Adhesive tape",
        "quantity": 20,
        "price": 30,
        "amount": 600.50
      }
    ]
  }
 }

Conditions with tables

Doc Gen allows you to conditionally render any content including tables, images, and so on. 

{{ if invoice.customerId isPresent }}

{{ endif }}

Conditions inside tables

Doc Gen allows you to conditionally render content with a column in a table. 

Examples

6. Calculations

Box Doc Gen templates support dynamic calculations. You can either write the computation code to the tagging language manually, or use the Box Doc Gen Template Creator add-in.
Sample code calculations include: 

• Invoice: Determining the net invoice amount from individual line items.
  Example: Sum (Individual Line item amounts in the invoice)
• Purchase order: Capping the maximum sourcing amount.
  Example: 5% * Net Order Value
• Sales contracts: Defining penalty on SLA breach.
  Example: 10% * Total Sales Value

Supported operations

The following JSON serves as input for adding calculations to the document template.

{
  "invoice":{
    "number": "Inv1203",
    "invoiceDate": "13-03-2023, 12:10 PM",
    "deliveryDate": "23-03-2023",
    "customerId": "90158",
    "currency": "$",
    "taxRate": 3,
    "taxAmount": 151.8,
    "shippingCharge": 15,
    "grossAmount": 5060,
    "penaltyRate": 10,
    "billCap": 25,
    "items": [
      {
        "id": 1,
        "name": "A4 Papers",
        "quantity": 100,
        "price": 29,
        "amount": 2900
      },
      {
        "id": 2,
        "name": "Ink  cartridge",
        "quantity": 40,
        "price": 39,
        "amount": 1560
      },
      {
        "id": 3,
        "name": "Adhesive tape",
        "quantity": 20,
        "price": 30,
        "amount": 600
      }
    ]
  }
}

Examples:

7. Box Sign template tags

Box Sign template tags can be added to the Box Doc Gen template for the output document created via Box Box Doc Gen to be sent for e-signature. 

The table below lists the tags available in the Box Doc Gen Template Creator add-in and the tagging script.