Clause users with a DocuSign account can use the DocuSign Listener to enable their Smart Clauses to respond to DocuSign Connect events. 

How to configure your DocuSign account to send DocuSign Connect events to Clause:

  1. Log in to your DocuSign account via https://account.docusign.com
  2. Click your avatar at the top right. In the dropdown, choose "Go to Admin".
  3. From the Admin console, choose "Connect" from the left-hand side menu.
  4. Click "Add Configuration" and choose the "Custom" option.
  5. In the field "URL to Publish", type https://docusign-listener.clause.io
  6. Make sure to check the box to include "Time Zone Information". The listener requires the time zone offset to be included in the Connect event information.

In order for the DocuSign Listener to send a request to your Smart Clause, you must provide a Bearer Token and the clause ID or trigger URL. This can be done in one of two ways:

  1. Add clauseId and bearerToken query parameters to the DocuSign Listener URL so that the URL appears as follows (replace the placeholders with the actual values). To do this, make sure you have started with a Smart Clause on your contract in Clause where you will find these two values:
    https://docusign-listener.clause.io?clauseId=ABC&bearerToken=DEF
  2. Add custom fields to your DocuSign envelope with the names triggerUrl and bearerToken.  You must do this via your DocuSign account. From your avatar, select "Go to Admin". Select "Envelope Custom Fields". Add triggerUrl and bearerToken as custom fields. Now, when you create a new envelope in DocuSign, you will see "Envelope Custom Fields" below the recipient section where you can enter the correct values.

The trigger URL and Bearer Token for your Smart Clause can be found in the right-hand sidebar of the Clause contract editor under "Triggers":

Once the DocuSign Listener has been configured (using either method 1 or 2 above) it will send the DocuSign Connect events to the Smart Clause.

Simple Example Using docusign-connect Template

If you'd like to try out the DocuSign Listener with a simple example, try adding the docusign-connect Smart Clause from the Accord Project Library to your Clause contract. This Smart Clause listens for a specified envelope status event and increments a counter each time an event is emitted with that envelope status.

The docusign-connect template emits a notification obligation, which you can use to send a notification, such as an email or Slack message. From the Clause contract editor, you can configure your Smart Clause to send an email each time a notification is emitted from the Smart Clause via the right-hand sidebar under "Actions". Select the "Email" action to send a simple message via email.

Use the "Custom" action to use variables from the response, such as response.message.

{
  "$class": "io.clause.outbound.physical.alerts.email.EmailMessage",
  "contractId": metadata.contractId,
  "to": "<EMAIL>",
  "subject": "<SUBJECT>",
  "message": response.message
}

Advanced Example Using purchase-order-failure Template

If you'd like to try a more advanced template, add the purchase-order-failure Smart Clause to your contract on Clause. This Smart Clause will determine if a purchase order is received past the due date and issue a payment obligation for a penalty if late. The Smart Clause is stateful and will keep track of the total number of late purchase orders. When the number reaches the integer set as maxFailures, an additional charge will be added to the penalty. 

You can configure your Smart Clause to send an email with the amount owed or even trigger a Stripe payment to be made, described here.

Once you have a contract running on Clause with the purchase-order-failure Smart Clause, you can issue purchase order agreements from your DocuSign account. Each DocuSign envelope should include the following custom envelope fields: triggerUrl, bearerToken, and must have the text recipient tabs with the following tab labels and validations: deliveryDate with Date validation, actualPrice with Numbers validation and currencyCode with no validation. You can create a template that pre-populates the triggerUrl and bearerToken with those from the Smart Clause. When the agreement is signed (signaling receipt of the order), the Smart Clause will be triggered and will check the time of receipt against the delivery date and emit a payment obligation if late.

Create Your Own Template

You can also create your own Smart Clause template that responds to DocuSign Connect events. A Smart Clause can utilize any of the following fields that are sent via a DocuSign Connect event, as illustrated in the model

The following envelope status fields are supported:

  • status ("Any", "Voided", "Created", "Deleted", "Sent", "Delivered", "Signed", "Completed", "Declined", "TimedOut", "Template", or "Processing")
  • envelopeId (String)
  • created (DateTime)
  • sent (DateTime)
  • delivered (DateTime)
  • signed (DateTime)
  • completed (DateTime)
  • declined (DateTime)
  • email (String)

The following recipient fields are supported:

  • status ("Created", "Sent", "Delivered", "Signed", "Declined", "Completed", "FaxPending", or "AutoResponded")
  • email (String)
  • userName (string)
  • sent (DateTime)
  • delivered (DateTime)
  • signed (DateTime)
  • declined (DateTime)
  • declineReason (String)
  • tabStatuses (Array) - see next section for more info

The listener also supports envelope custom fields with properties:

  • name (String)
  • value (String)

Using Recipient Tab Statuses

Recipient Tab Statuses are tags that are dragged onto a DocuSign envelope upon being sent, and can be filled out either by the sender or the signer. After dragging on a recipient tab in the DocuSign UI, edit the "Data Label" to be a variable name that can be mapped to your Smart Clause template.

The DocuSign Listener converts certain types of recipient status tabs into data types that are used by the Concerto Modeling language and can be used in a Smart Clause template's logic. The type of recipient tab and its validation determine the data type it is transformed into. Refer to the DocuSign connect model and the table below:

Connect Model ConcepttabValue Data Type
Recipient Tab Type
Recipient Tab Validation
DateTabStatus
DateTimeTextDate
NumberTabStatusDoubleTextNumbers
TextTabStatusStringTextNone
BooleanTabStatusBooleanCheckbox, RadioN/A
ListTabStatusArrayDropdownN/A