Custom Connect Technical Information. DocuSign Guide

DocuSign Administrator Guide is a comprehensive guide for administrators who are responsible for managing the DocuSign account. It contains detailed information on account settings, users, groups, signing and sending, integrations, auditing and the DocuSign Part 11 Module. This guide will help you to understand the features and capabilities of DocuSign and guides you through the process of setting up and managing your account in an efficient way.

PDF

Document

New DocuSign Experience Administrator Guide 151

Custom Connect Technical Information

This topic provides additional information about DocuSign custom Connect configurations. The information in this topic includes: l

Custom Connect

Best Practices

Recommendations for receiving documents

Custom

Connect and SOAP API publishing

XML message structure

Once you activate a custom Connect configuration, DocuSign sends an XML object to the secure

URL entered on the configuration page for every event selected and from every user selected.

If your application is not configured to accept these post messages, the DocuSign system will not return an error.

It is important that you do not turn on DocuSign Connect if you have not configured a listener or

Retrieving Service endpoint at the URL entered in the configuration page. Once you have the listener set up, you may test the publisher by sending transactions and observing the behavior of your application.

Note: You must include the protocol (HTTP: or HTTPS:) in the web address for Demo account.

You must include HTTPS:// in the web address for Production accounts because SSL is required in Production. Connect sends to the default ports of 443 for HTTPS: and 80 for HTTP. If you cannot use port 443 for Production contact DocuSign to review possible options.

Best Practices

In order to take advantage of DocuSign Connect, a clear understanding of the use of the information needs to be understood. Be sure to ask questions such as:

1. What data do you want to capture?

2. Who will be accessing this information?

3. What decisions or reporting will be generated?

4. Should the document be pushed?

These questions must be thought out and agreed in order to deploy a solution that will meet your business needs. Additionally, developing the secure listener application to have some flexibility can enable modifications to the data that is collected without requiring coding for minor adjustments. This field mapping approach enables future modifications and changes that can be made by analysts.

221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

New DocuSign Experience Administrator Guide 152

Recommendations for Receiving Documents

There are several factors to consider when determining how to receive envelope PDF documents from DocuSign in your document management system. While it is perfectly acceptable to just select the Include Document PDFs option in your Connect configuration to have Connect include the PDF documents when an event is triggered; you might consider using the DocuSign API to retrieve the documents when a triggering event (such as envelope status

Complete) is received if the following are considerations for your architecture: l

Throttling of document retrieval: If for some reason your service is not available to

Connect or you are expecting a very high volume, your processing routines might be overwhelmed by the Connect messages. If you are not appropriately scaled to handle the volume or catch-up spikes from connection outages, you might be at risk of an out of memory error.

File size and storage: Connect sends PDF documents in base 64 encoding format, which is on average 1/3 larger than a binary file format. This might or might not be a storage consideration for you.

In these cases, DocuSign often recommends that corporate and enterprise customers get the completed envelope message through Connect without including the PDF documents, then makes an API call to get those PDF documents at a time that make sense to your workflow and allow you to throttle the processing of those files.

Connect SOAP Publishing

The following configurations are available in Connect: l

Retrieving Service endpoint (URL).

Retrieving Service method name. DocuSignConnectUpdate.

Retrieving Service method’s argument name. DocuSignEnvelopeInformation.

Retrieving Service Namespace. The default is DocuSignConnectListener.

X.509 security in the SOAP Header. DocuSign uses the standard WSE3

BinarySecurityToken in the Soap Header to pass the certificate.

When planning the SOAP Publishing Retrieval Service, you need to do the following:

1. Create a web service that has the DocuSign API as a web reference.

2. Create a method in your web service that matches the Retrieving Service method name.

3. Have a single argument on the method that matches

221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

New DocuSign Experience Administrator Guide 153

The argument must be of the type DocuSignAPI.DocuSignEnvelopeInformation, where

DocuSignAPI is configurable based on the namespace used when importing the DocuSign

API web service.

4. Return the EnvelopeID passed to it, if received. Otherwise, it should return a SOAP Fault.

XML Message Structure

The DocuSign Connect publisher sends the status update in the body of an HTTP or SOAP XML post. The receiving web server needs to take the entire structure and parse the XML in order to make use of the various elements available in the XML.

Key Transaction Elements

The key transaction elements available are listed below. The full XML structure contains more, but these are the most commonly used data elements:

Status Information l

Sent Date/Time l

Envelope Status (in process, completed) l

Envelope ID

Document (Envelope) Information l

Document(s) l

Recipients l

Tabs l

Subject l

Email l

Custom Fields

Recipient activity and information l

Recipient ID(s) l

Recipient Email(s) l

Recipient Username(s)

221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

New DocuSign Experience Administrator Guide 154

Recipient Note(s) l

Recipient Type (Signer, CC, CD) l

Recipient Sent Date/time l

Recipient Delivered Date/time l

Recipient Signed Date/time l

Recipient Routing Order l

Recipient Status Code (created, sent, delivered, signed, declined) l

Recipient Event (viewed, declined, signed)

Document Information l

Document Name(s) l

Document ID(s)

Document Content l

Custom Tab Name l

Custom Tab Value l

Custom Tab Label l

Custom Tab Required/Not Required l

Custom Tab Type (text, checkbox, radio, list) l

TabTypeCode (signature, initial, name, company, title, date) l

Document PDF Bytes (base 64)

To make use of this information your application must parse the inbound XML looking for the data associated with each node you are evaluating. Then the application must extract the data and place it into the external application.

Form Field Data

DocuSign Connect is able to publish not only the status of the transaction, but also the values contained in any form fields or envelope fields in the transaction. This is useful to help interpret what transaction data can be updated into the external system. DocuSign supports many

221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

New DocuSign Experience Administrator Guide 155

different field types including checkbox, radio button, form field, and drop down list. These all have a common name structure and the value from the signer can be extracted from the XML structure.

Sample Connect Message

The information below is a sample DocuSign Connect message in XML format. Note that the personal information (names and email addresses), document names, and PDFBytes information has been removed from this sample.

<?xml version="1.0" encoding="utf-8"?>

<Type>Signer</Type>

<Email>[email protected]</Email>

<Status>Delivered</Status>

<TabType>Custom</TabType>

<Status>Active</Status>

<TabLabel>Radio</TabLabel>

<RoleName>TestRole</RoleName>

</TabStatus>

</TabStatuses>

<AccountStatus>Active</AccountStatus>

</RecipientStatus>

221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.

New DocuSign Experience Administrator Guide 156

</RecipientStatuses>

<Subject>CreateEnvelopeFromTemplates Test</Subject>

<Email> [email protected] </Email>

<Status>Delivered</Status>

<ACStatus>Original</ACStatus>

<ACHolder>ACHolder Name</ACHolder>

<ACHolderEmail> [email protected] </ACHolderEmail>

<ACHolderLocation>ACHolder Location</ACHolderLocation>

<SigningLocation>Online</SigningLocation>

<Name>Envelope Field 1</Name>

<Show>False</Show>

<Required>False</Required>

</CustomField>

<Name>Envelope Field 2</Name>

<Show>False</Show>

<Required>False</Required>

</CustomField>

</CustomFields>

<AuthoritativeCopy>false</AuthoritativeCopy>

<Name>Document_Name</Name>

<TemplateName>radio parents</TemplateName>

</DocumentStatus>

</DocumentStatuses>

</EnvelopeStatus>

<Name>DocumentPDF_Name</Name>

<PDFBytes>PDFBytes_Information</PDFBytes>

</DocumentPDF>

New DocuSign Experience Administrator Guide

</DocumentPDFs>

</DocuSignEnvelopeInformation>

157

Key features

Account settings
Users, groups, and permission sets
Signing and sending options
Connect configurations and API integration keys
Audit log for the account
DocuSign Part 11 Module

Frequently asked questions

You can access DocuSign Admin from the New DocuSign Experience by selecting the Go to Admin link in the account settings drop-down menu. You can also access it directly by going to https://admin.docusign.com.

The DocuSign Admin web application is divided into several sections: Accessing DocuSign Admin, Account, Single Sign On Overview, Users and Groups, Signing and Sending, Integrations, Auditing, and DocuSign Part 11 Module.

In Account settings, you can manage account billing and usage, profile, security, regional, and branding settings.

In DocuSign Admin, go to Security Settings, then click Document Retention. Clear the Always retain documents from completed envelopes check box and enter the number of days to retain documents from completed envelopes. You can also choose to remove metadata, including DocuSign fields, attachments, etc., from the system.

User questions

Mary F.

What is the maximum number of audit log events that can be exported at one time in a CSV file?

When exporting audit log events to a CSV file, the maximum number of events that can be exported at one time is limited to the number of rows displayed on the audit log page, which defaults to 100 events. To export more events, adjust the date range and then export to the CSV file.

Michael I.

How to configure digital signature adoption settings?

To configure signature adoption settings, go to Signing Settings in DocuSign Admin. Scroll to the Signature section and click Signature Adoption Configuration, where you can choose from three methods: draw, upload, or select a pre-defined style, and set your preferences.

Mary F.

What are agreement actions used for?

Agreement actions are used to track different bulk actions, such as uploading multiple users, envelope transfers, and publish envelope actions for an account. Administrators can view these actions in the Bulk Actions Log, which provides details on the type of action, status, administrator name, and date.