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 document or contract management needs. Through the DocuSign API, Agiloft creates DocuSign envelopes and sends out documents 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.

Terminology

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 sign the documents. They are specific to the DocuSign envelope and each recipient is assigned a specific DocuSign Role. See here for more information.

DocuSign roles

The DocuSign 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.

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 and creates an attached document using the print template containing the DocuSign tags. 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 in PDF format is sent back to Agiloft. 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.

Set Up a Test Account

You can test your DocuSign setup with a free developer account before using you or your customer's enterprise account details. The following steps will enable you to setup a test account.

Create a Developer Account for Testing

  1. Go to https://www.docusign.com/developer-center.
  2. Click Create Free Dev Sandbox. You can create an unlimited number of test/developer accounts.
  3. In the DocuSign website for the account, ensure that the Send On Behalf Of Rights (API) are enabled under  Preferences   >   Member Options   >   Permissions in Classic view. This option is on by default. 

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  to add the DocuSign server details. 
  4. For the initial setup and testing, set the DocuSign server to the Demo server. 

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.

  1. Navigate 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 give DocuSign access to.
  3. Once selected, enter the DocuSign username and password you used to create a user in the DocuSign website.
  4. Click Grant Access to DocuSign to add the user to the DocuSign account. This user will be the DocuSign Administrator.  

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. Either in the DocuSign Setup, or in the DocuSign Users table, add a new user record. 
  2. In the DocuSign Users record, enter the login and full name of the user, or use the lookup to import them from the People table. 
  3. If you wish to use a unique login for the user, select Authenticate "With username".
    1. Only enter the DocuSign login/email into the DocuSign User Name and optionally a password. 
    2. Click the Grant Access to DocuSign button. 
  4. If you wish for this user to work with DocuSign from the account of another DocuSign user, select Authenticate "As another user".
    1. Use the lookup to find and import the account name from the DocuSign Users table. 
    2. Click the Grant Access to DocuSign button. 

Adding and removing DocuSign users through 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

Notes on the Add/Update action

  • The Add/Update action first checks the user's email address in the knowledgebase's configured DocuSign account; if the user does not exist, they are added to the account, or reactivated if previously deactivated. Depending on the DocuSign account settings, which must be handled through DocuSign support, the user will be placed in ActivationSent or Active status, which will determine whether or not they are sent an activation email before they can be Active. 
  • This action does not add the user to the  Agiloft DocuSign users list and does not grant them connection permissions. The user is therefore restricted to sending envelopes only in send-on-behalf mode, which means that the 'real' envelope sender is a DocuSign user (usually an admin) who has been granted access in DocuSign Setup, located at Setup > Integration > DocuSign Extension Configure . This user must have send-on-behalf permissions active in the DocuSign account, which must be configured on the DocuSign website. This user will then send the envelopes on behalf of the user who was created through the Add DocuSign User action, and the envelope will appear to have been sent by the non-admin user. 
    • If a user needs the ability to send envelopes directly, manually add them to the DocuSign Users list in DocuSign Setup and granted access.
  • The configuration file DSAddUserToAccountAction.properties, located at ALHOME/KBNAME/scripts, enables you to change field mappings and some DocuSign access properties for the newly added user. 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

  1. In the DocuSign Extension screen, click the Enable DocuSign Connect button. This will allow  Agiloft to receive real-time updates from DocuSign. If this is not enabled, you will not receive status updates for your DocuSign Envelopes and Recipients as well as completed signed documents. 

  2. If DocuSign is successfully enabled, a new status notification will display.

  3. In the DocuSign Extension screen, the ConnectID will also be displayed. This will indicate that you have successfully connected the  Agiloft KB and user(s) to the DocuSign API and enabled real-time updates via DocuSign Connect.

Enabling DocuSign Connect with a Closed Server

In the case that your company has a server which is not openly accessible via the web, the following steps should be done to enable secure port access for DocuSign Connect. 

  1. Open port access: In the web server, open up access to port 443 for the following DocuSign IP ranges (from https://trust.docusign.com/en-us/trust-certifications/ip-ranges/):
    1. Current and continuing for North America based and demo accounts:
      1. 209.67.98.1 through 209.67.98.63
      2. 206.25.247.129 through 206.25.247.159
      3. 209.46.117.161 through 209.46.117.191
      4. 162.248.184.1 through 162.248.187.255
      5. 54.149.21.90
    2.  New additions for North America based and demo accounts:

      1. 54.69.114.54
      2. 52.25.122.31
      3. 52.25.145.215
      4. 52.26.192.160
      5. 52.24.91.157
      6. 52.27.126.9
      7. 52.11.152.229
  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 to https://internal-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. 
    Tip: If you receive an error message when using DocuSign that mentions the Publish URL, check that setting in the DocuSign Connect configuration. To open the configuration, log in to the DocuSign sandbox and go to Preferences > Account Administration > Connect, select the configuration, and review the URL to publish to 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 holes the documents.
  • The subject line for the DocuSign email to signers/recipients. 

Edit the Create DocuSign Envelope action

  1. In the DocuSign Extension screen, select the Create DocuSign Envelope in the Action field and click Edit Action.
    The DocuSign Action wizard opens.
  2. Or, to create a new DocuSign Envelope action for a table, select the table from the list and click Add Action. 
    • Add a Name and Description for the action.
  3. Add any DocuSign template you'd like to use, indicate which attached file field holds the documents to be included in the envelope, and decide the subject  line for the DocuSign email to the signers/recipients. 
  4. Click the Recipients tab.
     
    1. Select the Number of recipients for the envelope action. 
    2. For each recipient number, there will be a section that appears where you can define their Role Name, Role, Recipient Field, Access Code if needed, and the message contents. 

      Note: The Roles available in the Role Name field are defined in the DocuSign Roles table. The standard setup comes with one internal signer and three customer signers defined, but these are customizable. These roles will be used in DocuSign Tags to identify which signer each DocuSign Tag or field is related to.

    3. Click Save.

Create and Send DocuSign Envelopes

Once you have created a document with DocuSign Tags by using a print template or manually editing in the tags, you are ready to create a DocuSign Envelope. First, select the Attachments you would like to add to the DocuSign Envelope by changing the value of the choice field To Be eSigned to Yes. This can be done from within the contract record by going to the Contract Attachments related table, selecting the Attachment, and clicking on the Add to DS Envelope action under Select Files. 

Once the right attachments are added, go to the Signature tab and click on the Refresh Files button next to the DS Files to Sign field to refresh the document files that will be sent to the DocuSign Envelope. If you are using the standard signer setup with the hard-coded fields, make sure that the signer email addresses are filled in. 

After selecting the appropriate documents and entering all of the signer information, press 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 via 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. Pressing the Send button will send the information to the DocuSign API in the background, which will trigger the DocuSign API to create the envelope and the recipients and start the signing process.

Pressing the Create & Preview button will also create the DocuSign Envelope and open it up in the DocuSign web interface. The user can make changes such as adding or moving various DocuSign elements and changing envelope and recipient settings before sending out the envelope by pressing the Send button inside the envelope record or in the DocuSign Envelopes related table in the contract record. 

In the screenshot of the DocuSign Envelope interface below, you can see the DocuSign fields that were placed where the DocuSign Tags were in the Agiloft print template. The recipients are listed in the upper left, and you can add new DocuSign fields such as signer initials by selecting a recipient, and drag-and-dropping the 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. After the edits are finished, pressing the Send button will start the signing process and send the document to the first signer(s). 

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. 


 

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 document(s) 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. This option can be enabled via the Attach Certificate of Completion field in the DocuSign Envelope record in Agiloft, or via the Attach Certificate of Completion to the Envelope PDF option in Preferences > Account Administration > Features > Sending and Signing on the DocuSign website. 
 
 

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

Send On Behalf Of

An  Agiloft user that is not in the DocuSign Users table can send out DocuSign Envelopes using their own account via SOBO (Send On Behalf Of) once the system has been set up to allow it. 

The following setup is required to make use of this feature:

  • The DocuSign Account Administrator should be added in  Agiloft at the Setup > Integration > Configure DocuSign Extension screen.
  • The DocuSign account must have the  apiAccountWideAccess and allowSendOnBehalfOf rights enabled through the DocuSign website. 
  • 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 his or her  Agiloft user record.

When a  user then sends a DocuSign Envelope, for example via an action button,  Agiloft sends the message through the DocuSign Administrator's account, acting as the authenticating user. The 'operating user's' email is attached to the request, and DocuSign sends the documents to the signers under the initiating user's name. 

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. Go back into Setup > Integration > Configure DocuSign Extension.
  2. Click Disable DocuSign Connect to turn off DocuSign Connect to the current developer sandbox account. 
  3. Edit all DocuSign Users that have been granted access and press the Revoke Access button to revoke their access.
  4. Click Change Server and change the DocuSign Server to the production server where your enterprise license account resides. 
  5. Once you are on the right production server, follow the same steps you used to enable and connect the developer account to connect your production account. Remember that you need to be signed in as an  Agiloft user that is listed as a DocuSign admin in order to enable DocuSign Connect.
  6. 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 website in Classic view under  Preferences > Account Administration > Features . If the DocuSign Connect option is grayed out, you can contact DocuSign to refresh this for you.  
  • 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.

Agiloft