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 functions to simplify handling of alerts generated by the engine. BPEL 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 - Special Purpose BPEL Processes. By default, the guide is installed in your ActiveVOS Designer doc directory:

[drive]:\activeVOS_5.0.0\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

Implement a custom alert service BPEL process using the alert.wsdl, email.wsdl and identity.wsdl service definitions
Add the custom alert service to an ActiveVOS server
Use soapUI and one or more test BPEL processes to exercise the custom alert service

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.*).

With the project successfully imported, in the Interfaces View you see the Partner Link Type and Port Type definitions associated with the various services - alertServicePLT, alertPT, etc. If those aren't visible, right-click on the AlertUsingEmailAndIdentity project and select Add Orchestration Nature. Once ActiveVOS Designer has finished building the project, the Interfaces View displays the service definitions.

A set of WSDL and Schema files is provided in the completedProcess folder in the sample archive for reference. However, since these definitions may change from one version of ActiveVOS to the next, it is probably safest to import them from your current ActiveVOS Designer installation. The following instructions assume the default installation location, so adjust as needed.

In the Project Explorer view, right-click on the completedProcess folder of the AlertUsingEmailAndIdentity project and select Import... In the Import dialog, select General / File System, and click Next. Click the Browse... button to the right of the From directory: textbox and navigate to

[drive]:\activeVOS_5.0.0\designer\support

Click the plus sign to the left of the support directory to expand it in the left-hand pane. Select (i.e., do not check) the schema subfolder. In the right-hand pane, check the boxes next to email.xsd and identity.xsd. Back in the left-hand pane, select the wsdl subfolder. On the right, check the boxes next to alert.wsdl, email.wsdl and identity.wsdl. Click Finish to import local copies of these five files into your project. Click the Yes To All button if a dialog pops up asking if you want to overwrite existing files.

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.wsdl, which we have just imported into the project.

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. Note that when this new (empty) process is created, ActiveVOS Designer will indicate errors in the Problems View. This is normal.

To begin constructing your process, go to the Interfaces View and expand the alertPT entry under Port Types. Drag the alert operation onto the empty canvas. The Create Activity wizard appears. Accept the default selection, BPEL Activity, and click Next.

Select the Create Partner Link Type: radio button and enter alertServicePLT, and for Role: enter handler if that isn't entered for you automatically. Click Next.

The partnerLinkType definition for our operation (which is not included in alert.wsdl) is defined next. Leave Create new WSDL file selected and enter a Target Namespace:

http://docs.active-endpoints.com/wsdl/samples/2007/06/alertHandlerService

Below that, navigate to and enter the following Location:

[project path]\completedProcess\wsdl\alertHandlerService.wsdl

Click Finish.

The Operation: alert dialog appears. Leave Receive selected and click Finish to accept the default partnerLinkType and role. A new Receive activity appears on your process canvas. Save the process (continue to ignore any errors/warnings at this point).

Note that ActiveVOS Designer has added a new alertServicePLT entry into the list of Partner Link Types in the Interfaces View. This appears to be a duplicate until you mouse over each of these entries in turn and note that one is from alertHandlerServiceComplete.wsdl and the other is from your newly created alertHanderService.wsdl.

Taking Action Based On Alert Criteria

We now have a process that can receive incoming alert messages from 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. Double-click on the If condition icon and use the If Expression Builder to create the following expression:

$alert/@status = 'suspended'

Click OK. Right-click on the If activity's main icon and select Add / Other / Else to add an Else condition. Change the If activity's name to DetermineWhichGroupToAlert.

We'll be using the Identity Service's findIdentitiesByRole operation to retrieve email information. To find this operation in the Interfaces View, fully expand the service role under the identityPLT Partner Link Type. Drag the findIdentitiesByRole operation onto the canvas below the If activity. The Operation: findIdentitiesByRole dialog appears. Select Invoke and click Finish to accept the default variables for this invocation. Rename the new Invoke activity GetGroupInfo. Shift-select the Receive, If and Invoke activities (in that order), right-click any one of these and select Link Activities. 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 AlertAdmin. AlertUser1 & 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 messageType 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. Create a link from GetGroupInfo to CreateEmailMessage. In the Interfaces View, fully expand the emailPLT Partner Link Type. Drag the send operation onto the canvas below CreateEmailMessage. Select Invoke and click Finish. Rename the new Invoke activity to SendAlertEmailMessage and create another link from CreateEmailMessage to the SendAlertEmailMessage.

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/@processId," Namespace: ", $alert/@processNamespace," Process: ", $alert/@processName," Status: ", $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. For this XQuery expression to work as provided, you'll need to adjust your namespace prefixes to match those used in the expression. In the Outline View, expand the Namespaces declaration section and ensure that the Namespace Prefix / URI combinations are defined as shown. Note that the namespaces for the WSDL references will already exist as ns1, ns2, etc. Modify them as shown below. You'll need to create a new namespace entry for the identity.xsd schema URI:

Prefix	URI
alert	http://www.active-endpoints.com/services/alert
alertHandler	http://docs.active-endpoints.com/wsdl/samples/2007/06/alertHandlerService
aeid	http://docs.active-endpoints/wsdl/identity/2007/03/identity.wsdl
ae-email	http://docs.active-endpoints/wsdl/email/2007/04/email.wsdl
ae-emailtype	http://schemas.active-endpoints.com/email/2007/01/email.xsd
aeid-type	http://schemas.active-endpoints.com/identity/2007/01/identity.xsd

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:	<ae-emailtype:emailMessage xmlns:ae-emailtype="http://schemas.active-endpoints.com/email/2007/01/email.xsd"> { for $user in $identityList/aeid-type:identity where $user/aeid-type:properties/aeid-type:property[@name='email'] != '' return <ae-emailtype:to> {$user/aeid-type:properties/aeid-type:property[@name='email']/text()} </ae-emailtype:to> } <ae-emailtype:from>ActiveBPELAlertService@MyCompany.com</ae-emailtype:from> <ae-emailtype:subject>Process Status Alert</ae-emailtype:subject> <ae-emailtype:body mimeType='text/plain'>{$emailBody}</ae-emailtype:body> </ae-emailtype: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 Professional and Enterprise 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. The default settings for our alertServicePLT are fine as is. Select emailPLT from the list of Partner Links. Under Partner Role, select an Invoke Handler of email (near the bottom of the drop-down list). Select identityPLT from the list of Partner Links and choose an Invoke Handler of identity.

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.