Chapter 13 Administering the Subscriptions Service

The Subscriptions service enables users to create a profile of interest covering many sources of information. In this release, the sources of information supported include categories, discussions, and searchable documents. The profile is updated with the latest information every time the user accesses the Subscriptions channel. The Subscriptions channel summarizes the number of hits (relevant information) that matches each profile entry the user defined for categorized document and/or discussions.

Match and count the number of new documents in a target category from a specified range of days

Match and count the number of new relevant comments within a discussion from a specified range of days

Match and count the number of document hits against saved searches

The result is displayed as a link that shows the number of matching information to the profile entry. This link redirects the user to a more detailed view of the match itself.

In case of a category subscription, the link redirects the user to the search channel where the specific documents of interest are summarized in a standard category search result format. The Subscriptions channel acts as the doorway to a more detailed view for the user.

The Profiler function provides e-mail notifications when the content of specified interests has changed. The Profiler obtains subscription details for users from the Identity Server, fetches the results from the Search service, and sends e-mail notifications to the users. The Profiler can be scheduled to run at a specific time at the organization level.

Administering the Subscriptions Service

The administrator can enable or disable subscriptions service. The Subscriptions service can be administered at the:

Root Level

Organization level

Organization User level

Root Level

Administering the Subscriptions service at the Root level sets the system wide default maximum number of subscriptions per type (that is, for categories, discussions, and for saved searches). See To Define the Subscriptions Service at the Root Level for information on defining Subscriptions service at root level.

Organization level

Administering the Subscriptions service at the Organization level overwrites the system wide default maximum number of subscription per type (that is, for categories, discussions, and for saved searches). See To Define the Subscriptions Service at the Organization Level for information on defining Subscriptions service at organization level.

Organization User level

Administering the Subscriptions service at the Organization User level edits user’s Subscriptions service settings. The administrator can maintain the user’s service data, such as:

Update user subscriptions

Delete user subscriptions

To Define the Subscriptions Service at the Root Level

Log into the Sun Java System Identity Server administration console and select the Service Configuration tab.

Select the Subscriptions service from the Portal Service Configuration menu on the left pane.

Modify the default values for:

Maximum number of Categories subscriptions specifies the maximum number of categories that a user can subscribe to.

Maximum number of Discussion subscriptions specifies the maximum number of discussions that a user can subscribe to.

Maximum number of Saved searches specifies the maximum number of searches that can be saved.

Select:

Save to save your values.

Reset to reset the values if you modified them.

To Define the Subscriptions Service at the Organization Level

Log in to the Sun Java System Identity Server administration console and select Services from the View pull-down menu for your organization.

Select the Subscriptions service from the Portal Service Configuration menu on the left pane.

Browse to Start Profiler under Organization from the menu bar.

Select the time (hour and minutes) and days to start the robot.

Browse to Stop Profiler under Organization from the menu bar.

Select the time (hour and minutes) and days to stop the robot.

Modify the default values for:

Conflict Resolution Level can be set to Highest, Higher, High, Medium, Low, Lower, and Lowest.

Maximum number of Categories subscriptions specifies the maximum number of categories that a user can subscribe.

Maximum number of Discussion subscriptions specifies the maximum number of discussions that a user can subscribe.

Maximum number of Saved searches specifies the maximum number of searches that can be saved.

Select:

Save to save your values.

Reset to reset the values if you modified them.

Delete.

To Manage the Subscriptions Service for the User

Select the User.

The user information is displayed on the right pane.

Select Subscriptions from the View pull-down menu.

A page to edit the user’s subscriptions is displayed.

Edit the subscriptions definition

For each type of subscription, add or remove subscriptions. The format of:

Category subscription is:

label | target category | scope | lapsed time

where:


label	Refers to a logical reference given to the edited subscription and it must be a string. This is a required field.
target category	Must be of the string format ABC:DEF:GHI
scope	Refers to a search query and it must be of a string format that is a valid search string, including search operators.
lapsed time	Must be one of the following numbers: 0=forever 7=since last week 30=since last month 180=since last 6 months 365=since last year

Discussions subscriptions is:

label | target discussion RD’s URL | scope | lapsed time | minimum rating

where:


label	Refers to a logical reference given to the edited subscription and it must be a string. This is a required field.
target discussion RD’s URL	Must be of string format matching the Discussion’s URL. This cannot be edited by the user using the subscriptions channel for editing the discussion.
scope	Refers to a search query and if must be of a string format that is a valid search string, including search operators.
lapsed time	Must be one of the following numbers: 0=forever 7=since last week 30=since last month 180=since last 6 months 365=since last year
minimum rating	Refers to a filter base on a minimum rating.

Saved searches is:

label | target category | scope | lapsed time

where:


label	Refers to a logical reference given to the edited subscription and it must be a string. This is a required field.
target category	Must be of the string format ABC:DEF:GHI
scope	Refers to a search query and if must be of a string format that is a valid search string, including search operators.
lapsed time	Must be one of the following numbers: 0=forever 7=since last week 30=since last month 180=since last 6 months 365=since last year

Using the Subscriptions Channel

The Subscriptions channel shows subscriptions by types which can be category subscriptions, discussion subscriptions, and saved searches. For each type of subscription, the following is displayed:

The subscription label

A link to the subscription detail representing the number of hits for that particular subscription

An end user can update all the subscriptions and unsubscribe via the subscriptions channel Edit button. End user alerts for matching subscriptions is grouped in the Subscriptions channel. The alerts are generated upon the subscriptions channel’s refresh time. The administrator can set the refreshTime property for the channel that make the actual rendering of the content cache for a certain period of time. When the end user tries to refresh the content of the subscriptions channel more than once within less time than the refreshTime parameter, then the content would be read from the cache instead of being generated from the actual data. The refreshTime channel property value can be specified in seconds.

Is categorized in a subscribed category and matches the scope and time criteria.

Is a comment on a subscribed discussion and matches the scope and time criteria.

Matches saved basic or advanced search criteria and time criteria.

To Subscribe to a Category

You can subscribe to categories via:

Browse categories - this includes a Subscribe link

Search results that show categories - this includes a Subscribe link

Results of search within a category - this includes a Subscribe to Category link

Select the subscribe link next to the category you wish to subscribe.

The page to specify subscription information is displayed.

Specify:

Subscription Name - A name for the category

Target Category- Name of the category

Scope of Search- A query string, similar to the Search text field

Since - Amount of time you wish to be subscribed to the specified category. It can forever, since last week, since last month, since last 6 months, since last year

Select the Finished button.

The category is added to your list of subscriptions.

To Subscribe to a Discussion

You can subscribe to discussions via the view discussions link - this includes a Subscribe link.

Select the subscribe link for the discussion you wish to subscribe.

The page to specify subscription information is displayed.

Specify:

subscription name - A name for the category

target category - Name of the category

scope of search - A query string, similar to the Search text field

since - Amount of time you wish to be subscribed to the specified category. It can forever, since last week, since last month, since last 6 months, since last year.

rating - Threshold rating above which subscription is valid

Select the Finished button.

You are now subscribed to the discussion.

To Save a Search

Access the Search tab and search for a document.

The search result page is displayed.

Select the subscribe link at the top of the result list.

The page to specify subscription information is displayed.

Specify:

Label - Save search label

Scope of Search- A query string, similar to the Search text field

Since - Amount of time you wish to save the specified search result. It can be forever, since last week, since last month, since last 6 months, since last year.

Select the Finished button.

Your search result is now saved.

Discussions

Discussions Overview

DiscussionProvider

Managing and Using the Channels

Discussions Overview

Discussions are tied to topics and specific documents. It is a powerful way for people to add and talk about existing documents or create their own. It provides an easy way to share information about specific documents or new topics.

The Sun Java System Portal Server software discussions feature includes discussion threads, starting discussions based on documents or new topics, searching discussions, and rating discussions. By default, the Discussions channel is available on the sample portal for anonymous users. However, an anonymous user cannot subscribe to a discussion or edit the Discussion channel.

The DiscussionLite channel and the Discussions channel are based on the DiscussionProvider. Similar to the search channel JSPs, they have a query portion, a display portion, and use Desktop themes.

DiscussionProvider

The DiscussionProvider is JSP provider that uses the Desktop themes. It retrieves data from the backend Search service using search tag libraries and API. The discussions and comments are stored as different Resource Descriptors (RDs) in the discussion database. The DiscussionProvider supports:

A full view (via the Discussions channel) and an abbreviated view (via the DiscussionLite channel) that:

Starts a new discussion from the discussion channel.

Posts reply to an existing discussion.

Starts a new discussion based on web documents from the search channel.

A Discussion List that:

Retrieves main posts sorted by last-modified date.

Has pagination so users can access older discussions.

a discussion view that displays each discussion subtree. The main item is displayed in detail and the subtree is displayed below the main item. View discussion includes:

Several filters on the page. A document display can be based on filters such as document rating (irrelevant, routine, interesting, important, and must read).

Display preference can be set to threaded or flat display.

Expansion threshold helps to control displayed items in the subtree. The users can choose to expand only highly rated documents, or expand all or collapse all. Default value is collapse all. Expand all will expand all the filtered comments. It will also show a description of the discussion, provide a menu for rating the discussion, and allow the user to post a reply.

Support to search within a discussion.

Commenting and rating a discussion. For example, users can:

Add a comment on an existing discussion.

Rate all discussions and comments. However user rating is not immediately visible. The rating calculation is based on an algorithm such that the rating for any comment goes up gradually. For example, a comment has to be rated important three times before it is marked as important.

Searching all discussions and within a discussion. These functions are routed to the search provider. Users can also search by rating in Advance Search.

Subscriptions. Authenticated users can choose to subscribe to a particular discussion by selecting the subscribe link. The request is handled by the SubscriptionProvider. The displaySubscription property (see Code Example 13-1) can be disabled if the feature is not required. By default, the value is true.

Display Profile XML Fragment for DiscussionProvider

Code Example 13-1 shows the DiscussionProvider provider XML fragment in the display profile.

Code Example 13-1 DiscussionProvider Provider Display Profile XML Fragment


<Provider name="DiscussionProvider" class="com.sun.portal.providers.jsp.JSPProvider">
<Properties>
<String name="title" value="* Discussions Provider *"/>
<String name="description" value="* DESCRIPTION *"/>
<String name="refreshTime" value="0" advanced="true"/>
<String name="helpURL" value="en/desktop/discussions.htm" advanced="true"/>
<String name="fontFace1" value="Sans-serif"/>
<String name="productName" value="Sun Java System Portal Server"/>
<String name="contentPage" value="discussionContent.jsp"/>
<String name="editPage" value="discussionEdit.jsp"/>
<String name="processPage" value="discussionDoEdit.jsp"/>
<Boolean name="isEditable" value="true" advanced="true"/>
<String name="editType" value="edit_subset" advanced="true"/>
<Boolean name="showExceptions" value="false"/>
<Boolean name="showErrors" value="true"/>
<String name="width" value="thick"/>
<String name="column" value="2"/>
<String name="searchServer" value=""/>
<String name="dbname" value=""/>
<Integer name="viewHits" value="8"/>
<String name="defaultDiscussionDisplay" value="Threaded"/>
<String name="defaultFilter" value="Irrelevant"/>
<String name="defaultExpansionThreshold" value="Collapse all"/>
<Boolean name="viewDiscussionWindow" value="false"/>
<String name="anonymousAuthor" value="anonymous"/>
<Boolean name="displaySearch" value="true"/>
<Boolean name="showDescription" value="false"/>
<String name="ratingText" value="Irrelevant,Routine,Interesting,Important,Must Read"/>
</Properties>
</Provider>

Administering the DiscussionProvider

Channel edit page (this is user configurable)

Desktop Channel and Container Management link on the administration console for the DiscussionProvider’s channel

Search Service

DiscussionLite Channel

The DiscussionLite channel displays the top twenty discussion titles (which can be reconfigured) and the date. The discussions are sorted by creation date (last modified) and the newest discussion is displayed first. The DiscussionLite channel view has links to view each discussion, view all discussions which target the Discussions Channel, and start a discussion. By default, the channel is displayed in a single container and all links are brought up in a JSPDynamicSingleContainer.

Properties can be configured from the administration console. By default, there are no user editable properties for this channel.

Discussions are stored in the discussion database specified in the dbname property in the display profile. Search server host (searchServer property), database name (dbname property), and the number of discussions to be displayed (viewHits property) can be configured in the display profile (see Code Example 13-2.)

Code Example 13-2 DiscussionLiteProvider Channel Display Profile XML Fragment


<Channel name="DiscussionLite" provider="DiscussionProvider">
<Properties>
<String name="title" value="Recent Discussions"/>
<String name="description" value="This is a DiscussionLite provider example"/>
<String name="contentPage" value="discussionLiteContent.jsp"/>
<String name="editPage" value=""/>
<String name="processPage" value=""/>
<String name="width" value="thin"/>
<String name="searchServer" value=""/>
<String name="db" value="discussion"/>
<Integer name="viewHits" value="20"/>
</Properties>
</Channel>

Discussions Channel

discussionLiteContent.jsp	JSP content page.
query.jsp	Sets and executes search query.
display.jsp	Displays results.
error.jsp	Displays exceptions and error messages.

Shows detailed descriptions for the top eight discussions sorted in descending order. This can be reconfigured via the channel edit page.

Includes pagination so that users can see all the discussions.

Supports search. The search returns discussion and comment results.

The Discussions channel properties can be configured from the Sun Java System administration console.

Code Example 13-3 Discussions Channel Display Profile XML Fragment


<Channel name="Discussions" provider="DiscussionProvider">
<Properties>
<String name="title" value="Discussions"/>
<String name="description" value="This is a Discussion provider example"/>
<String name="searchServer" value=""/>
<String name="dbname" value="discussions"/>
<Integer name="viewHits" value="8"/>
</Properties>
</Channel>


discussionContent.jsp	JSP content page
discussionEdit.jsp	The edit page
discussionDoEdit.jsp	The process edit page
declare.jsp
portal.jsp	Extracts the display profile data
fullDiscussion.jsp	handles the full view presentation
fullDiscussionDisplay.jsp	User interface for the all discussions page
searchUI.jsp	Search form displayed on the all discussions page
viewDiscussion.jsp	View discussion
viewDiscussionBar.jsp	Center horizontal bar with all the filters on the view discussion page
viewDiscussionDisplay.jsp	User interface for the view discussion page
viewDiscussionHeader.jsp	Header comment display on the view discussion page
viewDiscussionNavigation.jsp	Navigation bar displayed above and below the header on the view discussion page
feedback.jsp	Provides comment, feedback, and rating functionality
feedbackDisplay.jsp	Displays the feedback
feedbackForm.jsp	Provides the feedback form
feedbackProcess.jsp	Processes the feedback
error.jsp	Displays exceptions and error messages
query.jsp	Formats and executes the search query
pageFooter.jsp	Provides pagination

Managing and Using the Channels

Administering the DiscussionProvider Channel

Administration of the DiscussionProvider channel is distributed between the Desktop display profile and the Search service in the Sun Java System Identity Server administration console. Provider specific information is stored in the display profile. Discussion document and database related administration must be done in the Search service.

Discussions are stored in the discussion database. The discussion database expects a specific schema for discussions and comments. New schema fields have been added for this feature in theschema.rdm file.The search CLI rdmgr can be used for database management and debugging. For example, to dump all the comments, type:

The sample DiscussionProvider channels are configured to use the default search server. Some sample discussions which are imported in the discussion database and channel is ready for use.

The samples are located at S1PSBaseDir/SUNWps/samples/discussions/ directory. They are:

Access to discussions can be controlled (to read only or totally hidden) by the administrator.

To Create a Channel from DiscussionProvider

discussions.soif	A sample SOIF file loaded in the discussion database.
dp-org.xml	Contains the discussion channel display profile XML fragments.
dp-providers.xml	Contains the discussion provider display profile XML fragments.
dp-anon.xml	Contains XML fragment for the authlessanonymous user, loaded at sample portal install time.

The list of services is displayed in the left frame.

Select Desktop and Channel and Container Management.

Note that the Channel and Container Management link is available in the right frame.

Select the Add button under Channels.

The page to specify the type of channel to add is displayed.

Specify a name for the channel in the Channel Name text box and select DiscussionProvider from the Provider pull-down menu.

Select Create.

This action creates a channel based on the specified provider. The Cancel button returns you to the Channel and Container Management page without creating any new channels.

Select the Edit link next to the newly created channel in the Channels table.

The page to edit the default values of the channel is displayed.

Edit the properties and select the Save button to save the modified values.

The following display profile properties are specific to this provider:


searchServer	Path to the search server. By default, portal/portal/search.
dbname	Any valid database.
viewHits	Number of discussions to display.
defaultDiscussionDisplay	This can be set to flat or threaded to allow the comment subtree to be displayed as flat or threaded.
defaultFilter	Filter for searching and displaying discussions and control display of the subtree. It can be based on ratings such as irrelevant, routine, interesting, important, or must read. By default, its value is irrelevant; so all comments rated irrelevant and above are displayed. The Must read filter will highlight the highly rated comments.
defaultExpansionThreshold	This can be set to expand all or collapse all. By default, its value is set to collapse all. If set to expand all, it will expand all the filtered comments, show description, rating menu, and allow user to post reply via links.
anonymousAuthor
viewDiscussionWindow
displaySearch
showDescription	For the Discussions channel, this is configurable.
ratingText	By default, discussions can be rated at irrelevant, routine, interesting, important, or must read.