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

(You can sign up for a 30 day trial account at https://account.docusign.com)

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

    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 Envelope 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. (You may need to contact DocuSign support and get the “Envelope Custom Fields” option enabled on your account, as be default this will be missing).
  6. 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 take a look at the purchaser-order-failure tutorial.

    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)
  7. 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
  8. The listener also supports envelope custom fields with properties:

    • name (String)
    • value (String)
  9. 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