DocuSign Embedded signing API

Question

two part question:

We are trying to receive a notification that a Document is ready to sign (which we're not totally clear on what is provided in the notification). We don't want to do email notifications; we want to shut off those. We presume the info for embedded signing is contained in the non-email notification. Is there an easy way to send a push notification to another program that says a document is ready to send, and if so, is the best way to follow up the notification to have the signing API POST and request the info from DocuSign?

In our testing we've been able to receive the embedded signing URL with the API call, but it takes us to a page to a signing view where the tabs are not displaying; this means the signer cannot sign, likewise for other roles. It's the same problem explained in this SO post, for the most part. I am coding in JavaScript, not PHP. I am unaware if this is going to make a difference in answering the question, if so, please ask more questions in the comments and I can provide more info.

This is what we're getting, but we are supposed to be getting a document with the signature tabs in it

This is what we're supposed to see. We see this version when manually logging into DS and clicking on the doc.

We believe the templateRoleName field might be what's causing this problem, but we have tested with and without it, and it seems to not make a difference.

This is the JS file for the API call we're using from the walkthroughs.

//
// to run this sample
//  1. copy the file in your own directory - say, example.js
//  2. change "***" to appropriate values
//  3. install async and request packages
//     npm install async
//     npm install request
//  4. execute
//     node example.js 
// 

var     async = require("async"),       // async module
    request = require("request"),       // request module
    email = "[email protected]",              // your account email
    password = "password1",         // your account password
    integratorKey = "DEEZ-010ebc24-01cc-143a-98c3-d9dbf7561cb1",            // your account Integrator Key (found on Preferences -> API page)
    recipientName = "[email protected]",          // recipient (signer) name
    templateId = "1C504DBA-B03F-4E57-B6BB-FD2ABD15837C",            // provide valid templateId from a template in your account
    templateRoleName = "Signer",        // template role that exists on template referenced above
    baseUrl = "",               // we will retrieve this
    envelopeId = "bc14310c-57c0-4168-91be-1fb71ea24c1c";            // created from step 2

async.waterfall(
    [
        //////////////////////////////////////////////////////////////////////
        // Step 1 - Login (used to retrieve accountId and baseUrl)
        //////////////////////////////////////////////////////////////////////
        function(next) {
            var url = "https://demo.docusign.net/restapi/v2/login_information";
            var body = "";  // no request body for login api call

            // set request url, method, body, and headers
            var options = initializeRequest(url, "GET", body, email, password);

            // send the request...
            request(options, function(err, res, body) {
                if(!parseResponseBody(err, res, body)) {
                    return;
                }
                baseUrl = JSON.parse(body).loginAccounts[0].baseUrl;
                next(null); // call next function
            });
        },

        //////////////////////////////////////////////////////////////////////
        // Step 2 - Send envelope with one Embedded recipient (using clientUserId property)
        //////////////////////////////////////////////////////////////////////
        function(next) {
            var url = baseUrl + "/envelopes";
            var body = JSON.stringify({
                "emailSubject": "DocuSign API call - Embedded Sending Example",
                "templateId": templateId,
                "templateRoles": [{
                    "email": email,
                    "name": recipientName,
                    "roleName": templateRoleName,
                    "clientUserId": "1001"  // user-configurable
                }],
                "status": "sent"
            });

            // set request url, method, body, and headers
            var options = initializeRequest(url, "POST", body, email, password);

            // send the request...
            request(options, function(err, res, body) {
                if(!parseResponseBody(err, res, body)) {
                    return;
                }
                // parse the envelopeId value from the response
                envelopeId = JSON.parse(body).envelopeId;
                next(null); // call next function
            });
        },

        //////////////////////////////////////////////////////////////////////
        // Step 3 - Get the Embedded Signing View (aka the recipient view)
        //////////////////////////////////////////////////////////////////////
        function(next) {
            var url = baseUrl + "/envelopes/" + envelopeId + "/views/recipient";
            var method = "POST";
            var body = JSON.stringify({
                "returnUrl": "http://www.docusign.com/devcenter",
                "authenticationMethod": "email",
                "email": email,
                "userName": recipientName,
                "clientUserId": "1001", // must match clientUserId in step 2!
            });

            // set request url, method, body, and headers
            var options = initializeRequest(url, "POST", body, email, password);

            // send the request...
            request(options, function(err, res, body) {
                if(!parseResponseBody(err, res, body))
                    return;
                else
                    console.log("\nNavigate to the above URL to start the Embedded Signing workflow...");
            });
        }
    ]);

    //***********************************************************************************************
    // --- HELPER FUNCTIONS ---
    //***********************************************************************************************
    function initializeRequest(url, method, body, email, password) {
        var options = {
            "method": method,
            "uri": url,
            "body": body,
            "headers": {}
        };
        addRequestHeaders(options, email, password);
        return options;
    }

    ///////////////////////////////////////////////////////////////////////////////////////////////
    function addRequestHeaders(options, email, password) {
        // JSON formatted authentication header (XML format allowed as well)
        dsAuthHeader = JSON.stringify({
            "Username": email,
            "Password": password,
            "IntegratorKey": integratorKey  // global
        });
        // DocuSign authorization header
        options.headers["X-DocuSign-Authentication"] = dsAuthHeader;
    }

    ///////////////////////////////////////////////////////////////////////////////////////////////
    function parseResponseBody(err, res, body) {
        console.log("\r\nAPI Call Result: \r\n", JSON.parse(body));
        if( res.statusCode != 200 && res.statusCode != 201) { // success statuses
            console.log("Error calling webservice, status is: ", res.statusCode);
            console.log("\r\n", err);
            return false;
        }
        return true;
    }

EDIT This is the recipients and routing section from the classic view of DocuSign for this template as it was of the original posting of this question

This is the Created_RequestRecipientToken file from the request log:

POST https://demo.docusign.net:7802/restapi/v2/accounts/1037192/envelopes/deez83c9-b1fg-46ab-bo0c-e4576d952ac6/views/recipient
Content-Length: 185
Connection: keep-alive
Host: demo.docusign.net
X-DocuSign-Authentication: {"Username":"[email protected]","Password":"[omitted]","IntegratorKey":"[omitted]"}
X-Forwarded-For: 543.155.155.55

{"returnUrl":"http://www.docusign.com/devcenter","authenticationMethod":"email","email":"[email protected]","userName":"[email protected]","clientUserId":"1002"}
201 Created
Content-Type: application/json; charset=utf-8

{
  "url": "https://demo.docusign.net/Signing/startinsession.aspx?t=3c06d2a3-e521-4e52-b669-01e24c81c3bf"
}

This is the Created_CreateEnvelopeFromTemplateAndForms file from the request log:

POST https://demo.docusign.net:7802/restapi/v2/accounts/1037192/envelopes
Content-Length: 272
Connection: keep-alive
Host: demo.docusign.net
X-DocuSign-Authentication: {"Username":"[email protected]","Password":"[omitted]","IntegratorKey":"[omitted]"}
X-Forwarded-For: 143.115.155.55

{"emailSubject":"DocuSign API call - Embedded Sending Example","templateId":"9AF271E2-D38E-4E61-8083-928A3CCE056C",
"templateRoles":[{"email":"[email protected]","name":"[email protected]","roleName":"Signer","clientUserId":"1002"}],
"status":"sent"}
201 Created
Content-Type: application/json; charset=utf-8

{
  "envelopeId": "deez83c9-b1fg-46ab-bo0c-e4576d952ac6",
  "uri": "/envelopes/deez83c9-b1fg-46ab-bo0c-e4576d952ac6",
  "statusDateTime": "2015-07-08T15:56:23.5930000Z",
  "status": "sent"
}

this or this or this are not solutions to this post.

Answer 1

When you send a signature request from a template if you want the recipient(s) to inherit all the tabs and workflow you have previously created then you must match them to a role. To match them you need to use the roleName property, which is set through the templateRoleName sample Node script you are referencing.

First off, I want to mention that in your first screenshot where there are no tabs the recipient can still sign by dragging any of the tabs from the left onto the document. This is called Free Form Signing and they chose which tabs, how many, and where to place them on the docs when they are not matched to a template role.

I see in your code that you are setting the template role name to value Signer, this will only work if you that's what you named your placeholder (template) role in the web console when you were creating it. Change the value of the role name in the web console to Signer and it should work.