Skip to main content
Blog
Home/

From the Trenches: Who’s locking my envelopes?

Author Hunter Wiegand
Hunter WiegandDeveloper Support Engineer
Summary3 min read

A Docusign-applied envelope lock can trip up your app when you leave a sender view in the web UI without saving changes.

    • What is an envelope lock?
    • Why did Docusign lock my envelope?
    • How can I add a lock token to my sender view?
    • Conclusion

    Table of contents

    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

    Author Hunter Wiegand
    Hunter WiegandDeveloper Support Engineer

    Hunter Wiegand joined Docusign’s Developer Support team in 2021 with a focus on assisting customers with API driven issues.

    More posts from this author

    Related posts

    • Trending Topics: Latest from our forums (November 2024)
      Developer Trending Topics
      Author Paige Rossi
      Paige Rossi
    • Leveraging Docusign AI and Salesforce for Improved Contract Management

      Leveraging Docusign AI and Salesforce for Improved Contract Management

      Author Subbarao Pydikondala
      Subbarao Pydikondala
    Trending Topics: Latest from our forums (November 2024)
    Author Paige Rossi
    Paige Rossi
    Leveraging Docusign AI and Salesforce for Improved Contract Management

    Leveraging Docusign AI and Salesforce for Improved Contract Management

    Author Subbarao Pydikondala
    Subbarao Pydikondala

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting