Configuring new event types
The main purpose of the event-driven architecture (EDA) engine is the reception of events and the running of processes on them. These two, events and processes, are the main data entities of the solution.
Each day, financial institutions receive high numbers of customer-related events, which might represent an increase in risk to their business. Financial institutions need to assess all events automatically and perform the necessary due diligence activities efficiently to understand any associated risk changes. Numerous systems generate many different types of events. For example:
- A change of registered address in Pega Customer Service™
- A complete name change from a third-party data provider
- An internal AML escalation from the Pega Client Lifecycle Management™ system
EDA is an infrastructural module that does not implement any specific events or processes. The architecture provides a framework in which financial institutions can define their own events and processes and manage them in an efficient and consistent manner. Learn how to define new event types that your application manages through EDA.
You define a new event type by completing the following steps:
- Creating a new payload class that represents the data model of each event type and handles basic aspects of the event, such as validation or visualization, through a UI gadget.
- Creating the payload data model to represent the event.
- Configuring the visualization of the event payload, which is a section rule that displays payload data.
- Configuring the event validation logic that the channel uses to perform an initial validation of the event payload after the reception of the event at the Validation phase.
- Configuring the event enrichment logic to enrich the event data in the same way that you use to validate the data at the reception of the event.
- Registering the event at the registry that contains, uniquely identifies, and associates all the different types of events with their corresponding data classes and with the processes to run on them.
1. Creating new payload class
The PegaFS-Data-EDA-Data-Event class represents all the events in the system. This class contains a set of properties that are common to all event types.
The following table lists the most important properties:
| Property | Description | Type |
|---|---|---|
| EventType | The type of event in the event registry. | String |
| EventSubtype | The subtype of event in the event registry. | String |
| EventPurpose | A description of the reason for the event. If you do not provide this parameter, the system uses the short description that is associated with the event type in the event registry. | String |
| Source | The name of the event producer system that sends the event. | String |
| Channel | The name of the channel by which the system received the event. | String |
| ExternalID | An identifier that the source gives to the event. The system uses that value for duplicate checks. | String |
| ReferenceKey | The type of reference to the main entity to which the event refers, such as customer identifier or transaction identifier. The logic that is specific to the event and process uses this parameter, but the engine does not. | String |
| ReferenceValue | The value of the reference to the main entity to which the event refers, such as the customer identifier value. The logic that is specific to the event and process uses this parameter, but the engine does not. | String |
| Data | The actual payload of the event that contains event-specific data. The class of the page extends the generic class PegaFS-Data-EDA-Data-EventPayload. | Page |
| Context | The processing options that are available for the event producer. The class of the page extends the generic class PegaFS-Data-EDA-Data-Context. | Page |
| EventID | A unique identifier of the event. | String |
This class and all the properties act as a generic envelope to the actual payload of the event, which is expected in the Data property. This property brings to the data model the polymorphism that is required to manage event types of very different natures. For example, in an event that represents a change of name, the property Data likely contains the previous name and the new name; in turn, in an event that represents a transaction, the property consists of the transaction identifier, the amount, the parties involved, and other related attributes.
The payload class manages the polymorphic nature of this property. Any new event type to accept in the system must be associated with a payload class. This association between the event type and the payload class is set up later during the event registration.
When you create the payload class, the location is the first aspect to consider. The EDA engine expects all payload classes to extend from PegaFS-Data-EDA-Data-EventPayload. For example, you can create the payload class for an event that represents a change of name as PegaFS-Data-EDA-Data-EventPayload-NameUpdate.
You can arrange payload classes as in any other class hierarchy, with inheritance, encapsulation, and extensibility as the main drivers for that arrangement.
In scenarios when the same data model represents different event types, you can define a single payload class and, at the time of registering the event types in the registry, make them all point to that class.
Create the payload class with the appropriate name, set up the inheritance to PegaFS-Data-EDA-Data-EventPayload, and define it as abstract.
2. Creating a payload data model
After creating the payload class for an event type, you define the data model to represent the event. For example, for an event that represents a change of name, you create properties to maintain the old name, the new name, and the effective date for the change.
The following figure shows an example of a data model for the payload of an event that represents a name update:
This process is similar to the creation of any other data model in a Pega Platform™ application. The only aspect to consider is that the data model that you define in this class is the one that the event producer needs to provide at the time of sending events into the system. For example, if the application uses the out-of-the-box REST/JSON interface, the data model that you define here defines the JSON message that is expected when the system receives an event. Therefore, ensure that your data model is straightforward and adjustable, and that rules can parse and map it.
3. Configuring the event payload visualization
Users and administrators might need to access the data of the event payload, either from the EDA operations console or from the modules that use the events. For that purpose, ensure that the payload class implements a section rule that displays its data. The section is later associated with the event type during the event type registration.
4. Configuring the event validation logic
After the event reception in the Validation phase, a channel performs an initial validation of the event payload. The validation logic ensures that the data that the system receives from the event producer is as expected. Two types of data usually require validation: basic event data, for example, the existence of a reference key or a reference value, and data specific to the event type payload.
You implement validations in data transform rules. To have visibility of all the event data and perform these validations, create the data transforms that run the event validation in the PegaFS-Data-EDA-Data-Event class, which gives access to the basic event properties and to the payload through the Data property. During the event type registration, users select the data transform that is applicable to validate each type of event.
For example, to validate an event type that represents a name change, you can create a ValidateFullNameEventPayload data transform in PegaFS-Data-EDA-Data-Event. The data transform can start by validating the presence of the basic fields (for example, the reference key), and then proceed with the event type-specific fields (for example, old and new names).
If the validation logic establishes that the event is not valid, ensure that the logic adds an EDA message to the event by using the EDAMessageLibrary data transform. The EDA engine detects the presence of the message and rejects the event.
The following figure shows an example of a validation data transform that checks the presence of the NameType field in the payload. If the field is not present, the data transform adds a message to the event so that the EDA engine can reject the event.
In this example, the validation logic at the event type level is a generic algorithm that ensures that the basic event data is present and valid. However, additional validations might occur at each of the processes that run on the event. This validation sets the focus on the essential event data.
5. Configuring the event enrichment logic
You can enrich the event data in the same way in which you validate the data at reception. Upon reception of the event and after its registration, the system invokes the data transform that is specified for the enrichment as defined in the event registry for this event type. This enrichment data transform is located in the class PegaFS-Data-EDA-Data-Event.
You can use enrichment to retrieve additional data about the event, for example, the customer segment to which the event is related or some additional details about a transaction that the event might mention. You can also use this logic to prepare the data for more efficient consumption at a later stage by the processes that are associated with the event.
If any error occurs during the enrichment process, the activity status notifies the EDA engine. This notification detects the situation and marks the event with an error.
The following figure shows an example of an enrichment data transform that, among other tasks, retrieves the registration address that is available in the customer master profile in a change of address event:
The additional data that this enrichment phase might produce is available later to all the processes; the event tracking table logs the event itself with the additional data. Therefore, ensure that the enrichment logic that you implement at this level is only for the data that is generic enough to use by all the processes, and obtain any data that is specific to a single process during the early stages of the process itself. This approach reduces the database footprint of the events in the system.
6. Adding the event to the registry
After creating the event data class and its associated rules, you register the event type in the EDA event registry. You register events in the EDA configuration console that you access by selecting . The registry displays all the event types that you configure in the EDA engine.
In the following image, click the + icons to learn about the information that you provide to register an event:
To add a new event type to the registry, click , and then configure the event details:
- In the Event name field, enter a short description of the event type that you want to register.
Ensure that the description is unique to help the user distinguish between different types of events. - In the Type and Subtype sections, enter short and meaningful identifiers of the type and subtype without spaces.
For example, you can represent the Confirmed Customer Data Change event type with the CCDC type, and an event subtype change of Legal name - Update as LGN-UPD.
When the system receives a new event through the EDA channel, the engine extracts its type and subtype from the message and uses that data to find the entry in the registry with its associated configuration. The type and subtype pair determine the processing of every event. Depending on the needs of your organization, you can follow different approaches at the time of naming the events and allocating types and subtypes. You might use the type to indicate the generic type of change that the event represents (for example, change of customer data, customer activity, screening) and the subtype to determine the exact nature of the event (for example, change of address or a card replacement request). You might choose to follow a completely different strategy too. - In the Classification parameter, select whether the event is a single event or a bundle.
In most scenarios, the events registered will be of type Event. However, in some scenarios, the processes that you create on top of the EDA engine can implement an event bundling feature. This approach uses special events to trigger the collection of all the events that are associated with a given bundle and then to process as a single unit. You can configure these special events in the registry as the type Bundle so that the associated processes can detect their special nature and act accordingly. - In the Description field, enter a summary of the event.
Use this field only to provide some more information to users about the content that is expected for that type of event. - In the Payload configuration section, in the Class and Section fields, enter a class name that defines its data model and basic features.
This class represents the event in the system. Choose the payload class of the event to register from the list of classes that the system prepares, which contains all classes that extend from PegaFS-Data-EDA-Data-EventPayload, the root class of all the payload classes. - In the Enrichment and validation section, in the Enrichment data transform field, enter the data transform that enriches event data upon receipt.
Only data transforms that you create in PegaFS-Data-EDA-Data-Event are available for selection. - In the Validation data transform field, enter the data transform that validates event data when the system receives the event.
Only data transforms that you create in PegaFS-Data-EDA-Data-Event are available for selection. - In the Processes section, in the Processes to execute field, select the processes to run on the event.
The system shows a list of all the processes that are available in the process registry. You can select one or more processes for a given event. When the system receives an event, the EDA engine ensures that all the processes that you select run, either immediately during the channel process or by dispatching them to a different domain. However, the system does not guarantee the order in which the processes run; some processes might even run in parallel threads. The order that you establish in this selection is not relevant at run time.
Check your knowledge with the following interaction:
This Topic is available in the following Modules:
If you are having problems with your training, please review the Pega Academy Support FAQs.
Want to help us improve this content?