LumApps Integration

Overview

The LumApps Integration plugin bundle allows ProcessMaker to integrate with the LumApps service, which is G Suite’s recommended intranet site solution. This integration provides the following functions through the LumApps service:

• Display assigned case notifications to LumApps site users when they have been assigned tasks in ProcessMaker cases.

• An assigned case notification about the task will disappear in the LumApps site when the task is completed and routed.

Description of the LumApps Integration Plugin Bundle

The LumApps Integration plugin bundle is composed of two plugins:

• LumApps plugin: The LumApps plugin integrates with the LumApps service as described in How the LumApps Integration Works.

• Google Auth plugin: The Google Auth plugin provides OAuth 2.0 authentication to your G Suite Administrator Google account for the LumApps Integration plugin bundle.

Notifications are sent from the LumApps site when the ProcessMaker server periodically executes a cron job. This cron job is typically configured to execute once per minute. This interval may be configured on the ProcessMaker server. For more information, see Executing Cron Scripts.

How the LumApps Integration Works

Refer to the following sections which discuss how the LumApps plugin integrates with the LumApps site:

• ProcessMaker sends case notifications to the LumApps site when a case is routed.

• ProcessMaker removes notifications from the LumApps site when a case is routed.

How a Notification is Sent from ProcessMaker to the LumApps Site

As soon as a case is routed, the following events occur:

• ProcessMaker sends a notification(s) to the LumApps site. To do so, a process executes to authenticate the current user with the Google server.

• The LumApps server connects with ProcessMaker using the lumsites.notification.send endpoint. This notification is sent when the ProcessMaker server executes a cron job.

This process is depicted below.

The following are variations of this process:

• A task using Self Service Assignment Rule: The notification is sent to all the assigned users and assigned groups in the assignment list of the task.

• A task with a Parallel Marker or a task following a Parallel Gateway: The notification is sent to all the assigned users and assigned groups on each thread involved.

• A user on Vacation: The notification is sent to the user set on the Replaced by field of the user’s Personal Information. If the user does not have an assigned "Replaced by" user, then the notification is sent to the current user.

• Plugin Functions: The new functions PSNewCase() and PSDerivate() have the same functionality as the existing ProcessMaker functions PMFNewCase() and PMFDerivateCase() respectively, but also include send notifications from Processmaker to the LumApps site.

How Notifications Are Removed from the LumApps Site

To remove the notification from the LumApps site, the following events occur:

• A process executes to authenticate the client's identity with the Google server.

• The LumApps server connects with ProcessMaker using the lumsites.notification.setRead endpoint. This functionality is executed as soon as the case is routed. The notification is removed when the ProcessMaker server executes a cron job.

This process is depicted below.

The following are variations of this process:

1. A task using Self Service Assignment Rule: The notification is removed for all the users as soon as the case is claimed for all the users except for the one who is claiming the case; for the user that claimed the case, the notification is removed after the case is routed.

2. A task with a Parallel Marker or a task following a Parallel Gateway: The notification is removed as soon as the case is routed, but the functionality does not affect the threads of other users’ notifications.

Requirements

The following are requirements to set up the LumApps Integration plugin bundle. Please ensure all requirements are met before importing the plugin bundle.

• ProcessMaker version 3.2.3 or later.

• A G Suite Administrator Google account to consume the LumApps API.

• The credential key that is generated as a .json file from the Google console will be used as a service account in order to consume the LumApps APIs. To create a service account visit the Google Developers Console page.

• The Instance ID from LumApps is needed in order to send the LumApps notifications from ProcessMaker. For more information, see Configure the LumApps Integration.

Setting Up

This section describes the following:

• How to import and enable the LumApps Integration plugin bundle into ProcessMaker.

• How to configure the LumApps Integration plugin bundle into ProcessMaker.

Import and Enable the Plugin Bundle

After verifying that the plugin bundle requirements are available, follow these steps to import and enable the three plugins in the bundle:

1. Log in to ProcessMaker as an administrator user such as admin.

2. Click the Admin option from the main menu at the top of the screen.

   

3. Click the Plugins tab.

   

4. Click the Plugins Manager option.

   

5. Click the Import button.

   

   The Import Plugin dialog box displays.

   

6. Click the Choose File button to select a plugin's tar file. Each of the following plugin tar files must be imported one at a time:

   • LumApps plugin tar file name: bpm3PluginLumApps-1.0.1

   • Google Auth plugin tar file name: bpm3PluginGAuth-1.0.1

7. Click the Open button to open the selected tar file.

8. After selecting the plugin file, click the Import button to upload it to ProcessMaker.

9. Repeat steps 5 through 8 for each of the three plugin’s tar file.

   Warning: If all two plugins are not imported, the LumApps Integration plugin will not work properly.

   Each plugin is localized in the plugins list with the “Disabled” status; therefore, the plugin is not available for use.

   

10. To enable each plugin, select a plugin from the list, and the Enable button displays.

    

    Click the Enable button at the top left side of the submenu. Repeat this for each of the three plugins.

    

    The plugins are enabled and ready to be used in ProcessMaker.

Configuration

After the plugins are imported, refer to the following sections to configure plugins:

• The Google Auth

• The LumApps integration

Configure the Google Auth Plugin

To configure the Google Auth plugin, follow these steps:

1. Log in to ProcessMaker as an administrator user such as admin.

2. Click the Admin option from the main menu at the top of the screen.

3. Click Google Auth from the pane on the left. The G Suite Authentication Authentication screen displays (shown after step 4).

   

4. In the Google auth main page, click the Enable Google Authentication for this workspace? checkbox.

   

5. Scroll down the page to the How to configure this plugin section that provides instructions on how to obtain the Client ID and the Client Secret in the Google Developer Console. Click the https://console.developers.google.com link.

6. Log in to the Google Developer Console using a G Suite administrator account.

   

7. Once on the GoogleAPIs site, click the Select Project button.

   

8. Click Create to proceed with the creation of the project. The New Project screen displays.

   

9. Enter the following information for the new project:

   • Enter a project name in the Project Name field. This is a required field.

   • Verify the organization to which the project will attach in the Organization field.

   • Specify the parent organization or folder in the Location field. This is a required field.

10. Click Create.

    

11. Select the project that you created from the list, and then click on ENABLE APIS AND SERVICES.

    

12. Search for Google+, and then select the Google+ API.

    

13. Click ENABLE to enable the Google+ API.

    

14. Click CREATE CREDENTIALS to create the new credentials.

    

15. Click Credentials option on the left side menu.

    

16. Click Create Credentials, and then select the OAuth client ID option. The OAuth client ID screen displays.

    

17. Click Web application from the Application type set of options. New fields display to configure the OAuth client ID for a web application.

    

18. Enter the following information to configure the OAuth authentication for your web application:

    • Enter a name for the OAuth authentication configuration in the Name field.

    • From the Google Auth plugin in ProcessMaker (in the How to configure this plugin section), copy the URL from the Authorized JavaScript origins field (noted in the screenshot below), and then paste it into the Authorized JavaScript origins field for your Google OAuth web application.

    • From the Google Auth plugin in ProcessMaker (in the How to configure this plugin section), copy the URL from the Authorized redirect URIs field (noted in the screenshot below), and then paste it into the Authorized redirect URIs field for your Google OAuth web application.

    

19. Click Create. A window displays with the client ID and client secret values for your web application.

    

20. Enter your web application’s client ID and client secret values into the ProcessMaker Google Auth plugin, and then click Update Configuration to finish the Google Authentication configuration.

    

Configure the LumApps Plugin

To configure the LumApps plugin, follow these steps:

1. Log in to ProcessMaker as an administrator user such as admin.

2. Click the Admin option from the main menu at the top of the screen.

3. Click LumApps from the pane on the left.

   

   The LumApps Integration Configuration screen displays.

   

4. Scroll down the page to the How to configure this plugin section that provides instructions on how to configure a service account in the Google Developer Console to create a authorization service. Click the https://console.developers.google.com link.

   

5. Log in to the Google Developer Console using a G Suite administrator account.

6. On the GoogleAPIs site, click the menu button to the left of the logo.

   

7. A menu displays. Select the IAM & admin option, and then Service Accounts.

   

8. Click + CREATE SERVICE ACCOUNT to create a new service account. The Service account details page of the Create service account screen displays.

   

9. Enter the following information for the service account:

   • Enter a name for the service account in the Service account name field.

   • Enter the service account ID in the Service account ID field.

   • Enter a description for the service account in the Service account description field.

     

10. Click Create. The Service account permissions (optional) page of the Create service account screen displays.

11. Click the Select a role option.

    

12. Select Project, and then select Owner.

    

13. Click CONTINUE. The Grant users access to this service account (optional) page of the Create service account screen displays.

14. Click + CREATE KEY.

    

    The Create key (optional) page displays.

    

15. Select the JSON option, and then click CREATE. The .json file downloads automatically according to your web browser’s download settings.

16. Go back to ProcessMaker’s LumApps section. Scroll to the top of the page to display the Google JSON Configuration File setting.

17. Click Choose File, and then select the .json file you downloaded from the Google Developer Console.

    

18. Email LumApps your service account’s client ID so that LumApps can allow your web application to access the LumApps API (which may take up to 24 hours). Your service account’s client ID can be found in the client_id key in the .json file.

    

Access the LumApps Plugin

Follow these steps to access the LumApps plugin:

1. Sign in to the Google account in which your organization uses LumApps.

2. Go to any Google application within your organization where is the Google Apps Grid displays (such as Gmail or Google Drive).

   

3. Click the LumApps Application icon.

   

   You can alternatively go to the following page https://sites.lumapps.com/login if you do not want to enter using the Google Apps Grid.

   Your organization’s LumApps page displays.

   

Edit the ProcessMaker Interface in LumApps

To edit the LumApps page, your G Suite administrator must grant you the proper permission to access to the Options button (shown on the left of the image below).

The Options button does not display if you do not have the Administrator permission in LumApps for your Google account (as shown below). Please contact your G Suite administrator to request this permission.

Follow these steps to edit the ProcessMaker interface in LumApps:

1. Click the Options icon and then select the Edit Content option.

   

   The LumApps page changes to edit mode.

   

2. Click on the icon to choose where to create a new interface.

   Hover your cursor over the icon to display options how to position the new interface window to display new content.

   

3. Select the position for the new interface window. The Add widget screen displays.

4. Select the ProcessMaker option.

   

   The widget settings display to the left of the LumApps dashboard.

   

5. In the Server address field, enter your address or IP address of the server hosting ProcessMaker and the LumApps plugin.

6. In the Workspace field, enter the workspace name where the LumApps plugin was installed. “workflow” is the default.

7. In the Language field, enter the language your ProcessMaker workspace uses. “en” is the default.

8. In the Skin field, enter the skin that your ProcessMaker workspace uses. “neoclassic” is the default.

9. From the View field, select from which ProcessMaker view to use the new LumApps interface.

   

   Depending on which view you select, the following occurs:

   • If you choose the Inbox option, the following widget displays.

     

     The Inbox widget will display all the pending cases and drafts for cases in which you have participated. When you click on any of the cases it will redirect you to ProcessMaker and to the exact case that you clicked.

   • If you choose the Start case option, the following widget displays.

     

     The Start case widget displays all the cases that you can start. Use the search tool to find the process that you want to start, and a LAUNCH button that will redirect you to ProcessMaker and start the case for the process that you clicked on LumApps.

10. Click the button to complete the widget configuration and exit the edit mode.

    

How the LumApps Integration Plugin Makes Notifications

When a case is routed to the next task, notifications are sent to the users assigned to that task. These notifications appear in the LumApps site. In the example below, routing to the next task uses the sequential routing rule.

If you are assigned to the next task, to access the assigned case notification and to open the assigned case notification from the LumApps site, follow these steps:

1. In the LumApps site on the top right, click on the Notifications icon. The Notifications panel displays.

   

2. Click the Display option to display all the notifications.

   

3. In the extended notification panel, click the notification to open the case with which you are working.

   

4. Open the corresponding Dynaform in the new tab. If there is not an active ProcessMaker login session, the ProcessMaker login screen displays the login screen.

   In other situations, the plugin sends notifications from ProcessMaker to LumApps as soon as the case is routed. See Process Sending a Notification from Processmaker to LumApps Site.

   As soon as the case is routed, the notification about that case disappears from the LumApps site and is no longer listed in the Inbox in ProcessMaker. For other situations, when the plugin setting notifications are marked as read in the LumApps site.