Package com.sapportals.wcm.repository.service.subscription

Provides a service that creates and manages subscriptions for resources.

See:
Description

Interface Summary

ISubscription	Represents a single subscription and provides methods to define, modify and access the details of a subscription.
ISubscriptionAttributes	Represents the customizable attributes of a subscription.
ISubscriptionCondition	Defines the conditions for which events lead to a notification.
ISubscriptionConditionEvent	Represents an event a user can subscribe to.
ISubscriptionConditionInterval	Defines the intervals at which a subscription has to be checked for changes An ISubscriptionConditionInterval is attached to an ISubscriptionCondition.
ISubscriptionConditionRecursionLevel	A Recursion level defines which hierarchy level is relevant for a subscription on a collection. An ISubscriptionConditionRecursionLevel is attached to an ISubscriptionCondition.
ISubscriptionList	A list of ISubscriptions.
ISubscriptionListIterator	An iterator for an ISubscriptionList.
ISubscriptionManager	Provides methods for creating, modifying, and accessing subscriptions that belong to this ISubscriptionManager.

Class Summary

SubscriptionUtils

Certain utility methods for obtaining a repository's subscription service.

Exception Summary

SubscriptionException

The exception thrown by the subscription service.

Package com.sapportals.wcm.repository.service.subscription Description

Provides a service that creates and manages subscriptions for resources.

Package Specification
Purpose
Detailed Concept
Interfaces and Classes
Code Samples
Configuration
Implementation Notes
Related Documentation

Purpose

A subscription enables users to keep track of changes that are made to resources in a repository. Users can create a subscription to a resource and specify that they want to be informed whenever the resource changes. Subscriptions can have many different forms. They can be created for various resource types and different recipients. They can return information about resources using different channels and at individually configured intervals.

Detailed Concept

A subscription is defined with a number of elements. These are:

• A name that identifies the subscription
• Resources that are subscribed to
  These can be documents, folders, folder hierarchies or taxonomy folders that are used for classification purposes.
  If folders are subscribed to, the recursion level can be set. This specifies whether the subscription applies only to a folder or also to levels of subfolders.
• Recipients (IRecipientList)
  The people or groups that receive information about changes to subscribed resources.
• Notification channel (IChannel)
  The medium that is used to communicate with the recipients of a subscription. For example, e-mail, fax, and SMS channels are supported.
• Attributes (ISubscriptionAtrributes)
  These are the expiry date when the subscription ends, the date of the next notification, and the text that is entered in the notification.
• Conditions for the subscription (ISubscriptionCondition)
  These are:
  • Events on the subscribed resource that are of interest to a subscriber and trigger notification. For example, events can be changes to contents, viewing of contents, deletion or creation of resources. Note that not all events are supported for all resource types. Events are sometimes resource-specific and can therefore differ depending on the resource involved.
  • Notification interval that defines how often notifications that are related to subscriptions are sent. For example, intervals can be weekly, daily, monthly or always.
    The notification interval also determines how frequently the resources are checked for events that are of interest to the subscriber. Intervals that are supported are sometimes resource or repository-specific. This means they can differ depending on the resource or repository involved. For example, if a repository does not support eventing, the interval always is not available.
  • Recursion level that specifies how many levels of the hierarchy are relevant for the subscription if a folder is subscribed to.
  The user that creates a subscription is subsequently the owner. Only the owner of a subscription or an administrator can change a subscription.

Interfaces

The subscription API comprises a number of interrelated interfaces that center around the ISubscriptionManager and ISubscription interfaces.

The ISubscriptionManager interface defines the core functions for creating and administrating subscriptions in general. It is the starting point for working with subscriptions. It supplies instances of all the objects required for a subscription, stores default settings and knows which settings are supported for different resource types. In addition it is responsible for controlling the subscription process. It checks the resources as required to find out whether a condition is met. If it registers that a condition related to the subscription is met, it generates a message (INotification ) and sends it to the recipients using the predefined communication channel.

The ISubscription interface represents an individual subscription. It stores all the relevant information about a subscription and offers all the methods that are required to manipulate it. In summary, it defines who (recipients) will be notified how (channel), when (condition) and about what (resources).

The following UML Diagram illustrates the interrelationships between the subscription manager and the other interfaces of the package:

In addition to the above, the interface of the package includes the SubscriptionUtils class that implements methods for accessing subscription managers.

Code Samples

The following shows code extracts. For a complete example, see the KM subscription service in the PDK.

Creating a Subscription

The code sample creates a subscription for the current user to an IResource resource using default attributes, conditions and channel. The user that becomes the owner of the subscription is provided by the context:

ISubscriptionManager subscriptionManager = SubscriptionUtils.getSubscriptionManager(resource);
ISubscription simpleSubscription = subsciptionManager.createSubscription(
  resource.getContext(), // the context
  "mySimpleSubscription", // the name of the subscription
  null, // use default condition
  resource,
  null, // use default channel
  null, // use user from context as recipient
  null // use default attributes
);

Defining a Notification Text
The code sample shows how to specify the text that is included in the notification for a subscription:

ISubscriptionAttributes attributes = new SubscriptionAttributes();
attributes.setNotificationText("your annotation here");

The ISubscriptionAttributes are specified in the last parameter of the createSubsciption()-call.

Configuration

The SubscriptionManager can be configured with the parameters shown in the table.
The parameters are set with the help of the user interface of the Content Management configuration framework.
For more information, see the Administering Content Management document.

The parameters in the table that are not required have default values that are used if no value is specified.

Property	Required	Description
serviceuser	No	User used for polling of resources. Default: anonymous user.
eventmap	No	Class for converting the technical events from the framework into semantic events that are used to trigger notifications for subscriptions. Default: com.sapportals.wcm.repository.service.subscription.wcm. SubscriptionEventMapStandard.
mininterval	No	The minimum time interval (in seconds) between 2 changes to a document that allows 2 notification messages to be sent. Default: 1 sec.
notifications	No	List of operations that generate an administrative notification (a list with the following values: create, delete, update, updaterecipient, updateresource). Default: create, update_recipient.
actioninbox_AdminNotifications	No	Flag to enable or disable admin notifications being sent to the ActionInbox. Default: false.
actioninbox_Notifications	No	Flag to enable or disable notifications being sent to the ActionInbox. Default: true
poolid	Yes	Connection pool for database access.
<channel>.from	No	The value of the from field in messages sent by the subscription service. If this field is not set, the recipients can not see who or what sent the notification. It is advisable to use an administrative account to keep track off invalid e-mail addresses or delivery failures.

The following shows a sample configuration for the subscription service:

Name	Value
serviceuser	subscription
mininterval	1
notifications	create,updaterecipient
actioninbox_AdminNotifications	false
actioninbox_Notifications	true
poolid	p1
EMAIL.from	Subscription Service <subscription@sap.com>
SMS.from	Subscription Service <subscription@sap.com>

Parameter Ridtracking

If the parameter ridtracking is set to true, the subscription follows the subscribed resource. If it is set to false, the subscription follows the subscribed URL.
Consider a subscription S for the resource /xyz/A
If A is renamed to B, the behavior is as follows: With RID tracking enabled, the subscription S points to xyz/B, with RID-tracking disabled it still points to /xyz/A
If A is removed, the behavior is as follows: With RID tracking enabled, the subscription S is also deleted, with RID tracking disabled, it remains unchanged.

Enabling RID tracking increases the system load because each event is handled by the subscription service. To detect a change, a database lookup is performed for each MOVE, RENAME and DELETE event. Note that RID tracking only functions for repositories where eventing is enabled.

Implementation Notes

The following sequence diagram shows the implementation of the subscription service for the CM repository.

When the subscription service is used, the two global services Scheduler and Notificator have to be available as well. If one of these is not available at startup (see the log-file for details), the subscription service is also not available.

The subscription service is a repository service. See the package com.sapportals.wcm.repository.manager to find out how to assign a repository service to a repository.

Related Documentation

Package Documentation

• Repository Manager
• Notificator
• JDBC Connection pool
• Scheduler

External Specifications
Not applicable