Concepts: event actions and subscriptions

Content Engine provides a framework for executing user-implemented actions when system or custom events are triggered on Content Engine objects. A user-implemented action is an event action. A subscription is the means by which you associate the event action with one or more events and with a target Content Engine object on which the events can be triggered. An event action is typically coded by a developer, but a subscription can be created by an administrator using Enterprise Manager.

For example, you can code an event action that sends an e-mail to the administrator when a document of a certain class is deleted. To set up and test this event, perform these general steps:

  1. Assign this event action to a subscription created for a document class.
  2. Select Delete as one of the trigger events in the subscription.
  3. Create a document using the class to which you assigned the subscription.
  4. Delete the document you created.
  5. Verify that the system administrator receives an e-mail message about the deleted document.

When an event occurs on any object, the subscription processor checks for a subscription on the object that specifies the event as a trigger. If a subscription exists, the processor loads the event action and calls the method corresponding to that event.

Subscription definition

When you define a subscription, you set the event action, target object, and trigger event. Note that for a workflow subscription, you also set a workflow definition (see Workflow subscriptions).

Event action: A code procedure that you, or a developer, implements as a Java™ class, based on the Content Engine API EventActionHandler interface.

For more information, see Event Actions in the Java and .NET Developer's Guide.

To view a sample source code implementation of EventActionHandler, see JavaEventHandler.java in the Content Engine directory:

<drive>:/Program Files/Filenet/Content Engine/samples

You can define whether a subscription executes an event action synchronously or asynchronously.

In synchronous execution, the call to execute the event action blocks further processing by the subscription processor until the action completes. The action runs in the same transaction as the originating activity on the target object. If the action fails, the transaction rolls back.

In asynchronous execution, the action occurs on a separate execution thread, allowing the subscription processor to continue without waiting for the results of the action. The action cannot be in the same transaction as the originating activity. For domains in which there are multiple Content Engine server instances, any server in the domain can handle a queued asynchronous event, not just the server that generated the event.

Target object: The object on which the subscription acts. An object can be one of the following types:

Class definition, in which the subscription applies to all instances of a given class.

Single instance: in which the subscription applies to a specific version of an object.

Version series: in which the subscription applies to all versions of a versionable object. Each version is a separate instance.

In the previous example, the deleted document belonged to the class specified by the subscription.

Although you can assign subscriptions to individual objects, it can be more efficient to assign subscriptions to classes instead. Assigning subscriptions to classes ensures that a set of common objects is managed consistently. Assigning subscriptions to classes can also limit the number of subscriptions that run simultaneously, which can affect system performance.

Trigger events: The type of events you want to trigger an event action. The event types available for a given subscription are determined by the type of object or class that is subscribing to the event action.

In the previous example, the trigger event was the deletion of the document.

The following table describes the different Content Engine events that you can use.

Event type Description Subscribing class or object
Cancel Checkout Event Triggers an event action when a reservation on a document is cancelled. Document
Change Class Event Triggers an event action when the class of an object is changed. Document, folder, or custom object
Change State Event Triggers an event action when the lifecycle state of a document is changed. Document
Checkin Event Triggers an event action when a document is checked in. Document
Checkout Event Triggers an event action when a document is checked out. Document
Classify Complete Event Triggers an event action when a document has been processed by a classifier. Document
Creation Event Triggers an event action when an instance of a class is created and saved. Checking out a document object triggers both the creation event and the checkout event, because a new document object (the reservation version) is created by the checkout process. Document, folder, or custom object
Custom Event Triggers an event action when a user-defined custom event is raised. Many kinds of objects
Deletion Event Triggers an event action when an object is deleted from the object store. Document, folder, or custom object
Demote Version Event Triggers an event action when a document is demoted to a minor version. Available only for documents that have versioning enabled. Document
File Event Triggers an event action when an object is filed in a folder (including the creation of a subfolder). Folder
Freeze Event Triggers an event action when the Freeze method of a document is called. Document
Lock Event Triggers an event action when the Lock method of an object is called. Document, folder, or custom object
Promote Version Event Triggers an event action when a document is promoted to a major version. Available only for documents that have versioning enabled. Document
Unfile Event Triggers an event action when an object is unfiled from a folder (including the deletion of a subfolder). Folder
Unlock Event Triggers an event action when the Unlock method of an object is called. Document, folder, or custom object
Update Event Triggers an event action when the properties of an object are changed. Document, folder, or custom object
Update Security Event Triggers an event action when the security of an object is changed. Document, folder, or custom object

Custom events

In addition to the events provided to you by Content Engine, you can create your own custom events. By default, a base CustomEvent class exists under Events. This is the base class for all user-defined custom events. To create a custom event in Enterprise Manager, create a CustomEvent subclass. Once you have created a custom event and refreshed the object store, you can select it from the available events list box when you create a subscription on a class or object.

Workflow subscriptions

A workflow subscription launches a workflow, as well as an event action, in response to an event triggered on an instance or class of document, folder, or custom object on Content Engine.

You can create a workflow subscription using tools available through Enterprise Manager or through Workplace XT or Workplace. When you create a workflow subscription, you must select a workflow definition that exists in the workflow database on Process Engine. For details on how to transfer workflow definitions to the workflow database, see About transfer.

Using the Workplace XT or Workplace applications to create workflow subscriptions provides the following advantages:

Use Workplace XT or Workplace tools to associate a workflow subscription with a class or subclass for documents, folders, or custom objects. When a trigger event occurs on any object associated with a workflow subscription, the event processor launches a workflow, using the workflow definition specified in the subscription.