DocuSign Integration with Mendix
This blog is meant to guide anyone who wants to integrate DocuSign in Mendix, using the DocuSign Connector from the Marketplace
What is DocuSign?
DocuSign is an electronic signature, transaction management, and document workflow service. Accessible anytime, anywhere, on any device, the DocuSign Global Network connects organizations to their customers, partners, suppliers, and employees where they transact business in confidence.
What do we need?
Before starting with the implementation, make sure you have all the required modules. You will need the below things to get started with the implementation
- Create a sandbox account in the DocuSign portal for testing purposes before moving to the production environment.
- Make sure you are using Mendix Studio Pro version 9.6.3 or higher.
- Additionally, you need to ensure you import the below modules to get started with the DocuSign Connector module:
View the DocuSign Connector In the Marketplace
Create your Sample Mendix App
Step 1: DocuSign Developer Account Setup
- Go to DocuSign and create a new account if you don’t have one.
- Once the account is created, log in to the portal with the created account.
- Once logged in, click on the “Settings” tab available at the top right.
- Click on the “Apps and Keys” option available in the left navigation.
- Click on the “ADD APP AND INTEGRATION KEY” button
A popup will appear, write your app name and click on the “CREATE APP” button.
- A page will open where you can see the IntegrationID
Make sure to save your IntegrationID somewhere safe for later use.
Under Authorization, select the option “Authorization Code Grant” option and click on “ADD SECRET KEY” to generate a secret key and store it for later use.
Under Service Integration, click on “GENERATE RSA KEY” to get the keyid, public key, and private key.
Note: Make sure you are storing it somewhere as you won’t be able to see these details again, you need to generate a new one if you have not stored it anywhere.
- Under “Additional Settings”, add a redirect URI based on the application URL. I have used my local URL and Mendix sandbox free cloud URL.
Note — Make sure the URL ends with “/auth/docusign/callback”
Once done, click on the “Save” button and save your configurations.
Step 2: Create Sample Mendix App and complete the required configurations
Once all configurations are done. Follow the below steps to start with the integration in Mendix Studio Pro.
- Create one sample application to test DocuSign Integration or you can continue with an existing application.
- Once done, import all the dependent modules in your application listed above.
- Give the DocuSign Connector and JWT module access to the ‘Administrator’ user role as below -
- Add a page “DocuSign Configuration”. Call the snippet “SNIP_Configuration” available in the DocuSign Connector on the created page.
- From the navigation menu, show the page “DocuSign Configuration” which we just created.
- Run the app, go to the browser, and go to the ‘DocuSign Configuration’ from the navigation.
Go to the ‘Authentication’ tab and add all the details on the page as requested.
Add the configurations below :
App Name — Give the name of the app created in the ‘DocuSign Developer portal’—for eg — Offer Generator Application.
Environment — Developer
Authentication Type — as “JWT”. (If the authorization is needed for each user who will be using the DocuSign- in that case use “Authorization Code Grant” else use “JWT”, it requires authentication for only one user).
Integration key — from the DocuSign developer portal as shown below-
User ID — available in the DocuSign developer portal as shown below-
JWT Private key — is visible once you create an app in the Docusign developer portal. If forgot to store it, go to the portal, edit the app and click on Generate RSA, copy the private key, and paste it into the Mendix configuration page.
Remeber to select Scopes as per your need.
Authorization endpoint — https://account-d.docusign.com/oauth/auth
Token endpoint — https://account-d.docusign.com/oauth/token
Userinfo Endpoint — https://account-d.docusign.com/oauth/userinfo
isActive — Yes
- Once all the details are added, click “Authorize with JWT” to get the authorization and “Access Token”.
You will be redirected to the DocuSign portal. Login with your DocuSign account and then again you will be redirected back to your Mendix app based on your callback URL.
Go to the “Authorization” tab and check whether your account is authorized or not.
Go to the “Templates” tab and add one template. This template will set the content of the subject and body of the email to be triggered by the DocusignConnector module.
Click on the “Create Template” button, add the required fields Template Name, Template description, Email subject, and Email body, and click on the “Save and Close” button.
Once everything is done, you can create an envelope by going to the “Envelopes” tab and sending it to the user manually.
The other option to implement is to send the document to the user using the DocuSign connector module dynamically.
Step 3: Create microflows to handle DocuSign integration dynamically.
For the second case, you need to follow the steps mentioned below -
Let’s look at an example: I am generating a document and I want to send the generated document to certain users who need to sign the document using the DocuSign Connector module dynamically.
Note: We will be using the microflows available in the DocuSign Connector module to accomplish our use case. Since it’s not a good idea to modify the existing microflows of the DocuSign Connector module. So, we will be creating a duplicate of the microflows and will be using it in our own module for our use case.
- Copy the microflow, “ACT_Envelope_Create” and call it from a button in your module.
Don’t forget to replace this sub-microflow call to get authorization from JWT.
In the same microflow, once the envelope is created, there is a decision activity to check if the envelope is created — proceed further, or else show an error message to the user.
Once an envelope is created successfully, call two sub-microflows :
— “ACT_Template_Use” (Remember to duplicate this microflow from the DocuSign Connector to use it for your use case) and — “ACT_Envelope_SaveSendNow” available in the DocuSign Connector directly.
You can refer to my microflow as shown below:
- Open microflow “ACT_Template_Use”. First, retrieve the Template from the database based on the template name created previously.
Pass the object of the new envelope and the file document (In my case it’s Offer Letter Templates) which you intend to send via DocuSign created in the previous microflow as a parameter.
Next, create an object of “DocusignConnector.Document”.
Then call “CommunityCommons.DuplicateFileDocument” to add your document contents to the DocuSign document, and provide the following configurations for the action:
File to clone -> Document which you wish to share using Docusign
Clone target -> DocusignConnector.Document the object which you created before this step.
Once done, use the Change object activity to set the template id, email subject, and status retrieved from the template object.
Next, retrieve DocusignConnector.Documents object via association between envelope and documents.
Set the association between DocusignConnector.Documents and DocusignConnector.Document by using change object activity.
Set the association between DocusignConnector.Document and DocusignConnector.Template by using change object activity.
Then create an object of DocusignConnector.TemplateRoles and call a sub microflow where you will set the recipients of the DocuSign envelope. For this call a microflow, “SUB_TemplateRole_AddRecipients” is available in the DocuSign connector module.
- Go to “SUB_TemplateRole_AddRecipients”, and based on your use case, set the recipients in this microflow.
Eg- In my case, I want to keep the recipient as a currently logged-in user. Recipients can be of two types — as a signer who will be signing the document and carbon-copies who will be in cc of the email.
Retrieve logged in user, and create a recipient as a Signer with the logged-in user name and email as shown below -
Microflow will look like below :
- Go back to microflow “ACT_Template_Use” and at last call, a microflow “DocusignConnector.ACO_Document” to upload a document to DocuSign.
Hence, the ACT_Template_Use microflow will look like the below-
Step 4: Run the application and test the flow.
On click of REVIEW DOCUMENT, the document will be opened in the DocuSign portal. The user can sign the document and hence the flow is completed.
That’s it, you’re done.
Please reach out if you have any queries😊, I’ll see you in the next article.
Read more
From the Publisher -
If you enjoyed this article you can find more like it on our Medium page. For great videos and live sessions, you can go to MxLive or our community Youtube page.
For the makers looking to get started, you can sign up for a free account, and get instant access to learning with our Academy.
Interested in getting more involved with our community? Join us in our Slack community channel.
