Plugin Version: 1.1.0 | Release Notes


Overview

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

The Enterprise Connectors plugin includes the following functionalities:

  • A wizard that helps the user create new connectors.
  • A connectors library.
  • Management of authorization/authentication for the user.
  • Integration with ProcessMaker workflows through a Service Task.
  • A PM Function that can be executed from script tasks and/or triggers.

Requirements

The Enterprise Connectors plugin version 3.2 has the following requeriments:

  • ProcessMaker 3.2 Standard, Corporate or Enterprise edition or later.

Concepts

  • Client: The client is the application that wants to access the user's account. Before it may do so, it must be authorized by the user, and the authorization must be validated by the API.
  • Access Token: The access token is used for authentication and authorization to get access to the resources from the resource server
  • Grants: Methods to get access tokens from the authorization server are called grants.

Installation

Log in with a user, such as "admin", who has the PM_SETUP_ADVANCE permission in their 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.

The PM Connectors section is divided in three parts:

Configuration Auth

The Configuration Auth section is used to store and manage the information about the user's credentials required to access the external service through a connector. An authentication configuration can be used by more than one connector, but a connector can use just one authentication configuration.

Warning: Please be aware that the authentication configuration data may hold sensitive information about the user's account credentials.

The Enterprise Connectors plugin supports three different type of authentication protocols, each one with its respective sub-protocols:

  • HTTP
    • Basic Authentication
  • No Authentication
    • No Authentication
  • OAuth2
    • Client Credentials
    • Password
    • Service Account

To create an authentication configuration, click 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: The protocol of the configuration, which can be:
  • Sub protocol: The sub-protocol. Depending on the protocol selected, the sub-procotol can be:

    Please read each sub-protocol section to know how to fill out the required information.

  • Once the sub-protocol configuration is set, click on Test to confirm that the information is correct. If the credentials given were correct, a green message will be displayed at the top of the window dialog as shown in the image below. Save the configuration by clicking the Save button.

    If a problem occurs, a red dialog message will be displayed containing the error information.

    Protocol: HTTP

    Sub-Protocol: Basic Authentication

    Basic authentication is a simple way to be authenticated using a special HTTP authorization header constructed with the user's username and password encoded in base64. The basic authentication sub-protocol works with services like: Alfresco, Zimbra, twilio, etc.

    • URL: The HTTP authorization header.
    • username: The username of the user account.
    • password: The password of the user account.

    Protocol: No Authentication

    Sub-Protocol: No Authentication

    The no authentication sub-protocol is used when credentials are not required to access the service or when the user needs to set a custom header with their own access token and bearer.

    Protocol: OAuth2

    Sub-Protocol: Client Credentials

    This sub-protocol is used to request authorization to resources owned by the client rather than any specific end-user, using only the client ID and client secret. Since the client authentication is used as the authorization grant, no additional authorization request is needed. The client credentials sub-protocol works with services like ProcessMaker, Bitbucket, etc.

    • tokenCredentialUri: The path of the application from where the token is provided.
    • grant_type: The token grant type. By default, the "client_credentials" option is selected.
    • scope: The access level the application is requesting access to. 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 that was given when registering an application.
    • clientSecret: The client secret code. This code is used to authenticate the identity of the application to the API service when the application requests access to the user's account. The client secret code is given when registering an application.
    Sub-Protocol: Password

    In this type of sub-protocol, the user provides their resource server credentials (username and password) to the Enterprise Connectors plugin, which uses the credentials to obtain an access token from the service. An identity server validates the credentials and if the information is valid, the service proceeds to generate an access token and returns it to the plugin. The password sub-protocol works with services like: SugarCRM, etc.

    • tokenCredentialUri: The path of the application from where the token is provided.
    • grant_type: Token grant type. By default, the password option is selected.
    • scope: The access level the application is requesting access to. This value depends on the service the user is requesting.
    • clientId: The client ID that was given when registering the application.
    • clientSecret: The client secret code. This code is used to authenticate the identity of the application to the API service when the application requests access to the user's account. The Client Secret code is given when registering the application.
    • username: The username of the user account.
    • password: The password of the user account.
    Sub-Protocol: Service Account

    A service account is an account that belongs to your application instead of to an individual end user. With this sub-protocol, 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: The path of the application from where the token is provided.
    • grant_type: The token grant type. The service account sub-protocol uses the value urn:ietf:params:oauth:grant-type:jwt-bearer by default.
    • signingAlgorithm: RS256. Service accounts rely on the RSA SHA-256 algorithm.
    • scope: The list of scopes that the connector should be granted access to. For example, if the connectors need 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.

    Category

    The category section helps the user keep connectors organized by category. Each category belongs to a single authentication configuration.

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

    • Name: Name of the category.
    • Product Name: (Optional) Name of the product, i.e. Sugar CRM.
    • Product Version: (Optional) Version of the product, i.e. 7.
    • API Version: (Optional) Version of the API. Versioning helps the user iterate faster and prevents invalid requests from hitting updated endpoints. i.e. 10.
    • Upload File: (Optional) The category image. Upload an image to easily identify the category.
    • Configuration Auth: The configuration to which this category will belong.

    Once all the properties are set, click on Save.

    Connectors

    The connectors section displays a list of all the connectors available in the current ProcessMaker instance. This section contains a connector wizard to create almost any kind of request quickly, along with a download button to access the Connectors Library.

    • Search: Search for a word in the category, name, description and type columns.
    • Select: Filter the connectors by category.
    • Edit: Edit the connector configuration.
    • Delete: Remove the connector from the ProcessMaker instance.
    • Copy: Users can copy an existing connector and create a new one from the original.

    Connector Wizard

    The connector wizard gives the user tools to set all the necessary parts (URL, method, headers, and body) of a service request. To start creating a connector, click on the Create button and define the following parameters:

    • Name: Name of the connector.
    • Description: A brief description of the connector.
    • Creation Date: The timestamp when the connector was saved. This field is automatically filled in.
    • Category: Select the category to which the connector will belong. The category image and information will be displayed in the Logo field.
    • Method: Request method which can be: GET, POST, PUT, DELETE, PATCH.

    • URL: The URL that points to the resource. This URL can include path parameters that are introduced in the Test Connector section or through the Service Task interface. To manually add a parameter to the path, include the parameter name between {} marks in the URL. For example:
      https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
    • Configuration Auth: Select an authentication configuration.
    • Headers: Request headers, such as Authorization, Accept, Content-Type, etc. This section allows arbitrary HTTP headers to be added that the user might want to include with their request. Note that a header can contain all sorts of meta information that can be overriden or merged with another header during execution. For example, the user can include the Content-Type header with the text encoding used in the message body, as shown in the image below.

    • Query Parameters: (Optional) Query parameters and their description. A query parameter is a method parameter not included in the URL path property to narrow the request response. They are separated from the URL path by the question mark (?).

    • Body Type: The request body type. Depending on the type of request, the body type can be set to Json or Form.
      • Json: Select this option if the data in the request body needs to be sent as a serialized JSON. Most of endpoints work with this type.
        If this option is selected, the following field will be displayed:
        • Body Description: (Optional) A description of all the parameters required in the body, so the user knows how to send the request body.
      • Form: Select this option if the data in the request body needs to be sent encoded as form-data. This option is useful for sending files as part of the request. If this option is selected, the following section will be displayed:
        • Form Parameters: A set of name and value pairs sent in the request. The parameter type can be "text" or "file".
    • Author: The user who created the connector.

    Once the configuration is set, click on Test to display the Test Connector window.

    Test Connector

    This option lets the user test a connector configuration before saving it.

    In the first part of the window, the following information about the connector is displayed:

    • Name: The name of the connector.
    • URL: The URL path.

    Depending on the connector's configuration, the following sections may be filled out with values to be tested.

    • Overwrite Config Parameters: Overwrite any of the header's configuration parameters.
    • Form Parameters: Fill out the form parameters set in the connector configuration.
    • Path Parameters: Fill out the path parameters configured in the connector configuration. These are the method parameters included between {...} marks in the URL property.
    • Query Parameters Fill out the query parameters configured in the connector.
    • Request Body: Introduce a request body in Json format. This field is available only if the connector body type was set to "Json".
    • Once all the test values are set, click the Test button at the end of the window. A new window named Response Connector will be displayed with the response to the connector's request.

      If the response is satisfactory, close this window and save the configuration. If there is a problem, the error will be shown in the Response Connector window as well.

      Connector Public Library

      The connector public library is a central repository of connectors that can be downloaded and customized within any ProcessMaker instance. The connector public library is controlled and constantly updated by ProcessMaker.

      To access this central repository, click on the Download button at the top-right corner of the Connectors panel. A new dialog window will open where the user can select a category.

      In the current version of the Enterprise Connectors plugin, connectors for the following services are available to be downloaded:

      See the complete list of connectors here.

      Select a category and all the connectors available in the library for that service will be listed.

      To download a connector, click the Download button next to its status column.

      A green message will be displayed at the top of the window.

      The window will remain open to download other connectors, and the Download button will be replaced by the Replace button for all the connectors that have been downloaded.

      When a connector of a service that does not exist in the current workspace is downloaded, its default category and authentication configuration will be downloaded as well, to help the user easily configure the connector. The authentication configuration and category are downloaded only the first time a connector from a new category is downloaded.

      The Replace button overwrites the existing connector configuration with the default configuration. A dialog window will be displayed to confirm the action.

      Note that duplicate connectors can NOT exist. Therefore, if a connector with the same name and category of an existing one is detected, only the Replace button will be enabled.

      Connector List

      The following table list all the connectors available to be downloaded in the public connector library.

      Category Version Connector Description
      Google Drive V. 3 Create a File Creates a new file.
      Copy a File Creates a copy of a file and applies any requested updates with patch semantics.
      Delete a File Permanently deletes a file owned by the user without moving it to the trash. If the target is a folder, all descendants owned by the user are also deleted.
      Export a File Exports a Google Doc to the requested MIME type and returns the exported content.
      List Files Lists or searches files.
      Update Files Updates a file's metadata and/or content with patch semantics.
      Create File permission Creates a permission for a file.
      Google Calendar V. 3. Get Event Returns an event.
      Insert an event Creates an event into an specific calendar
      Event Update Updates an event
      Delete event Deletes an event
      Move events Moves an event to another calendar, i.e. changes an event's organizer.
      List calendars Returns entries on the users calendar list
      List events of a calendar Returns events on the specified calendar
      Google Sheets V. 4 Create Sheet Creates a spreadsheet, returning the newly created spreadsheet.
      Get Sheet Copies a single sheet from a spreadsheet to another spreadsheet. Returns the properties of the newly created sheet.
      Append Sheet Values Appends values to a spreadsheet. The input range is used to search for existing data and find a "table" within that range. Values will be appended to the next row of the table, starting with the first column of the table.
      Clear Sheet Values Clears values from a spreadsheet. The caller must specify the spreadsheet ID and range. Only values are cleared -- all other properties of the cell (such as formatting, data validation, etc..) are kept.
      Get Sheet Values Returns a range of values from a spreadsheet. The caller must specify the spreadsheet ID and a range.
      Get Worksheet Returns the spreadsheet at the given ID. The caller must specify the spreadsheet ID.
      Alfresco 5.0.4 Get Items of a task Get Items of a task
      Get Node Gets information of a node
      Get children of a node Lists all descendants of a node
      Add items to a task Creates an item for a given task. If the item already is part of that task the request will have no effect.
      Deletes items from a task Deletes an item from a specific task
      Create a Folder in Repository Creates a folder on a given node
      Download Document/File Downloads a file from the server
      Upload File/Document Uploads a file/document on a given directory
      SugarCRM 7.7 Create Account Creates SugarCRM entries for the Account module
      Create Contact Creates SugarCRM entries for the Contacts module
      Create Leads Creates SugarCRM entries for the Leads module
      Create Opportunities Creates SugarCRM entries for the Opportunities module
      Get Account Gets SugarCRM entries from the Account module
      Get Calls Gets SugarCRM entries from the Calls module
      Get Contacts Gets SugarCRM entries from the Contacts module
      Get Leads Gets SugarCRM entries from the Leads module
      Get Opportunities Gets SugarCRM entries from the Opportunitie smodule
      Zimbra 8.7 Get Folder Gets the items in the folder.
      Get Contacts Gets the contacts in the designated folder. The default folder is "contacts"
      Get Calendar Gets the appointments from the calendar. The default folder is "calendar"
      Get Item Gets an item
      Get Briefcase Gets a briefcase
      DocuSign v. 2 Get Login Information Gets login information for a specified user.
      Create Envelope Create and send an envelope with documents, recipients, and tabs.
      Create and send an envelope from a template.
      Create and send an envelope from a combination of documents and templates.
      Create a draft envelope.
      Get Templates Retrieves all the templates defined in the account
      Get envelope Gets information of a given envelope id.

      Using Connectors Inside Processes

      Connectors can be invoked using a ProcessMaker function or a special type of task.

      executeRestConnector()

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

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

      Parameters:

      • string connectorName: The unique name of the connector.
      • array overwriteParameters: (Optional) Overwrite any of the headers configuration parameters.
      • array pathParameters: (Optional) Required nested parameters in the URL.
      • array queryParameters: (Optional) String value that 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.
      • array configuration: An array with the parameter 'bodyType', which can be 'form-data' or 'json'.

      Example:

      The following trigger executes the uploadFileToDrive connector of the Google Drive service. This connector needs a form-data configuration to upload the file.

      $overwriteParams = [
          'sub' => 'john@example.com'
      ];

      $pathParameters = [];
      $queryParameters = [];
      $requestBody = [
          0 => [
              'name' => 'file',
              'contents' => '/home/ec2-user/contract.pdf',
              'type' => 'file'
          ]
      ];
      $configuration = [
          'bodyType' => 'form-data'
      ];

      $data = executeRestConnector(
          'uploadFileToDrive', //name of the connector
          $overwriteParams,
          $pathParameters,
          $queryParameters,
          $requestBody,
          $configuration
      );

      Response:

      If the trigger is executed successfully, the code of the reponse is 200 and the following message is returned.

      stdClass Object (
          [code] => 200
          [contentType] => Array (
              [0] => application/json;
              charset=UTF-8
          )
          [message] => stdClass Object (
              [kind] => drive#file
              [id] => 0B2amqXoRjLvyTjk0U2dNWDZKdHc
              [name] => Untitled
              [mimeType] => application/pdf
          )
          [rawBody] => {
              "kind": "drive#file",
              "id": "0B2amqXoRjLvyTjk0U2dNWDZKdHc",
              "name": "Untitled",
              "mimeType": "application/pdf" }
          )

      Service Task

      When the Enterprise Connectors plugin is installed and enabled, a service task provides an interface to configure connector execution inside ProcessMaker processes.

      Note: If the Enterprise Connectors plugin is disabled or hasn't been installed in the current ProcessMaker instance, the service task will behave like any other normal task.

      To use the service task, drag and drop a regular task into the process designer and change its task type to Service task.

      An engine icon will appear in the left corner of the task. Access the task configuration by left clicking on the task and selecting Properties.

      Instead of the properties window, the service task configuration window will be displayed with the following fields:

      • Category: Select a category. The image and category information including the product name, product version, and API version used to get access to the resource will be displayed in the boxes under the category field.
      • Connectors: Depending on the selected category, different connectors will be available to be chosen from the list.
      • Description: The description of the connector selected will be displayed.
      • Method: The selected connector's method.
      • URL: The URL of the resource. The URL can include path parameters, which are the path sections enclosed between {...}, that can be specified in the Path Parameters section.
      • Note: Note that the Description, Method and URL fields can not be edited in this section. To modify this information, go to the connector configuration under the Connectors tab.

      • Configuration Auth: Select the authentication configuration.
      • Headers: (Optional) Request headers, such as Authorization, Accept, Content-Type, etc. Headers contain more information about the resource to be fetched or about the client itself. In this section, headers can be added, edited or deleted. If not included, default headers will be used when the connector is executed.

      • Query Parameters: (Optional) Query parameters and their description. Query parameters are the method parameters not included in the URL path property used to narrow the request response. They are separated from the URL path by the question mark (?).

      • Overwrite Config Parameters: Overwrite any of the headers configuration parameters.
      • Path Parameters: URL parameters that were enclosed between {...} will be displayed in this section.
      • Body Type: Depending on the body type selected in the connector configuration, the following sections may or may not be available:
        • Body: Introduces a request body in Json format. This field is available only if the connector body type was set to "Json". ProcessMaker variables can be used in this request body.
        • Form Parameters: Places the set of name and value pairs that will be sent in the request. This field is available only if the connector body type was set to "Form".
      • Variable to hold return value: Define an object variable to store the result of the request by clicking the @@ button and selecting the object variable. The result object usually returns a status and a message serialized in JSON, but it is recommended to inspect the content-type of the requested service to find out what kind of data is returned.

      To see examples of the use of service tasks, please refer to the DocuSign or Alfresco connectors page.

      ProcessMaker Variables

      Process variables can be used to define parameter values in the following sections:

      • Headers
      • Overwrite Config Parameters
      • Path Parameters
      • Query Parameters
      • Body
      • Form parameters

      Using ProcessMaker Endpoints with Enterprise Connectors

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

      Configuration Authentication for ProcessMaker Endpoints

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

      In the next dialog window, fill in 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 obtain access to ProcessMaker services. Therefore, select OAuth2 from the menu.
      • Sub-Protocol: Select Password.

      Before continuing, first it is necessary to register a user application to authorize access to ProcessMaker. By default, the pmConnectorsPlugin application is created when installing the Enterprise Connectors plugin. 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

      Using these credentials, complete the rest of the parameters:

      • tokenCredentialUri: OAuth2.0 authorizes the external application and logs into ProcessMaker in a single step by directly calling the /workspace/oauth2/token.
      • grant_type: The token grant type. password is the option selected by default.
      • scope: The scope that 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 everything is set up properly, 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 under the PM Connectors tab, and click on Create to 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 used 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 in the current workspace.

      First, go to the PM Connectors 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 add 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 to modify its Datasource property and select the 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 usernames retrieved for the connector will be set as dropdown's options.