DocuSign

The DocuSign Service Type is used to allow K2 to integrate with DocuSign.

K2 can integrate with DocuSign through SmartObjects and workflow wizards. To enable integration between K2 and DocuSign, the DocuSign Feature must be activated by registering an Instance of the feature with the DocuSign Feature Activation page. Once complete, SmartObjects are created for the DocuSign Service Instance, and workflow wizards are activated within the web-based K2 workflow design tools. The underlying Service Type integrates with the DocuSign service, enabling you to design K2 workflows that manage document signing steps or build SmartForms that utilize the SmartObjects to interact with DocuSign.

Theoretical and functional knowledge of DocuSign is required to use the DocuSign integration provided by K2. You may learn more about DocuSign from the DocuSign website at https://www.docusign.com/. The documentation below assumes you are familiar with DocuSign as well as K2 SmartObjects.
The screenshots and instructions for third-party software are accurate at the time of writing. Third-party vendors may have changed or updated aspects of their systems (such as user interfaces, functionality, and security). As a result, this content may be outdated.

Prerequisites

The following prerequisites apply for K2-DocuSign integration

  1. DocuSign Enterprise Version. K2 integration requires the DocuSign API and a DocuSign Integrator Key. (When moving from development to production, K2 required all customers to obtain and register their integrator Key as part of the DocuSign broker service instance configuration. Previously this certification process was not necessary as K2 provided the option to use a K2 integrator Key. Docusign no longer supports the K2 integrator key and customers need to create their own key. This change has been applied in K2 5.5 March 2022 Cumulative Fix Pack 9 together with the OAuth option.
    • If you are using a different version of DocuSign, please contact DocuSign to determine whether you can use the API and obtain an Integrator Key in your version of DocuSign.)
  2. DocuSign Developer Account. This account must be created prior to integrating K2 with DocuSign, and the Developer Account must be obtained from DocuSign – it is not provided by K2. See the following link for more information on obtaining a developer account: https://www.docusign.com/developer-center

  3. The following information will be required for using K2-Docusign integration

    • Account ID
    • API Account ID
    • Account base URL
    • Authorization base URL
    • Client ID
    • Integration Key
    • RSA Private Key
    • REST API URL
    • Scope
    • User ID

    See Docusign Apps and Keys for more information.

Required permissions

DocuSign integration with K2 requires the following permissions:

  • Allow sequential signing
  • Allow view and manage envelope rights through API
  • Allow send on behalf of other users through API

You can assign these permissions to existing permission profiles in DocuSign, or create a new permission profile in DocuSign, and assign the new permission profile to the relevant users who need to use DocuSign integration through K2.

Follow the steps below to create a permission profile and set permissions.

The screenshots and instructions for third-party software are accurate at the time of writing. Third-party vendors may have changed or updated aspects of their systems (such as user interfaces, functionality, and security). As a result, this content may be outdated.
  1. Log in to your DocuSign Developer Sandbox.
  2. Select the Admin tab.
  3. On the Admin page, click Permission Profiles in the Users and Groups section.
  4. On the Permission Profiles page, click Add Permission Profile.
  5. On the Add Permission Profile page, provide a Name for your permission profile, select Allow view and manage envelope rights through API and Allow send on behalf of other users through API. Click Add.
  6. To add users to the permission profile, click Users under the Users and Groups section.
  7. On the Users page, select the user for the permission profile, click Actions and then Edit.
  8. On the User Profile page, select your permission profile from the Permissions Profile drop-down. Click Save.

Service Authentication

A DocuSign Service Instance can only be configured with the Static Authentication Mode.

Service Keys (Service Instance Configuration Settings)

Key Can be modified Data Type Sample Value Notes
DocuSign URL Yes Text https://demo.docusign.net Address for DocuSign's API. By Default this is set to the demo URL. Production DocuSign instances will most likely require a different URL.
Account ID Yes Text

The DocuSign API Account ID.

This property contains sensitive information. You can enter and see your values when you first configure this value. The value will be masked when the service instance is updated.
Integrator Key Yes Text

DocuSign Active Integrator Key.

This property contains sensitive information. You can enter and see your values when you first configure this value. The value will be masked when the service instance is updated.
Polling Interval Yes Text 15 The Polling Interval is set to 15 minutes by default. This can be changed, however any value that is set below 15 minutes will return cached values instead of real-time values. To return real-time values it is recommended that the value be set higher that 15 minutes.

Service Objects

The DocuSign Service 2 typically exposes the following Service Objects:

SmartObjects

K2 automatically creates SmartObjects for the Service Objects in this service. SmartObjects can be automatically created by selecting the Generate SmartObjects for this Service Instance check box when creating a new Service Instance. Designers can use the SmartObject design tools to build advanced SmartObjects that leverage the Service Objects in this service. It is recommended to use the SmartObject design tools to create SmartObjects rather than generating SmartObjects, since this allows better control over the naming, behavior and design of the SmartObject and its methods and properties.

Important Considerations

  • If the DocuSign Service Instance is registered using the K2 Integrator Key option, DocuSign does not require certification. If you use your own Integrator Key provided by DocuSign when enabling the feature, certification is required. Certification allows for the Sandbox Integrator Key to be used against DocuSign’s Production Service Address. See the DocuSign article which explains this in more detail: https://www.docusign.com/developer-center/go-live/certification
  • It is highly recommended to use the DocuSign Feature Activation page to register the necessary Service Instances and other resources to enable K2-DocuSign integration. If the Service Instance is registered using tooling other than the Features page, the DocuSign wizard category will not be added in the relevant workflow design tools.
  • If building embedded signing solutions using the DocuSign View Service Object, the Client User_ID must be specified (Recipient -> Input -> Client User ID). Embedded signing is an advanced DocuSign function and is not part of the K2 DocuSign Wizards, and must be built using custom SmartObjects and K2 smartforms. See the DocuSign Post Recipient, Post Sender, and Post Edit Help Topics for more.
  • When registering multiple DocuSign Feature Instances with different user credentials, DocuSign Templates will not be available across all service instances (in other words, Service Instance A will be unable to see Service Instances B's templates). To rectify this, Template Sharing is required. To enable Template Sharing in DocuSign, log in to the DocuSign site, click on the Manage tab > My Templates > Actions > Share. In the Template Sharing window, select the appropriate User(s)/Group(s) you want to share templates with, and then click Save
  • The input property added for the load method of the Document SMO is the Escape Non ASCII Filenames which is a Boolean value that can be set to either true or false to ensure file names get encoded correctly. When you set the Escape Non ASCII Filenames to true then non ASCII characters like भारत or Č will be encoded to their respective URL encoded values. When you set the Escape Non ASCII Filenames to false then non ASCII characters like भारत or Č will not be encoded and left as is. If no value is specified for the Escape Non ASCII Filenames parameter its default value is going to be false. This is implemented to ensure systems like SharePoint will be able to upload these files with the non ASCII file name characters without error.
  • After October 4th 2022 , all non OAuth 2.0 authentication flows will be fully deprecated. See OAuth Migration for more information.
  • Known issues:
    • When editing an existing OAuth/Static DocuSign Feature Instance via K2 Management and entering an incorrect UserID, the instance will be updated but will present an error when an execution is attempted to DocuSign which requires the UserID. Error message states:

      Error: SmartObject Server Exception: {"error":"invalid_request"}.
      When attempting to create a new OAuth DocuSign Feature Instance using an incorrect UserID the same error will be presented on the DocuSign Service Broker configuration Step.

    • When you create a new OAuth DocuSign Feature Instance and the OAuth section details (ClientID, UserID, Authentication Service Url, Scope, RSA Private key) are all correct but REST API URL or the AccountID is incorrect, clicking OK will take you to the Feature Instance configuration screen and fail with a validation message stating that the REST API URL or the AccountID are incorrect. When you correct the REST API URL or the AccountID value but you add the incorrect values for OAuth section and click OK, the Feature Instance configuration will succeed as the token for your OAuth DocuSign Feature Instance has already been created. Only when the token expires or is deleted will the validation for OAuth section activate again. When you edit an existing OAuth DocuSign Feature Instance where the token has not expired yet, you will also be able to add the incorrect values into the OAuth section and validation will not appear.