Microapps

Integrate DocuSign

Deploy the DocuSign integration to send and receive envelopes for digital signatures from any device using Citrix Workspace. Users can initiate a new template for signature, be notified for any new pending documents, and view a list of envelopes previously sent or received in their DocuSign inbox.

Note:

We want your feedback! Please provide feedback for this integration template as you use it. For any issues, our team will also monitor our dedicated forum on a daily basis.

For comprehensive details of the out-of-the-box microapps for DocuSign, see Use DocuSign microapps.

Review prerequisites

These prerequisites assume that the administrator is part of the DocuSign integration set up of the organization. This DocuSign admin account must have full read privileges for user information.

After you set up this integration with DocuSign, you will need these artifacts to add the integration in Citrix Workspace Microapps, specifically the following list of parameters for setting up OAuth integration:

  • Base URL: The Base URL to which the endpoint paths are appended. You can collect the Base URL from the Service Account under Apps and Keys. Base URL format: {baseURL fetched from sevice account}/restapi/2.1/. For how to find Base URL, see Configure OAuth server.
  • DocuSign Account Id: Your docusign admin account Id. See Configure OAuth server.
  • Environmental URL: For example from the base URL https://{yourEnvironmentalURL}.docusign.net/restapi/v2.1/.
  • Authorization URL: https://account-d.docusign.com/oauth/auth
  • Token URL: https://account-d.docusign.com/oauth/token
  • Client ID: The client ID is the string representing client registration information unique to the authorization server. Additionally, all application keys for DocuSign must pass the DocuSign go live process. This applies to the Integration Key (ClientId). This can take up to a week. For more information about the DocuSign go live process, see https://developers.docusign.com/docs/esign-rest-api/go-live/.
  • Client Secret: The client secret is a unique string issued when setting up the target application integration.

Note:

We recommend that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

Configure Citrix Gateway to support single sign-on for DocuSign so that once users log in they are automatically logged in again without having to enter their credentials a second time. For more information about configuring SSO, see Citrix Gateway Service.

The number of API requests that can be made to specific resources is limited, we therefore recommend the following:

DocuSign API limitation form link: https://developers.docusign.com/docs/esign-soap-api/esign101/security/call-limits/

Create a new service account

Sign up here: https://admin.docusign.com. You can view User Permission Profiles here: https://support.docusign.com/en/guides/ndse-admin-guide-permission-sets. If you want to access the demo version of eSignature Admin, use this URL instead: https://admindemo.docusign.com. For more information on new service accounts, see: https://support.docusign.com/en/guides/org-admin-guide-getting-started.

Configure OAuth server

Configure the OAuth server to read data through the DocuSign integration.

  1. Log in to the eSignature Admin with your service account: https://admin.docusign.com. For the demo version of eSignature Admin: https://admindemo.docusign.com. For more information, see: https://support.docusign.com/en/guides/ndse-admin-guide-access and https://support.docusign.com/en/guides/ndse-admin-guide-welcome-to-administration.
  2. Go to Setting in the navigation bar.
  3. On the settings page, select Apps and Keys and then ADD APP & INTEGRATION KEY.
  4. Enter an APP Name and select ADD.
  5. Select +Add Secret Key to generate a Secret Key.
  6. Enter the Redirect URI: https://{yourmicroappserverurl}/admin/api/gwsc/auth/serverContext
  7. Copy and save the Integration Key and Secret Key (ClientId and Secret) shown on the screen. You use these details for Service Authentication while configuring the integration.
  8. Copy and save the Account’s Base URI.
  9. Copy and save the DocuSign Account Id.

Additionally, all application keys for DocuSign must pass the DocuSign go live process. This applies to the Integration Key (ClientId). This can take up to a week. For more information about the DocuSign go live process, see https://developers.docusign.com/docs/esign-rest-api/go-live/.

Configure OAuth client

Configure the OAuth client for writing back data through the DocuSign integration.

  1. Log in to the eSignature Admin with your service account: https://admin.docusign.com. For the demo version of eSignature Admin: https://admindemo.docusign.com. For more information, see: https://support.docusign.com/en/guides/ndse-admin-guide-access and https://support.docusign.com/en/guides/ndse-admin-guide-welcome-to-administration.
  2. Go to Setting in the navigation bar.
  3. On the settings page, select Apps and Keys and then ADD APP & INTEGRATION KEY.
  4. Enter an APP Name and select ADD.
  5. Select +Add Secret Key to generate a Secret Key.
  6. Enter the Redirect URI: https://{yourmicroappserverurl}/app/api/auth/serviceAction/callback
  7. Copy and save the Integration Key and Secret Key (ClientId and Secret) shown on the screen. You use these details for Service Action Authentication while configuring the integration.

Additionally, all application keys for DocuSign must pass the DocuSign go live process. This applies to the Integration Key (ClientId). This can take up to a week. For more information about the DocuSign go live process, see https://developers.docusign.com/docs/esign-rest-api/go-live/.

Configure Organization

Link accounts to your organization. The account that you used to create the organization is automatically linked.

  1. From the eSignature Admin home page, select GET STARTED. If you do not see this option in your DocuSign account, then DocuSign Admin is not enabled on the account. Contact your DocuSign account manager for assistance.
  2. Enter an Organization Name and an optional Description in the fields provided, then select NEXT.
  3. Select CREATE to finish creating your organization. For more information, see https://support.docusign.com/en/guides/org-admin-guide-create-org.
  4. Go to the Organization Admin dashboard. Select Connected Apps, and select AUTHORIZE APPLICATION.
  5. Select the App name that you entered and created while configuring the OAuth server and client. Select ADD to provide permissions.
  6. Enter these scopes. For more information, see: https://developers.docusign.com/platform/auth/reference/scopes.
    • For service authentication, select the App Name that you created in Configure OAuth server, provide the user_read permission, and select ADD.
    • For service action authentication, select the App Name that you created in Configure OAuth client, provide the user_write permission, and select ADD.

Add the integration to Citrix Workspace Microapps

Add the DocuSign integration to Citrix Workspace Microapps to connect to your application. The authentication options are preselected. Ensure that these options are selected as you complete the process. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Choose the DocuSign tile.
  3. Enter an Integration name for the integration.
  4. Enter Connector parameters.
    • Enter the instance Base URL:
    • Select an Icon for the integration from the Icon Library, or leave this as the default icon.

    DocuSign parameters

  5. Enter your DocuSign Account Id. See Configure OAuth server.
  6. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

    1. Select Authorization code from the Grant type menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This displays the Callback URL, which you use when registering your application.
    2. Select Request body from the Token authorization menu.
    3. The Authorization URL is prefilled.
    4. The Token URL is prefilled.
    5. Ensure the following is entered for Scope: user_read
    6. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret when you configured the OAuth server. You need to add the Callback URL you see on the integration configuration page.
    7. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.

    Service Authentication

  7. Under Service Action Authentication, enable the Use Separate User Authentication in Actions toggle. Service action authentication authenticates at the service action level. The authentication options are preselected. Ensure that these options are selected as you complete the process.

    1. Select OAuth 2.0 from the Authentication method menu and complete the authentication details.
    2. Select Authorization code from the Grant type menu. This grants a temporary code that the client exchanges for an access token. The code is obtained from the authorization server where you can see the information the client is requesting. Only this grant type enables secure user impersonation. This displays the Callback URL, which you use when registering your application.
    3. Select Request body from the Token authorization menu.
    4. The Authorization URL is prefilled.
    5. The Token URL is prefilled
    6. Ensure the following is entered for Scope: user_write
    7. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server. You collect this and the secret when you configured the OAuth client. You need to add the Callback URL you see on the integration configuration page.
    8. Enter your Client secret. The client secret is a unique string issued when setting up the target application integration.

    Service action authentication

  8. The Enable request rate limiting toggle is enabled. Leave 400 for Number of requests and 1 minute for Time interval. 1.. Request timeout is set to 120 by default.
  9. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.

    Service Authentication

  10. Select Save to proceed.
  11. Under OAuth Authorization, select Authorize to log in with your service account. A pop-up appears with a Google login screen.
    1. Enter your Service Account user name and password and select Log in.
    2. Select Accept.

    Authorize

Add actions to buttons

Configure Go to URL actions for the following buttons to enable Sign Envelope and View Envelope button capabilities. This Go to URL configuration redirects the user action to the specific envelope detail page in DocuSign.

  1. Navigate to and then select the following buttons in the page builder. Perform this procedure for each button below:

    • My Received Envelopes microapp: Pending Envelope Details page: Sign Envelope button
    • My Sent Envelopes microapp: Recipient View of Envelope page: Sign Envelope button
    • My Sent Envelopes microapp: Sender View of Envelope page: View Envelope button
  2. Select the Actions tab on the right.
  3. Under Actions, select Go to URL.
  4. In the URL template field, replace the {yourEnvironmentName} portion of the URL with your environmental URL. Find your environmental URL in your base URL: https://{yourEnvironmentName}.docusign.net/restapi/v2.1/. For example: https://appdemo.docusign.com/documents/details/\{\{nested_table_envelopes_recipients_sign.envelope_id\}\}.

    Environmental URL

  5. Now, repeat this procedure for the other buttons.

You are now ready to set and run your first data synchronization. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see DocuSign connector specifications.

Use DocuSign microapps

Existing application integrations come with out-of-the-box microapps. Start with these microapps and customize them for your needs.

Note:

To enable Sign Envelope and View Envelope button capabilities, you must replace the button Action for Pending Envelope Details page, Recipient View of Envelope page and Sender View of Envelope page with your environmental URL. See Add actions to buttons.

My Received Envelopes: View user’s received envelopes, which are awaiting signature. User can authenticate himself and view the Envelope in DocuSign.

Notification or Page Use-case workflows
My Pending Envelopes page Provides a table with all the envelopes pending the user’s signature with a search option to filter envelopes by email subject or the senders name. Users can view the envelopes for the status Sent and Delivered.
Pending Envelope Details page Provides details for an envelope pending signature, such as email subject, sender name, and expire after (number of days). Users can view the envelope in DocuSign using the Sign Envelope button.

Send a Template: Send an existing template for signature.

Notification or Page Use-case workflows
All Templates page Provides a table with all the templates for the user. The integration doesn’t list Shared templates in the list of templates for the signed in user.
Template Details page Provides a form to send the template to recipients. The sender provides the following details to send an envelope: Name, Email, and Role. Envelopes can be sent to at maximum three (3) recipients at a time. A template must contain a document to send an envelope using that template.

My Sent Envelopes: View a list of envelopes sent by the user. Users also can view the details of the envelope, and also add, edit, and delete recipients.

Note:

Notifications expire two days after their creation.

Notification or Page Use-case workflows
Envelope Status Change notification When an envelope’s status is changed to either Completed or Declined, a notification is generated and sent to the sender of the envelope. If an envelope’s status is already Completed or Declined when the record is added to the Citrix Microapps Database, then the notification is not generated for the sender.
New Envelope notification When a new envelope is received, the envelope status and recipient status must be either Sent or Delivered, and a notification is generated and sent to the associated recipient.
Add Recipient page Provides a form to add a recipient to an envelope. Contains input fields such as Name, Email, and Role.
Edit Recipient page Provides a form to edit input fields such as name and email. When a user modifies a name or email, a Save and Resend button is displayed and an email is sent to the recipient.
Envelope Details page Provides envelope details such as email subject, created on, and status. Also shows a list of recipients associated with the envelope, and an Add Recipient button. Users can’t edit or add recipients to voided or declined envelopes.
My Envelopes page Provides the list of all envelopes sent by the user having a status (sent, delivered, completed, declined, voided) with a search bar to filter envelopes by email subject or envelope status.
Recipient Details page Provides recipient details such as name, email, and status with these buttons: edit recipient, resend envelope, and delete recipient.
Recipient View of Envelope page Provides details for an envelope pending signature, such as email subject, sender name, and expire after (number of days). Users can view the envelope in DocuSign using the Sign Envelope button to sign the envelope.
Sender View of Envelope page Provides envelope details such as email subject, created on, and status. Also contains a list of recipients associated to the envelope, and a View Envelope button.
Integrate DocuSign