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:

1. Click Marketplace at the top right of the Unqork Designer Platform.

NOTE  You can also access the Marketplace at any time by visiting https://marketplace.unqork.io.

2. Enter SignNow in the Search the Marketplace field.
3. Click on the SignNow tile.
4. Click Install to Environment.
5. Click Install Template.

NOTE  If you aren't logged in, you'll see a field for Environment URL and a Login button. Enter your environment's URL where you want to install the template. For example: [environmentname.unqork.io]. Click the Login button. Then, return to step 4 and click Install to Environment again. Follow the remaining steps as listed.

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.

1. Click Library at the top right of the Unqork Designer Platform.
2. Find the SignNow template tile.
3. Click Create App from Template.
4. Choose the destination workspace from the Workspace drop-down. This is where your application will live once created.
5. Enter your unique App Name. The App Path auto-fills as you type your App Name.
6. If you want a different App Path, enter it in the App Path field.
7. Select a preview style from the Style drop-down. A style specifies your application’s appearance in Express View. If left blank, your application uses your environment's default style.

NOTE  You'll notice the App Type and App Entrypoint are grayed out. The template automatically takes care of these for you!

8. Click Create App.

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 Editor:

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 Editor:

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 Editor:

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 Editor:

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 Editor:

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:

1. Click the Settings drop-down at the top right of the Unqork Designer Platform.
2. Click Administration.
3. Under Integration, select Services Administration.

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

1. Scroll to the bottom of your Active Services list.
2. Click your SignNow service.

NOTE  The title should be something like this: signNow - 5fe24d6bec6d7e0231f4bf34 1.0.0 2021-04-29T17:54:16.987Z. What if your environment has more than one SignNow service? Here's a trick. Look for the service with the same template ID and time stamp as the modules in the application you created from the template.

3. Scroll to the top of the page.
4. Enter your Client ID in the Client ID field.
5. Enter your Client Secret in the Client Secret field.
6. In the Username field, enter the username you use when signing in to SignNow.
7. In the Password field, enter the password you use when signing in to SignNow.
8. Click the Capture request & response bodies checkbox if you want to capture this information.

NOTE  Enabling this checkbox logs the details (bodies) of the call's request and response. If you have a failed API call, the log's request body and response body give you information on why the call failed. Or, maybe the API request was successful, but the data sent wasn't handled correctly. The request body and response body show you the details of your calls. The service logs save to Unqork's database and you can query the logs at any time.

9. Click Save Changes.

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:

1. Open your Generate PDF (API) module in the Module Editor.
2. Click the (Transforms) button in the left side menu bar.
3. Click the signNowTextTagPdf tile under Active Transforms.
4. Make the changes to your PDF text.

WARNING  Make sure to keep the SignNow text tags. You can learn more about SignNow's text tagging here: https://help.signnow.com/docs/how-to-generate-text-tags-on-a-document.

5. Click Save Changes.

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:

1. Hover over the Text Field component.
2. Using the toolbar, click the (Settings) button.
3. Enter the Property ID and Label Text for each Field Text component as follows:
Property ID Label Text

firstName

First Name

lastName

Last Name

jobTitle

Job Title

NOTE  By default, each Text Field component has Helper Text that says Example document field one, Example document field two, and so on. This text shows under the entry field in Express View. When editing your Text Field components, you can change or delete this Helper Text.

4. Save each component as you update it.

To update the Plug-In component:

1. Hover over the pluginSignNow Plug-In component.
2. Using the toolbar, click the (Settings) button.
3. Upate the Inputs table as follows:
Property ID Mapping

signers

data.signers

firstName

data.firstName

lastName

data.lastName

jobTitle

data.jobTitle

4. Click Save.
5. Save your module.

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:

1. Hover over the Hidden component.
2. Using the toolbar, click the (Settings) button.
3. Enter the Property ID and Label Text for each Hidden component as follows:
Property ID Label Text

firstName

First Name

lastName

Last Name

jobTitle

Job Title

4. Save each component as you update it.

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

1. Hover over the pluginGeneratePdf Plug-In component.

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

2. Using the toolbar, click the (Settings) button.
3. Update the Inputs table as follows:
Property ID Mapping

firstName

data.firstName

lastName

data.lastName

jobTitle

data.jobTitle

4. Click Save.
5. Save the module.

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:

1. Hover over the Hidden component.
2. Using the toolbar, click the (Settings) button.
3. Enter the Property ID and Label Text for each Hidden component as follows:
Property ID Label Text

firstName

First Name

lastName

Last Name

jobTitle

Job Title

4. Save each component as you update it.

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

1. Hover over the pluginGeneratePdf Plug-In component.
2. Using the toolbar, click the (Settings) button.
3. Update the last 3 rows of the Inputs table as follows:
Property ID Mapping

firstName

data.firstName

lastName

data.lastName

jobTitle

data.jobTitle

4. Click Save.
5. Save the module.

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.

1. Open the Generate PDF (API) module in the Module Editor.
2. Click the (Transforms) button in the left side menu bar.
3. Click the signNowTextTagPdf tile under Active Transforms.
4. Find lines 54-58 of the transform that reference the Field Text components.

NOTE  These line numbers assume you haven't yet changed the PDF text in the transform. If you've already customized your PDF text in the transform, great job! Simply find and replace the transform's reference to Field A, Field B, and Field C.

5. Replace lines 54-58 with the following:
Copy
 
First Name: {{ data.firstName }}
<br>
Last Name: {{ data.lastName }}
<br>
Job Title: {{ data.jobTitle }}
6. Click Save Changes.
7. Save the module.

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.

1. Open the Invite Signers (API) module in the Module Editor.
2. Click the (Transforms) button in the left side menu bar.
3. Click the inviteSigners tile under Active Transforms.
4. Enter the email subject you want after "subject": in the transform's body. Make sure to keep your text in quotation marks. For example, you could enter: "subject": "You've successfully applied. Woohoo! Please sign this document."
5. Enter the email message you want after "message" in the transform's body. Make sure to keep your text in quotation marks. Also, make sure to keep the '\''Sign Now'\'' text as it is. This creates a clickable link in the email to your end-user.

6. Click Save Changes.
7. Save the module.

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:

1. At the top right of the Unqork Designer Platform, click Library.
2. Find the template to uninstall.
3. Click the ellipsis (...) in the template tile header.
4. Click Uninstall Template.
5. Click Yes, Uninstall in the confirmation modal.

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:

1. Navigate to the Apps tab from an open workspace.
2. Find the application to delete.
3. Click the ellipsis (...) in the app tile header.
4. Click Delete.
5. Retype the provided text.
6. Click Yes, Delete.

Removing the SignNow Service from Your Environment

To remove your SignNow service from your environment:

1. Click the Settings drop-down at the top right of the Unqork Designer Platform.
2. Click Administration.
3. Under Integration, select Services Administration.
4. Scroll down and select the SignNow service you want to delete from the Active Services list.
5. Click the Delete link. You’ll find this above the Active Services list.
6. At the Delete message, click OK.
7. At the Success message, click OK.