Package com.ibm.openpages.api.trigger

The GRC Trigger framework for extending OpenPages with custom business rules.

See: Description

Class Summary

Class	Description
AbstractEventHandler	Base abstract class for event handlers.
AbstractRule	Base class for Rules.

Enum Summary

Enum	Description
TriggerPositionType	Defines the trigger position type enumeration.

Exception Summary

Exception	Description
GRCTriggerException	Exception thrown for all GRC trigger related errors.

Package com.ibm.openpages.api.trigger Description

The GRC Trigger framework for extending OpenPages with custom business rules.

Note: For complete discussion of implementing and working with Triggers, refer to the OpenPages with Watson Trigger Developers Guide.

Overview

The OpenPages application provides a trigger framework that allows the implementation and deployment of custom business logic and rules, and the capability to plug them into a production OpenPages deployment. This framework is built in Java and allows the implementation of any business logic based on existing functionality available through the OpenPages GRC API.

Events

As operations take place in the system, either from user or system automation performing actions, events are generated by a subset of supported operations. As these events are generated they are passed to the trigger framework, any triggers which are registered through configuration for different event types have the opportunity to handle these events and perform additional operations. For example when a user creates a new GRC Object in the OpenPages user interface, a CREATE_OBJECT event is generated and triggers may be configured to handle CREATE_OBJECT events.

See package com.ibm.openpages.api.trigger.events for descriptions of all supported events.

Rules

Each registered trigger will have a rule defined. Every rule is a Java class which extends AbstractRule. The rule determines whether or not the event applies to the business logic for that trigger, if it does not apply the event is passed to the next trigger and if no rules apply the event continues and is processed by the system. The definition of what rules apply is based on the business logic and implementation of the rule class, but common use case may be a rule that applies a "Type match" rule e.g. this rule applies if the event is for an object of type "LossEvent".

Event Handlers

Once a rule returns a positive result for an event, one or more event handlers defined for the same trigger will be able to handle the event. Every event handler is a Java class which extends AbstractEventHandler. These actions can perform any business logic. For example,

• Throw a validation error (see AbstractEventHandler.throwException(String, java.util.List, Throwable, com.ibm.openpages.api.Context))
• Create a new object
• Delete an existing object
• Reset or modify field values of the object
• Modify fields of a related object
• Execute a report (see IApplicationService.invokeCognosRowReport(String, com.ibm.openpages.api.application.IReportParameters))
• etc...

Position

One consideration is that events are generated in either of two phases of an operation, PRE or POST. These positions are represented on every event type with the TriggerPositionType enum. And triggers are registered to listen for either one or other position.

PRE - are events that happen prior to the operation actually being performed by the system. For example, creation of a GRC Object, a PRE event has all the information about the object to be created, but the system has yet to take action and actually create the object and persist values.

POST - are events that happen after the operation has been performed by the system and before the the transaction has been committed allowing for further processing of additional business logic.

The position may affect the availability of certain information and methods within the trigger context for the rules and event handlers. Please refer to the individual event types for more detail. Also see the OpenPages with Watson Trigger Developers Guide for best practices.

Transactions

All triggers on operations that are currently supported in the trigger framework are executed within the same transaction of the original system operation. Any error, whether system errors or business logic specific ones, will rollback the transaction. In other words, the original operation will be rolled back if any error occurs.

Implementation

To implement a trigger you must write a rule and event handler classes.

For the new rule extend DefaultRule. The DefaultRule has an isApplicable() method for every event type which always return false. Your new Rule can override any of the Events that you wish to capture with this Rule class and implement logic in the isApplicable() method based on the event details.
Example:

 public boolean isApplicable(CreateResourceEvent event) {
     IResource resource = event.getResource();
     if (resource.isFolder()) {
         //do not apply to folders in this case
         return false;
     } else {
         //do business logic to evaluate if resource applies or not
         return evaluate((IGRCObject) resource);
     }
 }
 

One or more event handlers can be configured per rule. For the event handler extend DefaultEventHandler. The DefaultEventHandler has a handleEvent() method for every event type which always return false. Your new handler can override the specific handleEvent() methods only for the Events that your trigger is concerned with.
Example:

 public boolean handleEvent(UpdateResourceEvent event) {
     IGRCObject object = (IGRCObject) event.getResource();
     //example: in addition to other updates, set a field to current date
     setCurrentDate(object);
     return true;
 }
 

Configuration

To configure a trigger with your rule and event handler which will process and handle some events you must edit the trigger configuration XML file. The configuration file is accessible only through the OpenPages platform's /opx web interface. Refer to the OpenPages with Watson Administrator's Guide for more information on /opx web application. The configuration file is located under the root directory and is named '_trigger_config_.xml'. You may check-out and download the file to modify it and perform a check-in when finished with any changes.

Within the XML file, to define a rule with event handlers in the trigger framework add a new <grcTrigger> element with one <rule> and multiple <eventHandler>. <attribute> tags are determined by the rule or event handler configuration requirements and are used to pass configurable parameters to the rule or event handler classes. The rule and eventHandler elements will refer to the classes you wrote with the "class" attributes.

For more details on configuration, refer to the GRC Platform Trigger Developers Guide.