# 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.
  GRCTriggerException | Exception thrown for all GRC trigger related errors.

- Enum Summary
  Enum | Description
  --- | ---
  TriggerPositionType | Defines the trigger position type enumeration.

## 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.

Licensed Materials - Property of IBM
OpenPages with Watson (PID: 5725-D51)
© Copyright IBM Corporation 2013, 2021. All Rights Reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.