IBM FileNet P8, Version 5.2

Subscriptions

A subscription is a device for launching a user-implemented, server-side component that extends the core functionality of the Content Engine. A subscription is defined by one or more events, a target Content Engine object on which the events can be triggered, and an event action. When an event is triggered on the target object, the event action is executed. For example, you can have a subscription that notifies you by email (event action) when documents of the "Code Module" class (target object) are created (triggered event).

This topic focuses on setting up a subscription; that is, creating a subscription and setting its properties. For subscription code examples, see Working with Subscriptions. For information on subscriptions as implemented in an Administration Console for Content Platform Engine, see Subscribing to events.

Subscription Setup Requirements

A subscription is represented by a Subscription class, which is the base class for InstanceSubscription and ClassSubscription (for general subscriptions), and InstanceWorkflowSubscription and ClassWorkflowSubscription (for workflow-related subscriptions). A workflow-related subscription initiates a workflow and event action in response to events triggered on a particular object, or on any object of a particular class.

To start, you use a Factory method to create an instance of a subclass derived from Subscription. (You cannot create a base Subscription object, but only retrieve one.) After creating a subscription object, you define the following key properties:

The display name of the subscription to identify it (DisplayName property).
The target object of the subscription (SubscriptionTarget property). The target object can be an instance of any Subscribable-derived class. The type of subscription object that you created (instance or class) determines the type of target object: either a specific object instance or any object of a specific class. The email notification example cited in the introduction is a class subscription because the target object is a class, not a specific object instance in a class.
The triggered events that launch the event action (SubscribedEvents property). These can be system or custom events. In the email notification example, the subscribed event is CreationEvent. See Subscribed Events.
The event action object representing the actions taken when a subscribed event fires (EventAction property). An event action can be implemented as a JavaScript or Java™ component. In the email notification example, the event action is the handler that generates the email notification. See Event Actions.

In addition to the required properties above, there are subscription properties that specify:

Whether the event handler code of a particular subscription should be executed synchronously or asynchronously. Note that if the code executes asynchronously, the event is inserted into the QueueItem table after any other waiting asynchronous operations and executes when resources permit. Also, failures in asynchronous events are retried; there are no retries for failed synchronous events.
Whether the subscription is enabled or not.
An optional filter expression that the Content Engine server evaluates (in memory) on the target object, to determine whether to queue the event request.
The symbolic name of an object-valued property of the target object to which the filter expression is applied (rather than applying the filter expression to the target object itself).
Whether — for a class subscription — the subscription should apply to all subclasses of the target class.

See Subscription Properties for more information.

Subscribed Events

When you create a subscription, you set its SubscribedEvents property to a collection of one or more system and custom events. If any of these events is triggered on the subscription's target object, the Content Engine executes the subscription's event action. For example, if you subscribe to a FileEvent object, filing a containable object in a folder or creating a subfolder executes an event action.

The system events that you can subscribe to derive from the ObjectChangeEvent interface. You can also subscribe to GetContentEvent, derived from the RetrievalEvent interface. If you need an event that's not already represented by a Content Engine system event, then you can create a custom event. Custom events apply to subclasses of the Subscribable class, and are triggered by calling the class's RaiseEvent method. For example, you could create a custom event class, then set the instantiated custom event object to the SubscribedEvents property of a subscription. To trigger the custom event, you would raise the event on the Subscribable object that is the target object of the subscription. This, in turn, would invoke the event action in the subscription.

Note that the system and custom events that you can subscribe to can also be audited. See Subscribable and Auditable Events.

Event Actions

Event actions are code procedures that you implement to extend Content Engine functionality, and which are executed using subscriptions. Event actions can also be launched when you publish or republish a document. There are various use cases for event actions, such as the following:

Notification/communication: You can write an event handler that generates email messages tailored to specific events and source objects and sends the message to the appropriate people.
Logging/counting: To track the frequency of usage for different kinds of Content Engine objects and events, you can write an event handler to generate a detailed record about the event, increment an event counter, and write the information to a database or file.
Filtering: Some complex processes, like a document life cycle or workflow process, might require advanced filtering on a document or its contents before it being accepted into the system. You can write an event handler to reject a particular document entry and abort or roll back the transaction.

You implement an event action as a JavaScript or Java component, based on the Content Engine API's EventActionHandler interface or the RetrievalEventActionHandler interface. For a Java-implemented handler, you can package the class in a JAR file. You can then check in your class or JAR file as a CodeModule object in a Content Engine object store, or, alternatively, you can specify the Java event handler in the classpath of the application server where the Content Engine is running. A handler executes on the application server hosting the Content Engine. The Content Engine explicitly disables security access checks during execution of a synchronous or asynchronous event handler.

You make an implemented event action handler available to a subscription or to a publish/republish operation through an EventAction object. You can create and retrieve EventAction objects, as well as set and retrieve properties and permissions for them. To associate an event action handler with an EventAction object, you set the EventAction's ProgId property, which identifies a JavaScript or Java component as the handler. If you check in a Java event handler to an object store, you must also set the EventAction's CodeModule property. You then set the subscription object's EventAction property to the EventAction object. For a publish/republish operation, you specify the event action name or ID.

Note that you can use both a subscription and a publish/republish operation to launch two event actions on an object. That is, for a given publishable object, you can subscribe to PublishRequestEvent or PublishCompleteEvent to launch one event action, and you can use the publish method or the republish method on the object to fire a second event action. In this scenario, the event action set in the subscription mechanism launches first, and the event action specified in the publish method or republish method launches second (if no exception is thrown from the first event action).

For code examples on implementing an event action handler and on creating an event action object, see Working with Subscriptions. For additional implementation information, see Restrictions and Best Practices. For more about deployment, see Deploying Java Action Handlers.