New DocuSign Experience Administrator Guide 144
Custom Connect Configuration
This topic provides information about how DocuSign's custom Connect configuration. The information in this topic includes: l
An
overview
of DocuSign Connect l
General Connect set-up information
and prerequisites l
Creating a Custom Connect Configuration
l
Editing a Custom Connect Configuration
l
Changing a Custom Connect Configuration Status
l
Deleting a Custom Connect Configurations
Overview
DocuSign Connect is a push service that sends real-time envelope and recipient data updates to customer listener applications. These updates are generated by changes to the envelope as it progresses from sending to completion. Connect provides updated information about the status of these transactions, including the actual content of document fields. Connect is useful to organizations that want a real-time view into the transactions across their user base in a centralized location. This information can be customized to drive reporting or workflow specific to that organization’s needs. Customers can create multiple custom Connect configurations, each with different events or users, and set up different listeners to monitor those configurations.
A DocuSign Connect configuration watches envelopes, noting when transactions reach the subscribed event triggers. At that point Connect sends an XML status change to the customer’s listener. The general flow of events is outlined below.
221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.
New DocuSign Experience Administrator Guide 145
An organization’s external application can use a secure (HTTPS) listener or an API interface to accept information from Connect.
l
The listener is an application that accepts XML transactions sent from DocuSign Connect as events happen. This interface is not a SOAP API, such as the other interfaces in the
DocuSign System, instead the messages are sent through an HTTP POST.
l
The API interface uses DocuSign’s SOAP or REST API, like the other interfaces in the
DocuSign System, to receive XML information posts.
Note: For cases where envelopes are sent through the DocuSign API with event notification enabled and Connect is also used, when the events for both the API and Connect are set to be the same, then two separate notifications are sent for the envelope. One from the API and another from Connect.
See the
custom Connect technical information
for additional information and best practices.
General Setup Information
In order to use DocuSign Connect, Connect must be enabled in your DocuSign account. It is not enabled by default. Once enabled, the Connect Settings page can be accessed from the
DocuSign Admin web application.
At a high level, the following steps must be taken to use a custom Connect configuration:
1. Request your account be configured to publish transaction updates. This step might be completed as part of your account setup. Your DocuSign Account Manager can help you with this step.
2. Select the events you will use as triggers for updating the information. Events can include several items such as document sent, viewed, signed, completed, etc.
Note: You can create multiple Connect configurations with different event triggers and users.
3. Develop an understanding of the XML data sent from Connect to your application.
4. Determine how your application will accept information from Connect; by secure listener or by an API interface.
l
If using a secure listener: Create an application at your HTTPS location that can accept data, parse the inbound XML data and utilize it. This is a web application written specifically for your business.
221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.
New DocuSign Experience Administrator Guide 146
l
If using an API interface: Create a Retrieving Service endpoint (URL), method name, method’s argument name, and Namespace. Refer to the Connect SOAP Publishing section for more information about using the SOAP interface. Inclusion of the DocuSign X.509 certificate in the SOAP header is optional.
Creating a Custom Connect Configuration
In order to use DocuSign Connect, Connect must be enabled in your DocuSign account. It is not enabled by default.
1. In DocuSign Admin, click Connect.
2. On the Connect Configurations page, click CONNECT CONFIGURATION or ADD
CONFIGURATION and select Custom.
An account can have a maximum of 300 Connect configurations.
3. On the configuration page you set the events that generate information and select the users integrated with the information.
Set the DocuSign Connect configuration settings as follows: l
Name: This is name of the Connect configuration. The name helps identify the configuration in the list.
l
URL to Publish: This is the web address and name of your listener or Retrieving
Service endpoint. 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.
Note: If you cannot use port 443 for Production contact DocuSign to review possible options.
l
Enable Log: Select this option to enable logging for this configuration. It is recommended that you enable this option to facilitate troubleshooting any problems. If you do not want to enable logging for this configuration, clear this box.
DocuSign will keep the last 100 log entries for all Connect configurations for the account. The log entries can be viewed by clicking LOGS on the Connect page.
l
Require Acknowledgment: Select this option to log posting failures. DocuSign waits 100 seconds for an acknowledgement before recording a failure. DocuSign logs a failure if the attempt to reach the external endpoint returns anything other
221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.
New DocuSign Experience Administrator Guide 147
than an HTTP 200. The acknowledgment failure messages are logged on the
Failures page, which is accessed by clicking FAILURES on the Connect page. When this option is selected, DocuSign will automatically attempt to repost any failures.
You can also manually repost from the Failures page.
l
Include Document PDFs: Select this option to have Connect send the PDF documents along with the XML update. If you do not want to receive the PDF documents with the updates, clear this box. For more information about this see
Recommendations for Receiving Documents.
l
Include Certificate of Completion: Select this option to have Connect include the
Certificate of Completion with completed documents. If you do not want to receive the Certificate of Completion with the updates, clear this box.
l
Include Time Zone Information: Select this option to include the document time zone information.
l
Include Document Voided Reason: Select this option to include the reason a document was voided (as entered by the person that voided the document) in the message.
l
Include Sender Account as Custom Field: Select this option to include the sender account information as a custom field on the Connect message.
l
Include Document Fields: Select this option to include the Document Fields associated with documents. Document Fields are optional custom name-value pairs added to documents using the API. Custom Document Field information is returned with status, but otherwise is not used by DocuSign.
l
Associated Users: Select the users associated with the trigger events. These are the users whose trigger events are sent to the listener or Retrieving Service endpoint. If a user is not selected, no information is sent about the user’s documents.
Select All users (includes new users) to send document information for all the current users and new users when they are added to the account.
Select Select users to include to view a list of all users associated with the account. Move users between the Available and Selected boxes using the Add and
Remove buttons.
l
Trigger Events: Select the trigger events for updating your system. There are two categories of trigger events - Document Events and Recipient Events. The
221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.
New DocuSign Experience Administrator Guide 148
difference between document events and recipient events is that document events are only triggered when the document status changes, while recipient events are triggered each time information for a recipient changes.
Note: In cases where multiple events for a single document or recipient are queued, only one set of XML data with the most recent change is published to a customer’s listener.
The following lists provide information about when particulate document and recipient events are sent by Connect.
Document Event Trigger Descriptions n
Document Sent - This event is sent when the email notification, with a link to the document, is sent to at least one recipient. The document remains in this state until all recipients have viewed the envelope.
n
Document Delivered- This event is sent when all recipients have opened the document through the DocuSign signing website. This does not signify an email delivery of a document.
n
Document Signed/Completed - The document has been completed by all the recipients.
n
Document Declined - The envelope has been declined by one of the recipients.
n
Document Voided - The envelope has been voided by the sender.
Recipient Event Descriptions n
Recipient Sent - This event is sent when an email notification is sent to the recipient signifying that it is their turn to sign a document.
n
Recipient Delivery Failed - This event is sent when DocuSign gets notification that an email delivery has failed. The delivery failure could be for a number of reasons, such as a bad email address or that the recipient’s email system auto-responds to the email from DocuSign.
n
Recipient Delivered - This event is sent when the recipient has viewed the document(s) through the DocuSign signing web site. This does not signify an email delivery of an envelope.
n
Recipient Signed/Completed - This event is sent when the recipient has
221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.
New DocuSign Experience Administrator Guide 149
signed (completed) the document. If the recipient is not a signer, this is sent when the recipient completes their actions for a document.
n
Recipient Declined - This event is sent when the recipient declines to sign the document(s).
n
Recipient Authentication Failed - This event is sent when the recipient fails an authentication check. In cases where a recipient has multiple attempts to pass a check, it means that the recipient failed all the attempts.
l
Use Soap Interface (SOAP method: DocuSignConnectUpdate): Select this option to use the SOAP interface Retrieving Service. If this option is selected, you must add your Namespace for the service.
l
Sign Message with X509 Certificate: Select this option to have a message sent to the listener signed with a DocuSign X.509 certificate. The text is viewable, this just verifies the content viewed is what was sent.
l
Require Mutual TLS: Select this option to enable mutual authentication at
Transport Layer Security (TLS) with DocuSign. DocuSign uses TLS v1.2 by default for all Connect messages, but will support earlier versions of TLS if required by the listener.
If the Sign Message with X509 Certificate option is selected, DocuSign will sign the message with our X509 certificate but it also requires that your listener provide an
X509 certificate to DocuSign for mutual authentication.
Note: At this time, self-signed certificates are not supported in Connect and the
Certificate Authority associated with your certificate must be in DocuSign’s CA store.
4. Click ADD to save your configuration. You can modify this information or add another custom configuration by repeating the previous steps.
Editing a Custom Connect Configuration
1. In DocuSign Admin, click Connect.
2. The page has a list of existing Connect configurations for the account. Find the configuration you want to edit
Click on the configuration name or click ACTIONS and select Edit.
221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.
New DocuSign Experience Administrator Guide 150
3. Edit the configuration as needed. Refer to the
Creating a Custom Connect Configuration procedure
for explanations of the custom configurations settings.
4. Click Save to save the changes.
Changing a Custom Connect Configuration Status
Normally when a custom configuration is created it is set to active status, which means
DocuSign Connect is sending data to the entered web address. There might be times when, due to maintenance or other issues, you need to stop DocuSign Connect from sending data without deleting the configuration. In this case you can change the custom configuration status to inactive and then change it back to active when your listener is ready to receive data.
1. In DocuSign Admin, click Connect.
2. The page has a list of existing Connect configurations for the account. Find the configuration you want to edit.
Click ACTIONS and select Deactivate to change the status to Inactive or Activate to change the status to active.
Deleting a Custom Connect Configuration
In cases where a custom Connect configuration should no longer be used, you can delete it from the system. If a configuration will not be used temporarily, DocuSign recommends changing the configuration status to Inactive and then activate it again when it is needed.
1. In DocuSign Admin, click Connect.
2. The page has a list of existing Connect configurations for the account. Find the configuration you want to delete.
Click ACTIONS and select Delete to delete the configuration
221 Main Street, Suite 1000, San Francisco, CA 94105 Ι Tel. 866.219.4318 Ι www.docusign.com Ι © DocuSign, Inc.
