|Warning: Gmail Contextual Gadgets have been deprecated by Google and will be permanently shut down on August 1, 2018. Take into account that this action impacts ProcessMaker's Google Integration functionality. We will let you know about the required changes to support these upcoming changes.|
The ProcessMaker Google Integration extension for Chrome fully integrates ProcessMaker services with Google applications to make case management easier. This extension is available at the Google web store and it adds a convenient toolbar shortcut at the top left-hand side of the browser.
After successfully connecting to ProcessMaker, it is important to set Cron Jobs to a regular interval to synchronize the information between your ProcessMaker server and your Gmail account. With this, the integration is complete and functional.
The extension adds the HOME ProcessMaker trays to Gmail so you receive, view and work on your cases directly from the Gmail interface. You can manage, review and route cases directly from Gmail without logging to ProcessMaker. The extension also adds a field at the top of the Gmail email list, so you can easily find your processes, start new cases and bookmark the necessary processes so they are easily accessed from the ProcessMaker bookmark icon (next to the field).
Take into account that you must be logged into Google Chrome with the Google account with which you are registered in ProcessMaker. Also, it is recommended to always work with the latest version of the Google Chrome browser.
This functionality is available for Corporate and Enterprise editions.
The following are the requirements needed for this feature:
- ProcessMaker version 3.1 or later: The ProcessMaker server must be with the SSL certificate, thus the server must use the
- Gmail Account: This Google account must be specified in the profile information of the user in ProcessMaker.
- To use the service account, your company must subscribe to Gmail such that Google Gmail manages all your corporate email accounts.
- ProcessMaker Google Integration extension.
- Google Chrome: This extension has been tested in version 46; however, it is always recommended to work with the latest version.
What ProcessMaker Needs to Integrate with Gmail
The following sections describe configurations required to integrate the ProcessMaker server with Google accounts.
- Service account configuration
- Provide the Authorization Key to ProcessMaker
- Cron execution to synchronize data
Service Account Configuration
In the service account is necessary to do the following:
- Create a private key for the ProcessMaker instance that integrates with Gmail
- Add APIs
- Get a client ID to add scopes in the Admin Console configuration
The following sections describe the service account configuration.
Creating a new Service Account in the Google Developers Console
To generate the private key needed to integrate ProcessMaker to Gmail, follow these steps.
Step 1: Login with your Gmail corporate email.
Step 2: Access the Google Developers Console page.
Step 3: Click Create to create a new project.
Step 4: The New Project window displays. In the Project Name field, enter the name of the project and then click Create.
After creating the project, the project opened in the Service accounts tab.
Step 5: Click Create service account to create a new service account.
Step 6: The Create service account screen displays. Do the following:
- In the Service account name field, enter a name for the service account.
- Check the Furnish a new private key option to download the file that contains the private key.
- From the Key type options, select the JSON option to download the private key as a .json file.
- Click Create.
Step 7: The service will be created and the
.json file is downloaded to your local computer. Click CLOSE to close the confirmation message.
After closing the confirmation window, the service account is listed in the Service Accounts tab. The information of this list is used while providing the authorization key to ProcessMaker, and includes the "Service account name," the "Service Account ID (Email address)," the "Key ID," the "Key creation date" and its options.
To run ProcessMaker Google Integration correctly, it is necessary to add the required APIs to the service account. For this purpose, after the creation of a new Service Account, follow these steps.
Step 1: In the navigation menu, go to the APIs & Services > Library option.
The API library displays.
Step 2: In the API library, go to the G Suite section.
Step 3: In the G Suite section, enable all Google API libraries needed for the google integration.
- Link Google Apps Marketplace SDK to enable Apps Marketplace SDK.
- Click the Google Calendar API icon or link Google Calendar API to enable the Google Calendar API.
- Click the Google Drive API icon or link Google Drive API to enable the Google Drive API.
- Click the Google Sheets API icon or link Google Sheets API to enable the Google Sheets API.
A similar window displays for each library:
Configuring Google Apps Marketplace SDK
The Google Apps Marketplace SDK requires the following configurations after this API library has been enabled.
Step 1: In the navigation menu, go to the APIs & Services > Dashboard option.
Step 2: In the Google Apps Marketplace SDK row, click the configuration icon.
The Configuration tab displays.
Step 3: Enter the application name.
Step 4: Enter the application description.
Step 5: In the New item window, click Done.
Step 6: Check Enable individual install.
If a warning message displays, click API credentials and follow the steps in the Configuring API Credentials section. Reload the page, and the warning message should disappear.
Step 7: Select an application icon according to size requirements.
Step 8: Enter the terms of the service URL.
Step 9: Check Drive extension.
To run Google Drive correctly, click Configure Drive SDK and follow the steps in the Configuring the Google Drive SDK section.
Step 10: After configuring the Google Drive SDK, if needed, reload the the Apps Marketplace SDK screen and save the changes.
Configuring API Credentials
An Individual install requires a web application client ID. Create one following the next steps.
Step 1: After clicking the API credentials in the Step 6 of the Configuring Google Apps Marketplace SDK section, the Credentials tab displays.
Step 2: In the Create credentials, click OAuth client ID.
Step 3: The Create client ID screen displays to create OAuth credentials. Select Web application.
Options to configure the Web application display.
Step 4: Leave the default values and click Create.
The new OAuth information credentials display in the Oauth client window.
Step 5:Click OK to close the window.
Go back to the configuration form and reloaded the page. The warning message should disappear.
Configuring the Google Drive SDK
To run correctly the Google Drive API configure the Google Drive SDK by following the next steps.
Step 1: After clicking Configure Drive SDK in the Step 9 of the Configuring Google Apps Marketplace SDK section, the Drive UI Integration tab displays:
Step 2: Enter the application name.
Step 3: Select an application icon according to size requirements.
Step 4: Enter the URL to open Google Drive files with the application.
Step 5: Save changes.
Getting the Client ID
The Client ID is necessary to add the required scopes. For this purpose follow these steps to get the Client ID.
Step 1: In the navigation menu, go to the IAM & admin > Service accounts option.
The Service Accounts screen displays, and all the service accounts are listed.
Step 2: In the service accounts list, select the newly created service account, and then click Edit.
The Edit service account window displays.
Step 3: Check Enable G Suite Domain-wide Delegation option and save the changes by clicking SAVE.
Step 4: For the selected service account, click View Client ID.
The Client ID for Service account client screen displays the Client ID that is used to configure the Admin Console.
Configuring the Admin Console
Note: The Admin Console configuration is available for the Gmail administrator of the company.
To correctly run the application created, the administrator needs grant access to the scopes needed in the application. For this purpose the Administrator must follow the next steps:
Step 1: Login to the google admin console using the URL: https://admin.google.com.
The administrator options display in a new window.
Step 2: Click Security.
The security window displays.
Step 3: Click More, then select Advanced settings.
Step 4: Inside the Advanced settings window, click Manage API client access.
Step 5: For each scope, in the Client Name field, enter the service account's Client ID. In the One or More API Scopes field, enter the list of scopes that your application should be granted access to. When all is done, click Authorize.
The scopes needed for spreadsheets, calendar events and drive are:
Providing the Authorization Key to ProcessMaker
After configuring the service account from the Google Developers Console page, return to ProcessMaker and upload the files downloaded in the previous step.
To use the
.json file in the configuration, follow these steps:
Step 2: Go to the Admin > Settings > PM Gmail option.
The configuration made in this section will be available for the current workspace.
Step 3: Check the Enable PM Gmail option to enable the integration with Gmail, and the Enable Google Drive checkbox to enable the option of synchronization between input, output and attached documents.
After one is selected, two new options will display to integrate ProcessMaker employing a direct server-to-server interaction with Gmail using a
json file to provide the user's private key.
Step 4: In the Service Account Email field, enter the Service Account ID shown in the list of service accounts in the project of the Developers page.
Step 5: Upload the
.json file in the field below.
Step 6: Click the Test Connection button to check that the authorization is working correctly.
Ensure that the service account is correctly configured and the key is validated by the company Gmail server administrator. Otherwise, the following error message displays:
Step 7: Click on Save Settings. The following confirmation message displays at the bottom right of the window:
Note: If there are multiple users with the same email and the connection is successful, it is not possible to save settings:
Cron Execution to Synchronize Data
To fully integrate ProcessMaker with Gmail, it is necessary to set cron jobs. Follow these steps.
Step 1: On Linux/UNIX systems, open a terminal and login as root user or use the
sudo command to gain root privileges:
Step 2: The following commands will synchronize emails, labels and input, output and generated documents. Do not forget to replace the workspace name example testdrive with the proper name of your workspace.
For more information about how to set cron jobs, please visit the Executing cron.php page.
Configure the cron execution using scripts
To set script files, follow these steps.
Step 1: Download the following files: hello.sh and runEvery.sh
The hello.sh file contains the cron commands explained before and the runEvery.sh file runs a command every X seconds for minute.
Step 2: Open the hello.sh file with your favorite editor and replace the workspace name testdrive with the proper name of your workspace, for example: +wWorkflow in the three comands contained.
Step 3: Save the changes and close the hello.sh file.
Step 4: Move the hello.sh and runEvery.sh file to the /bin folder located at:
Step 5: Set permissions to the files with the following commands:
Step 6: Execute the hello.sh script manually through the following command to see how it works:
For more information about executing cron scripts, please visit the Manually executing cron scripts
Step 7: To execute periodically the downloaded cron scripts in Linux, add the following line to the crontab according to the instructions of the Configuring crontab in Linux page.
Installing the Extension
To install the extension, follow these steps.
Step 1: Download the ProcessMaker Google Integration from the Chrome web store at the following address:
Step 2: Click the Add to Chrome button at the top right side of the window that opens:
Step 3: An alert window asks if the extension should be added to Chrome or not. Click on the Add extension option to continue the installation.
Step 4: Google Chrome downloads and installs the extension to the browser. After the installation is completed, the ProcessMaker icon is added at the top right side of the browser and the following message displays:
Integrating ProcessMaker with Gmail
To integrate ProcessMaker with Gmail, follow these steps:
Step 1: After installing the extension, logging in to your email.
Step 2: A new dialog window displays to fill out the credentials of the ProcessMaker server and the workspace from where the information of the cases will be retrieved in Gmail.
Step 3: Click on Save Settings to verify the information and retrieve the information of the cases from the server.
Step 4: A success message confirms the information. Click OK.
If the information is wrong the next message displays.
The ProcessMaker Field in Gmail and Process Bookmarks
After configurations to connect ProcessMaker are saved and the page refreshed, a field adds on the top left-hand side of the email list along with the ProcessMaker button as shown in the image below.
This field allows searching for processes that can be started by you (meaning that you are assigned to an starting task in the process). All coincidences of the text entered show down. Also, by clicking on the down arrow of the field, the complete list of processes, which you are assigned to start a task, displays.
Notice that next to the name of the processes in the list there is a star icon with plus sign inside. By clicking this icon, the process is added as a new bookmark in the process preferences of the user.
These bookmarks can be easily accessed by clicking the ProcessMaker icon next to the field. To remove a bookmark from this list, simply click the star icon with the minus sign inside.
Starting New Cases
The integration gives you the ability to start cases to which they are assigned directly from Gmail.
To start a new case, click the name of the process from the list shown in the field or from the user bookmarks.
A modal window opens showing the first step in the task (which could be a Dynaform, an Input Document or an Output Document). All steps of the task show in this window.
If at any point of the steps, before routing the case, this window is closed, it will be saved in the DRAFT label as an inbox email just like in ProcessMaker.
The last step in all cases of ProcessMaker is the routing of the case. In this window the information of the next task and the next assigned user is shown.
To route the case to the next task, click Continue.
Now, the information of the case is shown in the window. This means that the case has been routed correctly. So, simply close the window to continue.
Managing Cases from Gmail
Notice that after installing the extension, the ProcessMaker category is added to the Inbox section of the interface. This category has its own ProcessMaker labels (the same as shown to an Operator user in ProcessMaker.)
These labels are the following:
- Draft: This label includes cases that are being edited or advanced by the user but have not yet been submitted to the next task. In ProcessMaker 3, only cases in their initial task may have the "Draft" status.
- Inbox: This label includes cases that are currently placed in the user's Inbox.
- Participated: This label includes the participated cases (cases in which the user has participated, meaning that the case was assigned to work on at least one of the tasks in the case).
- Unassigned: This label includes the unassigned cases to which the user account is assigned in the task and can decide to claim the case as their own.
See more information of the states of cases in the ProcessMaker Cases page.
Note: It is recommended to avoid changing the name of the ProcessMaker labels. In case of changing the label name, a new ProcessMaker label is automatically created with the original name.
The management of these cases is similar to the management of emails in Gmail.
The difference is that when opened, the information of the case is shown:
The available tabs are the following:
- Form: If the task has forms as steps, they are shown in this tab (including the routing window).
- Process Map: It shows the workflow of the process highlighting the current task.
- Uploaded: It shows the Input Documents related to the case.
- Generated: It shows the Output Documents related to the case.
After routing a case to the next task, or finishing it, the case properties show and the case is marked as "read" (as with emails in Gmail) in the list. If opening the information of the case and not routing it, the case also is marked as "read" in the list.
Searching for Cases
The integration also allows to search for cases from the search field in Gmail.
To search a case, enter the number of the case, the name of the process, or any searching criteria as used with emails in Gmail. For example, if looking for the number of the case:
The results displays below:
Removing the Gmail Extension
The extension can be removed in the following ways:
Uninstalling from the Extension Icon
To remove the Gmail Extension press right-click in the ProcessMaker Extension icon and select the Remove from Chrome option.
An alert window asks if the extension should be removed from Chrome or not. Click the Remove option to continue.
A new window displays a message confirming that the extension has been uninstalled from Chrome:
Finally, refresh the Gmail page to uninstall all the components of the extension.
Uninstalling from the Extension Manager
To uninstall this extension from the Extension Manager, open a new tab and enter the following URL:
chrome://extensions/. All extensions installed in Chrome are listed in this window.
To uninstall the ProcessMaker Google Integration extension, click REMOVE.