Package com.sapportals.wcm.service.actioninbox

Provides a service that handles notifications by saving them as action items.

See:
Description

Interface Summary

IActionInboxAction	The IActionInboxAction defines an action which can be performed for an item and is handled by a producer.
IActionInboxCategory	A IActionInboxCategory describes the type of a IActionInboxNotification.
IActionInboxCategoryList	A list of IActionInboxCategorys.
IActionInboxCategoryListIterator	An iterator for a IActionInboxCategoryList.
IActionInboxItem	The stored IActionInboxNotification object for a specific user.
IActionInboxItemCategory	A IActionInboxItemCategory is a representation of a specific user's inbox folder for a category.
IActionInboxItemCategoryList	A list of IActionInboxItemCategorys.
IActionInboxItemCategoryListIterator	An iterator for the IActionInboxItemCategoryList.
IActionInboxItemList	A list of IActionInboxItems.
IActionInboxItemListIterator	An iterator for the IActionInboxItemList.
IActionInboxItemProducer	A IActionInboxProducer sends IActionInboxNotifications to the action inbox.
IActionInboxNotification	A IActionInboxNotification is something like a 'semantic event' which will be stored as a IActionInboxItem in a user's IActionInboxItemCategory.
IActionInboxService	The IActionInboxService stores IActionInboxNotificationss grouped by IActionInboxCategory as IActionInboxItems into IActionInboxItemCategorys.

Class Summary

AbstractActionInboxAction	A base implementation for an IActionInboxAction.
AbstractActionInboxCategory	A base implementation for an IActionInboxCategory.
AbstractActionInboxNotification	A base implementation of a IActionInboxNotification.
ActionInboxItemCategoryComparator	A IActionInboxCategoryComparator.
ActionInboxUtils	Some methods which should make handling of action inbox objects a little bit easier.

Package com.sapportals.wcm.service.actioninbox Description

Provides a service that handles notifications by saving them as action items.

Package Specification

Purpose
Detailed Concept
Interfaces and Classes
CodeSamples
Configuration
Implementation Notes

Purpose

The action inbox service manages an inbox that is integrated in the Knowledge Management platform. Basically it provides a link between applications and the action inbox of users. Applications can use the service to post messages that have to be read or processed by users.

The main task of the service is to route the messages from the application to the correct inbox and to organize the entries in the inbox into predefined categories. In addition, it enables users to process messages by giving them direct access to the functions of relevant applications. To process a message, users simply need to choose an action offered in the inbox. The action is then directed back to the application which presents the users with the appropriate functions. It is the task of the service to provide the direct link between the message and the functions of the application.

The subscription service, which informs users of updates and changes to content, is an example of an application that uses the action inbox service. It uses the service to post messages related to subscriptions in the corresponding category of a user’s inbox. If the user wants to perform an action related to subscriptions, like the deletion or update of a subscription, then he/she can click on a link included in the message. The action inbox service then provides direct access to the corresponding functions of the application. The user can access the functions via the inbox without explicitly calling the subscription application.

Detailed Concept

The following explains the different components that play a role in the action inbox service. An understanding of the components and how they interact is useful when you are working with the API.

The main components are the application, the notification, the service, and the inbox. The application, also called the producer, generates notifications that contain all the technical information required by the action inbox service. The service, acts as an intermediary between the application and the inbox. It analyses the notifications and then stores them as messages in the inbox of a user.

In detail, the interaction between the producer, the service and the inbox is as follows:

• The producer creates a notification and passes it on to the service. The structure of the notification is based on an XML file that defines the elements that a notification must consist of. Amongst other details, the notification specifies a recipient, a message, and the category that the message belongs to. The category identifies the application that the message originates from and is used to classify messages in the user’s inbox.
• The service component receives the notification and then stores it in the inbox of the correct recipient. In the inbox of a specific recipient, the notification is stored as an inbox item. Each item in the inbox is assigned to an item category. The item category classifies the items in the recipient's inbox.
  

Note that when you use the action inbox API, it is important to distinguish between the notification and the category defined by the application and the notification and category stored in the inbox of a specific user. The application represents these as an IActionInboxNotification and IActionInboxCategory object. The service represents these in the inbox of a specific user as an IActionInboxItem and IActionInboxItemCategory object.

The central feature of the inbox is that actions can be performed on its items. Depending on the category an item belongs to, certain predefined actions are permissable. The application must define these actions and handle their execution. For example, if an item is in a subscription category, the subscription application must predefine permitted actions like delete or update and execute them whenever required.

The graphic illustrates the interrelationship between the main interfaces of the action inbox service.

The following table explains the meaning of the central terms used for the action inbox service:

Term	Meaning
user	A valid system user
category	All messages that are sent and stored in the action inbox belong to a category, for example, a subscription service category
item category	A category of a specific user (user + category = ItemCategory)
notification	A message that is sent from an IActionInboxItemProducer to one or more recipients via the action inbox service.
action item	A notification belonging to a specific item category or a notification belonging to a specific category and a specific user. (Item Category + Notification = user + category + notification = action item). It has an ID, description, item category and producer ID.
item	See: action item

Interfaces and Classes

The action inbox API is comprised of a number of interrelated interfaces that center around the IActionInboxService:

• IActionInboxService
  Defines the core functions for creating and administrating action inbox items in general. It is the starting point for working with the action inbox. Every producer of action inbox items has to register himself with the service. The service handles the persistence of every item that is sent.
  
• IActionInboxNotification
  Represents the notification. It stores all the information that is required by the IActionInboxService to post a message to a user’s inbox. The methods of the interface enable access to details like the category the notification belongs to, the properties of the notification and the user that generated the notification. The properties of the notification store information like the recipient, the RID of the resource involved and the content of the message.
• IActionInboxCategory
  Represents the area that a notification belongs to, for example, subscriptions. A category is always associated with actions that can be performed on the inbox items that belong to that category. The methods of the interface return the actions permitted for the category, the ID of the category and the rules for handling the categories. Some categories do not allow the deletion of items, whereas others allow automatic deletion when associated actions have been completed.
  
• The IActionInboxItemCategory
  Offers a method to create an item for a category. It also defines various methods to access items within a category or to get information about a category.
• IActionInboxItem
  Stores information about an individual item in a user’s inbox. A central method of the interface executes the action to process the item. Other methods access information about the item like its status, permitted actions and the category it belongs to.
• IActionInboxAction
  Represents a predefined action which can be executed on an item in a category. The available interface methods return information about the action.
• IActionInboxItemProducer
  Represents the application that generates the notification. An application that wants to generate notifications must implement this interface to create IActionInboxItems that are meaningful for the application in question. The IActionInboxItemProducer must be registered with the IActionInboxService.

Code Samples

The code sample shows how to register an IActionInboxItemProducer with the action inbox service. The producer is implemented as an MyServicesActionInboxItemProducer.

IActionInboxService myActionInbox = (IActionInboxService)myResourceFactory.getServiceFactory()
					.getService(IServiceTypesConst.ACTION_INBOX_SERVICE);
if( myActionInbox != null ) {
  // create Instance of our item producer
  IActionInboxItemProducer myActionInboxItemProducer = new MyServicesActionInboxItemProducer();
  // register producer at service
  IActionInboxItemCategory myActionInboxCategory = myActionInbox.registerProducer(myActionInboxItemProducer,
										  "myService"); 
} else {

	// We have a problem...
  }

Configuration

The action inbox service 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 document Administering Content Management.

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

Property	Required	Description
serviceuser	Yes	User used for persisting the items to the userhome repository.
categories	Yes	Path to the XML files that describe all known item notifications. Default: /etc/actioninbox
userhome	Yes	Path to userhome repository where items for a user are presisted. Default: /cm/repository_managers/RepositoryManager
grouphome	Yes	Path to userhome repository where items for a group are persisted. Default: /cm/repository_managers/RepositoryManager
rolehome	Yes	Path to userhome repository where items for a role are persisted. Default: /cm/repository_managers/RepositoryManager
actioninbox	Yes	Root folder name in userhome where items are persisted. Default: actioninbox.
unread	Yes	Folder name where unread items are stored.
read	Yes	Folder name where read items are stored.
done	Yes	Folder name where done items are stored.
doneage	Yes	Time to live for done items. Default: -1 (unlimited)
poolid	Yes	Connection Pool ID for database access (items are persisted in DB as well as in userhome repository)

The following shows a sample configuration for the subscription service:

Name	Value
serviceuser	notificator_service
categories	/etc/actioninbox
userhome	userhome
grouphome	grouphome
rolehome	rolehome
actioninbox	actioninbox
unread
read
done
doneage	-1
poolid	dbcon_r

Implementation Notes

In summary, an application that wants to use the action inbox service must do the following:

1. Write the XML file that describes the structure of the information in the notification. The file provides all the essential information that the action inbox service needs. It contains two types of information:
   
• Data that is defined by the application in advance. For example, the category that notifications belong to, the actions that are permitted for items of a category or the handling of items when the user has processed them.
• Properties that are given values at runtime. The properties define what type of information is needed for the notification at runtime. For example, the name of the recipient, the URL of the resource involved and the text of the notification.
2. Implement the IActionInboxNotification interface. The implementation must be based on the data defined in the XML file. For an abstract implementation the interfaces see the class AbstractActionInboxNotification.
3. Implement the IActionInboxItemProducer interface. The main purpose of the ActionInboxItemProducer class is to handle the actions that are permitted for inbox items. For example, if an update action is permitted, then the class must execute this action. The IActionInboxItemProducer must be registered with the action inbox service specifying the category group and ID entered in the XML.

The XML file is stored under etc\actioninbox and must be specified in the configuration of the service. T he structure of the XML file is defined in a DTD.

The graphic shows the action inbox implementation.