From the Trenches: Managing long-running createEnvelope calls

•

Summary•4 min read

Discover how to track and optimize your long-running calls.

The Docusign TimeTrack header
How do I speed up my create Envelope call?
Additional resources

The Docusign TimeTrack header
How do I speed up my create Envelope call?
Additional resources

Creating an envelope is one of the most fundamental and important tasks that our eSignature API is used for. Have you ever wondered how long it takes for a createEnvelope API call to complete? Or why is your createEnvelopecall taking so long? This post will explain how you can track your createEnvelope call times as well as several different factors you can look at to mitigate long createEnvelope calls.

The Docusign TimeTrack header

The TimeTrack header, available both in our SOAP and REST APIs, is a special header that you can include with your request headers that will be returned with the time when your request started processing and the time when your request finished processing.

Here’s an example of how to achieve this using our Node.js SDK:

let dsApiClient = new docusign.ApiClient();
  dsApiClient.addDefaultHeader(
    "X-Docusign-TimeTrack",
    "TimeTrackTest," + new Date().toISOString() // Adding a default original value is necessary, whatever value is entered will be returned in the response
  );
// run your API call. For the purposes of this post, I’m using the createEnvelope function
  envelopesApi.createEnvelope(
    ACCOUNT_ID, // Your account Id
    {
      envelopeDefinition: envelope, // Required envelope definition
    }, // Using the third optional parameter, which is a callback function
    function (err, envelopeSummary, response) {
      if (err || !response) {
        console.log(err);
      }else{
        console.log('The Timetrack header ' + response.headers['x-docusign-timetrack']);
// The header will look like this - 
//TimeTrackTest,2022-11-08T05:18:10.329Z;REST0_Start,2022-11-08T05:18:14.3443056Z;REST0_End,2022-11-08T05:18:18.6408938Z
      }
      
    }
  );
// REST0_Start indicates when your request started processing and REST0_END indicates when it was finished

This function is available in our other SDKs as well, which is discussed in our Trenches post Working with Headers in Docusign SDKs.

How do I speed up my create Envelope call?

Most createEnvelopecalls are processed within 10 seconds. However, it is not unusual for complex envelopes to take 30-60 seconds or longer. Once you have identified that your createEnvelopecall is taking more time than expected, there are a few things you can do to try to mitigate the response time.

Pre-convert all documents to PDF before uploading
Docusign allows users to submit documents in various formats and internally converts them into PDFs. If your envelope has a lot of documents in different formats, then you will see increased processing time as our system parses your documents and converts them into PDFs. You can use a free tool such as Microsoft Print to PDF to convert all your documents into PDFs before supplying them to your createEnvelope call. Using purpose-driven tools for PDF conversion will also give you more control over the final PDF's look and feel.
Fixed tab placement instead of using Anchor tags
Using anchor tagging to place your tabs is great because it allows you to place tabs whenever a predefined string is found. How anchor tagging works is that Docusign scans all your documents (or the specified document, based on your data population scope) for instances of the anchor string and places the specified tab. If you have a lot of anchor strings, your documents would need to be scanned many times and as a result, this would lead to an increase in the time it takes for your createEnvelope call to process. An easy way around this would be to use fixed positioning to specify the position of the tab directly and skip the anchor string altogether.
Reference server templates
If you have multiple documents in your envelope and you are reusing some of them frequently, you can use the composite template model and save those documents as templates and reference them in the composite template. This will save you some time as the document would already be processed (converted to PDF, some tabs preplaced, etc.) and will be ready to use simply by referencing its template ID.
Increase the timeout window of your ApiClient object
The ApiClient object that allows you to make requests to our different APIs comes with a predefined timeout. When the timeout is exceeded, the ApiClient automatically closes the connection and errors out giving a "Connection closed" error. If your API call is taking longer than the initial timeout, you can extend it, giving Docusign more time to process and respond to your API call. I am attaching a code snippet below showing how to accomplish this in our Node.js SDK:
```
  const docusign = require("docusign-esign");
  let dsApiClient = new docusign.ApiClient();
  dsApiClient.timeout = 100000; // the timeout parameter controls the default timeout for requests
```

We recommend testing these solutions on your demo account to get a feel for what would work best for your application. If you find that none of these work for you and you are looking for a way to create an envelope asynchronously, stay tuned for a future article currently in the works which will demonstrate how to create envelopes asynchronously without having your application wait for a response.

Additional resources

Karan KaushikDeveloper Support Engineer

Karan Kaushik began his Docusign career in January 2022. As a front-line developer support engineer, Karan enjoys working on complex technical problems. He is passionate about using technology to make people's day-to-day lives easier and simpler, leveraging his array of experience across information technology, cloud operations, and software development.