Set document visibility code example (#88)

* added example

* update page

* fixes

* fixes

* add example

* update title

* fixes

* removing numbering and reorganizing homepage

* change description to be consistent with c# example

* fixed number ex 39 and made esignature default

* removed Host name field on code example page

* signer emails

* fix hostname issue

* update comment for clarity

* reordering embed the docusign ui example

Co-authored-by: Paige Rossi <paige.rossi@docusign.com>
Co-authored-by: Patrick Mackle <pimackle@ucdavis.edu>
Co-authored-by: meihDS <70775251+meihDS@users.noreply.github.com>

Author: 4 people

config/examplesApi.json

@@ -0,0 +1 @@
+{"examplesApi":{"isESignatureApi":true,"isRoomsApi":false,"isClickApi":false,"isMonitorApi":false,"isAdminApi":false}}

index.js

@@ -28,7 +28,7 @@ const {
   eg016, eg017, eg018, eg019, eg020, eg022, eg023,
   eg024, eg025, eg026, eg027, eg028, eg029, eg030,
   eg031, eg032, eg033, eg034, eg035, eg036, eg037,
-  eg038
+  eg038, eg039, eg040
 } = require("./lib/eSignature/controllers");
 
 const {
@@ -240,6 +240,10 @@ if (examplesApi.examplesApi.isRoomsApi) {
     .post('/eg037', eg037.createController)
     .get('/eg038', eg038.getController)
     .post('/eg038', eg038.createController)
+    .get('/eg039', eg039.getController)
+    .post('/eg039', eg039.createController)
+    .get('/eg040', eg040.getController)
+    .post('/eg040', eg040.createController)
 }
 
 function dsLoginCB1(req, res, next) { req.dsAuthCodeGrant.oauth_callback1(req, res, next) }

lib/eSignature/controllers/eg039SigningInPerson.js

@@ -0,0 +1,106 @@
+/**
+ * @file
+ * Example 039: Send an envelope to an In Person Signer
+ * @author DocuSign
+ */
+
+const path = require('path');
+const { sendEnvelopeForInPersonSigning } = require('../examples/signingInPerson');
+const validator = require('validator');
+const dsConfig = require('../../../config/index.js').config;
+const { getUserInfo } = require('../getData');
+
+const eg039SigningInPerson = exports;
+const eg = 'eg039'; // This example reference.
+const mustAuthenticate = '/ds/mustAuthenticate';
+const minimumBufferMin = 3;
+const demoDocsPath = path.resolve(__dirname, '../../../demo_documents');
+const pdf1File = 'World_Wide_Corp_lorem.pdf';
+const dsReturnUrl = dsConfig.appUrl + '/ds-return';
+const dsPingUrl = dsConfig.appUrl + '/'; // Url that will be pinged by the DocuSign signing via Ajax
+
+/**
+ * Create the envelope, the embedded signing, and then redirect to the DocuSign signing
+ * @param {object} req Request obj
+ * @param {object} res Response obj
+ */
+eg039SigningInPerson.createController = async (req, res) => {
+    // Step 1. Check the token
+    // At this point we should have a good token. But we
+    // double-check here to enable a better UX to the user.
+    const isTokenOK = req.dsAuth.checkToken(minimumBufferMin);
+    if (!isTokenOK) {
+        req.flash('info', 'Sorry, you need to re-authenticate.');
+        // Save the current operation so it will be resumed after authentication
+        req.dsAuth.setEg(req, eg);
+        return res.redirect(mustAuthenticate);
+    }
+
+    // Step 2. Get the email and name of the current user
+    const user = await getUserInfo(req.user.accessToken, req.session.basePath);
+    const email = user.email;
+    const hostName = user.name;
+
+    // Step 3. Call the worker method
+    const { body } = req;
+    const envelopeArgs = {
+        hostEmail: email,
+        hostName: hostName,
+        signerName: validator.escape(body.signerName),
+        dsReturnUrl: dsReturnUrl,
+        dsPingUrl: dsPingUrl,
+        docFile: path.resolve(demoDocsPath, pdf1File)
+    };
+    const args = {
+        accessToken: req.user.accessToken,
+        basePath: req.session.basePath,
+        accountId: req.session.accountId,
+        envelopeArgs: envelopeArgs
+    };
+    let results = null;
+
+    try {
+        results = await sendEnvelopeForInPersonSigning(args);
+    }
+    catch (error) {
+        const errorBody = error && error.response && error.response.body;
+        // we can pull the DocuSign error code and message from the response body
+        const errorCode = error && error.status || errorBody && errorBody.errorCode;
+        const errorMessage = errorBody && errorBody.error_description || errorBody.message;
+        // In production, may want to provide customized error messages and
+        // remediation advice to the user.
+        res.render('pages/error', {err: error, errorCode, errorMessage});
+    }
+    if (results) {
+        // Redirect the user to the embedded signing
+        // Don't use an iFrame!
+        // State can be stored/recovered using the framework's session or a
+        // query parameter on the returnUrl (see the makeRecipientViewRequest method)
+        res.redirect(results.redirectUrl);
+    }
+}
+
+/**
+ * Form page for this application
+ */
+eg039SigningInPerson.getController = (req, res) => {
+    // Check that the authentication token is ok with a long buffer time.
+    // If needed, now is the best time to ask the user to authenticate
+    // since they have not yet entered any information into the form.
+    const isTokenOK = req.dsAuth.checkToken();
+    if (!isTokenOK) {
+        // Save the current operation so it will be resumed after authentication
+        req.dsAuth.setEg(req, eg);
+        return res.redirect(mustAuthenticate);
+    }
+
+    const sourceFile = (path.basename(__filename))[5].toLowerCase() + (path.basename(__filename)).substr(6);
+    res.render('pages/examples/eg039SigningInPerson', {
+        eg: eg, csrfToken: req.csrfToken(),
+        title: "Send an envelope to an In Person Signer",
+        sourceFile: path.basename(__filename),
+        sourceUrl: dsConfig.githubExampleUrl + 'eSignature/examples/' + sourceFile,
+        documentation: dsConfig.documentation + eg,
+        showDoc: dsConfig.documentation
+    });
+}

lib/eSignature/controllers/eg040SetDocumentVisibility.js

@@ -0,0 +1,111 @@
+/**
+ * @file
+ * Example 040: Set document visibility for envelope recipients
+ * @author DocuSign
+ */
+
+const path = require('path');
+const validator = require('validator');
+const dsConfig = require('../../../config/index.js').config;
+const { sendEnvelope } = require('../examples/setDocumentVisibility');
+
+const eg040SetDocumentVisibility = exports;
+const eg = 'eg040'; // This example reference.
+const mustAuthenticate = '/ds/mustAuthenticate';
+const minimumBufferMin = 3;
+const demoDocsPath = path.resolve(__dirname, '../../../demo_documents');
+const doc2File = 'World_Wide_Corp_Battle_Plan_Trafalgar.docx';
+const doc3File = 'World_Wide_Corp_lorem.pdf';
+
+/**
+ * Create the envelope and set document visibility for envelope recipients
+ * @param {object} req Request obj
+ * @param {object} res Response obj
+ */
+eg040SetDocumentVisibility.createController = async (req, res) => {
+    // Step 1. Check the token
+    // At this point we should have a good token. But we
+    // double-check here to enable a better UX to the user.
+    const isTokenOK = req.dsAuth.checkToken(minimumBufferMin);
+    if (!isTokenOK) {
+        req.flash('info', 'Sorry, you need to re-authenticate.');
+        // Save the current operation so it will be resumed after authentication
+        req.dsAuth.setEg(req, eg);
+        return res.redirect(mustAuthenticate);
+    }
+
+    // Step 2. Call the worker method
+    const { body } = req;
+    const envelopeArgs = {
+        signer1Email: validator.escape(body.signer1Email),
+        signer1Name: validator.escape(body.signer1Name),
+        signer2Email: validator.escape(body.signer2Email),
+        signer2Name: validator.escape(body.signer2Name),
+        ccEmail: validator.escape(body.ccEmail),
+        ccName: validator.escape(body.ccName),
+        status: "sent",
+        doc2File: path.resolve(demoDocsPath, doc2File),
+        doc3File: path.resolve(demoDocsPath, doc3File)
+    };
+    const args = {
+        accessToken: req.user.accessToken,
+        basePath: req.session.basePath,
+        accountId: req.session.accountId,
+        envelopeArgs: envelopeArgs
+    };
+    let results = null;
+
+    try {
+        results = await sendEnvelope(args);
+    } catch (error) {
+        const errorBody = error && error.response && error.response.body;
+        // we can pull the DocuSign error code and message from the response body
+        const errorCode = errorBody && errorBody.errorCode;
+        const errorMessage = errorBody && errorBody.message;
+
+        let errorData = { err: error, errorCode, errorMessage }
+
+        if (errorCode && errorCode === "ACCOUNT_LACKS_PERMISSIONS") {
+            errorData.errorInfo = `<p>See <a href="https://developers.docusign.com/docs/esign-rest-api/how-to/set-document-visibility/">How to set document visibility for envelope recipients</a> in 
+                the DocuSign Developer Center for instructions on how to 
+                enable document visibility in your developer account.</p>`
+        }
+        // In production, may want to provide customized error messages and
+        // remediation advice to the user.
+        res.render('pages/error', errorData);
+    }
+    if (results) {
+        res.render('pages/example_done', {
+            title: "Set document visibility for envelope recipients",
+            h1: "Set document visibility for envelope recipients",
+            message: `The envelope has been created and sent!<br/>Envelope ID ${results.envelopeId}.`
+        });
+    }
+}
+
+/**
+ * Form page for this application
+ */
+eg040SetDocumentVisibility.getController = (req, res) => {
+    /**
+     * Check that the authentication token is ok with a long buffer time.
+     * If needed, now is the best time to ask the user to authenticate
+     * since they have not yet entered any information into the form.
+     */
+    const isTokenOK = req.dsAuth.checkToken();
+    if (!isTokenOK) {
+        // Save the current operation so it will be resumed after authentication
+        req.dsAuth.setEg(req, eg);
+        return res.redirect(mustAuthenticate);
+    }
+
+    const sourceFile = (path.basename(__filename))[5].toLowerCase() + (path.basename(__filename)).substr(6);
+    res.render('pages/examples/eg040SetDocumentVisibility', {
+        eg: eg, csrfToken: req.csrfToken(),
+        title: "Set document visibility for envelope recipients",
+        sourceFile: sourceFile,
+        sourceUrl: dsConfig.githubExampleUrl + 'eSignature/examples/' + sourceFile,
+        documentation: dsConfig.documentation + eg,
+        showDoc: dsConfig.documentation
+    });
+}

lib/eSignature/controllers/index.js

@@ -35,3 +35,5 @@ module.exports.eg035 = require('./eg035ScheduledSending');
 module.exports.eg036 = require('./eg036DelayedRouting');
 module.exports.eg037 = require('./eg037SmsDelivery');
 module.exports.eg038 = require('./eg038ResponsiveSigning');
+module.exports.eg039 = require('./eg039SigningInPerson')
+module.exports.eg040 = require('./eg040SetDocumentVisibility');