How to create a user form in PEGA through Section and Flow Action rules — Traditional Approach
User forms in a Pega Platform Application are used to either display or collect data from users through UI elements such as — text box, dropdown list, autocomplete, radio buttons, checkbox, buttons, etc.
In this article I’m going to illustrate the traditional methodology to design a user form that was followed in the lower versions of PEGA such as v6 or v7, and is still followed in v8 (to some extent). With a shift in focus on the Low-code development, the UI design has become easier in PEGA as the system automatically takes care of a certain aspects or configuration that’d had to be done manually in the traditional approach. But the modern low-code approach is based on the traditional one, and has many things in common. For this reason, having a sound understanding of the traditional method helps debug the UI related issues even while working with the low-code approach, and it remains vital for a PEGA developer.
Note — You can develop a user form for a Collect Information type step in a Case Type.
Important
The approach covered in this article is applicable to the applications built on Pega’s section-based UI architecture (Traditional UI). It is not suitable for the ones built on the latest view-based UI architecture.
Key Rule Types
We’re going to work with the following rule types as we create and design a user form with the traditional approach. I am going to explain each one of them in this article later on.
- Flow
- Flow Action
- Section
Let’s begin!
Step# 1 Create a Case Type
Firstly, you need to create a Case Type, design the case life cycle. As shown below, I’ve created a Medical Insurance case type, and designed a basic case life cycle — with three stages, one process (in the first stage) and two steps (in the process) to collect Insured details and their dependent(s) details. In this demonstration, I’m going to cover creating a user form for the first step — Collect Insured Details. The user form would include a number of fields to fill the details, such as — name, email address, mobile number, date of birth, and residential address of the person who is insured under the health insurance.
If you want to learn more about creating a case type, and designing a case life cycle, and other important details such as the Work Class associated with the case type, then you can read through the following article.
Step# 2 Data modelling
Next, you need to identify any entity(s) that are associated with your user form. For example — in my case, I’m creating a user form to collect the Insured details. Hence, Insured person is one entity that is closely related with my user form. After you’ve identified such entity(s), you need to model it in Pega with the help of data class(s) and its properties before you start creating your user form.
Insight — Data classes along with their properties are used to model an entity, such as — an Insured, a dependent, a customer, a user, a product etc.
In order to model the Insured entity in Pega, I’ve created the following concrete data class: MyOrg-Data-Insured in the organizational layer. You can create your data class in an appropriate layer.
Thereafter, in the above Insured class, I’ve created the following properties that represent the attributes or details about an insured person that we want to collect from user — First Name, Last Name, Date of Birth, Email, Mobile, and some address-related properties.
As a last step in the data modelling exercise, you need to create an object of the Insured data class in the Work class associated with your Case Type. This object is meant to store an insured person’s details such as name, email, phone, etc. entered by user in the user form. In order to create an object of any data class in a Work class, create a Single Page property in the Work class.
Insight — A Single Page property in Pega essentially represents an object of one class created in another class. The Page Definition (a field in the Single Page property ruleform) indicates the class of which it is an object. The Applies-to class of the property signifies the class in which it is created.
I’ve created a Single Page property named Insured in the Work class related to my case type i.e. MyOrg-MyDiv-Alpha-Work-MedInsurance as shown below.
Note that I’ve specified MyOrg-Data-Insured as the Page definition in the property ruleform because it represents an object of the Insured data class.
Read on to find out how to use this single page property so that it stores the insured person’s details entered by user.
Step# 3 Create and configure the important rules
1) Flow rule
Go to the Case Type, and select the process that includes the step for which you want to create a user form. In my case, it is the process named Create in the first stage. It contains the step — ‘Collect Insured Details’ for which I’m going to create a user form. When you select the process, it would bring up a properties panel on the right hand side as shown below.
Click on the Open process link in the panel.
It would open the flow rule as shown below.
What is a Flow rule?
- Every process added in the Case Type has an associated flow rule.
- A flow rule illustrates the graphical flow of events such as — collecting data from user, decisioning, automation, sending email notifications, etc., that constitute the process.
- It is made up of different shapes — one shape connecting to the other.
- Some of the basic shapes found in a flow rule are as follows —
a) Start shape — A green colored circular shape that signifies the beginning of the process/flow.
b) End shape — A red colored circular shape that denotes the finish to the process/flow.
c) Assignment shape — For each step added in the process, the system includes a green-colored rectangular shape in the flow rule. It represents a touch point in the process where a user interacts with the application by either providing or reviewing information in a user form.
There are also advanced shapes that are a subject of future discussion.
Configuration of the flow rule
As shown below, the system has included two assignment shapes in the flow — one shape each for the two steps added in the process. You need to configure the flow with the flow action (Don’t worry! flow action is explained below) name(s). Right click on the first assignment shape that corresponds to the ‘Collect Insured Details’ step. It would open up a menu as shown below. Select View Properties from it.
It would launch Assignment properties modal dialog as given below. Specify the flow action name in the dialog. The system pre-populates a default name derived from the corresponding step name entered in the Case Type.
You can choose to either keep the default name or provide a different name. In my case, I have changed the name to EnterInsuredDetailsFA.
Next, you need to create this flow action. Click on the crosshair icon besides the flow action name. It will open up Create Flow Action form in a new tab as shown below.
Apply your flow action to an appropriate Work class and ruleset, and click on the [Create and open] button in the header. It would open Flow Action ruleform as shown below.
2) Flow Action rule
Flow Action represents an action to be performed by a user in a process/flow. An action could be — to either provide or review information through user forms. In this case, the action for user is to fill insured information in the user form.
You need to configure the flow action with the name of the section rule. Don’t stress out! I’ve explained the section rule below in this article. Specify a section name in the ruleform as I’ve done below.
Then, you need to create this section rule. Click on the crosshair icon besides the section name. It would open Create Section form in a new tab as shown below. Apply your section to a suitable Work class and ruleset. And, click on the [Create and open] button.
It would open the Section ruleform as shown below.
3) Section rule
What is a Section rule?
A section rule(s) enables to design and develop a user form for a particular user action. It is the place where you would select the UI elements (such as — text box, check box, radio buttons, dropdown list, auto-complete, etc.) to be included in the user form, arrange them, and configure them.
Design Template vs Full Section Editor
In version 8 of the product, Pega recommends the use of Design Templates as a best practice to design your section rules. However, in lower versions of Pega (such as v7 and v6), and even in v8 on some occasions, the section rules are designed using full section editor. Design Templates support reusability and better performance, whereas, the full section editor approach provides more control over the design. Hence, it remains vital for a Pega developer to be equipped with the capabilities offered by the full section editor methodology.
Since, I’m focusing on the traditional approach to develop user forms in this article, I’m going to use the full section editor method. By default, the section rule uses the design template. In order to switch to the full section editor, in the section ruleform, click on the “convert to full section editor” link in the blue colored header ribbon. It would bring up a modal dialog as given below, seeking confirmation.
Click [Submit]. You would notice a change in appearance of the section ruleform as shown below. Now, the section uses the full section editor.
Configuration of the section rule
After the section is converted, the toolbar displays different menus, namely — Structural, Data capture, Pickers, Action, and Data display for selecting different types of UI elements, such as — text box, dropdown list, auto-complete, button, etc.
Important —
This section is created in the Work class (MyOrg-MyDiv-Alpha-Work-MedInsurance), and would execute in the context of an object aka clipboard page of the same class, namely — pyWorkPage. However, I rather need a section — created in the Insured data class (MyOrg-Data-Insured), that refers the properties of that class, and that would execute in the context of an object of the same class, so that this object, representing an insured person — stores all the details of the person filled in the user form.
Hence, I’m going to embed another section — created in the Insured data class — in this section created in the MedInsurance Work class, and use an object of the data class — created in the Work class — as the context to execute the embedded section. In the Work class, I’ve already created a single page property named Insured — essentially an object of the Insured data class. I’m going to use this single page property as the page context of the embedded section.
In order to embed one section in another, expand the Structural menu in the tool bar.
Select and drag the Embedded section item towards the Dynamic Layout, and drop it within the layout as shown below.
Note — Left click and hold the mouse button pressed while dragging the section. Release the mouse button in order to drop the section.
It would bring up the Section Include modal dialog as given below.
In order to execute the embedded section in the context of the single page property named Insured, change the Page context to Use clipboard page.
And select the .Insured property as the Clipboard page as shown below.
Since, the embedded section needs to be created in the Insured data class, change the Class to MyOrg-Data-Insured as shown below.
Provide a name for the embedded section.
And, click on the crosshair icon next to the section name. It would open the Create Section form in a new tab. Note that the section is applied to the Insured data class i.e. MyOrg-Data-Insured.
Click [Create and open] button. It would open the Section ruleform.
Convert to full section editor using the approach described earlier.
Now, you need to add the UI elements of your choice such as — text box, dropdown list, checkbox, buttons, etc. to this section and organize them. Each UI element would reference a property of the Insured data class that would store the value entered in the respective UI element by user.
a) Add the fields —
Let’s start by adding a text box for the first name of Insured. Click on the Data Capture menu in the toolbar.
Left-click on the Text input control, drag it (while holding the mouse button) into the Dynamic Layout. As shown below, the layout would change color as you drag the text input into it.
Release the mouse button to drop the text input control inside the layout. The control would be added to the layout as shown below. Thereafter, you need to configure the control to use FirstName property of the Insured class so that a value entered by user in this field would be stored in FirstName property within the Insured object. In order to configure, select the Text input, and click on the gear icon to View properties.
It would bring up the Cell Properties modal dialog.
Select the .FirstName property in the dialog as given below. This property within the object would store the first name value entered by user.
Click [Submit] to close the dialog. With this, you have added and configured a text input field for First Name.
Similarly, add another field for Last Name by dragging another Text input control from the Data capture menu, and dropping it below the First Name field in the Dynamic Layout as shown below.
Configure the field to refer the .LastName property, so that the last name value entered by user is stored in this property within the object i.e. single page property,
For Date of birth field, use the Date time control, also available in the Data capture menu.
Drag and drop the Date time control below the Last Name field. Configure it to refer the .DateOfBirth property as shown below.
The Date time control, by default, uses the date component plus timestamp. On the Presentation tab, in the Editable Settings section, configure it to collect the date part only.
On the same tab, in the Read-Only Format section, change the Type to Date for the control to display only the date part.
In the same section, select a Date format of your choice.
For the email address field, use the Email control.
Configure it to reference the .Email property.
You can use the Phone control for the mobile field.
Configure to use the .Mobile property.
I’m going to use an autocomplete for the City field. The autocomplete control is available in the Pickers menu as shown below.
Refer the .City property. There are different ways to source the autocomplete with data. The data source is specified in the List source section. The easiest way is to define the list of items on the associated property ruleform. I’m going to use the same method.
For this method, make sure that the Type is set to As defined on property as shown below.
Now, let’s define the list of items on the property ruleform. In the above dialog, click on the crosshair icon adjacent to the property name to open the ruleform.
On the ruleform, change the Table type to Local List.
Enter the list of cities in the Table values section as shown below, and save the property ruleform.
Go back to the section, and click [Submit] in the Cell Properties modal dialog. The City autocomplete would be added as shown below.
For the State field, I’m going to use the Dropdown control — also available in the Pickers category.
Reference the .State property. Select the Include placeholder checkbox, and provide a placeholder value as given below. Use the same above method of sourcing the dropdown list with the values defined on the property ruleform.
Ensure that the List source -> Type is set to As defined on property.
Open the property ruleform, and define a Local List of the state values. Remember to save the ruleform.
Change back to the section rule, submit the Cell properties modal dialog. The State dropdown list would be added as shown below.
For the remaining address related fields — Address Line 1, Address Line 2 and Postal Code, you can use the Text input control, and add them the same way as first name and last name fields.
Insight — You can also create your own control with the help of the Control rule type, and use it for a field in a section. For the inbuilt controls that I’ve used in this demonstration, the following control rules are predefined in PEGA — pxTextInput, pxDateTime, email, pxPhone, pxAutoComplete, pxDropdown.
b) Arrange the fields —
The Dynamic Layout in the section, by default, uses Stacked format i.e. the fields are stacked on top of each other. In order to arrange the fields in a different format, left click on the Dynamic Layout to select it, thereafter, click on the gear icon to View its properties as shown below.
It would bring up Dynamic Layout properties modal dialog as shown below. Change the Layout format from its default value of Stacked to Inline grid double to arrange the fields in a more presentable format of 2 columns as opposed to 1 column earlier.
Submit the modal dialog, and the fields would re-arrange into two columns. Save the section.
Step# 4 Save the rules
- Save the embedded section (InsuredDetailsForm), if not done already.
- Go back to the main section (InsuredDetailsWrapper) with the Section Include modal dialog still open.
Submit the modal dialog, and save the section.
3. Thereafter, change back to the Flow Action, and save it.
4. Switch back to the Flow rule with the Assignment properties modal dialog still open. Submit the modal dialog, and save the flow rule.
5. If your Case Type is already open, go back to it, and first refresh it through Actions -> Refresh
And, then, save the Case Type by clicking on the [Save] button in the header bar as shown below.
Step# 5 Initialize the single page property
The system does not generate a single page property in memory unless you specifically set an initial value to at least one single-value property within it. You would need to initialize a single-value property within the Insured single page property which is the page context of the section rule. If you can’t think of an initial value, set null value to any single-value property — including inbuilt properties such as pyLabel, pyNote, etc.
Note — If you miss this step, your user form would not render as the single page property — the page context of the section rule — would not exist in memory.
In order to initialize a single-value property, I’m going to apply a pre-processing data transform to the flow action that executes before the user form is rendered. It would execute, initialize, generate the single page property, and thus establish the page context before the section rule executes.
Go to the Flow Action. Change to the Action tab.
In the Pre-processing section, provide a data transform name as shown below.
Then, create the data transform. Click on the crosshair icon besides the data transform name. It would open the Create Data Transform form in a new tab as shown below. I’ve applied it to the same Work class as the flow action.
Click [Create and open]. It would open the Data Transform ruleform as given below.
I’ve set default or initial values to the City and State single-value properties within the Insured single page property as given below.
If you want to learn more about how to set single-value properties using a data transform, you can check out the below article.
Save the data transform. Remember to change back to the flow action (EnterInsuredDetailsFA), and save it as well.
Step# 6 Verification
There are three possible ways to verify —
Method #1 — Save and Run the Case Type as shown below.
It would create and open an Medical Insurance case instance (e.g. MED-1004) in a new tab with the user form to enter the insured details as shown below.
Note that the City and State fields are pre-populated with the respective default values.
The City autocomplete is sourced with the different options.
Similarly, the State dropdown list is also sourced with all the options.
Method #2 — via Create menu
Create menu (in the header) -> New -> Medical Insurance as shown below
It would also create and open a Medical Insurance case instance in a new tab as already shown above.
Method #3 — via User Portal
From the header, select Launch portal -> User Portal.
It would launch the portal in a new browser tab as shown below.
Hover over + icon in the left navigation panel.
Expand Create menu, and select Medical Insurance.
It would bring up a modal dialog with the user form to collect insured details as illustrated below.
Fill the insured details in the form.
Click [Continue] to submit the form.
Lastly, launch the clipboard, and verify that the input insured details are stored in the Insured single page property in the pyWorkPage as shown below.
Note — Remember to select the relevant thread in the clipboard to locate the pyWorkPage.
Well, that’s it for now!!
In the upcoming article, I would demonstrate how to design the user form for the second step in the process to collect details of a LIST of dependents of the insured. So, stay tuned!
To learn more about Pega, be sure to Follow the below page
