Explore our blog

Generate and send agreements with dynamic tables using document generation for eSignature

We are excited to introduce eSignature REST API support for one of our newest document generation features: dynamic tables!

What is a dynamic table?

A dynamic table is a table in your eSignature template that has a variable number of rows for every envelope generated from the template. This new feature builds on our document generation capabilities in eSignature, enabling you to generate personalized, professional-looking agreements at the time you send them.

Have you ever wanted to create a template with tabular data, but gotten frustrated knowing that sometimes an agreement would have one data row, and at other times it would have five? Dynamic tables solve that problem! You can now create a single template that has a dynamic table, and the table will automatically be generated with the correct number of rows based on the data that the sender provides for each envelope.

You can try dynamic tables and document generation for free in your developer account. In production accounts, the feature is a paid add-on, so please reach out to a Docusign representative to learn more.

Sample use cases for dynamic tables

Dynamic tables are great for any use case in which the agreement contains a table where the number of rows varies based on the data provided. Here are some examples:

Agreement type	Table row count depends on
Purchase orders and invoices	Number of items in the order
Grant applications	Number of projects for the applicant
Project status reports	Project size and milestones
Insurance settlement distribution statements	Categories and payouts that are required based on the insurance plan and damage done
Employment contracts	Job title, location, benefits, and other employment details

Create your template with dynamic tables

The first step in creating a template with dynamic tables is to create a DOCX file, which is the required file format for document generation. The sender fields you define in the file will be populated at send time with personalized values for each envelope generated from the template. You can define sender fields and dynamic tables using the Docusign Template Assistant for Word (download it from the Microsoft Office Store). When you add a dynamic table, you specify the sender field that appears in each column. After defining the DOCX file content, you use the template assistant to add the file to an existing template in your eSignature account or create a new template that includes the file. See Docusign Template Assistant for Word for details about how to create and upload DOCX files.

Note: In a few months, we will offer dynamic table support in the Agreement Template Builder. This will provide a more streamlined template creation experience.

Send your envelope with dynamic tables via the API

The high-level steps to send an envelope created from a document generation template are listed below. Since the dynamic tables feature is an enhancement to the existing document generation workflow, you follow the same steps and simply adjust the payload for step 3 to include the table data!

Create an envelope draft from the template: Envelopes:create
Get the data fields (DocGenFormFields) for each document on the envelope: DocumentGeneration:getEnvelopeDocGenFormFields
Update the values for each data field (DocGenFormField): DocumentGeneration:updateEnvelopeDocGenFormFields
Send the envelope: Envelopes:update

Read on for examples of steps 2 and 3 that show dynamic table properties. For a detailed walk-through of the entire document generation workflow, see this how-to guide.

Example: Generate and send a purchase order to a buyer

As an example, let’s take a purchase order that has a dynamic table listing all of the items to be purchased. This table name is Line_Items and it includes the following sender fields for each row:

Description
Quantity
Unit_Price
Line_Total

Here’s the purchase order template DOCX file as defined in the Docusign Template Assistant for Word:

Get a list of sender fields

Once you’ve created your envelope draft from the template, send a DocumentGeneration:getEnvelopeDocGenFormFields request to retrieve the sender fields (listed in the docGenFormFields object) on that document. The response includes a new TableRow field type for dynamic tables.

A TableRow field has a rowValues property that contains a list of all the sender fields required for each row of the table.

For the sake of this example, I only show the dynamic table-related information in the GET response. The other sender fields will also be included.

GET {basepath}/accounts/{accountId}/envelopes/{envelopeId}/docGenFormFields

Sample response:

{
  "label": "Line_Items",
  "type": "TableRow",
  "required": "True",
  "name": "Line_Items",
  "rowValues": [
    {
      "docGenFormFieldList": [
        {
          "label": "Description",
          "type": "TextBox",
          "required": "True",
          "name": "Description"
        },
        {
          "label": "Quantity",
          "type": "TextBox",
          "required": "True",
          "name": "Quantity"
        },
        {
          "label": "Unit_Price",
          "type": "TextBox",
          "required": "True",
          "name": "Unit_Price"
        },
        {
          "label": "Line_Total",
          "type": "TextBox",
          "required": "True",
          "name": "Line_Total"
        }
      ]
    }
  ]
},

Add sender field values

Then, send a DocumentGeneration:updateEnvelopeDocGenFormFields request to update the value properties in the docGenFormFields object with the appropriate sender field values. Again, I only show the request body section relevant to dynamic tables in the example.

For a field of type TableRow, supply the row data in the rowValues property. Provide the data as an array of docGenFormFieldLists, where each docGenFormFieldList object represents a row in the table.

PUT: {basepath}/accounts/{accountId}/envelopes/{envelopeId}/docGenFormFields

{
  "docGenFormFields": [
    {
      "documentId": "d5f70ce4-xxxx-xxxx-xxxx-04535e6ze372",
      "docGenFormFieldList": [
        {
          "name": "Line_Items",
          "type": "TableRow",
          "rowValues": [
            {
              "docGenFormFieldList": [
                {
                  "name": "Description",
                  "value": "Gadgets"
                },
                {
                  "name": "Quantity",
                  "value": 5
                },
                {
                  "name": "Unit_Price",
                  "value": "100.00"
                },
                {
                  "name": "Line_Total",
                  "value": "500.00"
                }
              ]
            },
            {
              "docGenFormFieldList": [
                {
                  "name": "Description",
                  "value": "Widgets"
                },
                {
                  "name": "Quantity",
                  "value": 100
                },
                {
                  "name": "Unit_Price",
                  "value": "10.00"
                },
                {
                  "name": "Line_Total",
                  "value": "1,000.00"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Your final purchase order has all of the personalized information dynamically merged in, and based on our sample PUT request, two rows of line item data are generated for the table. Now you can send a clean, professional-looking purchase order to your buyer!

Final purchase order with all of the personalized information dynamically merged in

Limitations

The major limitation of dynamic tables is that you are not able to add the sender field values within the composite template API call. See Limitations and Considerations for Document Generation for a more detailed list of limitations.

Additional resources

Take a look at the resources below and take advantage of dynamic tables and document generation!

Author

Aaron Prohofsky

Product Manager

Published

May 2, 2024