READY

Video Walk-Through of this Tutorial

If you would like to see the "NDA Agreement Signing Using Google API Connectors" use case in action, click this video below.

General Description

This use case demonstrates how ProcessMaker I/O combines with Google services to create and manage a Google document within sets of Google connectors. Both software programs provide the tools to build effective processes while satisfying a variety of business needs.

To work with this MVP example, click on the top navigation tab labeled “NDA Agreement Signing Process” on the Examples portal. (Juliya Zagoruyko (Unlicensed): When I click this link from the live page, the link is broken. But if I access the Examples portal from within the PM I/O environment (such as clicking the Click to open" link for a BPMN file I've uploaded to an environment) the link works. Does this mean we cannot provide a link to the Examples portal from the live page? - yes, the link is available only from Environment details page) The top navigation presents a series of steps available for the selected example.

For this example, you 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. Put these tokens and settings 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 their statuses from the Processes page.

Getting Started with the Use Case

Run a ProcessMaker I/O Environment*

*ProcessMaker I/O is an "always on" cloud service. In this document an Environment refers to an installation of ProcessMaker I/O in a virtual machine or a container. This environment is created, run, and managed directly through the ProcessMaker I/O web management console.

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

1. Log on to your ProcessMaker I/O account. If you do not have a free ProcessMaker I/O account, please create one.
2. Click the Environment page on the top menu.
3. Click the Create Environment button, and then follow the instructions provided.

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

1. Log on to your ProcessMaker I/O account.
2. Click the Environment page on the top menu, and then run a ProcessMaker I/O Environment.
3. Copy the Environment URL link to remember it for later; this URL is required as your-environment-url (for example, "your-environment-url" is "MYENVIRONMENT.api.processmaker.io", where "MYENVIRONMENT" is your "Processmaker I/O Environment name").
4. Click the Environment name to display information about it.
5. From the Info tab, click the Example: Click to open link to display the ProcessMaker I/O Examples Portal.
6. From the left menu, click the NDA Agreement Signing Process tab.
7. Click on the NDA BPMN file link to download the BPMN file to your computer. You will use this BPMN file for this use case.
8. From your Environment, click on the Import tab, and then click the Choose File button to upload the BPMN file from your computer.
9. Click the Processes tab, and then click the ID button for all displayed processes to ensure no processes are in your Environment.

Set Up Credentials for Google Drive

1. Log on to your Google account and then go to this website: https://console.developers.google.com/.
2. Create a new project by clicking the My Project drop-down at the top of the page, as noted in the graphic below. (Juliya Zagoruyko (Unlicensed): The arrow in the graphic is pointing to "Create project", not "My Project". Is this pointing to the wrong GUI element in the screenshot? - everything is correct. "My project" is the top menu (new Google logo)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. Under Google Apps APIs, go to Library, and then click on Drive API under Google Apps APIs (as noted in the graphic below).
4. Click Enable to enable the Drive API, as noted in the graphic below.
5. Go to Credentials and then click on the Auth Consent Screen tab. Enter the Product name shown to users field, and then click the Save button (as noted in the graphic below). Ignore the other fields.
6. Create the Credentials with OAuth.
7. Go back to Credentials, click the Create Credentials button, and then select OAuth Client ID (as noted in the graphic below).
8. Choose Web Application and then enter a name (as noted in the graphic below).
9. Enter your authorized redirect URIs, preferably to your test URL (http://mysite.dev) and your production URL (https://mysite.com). Alternatively, 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.
10. Click Create and then take note of your Client ID and Client Secret.
11. Now head to https://developers.google.com/oauthplayground. (Juliya Zagoruyko (Unlicensed): I don't understand what Step 11 is saying. I don't see this GUI element in any screenshots here.  - I removed first part, now it's clear )
    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 then paste your Client ID and Client Secret (as noted in the graphic below).
13. In Step 1 on the left, scroll to Drive API v3, expand it, and then check each of the scopes (as shown in the graphic below).
14. Click the Authorize APIs button 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 (as shown in the graphic below).
16. When you get to Step 3, click on Step 2 again to display your refresh token.

Set Up Your Form

Follow these steps to set up your form:

1. Copy the NDA form request to your Google Drive.
2. Open this form in the editor.
3. Go to the script editor and then paste the following code:

function myFunction(e) {
 var host = "pm instance host";
 var token = "access_token_for_instance"; (Louis question: Should this now read "access_token_for_environment"?)
 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());
}

1. Substitute all credentials in the script with your instance and Google Drive credentials. (Louis note: This is Step 4, not Step 1.) (Juliya Zagoruyko (Unlicensed): Should "instance" be changed to "Environment"? - yes)

Set Up the Project Trigger

To set up the project trigger, click Edit > Current project triggers and then create a trigger using the existing myFunction(e) to submit the event. Google displays a notice requesting new permissions; accept them.

Download the Template File

Download Example_template.docx to the root of your Google Drive. This is the template with variables.

Process Execution

Start the Process

After you have performed all previous steps, start the process in one of these ways:

• Open your Google Form and then submit it.
• Call the eventTrigger() method using an SDK.
• Request the endpoint (Louis question: eventTrigger() endpoint?) and pass all the fields presented in the Google script to datamodel: "http://"++"/api/v1/processes/"+"Requester"+"/events/"+"NDA%20form%20request"+"/trigger".

Newly created processes with their respective statuses display in your ProcessMaker I/O Environment's Processes tab.

Finish the Process

Go to Check NDA status in the menu to display links to the new files generated by example_template.docx. Choose to either Approve or Decline your instance. To clear all data from your Environment (with all processes), go to the Processes tab list in the main menu of the NDA example and then click on all existing processes.

Connector Descriptions

Google Connectors

GoogleDrive/GDriveConnector

Starts the Google Drive connector Service Task. Requires the following credentials to access the Google Drive:

• client_id
• client_secret
• refresh_token

These methods use string variables to:

• write: upload a file to the Google Drive
• read: download a file from the Google Drive
• update: renaming a file on the Google Drive
• delete: delete a file on the Google Drive

Parameters for these methods are described below.

Write method (use GoogleDrive > create method) (Juliya Zagoruyko (Unlicensed): In the Task table below, this is reference as "CreateFile", not "create". Should this be changed? - please change)

Input parameters, except main: (Juliya Zagoruyko (Unlicensed): What does "except main" mean? I see this phrase is used throughout this page. )

• file: file content coded in base64 (required)
• filename: full filename with extension (required)
• folder_name: put the file into a folder; folder is automatically created (optional)

Output parameters: (Juliya Zagoruyko (Unlicensed): It is not explicit that these output parameters are required, as it was explicit which input parameters are required. Are these output parameters required? - done)

• file_id: ID of the uploaded file ( required)
• folder_id: ID of the folder containing the uploaded file ( not required)

Read method (use GoogleDrive > get method)

Input parameters, except main:

• file_id: ID of the file on the Google Drive to read (required)

Output parameters: (Juliya Zagoruyko (Unlicensed): It is not explicit that these output parameters are required, as it was explicit the input parameters are required. Are these output parameters required? - done)

• file_from_drive: file content from the Google Drive, coded in base64(required)
• filename_from_drive: full filename from the Google Drive with the extension (required)
• mimetype_from_drive: MIME type of the file ( not required)
• filesize_from_drive: file size of the file ( not required)

Update method (use GoogleDrive > create method) (Juliya Zagoruyko (Unlicensed): In the Task table below, this is reference as "RenameFile", not "create". Should this be changed? please change with new schema)

Input parameter, except main:

• file_id: ID of the file to rename on the Google Drive (required)

Delete method (use GoogleDrive > delete method):

Input parameter, except main:

• file_id: ID of the file to delete on the Google Drive (required)

GoogleDrive/GDPermissionConnector (Juliya Zagoruyko (Unlicensed): In the Task table below, you reference the method "ShareFIle". Should we reference that anywhere here in the GDPermissionConnector description? Share Document is the proper name for the task that use this connector )

Creates or deletes the file permission for the Google Drive. Requires the following credentials to working with the Google Drive client:

• client_id
• client_secret
• refresh_token

These methods use string variables to:

• write: create the file permission with the Google Drive
• read: delete the file permission with the Google Drive

Parameters for these methods are described below.

Create method (use GoogleDrivePermissions > create method)

Input parameter, except main:

• permission_list: Array of users with roles and types in JSON format (required). 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.

Output parameters:

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

Delete method (use GoogleDrivePermissions > delete method)

Input parameters, except main:

• file_id: file ID on the Google Drive (Juliya Zagoruyko (Unlicensed): Is this parameter not required? yes)
• permission_ids: IDs of the permissions to delete; note that you can't delete the permission from the owner of the file (Juliya Zagoruyko (Unlicensed): Is this parameter not required? this is not required)

GoogleDrive/GDReaderConnector (Juliya Zagoruyko (Unlicensed): Should we follow the convention you've established for other methods whereby you write "use ReadFile method", as referenced in the Task table below? - It will be good)

Triggers the start event with data to generate the template and credentials for the Google Drive SDK. Requires the following credentials to working with the Google Drive client:

• client_id
• client_secret
• refresh_token

This method uses string variables to:

• read: reads a file's content from the Google Drive using the full name with extension (Juliya Zagoruyko (Unlicensed): If this method reads a file's content, are there limitations to file types it cannot read? If so, we should state that. we are supporting all google drive supported files)

Google Reader Connector (use GoogleDrive > get method)

Input parameter:

• file_name: full filename with extension (required)

Output parameter:

• file_content_from_drive: file content coded in base64

Doc Connectors

Doc/HTMLConnector

Runs the generate docs Service Task.

Input parameters:

• document_format: supports DOCX, ODT, HTML, PDF, and RTF formats (required)
• document_template: template in HTML with variables available in datamodel (required)
• Can also be set with the parameters of the document in JSON format (Juliya Zagoruyko (Unlicensed): Are the parameters below optional? - this is optional )
  • {"orientation": "landscape", "size":"A5","filename":"test"} (Juliya Zagoruyko (Unlicensed): For the orientation key-value pairs, there is space after the key; the others do not; we should be consistent; which is proper or correct? we have only two option for the orientation landscape and portrait. This is the example )

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

Generates documents in docx format using templates in docx format.

Input parameters:

• docx_template: file content of the template coded in base64, filled in with the variables in the following way: ${variable_name} (required)
• replacement_array: array of replacements in JSON format (required). Example: {"variable_name":"value", "variable_name1":"value1"}

Output parameter:

• {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.

Input parameters:

• To: requester email address (required)
• Body: email text (Notification to requester) (required)
• To_name: requester full name (required)
• Subj: email subject (required)
• Options: options to log mail driver actions to the log file (required) (Juliya Zagoruyko (Unlicensed): What are these options? Should we document them? - its log options)

No output parameters.

NDA Agreement Signing: Process Description and Scheme

In this use case, a user wants to do business with a company that requires an NDA form be signed as part of its standard procedures. For example, the signed NDA might apply to a new potential business partner or employee.

Workflow for this use case is as follows:

1. The user fills out a Request/Order form on a website or imaginary company portal to request the NDA.
2. The company receives the request.
3. If the NDA request is from a new customer or partner, the process follows the Business path: the company generates an NDA document based on a docx template. If the request comes from a potential employee, then the process follows the Employee path: the company generates an NDA document based on an html template.
4. The company sends the generated document to the requester via an email with the permission "Only for comment".
5. The requester reviews the NDA, signs the document, and then sends an email to the company with the signed and scanned NDA in the attachment (external process).
6. When the company receives the reply from the requester, the document is renamed with the mark "Signed" or "Unsigned" according to its status.

The graphic below shows the BPMN process scheme.

Tasks (Juliya Zagoruyko (Unlicensed): Should these step types be all lower-cased? Right now they are a mix of upper and partial lower-case. This is also true for the methods.)

Forms

Manual Request (Google Form)

This is a Google Form implementation to trigger the “Manual Request” Event. (Juliya Zagoruyko (Unlicensed): Are "Events" considered proper nouns or common nouns? Its one 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 the API endpoint URL and authorization token in Google Script (attached to the form), and configure form triggers.

Check NDA Status Form

This is a jQuery implementation for the “Check NDA status” user task that finds the delegated user task data for a specified user by referring to the selected user on the top-right and pre-filling form inputs. Please note the NDA  example process delegates the “Check NDA status” user task to a user named “Test,” so ensure this user is selected on the 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.