Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Preparing a DocuSign envelope

Updated on April 6, 2022

Build a request envelope that holds the information that you need to provide to DocuSign to successfully send documents for digital signing.

Note: Consider the following points:
  • Alternatively, you can use an existing DocuSign template to speed up envelope configuration. For more information, see Requesting digital signatures through DocuSign templates.
  • By configuring case type-specific event notification settings directly in the pyPrepareNewEnvelope data transform, you can adjust the types of event notifications to receive per each case type. To ensure that the event notification settings are the same across all case types, you can skip steps 5 through 9, and then configure account-specific settings in the DocuSign Developer portal. For more information, see .

Before you begin:
  1. In your Pega application, install the DocuSign component and configure the authentication settings. For more information, see Connecting your application to DocuSign.
  2. Save the pyPrepareNewEnvelope data transform rule as part of your application ruleset, in the case type class that integrates the DocuSign services.
pyPrepareNewEnvelope is the data transform whose purpose is to create the payload for a connect REST request to DocuSign. The pyPrepareNewEnvelope data transform, as well as other out-of-the-box DocuSign integration data transforms, is a template that you need to adjust to your unique business needs. You can do so by replacing the default or sample values with the ones that pertain to your specific business needs. Additionally, you can enable or disable data transform steps, as needed.
  1. In the header of Dev Studio, find and open the pyPrepareNewEnvelope data transform.
  2. If you are using basic authentication for API calls to DocuSign, in data transform step 2.2, open and configure the pySetEnvelopeCredentials data transform.
  3. Construct the email body:
    StepPropertyDescription
    2.4.1.pyEmailBlurb

    Customize the signature request message according to your business needs.

    For example, "To complete your credit card application, please review and sign the attached document."

    2.4.2.pyEmailSubject

    Provide a meaningful and informative signature request subject.

    For example, "Sign your uPlus Bank credit card application"

  4. Set the envelope request status:
    StepPropertyDescription
    2.4.4.pyStatus

    Set the envelope status. Available options include:

    • sent – DocuSign sends the email notification with the envelope to the recipients.
    • created – DocuSign saves the envelope as a draft. You can further modify that envelope or send it later.

    The default setting is "sent"

  5. Receive updates about the envelope and the recipients in your Pega application as the envelope progresses through the signing process:
    Tip: You can disable step 2.4.6 if you do not need to track envelope events in your application.
    StepPropertyDescription
    2.4.6.1.pyUrl

    Specify the URL address to which DocuSign sends a status updates:

    "https://<YOURDOMAIN>/prweb/PRRestService/DocuSignService/Services/pyConnect"

    2.4.6.2.pyLoggingEnabled

    Enable event logging to facilitate troubleshooting issues.

    The default value is "true"

    2.4.6.3.pyRequireAcknowledgement

    Require DocuSign to confirm whether the envelope was successfully sent. By default, DocuSign waits 100 seconds before recording a failure.

    The default value is "true"

    2.4.6.4.pyIncludeDocuments

    Configure event notification messages to include the documents.

    The default value is "true"

    2.4.6.5.pyIncludeTimeZone

    Configure event notification messages to include the envelope time zone information in the UTC format.

    The default value is "true"

    2.4.6.6.pyIncludeCertificateOfCompletion

    Configure event notification messages to include a certificate of completion in addition to signed documents.

    The default value is "true"

  6. If you enabled event notification in task step 5, configure the envelope status changes that trigger event notifications:
    StepPropertyDescription
    2.4.6.8.2.pyEnvelopeEventStatusCode

    The available event types include:

    • Sent – The envelope was sent to at least one recipient.
    • Delivered – All recipients opened the envelope through a DocuSign app.
    • Completed – All recipients signed (completed) the envelope.
    • Declined – A recipient declined the envelope.
    • Voided – The sender voided the envelope.
    • AuthenticationFailed – The recipient failed an authentication check.
    • AutoResponded – The recipient’s email account sent an automated response to an envelope notification.
    2.4.6.8.3.pyIncludeDocuments

    DocuSign sends the documents in the message.

    The default value is "true"

    For more information, see DocuSign Connect overview (webhooks).

  7. Optional: To track changes for multiple envelope status types, perform the following actions:
    1. For each status type that you want to track, create a copy of step 2.4.6.8.
    2. In each copy, set the value of the .pyEnvelopeEventStatusCode property equal to the status type that you want to track.
    For example: The following figure shows the pyPrepareNewEnvelope data transform configuration for tracking additional recipient and envelope status changes:
    Tracking multiple envelope and recipient status types
    The pyPrepareNewEnvelope data transform with multiple steps for tracking recipient and envelope status changes.
  8. If you enabled event notification in task step 5, configure the recipient status changes that trigger event notifications:
    StepPropertyDescription
    2.4.6.10.2.pyRecipientEventStatusCode

    The available event types include:

    • Sent – A notification was sent to the recipient indicating their turn to sign.
    • Delivered – The recipient viewed the documents through the DocuSign signing website.
    • Completed – The recipient signed (completed) the envelope.
    • Declined – The recipient declined to sign.
    • AuthenticationFailed – The recipient failed an authentication check.
    • AutoResponded – The recipient’s email account sent an automated response to an envelope notification.
    2.4.6.10.3.pyIncludeDocuments

    DocuSign sends the documents in the message.

    The default value is "true"

    For more information, see DocuSign Connect overview (webhooks).

  9. Optional: To track changes for multiple recipient status types, perform the following actions:
    1. For each status type that you want to track, create a copy of step 2.4.6.10.
    2. In each copy, set the value of the .pyRecipientEventStatusCode property equal to the status type that you want to track.
  10. In step 2.4.8, set the reminder and expiration settings for envelopes and documents:
    StepPropertyDescription
    2.4.8.pyNotification

    By default, this data transform step is enabled. You can disable the step to prevent DocuSign from sending notifications of any type to recipients.

    You can also disable a specific notification type, as needed.

    2.4.8.1.pyReminderConfigure the settings for automatic reminders about a document that is pending signature.
    2.4.8.1.1.pyReminderEnabled

    Specify whether this notification type is enabled. To disable this notification type, change the default value to "false"

    The default value is "true"

    2.4.8.1.2.pyReminderDelay

    Specify the number of days before sending the first reminder.

    The default value is "2"

    2.4.8.1.3.pyReminderFrequency

    Specify the interval (in days) between subsequent reminders.

    The default value is "1"

    2.4.8.2.pyExpirationConfigure the envelope expiration settings.
    2.4.8.2.1.pyExpireEnabled

    Specify whether this notification type is enabled. To disable this notification type, change the default value to "false"

    The default value is "true"

    2.4.8.2.2.pyExpireAfter

    Specify the number of days after which the envelope expires.

    The default value is "2"

    2.4.8.2.3.pyExpireWarn

    Specify how many days before the expiration DocuSign sends a warning.

    The default value is "1"

    For more information, see Common API Tasks: Add Reminders and Expiration to an Envelope in the DocuSign Developers documentation.

  11. Optional: To select which documents attached to the case type to include in the envelope, modify step 2.4.10.
    By default, step 2.4.10 includes all documents attached to the case type in the envelope, as shown in the following figure:
    Attaching documents to a DocuSign envelope
    Step 2.4.10 sequence in the pyPrepareNewEnvelope data transform.
  12. Add recipients to the envelope:
    1. In step 2.4.12.1, open the pyAssignRecipientsToEnvelope data transform.
    2. Adjust the data transform steps to your business needs.
      For more information, see Assigning recipients to an envelope.
  • Previous topic Configuring DocuSign envelopes
  • Next topic Configuring basic authentication details for DocuSign envelope requests

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us