Adobe Sign for ServiceNow - Installation and Configuration Guide

The Adobe Sign for ServiceNow allows document signature requests to be sent via the ServiceNow platform using native functionality.  Signature request are sent via workflow to the Adobe Sign service.

Below are the application dependencies for Adobe Sign for ServiceNow.

• Adobe Sign enterprise level service

          ○ You must have an account level administrator in the Adobe Sign application to establish the OAuth connection

• Required Plugins

○ Orchestration

• System Table Permissions Required

○ Email Notification (sys_event_email_action)

○ Email Templates (sys_email_client_template)

○ Email Layouts (sys_email_layout)

Once you have signed up for and/or purchased the connector, it should show up under the “System Applications” menu in your ServiceNow instance.

After the installation has completed, you have two new Application menus in your left navigation panel - “Adobe Sign” and “Adobe Sign Administration”.

The left menu is the user's menu/view, and the right is the administrator's view.

A scheduled job named Adobe Sign - Auto-Refresh Documents has been created that updates the documents contained in the Adobe Sign Documents table.  By default, it is set to run nightly at 1 AM.  This can be configured to run as needed.

In order to facilitate the signing of attachments, a Mid server is needed along with two custom Jar files (provided below).  If you do not already have a Mid server, follow the setup instructions provided by ServiceNow here.

Once the Mid Server is installed, make sure that it’s set to be the default server for Orchestration.  Under the Orchestration menu, go to Mid Server Properties and enter the name of your Mid Server in the Default Mid Server to use for Orchestration activities field.  

There are two custom Jar files that need to be deployed to your MID Server:

• JSON Simple
• MultiPartFileUpload

They can be installed by following the procedure outlined here.

Make sure the Mid Server restarts (this should happen automatically).

There are two roles included with the application - “x_desci_adobesign_admin” and “x_desci_adobesign_user”.  Any user with the “x_desci_adobesign_admin” role has full access to all functionality as well as both user and admin menus.  

Users with the “x_desci_adobesign_user” only have access to the “Adobe Sign” user menu and example catalog items.

All custom workflow activities were built with a “result” output.  By default, this output is set to the activity result value: 

• If there is no error (activityOutput.result==null), then the activities move on as successful. 
• An error state (activityOutput.result!=null)) results in the specific error being logged, and the workflow being set as closed incomplete. 

How the “failure” state is handled is configurable, so notifications can be sent, a task can be added for a technical resource to review, etc.  

Three custom fields have been added to the task table, and can be added to an Adobe Sign custom list view, if desired, to show document status and information to the end-user in a more clear manner.  The fields are:

• Document Status (x_desci_adobesign_document_status) - Status of the document in based on the status within Adobe SIgn.  The same values are in the “Document Status” field and also correspond to the states used within Adobe Sign.
• Document URL (x_desci_adobesign_document_url) - Adobe Sign URL of the Document agreement
• Agreement ID (x_desci_adobesign_agreement_id) - Unique ID of the agreement 

For more information on creating a custom list view,  click here. 

A view rule can also be created that forces the users to see the custom view.  For more information, click here.  

For more information on creating a custom list view,  click here. 

A view rule can also be created that forces the users to see the custom view.  For more information, click here. 

A screenshot of an example view is shown below:

The Adobe Sign for ServiceNow application requires an Adobe Sign account in order to facilitate communication between the connector and ServiceNow.  

You need an Adobe Sign Account to allow ServiceNow to communicate with the E-signature service.  If you do not have an account, get one here - Adobe Sign

Once you have an account, create the link between ServiceNow and Adobe Sign by clicking the Connect To Adobe link in the Adobe Sign Administration menu.

This directs you to the connection page:

• Click the Connect button to establish a trusted relationship to Adobe Sign.
  • This redirects you to the Adobe Sign login page, where you need to login and grant persistent access

• Authenticate to Adobe Sign using your Adobe Sign Administrator account
  • The panel refreshes to verify that you want to establish a trusted relationship

• Confirm access by clicking the Allow Access button

Once you have done this, you should see the Adobe Sign Connect Complete message (shown below) when you use the Connect to Adobe Sign link.

You have now connected the Adobe Sign service to ServiceNow. 

Testing can be performed by following the steps outlined in the section above.  If you are connected, and the logged in user has the correct role, then your configuration should be correct.

Demo catalog items and workflows that illustrate usage of the custom workflow activities have been created.  These provide end-to-end examples of how items and workflows need to be setup in order to leverage the Adobe Sign for ServiceNow application.

Two demo catalog items have been created for the application.  Between the two items, all supported scenarios for obtaining a signature are demonstrated.  

• Adobe Sign - Request A Signature – Allows requestor to select an existing document – either on their local hard drive or an existing library document within Adobe Sign – and send to one or more people for signature. The process can be configured to send the document AS-IS/Immediately or to first preview the document within the Adobe Sign Send experience
• Adobe Sign – Request W9 Signature – Sends a specific document for signature (in this case a W9 form), with the user never having to specify.  This example shows how to leverage the connector to send a specific document without having to ask the user to search for it or attach to the request.  The document specifics are added to the custom workflow activity in the workflow.

Two demo workflows have been installed with the application.  These workflows also have custom stage values that correspond with the document status within Adobe Sign.  At this time, only a few of these values are used, but others may be used in future versions of the application. 

Adobe Sign - Request A Signature – Tied to the “Adobe Sign - Request A Signature” catalog item, and illustrates four different scenarios as to how the connector can be used to send a document for signature:

• Use an existing document with preview - Sends the document chosen from the drop-down list after the requestor has previewed it.  On submission, the requestor receives an email with a link to the created agreement (see Email Notifications).  After the user has verified the document, it is then sequentially sent (in order of entry) to all emails addresses entered for signature.  Once the agreement is signed, it is attached to the completed requested item.
• Use an existing document without preview - Upon submission, sends the document chosen from the drop-down list to all email addresses entered, in order of entry.  There is no preview of the document. Once the agreement is signed, it is attached to the completed requested item.
• Attach document with preview - Sends the attached document after the requestor has previewed it.  On submission, the requestor receives an email with a link to the created agreement (see Email Notifications).  After the user has verified the document, it is then sequentially sent (in order of entry) to all email addresses entered for signature.  Once the agreement is signed, it is attached to the completed requested item.
• Attach document without preview - Upon submission, sends the document chosen from the drop-down list to all email addresses entered in order of entry.  There is no preview of the document. Once the agreement is signed, it is attached to the completed requested item.

Adobe Sign - Request Specific Document Signature - Tied to the “Adobe Sign – Request W9 Signature” catalog item, and illustrates how the connector can be used to set the document to send via the workflow, and presenting the requestor with a specific document to request.  The following two scenarios are illustrated in this workflow:

• Send workflow-specified document with preview - Sends the document specified in the workflow after the requestor has previewed it.  On submission, the requestor receives an email with a link to the created agreement.  After the user has verified the document, it is then sequentially sent (in order of entry) to all emails addresses entered for signature.  Once the agreement is signed, it is attached to the completed requested item.
• Send workflow-specified document without preview -  Upon submission, sends the document specified in the workflow to all email addresses entered.  There is no preview of the document. Once the agreement is signed, it is attached to the completed requested item.

Custom workflow activities were created to facilitate the signature process.  Based on the operation chosen (attach a document, use an existing, preview or no preview, etc.), the operation of the activity has to change in order to process the request.  Each custom activity is listed below, and is used at least once in the two example workflows provided.

• Adobe Sign - Send Selection, Preview - Used when the “adobe_preview” variable = yes and the “adobe_attach_or_existing” variable = no.  Sends the document chosen (the “adobe_lib_doc”) to the email addresses in the “adobe_email_address” for signature after the requester has previewed and sent for signature.
• Adobe Sign - Send Selection, No Preview - Used when the “adobe_preview” variable = no and the “adobe_attach_or_existing” variable = no.  Sends the document chosen (the “adobe_lib_doc”) to the email addresses in the “adobe_email_address” for signature after submission of the request, and does not wait on a preview.
• Adobe Sign - Send Attachment, Preview - Used when the “adobe_preview” variable = yes and the “adobe_attach_or_existing” variable = yes. Sends the attached document to the email addresses in the “adobe_email_address” for signature after the requester has previewed and sent for signature.
• Adobe Sign - Send Attachment, No Preview - Used when the “adobe_preview” variable = no and the “adobe_attach_or_existing” variable = yes.  Sends the document chosen (the “adibe_lib_doc”) to the email addresses in the “adobe_email_address” for signature after submission of the request, and does not wait on a preview.
• Adobe Sign - Get Attachment Data - Used when the “adobe_attach_or_existing” variable = yes.  Gathers the agreement data and leverages the custom jar file and Mid Server to convert to multipart / form format. 
• Adobe Sign - Send Document X, No Preview - Used when the document has been pre-defined, and “adobe_preview” variable = no.  The "adobe_lib_doc" input parameter holds the name of the agreement that is sent.  The name value can be found in the "Adobe Sign Documents" table.  In our we are sending the W-9 document, and we are also defaulting "adobe_agreement_name" to "W9 Form Signature Request".
• Adobe Sign - Send Document X, Preview - Used when the document has been pre-defined, and “adobe_preview” variable = yes.  The "adobe_lib_doc" input parameter holds the name of the agreement that is sent.  The name value can be found in the "Adobe Sign Documents" table.  In our example item/workflow, we are sending the W-9 document, and we are also defaulting "adobe_agreement_name" to "W9 Form Signature Request"
• Adobe Sign - Attach Signed Agreement - This activity returns the signed document from Adobe Sign, and attach to the current record.  This activity should be used when a document has been selected or attached by the requester, and NOT when a specific document has been hardcoded.  Use "Adobe Sign - Attach Signed Agreement X" for those situations. 
• Adobe Sign - Attach Signed Agreement - This activity returns the signed document from Adobe Sign, and attach to the current record.  This activity should be used when a document has been selected or attached by the requester, and NOT when a specific document has been hardcoded.
• Adobe Sign - Attach Signed Agreement X - This activity returns the signed document from Adobe Sign and attach to the current record, in the instance of a pre-defined document.

Three custom email notifications have been built to illustrate the custom templates and layouts, as well as to provide an example of the preview / verification URL.

• Adobe Sign - Request Opened - Fires when a preview has been requested (“adobe_preview” variable is set to yes) and the item is one of the demo items.  It includes a link to the agreement waiting to be verified.  

NOTE - If other notifications are created, you need to include the URL of the document so that the requester can verify.  This link is also on the RITM form and can be added to others by adding the “document URL” field to the form view.

• Adobe Sign - Request Cancelled - Fires when the Item is either of the 2 demo catalog items, State is “Closed Incomplete”, and Stage is “Aborted”.
• Adobe Sign - Request Closed - Fires when the Item is either of the 2 demo catalog items, State is “Closed Complete”, and Stage is “Signed”.

Navigating to any of these records allows you to see the example templates as well as the example layout.

The scheduled job that auto-refreshes the Adobe Sign Documents table is preconfigured to execute at 1 AM local system time. This job can be reconfigured to execute at any time, and can run daily, weekly or continually.

To edit the job, access the Adobe Sign Administration menu > expand the Refresh Documents Setup item > click Auto-Refresh Documents Job

Configure the panel to the desired settings, and click Update to save.

Clicking Execute Now runs the job immediately one time.

Help documentation and links are included on both the user and admin menus.  The below website also provides support contact information

• Contact Method: Website
• Contact Details: https://echosign.zendesk.com/hc/en-us

Below are a few common issues that may come up during setup and usage of Adobe Sign for ServiceNow.

Catalog Item variable names - The variable names used in the two example catalog items are very important to the functionality of the connector.  They are used extensively in the custom workflow activities, and any change to them causes issues in the workflow.  If you make changes to any variable names, then you must make a corresponding change within any Adobe Sign activity used in the workflow.

Connection Error when you visit the “Connect to Adobe Sign” link (admins only) – If you see a connection error screen (shown below), then you need to reconnect following the procedures outlined in the Connecting your Adobe Sign account to ServiceNow section.  Also, verify the Adobe Sign account info is correct.

Attachment activities are not functioning correctly - The attachment activities depend on the Mid server connection to function correctly.  Make sure that the Mid server is up and running and that the Jar file is installed correctly.  If they still fail, make sure that all variable names are correct as outlined above.

Agreement ID errors when submitting a request - Agreement ID errors can be caused by the documents listed in the “Adobe Sign Document” table / My Documents menu option belonging to another Adobe Sign account.  Although the names of the demo documents provided by Adobe may match, they have different agreement IDs in the account. If the attached Adobe account changes, make sure to refresh the document by using the “Update Document List” in the Adobe Sign menu.

Menu options are / are not visible for users - Make sure all users who need access to the application have the correct roles assigned to them.  If you are using groups, make sure that they also have the needed roles attached to them.

No errors, but email recipients aren’t receiving the signature requests - Make sure you are entering the addresses as comma separated. The correct format is email1@email.com, email2@email.com, email3@email.com, etc

Custom Workflow Activities do not show as they should in the workflow editor – Currently, there is a bug that affects the visibility of the custom workflow activities.  The problem usually shows up after an upgrade or update to the AdobeSign for ServiceNow application.  If the activities cannot be seen follow the below steps to correct.

• Navigate to the “wf_element”activity” table by typing wf_element_activity.list in the left navigation search bar

You see all the workflow activities listed, including the global ones.

• Filter the list down to just the Adobe Sign activities by using the application = AdobeSign filter

Once you have the list filtered to just the AdobeSign activities, you will see each version of the activity listed. Unless you have added your own custom activities, the count should be around 320, as shown in the screenshot

• Click on any activity record to open that specific activity, and click the “hamburger” on the record header and choose Versions
  

This takes you to a version list:

• Sort the version list by the version, and open the latest version record.  In this example, our latest version is 10, so we will need to edit that particular record 
  

Note that even though you see version 10, it is set to Published = false.  This is the root of the issue we are working around.  Even though the activities are there, the latest version record is not set to Published=true, so they do not show in the workflow editor as available to you.

• Set the latest version to true by double-clicking the published field and changing from false to true
• Repeat this process for each custom activity
  • It may be helpful to filter the activity you just corrected out of the main list as you go through them.

To add the Related Lists to your view:

• Click on the hamburger (as you did above to get the versions option), and choose Configure > Related Lists.  

• Move the Version -> Element Definition related list to the Selected box
• Click Save

This action adds the related lists to the form only needs to be completed once for all records.

You should now be able to double-click the active field and set to true.