Why You Should Be Using the Composite Template Model

Intro: what do you use?

Those already familiar with the DocuSign eSignature APIs have likely created envelopes without being aware of the three different envelope creation models available. I refer to the three models as “direct documents,” “template reference,” and “composite templates” models. Many of the introductory examples to the DocuSign APIs have used the direct documents or template reference models. In this article, I will explain why those are good for “hello world” initial toe-dip-in-the-water exploration, but for real products you should be using composite templates.

Why the other models suck

The direct documents model is centered on using a documents element, which is an array of document elements. This model allows you to create multi-document envelopes with multiple recipients. It also supports placement of tabs based on text anchors or PDF Form transformation.

However, DocuSign templates are not supported. This limits the future growth of your solution. Templates are invaluable for pre-specifying static documents, building in role-based workflow, applying tabs to a document all at once, and reducing API payload size. To upgrade your integration will require re-implementing your envelope creation logic to follow the composite templates model.

The template reference model is also a popular model for basing envelopes on a DocuSign template. This model focuses on the templateId and templateRoles elements. This model is extremely limited, as you can only specify a single template ID to be the basis of the envelope. If your users demand the ability to add additional documents, you will need to rework your integration to use the composite templates model.

Are you seeing a trend here? Updating your integration beyond your initial simple use case almost always leads to re-implementing with the composite templates model. Maybe you should have started with the composite templates model? Let’s take a look at the composite templates model and see if it makes sense to start with it—that is, it meets both short-term and long-term needs, supports both simple and complex envelopes, and so on.

Composites: the flexible model

The composite templates model supports everything, from simple to complex. Everything done with direct documents and template reference models can be done with the composite templates model. Furthermore, you can use the same model to expand into more complex cases, including cases that cannot be handled by either of the other models. It is best to start with this model from the beginning, to prevent the necessity of rewriting a “dead-end” MVP.

The composite templates model consists of an array of composite template elements. These composite template elements are not themselves templates, but rather “composites” made up of one or more templates. From here on I will refer to these as “composites” for brevity. Each of these elements acts as a unit of contribution, contributing a document and related envelope attributes to the envelope being constructed. The composite elements contribute to the envelope in the order in which they appear in the array. Each composite element contains any of three optional elements: document, serverTemplates, and inlineTemplates.

Example: individual composite element:

"compositeTemplates": [
    {
        "document": {},
        "serverTemplates": [{}],
        "inlineTemplates": [{}]
    }
]

The document element is used to directly contribute a document from your integration. The serverTemplates array is used to contribute DocuSign templates built and saved within DocuSign. These each have a server template GUID reference and are each sequenced within the composite template assembly process via a sequence ID (integer). The inlineTemplates array is used to contribute envelope-fragments that your integration provides. This could be as simple as specifying the recipient details for a server template’s roles, or a detailed envelope specification for a contributed document.

Example: sending a document (equivalent to direct documents):

"compositeTemplates": [{
    "document": {
    "documentId": "1",
    "name": "doc_1.pdf",
    "transformPdfFields": "true",
        "documentBase64":"..."
    },
    "inlineTemplates": [{
    "recipients": {
        "signers": [{
        "email": "joe.bloggs@example.com",
        "name": "Joe Bloggs",
        "recipientId": "1",
        "defaultRecipient": "true"
        }]
    },
    "sequence": "1"
    }]
}]

Example: sending a template:

"compositeTemplates": [{
    "serverTemplates": [{
    "sequence": "1",
    "templateId": "741c8b4c-xxxx-xxxx-xxxx-c03acb1a3993"
    }],
    "inlineTemplates": [{
    "recipients": {
        "signers": [{
        "email": "joe.bloggs@example.com",
        "name": "Joe Bloggs",
        "roleName": "customer"
        }]
    },
    "sequence": "2"
    }]
}]

The final example will demonstrate a use case that isn’t possible using anything other than composites. Scenario: you must send a rental property description document and two copies of the same lease agreement for two renters to sign. The lease agreement is a standard document saved as a DocuSign template with “Tenant” role. You will send three3 documents: 1) Property description doc, 2) lease template for first tenant, and 3) lease template for second tenant. The first is a standalone document (no actions), but the second two are the same template but require a different signer. This example shows the entire envelope body.

{
    "emailSubject": "Please sign your lease agreement.",
    "emailBlurb": "Each tenant must sign individual lease.",
    "status": "sent",
    "compositeTemplates": [{
        "document": {
        "documentId": "1",
        "name": "Property-A",
        "fileExtension": "pdf",
        "documentBase64": "JVBERi...NCg=="
        }
    },
    {
        "serverTemplates": [{
        "sequence": "1",
        "templateId": "E5577130-xxxx-xxxx-xxxx-95DD79644971"
        }],
        "inlineTemplates": [{
        "recipients": {
            "signers": [{
            "email": "wile.e.coyote@example.com",
            "name": "Wile E. Coyote",
            "roleName": "Tenant"
            }]
        },
        "sequence": "2"
        }]
    },
    {
        "serverTemplates": [{
        "sequence": "1",
        "templateId": "E5577130-xxxx-xxxx-xxxx-95DD79644971"
        }],
        "inlineTemplates": [{
        "recipients": {
            "signers": [{
            "email": "hunter_of_rabbits@example.com",
            "name": "Elmer Fudd",
            "roleName": "Tenant"
            }]
        },
        "sequence": "2"
        }]
    }
    ]
}

Rules and “RoT”

Let’s look at some processing rules that govern how composites work in the assembly process of an envelope as well as some conceptual “rules of thumb.”

Document contribution

Each composite element contributes a document to the envelope. If the composite template has a document element, then this element directly contributes the document. If there is no document element, then each template is checked in sequence order. If the first template is a Server Template, it will contribute the document to this composite (as all server templates should have a document). If the first template is an Inline Template and does not have a documents element, then the next template is checked, and so forth. Note: while inline templates can contribute documents via the documents element, the preferred approach is to employ the composite template document element. To recap:, for the contribution of a document to the composite, it is “first in, wins” with the following priority:

1. Composite template’s document element.
2. The first template (of all templates in this composite) by sequence order that has a document within it.

Non-document envelope elements contribution

All other envelope attributes are contributed by templates. The impact of sequencing and repeated attribute elements is that later values override earlier values, such that the “last in wins.”. Sequence ordering via the sequence element is therefore critical to proper assembly. For example, if a server template specifies a recipient role and an inline template maps a recipient to that role name, it is essential that the server template be sequenced prior to the inline template, such that the role and associated tabs are established before a recipient is mapped to it.

RoT: Rules of thumb that prevent code rot

1. Create DocuSign templates around individual documents, rather than bundling multiple documents in a single template. By keeping them separate, you can easily accommodate a custom envelope payload by mixing in the necessary server templates.
2. Design the assembly of envelopes around composites, with each being a “single document contributor”. By building in this “compositing loop,” your business logic can be modified to handle new or complex use cases without a complete redesign of your envelope construction logic.
3. The sequencing of templates takes place within the context of individual composites. Each new composite can start sequencing at “1.” There’s no need to increment sequence values across the entire array of composites. This, again, makes it easy to set the sequence value with the logic that is building the individual composite.
4. Within an individual composite, do not repeat the same sequence for two templates. The results may appear ambiguous, as the actual sequencing will be based on load order. It is always best to explicitly specify the exact sequencing of templates within an individual composite.
5. Consider leaving out the base64 encoding of documents. Composites provide an additional element (compositeTemplateId) to make it easy to use multipart form requests and pass the documents in their native binary format.

Composite templates resources

Developer site:

• Envelope Create API
• Code Example: Requesting a Signature using a Composite Template

DocuSign University composite templates courses:

• Developer Composite Template Use Cases
• Composite Templates Using Server Templates

Additional resources

• DocuSign Developer Center
• @DocuSignAPI on Twitter
• DocuSign for Developers on LinkedIn
• DocuSign Developer Newsletter

Gil Vincent is a software professional with experiences as varied as technical lead, developer training consultant, program manager, and technical architect. For the past 9+ years, he has been guiding DocuSign customers and partners in implementing and deploying DocuSign integrations.