Update as of December 21nd, 2023: DocuSign has suspended all extensions in general, and set the new deadline for September 2024. Services created after November 21st, 2023, automatically utilize the new authentication method.
Update as of August 9th, 2023: The extension has been extended until December 31st, 2023. DocuSign emphasizes that no further exceptions will be made beyond this date. Documentation from their side regarding this has not been updated as of now, but they have confirmed that it will be published this month.
Original as of July 10th, 2023:
DocuSign has announced the retirement of basic authentication (read more), with the official cut-off date set for August 31st, 2023. If you are currently using DocumentsCorePack in conjunction with DocuSign, it is crucial that you take action to ensure the continued functionality of this integration before that date.
DocuSign will provide us with an extension option that will be available until mid to end 2024, and we intend to utilize this extension after that date. However, it is important to note that currently, we are unable to submit a request for an extension before August.
What does this mean for you?
As a result, it will be necessary for you to update DocumentsCorePack, as well as perform additional steps for DocuSign integration and configuration changes.
You will have to perform the following steps for a seamless transition. The first two steps serve as preparation and can be performed at any time, whereas step three initiates the actual activation process, triggering the switch.
Summary of the required steps:
- Step 1: Solution Update
Update the DocumentsCorePackServerDocuSign Solution to Version 6.2 or higher if you are using the solution to save signed documents back to CRM (“pushback”). - Step 2: Giving Consent
Provide User-based or Administrative Consent for DocuSign. You may require assistance from the current DocuSign Administrator within your organization. - Step 3: Activate new authentication
Set a Settingskey to activate the new authentication method, followed by a service restart. It is important to note that no changes will occur until this step is completed, as it acts as the actual “go-live” switch. - Step 4: (Optional) Cleanup
(Optional) Remove deprecated Settingskeys and update or optimize any existing custom workflows.
The first two steps do not actively change the authentication method and so do not have a major impact.
Only step three is the actual “activation” step. This step enables the new authentication method for DocumentsCorePack combined with DocuSign. It is important to note that in case of any issues after the activation, you can always revert by undoing step three.
To follow the steps, specific rights and roles are required for different systems involved:
- DocuSign Administrator: A user who has the authority to log in to the DocuSign Administrator Page.
- DocumentsCorePack Service Admin: A user who can access the DocumentsCorePack service on the website www.mscrm-addons.com. (If you have received an email from support@mscrm-addons.com redirecting you to this blog, it means you are a DocumentsCorePack Service Admin.)
- Dynamics 365 User or Administrator: A user or administrator with the necessary access permissions for certain entities in Dynamics 365 that are related to DocumentsCorePack and DocuSign.
We strongly recommend coordinating with the other administrators to ensure effective communication and coordination regarding the necessary steps for updating.
Required Versions (online only):
DocumentsCorePack Service Version 2020.142 or higher (with Solutions Versions AutoMergeServer Core 2020.142 and AutoMerge GlobalButton 2020.231 or higher) is required to use the new authentication method. DocumentsCorePack DocuSign Solution with Version 6.2 is only optional dependent on your current setup.
1. Solution Upgrades
The solution upgrade covers the upgrade of our standard solutions through the DocumentsCorePack Service web configuration. Additionally, it includes the manual update of the DocumentsCorePack DocuSign Solution. The update of the DocumentsCorePack DocuSign Solution is specifically responsible for updating the functionality of “pushbacks”. The installation of this solution was an additional optional step that was described here.
The process of determining whether the DocumentsCorePack DocuSign Solution has been set up in the past is described in the relevant paragraph below.
Please note: The Integration of DocumentsCorePack is built upon the standard DocuSign Integration. Therefore, we highly recommend updating to the latest available version of their solution. As of now this would be DocuSign for Dynamics CRM Online 7.1.3 that you can find here.
1.1 DocumentsCorePack Solution Update
While this step is secondary for DocuSign used in Workflows or with PowerAutomate, it is required to have the best user experience in the DocumentsCorePack Dialog.
This step requires the presence of a DocumentsCorePack Service Admin who should already be familiar with updating solutions to take advantage of the latest features and bug fixes in the dialog. The duration of the import process can vary, typically ranging from 30 to 60 minutes.
Here you can find a detailed description on how to update the solutions.
1.2 DocumentsCorePack DocuSign Solution
For this step, you will need an online Dynamics 365 user or admin who has the ability to install or update solutions and can access the DocumentsCorePack Settingskey table. The estimated time for completing this step is approximately 5 to 10 minutes.
The solution update is specifically required if you need to save your signed documents, which are generated with DocumentsCorePack, back into CRM, and only if the configuration is already established in your system. The following instructions will assist you in verifying if this configuration is in place. If it is determined that the configuration is not present, you can safely skip this step and proceed with the next one.
To determine if an update is necessary, you can check for the existence of a previous solution along with the Settingskey “DocuSignWorkflow” for the mscrm-addons product “Automerge“. If the solution exists but the setting does not, it indicates that you may not require this solution, and you can consider uninstalling it.
To verify the existence of this key, please refer to the detailed steps provided in the documentation here.
If the key exists, the next step is to check the version of the DocumentsCorePack DocuSign Solution in your system. Instructions on how to locate the solution and check the version number can be found in the provided documentation here:
Since you need to have version 6.2 or higher installed, please download the latest version from the provided location. Once downloaded, follow the update instructions outlined in the documentation to perform the update:
When performing the import, please ensure that the following options are selected: “Upgrade (recommended),” “Maintain customizations (recommended),” and “Enable any SDK message processing steps included in the solution.” These options help ensure a smooth and successful import process while preserving any customizations that have been made.
2. Giving Consent
The new DocuSign Integration requires you to grant consent for our integration. There are two options to give consent for our application.
The first option is admin consent, which grants access to all DocuSign users with email addresses from a specific domain (e.g., “contoso.com”). The second option is user consent, where each individual user needs to individually allow our application access.
Our recommendation would be to opt for admin consent. This step allows the DocuSign Administrator to grant access to all DocuSign users at once, simplifying the process.
Before proceeding with either of these two methods, it is important to determine whether the service you want to update is linked to a sandbox or a production system of DocuSign. This can be determined by assessing the Dynamics 365 organization and the DocuSign Admin page of that system.
Instructions on how to access the DocuSign admin page can be found in the provided documentation here.
If the environment is labeled as “Demo” it indicates that you are in a sandbox system.
If you do not provide consent before activating the new authentication, users will encounter an error message requesting them to provide user consent.
Both user or admin consent also can be revoked in the DocuSign settings. Details can be found in this documentation.
2.1 Admin Consent
For this step, the involvement of a DocuSign Administrator is necessary, and you may need to collaborate with your network administrator. As this step falls outside the scope of DCP and Dynamics, it is not possible to provide a specific time estimate.
To provide admin consent, you first need to claim your domain. If you have already claimed your domain because you use it for other applications as well, you can proceed by following the actual authentication links provided below. To check the domains you have currently claimed, navigate to the DocuSign Admin Portal and go to Access Management > Domains. Here, you will be able to view the list of domains that you have claimed within DocuSign.
If you have not claimed a domain yet you can find a description in this documentation.
Once you have successfully claimed your domain, you can proceed by following one of the links provided below. Here, the previous information about if the linked DocuSign system is a sandbox or a production system is needed.
When you follow the required link, you will be prompted to log in to your account. Please note that Demo and Sandbox environments may have different login credentials. After logging in, you need to select the organization for which you wish to grant consent. Finally, you will be asked to allow access to specific information. In this case, we only require access to the email address of the user.
If the process is successful, you will be redirected to our homepage where you will see the following landing page, indicating that the admin consent configuration has been completed.
Again, it is important to note that before you actually enable the new authentication method, providing consent will not have any effect an the existing system.
2.2 User Consent
For this step, the DocuSign users need to log in to their DocuSign accounts and individually grant their consent.
Similarly to the admin consent process, it is also important to determine whether the system is linked to a Sandbox or Demo environment for user consent. One of the more complex aspects of this task is identifying the affected users and devising a plan to inform them prior to the update. Users that use or utilize DocuSign and DocumentsCorePack in workflows in Dynamics or with flows in Power Automate need to be addressed.
One approach is to reach out to users based on the list and request them to provide consent before enabling the new authentication method. This ensures that users are aware of the upcoming changes and have the opportunity to provide their consent in advance.
If a user does not provide consent before activating the new authentication, they will encounter an error message requesting them to provide user consent.
To access the list of DocuSign users in Dynamics, please refer to the following location: Access the DocuSign User Table. This will allow you to identify the users who need to be notified and provided with the necessary instructions regarding the user consent process. Alternatively, you can estimate the number of users who will be affected by the update and assess whether a priority notification is required based on the urgency and impact of the changes.
The users will need to follow the provided link to provide their consent, depending on whether the system is a sandbox or live environment. The link will direct users to the appropriate consent process.
When you follow the provided link, you will be prompted to log in to your account. Please note that Demo and Sandbox environments may have different login credentials. After successfully logging in, you will be asked to grant access to specific information. In this case, we only require access to the user’s email address.
If the process is successful, you will be redirected to our homepage where you will see the following landing page, indicating that the user consent process has been completed.
3. Activate the new Authentication Method
To activate the new authentication method, you will need an online Dynamics 365 user or admin who can create or update records of the entity “mscrm-addons.com SettingsKey.” Additionally, a DocumentsCorePack Service Admin is required to start and stop the service. Ideally, the user performing this step fulfills both roles.
The estimated time for this step is approximately 5 minutes if you have all the required credentials readily available, have previously used our service configuration, and are familiar with Dynamics 365.
To begin, start by stopping the service. This ensures that any manually triggered processes or automation workflows or flows do not unintentionally use the “wrong” authentication method. Rest assured that any triggered options will not be lost during this period, as they will be processed after the service is restarted.
Next, set the Settingskey in Dynamics as described in the article titled “How to Add a Settingskey“.
The following are the required values to set for the Settingskey:
Name | Value | Product |
---|---|---|
DocuSignV2 | true | Automerge |
Please ensure that you set these values accurately according to the provided guidelines and requirements.
Once you have set the key, you can restart the service. Instructions on where to find the start and stop controls for the service can be found in the provided documentation here: Service Configuration options.
That concludes the process of enabling the new authentication method for DocuSign with DocumentsCorePack. Congratulations!
Fallback Option: In the event of any issues, you always have the option to stop the service, remove the Settingskey, and then restart the service. This will revert the authentication method back to its previous state, providing a fallback solution if needed.
4. (Optional) Cleanup and Other Details
This section, along with subsequent subsections (4.1, 4.2, etc.), includes optional additional steps and details that are not mandatory for the overall process, but are worth mentioning.
If you are utilizing DocuSign within your own workflows, you have the option to improve existing workflows by optimizing them. Additionally, if you have modified our predefined workflows, you can consider migrating them to actions.
Please note that this step is only recommended once the transition to the new authentication method has been successfully implemented and has been running smoothly for an extended period of time.
If you come across any workflows that might be affected and are unsure about the potential effects, we encourage you to reach out to our support team at support@mscrm-addons.com. When contacting support, kindly provide any relevant screenshots or documentation related to the workflows to ensure our team has sufficient details to assist you effectively.
To finalize the optimization process, it is crucial to delete the “DocuSignWorkflow” Settingskey. This Settingskey retains the classic functionality for each of the optimization steps mentioned below. Therefore, if you have custom workflows, actions, or if you use workflow steps, it is essential to address all of these elements simultaneously to ensure smooth operation and maximize the benefits of the optimization process.
To find the “DocuSignWorkflow” Settingskey, you can refer to the instructions provided in the documentation How to check the existence… . Once you have located the Settingskey, you can use the standard delete option in Dynamics to remove it.
4.1. (Optional) Updating custom Workflows
Any custom workflow that was created to initiate a signature process with DocumentsCorePack typically consists of three steps. The first step is the “Sign Document” action, which triggers the creation of the AutoMergeWorkingItem. This is followed by a “wait step” that allows for the necessary processing time of the DocumentsCorePack service, particularly when a document is created with the AutoMergeWorkingItem. Subsequently, the third step triggers the workflow “DCPDocuSignWorkflow,” which facilitates the sending of the documents using DocuSign.
An example of an existing workflow could be as follows:
With the new authentication method enabled, these three steps within the workflow can be removed to align with the updated integration. Please review and adjust the workflow accordingly to ensure seamless functionality with the new authentication method.
Details on how to work with workflows in Dynamics can be found in this article provided by Microsoft: Overview of using workflow processes. The article offers comprehensive information and guidance on utilizing workflows effectively within the Dynamics environment.
We recommend that any future workflows adhere to this standardized structure once they are created. Additionally, we will update existing documentation to incorporate the new descriptions, ensuring consistency throughout all workflow materials.
4.2. (Optional) Update Customizations of “DCPDocuSignAction_default” or “DCPDocuSignAction_[entityname]”
If you have made modifications to our default “DCPDocuSignAction_default” Action, we recommend migrating those changes to our new “DCPDocuSignCreate_default” actions.
We previously handled the main process for sending documents with DocuSign through the “DCPDocuSignAction_” workflow. We have recommended making custom changes to this workflow, such as modifying the DocuSign email subject or message.
With the new implementation of DocuSign, we have introduced a smaller action called “DCPDocuSignCreate_default” to replace the previous “DCPDocuSignAction_”. As a result, the “DCPDocuSignAction_” will no longer be utilized, requiring the migration of your customizations to the new “DCPDocuSignCreate_default” action. This ensures that your custom changes are effectively implemented and compatible with the updated integration.
To address specific actions for specific entities, please perform the following steps:
Create a new action with the name “DCPDocuSignCreate_[entityname],” where “entityname” represents the schemaname of the entity. Ensure that the new action includes the same arguments and steps as the current default action. Next, migrate any customizations you have made from your “DCPDocuSignAction_[entityname]” to the newly created action. Once the migration is complete, activate the action to make it operational.
4.3 (Optional) Deprecations
We are now deprecating the workflow steps DCPDocuSignWorkflow and DCPDocuSignWorkflowGuarded, and there is a possibility of their removal in a future version.
We are also deprecating the following workflow steps of the DCPDocuSign solution (DocumentsCorePackServerCoreDocuSign)::
Name | Function | Alternative |
---|---|---|
GetSignLinks | Creates links for signing | The sign links are created by DocumentsCorePack service when the In-Person option is set in the dialog, or in the SignXML <InPerson>true<InPerson/> |
GetDocuments | Gets the document with filename not the name of the envelope subject | Use the default DocuSign feature of the Dynamics CRM integration |
GetFieldValue | Gets the field value | Use the GetFieldValue step of DocuSign Note: Radiobutton values are not working |
StartDocuSignAction | Start action | Not available and not required |
StartWorkflowAsync | Start workflow async | Not available and not required |
UpdateEnvelope | Updates the envelope with data from the document | Not available and not required |
Please be aware of these deprecations and ensure that you update your workflows accordingly to prevent any potential disruptions in functionality in future versions of the solution.
To check the usage of these elements (such as “GetSignLinks,” “GetFieldValue,” or “UpdateEnvelope”), you can utilize the out-of-the-box dependency checker tool provided by Dynamics. This tool allows you to identify and analyze the dependencies of various components within your Dynamics environment, helping you determine if any of these elements are in use and their impact on the system.
That’s all about DocuSign retiring basic authentication. We appreciate your feedback! Please share your thoughts by sending an email to support@mscrm-addons.com.