Introduction

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

Pega Constellation provides a set of field types for managing information related to data objects within a case. Each field type serves a specific purpose, promotes reuse of data, and ultimately helps manage data used in a case and overall application. This document explores these three most used fields- Data Reference, Embedded Data and Query along with a practical example of where to use them.

Data Reference

A Data Reference field stores data records of a data instance that lives outside the case (this could be in Pega or an External System of Record).  Pega retrieves the related data using a database lookup with the unique identifier when reference data is needed. The Data Reference field only keeps the key (unique identifier), rather than storing the entire data object making for efficient data retrieval.  While it is possible to store a copy of the reference data, this is typically avoided for performance or redundancy reasons.

Data Reference can operate in three different modes:

• Single Record Mode: Enables the selection of one data record, using a table or dropdown controls. Example, selecting a specific product from a list of products.

• List of Records Mode: Enables the selection of multiple data records, using table, combo box, or checkbox controls. For example, selecting multiple products from a list of products or selecting multiple skills for job opening.
• Many to many Mode: Enables the relationship between two data objects where multiple records in one data object can be associated with multiple records in another data object. For example, establishing a relationship between orders and products, where a single order can include multiple products, and each product can be referenced by different orders. Many to many relationships enable lookup of data from both sides example-Lookup product associated with order(s) and query all orders which reference a given product.

         Configuration Tip

         Two data pages are required, when setting up a Data Reference. This is regardless of whether you configure it for a single record or a list of records mode.

1. Create a field within the case type and update Type to Data Reference with appropriate data object.
2. In the Advanced tab, notice that Pega generated a Single page data page. You can use this data page for configuring the data reference.
3. When adding this field to a view, Pega requires a List type data page. You can use the out-of-the-box (OOTB) data page, which is automatically created when defining the source of the data object. Or you can create a custom data page, such as one that accepts any parameters. Example, filtering a list of cities after selecting a state would require passing state information as a parameter to a data page.  This Data Page that passes the state parameter is created manually. 

Embedded Data 

An Embedded Data field type is ideal for capturing information because it stores data directly within the case. Examples include- Customer information, shipping address or order details. Embedded data fields store complex, nested or hierarchical data within a case that is unique to that instance and does not have to be shared or referenced across multiple cases. For example, complaint information for a specific product or service contains unique information about a problem, and appropriate to store just within the case. 

Use Embedded Data to capture data for single records or a list of records.

• Single Record Mode: Supports data entry via forms or combo-boxes. Forms can be created from scratch or contain previously created views on the Embedded Data object class. The combo-box control shows an existing list of pages where you can select a record and edit the data associated with that record. Example, you can select a hospital from a list that is associated to an appointment case.
• List of Records Mode: Enables data entry for multiple records simultaneously, such as entering multiple address details, using either a table format or by selecting existing records through repeating views. In a table display, you can add rows and fill in information. Repeating views are ideal for scenarios where there's a list of records, such as invoice line items for dispute, you can select one or more items and embed them as data within the case instance.

It is important to note that embedded data fields are not directly exposed for reporting purposes. These fields are stored in a Page or Page List structure and must be explicitly exposed by creating Declare Index rules.

For more details on Declare Index rules, you can refer to the Declare Indexes Performance Documentation.

Query 

A Query Field retrieves read-only data from a System of Record (SOR) by referencing a Data Page. The Data Page can include parameters used to query the source system when accessing the query field. 

A Query Field provides a convenient display of data (in read-only mode) that is stored outside of the main object.

The main difference between the Query and Data reference fields is that the Data Reference does not require key information (example- listing an instance of a Product or Customer data object). Additional details are included in the sections below.

Use Case Order Equipment

Let us walk through an example Case Type where these data fields are utilized to highlight their practical use. In this example a user, selects a product, adds customer information, and retrieves a shipping quotation. 

Step 1: Select a Product

The order process begins with the 'Select product' task, where users are required to choose a product from a provided list. The product data object can reside either within the same application or in any related build application. It holds product instances, including their property details, to define the specifications of each product.

• Data Object: Product
• Fields: Name, Size, Price 
• Recommended Field Type: Data Reference (Single record)
• Explanation: The product list is stored within the system, and the business requirements specify that users must select a product from this list, rather than manually entering the information. To ensure consistency, use a data reference field for this use case. This enables users to select standardized data already stored in the system. The selected product information is not stored in the case but is retrieved only when needed. This approach keeps the clipboard size small by referencing data only when required. 

When there is a need to display a list of page data and provide users the option to select one or multiple options, the data reference field type is the preferred choice.  

Selecting an item from a list can be achieved using the Picklist control, which can be configured to use a data page to retrieve data dynamically. There are two key differences between using Picklists and Data References.

The first difference lies in the data structure requirements. Data References provide ability to reference complex data structures, such as page lists or pages, enabling multiple selection of the data. In contrast, Picklists are typically used for simple data structures (like text or number values) and are limited to single-value selection.

a. Create the Data Reference in App Studio  

In App Studio, navigate to the Case Type Data Model tab and create a new Data Reference. Before creating a reference field, the data object to be referenced must already exist. In this scenario, the “Product” data object is already available in the system and can be referenced through a reference field.

b. Add the Data Reference to the view

In this case type one product can be chosen from an autocomplete dropdown (Data Page of type List is used to to render the instance(s) displayed). Additional product details are then shown when a product is selected.

c. Preview in User Portal

Preview the step in the User Portal.

Step 2: Enter Customer Information

Next, the customer provides personal details required for the order, such as Name, Email, and Shipping address. This is a typical data collection step that requires users to enter required information manually. 

• Data Object: Customer
• Fields: Name, Email, Phone, Address (incl. Country)
• Recommended Field Type: Embedded data (Single record)
• Explanation: This information is specific to the customer and is stored as a snapshot directly within the case. It does not need to be queried or referenced outside the case. The embedded data field is recommended here because the information is unique to the case and is stored with it. When complex data needs to be collected manually by end users, embedded data fields are the preferred option. They capture data and store it within the case, without referencing external objects outside a case.

           a. Create the Embedded Data in App Studio

           In App Studio, navigate to the Case Type Data Model tab and create a new Embedded Data referencing a customer object containing an Address Field. In this scenario, both” Customer” and “Address” data objects is already available in the system and can be referenced through a reference field.

          b. Add the Embedded Data to the view

          Add the Embedded Data to the view of the Enter Customer Information step.

          c. Preview in User Portal

          Preview the step in the User Portal.

Step 3: Retrieve shipping fee

The application retrieves a shipping fee based on the customer’s address and the selected product’s size. The information (product size and customer country information) gathered from previous steps are passed to an external system to retrieve a shipping quotation from external system. 

• Data Object: Shipping
• Fields: Fee, Destination, Parcel Size
• Recommended Field Type: Query Data Field (List of records)
• Explanation: Data can be pulled dynamically from a System of record like an external shipping service, based on the order's shipping address and product size. In this use case, the shipping fee is being pulled from a local record within the Shipping object.

         Both query fields and data reference fields are used to pull data without storing it in the case. The main difference lies in how they are used. A query field lets us view external data in read-only mode, meaning you can see the information but cannot interact with or change it. On the other hand, a data reference field retrieves data, and you can choose one or more items based on unique identifiers from the data source.

         a. Create the Query Field in App Studio 

         In App Studio, navigate to the Case Type Data Model tab and create a new Query of type List of records and select data source List of Shipping. In step c. change the data source as list of Shipping records by Country and Size.

         b. Switch to Dev Studio to configure a new Data Page and Report definition

         You configure a new Data Page and a Report Definition in Dev Studio. The Data Page requires two input parameters (Destination and ParcelSize). These parameters are passed to the Report Definition, which is the source for the Data Page, to filter and return the correct shipping fee.

Data Page Configuration

• Go to Records > Data Model > Data Page and create a new Data Page (or right-click and choose Create on the data class under App > …-data)
• On the Parameters tab, add the necessary parameters for the query.
• On the Data Sources tab:
  1. Set the structure to List.
  2. Set the correct class under Object type.
  3. Select Report Definition as the source and create a new one.
  4. Click the Parameters link and add Destination and ParcelSize parameters under the Data Sources section.

              Report Definition Setup

              Configure the Query tab of the Report Definition:

•             Add the required columns.
•            Click the gear icon on each filter and check "Use null if empty" to ensure the filter works with empty values.

                 On the Parameters tab of the Report Definition, configure any required parameters.

             c. Reference the Data Page in App Studio

                 Go back to App Studio and edit your Query.

                 Set the source to the Data Page you just created and configure any necessary parameters for the field.

            d. Add the Query to the View

                Add the Query Field to the view (shown as table) in the Retrieve shipping fee step.

                Configure the columns in the table to match the data returned from the query.

 

Comparing Data Reference and Query Field Types

During the creation of a Data Reference, regardless of the data relationship mode, Pega requires a data page. This data page passes parameter as a unique identifier, enabling it to populate every instance of the referenced data, so you can select it. 

The unique identifier is used to perform a database lookup, ensuring that the information from the reference data objects is always up to date. 

The key distinction between Data Reference Fields and Query Fields in Pega is how they manage keys. A Data Reference Field is used when a user selects a key, such as choosing a specific item from a list (example- selecting a product from a list of available products). On the other hand, a Query Field is used when the key is already available, enabling you to retrieve related data (example- country information or product size) that can then be used to fetch additional details from an external system.

Conclusion

In this article, we explored the three data field types in Pega Constellation and how they are used in a case type for placing an order. Embedded Data for capturing data inside a case, Data Reference for referencing and selecting data within the system and finally Query to query data from external systems or applications. Understanding these field types help us design efficient case flows that manage data in the right way, improving performance and usability.