SignNow Integration Template

About this Configuration Guide

Using this guide, you'll explore how the SignNow integration template works. You'll learn how to install the template to your environment and how to build an application from it. Plus, we'll walk you through how to customize your application to fit your needs.

This template has modules and an API (application programming interface) integration. So, we'll also show you how to set up your external SignNow service in Unqork. Then, powered by SignNow's API, you can generate and send a PDF right from your application.

NOTE  You'll need to set up your SignNow account first directly through SignNow. When configuring your template, you'll enter your SignNow credentials to link your application with SignNow. This grants your environment permission to use SignNow.

All images used in this guide are for illustrative purposes only. Images are subject to change without notice. All images were correct at the time of publication.

Overview

This template uses SignNow so you can generate and send eSignature PDFs to end-users from your application.

This is a module integration template. So, when you build an application from this template, your application starts with 5 modules. Also, you'll see a service (integration) added to your environment in Services Administration. The service has a layout prepped for your SignNow credentials. You'll learn more about this later in the article.

Features

With this template, you can:

• Send PDFs for your end-users to sign, right from your application.

• Generate a dynamic document tailored to your recipients.

Requirements

To use this template, you must have a SignNow developer account with valid API credentials.

Adding the Template

Before you can build an application from this template, you must install the template to your environment. Then, you can visit your Library and build an application from your new template.

Adding the Template to Your Environment

To add the template to your environment:

Now, you can now use your newly installed template to create an application!

Creating an Application from the Template

After you've added the template to your environment from Marketplace, you can use it to create an application. This template creates a module-type application.

The application opens in the workspace you specified. You'll land on the Modules tab of your application, which lists all modules of this template.

Your new application should look something like this:

NOTE  When you create an application from the template, your module names will also automatically include the template ID and a time stamp. This is to prevent any duplicate module paths. You're welcome to change module names and module paths at any time. The external service added to your environment will also have a template ID and time stamp.

When you create an application from this template, you'll see a new service added to your Services Administration. This service has the correct service protocol for SignNow. You'll need to update it with your company's SignNow account credentials. (You'll get those credentials when you set up your account directly through SignNow.) We cover how to link your environment to SignNow in the Configuring the Template section.

Here's an example of a SignNow service in Services Administration:

How the Template Works

As the name suggests, a module integration template has modules and an integration. An integration is a service external to Unqork. Here, the service is a SignNow API that generates and sends PDFs for your end-users to eSign. You'll set up your SignNow account directly through SignNow. Then, when you create an application from this template, you’ll get:

• A new service in Services Administration that's prepped for your SignNow credentials.

• A module-type app with 5 modules.

Let's take a look at how the SignNow service and modules work.

How the SignNow Service Works

SignNow is a service that uses API calls to generate and send eSignature PDFs to your end-users. Here are some examples of when you might generate and send a PDF using SignNow:

• You want multiple people to sign sales contracts.
• You want to have an invoice eSigned before you start on a project.
• You need a same-day eSignature on an offer letter.

You'll set this service up directly through SignNow. Then, you'll create an application from the SignNow integration template. The template automatically adds a service to your environment that has the correct service protocol for SignNow. After configuring the service, your application will connect with SignNow to generate and send PDFs to your signers.

How the Sign Tagged Document Template Module Works

The Sign Tagged Document Template module is the only user-facing module in this template. This module is where you or your end-user will fill out fields and add signers.

Let's look at how this process works. You'll fill out the fields in Express View and click the Create Document and Send Invite to Sign button. Then, this module calls the Create and Send Document Orchestrator (API) module. The Orchestrator (API) module orchestrates the rest of the functions in this template.

Once the behind-the-scenes API modules generate and send your PDF to the signers, the Express Viewmodule populates with a Document ID. This ID is a unique identifier for the generated PDF in SignNow. If you want to check the status of your PDF in SignNow, you'll need this Document ID.

NOTE  This module serves as somewhat of a placeholder. In your actual application, you'll likely get the signers' information from elsewhere in the application. This module gathers all the necessary information in one place. So, you can see how the template takes information and outputs it to SignNow.

Here's how the Signed Tagged Document Template module looks in Express View:

And here's how it looks in the Module Builder:

Once you fill out the fields in Express View and click Create Document and Send Invite to Sign, the module fires the ruleSendSignNow Decisions component. The Decisions component works with the dwfDuplicateSigner Data Workflow to check for duplicate signers. If there are duplicate signers, the initError Initializer fires, showing a pop-up modal prompting the end-user to remove the duplicate signer. If there aren't any duplicate signers, the pluginSignNow Plug-In fires, calling the Orchestrator (API) module. When the entire process finishes, the SignNow Document ID maps back to this Sign Tagged Document Template module. The initSuccess Initializer fires, showing a pop-up modal with the modalDocumentSuccess Panel's Success message.

TIP  You may notice that the Success message says to check your inbox. This is because we assume you'll use the template in a non-production environment and send emails to yourself rather than real signers. Once you release your application to real end-users, make sure to update your Success message.

How the Create and Send Document Orchestrator (API) Module Works

The Create and Send Document Orchestrator (API) module works as an aid to the other 4 modules in this template. Its main function is to communicate information between the front-end module and back-end modules. The Orchestrator (API) module lets the end functions of this template each live in their own module. A great thing about this setup is that it's easy to troubleshoot or reuse the modules.

NOTE  For simplicity's sake, we'll call this module the Orchestrator (API) module throughout this guide.

In Express View, your end-user enters information in the Sign Tagged Document Template module. This information maps to the Orchestrator (API) module. The Orchestrator (API) module communicates that information to the Generate PDF (API) module. Once the Orchestrator (API) module receives the PDF, it sends the PDF over to the Upload Tagged Document (API) module. The Orchestrator (API)'s last call is to the Invite Signers (API) module. Then, the Orchestrator (API) module passes the Document ID back to the Express View of the Sign Tagged Document Template module.

Here's how the Orchestrator (API) module looks in the Module Builder:

You'll see many Hidden components in this configuration. The fieldA, fieldB, fieldC, and signers Hidden components map from the Sign Tagged Document Template module. So, the information added to the Sign Tagged Document Template module in Express View passes to these 4 Hidden components.

Let's take a peek at how these components work together. The initNewSubmission Initializers fires the pluginGeneratePdf Plug-In, which calls the Generate PDF (API) module. The Base64 of the generated PDF outputs to the document Hidden component. Once the pluginGeneratePdf finishes its job, it fires the pluginUploadDocument Plug-In, which calls the Upload Tagged Document (API) module. Next, the pluginInviteSigners Plug-In fires, calling the Invite Signers (API) module. Once SignNow sends the generated PDF to the signers, SignNow's Document ID outputs to the documentId Hidden component.

How the Generate PDF (API) Module Works

The next module is the Generate PDF (API) module. This module takes the information gathered in the Sign Tagged Document Template module and builds a PDF.

The Generate PDF (API) module calls a transform, which has a simple HTML and Nunjucks layout for the PDF. The template's default PDF includes mapping to the Text Fields. Also, to help you out, there's text explaining how to best format the PDF for SignNow’s standards. The PDF generates using what's called SignNow text tags.

NOTE  To learn more how SignNow's text tags work, go to: https://help.signnow.com/docs/how-to-generate-text-tags-on-a-document.

The transform outputs a Base64 version of the PDF to the document Hidden component. From there, the Generate PDF (API) module sends the PDF back to the Orchestrator (API) module.

Here's how the Generate PDF (API) module looks in the Module Builder:

Let's look at how the components play together in this module. The initNewSubmission Initializer fires the pluginGeneratePdf Plug-In, which calls the signNowTextTagPdf transform. The pluginGeneratePdf fires the calcDocument Calculator component. This Calculator sets the Base64 string of the PDF to a format that SignNow accepts. The Calculator then outputs this formatted PDF to the document Hidden component, which sends back to the Orchestrator (API) module.

Here's what the signNowTextTagPdf transform looks like:

The PDF transform in this module is a placeholder. You'll want to customize this transform for the document you want signed. We'll cover how to do that in our Customizing the Template section.

NOTE  SignNow uses text tags to mark the location of a certain action. To learn more about SignNow's text tags, go here: https://help.signnow.com/docs/how-to-generate-text-tags-on-a-document.

How the Upload Tagged Document (API) Module Works

The Upload Tagged Document (API) module has a pretty straightforward job. First, it receives the PDF from the Orchestrator (API) module. Then, it uses a SignNow API call to upload the generated PDF to SignNow.

Here's how the Upload Tagged Document (API) module looks in the Module Builder:

Let's take a look at how the components of this module work together. The Orchestrator (API) module sends the Base64 of the PDF to this module's document Hidden component. The initNewSubmission Initializer triggers the pluginUploadDocument Plug-In component. This Plug-In uses the SignNow service to upload the generated PDF. SignNow uses the PDF's SignNow text tags to extract the signature fields. Once your PDF uploads to SignNow, the Document ID passes to the documentId Hidden field. This ID maps back to the Orchestrator (API) module to help with the next steps in the process.

How the Invite Signers (API) Module Works

The Invite Signers (API) module does exactly what its title suggests. It sends the signer information to SignNow. SignNow then sends an invitation for the signers to eSign the generated PDF. Then, this Invite Signers (API) module sends the PDF's Document ID back to the Sign Tagged Document Template module.

Here's how the Invite Signers (API) module looks in the Module Builder:

Let's take a look at how the components of this module work together. The documentId Hidden component holds the Document ID of the PDF uploaded to SignNow. The signers Hidden component holds the signers entered in Express View in the Sign Tagged Document Template module. The initNewSubmission Initializer triggers the pluginInviteSigners Plug-In component. This Plug-In uses the SignNow service and inviteSigners pre-request transform to prep your request for SignNow. Once your envelope sends to your signers, the DocuSign Envelope ID passes to the envelopeId Hidden field. This ID maps back to the Orchestrator (API) module, which sends the ID to the Create Envelope Template module.

Here's what the inviteSigners transform looks like:

The transform's contents already adhere to SignNow's standards. There's a section for subject and message where you can customize the subject and message of the email that invites signers to eSign the PDF.

NOTE  Remember that SignNow uses text tags. To learn more about SignNow's text tags, go to: https://help.signnow.com/docs/how-to-generate-text-tags-on-a-document.

Configuring the Template

To get your application up and running, you have to set up your SignNow service in Services Administration. Most of the setup work takes place in your SignNow account, which you'll set up through SignNow. So, we'll walk you through what to do in your Unqork environment. Then, we'll help point you in the right direction for your SignNow account.

Configuring the SignNow Service in Services Administration

To configure the SignNow service, you'll need to set up an Integration App in DocuSign to get a few pieces of information. Then, you'll do a quick and easy update in Services Administration.

NOTE  We've set up this template to work with the SignNow Developer Environment (sandbox). If you want to connect your production environment to SignNow, you'll need to update your SignNow service in that environment.

To access Services Administration:

Next, you'll need to find and update the SignNow service with your SignNow credentials:

And, that's it! Now that you've connected your environment to your SignNow account, you're ready to use your new application.

Customizing the Template

You'll definitely want to make this template your own. Importantly, you'll want to customize the PDF the way you want it. By default, the template's PDF is a placeholder. The text in the PDF explains how a SignNow PDF works. Also, the entry fields in the Sign Tagged Document Template module are example fields. Here are some common customizations for the SignNow template:

• Change the text in the PDF.

• Edit the fields you want end-users to fill out.

• Update the subject line and message text of the email to end-users.

Editing the Text in the PDF

The text in the PDF transform is regular HTML with some limitations since it's a PDF page and not a webpage. You can customize your PDF using HTML and Nunjucks.

To change your PDF's text:

2.

Click the (Transforms) button in the left side menu bar.

Editing the Entry Fields

By default, your Express View module has 3 Text Field components, fieldA, fieldB, and fieldC. When your end-user visits your application, they enter their information in those fields. Then, the PDF generates with the information they entered. You'll likely want to change these fields. For instance, say you want to change the fields to First Name, Last Name, and Job Title. You'll make this change in 3 modules and 1 transform.

NOTE  In these steps, we'll walk you through changing the fields to First Name, Last Name, and Job Title. Obviously, you can change them to whatever works for you.

Updating the Fields in the Sign Tagged Document Template Module

First up is the Sign Tagged Document Template module. This is where you'll change the Property IDs and Label Texts of the 3 Text Field components. You'll also update the pluginSignNow Plug-In component.

To update each Text Field component:

2.

Using the toolbar, click the (Settings) button.

To update the Plug-In component:

2.

Using the toolbar, click the (Settings) button.

Updating the Mapping in the Orchestrator (API) Module

You have 2 changes to make in the Create and Send Document Orchestrator (API) module. First, you'll update the fieldA, fieldB, and fieldC Hidden components. Then, you'll update the pluginGeneratePdf Plug-In component.

To update each Hidden component:

2.

Using the toolbar, click the (Settings) button.

To update the mapping in the pluginGeneratePdf Plug-In component:

A 5-button toolbar appears above the component on hover-over.

2.

Using the toolbar, click the (Settings) button.

Updating the Mapping in the Generate PDF (API) Module

The changes you'll need to make to the Generate PDF (API) module are much like what you did in the Orchestrator (API) module. First, you'll update the fieldA, fieldB, and fieldC Hidden components. Then, you'll update this module's pluginGeneratePdf Plug-In component.

To update each Hidden component:

2.

Using the toolbar, click the (Settings) button.

To update the mapping in the pluginGeneratePdf Plug-In component:

2.

Using the toolbar, click the (Settings) button.

The next and final step is to update mapping in the signNowTextTagPdf transform.

Updating the Mapping in the signNowTextTagPdf Transform

By default, the signNowTextTagPdf transform maps to the template's original placeholder fields. So, you'll need to update the transform to make it map to your updated fields.

2.

Click the (Transforms) button in the left side menu bar.

54
55
56
57
58
First Name: {{ data.firstName }}
<br>
Last Name: {{ data.lastName }}
<br>
Job Title: {{ data.jobTitle }}

Updating the Subject Line and Message of the Email

By default, the subject line of the email that sends to signers is Please sign this document. Changing that subject is easy. You'll adjust a single line of your inviteSigners transform. You can also change the default message of the email.

2.

Click the (Transforms) button in the left side menu bar.

Testing the Template

Have you configured your SignNow service and made the necessary updates to your modules? If so, it's time for the fun part: try it out! Open the Sign Tagged Document Template module in Express View. Fill out the fields as if you're an end-user, adding your own information as a signer. Then, click Create Document and Send Invite to Sign at the bottom of the page. Check your inbox for your eSignature PDF.

Removing the Template

There are 3 steps to removing the template, and these can happen in any order:

• Uninstall the template from your environment.

• Delete the application you created from the template.

• Remove the SignNow service from your environment.

If you think you'll want to reference the SignNow service in the future, you can leave it in your environment.

Removing the Template from Your Environment

You might need to clean your environment and remove unused templates. The Unqork Library makes this easy. To uninstall a template from your environment:

You can visit the Marketplace and reinstall the template at any time.

NOTE  What if you have an existing application built from this template and then uninstall the template from your environment? Your existing application remains unaffected. Also, it no longer has any ties to the template. So, let's say you reinstall a newer version of the template in the future. You can rest assured that the installation doesn't impact your existing application.

Deleting Your Application

If you no longer need the application you created from your template, you can delete it. To delete your application:

Removing the SignNow Service from Your Environment

To remove your SignNow service from your environment: