Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Follow an demonstrative example that shows and hides controls in a Screen based on visibility rules set by the selected button.
Intended audience: Process designers, Web designers, graphic designers
Tags: Submit Button control; Rich Text control; Multicolumn / Table control; visibility rule; Screen design
Use visibility rules to design how Screen Builder controls show and/or hide based on Request variable values while that Screen is open during a Task. The following example demonstrates how to use visibility rules in Screen design. From among four different Submit Button controls, after one button is selected, one among four Rich Text controls display while the others hide. This example demonstrates how to show and/or hide controls in the Screen as the user interacts with it.
This example contains the following procedures in this order:
After designing the example, preview it.
Follow these steps to add and configure a Multicolumn / Table control for this example:
Log on to ProcessMaker Platform.
In the Name setting, enter the name of the Screen. This example uses the name Show and Hide Controls Based on Visibility Rules
.
In the Description setting, enter a description of this Screen.
From the Type setting, select the Form option.
Click Save. The Screen is created and opens in Screen Builder to design.
This example uses four (4) columns. Since the total column span must equal to 12, each of the four columns must be a column span setting of 3
. Follow these steps to configure these four columns:
In the Column Width setting, enter 3
.
Click OK. The new column with a column span setting of 3
displays.
Remove the other default column that has a column span of 6.
Repeat steps 2 through 4 to add a third column with a column span of 3.
Repeat steps 2 through 4 to add a fourth column with a column span of 3.
This example uses four Submit Button controls from which to demonstrate how Rich Text controls show and hide based on which of the four buttons is selected.
Follow these steps to add and configure four Submit Button controls for this example:
Add the first Submit Button control to the leftmost column in the Multicolumn / Table control, and then configure that control with the following setting values:
Label: In the Label setting, enter Tip 1
for this example.
Variable Name: In the Variable Name setting, enter tip
for this example. Note this value because this will be used for the other Submit Button controls as well.
Value: In the Value setting, enter 1
for this example to represent the first of the four Submit Button controls. When this button is clicked, this control sets the tip
variable to 1
.
Type: From the Type setting in the Configuration panel, select the Regular Button option for this example. The default Submit Button option submits the Screen when used in a Request, which is not the intended design for this example. Furthermore, when previewing this Screen, a message displays that the Screen was submitted.
Add the second Submit Button control to the second column in the Multicolumn / Table control, and then configure that control with the following setting values:
Label: In the Label setting, enter Tip 2
for this example.
Variable Name: In the Variable Name setting, enter tip
for this example.
Value: In the Value setting, enter 2
for this example to represent the second of the four Submit Button controls. When this button is clicked, this control sets the tip
variable to 2
.
Type: From the Type setting in the Configuration panel, select the Regular Button option.
Add the third Submit Button control to the third column in the Multicolumn / Table control, and then configure that control with the following setting values:
Label: In the Label setting, enter Tip 3
for this example.
Variable Name: In the Variable Name setting, enter tip
for this example.
Value: In the Value setting, enter 3
for this example to represent the third of the four Submit Button controls. When this button is clicked, this control sets the tip
variable to 3
.
Type: From the Type setting in the Configuration panel, select the Regular Button option.
Add the fourth Submit Button control to the fourth column in the Multicolumn / Table control, and then configure that control with the following setting values:
Label: In the Label setting, enter Tip 4
for this example.
Variable Name: In the Variable Name setting, enter tip
for this example.
Value: In the Value setting, enter 4
for this example to represent the fourth of the four Submit Button controls. When this button is clicked, this control sets the tip
variable to 4
.
Type: From the Type setting in the Configuration panel, select the Regular Button option.
This example uses four Rich Text controls that show or hide based on which of the four Submit Button controls are selected.
Follow these steps to add and configure four Rich Text controls for this example:
Add the first Rich Text control below the Multicolumn / Table control, and then configure that control with the following setting values:
Content: In the Content setting, enter text that displays when this Rich Text control shows. This example uses the following text: <h2>Tip 1</h2>
<p>This is Tip 1 that displays when the "Tip 1" button is selected.</p>
Visibility Rule: In the Visibility Rule setting in the Advanced panel, enter tip == "1"
. Whenever the variable tip
equals 1
, then this control displays. In this example, tip
is set to 1
only when the Submit Button control that is labeled Tip 1 is selected.
Add the second Rich Text control below the first Rich Text control, and then configure that control with the following setting values:
Content: In the Content setting, enter text that displays when this Rich Text control shows. This example uses the following text: <h2>Tip 2</h2>
<p>This is Tip 2 that displays when the "Tip 2" button is selected.</p>
Visibility Rule: In the Visibility Rule setting in the Advanced panel, enter tip == "2"
. Whenever the variable tip
equals 2
, then this control displays. In this example, tip
is set to 2
only when the Submit Button control that is labeled Tip 2 is selected.
Add the third Rich Text control below the second Rich Text control, and then configure that control with the following setting values:
Content: In the Content setting, enter text that displays when this Rich Text control shows. This example uses the following text: <h2>Tip 3</h2>
<p>This is Tip 3 that displays when the "Tip 3" button is selected.</p>
Visibility Rule: In the Visibility Rule setting in the Advanced panel, enter tip == "3"
. Whenever the variable tip
equals 3
, then this control displays. In this example, tip
is set to 3
only when the Submit Button control that is labeled Tip 3 is selected.
Add the fourth Rich Text control below the third Rich Text control, and then configure that control with the following setting values:
Content: In the Content setting, enter text that displays when this Rich Text control shows. This example uses the following text: <h2>Tip 4</h2>
<p>This is Tip 4 that displays when the "Tip 4" button is selected.</p>
Visibility Rule: In the Visibility Rule setting in the Advanced panel, enter tip == "4"
. Whenever the variable tip
equals 4
, then this control displays. In this example, tip
is set to 4
only when the Submit Button control that is labeled Tip 4 is selected.
After designing the example that demonstrates how to show and hide controls, preview it:
Click the Preview button if you are in Design mode. The four Submit Button controls display.
Upon selection, the Rich Text control displays in which its Visibility Rule setting is set for tip == "1"
. When that Submit Button control is selected, it sets the variable tip
to the value 1
. ProcessMaker Platform evaluates all visibility rules that meet that condition, and then displays those controls that meet that condition. All other controls in the Screen hide.
Create a new Screen. The Create Screen screen displays.
From the Category drop-down menu, select the Screen Category to assign this Screen. This example uses the following settings.
Add a Multicolumn / Table control. The control displays with two columns by default, each with a 6 column span setting.
Remove one of the default columns with a column span of 6 by clicking its Remove icon since the default columns are too wide to accommodate two more columns and still equal 12 column span.
Click the Add Column button to add a new column. The Add New Column screen displays.
The Multicolumn / Table control now has four columns, each with a column span setting of 3
.
The four Submit Button controls are now placed in the Multicolumn / Table control.
Select any of the Submit Button controls, such as the one labeled Tip 1.
Follow an example that uses a Collection containing records of all countries and their regions that display in dependent Select List controls.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Collections; Select List control; dependent fields; geographical location; Screen design
The Select List control in ProcessMaker Platform allows Process Designers to filter the contents of a list in real-time by using PMQL. Through this feature, the data displayed in a Select List control can change dynamically depending on the selection in another control or the value in a Request variable.
Would you like to see this example that uses two Data Connectors that access the data sources from which the Select List controls reference countries and their corresponding regions? See Example: Dependent Select List Controls Display Countries and Regions Using Two Data Connectors.
The following example demonstrates dependent fields: how the options in one Select List control depend on which option is selected from a previous Select List control. This example demonstrates that after a country is selected from one Select List control, a second Select List control contains as options the regions in that selected country. This example uses a Collection that contains a list of countries and regions within those countries.
Each record in the Collection contains multiple fields, including but not limited to the following:
Country Name
Sub-country (region or city)
For the purposes of this example, only the country name and region are relevant. Below is an example of a Collection with the relevant country name and associated region or city within that record after columns within the Collection are configured.
The two Select List controls for this example both reference the same Collection as the data source for their options. When a country is selected from one Select List control, only the regions associated with that selected country are available as options in the second Select List control: the second Select List control depends on the first Select List control for its options.
This example requires the following procedures:
Import and configure a Collection: Import a Collection that serves as a data source for both Select List controls.
Design a Screen with dependent controls: Design a Screen which displays two dependent Select List controls where the data in the second control is dependent on the selection made in the first control.
Follow these steps to import the Collection needed for this example:
Download the attached ZIP file below the following screenshot.
Extract the JSON file contained within the downloaded ZIP file. This is the Collection for this example.
Import the Collection. The Collection displays in the Collections page.
Follow these steps to design a Screen that uses dependent Select List controls as described in this example:
Create a new Screen. The Screen displays in Screen Builder.
Add the Select List control from which to select a country from the list of countries.
Add the Select List control from which to select a region from the selected country in the first Select List control. This is the dependent control.
For the first Select List control, configure the following settings:
Variable Name: Enter Countries
in the Variable Name property.
Data Source: Select the option Collection from the Data Source property.
Collection: From the Collection drop-down menu, select the Collection Countries with Regions
. If you are unable to see this Collection as an option, then review the steps in Import and Configure a Collection section again.
Label: From the Label drop-down menu, select the option Countries
.
For the second Select List control, configure the following settings:
Variable Name: Enter Countries
in the Variable Name property.
Data Source: Select the option Collection from the Data Source property.
Collection: From the Collection drop-down menu, select the Collection Countries with Regions
. If you are unable to see this Collection in the list, review the steps in Import and Configure a Collection section again.
Label: From the Label drop-down menu, select the option Countries
.
Value: From the Value drop-down menu, select the option Countries
.
Preview the Screen. The Countries Select List control displays a list of countries from the Countries with Regions Collection.
Select a country from the list. The Regions in the Selected Country Select List control only displays regions from the selected country. The second Select List control depends on the first for its options.
Follow an example that uses a Page Navigation control to navigate between multiple pages within a Screen.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Page Navigation Control; multiple page form; Multicolumn / Table control; Screen design
The image below shows a multi-page Screen that uses Page Navigation controls in the following ways:
Each Page Navigation control at the bottom of of each Screen page guides the Request participant in a sequential order of the multiple pages similar to a wizard. Information must be provided or reviewed in a specific order.
Page Navigation controls along the top of each all pages in the Screen provide menu navigation similar to a website.
Use Multicolumn / Table controls to equidistantly space the Page Navigation controls on the top and/or the bottom of each page in the Screen. In the image below, the top of each page uses a Multicolumn / Table control with four columns, each with a Colspan setting of 3
; the bottom of each page uses a Multicolumn / Table control with two columns, each with a Colspan setting of 6.
To imply that previous pages within the Screen are completed, add a unique character preceding the default button label in the Button Label setting for those Page Navigation controls on the latter pages of the Screen for which the preceding pages are complete. For example, to imply that the information in the Profile page of your multi-page Screen is complete, on all pages after the Profile page for those Page Navigation controls that link to that page, set those controls' Button Label settings to ✓Profile
.
Follow an example that uses two Data Connectors and a Watcher to get a list of all countries and their regions that display in dependent Select List controls.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Data Connector; Watchers; Select List control; dependent fields; geographical location; Screen design
The following example demonstrates dependent fields: how the options in one Select List control depend on which option is selected from a previous Select List control. This example demonstrates that after a country is selected from one Select List control, a second Select List control contains as options the states and/or provinces in that selected country. This example uses two Data Connectors, one to get the list of countries, the other to get the list of regions.
Would you like to see this example that uses a Collection data source from which the Select List controls reference countries and their corresponding regions? See Example: Dependent Select List Controls Display Countries and Regions from a Collection.
The Select List control that contains the countries as its options gets those options from a Data Connector that uses a Resource to get the list of countries and their corresponding International Organization for Standardization (ISO) country code from a third-party application program interface (API). A Watcher monitors when a country is selected, and then another Data Connector uses a Resource to get the list of states and/or provinces from that selected country based on that country's ISO code. The Watcher stores that list of states/provinces as a Request variable in that Request's data so that the second Select List control may access that list to display as its options. The second Select List control's options depend on the first Select List control's selection.
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: 21 minutes; contains narration
Note: The video demonstrates how to configure the Select List controls using obsolete settings. The written form of this example documents how to configure the Select List controls using current settings.
This example refers to Request data, Request variables, and uses JSON. If you are not familiar with these concepts or JSON, see the following topics for a primer:
This example contains the following procedures in this order:
Create the Data Connector that gets the list of countries for one Select List control: Create the Data Connector that gets a JSON array containing a JSON object for each country. One Select List control in this example uses this Data Connector's API response to get the list of countries as its options. This Data Connector accesses a public API that has been made available for demonstration purposes, so it does not require host authentication. As part of the Data Connector's JSON array response, it includes the two-letter International Organization for Standardization (ISO) country code in each JSON object, which is required for the second Data Connector as described below. See Create the Data Connector That Gets a JSON Array of Countries in its Response.
Create the Data Connector that gets the list of states and/or provinces for the dependent Select List control based on the first Select List control's option selection: After selecting a country as an option from the first Select List control, create another Data Connector that gets the region for the selected country based on its two-letter ISO country code.
This Data Connector accesses an API host under Creative Commons license that requires signing up for authentication. To demonstrate how to add request headers to a Data Connector's Resource, the authentication information for this API host is configured in a Resource's request headers instead of the Authentication tab of the Data Connector. Before creating this Data Connector, read about the API host, and then sign up to access the API. This example uses this API host for demonstration purposes since it returns only the first five JSON objects in its JSON array response for the United States that has the two-letter ISO country code of US
. Note that third-party APIs change their terms of use, so ensure that you are comfortable signing up to use this API host for this example. See Create the Data Connector That Gets a JSON Array of Regions in its Response Based on a Selected Country.
Configure the Select List control to select a country: From the Screen to use for this example, add and configure the first Select List control from which to select a country. When a country is selected, that country's ISO code is stored in a Request variable called country
for the Watcher that monitors when a country has been selected. The Watcher, in turn, sends that country's ISO code to the second Data Connector to get that country's regions as described below. See Configure the Select List Control's Data Source That Gets the List of Countries.
Configure the Watcher that monitors for a country selection: Configure the Watcher that monitors when a country is selected from the first Select List control, and then sends that country's ISO Code to the second Data Connector to get the regions for that country. The second Select List control contains no options until the Watcher sends the country's ISO code to the second Data Connector; this Data Connector's Resource URL requires that ISO code to successfully get the list of regions for that country. After the Data Connector gets the list of regions for the selected country as a JSON array, the Watcher stores that JSON array in that Request's data in a Request variable called Regions
, from which the second Select List control's regional options are available. See Configure the Watcher That Sends the Country Name to the Data Connector to Get That Country's Regions.
Configure the dependent Select List control to select a region based on the country selection: Below the first Select List control, add and configure the second Select List control from which to select a region. The regional options that display in this second Select List control depend on which country is selected from the first Select List control. The regional options for this Select List control are not available until the Watcher receives them from the second Data Connector, and then adds them to that Request's data as described below. See Configure the Select List Control's Data Source That Gets the List of Regions.
Preview the Screen: Preview the Screen to see how the second Select List control depends on the country selected from the first Select List control. Further, preview the JSON data model from the controls as you interact with them. See Preview the Screen.
Follow these steps to create the Data Connector that gets a JSON array containing the JSON objects of countries that the first Select List control uses to display a list of countries as its options as described in this example:
Log on to ProcessMaker Platform.
Click the Designer option from the top menu. The Processes page displays.
Verify the Data Connector Category exists in which to assign this Data Connector. If this Category does not exist, see Create a New Data Connector Category.
In the Name setting, enter the name of the Data Connector. This example uses the name Call Countries API
.
In the Description setting, enter a description of this Data Connector.
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.
Click Save. The Data Connector is created and the Resources tab displays.
Go to the Configuration tab to disable the Enable SSL certificate verification setting, which is enabled by default.
Click Save. The Data Connector is updated.
In the Name setting, optionally edit the purpose for this Resource. Therefore, provide a concise but relevant name for this Resource so other Process designers understand its function. This example uses the default list
for this setting.
In the Description setting, enter a description of this Resource. This example uses the following description: Gets a list of countries.
.
From the Category drop-down menu, select the Data Connector Category to assign this Resource.
From the Method drop-down menu, select the GET option. The GET method reads data from the API host.
In the URL setting, enter the following URL for this example: https://restcountries.eu/rest/v2/all
. This URL is provided by this host.
Notice which element in each JSON object within the resource response contains the name of the country. Look at the first JSON object. Notice the following key names in this JSON object:
name
: Notice that the name
key name in the JSON object contains the name of each country; the value of the name
key name displays as each option in the Select List control from which a country name is selected.
alpha2Code
: Notice the alpha2Code
key name contains the two-letter International Organization for Standardization (ISO) code for each country; this Select List control stores the value of the alpha2Code
key name element. In this example, a Watcher uses the ISO country code to determine which regions to display in the dependent Select List control.
Make note of the relevant key name(s) that contains relevant data, as the ProcessMaker Platform asset requires this key name when configuring which data that asset requires from the Data Connector's response. In this example, the Screen containing the Select List control is the ProcessMaker Platform asset. See Example JSON Object from the Endpoint Response for the List of Countries.
Click Save to save the Resource. The Data Connector is configured for this example.
Before creating this Data Connector, read about the API host, and then sign up to access the API. Note that third-party APIs change their terms of use, so ensure that you are comfortable signing up to use this API host for this example.
Follow these steps to create the Data Connector that gets a JSON array containing the JSON objects of regions for the selected country from the first Select List control as described in this example:
Log on to ProcessMaker Platform.
Click the Designer option from the top menu. The Processes page displays.
Verify the Data Connector Category exists in which to assign this Data Connector. If this Category does not exist, see Create a New Data Connector Category.
In the Name setting, enter the name of the Data Connector. This example uses the name Get Regions
.
In the Description setting, enter a description of this Data Connector. This example uses the description:
Gets the region(s), state(s), department(s), and/or province(s) for the country selected from the first Select List control after the Watcher gets that country selection.
From the Authentication Type drop-down menu, select the No Auth option. To demonstrate how to add request headers to a Data Connector's Resource, the authentication information for this API host is configured in a Resource's request headers instead of the Authentication tab of the Data Connector.
Click Save. The Data Connector is created and the Resources tab displays.
Go to the Configuration tab to disable the Enable SSL certificate verification setting, which is enabled by default.
Click Save. The Data Connector is updated.
In the Name setting, optionally edit the purpose for this Resource. Therefore, provide a concise but relevant purpose for this Resource so other Process designers understand its function. This example uses the default list
for this setting.
In the Description setting, enter a description of this Resource. This example uses the following description: Gets a list of regions from the selected country.
From the Category drop-down menu, select the Data Connector Category to assign this Resource.
From the Method drop-down menu, select the GET option. The GET method reads data.
In the URL setting, enter the following URL for this example: https://wft-geo-db.p.rapidapi.com/v1/geo/countries/{{country}}/regions
Notice how this URL contains the API resource parameter {{country}}
within it. This URL uses mustache syntax to get the value from the Watcher; in this example, the Watcher monitors when the Select List control of which its Variable Name setting value is country
has a selected option, and then sends that country's ISO code to this Data Connector. By using mustache syntax in this Resource's URL, that country's ISO Code replaces {{country}}
as an API resource parameter when this Resource calls that endpoint. See Create the Select List Control to Select a Country and Configure the Watcher That Sends the Country Name to the Data Connector to Get That Country's Regions.
In the Key setting for the first request header, enter X-RapidAPI-Host
as specified by the API host for this request parameter.
In the Default setting for the first request header, enter wft-geo-db.p.rapidapi.com
as specified by the API host for this request parameter.
Click Required to mandatory use this header for the API authentication.
Click Save. The first request header displays in the Headers tab.
Click the +Header button to add the second request header. The Add screen displays.
In the Key setting for the second request header, enter X-RapidAPI-Key
as specified by the API host for this request parameter for authentication.
In the Default setting for the second request header, enter your unique application key for authentication.
Click Required to mandatory use this header for the API authentication.
Click Save to save the Resource with the two configured request headers.
Click Send. If configured correctly, the Response Body tab displays the Resource response. This example returns only the first five JSON objects in its JSON array response since this example uses this API host for demonstration purposes.
Notice the following:
data
: Notice that the JSON array containing the response is called data
. The name of this JSON array is relevant when configuring the Select List control from which to select the country's region.
name
: Notice which key in each JSON object within the Resource response contains the name of the region: in this test, the states and provinces within the United States. Look at the first JSON object. Notice that the JSON key called name
contains the name of the state; the value of the JSON keyname
displays as each option in the Select List control from which a region is selected.
Click Response Mapping to map data from the API response to a ProcessMaker Platform asset; which is the Screen containing the Select List controls in this example.
In the first Source setting, select from where you want to map the data. For this example, select BODY.
In the Process Variable, enter the Request variable in which to save the list of regions to display in the Select List control. This example uses Regions
.
In the second Source setting, enter the key name from the API response containing the names of the regions as describe in step 34 above. This example uses name
.
Click Save to save the Resource with the response mapping.
Follow these steps to configure the Select List control's data source to get the list of countries as described in this example:
Log on to ProcessMaker Platform.
Create the Screen for the example to contain the two Select List controls and the Watcher.
Add the Select List control from which to select a country from the list of countries.
Click the Data Source panel.
From the Value setting, enter alpha2Code
to get the value of the alpha2Code
JSON object key name's value. When testing the first Data Connector that gets the list of countries,
Follow these steps to configure the Watcher as described in this example:
Log on to ProcessMaker Platform.
Open the Screen for this example. Ensure that this Screen contains the first Select List control configured for this example.
In the Watcher Name setting, enter the name of the Watcher. This example uses the name Get Region
.
From the Variable to Watch drop-down menu, select country. country
is the Variable Name setting value for the Select List control from which a country is selected. This Watcher monitors for when a value is selected from this control: in this example, a country name. After the monitored control has a value, then the Watcher triggers.
Select the Run Synchronously toggle key to run the Watcher while still interacting with the Screen.
From the Source drop-down menu, select Get Regions. Get Regions
is the name of the Data Connector that gets the list of regions from the selected country.
From the Resource drop-down menu, select list. list
is the name of the Data Connector's Resource that gets the list of regions from the selected country.
In the Outbound Configuration section, add the parameters that the Watcher passes to the Data Connector Get Regions
. This Data Connector requires the selected country's ISO code as a parameter to get a list of regions in that country. The Select List control that displays a list of countries also saves the selected country's ISO code in the Request variable {{country}}
. When the Screen previews or displays during a Request, the selected country name in that Select List control replaces {{country}}
.
In the Output panel, specify how to map data returned by the Watcher or the Watcher's output to a Request variable. In this example, the Watcher's output is saved in the JSON object called data
; use this in the Source setting. The Request variable receiving the Watcher's output is Regions
; use this in the Form Variable setting.
Close the Watchers screen, and then continue to add and configure the Select List control's data source that gets the list of regions.
Follow these steps to configure the Select List control's data source to get the list of regions as described in this example:
Log on to ProcessMaker Platform.
Open the Screen for this example. Ensure that this Screen contains the first Select List control configured for this example.
Add the Select List control below the first Select List control from which to select a region from the selected country.
In the Variable Name setting, enter regionName
.
Click the Data Source panel.
The Watcher outputs data it receives from the Data Connector to the Request variable called Regions
.
The Data Connector receives its response from the API endpoint in a JSON object element called response
by default.
The JSON array nested in theresponse
JSON object is called data
as shown when testing the Data Connector's Resource to get a list of regions.
Save your Screen. The Screen is now ready to preview how this Select List control depends on the country selected from the first Select List control.
Follow these steps to preview the Screen as described in this example:
Log on to ProcessMaker Platform.
Open the Screen for this example.
Click the Preview button. The Screen is in Preview mode.
Click the Region Select List control. The first five alphabetical states in the United States are options. There are only five options since this example uses the API host that returns only five JSON objects in the JSON array response for demonstration purposes.
Expand the Data Preview panel. Notice the JSON data model generated by the ProcessMaker Platform assets used in this example:
country
: The JSON data object with the key name country
represents the Select List control from which the country was selected. This JSON data object contains the two-letter International Organization for Standardization (ISO) code for the United States ("US"
).
regions
: The JSON array called regions
contains the JSON objects for the first five alphabetical states in the United States.
This example is complete.
Below is one JSON object from the Resource response that gets the list of countries. The key names relevant in this JSON object for this example are Call Countries API
and alpha2Code
.
Follow an example that uses Screen Builder's built-in functionality to disable a form-submission button until a toggle key is selected (acknowledge the form). This example does not use custom scripts.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Screen design; Check Box control; Rich Text control; Visibility Rules; HTML
When designing a Screen, it is possible to customize functionality by using custom scripts. However, such customization makes the Screen prone to errors and difficult to support or debug later. Most design needs can be met without custom scripts by simply using the functionality available in the Screen Builder.
Consider a Screen design that uses the following controls with their respective default display states:
For example, the Save Form button in the following screen appears disabled until the user agrees to the terms of the form.
After the terms are agreed to, the Save Form button enables.
From the Variable panel, enter in the Variable Name setting i_agree
.
From the Configuration panel, enter the following HTML in the Content setting:
Click the Preview icon to test the Screen.
Follow an example how to use a Signal Start Event element in the Process Modeler using a Signal with a webhook.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Signal Manager; Process Modeler, Signal Start Event; Screen design
Follow these steps to use a Webhook Signal in a Process:
In the Accepted Form Fields without fields.
In the Accepted Method, the POST option selected.
In the Authentication, the None option selected.
In the Restrict Access From, without URLs.
In the Webhook URL, click Copy to Clipboard to copy the URL to use it in the external third-party app.
Click Save to save the signal webhook configuration.
In the Name setting, enter the webhook name.
In the Payload format setting, select the JSON format.
In the Target URL setting, copy the ProcessMaker Platform's Webhook URL .
In the Name setting, enter the Signal Start Event name, which is Webhook sent from DocParser.
In the Signal setting, select the signal created in step 1.
In the Request Variable setting, enter the variable name that store the payload data. For this example, it is payload.
Configure your Process elements and Screens as necessary.
Label: Enter Countries
in the Label property.
Value: From the Value drop-down menu, select the option Countries
.
Label: Enter Countries
in the Label property.
PMQL: Enter data.Countries = "{{Countries}}"
in the PMQL property.
Click the Data Connectors iconfrom the left sidebar. The Data Connectors tab displays all Data Connectors in the Data Connectors page.
Click the +Data Connector button. The Create Data Connector screen displays.
From the Category drop-down menu, select the Data Connector Category to assign this Data Connector. This example uses the following settings.
Go back to the Resources tab and click the +Resource button. The Create Resource screen displays.
Click Add. The new Resource displays in the Configuration tab.
Click the Send button. If configured correctly, the Response Body tab displays the Resource response.
Click the Data Connectors iconfrom the left sidebar. The Data Connectors tab displays all Data Connectors in the Data Connectors page.
Click the +Data Connector button. The Create Data Connector screen displays.
From the Category drop-down menu, select the Data Connector Category to assign this Data Connector. This example uses the following settings.
Go back to the Resources tab and click the +Resource button. The Create Resource screen displays.
Click Add. The new Resource displays in the Configuration tab.
Click the Headers tab to add request headers that contain the authentication information to access the host's API. This example requires two request headers that provide valid authentication to access this API's endpoint.
These request headers are required header parameters for the Country Regions endpoint using the GET method: X-RapidAPI-Host
and X-RapidAPI-Key
. Note that the X-RapidAPI-Key
header parameter value is unique for each person using this API for authentication. To obtain this information, see GeoDB Cities API Documentation and then copy the following information:
Click the +Header button to add the first request header. The Add screen displays.
Click Save. The second request header displays in the Headers tab.
To test if the Resource and its authentication application key function as intended, click the Params tab to add a value for the country
parameter in this Resource to a real two-letter ISO country code. This example uses the ISO country code US
.
Click +Mapping. The Add screen displays.
Click Save. The response mapping is listed.
In the Variable Name setting, entercountry
since both the Watcher and the Data Connector that gets the regions for the selected country from this Select List control expect this Variable Name setting value.
From the Data Source drop-down menu, select Data Connector.
From the Options Variable setting, do not change the default response value.
From the Show Control As drop-down menu, select whether to show this Select List control's options as a drop-down menu or as a group of checkboxes. This example uses the Dropdown/Multiselect option.
Do not select the Allow Multiple Selections option. In this example, only one country must be selected for this example to function because the Watcher that monitors when a selection is made may only send one country name to the Data Connector that gets the regions in that country.
From the Type of Value Returned setting, do not change the default Single Value option since this example requires only one value from the selected JSON object and not the entire JSON object itself.
alpha2Code
is the JSON object key name that contains the two-letter ISO country code the second Data Connector uses to get that country's regions.
From the Content setting, enter name. When testing the first Data Connector that gets the list of countries, name
JSON object key contains the country name as its value within each JSON object of the JSON array response.
From the Data Connector drop-down menu, select Call Countries API, which is the name of the Data Connector that gets the list of countries.
From the End Point drop-down menu, select list, which is the name of the Resource in the Call Countries API that gets the list of countries from the API's resource.
Click the Watchers button. The Watchers screen displays all Watchers configured for this Screen.
Click the +Watcher button. The Watchers screen displays with the Configuration panel expanded.
Check and confirm the settings in the Configuration panel.
Select the Source panel.
Confirm the settings in the Source panel.
Click the Output panel.
Confirm the settings in the Output panel.
Click Save. The Watcher displays in the Watchers screen.
From the Data Source drop-down menu, select Request Data.
In the Options Variable setting, enter the Request variable Regions
that saves JSON data configured in the Watcher:
In the Option Label Shown setting, entername
. When testing the Data Connector that gets the list of a country's regions, the key name called name
contains the region in each JSON object of the JSON array the Data Connector returns to the Watcher. The Watcher then outputs this JSON array to the Request variable Regions
from which this Select List control's options derive.
From the Show Control As drop-down menu, select whether to show this Select List control's options as a drop-down menu or as a group of checkboxes. This example uses the Dropdown/Multiselect option.
Select the Allow Multiple Selections option if you would like the Request participant to select more than one country region. This example does not use this setting.
From the Type of Value Returned setting, do not change the default Single Value option since this example requires only one value from the selected JSON object and not the entire JSON object itself.
From the Variable Data Property setting, enter name
to store the selected country region in a JSON object key name called name
.
From the Country Select List control, select United States of America. After making a selection, a screen displays while the Watcher sends the selected country's ISO code to the Data Connector that gets that country's regions, returns that JSON array of objects to the Watcher, and then the Watcher stores that response to the Regions
Request variable in the preview.
Select one of the five states.
control: A Check Box control displays by default with the toggle key to acknowledge the terms of the form.
control: A Rich Text control displays HTML containing the image of a disabled button until all required information in the form has been entered. The Rich Text control displays by default to appear as a disabled button.
control: A Submit Button control remains hidden until the state of the Check Box control is True
. Since the the Check Box control is FALSE
by default, the Submit Button control is hidden by default.
Follow these guidelines to design a Screen with a disabled button until a toggle key is selected. This example does not use a custom script as described in this :
. The new Screen opens in Design mode.
and configure the following settings:
Enter in the Label setting I agree to the terms of this form
.
From the Design panel, select the Toggle Style setting.
and configure the following settings:
<span class="btn btn-primary disabled">Save Form</span>
. This HTML uses the btn
(button) class to display a disabled button using the same text SAVE FORM
as the Submit Button control displays its Label setting value (described below).
From the Advanced panel, enter in the Visibility Rule setting i_agree == false
. This means that the Rich Text control remains hidden while the Check Box control's state remains FALSE
(not selected).
Insert a control and configure the following settings:
From the Variable panel, enter in the Label setting Save Form
.
From the Advanced panel, enter in the Visibility Rule setting i_agree == true
. This visibility rule means that the Rich Text control hides while the Check Box control's state becomes TRUE
(selected). The Submit Button control displays.
The Screen is now complete. .
The following example demonstrates signals: how a Process uses a Signal Start Event with a Webhook Signal collection. This example demonstrates that external thirdparties are available to configure in a Webhook Signal. For this example, the external thirdparty to use is . Docparser send the signal and the payload request.
.
for the created signal with the default values:
Configure the Docparser account to use the webhook URL. This configuration depends on the third-party app and its version. For Docparser, it is configured in the Integrations section as follows:
In the Include Fields setting, select the fields that Docparser is going to send to ProcessMaker Platform.
and model the process including a . In this example the Signal Start Event is Webhook sent from DocParser:
Configure the Signal Start Event to broadcast the external Docparser signal as follows:
Use the JSON data from the payload request variable in your Screens as follows: The Variable Name setting of a control setting calls the Signal payload by calling the JSON object as payload.bol. In this example, bol is the object called.
Follow an example that uses Loop and File Upload controls to limit how many files may be upload to a Screen.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Loop control; File Upload control; Screen design
Use the Loop and File Upload controls to limit how many files may be uploaded to a Screen. Though the File Upload control allows multiple files to be uploaded, any number of files can be uploaded if this feature is enabled. Therefore, this example provides a way to limit the number of files that may be uploaded to a Screen.
Download an example of this Screen at the end these instructions, and then import it.
Follow these steps to design a Screen that limits how many files may be uploaded:
Add the Loop control to the Screen page from which users may upload multiple files.
Do not enter a visibility rule in the Visibility Rule setting so that the Loop control always remains visible.
Specify other settings in the Loop control as necessary. These settings do not affect how this example functions.
Add a File Upload control to the Loop control by dragging it into the Loop control.
Configure the File Upload control as necessary. These settings do not affect how this example functions.
Add a Submit Button control to this Screen. Ensure not to add the Submit Button control inside the Loop control.
Save your Screen.
Reference this Screen from a Process model or as an editable Screen in a Collection.
From the Data Source setting, select the New Array of Objects option.
In the Default Loop Count setting, enter how many files by default that may be uploaded to this Screen. 3 is the default setting.
Select the Allow additional loops option to allow additional files be uploaded to this Screen. By default this setting is not selected, which would prevent additional files be uploaded.
Follow examples that use Screen Builder to guide and inspire your own ProcessMaker implementations.
Follow an example to either preview or download multiple files in a Screen that have been uploaded from a previous Task in that Request.
Intended audience: Process designers, Web designers, graphic designers, software developers, coding engineers
Tags: Loop control; File Upload control; File Preview control; File Download control; Screen design
If multiple files have been uploaded to a Task within a Request, those files can be previewed and then downloaded from the current Task in that Request.
In the Screen of the Task from which to preview or download those multiple files, use a File Preview control or File Download control, respectively, with a Loop control.
See the following sections regarding how to view and/or configure each control used in this example:
Follow these steps to locate applicable setting information for the File Upload control in this example:
Locate the File Upload control from the Screen page designed to upload multiple files. This Screen is used in the previous Task of the Request that the Request participant uploads those files.
To preview multiple files for this example requires the following controls:
Follow these steps to configure the Loop control to preview multiple files as in this example:
Add the Loop control to the Screen page from which to preview multiple files.
In the Variable Name setting of the Loop control, enter the Variable Name setting value from the File Upload control. For this example, enter MultiFileUploadControl
.
Follow these steps to configure the File Preview control for this example:
Add the File Preview control to the Screen page from which to preview multiple files.
This value is required because the Request data stores each file in within a JSON array named from the File Upload control's Variable Name setting value; within this JSON array, each file uploaded to the File Upload control is stored in a JSON object with a unique file ID referenced by the key name file
. This value is not case sensitive.
To download multiple files for this example requires the following controls:
Follow these steps to configure the Loop control to preview multiple files as in this example:
Add the Loop control to the Screen page from which to download multiple files.
In the Variable Name setting of the Loop control, enter the Variable Name setting value from the File Upload control. For this example, enter MultiFileUploadControl
. These are the same settings as for the Loop control that contains the File Preview control.
Follow these steps to configure the File Download control for this example:
Add the File Download control to the Screen page from which to download multiple files.
This setting is configured for the same reason as that of the File Preview control in this example.
Note the Variable Name setting value for that File Upload control. This example uses the value MultiFileUploadControl
.
From the Data Source setting, select the Existing Array option.
From the File Name setting, enter file
.
From the Data Source setting, select the Existing Array option.
From the Name setting, enter file
.