IBM FileNet P8, Version 5.2.1

Subscriptions

A subscription is a device for starting 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 run. 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).

For subscription code examples, see Working with Subscriptions. For information about 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 that is derived from Subscription. (You cannot create a base Subscription object, but retrieve only one.) After you create 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 subclass. 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 start the event action (SubscribedEvents property). These events can be system or custom events. In the email notification example, the subscribed event is CreationEvent. See Subscribed Events.
The event action object that represents the actions that are taken when a subscribed event fires (EventAction property). An event action can be implemented as a JavaScript or Java™. 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, these subscription properties specify the following information:

Whether the event handler code of a particular subscription is run synchronously or asynchronously. Note that if the code runs asynchronously, the event is inserted into the QueueItem table after any other waiting asynchronous operations and runs when resources permit. Also, failures in asynchronous events are tried again; failed synchronous events are not tried again.
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 applies to all subclasses of the target class.

For more information, see Subscription Properties.

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 runs 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 runs 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 might create a custom event class, then set the instantiated custom event object to the SubscribedEvents property of a subscription. To trigger the custom event, raise the event on the Subscribable object that is the target object of the subscription, which starts the event action in the subscription.

Note that the system and custom events that you can subscribe to can also be audited. For more information, see Subscribable and Auditable Events.

Event Actions

Event actions are code procedures that you implement to extend Content Engine functionality, and, which are run by using subscriptions. Event actions can also be started when you publish or republish a document. There are various use cases for event actions:

Notification/communication: You can write an event handler that generates email messages that are 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 lifecycle or workflow process, might require advanced filtering on a document or its contents before it is accepted into the system. You can write an event handler to reject a particular document entry and stop or roll back the transaction.

You implement an event action as a JavaScript or Java component, based on the Content Engine EventActionHandler interface or the RetrievalEventActionHandler interface. For a handler that is implemented with Java, 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 class path of the application server where the Content Engine is running. A handler runs on the application server that hosts 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, and set and retrieve properties and permissions for them. To associate an event action handler with an EventAction object, you set the EventAction object'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 start two event actions on an object. That is, for a given publishable object, you can subscribe to PublishRequestEvent or PublishCompleteEvent to start 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 starts first, and the event action that is specified in the publish method or republish method starts 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 more implementation and deployment information, see Action Handlers.