Switching to OAuth Individual Consent for DocuSign Legacy Integrations

This article is for users who are currently using DocuSign with Nintex DocGen and want to switch their current DocuSign Legacy authentication method to the OAuth - Individual Consent option.

Why do I need to do this?

DocuSign is deprecating its basic authentication methods: Legacy Authentication and Send-On-Behalf-Of (SOBO). These authentication methods are available for our "DocuSign (Legacy)" integration, an integration that relies on DocuSign for Salesforce (DocuSign's legacy Salesforce app). In order to continue to this DocuSign (Legacy) integration in Nintex DocGen you will need to switch to one of the following integration methods: OAuth - Admin Consent, or OAuth - Individual Consent.

Who does this apply to?

• Users with the DocuSign Legacy app integration

• Users using one of the following two integration methods

  • Legacy Authentication

  • Send-On-Behalf-Of

The following how-to video provides step-by-step guidance on switching to OAuth - Individual Consent.

See the following table for more information on the currently available authorization methods.

Switch from basic DocuSign authentication to OAuth - Individual Consent option

After DocuSign deprecates their basic authentication options, you will need to choose one of the new authentication methods. In the event that you do not want to switch to OAuth - Admin Consent, or you would like individual users to authenticate using their DocuSign credentials, you can use switch to the OAuth - Individual Consent option. However, before switching to OAuth - Individual Consent, it is important to understand how Individual Consent works, and that the user experience may differ from how they were previously using the DocuSign delivery option in Nintex DocGen.

How will the user experience change when using OAuth - Individual Consent as an authorization method?

By using OAuth - Individual Consent as the authorization method, each user who needs to send out generated documents using the DocuSign delivery option will need to make a one-time authorization that is limited to that users account. For delivery options using DocuSign, the user will see an Authorize and Send to DocuSign button.

When generating a document while using the DocuSign delivery option, you will see the following pop-up asking you to authorizing Nintex DocGen to work with DocuSign for your account.

"File-test.pdf" is a placeholder file name and not the file name you will see.

When on a Salesforce record, such as an Opportunity, that has a Document Package set for a DocuSign delivery option, before generating the document you will see the following:

The Authorize and Send to DocuSign button acts as a one-time authorization for that user's DocuSign account to send out Document Packages for the DocuSign delivery option. That means each user who needs to use the DocuSign delivery option will need to have access to a DocuSign account that is used to authorize that transaction. After clicking the button you will be prompted to log into a DocuSign account, and allow Nintex DocGen access to DocuSign for authorization to complete the transaction.

Click Allow Access to continue generating the document.

1. Upgrade your Nintex DocGen package to 20.5.0 or above

In order for the OAuth - Individual Consent option to be available for use as an authentication method, you need to upgrade to the latest Nintex DocGen package release. It is always recommended to first upgrade a sandbox environment first before upgrading your production or live environment.

If you are on an older version of Nintex DocGen (version earlier than 18.10) you will need to perform a two-step upgrade in order to get to version 20.5 or higher. If you do not need to update to 18.10, then you can update to version 20.5 using the AppExchange

1. First direct download version 18.10 using one of the following links depending on what type of environment you are trying to upgrade:

   1. If you are updating a Sandbox environment download version 18.10 from here: https://test.salesforce.com/?retURL=%2Fpackaging%2FinstallPackage.apexp%3Fp0%3D04t2E000003kYjxQAE

   2. If you are updating a Production environment download version 18.10 from here: https://login.salesforce.com/?retURL=%2Fpackaging%2FinstallPackage.apexp%3Fp0%3D04t2E000003kYjxQAE

2. After updating to version 18.10 you can upgrade Nintex DocGen as usual using the AppExchange here: https://appexchange.salesforce.com/appxListingDetail?listingId=a0N300000016Zn3EAE

2. Ensure that users who need to send out Document Packages using the DocuSign delivery option have a DocuSign account

In order to use OAuth - Individual Consent as an authentication method, each user who needs to send out a generated document using the DocuSign delivery option has a DocuSign account they can use to authorize the send.

3. Switch your integration option to OAuth - Individual Consent in Nintex Admin

After you have performed the upgrade to Nintex DocGen version 20.5.0, you can set up OAuth - Individual Consent from the Integrations menu inside of Nintex Admin. Note that once you switch your integration method over to Individual Consent, any user who needs to send out a Document Package using the DocuSign delivery option will need to authorize their account. For more information on how individual users can authorize their DocuSign account, refer to 4. Authorize individual users.

Important: After performing the upgrade to Nintex DocGen your previous DocuSign integration will now be called "DocuSign (Legacy)". This is the integration option you will be changing.

Important: The steps outlined below will need to be performed for any environment you need this to work in, such as a production, sandbox, or demo environment.

Important: Be aware that once you switch to OAuth - Individual Consent any service account being used for automation or use of the autosend feature will cease to function until those accounts are authorized. These accounts can be authorized in a similar way to how individual user's accounts are authorized.

Switch to OAuth authentication

1. Log into Salesforce using a Salesforce account that has administrative privileges.

2. If necessary open Nintex DocGen from the Apps Launcher.

3. Select the Nintex Admin tab.
4. Under Configuration, select Integrations.

5. Locate the Service Name that is called "DocuSign (Legacy)" and click Edit.

   

6. In the Authentication to Use drop-down select, OAuth - Individual Consent.

   

7. Click Save.

8. After clicking Save you are going to be prompted to authorize the integration using a DocuSign account. Note that this only authorizes the user who is currently setting up the integration, and not other users needing to send out generated documents using the DocuSign delivery option. These users will be prompted to authorize their own DocuSign account the first time they go to send.

9. Your DocuSign delivery options will continue to function as before.

4. Authorize individual users for use with Individual Consent

After OAuth - Individual Consent has been authorized in Nintex Admin, and the integration has saved successfully, users will now need to authorize their own accounts for use with the DocuSign delivery option.

Important: The DocuSign account that the user is going to use to authenticate their delivery option must have the same account ID number in the DocuSign Username field in Salesforce. Refer to Step 3 before having a user authorize their DocuSign delivery option.

There are two ways users can authorize their accounts:

• On the integration page, admins are provided with an authorization URL that they can share with each user who needs to use the DocuSign delivery option. By clicking this URL users will be prompted to authorize their DocuSign account. Once they have been authorized users can use the DocuSign delivery option as normal.

or

• After logging into Salesforce, users can generate a document with a new or existing Document Package using the DocuSign delivery option, they will be prompted to click the Authorize and Send button. When clicking this button the user currently logged in will be prompted with an DocuSign authorization screen they can use to log into DocuSign and authorize their account. Once they have been authorized users can use the DocuSign delivery option as normal.

5. Re-authorize Nintex DocGen through Nintex Admin

After you have performed all of the previous steps, and set up the desired integration method, you need to re-authorize Nintex DocGen through Nintex Admin.

Re-authorize Nintex DocGen

1. From the Nintex DocGen home screen, click the Nintex Admin tab.

2. In Nintex Admin locate the Authorize Nintex DocGen section.

3. Click Authorize Nintex DocGen.

4. You may see a pop-up window asking for access to certain features. Click Allow.

   

Your DocuSign delivery options will continue to function as before.

OAuth - Individual Consent troubleshooting

An error has occurred. Error while requesting server, received a non successful HTTP code with response Body: {"error":"consent_required"}"

When a user attempts to run a DocuSign delivery option, they may encounter the above error. This error occurs when the DocuSign account the user used to authenticate their DocuSign delivery option does not match the DocuSign ID in the DocuSign Username field in Salesforce. To resolve this issue admins can confirm the DocuSign user ID for the user through the Users list in DocuSign.

How can a user check the DocuSign Username field?

1. From any screen in Salesforce, click your Profile portrait.

2. In the expanded menu, click the Settings link.

3. In the Settings menu, under the My Personal Information section, click Advanced User Details.

4. In the User Detail section click Edit.

5. Locate the DocuSign Username field.

   If the DocuSign Username field does not show up in the Edit screen then the DocuSign Username field can be added to the User Page layout through the Object Manager in Salesforce.

   There are two fields to locate in the Fields and Relationships list:

   • dsfs_DSProSFUsername_c, or

   • dfsle_Username_c

   These two fields contain the User ID related to the Salesforce account the user is currently logged into, and be added to the Page Layout.

   Note: If you are using Chrome, you can also use the "Salesforce Inspector" plugin while on the User Details page to locate the two above fields and view the metadata attached to those fields without needing to add them to the Page Layout.

6. Have an admin of DocuSign confirm the user's DocuSign User ID by checking the user in the Users list in DocuSign. For more information on how to view a user's DocuSign ID refer to the following DocuSign help article: View User Details.

7. If the IDs match, then no further action is required. If the field is empty, or the ID does not match, then update the DocuSign Username field with the correct ID from DocuSign.