The DocuSign integration allows you to use either Workbooks PDFs or DocuSign Templates. This article covers how to setup a DocuSign Template.

Creating a Template in DocuSign

Before you can configure the integration in Workbooks, you will need to upload a blank Template within DocuSign. Login to your DocuSign Account to do so.

Once logged in, select the Templates option from the toolbar at the top of the page.

Select the New button at the top of the toolbar on the left side of the screen.

In the new template, set the following fields:

• Template Name: This is the name that will appear in the DocuSign Plugin within Workbooks when setting up a new document configuration
• Template Description: Provide a brief description so it's clear how this template is being used.

Finally, upload the document that will form the basis of your Template. Documents can be uploaded from your computer or uploaded from a number of file sharing sites.

Next, you will need to define placeholders for Template Roles within this Template. When the integration generates an envelope using this template, the Template Roles are matched with Workbooks Relationships, and the Recipient automatically added to each role specified in the Template. The Role entered here must be an available relationship value that has been configured in Workbooks. For each record type, the values available differ:

For Transaction Documents, the picklist can be amended in Workbooks under Configuration > Customisation > Picklists. Filter by Name for the "Document People Roles" or "Opportunity Contact Roles" (if using Opportunities) picklists to see available values.

In this example, add one recipient, where the Role is set to Primary Contact with "Needs to Sign" as the signing action. Multiple recipients with either the Needs to Sign (Signer) or "Receives a Copy" (CC) signing action can be added as required. More information on Templates and Template Roles in DocuSign can be found here. You will need to know the Roles that have been configured later in the setup, so leave this window open.

As a final step, save the Template by clicking Actions > Save and Close, otherwise it will not be available within Workbooks to complete the next steps.

Set up the Template in Workbooks

Return to Workbooks to configure the DocuSign Integration with your new Template. The DocuSign menu can be accessed from Start > Configuration > Email & Integration.

Plugin - Step 1 - Introduction

On the first page, select New Document then Continue. If this is the first document that you have configured, then you will taken straight to Step 2 below.

Plugin - Step 2 - Settings

Work through the Plugin settings, configuring them to your requirements as needed. See here for further information on each setting. There are a few important settings that must be configured as detailed below for the integration to work with a DocuSign Template:

• Select DocuSign Template in the Integration Type picklist
• Select the DocuSign Template created in Stage 1 of this guide for the DocuSign Template picklist
• Ensure that you configure "Which relationship roles should be used as Signers" and "CC Recipients" as per the Template Roles configured in DocuSign e.g. if you created a Template Role of Primary Contact in DocuSign and set this role as the Signer, ensure you select Primary Contact in the "Which relationship roles should be used as Signers" in the plugin.
  • NOTE: If you do not choose the same Relationship here as you have configured on your DocuSign Template, the Process Button will error with the following message:

​

Click "Continue" when you are happy with the settings.

Plugin - Step 3 - Configure AutoPlace Mappings

This step allows you to configure fields from your selected Workbooks record type to populate fields on the DocuSign Template when a new envelope is generated. The integration has the capability to default the field values on the DocuSign document to the value held within Workbooks. When the document is signed, the updated information can be reflected back in Workbooks.

To set up a new Mapping select the Add New button. In the dialogue box, populate the following information to create a new field mapping

• Docusign Tag Type: The DocuSign Field data type. The Tag Type can affect how data is displayed on the Document, more information can be found on DocuSign’s Support Site. Based on the Workbooks Custom Field type, we recommend reviewing this page which details the best type to use for the integration.
  • For DocuSign Tags that cannot be set to Workbooks values such as Signatures, Recipient Names, Date Signed etc, you should add these directly to the DocuSign Template in the following steps. They do not need to be added here.
• DocuSign Anchor String: This defines where on the document the tag will appear if the tag is found by DocuSign in your template. See here for DocuSign's help page on Anchors. This is optional and can be left blank if your Template does not have Anchor Tags specified. Fields can manually placed if this is the case.
• Workbooks Field: Select the field which will be used to initially pull through a value to the DocuSign Field. This field can then be updated if the field is made editable in DocuSign
  • Multi-select picklists are not supported in DocuSign and therefore, if configured in Workbooks, do not show in this list
  • Picklist selections may break if they contain a semi-colon in the value, due to a limitation in DocuSign

Once you have added a mapping, it can be edited or deleted using the Actions button beside each row. 5 mappings are shown per page. A search feature is provided if you have several mappings - you can search by DocuSign tag name, DocuSign field type or Workbooks field name. Mappings are not stored until you click Continue. 

Plugin - Step 4 - Related Record Mappings

If you turned on the Update Related Records setting in Step 1, then a 2nd Mappings screen is shown. This screen allows you to configure mappings for fields that are on records related to the source record via a DLI field. For example, you may have a Contact DLI which relates a Person to your source document.

The process for adding mappings is the same as Step 3. However, there are two slightly different options:

• Workbooks DLI Field: This is a list of all DLIs on the selected record type set in Step 1
• Workbooks Field: A DLI is driven from a report based on a record type. Once you select a DLI, this list will be populated with the fields from that record type.
  • For example, if you have a Person DLI, the report will be based on People and thus the fields shown here will be for People records.
  • This feature only allows you to drill through to one record. You cannot subsequently drill through to another record related to the first.

Again mappings can be edited or deleted using the Actions menu. They can also be searched. Changes will not be applied until you click Continue.

Plugin - Step 5 - Complete

The DocuSign document is ready to be generated. However, you will now need to add a Process Button to the appropriate Form Layouts so you can send the document out. This is documented fully on this page: here.

Once you have completed the configuration screen, it can take up to 1 hour for the mappings to synchronise to DocuSign. Field mappings are synced to DocuSign using the DocuSign Maintain Fields Scheduled Process. If you have created a lot of mappings, it may take several hours to sync - a maximum of 100 fields per hour are created to avoid DocuSign API Limits.

After the final page is complete, you will need to configure a Process Button as explained here.

Configuring DocuSign Fields

Back in DocuSign, select the Template that you configured earlier, then click Edit. In Edit mode, you can make any final amendments to the Template. Click Next to generate a Template mockup. From here, you can add the DocuSign Fields to your Template.

Under Standard Fields, you can should add any fields where a Workbooks Field Mapping was not created such as for Signatures, Date Signed, Recipient Name etc. Add these to your Template by dragging and dropping them into the relevant location on your Template. If you have multiple Template Roles, change the recipient in the top left, before adding the field to setup who can populate each field:

Once Workbooks Fields have synced, you will see a DocuSign Custom Field under the Custom Field section within the Template. Each field is prefixed with the Record Type and then has the Field Label so you can easily identify which fields to include in your document. For fields that are linked to related records, they will have "DLI" in the field label, and also the corresponding Workbooks DLI name so you can easily identify fields. These fields can also be dragged and dropped onto your template. If you specified an Anchor String when you created the mapping, then DocuSign will attempt to place the field at all occurrences of that anchor.

Custom Fields are automatically mapped back to the corresponding Workbooks field when the document is signed. You should not create any new Custom Fields directly in DocuSign as these will not map back to Workbooks.

Once you have added the Custom Field to your DocuSign Template, configure the settings for that field directly within the properties panel of DocuSign, such as making it Read Only, Required, changing the font etc.

Once this step is complete, Save and Close. You can now generate a new DocuSign envelope for signature using this Template.