Please see the Introduction Youtube video for a run-down on how to use this activity.
To get started with the DocuSign Activiy Pack, you'll need a DocuSign Account. You can get a developer account here: UiPath Sandbox Account
You will also need to generate a DocuSign Integrator key, and take note of:
- Client ID
- Client Secret
- Redirect URL - This should be input to http://localhost:5000 (or something similar if you know what you're doing)
I've created an advanced training video for the DocuSign Activity Pack. It goes through all the features including formatting, different roles, special tabs such as formulas, radio buttons, and different signing methods.
https://www.youtube.com/watch?v=S70Zfqfzk_0&t=588s
To start using the DocuSign Activities, you'll need to drag a new DocuSign Application Scope into UiPath. You'll need to set the following values:
- Client ID
- Client Secret
- Redirect URL
- DocuSign API Url
The API Url will be either:
- For Development/Sandbox environments: https://account-d.docusign.com
- For Production Platforms: https://account.docusign.com/oauth/auth
The Docusign Application Scope also has the following parameter:
- Timeout (MS) This is the amount of time the activity will have to authenticate before throwing a TimeOutException. When using this activity for the first time, it can be useful to set this to a high value (i.e. 100000) to give you time to manually authenticate
The DocuSign Application Scope Is divided into 2 areas: The Authentication area, and the DocuSign activity area.
- The Authentication area is for all of the authentication activities.
- The DocuSign Activity area is for working with the actual DocuSign Activities.
There are two activities related to Authentication. They are both automatically added to a new DocuSign scope activity. They are:
- Authenticate
- Get Authorization Url
The authenticate activity completes the final step of the authentication process for DocuSign (yes, DocuSign makes authentication very difficult - they are clearly very concerned about security)
In order to complete the authentication, it is required to visit a special URL in a browser. The browser page uses javascript to complete the operation, so this step can't be achieved with a simple HTTP request
The authenticate activity completes this authentication step in one of three ways:
-
Manual This opens your default browser to the DocuSign authentication page. You will then be prompted to enter in your username and password for DocuSign. This method should only be used for testing and development.
-
Automatic - Insecure This method automates the log-in process. It requires a username and (insecure) password as input, and will step through the automation process for you. It also takes a Timeout (MS) argument - how long it will wait for the browser to load. This can usually be set to a lower value than the default. This method also should only be used for testing and development.
-
Automatic - Secure This is the same as the insecure method, only it uses a SecureString instead of a string. This means it will work with credentials stored on the Orchestrator. This is the recommended for authentication. This method is acceptable for using within production environments.
This activity can usually be deleted. It has a very low overhead, so it doesn't matter whether you delete it or not.
However, if you would like to implement your own authentication by automating the browser yourself, you will need to use this activity. It gives one output - Authentication Url. This is the page that you will need to point your browser towards. Then, you will have to automate clicking through the screens, entering email and password.
If you have already used the Authenticate Activity in a project, with either Secure or Insecure as the method, then you will find templates for the automation in your_project_folder/DocuSignAuthentication. These files are automatically generated by the Authenticate activity and can be used with an Invoke Workflow Activity.
There is one basic activity - the Request Signature activity. This is reccomended for new uses and basic use cases. It simply asks for details of the recipient - email, name, etc, a document upload, and then either an absolute or relative position on the page to sign.
These activities allow you to build an envelope by compositing Activities. This method can be very useful when:
- You want to include or exclude certain recipients based on conditional logic
- You want to include or exclude certain Tabs, or display certain information based on conditional logic
In the Advanced Training, you will see a case where both of these methods are employed
Any DocuSign workflow will require both a Create Envelope and a Send Envelope Activity.
-
Create Envelope - This generates the Envelope object that will be used by the rest of the DocuSign Activities. It takes 1 input - the Email Subject line, which will be sent out to the recipients.
-
Send Envelope - This actually sends the envelope. It takes as input the Envelope object generated by the Create Envelope activity. It also optionally generates an Envelope ID, which can be stored and used later with the List Envelopes activity.
There is one activity in this category - the Attach Document Activity.
- Attach Document - This takes a filepath to the document to be included, and a name for the document. It generates a Document object, which will be used by the Add Tab activites
There are several types of recipients. The main one that you will use is the Signer recipient - only signers can complete signatures, and fill in other fields. The other recipient types are for viewing or editing the envelope.
Details for the other recipient types can be found Here
All recipients have the following required arguments:
- Envelope - The envelope object that was generated by the Create Envelope Activity
- Recipient Email - The email address of the recipient
- Recipient Name - The name of the recipient
- Routing Order - This is the order in which recipients will receive the Envelope.
If 2 recipients have the same routing order, they will receive the Envelope at the same time. If 2 recipients have different routing orders: recipient 1 has routing order 1 & recipient 2 has routing order 2, then the envelope will be delivered to recipient 1. It will then wait until it has been signed by recipient 1. Only then will it be delivered to recipient 2.
There are a range of different tabs that can be added to a document. Tabs are added on a per document, per recipient basis. They require both a Document object (generated by the Attach Document Activity) and a Recipient object (created by the Add Signer Activity)
Trying to add a Tab to a recipient type other than a Signer will cause an error.
Tabs are divided into the following categories:
-
Display. These are Tabs which generally display information. Some of them contain information that is automatically generated, such as the EnvelopeID, or Full Name Tabs. There are also Tabs which allow the for input in UiPath, such as the Add Note tab, or Add Text Tab.
-
Input. These prompt the recipient to enter information. If the Value parameter is present, these can be set to a default value. All of these have a "Required" checkbox in the parameters. This specifies whether the recipient is required to complete this Tab in order to finish signing the envelope.
They also have "Shared" checkboxes, which haven't yet been implemented by the DocuSign Api.
-
GUI. These are special Tabs which display GUI elements to the recipient, such as Checkboxes, and Formulas.
-
Signing. These are the activities which allow the recipient to Sign (or decline) the document. The Sign Here & Intial Here Tabs are both required for the envelope to be completed, if they are added.
Many of the tabs share similar parameters. These are as follows.
- Font - DocuSign offers 15 different fonts
- Font Size - An unusual font-sizing system is used, starting at 1 for normal size text. 10 is very large.
- Font Color - A few options of colour are available
- Bold / Italc / Underline - As expected
- Width / Height - As expected
- Document - The document to attach to
- Page Number - The page on which to display the Tab
- Signer - The signer to complete or view this Tab
-
Tab Label - This is for used with Number Tabs and the Formula Tab. Give Number Tabs a Label, and you'll be able to reference them in calculations you perform with the Formula Tab.
-
Tool Tip - Displays information when the recipient hovers over the Tab
-
Required - If this box is checked, the recipient must fill out this tab before they can complete the signing process.
Position can be specified in either Absolute or Relative form.
In Absolute form, you give the X & Y co-ordinates in pixels for the Tab
In Relative form, you give the "Anchor Text" to position next to, and the X & Y offset relative to the anchor text. Only selectable PDF text can be used, it won't search images for text information.
The Add List & Add Radio Group tabs both take a comma seperated list of values to be displayed. For example, if you wanted a dropdown box to be displayed with a few items, you'd create a Add List Tab activity, and set the List Items parameter to: "New Account,Existing Account,External Account"
The Formula Tab can compute sums and display the results. The formula parameter can be used to calculate simple sums, such as:
"1 + 2" will display 3.0
Or, it can be used to perform calculations using other Number Tabs on the same document. For example, if you'd like to calculate the result of two number tabs, you'd do the following.
- Create a number tab, and set the Tab Label parameter to "number1"
- Create a second number tab, and set the Tab Label to "number2"
- Create a formula tab, and set the formula parameter to "[number1] + [number2]"
Some of the signing tabs come with a Scale Value parameter. This hasn't yet been implemented by DocuSign.
It's possible to define an envelope using the Visual Editor on the DocuSign website. If you don't require complex logic for your envelope, this option is preferred over building your own envelopes using the composite activities.
A template is sent by:
- Load Template - Use the load template activity to load the template information, using the Template Name you specified in the DocuSign editor as a reference.
- Assign Template Role - Match up the Template Roles you defined in the DocuSign Editor with names and email addresses as inputs.
- Send Template - Templates require a special activity in order to send.
It's possible to retrieve the status of envelopes that have been sent, and take according action. This can be useful to continue the automation of a process, once an envelope has been completed.
Warning: DocuSign require that you run this activity no more than every 15 minutes. If you poll the server more than this, you will struggle to get your API key promoted from a development to a production key
In the Envelopes Category, you will find a List Envelopes activity. This will retrieve the envelopes on the DocuSign server, along with their current status. There are various ways to search and filter the envelopes that are returned. These are:
- From Date - The date at which to begin the search
- To Date - The date at which to end the search
- Envelope IDs - The envelope IDs generated by the Send Envelope Activity
- From-To-Status: This filters the envelope by it's current status. This value can be any of: Any (all envelopes), created, sent, delivered, signed, completed, declined, timedout, declined, deleted. For more details see this page
- Status: This is a comma seperated list of statuses which to return. It allows more fine-grained control of the envelops to return. These values can include any of: "any, created, sent, delivered, signed, completed, declined, voided, deleted"
There are a few reasons why you might be getting this error message. It means the browser-based authentication wasn't able to complete within the Timeout MS value given in the DocuSign Scope activity.
Potential Solutions
-
Make sure that the authentication is happening correctly. If the username or password are incorrect, you will get this error message.
-
If you are authenticating manually, or you are on a slow system, it might be worth increasing the Timeout MS value in the DocuSign Application Scope Activity.
-
Check your firewall. If you are not allowed to listen on the port specified in the Redirect URI, you won't be able to complete the authentication process. It may be as easy as clicking "Allow this Connection" when your firewall throws an alert. In the worst case scenario, this will mean contacting your system administrator.
This almost certainly means that you are using an Envelope, Document, or Recipient object that hasn't been created by the corresponding Create Envelope, Attach Document, or Add Recipient activity. Basically, you are using an empty variable instead of a real Envelope, Document, or Recipient object (created in the proper way).
In order to deploy this Activity Pack into a production environment, you will need to "Go Live" with your Integrator Key. A detailed guide can be found at Docusign - Go Live
Once you have Gone Live, you will need to update your URI endpoint from https://account-d.docusign.com --to--> https://account.docusign.com/
- JSON.Net - Took care of all the encoding to JSON
- Visual Studio - What a pleasure it was working with such a lavish IDE
- Vim - Used to plow through the repetitive editing
- Ben Mann - Design / Development / Production / etc
This project is licensed under the MIT License - see the LICENSE.txt file for details
- Thankyou to the wonderful UiPath Team for all the help they've given me in the Slack Channel, and in the Webinar for developing Custom Activities