Working with HCM Event Manager

This chapter provides an overview of the HCM (Human Capital Management) Event Manager feature, lists steps to implement it, and discusses how to:

• Define and register events.

• Create event handlers.

• Register event handlers.

• Test event handlers and events.

• Raise events.

• Monitor events.

• View event summaries.

• View help for Event Manager pages.

Understanding the HCM Event Manager

The HCM Event Manager is a feature and framework that enables you to define, implement, and run business logic for business events.

Using the Event Manager framework, you can define the business events that the system raises when you change certain data in application components or run certain PeopleTools Application Engine processes. You can also define the event handlers that the Event Manager framework executes to react to these specific event instances. Raising an event is the act of creating an event instance. If an event is raised, the Event Manager framework automatically executes the business logic for the registered event handlers of the event.

Advantages of the Event Manager Framework

Using the Event Manager framework has several advantages. One of the major advantages is improved processing performance. The Event Manager framework enables you to manage your business events around the business objects that define the events. By isolating the reactionary business logic within events and event handlers, you improve performance because you no longer have mainline business processes embedded with time-consuming code that runs in the background as part of its critical path. The Event Manager framework provides a simple mechanism for isolating, automatically processing, and monitoring the business logic asynchronously.

Another advantage is that you can define your own business events and build your own event handlers for these events with minimal impact to the delivered code.

A third advantage is that through the event monitoring components, you have much greater processing detail which assists when troubleshooting.

Events and Event Handlers

Use the Event Registry component to register business events and register event handlers to business events so that they are available to the Event Manager framework. Business events are the functions in a business environment, such as adding a person, changing an employee's compensation rate, terminating an assignment, promoting an employee, and so on. PeopleSoft Human Resources delivers many events ready for use. You can also have a developer create and register additional events in PeopleTools Application Designer. After the events are created, you register events in the Event Registry component. Event handlers are modules of business logic that react to instances of particular events to which they are registered. You must register event handlers to events so that the Event Manager framework executes the event handlers whenever the event is raised. All properties and methods of the event instance (most notably the event keys) are available to the event handler during execution.

You can assign multiple event handlers to a single business event, and you can assign a single event handler to react to multiple events. When defining events in the Event Registry component, you can assign event handlers to function in either synchronous mode or asynchronous mode with respect to the process that raises the associated event. When a process raises a registered event, the Event Manager framework determines whether the event handlers that are registered to that event are synchronous or asynchronous. If an event handler is synchronous, the Event Manager framework executes that event handler inline as part of the process that raises the event. If the event handler is asynchronous, the Event Manager framework executes the event handler as a detached process that is out of the critical path of the mainline process. You can register both synchronous and asynchronous event handlers concurrently to the same event. The Event Manager framework executes the registered event handlers in whichever mode you configure them to operate, always executing synchronous event handlers first. When defining event handlers for registry in multiple events, you should include some code in the event handler to examine the Name property of the passed-in event object so that you know which type of event caused the event handler to be executed.

The Event Manager framework is based upon a simple notify and respond model. For the notification side, the Event Manager framework broadcasts that event has occurred, along with the data that caused the creation of the event instance. For the respond side, the individual applications link business logic into the Event Manager framework to respond to the business event. By linking PeopleTools Application Classes to the event in the Event Registry component, the Event Manager framework knows when to execute the registered event handlers for the event when the event is raised.

When you raise an event through a component or PeopleTools Application Engine process, the system creates a unique event instance for each business event. These event instances are a signal to the Event Manager framework that an event happened. Event instances are specific objects in the system and contain underlying data regarding the event occurrence. This data varies depending on the event.

An event handler that fails during execution causes a disruption to the execution of any other event handlers for that event or the mainline process. The Event Manager framework therefore provides many options for monitoring and troubleshooting event handlers and events. You can monitor event instances and the executions and exceptions of the event handlers through the Event Monitor component or the Event Summary component. You can also test event handlers and events outside of the mainline business process through the Handler Tester component and the Event Tester component.

Local and Remote Nodes

The Event Manger framework enables you to manage events that have influence over more than one database instance. You can use the Event Manager framework to process business events that occur on either a local or remote database (also called a node). A remote node can execute only event handlers that are implemented locally and registered to events in its local event registry. For example, an event that is raised in an HCM database might be important to a separate PeopleSoft Enterprise Learning Management (ELM) database or a PeopleSoft Financials database.

The Event Manager Framework is currently not integrated with the Service Oriented Architecture (SOA) distributed registry. Instead, each database has its own local event registry. Within a local event registry, you can define events that you can raise by local process as well as events of interest to applications on the local database that are raised by remote databases. To support the processing of an event in a remote database, remote databases must implement the Event Manager framework. Also, each local event registry must contain entries for the remote events of interest along with their associated local event handlers.

From the perspective of the Event Manager framework, virtually no difference exists between the way that asynchronous handlers are supported for remote events and local events. You register event handlers to events in the event registry, configuring the Event Manager framework to execute event handlers for events that are raised in the local database, a remote database, or both types of databases. Thus, a single event handler can respond to instances of the same event that are raised on the local database as well as a remote database.

Event handlers for remote events are by definition asynchronous. Thus, on the local database the Event Manager framework executes these remote events only after completing the execution of synchronous handlers that you have registered for the event.

Example: Local Event with Synchronous Event Handlers

This example illustrates the processing of a mainline business process on a local database using an event with two registered synchronous event handlers:

Local event with synchronous handlers

In this scenario, the mainline business process calls the application program interface (API) for the Event Manager framework to raise the event. The framework executes inline the two event handlers in order, publishes the generic PeopleTools Integration Broker event message, and then returns processing control back to the mainline business process.

Note. The generic PeopleTools Integration Broker event message contains coding that is similar to XML language that provides the event name, event keys, and node that raised the event.

Example: Local Event with Asynchronous Event Handlers

This example illustrates the processing of a mainline business process on a local database using an event with two registered asynchronous event handlers:

Local event with asynchronous handlers

In this scenario, the mainline process calls the API for the Event Manager framework to raise the event. The framework immediately publishes the generic PeopleTools Integration Broker event message, and returns processing control back to the mainline process without delay. A normal PeopleTools Integration Broker local subscription picks up the generic event message and invokes the framework to execute the asynchronous event handlers that are registered to the event.

Example: Local Event with Both Synchronous and Asynchronous Event Handlers

This example illustrates the processing of a mainline business process on a local database using an event with two registered synchronous handlers and two registered asynchronous event handlers:

Local event with both synchronous and asynchronous handlers

In this scenario, the mainline process waits while the Event Manager framework executes the synchronous event handlers. The Event Manager framework executes the asynchronous event handler as detached processes launched by the local subscription to the generic PeopleTools Integration Broker event message.

Example: Remote Event

This example illustrates event processing that spans across local and remote databases:

Remote event

In this scenario, the event is registered in the local event registry (Registry A) and a remote event registry (Registry B).

In Registry A, the event has both registered synchronous and asynchronous event handlers. The event handler that is registered to this event is set for a local source. When the event in raised in Registry A, the Event Manager framework logs the event (if it is configured for logging), publishes the generic event message, executes synchronous event handlers that are registered to the event, and then subscribes locally to the generic event message to execute asynchronous event handlers that are registered locally to the event.

Registry B has the same event active in its local event registry. The event handler that is registered to this event is set for a remote source. Because Registry B subscribes remotely to the same event message that Registry A publishes, Registry B logs the occurrence of the event and then executes the registered asynchronous handler.

Rules for Extending HCM Event Manager

When you are creating custom events and event handlers to extend the delivered objects within the Event Manager framework, you must adhere to the following rules to ensure that delivered upgrades and fixes do not affect your extension:

• Never indicate that the events that you develop are system data.

• Always create application classes for new event definitions in one or more new, nondelivered application packages, never in delivered application packages.

• Always create new event handlers in one or more new, nondelivered application packages, never delivered application packages.

Common Elements Used in This Chapter

Steps to Implement the HCM Event Manager

To implement the HCM event Manager into your application processing:

1. Identify the business events that drive the execution of your business logic and, if necessary, define a new event.

   In many cases, the event is already defined in the local event registry that is accessible through the Event Registry component. If the event is not yet defined, you must define a new business event. To define a new event:

   1. Create an Application Class in PeopleTools Application Designer.

      Generate the code for this application class through the Define Events page of the Event Registry component, or use the template code that is provided in this chapter.

   2. Register the event to the Event Manager framework through the Event Registry component.

2. Write the event handlers in PeopleTools Application Designer to execute the business logic that is specific to the event.

   To develop an event handler, create an Application Class with a method named ProcessEvent() that includes the Event Manager interface code that is provided in this chapter. Event handlers can be for one or more business events.

3. Register the event handlers to the event through the Event Registry component.

4. Test your event and its registered event handlers.

   To test event handlers and events:

   1. Test the event handler in standalone mode through the Handler Tester component.

   2. Test the event independent of the business process that raises the event through the Event Tester component.

   3. Test the event in the context of the business process by executing the business process that raises the event through the component or PeopleTools Application Engine process.

      The Event Manager framework automatically executes the registered event handlers for an event when you raise the business events.

Defining and Registering Events

To register business events and their event handlers, use the Event Registry (HCR_EM_REGISTRY) component.

This section provides an overview of new events and discusses how to:

• Create an application class for a new event.

• Register events to the Event Manager framework.

Understanding New Events

Occasionally, you need to create new events that you can raise in the system for use by the Event Manager framework. As stated in the chapter overview, the first step is to identify the business events that drive the execution of your business logic and, if necessary, define a new event. Recall that to define a new event you must:

• Create a new application class for a new event in PeopleTools Application Designer.

• Register the new event to the Event Manager framework through the Event Registry component.

If you want to register a new event handler to an existing business event, you can bypass this step.

Page Used to Define and Register Events

Creating an Application Class for a New Event

Each event in the Event Manager framework must have a corresponding application class. Use PeopleTools Application Designer to create a new application class for a new event. The application class can reside in any application package, but you must place it under the subpackage called Events. Depending on the nature of the business event, you should create the application class in either the Core HR application package or an application package that is owned by some other PeopleSoft product or module (such as a PeopleSoft Global Payroll country extension). The owner of the application package in which you define the application class for the event is the owner of the event and should therefore be responsible for creating and maintaining the code that raises the event.

To create a new application class for a new event:

1. Decide in which application package you will create the application class for the new event.

   When you have decided this, you can use the Define Events page of the Event Registry component to automatically generate the class definition code.

2. Select Set Up HRMS, System Administration, HCM Event Manager, Event Registry.

3. Select the Add a New Value tab.

4. Enter the name of the new event (for example, MyNewEvent) in the Event Name field, and click the Add button. The system displays the Define Events page.

5. Click the Generate Event Class Code button in the Event Class Definition group box to have the system automatically create the PeopleCode that is necessary to define the new application class for this event.

   See Registering Events to the Event Manager Framework.

6. Highlight all of the code in the Event Class Code group box, and copy it to your clipboard.

   Note that you will not be able to save the page because you have not yet created the required information about the application class.

7. Access PeopleTools Application Designer to edit the application package in which this new event definition resides.

   For example, perhaps you are creating an event application class in the HR_EVENT_MGR_DEMO root package.

8. Create the new application class for the new event in the Events subpackage.

   The name of the new application class must be the same as the event name that you defined in the Event Registry component. The root application package must contain a subpackage called Events, and you must create the application class as part of this subpackage. The structure of your application package, for example, might be HR_EVENT_MGR_DEMO:Events:MyNewEvent. Optionally, you can use second-level application packages to organize your application classes. Thus, if you use a second-level application package called Person to group all person-related events together, then the structure of your application package would be HR_EVENT_MGR_DEMO:Events:Person:MyNewEvent.

9. Double-click the new application class to edit the OnExecute PeopleCode program for it.

10. In the edit window that the system displays, paste the system-generated code that you copied from the Define Events page.

    For reference, you can use the following code to implement an event class definition:

    import HCR_EVENT_MANAGER:Base:baseEvent;
    
    class MyNewEvent extends HCR_EVENT_MANAGER:Base:baseEvent;
       
       /* Constructor */
       method MyNewEvent(&EventName as string);
        
    end-class;
    
    method MyNewEvent
       /+ &EventName as string +/
       %Super = create HCR_EVENT_MANAGER:Base:baseEvent("MyNewEvent");
    end-method;
    

11. Click Save.

This completes the PeopleTools Application Designer portion of defining a new event.

Registering Events to the Event Manager Framework

Access the Define Events page.

Important! The application class that you reference here must already exist in the database. If you are creating a new business event and have not yet created the associated application class, first use the Generate Class Code button to create the PeopleCode that you must use when creating the application class. Note that you will not be able to save the page because you have not yet created the required information about the application class. Create the application class for the event in PeopleTools Application Designer. Afterwards, return to this page to register the event with the Event Manager framework.

Key Signature (Info Only)

This group box is primarily for information purposes. It displays the keys for the event and the record from which the system derives these keys.

When an event is raised, the system associates this set of keys with the event instance. These event keys enable an event handler to associate an event instance with a specific object in the database, such as a particular employee or job data row. Each instance of the event has the same event keys but different key values.

Event Class Definition

The Event Manager framework requires that you represent each business event with a simple application class. Use this group box to establish the link between the business event and its application class.

Event Class Code

This group box displays the OnExecute PeopleCode for the new application class that you must create for the event in PeopleTools Application Designer. The group box appears when you click the Generate Event Class Code button.

Copy the generated code and save the page. Then open PeopleTools Application Designer and create the application class for the business event, pasting this code into the OnExecute program. Return to this page and select values for the Application Package and Path fields for the new application class that you just created in PeopleTools Application Designer.

Creating Event Handlers

An event handler is the application-specific code that responds to a particular type of event. You must register event handlers to events so that when an event is raised, the Event Manager framework executes the appropriate event handlers.

Requirements for Creating Event Handlers

To be compatible with the Event Manager framework, when creating event handlers, you must implement all business logic for the event handlers to abide by the following set of standards and code requirements:

• You must implement the entry point to the event handler in a method named ProcessEvent() within an application class.

  The Event Manager framework executes the ProcessEvent()method whenever the associated event is raised. Within the ProcessEvent() method, you are free to reference or execute code in other methods, classes, or function libraries. This application class can be an extension of any other application class if necessary.

• You can create the event handler in any new or existing application package within your application, but you must create the event handler under the Handlers subpackage.

• The application class and the application package that it resides in must be owned by the application, not the Event Manager framework.

• You must import the baseEvent class definition from the Event Manager framework application package into the application class that implements the event handler.

  The ProcessEvent() method in the application class of the event handler receives as an input parameter an instance of this baseEvent class object. This baseEvent class object represents the event instance that caused the Event Manager framework to execute the event handler, thus giving you access to the underlying properties and methods that are associated with the event that caused the Event Manager framework to execute the event handler. At a minimum, the event handler code must access the event keys to perform meaningful processing.

• If you want to be able to communicate detailed errors, warnings, or any other messages back to the Event Manager framework, then you must populate the HandlerStatus property with appropriate entries.

  The HandlerStatus property is a complex property that is part of the baseEvent object that the Event Manager framework makes available to the event handler. The structure of this property is defined by HCR_EVENT_MANAGER:Base:Types:ExecStatusType. The property contains both an overall status indicator and an exception array. The Event Manager framework examines the contents of this property after executing this class and take appropriate action.

  The HandlerStatus complex type also carries a method that facilitates appending an entry to the ExceptionArray structure. This method is named AddException() and takes as an argument the structure defined by HCM_EVENT_MANAGER:base:Types:ExceptionType.

  Note. The Event Manager framework automatically creates an exception entry that lists the event keys that were made available to the event handler. The system displays these event keys in the pages of the Event Monitor component.

  The structure within the HandlerStatus property is:

  • ExecutionStatus (string – values "S"uccess, "F"ail)

  • ExceptionArray (array):

    EXCEPTION_TYPE (string – values "E"xception, "K"eys, "T"race)

    MESSAGE_SET_NBR (number)

    MESSAGE_NBR (number)

    MSG_SEVERITY (string – values "M"essage, "W"arning, "E"rror)

    MESSAGE_TEXT (string)

    EXPLAIN_TEXT (string)

Details of the baseEvent Class

When the Event Manager framework invokes the baseEvent class, it passes the baseEvent class into the ProcessEvent() method of the application class of the event handler. This enables you to use the properties and methods of the bass class to obtain more information about the event instance to direct internal processing of the event.

This table lists public properties of the event object that are of interest to application developers who are implementing the Event Manager framework:

This table lists public methods of the event object that are of interest to application developers who are implementing the Event Manager framework:

&myType = &myEvent.GetKeyType("EMPLID");

Local Number &myKeyvalue;    
&myKeyValue = &myEvent.GetNumericKey("EFFSEQ");

    Local String &myKeyvalue;    
&myKeyValue = &myEvent.GetCharacterKey("EMPLID");

    Local Date &myKeyvalue;    
&myKeyValue = &myEvent.GetDateKey("EFFDT");

Event Handler Skeleton Code

You can use the following skeletal code as a starting point when building an event handler class:

import HCR_EVENT_MANAGER:Base:baseEvent;
import HCR_EVENT_MANAGER:Base:Types:ExceptionType;   /* Optional */

class myHandlerClass
   /* Dummy Constructor */
   method myHandlerClass ();

   method ProcessEvent(&inEvent As HCR_EVENT_MANAGER:Base:baseEvent);
   
private
   instance HCR_EVENT_MANAGER:Base:baseEvent &myEvent;   /* if you want to access  the event elsewhere */
   
end-class;

method myHandlerClass
end-method;

method ProcessEvent
   /+ &inEvent as HCR_EVENT_MANAGER:Base:baseEventHandler +/

   /* The following 2 lines are required only if you want to pass detail info about    */
   /* Errors, Warnings or other Messages back to the Event Manager framework. */
   Local HCR_EVENT_MANAGER:Base:Types:ExceptionType &myExceptionEntry;
   &myExceptionEntry = create HCR_EVENT_MANAGER:Base:Types:ExceptionType();
  
   &myEvent = &inEvent;  /* if you want to access  the event properties and methods elsewhere in this class */
/* =================================================== */
/*------------------------- Business Logic goes here  ---------------------------- */
/* =================================================== */
End-method;

Within the preceding code, the following lines are the minimum lines that are required to interface an event handler named “myHandlerClass” to the Event Manager framework:

import HCR_EVENT_MANAGER:Base:baseEvent;

   method ProcessEvent(&inEvent As HCR_EVENT_MANAGER:Base:baseEvent);
   

method ProcessEvent

Addressing Errors and Warnings

During execution, an event handler might encounter errors, warnings, or other issues that a user needs to be made aware of. In most cases, you want to pass this information back to the Event Manager framework so that users can view the information through the Monitor Events component. Although you do not have to pass this information back to the Event Manager framework, the more information that you do pass back, the easier it is for the administrator to resolve the problem.

The Event Manager framework uses a simple exception-array scheme to receive status information that is passed back to it from an event handler and subsequently displays that information in the Monitor Events component. The structure of the exception array is the same as the structure of a message in the message catalog. It contains a message set number, message number, severity level, message text, and explanation text in each row of the array. The message set number and message number are significant only if the information that you want to pass back to the Event Manager framework is described in a Message Catalog entry. If not, you can leave these two properties blank and just populate the message text, explanation text, and severity properties.

As mentioned previously, the event object that is passed into your event handler contains a complex property that is used to communicate the status of your event handler. At a minimum, you should populate the overall-status simple property with either (S)uccess or (F)ail prior to quitting your ProcessEvent() method. If you do not populate the overall status property, the Event Manager framework assumes that the event handler executed successfully. PeopleSoft recommends that you pass back information through the exception array of the complex property, although this is optional. For example, if the event object is passed into your handler as &inEvent, you populate the overall status property as:

&inEvent.HandlerStatus.ExecutionStatus = "S";     /* Handler terminated successfully */

You never have to deal directly with the exception array that is embedded in the event object that the event handler receives. Instead, whenever you want to add an item to this array, you call the AddException() method, thus passing in an object that the system has already populated with exception information. This object that you pass in is an instance of the ExceptionType TypeClass. This class has the following properties:

• Message Set Number

• Message Number

• Message Severity

• Message Text

• Explain (Long) Text

The following example shows how to add a message to the exception array for a message that does not come from the Message catalog, assuming that the event object is passed into your event handler as &inEvent:

&myExceptionEntry = create HCR_EVENT_MANAGER:Base:Types:ExceptionType();

&myExceptionEntry.MESSAGE_SET_NBR = 0;
&myExceptionEntry.MESSAGE_NBR = 0;
&myExceptionEntry.MSG_SEVERITY = "M";
&myExceptionEntry.MESSAGE_TEXT = "Hello World!";
&myExceptionEntry.EXPLAIN_TEXT = "";

&inEvent.HandlerStatus.AddException(&myExceptionEntry);

For a Message Catalog entry, you must include the message set number and the message number. You must also retrieve the text and explain text from the Message Catalog because substitution tokens might be involved that the Event Monitor framework cannot pass or resolve.

Note. If you use the AddException() method to create an exception array entry with the MSG_SEVERITY property set to (E)rror, then the system automatically sets the overall execution status indicator for the event handler to (F)ail. This means that you do not need to separately set the overall status property.

Note. The Event Manager framework executes all event handlers that you register to an event. If a particular event handler fails, the Event Manager framework still executes the remaining event handlers that are registered to the event. The Event Manager framework can catch exceptions that an event handler raises rather than terminating before it has finished executing all of the registered event handlers. However, the Event Manger framework does not contain any exception processing or error handling subsystems, and because of this you must ensure that event handler code does not raise an exception that the Event Manager framework cannot catch. One such exception is the PeopleCode error statement. Therefore, you must never raise an exception for an error statement in your event handler. Otherwise, the Event Manager framework stops and does not execute any remaining event handlers that are registered to the event.

Component Interface and SOA Service Exceptions

PeopleSoft Human Resources anticipates the use of Component Interfaces (CIs) and Service Oriented Architecture (SOA) services to be fairly common within event handlers. The Event Manager framework therefore provides assistance to facilitate passing exceptions from these sources back to the Event Manager framework and ultimately into the Event Monitor component.

The system displays exceptions that are raised by CIs or SOA services on the Handler Exceptions page of the Event Monitor component, much like any other exceptions that are written to the log. For severity information, the system prefaces the message with “[CI] ” or “[SOA]”, respectively.

The structure of the event-handler exception log is similar to the exception structure within PeopleTools for CIs and within the SOA framework for SOA services. Essentially, you must pass these exceptions back to the Event Manager framework when they arise. Two methods are available within the Event Manager framework that enable you to do this easily. One method is:

.HandlerStatus.AddCIException(&arrExceptions as array of Record, &Severity as string)

This method copies all exceptions from a standard CI exception array to the exception log of the event handler according to the specified severity of the exception. Severity codes are (E)rror, (W)arning, and (M)essage.

You can specify multiple severity codes by concatenation. Thus, if you want to copy both errors and warnings, then specify a severity code of EW. A blank severity code causes the copying of all exceptions regardless of severity.

The structure of the exception array that is passed into this method is identical to the exception array that the FUNCLIB_CI version of the standard HCM CI wrapper uses. This is an array of Record.CI_EXCEPTIONS. If you're using the FUNCLIB_CI wrapper, you can pass the exception array that you use with those functions into this method.

If you are calling a CI directly, then you need to first ensure that you have instructed PeopleTools to redirect CI exceptions from the screen to the %Session.PSMessages object. Then, you need to copy the items from PSMessages into an array of Record.CI_EXCEPTIONS so that these exceptions can be passed into this method.

Another method is:

.HandlerStatus.AddSOAException(&inException As HMCR_TYPES:ExceptionTypes:ExceptionType_v1_0:ExceptionType)

This method copies all exceptions from a standard SOA exception type structure to the exception log of the event handler.

When invoking SOA services, the system always executes them in a try/catch block. Typically, the event handler executes the services and catches certain defined exceptions that arise. A catch-all exception always catches any exceptions that have not been specifically called out.

SOA exceptions differ slightly from CI exceptions in that when invoking an SOA service, you manage only one (if any) exception. The exception that you pass into this method is the exception structure that you catch in your try/catch block.

The following example shows an SOA service invocation passing exceptions back to the Event Manager:

     *      try
     *        &MyService.MyServiceManager.LocateService(&ServiceName); 
     *        &MyService.DoService();
     *          catch <NamedException1> &e1
     *                &myEvent.HandlerStatus.AddSOAException(&e1.ServiceException);
     *                --- other exception processing ---
     *          catch <NamedException2> &e2
     *                &myEvent. HandlerStatus.AddSOAException(&e2.ServiceException);
     *                --- other exception processing ---
     *          . . .
     *          catch HMCR_FRAMEWORK:ServiceFramework:baseClasses:baseException &e0    
     *                &myEvent. HandlerStatus.AddSOAException(&e0.ServiceException);
     *                --- other exception processing ---
     *      end-try 

In this code, the items appearing as <NamedExceptionX> represent the application-specific exceptions that are registered in the SOA registry. These are exceptions that are known to be thrown by the indicated SOA service. The class named HMCR_FRAMEWORK:ServiceFramework:baseClasses:baseException is for the catch-all exception, defining the shape of the generic SOA exception.

Providing Trace/Debug Information

The Registered Handlers page of the Event Registry component provides a Trace check box to indicate whether to write trace/debug information to the execution log of the event handler. This functionality is available only when you set the Logging field for the event handler to the All value.

When you select the Trace check box, the event handler produces trace/debug in the handler execution log. The amount of trace/debug information that the system writes to the log is determined by the developer of the event handler. Generally, you must provide enough information so that anyone examining the event handler log can trace the path of the execution that the event handler has taken.

The system makes the selected value of this check box available to the event handler using the HandlerTraceEnabled Boolean property of the event. When this property is True, the event handler creates trace/debug entries in the exceptions structure. PeopleSoft software provides the following method to make the creation of these entries easier:

&myEvent.HandlerStatus.AddTraceEntry(&Heading, &Detail);

In the preceding code, &Heading is the string that appears as the first line of the entry, and &Detail is a long string containing whatever detailed trace/debug information you want to create.

The system displays the trace/debug information in the Event Monitor component. For example:

This entry was from the following code:

&myEvent.HandlerStatus.AddTraceEntry("Sample Trace Entry","More detail about the state of the Handler execution.");

No fixed rules are associated with the trace/debug entries that the event handler generates. This is a judgement call. You should provide whatever entries you think are useful to debug or troubleshoot the event handler code.

Create trace/debug entries only when the .HandlerTraceEnabled property is True. Thus, the code looks similar to:

   If &myEvent.HandlerTraceEnabled Then
      &myEvent.HandlerStatus.AddTraceEntry("Method ABC()", "No data returned for: " | &Emplid);
   End-If; 

Sample Event Handler Code

This section provides an example of a working event handler that responds to the ProfileItemUpdated event.

This event handler examines the underlying event to determine whether the profile item that raised the event belongs to a Person profile. If so, and if the profile item represents a manager's evaluation of a competency, then the system deletes the corresponding item from the manager's To Do list. The application class is JPM_ItemHandler, which resides in an application package named JPM_SYNDICATION.

The code for this event handler is:

import HCR_EVENT_MANAGER:Base:baseEvent;
import HCR_EVENT_MANAGER:Base:Types:ExceptionType;    /* We'll be passing exceptions back */

class JPM_ItemHandler
   /* Dummy Constructor */
   method JPM_ItemHandler();

   method ProcessEvent(&inEvent As HCR_EVENT_MANAGER:Base:baseEvent);
   
private
   instance HCR_EVENT_MANAGER:Base:baseEvent &myEvent;
   
end-class;

method JPM_ItemHandler
   /* Dummy Constructor */
end-method;

method ProcessEvent
   /+ &inEvent as HCR_EVENT_MANAGER:Base:baseEvent +/

  Local HCR_EVENT_MANAGER:Base:Types:ExecStatusType &myStatus;
  
   /* We define the ExceptionType object because we want to pass detailed info        */
   /* about the execution of this method back to the Event Manager framework.          */
   Local HCR_EVENT_MANAGER:Base:Types:ExceptionType &myExceptionEntry;

  &myEvent = &inEvent;        /* Make the Event object available throughout the class */

  /* Get the Event Keys – these vary, depending upon the Event – for this event, there are 6 keys */
  Local Number &keyProfileID = &myEvent.GetNumericKey("JPM_PROFILE_ID");
  Local String &keyCatType = &myEvent.GetCharacterKey("JPM_CAT_TYPE");
  Local String &keyCatItemID = &myEvent.GetCharacterKey("JPM_CAT_ITEM_ID");
  Local String &keyCatQUAL1 = &myEvent.GetCharacterKey("JPM_CAT_ITEM_QUAL1");
  Local String &keyCatQUAL1 = &myEvent.GetCharacterKey("JPM_CAT_ITEM_QUAL2");
  Local Date &keyEffdt = &myEvent.GetdateKey("EFFDT");


  /*------------------------- Business Logic starts here  ---------------------------- */
  /* The profile item that raised the event is identified by the keys above. */
  /* If this is a "Person" profile, and the Item is a Competency, and           */
  /* and the Evaluation Type is "M", then delete the corresponding entry  */
  /* from the manager's "To-Do" list.                                                           */

  Local string &ProfileEmplid, &OwnerEmplid;

  If &keyCatType = "COMPETENCY" And &KeyCatQUAL1 = "M" Then
     SQLExec("SELECT EMPLID, JPM_OWNER_EMPLID FROM PS_JPM_PROFILE WHERE   JPM_PROFILE_ID = :1", &ProfileEmplid, &OwnerEmplid,
 &keyProfileID);
     If All(&ProfileEmplid, &OwnerEmplid) Then

        /* This is a "Person" profile, and there is an Owner ID – delete the corresponding ToDo entry */
        SQLExec("DELETE FROM PS_JPM_TO_DO_LIST WHERE JPM_OWNER_EMPLID=:1 AND JPM_PROFILE_ID=:2 AND JPM_CAT_TYPE=:3 AND JPM_CAT_ITEM_ID=:4",
&OwnerEmplid,   &keyProfileID, &keyCatType, &keyCatItemID);

     End-If;
  End-If;

   /* As an example – we'll send some detail status back to the Event Manager Framework */
  &myExceptionEntry = create HCR_EVENT_MANAGER:Base:Types:ExceptionType();

  &myExceptionEntry.MESSAGE_SET_NBR = 9999;
  &myExceptionEntry.MESSAGE_NBR = 1234;
  &myExceptionEntry.MSG_SEVERITY = "M";
  &myExceptionEntry.MESSAGE_TEXT = "Hello World!";
  &myExceptionEntry.EXPLAIN_TEXT = "";
  &myEvent.HandlerStatus.AddException(&myExceptionEntry);

  &myExceptionEntry.MESSAGE_SET_NBR = 0;
  &myExceptionEntry.MESSAGE_NBR = 0;
  &myExceptionEntry.MSG_SEVERITY = "M";
  &myExceptionEntry.MESSAGE_TEXT = "Everything is Just Fine!";
  &myExceptionEntry.EXPLAIN_TEXT = "";
  &myEvent.HandlerStatus.AddException(&myExceptionEntry);

  If &myEvent.HandlerTraceEnabled Then
     &myEvent.HandlerStatus.AddTraceEntry("Sample Trace Entry","Trace Detail Information.");
  End-If;
   /* -------------------------------  End of Example Detail Status ----------------------------- */

End-method;

To be compatible with the Event Manager framework, the framework requires the following lines from the preceding code to be present in event handler code:

import HCR_EVENT_MANAGER:Base:baseEvent;
import HCR_EVENT_MANAGER:Base:Types:ExceptionType;    /* We'll be passing exceptions back */


   method ProcessEvent(&inEvent As HCR_EVENT_MANAGER:Base:baseEvent);
   

method ProcessEvent

Registering Event Handlers

This section discusses how to register event handlers to business events.

Page Used to Register Event Handlers

Registering Event Handlers to Business Events

Access the Registered Handlers page.

Note. The number of different events to which you can register a particular event handler is not restricted.

Handler Implementation

Handler Options

Logging/Trace

Testing Event Handlers and Events

This section provides an overview of event testing and discusses how to:

• Test an event handler.

• Test an event.

Understanding Event Testing

Generally in a production environment, you raise events by making a change to application data through a component or by running a PeopleTools Application Engine process. When the event is raised, the Event Manager framework executes the event handlers registered with the event as defined in the Event Registry component. When testing events, you should begin at the lowest level, which is the event handler, and then work your way up to the highest level, which is the business process that raises the event. Thus, to test events:

1. Test the event handler in standalone mode through the Handler Tester component.

2. Test the event independent of the business process that raises the event through the Event Tester component.

3. Test the event in the context of the business process by executing the business process that raises the event through the component or PeopleTools Application Engine process.

Pages Used to Test Event Handlers and Events

Testing an Event Handler

Access the Event Manager - Test an Event Handler page.

Event

Select the event to which the event handler that you want to execute is registered. Event handlers must always execute within the context of an event.

Record

When you select an event, the system displays the default record that is associated with the event in the Key Signature group box on Event Registry component. The system uses the record to define event keys, which provides the key signature for this event. Typically, this is the record in the database from which a data change normally raises the event. You can select a different record besides the default record. The record must have the same keys as the record that normally raises the event. The system displays in the Registered Handlers group box the event handlers that are registered with the selected event in the local database through the Event Registry component. The system also displays the keys in the Event Keys grid so that you can enter key values.

Registered Handlers

This group box displays the event handlers that you have registered with the selected event in the Event Registry component.

Handler Exceptions

Use this group box to view results of the event handler execution. The system displays event keys, exceptions, and trace information that is associated with the execution of the event handler.

Event Keys

Use this group box to enter values for each of the event keys that are part of the selected event and record. These are the values that the system passes into the event handler during the test. The system does not perform any validation on the data that you enter in the Value fields. Be sure to enter the correct format for data values and use uppercase or lowercase values for character data as appropriate. The system makes these key values available to the event handlers just as if you raised the event from within the application.

Testing an Event

Access the Event Manager - Raise an Ad-Hoc Test Event page.

Event	Select the event that you want to raise. You can only raise events that are active in the local event registry. If you are unsure of the status of an event, select the event in the Event field and click the Event Info button.
Record	When you select an event, the system displays the default record that is associated with the event in the Key Signature group box on the Event Registry component. The system uses the record to define event keys, which provides the key signature for this event. Typically, this is the record in the database from which a data change normally raises the event.You can select a different record besides the default record. The record must have the same keys as the record that normally raises the event. The system displays the keys in the Event Keys grid so that you can enter key values.
	Click the Event Info button to view select information from the Event Registry component about the selected event and its registered event handlers. The system displays the Registry Info group box, which contains the event details.
Raise Event	After you select a value in the Value field for each event key in the Event Keys grid, click this button to have the Event Manager framework raise the event with the specified event keys and their values. The system processes the event and executes all active event handlers that you have registered to the event exactly as if you have raised it from the normal business process such as through a component or PeopleTools Application Engine process. The local event registry settings as defined in the Event Registry component control the processing of the event. Depending on an event handler entry in the registry, the system executes active synchronous event handlers inline through this page and executes all asynchronous event handles through the generic PeopleTools Integration Broker message subscription. The system displays a message below the Record field indicating whether you have successfully raised the event. This message also includes the event ID on the local node and, for multichannel events, the event channel.
Launch Event Monitor	After you raise the event, click this link to view the execution status of the raised event. The system launches the Event Monitor component in a new browser window and automatically displays information for this particular event instance. See Monitoring Events.

Registry Info

Use this group box to view select information from the Event Registry component about the selected event and its registered handlers. The system displays this group box only if you select an event and click the Event Info button. To change any of this data, you must access the Event Registry component for the selected event.

Event Keys

Use this group box to enter values for each of the event keys that are part of the event that you are raising. The system does not perform any validation on the data that you enter in the Value fields. Be sure to enter the correct format for data values and use uppercase or lowercase values for character data as appropriate. The system makes these key values available to the event handlers just as if you raised the event from within the application.

Raising Events

After you determine that an occurrence of the business event exists that the event in the Event Manager framework represents, you can raise the event in the Event Manager framework.

The Event Manager framework provides an API that creates and raises events. The API code is:

Import HCR_EVENT_MANAGER:Utils:EventFactory;
Import HCR_EVENT_MANAGER:Base:baseEvent;
Local HCR_EVENT_MANAGER:Utils:EventFactory  &myEventFactory;
Local HCR_EVENT_MANAGER:base:baseEvent  &myEvent;

&myEventFactory = create HCR_EVENT_MANAGER:Utils:EventFactory();
&myEvent = &myEventFactory.CreateEventObject("EventName");
&myEvent.RaiseEventFromRecord(&Record);

Pass the name of the event to the Event Factory, which returns an instance of the event object. Then execute the RaiseEventFromRecord() method on the event object, passing in the record object that is causing the event to be raised. The framework determines the event keys based upon the values of the key fields in the record object.

Important! Instantiating an event object does not automatically raise the event. You must invoke the event's RaiseEventFromRecord() method to raise the event and initiate subsequent Event Manager framework processing.

In the following example, assume that we have created an event called AssignmentMilitaryRankChanged. This event represents the business event of assigning or updating the military rank of a person's assignment (Job record) instance. Whenever the rank attribute of the assignment (Job record row) changes, we want to raise the event. Here is the pseudocode to add to the JOB_MIL.MIL_WORN_RANK:SavePostChange PeopleCode event for the Job component:

Import HCR_EVENT_MANAGER:Utils:EventFactory;
Import HCR_EVENT_MANAGER:Base:baseEvent;

Local HCR_EVENT_MANAGER:Utils:EventFactory &myEventFactory;
Local HCR_EVENT_MANAGER:Base:baseEvent &myEvent;
Local Row &Row;
Local Record &Rec;
Local Field &Fld;
Local Number &ThisRowNumber;
Local String &ThisRank;
Local Boolean &RaiseEvent;

&Row = GetRow();
&Rec = GetRecord();
&Fld = GetField();

/* --- Should we raise an event? --- */
If INSTALLATION.MILITARY = "Y" Then
   &RaiseEvent = False;
   &ThisRank = &Fld.Value;
   If &Row.IsNew Then
   <If there is a previous row, and it's Military Rank is not = &ThisRank> Then
      &RaiseEvent = True;
   <End-If>
   Else
   If &Row.IsDeleted Then
      <If there is a previous row, and it's Military Rank is not = &ThisRank> Then
         &RaiseEvent = True;
       <End-If>
   Else
         /* Not deleted, and Not a new row – existing row was updated */
      If &Rec.IsChanged Then
         If &Fld.IsChanged Then
            &RaiseEvent = True;
         End-If;
      End-If;
   End-If;
   End-If;
If &RaiseEvent Then
   &myEventFactory = create HCR_EVENT_MANAGER:Utils:EventFactory();
   &myEvent = &myEventFactory.CreateEventObject("MilitaryRankEvent");
   &myEvent.RaiseEventFromRecord(&Rec);
   End-If;
End-If;

The lines in the preceding code that deal with the action of raising the event are:

Import HCR_EVENT_MANAGER:Utils:EventFactory;
Import HCR_EVENT_MANAGER:Base:baseEvent;

Local HCR_EVENT_MANAGER:Utils:EventFactory &myEventFactory;
Local HCR_EVENT_MANAGER:Base:baseEvent &myEvent;

   &myEventFactory = create HCR_EVENT_MANAGER:Utils:EventFactory();
   &myEvent = &myEventFactory.CreateEventObject("MilitaryRankEvent");
   &myEvent.RaiseEventFromRecord(&Rec);

Important! During the course of raising an event, the framework causes certain tracking and logging information to be stored in the database. Because of this, events can be raised only from PeopleCode events that normally allow database updates. More specifically, events can be raised only from SavePreChange, SavePostChange, and Workflow PeopleCode events.

Monitoring Events

This section discusses how to:

• Review event instances.

• Review event handler executions.

• Review event handler exceptions.

Pages Used to Monitor Events

Reviewing Event Instances

Access the Event Manager - Monitor page.

Search Criteria

Enter the search criteria for retrieving event instances. At a minimum, you must select at least one criterion to retrieve results. Use the remaining fields to narrow your search results.

Event Instances

Review the logged event instances that meet your search criteria. The system displays instances for only the events and event handlers that you have configured in the local Event Registry component to be logged. You set the logging option for an event by selecting the Logging Enabled check box for an event on the Define Events page. Note that the process that raises the event waits for all registered synchronous event handlers to execute.

Reviewing Event Handler Executions

Access the Event Monitor - Handlers page.

The system displays information for only the event handlers that you have configured to log executions. To log event handler executions, you must set the Logging option for a specific event handler and event combination on the Registered Handlers page.

The upper portion of the page displays information about the selected event instance that caused the event handler execution as well as the date and time that the local node began processing the event. For local events, the Processed date and time is generally the same as the date and time that the event was created. For remote events, the Processed date and time indicates when the local node received notification of the remote event from PeopleTools Integration Broker.

Handler Execution

This grid lists the event handlers that the system executed on the local database in response to the selected event instance.

If no event handler execution information is available, the system displays an informative message that indicates the possible reasons why no information is available. Possible reasons are that no event handlers are registered for the selected event, no event handlers are configured to log execution for the selected event, no synchronous event handlers are registered for the selected event and PeopleTools Integration Broker has not yet executed any asynchronous event handlers, or no event handlers executed for the event.

Reviewing Event Handler Exceptions

Access the Event Monitor - Handler Exceptions page.

The upper portion of the page displays information about the selected event instance that caused the event handler execution as well as the date and time that the local node began processing the event.

Events raised in a remote database are visible in the Event Monitor component only after the local node receives and processes the asynchronous event message, and only if you have enabled logging for the event when registering the event in the local database through the Event Registry component.

Note. If you inactivate the PeopleTools Integration Broker Service Operation for the generic event message, then the local Event Manager framework does not process any remote events and thus no remote events will be visible in the Event Monitor component.

Viewing Event Summaries

This section discusses how to:

• View a summary of event instances.

• View failed event handlers.

Pages Used View Event Summaries

Viewing a Summary of Event Instances

Access the Event Manager - Event Summary page.

Refresh

Click to refresh the statistics that the system displays on this page. The option to refresh is useful in production environments in which the raising and processing of events occurs frequently.

Summary Grid

Use this group box to review statistics for every event that has logged instances in the local database. The system displays event instances for only the events that are configuring for logging through the Event Registry component in the local database. The system groups the logged event instances by event and node combination.

Viewing Failed Event Handlers

Access the Event Manager - Failed Handlers page.

The system lists information about each failed event handler. Click the Details button to access the Event Monitor - Handler Exceptions page, where you can view the exceptions that the failed event handlers produced.

Viewing Help for HCM Event Manager Pages

This section discusses how to view page help for HCM Event Manager pages.

Page Used to View Help for HCM Event Manager Pages

Viewing Page Help for HCM Event Manager Pages

Access the Page Help page.

Click the Return arrow at the top or bottom of the help page to return to the original HCM Event Manager page for which you are seeking additional information.