How to Trigger Notifications when Elements Change in Rule Team Server

Samples > Rule Team Server Business Rule Management Extensions > How to Trigger Notifications when Elements Change in Rule Team Server

How to Trigger Notifications when Elements Change in Rule Team Server

PREVIOUS NEXT

This sample shows how to:

Generate notifications for actions performed on model elements in Rule Team Server. For example, when a rule is created, updated, or deleted by a business user, an automatic notification through RSS can be triggered to inform the development team of the change. The change notification will include such information as the name of the user, the name of the rule affected, and the name of any modified properties, together with their old and new values.
Use permanent links.
Enable anonymous sign-in, and restrict their permissions to read-only.
Redefine the seach criteria according to the role of the user.

To show these, the change notification URL is generated using a permanent link on the modified element. This link allows users to access Rule Team Server as anonymous users with read-only permissions. In addition, anonymous users can only view rules that have a status of new.

Implementing these requirements in Rule Team Server involves the following:

Write a custom session controller to redefine the behavior of Rule Team Server when committing or deleting an element, computing the possible values for a feature, and so on, and to only show rules having a status of new to users signed in as anonymous users. Deploy this session controller to Rule Team Server.
Generate an anonymous permanent link on the modified element.
Limit the permissions of anonymous users to read-only using UI customization.
Generate RSS data and make it available from the web server, and then invite interested users to subscribe to the RSS feed using an RSS reader tool.

Key Features

Key features of this sample include:

Custom session controller
Permanent links
Anonymous access
Redefine the search criteria
UI customization for read-only users
Repackage the EAR application
Deploy the customized EAR

Installing this Sample

To install this sample through the Samples Console:

Check that the Samples Server is started. For information on how to start and stop the Samples Server, see Stopping and Restarting the Samples Server from the Samples Console.
Go to the Samples Console and locate the teamserver > serveractionnotification sample.
Execute the deploy command to deploy the new EAR.

This compiles the application, repackages the EAR, and deploys it to the application server.

Wait for the Java EE application to start before continuing.

Running this Sample

This sample can only be opened and run in the Samples Console.

How to Trigger Notifications

To see how you can be notified of modifications:

Execute the run command in the Samples Console to create a project, some packages, and two rules that will be used to trigger notification.

Note

The sample handles only the ActionRule element.

The RSS data is displayed on the console in XML format.

Click on the following link to subscribe to the RSS feed:

http://localhost:8080/teamserver/RSSRawProvider.jsp

Note

You can also configure your own RSS reader to be notified each time a rule is modified.

Note

The RSS format may not be recognized on certain browser versions. In this case, the tree is shown as XML.

Notice the changes that you have just done.

How to Use Permanent Links and Enable Anonymous Sign-in

In the RSS reader, copy the permanent link from either rulename1 or rulename1Active to your browser.

This link has the format http://localhost:8080/teamserver/anonymous/faces/explore/details.jsp?project=...

Notice, at the right of the top banner, that you are not signed in, and that as an anonymous user you do not have access to any of the editing buttons in the toolbar.

Click the Query tab.

Here, again, you do not have any editing buttons available.

Click the Explore tab.
Click the folder Samplepath > Samplepath1.

Notice how you only see rules with a status of new.

In the Samples Console, double-click the resetrss command to reset the RSS data on the server.
Refresh your Reader to see how recent changes have been cleared.

Source Files

This sample is located in <InstallDir>/teamserver/samples/serveractionnotification.

NotificationController.java - Implements ilog.rules.teamserver.model.IlrSessionController by extending ilog.rules.teamserver.model.IlrDefaultSessionController. It provides the following methods:

onCommitElement(IlrCommitableObject cobject) - Called before an object is created or updated.
onDeleteElement(IlrElementHandle handle) - Called before an element is deleted.

The onCommitElement and onDeleteElement methods throw an exception if the user is anonymous. Otherwise they create an Event object instance containing all the required data.

elementCommitted(IlrCommitableObject cobject,IlrElementHandle newHandle) - Called when the object creation or update is committed.
elementDeleted(IlrElementHandle handle) - Called when the delete is committed.

The elementCommitted and elementDeleted methods create an Item object instance that is delivered to a listener. In this sample, the listener is a class that will generate RSS formatted data.

redefineSearch(IlrSearchCriteria searchCriteria) - Called each time a search is performed using a search criteria. It is redefined to have anonymous users view only rules with the status new.

NotificationListener.java - The interface that the listener must implement.
Constant.java - Represents all constants manipulated through the sample.
Configuration.java - Holds the configuration set in the preferences.properties file.
Event.java - Represents an event (an action performed in Rule Team Server but not yet committed).
Item.java - Represents a committed instance item (for example, 3 deleted rules leads to 3 item instances, even if it is done in one step).
HistoryValues.java - Represents the history of modifications.
ModelHelper.java - Extracts element property values before and after modification.
ProjectFactory.java - A helper class for creating project and rule artifacts, as well as getting and resetting RSS data.
StringHelper.java - A helper to manipulate strings.
RSSNotificationListener.java - Stores the item instances in memory, persists them in a file whenever the application server shuts down, and loads them from the file when the application server starts.
RSSHelper.java - A helper for manipulating RSS data.
RSSRawProvider.jsp - The news provider for this sample. Most of the time, RSS Reader reads news from an HTTP source. You can also use an RSS reader to subscribe to the RSS feed at http://localhost:8080/teamserver/RSSRawProvider.jsp.
RSSResetRawProvider.jsp - A convenient JSP helper to reset the news.
MyIsUserInRoleCallback.java - Implements ilog.rules.teamserver.model.IlrIsUserInRoleCallback by extending ilog.rules.teamserver.model.IlrDefaultIsUserInRoleCallback. It provides the following method:

isUserInRole(String role) - Called when you call session.isUserInRole(role). It is redefined to define the anonymous role.

Util.java - A utility class to get localized messages.
MyDetailsToolbarBean.java - Extends ilog.rules.teamserver.web.beans.DetailsToolbarBean to disable the editing features in the Details toolbar.
MyQueryToolbarBean.java - Extends ilog.rules.teamserver.web.beans.QueryToolbarBean to disable the editing features in the Query toolbar.
MyTableToolbarBean.java - Extends ilog.rules.teamserver.web.beans.TableToolbarBean to disable the editing features in the toolbar above tables.
MyTreeToolbarBean.java - Extends ilog.rules.teamserver.web.beans.TreeToolbarBean to disable the editing features in the toolbar above the tree.
MyLinkBean.java - Extends ilog.rules.teamserver.web.beans.LinkBean to disable the Compose tab.
WebUtil.java - A utility class used by MyDetailsToolbarBean, MyQueryToolbarBean, MyTableToolbarBean, and MyTreeToolbarBean to disable editing features in the toolbars if the user is anonymous.
extended-faces-config.xml - Located in webresource\WEB-INF, it is the JSF configuration file for extended features. Here it is used to configure the beans to be used to customize the UI for read-only users.
messages.properties - Located in \resources, it is the messages file used to get the message printed when an exception is thrown in the onCommitElement and onDeleteElement methods of the controller.
anonymous-web.xml - Located in \data, it is a descriptor used to enable anonymous sign-in. This descriptor is merged with the original descriptor for the application server in the build phase.

Highlights

Highlights of this sample are as follows.

Create or update an element

The NotificationController.onCommitElement() method is called when entering the IlrSession.commit method, just before committing an element. An event containing all relevant data is created and stored in a thread-local storage. The NotificationController.elementCommitted() is called just after an element has been committed. The event is retrieved from a thread-local storage and an RSS item is created in memory.

Delete an element

The NotificationController.onDeleteElement() method is called when entering the IlrSession.delete() method, just before deleting an element. The NotificationController.elementDeleted() method is called just after an element has been deleted.

Make an RSS reader HTTP request

RSS data is made available via an HTTP request. Whenever an RSS reader requests RSS data, the .jsp script is executed and an RSS-formatted string is returned. All RSS items generated by creating, updating, or deleting are stored in memory, as shown above. When the application server shuts down, items are persisted in a file and when the application server is restarted, items are read from the file and loaded into memory.

Customize the Rule Team Server EAR file

To configure Rule Team Server to use the new controller, a custom session controller is implemented. It is specified in a preferences.properties file (teamserver.controller.class=ilog.rules.rts.samples.notification.model.NotificationController) and stored in a JAR file. Also specified in this file is the isUserInRole class to be used (teamserver.isUserInRole.class = ilog.rules.rts.samples.notification.model.MyIsUserInRoleCallback).

Included are three additional JAR files containing the sample code and an RSS library.

This customization is done in the build.xml file. The repack command calls a predefined target named repackage-ear that helps repack the Rule Team Server EAR. This command uses the following parameters:

sourceEar: The initial EAR file
targetEar: The customized EAR file
additionalJars: Additional JAR files required by this sample:

sample-controller.jar: Contains the sample code, the preference.properties file, and the messages.properties file.

rome-0.8.jar: ROME is an open source (Apache license) set of Atom/RSS Java utilities that make it easy to work in Java with most syndication formats, including RSS 0.90, RSS 0.91 Netscape, RSS 0.91 Userland, RSS 0.92, RSS 0.93, RSS 0.94, RSS 1.0, RSS 2.0, Atom 0.3, and Atom 1.0.

webResourcesDir: A directory that includes the .jsp files, the web.xml descriptor with the anonymous sign-in enabled, the extended-faces-config.xml JSF configuration file, and the sample-web.jar containing the sample code to customize the UI for read-only users.

Generate permanent link

To get a permanent link on the modified element, you use the method getElementDetailsURL from the class ilog.rules.teamserver.model.permalink.IlrPermanentLinkHelper.

You create an instance of IlrPermanentLinkHelper with anonymous enabled.

Enable anonymous sign-in

Anonymous sign-in is enabled by adding the extensionsFilter, the accessFilter, and the Faces Servlet mapping for anonymous in the web.xml descriptor. These lines are already present in the delivered web.xml file so you simply have to uncomment them. In the sample, to do this automatically when repackging the EAR, two descriptors are merged: anonymous-web.xml located in the \data directory, and the original one we get from the Rule Team Server EAR (see the build.xml file for more details).

Customize the UI to have anonymous users connected to a read-only Rule Team Server

To do this, some bean classes are redefined: DetailsToolbarBean, QueryToolbarBean, TableToolbarBean, TreeToolbarBean, and LinkBean to disable the editing features in the toolbars as well as the Compose tab.

Once these classes are redefined, they are added to the JSF configuration file for extended features, extended-faces-config.xml, and this file is added to the repackaged EAR.

Redefine the search

To redefine the search criteria to have anonymous users view only rules with the status new, redefine the redefineSearch method on the controller.

Rebuilding this Sample

To rebuild this sample, execute the build command to recompile the code.

Related Concepts

Rulesets and Ruleset Archives

Extracting Artifacts to be Put in a Ruleset

Related Tasks

Deploying and Exporting RuleApps

PREVIOUS NEXT