How to Use Expressions and Pega 7 Library Functions for String Manipulations in a Data Transform or Activity

For this post, Pega 7.1.9 was used. Pega 7 (and earlier versions) provides several utility functions for manipulating Strings.
These functions can be called as part of Expressions in Data Transforms and Activities.


  1. Sample Data Transform and Debugging
  2. Examples of String Manipulations with Expressions and Functions
    1. Conversion to Upper- and Lower Case
    2. Extraction of Substrings
    3. String Comparison
    4. Substring Search
    5. Substring Replace
    6. String to Number Conversions

Related Posts

  • For this example, a data transform with 7 input parameters was created:

Data Transform - TransformNames - Parameters Tab

  • On the Definition tab, the Set action is used to assign new values to the parameters using expressions. Here, Param.fullName is set using concatenation and conversion to upper case.

Data Transform - TransformNames - Set Action and Expression Builder Gear Icon

Data Transform - TransformNames - Pega 7.1.9 Expression Builder

  • The data transform can be run by clicking on Actions > Run.
  • Use the Trace button to start the Tracer. This allows to view the transformed input parameter values.

Data Transform - TransformNames - Run Data Transform Page

  • The data transform’s execution page can be viewed by clicking on the FIRST row in the Tracer (…execution page state after running the data transform).

Data Transform - TransformNames - Run Data Transform - Steps Execution and debugging in Tracer

  • Click on the =unnamed= link in the Parameter Page Name row to open the parameter page.

Data Transform - TransformNames - Tracer Debugging - View Trace Event

  • Here, the parameter page shows the data transform’s parameters AFTER execution is completed.

Data Transform - TransformNames - Tracer Debugging - View Data Transform Parameter Page

  • The Pega 7 String Library functions use the methods of the java.lang.String class. But, NOT ALL methods of java.lang.String are included in the Pega 7 String library.

A: Conversion to Upper- and Lower Case

  • Changing the case of a String is straightforward. Here, a single input String is converted to upper case.
  • Likewise, a method exists for changing the case of a single input String to lower case.
    @String.toLowerCase("Ulysses S. Grant")
    "ulysses s. grant"
  • The + operator can be used for concatenating multiple parameters to one input parameter:
    @String.toLowerCase(Param.firstName + " " + Param.middleName + ". " + Param.lastName)
    "ulysses s. grant"

B: Extraction of Substrings

  • There are two overloaded @String.substring methods (same name, different input parameters) that can be used to extract a substring from a given string. The first one has 3 input parameters, the string (zero indexed) and a start-(inclusive) and end index (exclusive) and uses to the Java method substring(int beginIndex, int endIndex).
    @String.substring("304-678-9185 EXT 776", 0, 12)
  • To extract the last 4 digits of the phone number:
    @String.substring("304-678-9185 EXT 776", 8, 12)
  • The second substring method only has 2 input parameters, the string and the start index.
  • To extract the extension in this example, use:
    @String.substring("304-678-9185 EXT 776", 17)
  • The result of a function can be passed as an input parameter to another function. Here, the 10-digit phone number is extracted first. Then, the area code is extracted:
    @String.substring(@String.substring("304-678-9185 EXT 776", 0, 12), 0, 3)
  • @String.length is used to obtain the length of a given string, i.e. the number of characters:

C: Comparison

  • @String.equalsIgnoreCase is used to compare two Strings (case-insensitive). For example:
    @String.equalsIgnoreCase(Param.firstName, Param.lastName)
  • @String.notEqualsIgnoreCase is used to compare two Strings for INEQUALITY. For example:
    @String.notEqualsIgnoreCase(Param.firstName, Param.lastName)
  • @String.equals is used for CASE-SENSITIVE comparison:
    @String.equals("Blue", "blue")
  • @String.notEquals is used for CASE-SENSITIVE comparison for INEQUALITY:
    @String.notEquals("Blue", "blue")

D: Substring Search

  • @String.contains is used to search for the occurrence of a given substring within a string:
  • Here, Param.street is "Oak Hill Dr" and the method is used to check if it contains "Hill".
    @String.contains(Param.street, "Hill")
  • @String.pxContainsViaRegex is used to search for the occurrence of a given substring within a string using a regular expression. For details on regular expressions, see the java.util.regex.Pattern class documentation.
  • In this example, a regular expression, \d{3}-\d{3}-\d{4}, is used to search for 10-digit phone numbers in a given String. Note that the \ character needs to be escaped as per Java syntax, using \\.
    @String.pxContainsViaRegex("phone=345-444-0001|name=smith", "\\d{3}-\\d{3}-\\d{4}", true)
  • @String.startsWith is used to check if a string starts with a given substring.
  • @String.endsWith is used to check if a string ends with a given substring:
    @String.endsWith(Param.street, "Dr")
  • @String.indexOf can be used to get the start index of a substring within a given String.
    @String.indexOf(Param.street, "Hill")
  • If the given substring is NOT found, @String.indexOf returns -1, for example:
    @String.indexOf("Oak Hill Dr", "Blvd")
  • @String.indexOf is often used with @String.substring.
  • For example, Param.inputRow is "Name=Warren". To extract the actual name:
    @String.substring(Param.inputRow, @String.indexOf(Param.inputRow, "=") + 1)

E: Substring Replace

  • @String.replaceAll is used to replace all occurrences of a given string with another string.
  • In this example, all of the hyphen characters are replaced with pipe characters:
    @String.replaceAll("apple-banana-cherry-date", "-", "|")
  • @String.pxReplaceAllViaRegex is used to replace all substrings that match the given regular expression. For details on regular expressions, see the java.util.regex.Pattern class documentation.
  • For example, to replace all 10-digit phone numbers in a String with XXX-XXX-XXXX:
    "Mr.Smith's work phone number is 675-999-0017 and his cell phone is 778-000-9999.",
    "Mr.Smith's work phone number is XXX-XXX-XXXX and his cell phone is XXX-XXX-XXXX."

F: String to Number Conversions

  • @String.isInteger is used to validate that a given String represents a number of type Integer:
  • @String.isDouble is used to validate that a given String represents a number of type Double:
  • Strings that represent Integer and Double type numbers can be converted to Integer and BigDecimal Java types:
  • If the String does not contain a valid Integer value, the function returns 0.
  • @String.toDecimal supports thousands separators and a decimal point:

Iterating over a Page List in a Data Transform in Pega 7

In this example, a Data Transform is used to iterate over a data page that uses a list structure. See this example on how to create a data page using the Data Table Wizard. For this example, a data page that is backed by a data table of car makes is used to show how to iterate over it in a data transform.

Related Posts


  1. Description of Data Table for Class ABC-Insurance-Data-Make Used in this Example
  2. List Data Page for ABC-Insurance-Data-Make Rule Instances
  3. Creating a Data Transform for Iterating over the Data Page

  • The screen shot below shows an example of a Data Table. In this case, the rows represent car makes. See the link under Related Posts on how the data table was created.
  • The data table contains instances of the class ABC-Insurance-Data-Make. This class has the properties ID (Integer) and pyLabel (Text).
  • The ID is a unique identifier (Key) and the pyLabel property contains the actual car make values.

Pega 7 Edit Data TAble Instances

  • The below screen shot shows the configuration of a list-structure data page named D_Makes. Its purpose is to store a list of car makes. The Data Page Definition section is configured as follows:
Structure: list
Object Type: ABC-Insurance-Data-Make
Scope: Node
Data Source: Report Definition
  • Node scope causes the data page to be available to all users on a node (i.e. it will be loaded once per PRPC node).
  • The Data Table Wizard creates a default Report Definition. Here it is named dataTableListReport and it returns all rows in the underlying data table.

Pega 7 Edit Data Page - Data Page Definition and Data Sources

  • The data page can be unit tested by clicking on ActionsRun.
  • The XML of the data page will be shown and the node pxResults (a PageList) will contain all of the rows in the data table.

Run DataPage XML Output

  • After running the data page once, it will appear in the Clipboard Tool under Data Pages > Node.
  • Due to its Node scope, the data page D_Makes will remain on the clipboard until the PRPC instance is restarted or the data page is deleted using the Designer Studio or the Clipboard Tool is used to delete it (see the Actions button in upper right-hand corner).

Pega 7 Clipboard Viewer Data Page pxResults

  • In the Designer Studio, a data transform can be created using +Create > Data Model > Data Transform.

Pega 7 Designer Studio - Create New Data Transform

  • The Data Transform Record Configuration form requires the user to enter a name, here it is IterateOverMakes and to select an Apply to class. Here, the class is ABC-Insurance-Data-Make.
  • Click on the Create and open button to create the data transform rule.

Pega 7 Create Data Transform Form - Iterating over Data Page pxResults

  • On the Parameters tab, an output parameter named MakeString of data type String is defined.
  • It will be used to return a comma-separated String of car makes that is created by the data transform while it iterates over the data page D_Makes.

Pega 7 Data Transform - Parameters Tab Output Parameter

  • On the Pages & Classes tab, the data page D_Makes needs to be listed with a class of Code-Pega-List.
  • The class Code-Pega-List has a page list property named pxResults which holds instances of the object type specified when the data page was configured. Here the object type is ABC-Insurance-Data-Make.
  • Specify the class of D_Makes.pxResults as shown below.

Pega 7 Data Transform - Pages and Classes Tab

  • On the Definition tab, the first row will use the action For Each Page In to iterate over the D_Makes.pxResults page list.
  • The checkbox Also use each page as source context in the Source column should be checked so that the . dot operator can be used to refer directly to the current page of the iteration instead of having to use D_Makes.pxResults(<CURRENT>).
  • In the second row, param.MakeString is concatenated with the pyLabel property of the current ABC-Insurance-Auto-Make instance.
  • The third row uses a simple expression to remove the last comma in the comma-separated string after the iteration. The complete expression is:

Pega 7 Data Transform - Definition Tab

  • Save the data transform and open the Tracer. Make sure that the check boxes for Start and End for data transforms under the section Events to Trace are checked.

Pega 7 Tracer Settings - Enable Data Transforms

  • The data transform can be unit tested by selecting Actions > Run and then clicking on the Execute button in the new window. Note: Make sure that the Tracer is running before executing the data transform.

Pega 7 Test Page for Running Data Transform

  • A new window opens and shows XML output from executing the data transform. The pzStatus will contain the value valid if the exeution was successful.

Pega 7 Data Transform - Run XML Output pzStatus is valid

  • Switch to the Tracer window and search for the row where the event type shows Data Transform End and click on that row.

Pega 7 Tracer Window - Data Transform End step

  • A new window opens, showing the properties of the test page that was created for running the data transform. Click on the link =unnamed= link of the Parameter Page Name property in the TraceEvent[8] page.

Pega 7 Tracer - Properties of Page TraceEvent

  • This will open the TraceEvent[=unnamed=] page, showing the output parameter named MakeString which was set by concatenating the car make values while iterating over the data page D_Makes to generate a comma-separated String value of the car makes.
  • The page also shows some Pega out-of-the-box properties, prefixed with py or pz.
  • In the below screen shot, a property named pyForEachCount with a value of 8 is shown. This is the number of iterations that were executed by the For Each Page In data transform action (i.e. the number of items in the D_Makes.pxResults list).

Pega 7 Tracer - Properties on Page TraceEvent - Data Page Entries

  • Note: The tracer also shows that Code-Pega-List maintains the order of the entries in the data table.
  • Pega is implemented in Java and the underlying Java interface- and implementation classes for Code-Pega-List are java.util.List and java.util.ArrayList from the java.util package.

Please register to add comments or feedback!