Example: Data Connector Provides Options in a Select List Control
Follow an example that uses a Data Connector to get a list of worldwide universities that become the options in a Select List control within a Screen.
This example demonstrates how a Select List control in a 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 Data Connector that calls a third-party Application Program Interface (API) when the Screen containing the Select List control opens. 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 Data Connector, it may be used for any ProcessMaker asset 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
- Note: The video demonstrates how to configure the Data Connector using obsolete settings. The written form of this example documents how to configure the Data Connector using current settings.
This example contains the following procedures in this order:
- 1.Create the Data Connector: Create the 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 Data Connector.
- 2.Configure the Select List control: After the Data Connector is created, create a Screen that contains a Select List control. Configure the Select List control to use this 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.
- 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 Data Connectors in the Data Connectors page.
- 5.Click the +Data Connector button. The Create Data Connector screen displays.
- 6.In the Name setting, enter the name of the 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 Data Connector. This example uses the description:
This ProcessMaker Data Connector gets a list of major universities around the world in JSON structure.
- 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 Data Connector Category to assign this Data Connector. This example uses the following settings.
- 10.Click Save. The Data Connector is created and the Resources tab displays.
- 11.Click the +Resources button. The Create Resource screen displays.
- 12.In the Name setting, optionally edit the purpose for this Resource. The value the Name setting displays from the ProcessMaker asset when configuring the data source from that asset. In this example, this setting value displays from the Select List control to select this Resource to get the list of universities. Therefore, provide a concise but relevant purpose for this Resource so other ProcessMaker designers understand its function. This example uses
list universitiesfor this setting.
- 13.In the Description setting, enter a description of this Resource. This example uses the following description:
This Resource gets a JSON list of worldwide universities.
- 14.From the Method drop-down menu, select the GET option. The GET method reads data.
- 16.Click Add. The new Resource displays in the Configuration tab.
- 17.Click the Send button. If configured correctly, the Response Body tab displays the Resource response.
- 18.Notice which element in each JSON object within the API endpoint response contains the name of the university. Look at the first JSON object that is the list of universities:
"country": "United States",
"name": "Marywood University",
nameelement 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 Data Connector's Resource response. In this example, the Screen containing the Select List control is the ProcessMaker asset.
- 19.Click Save to save the Resource. The Data Connector is configured for this example.
- 3.Most settings for the Select List control are outside the scope of this example. The default settings can be used for required settings, and optional settings do not need to be configured.
- 4.Expand the Data Source panel.
- 5.From the Data Source drop-down menu, select the Data Connector option. Settings in the Data Source panel display to configure which Data Connector and Resource this control uses as its data source.
- 6.In the Options Variable setting, keep the default
responsevalue. This setting represents the name of the JSON object that contains the response from the Data Connector's Resource. In this example,
responsewill contain the JSON array of universities.
- 7.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.
- 8.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 Resource response. In this example, enter
nameJSON element contains the name of each university in each JSON object.
- 9.In the Content setting enter
namefor the same reason as above.
- 10.From the Data Connector drop-down menu, select the Data Connector the Select List control uses to access the data source. For this example, select Get List of Major Universities in the World.
- 11.From the End Point drop-down menu, select which Resource in the selected Data Connector to access the data source. For this example, select list universities.
The example is ready to demonstrate. To demonstrate this example, start a Request of this Process.
- 2.Open the Form Task from your To Do Tasks. The Process model is configured by default that the Request starter is the Task assignee. After opening the Form Task, the 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 Screen opens for the Form Task, the Select List control uses the Data Connector to call the host's Application Program Interface (API) and get the complete JSON array, but only display the
nameelement 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
Harvardto select Harvard University.