Prefill docusign template fields

Question

Using the Docusign node.js sample I'm able to send a template, however I'm having trouble pre-setting the field values.

I've looked around on stack overflow and found 3 different versions of the setTemplateRoles JSON format. I've tried them all and none worked. When I run this code, the email comes to foo@email.com and my template comes through fine, but the fields are not pre-filled.

Q1. When they say tab what are they talking about? What is a tab?

Q2. Does tabLabel mean Data Label, or are they different things?

Screenshot:

when editing the template in the GUI.

Q3. How can I add a "custom field" to my docusign template? I've tried to do it by clicking Custom Fields, and adding one. But it seems to be more of a field template than a specific custom field. When I run the API call listCustomFields, it comes back empty.

var docusign = require('docusign-esign');

// Note: Following values are class members for readability and easy testing
// TODO: Enter your DocuSign credentials
var UserName = 'foo@email.com';
var Password = 'SECRET1';

// TODO: Enter your Integrator Key (aka API key), created through your developer sandbox preferences
var IntegratorKey = 'SECRET2';

// for production environment update to 'www.docusign.net/restapi'
var BaseUrl = 'https://demo.docusign.net/restapi';

var RequestSignatureFromTemplate = function () {
  // TODO: Enter signer information and template info from a template in your account
  var signerName = 'Bob';
  var signerEmail = 'foo@email.com';
  var subject = "testing 123";
  var templateId = 'XXX';
  var templateRoleName = 'Seller';

  // initialize the api client
  var apiClient = new docusign.ApiClient();
  apiClient.setBasePath(BaseUrl);

  // create JSON formatted auth header
  var creds = '{"Username":"' + UserName + '","Password":"' + Password + '","IntegratorKey":"' + IntegratorKey + '"}';
  apiClient.addDefaultHeader('X-DocuSign-Authentication', creds);

  // assign api client to the Configuration object
  docusign.Configuration.default.setDefaultApiClient(apiClient);

  // ===============================================================================
  // Step 1:  Login() API
  // ===============================================================================
  // login call available off the AuthenticationApi
  var authApi = new docusign.AuthenticationApi();

  // login has some optional parameters we can set
  var loginOps = new authApi.LoginOptions();
  loginOps.setApiPassword('true');
  loginOps.setIncludeAccountIdGuid('true');
  authApi.login(loginOps, function (error, loginInfo, response) {
    if (error) {
      console.log('Error: ' + error);
      return;
    }

    if (loginInfo) {
      // list of user account(s)
      // note that a given user may be a member of multiple accounts
      var loginAccounts = loginInfo.getLoginAccounts();
      console.log('LoginInformation: ' + JSON.stringify(loginAccounts));

      // ===============================================================================
      // Step 2:  Create Envelope API (AKA Signature Request) from a Template
      // ===============================================================================

      // create a new envelope object that we will manage the signature request through
      var envDef = new docusign.EnvelopeDefinition();
      envDef.setEmailSubject(subject);
      envDef.setTemplateId(templateId);
      envDef.setTemplateRoles([
       {email:'foo@email.com',
       name:'bob',
       roleName:'Seller',
       // tabStatuses:[
       //   {tabStatus:[{
       //    tabLabel:'sellerName',
       //    tabValue:'test123'
       //   }]}
       // ]

       tabs:
         {textTabs:[{
          tabLabel:'sellerName',
          tabName:'sellerName',
          tabValue:'test123'
         }]},

       // tabStatuses:
       //   {textTabs:[{
       //    tabLabel:'sellerName',
       //    tabName:'sellerName',
       //    tabValue:'test123'
       //   }]}

       }
      ]);
      // console.log("eid", envDef.getEnvelopeId()); //undefined



      //I commented out the following example code. I looked through the docusign-esign source and it didn't seem to have a way to add tabStatuses (whatever that means) so I used the above code instead. Which works as far as sending the email, but doesn't work for pre-filling the fields.
      // create a template role with a valid templateId and roleName and assign signer info
      // var tRole = new docusign.TemplateRole();
      // tRole.setRoleName(templateRoleName);
      // tRole.setName(signerName);
      // tRole.setEmail(signerEmail);
      //
      // // create a list of template roles and add our newly created role
      // var templateRolesList = [];
      // templateRolesList.push(tRole);
      //
      // // assign template role(s) to the envelope
      // envDef.setTemplateRoles(templateRolesList);

      // send the envelope by setting |status| to "sent". To save as a draft set to "created"
      envDef.setStatus('sent');

      // use the |accountId| we retrieved through the Login API to create the Envelope
      var loginAccount = new docusign.LoginAccount();
      loginAccount = loginAccounts[0];
      var accountId = loginAccount.accountId;






      //it gets a little messy with junk experimental code. But what's not commented out is the same as the example, except I've added an additional callback in the deepest function.




      // instantiate a new EnvelopesApi object
      var envelopesApi = new docusign.EnvelopesApi();

      // envelopesApi.getDocuments(loginAccount.accountId)

      // call the createEnvelope() API
      envelopesApi.createEnvelope(accountId, envDef, null, function (error, envelopeSummary, response) {
        if (error) {
          console.log('Error: ' + error);
          return;
        }

        if (envelopeSummary) {
         console.log('EnvelopeSummary: ' + JSON.stringify(envelopeSummary));
         var envelopeId = envelopeSummary.envelopeId;
         console.log("envelopeId", envelopeId);
         // envelopesApi.listDocuments(accountId, envelopeId, function (error, data, response) {
         //  if (error) {console.log("error", error);return;}
         //  console.log("data", data);
         //  console.log("response", response);
         // });
         //envelopesApi.getDocument downloads the PDF binary 2.5MiB.
         var documentId = '1';
         var chunks=[];
         envelopesApi.listCustomFields(accountId, envelopeId, function (error, data, response) {
          if (error) {console.log("error", error);return;}
          console.log("typeof data", typeof data);
          // console.log("data.length", data.length);
          // // console.log("response", response);
          // response.on('data',chunk => chunks.push(chunk));
          // response.on('end',()=>{
          //  var allChunks = chunks.join('');
          //  console.log("allChunks", allChunks);
          // });
          console.log("data", data);
          // console.log("data.toJson()", data.toJson());
          console.log("data.getTextCustomFields()", data.getTextCustomFields());
         });

        }

      });
    }
  });
}; // end RequestSignatureFromTemplate()

Answer 1

When they say tab what are they talking about? What is a tab?

Tabs - aka fields or tags- can be added to documents and templates and are used several ways.

• First they are used to indicate to a recipient where a signature or initials are required.
• Second, they can be used to show data or information to recipients, such as dates, names, addresses, and other data.
• Third, tabs can be used as editable information fields so you can retrieve data or information from your recipients

More information here

---

Does tabLabel mean Data Label, or are they different things?

Yes they are the same.

If you give tabs of the same type the same tabLabel when a recipient updates one tab it will update all the others with the same data in real-time.

More information here (see "Shared Tab Labels" section)

---

How can I add a "custom field" to my docusign template? I've tried to do it by clicking Custom Fields, and adding one. But it seems to be more of a field template than a specific custom field. When I run the API call listCustomFields, it comes back empty.

A "custom field" could mean several things. See this answer for more information.

If you are looking for the Tabs on a document then you should explore the listEnvelopeTabs api

---

My template comes through fine, but the fields are not pre-filled.

If you are looking for pre-filled Fields (aka Tabs), you should set the "value" property in your request. More info here

Here is the raw Json request.

"tabs": {
 "textTabs": [
  {
    "value": "$100",
    "xPosition": "300",
    "yPosition": "200",
    "documentId": "1",
    "pageNumber": "1"
  }]
}