Page tree

DocuSign Setup

DocuSign is an e-signature integration that allows you to manage digital signatures on your contracts and other documents. This page focuses on the initial setup for a DocuSign integration.

When you finish setting up DocuSign, consider exploring DocuSign Resources and Tips.

Access and User Consent

To set up DocuSign, you need admin access in both your Agiloft KB and in DocuSign. There are different levels of admin access needed in DocuSign, and the level required for your integration depends on the type of User Consent your integration will use.

When  Agiloft attempts to create and send documents for a user, that user will be asked to grant User Consent for the set of scopes (sets of permissions) that the application has requested. The two methods to obtain User Consent for the DocuSign API are:

  • Admin Consent: Each DocuSign User within an organization’s domain can be granted consent simultaneously. This is the best option if each user will use their own name to send envelopes, and is generally quicker. Admin Consent also makes it easier to add more users in the future.
  • Individual Consent: Each DocuSign User must grant consent to the API by logging in to confirm permission. This option can be used for one main account, or in cases where each user will use their own name but might use a different domain. This is common with contractors.

Some integrations are set up using a single one of these options, while others may require both. Generally, both consent options are required if not all users have the same domain for their email addresses.

Admin Consent

For Admin Consent, an organization and claimed Domain within DocuSign are required. To do this, you will need:

  1. A DocuSign Account enabled with DocuSign Admin, which requires Enterprise Pro with the Organization Management Add-On.
  2. An eSignature Admin that has been granted All Administration Capabilities, which allows you to create an organization and claim the domain from the DocuSign Admin platform.
  3. Access to the DNS for your domain, which may require the help of your organization's system admin.
When claiming a domain, make sure that you claim the domain used by the email addresses you use with DocuSign. A domain can only be claimed by one DocuSign organization. If one organization has claimed and verified a domain, then another organization cannot claim it. An organization can claim the same domain in both the demo and production environments.

Individual Consent

For Individual Consent, a consent URL can be provided to each DocuSign User who will send envelopes under their own account. This is the easiest option to set up if you want use one main account for all users. This is also used if a minority of your users have email addresses with a different domain. You will only need eSignature Admin access for DocuSign.

Creating a DocuSign Account

Before you can set up DocuSign, create a developer account if you don't already have one. You'll use this account for testing purposes during the initial setup. You can create an unlimited number of these accounts.

To set up a free developer account, complete the following steps. When you've completed the set up, you can also follow these same steps to create your production account. 

  1. Open https://developers.docusign.com/ and go to Developer Account > Create Account
  2. Enter the required details and finish creating an account. This isn't the same as the DocuSign User account you will authenticate later.
  3. Click the profile icon in the top right, and then click My Apps and Keys in the drop-down.
  4. In the sidebar under Users and Groups, click Permission Profiles.
  5. Click Actions > View on the DS Admin permission profile to open it.
  6. Go to the User Permissions tab.
  7. Ensure that the "Allow send on behalf of other users through API" check box is selected. If the option is disabled, create a copy of the permission set and then select this option.

Now that you have an account created, you can continue to create an organization and set up authentication.

Configuring DocuSign and Consent

  1. Return to DocuSign and log in with the developer account you created, if you aren't still logged in.

  2. Click the profile icon in the top right, and then click My Apps and Keys in the drop-down. 
  3. Click Add App and Integration Key.
  4. Under General Info, give the integration a name (such as "Agiloft") in the App Name Field, then click Create App.
    1. Leave the Authentication setting on Authorization Code Grant.
    2. Under Service Integration, click Generate RSA. 
    3. Copy the Public and Private Keys in their entirety, including the header and footer.

      Be sure to save both Keys to a safe place. You won't be able to view them again, and you'll need them in later steps to complete the setup.
    4. If you are using Individual Consent, add a redirect URI. The redirect URI is a splash page or other internal site where the user is sent once they have granted consent for the app. If you like, you can use an Agiloft hosted splash page and set the redirect URI to: https://www.agiloft.com/success/
    5. Leave the Additional Settings as they are, and click Save.
  5. Save the API Account ID, the Account Base URI, and Integration Key Information in a convenient and accessible location, just like with your Public and Private Keys.
  6. The next step depends on the method of User Consent used in your integration:
    1. For integrations that require Admin Consent, complete the Getting Admin Consent section.
    2. For integrations that require Individual Consent, complete the Getting Individual Consent section.
    3. For integrations that require both methods, complete both sections.

Granting Admin Consent

To request Admin Consent, you first need to configure an organization in DocuSign using the developer account you created.

  1. If you have an existing DocuSign organization that has claimed the domain you'd like to use, follow DocuSign's instructions to Link Administered Accounts to an Organization, and then skip to step 3 below.
  2. Otherwise, to create an organization:

    1. Click on Overview on the left menu, then click Get Started in the upper right corner and follow DocuSign's instructions to Create an Organization.

      If you don't see the Get Started button, then DocuSign Admin is not enabled on the account. Contact DocuSign customer support for assistance.

    2. Enter an Organization Name and an optional Description. Click Next.
    3. The account you used to create the organization is automatically linked. Add any other accounts you want to manage centrally, and click Create.
  3. Once the Organization is created, you can use the Switch To button to navigate between the eSignature Admin and the DocuSign Admin interfaces. Make sure you're on the DocuSign Admin interface.
  4. Navigate to the Connected Apps menu in the Organization Dashboard.
  5. Click Authorize Application in the top right corner.
  6. Select your app. Under the Permissions field, enter: signature impersonation
  7. Click Add. This adds the app to the organization, and grant impersonation for every user. This feature requires that you claim your organization domain before it can become functional.
  8. Follow the DocuSign instructions to prove ownership. This will require you to work with your domain admin to make changes to the DNS and CNAME.

    When claiming a domain, ensure that you claim the domain used by the email addresses you use with DocuSign. A domain can only be claimed by one DocuSign organization. If one organization has claimed and verified a domain, then another organization cannot claim it. An organization can claim the same domain in both the demo and production environments.

  9. Complete Individual Consent if you plan to use it, or skip to Configuring Your KB.

Getting Individual Consent

To request Individual Consent:

  1. Construct the Consent URI based on the below syntax. With values, it will look similar to the Individual Consent URI Sample below.
  2. For the Base URI value, you'll use https://account-d.docusign.com/oauth/auth when setting up the test environment. When you're switching to production, you'll use https://account.docusign.com/oauth/auth as the Base URI value. This example shows the Base URI used for the test environment and a Redirect URI to an Agiloft splash page:

    https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature%20impersonation&client_id=<your_Integration_key>&redirect_uri=https://www.agiloft.com/success/
  3. Copy the Consent URI Sample above and replace the <your_Integration_key> value of the Consent URI with the value of your integration key.

  4. If you did not use Agiloft's splash page for the Redirect URI in step 4d , replace https://www.agiloft.com/success/ with the value you used in 4d in the sample consent URI.

  5. Open the URI in a browser.
  6. Log in with your individual account and grant consent for the application.  

  7. Provide the link to all users who need to grant individual consent, so they can log in with their individual accounts to also grant consent.

  8. Continue to Configuring Your KB.

Configuring Your KB

The next step of the DocuSign Integration involves configuring your KB, verifying it with DocuSign, and connecting your DocuSign production account. KBs need to be verified and approved by DocuSign in the developer environment by completing 20 messageful API calls. To set up your KB to make these calls, you must configure your Agiloft instance to integrate with the developer environment.

  1. Log in to your KB as the DocuSign admin user.
  2. Go to Setup > Integration > DocuSign Extension and click Configure.
  3. Edit the existing account, or click New to create a new account. You can connect multiple DocuSign accounts with a single KB; this isn't necessary in most cases, but it can useful if you need a separate account to purchase a smaller number of more expensive envelopes in order to avoid higher charges under the primary DocuSign account. 
  4. Give the account a name. If you have multiple accounts, make sure the new name specifies what differentiates that account.
  5. Click Change Server
  6. For the initial setup and testing, select the Demo server. Otherwise, set the server to match the Account Base URI you saved earlier in this process.
    Selecting the Demo server
  7. Click Set Server.
  8. Fill out the form with the information you saved when Configuring DocuSign and Consent. In the RSA Private Key field, include the header and footer.
  9. Click Save and then edit the account again to continue.
  10. On the DocuSign Users tab, create a record for the person who will serve as your DocuSign administrator for  Agiloft. This user is able to add and remove users and manage other aspects of the DocuSign setup. The user should have admin rights in both the KB and DocuSign. This should be a new user account, and it's best to create a separate account only for this purpose, rather than assigning a named user. That way, it's easier to transition responsibility internally if needed. To create the user:
    1. Click New.
    2. Use the look-up for the Login or Full Name to find the  Agiloft user. For this first record, select the user you'd like to make the DocuSign Administrator.
    3. If you see an option to choose how to authenticate, select JWT. If you don't see this option, proceed to the next step.
    4. Get the DocuSign User ID by navigating to the User tab in DocuSign, opening the user's profile, and copying the User ID. Then, enter it into the User ID field. For the first user, this should be an admin user account in DocuSign, with the permission profile set to DS Admin.

      In older KBs, this field might not be included in the layout. To make the User ID field visible, open Setup for the DocuSign Users table, go to the Layout tab, and add the User ID field to the layout.

    5. Click Grant Access to DocuSign, then Save and Close the account.
    6. On the DocuSign configuration page, select the new user in the Account Administrator dropdown.
    7. Click Enable DocuSign Connect. If DocuSign is messagefully enabled, you are returned to the Integration menu and a status notification appears at the top of the page. You can also confirm your connection by clicking Configure again under DocuSign Extension and confirming that a Connect ID now appears. You can now begin testing, or continue on to step 11 to add users.

      You might see an error message if the hotlink server URL is set to the localhost by default. To update this value, set the Hotlink Server URL global variable value to your server's domain name. For other issues, consult DocuSign Troubleshooting.

  11. Return to DocuSign Users. For each employee who needs to send DocuSign envelopes, follow step 10 to create a DocuSign User entry. When completing step 10d for each user:
    • To send envelopes under a user's own DocuSign name, input their DocuSign User ID.
    • To send envelopes under one main account, input the DocuSign Admin User ID for every subsequent user granted access to DocuSign. Make sure that in DocuSign administration, you go to Settings > Users and Groups > Permission Profiles and enable "Allow send on behalf of other users through API" for the admin user's permission profile.

Verifying the KB with DocuSign

Now, you need to establish a connection to DocuSign so it will receive envelopes sent from  Agiloft, which is done through API calls.

  1. Log in as one of the users assigned to the DocuSign account. Typically you can log in to the user assigned to the developer account you created.
  2. Create a test Contract record that requires a signature, and send it through DocuSign.
  3. Repeat step 2 until 20 API calls are registered. You can send the envelopes under a single Contract record to expedite the process. You can see the amount of API calls on the DocuSign Account Admin dashboard under the Apps and Keys settings, although this number does occasionally take some time to update. Some other API calls that count towards the 20 are granting access to users, or sending and voiding envelopes.
  4. Once 20 calls have been completed, go to the Apps and Keys area of DocuSign. Next to the integration key you want to promote to a production application, select Actions > Start Go-Live Account.
  5. In the Request App Review window that appears, select Request Review to start the automatic inspection. After passing this automated review, the key's status changes to Review Passed. 

Going Live with DocuSign

Whether you're going live with DocuSign for the first time, or transitioning from an older integration to a new account, make a plan for the process.

  1. If you're transitioning from a previous DocuSign integration, determine a cutover date and communicate it to your users. Make sure they understand that DocuSign will be temporarily unavailable during the cutover window.
  2. Log in to the test account at: https://developers.docusign.com/ 
  3. Next to the integration key you want to promote, select Actions > Select Go-Live Account.
  4. You are prompted to choose a production account. Click Next.
  5. In the login window that appears, log in using your production DocuSign account credentials (not your developer account credentials).
  6. After logging in, you are prompted to accept the developer terms and conditions. Note that you might need to enable pop-ups in your browser.
  7. Next, you are prompted to select a production account to promote the key. Depending on your internal setup, there may be one or many accounts to choose from. Choose the account that contains the DocuSign users who will also be Agiloft users.

Configuring your Production Account

Once your app has been verified:

  1. Log in to your Production account in DocuSign at: https://account.docusign.com/

  2. The integration key promoted from the development account appears in the Apps and Keys section of your Production DocuSign account. Next to the key, select Actions > Edit.

  3. Repeat the steps from Configuring DocuSign and Consent to generate an RSA key and grant user consent.

  4. Return to Agiloft and log in as the DocuSign administrator you assigned earlier.
  5. Reintegrate the KB with DocuSign:
    1. First, disable DocuSign Connect. To do so, go to Setup > Integration > DocuSign Extension and click Configure, then click Disable DocuSign Connect.
    2. Click Remove Access to remove current DocuSign users, then ignore the warning and save your changes. If you don't remove user access, you will be unable to change the server in the next step.
    3. Change the server from the developer Account Base URI to match your production Account Base URI. Click Set Server to apply the change.

    4. Paste the Integration Key in the Client ID field.
    5. Paste the API Account ID in the Account ID field.
    6. Paste the new RSA Private Key from step 2 in the RSA Key field, including the header and footer.
    7. Go to the DocuSign Users tab, create or select your DocuSign Admin account as a user, and then select them as Account Administrator.
      1. Enter their production User ID and Grant access again under DocuSign Users section.
      2. Scroll back up and set them as Account Administrator. 
    8. Click Save and then edit the account again to continue.
  6. Click Enable DocuSign Connect. If DocuSign is messagefully enabled, you are returned to the Integration menu and a status notification appears at the top of the page. You can also confirm your connection by clicking Configure again under DocuSign Extension and confirming that a Connect ID now appears. You can now begin testing, or continue on to step 11 to add users.

    You might see an error message if the hotlink server URL is set to the localhost by default. To update this value, set the Hotlink Server URL global variable value to your server's domain name. For other issues, consult DocuSign Troubleshooting.

  7. Regrant access to the DocuSign users from step 5. For each one, before granting access, replace the existing DocuSign User ID with the user ID from the production account.
  8. Finally, create a new contract and test it by sending it out for signature.

Customizing the Create DocuSign Envelope Action

The optional final step is to customize the Create DocuSign Envelope action. This option is useful if you need to change the default attributes about the Create DocuSign Envelope used to create and send out DocuSign envelopes. Some customizable attributes are: 

  • The total number of signers
  • Which DocuSign templates to use
  • Which attached file field holds the documents
  • The subject line for the DocuSign email to recipients

To configure the Create DocuSign Envelope action, follow the steps below.

  1. Go to Setup > Integration, click Configure under DocuSign Extension, and edit the account.
    • To edit an existing action, locate the Action drop-down menu, select Create DocuSign Envelope, and click Edit Action.
    • To create a new DocuSign Envelope action for a table, locate the Table drop-down menu, select the table from the list, and click Add Action. When you create a new action, you must also also add a Name and Description for the action.
  2. Complete the fields to configure the action.
    DocuSign action
  3. Click the Recipients tab and complete the fields for each recipient. At the top, specify how many people will receive the envelope. Then, for each recipient in the sending order, configure the Role Name (defined in the DocuSign Roles table), Role, Recipient Field, optional Access Code, and message contents.
    Recipients tab
  4. Click Save. 

This completes the setup. For more information about using DocuSign, consult the DocuSign Resources and Tips pages.

If you need to create multiple DocuSign actions at once, use the Actions tab of the table setup menu to set up your Ext: actions. You can create multiple DocuSign actions for the same table. Normally we create multiple DocuSign actions to toggle the signing order of the signers (such as Internal Signs first vs. External Signs first).