Contents: [hide]

Plugin Version: 1.2.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 features:

  • 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 1.2.0 has the following requirements:

  • 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. Do one of the following options:

  • Install the Enterprise Connectors plugin by clicking on Install from File and uploading the plugin file.
  • Click on the Enterprise Connectors plugin's Install Now button in the list of available plugins.

After installing the plugin, make sure that the Enterprise Connectors plugin is enabled . If the plugin is not enabled, click the Enable button, as shown in the graphic below.

Customizing the Skin

The default skin of the Enterprise Connectors plugin is defined in the skinConfig.ini file located at:

<install-directory>/processmaker/workflow/engine/plugins/pmConnectors/config

To use a different skin, configure the sample skin configuration file, which is named skinConfig.ini.example and contains the following code:

#[skin-name] #files[] = 'path-css'

Replace the path-css parameter with the path of your custom CSS file and uncomment both lines by removing the # symbol.

[customSkinOne] files[] = '/css/customSkinOne'

Finally, overwrite the original file by renaming the skinConfig.ini.example to skinConfig.ini.

Connectors Wizard

After 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 tab is divided in three parts:

Authentication Configuration

The Authentication Configuration 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 types of authentication protocols, each one with its respective sub-protocols:

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

To create a new authentication configuration, click the Create button at the top-right of the section.

The Authentication Configuration dialog is 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.

  • After 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: Authorization Code

    The sub-protocol should be very familiar if the user has ever signed into a web app using their Facebook, Google, Adobe Sign, among other accounts.

    • grant_type: The token grant type. By default, the "authorization_code" option is selected.
    • authorizationUri: The Authorization URL of the API Service Provider where ProcessMaker will make the request to obtain an authorization code.
    • tokenCredentialUri: The path of the application that provided the token.
    • refreshTokenUri: An encrypted payload that can be used to refresh the access token when it expires.
    • redirectUri: The client redirect URI. This parameter is optional, but if not send the user will be redirected to a pre-registered redirect URI.
    • 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.
    • scope: The list of scopes that the connector is 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.
    • response_type: The value of the autorization response code.
    • masterCredentials: Levels of accesing the service from the plugin.
      • True: If set to true, the tokens generated by this service is shared by all the users in ProcessMaker.
      • False: If set to false, the tokens will not be shared and each user should generate their own tokens.
    • authorizationPrefix: The token type that will be used in the authorization header, which is set to "Bearer" by default in sub-protocols that use OAuth2, but can be edited depending on the web service.
    • headerAuthorization: The type of authorization, which is set to "Authorization" by default, but can be edited depending on the web service.
    • audience: The audience for the generated token to know which API issue can access the token. The audience should be in a JWT format.
    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, Adobe Cold Fusion, and others.

    • tokenCredentialUri: The path of the application that provided the token.
    • grant_type: The token grant type. By default, the "client_credentials" option is selected.
    • scope: The access level the application can request access to. The options include: * (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 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.
    • authorizationPrefix: The token type that will be used in the authorization header, which is set to "Bearer" by default in sub-protocols that use OAuth2, but can be edited depending on the web service.
    • headerAuthorization: The type of authorization, which is set to "Authorization" by default, but can be edited depending on the web service.
    • audience: The audience for the generated token to know which API issue can access the token. The audience should be in a JWT format.
    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, Oracle, Zendesk and others.

    • tokenCredentialUri: The path of the application that provided the token.
    • grant_type: Token grant type. By default, the password option is selected.
    • scope: The access level the application can request 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.
    • authorizationPrefix: The token type that will be used in the authorization header, which is set to "Bearer" by default in sub-protocols that use OAuth2, but can be edited depending on the web service.
    • headerAuthorization: The type of authorization, which is set to "Authorization" by default, but can be edited depending on the web service.
    • audience: The audience for the generated token to know which API issue can access the token. The audience should be in a JWT format.
    Sub-Protocol: Service Account

    A service account is an account that belongs to the 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 that provided the token.
    • 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 is 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.
    • authorizationPrefix: The token type that will be used in the authorization header, which is set to "Bearer" by default in sub-protocols that use OAuth2, but can be edited depending on the web service.
    • headerAuthorization: The type of authorization, which is set to "Authorization" by default, but can be edited depending on the web service.
    • audience: The audience for the generated token to know which API issue can access the token. The audience should be in a JWT format.

    Services

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

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

    • Name: Name of the service.
    • 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 Service image. Upload an image to easily identify the service.
    • Authentication Configuration: The configuration to which this service will belong.

    After 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 services, name, description and type columns.
    • Select: Filter the connectors by services.
    • 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 at the top-right corner of the Connectors panel and define the following parameters:

    • Name: Name of the connector.
    • Description: A brief description of the connector.
    • Date Created: The timestamp when the connector was saved. This field is automatically filled in.
    • Services: Select the service to which the connector will belong. The service 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
    • Authentication Configuration: Select an authentication configuration.
    • Headers: (Optional) 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 overridden 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.

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

    Testing a Connector

    The Test button at the end of the Connectors window lets the user test a connector configuration before saving it. By clicking it, the Test Connector window will be displayed:

    In the first part of this window, 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. An example of a path parameter is marked in red in the image above.
    • 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".
    • After all the test values are set, click the Test button at the end of the window. A new window named Response 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 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 service.

      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 service 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.

      Service 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 uploads a local file to a Google Drive account. Two calls are made to the Google Drive service. In the first call, the file is uploaded. In the second call, the file is renamed and added to a folder.

      //This parameter overwrites any OAuth configurations set in the connector configuration.
      //In this case overWriteParameters replaces the variable with the email address of a user in the domain. The ID to be used is the email address (this is just for Google Drive endpoints.)
      $overWriteParameters = ['sub' => 'john@example.com'];

      //If the configured connector has some path parameters, they should be configured in this array.
      $pathParameters = [];

      //If the endpoint needs query parameters (the ones that are after the url’s question mark) they should be added in this array.
      //In this case is needed to send ?uploadType=multipart
      $queryParameters = ["uploadType" => "multipart"];

      //The body to send to the endpoint. If the body type is JSON a simple associated array is sent.
      //In this case the connector has a body type of form-data, so an array of arrays is sent. Change the file parameter to one existing in the server.
      $requestBody = [
          ['name'=>'uploadType', 'contents'=>'file', 'type'=>'text'],
          ['name'=>'title', 'contents'=>'test', 'type'=>'text'],
          ['name'=>'file', 'contents'=>'/home/john/Downloads/contract.pdf', 'type'=>'file']
          ];

      //In this array any additional configuration parameter must be sent. In this case the config variable sends the body type.
      $config = ['bodyType' => 'form-data'];

      //The uploadFileToDrive function with all our previous parameters is executed.
      $response = executeRestConnector('uploadFileToDrive', $overWriteParameters, $pathParameters, $queryParameters, $requestBody, $config);

      //Google will return the file ID of the uploaded file in the response variable. This ID will be stored in the uploadedFileId variable.
      $uploadedFileId = $response->message->id;

      //This is the name that the file will have.
      $fileName = 'MyUploadedFile.pdf';

      //This is the directory ID (of Google Drive) where the file will be stored.
      //Get this ID by going inside the directory and copying the last part of the URL, for example: https://drive.google.com/drive/u/0/folders/0B6sVMFnKbbFRQVZnSjdTY1dNdkk
      $directoryId = '0B6sVMFnKbbFRQVZnSjdTY1dNdkk';

      //The updated file is called to change the name and add the file to some directory.
      $overWriteParameters = ['sub' => 'john@example.com'];

      $pathParameters = [
          "fileId" => $uploadedFileId
      ];

      //This query parameter adds the file to the Google Drive folder. To move the file to a new directory, change here the directoryId variable.
      $queryParameters = [
          "addParents" => $directoryId
      ];

      //In this call the body is the default (JSON) so a simple associated array is sent.
      $requestBody = [
          "name" => $fileName
      ];
      $response2 = executeRestConnector('updateFile', $overWriteParameters, $pathParameters, $queryParameters, $requestBody);

      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" }
          )

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

      Service Task

      When the Enterprise Connectors plugin is installed and enabled, service tasks become available in the designer. Service tasks provide connections between outside web services and processes in ProcessMaker.

      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. A gear 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 two tabs: Request Configuration and Response Configuration.

      Request Configuration

      The Request Configuration tab allow users to select and configure the connector the service task will use to make its request. This tab includes the following fields:

      • Services: Select a service. The image and service 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 Services field.
      • Connector: 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.

      • Authentication Configuration: Select the authentication configuration.

      Scroll down the window to configure the connector's other parameters.

      • 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 descriptions. 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 a question mark (?).
      • Overwrite Configuration Parameters: Add overwrites of the header's configuration parameters here.
      • Path Parameters: URL parameters that were enclosed between {...} will be displayed in this section.

      Scroll down the window to complete the request body.

      • 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".
      • ProcessMaker Variables

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

        • Headers
        • Overwrite Configuration Parameters
        • Path Parameters
        • Query Parameters
        • Body
        • Form Parameters

        Response Configuration

        The response configuration includes the following fields:

        • Response Variable: 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.
        • Response Mapping:
          • None: This option is selected by default, and means that no mapping will be performed.
          • Variables: Select this option to extract values from the object variable that contains the endpoint response and put them into ProcessMaker variables. For more information, go here.
          • Trigger: Select this option to use the response contained in the object variable in a trigger where the user can map it manually. For more information about this option, go here.
        Response Mapping Using Variables

        Select the Variables option to extract specific values from an HTTP response body.

        Click the Add Variable button, and a dialog window will be displayed where a new variable can be configured:

        • Variable: (Required) Select a variable to store the extracted value of the JSON body. The @@ button is located next to this field to allow users to easily select a preexisting variable. The following variable types can be used:
          • String Type - @@
          • Integer Type - @%
          • Object Type - @&
        • Mapped Object: (Required) Specify the part of the response to be extracted by accessing the object properties using PHP object standard syntax (->).
          message->property

        Before defining the variables and mapped objects, it is necessary to know the structure of the response body. For example, if the response body consists of the following JSON:

        "response" : {
           "code":201,
           "contentType":[
              "application\/json; charset=utf-8"
           ],
           "message":{
              "envelopeId":"5d2da4e5-41dc-4a5f-9716-d353035d8096",
              "uri":"\/envelopes\/5d2da4e5-41dc-4a5f-9716-d353035d8096",
              "statusDateTime":"2017-05-25T21:16:08.2970000Z",
              "status":"sent"
           }
        }

        • To get the response code, the mapped object will be: code
        • To get the envelopeId, the mapped object will be: message->envelopeId
        • To get the envelope status, the mapped object will be: message->status

        After the variables and mapped objects are defined, the response configuration will look like the image below.

        To see how to test this configuration, go here.

        Response Mapping Using Triggers

        The Trigger option allows users to use the data stored in the object variable in an existing trigger by accessing the object properties using PHP object standard syntax.

        Select a trigger in the Title dropdown. The PHP code of the trigger will be displayed in the Response Code textarea. To make the code easier to read and to help eliminate careless errors, the code editor contains syntax highlighting, parentheses, bracket matching and line numbering.

      Also, a new trigger can be created by clicking on the plus button. A new panel will be displayed in the same window where the title and PHP code of the new trigger can be filled in, as shown in the following image:

      Note that the new trigger will be created when the service task configuration is saved.

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

      Testing the Service Task Configuration

      After the service task is configured, click on the Test button at the end of the window to see if the configuration is set correctly before saving it. If the None or Trigger option was selected in the Response Mapping section, the following window will be displayed:

      If the Variable option was selected, an additional section named Test Result will be displayed at the bottom of the window.

      The Test Result section lists the variable mapping results in a table where the user can check to see if the mapped object values are stored in the proper variables correctly:

      • Variable: The variable selected to stored the response value.
      • Response Property: The property of the reponse that will be stored in the variable.
      • Status: The status of the test. A "passed" message will be displayed in this column if the variable stored valid data. Otherwise, a "failed" message will be displayed if the data couldn't be stored in the variable or the endpoint didn't retrieve any data.
      • Value: The data retrieved from the endpoint response.

      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 Authentication Configuration 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.
      • authorizationPrefix: The token type that will be used in the authorization header, which is set to "Bearer" by default in sub-protocols that use OAuth2.
      • headerAuthorization: The type of authorization, which is set to "Authorization" by default.
      • audience: The audience for the generated token to know which API issue can access the token. The audience should be in a JWT format. Left blank if is not necessary configure audience.

      After 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 Service for ProcessMaker Endpoints

      After that, select the Services option under the PM Connectors tab, and click on Create to create a new service.

      In the next dialog window, fill in the following fields:

      • Name: Name of the service. In this example the service is named as "ProcessMaker".
      • Product Name: (Optional) Name of the product, e.g. ProcessMaker.
      • Product Version: (Optional) Version of the product, e.g. 3.2.
      • API Version: (Optional) Version of the API. Versioning helps the user iterate faster and prevents invalid requests from hitting updated endpoints. e.g. 3.2.
      • Upload File: (Optional) The Service image. Upload an image to easily identify the service.
      • Authentication Configuration: The configuration to which this service will belong. In this example the service selected is "ProcessMaker Authentication Service".

      Finally, click on Save to save the data.

      After setting these configurations (Authentication Configuration and Services), 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 dialog will open with the response given by the service.

      After 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.