Creating custom actions for GRC workflows

You can create custom actions to use in IBM OpenPages® workflows.

A custom action is a Java™ class that can be invoked during a workflow action. A custom action is very similar in function to a trigger, which executes on object operations. But triggers and custom actions have different interfaces and abstract implementations, so the classes are not interchangeable. Like triggers, custom actions must be deployed to each OpenPages application server and are dynamically loaded during startup.

To implement a custom action, do the following tasks:
  • Create a custom action Java class by extending the abstract implementation com.ibm.openpages.api.workflow.actions.AbstractCustomAction
  • Add the class to a JAR file. Use the JAR file for all of your custom code. Deploy the JAR file to each OpenPages application server in the <OP_HOME>/aurora/op-ext-lib directory.
  • Restart the OpenPages application servers so that the custom action can be picked up by the dynamic class loader.
  • Configure the custom action within the context of a workflow by using the Custom Action operation type. Set any property values or fields that the custom action requires as inputs.

Custom actions run in the order of operation that is listed in the workflow action.

All operations in a workflow action are performed in a single transaction. This means that if a custom action fails for any reason, the entire workflow action is rolled back.

Passing arguments to a custom action

In order for the custom actions to be reusable in different contexts, properties and field values can be passed in during configuration. This is optional. As the developer of the custom action class, you decide which, if any, arguments to pass in and validate.
  • Properties are name-value pairs that you define. For example, you might create a custom action that creates a child object and has a property that is named object_type that determines the type of object to create.
    • The custom action needs to validate that the properties that it expects to be passed in have been passed in and that they have valid values.
    • You can use expressions, such as [$END_USER$] or [$TODAY$] in the property values to pass in dynamic content. For a full list of expressions, see Using variables, functions, and fields.
  • Fields can also be passed in to provide a typed value to an object field. This technique can be very useful if your custom action is interacting with objects, either setting or evaluating field values.

Authoring the custom action Java class

The only requirement of a custom action Java class is that it extends com.ibm.openpages.api.workflow.actions.AbstractCustomAction. This requirement is validated when the custom action is defined in a workflow.

A single abstract API must be implemented in AbstractCustomAction:
process();

Use this method to contain the business logic that the custom action will perform.

For more information about the IBM OpenPages GRC Java API, which you can use in custom actions, see IBM OpenPages GRC Java API .

You can access context about the current workflow and configuration through the following methods on AbstractCustomAction:
  • getContext() – Returns an IWFOperationContext object that contains all relevant information about the workflow state and the associated GRCObject.
  • getPropertyValue(String prop_name) – Returns the value of a named property.
  • getFields() – Returns a List<IWFFieldSetter> object based on the configuration of the custom action.

Exception or validation messages can be thrown from a custom action and displayed to the user. To display messages, use:

throwException(String message, Throwable cause)

Use this method to throw exceptions and display a custom message to users. Uncaught exceptions or exceptions that are explicitly thrown are logged by the application, but only a general error message is displayed to users.

Workflow context

The class com.ibm.openpages.api.workflow.actions.IWFOperationContext provides state information for the workflow action.

Related workflow data:
  • IWFProcessDefinition getProcessDefinition() – Returns the workflow definition.
  • IWFProcess getProcess() – Returns the current workflow instance.
  • IWFActivityInstance getActivityInstance() – Returns the current stage instance.
  • IWFTransition getTransition() – Returns the current workflow action.

Related GRCObject:

  • IGRCObject getResource() – Returns the GRCObject for the workflow instance.
  • Id getResourceId() – Returns the ID of the GRCObject.
Service API access:
  • IServiceFactory getServiceFactory() – Returns a service factory for instantiating other OpenPages GRC API services.

Tips

  • Updating objects:

    If you want your custom action to update an object for the current workflow action, access the object through IWFOperationContext.getResource(). Updates that are made in this way are saved automatically by the workflow engine. Use this technique so that changes by multiple operations during an action are saved only once.

    If your custom action looks up other objects and modifies them, the custom action must save the objects explicitly. You can save the changes by using IResourceService.saveResource(). For example, if your custom action updates controls that are children of a risk, save the controls explicitly.

  • Utility functions:

    The class com.ibm.openpages.api.workflow.actions.util.WFActionUtil has some useful utility functions that you can use in a custom action. Review the IBM OpenPages API Javadoc for a full list of functions.

    Examples:
    • replaceStringExpressions(IWFOperationContext context, String value) – This function takes any string value and replaces expressions in it. This function is very useful if you want to leverage expressions in property values that are passed in to your custom actions.
    • setFieldValue(IWFOperationContext context, IGRCObject grcObject, IWFFieldSetter field) – This function updates the object with the field setter value that is passed in. This field can also use expressions in its value.