Table of Contents

Article

Integrating DocuSign with the Pega 7 Platform

The DocuSign service is a popular way to electronically sign documents for a variety of business transactions. You can integrate DocuSign with your Pega 7 Platform application to collect digital signatures during case processing. You can sign, review, and exchange documents electronically, which eliminates having to manually print, sign, and scan documents back into your system. You can also make dynamic corrections and modifications to the documents before signing them.

Do the following tasks to integrate DocuSign with the Pega 7 Platform:

  1. Create a DocuSign integrator key.
  2. Make a signature request to DocuSign.
  3. Configure DocuSign to send response notifications.
  4. Optional: Cancel a document that has been sent out for signature collection.

Prerequisites

Before integrating the DocuSign service with your Pega 7 Platform application, you must have a DocuSign account and apply a hotfix if you are using Pega 7.2.

Creating a DocuSign account

Create a developer account with DocuSign. You can later upgrade the account to a production account.

  1. Create a developer account with DocuSign.
  2. Sign in to your developer account.
  3. Create a DocuSign template to define recipient roles, signing instructions, and informational fields.
  4. Upload a document by using the template that you created.
  5. Create tags for the document that you uploaded to indicate locations on the document where the recipient needs to take an action or provide information, for example, where a signature is required.
  6. Optional: Send your document to a group of recipients to test the configuration.

Applying a hotfix

If you are using Pega 7.2 , apply the HFIX-26109 hotfix package to your Pega 7 Platform application by using the Hotfix Manager. This hotfix package contains a hierarchy of abstract Pega 7 Platform classes that you can use to modify the most common configuration options when you make a signature request to DocuSign.

This hotfix package is not required for Pega 7.2.1 and later.

Integrating DocuSign with your Pega 7 Platform application

To integrate the DocuSign service with your application, create a DocuSign integration, and then create a DocuSign envelope in your Pega 7 Platform application. You can also configure DocuSign to notify your application when a document is signed by the recipients.

Creating a DocuSign integrator key

Create a DocuSign integrator key by doing the following actions:

  1. Sign in to your DocuSign account.
  2. In the operator drop-down menu, click Go to Admin.
  3. Click API and Keys in the Integration section.
  4. Click Add Integrator Key and make note of the API account ID and integrator key.

Making a signature request to DocuSign

Do the following actions in your Pega 7 Platform application to make a signature request to DocuSign and create an envelope that sends multiple documents to multiple recipients:

  1. Add the DocuSign smart shape to a new or existing flow. The pxSendViaDocuSign activity validates the inbound envelope page, and then invokes the pxSendNewEnvelope REST connector to send the request to DocuSign. You can point the URL endpoint of the REST connector to the demo or production DocuSign service by configuring the pyPrepareNewEnvelope data transform (step 2.3). The pyProcessNewEnvelopeResponse activity handles the response from DocuSign.
    1. Add the Send via DocuSignsmart shape to your flow, as shown in the following figure:

      Adding a DocuSign smart shape

    2. Optional: Configure the smart shape to reference the top-level page name that is populated in the pyPrepareNewEnvelope data transform in the Envelope field, as shown in the following figure:

      Configuring a DocuSign smart shape

      • If you do not enter a name in the Envelope field, the underlying pxSendViaDocuSign activity creates a page with a default name.
      • By default, the system sends the documents that are currently attached to your case to DocuSign for signature collection. The next step describes how you can customize your signature request.
  2. Customize your signature request:
    1. Override the pyPrepareNewEnvelope data transform to prepare the envelope for making the signature request to DocuSign. For more information, see Steps in thepyPrepareNewEnvelope data transform.
    2. Review the pySetEnvelopeCredentials data transform that is referenced in the pyPrepareNewEnvelope data transform. This data transform sets the DocuSign account credentials (account ID, user name, password, and integrator key).
    3. Override the pyAssignRecipientsToEnvelope data transform that is referenced in the pyPrepareNewEnvelope data transform. For more information, see Steps in the pyAssignRecipientsToEnvelope data transform.
Ensure that all three data transforms are specialized into your application ruleset.

Configuring DocuSign to send response notifications

You can configure DocuSign to notify your Pega 7 Platform application when a DocuSign document is signed by all the recipients.

  1. Sign in to your DocuSign account.
  2. Enable DocuSign Connect for your account.
  3. Add a custom Connect configuration that points to your Pega 7 Platform application server.
    • Specify the URL of the REST service as https://<Your domain>/prweb/PRRestService/DocuSignService/Services/pyConnect. This REST service is included in the hotfix package that you installed.
      Ensure that the URL of the REST service is visible from the DocuSign service.
    • Select the check box to include PDF documents.
    • Select the trigger event to notify your Pega 7 Platform application when a document is signed or completed.
      You can also programmatically register for any of these events in steps 2.4.6.7 and 2.4.6.9 in the pyPrepareNewEnvelope data transform by using the EventNotification element. If both DocuSign Connect and the EventNotification element are registered for the same event with the same service URL, the service is invoked twice.
      The REST service listens to the events from DocuSign. When the Pega 7 Platform application receives the signed or completed event, the completed document is attached to the case that originally triggered it.

Canceling a document

You can cancel a document that has already been sent for signature collection if you decide to sign the document offline. To cancel a single in-process envelope that is not locked or signed by any of the recipients, do the following actions:

  1. Add the pxVoidDocuSignEnvelope flow action as a case-wide local action.
  2. Override the pySetEnvelopeCredentials data transform to specify the ID of the envelope that you want to cancel.

At run time, you can cancel an outstanding document by selecting the local action from the work object.

Troubleshooting

The following issues can prevent the REST connector from sending your request to DocuSign:

  • The top-level inbound page is not found or created.
  • Some of the email recipients are not valid.
  • The status for the envelope is not valid. "Created" and "Sent" are the only valid statuses.
  • Documents are not in binary format.
  • Document IDs are not valid.
  • File extensions of documents are not valid.
  • Recipient IDs are not valid.
  • The mapping of document IDs to recipient IDs when using the Sign Here or Date tabs in DocuSign is not valid.

If you experience issues while getting DocuSign to send your request, you can troubleshoot your request by inspecting the DocuSign response messages on the Pega 7 Platform clipboard.

Additional concepts

This section describes the significant steps of the pyPrepareNewEnvelope and pyAssignRecipientsToEnvelope data transforms, which are referenced in this article.

Steps in the pyPrepareNewEnvelope data transform

The pyPrepareNewEnvelope data transform enables you to prepare the DocuSign envelope that has all the information that is required to make a successful signature request to DocuSign. Each request is stored in the top-level clipboard page of the Pega-Int-DocuSign-NewEnvelope class that is populated in the pyPrepareNewEnvelope data transform. You can override this data transform to insert data that was collected during case processing.

The following table describes the steps on the Definition tab of this data transform.

Step numberDescription
2.2

Call the data transform and extension point pySetEnvelopeCredentials to provide the account ID, user name, password, and integrator key.

It is a best practice to use an encrypted account ID and user name from the DocuSign Admin panel when adding an integrator key.

2.4.1Set an email summary for your outgoing signature request message.
2.4.2Set an email subject.
2.4.4Set the overall status of the request. The "Sent" status sends the envelope.
2.4.6Set the options that control envelope and recipient responses. A DocuSign Connect needs to be configured for the system to send notifications to your Pega 7 Platform application.
2.4.6.8

Register for envelope events. You can register for the document events "Sent," "Delivered," "Completed," "Declined," and "Voided." You can implement specialized business logic to execute upon the receipt of these envelope events by using the document event extension points.

By default, the system registers for the "Completed" event. After all the recipients sign your documents, DocuSign returns the documents to your application and attaches them to your work object.

2.4.6.10

Register for recipient events. You can register for the recipient events "Sent," "Delivery, "Failed," "Delivered," "Signed/Completed," "Declined," and "Authentication failure." You can implement specialized business logic to execute on receipt of these recipient events by using the recipient event extension points.

By default, the system registers for the "Delivered" event.

2.4.10Set the documents that you want to send to the DocuSign service for signature. By default, all documents that are currently attached to the case are sent to DocuSign. If this is the desired behavior, do not modify this step.
2.4.12Call the pyAssignRecipientsToEnvelope data transform to set the recipients of your documents.

Steps in the pyAssignRecipientsToEnvelopedata transform

ThepyAssignRecipientsToEnvelopedata transform is referenced in the pyPrepareNewEnvelope data transform and allows you to define the recipients for your documents. You can do the following actions by using this data transform:

  • Specify which recipient should sign which of your documents.
  • Optional: Define a routing (signing) order for your recipients.
  • Optional: Authenticate the transaction. You can use SMS and email authentication.
  • Specify DocuSign tabs that represent interaction points on your document and are associated with a specific recipient. The hotfix package that you installed supports signature tabs, check box tabs, text field tabs, and initial tabs.

The following table describes the steps on the Definition tab of this data transform:

Step numberDescription
2

Set the signers. Signers are recipients who must interact (sign or take some other action) with one or more areas of one or more documents.

2.7 to 2.9Configure SMS authentication.
2.11.3Set the Sign Here tabs. A Sign Here tab results in a signature point on the document. Each tab must be associated with a unique recipient ID and document ID.
2.11.7Set the Text tabs. Text tabs represent plain text fields that a recipient can interact with. These tabs are useful for typing information, entering a name, or modifying the document in some way. Each tab must be associated with a unique recipient ID and document ID.
2.11.9Set the Checkbox tabs. A Checkbox tab places a check box in the document. A custom textual label is placed next to the check box. Each tab must be associated with a unique recipient ID and document ID.

Published February 12, 2016 — Updated February 14, 2019


91% found this useful

Have a question? Get answers now.

Visit the Pega Support Community to ask questions, engage in discussions, and help others.