Common tasks the TS/JS SDK

Most e-signature developers will need to use (and possibly reuse) a template, document or group for one of their automations. The code that follows is aimed at getting you started with simple implementations to perform common tasks.

If you haven't already you should follow the Getting Started guidance.

Send an Existing Template

In a node project with the legalesign-sdk-js installed include the following code

import { Legalesign, SendOptions, Recipient } from "legalesign-sdk-js";

const lesign = new Legalesign({
  organisationId: "b3XXXXX",
  options: {
    apiUser: "api@legalesign.com",
    apiPassword: "yourapipassword",
  },
});

const recipient: Recipient = {
  email: "recipient@legalesign.com",
  firstName: "Sidney",
  lastName: "Lawrence",
};

const sendOptions: SendOptions = {
  title: "SDK Test Simple Send",
  groupId: "Z3GROUPID",
  templateId: "dHBTEMPLATEID",
  recipients: [recipient],
};

const response = await lesign.sender.send(sendOptions);

You can find a version of this in the legalesign-sdk-js-test project.

Note that in this version we assume that the groupId and the templateId that you're using are static so you can simply look up the ids through (console.legalesign.com). If this isn't the case then you might need to use the SDK to get the lists of templates or groups available to your API user. The example also assumes that you've locked the template - otherwise there is the chance that alterations may have made it invalid to send.

In order to find out if the sending process succeeded you'll need to monitor the status of the document and the events sent back to you. Depending on your integration the example code may be enough for you, but the next example will show you how to check on a document.

Retrieve Document Details

This item is so common it falls into the "we've made a shortcut for that" category. You'll find that the same is true of almost every basic object in the GraphQL api. Here's some code that will retrieve the details (in JSON) of a document given its API ID (remember you can pull sample IDs by looking at document details in the Console application).

  const result = await lesign.selector.getDocument('ZG9jYTc0YmMzMGUtZWZhYj0xMWVmLWJiYjUtMDZlNDc2YTA3NTY5');

  if(result?.status === 'completed') doMoreWork();

Receive Events

The GraphQL API provides a websocket service that you can monitor for events about your group or user. These can be particularly helpful if you want to take action as soon as possible, rather than poll the system every ten minutes.

Here are some of the commonly used events that can be captured:

• documentCreated
• documentSent
• documentCompleted

You'll find more details under the documentation for the subscriber sub-module but be aware this is intermediate to advance topic. Here's an example which looks for an event to test if the document upload and creation has finished (remember to intialize your Legalesign object);

   const templateId = await lesign.factory.createTemplate("z9kjhsadk=j", "SDK Auto-Test Template");

    if (!templateId) done("Unable to create Template record in this group.");

    const options: FileOptions = {
      fileName: "SDK Upload Test",
      path: `${__dirname}/sample.pdf`,
      fileType: "template",
      id: templateId,
      fileExtension: "pdf",
    };

    // Prepare the function we want to handle events
    lesign.subscriber.listen((response: FileEvent | null) => {
      try {
        if (!response) {
          done("No data returned.");
          return;
        }

        lesign.subscriber.disconnect();
        const fe: FileEvent = response as FileEvent;

        if (fe.systemMessage === "UPLOADOK") done();
      } catch (error) {
        done("Response not truthy");
      }
    });

    // Connect to the user subscription channel
    lesign.subscriber.connect();

    console.log(options)

    // Send our new template document to the Legalesign platform
    lesign.uploader.upload(options);

Reuse a Draft

Often you'll already know a lot of the details that you want to apply to your send task. The easiest way to store this so that they can be altered /without changing your code later/ is to create a draft object inside the Legalesign platform. This is a JSON version of all the parameters required to send one or more documents with all the recipients and prefilled fields which it might require.

To see how this is done go into console.legalesign.com and start the preparations to send your target template. Before sending click in the top left corner and choose Save As Draft. This will take all the information that you've applied and stash it away. The console will take you to the Drafts listing and your new draft will appear once it has been generated by the system.

Here's how we might do the same thing with the SDK.

// Create an instance of the Legalesign SDK
const lesign = new Legalesign({
  organisationId: "yourorgid",
  options: {
    apiUser: "yourapiuser@yourcomp.com",
    apiPassword: "yourapipassword",
  },
});

// send a file to Legalesign for processing - note that this goes through
// a lot of security and type checking so it may take some time.
const fileUUID = await lesign.uploader.upload({
  path: `${__dirname}/draft.json`,
  fileName: `SDKTEST${new Date().toISOString()}.json`,
  fileType: "draft",
  fileExtension: "json",
});

The key thing to remember here is that a Draft is really just well-formed JSON that fits the type SendOptions. So it may be very useful for automation to pull a pre-generated set of SendOptions saved as a Draft and use them in a send process. This would allow changes to be made to the settings and template without changing the automation code.

import { SendOptions } from "legalesign-sdk-js";