DocuSign is a well known platform where users can send their document for signing via email or your app. I will try to show you how DocuSign authorize an user and how can we send a document to users for signing electronically and we will do that programmatically.

To use DocuSign at first we need a free developer account. Go there and select Developer Account button in the top left then Create Account. Log into this account. After login you need to create an app for your integration. Go to My Apps and Keys there you will see your Integrations. Click ADD APP & INTEGRATION KEY button. Give a name and select Authorization Code Grant for User Application. In secret keys generate one and save them somewhere because you won't be able to see it again. In Redirect URLs Add one which will be needed when we make URLs for authorization. An Integration key will be generated for your app we need this later.

We will use Authorization Code Grant to authorize users. Authorization process has 2 steps first we need to obtain Authorization Code and 2nd using that Authorization Code we need to obtain access token using rest api call.

To get Authorization Code we need to generate a url where we need to redirect ours users to that url. There user will login to their DocuSign Account and grant access to our app. After user authorizes our app user will be redirected to our whitelisted redirect url with a Authorization Code. Below is the URL format.

https://account-d.docusign.com/oauth/auth?response_type=code&scope=signature&client_id=7c2b8d7e-xxxx-xxxx-xxxx-cda8a50dd73f&state=a39fh23hnf23&redirect_uri=http://example.com/callback/

client_id is the integration key and redirect_uri is the url where DocuSign will redirect users with a Authorization Code. After Redirected URL will contain a parameter called code. We need this code to generate access token.

To Get Access Token we need to call a rest api and we need to set header. The authorization header will contain integration key and secret key separated by a colon and converted it to base64 with prefixed by a word Basic. We can generate this base64 easily by using browser console. In Console write this and enter

 btoa('INTEGRATION_KEY:SECRET_KEY')

it will show the base64 of the string. set this string in the Authorization Header. This is a POST method so I am using curl to request this endpoint.

curl --header "Authorization: Basic BASE64_OF_YOUR_INTEGRATION_AND_SECRET_KEY"
--data "grant_type=authorization_code&code=AUTHORIZATION_CODE_FROM_DOCUSIGN" 
--request POST https://account-d.docusign.com/oauth/token

The response of this request will have access_token, refresh_token and expires_in . We need this access token to make every DocuSign API Call.

I am using C# as an example for how to send a document for signing. We need to add a C# library to make DocuSign api call. Search and install eSignature API via  Nuget Package Manager Which is made by DocuSign. First we need to make an envelope here is the Code example to  make an Envelope.

private EnvelopeDefinition MakeEnvelope(string signerEmail, string signerName, string ccEmail, string ccName)
{
    string doc2DocxBytes = Convert.ToBase64String(System.IO.File.ReadAllBytes(Config.docDocx));
    string doc3PdfBytes = Convert.ToBase64String(System.IO.File.ReadAllBytes(Config.docPdf)); 
    // Create the envelope definition
    EnvelopeDefinition env = new EnvelopeDefinition();
    env.EmailSubject = "Please sign this document set";
    Document doc1 = new Document();
    string b64 = Convert.ToBase64String(document1(signerEmail, signerName, ccEmail, ccName));
    doc1.DocumentBase64 = b64;
    doc1.Name = "Order acknowledgement"; // can be different from actual file name
    doc1.FileExtension = "html"; // Source data format. Signed docs are always pdf.
    doc1.DocumentId = "1"; // a label used to reference the doc
    Document doc2 = new Document {
        DocumentBase64 = doc2DocxBytes,
        Name = "Battle Plan", // can be different from actual file name
        FileExtension = "docx",
        DocumentId = "2"
    };

    Document doc3 = new Document
    {
        DocumentBase64 = doc3PdfBytes,
        Name = "Lorem Ipsum", // can be different from actual file name
        FileExtension = "pdf",
        DocumentId = "3"
    };


    // The order in the docs array determines the order in the envelope
    env.Documents =  new List<Document> { doc1, doc2, doc3};

    // create a signer recipient to sign the document, identified by name and email
    // We're setting the parameters via the object creation
    Signer signer1 = new Signer {
        Email = signerEmail,
        Name = signerName,
        RecipientId = "1",
        RoutingOrder = "1"
    };

    // routingOrder (lower means earlier) determines the order of deliveries
    // to the recipients. Parallel routing order is supported by using the
    // same integer as the order for two or more recipients.

    // create a cc recipient to receive a copy of the documents, identified by name and email
    // We're setting the parameters via setters
    CarbonCopy cc1 = new CarbonCopy
    {
        Email = ccEmail,
        Name = ccName,
        RecipientId = "2",
        RoutingOrder = "2"
    };

    // Create signHere fields (also known as tabs) on the documents,
    // We're using anchor (autoPlace) positioning
    //
    // The DocuSign platform searches throughout your envelope's
    // documents for matching anchor strings. So the
    // signHere2 tab will be used in both document 2 and 3 since they
    // use the same anchor string for their "signer 1" tabs.
    SignHere signHere1 = new SignHere
    {
        AnchorString = "**signature_1**",
        AnchorUnits = "pixels",
        AnchorYOffset = "10",
        AnchorXOffset = "20"
    };

    SignHere signHere2 = new SignHere
    {
        AnchorString = "/sn1/",
        AnchorUnits = "pixels",
        AnchorYOffset = "10",
        AnchorXOffset = "20"
    };
    

    // Tabs are set per recipient / signer
    Tabs signer1Tabs = new Tabs {
        SignHereTabs = new List<SignHere> { signHere1, signHere2}
    };
    
    signer1.Tabs = signer1Tabs;

    // Add the recipients to the envelope object
    Recipients recipients = new Recipients
    {
        Signers = new List<Signer> { signer1 },
        CarbonCopies = new List<CarbonCopy> { cc1 }
    };
    
    env.Recipients = recipients;

    // Request that the envelope be sent by setting |status| to "sent".
    // To request that the envelope be created as a draft, set to "created"
    env.Status = RequestItemsService.Status;

    return env;
}

// The HTML of the first document in the envelope used by our example is defined here
private byte[] document1(string signerEmail, string signerName, string ccEmail, string ccName)
{
    return Encoding.UTF8.GetBytes(
    " <!DOCTYPE html>\n" +
        "    <html>\n" +
        "        <head>\n" +
        "          <meta charset=\"UTF-8\">\n" +
        "        </head>\n" +
        "        <body style=\"font-family:sans-serif;margin-left:2em;\">\n" +
        "        <h1 style=\"font-family: 'Trebuchet MS', Helvetica, sans-serif;\n" +
        "            color: darkblue;margin-bottom: 0;\">World Wide Corp</h1>\n" +
        "        <h2 style=\"font-family: 'Trebuchet MS', Helvetica, sans-serif;\n" +
        "          margin-top: 0px;margin-bottom: 3.5em;font-size: 1em;\n" +
        "          color: darkblue;\">Order Processing Division</h2>\n" +
        "        <h4>Ordered by " + signerName + "</h4>\n" +
        "        <p style=\"margin-top:0em; margin-bottom:0em;\">Email: " + signerEmail + "</p>\n" +
        "        <p style=\"margin-top:0em; margin-bottom:0em;\">Copy to: " + ccName + ", " + ccEmail + "</p>\n" +
        "        <p style=\"margin-top:3em;\">\n" +
        "  Candy bonbon pastry jujubes lollipop wafer biscuit biscuit. Topping brownie sesame snaps sweet roll pie. Croissant danish biscuit soufflé caramels jujubes jelly. Dragée danish caramels lemon drops dragée. Gummi bears cupcake biscuit tiramisu sugar plum pastry. Dragée gummies applicake pudding liquorice. Donut jujubes oat cake jelly-o. Dessert bear claw chocolate cake gummies lollipop sugar plum ice cream gummies cheesecake.\n" +
        "        </p>\n" +
        "        <!-- Note the anchor tag for the signature field is in white. -->\n" +
        "        <h3 style=\"margin-top:3em;\">Agreed: <span style=\"color:white;\">**signature_1**/</span></h3>\n" +
        "        </body>\n" +
        "    </html>"
        );
}

And this is the code for sending this envelope to DocuSign.

public EnvelopeSummary SendEnvelope(string signerEmail, string signerName, string ccEmail, string ccName)
        {
            var accessToken = ACCESS_TOKEN;
            var basePath = BASE_PATH + "/restapi";
            var accountId = ACCOUNT_ID;

            EnvelopeDefinition env = MakeEnvelope(signerEmail, signerName, ccEmail, ccName);
            var apiClient = new ApiClient(basePath);
            apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
            var envelopesApi = new EnvelopesApi(apiClient);
            EnvelopeSummary results = envelopesApi.CreateEnvelope(accountId, env);
            RequestItemsService.EnvelopeId = results.EnvelopeId;
            return results;
        }

ACCESS_TOKEN is the token we got from the authorization step. BASE_PATH will be https://demo.docusign.net as this is for development purpose and you will find it in the admin dashboard (My Apps and Keys) Page. ACCOUNT_ID is the API Account Id which is also in the dashboard.  If our SendEnvelope method is called successfully , Signers will be notified via email that he/she has a document to Sign. Go through their official doc if you want to dive deeply to know other features also.

Custom elements are useful when we have large page content and we need to break the pages into small pieces of components which can be reusable in the other pages also. To create a custom element we just need to create a view template and optionally a view model for it. Using a custom element to a page or another element is to just require it in that page and add a custom html tag for this.

Say we have a page that displays users information users personal info, his address and the blog posts which was posted by them. If we put all the information in a single component it will look like similar as below

<template>
  <div>
    Users Personal Information
  </div>
  <div>
    Users Contact Information
  </div>
  <div>
    Blog Posts
    <ul>
      <li>Post 1</li>
      <li>Post 2</li>
      <li>Post 3</li>
    </ul>
  </div>
</template>

Here its not a large amount of code but definitely it will be very large in real scenarios. There we can refactor this code and break these into 3 components like PersonalInfo, ContactInfo, UserBlogPost then it will look clean and easy to understand and it will be highly maintainable. Basically as a frontend developer you will deal with hundreds of components and composing them. It is conventional to put the reusable pieces of components in a separate folder called components/partials you can use whatever names you like. So I am creating these custom elements in components folder  as like below.

PersonalInfo.html

<template>
  <div>
    Users Personal Information
  </div>
</template>

ContactInfo.html

<template>
  <div>
    Users Contact Information
  </div>
</template>

UserBlogPost.html

<template>
  <div>
    Blog Posts
    <ul>
      <li>Post 1</li>
      <li>Post 2</li>
      <li>Post 3</li>
    </ul>
  </div>
</template>

Create 3 view models for each of these also PersonalInfo.js , ContactInfo.js and UserBlogPost.js.Make a class with the same file name (its optional though but its good to have a view model also). Now we will include them in our main user details page. I am using app.html file for these. See how our app.html look like

<template>
  <require from="./components/PersonalInfo"></require>
  <require from="./components/ContactInfo"></require>
  <require from="./components/UserBlogPost"></require>
  <personal-info></personal-info>
  <contact-info></contact-info>
  <user-blog-post></user-blog-post>
</template>

If you run it you will see the exact same result but our code now looks clean and we can easily reuse them into other pages also. Now see how we require and placed it in the template. we need to require it and specify its relative path don't need to specify the extension. After requiring it we need to tell where to place it by html tag (hyphened version of the file name). That's it you now know about custom elements.

Another way to use it by using <compose> attribute. Using compose attribute code will look like these for our app.html file

<template>
  <compose view-model="./components/PersonalInfo"></compose>
  <compose view-model="./components/ContactInfo"></compose>
  <compose view-model="./components/UserBlogPost"></compose>
</template>

Output will be the same. Compose is good when you want to render dynamic element based on some criteria. You can put a variable in the view-model attribute and change the path of the component from parent View Model. That is a difference between compose and custom element.

Now I will show you how you can pass a variable to the child component. Say we have user object with firstName and lastName in our app.js (Parent Component). We want to pass its value to the PersonalInfo component (Child Component). To make it work we need to declare a variable in  PersonalInfo.js and make it bindable properties. see how it do that

PersonalInfo.js

import { bindable } from "aurelia-framework";
export class PersonalInfo {
  @bindable user;
}

And In the child component view template we will display the firstName and lastName info.

PersonalInfo..html

<template>
  <div>
    ${user.firstName }
    ${user.lastName }
  </div>
</template>

Now to pass user object from parent model we need to add an attribute in the html tag for custom element. so the code will be

<template>
  <require from="./components/PersonalInfo"></require>
  <require from="./components/ContactInfo"></require>
  <require from="./components/UserBlogPost"></require>
  <personal-info user.bind="user"></personal-info>
  <contact-info></contact-info>
  <user-blog-post></user-blog-post>
</template>

See user.bind here user is the child component property name (it will be hyphened version of the name) and you have to specify which parent property it will pass as value. You can also bind a function like this way. To know more about custom elements go through their official docs .

In VivaSoft Limited We have some Clients who want to develop their project using aurelia in the frontend. So recently I have learned Aurelia to work with a Client. It is similar with Angular and VueJS. Here I will try to show you how to start a project with aurelia and its basic structure.

Aurelia is a Javascript Frontend Framework. It is very simple to understand and learn. As It is a frontend framework its purpose is to render UI in the browser. We can easily make SPA Web Applications using Aurelia.

Before learning it you must know JS as it is a JS framework and You should know Modern ES Syntax (ES6). You must know HTML and CSS very well also as it deals with Web UI.

You need to have NodeJS installed in your Machine as Aurelia uses NPM as Dependency Manager. NPM will be installed with NodeJS.

After Installing NodeJS run the following command in your cmd/bash terminal to install Aurelia CLI tool.

npm install -g aurelia-cli

Using aurelia-ali we can create a basic project with all the things we need to develop a project with Aurelia. To create a project go to the folder where you want to create your project and run `au new` command in your terminal. Give a name to your project and enter then a couple of options will appear select Default Setup. When it asks for “if you would like to install your new project’s dependencies” Select Yes to install Dependencies. Wait for a few seconds until this process finishes. After Successfully created go to the project folder and run `npm start` . it will start the project and You will see a Hello World! Page at http://localhost:8080/ in your Browser.

Now open the project folder in your Code Editor (I prefer VS Code for JS Development). If you see the Project Folder Structure you will see a src folder basically all our codes will be there. There you will see an app.js and app.html file which is rendering Hello World! Page. In Aurelia every page will have 2 files one will be a .js file and the other will be a .html file with the same name. HTML file will contain the html and css code related to this page which will be used for styling and UI layout and js will contain a Class with properties and methods which will be used for event handling and show dynamic content based on properties. JS file is called View Model and HTML file is called View.

In the view file there will be a <template> tag basically all your html will be wrapped by this tag. To show a value of a JS property in the View use ${PROPERTY_NAME}. In our generated project you will see ${message}. Message property is the property defined in our App Class (View Model) and the value of this property will be displayed in the browser. We can use any js expression here. ${ANY_EXPRESSION}

I will try to show you some basic things in Aurelia like data binding and event handling by doing a TODO Application. I will use app.js and app.html for now. I have created 3 properties and 2 methods. Here is the code below for our App Class.

export class App {
  constructor() {
   this.heading = ‘Todos’;
   this.tasks = [];
   this.description = ‘’;
  }
  addTask() {
   if (this.description) {
    this.tasks.push({
     description: this.description,
     done: false
    });
    this.description = ‘’;
   }
  }
  removeTask(task) {
   let index = this.tasks.indexOf(task);
   if (index !== -1) {
    this.task.splice(index, 1);
   }
  }
}

You can see that the first method will add a new task to our tasks property and the second one will remove a task which the user wants to delete. To capture which value user types for description we will use description property. Heading property will be used to show the Header text.

Our View file will look like this.

<template>
  <h1>${heading}</h1>
  <form submit.trigger=”addTask()”>
   <input type=”text” value.bind=”description”>
   <button type=”submit” disabled.bind=”!description”>
     Add   Task
   </button>
  </form>
</template>

I am using h1 tag to show the heading. I have created a form to get input from the user. You can see that input tag has value.bind property and the value is description. Basically thats how we tell aurelia that the description property will be used to store the value from user. This is called 2 way data binding because if we change description from js file it will display that value and If user changes input from browser the value will be changed also. For button disabled.bind will enable/disable this button based on description property. In form tag submit.trigger is binded with addTask method. When user submits this form addTask method will be called. There are many types of html properties in aurelia check out their doc (https://aurelia.io/)to know all the available properties and their behavior.

Now we need to show the list of tasks in a ul tag. We will loop through tasks array using repeat.for. This will repeat the li tag and display the values of a single task. See the code below.

<template>
  <h1>${heading}</h1>
  <form submit.trigger=”addTask()”>
   <input type=”text” value.bind=”description”>
   <button type=”submit” disabled.bind=”!description”>
     Add Task
   </button>
  </form>
  <ul>
    <li repeat.for=”task of tasks”>
      <input type=”checkbox” checked.bind=”task.done”>
      <span css=”text-decoration: ${task.done ? ‘line-through’ : ‘none’}”>
        ${task.description}
      </span>
      <button click.trigger=”removeTask(task)”>Remove</button>
    </li>
  </ul>
</template>

click.trigger is used to handle click event and checked.bind is check/uncheck the check box based on done property of a task. If you run this project a form will be displayed in the browser. If user submits form after writing something in the text box a new task will be created and will be displayed in a list. User can delete a task by clicking remove button. And User can check/uncheck a particular task.

I will try to show you How to use Custom Element (Components) , Aurelia Router, Event Aggregator in later posts. Check out next post about Aurelia Router.