WebSphere Dashboard Framework Alerting Sample

Prerequisites

This sample demonstrates how to use the WebSphere Dashboard Framework (WDF) alerting feature to generate alerts that can be viewed in Portal. It uses a sample sales orders database and a sample alert definition that generates alerts when the total sales for a region are below a set threshold. The remainder of this document cover the steps needed to install , configure, and verify the sample in a WDF development environment.

Before you can configure and run this sample a number of components must be in place. You must have the following installed and ready for use:

• A version of WebSphere Portal compatible with WDF 7.0.1
• WDF Version 7.0.1 installed and a development project created and deployed to Portal
• A supported database into which the alerting tables have been created
• A supoprted database into which the sample sales orders table will be created
• A datasource defined for the alerting database and one for the sales orders database
• WDF alerting configured to store its data in the alerting database

Instructions for completing these prerequisites is beyond the scope of this document, but documentation on most of these topics is included as part of WDF 7.0.1 and Portal / WebSphere.

Setup

Follow these setup steps.

Adding WDF to a Project

The first step is to add the WDF feature sets to your development project. In Designer right click on the project and select “Properties” from the menu. Expand the “WebSphere Portlet Factory” folder and click on “Feature Info”. You should see a dialog such as the one below.




Click on the “Alerts Module” and “Dashboard Framework” selections then press “OK” and allow Designer to update and deploy the project.

Importing the Sample Files

The sample files are contained in the attached file WDF701AlertingExample.zip. They are imported into a project by right clicking on the project and selecting “Import” then “WebSphere Portlet Factory Archive” as shown below.



In the dialog that appears browse to the location where WDF701AlertingExample.zip is stored and select this file. Then press “Finish” and allow Designer to update the project. Do not allow Designer to deploy the project if that option is presented; a few more updates are required before the project is deployed with the sample.

Setting override properties

There are a number of properties that can be set to control how WDF alerting behaves; they are covered in detail in the WDF and Alerting guides. For this sample it is recommended to set the following properties in WEB-INF/config/override.properties in the project.



These values ensure that the sample will perform reasonably under load and use a minimal amount of heap.

Note: override.properties should already contain properties that direct WDF alerting to us a database to store its data. If properties similar to the following are not present, then you have not completed the prerequisite to configure WDF alerting to use a database and you must complete that before proceeding.

Configure Sample Sales Table

In Designer open the model Alerting_Examples_Provider_Orders_Admin.model under the folder WEB-INF/models/solutions/alerting/examples/data_providers/. The model will have at least one regeneration error because the sales orders table does not yet exist. Double click on builder 3 in the outline view. You should now see the SQL Table Create builder UI displayed as illustrated below.



Click on “Fetch DataSource Names”. Then click on the profile icon for the SQL DataSource input. You should now see the following dialog.



Click on the pencil icon to reveal the following dialog:



Use the pull down selection list to select the JDBC datasource that points to the database where the sales orders table will be created. Click “OK” two times and then scroll down until you see the “Create Table” button. Click this button and the builder will create the table and prepopulate it with sample data. If that process is successful, then you will see a confirmation dialog as below.



Now click the “Apply” button at the bottom of the builder's UI to force a model regeneration. All errors should now disappear.

Verify Sample Sales Database

Run Alerting_Examples_Provider_Orders_Admin.model to verify that the sample table was populated correctly. A browser window will appear with the following display.



Click “listOrders” to view of all the sample sales data. There should be 3000 rows (note that the rows start numbering with 0 so the last one will have an ID of 2999).

By running the model you also created a set of indices on the table to ensure that the alerts engine can access the data in an efficient way. The presence of these indices can be verified using the administration tool provided by your database.

Configure Alerting Data Provider

Open the model Alerting_Examples_Provider_Orders.model under the folder WEB-INF/models/solutions/alerting/examples/data_providers/. The model may have some regeneration errors; those will be addressed by reconfiguring a few builder inputs to correspond to you database environment. Double click on builder 2 in the outline view. You should now see the SQL Data Services builder UI displayed as illustrated below.



Notice that the SQL DartaSource input has the name you selected earlier. If not, then you may not have correctly completed the prior step and should revisit that section.

Click on “Fetch Entity Names” then use the pull down selection list for “Table Name” to select the correct SALESORDERS table. Click the “Apply” button at the bottom of the builder's UI to force a model regeneration. All errors should now disappear.

Verify Alerting Data Provider

Run Alerting_Examples_Provider_Orders.model to verify that the provider is able to access the sample table. A browser window will appear with the following display.



Click “getSalesByRegion” to view the sales data that will be fed to the WDF alerting engine. You should see this view:

Deploy Project

At this stage the project is completely configured and ready for deployment. Deploy the project to your Portal.

Place Sample Portlets

Log in to Portal and create a page where you can place the sample portlets. Add the following portets to the page (these are the portlet titles):

• Alerts Module Example - Add Sales Order Portlet
• Alerts Module Example - Sales Orders Portlet
• My Alerts
• Import Definitions

The first two are from the sample package. The third is the standard My Alerts portlet that shows all of the alerts visible to the user. The last is a standard alerting administration
portlet used to import alert definitions into the alerting database.

Import Sample Alert Definition into Alerting Database

In the Alert Definitions tab of the Import Definitions portlet you should see an entry as shown below. This indicates that the sample alert definition appears in the project as an XML file, but has not been imported into the alerting database. Click “Import” and the definition will be added to the database.

Verify Portlet and Alerting Functionality

At this point the alerts engine will have all it needs to start generating alerts for the My Alerts portlet which should now have the following content.



This shows that 2 alerts have been generated; the North East and North West sales regions have do not have total sales that exceed the configured threshold of $200,000. Alerts Module Example - Sales Orders Portlet will also appear as follows.



This is just a different way of viewing the alerts. In this case, the alerts are integrated with the data display showing the total sales for all regions. Notice that the North East and North West sales amounts are highlighted in red. This is caused by the alerts for those regions telling the model to highlight any regions that fall below the threshold.

You can now use Alerts Module Example - Add Sales Order Portlet to add sales to any of the regions to see how that changes the alerting state. If, for example, you add a $20,000 sale to the Norht East region, then click “Refresh” the alert disappears because that region's total sales exceed the $200,000 threshold.