It has been a while since I did any K2 related write up, so here goes the first one after unintentional hiatus. In this blog post I would like to cover a topic of configuring DocuSign integration in K2 5.4 (the latest on-premises version of the K2 platform). This integration is available in K2 for quite some time now, starting from version 4.6.10, and back then it was necessary to use individual feature forms to configure it, searching them in Designer categories, as complete Management UI has not been available until initial K2 Five release. By now DocuSign integration is well documented and used quite widely by K2 clients, so we can consider it to be a battletested feature. Let’s have a look at how we can configure and use it in K2.
In line with the standard K2 integration capabilities integration with DocuSign implemented through the SmartObjects layer and involves creation of corresponding Service Instance. Main difference here being new and shiny branded Features section of the K2 Management used for configuring good old service instance in a more specialized and focused way providing richer and less generalized UI than standard service instance management. It is safe to assume that this is something that will be a standard for any new K2 brokers/integration options in the future. Beyond more branded and customized user experience per every feature, terminology wise it is much easier for the consumers, and especially those new to K2, to think about different integration options in terms of features, bypassing K2 specific low-level service instance concept. Once you configure DocuSign service instance through adding a feature instance you will be able to use DocuSign SmartObjects and workflow wizards.
Let’s go through DocuSign integration configuration steps together, covering all the configuration tasks involved into this process. First of all, we will need to have DocuSign account. For testing purposes we can create so called Developer Sandbox account on the DocuSign Product Shot page. Once we navigate to https://go.docusign.com/sandbox/productshot/ we will be presented with a form to fill in:
DocuSign Product Shot Page Get Started Form
After filling in the Get Started form you will receive activation email with a link which will take you to another form allowing you to set up your password along with security question and finalize creation of the account:
DocuSign Account Activation Form
Once created, the first account becomes a DocuSign administrator and using this account you will be able to add more users later on. With admin account in place, we need to create DocuSign permission profile for K2. Our next step is creating and assigning security profile with minimum permissions to a user account which we will be using for K2 integration. As I just mentioned, account which we just created has a full DocuSign permissions (DS Admin permission profile) and those cannot be revoked or reduced when we only have one primary user. So, to be able to assign lower level permissions we will also need to add a one more user to which we assign K2 permission profile and use this user’s account for K2 integration. Adding user is a straightforward process which you can initiate by clicking on Add User button from Settings section of the DocuSign eSignature admin page.
DocuSign Admin Site – Adding New User
Once you click on Add User you will need to specify yet another email address and complete an activation as we did with the first account.
DocuSign Admin Site – Add User Wizard
Once additional user was added we can proceed to creation of K2 permission profile. To do this we open https://admindemo.docusign.com/ page and navigate to Settings > Permissions profiles as shown below:
DocuSign Admin Site – Add Permission Profile
On the Permission Profiles page, we just click Add Permission Profile button, type in permission profile name (e.g. “K2 Permission Profile) and grant the following permissions:
- Allow sequential signing
- Allow view and manage envelope rights through API
- Allow send on behalf of other users through API
That translates into ticking three checkboxes as shown below and clicking on Add button.
Add Permission Profile – Permissions Required for K2 Integration
With K2 permission profile created, we need to edit a DocuSign user account which we created earlier and assign a newly created permission profile to it (remember you can only assign this policy to additional user, not to the first user/primary administrator). If permissions profile has been created before you added this user, then it can be also assigned at the user creation stage. To assign K2 security profile to existing user from the same Settings section of admin page we need to click on the Users link under Users and Groups again and then select Edit option from user’s context menu:
DocuSign Admin Site – Edit User
Once User Profile page is opened, you can select K2 Permission Profile from Permission Profile drop-down and click on Save button on the bottom of this page.
DocuSign Admin Site – Assigning Permission Profile to the User
Now, having a user account with the proper permission profile assigned we can switch over to K2 Management and register an instance of the DocuSign feature. To initiate this process, we need to navigate to K2 Management > Features, select DocuSign under Features list and click on New Instance button as shown below:
K2 Management – Adding DocuSign Feature
That will open Add Feature Instance dialog:
K2 Management – Add Feature Instance Dialog
In this dialog we will need to fill in the following fields:
- REST API URL – in case of Developer Sandbox account it should be https://demo.docusign.net, otherwise, you can grab this value in the Settings > INTEGRATIONS > API and Keys section of DocuSign admin site
- Account ID – here we need to paste API Account ID which can be found in DocuSign Admin > Integrations > API and Keys > API Account ID (see screenshot below)
DocuSign Admin Site – API & Keys – API Account ID
IMPORTANT WARNING: This Account ID field has no validation at all allowing you to type in any random text without warning or errors. If you use a wrong value there your DocuSign service instance will be registered but you will see empty dropdowns in DocuSign wizards (e.g. required Recipient Type dropdown of Add Recipient workflow step will contain no values) and your DocuSign integration SmartObjects won’t work returning “Object reference not set to an instance of an object” error.
- Username – here we specify API Username of limited access user with K2 Permission Profile assigned (from DocuSign Admin > Users > User Properties > API Username)
- Password: password you configured for dedicated K2 user account which has K2 Permission Profile assigned
It is recommended to keep default selection for the Use the K2 Integrator Key option, otherwise you will need to provide your own DocuSign Integrator Key valid for your DocuSign tenancies. The Integrator Key being used by DocuSign to verify that code running against a production tenant has been validated by them. As K2 has obtained this verification already it has an Integrator Key incorporated into K2’s code so that you can use it without typing in anything and this is the key that will be used if you select the Use the K2 Integrator Key option.
Once we filled in all required fields we just click on OK button and it kicks off instance creation process which will create DocuSign Service Instance, SmartObjects and SmartWizards. Once it completes just click on Done button in Add Feature Instance window:
K2 Management – Add Feature Instance Dialog Completion
Once instance creation process completed, we can see newly created instance under Feature Instances when DocuSign feature is selected (and we can also see instances count value):
K2 Management – DocuSign Feature Instance Added
We can also see this newly created Service Instance through the conventional Service Instances management UI:
K2 Management – Service Instances – DocuSign Service Instance
And SmartObjects based off this instance can be found in K2 Management Under DocuSign category as shown below:
K2 Management – DocuSign SmartObjects
It is important to note that although DocuSign service instance is visible and can be created though all K2 UIs allowing you to work with service instances (Management > Service Instances, Tester Tool) you should always use K2 Management Features UI to register the necessary Service Instances and other resources to enable K2-DocuSign integration, as only this option adds DocuSign wizard category in the relevant workflow design tools.
K2 Workflow Toolbox with DocuSign Steps Group Available after Registering DocuSign Service Instance
With this in place we can move on to actual use or testing of this integration, for example going through “How To: Create Embedded Signatures with DocuSign” or “How To: Create a Workflow with DocuSign Events” examples on K2 help site or look at DocuSign and K2 Integration K2 KB article which lists numerous resources on the topic to dive in into it.
I hope this walkthrough was informative and useful and in case you have any further questions around this topic feel free to leave them in the comments section below.
