NDA Agreement Signing Use Case with Google API connectors

Video Walk through of this Tutorial

If you would like to see this "NDA Agreement Signing Use Case using Google API connectors" in action, click this video below.

General description

This use case shows the user how to use ProcessMaker I/O in combination with Google services. Both software programs provide the tools that allow the user to build effective processes while satisfying a variety of business needs.

This example shows the user how to create and manage a Google document within sets of Google connectors.

To work with this MVP example, click on the top navigation tab labeled “NDA Example” on the Examples portal.

The top navigation will present a series of steps available for the selected example.

For this example you will need a Google Drive account, some templates in the account, and access tokens to allow the process to read and write files to your Google Drive. These tokens and settings should be put into the BPMN file in advance before importing the process. Please refer to the process documentation for more details.

During process execution you can monitor your Process Instances and the status of these instances using “Process List” page.

Getting started with Use Case

How to Launch an Environment* of ProcessMaker I/O

*ProcessMaker I/O is an always on service that is running in the cloud, so in this document an Environment refers to a separate installation of ProcessMaker I/O being spun up in the ProcessMaker I/O cloud on demand using our internal container and on demand scaling technology stack.

If you don't have a ProcessMaker I/O environment yet, please do the following:

  1. Go to the [Environment page.] (https://portal.processmaker.io/dash/core)
  2. Click Create an Environment and follow the instructions provided.

If you already have a ProcessMaker I/O environment, please do the following:

  1. Launch an environment of ProcessMaker I/O on the [environment page.] (https://portal.processmaker.io/dash/core)
  2. Copy/remember the environment URL link as this will be required later as your-environment-url, (as example "your-environment-url" is "MYENVIRONMENT.api.processmaker.io", where "MYENVIRONMENT" is your "Processmaker I/O environment name")

Start with a NDA Use case

  1. Click on Form examples link
  2. Switch to the NDA tab on the left menu
  3. Download GoogleExample_updated.bpmn on your computer
  4. Click on Import tab on the Environment details and upload BPMN file from your PC.
  5. Go to the Process list on the Environment details. You should see two processes. These can be deleted by clicking on their ID button, if necessary.

Set Up Credentials for Google Drive

  1. Log into your Google Account and go to this website: https://console.developers.google.com/
  2. Create a new project by clicking the "My project" dropdown at the top. Alt text here After you enter a name, it takes a few seconds before the project is successfully created on the server. Make sure you have the project selected at the top.
  3. Then go to Library and click on "Drive API" under "Google Apps APIs". Alt text here
  4. Enable the Drive API. Alt text here
  5. Go to Credentials and click on the tab "OAuth Consent Screen". Fill in the "Product name shown to users" field and save it. Don't worry about the other fields. Alt text here
  6. Create the Credentials with OAuth.
  7. Go back to Credentials, click the button that says "Create Credentials" and select "OAuth Client ID". Alt text here
  8. Choose "Web Application" and give it a name.
  9. Enter your authorized redirect URIs, preferably your test URL (http://mysite.dev) and your production URL (https://mysite.com); or, create a separate production key later. Also add https://developers.google.com/oauthplayground to your redirect URLs temporarily, because you will need to use it in the next step. Alt text here
  10. Click Create and take note of your Client ID and Client Secret.
  11. Get your Refresh Token Now head to https://developers.google.com/oauthplayground.
    Make sure you added this URL to your authorized redirect URIs in the previous step.
  12. In the top right corner, click the settings icon, check "Use your own OAuth credentials," and paste your Client ID and Client Secret. Alt text here
  13. In Step 1 on the left, scroll to "Drive API v3", expand it, and check each of the scopes. Alt text here
  14. Click "Authorize APIs" and allow access to your account when prompted.

    Please note, during this step your account must be pre-approved by Google to use Oauth keys. You must fill in the form https://support.google.com/code/contact/oauth_app_verification, if you are going to use the app only for personal verification purposes please refer to the form section Apps for testing or personal use only.
  15. When you get to Step 2, check "Auto-refresh the token before it expires" and click "Exchange authorization code for tokens". Alt text here
  16. When you get to step 3, click on step 2 again, and you should see your refresh token. Alt text here

Set Up your Form

  • Copy the NDA form request to your Google drive
  • Open this Form in the editor
  • Go to the script editor and paste the following code:
function myFunction(e) {
 var host = "pm instance host";
 var token = "access_token_for_instance";
 var datamodel={};
 //Setting up google drive credentials
 datamodel.client_id = "google_drive_client_id";
 datamodel.client_secret = "google_drive_client_secret";
 datamodel.refresh_token = "google_drive_refresh_token";
 var headers =
     {
       "content-type": "application/json",
       "Accept": "application/json",
       "authorization": "Bearer "+token
     };
 var trigger_event_url = "https://"+host+"/api/v1/processes/"+"Requester"+"/events/"+"NDA%20form%20request"+"/trigger";
 var formResponse = e.response;
 var itemResponses = formResponse.getItemResponses();
 var replacement_array = {};
 for (var i=0; i<itemResponses.length; i++) {
   var key = itemResponses[i].getItem().getTitle();
   if (key == 'Name') {
     datamodel.RequesterName = itemResponses[i].getResponse();
     replacement_array.RequesterName = datamodel.RequesterName;
   }
   if (key == 'Address') {
     datamodel.RequesterAddress = itemResponses[i].getResponse();
     replacement_array.RequesterAddress = datamodel.RequesterAddress;
   }
   if (key == 'E-mail') {
     datamodel.RequesterEmail = itemResponses[i].getResponse();
   }
   if (key == 'Passport or ID number') {
     datamodel.RequesterID = itemResponses[i].getResponse();
     replacement_array.RequesterID = datamodel.RequesterID;
   }
   if (key == 'Phone number') {
     datamodel.RequesterPhone = itemResponses[i].getResponse();
     replacement_array.RequesterPhone = datamodel.RequesterPhone;
   }
   if (key == 'Choose NDA template') {
     datamodel.template = itemResponses[i].getResponse().toLowerCase();
   }
   if (key == 'Company name (for Customer)') {
     datamodel.RequesterCompanyName = itemResponses[i].getResponse();
     replacement_array.RequesterCompanyName = datamodel.RequesterCompanyName;
   }
  }
 datamodel.replacement_array = JSON.stringify(replacement_array);
 datamodel = JSON.stringify(datamodel);
 //Making our request body
 var data = {
   'data': {
     'type':'data_model',
     'attributes': {
       'content':datamodel
     }
   }
 };

 data = JSON.stringify(data);
 Logger.log(data);
 var options =
     {
       "content-type": "application/json",
       "method": "POST",
       "headers": headers,
       "payload": data
     };


 var response = UrlFetchApp.fetch(trigger_event_url, options);
 Logger.log(response.getContentText());
}

Substitute all credentials in the script with your instance credentials and Google drive.

Setup project trigger

Click Edit > Current project triggers and create a trigger using the existing myFunction(e) to submit the event. Google will display a notice requesting new permissions - accept them.

Work with the Template File

Download Example_template.docx

This is the template with variables. Download it to the root of your Google drive.

Process Execution

Starting the process:
After all steps are done, you can open your Google Form and submit it to start the process, or start the process manually by calling the eventTrigger() method using an SDK or requesting the endpoint and passing all the fields presented in the Google script to datamodel: "http://"++"/api/v1/processes/"+"Requester"+"/events/"+"NDA%20form%20request"+"/trigger" In the list of processes, you will find the newly created process instances with their respective statuses.
Finishing the process:
To finish the process, go to Check NDA status in the menu, and there you can find links to the new files generated by example_template.docx. Choose to either Approve or Decline your instance. To clear all data from your instance (with all processes), just go to the process list in the main menu of the NDA example and click on all existing processes.

Connectors

Google

GoogleDrive/GDriveConnector

Starts the Google drive connector Service Task with the following required input parameters:

-Method - string variable (read, write, update, delete). The method can be:

  • write - upload file
  • read - download
  • update - renaming files
  • delete - delete file with Google Drive

-Google Drive access credentials:

  • client_id
  • client_secret
  • refresh_token

Write method (use GoogleDrive->create method):

Required input parameters for the write method, except main:

  • file - file content coded in base64
  • filename - full filename with extension

Additionally, you can set the folder_name parameter if you need to put the file into a folder (the folder will be created automatically)

In the output parameters, you should set the following variables:

  • file_id - to manipulate with uploaded file
  • folder_id

Read method (use GoogleDrive > get method):

Required input parameters for the write method, except main:

  • file_id - ID of the file on Google Drive to read

In the output parameters, you should set the following variables:

  • file_from_drive - file content from the drive, coded in base64
  • filename_from_drive - full filename from the drive with the extension

Additionally, you can set mimetype_from_drive and filesize_from_drive

Update method (use GoogleDrive > create method):

Required input parameters for the write method, except main:

  • file_id - ID of the file on Google Drive to rename

Delete method (use GoogleDrive > delete method):

Required input parameters for the write method, except main:

  • file_id - ID of the file on Google Drive to delete

GoogleDrive/GDPermissionConnector

The Permission connector for Google Drive supports two methods: create and delete.

Required main parameters:

-Method - string variable (create, delete):

  • write - creates the file permission with Google Drive.
  • read - deletes the file permission with Google Drive.

-Google Drive access credentials - required for all methods to start working with the drive client:

  • client_id
  • client_secret
  • refresh_token

Create method (use GoogleDrivePermissions > create method):

Required input parameters, except main:

  • permission_list - Array of users with roles and types in JSON format, for example:

     [
      {
      "sendNotificationEmail":false,
     "role":"reader",
     "type":"user",
     "emailAddress":"oleg@processmaker.com"
      },
     {
     "sendNotificationEmail":false,
     "role":"reader",
      "type":"user",
     "emailAddress":"egor@processmaker.com"
      }
     ]
    

Supports the following roles: organizer, owner, writer, commenter, reader.

Can be shared with: user, group, domain, anyone.

In the output parameters, you should set the following variables:

  • permission_ids - IDs of the permission to manipulate, if needed
  • share_link - link to access the file on Google Drive

Delete method (use GoogleDrivePermissions > delete method):

input parameters, except main:

  • file_id - file ID on Google Drive
  • permission_ids - IDs of the permissions to delete, note that you can't delete the permission from the owner of the file.

GoogleDrive/GDReaderConnector

Triggers the start event with data to generate the template and credentials for the Google Drive SDK.

Google Reader Connector (use GoogleDrive > get method) Reads files (file content) from Google Drive using the full name (with extension).

Required input parameters:

  • file_name - full filename with extension.

Google Drive access credentials - required for all methods to start working with the drive client:

  • client_id
  • client_secret
  • refresh_token

In the output parameters, the following variable should be set:

  • file_content_from_drive - file content coded in base64.

Doc

Doc/HTMLConnector

Runs the generate docs Service Task with the required input parameters:

  • document_format (DOCX, ODT, HTML, PDF, RTF)
  • document_template (template in HTML with variables available in datamodel)
  • Can also be set with the parameters of the document in JSON format
    • {"orientation": "landscape", "size":"A5","filename":"test"}

Output parameters:

  • file - file content coded in base64
  • filename - full filename with extension
  • mimetype - mimetype added automatically:
    • 'docx' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    • 'odt' => 'application/vnd.oasis.opendocument.text',
    • 'rtf' => 'application/rtf',
    • 'html' => 'text/html',
    • 'pdf' => 'application/pdf'

Doc/DocxConnector

DocxConnector is used to generate documents in docx format using templates in docx.

Required input parameters:

  • docx_template - file content of the template coded in base64, filled in with the variables in the following way:
    • ${variable_name}
  • replacement_array - array of replacements in JSON format, for example:
    • {"variable_name":"value", "variable_name1":"value1"}

In the output parameter, the following variable should be set:

  • {docx_result} - resulting file content, coded in base64 and filled in with the values of each variable.

Email

SendEmailConnector

Sends an email message to the requester.

Required input parameters:

  • to - requester email
  • Body - email text (Notification to requester)
  • To_name - requester name
  • Subj - email subject
  • Options - options to log mail driver actions to the log file

No output parameters required

NDA Agreement Signing Use Case

Process Description

The steps of this use case are as follows:

  1. The user wants to do business with another company. The second company requires an NDA form as part of its standard procedures. It could also be an employee or new hire that is requesting to sign an NDA with the company. Requesting an NDA requires the user to fill out a Request/Order form on a website or imaginary company portal.
  2. The company receives the request.
  3. The company generates an NDA document based on the docx template if the NDA is for a new customer or partner (business). If the request comes from a potential employee, then the process will take a different path and the NDA will be generated based on an html template.
  4. The company shares the generated document with the requester by sending an email to the requester (permission is 'Only for comment').
  5. The user reviews the NDA and signs the document and then sends the email to the company with the signed and scanned NDA in the attachment (external process).
  6. When the company gets the reply from the requester, the document will be renamed with the mark "Signed" or "Unsigned" according to the status.

Process Scheme

Alt text here

Tasks

Task Type Connector/Form Method
NDA Request Form Start event Request form
Read Template Service task Google/GDReaderConnector ReadFile
Generate NDA Service task DocxConnector
Generate NDA based on HTML Service task HTMLDocConnector
Upload File to GDrive Service task Google/GDriveConnector createFile
Set Permission Service task Google/GDPermissionConnector ShareFile
Send Email with Generated NDA Service task SendEmailConnector
Check NDA Status User Task JQuery form
Add Mark Signed Service Task Google/GDriveConnector RenameFile
Add Mark UnSigned Service Task Google/GDriveConnector RenameFile
Send Email with Signed NDA Service Task SendEmailConnector
Add NDA to Google Drive Service Task CDConnector

Forms

Manual Request (Google Form)

This is a Google Form implementation to trigger the “Manual Request” Event.

! Please note - this form is just a sample and will require manual adjustment on your Google Forms account. To use the form you need to copy the form to your Google Forms account, change API endpoint URL and authorization token in Google Script (attached to the form), and set-up form triggers.

Field ID Field Label User Filled Field Type Field Description
CompanyName Company name Y String Requester Company name
RequestorFullname Requester Full name Y String The full name of the requester
RequestorEmail Requester Email Y String The email of the requester
RequestorPhone Requester Phone Y Integer The phone of the requester
RequestorID Requester ID Y String Passport or ID number
RequestAddress Requester Address Y String The address of the requester
Business/Employee Templatetype Y Multichoice Template type

Check NDA status form

This is a jQuery implementation to support the user task “Check NDA status”. It will find the delegated user task data for a specified user (refer to the selected user on top-right) and pre-fill form inputs. Please note the NDA Example process delegates “Check NDA status” user task to a user named “Test”, so be sure the proper user is selected on top-right of the page.

  1. Choose the requester email from the list of requesters
  2. Get the Google Document ID
  3. Click the "Signed" or "Unsigned" button

Messages

All messages are emailed and covered by the Email connector.

Message Title Task Content
Notification to requester Send email Hello {{RequesterFullname}},
Thank you for your interest in our company.
Your copy of the NDA has been shared via your email {{RequesterEmail}} and is located here {{RequesterGoogleDocLink}}
Please review and sign the NDA, then we will proceed with your data.
Best regards,