Using the ActiveBPEL Enterprise Email and Identity Services to handler Alerts

Introduction

ActiveBPEL Enterprise version 4.0 has new capabilities 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 ActiveBPEL Enterprise's new Email Service, which can be invoked from within a BPEL Process.

In addition to the new Email Service, version 4.0's 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 send notifications at run-time, based on the name of the process, time of day, or whatever other criteria are available.

The ActiveBPEL Designer User's Guide - ActiveBPEL_User_Guide.pdf - for Version 4.0+ discusses the Alert, Identity and Email Services in Appendix B. If you haven't previously read this part of the documentation, please do so now. By default, the guide is installed in your ActiveBPEL Designer Docs directory:

[drive]:\Program Files\Active Endpoints\ActiveBPEL Designer\Docs

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 ActiveBPEL 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 AlertUsingEmailAndIdentity.zip. You may extract this archive into a directory of your choosing. The archive contains numerous directories, and includes an ActiveBPEL® Designer project and various support, test and deployment files.

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

[path to extracted archive]/AlertUsingEmailAndIdentity

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

With the project successfully imported, you can now import the Web Reference files for the Email, Identity and Alert services. A set of these files is provided in the completedProcess folder, however since these definitions may change from one version of ActiveBPEL to the next, it is probably safest to import these from your current ActiveBPEL Designer installation. The following instructions assume the default installation location, so adjust as needed.

In the Navigator view, right-click on the support 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

C:\Program Files\Active Endpoints\ActiveBPEL 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.

Next, switch to the Web References view and select the Add a Web Reference icon. Select the Browse Projects... button and navigate to the support/wsdl directory under AlertUsingEmailAndIdentity. Add the alert.wsdl, email.wsdl and identity.wsdl files. They appear in the Web References View and can now be used to build your custom alert handling process.

Using the Alert, Email and Identity Service Framework

ActiveBPEL Enterprise can be configured to suspend a running BPEL process whenever that process experiences an uncaught. 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 imported into the project and added to Web References.

When invoked by ActiveBPEL, 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:

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

Constructing the Alert Service BPEL Process

In ActiveBPEL Designer's Navigator View, navigate to the AlertUsingEmailAndIdentity project. Right-click on the support/bpel folder and select New / BPEL Process... .  Name the process alertHandlerService.bpel. Note that when this new (empty) process is created, ActiveBPEL Designer will indicate errors. This is normal.

To begin constructing your process, switch to the Web References view and fully expand the alert.wsdl web reference. Drag the alert operation onto the empty canvas. The Define Partner Link Type dialog appears.

Select Create Partner Link Type: and enter alertServicePLT, and for Role: enter handler. 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, enter a Location:

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

You can used the Browse... button to navigate through your local file system to the appropriate location and enter the filename there. Click Finish.

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

Note that ActiveBPEL Designer has added the new alertHandlerService.wsdl file into the list of Web References. The location is based on the file system, but we'd prefer that it be project-relative. To do this, remove the alertHandlerService.wsdl entry from the Web References list (right-click, then Remove Web Reference). Switch to the Navigator View, right-click on the project folder and select Refresh. Switch back to the Web References view and add back alertHandlerService.wsdl, being sure to select the Browse Projects... button before navigating to the file's location.

Once the alertHandlerService.wsdl file has been added back, locate the file-relative Import for this WSDL in the process' Outline View and delete it from the list of Imports. Right click the Imports declaration node in the Outline View and select Refresh Imports to record the new web reference location (select Yes if Designer asks about deleting the obsolete reference). Save your BPEL process.

Note the Problems listed. To fix these, double-click on the new Receive activity. In the Properties view, modify the Create Instance attribute from No to Yes and change the activity name to ReceiveAlertMessage. Save the process.

Taking Action Based On Alert Criteria

We now have a process that can receive incoming alert messages from ActiveBPEL Enterprise. 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 practise, you could use any criteria available when making this sort of determination.

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:

$alertMessage.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 Web References View, fully expand the identityPLT partnerLinkType found in identity.wsdl. 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:

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 ActiveBPEL Enterprise 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 $roleNameInput.roleName. This information is returned in the messageType variable identityListOutput. 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: extractthe email addresses from identityListOutput, creating a "To" entry for each, and construct the message to 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 Web References View, fully expand the emailPLT partnerLinkType in email.wsdl. 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:

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 identityListOutput 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 new namespace entries for the two schema (*.xsd) URIs:

One other minor adjustment we need to make is to change the emailMessage variable's type. By default, this variable was created based on ae-email:emailMessage when we dragged the send operation into our process. We need a variable based on ae-emailtype:emailMessage, which is slightly different. Double-click on the emailMessage variable in the Outline View to bring up the Definition dialog. Select Schema element and ae-emailtype:emailMessage. Click OK.

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.

Note: be sure to 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.

Deploying the Alert Handler

Once you've constructed the alert service BPEL process, it can be deployed to ActiveBPEL Enterprise, 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 Navigator View and right-click. Select New / Deployment Descriptor to start the New Deployment Descriptor wizard. Select ActiveBPEL Enterprise (or ActiveBPEL Enterprise .NET) as the Deployment Platform and click Next. Leave Process Persistence set to (System Default). 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 Next.

The Partner Links page is where we'll define the run-time bindings for the partner links defined in our process. The default setting for our alertServicePLT is fine as it 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. Click Next twice. On the Deployment Descriptor File page, select the AlertUsingEmailAndIdentity/support/deploy folder and click Finish to accept the default file name of alertHandlerService.pdd. Review the new PDD file as desired.

Once the PDD has been created you can deploy your alert service BPEL process. Ensure that ActiveBPEL Enterprise is running, right-click on the alertHandlerService.pdd file in the Navigator View and select Export... In the Export wizard, select ActiveBPEL / Business Process Archive File and click Next. Enter or accept the BPR file desination - the location is not critical, but by default it's best to save BPR files in the project's directory structure (e.g., support/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 the BPRD file, e.g.,

/AlertUsingEmailAndIdentity/support/deploy/alertHandlerService.bprd

Click Finish to deploy your process to the server.

Configuring the Alert Handler in ActiveBPEL Enterprise

First we set up the Identity and Email services. With your ActiveBPEL Enterprise engine running, open the Administration Console (see the ActiveBPEL Enterprise 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 ActiveBPEL 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 in practise, you can invoke the process directly using a web service development tool like soapUI. Included in the support/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., Faulted) 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.

Copyright © 2004–2007 Active Endpoints, Inc.