Integrating BMC Helix Innovation Studio with DocuSign

Before you begin

Make sure that you have a DocuSign account.

Workflow

The following image represents the tasks to connect BMC Helix Innovation Studio with DocuSign:

 The following table describes the actions that an administrator must perform to integrate BMC Helix Innovation Studio with DocuSign:

To generate the HMAC key in DocuSign

You must generate the HMAC key in DocuSign and enter the key in BMC Helix Innovation Studio. The HMAC key authenticates DocuSign and BMC Helix Innovation Studio to trust each other and share content.

To generate the HMAC key, perform the following steps:

1. Log in to your DocuSign account.
2. Navigate to the Admin tab, and in the Integrations section, select Connect.
3. On the Connect Configurations page, select Connect Keys, and click Add Secret Key.
   The HMAC key is generated. Copy the key so that you can use it when you integrate BMC Helix Innovation Studio with DocuSign.

To configure OAuth for the API application

1. Log in to your DocuSign account.
2. Navigate to the Settings tab, from the Integrations section, select Apps and Keys.
3. In the Apps and Integration Keys section, click App and Integration Key.
4. Enter a unique name for the application, for example, Innovation Studio.
5. Click Create App.
6. In the Authentication > User Application section, set Is your application able to securely store a client secret? option to Yes.
7. Verify that the Authentication Method for your application is Authorization Code Grant.
8. Click Add Secret Key.
   The secret key is generated.
9. Copy the secret key so that you can use the key to configure BMC Helix Innovation Studio to connect to DocuSign.
10. In the Additional settings > Redirect URIs section, click ADD URI, and enter the URL for BMC Helix Innovation Studio authentication. 
    For example, https://<innovation-suite-host-name>/api/rx/application/oauth/callback
11. Click Save.
    The following image displays an example of the OAuth configuration for the API application:
    

To configure a webhook callback for DocuSign

You must configure a webhook callback and update the DocuSign configuration with the generated callback URL.

1. Log in to BMC Helix Innovation Studio and navigate to the Administration tab.

2. Select Integrations > Webhook callback configuration and provide the following information:

   Field	Description
   Configuration Name	Enter a unique configuration name.
   Bundle name	Select your bundle.
   Processor	Select DocuSign.
   DOCUSIGN_HMAC_KEY	Enter the HMAC key created earlier.

3. Click Save. 
   The Callback URL is automatically generated for your configuration. 
4. Copy the Callback URL.
   
5. Click Close.

To add the webhook callback URL in DocuSign

After you've configured the webhook callback, you must add the webhook callback URL in DocuSign so that the application can connect to BMC Helix Innovation Studio.

1. Log in to your DocuSign account.
2. Navigate to the Admin tab, and from the Integrations section, select Connect.
3. On the Connect Configurations page, select Add Configuration > Custom. 

4. On the Listener Settings section, provide the following details:
   

   Field	Description
   Name	Enter the name for the configuration.
   URL to Publish	Enter the webhook callback URL generated earlier.

5. In the Trigger Events section, click Envelope and Recipients, and select the events when DocuSign should call the webhook; for example, Envelope Signed/Completed.
6. From the Integrations and Security Settings section, select Include HMAC Signature (Recommended).
7. Click Add Configuration. 

To configure BMC Helix Innovation Studio to connect with DocuSign

1. Log in to BMC Helix Innovation Studio and navigate to Administration tab.

1. Select Integrations > OAuth configuration.

2. On the OAuth configuration UI, click New, and enter the values for the following fields:

   Field	Description
   OAuth provider	Enter DocuSign as the service provider for e-signature.
   Client ID	Enter the Client ID copied during OAuth for API application configuration in DocuSign. For example, 9c70bd39-1017-476b-a99e-abd83e91
   Client secret	Enter the client secret copied during OAuth for API application configuration in DocuSign. For example, ada504cd-9c1c-47f7-8939-9d74ca5a8088
   Authorization URL	Enter https://account-d.docusign.com/oauth/auth
   Redirect URL	Enter the Redirect URL that you provided in DocuSign. For example, https://<innovation-suite-host-name>/api/rx/application/oauth/callback
   Grant type	Select Authorization Code.
   Scope	Enter signature.
   Client credentials transfer mechanism	Select Authorization request header. This field determines whether to pass client credentials through the Authorization request header as basic authentication or through form parameters while fetching the tokens by using the access token URL.
   Access token URL	Enter the URL to get the token from the OAuth2 server.  For example, https://account-d.docusign.com/oauth/token
   Refresh token URL	Enter the URL to get the access token from the OAuth2 server. For example, https://account-d.docusign.com/oauth/token
   Description	Enter a description for the configuration.

3. Click Save.
4. To register BMC Helix Innovation Studio with DocuSign, click Register application.

5. To test connectivity between BMC Helix Innovation Studio and DocuSign, select the configuration, and click Test connection.

   Important

   If the connection fails, verify that you have entered the correct values for all the fields.

The application registration details are authenticated, and BMC Helix Innovation Studio is registered with DocuSign. 

To configure the authorized user

1. Log in to BMC Helix Innovation Studio and navigate to Administration tab.

1. Select Integrations > E-sign configuration.

2. On the E-sign configuration UI, click New, and enter the values for the following fields:

   Field	Description
   Provider type	Select DocuSign as the service provider for e-signature.  Important: You cannot have more than one configuration with the same e-signature service provider.
   Authorized user	Enter the user name of the user who is authorized to get the OAuth token from the e-signature service provider. Important: If the user updating this information is the same user who was authorized to get the OAuth token, then you do not need to update this field. The server updates this field with the current user.
   API access URL	Enter the URL used to access APIs related to e-signature. For example, https://demo.docusign.net
   Account ID	Enter the API Account ID of your DocuSign account.  To get the API Account ID from DocuSign, select Settings > Integrations > Apps and Keys > My Account Information. For example, bb57b286-4e8e-4523-9bf7-2ceba79ba

3. Click Save.

After you complete the configurations, the DocuSign and BMC Helix Innovation Studio applications are ready to send and receive documents that are e-signed by using DocuSign.

The application business analyst must create a process in BMC Helix Innovation Studio so that documents in your application are sent to DocuSign for e-signing, and you receive a notification in BMC Helix Innovation Studio to download the e-signed documents.

Where to go from here

Configuring-e-signing-in-your-custom-application