From the Trenches: Who’s locking my envelopes?
A great way to elevate your integration as a developer is by implementing the EnvelopeViews: createSender API call for embedded sending. Proceed with caution, however, as this view can allow for some unexpected behavior regarding envelope access. In this article I will be covering a common problem regarding envelope locks.
What is an envelope lock?
One of the most troublesome issues that can arise within a development cycle is handling merge conflicts and manipulating version control. This issue can arise within DocuSign if two or more users attempt to make changes to the same envelope or template. To help avoid this, you can create an envelope lock using the eSignature REST API. With this lock, all other requests to modify the envelope will be met with an error message.
For more information to help understand the purpose of envelope locks, check Inbar Gazit’s blog post about Common API Tasks: Locking and unlocking envelopes.
Why did DocuSign lock my envelope?
Developers will often stumble upon this error while navigating EnvelopeViews:
{"errorCode" : "EDIT_LOCK_NOT_LOCK_OWNER
", "message" : "The user is not the owner of the lock. The envelope is locked by another user or in another application
."}
At seeing this error, you may well wonder, “Who is this ‘another user’ and why are they holding my envelope hostage?”
The cause of this error is due to an envelope lock. If a user is making changes to an envelope, but leaves the sender view without saving the changes, then DocuSign will add a lock to the envelope to avoid conflicts. This can be frustrating, as this lock does not expire for 900 seconds. Luckily, there is a solution: by appending a lockToken parameter to the view URL, you can give your integration control over the envelope lock, enabling it to make changes to the envelope without having to wait for the DocuSign token to expire.
How can I add a lock token to my sender view?
A lock token can be created with a simple POST request:
base_uri/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/lock
The API response to this call includes the lockToken parameter, which you then use in subsequent API calls. Using the lockToken parameter with the envelope view, however, is not as intuitive. Similar to how you can customize your sender view, you can add a lock token to your envelope by appending a query string to the URL:
&lockToken={lockToken}
With the added lockToken, the URL sent back from a successful senderView request would resemble the following:
https://demo.docusign.net/Member/StartInSession.aspx?StartConsole=1&t=f514d53e-xxxx-b087-ba933cd11d1c&DocuEnvelope=766e59ff-xxxx-xxxx-xxxx-b7729bbe7e7e&send=1/&lockToken=NTExNj…
Conclusion
At first glance, an envelope lock may appear to cause more roadblocks than beneficial uses, but once your integrations begin to utilize them efficiently, they will save your team hours of heartache!
Additional resources
