rev 2.0 - 10/09
Contents
Introduction
Getting Set Up
Alert Service Framework
Deploying the Alert Handler
Configuring the Alert Handler
Test the Process

Handling ActiveVOS Server Alerts using Email and Identity Services

Introduction

ActiveVOS Server has built-in system services to simplify handling of alerts generated by the server. ActiveVOS System Administrators no longer need to create Java components to broadcast alert notifications via email. Support for this is now provided by ActiveVOS Server's Email Service, which can be invoked from within a BPEL Process.

In addition to the Email Service, the Identity Service provides functionality to automate the routing of notifications to one of a number of pre-defined groups or users. For instance, your Alert Handling Process can now determine where to send notifications at run-time, based on the name of the process, time of day, or whatever other criteria are available.

The ActiveVOS Designer User's Guide - ActiveVOS_User_Guide.pdf - discusses the Alert, Identity and Email Services in Appendix B - Building a Process with a System Service. By default, the guide is installed in your ActiveVOS Designer doc directory:

[install location]:\ActiveVOS\Designer\designer\doc\

This information is also available in the online Infocenter, accessible here. If you haven't previously read this part of the documentation, please do so now. This sample assumes you understand the basics of using these services.

Objectives

Getting Set Up

The files provided with this article are contained in the downloadable archive (accessible via the links at the bottom of the menu to the left when viewed online). You may extract this archive into a directory of your choosing. The archive contains numerous directories, and includes an ActiveVOS Designer project and various support, test and deployment files.

Because the Identity and Email services are specific to ActiveVOS Server, you should use ActiveVOS Designer to create, simulate and deploy your process. Start ActiveVOS Designer and select File / Import. In the Import dialog, select General / Existing Projects into Workspace, click Next, and navigate to and import the following project directory

[path to extracted archive]/AlertUsingEmailAndIdentity

This opens a project called AlertUsingEmailAndIdentity, which appears in the Project Explorer View.

Note that the sample includes a completed process and WSDL definition for reference (alerthandlerServiceComplete.*).

Using the Alert, Email and Identity Service Framework

ActiveVOS Server can be configured to suspend a running BPEL process whenever that process experiences an uncaught fault. In addition to suspending the process, the server can instantiate an alert service, which can then take some action, such as resuming the process by stepping over the faulting activity, automatically correcting a data value that is known to cause a fault, or simply notifying an operator or administrator that a process is faulting.

You can design a BPEL process to serve as the alert service. The process must expose an operation defined in alert system service.

When invoked, the alert operation receives information from the server regarding the process id, namespace, name, variable location path, and status of the faulting process.

An input message sent to an alert service BPEL process would have the following XML structure:

<ns1:alert xmlns:ns1="http://www.active-endpoints.com/services/alert"
           processId= "101" processNamespace="http://tempuri.org"
           processName="myProcess"
           locationPath="/process/variables/variable[@name='testMessage']"
           status="suspended"
           faultName="someFault"
           faultNamespace="someFaultNamespace">
</ns1:alert>

We'll use the information in the above message to send an email that will notify the appropriate personnel about the faulting/suspended process.

Constructing the Alert Service BPEL Process

In ActiveVOS Designer's Project Explorer View, navigate to the AlertUsingEmailAndIdentity project. Right-click on the completedProcess/bpel folder and select New / BPEL Process... .  Name the process alertHandlerService.bpel. Click Next and select the Alert Process from the list of Available Templates. Finally click Finish.

Taking Action Based On Alert Criteria

We now have a process that can receive incoming alert messages from the ActiveVOS Server. Next, we need to add some activities that will take action based on values in the incoming message. In this process we'll send out an email notice to one of two different sets of users, depending on the status of the process as reported in the alert. In practice, you could use any criteria available when making this sort of choice.

To determine where to send our alert emails, we'll use the Identity Service to get the email address(es) required. The Identity Service keeps a record of users and groups (also known in some circles as principals and roles, respectively). At run time our process will determine which group needs to be notified, and will use the Identity Service to retrieve the email addressing information for that group. We use an If activity to make this determination.

From the Activity Palette to the left of the Process Editor canvas, select an If activity and drop it below the Receive. Select the If condition icon and use the If Expression Builder to create the following expression:

$alert.alert/@status = 'suspended'

We'll be using the Identity Service's findIdentitiesByRole operation to retrieve email information. We need to add the Identity Service to our list of Service Providers in the Participants View by right-clicking on the Partner Service Providers node and selecting New Partner Service Provider....  Change the Provider Name to IdentityProvider, expand the System Services Folder and select the Identity Search Port Type.  Click OK to complete this step.

In the Participants View expand the IdentityProvider and drag the findIdentitiesByRole operation onto the canvas below the If activity. A new Invoke activity is created. Rename the new Invoke activity GetGroupInfo. Save the process.

Inside the If condition, add an Assign activity. Add one Copy Operation to this Assign:

From Type: Expression
Expression: "alertserviceuser"
To Type: Variable
Variable: roleName
Part: [empty]
Query: [empty]

This will cause the GetGroupInfo activity to request group information for the alertserviceuser group. This group is defined as one of the role elements in a file named alert-service-users.xml, which we'll be using later to configure the Identity Service in our ActiveVOS Server. For now, if you take a look at the file (located in the project's conf directory) you'll notice that it uses a format similar to the tomcat-users.xml file normally found in %CATALINA_HOME%/conf.

The alert-service-users.xml file defines two roles (groups), alertserviceuser and alertserviceadmin, and three users, AlertUser1 & 2 and AlertAdminAlertUser1 & 2 are members of the alertserviceuser role (group) and the AlertAdmin is a member of both. The email address assigned to each user is the email address we'll use for notifications. You may want to edit the file at this point to change the default email addresses to real ones, for testing in your environment.

The Assign activity in our If condition determines which group to notify in the case of a suspended process status. Rename this activity to AlertUsers. Other process status values should only send notification to the AlertAdmin. To implement this, our Else condition will need a slightly different Assign activity. Copy AlertUsers (right-click and Copy) and paste it into the Else condition. Rename the new Assign to AlertAdmin. Double-click AlertAdmin and modify the Copy Operation by replacing the "alertserviceuser" Expression with "alertserviceadmin". Save the process.

Extracting Email Address Information and Building the Alert Notification

When GetGroupInfo executes, it sends a request to the Identity Service for information on the group specified in $roleName. This information is returned in the variable identityList. Since our next step is to create the email message we're going to send as an alert notification, we'll use an XQuery 1.0 expression to do two things: extract the email addresses from identityList, creating a "To" entry for each, and construct the message to be sent by the Email Service.

Drop a new Assign activity below GetGroupInfo and rename the new Assign to CreateEmailMessage. In the Participants View create a new service provider for the email system service using the same procedure that you used to create the Identity Service Provider.  Use a name of EmailProvider for this service.  From the Participants view expand the EmailProvider and drag the send operation onto the canvas below CreateEmailMessage. Rename the new Invoke activity to SendAlertEmailMessage.  In the Properties View for select the Input tab and create a new Single Variable and use the default name of emailMessage.

CreateEmailMessage will have two Copy Operations. In the first, we'll construct the body of the email. Before we do that, we need a temporary string variable to store it. In the Outline View, right-click on the Variables declaration section and select Add / Declaration / Variable. In the Definition dialog, select Schema type of xsd:string.

Rename the new variable to emailBody. Now we're ready to create our first Copy Operation in CreateEmailMessage. In the Copy Operation dialog, use the following From and To settings:

From Type: Expression
Expression: concat("Here's the Alert Message data:

Process ID: ", $alert.alert/@processId,"
Namespace: ", $alert.alert/@processNamespace,"
Process: ", $alert.alert/@processName,"
Status: ", $alert.alert/@status)
To Type: Variable
Variable: emailBody
Part: [empty]
Query: [empty]

To preserve the formatting shown above, be sure to take careful note of where the quotes, commas and line breaks are. For best results, copy and paste the expression text from the table above.

In the second Copy Operation we'll construct an XQuery 1.0 expression to extract email addresses from the identityList variable and build the request message to be sent to the Email Service's send operation. 

Now we can construct the second Copy Operation, which is shown below. An in-depth discussion of XQuery 1.0 is far beyond the scope of this sample, so we won't be going into detail here. Examine the query for more information and/or see online XQuery resources for syntax rules, etc. In short, what this expression is doing is combining email addresses from the Identity Service response and creating an XML instance that will be copied directly into the emailMessage variable.

From Type: Expression
Expression: <ns:emailMessage xmlns:ns="http://schemas.active-endpoints.com/email/2007/01/email.xsd"  xmlns:aeid="http://schemas.active-endpoints.com/identity/2007/01/identity.xsd">
  <ns:from>ActiveVOSAlertService@MyCompany.com</ns:from>
 {
   for $user in $identityList/aeid:identity
   where $user/aeid:properties/aeid:property[@name='http://www.activebpel.org/ontologies/higgins/2008/identity-search.owl#email'] != ''
  return
      <ns:to>
         {$user/aeid:properties/aeid:property[@name='http://www.activebpel.org/ontologies/higgins/2008/identity-search.owl#email']/text()}
      </ns:to>
  }
    <ns:subject>Process Status Alert</ns:subject>
    <ns:body mimeType='text/plain'>{$emailBody}</ns:body>
</ns:emailMessage>
To Type: Variable
Variable: emailMessage
Part: [empty]
Query: [empty]

Note: be sure to click the Expression Builder button and select an Expression language of "urn:active-endpoints:expression-language:xquery1.0" at the top of the Expression Builder when you open it to paste the above query.

Your process is now ready to generate alert notification emails to one of two groups, depending on the status specified in the alert. Save your process.

At this point it's not a bad idea to Simulate your process to verify that it performs as expected. Simulation is beyond the scope of this sample, but is covered extensively in the product documentation.

Deploying the Alert Handler

Once you've constructed the alert service BPEL process, it can be deployed to ActiveVOS Server, and configured to handle any alerts sent out due to uncaught faults detected by the BPEL engine. With the pre-defined Identity, Alert and Email services, creating the deployment descriptor for this process, and deploying it, is almost trivial.

Select alertHandlerService.bpel from the Project Explorer and right-click. Select New / Deployment Descriptor to open a new descriptor in the PDD Editor. Navigate to the deploy folder under completedProcess and accept the default filename alertHandlerService.pdd. Click Finish.

Select ActiveVOS Enterprise Server as the Deployment Platform. Leave Process Persistence set to Full. You can optionally enter Sample for the Process Group, or leave it blank. To prevent "endless loop" process invocations in the event of a fault being thrown by this process, set Suspend on Uncaught Fault to false. Click the Partner Links tab (at the bottom of the editor).

The Partner Links tab is where we'll define the run-time bindings for the partner links defined in our process. Change the service name for the alertPL to alertServicePLTService. Select EmailProvider from the list of Partner Links. Under Partner Role, select an Invoke Handler of System Service. Select IdentityProvider from the list of Partner Links and choose an Invoke Handler of System Service.

Once the PDD has been created you can deploy your alert service BPEL process. Ensure that your ActiveVOS Server is running, right-click on the alertHandlerService.pdd file in the Project Explorer View and select Export... In the Export wizard, select Orchestration / Business Process Archive File and click Next. Enter or accept the BPR file destination - the location is not critical, but by default it's best to save BPR files in the project's directory structure (e.g., completedProcess/deploy). Under Deployment select a Type of Web Service. Check the checkbox under the Options section and use the Browse... button to navigate, again, to a location in your project directory structure where you'd like to save the BPRD file (see documentation if you are unfamiliar with the BPRD), e.g.,

/AlertUsingEmailAndIdentity/completedProcess/deploy/alertHandlerService.bprd

Click Finish to deploy your process to the server. Save the PDD.

Configuring the Alert Handler in ActiveVOS Server

First we set up the Identity and Email services. With your ActiveVOS Server instance running, open the Administration Console (see the ActiveVOS Server Administration Console Help PDF if you're unfamiliar with this) and click the Identity Service link in the main menu to the left. Check the Enable checkbox. Select a Provider Type of XML File. Enter a File location on server that identifies the full path to your edited copy of alert-service-users.xml (with your modified email addresses). Typically, it's easiest to place this file in %CATALINA_HOME%/conf and specify the full path of your file system's equivalent location for this entry. Click Test Settings to verify and then click Update when the settings are correct.

Click the Email Service link in the main menu. Check the Enable checkbox and enter the SMTP settings required to send mail from your mail host. Again, see Appendix B of the ActiveVOS Designer User's Guide for details. Click Update when the values are entered.

Next, click the Configuration link in the main menu. Select the Engine Properties tab and check the Suspend process on uncaught fault checkbox. Click Update. Select the Alerts tab and enter a Service value of  alertServicePLTService. Click Update to update the engine configuration. The alertHandlerService process information is displayed. Your process is now set to execute whenever a process experiences an uncaught fault.


Test the Process

To test your alert service BPEL process, simply deploy a process that throws an uncaught fault at some point in its execution. When the process faults and the alert service runs, the email accounts you specified should receive a message indicating the problem.

Alternately - and it's probably a good idea to do this first - you can invoke the process directly using a web service development tool like soapUI. Included in the conf project folder is a soapUI project definition file that is already configured to invoke the process on localhost: AlertService-soapui-project.xml. Set the status attribute to suspended to send notification emails to all users. Set the status to anything else (e.g., faulting) to send notification to the AlertAdmin user only. Remember that the alert service process exposes a one-way operation (alert), so your request will not get a SOAP response message.