Learn how to design and manage Screens that you can re-use throughout all your Processes.
Loading...
Loading...
Loading...
Loading...
Manage your Screens.
Manage your Screen Categories.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Understand how to use controls to design your Screens.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Manage Calculated Properties that perform calculations in your Screens.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Manage Watchers that monitor for Variable Value setting changes in your Screens.
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Design rule-based modern chat-style Screens, and then deploy them into third-party sites to provide chat-style automated interactions with site visitors.
Loading...
Loading...
Follow best practices, and avoid worst practices, when designing Screens.
The Advanced Screens package deprecated in March 2021.
See ProcessMaker University training to learn how to design Screens.
If you use the Advanced Screens package, please contact your Customer Success Manager.
Follow these best practices when designing Screens in Screen Builder.
Controls that have the Variable Name setting use this value as a variable name in the Screen in which that control is used. Use unique Variable Name settings from any other control of the same type in all Screens in your organization. Why? If a Process uses two different Screens in which two controls of the same type have the same Variable Name setting, the value of the first Screen's control overwrites the value of the second during Requests.
For example, suppose you have a Process that uses two different Screens that have a Line Input control with the setting FirstName
. During a Request, the first Line Input control receives a value. As the Request continues, that Line Input control's value automatically overwrites any value in the second Screen's Line Input control because they have the same Variable Name setting. This may be unintended. This is why it is helpful to experiment with JSON data models in Preview mode.
To avoid this issue, establish a naming convention with all Process Owners in your organization for Variable Name settings. For example, use a naming convention such as <ScreenName>_<FieldName>
. This naming convention minimizes two controls of the same type in different Screens to have identical names.
Use Variable Name setting values that provide context to that control's use so that when viewing the JSON data outside the context of that Screen, you and other designers understand information that control contains in the Request.
Use the Tab Order setting for applicable controls to coordinate the keyboard navigation order that a control takes focus amongst the structure of other controls in a Screen. Assistive technology users often use a keyboard for navigation. When the tab order for a Screen's controls is designed well, that Screen navigates via keyboard in the logical and intuitive structure of that Screen's content.
Follow these best practices to set the tab order for a Screen's keyboard navigation:
The tab order should follow the visual flow of the page: left to right (for Western readers), top to bottom.
Set the first control's tab order to 1
.
Set the number for each subsequent control the sequential order that each control takes focus in the keyboard navigation order. Consider the following example.
Set the tab order for these controls as displayed from top to bottom as follows:
Set the tab order for all applicable controls for the best Screen usability experience and to avoid unexpected usability.
Use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
If a Screen control affected by a visibility rule is hidden by default from custom CSS, the visibility rule overrides the custom CSS design. For example, if custom CSS is designed to hide a Screen control by default when that control's visibility rule dictates that it be visible, the visibility rule overrides the custom CSS to display that control. As a best practice, use visibility rules instead of custom CSS to hide a control by default.
When using a Select List control that gets its options as a JSON array from a data source, and that Select List control is used in a Loop control, follow this best practice:
Configure the Select List control to get the JSON object of the array, not only values.
Within the Loop control, duplicate the JSON object so that JSON object elements match those of the Select List control's.
Consider this example. The following is a JSON object that contains the JSON array from which a Select List control could use as its options when configured to reference the JSON object.
Download and then import the following Screen into Screen Builder. Preview the Screen to observe how the Select List control functions within the Loop control: select an option, and then enter values. Observe the JSON array that displays in the Preview panel.
For optimal Screen performance, as a best practice use fewer than 25 controls in one Screen. When adding more than this number, a warning displays.
Use Nested Screens or divide your Task into multiple steps to avoid creating large Screens that adversely affect performance. Alternatively, use the Page Navigation control to create a multi-page Screen. See an example of using the Page Navigation Control to Design a Multi-Page Screen.
As a best practice when a Vocabulary validates the JSON in a Screen for a datetime value, use a Date Picker control instead of a Line Input control.
As a best practice when using HTML escaped characters like &
, <
, >
, /
, “
, '
, `
, or =
, use triple mustache brackets to avoid displaying incorrect values in Screen controls. Example: {{{name_with_character}}}
For more about mustache syntax, see mustache documentation.
Follow these best practice guidelines regarding the use of single-value JSON objects versus JSON arrays to reference Select List control options from Request data:
As a best and general practice, use single-value JSON objects from which to reference Select List control options instead of a JSON array that contains all options within an array of objects.
If any value within the JSON object that contains all Select List control options change, such as via Request data, then none of the Select List control options display when a user clicks that Select List control.
Therefore, to use a JSON object that contains all Select List control options, ensure that none of the following would occur to the Request data from which the Select List control references its options:
Ensure that none of the values in any of the individual JSON objects would modify in any way.
Ensure that empty values are transformed to null
. ProcessMaker Platform cannot accept empty values as options in Select List controls or Collection records.
As a best practice, when editing a Collection record using a Select List control in a Loop control, configure the Select List control's Type of Value Returned setting with the Single Value option. This best practice applies only to this use case.
If you select the Object option, which reads the entirety of a JSON array or object instead of one value, ProcessMaker Platform expects the selected Select List control option to match that of the Collection record. However, when the Select List control is first selected by the user to view its options, the Select List control contains a different value, thereby causing an error.
When using a single value from which to select a Collection record, ProcessMaker Platform does not have this expectation. See Reference Request Data section in Select List control settings where this setting applies to this use case.
Avoid these worst practices when designing Screens in Screen Builder.
Avoid adding custom JavaScript when designing Screens for the following reasons:
Custom JavaScript implementations are not under the ProcessMaker Platform Support scope: Because custom JavaScript implementations are not under the ProcessMaker Platform Support Scope, Support agents will not support custom JavaScript implementations.
Custom JavaScript implementations creates an unmaintainable business solution: By introducing custom JavaScript into Screen design that may affect workflow routing behavior outside of that Screen, you make that business solution much more difficult to maintain.
Watchers that use Scripts as their Source can adversely affect your Screen's performance. Therefore, when defining such Watchers, a warning message displays.
Use Scripts sparingly with your Watchers and consider other alternatives when possible. For example, instead of using a Script to call an API, use a Data Connector to connect to the API. Afterwards, use this Data Connector in your Watcher. See an example where a Data Connector is used in a Watcher to display Countries and Regions in Select List controls.
When configuring Select List controls to reference Request data for their options, avoid using JSON data in which a JSON object contains its own JSON objects that may change dynamically. The value of any JSON object may be changed dynamically in the following ways:
During a Request, a JSON object's value changes while routing.
The Request may reference Collection data that has changed since the Request started.
It is not good practice to store all data in one variable of type object
because any of the attributes can be modified at any time.
Instead, reference Request data that in which all JSON objects are peers of one another.
Note that this practice to avoid does not affect when you are providing your own Select List control options or using a Data Connector to get options.
Consider the following JSON array in a control called Composers
that contains two JSON objects. The Request data at this moment in the Request is the content of that Record List control as a JSON object.
A Screen contains a Select List control with a Variable Name setting value of SelectedComposer
. This Select List control follows the bad practice to avoid described above by referencing the Composers
JSON array to return type Object.
See these sections in Select List control settings that document the settings described above:
Variable Name setting of SelectedComposer
Options Variable setting of Composers
During a Request, if the second option in the Select List control is selected, Dmitri Shostakovich, then the current Request data is as follows:
If a Task modifies the Record List values, the JSON objects in the JSON array have changed from the original values that Select List recognizes. For example, suppose the address in the second JSON object changes in the Record List control: Moscow
has been changed to Petersburg
.
When the Screen containing the Select List control accesses the Request data to get its values from the Composers
JSON array, the second JSON object is different. Therefore, the Select List control contains no options because the Composers JSON array is not identical to the object stored in the ComposerSelected
JSON object: ComposerSelected
contains the address with Moscow
, while the Composers
JSON array contains Petersburg
.
This example demonstrates why it is a bad practice to store JSON objects in which their values may change dynamically within other JSON objects.
Instead of following the example of the bad practice to avoid described above, configure the Select List control to store a single value for the type of value returned and reference the id
JSON key name in the Variable Name Property setting because its value is not likely to change.
Following this configuration, when the Select List control references the id
JSON key name, then the current Request data is as follows:
If any of the JSON objects in the Composers
JSON array change, the Select List control references a key name in the JSON object does not change. Therefore, the Select List control displays options derived from the Request data.
Follow best practices, and avoid worst practices, when designing Form-type Screens.
For each example, the Bad Practice tab displays by default. Click the adjacent Good Practice tab to view the best practice to follow. Design practices that are similar are grouped into the following sections:
Use labels in controls to indicate their purpose, since they are always visible for users to see.
When a user navigates through a multi-column Screen, making the user follow a Z-pattern is more difficult for the user's eyes. Users might not even know where to start.
Avoid text redundancy as shown in the example below.
Be as concise as possible in control labels.
By providing no user guidance for information to enter into the form, users become confused.
Use helper text to provide context how to interact with each control.
Unmasked Line Input controls allow users to introduce errors when entering commonly-used information.
Understand how to use Screens in ProcessMaker Platform.
In ProcessMaker Platform, a Screen presents information for a person to interact with or view. An interactive form is an example of a Screen. Any Screen can be re-used in any Process. Many Processes require the same type of information be gathered, such as a person's name, email address, and other business information. In other words, "design once, use anywhere."
Enter information into a Request.
Review information and then approve or reject a Request.
Designers can design Screens that only display information in useful ways:
There are many ways to design Screens to digitize your business needs across your business solutions in savvy ways to reuse them across multiple Processes.
Control Label | Tab Order Number |
---|---|
Follow basic form design best practices so your -type are easy to navigate and read. Many of these best practices may apply to -type Screens.
Use controls to organize the layout and width of other controls.
Avoid using for controls. When users start typing in the controls, the placeholders disappear.
See the setting for the control for more information.
If the controls associate with one another, place them in one horizontal line.
If your form is large, do not use all controls in one section.
Use the control to add headings that break the form into logically-related groups.
If there are fewer than four options, as a general guideline do not put them in a control as drop-down options. This design requires the user to click twice to commit an action: once to display the Select List control options, another select an option.
If there are fewer than four options, show the options immediately using controls. This design requires one click to commit an action.
Use masking patterns to pre-format commonly used information, thereby allowing users to enter information accurately. See the setting for the control for more information. Click the image below to enlarge.
Screens also allow people to interact with information. Below are a few ways Request participants can interact with Screens:
or documents as attachments to a Request.
Display information from output.
Acquire a , and then display that digital signature in another Screen.
Insert to display key performance indicators (KPIs) to monitor your business goals.
Insert commonly used information and downloadable files for your employees or a subset of your employees, and then place them into a for these employees to access. For example, create a dashboard that serves as a portal for all your employees to read special announcements, download the employee handbook, and display relevant record information.
.
First Name
Middle Name
Last Name
Submit Your Name
Improve your Screen organization by creating Categories to which to assign them.
Your user account or group membership must have the following permissions to create a new Screen Category unless your user account has the Make this user a Super Admin setting selected:
Screens: Create Screen Categories
Screens: View Screen Categories
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to create a new Screen Category:
Click the +Category button. The Create Screen Category screen displays.
In the Category Name setting, enter the name of the new Screen Category. The Screen Category name must be unique from all other Screen Category names in your organization and can only use apostrophe characters ('
) and spaces. This is a required setting.
From the Status drop-down menu, select one of the following options for the Screen Category's status:
Active: Active Screen Categories can have Screens assigned to them.
Inactive: Inactive Screen Categories cannot have Screens assigned to them.
The Active option is selected by default. This is a required setting.
Click Save.
View the Screen Categories in your organization.
Your user account or group membership must have the following permissions to view Screen Categories unless your user account has the Make this user a Super Admin setting selected:
Screens: View Screen Categories
Screens: View Screens
Click the Designer option from the top menu. The Processes page displays.
Click the Categories tab. The Screen Categories display.
The Categories tab displays the following information in tabular format about Screen Categories:
Name: The Name column displays the name of the Screen Category. The Screen Category named Uncategorized is the default Category.
Status: The Status column displays the status of the Screen Category. Below is a description of each status:
Active: Active Screen Categories can have Screens assigned to them. The Screen Category named Uncategorized is active by default.
Inactive: Inactive Screen Categories cannot have Screens assigned to them.
Screens: The # Screens column displays how many Screens in your organization have been assigned to that Screen Category.
Understand what Screen Categories are and how they can help organize your Screens.
Use Screen Categories to organize your Screens. Organizing your Screens into Categories makes it easier to search for a Screen based on its assigned Category. Assign multiple Screen Categories to a Screen if necessary. For example, assign a Screen named "Personal Information Form" to the "Banking Forms" and "Human Resources Forms" Screen Categories.
Screen Categories can be in active or inactive status. Following is a description of each status:
Active: Active Screen Categories can have Screens assigned to them.
Inactive: Inactive Screen Categories cannot have Screens assigned to them.
See the permissions or ask your Administrator for assistance.
Follow these steps to view :
to ProcessMaker Platform.
Click the Screens icon from the left sidebar. The Screens tab displays all Screens in the Screens page.
Modified: The Modified column displays the date and time the Screen Category was last modified. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your Time zone setting is specified.
Created: The Created column displays the date and time the Screen Category was created. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your Time zone setting is specified.
, including how to sort columns or how many items display per page.
: Organize your .
: Organize your .
Screen Categories: Organize your .
: Organize your (if the is installed).
: Organize your (if the is installed).
Search for a Screen Category.
Your user account or group membership must have the following permissions to search Screen Categories unless your user account has the Make this user a Super Admin setting selected:
Screens: View Screen Categories
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance
Follow these steps to search for Screen Categories:
Enter in the Search setting the text to filter Screen Categories by name.
As you enter text into the Search setting, Screen Categories display that match your entered text.
If there are no search results, the following message displays: No Results.
Edit the name and/or status of a Screen Category.
Your user account or group membership must have the following permissions to edit a Screen Category unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screen Categories
Screens: View Screen Categories
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to edit a Screen Category:
Edit the following information about the Screen Category as necessary:
In the Category Name setting, edit the name of the Screen Category if necessary. The Screen Category name must be unique from all other Screen Category names in your organization. This is a required field.
From the Status drop-down menu, change the status of the Screen Category, if necessary, from the following options:
Active: Active Screen Categories can have Screens assigned to them.
Inactive: Inactive Screen Categories cannot have Screens assigned to them.
This is a required setting.
Click Save.
Delete a Screen Category when it is no longer needed.
Your user account or group membership must have the following permissions to delete a Screen Category unless your user account has the Make this user a Super Admin setting selected:
Screens: Delete Screen Categories
Screens: View Screen Categories
Screens: View Screens
Deleting a Screen Category cannot be undone.
Click Confirm. The following message displays: The category was deleted.
Click the ellipses icon, and then select the Edit Category option for the Screen Category to edit. The Edit Screen Category page displays.
See the permissions or ask your Administrator for assistance.
To delete a Screen Category, no Screens can be assigned to it. If any Screens are assigned to the Screen Category, its Delete icondoes not display. .
Follow these steps to delete a :
.
Click the ellipses icon, and then select the Edit Category option for the Screen Category to delete. A message displays to confirm deletion of the Screen Category.
Design your Screen for Request participants to interact with Request data.
Delete a Screen from being used in any Process.
Your user account or group membership must have the following permissions to delete a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Delete Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
When a Screen is deleted, Process models that use that Screen in Task elements are not affected. However, that Screen can no longer be referenced from other Process models thereafter.
Deleting a Screen from the Screens page cannot be undone.
Follow these steps to delete a Screen:
View your Screens. The Screens page displays.
Click Confirm. The following message displays: The screen was deleted.
Click the ellipses icon, and then select the Delete option for the Screen to delete. The Caution screen displays to confirm the deletion of the Screen.
Understand what Screen Builder is in ProcessMaker Platform.
Your user account or group membership must have the following permissions to create or edit a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Create Screens
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Use Screen Builder to design Screens for your Processes. Screens are independent of Processes: any Screen can be used in any Process, even those that you did not design. Screens can be exported and then shared with other Process designers so they may import them for their Processes.
While Screen Builder has an easy-to-use drag-and-place design interface to edit and preview Screens, ProcessMaker Platform represents them as JSON data models. You can view the JSON data model while in Preview mode.
You can use different types of Screens. See Screen Types.
Screens are composed of controls. Use controls to provide your Screen with specific functionality. See Control Descriptions and Inspector Settings.
Below are a few examples of these controls:
Display text.
Provide a group of radio buttons to allow the Request participant to select an option.
Provide a drop-down menu to allow the Request participant to approve or reject a Request.
Provide a text area where the Request participant can enter text.
Provide a date control where the Request participant can select a date.
Add a Date Picker control that allows the Request participant to select dates from a Screen through an interactive calendar.
Configure the Date Picker control to accept one of the following data types:
Datetime: The control accepts a datetime, which includes both date and time components: YYYY-MM-DD HH:MM:SS
. Example: "2020-07-01 14:25:15"
Date: The control accepts a date: YYYY-MM-DD
. Example: "2020-07-01"
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
View the Screen page to which to add the control.
Drag the Date Picker icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The Date Picker control has the following panels that contain settings:
Below are settings for the Date Picker control in the Variable panel:
Use the Variable Name setting value in the following ways:
Select one of the following data type options this control accepts when the Request participant enters content into this control:
Datetime: This control accepts a datetime, which is includes both date and time components.
Date: The control accepts a date.
Follow these steps to add a validation rule to this control:
Select the rule that this control validates against.
Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.
Follow these steps to edit a validation rule for this control:
Follow these steps to delete a validation rule for this control:
Click Delete.
Below are settings for the Date Picker control in the Configuration panel:
Below are settings for the Date Picker control in the Design panel:
Below are settings for the Date Picker control in the Advanced panel:
If the Request variable is empty, the control does not display any value by default.
When the Request variable is assigned a value for the first time, this value becomes the permanent default value of the control.
Any further changes to the Request variable do not affect the default value of the control.
There are two ways to enter the default value this control displays.
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Use Design mode to design your Screen. Design mode is the default mode when a Screen is created or edited. While in Design mode, use the Design setting section to configure that you place into your Screen Builder canvas.
See .
See .
Use Preview mode to view and test your Screen. Test how your controls function as a form user would experience your Screen during a .
Furthermore, test how the Screen's controls you configured in Design mode interact with JSON data models. ProcessMaker Platform represents Screens as JSON data models. You can view any JSON data model in Preview mode to test how a JSON data model or another Screen's data model interacts with your Screen. Viewing the JSON data model can be helpful to see how values are entered into the Screen as well as to use that JSON data model in your .
See .
Use Calculated Properties mode to add Calculated Properties to that Screen. A Calculated Property is any value, mathematical calculation, or formula. A Calculated Property's determines its value either through a mathematical formula or valid JavaScript, and may include values from values and during that . Likewise, a Calculated Property's value can display in a Screen control during that Request. Calculated Properties can only be used within and only affect the Screen to which the Calculated Property is defined.
See .
See .
Use Watchers mode to add Watchers to that Screen. During a or while the Screen, a Watcher monitors when the value of a control in that Screen changes or receives a value, acts upon a Data Connector or runs a using that control's value, and then outputs its result to another Screen control.
See .
The Date Picker control allows the participant to click the control and select a date from a calendar pop-up. After the user selects a date from the control, the calendar hides and the control shows the selected date.
Use the Date Picker control to validate datetime format such as for .
The display format of the Date Picker control is determined by the in a .
This control is only available for -type Screens. See .
Use the control for Request participants to select a date or datetime through a user interface.
See the permissions or ask your Administrator for assistance.
.
.
Follow these steps to add this control to the :
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the Date Picker iconin the panel to the left of the Screen Builder canvas.
Configure the Date Picker control. See .
Validate that the control is configured correctly. See .
Below is a Date Picker control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
As a best practice, after copying a control, change the value for the copied control to its own unique variable value. Otherwise, in-progress that use this Screen read from and send data to both controls.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during . Ensure that the Variable Name setting value is a unique name from other controls in this and contains at least one letter. This is a required setting.
Reference this control by its Variable Name setting's value. The Data Preview panel in corresponds with the Date Picker control's entered datetime with that Date Picker control's Variable Name value. In the example below, DatePickerControl
is the Variable Name setting's value.
Reference this control's value in a different Screen Builder control. To do so, use and reference this control's Variable Name value in the target control. Example: {{ DatePickerControl }}
.
Reference this value in .
See when editing a Request variable name.
Edit the default label that displays for this control if necessary. New Date Picker is the default value.
This is a required setting.
Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: No validation rule(s). See .
Access the while in mode, and then locate the Validation Rules setting.
Click the Add Rule button. The Select drop-down menu displays.
Enter the parameter settings that this control uses to validate against. See , and then locate the validation rule for its parameters.
Access the while in mode, and then locate the Validation Rules setting.
Click the Edit iconfor the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays.
Edit the parameter settings that this control uses to validate against. See , and then locate the validation rule for its parameters.
Access the while in mode, and then locate the Validation Rules setting.
Click the Delete iconfor the validation rule to delete. A message displays to confirm deletion of the validation rule.
Select to indicate that this control cannot be edited. This option is not selected by default.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Enter the placeholder text that displays in this control when no value has been provided. This setting has no default value.
Enter text that provides additional guidance on this control's use. This setting has no default value.
Click the control while in mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Enter the default value this control displays. The default value can be assigned as a Request variable, text or JavaScript. When the Screen submits, the Request uses this control's default value unless the Request participant changes it. When using a in the Default Value setting, consider the following:
The Default Value setting supports using Request variables in . For example, if the Default Value setting is {{ FirstName }} {{ LastName }}
from which a Request participant entered her first name and last name in separate controls (respectively) earlier in that Request, this control displays the contents of those controls by default during the Request.
Enter the default value as text or use a Request variable in mustache syntax.
Enter the default value as JavaScript, especially if a might change this default value setting. Ensure to use the preceding the Screen control reference. Example: this.FullName
when FullName
is the Variable Value setting value for the control to set its default value.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the value. For example, if a control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
Validate That Your Screen is Ready for Use in Processes.
Before you deploy your Screen to production, validate that it is ready for use in Processes for the following reasons:
Minimize problems when previewing your Screen.
ProcessMaker Platform represents Screens as JSON data models. You can view any JSON data model in Preview mode to test how a Process's JSON data model or another Screen's data model interacts with your Screen. When testing a JSON data model, the Screen Validation feature indicates when that data model is not valid.
Minimize problems when Process designers test your Screen in their Processes. Since your Screen may be used in multiple Processes in your organization, ensure that your Screen won't cause production problems later.
Your user account or group membership must have the following permissions to validate a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to validate a Screen:
Screen Validation is enabled by default. If the Screen Validation toggle key is disabled, enable the Screen Validation toggle key so that Screens Builder automatically validates your Screen as you work.
Work on your Screen. Screens Builder indicates any validation issues as you work. The following indicators may occur:
No errors found: If no errors are found, the following text displays to the right of the Open Console button: 0. The green check mark displays. Your Screen is valid.
Furthermore, controls that are associated with errors display a red-colored highlight.
If errors are found, click the Open Console button again to hide the error summary. Make changes to your Screen or JSON data model and then repeat steps 3 and 4 again until Screens Builder finds no validation errors.
Add a control from which the Request participant can download files to a local computer.
The File Download control adds an area in the Screen from which the Request participant can download a file to a local computer that was attached to the Request via a File Upload control in a different Screen in that Request.
This control is only available for the following Screen types:
See Screen Types.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Permissions are required to do this.
Avoid designing with more than 25 controls in one Screen.
See this example how to download multiple files that have been uploaded from a previous Task in that Request.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the File Download icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Configure the File Download control. See Settings.
Below is a File Download control in Preview mode. The File Download control displays No files available for download until this control references a downloadable file in the Process or during a Process's Request.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The File Download control has the following panels that contain settings:
Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Below are settings for the File Download control in the Variable panel:
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the File Download control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Add a control from which the Request participant can select or deselect an option. Multiple Checkbox controls can be grouped together.
The Checkbox control adds a checkbox from which the Request participant can select or deselect an option. Multiple Checkbox controls can be grouped together to function as one set of options whereby separate Checkbox controls with the same name maintain the same selected or deselected state. See a design example.
This control is only available for Form-type Screens. See Screen Types.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Checkbox icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Configure the Checkbox control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below are two Checkbox controls in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Checkbox control has the following panels that contain settings:
Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Checkbox control in the Variable panel:
Use the Variable Name setting value in the following ways:
Reference this control by its Variable Name setting's value. The Data Preview panel in Preview mode represents the state of the Checkbox control using its Variable Name value in the Request's JSON data model in the following ways:
The Checkbox control is selected: The key's value is true
(shown below).
Reference this control's value in a different Screen Builder control. To do so, use mustache syntax and reference this control's Variable Name value in the target control. Example: {{ CheckboxControl }}
.
Reference this value in Visibility Rule setting expressions.
See best practices when editing a Request variable name.
Follow these steps to add a validation rule to this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Select the rule that this control validates against.
Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.
Enter the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.
Follow these steps to edit a validation rule for this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Edit the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.
Follow these steps to delete a validation rule for this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Click Delete.
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below is the setting for the Checkbox control in the Configuration panel:
Click the control while in Design mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Checkbox control in the Design panel:
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Checkbox control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Preview a file that has been uploaded from a previous Task via a File Upload control in that Request.
This control is only available for the following Screen types:
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
View the Screen page to which to add the control.
Drag the File Preview icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The File Preview control has the following panels that contain settings:
Below is the setting for the File Preview control in the Variable panel:
Below is the setting for the File Preview control in the Configuration panel:
Below are settings for the Line Input control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Add a control to which the Request participant can upload a file from a local computer.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
View the Screen page to which to add the control.
Drag the File Upload icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The File Upload control has the following panels that contain settings:
Below are settings for the File Upload control in the Variable panel:
Select the Upload multiple files setting to allow the Screen user to upload multiple files at once using this File Upload control.
Below is the setting for the File Upload control in the Configuration panel:
Separate multiple file types with commas (,
). One space after each comma is acceptable. Example: application/msword, image/gif, image/jpeg, application/pdf, application/vnd.ms-powerpoint, application/vnd.ms-excel, text/plain
Below are settings for the File Upload control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Add a control that displays an image.
The Image control has the following functionality:
The Image control displays a specified image that is GIF, JPG, or PNG file types.
This control is only available for the following Screen types:
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Image icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The Image control has the following panels that contain settings:
Below are settings for the Image control in the Configuration panel:
Click the Upload button to browse for the GIF, JPG, or PNG file type image to upload to the Image control.
Below are settings for the Image control in the Design panel:
Below are settings for the Image control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Add a control that displays a text field that allows the Request participant to enter plain text or a password.
Text: The control only accepts alphanumeric characters.
Integer: The control only accepts integers.
Currency: The control only accepts a currency value.
Percentage: The control only accepts a percentage value.
Decimal: The control only accepts any number, both positive and negative.
Datetime: The control only accepts a datetime, which is includes both date and time components.
Date: The control only accepts a date.
Password: The control accepts a password. Entered text is hidden.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
View the Screen page to which to add the control.
Drag the Line Input icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The Line Input control has the following panels that contain settings:
Below are settings for the Line Input control in the Variable panel:
Use the Variable Name setting value in the following ways:
Select one of the following data type options this control accepts when the Request participant enters content into this control:
Text: The control only accepts alphanumeric characters. Text is the default setting.
Integer: The control only accepts integers.
Currency: The control only accepts a currency value.
Percentage: The control only accepts a percentage value.
Decimal: The control only accepts any number, both positive and negative.
Datetime: The control only accepts a datetime, which is includes both date and time components.
Date: The control only accepts a date.
Password: The control accepts a password. Entered text is hidden.
For the Currency and the Percentage data types, data formatting is not saved in the Request variable linked to the Line Input control. As a result, the formatting is not available if the variable is used elsewhere in that Request. For example, instead of $50.00
, the Request variable only saves the value 50
.
The following message displays below the control if the Request participant enters content that does not comply with this control's data type: The format is invalid..
Follow these steps to add a validation rule to this control:
Select the rule that this control validates against.
Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.
Follow these steps to edit a validation rule for this control:
Follow these steps to delete a validation rule for this control:
Click Delete.
Below are settings for the Line Input control in the Configuration panel:
Below are settings for the Line Input control in the Design panel:
Below are settings for the Line Input control in the Advanced panel:
If the Request variable is empty, the control does not display any value by default.
When the Request variable is assigned a value for the first time, this value becomes the permanent default value of the control.
Any further changes to the Request variable do not affect the default value of the control.
There are two ways to enter the default value this control displays.
Numbers as a string are concatenated. To set the expected number result as the default value using JavaScript, enter return 0;
instead of 0
.
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
Date, SSN and Phone mask pattern display as examples.
Use the following mask components to compose your mask pattern:
Examples
Additionally, use the Min Length and Max Length Validation Rules to define character length boundaries for this control.
Additionally, use the Min Length and Max Length Validation Rules to define character length boundaries for this control.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Add a control from which the Request participant can auto-complete an entered address, location, or business.
Start entering an address, location, or business name into a Screen control, then allow the Google API to auto-complete that address or location. The Google Place control stores the selected address in the Request data as well as all the returned data from the Google API.
View and/or select from one or more geographical locations in a Google map.
Below are a few ways to use the Google Places control:
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Google Places icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The Google Places control has the following panels that contain settings:
Below are settings for the Line Input control in the Variable panel:
Use the Variable Name setting value in the following ways:
Follow these steps to add a validation rule to this control:
Select the rule that this control validates against.
Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.
Follow these steps to edit a validation rule for this control:
Follow these steps to delete a validation rule for this control:
Click Delete.
Below are the settings for the Google Places control in the Configuration panel:
The following settings are available below the Enable Maps setting to configure the Google Map settings and the map's geographical location when the map displays:
Below are settings for the Google Places control in the Design panel:
Below are settings for the Google Places control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Review the Google's JSON API response often as Google revises it often and without notice.
Below is the Google Places control selection for this example. The Google Places control's Variable Name setting value is the default google_places_1
.
The Rich Text control displays the following during a Request:
Below is the Google Places control selection for this example. The Google Places control's Variable Name setting value is the default google_places_1
.
The Rich Text control displays the following during a Request:
The Rich Text control displays the following during a Request:
Below is the Google Places control selection for this example. The Google Places control's Variable Name setting value is the default google_places_1
.
The Rich Text control displays the following during a Request:
The Rich Text control displays the following during a Request:
Below is the Google Places control selection for this example. The Google Places control's Variable Name setting value is the default google_places_1
.
The Rich Text control displays the following during a Request:
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode. Though you can enable Screen Validation in Preview mode, you may only fix validation errors in Design mode.
Errors are found: If errors are found, Screens Builder displays how any errors are found to the right of the Open Console button. The error icon displays with the number of current errors. Click the Open Console button to display a summary of the errors. Below is an example.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the File Download iconin the panel to the left of the Screen Builder canvas.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Enter the name of the download file. This setting has no default value.
Edit the default label that displays for this control if necessary. New File Download is the default value.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the Label setting value. For example, if a Submit Button control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Checkbox iconin the panel to the left of the Screen Builder canvas.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during Requests. Ensure that the Variable Name setting value is a unique name from other controls in this Screen and contains at least one letter. This is a required setting.
The Checkbox control is not selected: The key's value is false
.
Edit the default label that displays for this control if necessary. New Checkbox is the default value.
Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: No validation rule(s). See Validation Rules for "Validation" Control Settings.
Click the Add Rule button. The Select drop-down menu displays.
Click the Edit iconfor the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays.
Click the Delete iconfor the validation rule to delete. A message displays to confirm deletion of the validation rule.
Select to indicate that this control is selected by default such that its key's value is true
. This option is not selected by default.
Select to indicate that this control cannot be edited. This option is not selected by default.
Enter text that provides additional guidance on this control's use. This setting has no default value.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select to display a toggle key control instead of a checkbox control for each checkbox option. See a design example.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the Label setting value. For example, if a Submit Button control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
The File Preview control allows the participant to configure a file preview that has been previously uploaded to that Request via a . After adding the control in the to where to display the file preview, configure the Name setting value for the File Upload control from which to preview the file it uploaded to that Request.
type
type
See .
To add a File Preview control to a Screen, the must be installed.
See the permissions or ask your Administrator for assistance.
.
.
.
See how to preview multiple files that have been uploaded from a previous in that Request.
Follow these steps to add this control to the :
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the File Preview iconin the panel to the left of the Screen Builder canvas.
Place into the Screen Builder canvas where you want this control to display the file preview on the Screen.
Configure the File Preview control. See .
Validate that the control is configured correctly. See .
Below is a File Preview control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
As a best practice, after copying a control, change the value for the copied control to its own unique variable value. Otherwise, in-progress that use this Screen read from and send data to both controls.
.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
.
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during . Ensure that the Variable Name setting value is a unique name from other controls in this and contains at least one letter. This is a required setting.
Use the Variable Name setting value to reference this value in .
See when editing a Request variable name.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Enter the value for the control from which to preview its file that was previously uploaded to this Request. Do not use when entering the File Upload control's Name setting. This setting has no default value.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The File Upload control adds an area in the to which the participant can upload one or more files from a local computer or accessible network location. The Request participant can drag and place the file(s) on the control or select a button from which to locate the file(s) for upload. The uploaded file(s) can be referenced in a later step in a Request.
When a file is uploaded to a Screen during an in-progress Request, then submitted, that file can be downloaded from the . The file remains available from that Request's summary regardless of that Request's status.
If the is selected for a File Upload control, the Screen user may upload multiple files. After uploading multiple files, any uploaded file may be removed from the File Upload control by clicking the Remove iconfor that file prior to submitting that Screen.
The File Upload control is not available in .
This control is only available for -type Screens. See .
Need a solution to upload multiple files to a Screen that limits the number of files that maybe uploaded to a File Upload control? See how to use a control to .
See the permissions or ask your Administrator for assistance.
.
.
Follow these steps to add this control to the :
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the File Upload iconin the panel to the left of the Screen Builder canvas.
Configure the File Upload control. See .
Below is a File Upload control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
As a best practice, after copying a control, change the value for the copied control to its own unique variable value. Otherwise, in-progress that use this Screen read from and send data to both controls.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Enter the name of the uploaded file. This setting has no default value.
Edit the default label that displays for this control if necessary. New File Upload is the default value.
Select the Required setting to require a file be uploaded before the Screen can be submitted. This setting is not selected by default.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Enter the file type(s) this control accepts to upload by referencing its .
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the value. For example, if a control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
The image control may reference another control's setting to display its value, such as to display the signature saved in a control. The Signature control saves the signature as a PNG image.
type
type
See .
See the permissions or ask your Administrator for assistance.
.
.
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the Image iconin the panel to the left of the Screen Builder canvas.
Configure the Image control. See .
Validate that the control is configured correctly. See .
Below is an Image control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Enter the alphanumeric name that identifies the image in this .
Preview the uploaded image.
Select the Render image from a variable name setting to render as an image the content of another control by referencing that control's Variable Name setting value. For example, render an image of a signature from the control.
Do not use this setting to display a file referenced from a control.
After selecting the Render image from a variable name setting, the Variable Name setting displays.
In the Variable Name setting, enter the name setting value of the content to display as an image in the Image control. This Request variable must contain the content of the image. For example, to display a digital signature entered into a control with a Variable Name setting of SignDocument
, enter SignDocument
. If the Signature control has been signed, that digital signature displays in the Image control when it displays.
Enter text that provides additional guidance on this control's use. This setting has no default value.
Click the control while in mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Enter the height of the uploaded image in pixels. If the setting has no value, the Image control adjusts the uploaded image to the Height setting value.
Enter the width of the uploaded image in pixels. If the setting has no value, the Image control adjusts the uploaded image to the Width setting value.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Line Input control is a text field that the participant can enter information. Configure the Line Input control to accept one of the following data types:
As a best practice when a validates the JSON in a Screen for a datetime value, use a control instead of a control.
See the permissions or ask your Administrator for assistance.
.
.
Follow these steps to add this control to the :
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the Line Input iconin the panel to the left of the Screen Builder canvas.
Configure the Line Input control. See .
Validate that the control is configured correctly. See .
Below is a Line Input control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
As a best practice, after copying a control, change the value for the copied control to its own unique variable value. Otherwise, in-progress that use this Screen read from and send data to both controls.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during . Ensure that the Variable Name setting value is a unique name from other controls in this and contains at least one letter. This is a required setting.
Reference this control by its Variable Name setting's value. The Data Preview panel in corresponds the Line Input control's textual content with that Line Input control's Variable Name value. In the example below, LineInputControl
is the Variable Name setting's value.
Reference this control's value in a different Screen Builder control. To do so, use and reference this control's Variable Name value in the target control. Example: {{ LineInputControl }}
.
Reference this value in .
See when editing a Request variable name.
Edit the default label that displays for this control if necessary. New Input is the default value.
Ensure that all Line Input controls implemented in a -type Screen contain Label setting values. See .
This is a required setting.
Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: No validation rule(s). See .
Access the while in mode, and then locate the Validation Rules setting.
Click the Add Rule button. The Select drop-down menu displays.
Enter the parameter settings that this control uses to validate against. See , and then locate the validation rule for its parameters.
Access the while in mode, and then locate the Validation Rules setting.
Click the Edit iconfor the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays.
Edit the parameter settings that this control uses to validate against. See , and then locate the validation rule for its parameters.
Access the while in mode, and then locate the Validation Rules setting.
Click the Delete iconfor the validation rule to delete. A message displays to confirm deletion of the validation rule.
Select to indicate that this control cannot be edited. This option is not selected by default.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Enter the placeholder text that displays in this control when no value has been provided. This setting has no default value.
Enter text that provides additional guidance on this control's use. This setting has no default value.
Click the control while in mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Enter the default value this control displays. The default value can be assigned as a Request variable, text or JavaScript. When the Screen submits, the Request uses this control's default value unless the Request participant changes it. When using a in the Default Value setting, consider the following:
The Default Value setting supports using Request variables in . For example, if the Default Value setting is {{ FirstName }} {{ LastName }}
from which a Request participant entered her first name and last name in separate controls (respectively) earlier in that Request, this control displays the contents of those controls by default during the Request.
Enter the default value as text or use a Request variable in mustache syntax.
Enter the default value as JavaScript, especially if a might change this default value setting. Ensure to use the preceding the Screen control reference. Example: this.FullName
when FullName
is the Variable Value setting value for the control to set its default value.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
.
Enter a mask pattern to require a custom input format. If this setting does not have a mask pattern, then this control adds plain text without formatting.
Set the Social Security Number (SSN) using the mask pattern ###-##-####
. Then, the Line Input control only allows numeric values with that pattern.
Additionally, to ensure that users enter the correct number of digits, use to set Max Length and Min Length of this control to 9
.
Set a US phone number using the mask pattern +1 (###) ###-####
. Then, the Line Input control only allows numeric values preceding the US telephone code by default.
Set a car license plate that complies with the format for a specific US state, such as AAA ###
. Then, the Line Input control only allows upper case alphabetic characters followed by numeric values.
The panel displays the entered text without the mask patterns.
This custom format input overrides any other formatting set by default, including the one described when using .
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the value. For example, if a control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
Use the Google Places package to allow participants to do the following in -type :
This control is only available for -type Screens. See .
Allow Request participants to easily enter a shipping or billing address.
Enter a business name into the Google Places control to select a business location.
Enter well-known monuments or international airport names to get their addresses or locations when requesting to travel.
To add a Google Places control to a Screen, the must be installed.
See the permissions or ask your Administrator for assistance.
.
.
.
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the Google Places iconin the panel to the left of the Screen Builder canvas.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Configure the Google Places control. See .
Validate that the control is configured correctly. See .
Below is a Google Places control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
As a best practice, after copying a control, change the value for the copied control to its own unique variable value. Otherwise, in-progress that use this Screen read from and send data to both controls.
.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
.
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during . Ensure that the Variable Name setting value is a unique name from other controls in this and contains at least one letter. This is a required setting.
Reference this control by its Variable Name setting's value. The Data Preview panel in corresponds the Google Places control's textual content with that Google Places control's Variable Name value. In the example below, GooglePlacesControl
is the Variable Name setting's value.
Reference this control's value in a different Screen Builder control. To do so, use and reference this control's Variable Name value in the target control. Example: {{ GooglePlacesControl }}
. See .
Reference this value in .
See when editing a Request variable name.
Edit the default label that displays for this control if necessary. New Google Places is the default value.
Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: No validation rule(s). See .
Access the while in mode, and then locate the Validation Rules setting.
Click the Add Rule button. The Select drop-down menu displays.
Enter the parameter settings that this control uses to validate against. See , and then locate the validation rule for its parameters.
Access the while in mode, and then locate the Validation Rules setting.
Click the Edit iconfor the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays.
Edit the parameter settings that this control uses to validate against. See , and then locate the validation rule for its parameters.
Access the while in mode, and then locate the Validation Rules setting.
Click the Delete iconfor the validation rule to delete. A message displays to confirm deletion of the validation rule.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Enter the placeholder text that displays in this control when no value has been provided. This setting has no default value.
Enter text that provides additional guidance on this control's use. This setting has no default value.
Select to enable Google Maps in this Screen. This setting is disabled by default.
Hide the address bar that displays above the map to enter an address to display in the map. This setting is disabled by default to display the address bar. Note that this setting is not available unless the is selected.
Allow the Request participant to select a location in the map. When this setting is disabled, the is available to enter the geo-location by longitude and latitude to center the map view. The Enable Geolocate setting is disabled by default. Note that the Enable Geolocate setting is not available unless the is selected.
Displays the zoom controls in the lower-right of the map view used to zoom into and out of the map view. This setting is disabled by default to hide the zoom controls. Note that this setting is not available unless the is selected.
Displays the Map or Satellite options in the upper-left of the map view used to toggle between viewing the map or the satellite image of the viewing area. This setting is disabled by default to display the Map options. Note that this setting is not available unless the is selected.
Displays the control in the upper-right of the map view to toggle full screen mode. This setting is disabled by default to hide this control. Note that this setting is not available unless the is selected.
Displays the Street View Pegman control to view the street view of the displayed map area. This setting is disabled by default to hide this control. Note that this setting is not available unless the is selected.
Displays the center geographical location of the map view by longitude and latitude coordinates. The default longitude and latitude coordinates are -93
by 39
. Note that this setting is not available unless the is selected and the is not selected.
Sets the initial map zoom level that ranges from 0 (no zoom) to 19 (maximum zoom). The default zoom setting is 3
. Note that this setting is not available unless the is selected.
Click the control while in mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
.
.
The Google Places control receives its source data from the Google API response after the participant selects an address or location. The Google Places control stores the in the Request data. See the to determine how to use JSON key name values in the response for Request data.
Follow these guidelines to reference key names and/or from Google's returned data object in other controls.
Reference the following JSON key name for the entire selected address or location that includes the entire value in the Google Places control as indicated in :
variable_name
represents the value for the Google Places control being referenced.
If a control references this Google Places control's entire selected address, use the following syntax in the Rich Text control's content using :
Reference the following JSON key name for the main text for the selected address or location as indicated in :
variable_name
represents the value for the Google Places control being referenced.
If a control references this Google Places control's main text for the selected address, use the following syntax in the Rich Text control's content using :
Reference the following JSON key name for the secondary text for the selected address or location as indicated in :
variable_name
represents the value for the Google Places control being referenced.
If a control references this Google Places control's secondary text for the selected address, use the following syntax in the Rich Text control's content using :
Reference the following JSON array for the for the selected address or location as indicated in :
variable_name
represents the value for the Google Places control being referenced.
If a control references this Google Places control's secondary text for the selected address, use the following syntax in the Rich Text control's content using :
Token | Pattern |
# | Positive integer values [0-9] |
X | [0-9, a-z, A-Z] |
S | [a-z, A-Z] |
A | All text convert to upper case |
a | All text convert to lower case |
! | Set undefined value |
Add a Nested Screen control into which select a separate Screen that is in your ProcessMaker Platform instance.
Use the Nested Screen control to nest a separate Screen into that control. In doing so, the separate Screen embeds into the Nested Screen control. The Nested Screen control is a placeholder for the embedded Screen such that the Request participant experiences the nested Screen as designed. When the Task loads the Screen using a Nested Screen control, the Nested Screen loads the latest version of the referenced Screen.
The Screen containing the Nested Screen control is the parent Screen. The Screen that is nested is the child Screen.
During an in-progress Requests, both Request and Magic Variable data pass to a child Screen when it displays within the parent Screen. Furthermore, information that is entered into a child Screen displays in Request summaries that use the parent Screen.
A nested Screen has the following attributes that vary from how it may have been designed:
CSS takes precedent: Any CSS designed in Custom CSS mode in the parent Screen takes precedent over any CSS designed in the child (nested) Screens. The Request participant experiences one design experience without a variety of design styles.
Submit Button control in nested Screens is hidden: During in-progress Requests, the Submit Button control is hidden in child Screens so that the Request participant uses the parent Screen's Submit Button control to submit the Task.
Two Screens cannot reference each other indefinitely: A child Screen that has already displayed within a parent Screen cannot display again in the same Request. This prevents an infinite loop whereby two Screens using Nested Screen controls reference each other indefinitely.
Screen designers can easily build a Screen by placing modular components into one Screen. For example, in a Screen designed for a purchase request, use Nested Screen controls as placeholders for the following components that are designed in separate Screens. Each of these Screens are nested into its own Nested Screen control.
Nested Screen control for Screen 1: Personal information
Nested Screen control for Screen 2: Payment information
Nested Screen control for Screen 3: Billing information
Nested Screen control for Screen 4: Shipping information
This control is only available for Form-type Screens. See Screen Types.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Nested Screen icon into the Screen Builder canvas. Existing controls on the Screens Builder canvas adjust positioning based on where you drag the control.
Configure the Nested Screen control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a Nested Screen control in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. Consider when moving this control that it displays a child (nested) Screen during in-progress Requests. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
Consider the following when deleting a configured Nested Screen control:
Deleting a Nested Screen control also deletes the nested Screen.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Nested Screen control has the following panels that contain settings:
Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Below is the setting for the Nested Screen control in the Variable panel:
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Nested Screen control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Add a control to display a container of two or more columns from which other controls display.
The Multicolumn / Table control adds a layout element with two or more columns. Drag and place other controls into any of the columns to display them to the width of the Multicolumn / Table control column.
Specify the width of each column in colspan
HTML attribute settings. The total of all colspan
attribute settings must be divisible by 12. The control contains two columns of six (6) colspan
HTML attribute setting each by default. See a design example.
This control is only available for the following Screen types:
See Screen Types.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Multicolumn / Table icon into the Screen Builder canvas. Existing controls on the Screens Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Configure the Multicolumn / Table control. See Settings.
Below is a Multicolumn / Table control in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. Consider when moving this control that it contains other controls. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control deletes configuration for that control as well as any controls placed into the Multicolumn / Table control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Multicolumn / Table control has the following panels that contain settings:
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below is the setting for the Multicolumn / Table control in the Configuration panel:
Specify the column width for each column in the control. Add each column and its width specification in the order they are to display from left to right in the control. Specify the width of each column in colspan
HTML attribute settings. The total of all colspan
attribute settings must be divisible by 12. The control contains two columns of six (6) colspan
HTML attribute setting each by default. See a design example.
Each option has the following settings:
Column: Column is the internal designation for the column that only the form designer views at design time.
Colspan: Colspan is the width of the column in colspan
HTML attribute settings.
Follow these steps to add a column and specify its width:
Click Add Column from below the Column Width setting. The Add New Column screen displays.
In the Column Width setting, enter the width of the column (as described above).
Click OK. The column displays below the existing columns in Column Width.
Click the control while in Design mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Multicolumn / Table control in the Design panel:
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Multicolumn / Table control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Add a Loop control that contains multiple controls that loop multiple times to allow entering multiple items, each of which requires multiple pieces of information.
Use the Loop control to contain one or more Screen controls to duplicate the contained set of controls a specified number of times, thereby minimizing the design work to duplicate that set of controls in a Screen. Use the Loop control when the Request participant must enter multiple instances of the same set of information, each of which contain multiple components.
For example, use a Loop control when a university registrar's office must enter the following information for each new university student enrolling to the university:
During the in-progress Request, the Loop control displays the set of controls contained in the Loop control a specified number of times so that the university registrar's office may enter the same information for each new student from one Screen page. The Submit Button control to submit the Screen must be placed outside of the Loop control. Otherwise, a Submit Button control displays in each set of controls placed into the Loop control. See a design example.
Do not place another Loop control inside the first Loop control.
_parent
JSON Key to Reference Request Data from Controls in a Loop ControlThe Loop control uses a unique JSON key available to any control placed within the Loop control to reference Request data. Controls that are placed into a Loop control for duplication are within a container and may only access another control's data that is in the same Loop control. Use the _parent
JSON key in a control's settings placed within a Loop control to reference Request data outside of that Loop control.
The _parent
JSON key only applies to controls placed into a Loop control or Record List control.
Consider the following examples:
A Line Input control placed within a Loop control requires a default value to display from another Line Input control used during that Request of which its Variable Name setting is Line_Input_Data
. From the Line Input control placed within the Loop control, enter the following into the Default Value setting: {{ _parent.Line_Input_Data }}
.
A Select List control placed within a Loop control requires its options to display from another Select List control's options used during that Request of which its Variable Name setting is Select_List_Options
. While configuring the Select List control placed within the Loop control to use Request data as its data source, enter the following into the Options Variable setting: _parent.Select_List_Options
.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Loop icon into the Screen Builder canvas. Existing controls on the Screens Builder canvas adjust positioning based on where you drag the control.
Configure the Loop control. See Settings.
Drag and place the Screen control(s) into the Loop control that you intend the Request participant to enter information each time the Loop control repeats. As a best practice, do not do the following:
Do not place a Submit Button control inside the Loop control.
Do not place another Loop control inside the first Loop control.
See Control Description for an example.
Configure each control placed into the Loop control. If a control placed into the Loop control requires to use Request data, use the parent
JSON key. See Use the parent
JSON Key to Reference Request Data from Controls in a Loop Control.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a Loop control in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. Consider when moving this control that it contains a set of controls that become duplicated during in-progress Requests. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.
Consider the following when deleting a configured Loop control:
Deleting a Loop control also deletes the controls placed into it.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Loop control has the following panels that contain settings:
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Loop control in the Configuration panel:
Make note of best practices when configuring a Loop control that contains a Select List control. If the Select List control references a JSON array from a data source, configure the Select List control to reference the JSON object containing the JSON array and not its values. Then duplicate the JSON array in the Loop control. See Duplicate the JSON Array in a Select List Control Used in a Loop Control.
This setting is not available in Display-type Screens since the content in these Screens is not editable.
Select whether to create a new array of JSON objects designed from Screen controls within the Loop control or to reference an existing JSON array of objects:
New array of JSON objects designed from Screen controls
When this option is selected, the Default Loop Count setting displays to indicate how many times to repeat the control(s) that the Loop control contains. See a design example.
Existing JSON array of objects
When this option is selected the Default Loop Count setting does not display since the JSON array specifies how many times to repeat the control(s) that the Loop control contains.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during Requests. Ensure that the Variable Name setting value is a unique name from other controls in this Screen and contains at least one letter. This is a required setting.
Use the Variable Name setting value in the following ways:
Reference this control's value in a different Screen Builder control. To do so, use mustache syntax and reference this control's Variable Name value in the target control. Example: {{ LoopControl }}
.
Reference this value in Visibility Rule setting expressions.
See best practices when editing a Request variable name.
This setting is not available in Display-type Screens since the content in these Screens is not editable.
This setting is not available in Display-type Screens since the content in these Screens is not editable.
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Loop control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Add a Page Navigation control from which the Request participant can go to another page in a multi-page Screen.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
View the Screen page to which to add the control.
Drag the Page Navigation icon into the Screen Builder canvas. Existing controls on the Screens Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The Page Navigation control has the following panels that contain settings:
Below is the setting for the Page Navigation control in the Variable panel:
Below is the setting for the Page Navigation control in the Configuration panel:
Below is the setting for the Page Navigation control in the Design panel:
Select the style for the Page Navigation control. The style changes the control's appearance but otherwise has no functional difference. Select from the following options:
Primary: Blue-colored background with white-colored Button Label text. This is the default option.
Secondary: Gray-colored background with white-colored Button Label text.
Success: Green-colored background with white-colored Button Label text.
Danger: Red-colored background with white-colored Button Label text.
Warning: Yellow-colored background with black-colored Button Label text.
Info: Teal-colored background with white-colored Button Label text.
Light: White-colored background with black-colored Button Label text.
Dark: Black-colored background with white-colored Button Label text.
Below are settings for the Page Navigation control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Add a control from which the Request participant can insert several values in a list.
This control is available for the following Screen types:
When configuring the Record List control, specify how the record list displays information after the control has recorded each record for the list:
Column Headers: Specify each column header that represents the data components for each record. For example, label a column header First Name
to indicate that this data component displays each person's first name for each record in the list.
After configuring the columns for the record list, sort the order in which they are to display in the record list.
Alternatively, use JSON format to configure the columns and their corresponding Variable Name setting values in their respective order to display in the Record List control.
Optionally, values can be edited after the Request participant initially enters the record(s) in the record list. However, after the Request participant submits the Screen, the record list cannot be changed.
Expect a similar experience as a Request participant when using a properly configured Record List control during a Request as follows:
Enter information for each data component for the record.
Click the OK button and ignore the Submit control.
Submit the Screen to save the record list in the Request. After the Task is submitted, the record list cannot be changed.
When configuring the Record List control, specify how the record list displays information in the Display-type Screen:
Column Headers: Specify each column header that represents the data components for each record in the list. For example, if the record list had recorded first names, then label a column header First Name
.
Repeat this procedure for each column header and its corresponding control that received a record data component for the record list. Make note of each control's Variable Name setting value, as you must provide this same value when configuring each column header in the record list.
After configuring the column headers for the record list, sort the order in which they are to display in the record list.
Alternatively, use JSON format to configure the column headers and their corresponding Variable Name setting values in their respective order to display in the Record List control.
After opening a Task or Manual Task with a Display-type Screen using a Record List control, the record list displays each record as entered in a Form-type Screen in a previous Task of that Request.
_parent
JSON Key to Reference Request Data from Controls in a Record List ControlThe Record List control uses a unique JSON key available to any control placed into the secondary page from which the Record List control references its values so that those controls can reference Request data. Controls that are placed into that secondary page function within a container and may only access another control's data that is in the same secondary page. Use the _parent
JSON key in a control's settings placed into the secondary page to reference Request data outside of that Record List control.
Consider the following examples:
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
View the Screen page to which to add the control.
Drag the Record List icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Form-type Screen:
Display-type Screen:
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The Record List control references the specified controls on the second page. The controls that receive the record data components cannot be on the same page as the Record List control.
The following table outlines how to configure the Column Header and Value settings for each column in the Record List control for this example.
Below are settings for the Record List control in the Variable panel:
Use the Variable Name setting value in the following ways:
Reference this control by its Variable Name setting's value.
Reference this control's value in a different Screen Builder control. To do so, use mustache syntax and reference this control's Variable Name value in the target control. Example: {{ RecordListControl }}
.
Below are settings for the Record List control in the Configuration panel:
The following message displays if no additional pages exist in this Screen from which to reference other controls: No Data Available.
Follow these steps to add a column to this control:
Ensure that the Edit as Options List option displays. If the Edit as JSON option displays, click the Edit as Option List option.
In the Column Header setting, enter the column header label that displays in the record list. This column header represents a data component for each record in the record list.
Follow these steps to add a column to this control:
Ensure that the Column list label displays. If the JSON Data option displays, click the Edit as Option List option.
In the Column Header setting, edit the column header label that displays in the record list as necessary. This column header represents a data component for each record in the record list.
Click Update. The edited column displays below the Column list label.
Follow these steps to delete a column from in this control:
Ensure that the Column list label displays. If the JSON Data option displays, click the Edit as Option List option.
Click Delete.
Follow these steps to sort the order of the columns that display in this control:
Ensure that the Column list label displays. If the JSON Data option displays, click the Edit as Option List option.
Follow these steps to add a column to this control using a JSON schema:
The JSON Data setting displays. If a valid JSON schema has been configured previously, the JSON Data setting displays the JSON. Otherwise the setting is empty.
Enter your control columns in the order they are to display in this control using JSON format. Use the scroll panel to the right of the JSON to scroll to different sections of the JSON if necessary. This is useful especially when you are editing a long JSON.
Below are settings for the Record List control in the Design panel:
Below are settings for the Record List control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Below are settings for the Record List control in the Variable panel:
Use the Variable Name setting value in the following ways:
Reference this control by its Variable Name setting's value.
Reference this control's value in a different Screen Builder control. To do so, use mustache syntax and reference this control's Variable Name value in the target control. Example: {{ RecordListControl }}
.
Follow these steps before configuring columns in this Record List control:
Save setting configurations in this Record List control if necessary.
Locate each control that corresponds with each specified column header. Each of these controls received a record data component when the record list was recorded in a Request. Make note of each control's Variable Name setting value, as you must provide this same value when configuring each column header in this Record List control.
Follow these steps to add a column to this control:
Ensure that the Column list label displays. If the JSON Data option displays, click the Edit as Option List option.
In the Column Header setting, enter the column header label that displays in the record list. This column header represents a data component for each record in the record list.
Follow these steps to add a column to this control:
Ensure that the Column list label displays. If the JSON Data option displays, click the Edit as Option List option.
In the Column Header setting, edit the column header label that displays in the record list as necessary. This column header represents a data component for each record in the record list.
Click Update. The edited column displays below the Column list label.
Follow these steps to delete a column from in this control:
Ensure that the Column list label displays. If the JSON Data option displays, click the Edit as Option List option.
Click Delete.
Follow these steps to sort the order of the columns that display in this control:
Ensure that the Column list label displays. If the JSON Data option displays, click the Edit as Option List option.
Follow these steps to add a column to this control using a JSON schema:
The JSON Data setting displays. If a valid JSON schema has been configured previously, the JSON Data setting displays the JSON. Otherwise the setting is empty.
Enter your control columns in the order they are to display in this control using JSON format. Use the scroll panel to the right of the JSON to scroll to different sections of the JSON if necessary. This is useful especially when you are editing a long JSON.
Below are settings for the Record List control in the Design panel:
Below are settings for the Record List control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Add a control that displays HTML-formatted text.
Aside from rich text styles and images, the Rich Text control can display the following information regarding in-progress Requests:
Include your own HTML syntax in the Rich Text control along with Request data references. Example: Full Name: <p>{{ FullName }}</p>
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
View the Screen page to which to add the control.
Drag the Rich Text icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Select the control to be deleted.
The Rich Text control has the following panels that contain settings:
Below is the setting for the Rich Text control in the Configuration panel:
Alternatively, use the What-You-See-Is-What-You-Get (WYSIWYG) rich text editor to enter your text. Reference images in your content using HTML syntax. The WYSIWYG rich text editor also supports mustache syntax. Your text and/or images display in the Content setting using HTML syntax.
Follow these guidelines to use the WYSIWYG rich text editor to stylize your text:
Select the required text from the Rich Text control.
In the URL setting, enter the destination URL.
In the Text to display setting, edit or enter the text displayed in the Rich Text control.
In the Title setting, enter the text to display when a user hovers over the displayed text.
From Open link in… drop-down menu, select one of these options:
New window: Select this option to open the destination page in a new browser window.
Current window: Select this option to open the destination page in the current browser window.
Format text: Follow these guidelines to format text:
Headings: From the Formats menu, select Headings and then select a heading size.
Bold: Do one of the following:
From the Formats menu, select Inline and then Bold.
Italics: Do one of the following:
From the Formats menu, select Inline and then Italic.
Underline: From the Formats menu, select Inline and then Underline.
Strikethrough: From the Formats menu, select Inline and then Strikethrough.
Superscript: From the Formats menu, select Inline and then Superscript.
Subscript: From the Formats menu, select Inline and then Subscript.
Code: From the Formats menu, select Inline and then Code.
Paragraph: From the Formats menu, select Blocks and then Paragraph.
Blockquote: From the Formats menu, select Blocks and then Blockquote.
Division: From the Formats menu, select Blocks and then Div.
Preformatted: From the Formats menu, select Blocks and then Pre.
Select one of the color swatches from the color palette. The selected text changes to that color.
Align text: Follow these guidelines to align text:
Left align: Do one of the following:
From the Formats menu, select Align and then Left.
Center align: Do one of the following:
From the Formats menu, select Align and then Center.
Right align: Do one of the following:
From the Formats menu, select Align and then Right.
Justify: Do one of the following:
From the Formats menu, select Align and then Justify.
Below are settings for the Rich Text control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Create a new Screen or click the Edit iconto edit the selected parent Screen to which to add the Nested Screen control. The Screen is in Design mode.
Locate the Nested Screen iconin the panel to the left of the Screen Builder canvas.
Place into the Screen Builder canvas where you want the control to display on the Screen. Ensure that the control's placement accounts for the Screen you intend to nest into this control.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Select which Screen to nest into this control. The nested Screen becomes the child Screen to the parent Screen that uses the Nested Screen control. Any Screen type may be selected for nesting into a Nested Screen control. However, only Form- and Display-type Screens preview in either Design or Preview modes.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Multicolumn / Table iconin the panel to the left of the Screen Builder canvas.
Drag and place others controls into a column. Configure and validate each control's settings.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Use the Show in Json Format toggle to display these settings in JSON.
Remove: Click the Removeicon to remove the column.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Loop iconin the panel to the left of the Screen Builder canvas.
Place into the Screen Builder canvas where you want the control to display on the Screen. Ensure that the control's placement accounts for the set of controls you intend to this control to contain.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Select the New Array of Objects option from the Data Source setting to place Screen controls into the Loop control while in Design mode.
Select the Existing Array option from the Data Source setting to reference a JSON array from the Request data that the Loop control contains.
Reference this control by its Variable Name setting's value. The Data Preview panel in Preview mode corresponds with the Loop control's Variable Name value. In the example below, LoopControl
is the Variable Name setting's value.
Enter the number of times to repeat the control(s) that the Loop control contains. 3 is the default value.
Select to allow additional loops during in-progress Requests if necessary.
If this setting is selected, then the Add Loop icondisplays below the looped container of controls that allows the Request participant to add a new loop for the Task. See a design example.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Page Navigation control adds a button from which the participant can go to another page in a multi-page . See a .
This control is only available for -type Screens. See .
See the permissions or ask your Administrator for assistance.
.
.
Follow these steps to add this control to the :
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the Page Navigation iconin the panel to the left of the Screen Builder canvas.
Configure the Page Navigation control. See .
Validate that the control is configured correctly. See .
Below is a Page Navigation control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Enter the text label that displays for this control. Page Navigation is the default value. See a .
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Select the destination page to which to navigate in a multi-page . Current pages in the multi-page Screen display. If the Screen contains only one page, the Destination Screen setting displays No Data Available when selected.
Click the control while in mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Link: White-colored background with blue-colored Button Label text.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the value. For example, if a control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
The Record List control functions differently in - and -type :
type
type (requires the )
type
See .
In the -type Screen, the Record List control records a record list. The record list is composed of multiple records, of which the participant enters data components for each record. The controls used to record each record's data components are designed in a second page of the same Screen containing the Record List control. The page that records the data components of each record cannot be on the same page as the Record List control.
Values: For each specified column header, reference the Variable Name setting value for the control on the second page that receives a data component for each record corresponding with each column header. For example, use a control with a Variable Name setting value of LineInputFirstName
to receive each person's first name for each record in the list, and then associate that LineInputFirstName
value with the First Name
column.
See .
Open the with the Screen using the Record List control. The Record List control displays an empty record list.
Click the Add Record button to add a record to the record list. A screen displays to enter data components for one record. In doing so, the Record List control references the controls on the secondary page of the Screen. In this example, enter a record for registrars for a conference.
Repeat Steps 2 through 4 for each record in the record list. As you enter each record, it displays in the record list. If the Record List control is configured to be editable (as shown below), then the Edit buttonand Delete buttondisplay to edit or delete a record, respectively. Otherwise, these buttons do not display and records cannot be changed after they are added.
In the -type Screen, the Record List control displays a record list previously entered into a -type Screen in a previous Task of that .
Values: For each specified column header, reference the Variable Name setting value for the control that corresponds with that specified column header's record data component. To do so, open the Screen that contains the Record List control that recorded the list, then locate the control that corresponds with the specified column header's record data component. For example, if a control with a Variable Name setting value of LineInputFirstName
is used to record each person's first name for each record in the list, associate that LineInputFirstName
with the specified First Name
column header.
See .
The _parent
JSON key only applies to controls placed into a Record List control or control.
A Line Input control placed into the secondary page requires a default value to display from another Line Input control used during that Request of which its Variable Name setting is Line_Input_Data
. From the Line Input control placed into the secondary page, enter the following into the : {{ _parent.Line_Input_Data }}
.
A Select List control placed within the secondary page requires its options to display from another Select List control's options used during that Request of which its Variable Name setting is Select_List_Options
. While configuring the Select List control placed into the secondary page to , enter the following into the Options Variable setting: {{ _parent.Select_List_Options }}
.
See the permissions or ask your Administrator for assistance.
.
.
Follow these steps to add this control to the :
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the Record List iconin the panel to the left of the Screen Builder canvas.
Do one of the following depending on whether you are using the Record List control on a - or -type Screen:
Create a new page in this Screen. Use this page to design how the Request participant enters data that the Record List control records. The page that records the submitted records cannot be on the same page as the Record List control. See .
On the new page, design the form using controls from which the Request participant enters the data component that the Record List control receives for each record. In each of the controls that receive a data component for each record, make note of the Variable Name setting values for each control; these values correspond with how the Record List control displays the record list in the Value parameter for each column. Do not place a control on the new page; otherwise, the cannot be submitted during a Request.
Configure each of the controls placed on the new page. If a control placed into this page requires to use Request data, use the parent
JSON key. See .
Return to the page that the Record List control is placed, and then configure the Record List control. See . Ensure to add a Submit Button or control on the page containing the Record List control so that the Task can be submitted after all records have been added to the record list during a Request.
Configure the Record List control. See .
Validate that the control is configured correctly. See .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. Consider when moving this control that it contains the set of records during in-progress . A control cannot be moved to another page.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
As a best practice, after copying a control, change the value for the copied control to its own unique variable value. Otherwise, in-progress that use this Screen read from and send data to both controls.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Consider the following example how to use a Record List control in a -type Screen. Configure a Record List control to record the following data components about registrars for a conference. The table below shows how the Record List control displays the record list. Configuring each column and the Variable Name setting value for each control that records the data component that displays in that column is the same for both Form- and -type Screens.
On a second page in the same , use Screen controls for participants to enter data components for each record. Ensure the following:
In each of the controls that receives a data component for each record, make note of the Variable Name setting values for each control; these values correspond with how the Record List control displays the record list in the Value parameter for each column. This setting is in the Columns panel. See .
The following image shows the Column Header and Value setting values in the Record List control to reference the control with the Variable Name setting value of firstname
.
The following image shows the column configuration for the Record List control. See for the Record List control setting descriptions.
Below is the secondary page in for each conference attendee to enter a record.
.
The Record List control has the following panels that contain settings for -type:
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during . Ensure that the Variable Name setting value is a unique name from other controls in this and contains at least one letter. This is a required setting.
Reference this value in .
See when editing a Request variable name.
Edit the default label that displays for this control if necessary. New Record List is the default value.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Select to indicate that records in the list can be edited or deleted with the Editand Deleteicons, respectively. Otherwise, deselect to indicate that after each record is added to the record list, it cannot be changed. Note that after the is submitted, the record list cannot be changed. This setting is not selected by default.
Select from which page to reference the controls that receive data components for each record. The page with these controls that receive the data components cannot be on the same page as the Record List control.
Click the control while in mode, and then click the Columns panel that is on the right-side of the Screen Builder canvas.
See the following procedures how to configure the column header(s) that display the record list data and from which control(s) on the additional page in this to reference data components of each record for this control.
Access the Columns panel for this control while in mode, and then locate the Column setting.
Click the iconbeside the Column label. The Add Column screen displays.
In the Value setting, enter the Variable Name setting value for the control on the second page of this Screen that receives a data component for each record that corresponds with this column header. For example, use a control with a Variable Name setting value of LineInputFirstName
to receive each person's first name for each record in the list, and then associate that LineInputFirstName
value with a column header labeled First Name
.
Click Save. The column header displays in the Column list label.
Access the Columns panel for this control while in mode, and then locate the Column setting.
Click theicon for the column to change its settings. The Edit Option screen displays.
In the Value setting, edit the Variable Name setting value for the control on the second page of this Screen that receives a data component for each record that corresponds with this column header as necessary. For example, use a control with a Variable Name setting value of LineInputFirstName
to receive each person's first name for each record in the list, and then associate that LineInputFirstName
value with a column header labeled First Name
.
Access the for this control while in mode, and then locate the Column setting.
Click theicon for the column to be deleted from this control. A message displays to confirm deletion of the option.
Access the for this control while in mode, and then locate the Column setting.
Drag theicon for each column up or down to sort the order they display in this control as necessary.
Access the Columns panel for this control while in mode, and then locate the Column setting.
Click the Edit as JSON option below the Column list label if this option does not currently displayed.
Click the iconbeside the JSON Data option. The Script Config Editor displays.
Click Close or the Close icon. The control columns are saved.
Click the control while in mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
Do not to use visibility rules with Screens. Some email clients that do not render natively from a web browser, such as Microsoft Outlook or Mozilla Thunderbird for the desktop, alter the HTML during rendering and may break visibility rules.
.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
.
The Record List control has the following panels that contain settings for -type :
Click the control while in mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during . Ensure that the Variable Name setting value is a unique name from other controls in this and contains at least one letter. This is a required setting.
Reference this value in .
See when editing a Request variable name.
Edit the default label that displays for this control if necessary. New Record List is the default value.
While in mode, open the Screen that contains the Record List control that recorded the list.
Click the control while in mode, and then click the Columns panel that is on the right-side of the Screen Builder canvas.
See the following procedures how to configure the column header(s) that display the record list data and from which control(s) on the additional page in this to reference data components of each record for this control.
Access the Columns panel for this control while in mode, and then locate the Column setting.
Click the iconbeside the Column label. The Add Column screen displays.
In the Value setting, enter the Variable Name setting value for the control on the second page of this Screen that receives a data component for each record that corresponds with this column header. For example, use a control with a Variable Name setting value of LineInputFirstName
to receive each person's first name for each record in the list, and then associate that LineInputFirstName
value with a column header labeled First Name
.
Click Save. The column header displays in the Column list label.
Access the Columns panel for this control while in mode, and then locate the Column setting.
Click theicon for a column to change its settings. The Edit Option screen displays.
In the Value setting, edit the Variable Name setting value for the control on the second page of this Screen that receives a data component for each record that corresponds with this column header as necessary. For example, use a control with a Variable Name setting value of LineInputFirstName
to receive each person's first name for each record in the list, and then associate that LineInputFirstName
value with a column header labeled First Name
.
Access the for this control while in mode, and then locate the Column setting.
Click theicon for the column to be deleted from this control. A message displays to confirm deletion of the option.
Access the for this control while in mode, and then locate the Column setting.
Drag theicon for each column up or down to sort the order they display in this control as necessary.
Access the Columns panel for this control while in mode, and then locate the Column setting.
Click the Edit as JSON option below the Column list label if this option does not currently displayed.
Click the iconbeside the JSON Data option. The Script Config Editor displays.
Click Close or the Close icon. The control columns are saved.
Click the control while in mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Specify an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Rich Text control displays HTML-formatted text and images. Use the What-You-See-Is-What-You-Get (WYSIWYG) editor to display a variety of text styles for the participant. Reference an image to display in the Rich Text control using HTML syntax. See a .
Request data: Display the value of another control in the same or different by referencing that control's Variable Value setting value using : encapsulate the Variable Name setting value between {{
and }}
that represent mustache syntax. In doing so, you are referencing Request data. Spaces surrounding the Request data reference are allowed. During the Request, the Rich Text control references the Request data to locate that control's value to display it in the Rich Text control.
Magic Variable values: Display the value of a by referencing the Magic Variable using mustache syntax. Example: {{ _user.fullname }}
. Spaces surrounding the Magic Variable reference are allowed.
See the permissions or ask your Administrator for assistance.
.
.
Follow these steps to add this control to the :
or click the Edit iconto edit the selected Screen. The Screen is in .
Locate the Rich Text iconin the panel to the left of the Screen Builder canvas.
Configure the Rich Text control. See .
Validate that the control is configured correctly. See .
Below is a Rich Text control in .
After , you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another page.
.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that page.
.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
.
Follow these steps to delete a control from a page:
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
.
Click the control while in mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Enter the text and/or image to display in the Rich Text control using HTML syntax (see a ) and/or . Rich text editor is the default value. See this for information how to use mustache syntax.
Ensure that all Rich Text controls implemented in a -type Screen contain content in their Content settings. See .
Undo changes: Click on theicon to undo the last action.
Redo changes: Click on theicon to redo the last undone action.
Insert/Edit links: Click on theicon to convert the selected text into a hyperlink. Follow these steps to create a hyperlink:
Click on theicon. The Insert/Edit Link screen displays.
From the editor toolbar, select theicon.
From the editor toolbar, select theicon.
Change text color: Use the Text Color drop-down to change text color. Click on theicon. The color palette displays. Do one of the following:
Click theicon to select a custom color from the Color Picker.
Click theicon to reset the text to its default color.
From the editor toolbar, use theicon to left- align text.
From the editor toolbar, use theicon to center-align text.
From the editor toolbar, use theicon to right-align text.
From the editor toolbar, use theicon to justify text.
Insert a bullet list: Use theicon to format text as a bulleted list.
Insert a numbered list: Use theicon to format text as a numbered list.
Indent text: Click on theicon to increase text indenting.
Outdent text: Click on theicon to decrease text indenting.
Select the Render HTML from a Variable setting to not show HTML syntax, but instead render the HTML syntax. If the Render HTML from a Variable setting is not selected, then the Rich Text control displays the HTML syntax. If a Request variable from which the Rich Text control references its data contains HTML syntax, select this setting to render that HTML.
Click the control while in mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Enter an expression that indicates the condition(s) under which this control displays. See . If this setting does not have an expression, then this control displays by default.
Do not to use visibility rules with Screens. Some email clients that do not render natively from a web browser, such as Microsoft Outlook or Mozilla Thunderbird for the desktop, alter the HTML during rendering and may break visibility rules.
.
Enter the value to represent this control in custom CSS syntax when in mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
Information
Screen Control
First Name
Line Input control
Last Name
Line Input control
Age
Line Input control
Sex
Select List control
Housing Dormitory
Select List control
Control Type | Control's "Variable Name" Value | Record List "Column Header" Value | Record List "Value" Value | What It Represents |
Line Input | firstname | First Name | firstname | Registrar's first name |
Line Input | lastname | Last Name | lastname | Registrar's last name |
Line Input | Email Address | Registrar's email address |
Select | confirmation | Confirmation | confirmation | Attendance confirmation |
Add a control from which the Request participant submits the Screen.
The Submit Button control adds a button to the Screen. The Submit Button control has two functions:
Submit: Submits the Screen whilst setting this control's value as specified from the Value setting. This is the default setting.
Do Not Submit, Set Value: Sets this control's value as specified from the Value setting, but does not submit the Screen.
This control is only available for Form-type Screens. See Screen Types.
See how to configure a Submit Button control that prevents the Request participant from clicking on that control multiple times so the Screen cannot be submitted after the first click.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Submit Button icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Configure the Submit Button control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a Submit Button control in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Submit Button control has the following panels that contain settings:
Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Submit Button control in the Variable panel:
Use the Variable Name setting value in the following ways:
Reference this control's value in a different Screen Builder control. To do so, use mustache syntax and reference this control's Variable Name value in the target control. Example: {{ SubmitButtonControl }}
.
Reference this value in Visibility Rule setting expressions.
See best practices when editing a Request variable name.
See how to configure a Submit Button control that prevents the Request participant from clicking on that control multiple times so the Screen cannot be submitted after the first click.
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below are the settings for the Submit Button control in the Configuration panel:
Select from the following options how the Submit Button control functions when the control is clicked:
Submit: Submits the Screen whilst setting this control's value as specified from the Value setting. This is the default setting.
Follow these steps to configure how the tooltip displays for the Submit Button control:
From the Position drop-down menu, select the position of the tooltip relative to the Submit Button control from the following options:
Top
Top Left
Top Right
Right
Right Top
Right Bottom
Bottom
Bottom Left
Bottom Right
Left
Left Top
Left Bottom
From the Variant drop-down menu, select the style for the tooltip:
Primary: Blue-colored background with white-colored Label text. This is the default option.
Secondary: Gray-colored background with white-colored Label text.
Success: Green-colored background with white-colored Label text.
Danger: Red-colored background with white-colored Label text.
Warning: Yellow-colored background with black-colored Label text.
Info: Teal-colored background with white-colored Label text.
Light: White-colored background with black-colored Label text.
Dark: Black-colored background with white-colored Label text.
In the Tooltip Contains setting, enter the text that the tooltip displays. This setting supports both HTML and mustache syntax.
Click the control while in Design mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Below is the setting for the Submit Button control in the Design panel:
Select the style for the Submit Button control. The style changes the control's appearance but otherwise has no functional difference. Select from the following options:
Primary: Blue-colored background with white-colored Label text. This is the default option.
Secondary: Gray-colored background with white-colored Label text.
Success: Green-colored background with white-colored Label text.
Danger: Red-colored background with white-colored Label text.
Warning: Yellow-colored background with black-colored Label text.
Info: Teal-colored background with white-colored Label text.
Light: White-colored background with black-colored Label text.
Dark: Black-colored background with white-colored Label text.
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Submit Button control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See how to configure a Submit Button control that prevents the Request participant from clicking on that control multiple times so the Screen cannot be submitted after the first click.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Add a control that displays a Saved Search chart.
The Saved Search Chart control embeds a chart from a Saved Search into a Screen. The Saved Search chart visualizes the latest Saved Search result data at the time the Screen displays. The Saved Search chart is interactive as if it were in the Charts tab of its Saved Search. By embedding a Saved Search chart into a Screen widens that chart's viewability to more stakeholders or even individuals who are not users in your organization by allowing anonymous users access ProcessMaker via the Web Entry package.
Use the Saved Search Chart control to visualize Saved Search results directly within Screens in the following ways:
Request participants can view the current chart configured for a Saved Search using the latest Request data at the time the Request participant views the Screen.
Request participants who do not have access to Collections can view charts for Saved Searches based on a Collection.
This control is only available for the following Screen types:
See Screen Types.
To add a Saved Search Chart control to a Screen, the Saved Searches package must be installed.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
To select a Saved Search Chart from a Saved Search Chart control, you must be that Saved Search's owner or have been shared the Saved Search.
A ProcessMaker Platform package is required to do this.
Permissions are required to do this.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Saved Search Chart icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Configure the Saved Search Chart control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a Saved Search Chart control in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Saved Search Chart control has the following panel that contains settings:
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below are the settings for the Saved Search Chart control in the Configuration panel:
The Size setting options are based on the height of the Saved Search chart. The width of the chart adjusts accordingly. Select from the following options:
Half: The Half option displays the chart by half its height.
Standard: The Standard option displays the chart in its default height. The Standard option is the default setting.
Double: The Double option displays the chart double its default height.
Add a control that displays a digital signature in Screens.
The Signature control allows the Request participant to sign and her or his signature in a Screen. The entered signature automatically saves, but is not committed until the signer submits the Screen. The signer may undo the entered signature prior to submitting the Screen. The submitted signature is recorded as a PNG image that may be referenced from an Image control by referencing the Signature control's Variable Name setting value.
This control is only available for Form-type Screens. See Screen Types.
To add a Signature control to a Screen, the Signature package must be installed.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
A ProcessMaker Platform package is required to do this.
Permissions are required to do this.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Signature icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Configure the Image control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a digital Signature added in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Signature control has the following panels that contains settings:
Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Signature control in the Variable panel:
Enter the alphanumeric name that identifies this Screen. This field is required.
Use the Variable Name setting value in the following ways:
Reference this control's value in a different Screen Builder control. To do so, use mustache syntax and reference this control's Variable Name value in the target control. Example: {{ SignatureControl }}
.
Reference this value in Visibility Rule setting expressions.
See best practices when editing a Request variable name.
Select the Required setting to clarify that the signature is required to submit the form.
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below is the setting for the Signature control in the Configuration panel:
The height may be set in any of the following units:
em unit, based upon the relative font-size of the parent font size (em)
inches (in)
percentage (%)
pixels (px)
relative to the viewpoint's height (vh)
relative to the viewpoint's width (vw)
rem unit, based upon the font-size value of the root element (rem)
100px is the default height setting.
If the entered value is not in the correct format, the following validation error displays: The Pad Height format is invalid..
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are the settings for the Signature control in the Advanced panel:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Add either a checkbox- or multi-select drop-down menu-style control from which the Request participant selects one or more options.
The Select List control provides either a checkbox- or multi-select drop-down menu-style control from which the Request participant selects one or more options.
Set options that display in this control in one of the following ways:
Provide each option: For each option, enter a unique value that represents the option, and then enter the text that displays as the option. After your options are configured, sort the order in which they are to display in the control. Alternatively, provide options in the control in JSON format.
Reference data in a Request Variable: Reference data from the in-progress Request as options in this control. This data object must be part of the Request's JSON data model.
Reference a data source in the JSON data model: Reference data from a Data Connector that displays in this control as its options. Specify the data name, value, and content from the Data Connector. See a design example. Optionally, use a PMQL expression to limit which data to use as options based on the PMQL expression's criteria. The order that data objects present in the data object determines the order these options display in the control; options cannot be manually reordered.
Reference data in a Collection: Reference data from a Collection and display it as options in this control. Optionally, use a PMQL expression to filter the displayed options in real-time. For an example, see Example: Dependent Select List Controls Display Countries and Regions from a Collection.
This control is only available for the following Screen types:
Conversational-type
Form-type
See Screen Types.
When using the Select List control with checkboxes, the control functions similarly to multiple Checkbox controls whereby multiple options may be selected. Unlike using multiple Checkbox controls, the Select List control includes all selected options as an array in the order that options are selected. This array becomes part of the JSON data model as shown in the example below in Preview mode.
When using the Select List control as the drop-down menu, multiple options may be selected one at a time. Selected options have the following attributes:
Each selected option displays in the control.
Each selected option displays in bold-style text in the drop-down menu. Furthermore, a red-colored highlight displays when hovering over a selected option, rather than the default green-colored highlight for deselected options.
Follow these guidelines to deselect an item from the Select List control when using the drop-down menu style:
Select the option again from the drop-down menu.
The Select List control includes all selected options as an array in the order that options are selected. This array becomes part of the JSON data model as shown in the example below in Preview mode.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Select List icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Configure the Select List control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a Select List control in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Select List control has the following panels that contain settings:
Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Select List control in the Variable panel:
Use the Variable Name setting value in the following ways:
Reference this value in Visibility Rule setting expressions.
Reference a property from the selected value when the Select List control is of type object
in the current Screen or with a Nested Screen control. To do so, first reference this control's Variable Name value in a Calculated Property, then use this Calculated Property in the target control. As a best practice, do not directly reference the Variable Name setting of a Select List control.
Create a Calculated Property and set the Property Name setting to accountName
.
In the JavaScript setting, enter the following JavaScript code:
See best practices when editing a Request variable name.
Ensure that all Select List controls implemented in a Conversational-type Screen contain Label setting values. See Controls in Conversational-Type Screens Require Labels.
Follow these steps to add a validation rule to this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Select the rule that this control validates against.
Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.
Enter the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.
Follow these steps to edit a validation rule for this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Edit the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.
Follow these steps to delete a validation rule for this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Click Delete.
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Select List control in the Configuration panel:
Click the control while in Design mode, and then click the Data Source panel that is on the right-side of the Screen Builder canvas.
From the Data Source panel, select one of the following methods to specify options that display in the Select List control:
Provide options: Enter a unique value that represents each option, and then enter the text that displays as the option. After your options are configured, sort the order in which they are to display in this control. Alternatively, provide options in this control in JSON format.
Request data: Reference data from the in-progress Request as options in this control. This data object must be part of the Request's JSON data model. During the in-progress Request, the Select List control references a specified data array and object in the Request's JSON data model to display its values as options in that control. The order that data objects are in the Request's JSON data model determines the order these options display in the control; options cannot be manually reordered. See the following related topics:
Data Connector: Reference the data from a Data Connector's Endpoint as options in this control. Note that the Data Connector package must be installed for this option to be available.
These Endpoints a Data Connector references may be Application Program Interface (API) endpoints, Collection records, or other data source endpoints. During the in-progress Request, when the Select List control references data from the Data Connector, the control maps the Data Connector data to a specified JSON data array, variable or key name, or data object to become part of that Request's data. Data maps to the JSON data array in the same order it is retrieved from the Data Connector. Optionally, use a PMQL expression to limit which data to use as options based on the PMQL expression's criteria. The order that data objects return from the Data Connector determines the order these options display in the control; options cannot be manually reordered.
See Example: Dependent Select List Controls Display Countries and Regions.
Collection: Reference data saved in a Collection and display records from a Collection column. Optionally, use a PMQL expression to limit which data to use as options based on the PMQL expression's criteria. For an example, see Example: Dependent Select List Controls Display Countries and Regions from a Collection.
See the following procedures how to provide options for a Select List control.
Follow these steps to add an option that displays in this control using Screen Builder:
Access the Data Source panel for this control while in Design mode, and then locate the Data Source setting.
In the Value setting, enter a value to represent the option in the Request data. This value must be unique from other values in this control. If the value is not unique to other Value settings in this control, the following message displays: An item with the same key already exists.
In the Content setting, enter the option that displays in this control.
Follow these steps to edit an option that displays in this control using Screen Builder:
In the Value setting, edit the value to represent the option in the JSON data model during in-progress Requests for Processes that use this Screen as necessary. This value must be unique from other values in this control. If the value is not unique to other Value settings in this control, the following message displays: An item with the same key already exists.
In the Content setting, edit the option that displays in this control as necessary.
Click Update. The edited option displays below the Options list label.
Follow these steps to delete an option from in this control using Screen Builder:
Click Delete.
Follow these steps to sort the order of the options that display in this control using Screen Builder:
Follow these steps to set whether multiple selections can be selected from this control and how the options display:
From the Render Options As drop-down menu, select one of the following options:
Dropdown/Multiselect: Select the Dropdown/Multiselect option to display the control as a drop-down menu.
Follow these steps to provide options that display in this control using a JSON schema:
Access the Data Source panel for this control while in Design mode, and then locate the Data Source setting.
The JSON Data setting displays. If a valid JSON schema has been configured previously, the JSON Data setting displays the JSON. Otherwise, this setting is empty.
Enter your control options in the order they are to display in this control using JSON format. Use the scroll panel to the right of the JSON to scroll to different sections of the JSON if necessary. This is useful especially when you are editing a long JSON.
Follow these steps to set whether multiple selections can be selected from this control and how the options display:
From the Render Options As drop-down menu, select one of the following options:
Dropdown/Multiselect: Select the Dropdown/Multiselect option to display the control as a drop-down menu.
Make note of best practices when configuring a Select List control's options when that control is within a Loop control. When referencing a JSON array from Request data, configure the Select List control to reference the JSON object containing the JSON array and not its values. Then duplicate the JSON array in the Loop control. See Duplicate the JSON Array in a Select List Control Used in a Loop Control.
Make note of best practices when editing a Collection record using a Select List control in a Loop control, configure the Select List control's Type of Value Returned setting with the Single Value option. See Use Single Value instead Object in a Select List.
Follow these steps to reference data from the in-progress Request as options in this control:
Access the Data Source panel for this control while in Design mode.
In the Option Label Shown setting, enter the JSON object key name from within the JSON array containing the Request variable from which to display as each option in this control. To use all JSON object key names in the JSON object, do not enter a value into the Option Label Shown setting. Use JSON dot notation as necessary.
For example, consider the following JSON array within Request data named accountTypes
that contains two JSON objects, both of which their key names are type
:
"accountTypes": [
{"type": "Life"},
{"type": "Medical"}
]
To reference both values from the key name type
as options in the Select List control, use the following JSON dot notation in the Option Label Shown setting: data.accountTypes
. The JSON array must contain JSON objects composed of key names and corresponding values, not just values like the following:
"accountTypes": [
"Life", "Medical"
]
From the Show Control As drop-down menu, select one of the following options:
Dropdown/Multiselect: Select the Dropdown/Multiselect option to display the control as a drop-down menu.
From the Type of Value Returned drop-down menu, select one of the following options:
Single Value: Select the Single Value option to indicate that only a part of the JSON object specified from the Option Label Shown displays as each option in this control. As a best and general practice, use single-value JSON objects.
Note that the Data Connector package must be installed for this option to be available. T
Make note of best practices when configuring a Select List control's options when that control is within a Loop control. When referencing a JSON array from a data source, configure the Select List control to reference the JSON object containing the JSON array and not its values. Then duplicate the JSON array in the Loop control. See Duplicate the JSON Array in a Select List Control Used in a Loop Control.
Make note of best practices when editing a Collection record using a Select List control in a Loop control, configure the Select List control's Type of Value Returned setting with the Single Value option. See Use Single Value instead Object in a Select List.
Follow these steps to reference data from a Data Connector as options in this control:
Access the Data Source panel for this control while in Design mode.
From the Show Control As drop-down menu, select one of the following options:
Dropdown/Multiselect: Select the Dropdown/Multiselect option to display the control as a drop-down menu.
From the Type of Value Returned drop-down menu, select one of the following options:
Single Value: Select the Single Value option to indicate that only a part of the JSON object specified from the Option Label Shown displays as each option in this control.
In the Content setting, enter the JSON object key name from within the JSON array containing the JSON response to display as each option in this control. To use all JSON object key names in the JSON object, do not enter a value into the Content setting. Use JSON dot notation as necessary. Optionally, use mustache syntax to indicate the JSON object key name from within the JSON array.
Consider the following example of doctors who work in a clinic.
Use the following settings to reference this data array as options for this control:
Element Name: doctors
Value: id
Content: name
Suppose that a new patient at the clinic indicates that she wants to see a female doctor. To filter doctors from this JSON data array who are female in the clinic so that only those objects display as options in a Select List control, use the following PMQL expression in the PMQL setting of that control:
gender = "female"
Note that the Collections package must be installed for this option to be available.
Follow these steps to reference data from a Collection as options in this control:
Access the Data Source panel for this control while in Design mode.
Selecting City Name
in Label and Value displays the name of all cities in the Select List control and save the name of the selected city in Request data.
Selecting City Name
in Label and Zip Code
in Value, displays a list of cities, but saves the Zip Code of the selected city in Request data.
Click the control while in Design mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Select List control in the Design panel:
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Select List in the Advanced panel:
Enter the default value this control displays. The default value can be assigned as a Request variable, text or JavaScript. When the Screen submits, the Request uses this control's default value unless the Request participant changes it. When using a Request variable in the Default Value setting, consider the following:
If the Request variable is empty, the control does not display any value by default.
When the Request variable is assigned a value for the first time, this value becomes the permanent default value of the control.
Any further changes to the Request variable do not affect the default value of the control.
The Default Value setting supports using Request variables in mustache syntax. For example, if the Default Value setting is {{ FirstName }} {{ LastName }}
from which a Request participant entered her first name and last name in separate controls (respectively) earlier in that Request, this control displays the contents of those controls by default during the Request.
There are two ways to enter the default value this control displays.
When the Select List control is configured with Provide Options, the Default Value setting compares numerical values as a string.
If the Select List is configured with Provide Options Using a JSON Schema, take care to enclose the numerical values in quotation marks (such as "1"
) because this can cause errors when comparing against the Default Value setting value.
If you need to compare default values other than a String-type value, enter the default value using JavaScript.
As opposite to the default setting, the JavaScript setting accepts values different to a String. Then if the Select List is configured with Provide Options Using a JSON Schema, then enter the Default Value as in the JSON schema. For example enter return 2;
if the JSON values are integers like:
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Add a control from which the Request participant can insert more than three lines of text.
The Textarea control allows the Request participant to insert more than three lines of text. Though this control displays a vertical scroll bar if more than three lines are inserted, the input box can be expanded as necessary. To do this, click the lower right-hand corner of the input box of the Textarea control, hold, and then drag to enlarge or shrink the control size as necessary. Release when you have adjusted the Textarea control to your required size.
This control is only available for Form-type Screens. See Screen Types.
Your user account or group membership must have the following permissions to design a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add this control to the Screen:
View the Screen page to which to add the control.
Drag the Textarea icon into the Screen Builder canvas. Existing controls on the Screen Builder canvas adjust positioning based on where you drag the control.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Configure the Textarea control. See Settings.
Validate that the control is configured correctly. See Validate Your Screen.
Below is a Textarea control in Preview mode.
After adding a control to a Screen page, you may move it to another location on that page such that it is above or below other controls placed on that page. A control cannot be moved to another Screen page.
Follow these steps to move a control to another location on that Screen page:
Place the control at the location on the page you want it. The other control(s) on the page automatically adjust position.
Copying a control also copies the current settings of that control. The copied control displays below other controls placed on that Screen page.
Follow these steps to copy a control:
Select the control to be copied.
As a best practice, after copying a control, change the Variable Name setting value for the copied control to its own unique variable value. Otherwise, in-progress Requests that use this Screen read from and send data to both controls.
Deleting a control also deletes configuration for that control. If you add another control, it will have default settings.
Follow these steps to delete a control from a Screen page:
Select the control to be deleted.
The Textarea control has the following panels that contain settings:
Click the control while in Design mode, and then click the Variable panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Textarea control in the Variable panel:
Use the Variable Name setting value in the following ways:
Reference this control's value in a different Screen Builder control. To do so, use mustache syntax and reference this control's Variable Name value in the target control. Example: {{ TextareaControl }}
.
Reference this value in Visibility Rule setting expressions.
See best practices when editing a Request variable name.
Follow these steps to add a validation rule to this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Select the rule that this control validates against.
Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.
Enter the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.
Follow these steps to edit a validation rule for this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Edit the parameter settings that this control uses to validate against. See Validation Rule Settings, and then locate the validation rule for its parameters.
Follow these steps to delete a validation rule for this control:
Access the Variable panel for this control while in Design mode, and then locate the Validation Rules setting.
Click Delete.
Click the control while in Design mode, and then click the Configuration panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Textarea control in the Configuration panel:
Click the control while in Design mode, and then click the Design panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Textarea control in the Design panel:
Click the control while in Design mode, and then click the Advanced panel that is on the right-side of the Screen Builder canvas.
Below are settings for the Textarea control in the Advanced panel:
Enter the default value this control displays. The default value can be assigned as a Request variable, text or JavaScript. When the Screen submits, the Request uses this control's default value unless the Request participant changes it. When using a Request variable in the Default Value setting, consider the following:
If the Request variable is empty, the control does not display any value by default.
When the Request variable is assigned a value for the first time, this value becomes the permanent default value of the control.
Any further changes to the Request variable do not affect the default value of the control.
The Default Value setting supports using Request variables in mustache syntax. For example, if the Default Value setting is {{ FirstName }} {{ LastName }}
from which a Request participant entered her first name and last name in separate controls (respectively) earlier in that Request, this control displays the contents of those controls by default during the Request.
There are two ways to enter the default value this control displays.
Note the following regarding how to use visibility rules:
To make this control hidden until another control contains a value, enter the Variable Name setting value of that control to this control's Visibility Rule setting.
See the following best practices regarding custom CSS in Screens:
Enter the string that provides a text alternative to this control for the following purposes:
Assistive technology, such as screen readers, read the Aria Label setting value.
This control has a visual indication of its purpose, such as a button that uses a graphic instead of text, but still needs to clarify that purpose for anyone who cannot access the visual indication.
Tab order determines the sequential navigation order to navigate a Screen's controls using a keyboard interface. Assistive technology users often use a keyboard for navigation.
Learn how to add, delete, or rename a Screen page.
Process Owners can create multi-page Screens. By default, a Screen contains one page that has the same name as the Screen.
Each page has its own name. Multiple pages in the same Screen can have identical page names.
Your user account or group membership must have the following permissions to add a new page to a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
Follow these steps to add a new page to a Screen:
In the Page Name setting, enter the name of the new page.
Click Save. The new page displays in the drop-down menu of pages for that Screen.
Access each page from the drop-down menu of pages for that Screen.
Your user account or group membership must have the following permissions to delete a new page to a Screen:
Screens: Edit Screens
Screens: View Screens
Deleting a page from a Screen cannot be undone.
Follow these steps to delete a page from a Screen:
Select the page from its the drop-down menu of pages for that Screen.
Your user account or group membership must have the following permissions to rename a new page to a Screen:
Screens: Edit Screens
Screens: View Screens
Follow these steps to rename a page on a Screen:
Select the page from its the drop-down menu of pages for that Screen.
Edit in the Page Name setting the name of the page.
Click Save.
Preview your Screen to evaluate and test how users would interact with your Screen and enter control data into the JSON data model during Requests.
Your user account or group membership must have the following permissions to preview a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
Follow these steps to use a Vocabulary during your Screen preview and testing:
Click the Preview button.
From the Select a vocabulary drop-down menu, select the Vocabulary from which to verify that your Screen complies with its JSON schema. Screen Builder loads the Vocabulary, and then evaluates if it is a valid JSON schema. One of the following messages display below the Select a vocabulary drop-down menu:
Valid JSON schema: If the JSON schema is valid, the following message displays: Data Valid for JSON Schema.
Invalid JSON schema: If the JSON schema is not valid, then the Vocabulary panel displays the errors that render the JSON schema invalid.
During your Screen evaluation, optionally do the following:
Optionally, enter mock Request data into your Screen to evaluate if your Screen processes expected Request data appropriately.
In the Data Input section, enter a JSON data model as your Screen's data input to evaluate how JSON data models for different Processes interact with the JSON data model for your Screen.
Follow these guidelines to enter mock Request data into your Screen to evaluate how your Screen processes expected Request data:
Click the Preview button.
During your Screen evaluation, optionally do the following:
Follow these guidelines to preview the JSON data model your Screen generates:
Click the Preview button.
During your Screen evaluation, optionally do the following:
Use these rules to describe how to validate your Screen controls.
Use validation rules in a control to constitute what is a valid value entered for that control.
If a control that has a Validation Rules setting but does not contain any value or properly structured validation rule, that control automatically passes validation.
If a control is hidden using Visibility Rules, any Validation Rules associated with that control are not evaluated upon submission of the Screen.
The following Screen Builder controls use the validation rules:
Follow these steps to add a validation rule to a Screen Builder control that provides validation:
Select the rule that this control validates against.
Click Save. Parameters for the selected rule display. Parameter settings display which ones are required to properly configure the rule.
Use the Accepted
validation rule to validate acknowledgement of this control. This is useful to validate "Terms of Service" acceptance.
Follow these steps to configure the parameter(s) for an Accepted
validation rule:
From the Select drop-down menu in the Validation Rules setting, select Accepted. The Accepted
validation rule has no parameters.
Use the After Date
validation rule to validate that the value entered into this control must be after (later than) a specified date. If the entered value is in datetime format, then the time format is ignored.
The value entered into this control must be in one of the following formats:
Date format: YYYY-MM-DD
. Example: "2020-07-01"
Datetime format: YYYY-MM-DD HH:MM:SS
. Example: "2020-07-01 14:25:15"
Follow these steps to configure the parameter(s) for an After Date
validation rule:
In the Date setting, enter the date in date format that this control's value must be after (later than). This is a required setting.
Use the After or Equal to Date
validation rule to validate that the value entered into this control must be the same or after (later than) a specified date. If the entered value is in datetime format, then the time format is ignored.
The value entered into this control must be in one of the following formats:
Date format: YYYY-MM-DD
. Example: "2020-07-01"
Datetime format: YYYY-MM-DD HH:MM:SS
. Example: "2020-07-01 14:25:15"
Follow these steps to configure the parameter(s) for an After or Equal to Date
validation rule:
In the Date setting, enter the date in date format that this control's value must be the same or after (later than). This is a required setting.
Use the Alpha
validation rule to validate that the value entered into this control must be contain only alphabetic characters.
Follow these steps to configure the parameter(s) for an Alpha
validation rule:
From the Select drop-down menu in the Validation Rules setting, select Alpha. The Alpha
validation rule has no parameters.
Use the Alpha-Numeric
validation rule to validate that the value entered into this control must contain only alphanumeric characters.
Follow these steps to configure the parameter(s) for an Alpha-Numeric
validation rule:
From the Select drop-down menu in the Validation Rules setting, select Alpha-Numeric. The Alpha-Numeric
validation rule has no parameters.
Use the Before Date
validation rule to validate that the value entered into this control must be before (earlier than) a specified date. If the entered value is in datetime format, then the time format is ignored.
The value entered into this control must be in one of the following formats:
Date format: YYYY-MM-DD
. Example: "2020-07-01"
Datetime format: YYYY-MM-DD HH:MM:SS
. Example: "2020-07-01 14:25:15"
Follow these steps to configure the parameter(s) for a Before Date
validation rule:
In the Date setting, enter the date in date format that this control's value must be before (earlier than). This is a required setting.
Use the Before or Equal to Date
validation rule to validate that the value entered into this control must be the same or before (earlier than) a specified date. If the entered value is in datetime format, then the time format is ignored.
The value entered into this control must be in one of the following formats:
Date format: YYYY-MM-DD
. Example: "2020-07-01"
Datetime format: YYYY-MM-DD HH:MM:SS
. Example: "2020-07-01 14:25:15"
Follow these steps to configure the parameter(s) for a Before or Equal to Date
validation rule:
In the Date setting, enter the date in date format that this control's value must be the same or before (earlier than). This is a required setting.
Use the Between Min & Max
validation rule to validate that the numerical value that this control contains is between the specified minimum value and a maximum value.
The Between Min & Max
validation rule evaluates the following:
integers
file sizes
The Between Min & Max
validation rule does not evaluate the number of characters in a text, but only the value of an entered number. Use one or both of the following to validate the number of characters in a text:
Furthermore, the Between Min & Max
validation rule does not evaluate calendar dates, such as when an entered value in that control is between two dates. Use any of the following to validate date-related values:
Follow these steps to configure the parameter(s) for a Between Min & Max
validation rule:
In the Min parameter setting, enter the numeric value that this control's value must be equal to or no lower than. This is a required setting.
In the Max parameter setting, enter the numeric value that this control's value must be equal to or no greater than. This is a required setting.
Use the Date
validation rule to validate that the value entered into this control is in date or datetime format.
One of the following formats validates that the entered value is a date:
Date format: YYYY-MM-DD
. Example: "2020-07-01"
Datetime format: YYYY-MM-DD HH:MM:SS
. Example: "2020-07-01 14:25:15"
Follow these steps to configure the parameter(s) for an Date
validation rule:
From the Select drop-down menu in the Validation Rules setting, select Date. The Date
validation rule has no parameters.
Use the Email
validation rule to validate that the value entered into this control is formatted as an email address.
Follow these steps to configure the parameter(s) for an Email
validation rule:
From the Select drop-down menu in the Validation Rules setting, select Email. The EMail
validation rule has no parameters.
Follow these steps to configure the parameter(s) for an In
validation rule:
In the Values parameter setting, enter the value to evaluate if it exactly matches the control's selected or entered value. This is a required setting.
Format a list in the Values parameter setting by separating the values with commas only, no spaces:
value1,value2,value3
In
Validation Rule ExamplesThe Select List control contains the following settings:
This control is configured to return the value of the property name
. Therefore, the doctors' names display as options in the Select List control.
This control has an In
validation rule to evaluate if Mindy Smith
is included in that control's selection.
If the Request participant selects the Mindy Smith option from that Select List control, then that control passes validation.
A Line Input control under evaluation has the following validation rule:
The validation rule is evaluated as follows:
Use the Max Length
validation rule to validate that the value entered into this control is no greater than a specified length.
The Max Length
validation rule evaluates the following:
a maximum number of characters in a string
a maximum integer value
a maximum file size
The Max Length
validation rule does not evaluate calendar dates, such as when an entered value in that control is no later than a particular date.
Follow these steps to configure the parameter(s) for a Max Length
validation rule:
In the Max Input parameter setting, enter the numeric value that this control's value must be equal to or no greater than. This is a required setting.
Use the Min Length
validation rule to validate that the value entered into this control is no less than a specified length.
The Min Length
validation rule evaluates the following:
a minimum number of characters in a string
a minimum integer value
a maximum file size
The Min Length
validation rule does not evaluate calendar dates, such as when an entered value in that control is no earlier than a particular date.
Follow these steps to configure the parameter(s) for a Min Length
validation rule:
In the Min Input parameter setting, enter the numeric value that this control's value must be equal to or no less than. This is a required setting.
Follow these steps to configure the parameter(s) for a Not In
validation rule:
In the Values parameter setting, enter the value to evaluate if it is not within the control's selected or entered value. This is a required setting.
Format a list in the Values parameter setting by separating the values with commas only, no spaces:
value1,value2,value3
Not In
Validation Rule ExamplesThe Select List control contains the following settings:
This control is configured to return the value of the property name
. Therefore, the doctors' names display as options in the Select List control.
This control is configured to allow multiple selections.
This control has a Not In
validation rule to evaluate if Mindy Smith
is not included in that control's selection.
If the Request participant selects multiple options from that Select List control, but the Mindy Smith option is not among them, then that control passes validation.
A Line Input control under evaluation has the following Validation Rule:
The Validation Rule is evaluated as follows:
Use the Regex
validation rule to validate that this control's value contains content as determined by a specified regular expression. A regular expression, abbreviated as regex, is a sequence of letters and symbols that defines a logical search pattern from which to search this control's content to validate that strings meet the defined pattern. This validation rule is useful to parse the contents of a control's value even if that control's Request variable contains programming code such as HTML or JSON.
Follow these steps to configure the parameter(s) for a Regex
validation rule:
In the Regex Pattern setting, enter the regular expression from which to validate this control's value contains that content. This is a required setting.
Use the Required
validation rule to validate that this control has a value and is not empty.
A control constitutes as having no value in the following circumstances:
The value is null
.
The value is an empty string that contains no characters.
The value is an empty JSON array or empty JSON object.
The value is an uploaded file with no path.
Follow these steps to configure the parameter(s) for a Required
validation rule:
From the Select drop-down menu in the Validation Rules setting, select Required. The Required
validation rule has no parameters.
A control constitutes as having no value in the following circumstances:
The value is null
.
The value is an empty string that contains no characters.
The value is an empty JSON array or empty JSON object.
The value is an uploaded file with no path.
Follow these steps to configure the parameter(s) for a Required If
validation rule:
In the Variable Name parameter setting, enter the Variable Name setting value to monitor for its value. This is a required setting.
In the Variable Value parameter setting, enter the value that must be entered into that control to make this control required. This is a required setting.
Required If
Validation Rule ExamplesThis example demonstrates depending controls: one control depends on another to be required. This example also demonstrates how a control depends on the specific value of another.
See the following .json
files below for this example:
List of countries in JSON format: Countries for Select List Control "Required If" Validation Example
List of US states and territories in JSON format: US States for Select List Control "Required If" Validation Example
Follow these steps to implement this example:
Download the file below Countries for Select List Control "Required If" Validation Example.
Review the JSON data. Notice that each JSON object contains the following:
content: A property called content
represents the label for each option (in this example, a country name). The label for each Select List option may contain any string as long as it is in the content
property of each JSON object.
value: A property called value
that contains a numeric value that corresponds with each label option. The value
property may contain any string as long as it is in the value
property of each JSON object. Notice that the JSON object that contains the content
property value of United States
has a value property of 232
. In this example, if the option corresponding with the 232
value is selected, then the second Select List control is required.
Copy this file's JSON data.
Paste it into the JSON Data setting.
Add a second Select List control to the same Screen page, and then configure its settings. This control displays the list of US states and territories as its options, and represents the required control if a specific setting in the first Select List control contains a specific value.
Download the file below US States for Select List Control "Required If" Validation Example.
Copy this file's JSON data.
Paste it into the JSON Data setting.
In the Variable Name setting of the Required If
validation rule, enter the Variable Name setting value for the first Select List control that displays the list of countries as its options.
In the Variable Value setting of the Required If
validation rule, enter 232
, which is the value
property value that corresponds with the content
property value United States
.
This example demonstrates depending controls: one control depends on another to be required. This example also demonstrates how a control depends on the specific value of another.
Follow these steps to implement this example:
No:
Value: 0
Content: No, I do not have a felony conviction within the past 10 years.
Yes:
Value: 1
Content: Yes, I have a felony conviction within the past 10 years.
The Value settings represent the values the Textarea control evaluates to determine if that control is required; these settings may contain any value, not necessarily Boolean values. The Content settings represent the label for each option. In this example, if the option corresponding with the 1
value is selected, then the Textarea control is required.
In the Variable Name setting of the Required If
validation rule, enter the Variable Name setting value for the Select List control.
In the Variable Value setting of the Required If
validation rule, enter 1
.
A control constitutes as having no value in the following circumstances:
The value is null
.
The value is an empty string that contains no characters.
The value is an empty JSON array or empty JSON object.
The value is an uploaded file with no path.
Follow these steps to configure the parameter(s) for a Required Unless
validation rule:
In the Variable Name parameter setting, enter the Variable Name setting value to monitor for its value. This is a required setting.
In the Variable Value parameter setting, enter the value that must be entered into that control to exempt this control from being required. This is a required setting.
Required Unless
Validation Rule ExamplesThis example demonstrates depending controls: one control depends on another to be required. This example also demonstrates how a control depends on the specific value of another.
See the following .json
file below for this example: US States for Select List Control "Required Unless" Validation Example.
Follow these steps to implement this example:
Download the file below US States for Select List Control "Required Unless" Validation Example.
Review the JSON data. Notice that each JSON object contains the following:
content: A property called content
represents the label for each option (in this example, a US state or territory). The label for each Select List option may contain any string as long as it is in the content
property of each JSON object.
value: A property called value
that contains a numeric value that corresponds with each label option. The value
property may contain any string as long as it is in the value
property of each JSON object. Notice that the JSON object that contains the content
property value of California
has a value property of 6
. In this example, if the option corresponding with the 6
value is selected, then the Line Input control is not required.
Copy this file's JSON data.
Paste it into the JSON Data setting.
Add a Line Input control to the same Screen page, and then configure its settings. The Request participant enters into this control required information unless a specific setting in the Select List control contains a specific value.
In the Variable Name setting of the Required Unless
validation rule, enter the Variable Name setting value for the Select List control that displays the list of US states and territories as its options.
In the Variable Value setting of the Required Unless
validation rule, enter 6
, which is the value
property value that corresponds with the content
property value California
.
This example demonstrates depending controls: one control depends on another to be required. This example also demonstrates how a control depends on the specific value of another.
Follow these steps to implement this example:
Option 1:
Value: 1
Content: 18 years old or younger
Option 2:
Value: 2
Content: 19 to 35 years old
Option 3:
Value: 3
Content: 36 to 64 years old
Option 4:
Value: 4
Content: 65 years old or older
The Value settings represent the values the Textarea control evaluates to determine if that control is required; these settings may contain any value, not necessarily Boolean values. The Content settings represent the label for each option. In this example, if the option corresponding with the 4
value is selected, then the Textarea control is not required.
In the Variable Name setting of the Required Unless
validation rule, enter the Variable Name setting value for the Select List control.
In the Variable Value setting of the Required Unless
validation rule, enter 4
.
Use the Same
validation rule to validate that the value entered into this control matches the value of a specified control.
Follow these steps to configure the parameter(s) for a Same
validation rule:
In the Variable Name parameter setting, enter the Variable Name setting value to evaluate if the control under evaluation matches its value. This is a required setting.
Use the URL
validation rule to validate that the value entered into this control is formatted as a Uniform Resource Locator (URL).
Follow these steps to configure the parameter(s) for a URL
validation rule:
From the Select drop-down menu in the Validation Rules setting, select URL. The URL
validation rule has no parameters.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Submit Button iconin the panel to the left of the Screen Builder canvas.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during Requests. Ensure that the Variable Name setting value is a unique name from other controls in this Screen and contains at least one letter. This is a required setting.
Reference this control by its Variable Name setting's value. The Data Preview panel in Preview mode corresponds the Submit Button control's Variable Name value. In the example below, SubmitButtonControl
is the Variable Name setting's value when the button is clicked.
Edit the default label that displays for this control if necessary. New Submit is the default value.
Enter any alphanumeric value that represents data when the Request participant selects the Submit Button control. This value can be evaluated in a Visibility Rule setting expression or in a Sequence Flow element's condition(s) to trigger.
Do Not Submit, Set Value: Sets this control's value as specified from the Value setting, but does not submit the Screen.
Configure a tooltip that displays when hovering over the Submit Button control.
Link: White-colored background with blue-colored Label text.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the Label setting value. For example, if a Submit Button control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Saved Search Chart iconin the panel to the left of the Screen Builder canvas.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Select the Saved Search chart to display in the Screen. If you are not that Saved Search's owner nor have not been shared the Saved Search associated with the chart, that chart does not display in the Chart setting.
Enter an additional ProcessMaker Query Language (PMQL) query from which to filter Saved Search results to display in the chart.
Enable the Title toggle key to display the Saved Search chart's title above the chart. The Title toggle key is enabled by default.
Enable the Border toggle key to display a border around the Saved Search chart. The Border toggle key is enabled by default.
Enable the Enable Link toggle key to display theicon that, when clicked, displays the Saved Search from which the chart visualizes data in a new browser window. The Enable Link toggle key is disabled by default.
Select the size of the Saved Search chart.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Signature iconin the panel to the left of the Screen Builder canvas.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Reference this control by its Variable Name setting's value. The Data Preview panel in Preview mode corresponds the Signature control's textual content with that Textarea control's Variable Name value. In the example below, SignatureControl
is the Variable Name setting's value.
Set the vertical spacing of the Signature control's pad: the space into which the signature is entered.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
Click the imagefor the option to be removed.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Select List iconin the panel to the left of the Screen Builder canvas.
Place into the Screen Builder canvas where you want the control to display on the Screen.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, and then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during Requests. Ensure that the Variable Name setting value is a unique name from other controls in this Screen and contains at least one letter. This is a required setting.
View the selection made in this control by its Variable Name setting's value. The Data Preview panel in Preview mode corresponds the option(s) the Request participant selects in the Select List control with that Select List control's Variable Name value. The Variable Name setting contains the selected option(s) as an array. In the example below, SelectListControl
is the Variable Name setting's value.
Consider the following example. A Select List control with Variable Name setting value account
displays a list of accounts available at your bank.
When a user makes a selection, you want to display the selected account in a Line Input control on this Screen. Use the following best practice to reference the value of the Select List control.
Insert a Line Input control and set its Variable Name value. This example uses the Variable Name value AccountName
.
Edit the default label that displays for this control if necessary. New Select List is the default value.
Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: No validation rule(s). See Validation Rules for "Validation" Control Settings.
Click the Add Rule button. The Select drop-down menu displays.
Click the Edit iconfor the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays.
Click the Delete iconfor the validation rule to delete. A message displays to confirm deletion of the validation rule.
Enter the placeholder text that displays in this control when no value has been provided. This setting has no default value.
Enter text that provides additional guidance on this control's use. This setting has no default value.
From the Data Source drop-down menu, select Provide Values if this setting is not selected. This is the default setting.
Ensure that the Options list label displays. If the JSON Data option displays, click the Edit as Option List option.
Click the iconbeside the Options list label. The Add Option screen displays.
Click Save. The option displays below the Options list label.
Access the Data Source panel for this control while in Design mode, and then ensure that the Data Source setting uses the Provide Values option.
Ensure that the Options list label displays. If the JSON Data option displays, click the Edit as Option List option.
Click theicon for an option to edit its settings. The Edit Option screen displays.
Access the Data Source panel for this control while in Design mode, and then ensure that the Data Source setting uses the Provide Values option.
Ensure that the Options list label displays. If the JSON Data option displays, click the Edit as Option List option.
Click theicon for the option to be deleted from this control. A message displays to confirm deletion of the option.
Access the Data Source panel for this control while in Design mode, and then ensure that the Data Source setting uses the Provide Values option.
Ensure that the Options list label displays. If the JSON Data option displays, click the Edit as Option List option.
Drag theicon for each option up or down to sort the order they display in this control as necessary.
Access the Data Source panel for this control while in Design mode, and then ensure that the Data Source setting uses the Provide Values option.
Click the Allow multiple selections setting to allow multiple options to be selected from this control. Otherwise, only one option can be selected.
Radio/Checkbox Group: Select the Radio/Checkbox Group option to display the control as a group of checkboxes.
From the Data Source drop-down menu, select Provide Values if this setting is not selected. This is the default setting.
Click the Edit as JSON option below the Options list label. If the JSON Data setting displays, skip this step.
Click the iconbeside the JSON Data option. The Script Config Editor displays.
Click Close or the Close icon. The control options are saved.
Access the Data Source panel for this control while in Design mode, and then ensure that the Data Source setting uses the Provide Values option.
Click the Allow multiple selections setting to allow multiple options to be selected from this control. Otherwise, only one option can be selected.
Radio/Checkbox Group: Select the Radio/Checkbox Group option to display the control as a group of checkboxes.
From the Data Source drop-down menu, select Request Data.
In the Options Variable setting, enter from which Request variable, based on its Variable Name setting value, to use as options for this control. The Request variable from which to use as options must be an array. The options in the Select List control display in the same order as the Request variable lists items in its array. Optionally, use mustache syntax to indicate the Request variable name, especially if each option in this control derives from combining multiple properties within an array where each of its items contains one or more objects. response is the default setting. See Dependent Field Design Example Using Select List Controls.
Optionally, use mustache syntax to indicate the JSON object key name from within the JSON array. content is the default value.
Radio/Checkbox Group: Select the Radio/Checkbox Group option to display the control as a group of checkboxes.
Select the Allow multiple selections option to allow multiple options to be selected from this control. Otherwise, only one option can be selected.
Object: Select the Object option to indicate that the entire JSON object within each item of the array displays as each option in this control.
If the Single Value option from the Type of Value Returned setting is selected, the Variable Data Property setting displays. In the Variable Data Property setting, enter the JSON object key name from within the JSON array containing the JSON response that this control stores in that Request's data when this Screen submits. To use all items in the JSON array, do not enter a value into the Variable Data Property setting. Use JSON dot notation as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. Optionally, use mustache syntax to indicate the JSON key name from within the JSON array. value is the default value. See Dependent Field Design Example Using Select List Controls.
From the Data Source drop-down menu, select Data Connector.
In the Options Variable setting, enter the name of the JSON array containing the API's JSON response from which to reference its objects as options that display in this control after the Data Connector's Resource interacts with the API endpoint. The name of the JSON array is called response
by default. Use JSON dot notation as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. response is the default value.
Radio/Checkbox Group: Select the Radio/Checkbox Group option to display the control as a group of checkboxes.
Select the Allow multiple selections option to allow multiple selections from this control. Otherwise, only one option can be selected.
Object: Select the Object option to indicate that the entire JSON object within each item of the array displays as each option in this control.
If the Single Value option from the Type of Value Returned setting is selected, the Value setting displays. In the Value setting, enter the JSON object key name from within the JSON array containing the JSON response that this control stores in that Request's data when this Screen submits. To use all items in the JSON array, do not enter a value into the Value setting. Use JSON dot notation as necessary if the relevant JSON array containing the object key name is embedded in other JSON objects and/or arrays. Optionally, use mustache syntax to indicate the JSON key name from within the JSON array. value is the default setting. See Dependent Field Design Example Using Select List Controls.
content is the default value.
From the Data Connector drop-down menu, select from which Data Connector to reference as a data source. If a Data Connector does not exist, this setting has no options.
From the End Point drop-down menu, select which Resource to reference from the selected Data Connector. A Resource is a Data Connector asset with which to interact with a data source, also called an End Point. These Resources are configured from the Data Connector itself. Depending on the Data Connector selected from the Data Connector Name drop-down menu, these Resources may reference Application Program Interface (API) endpoints, Collection records, or other data source endpoints.
In the PMQL setting, optionally enter a PMQL expression to filter which data in the JSON data array to display as options in this control based on which JSON objects in that array meet the PMQL expression's criteria.
From the Data Source drop-down menu, select Collection.
From the Collection drop-down menu, select the name of the Collection from which to retrieve data.
From the Label drop-down menu, select the name of the Collection column that contains the data to be displayed as options in the Select List control.
From the Value drop-down menu, select the name of the Collection column that contains the data to be saved into Request data when a user makes a selection.
The Label and Value drop-down menus can have the same or different Collection columns selected. Consider an example of a Collection with columns City Name
and Zip Code
. The Select List control can be configured in the following ways:
In the PMQL setting, optionally enter a PMQL expression to filter the data being retrieved from the Collection. If a filter criteria is specified here, the Select List control dynamically filters in real-time based on the specified PMQL expression.
Select the Ignore duplicates in list option to display repeating data only once in the Select List control.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Enter the default value as text or a Request variable in mustache syntax.
Enter the default value as JavaScript, especially if a Calculated Property might change this default value setting. Ensure to use the this.
JavaScript keyword preceding the Screen control reference. Example: this.FullName
when FullName
is the Variable Value setting value for the control to set its default value.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the Label setting value. For example, if a Submit Button control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
Create a new Screen or click the Edit iconto edit the selected Screen. The Screen is in Design mode.
Locate the Textarea iconin the panel to the left of the Screen Builder canvas.
Place your cursor anywhere on the control not displaying the Duplicate Controlor Delete Controlbuttons.
Hold your cursor, then drag the control above or below other controls on that Screen page. Screen Builder previews where the control would display on the page based on how you position the control above or below other controls. If the control cannot be placed in a location because your cursor is above an existing control or too far to the left or right of the page, theicon displays in the preview.
Click the Duplicate Control button. The control copies with its current settings, and then displays below other controls placed on that page.
Click the Delete button. The control deletes. Other controls on that Screen page adjust their locations automatically.
Edit the default Variable Name setting value for this control if necessary. The Variable Name setting value represents data in this control during Requests. Ensure that the Variable Name setting value is a unique name from other controls in this Screen and contains at least one letter. This is a required setting.
Reference this control by its Variable Name setting's value. The Data Preview panel in Preview mode corresponds the Textarea control's textual content with that Textarea control's Variable Name value. In the example below, TextareaControl
is the Variable Name setting's value.
Edit the default label that displays for this control if necessary. New Textarea is the default value.
Enter the validation rule(s) the Request participant must comply with to properly enter a valid value into this control. This setting has no default value. If there are no configured validation rules the following message displays: No validation rule(s). See Validation Rules for "Validation" Control Settings.
Click the Add Rule button. The Select drop-down menu displays.
Click the Edit iconfor the validation rule to edit if that rule can be edited. Validation rules that do not have parameters cannot be edited. The parameter settings for that validation rule displays.
Click the Delete iconfor the validation rule to delete. A message displays to confirm deletion of the validation rule.
Select to indicate that this control cannot be edited. This option is not selected by default.
Enter the placeholder text that displays in this control when no value has been provided. This setting has no default value.
Enter text that provides additional guidance on this control's use. This setting has no default value.
Select the Rich Text checkbox to display the What-You-See-Is-What-You-Get (WYSIWYG) rich text editor to allow the Request participant can enter rich text. This option is not selected by default.
Enter the number of rows to provide for input. 2 is the default value.
Select the text color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Select the background color that displays for this control. Optionally, click the Clear Color Selection option to remove the selected color.
Enter the default value as text or as a Request variable in mustache syntax.
Enter the default value as JavaScript, especially if a Calculated Property might change this default value setting. Ensure to use the this.
JavaScript keyword preceding the Screen control reference. Example: this.FullName
when FullName
is the Variable Value setting value for the control to set its default value.
Specify an expression that indicates the condition(s) under which this control displays. See Expression Syntax Components. If this setting does not have an expression, then this control displays by default.
Enter the value to represent this control in custom CSS syntax when in Custom CSS mode. As a best practice, use the same CSS Selector Name value on different controls of the same type to apply the same custom CSS style to all those controls.
The Aria Label setting value replaces the Label setting value. For example, if a Submit Button control has both a Label setting value and an Aria Label setting value, assistive technology only uses the Aria Label setting value.
Enter the number for the sequential keyboard navigation order that this control takes focus amongst other controls in this Screen.
See the permissions or ask your Administrator for assistance.
or the Screen in which to add a new page. The Screen is in .
Click thebutton. The Add New Page screen displays.
See the permissions or ask your Administrator for assistance.
the Screen in which to delete a page. The Screen is in .
Click thebutton. The page is deleted.
See the permissions or ask your Administrator for assistance.
or the Screen in which to add a new page. The Screen is in .
Click thebutton. The Edit Page Title screen displays.
To allow to be used among any , they are represented in format. Processes are also represented as JSON data models that pass to defined in the . Preview, evaluate, and test how data in your Screen is passed to JSON data models before using that Screen in Processes.
See the permissions or ask your Administrator for assistance.
To use a from which to preview your Screen, the must be installed.
Optionally, use a Vocabulary from which to preview your Screen to ensure that it complies with any regulatory compliance that using this Screen must comply. A Vocabulary is a JSON schema. The JSON schema describes the data objects, types, and structure that you want in both a machine- and human-readable format. The Vocabulary from which to preview your Screen must already exist.
the Screen. The Screen is in .
Expand the Vocabulary panel that is on the right-side of the Screen Builder canvas if it is not already.
Enter or review data in the Screen controls as you would for a during a . Evaluate if your Screen processes the Vocabulary's JSON schema appropriately.
the Screen. The Screen is in .
Expand the Data Input panel that is on the right-side of the Screen Builder canvas if it is not already.
Enter a JSON data model into the Data Input panel. This JSON data model may come from a Process's data or another Screen. As you enter a JSON data model, the Screen Validation indicator displays if your JSON schema has any errors that prevents validation.
Enter or review data in the Screen controls as you would for a during a . Evaluate if your Screen processes the mock Request data appropriately.
the Screen. The Screen is in .
Expand the Data Preview panel that is on the right-side of the Screen Builder canvas if it is not already.
Enter or review data in the Screen controls as you would for a during a . When data is entered into each control, the Data Preview panel adds that control value into a JSON data model using the Variable Name setting value of that control. During an in-progress Request, this JSON data model would incorporate into that Request's data model.
Evaluate if your Screen generates data appropriately. To denote that the content of a control is of String
data type, those Request variable values display with one backslash (\
) preceding and following single- and double-quotation marks (`
and "
, respectively) that may be within the string of that Request variable value so as to indicate that these punctuation marks are interpreted as part of the literal string instead of functioning as punctuation. For example, a Line Input control with a text value of ""Louis Canera" has been employed at "Company" from '2015' until '2023'"
displays in the preview as "\"Louis Canera\" has been employed at \"Company\" from \'2015\' until \'2023\'"
.
Calculated properties also display in the Data Preview panel as part of the JSON data model if you submit the Screen by clicking the control in -type Screens. See .
control
control
control
control
control
Access the Variable panel for the control while in mode, and then locate the Validation Rules setting.
Click the Add Rule button. The Select drop-down menu displays.
Enter the parameter settings that this control uses to validate against. See , and then locate the validation rule for its parameters.
If you want a validation to fail for undefined or ''
, use the rule.
.
.
From the Select drop-down menu in the Validation Rules setting, select After Date. The Date setting displays.
.
From the Select drop-down menu in the Validation Rules setting, select After or Equal to Date. The Date setting displays.
.
.
.
From the Select drop-down menu in the Validation Rules setting, select Before Date. The Date setting displays.
.
From the Select drop-down menu in the Validation Rules setting, select Before or Equal to Date. The Date setting displays.
.
From the Select drop-down menu in the Validation Rules setting, select Between Min & Max. The Min and Max parameter settings display.
.
.
Use the In
validation rule to validate that the value entered into this control exactly matches the given parameter setting. The validation rule evaluates the entire value entered in the control and considers case-sensitivity and empty spaces. The control's scope of evaluation may be within an array or a string. See .
.
From the Select drop-down menu in the Validation Rules setting, select In. The Values parameter setting displays.
The following JSON Request data represents the JSON array for a control under evaluation.
Entered Value | Validation Rule Evaluation |
---|
.
From the Select drop-down menu in the Validation Rules setting, select Max Length. The Max Input parameter setting displays.
.
From the Select drop-down menu in the Validation Rules setting, select Min Length. The Min Input parameter setting displays.
Use the Not In
validation rule to validate that the value entered into this control does not match the given parameter setting. The validation rule evaluates the entire value entered in the control and considers case-sensitivity and empty spaces. The control's scope of evaluation may be within an array or a string. See .
.
From the Select drop-down menu in the Validation Rules setting, select Not In. The Values parameter setting displays.
The following JSON Request data represents the JSON array for a control under evaluation.
Entered Value | Validation Rule evaluation |
---|
Need a primer on regular expression syntax? See this , and then use to learn, build, and test your regular expressions.
.
From the Select drop-down menu in the Validation Rules setting, select Regex. The Regex Pattern setting displays.
.
Use the Required If
validation rule to validate that this control has a value and is not empty if another control in that page contains a specific value. If the control being monitored contains a specific value, then the control under evaluation is required. See .
The Required If
validation rule is the inverse of the .
.
From the Select drop-down menu in the Validation Rules setting, select Required If. The Variable Name and Variable Value parameter settings display.
A participant enters information into a for a job application. If that Task assignee selects from a control in which country that person lives. If the Task assignee selects the option United States (US), then another Select List control becomes required to select from which US state that person lives.
Add a , and then . Make note of its Variable Name setting value you set for that control. This control displays the list of countries as its options.
. In doing so, edit options as JSON:
. In doing so, edit options as JSON:
Add a Required If
to the second Select List control that displays the list of US states and territories.
to the same Screen page, and then .
A participant enters information into a for a job application. If that Task assignee selects the Yes option from a control labeled Have you been convicted of a felony within the past 10 years?, a control labeled Describe your felony conviction. becomes required. The Task assignee cannot submit the form without describing the felony conviction(s).
Add a , and then . Make note of its Variable Name setting value you set for that control.
. In doing so, provide the following values:
to the same Screen page, and then .
Add a Required If
to the Textarea control.
to the same Screen page, and then .
Use the Required Unless
validation rule to validate that this control has a value and is not empty unless another control in that page contains a specific value. If the control being monitored for its value has a specific value, then the control under evaluation is not required. See .
The Required Unless
validation rule is the inverse of the .
.
From the Select drop-down menu in the Validation Rules setting, select Required Unless. The Variable Name and Variable Value parameter settings display.
A participant enters information for a regarding United States (US) federal taxes. If that Task assignee selects from a control that person lives in California, then that person is exempt from a federal tax credit. If the Task assignee selects the option California, then a control becomes required to enter tax information. If any other option is selected, then the Line Input control is not required.
Add a , and then . Make note of its Variable Name setting value you set for that control. This control displays the list of US states and territories as its options.
. In doing so, edit options as JSON:
Add a Required Unless
to the Line Input control control.
to the same Screen page, and then .
A participant enters information for a that solicits viewer feedback for a streaming video. The organization soliciting viewer feedback is particularly interested in viewer feedback for a particular demographic: if that viewer indicates that she or he is in a specific age group, then that person does is not required to provide feedback on a particular question.
If that Task assignee selects from a control the option 65 years old or older, then a control is not required. If any other option is selected, then the Textarea control is required.
Add a , and then . Make note of its Variable Name setting value you set for that control.
. In doing so, provide the following values that represent demographic age groups:
to the same Screen page, and then .
Add a Required Unless
to the Textarea control.
to the same Screen page, and then .
.
From the Select drop-down menu in the Validation Rules setting, select Same. The Values parameter setting displays.
.
NA | True |
North America | True |
NA,North America | False |
This is North America | False |
Niagara Falls, NA | False |
NA | False |
North America | False |
NA,North America | True |
This is North America | True |
Niagara Falls, NA | True |
View the Calculated Properties for a Screen.
Your user account or group membership must have the following permissions to view the Calculated Properties for a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to view the Calculated Properties for a Screen:
Open the Screen in which to view its Calculated Properties. The Screen is in Design mode.
The following information displays about each Calculated Property:
Property name: The Property Name column displays the name of the Calculated Property.
Description: The Description column displays the description of the Calculated Property.
Understand how to use Calculated Properties in your Screens.
Use Calculated Properties to easily design formulas that perform calculations and solve problems within the context of a Screen. The output of a Calculated Property is automatically generated, read-only, and is available immediately in the Request data model. Advanced JavaScript developers can use Calculated Properties to do more advanced data manipulations.
Use Calculated Properties to add more context to your Screen display. A Request should never trust any data that originates from the client side, and trusted calculations should always be performed within a Request in a Script Task element.
Calculated Properties have the following attributes:
Calculated Properties can only be used within and only affect the Screen to which the Calculated Property is added.
Calculated Properties are generated values that cannot be edited after calculation.
The name of a Calculated Property is case sensitive. For example, netCost
and NetCost
are two distinct names for Calculated Properties.
Below are a few uses for Calculated Properties that can be calculated mathematically or through JavaScript:
Perform simple mathematics. Example: 1+1
Calculate the final cost of a purchase based on a sales tax. Example: $60
(item cost) x .075
(sales tax)
Calculate the minimum credit card payment. Example: $1000
(amount owed) x .03
(interest rate)
Reference the Screen control values for a Property using their Variable Name setting values. For example, to determine the cost for a number of items in a Screen for a purchase request form that uses a Line Input control with a Variable Name setting of units
to indicate how many items to purchase, and price
is the amount per unit, use the following calculation in a Property:
units * price
Calculated Properties display as the second key-value pair of the Screen's JSON data model from the Data Preview panel when previewing that Screen.
Follow best practices when using Calculated Properties.
Follow best practice guidelines and considerations when using Calculated Properties.
Follow these best practices and considerations when using Calculated Properties in Screens:
Calculated Properties are not designed to modify the current Screen control value(s). Calculated Properties read the value(s) from a specified Screen control via its Variable Name setting to calculate a result.
When designing a Calculated Properties, do not use the value from a Screen control which, in turn, calculates that property. Such design is circularly referencing the control from which to calculate its value.
Calculated Properties are not designed for a user to modify a Calculated Property via a Screen control.
When referencing a Calculated Property in a Screen, use its name in the exact case as defined since a Calculated Property's name is case sensitive. For example, netCost
and NetCost
are two distinct names for Calculated Properties.
Calculated Properties are not designed to introduce additional JavaScript functionality: doing so can cause instability in that Screen. ProcessMaker Platform does not support Screens that have additional JavaScript functionality within them.
Do not use third-party libraries within Calculated Properties such as jQuery or moment.js, as these libraries may be updated in and/or removed in ProcessMaker Platform. ProcessMaker Platform does not support Screens that use third-party libraries within them.
Do not reference one Calculated Property within another, such as referencing this.myCalcProp
in a Calculated Property named myCalcProp
: doing so causes a circular reference which degrades the performance of the Screen or may cause the Screen to stop functioning entirely.
If using a Calculated Property in a nested Screen that requires the value from its hosting Screen, then do not use the same Request variable in the nested Screen’s Calculated Property as that used in the hosting Screen.
Calculated Properties are generated values that cannot be edited after calculation.
Delete a Calculated Property from a Screen.
Your user account or group membership must have the following permissions to delete a Calculated Property from a Screen:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Deleting a Calculated Property from a Screen cannot be undone.
Follow these steps to delete a Calculated Property from a Screen:
Open the Screen in which to delete a Calculated Property. The Screen is in Design mode.
Edit a Calculated Property for a Screen.
Your user account or group membership must have the following permissions to edit a Calculated Property for a Screen:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Avoid performance issues and follow best-use guidelines by following best practices.
Follow these steps to edit a Calculated Property for a Screen:
Open the Screen in which to add a Calculated Property. The Screen is in Design mode.
Edit the following settings about the Calculated Property as necessary:
In the Property Name setting, edit the name of the Calculated Property. This Calculated Property name displays both in the Calculated Properties screen and in the JSON data model when previewing the Screen. Calculated Properties are case-sensitive. See Calculated Property Best Practices. This is a required setting.
In the Description setting, edit the description of the Calculated Property. This is a required setting.
Above the Formula setting, select one of the following ways to determine how the Calculated Property determines its value:
Screen control value:
Reference a Screen control's value by referencing that control's Variable Name setting to use it in a mathematical calculation. Example to calculate the total cost of a purchase: NetCost
+ ( NetCost
* (SalesTaxRate
/100)) when NetCost
and SalesTaxRate
are the Variable Name setting values for the two controls storing the net cost for a purchase prior to sales tax and the local sales tax rate, respectively.
Magic Variable value:
Reference a Magic Variable's value. ProcessMaker Platform uses a set of Magic Variables that become part of the JSON data model for all Requests. ProcessMaker Platform uses these Magic Variables to store user, Process, and Request related data for all Requests. During an in-progress Request, these Magic Variables are updated. An underscore (_
) character precedes all Magic Variables in the JSON data model. Example to get the ID for the user completing the current Task in that Request: _user.id
.
Follow these guidelines to reference Screen control or Magic Variable values:
Screen control value:
Reference a Screen control's value by referencing that control's Variable Value setting. Example: return this.FullName
when FullName
is the Variable Value setting value for the control to reference its value when the Calculated Property runs.
Magic Variable value:
Reference a Magic Variable's value as described above for mathematical calculations. Reference the Magic Variable after the this.
keyword when using JavaScript as the input method. Example: return this._user.fullname
to reference the user's full name from the in-progress Request. See Magic Variable Descriptions.
In the Formula setting, edit the mathematical calculation/JavaScript that determines the Calculated Property value. This is a required setting.
Click Save. The Property displays in the Calculated Properties screen. The following message displays: Property Saved.
Ensure to save your Screen. The Calculated Property is not edited until you save it. Doing so will save your work if your session expires.
Add a Calculated Property to a Screen.
Your user account or group membership must have the following permissions to add a Calculated Property for a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add a Calculated Property for a Screen:
Open the Screen in which to add a Calculated Property. The Screen is in Design mode.
View the Calculated Properties for that Screen. The Calculated Properties screen displays all Calculated Properties configured for this Screen. If no Calculated Properties have been configured for this Screen, No Data Available displays.
Click the +Property button. The Calculated Properties screen displays settings to configure a Property.
In the Property Name setting, enter the name of the Calculated Property. This Calculated Property name displays both in the Calculated Properties screen and in the JSON data model when previewing the Screen. Calculated Properties are case-sensitive. See Calculated Property Best Practices. This is a required setting.
In the Description setting, enter the description of the Calculated Property. This is a required setting.
Above the Formula setting, select one of the following ways to determine how the Calculated Property determines its value:
Follow these guidelines to reference Screen control or Magic Variable values:
Screen control value:
Reference a Screen control's value by referencing that control's Variable Value setting. Example: return this.FullName
when FullName
is the Variable Value setting value for the control to reference its value when the Calculated Property runs.
Magic Variable value:
Reference a Magic Variable's value. ProcessMaker Platform uses a set of Magic Variables that become part of the JSON data model for all Requests. ProcessMaker Platform uses these Magic Variables to store user, Process, and Request related data for all Requests. During an in-progress Request, these Magic Variables are updated. All Magic Variables are preceded by an underscore (_
) character in the JSON data model. Reference the Magic Variable after the this.
keyword. Example: return this._user.fullname
to reference the user's full name from the in-progress Request. See Magic Variable Descriptions. Note that there is no Magic Variable that stores the user that starts a Request. To address this, use a Calculated Property to reference the _user.fullname
Magic Variable's value in the Screen referenced in the first Task element of a Process; since many Processes are designed such that the Request starter is the user assigned the first Task in a Request, this is a helpful way of storing who the Request starter is. This Calculated Property stores this Magic Variable's value, which you may reference elsewhere.
In the Formula setting, enter the mathematical calculation/JavaScript that determines the Calculated Property value. This is a required setting.
Click Save. The Property displays in the Calculated Properties screen. The following message displays: Property Saved.
Ensure to save your Screen. The Calculated Property is not added to your Screen until you save it. Doing so will save your work if your session expires.
View the Watchers for a Screen.
Follow these steps to view Watchers for a Screen:
The following information displays about each Watcher:
Name: The Name column displays the name of the Watcher.
Output Variable: The Output Variable column displays the Request variable that the Watcher places its output value after that Watcher performs its action.
Understand how to use Watchers in your Screens.
A Watcher is a Screen Builder tool that loads remote data from a data source external to the current Screen:
The Watcher “watches” a specific data property. This data property may correspond with the Variable Name setting value of a Screen control.
When the value of the data property changes, the Watcher calls an external data source. The following may be the Watcher's data source:
The response data assigns to a configured output property. This output data property may correspond with the Variable Name setting value of a Screen control.
Add custom CSS to controls in your Screen.
Use the Custom CSS mode to add custom CSS styles to a Screen. ProcessMaker Platform supports standard Cascading Style Sheet language (CSS) syntax.
Follow these steps to add custom CSS to a Screen:
Enter your custom CSS syntax.
Address any syntax errors or changes as necessary, then click Save.
Click the Design button to return to Design mode, and then repeat Steps 2 through 6 as necessary.
Use standard Cascading Style Sheet language (CSS) syntax as well as wildcards to customize CSS styles for ProcessMaker Screen controls.
Use the following syntax to apply CSS styling to a specific control in this Screen by referencing its CSS Selector Name setting value. Use single quotes ('
) around the control reference. The reference is case sensitive in the CSS syntax. As a best practice, use the same CSS Selector Name setting value on different controls of the same type to apply the same custom CSS style to all those controls.
[selector='CSS Selector Name Setting that is case sensitive']
Example for a Screen control with the CSS Selector Name setting value of Submit Form
:
Use div.page
to apply CSS styling to all pages in a Screen.
Example:
Click the Calcs button. The Screen is in Calculated Properties mode. The Calculated Properties screen displays all Calculated Properties configured for this Screen. If no Calculated Properties have been configured for this Screen, No Data Available displays.
Click the Calcs button. The Calculated Properties screen displays all Calculated Properties for this Screen.
Click the Delete icon for the Calculated Property to delete. The Calculated Property is deleted, and the following message displays: Property deleted.
View the Calculated Properties for that Screen. The Computer Properties screen displays all Calculated Properties for this Screen.
Click the Edit iconfor the Calculated Property to edit. The Calculated Properties screen displays that Calculated Property's name, description, and how its value is determined.
Mathematical calculation: Click the Formula iconto enter the value, mathematical calculation, or formula that calculates the Calculated Property. The Formula icon is selected by default. Follow these guidelines to reference Screen control or Magic Variable values:
JavaScript:
Click the JavaScript iconto calculate the Calculated Property using valid JavaScript. By calculating the Calculated Property using JavaScript, you can reference the values for Screen controls and Magic Variables. Ensure to use valid JavaScript to calculate the Calculated Property by using a return
statement to return the result of an expression (the value). Furthermore, ensure to use the this.
JavaScript keyword preceding the Screen control/Magic Variable reference. See the examples below.
Mathematical calculation: Click the Formula iconto enter the value, mathematical calculation, or formula that calculates the Calculated Property. The Formula icon is selected by default.
JavaScript:
Click the JavaScript iconto calculate the Calculated Property using valid JavaScript. By calculating the Calculated Property using JavaScript, you can reference the values for Screen controls and Magic Variables. Ensure to use valid JavaScript to calculate the Calculated Property by using a return
statement to return the result of an expression (the value). Furthermore, ensure to use the this.
JavaScript keyword preceding the Screen control/Magic Variable reference. See the examples below.
See the permissions or ask your Administrator for assistance.
the Screen in which to view its Watchers. The Screen is in .
Click the Watchers button. The Screen is in mode. The Watchers screen displays all Watchers configured for this Screen.
Watching Variable: The Watching Variable column displays the Variable Name setting value () for the control that the Watcher monitors for value changes.
Source: The Source column displays the name of the or that the Watcher acts upon to determine its output value.
Script: The data source may be a configured that runs, and then returns a response. Scripts are available in all ProcessMaker editions. .
Data Connector: The data source may be a that gets data and returns a response. The must be installed to use Data Connectors.
See the permissions or ask your Administrator for assistance.
If a Screen control affected by a is hidden by default from custom CSS, the visibility rule overrides the custom CSS design. For example, if custom CSS is designed to hide a Screen control by default when that control's visibility rule dictates that it be visible, the visibility rule overrides the custom CSS to display that control. As a best practice, use visibility rules instead of custom CSS to hide a control by default.
Start with .
the Screen in which to add custom CSS. The Screen is in .
Click the Custom CSS button. The Custom CSS screen displays.
Optionally, reference the CSS Selector Name setting value for specific Screen controls to indicate that CSS styling applies to those controls. Enter the value to represent this control in custom CSS syntax when in mode. The reference is case sensitive in the CSS syntax. See . Example: [selector='Submit Form']
.
Click the Preview button to view your CSS syntax for your Screen in mode. Custom CSS does not display in Design mode.
A common use case is to make existing controls read-only by using the Read Only setting for controls that have this setting. Instead, accomplish this with the Input CSS class.
Also use a control in combination of a control to reference all inputs inside of the Multicolumn/Table control, which is multi
in the example below.
Filter all Watchers in a Screen to find that one you need.
Use the Search function to filter all Watchers from the Watchers screen. All Watchers in the Watchers screen may be used in the Screen from which the Watchers screen displays.
Your user account or group membership must have the "Screens: View Screens" permission to search for Watchers in a Screen unless your user account has the Make this user a Super Admin setting selected.
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to search for a Watcher in a Screen:
View your Screens. The Screens page displays.
View the Watchers for a Screen. The Watchers screen displays.
Enter in the Search setting the text to filter Watchers in that Screens by using any of the following criteria:
Name: Filter by the Watcher name that displays in the Name column.
Watching Variable: Filter by the control in that Screen from which the Watcher monitors for a change in its value by searching for that control's Variable Name value (Request value) that displays in the Watching Variable column.
Output Variable: Filter by the control in that Screen to which the Watcher places its output by searching for that control's Variable Name value that displays in the Output Variable column.
As you enter text into the Search setting, Watchers display that match your entered text.
If there are no search results, the following message displays: No Results.
Edit a Watcher for a Screen.
Your user account or group membership must have the following permissions to edit a Watcher in a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to edit a Watcher in a Screen:
Open the Screen in which to add a Watcher. The Screen is in Design mode.
From the Configuration panel, edit how the Watcher monitors for a control's value to change as necessary. Follow these guidelines:
In the Watcher Name setting, edit the name of the Watcher. This is a required setting.
From the Variable to Watch drop-down menu, select which Screen control by its Variable Name setting value (Request variable) the Watcher monitors for its value to change. This is a required setting.
Select the Run Synchronously toggle key to prevent further interaction with the Screen until the Watcher's action completes. If the Run Synchronously toggle key is not selected when the Watcher runs, the Screen remains active for further interaction. The Run Synchronously toggle key is disabled by default.
Select the Show message while loading remote data toggle key to display an overlaying screen while the Watcher runs. The Show message while loading remote data toggle key is not available if the Run Synchronously toggle key is enabled since the Watcher runs while further Screen interaction is permitted. While the Watcher runs, the overlaying screen displays the name of the Watcher and that it is running. The Show message while loading remote data toggle key is disabled by default.
Select the Run watcher on Screen Load toggle key to run the Watcher when the Screen displays. The Run watcher on Screen Load toggle key is disabled by default.
From the Source panel, select whether the Watcher acts upon a Data Connector or runs a Script when the monitored Request variable changes. Follow these guidelines:
Use a Script as the source (avoid to not affect Screen performance):
From the Source drop-down menu, select a Script from the Script section to run when the monitored Request variable's value changes.
Optionally, in the Input Data setting, enter a valid JSON object the Watcher passes to the Script prior to running as input data for the Script. The Script may reference Screen control values by referencing their Variable Name setting values when placed within mustache syntax. In the example below, FullName
is the Variable Name setting value for a control to store a Request participant's full name:
{
"Name": "{{ FullName }}"
}
Optionally, in the Script Configuration setting, include JSON configuration settings your Script uses when it runs.
Use a Data Connector as the source:
From the Endpoint drop-down menu, select which resource to act upon in the selected Data Connector. These resources are configured from the Data Connector itself. Depending on the Data Connector selected from the Data Connector section of the Source drop-down menu, these resources may reference API resources or Collection records.
From the Outbound Configuration section, specify how the Watcher maps data from a Request variable to a property of the Data Connector. Follow these guidelines:
From the Type drop-down menu, select whether to pass data as a Parameter, Header or in the Body.
From the Key drop-down menu, select from a list of keys available in the Data Connector resource.
In the Value setting, enter the Request variable from which to pass data.
From the Output panel, specify to which Request variable that the Watcher outputs its value after the Watcher performs the action configured from the Source panel. The variable that the Watcher outputs its value does not need to be in this Screen. The output variable may be in a different Screen referenced elsewhere in this Request. Follow these guidelines:
A Script is a source:
In the Output Variable setting, enter the Request variable to which the Watcher outputs the value of its result.
A Data Connector is the source:
From the Output Variable Property Mapping section, specify how the Watcher maps values from the Data Connector to the output Request variable specified in the Form Variable setting. In doing so, the Watcher maps the Data Connector output as a set of properties in JSON format to the output Request variable. Follow these guidelines to map each property:
Click the +Property button. The Source and Form Variable settings display to specify the Data Connector property and Request variable which will receive the output from the Watcher.
In the Source setting, enter the Data Connector property from which to receive data.
In the Form Variable setting, enter the Request variable which will receive the output from the Watcher.
Repeat steps 1 through 4 to map each required property from the Data Connector to a Variable Name.
Click Save. The Watcher displays in the Watchers screen. The following message displays: Watcher updated.
Ensure to save your Screen. The Watcher is not edited until you save it. Doing so will save your work if that your session expires.
Add a Watcher to a Screen.
Your user account or group membership must have the following permissions to add a Watcher to a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to add a Watcher to a Screen:
Open the Screen in which to add a Watcher. The Screen is in Design mode.
From the Configuration panel, configure how the Watcher monitors for a control's value to change. Follow these guidelines:
In the Watcher Name setting, enter the name of the Watcher. This is a required setting.
From the Variable to Watch drop-down menu, select which Screen control by its Variable Name setting value (Request variable) the Watcher monitors for its value to change. This is a required setting.
Select the Run Synchronously toggle key to prevent further interaction with the Screen until the Watcher's action completes. If the Run Synchronously toggle key is not selected when the Watcher runs, the Screen remains active for further interaction. The Run Synchronously toggle key is disabled by default.
Select the Show message while loading remote data toggle key to display an overlaying screen while the Watcher runs. The Show message while loading remote data toggle key is not available if the Run Synchronously toggle key is enabled since the Watcher runs while further Screen interaction is permitted. While the Watcher runs, the overlaying screen displays the name of the Watcher and that it is running. The Show message while loading remote data toggle key is disabled by default.
Select the Run watcher on Screen Load toggle key to run the Watcher when the Screen displays. The Run watcher on Screen Load toggle key is disabled by default.
From the Source panel, select whether the Watcher acts upon a Data Connector or runs a Script when the monitored Request variable changes. Follow these guidelines:
Use a Script as the source (avoid to not affect Screen performance):
From the Source drop-down menu, select a Script from the Script section to run when the monitored Request variable's value changes.
Optionally, in the Input Data setting, enter a valid JSON object the Watcher passes to the Script prior to running as input data for the Script. The Script may reference Screen control values by referencing their Variable Name setting values when placed within mustache syntax. In the example below, FullName
is the Variable Name setting value for a control to store a Request participant's full name:
{
"Name": "{{ FullName }}"
}
Optionally, in the Script Configuration setting, include JSON configuration settings your Script uses when it runs.
Use a Data Connector as the source:
From the Endpoint drop-down menu, select which resource to act upon in the selected Data Connector. These resources are configured from the Data Connector itself. Depending on the Data Connector selected from the Data Connector section of the Source drop-down menu, these resources may reference API resources or Collection records.
From the Outbound Configuration section, specify how the Watcher maps data from a Request variable to a property of the Data Connector. Follow these guidelines:
From the Type drop-down menu, select whether to pass data as a Parameter, Header or in the Body.
From the Key drop-down menu, select from a list of keys available in the Data Connector resource.
In the Value setting, enter the Request variable from which to pass data.
From the Output panel, specify to which Request variable that the Watcher outputs its value after the Watcher performs the action configured from the Source panel. The variable that the Watcher outputs its value does not need to be in this Screen. The output variable may be in a different Screen referenced elsewhere in this Request. Follow these guidelines:
A Script is a source:
A Data Connector is the source:
From the Output Variable Property Mapping section, specify how the Watcher maps values from the Data Connector to the output Request variable specified in the Form Variable setting. In doing so, the Watcher maps the Data Connector output as a set of properties in JSON format to the output Request variable. Follow these guidelines to map each property:
In the Source setting, enter the Data Connector property from which to receive data.
In the Form Variable setting, enter the Request variable which will receive the output from the Watcher.
Repeat steps 1 through 4 to map each required property from the Data Connector to a Variable Name.
Click Save. The Watcher displays in the Watchers screen. The following message displays: Watcher saved.
Ensure to save your Screen. The Watcher is not added to your Screen until you save it. Doing so will save your work if that your session expires.
Discard the changes to your Screen since its last publication.
If necessary, discard the changes to your Screen since its last publication.
Follow these steps to discard changes to your Screen since its last publication:
Click the Discard button. Screen Builder discards the changes since last starting to edit that Screen, and then closes. The Scripts page displays.
Delete a Watcher from a Screen.
Your user account or group membership must have the following permissions to edit a Watcher in a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
Deleting a Watcher from a Screen cannot be undone.
Follow these steps to delete a Watcher from a Screen:
Everyone makes mistakes, and sometimes wish they can redo them.
Your user account or group membership must have the following permissions to undo changes in the Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
Follow these steps to use the Undo button in Screen Builder:
Make a change in the Screen or any of its controls' settings. The Undo button enables.
Click the Undo button to undo the most recent change if necessary. Continue using the Undo button as many times as necessary or until the Screen's state when the Screen was created/opened.
Your user account or group membership must have the following permissions to redo changes in the Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
The Redo button can be used to redo any revision undone by the Undo button up to the current state.
Follow these steps to use the Redo button in Screen Builder:
Make a change in the Screen or any of its controls' settings, and then click the Undo button as necessary. The Redo button enables.
Click the Redo button to redo any revision undone by the Undo button up to the current state.
Click the Watchers button. The Watchers screen displays all Watchers configured for this Screen.
Click the Edit iconfor the Watch to edit. The Watchers screen displays that Watcher's settings with the Configuration panel expanded.
Select the Source panel.
From the Source drop-down menu, select a Data Connector from the Data Connector section upon which to act when the monitored Request variable's value changes. The Endpoint setting displays below the Source drop-down menu.
Click theicon to add a new property.
Select the Output panel.
Optionally, click the Delete iconto delete an added property.
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.
Select the Source panel.
From the Source drop-down menu, select a Data Connector from the Data Connector section upon which to act when the monitored Request variable's value changes. The Endpoint setting displays below the Source drop-down menu.
Click theicon to add a new property.
Select the Output panel.
In the Output Variable setting, enter the Request variable to which the Watcher outputs the value of its result.
Click the +Property button. The Source and Form Variable settings display to specify the Data Connector property and Request variable which will receive the output from the Watcher.
Optionally, click the Delete iconto delete an added property.
automatically saves your every five (5) seconds when changes are made to any of the configuration panels. Regardless of whether you prior to leaving Screen Builder, the next time you edit that Screen, the changes since its last publication remain intact.
While in Screen Builder, click the ellipses menu, and then select Discard Draft.
See the permissions or ask your Administrator for assistance.
the Screen in which to edit a Watcher. The Screen is in .
Click the Watchers button. The Watchers screen displays all Watchers configured for this Screen.
Click the Delete iconfor the Watcher to delete. The following message displays: Watcher deleted.
See the permissions or ask your Administrator for assistance.
Screen Builder displays the Undobutton in the upper right corner of the Screen Builder canvas. The Undo button is disabled when a Screen is initially created or opened until a change in the Screen or any of its control configuration settings is made. The Undo button can be used as many times as necessary or until the Screen Builder's state when the Screen was created/opened this log on session.
. The Screens page displays.
or click the Edit Screen iconto edit the selected Screen. Screen Builder displays. The Undo button is disabled.
See the permissions or ask your Administrator for assistance.
Screen Builder displays the Redo buttonin the upper right corner of the Screen Builder canvas. The Redo button is disabled when a Screen is initially created or opened until the Undo buttonis used to undo a change.
. The Screens page displays.
or click the Edit Screen iconto edit the selected Screen. Screen Builder displays. The Redo button is disabled.
Understand what a Conversational-type Screen is and how they work.
Design functional rule-based modern chat style experiences with Conversational-type Screens, also called Conversational Screens. When a Conversational Screen renders, that Screen displays as a streaming interactive chat box from which the Request participant interacts with the automated chat.
Conversational Screens are intended for use with Web Entry so that the chat experience can be integrated to any third-party site, such as your company and Support portals or any site to which your customers visit frequently. Therefore, Conversational Screens can be used by specified authenticated users or any anonymous person, depending on how the Web Entry for a Start Event element is configured.
Conversational Screens are designed to be modular so that both the data for that Request as well as the validation and visibility rules within the current Conversational Screen determine the course of the automated chat.
For example, one Conversational Screen may contain only four controls. The first control may be a Select List control, of which its Variable Name setting value (Request variable) is ask
, that displays the options described below from which the Request participant selects one.
The following table describes the content of each option that displays in the Select List control as well as the Request variable value that stores the content in Request data.
The subsequent three controls remain hidden by default unless the Visibility Rule setting value evaluates to show that control based on the selected option from the Select List control ask
. Use the Label setting in controls, such as for Line Input controls, to display the text for the conversation response (except for Rich Text controls that use the Content setting to display its content).
The following table describes those subsequent controls by type, the text that displays in the conversation if that control displays, the visibility rule setting that displays that control, and subsequent actions in the Request.
Link Conversational Screens together while the Request resumes routing based on previous conversational responses by the participant. To provide a seamless conversation, select an interstitial Screen to display in the chat box after each Start Event element and/or Form Task element that is part of the overall conversation during workflow in that Request. An interstitial Screen is a Screen that displays after each Conversational Screen completes until the next Conversational Screen in that Request loads, thereby linking the Conversational Screens together into a seamless conversation for the Request participant. An interstitial Screen may be of Display-type.
Each Request's automated conversation may vary depending on how the Request participant responds to Conversational Screen interactions.
An effective interstitial Screen appears as if the Request participant interacts with a person. For example, design a Screen that uses an Image control that displays an animated GIF to imply that the other conversational participant is typing.
While the interstitial Screen displays, multiple elements and/or connectors may perform automatic tasks between one Task's Conversational Screen and the next during a Request. For example, a Data Connector connector may access a Collection record or call a third-party Application Program Interface (API) endpoint, and then return information that the Request participant requested in the conversation. However, the Request participant experiences a seamless conversation between the two Conversational Screens' Tasks while the interstitial Screen displays in the chat box.
For any of these elements that use a Conversational Screen, select the Display Next Assigned Task to Task Assignee setting, and then select the interstitial Screen that displays until the next Conversational Screen displays. The interstitial Screen displays until the next Task's Conversational Screen loads regardless of whether other elements and/or connectors trigger between the two Tasks using Conversational Screens.
Follow these guidelines when designing Conversational Screens and linking them together for a cohesive chat-style conversation with a Request participant:
Design each Conversational Screen modularly within the overall purpose of each conversational outcome. For example, solicit a response from the participant by asking a question with options from a Select List control. Allow the Process model to evaluate the flow of the conversation based on that and/or previous responses, and then in a subsequent Conversational Screen display the automated conversational feedback based on the participant's response. For example:
Configure each Start Event element that provides access to initiate a chat from the hosting site, such as your company and Support portals or any site to which your customers visit frequently. By using Web Entry, the Start Event element specifies who may start a Request of that Process: any anonymous person or specified authenticated users. Since the Start Event element starts the Request, use a Conversational Screen that greets the Request participant. Then, select an interstitial Screen to display after that Conversational Screen completes until the subsequent Conversational Screen loads, such as this example.
From each Start Event element configured using Web Entry, copy the JavaScript from the Embed Code setting, and then embed it into your the hosting site's header from which to initiate chat conversations.
From each Start Event element configured using Web Entry, configure how the chat experience displays from within the hosting site, including the icon that displays to initiate a chat, its placement in the hosting site, and the appearance of the chat box.
Configure each Form Task element that is a segment of the automated conversation with Web Entry and its Conversational Screen. Select an interstitial Screen to display after that Conversational Screen completes until the subsequent Conversational Screen loads.
Use gateways, such as Exclusive Gateway elements, to route each Request based on responses from the Request participant's interactions in each Task's Conversational Screens.
Design automated work in between elements that use Conversational Screens to get or submit information the Request participant request or requires via Conversational Screens. For example:
Data Connector connectors and Scripts get or submit entered information to a Conversational Screen.
Actions By Email, Send Email, and Slack Notification connectors communicate with relevant stakeholders during the Request and optionally allow them to make decisions based on information the Request participant entered into Conversational Screens during the automated chat.
PDF Generator connectors generate PDFs to send printable hard copies to the Request participant for receipts or purchase orders.
Use mustache syntax to incorporate previous participant responses into the automated conversation based on an entered values. For example, at the beginning of the automated conversation, ask for the participant's name in a Line Input control in which its Variable Name setting value is Name
. Name
becomes part of the Request data. In a subsequent control in this or another Conversational Screen, use How may I help you today, {{ Name }}?
in a Rich Text control to personalize the conversation.
Use control validation rules to ensure the Request participant enters responses within the parameters of the conversation you expect for the Request.
Use control visibility rules to indicate which control(s) display as responses and subsequent questions to the Request participant. These visibility rules "steer" the conversation with the participant based on past responses. Remember that visibility rules can reference Request variables not created in that Conversational Screen, but are added to Request data from another Screen in that Request.
Deploy a set of Conversational Screens for a Process to run from any third-party site such as an organization's portal.
To allow Request participants to initiate an automated chat-style conversation to request or get information via Conversational Screens, configure each Start Event element and Form Task element that uses a Conversational Screen in your Process model to use Web Entry. Furthermore, configure Web Entry for the Start Event element how the icon to initiate a chat (which thereby starts a Request) and chat box display from site hosting the chat interface.
Web Entry provides the following benefits:
Embed JavaScript into your Web server's or blog's HTML header that contains the Web Entry URL to start Requests from the hosting site. ProcessMaker generates this JavaScript that informs the hosting site how to start Request of that Process from the hosting site, such as your organization's portal. Copy the JavaScript after configuring Web Entry for the Start Event element.
Both anonymous persons or authenticated users may start Requests, thereby potentially allowing anyone to contact your organization via the automated chat.
Follow these guidelines to configure Conversational Screens with Web Entry:
Configure each Start Event element that provides access to initiate a chat from the hosting site, thereby starting a Request, with Web Entry and the Conversational Screen that greets the Request participant. Select an interstitial Screen to display after that Conversational Screen completes until the subsequent Conversational Screen loads, such as this example.
From each Start Event element configured using Web Entry, copy the JavaScript from the Embed Code setting, and then embed it into your the hosting site's header from which to initiate chat conversations.
From each Start Event element configured using Web Entry, configure how the chat experience displays from within the hosting site, including the icon that displays to initiate a chat, its placement in the hosting site, and the appearance of the chat box.
Configure each Form Task element that is a segment of the automated conversation with Web Entry and its Conversational Screen. Select an interstitial Screen to display after that Conversational Screen completes until the subsequent Conversational Screen loads.
See Conversational Screen Design Guidelines how to use connectors in Process models that use Conversational Screens to automate work between Tasks during the automated chat with a Request participant.
Close Screen Builder with your changes to your Screen intact.
Since Screen Builder saves changes to your Screen automatically when changes are made to any of the configuration panels, it is not necessary to manually save your changes. However, you may close Screen Builder without publishing your changes, but keep all your changes intact.
While in Screen Builder, click the Close button. Screen Builder closes with your saved changes. The Screens page displays.
Publish your designed Screen.
A Screen can be saved in Design mode.
Your user account or group membership must have the following permissions to publish a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
A Screen can be published in two ways depending if the Versioning package is installed. See the following sections regarding how a Screen may be published:
Versioning package is not installed: Publish a single version of your Screen.
Versioning package is installed: Publish distinct versions of your Screen.
Click the Publish button from Screen Builder's top menu to save the Screen. When the Versioning package is not installed, this action overwrites the previous publication of this Screen without maintaining a record of its previous publication(s). To publish distinct versions of a Screen, the Versioning package must be installed.
The Versioning package must be installed to publish distinct versions of a Screen.
When the Versioning package is installed, distinct versions of a Screen can be published. A version is a set of changes published for a Screen since the last publication. Versioning maintains a record of all named and unnamed publications to that Screen. Any of these versions may be viewed or retrieved, if needed. See the Versioning package for more information.
Follow these guidelines to publish a new distinct version of your Screen:
Click the Publish button from Screen Builder's top menu.
Do one of the following:
Publish an unnamed version:
Follow these steps to publish an unnamed version:
Click Save to publish an unnamed version. Otherwise, click Cancel to return to Screen Builder without publishing. As a best practice, name each published version to provide auditing and documentation to what has changed in each publication. Otherwise, Process designers that manage versions of this Screen do not view unnamed versions when the Only show named versions toggle key is enabled while viewing that Screen's version history.
Save a named version:
Follow these steps to publish a named version:
In the Version Name setting, enter a name for this version. The version name displays when viewing the version history of that Screen and helps identify this version. Although this setting is not required, as a best practice name each version for easier maintenance, documentation, and auditing purposes. Name the version that describes changes in this Screen.
In the Additional Details (optional) setting, optionally enter details of the changes made in this version. The additional details display when viewing the version history of that Screen and helps other Process Designers or Administrators understand the changes made in that version. Enter details which concisely summarize the changes made in this version.
Click Save to save this version. Otherwise, click Cancel to return to the Screen Builder without publishing.
Understand the different types of Screens.
The Conversational type provides the following controls in Screen Builder:
Use the Form-type Screen to design interactive and complex multi-page forms. Below are a few ways that Request participants might interact with a digital form:
Enter information, such as name and email address, to apply for a loan.
Approve the department budget.
If the Versioning package is installed, the Commit Changes screen displays to name that published version of this Screen.
ProcessMaker Platform provides the following Screen types, though some require to be installed.
The must be installed.
Use the Conversational-type Screen, part of the Conversational Form package, to design functional rule-based modern chat style experiences. When a Conversational-type Screen renders, that Screen displays as a streaming interactive chat box from which the Request participant interacts with the automated chat. See for more information regarding how Conversational-type Screens function.
control
control
control
Use the Display-type Screen to display information or allow participants to download files. The Display type has limited functionality compared the Form type, but use Display-type Screens to display key performance indicators (KPIs) and commonly used information for specific business stakeholders in your organization. The Display type provides the following controls in Screen Builder:
control
control (requires the )
control
control (with limited functionality)
control
control
control
control
control (requires the )
The must be installed.
Use the Email-type Screen to compose the email body for email messages to be used with the . The Email type provides the following controls in Screen Builder:
control
control
Do not use a Screen type other than the Email type when using the connector. Otherwise, you will not be able to reference any Screens from the Email control in Process Modeler to specify which Screen to use for the email body content.
or documents.
All Screen in Screen Builder are available for the Form type.
Content of the Select List Control Option
Value of the Option Stored in Request Data
Start a Purchase Order
order
Track the Delivery of My Purchase
track
Contact Support
support
Control Type
Content or Label
Visibility Rule Setting to Display Control
Subsequent Action(s) in Request
Rich Text
Let's start a purchase for you.
ask == "order"
Routes to a Sub Process element to start a child Request of "Purchase Request" Process.
Line Input
What is the Order ID for your purchase?
ask == "track"
Entered value routes Request to Exclusive Gateway element that evaluates same the expression, and then routes to a Script Task element to get order status. Thereafter, an interstitial Screen displays until Script Task returns order status to display in subsequent Conversational Screen. See Link Conversational Screens Together.
Rich Text
I'm adding you to the Support queue now.
ask == "support"
Routes to a subsequent Form Task element configured with a Self Service Task. The next available Support agent self-assigns that Task and contacts the Request participant.
Filter all Screens in your organization to find that one you need.
Use the Search function to filter all Screens from the Screens page based on your entered text.
Your user account or group membership must have the "Screens: View Screens" permission to search for Screens unless your user account has the Make this user a Super Admin setting selected.
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to search for a Screen:
View your Screens. The Screens page displays.
Enter in the Search setting the text to filter Screens using any of the following criteria:
Name: Filter by the Screen name that displays in the Name column.
Category: Filter by the Screen Category name that displays in the Category column.
Description: Filter by the Screen description that displays in the Description column.
As you enter text into the Search setting, Screens display that match your entered text.
If there are no search results, the following message displays: No Results.
View the Screens in your organization.
ProcessMaker Platform displays all Screens in one location. Any Screen developed by any Process designer can be used in any Process. This makes it easy to manage Screens.
Your user account or group membership must have the "Screens: View Screens" permission to view the list of Screens unless your user account has the Make this user a Super Admin setting selected.
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to view all Screens in your organization:
Log on to ProcessMaker Platform.
Click the Designer option from the top menu. The Processes page displays.
The Screens page displays the following information in tabular format about Screens:
Name: The Name column displays the name of the Screen. Click the name to edit the Screen in Screens Builder.
Description: The Description column displays the description of the Screen. See Edit Script Configuration for more information.
Category: The Category column displays to which Screen Category the Screen is assigned.
Type: The Type column displays which type the Screen is. See Screen Types.
Modified: The Modified column displays the date and time the Screen was last modified. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
Created: The Created column displays the date and time the Screen was created. The time zone setting to display the time is according to the ProcessMaker Platform instance unless your user profile's Time zone setting is specified.
Use the Search setting to filter Screens that display.
Click the +Screen button. See Create a New Screen.
Click the Import button. See Import a Screen.
If no Screens exist, the following message displays: No Data Available.
Control how tabular information displays, including how to sort columns or how many items display per page.
Edit general information about a Screen.
Follow these steps to configure a Screen:
Edit the following information about the Screen as necessary:
In the Name setting, edit the unique name of the Screen. This is a required field.
In the Description setting, edit the description of the Screen. This is a required setting.
Click Save.
Furthermore, your user account or group membership must have the following permissions unless your user account has the Make this user a Super Admin setting selected:
Screens: Edit Screens
Screens: View Screens
Version History: Edit Version History
Version History: View Version History
Follow these steps to view or edit the version history of your Screen:
Name: The name of this version as entered by a Process designer when saving the Screen in Screen Builder.
Description: A description of the changes in this version as entered by a Process designer when saving the Screen in Screen Builder.
Saved by: The name of the Process designer who saved this version.
Toggle the Only show named versions toggle key to show only the versions with a name assigned to them.
Optionally, edit any of the following existing details about this named version:
In the Version Name setting, edit the name to this named version. If saving this named version with no name, this version does not display in the Version History page if the Only show named versions toggle key is enabled.
In the Additional Details (optional) setting, edit the details about this version. For example, describe the changes in this version for auditing, historical, or maintenance purposes.
Click Confirm and Save to save your changes. Otherwise, click Cancel.
Click Confirm and Save to set this version as the current version. Otherwise, click Cancel.
Create a new Screen that can be re-used in any Process.
Follow these steps to create a new Screen:
Click the +Screen button. The Create Screen screen displays.
In the Name setting, enter a unique name for the Screen. Screen names must be unique in your organization and can only use apostrophe characters ('
) and spaces. This is a required setting.
Enter in the Description setting a description for the Screen. This is a required setting.
From the Type drop-down menu, select one of the following Screen types:
This is a required setting.
Click the Screens iconfrom the left sidebar. The Screens tab displays all Screens in the Screens page.
Click the ellipses icon, and then select the Edit Screen option or click the Screen name. See Screens Builder for topics.
Click the ellipses icon, and then select the Configure option. See Edit Screen Configuration.
Click the ellipses icon, and then select the Copy option. See Copy a Screen.
Click the ellipses icon, and then select the Export option. See Export a Screen.
Click the ellipses icon, and then select the Delete option. See Delete a Screen.
See the permissions or ask your Administrator for assistance.
Click the ellipses icon, and then select the Edit Screen option or click the Screen name. See for topics.
The Screens page displays.
Click the ellipses icon, and then select the Configure option for your Screen. The Edit Configuration page displays.
From the Category drop-down menu, select one or more to associate with this Screen. In doing so, Screen Categories may be sorted from the . To remove a Screen Category that is currently selected, click the icon for that selection or press Enter
when the drop-down is visible. This is a required setting.
The must be installed to view or edit the version history for a Screen.
See the and permissions or ask your Administrator for assistance.
A version is a set of changes made to a Screen at a particular time by a Process designer. Versioning maintains a record of all named and unnamed changes to that Screen. Any of these versions may be viewed or retrieved, if needed. The Version History page displays all saved versions of the Screen in a tabular format from where they can be edited and/or marked as the Current Version
according to your business needs. The current version of a Screen is used in all new of a Process using that Screen. Version changes are not reflected in Requests which were in-progress or already completed when the version changed. .
The Screens page displays.
Click the Configure iconfor your Screen. The Configuration tab of the Edit Configuration page displays.
Click on the Version History tab. The Version History page displays. The Version History page organizes versions in a monthly format and displays the following information:
Date: The date and time of when a Process designer in the .
Current Version: The most recent version of the Screen is displayed at the top and is marked as the Current Version
. This version is used in all in-progress and new .
Click the Change Version Details iconto edit version details for this version. The Change Version Details screen displays.
Click the Copy to Latest iconto set a version as the current version. The Copy to Latest screen displays.
The screen displays the warning This version will become the active version for this asset
,
indicating that this action will set this version as the current version.
See the permissions or ask your Administrator for assistance.
See before creating a Screen.
The Screens page displays.
Conversational: Use the Conversational type to design functional rule-based modern chat style experiences. See and Screen-type.
Display: Use the Display type to display information or allow participants to download files. The Display type has limited functionality compared the Form type. See Screen-type.
Email: Use the Email type to compose the email body for email messages to be used with the Send Email connector. Note that the Send Email connector must be installed for this option to display. See and Screen-type.
Form: Use the Form type to design interactive and complex forms. See Screen-type.
From the Category drop-down menu, select one or more to associate with this Screen. In doing so, Screen Categories may be sorted from the . To remove a Screen Category that is currently selected, click theicon for that selection or press Enter
when the drop-down is visible. This is a required setting.
Click Save. Screens Builder displays the new Screen in . See .
Import a Screen that has previously been exported.
Import a Screen that has been exported from the same ProcessMaker Platform version. The imported Screen contains the configured controls from the exported Screen. Exported Screens have the .json
file extension. The imported Screen can then be referenced in Processes.
Your user account or group membership must have the following permissions to import a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Import Screens
Screens: View Screens
See the Screens permissions or ask your Administrator for assistance.
Follow these steps to import a Screen:
View your Screens. The Screens page displays.
Click the Import button. The Import Screen displays.
Click Browse to locate the Screen to import. Screens have the .json
file extension.
Click Import. The Import Screen screen displays to indicate that the Screen imported correctly.
Click List Screens. The Screens page displays the imported Screen with the same name as the original Screen except with a number "2" suffix.
If the original Screen cannot import successfully, the following message displays: Unable to import the screen. Ensure the following:
The .json
file you tried to import is a Screen and not a Process. An exported Process also uses the .json
file extension.
The exported Screen was exported from the same ProcessMaker Platform version.
Copy an existing Screen.
Your user account or group membership must have the following permissions to copy a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: View Screens
Screens: Create Screens
Follow these steps to copy a Screen:
Edit the following information from the original Screen as necessary:
In the Name setting, edit the name of the copied Screen. After the original Screen is copied, the word Copy is suffixed to the original Screen's name. This is a required setting.
In the Description field, edit the description of the original Screen.
Click Save.
Export a Screen.
The exported Screen has the .json
file extension.
Your user account or group membership must have the following permissions to export a Screen unless your user account has the Make this user a Super Admin setting selected:
Screens: Export Screens
Screens: View Screens
Follow these steps to export a Screen:
Click Download, and then browse for the location on your local computer to save the exported Screen.
By default, ProcessMaker Platform exports the Screen using the original Screen name except spaces in the name are replaced with underscores (_
). The file has the file extension .json
. Rename the default file name if necessary, though do not change the file extension. As a best practice, specify in the file name that this is an exported Screen to distinguish it from other exported assets.
Specify a directory location to save the file. ProcessMaker Platform exports the .json
file to your local computer. The following message displays when the Screen exports successfully: The screen was exported.
Edit a Screen.
See the permissions or ask your Administrator for assistance.
The Screens page displays.
Click the ellipses icon, and then select the Copy option for your Screen. The Copy Screen screen displays.
From the Category drop-down menu, optionally change one or more to associate with this Screen. In doing so, Screen Categories may be sorted from the . To remove a Screen Category that is currently selected, click theicon for that selection or press Enter
when the drop-down is visible. This is a required setting.
The Type field shows which the original Screen is. The copied Screen must be of the same Screen type as the original.
Export a Screen to your local computer. The exported Screen may then be imported to the same or another ProcessMaker Platform instance of the same . An exported Screen may then be shared with others so they can import your Screen for their Processes.
An exported Screen contains all the as the original at the time the original Screen was exported.
See the permissions or ask your Administrator for assistance.
The Screens page displays.
Click the ellipses icon, and then select the Export option for your Screen. The following message displays: You are about to export a Screen. All the configurations of the screen will be exported.
See the permissions or ask your Administrator for assistance.
. The Screens page displays.
Click the ellipses icon, and then select the Edit Screen option or click the Screen name. The Screen opens in Screen Builder. See .