Represents a request to execute an event action when an event is triggered on a target Content Engine object. For example, you can have a subscription that notifies you by email when documents of a certain class are created and saved in the object store. The specified EventAction and Subscribable objects, which represent the event action and target object, must exist before you can create a Subscription object and persist it.

Subscription is the base class for subclasses defined with specialized behavior. You can create objects for the subclasses, but you cannot create a base Subscription object. You can, however, instantiate one in the following ways:

  • By calling the GetInstance or FetchInstance method on the Factory.Subscription class.
  • By getting the Subscriptions property on an ObjectStore object or an EventAction object, then iterating the SubscriptionSet collection.
  • By getting the WorkflowSourceSubscriptions property on a WorkflowDefinition object, then iterating the SubscriptionSet collection.

The following tables list the members exposed by ISubscription.

Public Properties

 NameDescription
Public propertyEventActionThe event action object that defines the actions to be taken when a event occurs that is subscribed to by a Subscription-based object (ClassSubscription, ClassWorkflowSubscription, InstanceSubscription, InstanceWorkflowSubscription). You set the property with an EventAction object, which must already exist in the object store. You then specify the property when you create the Subscription-based object.

Once this property is set, the Content Engine adds the Subscription-based object to the EventAction object's Subscriptions collection property.

Public propertyFilteredPropertyId 
Public propertyFilterExpression 
Public propertyIsEnabledIndicates whether a given object is enabled or disabled. For example, you can globally disable or enable active events by setting an IEventAction object's IsEnabled property to False (off) or True (on). Likewise, you can enable or disable a subscription or a security template. Enabling a security template indicates that it can be applied to an object. A disabled security template remains part of its security policy container, but cannot be applied to an object. Disabling a security template is useful when you are testing or developing the security templates that make up a security policy. Disabling a subscription prevents the function associated with the event from being loaded and executed. You might want to disable a subscription that is undergoing modifications due to a change in business processes or when you do not want functions to execute against federated documents. Note that when you disable an IEventAction, all of its associated subscriptions are also disabled. However, when you disable one particular ISubscription, you only disable events that are in its subscribed event list.
Public propertyIsSynchronousThe method by which the event procedure code is executed for a ISubscription-based object(IClassSubscription, IClassWorkflowSubscription, IInstanceSubscription, IInstanceWorkflowSubscription). To execute the event procedure synchronously, set the property to true. To execute the event procedure asynchronously (in the background), set the property false. The default is false. Specify the property when you create the Subscription-based object.

When an asynchronous event procedure is triggered, the action occurs on a separate execution thread, allowing the subscription processor to continue without waiting for the results of the action. The Content Engine inserts the event into the QueueItem table, after any other waiting asynchronous operations, and executes it when resources permit. While execution usually occurs instantaneously, there may be a delay if there are many other asynchronous events or operations (such as security propagation or XML classification) waiting in the queue. If your application depends on a particular asynchronous event procedure being completed, your application should first test the status of that event to verify its completion.

If the asynchronous event action fails, the exception comes back to the server. The event action transaction rolls back, but the transaction of the originating activity executes.

Note that 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.

When a synchronous event procedure is triggered, 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 exception comes back to the client. The single transaction rolls back; therefore, the originating activity fails along with the event action.

Note that, for a workflow subscription, this property is read-only with a value of false because a workflow subscription's event is always fired asynchronously on the Content Engine.

Public propertySubscribedEventsA list of objects specifying the events to which the subscription applies. When you create a subscription, you set this property to ISubscribedEventList, a list of objects representing the system and custom events to which to subscribe.
Public propertySubscriptionTargetThe target object of a ISubscription-based object(IClassSubscription, IClassWorkflowSubscription, IInstanceSubscription, IInstanceWorkflowSubscription). You set the property with an a Subscribable object, then specify the property when you create the ISubscription-based object.

For a IClassSubscription or IClassWorkflowSubscription object, set the value of the SubscriptionTarget property to a ISubscribableClassDefinition object or subclass that specifies a type of Content Engine class (for example, Document or Folder). This means that any instance of the class, whether it currently exists in the persistent store or you create a new instance, will, when acted upon, cause one or moreof the IEventAction object's events to be raised.

For an IInstanceSubscription or IInstanceWorkflowSubscription object, set the value of the SubscriptionTarget property to a specific ISubscribable object. This means that only this currently instantiated object, when acted upon, causes one or more of the IEventAction object's events to be raised. If the object is a IVersionSeries object, the event is raised when a version in the version series is acted upon.

Public propertyUserStringA string used to identify a subscription, with no built-in behavior.
Top

Public Methods

 NameDescription
Public methodChangeClassChanges the class of a Content Engine object. The new class must already exist and both it and the original class must be subclasses of the same base class. The ChangeClass method does not modify the security for an object, even if the object's current security is derived from the default security for its source class. For the object's user-defined properties, the following rules apply:
  • Any user-defined properties that exist in the new class but not in the original class are set to the default value defined by the new class (or to null if there is no default defined).
  • Any user-defined properties that exist in both the original and the new class that are writable and have the same value (including null) as the default value defined in the original class will be set to the default value defined by the new class. However, any user-defined property that has had its value modified from the default value will retain that modified value in the new class.
  • Any user-defined properties whose definitions exist in the original class but not in the new class will no longer exist on the object when its class is changed.

When the class of a document object is changed, the default document lifecycle policy of the new class will only be applied to the document object's DocumentLifecyclePolicy property if both of the following scenarios occur:

  • The document has no current lifecycle policy.
  • The document is either a reservation object, or is the current version object and is not reserved.

Top

See Also