Entity design pattern

Data Pages use aggregate sources and provide profiles to enable a centralized setup. In the Common Data Model, Data Pages have the following characteristics:

• They have multiple profiles (When Rules) defined on each Data Page based on the data access needs. For example, Profile_Acct_Detail is associated with the Get method, Profile_Acct_Create with the Post method, and Profile_Acct_Replace with the Put method.
• They connect to a data source by using a REST API. Predefined entities use REST to connect to the Pega database. You can modify the REST connection to call an external source.
• They are configurable for interaction with external APIs to connect to a data source.
• They use a single point of entry for all Data Pages and a single request and response mapping, which in turn calls the respective mappers.

Data Pages in the Common Data Model use a design pattern called Inversion of Control (IOC) that enables an application to receive the flow of control from a generic framework. Adopting applications can focus on mapping the system of record (SOR) to a logical Data Model (LDM) rather than building infrastructure. The following diagram shows the design pattern by using the D_Contact Data Page:

The D_Contact Data Page uses multiple profiles to perform data operations. Each profile is associated with a data operation, such as Get, Post, Replace, Delete. The CDM_Request and CDM_Response Data Transforms call the appropriate Data Transforms based on the profile and data source. Profile_Con_Detail returns the properties for a specified contact. The Con_Detail_Request Data Transform maps properties from the logical Data Model to the data source. The Con_Detail_Response Data Transform maps data from the data source to the logical model. If you use the Contact entity with an external data source, you map the properties in the Data Transforms for each profile.

The diagram also shows the flow of a Get request. The generic Data Transforms, CDM_Request and CDM_Response, use the profile information to identify the Data Transforms that map properties, such as Con_Detail_Request and Con_Detail_Response. The Data Page then invokes the service to connect to the data source. The Data Page caches the response from the data source.

The following figure shows the flow of control for a request and response for the D_Contact Data Page:

The Data Page uses a REST Connector API that is defined in Common-Interface-Contact in the Integration Layer. Depending on the profile and data source information, the Service Package invokes a method (Get, Post, Put, Patch, Delete and then calls the appropriate mapping Data Transforms for request and response. You can modify the request and response Data Transforms to work with your System of Record. These Data Transforms are shown in the App Explorer under each entity. The following figure shows the Data Transforms for the Contact entity:

Data sources

The design of the Common Data Model enables it to act as a system of record for entities, but it can also connect to external systems of record. The following figure shows the Data Sources section of the Account entity:

The Account entity connects to the Pega database by using the Acct REST connector. The following figure shows this API interface:

The Rules in the Common-Int class provide a sample design pattern for customers to connect to their external systems of record if needed. The Common Data Model includes one class in the Interface class structure for each corresponding entity class. Data Transforms map the data back and forth from the interface classes to the entity classes during operations through REST APIs called from Data Pages.

Saving data

Each entity has a savable Data Page to handle data operations. For example, the D_Contact Data Page manages the data for the Contact entity. The Data Page has the following design pattern:

• One Data Page for CRUD data operations.
• One profile for each of the CRUD driven by REST APIs.
• A single point of entry.

The following figure shows the Data save options section of the D_Contact Data Page:

The design pattern for the entity details Data Page provides the following benefits:

• You can understand one entity and apply that knowledge to all the others.
• You can extend the Entity Data Model and integrate it with new data sources.

Entity search or retrieval of a list of records

Each entity has one list Data Page to handle getting and managing a list of records. For example, to get a list of records for the Contact entity, you use the D_Contact_List Data Page. The Data Page has the following design pattern:

• The list Data Page contains multiple profiles that fetch a list of records.
• The list Data Page takes a profile, RelationType, and searchCriteria (JSON) as input, accepts filters dynamically, and returns the matching results.

The following figure shows some of the profiles used on the Contacts list Data Page:

Note that some of the profiles for D_Contact, for example Profile_Con_Summary_List_For_SvcAcct, search related entities for records associated with the contact.

All the entity and relationship Data Pages in the Common Data Model use a centralized, single set of Data Transforms for all requests and responses, mapping data from the integration with the system of record to the Pega logical Data Model.

All the request Data Transforms use CDM_Request. Based on the profile passed in as an input parameter, the request Data Transforms perform the following actions:

• Determine the name of the mapping Data Transform that is specific to each entity or relationship.
• Initialize the request pages (connectorPage and request).
• Determine the list of extensions to apply based on the application stack.
• Determine the list of Data Transforms to call according to the extension list.
• Call the list of Data Transforms in a Rule-resolved sequence.

All the response Data Transforms use CDM_Response. Based on the profile passed as an input parameter, the response Data Transforms perform the following actions:

• Determine the name of the mapping Data Transform that is specific to each entity or relationship.
• Initialize the response pages such as the (connector Page and Response).
• Determine the response data and response codes.
• Perform error handling.
• Apply the appropriate class context.
• Determine the list of extensions to apply based on the application stack.
• Determine the list of Data Transforms to call according to the extension list.
• Call the list of Data Transforms in a Rule-resolved sequence.
• Set additional fields as part of the response.

Data Transform structure

Data Page Rules invoke all logic by using SettingsPg as a parameter. It is a global page parameter that holds all the necessary settings for request and response Data Transforms.

While the wrapper Data Transforms handle all the logic, the system uses the mapping Data Transforms to map the data from the integration layer to the logical model. Each entity or relationship needs a mapping Data Transform to map the data.

All applications that use Pega as the system of record can use the automap feature, which maps the data automatically from the integration layer to the logical Data Model. The mapping Data Transforms are only for any conditional data formatting.

All applications that use an external system of record should use these mapping Data Transforms to map the properties from the integration layer to the logical Data Model.

Name the mapping Data Transforms based on the entity or relationship.

For more information about the Common Data Model, see Using centralized data transforms.