Page tree
Skip to end of metadata
Go to start of metadata

DocuSign Integration

These topics describe the process of integrating DocuSign with a standard Agiloft knowledgebase. DocuSign is an electronic signature (eSignature) solution that integrates with Agiloft and can be used for a variety of document or contract management needs. Through the DocuSign API, Agiloft creates DocuSign envelopes and sends out document tables and records which are then signed and returned by the customer's signers. In Agiloft's standard knowledgebases, the Contracts table already contains DocuSign functionality, and other tables can also be configured to use DocuSign.

Table of Contents


DocuSign envelope

A DocuSign envelope is a container used to send one or more documents for signature using the DocuSign system. Envelopes can contain multiple documents and can be sent to several recipients. The documents can have multiple pages. For more information, see here. In Agiloft, there is a DocuSign Envelopes table which contains the records of your DocuSign envelopes.

DocuSign recipients

DocuSign recipients are the people who receive the documents, usually to sign them. They are specific to the DocuSign envelope and each recipient is assigned a specific DocuSign Role. You can select any of the following roles, which are listed with the role they correspond to in DocuSign:

  • Signer, which corresponds to Needs to Sign
  • CC, which corresponds to Receives a Copy
  • Editor, which corresponds to Allow to Edit
  • Certified Delivery, which corresponds to Needs to View
  • Agent, which corresponds to Specify Recipients

For more information about recipient roles, see here.

DocuSign signing roles

The DocuSign signing role defines who the signer is, such as an employee or a customer. They are system-wide definitions and not specific to any envelope. The DocuSign Roles table enables you to manage and create roles in Agiloft. Note that these roles are used in  Agiloft print templates to distinguish internal and external signers, while roles on the DocuSign side of your configuration work differently.

DocuSign users

DocuSign users are users in the Agiloft KB who are authorized to create and send DocuSign envelopes. A record in the DocuSign User table must be linked to an Agiloft user record in the People table or one of its subtables.

DocuSign tags

DocuSign tags are formulas/variables placed within documents that tell the DocuSign API where signatures, signed dates, initials, and other DocuSign fields must go, as well as which signer each field belongs to. They are usually formatted in white font so that the tag text is not visible in the document. For more information, see here.

Standard DocuSign Setup 

After the initial setup, a contract user who is an authorized DocuSign user fills in the appropriate signer fields in the record and creates an attached document using the print template containing the DocuSign tags, or attaches a document that has already been created. After generating the document with the correct tags, the user presses the Create DocuSign Envelope button to convert the information into DocuSign Envelope and DocuSign Recipient records that correspond to the signers.

When the user previews the envelope and sends it out, DocuSign will send an email with a signing link to the first signer(s). As each signer signs the document, DocuSign emails the next signers on the list until everyone has signed the document, at which point the envelope is marked as completed and the signed document is sent back to Agiloft in PDF format. When Agiloft receives the completed document, the system marks the DocuSign Envelope record as completed, generates a new Attachment record for the signed PDF document, and changes the Status of the contract to Signed. If the Contract Start Date has passed, the Status of the contract is set to Active, instead.

Set Up a Test Account

You can test your DocuSign setup with a free developer account before using your enterprise account details. The process is identical to setting up a production account.

Create a Developer Account for Testing

To set up a test account:

  1. Go to:
  2. Go to Developer Account > Create Account. You can create an unlimited number of test developer accounts.
  3. In the DocuSign website for the account, click the profile icon and then My Apps and Keys.
  4. In the sidebar, click Permission Profiles in the Users and Groups section.
  5. Click Actions > View on the 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.

Enable DocuSign in Agiloft

After setting up a developer account with DocuSign:

  1. Log in to your KB as an admin user.
  2. Navigate to Setup > Integration > DocuSign Extension and click Configure.
  3. Click Change Server. 
  4. For the initial setup and testing, select the Demo server. 
    New DocuSign Server field
  5. Click Set Server.
  6. Optionally, set "Track envelopes sent outside Agiloft" to Yes or No. If you select Yes,  Agiloft will create records in the DocuSign Envelopes table when envelopes are created outside the  Agiloft system. If you select No,  Agiloft will only accept DocuSign data for envelopes that already have a corresponding record in the DocuSign Envelopes table.
  7. Optionally, if you have multifactor authentication set up in your system and you don't want users to need to confirm their identity every time they use DocuSign, you can configure your integration to use DocuSign to authenticate users instead. For more information on how to complete this optional process, refer to the Avoid Redundant User Authentication section. 
  8. Click Save.

Add a DocuSign Administrator

The first user that you grant DocuSign access to with the password will be the DocuSign Administrator. The user should therefore have admin rights in the KB. They will be able to add and remove users and manage other aspects of the DocuSign setup.

After you do this the first time, you can change the DocuSign Administrator by going to Setup > Integration, clicking Configure under DocuSign Integration, and selecting the new administrator in the Account Administrator drop-down menu. Note you will only be able to select users who are set up to use DocuSign.

  1. Create a new DocuSign User record using either of these methods:
    • Go to Setup > Integration, click Configure under the DocuSign Extension section, and click New in the DocuSign Users related table.
    • Go to the DocuSign Users table and click New.
  2. Use the lookup for the Login or Full Name to find the Agiloft user you'd like to make the DocuSign Administrator.
  3. Choose the "With username" option. Alternatively, you can use the JWT option to bypass additional verifications if you have the DocuSign API Username for the DocuSign admin account you are linking with Agiloft. For more information, visit the Avoid Redundant User Authentication section.
  4. Once selected, enter the DocuSign username and password you used to create the user on the DocuSign website.
  5. Click Grant Access to DocuSign to add the user to the DocuSign account. This user will be the DocuSign Administrator
    DocuSign User page

Create Additional DocuSign Users

You can set up additional authorized DocuSign Users in the  Agiloft KB. These can either have their own DocuSign user details, or they can be authenticated using the details and access token of another account in the DocuSign Users table. If the Send On Behalf Of feature is enabled in the DocuSign account and each Agiloft user who uses DocuSign  functionality in Agiloft has the same email address as its matching user in the DocuSign account, you do not need to use more than one DocuSign administrator account in one system.

To create additional users:

  1. Create a new DocuSign User record using either of these methods:
    • Go to Setup > Integration, click Configure under the DocuSign Extension section, and click New in the DocuSign Users related table.

      In the DocuSign Extension settings, you can set a Default DocuSign Group at the bottom to automatically assign new DocuSign users to a specific permission profile. This can speed up the process of adding new DocuSign users, especially if you want to automate it.

    • Go to the DocuSign Users table and click New.
  2. In the DocuSign User record, use the lookup for the Login or Full Name to find the Agiloft user. 
  3. In the Authenticate field, select one of the options:
    1. To authenticate users with DocuSign instead of the KB, select JWT. This allows users to work with DocuSign without triggering multifactor authentication in the KB. This allows you to login to DocuSign using the DocuSign API Username instead of providing a username and password. 
      1. Acquire the DocuSign API Username value from the DocuSign account that will be linked to the DocuSign User record in Agiloft. This value can be found in the user's DocuSign account in the Users and Groups section on the user's profile under API Username.
      2. In the DocuSign User record in  Agiloft, add the API Username value to the DocuSign User ID field. If this field doesn't appear, add it to the common area of your record layout. 
    2. To use a unique login for the user, choose the "With username" option. This allows you you to set up an Agiloft account directly using your existing DocuSign user login and password.
      1. Enter the DocuSign login email into the DocuSign User Name. Optionally, enter a password. 
    3. To share another user's DocuSign account with this user, choose the "As another user" option. This allows an Agiloft user to use a pre-existing DocuSign account that isn't directly linked. This is ideal for Agiloft users that would like to use a shared DocuSign account.
      1. Use the lookup to find and import the account name from the DocuSign Users table.
  4. Click the "Grant Access to DocuSign" button.

When you set up a user with their own unique login, the user will receive an email from DocuSign to activate their account. Until they complete this activation, they won't be able to perform DocuSign functions in  Agiloft, unless you work with DocuSign to configure Single Sign-On for this purpose.

Avoid Redundant User Authentication

If you have multifactor authentication set up for your  Agiloft KB, users may need to reconfirm their identity every time they attempt to use DocuSign directly from  Agiloft. This can be tedious and unnecessary for users, but there is a built-in way to prevent this additional login prompt from appearing while you create users. Instead of using the KB to authenticate users, you can use authentication tools from DocuSign that allow you to set up users without using a username and password. Instead, this method uses the API Username value from DocuSign to establish a connection between the two platforms.

To configure this feature, you require access to both  Agiloft and your DocuSign account. To set up a user with this authentication process, follow the steps below:

  1. Go to Setup > Integration and click Configure under DocuSign Extensions to access the DocuSign Extension tab in  Agiloft
  2. In another browser tab, open DocuSign and go to Admin > Apps and Keys. Copy the API Account ID, which can be found under the "My Account Information" section. Keep this browser tab open.
  3. In the DocuSign Extension tab of  Agiloft, paste the API Account ID into the Account ID field.
  4. In DocuSign, copy the Integration Key value, which can be found under the "Apps and Integration Keys" section.
  5. In the DocuSign Extension tab of  Agiloft, paste the Integration Key value into the Client ID field.
  6. In DocuSign, copy the RSA Keypairs (ID) value, which can be found under the Service Integration section. If there isn't a value present already, you can generate one by clicking the Add RSA Keypair button. This value may also be referred to as the RSA public key.
  7. In the Document Extension tab of  Agiloft, paste the RSA Keypairs (ID) value into the RSA Key field.
    Client ID, Account ID, and RSA Key fields

Now that you've properly configured your DocuSign extension to support this authentication process, you can create users who are able to use it. To set up users with this authentication method in your system, follow the steps below:

  1. Under DocuSign Users, click New. All DocuSign users created here should already have DocuSign accounts. Create the user as usual, but choose "JWT" next to the Authenticate section. This is what allows you to log in to DocuSign without needing to provide a username and password.
  2. Acquire the DocuSign API Username value from the DocuSign account that will be linked to the DocuSign User record in Agiloft. This value can be found in the user's DocuSign account in the Users and Groups section on the user's profile under API Username.
  3. In the DocuSign User record in  Agiloft, add the API Username value to the DocuSign User ID field. If this field doesn't appear, add it to the common area of your record layout. 
  4. Click the "Grant Access to DocuSign" button.

Add, Update, and Remove Users with Actions

After DocuSign is deployed in a knowledgebase, two actions are automatically added to the People table, and can be included in rules and action buttons:

  • Add/Update DocuSign User
  • Remove DocuSign User

However, as we saw earlier, adding a DocuSign user requires you to configure several settings. The Add/Update DocuSign User action can link the user to a DocuSign account automatically, but it does not add the user to the  Agiloft DocuSign users list and it does not grant them connection permissions. That means any user who is added by the action alone and not by an admin will be restricted to sending envelopes only in send-on-behalf mode, where the DocuSign admin user (specified in Setup > Integration > DocuSign Extension Configure) is used as the envelope sender of record. For this to work, the admin user must have send-on-behalf permissions active in the DocuSign account. If you want the user to send envelopes in their own name, you must manually add them to the DocuSign Users list in DocuSign Setup and grant access.

When the Add/Update DocuSign User action links the user to an account, it first checks the user's listed email address in the configured DocuSign account. If the user doesn't exist, they are added to the account or reactivated. Depending on the DocuSign account settings, which must be handled with DocuSign support, the user will be placed in Active status, where they can immediately use DocuSign privileges, or in ActivationSent status, which requires them to act on an activation email before they can use DocuSign.

The configuration file, located at ALHOME/KBNAME/scripts, enables you to change field mappings and some DocuSign access properties for users newly added by the Add/Update DocuSign User action. Note that if you wish to use the automatic password allocation option, with a retrieval mail in case of forgotten passwords, the options are:

  • password=abcdef
  • forgottenPasswordQuestion1=question1
  • forgottenPasswordAnswer1=answer1

Enable DocuSign Connect

DocuSign Connect allows  Agiloft to receive real-time updates from DocuSign. If this isn't enabled, you won't receive status updates for your envelopes and recipients, or for completed signed documents.

  1. Log in as the DocuSign Administrator.

  2. Go to Setup > Integration and click Configure under DocuSign Extension.

  3. Click Enable DocuSign Connect. If DocuSign is successfully 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 may 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 hosted server.

Once the DocuSign Connect link has been established, there will be a new Connect Configuration in the DocuSign admin console that you can use to monitor logs and failures and to control certain settings, such as the Gateway. To view this, click Connect under the Integrations seaction in the sidebar.

DocuSign Connect Configurations screen, showing an active connection with the knowledgebase

Enable DocuSign Connect with a Closed Server

If your server is not openly accessible to the web, follow these steps to enable secure port access for DocuSign Connect. 

  1. Open port access: In the web server, open up access to port 443 for the specified DocuSign IP ranges listed in the DocuSign security whitelist in the Trust section.
  2. Configure proxy: If there is an active proxy or firewall, configure it to also allow URL and port forwarding from https://external-address:443/extension.
  3. Update the DocuSign certificate: Your SSL certificate must be updated. Download the latest public DocuSign Connect certificate from this location and add it to the server.
  4. Manage hotlinks: All hotlinks for the server should be pointing to https://external-address. This will mean that when an admin creates a DocuSign Connect configuration and clicks the Enable DocuSign Connect in the DocuSign wizard,  Agiloft will use the external address to create the configuration in the DocuSign website. 

    If you receive an error message when using DocuSign that mentions the Publish URL, go to the DocuSign Connect configuration and check the value in the URL to Publish field.

Configure the DocuSign Envelope Action

The next step is to configure the Create DocuSign Envelope action. This action determines:

  • 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 create or edit the Create DocuSign Envelope action:

  1. Go to Setup > Integration and click Configure under DocuSign Extension.
  2. Either:
    1. To edit an existing action, locate the Action drop-down menu, select Create DocuSign Envelope, and click Edit Action.
    2. 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.
  3. Complete the fields to name and describe the action, optionally assign a template, specify the attached file field that holds the documents intended for the envelope, and configure a subject line for the email sent to the recipients.
    DocuSign Action
  4. 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 settings
  5. Click Save.

If you need to create multiple DocuSign actions at once, use the Actions tab of the table's 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).

Create and Send DocuSign Envelopes

Once you have created a document with DocuSign Tags by using a print template or manually adding the tags to a single document, you are ready to create a DocuSign Envelope.

For an in-depth discussion of creating documents with DocuSign Tags, see Create Print Templates with DocuSign Tags. Here are some tips to keep in mind:

  • Microsoft Word can be inconsistent in the way it formats print templates, variables and API tags from  Agiloft. Often, Word can insert extra formatting that is not visible in the document but that can interfere with DocuSign Tags.
  • Be careful when formatting DocuSign tags in Word print templates, and be sure to test the results.
  • As a rule, do not use HTML-enabled text fields in  Agiloft to insert DocuSign Tags into print templates. The resulting Word document will separate any sections containing HTML code away from the main document's XML file, which will result in an incorrect translation by the DocuSign API.
  • Spelling and grammar checks should be turned off for print templates, as Word may insert formatting that will interfere with the DocuSign Tags.

Create a DocuSign Envelope

  1. Open the contract record that contains the attachments you want to put in the envelope.
  2. Go to the Attachments tab and scroll down to the All Contract Attachments related table.
  3. Send any attachments you want to include in the envelope:
    1. To send just one attachment, edit the To Be eSigned field and set it to Yes.
      To Be eSigned field set to Yes
    2. To send multiple attachments, select all the attachments, mouse over Select Files, and click Add to E-Sign Packet.
  4. When you've added all the attachments you need, go to the Signature tab and locate the Esignature Files section.
  5. Click Refresh Files. If you are using the standard signer setup with the hard-coded fields, make sure that the signer email addresses are filled in.
  6. After checking the listed documents and entering all of the signer information, click Create DocuSign Envelope to convert the information into a DocuSign Envelope record. A DocuSign Recipient record is created for each signer and linked to the envelope. 

The DocuSign Envelope is created with a Status of Draft and appears in a pop-up window. The Status fields for both the DocuSign Envelope and the DocuSign Recipients are locked from editing and will only be updated by action buttons or updates from the DocuSign API.

Although we now have the DocuSign Envelope record in the Agiloft KB, the actual DocuSign envelope still hasn't been generated via the DocuSign API, and the user can still make edits to the email subject, custom messages for the recipients, and other settings.

Send the DocuSign Envelope

When you've made any necessary adjustments to the fields in the  Agiloft envelope record, you need to generate the envelope via the DocuSign API and thereby send it to the recipients.

  1. Verify all the information in the fields is correct. After this step, you'll have to go out of your way to make any more changes.
  2. Click Create and Preview to create the envelope and show it in the DocuSign web interface. Here, you can make changes before you send the envelope, such as adding or moving DocuSign elements and adjusting settings for the envelope and its recipients.

    Make sure to preview your envelope before you click Send to make sure your tags are positioned properly. If you click Send first, DocuSign will create the envelope in the background and immediately distribute it to the recipients to begin signing.

  3. In the DocuSign interface, notice the DocuSign fields that were placed wherever you had DocuSign Tags placed in the print template. The recipients are listed in the upper left, and you can add new DocuSign fields such as signer initials by dragging a field from the left pane to the body of the document. Similarly, existing DocuSign fields in the document can be removed or dragged to new locations. Make any such changes you need to.

  4. After the edits are finished, click Send to start the signing process and send the document to the first signers.

    Do not close the DocuSign window via the browser. If you are not sending the envelope out right away and need to come back to it later, always make sure to click on the Other Actions drop-down and choose to Save and Close or Discard. If you simply close the browser window, the DocuSign Envelope may become locked from editing. 

Track Envelope Progress

The Status value of the envelope record and recipient records is updated as each signer receives and signs the document. 

Once all signers have signed the documents in the DocuSign Envelope, the DocuSign API will send the finished signed PDF back to Agiloft. Agiloft then changes the Status value of the contract to Signed, and converts the signed PDF to an Attachment and links it to the contract. If you have enabled the option to attach the Certificate of Completion, the signed PDF that the envelope returns will have the certificate attached to the end of the document.

DocuSign sends out email notifications to the administrator and the recipients when the envelope is completed. Notification settings can be changed in the DocuSign account.

The option to attach a Certificate of Completion can be enabled using the Attach Certificate of Completion field in the DocuSign Envelope record in  Agiloft, or by adding the Attach Certificate of Completion to the Envelope PDF option in Preferences > Account Administration > Features > Sending and Signing on the DocuSign website. 

If a recipient reports an issue with delivery, or if you want to remind recipients of the envelope by sending it again, you can click Send again even if the envelope is Sent or Delivered already. If the Send button doesn't appear in the record, go to Setup DocuSign Envelopes, edit the Send action button field, and edit the visibility condition on the Options tab to include the Sent or Delivered statuses.

Send On Behalf Of

An  Agiloft user that is not in the DocuSign Users table can send out DocuSign Envelopes from their own account using SOBO (Send On Behalf Of) once the system has been set up to allow it. With this option enabled, when the user sends a DocuSign Envelope,  Agiloft sends the message using the DocuSign admin user's account, with the DocuSign admin acting as the authenticating user. The email address of the user who actually sent the envelope is attached to the request, and DocuSign sends the documents to the recipients under that user's name.

To enable this feature:

  • The DocuSign Account Administrator must be added in  Agiloft at the Setup > Integration > Configure DocuSign Extension screen.
  • The DocuSign account must have Account-Wide Rights and Send On Behalf Of Rights (API) Permission settings enabled. This can be done by a DocuSign administrator through the Classic DocuSign Experience web application or by contacting your DocuSign Account Manager.
  • The  Agiloft user that will be sending the DocuSign Envelope via SOBO must be registered as a Sender on the DocuSign website with an email address that matches the email address of their  Agiloft user record.

Switch to a Production Server and Finalize Setup 

Once you have set up and tested the DocuSign API functionality in your KB using the developer sandbox account, you can switch to a DocuSign production server and link your enterprise license to finalize the setup by following the steps below.

  1. Make sure you are signed into  Agiloft as the DocuSign admin user.
  2. Go to Setup > Integration and click Configure under DocuSign Extension.
  3. Click Disable DocuSign Connect. This disables the DocuSign Connect link to the current developer sandbox account. 
  4. In the DocuSign Users table, edit each DocuSign User that has been granted access and click Revoke Access.
  5. Return to Setup > Integration and click Configure under DocuSign Extension.
  6. Click Change Server and change the DocuSign Server to the production server where your enterprise license account resides. 
  7. Once you set the right production server, connect your production account using the same steps you used to enable and connect the developer account.
  8. Optionally, set the Create external envelopes option to Yes or No. If you select Yes,  Agiloft will create records in the DocuSign Envelopes table when envelopes are created outside the  Agiloft system. If you select No,  Agiloft will only accept DocuSign data for envelopes that already have a corresponding record in the DocuSign Envelopes table.
  9. Be sure to test the full DocuSign API integration from beginning to end by creating an envelope, sending it out, and completing the signing process.

In order for DocuSign Connect functionality to work on DocuSign's production servers, you must have an enterprise license and DocuSign Connect must be enabled on the DocuSign account. To view this, click your account icon and then Go to Admin. Under Integrations, click Connect and make sure it's enabled. If the option is grayed out, you can contact DocuSign to refresh this for you. 


If DocuSign envelopes aren't being received, try resetting the connection to the DocuSign server:

  1. Log in as the DocuSign Administrator.

  2. Go to Setup > Integration and click Configure under DocuSign Extension.

  3. Click Disable DocuSign Connect. This brings you back to the Integration menu.
  4. Click Configure under DocuSign Extension.
  5. Click Enable DocuSign Connect.

When a connection is established, you need to resend any envelopes that were sent and not received. In  Agiloft version 2019_02 and later, you can do this in  Agiloft:

  1. Go to the DocuSign Envelopes table.
  2. Open the envelope you want to resend.
  3. Click Send.

Otherwise, you can resend them through DocuSign:

  1. Log in to DocuSign as the administrator.
  2. Click Manage on the toolbar.
  3. Check each folder and resend any envelopes that failed.

Bypass Single Sign-on (SSO) Requirements

When SSO is enabled, you might want to exclude certain users from the SSO requirement so that they can still log in with their DocuSign username and password. For example, maybe you want to give administrators or other privileged users the ability to bypass the SSO requirement to allow them to address potential SSO configuration issues.

To configure this permission for certain users, see How to exclude specific users from SSO requirements? on the DocuSign website. Follow the instructions on the page, and for each desired user, choose the "Identity Provider or Username / Password" option for the Login Policy dropdown on the Security tab.