Use a template, Luke!

With apologies to George Lucas. DocuSign eSignature templates offer a powerful pattern for application developers that can be overlooked. While any combination of documents, recipients, tabs, and other features can be requested via the Envelopes:create API request, using a template or two is often a better, faster, more flexible route to solving your use case.

Key benefits of using templates for your DocuSign API application

• Speed: develop with a WYSIWYG editor instead of code
• Flexibility: your business partners can update the application
• Partitioning: better modularization of your application
• Quality: easier testing of your application

Speed: Develop with a WYSIWYG editor instead of code

Templates are best created by using the DocuSign eSignature web app, a what you see is what you get (WYSIWYG) editor. It enables you quickly to try out different combinations of documents, recipients, tabs, and other features for your template and the resulting envelopes. Using the web app to fine-tune your application’s envelopes is much easier and faster than trying different API calls.

Flexibility: your business partners can update the application

Templates offer you the wonderful benefit of enabling your business partners (non-programmers) to update your application without needing a developer’s involvement. For example, if the template holds the application’s document, a business person can update the document via the DocuSign web application. Updating the template’s document will immediately cause the application to use the new document.

This feature must be used carefully, because it is also easy for the business person to break the application by changing the template in an unanticipated or incorrect manner. Suggestions:

• The application developer should carefully document what types of changes to the templates are okay, and which need the involvement of a developer.
• A version of the application should be available on the DocuSign developer system (demo.docusign.net). This version should be used to test any changes before making them on the production application. The same template changes would then need to be made against the production templates. Or better: the application can look up the template ID from the template’s name rather than hardcoding the template’s ID. The developer version of the template can be exported, and then imported into the production environment. Since the application is looking up the template by name, it can automatically update to the new template version (which will have a different template ID.)
• A more sophisticated pattern is to set up templates for the business people to change; then the application can copy the updated templates to the production templates once the changes have been verified. Applications can also implement a rollback function to restore the application to the previous version.
• It is always advisable to export working versions of templates so they can be restored in case of unforeseen issues. Templates can be exported from the DocuSign web app or programmatically via the API (see below).

Partitioning: better modularization of your application

Templates can assist the developer in modularizing their application to enable a more agile development process. If the application includes multiple documents or multiple pages, you can use more than one template to construct the overall envelope.

For example, if the application’s envelopes include a main document and a supplemental document, handle each with its own template. When the envelopes are sent, the multiple templates are easily combined (see below for examples).

Quality: easier testing of your application

Related to modularization, using one or more templates in your application improves testing by enabling smaller unit tests of the application’s different components.

Plan your templates

Plan out the template or templates that your application will use. For each template, decide on its name, the recipients it will include, which recipients are roles (whose recipient contact details will be filled in later by your software) rather than specific individuals, the tabs for each recipient, and other envelope features included in the template.

Record the templates’ names, purpose, roles, tabs and other information in a specification sheet. Remember to record each tab’s Data Label setting from the DocuSign web app. The Data Label is used in the Envelopes:create API call to reference the tab. In the API, the tabLabel attribute is the same as the DocuSign app’s Data Label field attribute.

Tab (Field) attributes

The many attributes of Tabs (Fields in the DocuSign web app) can be set in either the template or your application. If the attribute needs to be changed dynamically for a particular envelope, then set the attribute value in your application. If the attribute value is fixed for your application, then set it in the template.

For example, set the tab’s font and font size in the template itself. If your application changes the tab’s text color depending on envelope specifics, then set the text color in your API call.

Templates can have a superset of recipients

For some use cases, envelopes will have a varying number of signers (or other types of recipients) depending on the dynamic attributes of the agreement. For example, a purchasing agreement will be signed by either the purchaser or by the purchaser and a co-signer. To accomplish this, you could create two templates, one for each case.

Alternatively, create one template with two signers. For envelopes that only need a single signer, delete the co-signer recipient from the envelope: To not include a recipient (and their tabs), don’t include the Template Role object in the envelope request (or the recipient’s object when using composite templates).

Dynamic documents

We often think of tabs as an input mechanism used by signers to enter data. But tabs can also be read-only (Locked) and used to add additional text to a document. For example, a text tab can be used to add an additional requirement to an agreement. To make the new text visible to all signers, set the Shared attribute to true.

A locked text tab can also be used to label an input tab such as a checkbox or list tab to create a dynamic form field. See the Examples section below for a live example.

Export a template via the API

To export a template via the API, use the eSignature Templates:list API method as follows:

GET https://demo.docusign.net/restapi/v2.1/accounts/{account_id}/templates?
	include=documents&is_download=true&
	template_ids={template_id}

Note that the returned content type will be application/zip.

Composite templates

Templates can be included in Envelopes:create API calls by using either the template reference or composite templates patterns. For many use cases, the greater power of Composite Templates is needed.

See Gil Vincent’s excellent blog post for an introduction to composite templates. Composite templates work like image compositing in film: multiple image sources are layered on top of each other to produce a final image that includes all of the source images. For composite templates, multiple sources of data, including documents; templates and their recipients, documents, and tabs; and additional data (inline templates) are combined together to produce an envelope.

Remember that an envelope can include multiple composite templates. Pro tip: Include only one document per composite template item and only one document per template stored on the DocuSign servers. 

Examples

These examples use the new API Request Builder application. You can use the app to try out the examples live. (When you open an example, any needed templates will be uploaded to your account with the name prefix API Req Builder.) The app can also be used to auto-program the examples in different languages for use in your own application.

Some examples use DocuSign eSignature features that may not be enabled in your developer account. To have a feature enabled, open a case with customer support. Best practice: use the Support Portal to login with your production (not developer) DocuSign credentials. Or use the general web form on the Contact Support page. Use the DocuSign API Integration Support option at the bottom of the page. Remember to include your developer account ID with your request to enable a feature on your account.

Template examples

• Template with two signers. Creating an envelope based on a template. Pattern: template reference.
• Set template tabs. The Envelopes:create call sets the values of the template’s tabs. Patterns: template reference and composite templates.
• Set envelope metadata. The Envelopes:create call sets metadata values for the envelope. Patterns: template reference and composite templates.
• Embedded recipient from a template. Embedded (captive) recipients require the recipient to have a clientUserId value. The clientUserId attribute is not available from the DocuSign web app, but can be added via the Envelopes:create call. Pattern: composite templates.
• Two templates and an added document. This example includes one template two times in the envelope. Use the same pattern to add different templates to an envelope. The example also adds a new document to the envelope. The new document is added as a supplemental document. A different example demonstrates the multiple options for supplemental documents. Pattern: composite templates.
• Add a new tab. This example uses a template, and then adds a new text tab and a new list (dropdown) tab. The text tab serves as a label for the list tab. Pattern: composite templates.
• Replace the template's document. This example uses a template, and then substitutes a new document for the template’s document. Only the first document in a template can be replaced; this is another reason why one document per template is a good guideline. Since the tabs in the template will be applied to the new document, anchor text positioning is recommended. Remember to include all of the needed anchor text in the new document. Pattern: composite templates.
• Use SMS + Email delivery. The template is set to use regular email-only delivery. The example updates the signer recipient object to use SMS + Email delivery. This pattern and the next example enable “late binding”: you don’t need to know the type of delivery until the envelope is sent. Pattern: composite templates.
• Use SMS-only delivery. The template is set to use regular email-only delivery. The example updates the signer recipient object to use SMS-only delivery. Pattern: composite templates.
• Add a webhook. This example configures a per-envelope Connect webhook. Either pattern can be used; the example uses a composite template.

Using templates with the API Request Builder

When you open an example in the API Request Builder, any templates the example includes will be uploaded to your DocuSign Developer account if they’re not already present. The templates’ names will always start with API Req Builder. You can delete the templates from your account if they’re not needed.

To modify an example’s template:

1. Use the DocuSign web app to make a copy of the template. Remove the API Req Builder part of the template’s name. Clear or rewrite the template’s description to remove the GUID.
2. Update the template as you wish.
3. Save any current work first! Then restart the API Request Builder by reloading its web page. The API Request Builder only refreshes its list of your account’s templates when the app is restarted.
4. Now reopen the example or load your saved diagram file.
5. Update the template blocks to use your new template.
6. Save the diagram.

To use a template from your account:

1. Create the template in your developer account.
2. Start or restart the API Request Builder. After you authenticate, it will create its list of your account’s templates.
3. You can now create a diagram that references your template.
4. You can make changes to your template without restarting the API Request Builder since the template’s ID does not change when you update the template.

Summary

Templates provide a powerful tool for building your applications and the API Request Builder enables you to easily test with them. Templates reduce the time and effort needed to create complex envelopes. Try a template today!

Additional resources

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