Plugin Version: 1.0.0 | Release Notes


New Feature: This functionality is available from ProcessMaker 3.1 Corporate and Enterprise editions.

Overview

The ProcessMaker Connectors plugin simplifies the access to external services that publish resources through a simple ProcessMaker wizard. The Enterprise Connectors creates a framework that manage connections to any web service or rest API of a provider that publish resources using protocols like: REST and authentication protocols like OAuth.

The Enterprise Connectors plugin include the following functionalities:

  • A plugin wizard that helps the user to register new connectors.
  • Connectors classified by category.
  • The connectors manage all the authorization / authentication complexities for the user.
  • Connectors integrated on ProcessMaker workflows through a PMFunction.
  • A PMFunction that can be executed from script tasks or / and triggers.

Requirements

ProcessMaker version

  • ProcessMaker v. 3.1 Corporate or Enterprise edition.

Browser Compatibility

  • Firefox v. 47 (latest stable version)
  • Chrome v. 51 (latest stable version)
  • Internet Explorer 11
  • Microsoft Edge

Installation

Login with a user such as "admin" who has the PM_SETUPADVANCE permission in his/her role and then go to ADMIN > Plugins > Enterprise Manager. Either install the Enterprise Connectors plugin by clicking on Install from File and uploading the plugin file or by clicking on its Install Now button in the list of available plugins.

After installing the plugin, make sure that the Enterprise Connectors plugin is  enabled.

Connectors Wizard

Once the plug-in is enabled, a new tab named PM Connectors will be added next to the Logs tab under the Admin section.

This new section is divided on three parts:

Configuration AUTH

The Configuration Auth section is used to store and manage the authentication information required to access the external service. Enterprise Connectors support two different authentication methods depending on the external service provider OAuth2: Service Account and Password.

Create an authentication configuration by clicking on the Create button at the top-right of the section.

The Authentication Protocol Configuration dialog will be displayed to set the following parameters:

  • Name: Name of the configuration.
  • Protocol: Select the protocol for the configuration. In the current version of the plugin, OAuth2 is the only available option.
  • Sub protocol: Select the sub protocol. In the current version of the plugin, the following options are avaliable: Service Account and Password.

Once all the parameters are set, click on Test to test the configuration. If the credentials given were the right ones, a green message will be displayed at the top of the window dialog. To save these credentials, click the Save button.

On the other hand, if there is a problem a red dialog message will be displayed containing the error information.

Sub-Protocol: Service Account

A Service Account is an account that belongs to your application instead of to an individual end user. With this service account ProcessMaker will connect to the APIs on behalf of the service account, so users aren't directly involved.

  • file_credential: The key file generated by the service account provider.
  • tokenCredentialUri: It is the path of the application where the token is provided.
  • grant_type: Token grant type. For example, use the following URL-encoded if connecting with Google APIs: urn:ietf:params:oauth:grant-type:jwt-bearer
  • signingAlgorithm: RS256. Service accounts rely on the RSA SHA-256 algorithm.
  • scope: The list of scopes that your application should be granted access to. For example, if your application needs domain-wide access to the Google Drive API and the Google Calendar API, enter: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.

Sub-Protocol: Password

In this configuration, the user provides his/her resource server credentials (username/password) to the Enterprise Connectors plugin, which sends them in an access token request. An identity server validates the credentials and if they are valid, the service proceeds to generate an access token and returns it to the app.

  • tokenCredentialUri: It is the application path from where the token is provided.
  • grant_type: Token grant type. By default, the password option is selected.
  • scope: Specifies the level of access that the application is requesting. For example: "*" (all scopes), "edit_process" (access to endpoints to change processes), "view_process" (access to endpoints to view but not change processes).
  • clientId: The Client ID, which was given when registering the application.
  • clientSecret: It is used to authenticate the identity of the application to the service API when the application request access to the user's account. It is given when registering the application.
  • username: The username of the user account.
  • password: The password of the user account.

Category

The Categories section organizes the connectors by its authentication configuration.

To create a new category, click on the Create button at the top corner of the window.

  • Name: Name of the category.
  • Configuration Auth: Select one of the configuration created on the "Configuration Auth" section.

Once done, click on Save.

Connectors

The Connectors section displays a list of all the connectors available. This section also contains the Create a connector wizard to create almost any kind of request quickly. This wizard gives the user tools to set all the necessary parts (URL, method, headers, and body) of a request.

To create a new connector, click on the Create button and define the following parameters:

  • Name: Name of the connector.
  • Description: Description of the connector.
  • Category: Select a category, this category will use the Auth configuration that was assigned to.
  • Method: Method of the Request. It can be: GET, POST, PUT, DELETE, PATCH.

  • URL: The URL that points to the resource. This URL can include path parameters. For example: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
  • Headers: In this section default headers can be added, edited and deleted. The default headers are used when the connector is executed, note that in execution time the default headers can be overriden or merged with additional ones.

Connector Testing Interface

For each connector created, the Test option is available to test its configuration.

If the configuration includes variables, these values must be defined under the Path Parameters section to execute the test.

A dialog will be displayed to request the value of each of the required variables.

Once set all the parameters, click the Test button to review the response in JSON format in the Response Connector window. If the response is satisfactory, close this window and Save the configuration.

If there is a problem, the error information will be shown in the Response Connector window.

Connectors PMFunction executeRestConnector

To execute a connector, it is necessary to call them from inside the process with the executeRestConnector function. This function executes the connector created by the user.

array executeRestConnector(string connectorName, array pathParameters, string queryParameters, array requestBody)

Parameters:

  • string connectorName: The unique name for the connector.
  • array pathParameters: (Optional) Required nested parameters part of the URI.
  • string queryParameters: (Optional) String value which contains a set of rules used to sort, filter or search information.
  • array requestBody: (Optional) List of parameters defined in JSON format. Required for some requests.

Example:

executeRestConnector("Create event", "{calendarId:234299832497234987}", "{ "start": { "date": "2016-06-10", }, "end": { "date": "2016-06-10" } }" );

Using ProcessMaker Endpoints with Enterprise Connectors

ProcessMaker provides a large number of endpoints so that almost any action which can be done within the ProcessMaker interface with the help of Enterprise Connectors.

Configuration Auth for ProcessMaker Endpoints

For this first, go to Configuration Auth menu under the PMConnectors tab and click on Create.

In the next dialog window, fill the following fields:

  • Name: The name of the service. In this example the configuration is named: "ProcessMaker Authentication Service".
  • Protocol: ProcessMaker uses OAuth 2.0 to first obtain access to ProcessMaker services. Therefore, select OAuth2 from the menu.
  • Sub-Protocol: Select Password.

Before continue, to authorize the access to ProcessMaker, first it is necessary to register an user application. By default, when installing the Enterprise Connectors plugin, the pmConnectorsPlugin application is created. Therefore, go to http://ProcessMaker-server/sysworkspace/en/neoclassic/oauth2/applications to review the application created.

Select the pmConnectorsPlugin application from the list and click on Details to review the application credentials. Copy the Client ID and Client secret which will be used by the external application to obtain authorization

With this credentials on mind, complete the rest of the parameters:

  • tokenCredentialUri: OAuth2.0 authorizes the external application and logins to ProcessMaker in a single step by directly calling the /workspace/oauth2/token.
  • grant_type: password is the option selected by default.
  • scope: The scope which determines which endpoints can be accessed: "*" (all scopes), "edit_process" (access to endpoints to change processes), "view_process" (access to endpoints to view but not change processes).
  • clientId: The Client ID code, which was given when the application was registered.
  • clientSecret: The Client Secret code, which was given when the application was registered.
  • username: The username of a ProcessMaker user, which is case insensitive.
  • password: The password of a ProcessMaker user.

Once ready, click on Test. If the credentials given were the right ones, a green message will be displayed at the top of the window dialog. Finally, click the Save button.

If there is a problem, a red error message will display the error information.

Create a Category for ProcessMaker Endpoints

After that, select the Category option menu under the PMConnectors tab, and click on Create a new category.

Name the new category, select the Service ProcessMaker configuration just created and click on Save.

After setting these configurations (Configuration Auth and Categories), any ProcessMaker endpoint can be consumed by creating a Connector.

Create a Connector: Get a list of all users

This example uses the endpoint Get Users List: GET /users to populate a dropdown with the usernames of all active users of the current workspace.

First, go to the PMConnectors option menu and click on the Create button.

In the next dialog, fill out the following parameters.

Click on the Test button, to open the Test Connector dialog. Then click the Test button.

The Response Connector dialog will open with the response given by the service.

Once done, close both dialog windows and do not forget to save the connector created. Now, open a process and create a new array variable named UsersName.

Create a new DynaForm and drop a dropdown control to display the names of the users. In the Create / Select Variable dialog, create a different variable.

Click on the dropdown control and modify its Datasource property, select Array variable. Then, click on the @@ button and select the UsersName array variable.

Save the changes. Now, create a Trigger with the following code:

$response = executeRestConnector('UsersList');
$aUsers = objectToArray($response);
$repositories = [];

foreach ($aUsers['message'] as $key => $repo) {
        array_push($repositories, [$key, $repo['usr_username']]);
}

@@UsersName = $repositories;

Put the trigger before the Dynaform in the Steps option and start a case. The user's names retrieved for the Connector will be set as dropdown's options.

Google Services and Enterprise Connectors

The Enterprise Connectors plugin include by default connectors for the following Google services:

  • Google Calendar
  • Google Drive
  • Google Spreadsheets

For this, the Service Account Google authentication configuration comes by default in the Configuration Auth menu. This configuration already set only needs a Service Account file credential to work succesfully.

Authentication Configuration for Google API

When using a Google Endpoint with PM Connectors some particular settings must be configured.

Creating a new Service Account

To generate the credential key needed to integrate ProcessMaker Enterprise Connectors with your Google account, it is necessary to first create a new Service Account in the Google Developers Console page of your Google account.

Access the Google Developers Console page and create a new project.

Provide the name of the project and select the App Engine Region.

After creating the project, it will be usually opened in the API Manager tab, click on the icon menu on the top left corner to display a menu.

In the displayed menu, select the IAM & Admin option.

From the left menu, choose Service Accounts option to create a new service account and click on the Create service account button.

Provide a name to the service account in the "Create service account" window. Then, check the Furnish a new private key option to download the file that contains the private key. Download the private key as a .json file, after checking the Furnish a new private key option, select the JSON option and click on Create.

The service will be created and the private key .json file will be generated and downloaded to your local computer. It serves as the only copy of this key, store it securely.

The service account created will be listed in the Service accounts tab in the https://console.developers.google.com/permissions link. The information of this list includes the "Service Account", the "Service Account ID", the "Key ID", the "Key creation date" and its options.

Providing the Authorization Key

After obtaining the private key from the Google Developers Console page, return to ProcessMaker PMConnectors tab. Edit the Service Account Google configuration.

Edit the file_credential parameter.

In the next dialog, click on Choose File, navigate and select the .json file Google Service Account generated. Once done, click on Save.

Finally, click the Test button to test the configuration. If the configuration is ready, a green message will be displayed at the top of the window. Click on the Save.

This configuration is already assigned to the Google category under the "Categories" section.

Enabling Google API

In order to allow the Enterprise Connectors plugin to access the user Google account information, it is necessary to enable the API requests.

Go to the Google API Console of your Google Account, make sure you are in the PMConnectors project just created and look for the Google Apps APIs section.

Under this section, select the service: Drive API, Calendar API, Sheets API to authorize depending on what type of connectors are used.

For example, click on the Calendar API option. In the next page, click the Enable button to allow the access to user data.

Google Services

Take into consideration that each one of these connectors created by default has their own configuration and their own parameters to be defined. Therefore, it is recommended to read the Google API documentation.

Google Calendar

The Enterprise Connectors plugin has integration with the Google Calendar API.

Google Drive

The Enterprise Connectors plugin has integration with the Google Drive API.

Google Spreedsheets

The Enterprise Connectors plugin has integration with the Google Sheets API.