From the Trenches: Go-live failures
Go-live is an exciting point in your development process with DocuSign! After developing and testing your integration using your DocuSign developer account, you're now at the point where you're ready to move into production. We want this process to go as smoothly as possible for you, so let's review a few common issues users may encounter during the go-live process.
Go-live review
The first part of the go-live process is to submit your integration key for go-live review. The go-live review includes a few automated checks on the traffic associated with the submitted integration key to ensure compliance with our API rules.
Note: If you are a DocuSign user looking to use a third-party integration that requires going through the go-live process in order to use it with your production DocuSign account, we would first recommend going through the setup steps within the help documentation provided by the tool developer.
Here are a few common reasons for why your go-live review may fail.
Too few successful API calls
The primary criteria for the go-live review is that your 20 most recent API calls complete without error when using the integration key you want to promote to production. This helps ensure that you've been able to work through any issues when starting with the DocuSign APIs during development, and that your production traffic will generally be error-free. One note is that login and getUserInfo calls, as well as activity from the DocuSign web app, do not count towards the 20 calls.
Want to review your latest API activity? You can find that on the API Dashboard within your developer account.
Polling violation
In addition to making 20 successful calls, one additional criteria for those 20 calls is that they do not violate our polling rules. Polling refers to repeated calls, often in regular intervals, in order to check on the status/state of an item. A polling violation can occur if an API request is sent for the same envelope resource within a 15-minute window.
Even if you are not intentionally polling, the 20 API calls used in your go-live review may inadvertently contain behavior that resembles polling. To pass this automated go-live review check, you’ll need to make sure your last 20 calls don’t contain a set of calls against a single envelope resource within a 15-minute window.
Example: Polling for envelope status
A common use case that users attempt to accomplish with polling is to retrieve the latest status of an envelope to keep their integration up to date with DocuSign:
[12:00:00] GET /accounts/12345/envelopes/AAA
[12:02:00] GET /accounts/12345/envelopes/AAA
[12:04:00] GET /accounts/12345/envelopes/AAA
The above example would cause a polling violation because the calls are repeated every two minutes for the same envelope to return its status. You’ll need to space out these status retrieval requests for a particular envelope to at least 15-minute intervals to comply with the polling rules.
A recommended approach for staying up to date on envelope statuses is to use DocuSign Connect, which will send notifications to a listener that you specify when updates occur. Using DocuSign Connect will enable you to avoid the need for polling for envelope statuses and may reduce the number of API calls that your integration is consuming (which is helpful for staying within the API Limits)
Example: Repeating calls Instead of storing results
Another example I’ve seen is the following calls made back-to-back in order to download the 2 documents in their envelope:
[12:00:00] GET /accounts/12345/envelopes/AAA/documents/
[12:00:01] GET /accounts/12345/envelopes/AAA/documents/1
[12:00:02] GET /accounts/12345/envelopes/AAA/documents/
[12:00:03] GET /accounts/12345/envelopes/AAA/documents/2
In this set of calls, a list of all of the documents on an envelope are retrieved, then the first document is downloaded, then the list of documents is retrieved again, and then the second document is downloaded. The second call to the EnvelopeDocuments endpoint would result in the polling check failing in the automated review even though the intention wasn’t polling. However, you should be able to store the results of the first call to the Documents endpoint, removing the need for the second call to the Envelope Documents endpoint.
Legacy authentication
As announced in our Legacy Authentication deprecation plan, as of Aug 16, 2021, all new REST API applications must use an OAuth 2.0 flow for authentication in order to pass the Go-Live review. DocuSign legacy authentication and OAuth 1.0 will not be accepted for new applications.
Promoting your integration key
Once you’ve passed the go-live review, your integration key is ready for promotion into the production environment. You'll start the promotion process from the Apps & Keys pages within your developer account. Here are a few things to look out for during this stage of the process:
Check your pop-up blocker
Once you start the promotion process and agree to the terms of service, a pop-up window will open for you to sign into an admin user on the production account where you are looking to promote your integration key. Your pop-up blocker may block this login window.
Make sure your production account user and plan are eligible
The production account where you are promoting your integration key cannot be a trial account. Additionally, the DocuSign plan for your production account must support the DocuSign features you’re using; for instance, ID Verification isn’t supported on all plans. Finally, the user on your production account that you are logging into needs to be an admin user on that Production account.
Post go-live
Your key is now in Production! But before the celebrations commence, you’ll want to make sure that your integration is now using the API base URLs for the Production environment, and that you’ve manually migrated anything needed from your developer account, as items like templates, users and settings are not automatically migrated between your developer and production accounts. Our After Go-Live Checklist provides more details on what to check to make sure you’re all set to start using your integration in production.
