Why 

“Form refresh settings” ensure users interact with the most up-to-date information within forms. In Traditional UI, action sets were used to build complex UI events based on things like click or change, to then update data or refresh parts of the UI.  

In this article, we explore achieving the same business outcome in Constellation.  

When to use

This article covers a few scenarios on when you can use this. The most important aspect is we are using this to refresh data for the current form – the examples are a simple demonstration of what can be achieved: 

• When Field A changes, I want to update Field B. When a scalar field change, I want to change the value of another scalar property on screen 

• Prefill a table (list) with information from my form. When a scalar field changes, I want to change an embedded field on screen. 

• Validate a field on change . When a scalar field changes, I want to run a validation rule against this. 

Prerequisites 

A flow setup with user actions and fields or in Dev Studio: 

• A process 

• A flow action 

• A view 

• Properties 

• A data transform to run in response to a field changing 

When not to use 

1. Cascading Dropdowns - Although we can use this to create cascading dropdowns, with the right data model setup, this is not required.

   1. See Configurating cascading dropdowns  

2. Calculations – Although this could be used to calculate a value, for example “length of stay” for a hotel booking, Pega provides tools to provide a robust data model. This provides a scalable model and avoids logic being stored in the User Interface. Calculations (declare expressions) are built into the Constellation Design System, ensuring inputs are listened for and values updated without manually developing events to do this.

   1. See Creating a calculated field  

3. Updating fields outside the form* – This is designed to update fields in the form, to help with the end user experience.  

   1. When executing a refresh data transform, the data modifications performed to the properties in the data transform will be merged to clipboard only if those modified properties are added as editable fields in the View. If the modified properties are either in Read-Only mode in view or the ones which are used for internal processing, those values will not be available after the submit. 

4. Listening for complex fields (aka changes to a list)*  

   1. A refresh data transform on flow action can only be configured for a scalar property like .Category in the work page level. For an embedded page property like .Address.ZipCode this is not a supported configuration for Form Refresh setttings. 

   2. 

*For items 3 and 4 above, you should explore data transform smart shapes in your flow or pre/post processing on the user action if there are other requirements. 

• See Configuring pre-processing for a Flow Action 

• See Configuring post-processing for a Flow Action 

• See Faster application development with smart shapes 

Scenario 1:  When Field A changes, I want to update Field B 

Let’s start simple. When I tick that I need my order today, then we should update Shipping Date to today’s date. 

Steps

1. Open the Dev Studio 

2. Open the Flow Action rule 

3. Add a new condition to your “Form refresh settings” 

   1. 

4. Create a new condition to look for changes in the “I need my order today” and select the data transform to run 

   1. 

5. In this example, the data transform I created looked like this 

   1. 

6. The result, is when I ran this on the 11th of July 

   1. 

Scenario 2: I want to prefill a table (list) with information from my form when it changes 

Building on the previous scenario, we are in a single form, and we want to have interaction between a field on screen and a list of items that need completing. In our scenario, we could ask the question “How many people live in your household?” and based on this we could prefill the number of records in that list.  

Important aspect of this scenario 

• All whilst on the same form. 

• Our form for this demonstration will be the Hierarchial form template, a new feature in 24.2. Whilst this breaks the UI up into “tabs”, this is still a single form configured in your application. 

  • 

• Personally, if I were tackling this scenario, I would recommend a regular process or multi-step form (screenflow). However, we have seen scenarios where a single assignment in a hierarchical form is preferred for other User Experience reasons. This would be that scenario. 

Steps 

1. Open the Dev Studio 

2. Open the Flow Action rule 

3. Add a new condition to your “Form refresh settings” 

   1. 

4. Create a new condition to look for changes in the “People in my household” and select the data transform to run 

5. In this example, the data transform I created looked like this – a very simple example just for demonstration (and in real life would be optimised better). 

   1. 

6. The result

   1. When I open the form 

      1. 

   2. When a I change the value for number of people applying 

      1. 

Scenario 3:  I want to validate a field on change 

Now we are going to get more complex, I'll speed up the configuration as we’ll assume you know the pieces from scenario 1. We want validation to happen on entry of a field. 

Important design caveat 

• Pega’s OOTB validation is usually done on submit of a form 

• The low code authoring platform is geared to provide this in a simple and scalable way.  

• By introducing validation on entry for this one field, you may be introducing a design pattern that  

• will take longer to implement 

• harder to maintain and  

• Introduces the risk of bugs.  

Careful consideration should be made to implementing change validation like this.This example illustrates how the Form Refresh settings can be used flexibly in the Constellation Design System, not should be. 

Steps to implement 

In this case, for my example, let’s say we want to stop erroneous names from being entered. We have a blacklist of entries, in this example, “whatever”. 

1. Create a Form Refresh Setting that runs a data transform and triggers the desired validation. 
   1. In this example, the data transform is running an activity that then runs the validation rule.
   2. You will also notice this example; I'm using the Form template, hierarchical form. To demonstrate this works with different form types as well.
      1. 
2. Full configuration 
   1. 

Tip 

Form refresh settings can not be used to cascade changes across a network of properties (e.g. declarative network). For example, when ‘first name’ changes, then update ‘full name’ – when full name changes, update ‘display name’.  

The listening event will only trigger one data transform, not a cascading network of data transforms. Careful consideration of your design should be taken to ensure your UI updates appropriately.  

Conclusion  

Form refresh settings is a powerful tool in Constellation to help listen for different field changes to ensure the data on your form is always up to date. It should be used in conjunction with other Pega tools such as pre/post processing, calculations (declare expressions) and datapages to build a robust data model that updates as needed. 

Additional Reads

• Defining the run-time presentation of Flow Actions

• Configuring dynamic field behavior  

Constellation 101 series

Enjoyed this article? See more similar articles in Constellation 101 series.