The DocuSign connector provides a standard mechanism in Alfresco Process Automation to send documents for digital signing in DocuSign. The DocuSign connector is displayed on the process diagram as a pen.

Important: The DocuSign connector requires a DocuSign account to handle document signing. This account is separate to the Alfresco hosted environment and should be created and managed by customers.

The actions that can be executed using the DocuSign connector are:

• SEND_FOR_SIGNATURE
• DOWNLOAD_DOCUMENT

As part of the BPMN definition process, any service task that is responsible for sending or downloading a document must set the docusignconnector.SEND_FOR_SIGNATURE or docusignconnector.DOWNLOAD_DOCUMENT properties as the value for its implementation attribute.

The following input parameters must also be provided for the DocuSign API in the Service task depending on the implementation.

BPMN Tasks Configuration

This process definition shows an example of how to set up the connector in Process Automation.

As part of BPMN definition process, any Service Task responsible for sending the document needs to set docusignconnector.SEND_FOR_SIGNATURE or docusignconnector.DOWNLOAD_DOCUMENT as the value for its implementation attribute.

In addition to the above, these input variables must be provided for the DocuSign API in the Service Task depending on the implementation:

SEND_FOR_SIGNATURE

The SEND_FOR_SIGNATURE action is used by the DocuSign connector to request a digital signature on a document.

The input parameters for SEND_FOR_SIGNATURE are:

Note: The connector can only receive either signers or recipientEmail but not both at the same time. The connector must receive either signHereTabLabel or signHerePage to fixed the positioning. If one of them is null the signature can be where the signer selects.

The output parameters from SEND_FOR_SIGNATURE are:

DOWNLOAD_DOCUMENT

The DOWNLOAD_DOCUMENT action is used by the DocuSign connector to download the envelope from DocuSign. It takes into account the envelopeId that is the UUID that relates to the envelope.

The input parameters for DOWNLOAD_DOCUMENT are:

The output parameters from DOWNLOAD_DOCUMENT are:

No exceptions or errors are thrown by the connector, however all exceptions are caught and logged. The task execution is always successful, and errors will be returned in an error event.

The following is an example of the POST body for the Activiti REST API endpoint http:///-rb/v1/process-instances:

{
  "processDefinitionKey": "DocuSignProcessTest",
  "processInstanceName": "processDocuSignTest_Simple",
  "businessKey": "MyBusinessKey",
  "variables": {
  	"recipientEmail" : "test@test.com",
  	"recipientName" : "AAE Test",
  	"emailSubject" : "Sign this document",
    "files" : [
        {
  	        "nodeId" : "<node-id-of-document-to-be-signed>"
        }
    ],
  	"outputFileName" : "testFileName.docx",
  	"nodeFormat" : "docx",
  	"documentId" : "10",
  	"signHerePage" : "1",
  	"signHereX" : "100",
  	"signHereY" : "200",
  	"timeout: "3600"
  },
  "payloadType":"StartProcessPayload"
}

In the business process definition, the service task called docuSignTask has the implementation attribute configured to use the connector.

<bpmn2:serviceTask id="ServiceTask_1cheezm" name="docuSignTask" implementation="docuSignConnector.SEND_FOR_SIGNATURE">
      <bpmn2:incoming>SequenceFlow_1siaofh</bpmn2:incoming>
      <bpmn2:outgoing>SequenceFlow_0nmtcso</bpmn2:outgoing>
</bpmn2:serviceTask>

No exceptions or errors are thrown by the connector. All exceptions are caught and logged. The task execution is always successful, and errors will be returned in an error event.

Configuration

1. Log into the DocuSign eSignature console and click Settings on the top right.

2. Click the ADD CONFIGURATION dropdown list and select Custom.

3. Under Listener Settings, select Active Connection from the Status dropdown list.

4. Under Listener Settings, enter your URL to Publish URL.

   The pattern of the URL must follow: {domain-name}/{application-name}/connector/{connector_name}/listener.

5. Under Event Settings, select Aggregate from the Event Message Delivery Mode dropdown list.

6. Under Event settings > Trigger events > Envelope Events, ensure the following are selected:

   • Envelope Sent
   • Envelope Delivered
   • Envelope Signed/Completed
   • Envelope Declined
   • Envelope Voided

7. Under Event settings > Trigger events > Recipient Events, ensure the following are selected:

   • Recipient Sent
   • Recipient Auto Responded
   • Recipient Delivered
   • Recipient Signed/Completed
   • Recipient Declined
   • Recipient Authentication Failure

8. Click SAVE CONFIGURATION.

Logs and failures

Once the listener has been created and is working you can see the logs and the failures from the same menu. You can click on one of the logs or failures and a popup with information is displayed.

Triggers for DocuSign events

1. From the Modeling Application, create a new trigger with one of the events.

2. You can filter the trigger using the condition field, which is an expression that must be true in order to trigger an action.

DocuSign Environment Configuration

The connector uses the DocuSign client library that relies on the DocuSign REST API and uses OAuth JWT for authentication, for more see OAuth JWT.

The basic steps to achieve this are:

1. Create a DocuSign account, for more see Sign documents for free.

   Register for a free developer sandbox account.

2. Configure an app for JWT in DocuSign, for more see How to get an access token with JWT Grant authentication.

   You need the private RSA key for the connector configuration.

3. Grant consent to the app, for more see How to obtain individual consent.

   The same user account from step 1. can be used, or a new one can be created.

Events

The DocuSign connector produces events when the DocuSign envelope changes its status.

Note: These events can be consumed by the process using Triggers. For example, a BPMN catch message event inside a process can be waiting for a trigger event that is set to ENVELOPE_DECLINED, and a trigger action set to throw a BPMN message.

The events are:

• ENVELOPE_VOIDED - The envelope has been voided by the sender or has expired. The void reason indicates whether the envelope was manually voided or expired.
• ENVELOPE_DECLINED - The envelope has been declined by one of the recipients.
• ENVELOPE_COMPLETED - The envelope has been completed by all of the recipients.
• ENVELOPE_DELIVERED - This event is sent when all recipients have opened the envelope through the DocuSign signing website. This does not signify an email delivery of an envelope.
• ENVELOPE_SENT - This event is sent when the email notification, with a link to the envelope, is sent to at least one recipient or when it is a recipient’s turn to sign during embedded signing. The envelope remains in this state until all recipients have viewed the envelope.

For more on events see Webhook event triggers.

When a Process Automation process is instantiated this way, the following variables are populated:

The connector is listening for events using the webhook that follows the pattern:

- {domain-name}/{application-name}/connector/{connector_name}/listener

Errors

The possible errors that can be handled by the DocuSign connector are: