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.

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 receive the documents, usually to sign them. 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 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. The following steps will enable you to set up a test account.

Create a Developer Account for Testing

  1. Go to https://developers.docusign.com/.
  2. Click Create Sandbox. You can create an unlimited number of test/developer accounts.
  3. In the DocuSign website for the account, click your user icon and click Go to Admin. In the sidebar, click Permission Sets.
  4. Next to your permission set, click Actions > View.
  5. 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 selection
  5. Click Set Server.
  6. 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.
  7. 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. Navigate to the DocuSign Users table in the ESignature group 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. 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 a DocuSign user and grant access

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. Go to either the DocuSign Users related table in the DocuSign configuration page or in the DocuSign Users table, and then click New.
    Create a New user from the related table in the DocuSign Extension configuration screen
  2. In the DocuSign User record, use the lookup for the Login or Full Name to find the Agiloft user
  3. To use a unique login for the user, set the account to authenticate with username.
    1. Enter the DocuSign login email into the DocuSign User Name. Optionally, enter a password. 
    2. Click the Grant Access to DocuSign button.
  4. To share another user's DocuSign account with this user, set the account to 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.

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.

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 DSAddUserToAccountAction.properties, 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 your account icon and then Go to Admin. Under Integrations, click Connect. 

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. 

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 Wizard
  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.
    DocuSign Envelope Wizard - Recipients Tab
  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.

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. Select any attachments you want to include in the envelope.
  4. Mouse over Select Files and click Add to E-Sign Packet.
    Adding an attachment file to an envelope
  5. When you've added all the attachments you need, go to the Signature tab and locate the Esignature Files section.
  6. 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.
  7. 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 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.

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. 

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 Connec tand make sure it's enabled. If the option is grayed out, you can contact DocuSign to refresh this for you.