ProcessMaker API Documentation
Script Central

Example Data Connector Use Case

Follow an example that uses a ProcessMaker Data Connector to get a list of worldwide universities that become the options in a Select List control within a ProcessMaker Screen.

Overview

This example demonstrates how a Select List control in a ProcessMaker Screen can display the names of major universities around the world as its options in a drop-down menu. The options in this Select List control come from a ProcessMaker Data Connector that calls a third-party Application Program Interface (API) when the ProcessMaker Screen containing the Select List control opens. This example demonstrates dependent fields: how the options in one Select List control depend on which option is selected from a previous Select List control. Click in the Select List control's drop-down menu to select an option or start typing into the control to filter those university names that match the text entered into the control.

Note that after creating this ProcessMaker Data Connector, it may be used for any ProcessMaker asset in your ProcessMaker instance that can use a Data Connector. It is not limited to being used with a Select List control.

Click the video below to watch a demonstration of this example.

  • Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers

  • Viewing time: 9 minutes; contains narration

This example contains the following procedures in this order:

  1. Create the ProcessMaker Data Connector: Create the ProcessMaker Data Connector that calls the API containing the list of universities. This is a public API that has been made available for demonstration purposes, so it does not require host authentication. The list of universities is in a JSON object. Though the host provides the domains, names, and countries of origin for each university in its list, this example references only the university name. The host provides public information about this API. See Create the ProcessMaker Data Connector.

  2. Configure the Select List control: After the ProcessMaker Data Connector is created, create a ProcessMaker Screen that contains a configure a Select List control. Configure the Select List control to use this ProcessMaker Data Connector as its data source to get the list of universities as the Select List control's options. See Configure the Select List Control.

  3. Create the Process model: Create the Process model to include a Form Task element that references the ProcessMaker Screen containing the Select List control. See Create the Process Model.

  4. Start a Request: Start a Request for the Process as designed in the Process model for this example. See Start a Request for the Example Process.

Create the ProcessMaker Data Connector

Follow these steps to create the ProcessMaker Data Connector as described in this example:

  1. Log on to ProcessMaker.

  2. Click the Designer option from the top menu. The Processes page displays.

  3. Click the Data Connectors iconfrom the left sidebar. The Data Connectors tab displays all ProcessMaker Data Connectors in the Data Connectors page.

  4. Verify the ProcessMaker Data Connector Category exists in which to assign this Data Connector. If this Category does not exist, see Create a New Data Connector Category.

  5. Click the +Data Connector button. The Create Data Connector screen displays.

  6. In the Name setting, enter the name of the ProcessMaker Data Connector. This example uses the name Get List of Major Universities in the World.

  7. In the Description setting, enter a description of this ProcessMaker Data Connector.

  8. From the Authentication Type drop-down menu, select the No Auth option. This example uses this option because the host does not require authentication from its publicly accessible API. Note that the video of this example uses Basic Auth, which is not necessary for this example since the data source is publicly accessible.

  9. From the Category drop-down menu, select the ProcessMaker Data Connector Category to assign this Data Connector.

    This example uses the following settings.

  10. Click Save. The Details tab displays to edit the settings for this ProcessMaker Data Connector.

  11. Click the Endpoints tab. This example requires no changes to the Authorization tab.

  12. Click the +Endpoint button. The Add Endpoint screen displays.

  13. In the Purpose setting, optionally edit the purpose for this Endpoint. The value the Purpose setting displays from the ProcessMaker asset when configuring the data source from that ProcessMaker asset. In this example, this setting value displays from the Select List control to select this Endpoint to get the list of universities. Therefore, provide a concise but relevant purpose for this Endpoint so other ProcessMaker designers understand its function. This example uses list universities for this setting.

  14. In the Description setting, enter a description of this Endpoint. This example uses the following description: This Endpoint gets a JSON list of worldwide universities..

  15. From the Method drop-down menu, select the GET option. The GET method reads data.

  16. In the URL setting, enter the following URL for this example: http://universities.hipolabs.com/search?. This URL is truncated from the host's documented example how to search its public API.

  17. Click Add. The Endpoints tab displays the configuration settings for the new Endpoint in the Config sub-tab.

  18. Click the Test tab, and then click the Run button to verify that the Endpoint functions as intended. If configured correctly, the Endpoint response displays.

  19. Notice which element in each JSON object within the Endpoint response contains the name of the university. Look at the first JSON object that is the list of universities: {

    "domains": [

    "marywood.edu"

    ],

    "country": "United States",

    "web_pages": [

    "http://www.marywood.edu"

    ],

    "name": "Marywood University",

    "state-province": null,

    "alpha_two_code": "PA"

    },

    The name element contains the name of each university in this JSON object. Make note of the element's name that contains relevant data from a data source, as the ProcessMaker asset requires this element name when configuring which data that asset requires from the ProcessMaker Data Connector's Endpoint response. In this example, the ProcessMaker Screen containing the Select List control is the ProcessMaker asset.

  20. Click Close to close the Test screen, and then click Save to save the Endpoint. The ProcessMaker Data Connector is configured for this example.

Configure the Select List Control

Follow these steps to configure the Select List control as described in this example:

  1. Create a ProcessMaker Screen for this example. This example uses the name Data Connector Example Using a Select List Control for the ProcessMaker Screen.

  2. Most settings for the Select List control are outside the scope of this example. The default settings can be used for require settings, and optional settings do not need to be configured.

  3. Expand the Data Source panel.

  4. From the Data Source drop-down menu, select the Data Connector option. Settings in the Data Source panel display to configure which ProcessMaker Data Connector and Endpoint this control uses as its data source.

  5. In the Existing Request Data Variable setting, keep the default response value. This setting represents the name of the JSON object that contains the response from the ProcessMaker Data Connector's Endpoint. In this example, response will contain the JSON array of universities.

  6. From the Type of Value Returned drop-down menu, select the Single Value option because this example requires only one element value from the JSON response.

  7. From the Data Connector drop-down menu, select the ProcessMaker Data Connector the Select List control uses to access the data source. For this example, select Get List of Major Universities in the World.

  8. From the End Point drop-down menu, select which Endpoint in the selected ProcessMaker Data Connector to access the data source. For this example, select list universities.

  9. In the Value setting, enter the JSON element name that contains the value to use as the Select List option in each JSON object of the Endpoint response. In this example, enter name because the name JSON element contains the name of each university in each JSON object.

  10. In the Content setting enter name for the same reason as above.

  11. Add a Submit Button control to the ProcessMaker Screen page so that the Screen can be submitted.

  12. In the Submit Button control, enter a value for the Variable Name setting. This example uses submit for the Variable Name setting value.

  13. Save your ProcessMaker Screen. The Select List control is configured for this example.

Create the Process Model

Follow these steps to create the Process model as described in this example:

  1. Create a new Process. This example uses the Process name List Universities Example.

  2. Add the following BPMN elements to the Process model in that order, and then connect them with Sequence Flow elements:

  3. From the Form Task element, select the ProcessMaker Screen for this example. This example uses the ProcessMaker Screen named Data Connector Example Using a Select List Control.

  4. Save your Process model. None of the other Process model settings are in the scope of this example. The Process is configured for this example.

Start a Request for the Example Process

The example is ready to demonstrate. To demonstrate this example, start a Request of this Process.

Follow these steps to start a Request of this Process as described in this example:

  1. Start a Request of this Process. Remember that the Process name is List Universities Example.

  2. Open the Form Task from your To Do Tasks. The Process model is configured by default that the Requester is the Task assignee. After opening the Form Task, the ProcessMaker Screen with the Select List control in the example displays.

  3. Click the Select List control. The list of universities displays in the same order as they are listed in the host's JSON array. When the ProcessMaker Screen opens for the Form Task, the Select List control uses the ProcessMaker Data Connector to call the host's Application Program Interface (API) and get the complete JSON array, but only display the name element value for each JSON object in that array.

  4. Type in the Select List control to filter the list of universities that display for selection in the control. For example, start to type Harvard to select Harvard University.

Related Topics