17 Using the Notification Service

This chapter describes how to send notifications from a BPEL process using a variety of channels. A BPEL process can be designed to send email, voice message, instant messaging (IM), or short message service (SMS) notifications. A BPEL process can also be designed to consider an end user's channel preference at runtime for selecting the notification channel.

This chapter includes the following sections:

Section 17.1, "Introduction to the Notification Service"
Section 17.2, "Introduction to Notification Channel Setup"
Section 17.3, "Selecting Notification Channels During BPEL Process Design"
Section 17.4, "Allowing the End User to Select Notification Channels"

Note:

The fax and pager notification channels are not supported in 11g Release 1 (11.1.1).

17.1 Introduction to the Notification Service

Various scenarios may require sending email messages or other types of notifications to users as part of the process flow. For example, certain types of exceptions that cannot be handled automatically may require manual intervention. In this case, a BPEL process can use the notification service to alert users by voice, IM, SMS, or email.

The contact information (email address, phone number, and so on) of the recipient is either static (such as admin@yourcompany.com) or obtained dynamically during runtime. To obtain the contact information dynamically, XPath expressions can retrieve it from the identity store (LDAP) or extract it from the BPEL payload.

This chapter uses the following terms:

Notification

An asynchronous message sent to a user by a specific channel. The message can be sent as an email, voice, IM, or SMS message.
Actionable notification

A notification to which the user can respond. For example, workflow sends an email to a manager to approve or reject a purchase order. The manager approves or rejects the request by replying to the email with appropriate content.
Human task email notification layer

Sends email notifications directly from a BPEL process or implicitly from the human task part of a BPEL process. Implicit notifications are modeled from the Human Task Editor.

For sending email notifications directly from a BPEL process, you must explicitly specify the user information in the BPEL process and can be inside or outside of a human task scope.

For sending email notifications implicitly from the human task part of a BPEL process, you only specify the recipient based on the relationship of the user with regards to the task (that is, the creator, assignee, and so on).

Note:

Implicit notifications are processed through more layers of code than explicit notifications. If explicit notifications are functioning correctly, it does not mean that implicit notifications also function correctly.
Oracle User Messaging Service

Oracle User Messaging Service is a new feature for release 11g. The BPEL notification service uses the underlying infrastructure provided by Oracle User Messaging Service to send notifications.

Oracle User Messaging Service also provides the user preference infrastructure for getting the end user's preferred channel during runtime.

For more information on the Oracle User Messaging Service, see Appendix 62, "Oracle User Messaging Service."

Figure 17-1 shows the Oracle User Messaging Service interfaces and supported service types.

Figure 17-1 Service Interfaces and Supported Service Types

Description of "Figure 17-1 Service Interfaces and Supported Service Types"

For more information about notifications, see the following section:

Section 34.2, "Notifications from Human Workflow"
Section 29.8, "Specifying Participant Notification Preferences" for instructions on specifying email notifications in the Human Task Editor
Part XI, "Using Oracle User Messaging Service"

17.2 Introduction to Notification Channel Setup

Notification setup is a multiple-step process that involves three user interface tools. Table 17-1 provides an overview of this process, including the task to perform, the tool to use, and the documentation to which to refer for more specific details.

Table 17-1 Notification Tasks

Task	Description	User Interface	Described In...
Select a channel for sending notifications in a SOA composite application.	Select a method for sending notifications: Explicitly select and configure an email, IM, SMS, or voice channel. or Do not explicitly select a notification channel, but simply select that a notification must be sent. Channel selection occurs later in the User Messaging Preferences user interface.	Selected and configured by the BPEL process designer in Oracle BPEL Designer	Section 17.3, "Selecting Notification Channels During BPEL Process Design" or Section 17.4, "Allowing the End User to Select Notification Channels"
Configure the driver for the notification channel	You configure drivers on the same Oracle WebLogic Server on which you deploy the SOA composite application. This action enables participants to receive and forward notifications. Driver support is provided for email, IM, SMS, and voice channels.	Configured by the administrator in Oracle Enterprise Manager Fusion Middleware Control	Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite
Configure the notification mode and actionable accounts for human workflows	If you are using notifications with human workflow, you configure the notification mode and actionable account for email.	Configured by the administrator in Oracle Enterprise Manager Fusion Middleware Control	Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite
Register the devices used to access messages by specifying user preferences	This action enables workflow participants to receive notification messages. For example, the end user registers email clients and specifies the message content to receive and the channel to use for receiving messages. If no channel is specified, email is used by default. The preferences set in this application are applicable only to that specific end user, and not to other users.	Registered by the end user in the User Messaging Preferences user interface. You can access this interface by selecting Preferences > Notification in Oracle BPM Worklist.	Part XI, "Using Oracle User Messaging Service"

17.3 Selecting Notification Channels During BPEL Process Design

Oracle JDeveloper includes the email, IM, SMS, and voice channel notification channels in the Component Palette. You can set the exact notification channels to use during design time. For example, a BPEL process can be designed to use the following notification channels:

If an expense report amount is less than $1000, an email notification channel is used.
If an expense report amount is between $1000 and $2000, an SMS notification channel is used.
If an expense report amount is more than $2000, a voice notification channel is used.

To select the notification channel during BPEL process design:

In the Component Palette, expand Oracle Extensions.
Drag a notification channel into the designer:
- Email
- IM
- SMS
- Voice

See the section in Table 17-2 based on the notification channel you selected.

Table 17-2 Notification Channels

If You Selected...	See...
Email	Section 17.3.1, "How To Configure the Email Notification Channel" to configure email notification
IM	Section 17.3.2, "How to Configure the IM Notification Channel" to configure IM notification
SMS	Section 17.3.3, "How to Configure the SMS Notification Channel" to configure SMS notification
Voice	Section 17.3.4, "How to Configure the Voice Notification Channel" to configure voice message notification

Note:

If you delete an email, voice, SMS, or IM activity, any partner link with which it is integrated is not automatically deleted.

17.3.1 How To Configure the Email Notification Channel

When you select Email from the Component Palette, the Email dialog appears. Figure 17-2 shows the required email notification parameters.

Figure 17-2 Email Dialog

Description of "Figure 17-2 Email Dialog"

To configure the email notification channel:

Enter information for each field as described in Table 17-3.

Note:

For the To, CC, and Bcc fields, separate multiple addresses with a semicolon (;).

Table 17-3 Email Notification Parameters

Name	Description
From Account	The name of the account used to send this message. The default account is named Default and is editable from the Workflow Notification Properties page in Oracle Enterprise Manager Fusion Middleware Control. To add additional accounts, you must use the System MBean Browser in Oracle Enterprise Manager Fusion Middleware Control. For information on editing this property in Oracle Enterprise Manager Fusion Middleware Control, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle Business Process Management Suite.
To	The email address to which the message is to be delivered. This can be one of the following: A static email address entered at the time the message is created An email address retrieved using the identity service A dynamic address from the payload The XPath Expression Builder can get the dynamic email address from the input. See Section 17.3.5, "How to Select Email Addresses and Telephone Numbers Dynamically."
CC and Bcc	The email addresses to which the message is copied and blind copied. This can be a static or dynamic address, as described for the To address.
Reply To	The email address to use for replies. This can be a static or dynamic address, as described for the To address.
Subject	The subject of the email message. This can be plain text or dynamic text. The XPath Expression Builder can set dynamic text based on data from process variables that you specify.
Body	The message body of the email message. This can be plain text, HTML, or dynamic text, as described for the Subject parameter.
Multipart message with n attachments	Select to specify email attachments. See Section 17.3.1.1, "Setting Email Attachments." The number of attachments if Multipart message is selected. The number does not include the body. For example, if you have a body and one attachment, specify `1`.

Click OK.

The BPEL fragment that invokes the notification service to send the email message is created.
See Table 17-1 for additional configuration procedures to perform.

The WebLogic Fusion Order Demo application uses an email activity in the Scope_NotifyCustomerofCompletion scope. The Oracle User Messaging Service sends the email to a customer when an order is fulfilled. The following details are specified in the Email dialog:
- An XPath expression specifies the customer's email address.
```
bpws:getVariableData('gCustomerInfoVariable','parameters','/ns3:findCustome
rInfoVO1CustomerInfoVOCriteriaResponse/ns3:result/ns2:ConfirmedEmail')
```
- A combination of manually-entered text and an XPath expression specifies the ID of the order:
```
Order with id
<%bpws:getVariableData('gOrderInfoVariable','/ns2:orderInfoVOSDO/ns2:OrderI
d')%> shipped!
```
- A combination of manually-entered text and an XPath expression specifies the body of the email message:
```
Dear<%bpws:getVariableData('gCustomerInfoVariable','parameters','/ns6:findCusto
merInfoVO1CustomerInfoVOCriteriaResponse/ns6:result/ns4:FirstName')%>,
your order has been shipped.
```
Figure 17-3 provides details.

Figure 17-3 Email Dialog

Description of "Figure 17-3 Email Dialog"

17.3.1.1 Setting Email Attachments

You can send attachments with an email activity. Each attachment has three elements: name, MIME type, and value. All three elements must be set for each attachment.

To add an attachment to an email message:

From the Component Palette, select Email as the notification channel.
Specify values for To, Subject, and Body.
Click the Attachments tab.
Click the Add icon to add as many attachments as you require. (the number of attachments does not need to include the body part.)
In the Name field, change the name or accept the default value of Attachmentnumber.
In the Mime Type field, click the Browse icon to invoke the Expression Builder dialog for adding MIME type contents.
When complete, click OK to return to the Attachments tab.
In the Value field, click the Browse icon to invoke the Expression Builder dialog for adding the contents of the attachment.
When complete, click OK to return to the Attachments tab.

The BPEL fragment with an assign activity with multiple copy rules is generated. One of the copy rules copies the attachment.
Click OK.
Expand the email activity.

An assign activity named EmailParamsAssign appears.
Double-click EmailParamsAssign.

Note the settings in EmailParamsAssign, as shown in Figure 17-4.

Figure 17-4 EmailParamsAssign Assign Activity

Description of "Figure 17-4 EmailParamsAssign Assign Activity"

For more information about sending attachments using email, see the following documentation:

Appendix J, "Oracle User Messaging Service Applications"
The notification-101 sample, which is available with the Oracle SOA Suite samples.

17.3.1.2 Formatting the Body of an Email Message as HTML

You can format the body of an email message as HTML rather than as straight text. To perform this action, apply an XSLT transform to generate the email body. Add in the XSLT tag you want to use. Tools such as XMLSpy can provide assistance in writing and testing the XSLT. The MIME type should be string('text/html;charset=UTF-8').

The email notification assignment looks as shown in Example 17-1:

Example 17-1 Email Notification Assignment

<copy>
 <from
expression="ora:processXSLT('TransformPositionSummary7.xslt',bpws: 
getVariableData('ClientPositionSummary'))"/>
 <to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns9:Content/ns9:ContentBody"/>
</copy>

17.3.1.3 Using Dynamic HTML for Message Content Requires a CDATA Function

If the HTML for the message content of an email activity is generated dynamically, (as with XSLT, file read, and so on), it must be wrapped in a CDATA function. This prevents conflicts between the XML/HTML content of the message body and BPEL's internal XML data structures.

For example, assume you use the append operation shown in Example 17-2 for the message content inside the email activity:

Example 17-2 Message Content Inside an Email Activity

<bpelx:append> 
  <bpelx:from 
    expression="ora:processXSLT('xsl/email.xslt',bpws:getVariableData('Variable_1'
    ))"/> 
  <bpelx:to variable="varNotificationReq" part="EmailPayload"
    query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[1]
    /ns1:ContentBody"/>
</bpelx:append>

For this to work correctly, you must pass the output of the processXSLT() function to the CDATA() function, as shown in Example 17-3.

Example 17-3 CDATA() Function

<%ora:toCDATA(xdk:processXSLT('xsl/email.xslt', 
 bpws:getVariableData('inputVariable','payload','/client:process/client:input') 
 ))%>

17.3.2 How to Configure the IM Notification Channel

When you drag IM from the Component Palette, the IM dialog appears. Figure 17-5 shows the required IM notification parameters.

Figure 17-5 IM Dialog

Description of "Figure 17-5 IM Dialog"

To configure the IM notification channel:

Enter information for each field as described in Table 17-4.

Table 17-4 IM Notification Parameters

Name	Description
To	The IM address to which the message is to be delivered. Enter the address manually or click the XPath Expression Builder icon to display the Expression Builder dialog to dynamically enter an account.
Body	The IM message body. This can be plain text or dynamic text. The XPath Expression Builder can set dynamic text based on data from process variables that you specify.

Click OK.

The BPEL fragment that invokes the notification service for IM notification is created.
See Table 17-1 for additional configuration procedures to perform.

17.3.3 How to Configure the SMS Notification Channel

When you select SMS from the Component Palette, the SMS dialog appears. Figure 17-6 shows the required SMS notification parameters.

Figure 17-6 SMS Dialog

Description of "Figure 17-6 SMS Dialog"

To configure the SMS notification channel:

Enter information for each field as described in Table 17-5.

Table 17-5 SMS Notification Parameters

Name	Description
From Number	The telephone number from which to send the SMS notification. This can be a static telephone number entered at the time the message is created or a dynamic telephone number from the payload. The XPath Expression Builder can get the dynamic telephone number from the input. See Section 17.3.5, "How to Select Email Addresses and Telephone Numbers Dynamically."
Telephone Number	Select a method for specifying the telephone number to which to deliver the message: A static telephone number entered at the time the message is created. A telephone number retrieved using the identity service. A dynamic telephone number from the payload. The XPath Expression Builder can get the dynamic telephone number from the input.
Subject	The subject of the SMS message. This can be plain text or dynamic text. The XPath Expression Builder can set dynamic text based on data from process variables that you specify.
Body	The SMS message body. This must be plain text. This can be plain text or dynamic text as described for the Subject parameter.

Click OK.

The BPEL fragment that invokes the notification service for SMS notification is created.
See Table 17-1 for additional configuration procedures to perform.

17.3.4 How to Configure the Voice Notification Channel

When you select Voice from the Component Palette, the Voice dialog appears. Figure 17-7 shows the required voice notification parameters.

Figure 17-7 Voice Dialog

Description of "Figure 17-7 Voice Dialog"

To configure the voice notification channel:

Enter information for each field as described in Table 17-6.

Table 17-6 Voice Notification Parameters

Name	Description
Telephone Number	The telephone number to which the message is to be delivered. Specify the number through one of the following methods: A static telephone number entered at the time the message is created A telephone number retrieved using the identity service A dynamic telephone number from the payload The XPath Expression Builder can retrieve the dynamic telephone number from the input.
Body	The message body. This can be plain text, XML, or dynamic text. The XPath Expression Builder can set dynamic text based on data from process variables that you specify.

Name

Description

Telephone Number

The telephone number to which the message is to be delivered. Specify the number through one of the following methods:

A static telephone number entered at the time the message is created
A telephone number retrieved using the identity service
A dynamic telephone number from the payload

The XPath Expression Builder can retrieve the dynamic telephone number from the input.

Body

The message body. This can be plain text, XML, or dynamic text. The XPath Expression Builder can set dynamic text based on data from process variables that you specify.

Click OK.

The BPEL fragment that invokes the notification service for voice notification is created.
See Table 17-1 for additional configuration procedures to perform.

17.3.5 How to Select Email Addresses and Telephone Numbers Dynamically

You may need to set email addresses or telephone numbers dynamically based on certain process variables. You can also look up contact information for a specific user using the built-in XPath functions for the identity service:

To get the email address or telephone number directly from the payload, use the following XPath expression:
```
bpws:getVariableData('<variable name>', '<part>','input_xpath_to_get_an_address')
```
For example, to get the email address from variable inputVariable and part payload based on XPath /client/BPELProcessRequest/client/mail:
```
<%bpws:getVariableData('inputVariable','payload','/client:BPELProcessRequest/
client:email')%>
```
You can use the XPath Expression Builder to select the function and enter the XPath expression to get an address from the input variable.

To get the email address or telephone number dynamically from the underlying identity store (LDAP) use the following XPath expression:

ids:getUserProperty(userName, attributeName[, realmName])

The first argument evaluates to the user ID. The second argument is the property name. The third argument is the realm name. Table 17-7 lists the property names that can be used in this XPath function.

Table 17-7 Properties for the Dynamic User XPath Function

Property Name	Description
`mail`	Look up a user's email address.
`telephoneNumber`	Look up a user's telephone number.
`mobile`	Look up a user's mobile telephone number.
`homephone`	Look up a user's home telephone number.

The following example gets the email address of the user identified by the variable inputVariable, part payload, and queries /client:BPELProcessRequest/client:userID:

ids:getUserProperty(bpws:getVariableData('inputVariable',
'payload','/client:BPELProcessRequest/client:userid'), 'mail')

If realmName is not specified, then the default realm name is used. For example, if the default realm name is jazn.com, the following XPath expression searches for the user in the jazn.com realm:

ids:getUserProperty('jcooper', 'mail');

The following XPath expression provides the same functionality as the one above. In this case, however, the realm name of jazn.com is explicitly specified:

ids:getUserProperty('jcooper', 'mail', 'jazn.com');

17.3.6 How to Select Notification Recipients by Browsing the User Directory

You can select users or groups in Oracle JDeveloper to whom you want to send notifications by browsing the user directory (for example, Oracle Internet Directory) that is configured for use with Oracle BPEL Process Manager. Click the Search icon to the right of the following fields to open the Identity Lookup dialog:

To field on the Email and IM dialogs
Telephone Number field on the SMS and Voice dialogs

For more information about using the Identity Lookup dialog, see Chapter 34, "Introduction to Human Workflow Services"

17.4 Allowing the End User to Select Notification Channels

You can design a BPEL process in which you do not explicitly select a notification channel during design time, but simply indicate that a notification must be sent. The channel to use for sending notifications is resolved at runtime based on preferences defined by the end user in the User Messaging Preferences user interface of the Oracle User Messaging Service. This moves the responsibility of notification channel selection from the BPEL process designer in Oracle BPEL Designer to the end user. If the end user does not select a preferred channel or rule, email is used by default for sending notifications to that user. Regardless of who selects the channel to use, channel use is still based on the driver installation and configuration performed in the Oracle User Messaging Service section of Oracle Enterprise Manager Fusion Middleware Control by the administrator.

For example, an end user may set their preferences as follows:

If an expense report amount is less than $153, they receive an email notification.
If an expense report amount is between $153 and $3678, they receive an SMS notification.
If an expense report amount is more than $3678, they receive a voice notification.

Note:

You can also set user preferences for sending notifications in human workflows in the Human Task Editor. Set these preferences in the Notification Filters part of the Notification Settings section. These preferences are used to evaluate rules in the task. For more information, see Section 29.8.8, "How to Send Task Attachments with Email Notifications."

For more information about the User Messaging Preferences user interface, see Chapter 67, "User Messaging Preferences."

17.4.1 How to Allow the End User to Select Notification Channels

To allow the end user to select notification channels:

From the Component Palette list, select BPEL.
Expand BPEL Activities and Components.
From the Component Palette, drag the User Notification activity into the designer. Figure 17-8 shows the required user notification parameters.

Figure 17-8 User Notification Dialog

Description of "Figure 17-8 User Notification Dialog"

Enter information for each field as described in Table 17-8.

Table 17-8 User Notification Parameters

Name Description

Name	Description
To	Enter a valid user for the recipient of this notification message through one of the following methods: Enter the user manually Click the Search icon to display a dialog for selecting a user configured through the identity service. The identity service enables the lookup of user properties, roles, and group memberships. Click the XPath Expression Builder icon to display the Expression Builder dialog to dynamically enter a user. Note: You must specify a user name (for example, `jcooper`) instead of an address.
Subject	Enter a message name or click the XPath Expression Builder icon to display the Expression Builder dialog to dynamically enter a subject. If notification is sent through email, this field is used during runtime. This field is ignored if notifications are sent through the voice, SMS, or IM channels.
Notification Message	Enter the notification message or click the XPath Expression Builder icon to display the Expression Builder dialog to dynamically enter a message to send.

Enter a valid user for the recipient of this notification message through one of the following methods:

Enter the user manually
Click the Search icon to display a dialog for selecting a user configured through the identity service. The identity service enables the lookup of user properties, roles, and group memberships.
Click the XPath Expression Builder icon to display the Expression Builder dialog to dynamically enter a user.

Note: You must specify a user name (for example, jcooper) instead of an address.

Subject

Enter a message name or click the XPath Expression Builder icon to display the Expression Builder dialog to dynamically enter a subject. If notification is sent through email, this field is used during runtime. This field is ignored if notifications are sent through the voice, SMS, or IM channels.

Notification Message

Enter the notification message or click the XPath Expression Builder icon to display the Expression Builder dialog to dynamically enter a message to send.

Click Apply.

17.4.1.1 How to Create and Send Headers for Notifications

The Advanced tab of the User Notification dialog enables you to create and send header and name information that may be useful to an end user in creating their own preference rules for receiving notifications. For example:

The BPEL designer creates specifies the users named jcooper and jstein in the General tab.
The BPEL designer creates the following header and name information in the Advanced tab:
- Amount = payload->salary
- Application = HR-Application
The administrator deploys the process and configures various channel drivers in Oracle Enterprise Manager Fusion Middleware Control.
The end user jcooper creates the following preference rules in the User Messaging Preferences user interface:
```
'Email if Amount < 30000" and "SMS if Amount is between 30000 and 100000' and
"Voice if Amount > 100000"
```
The end user jstein creates the following preference rule in the User Messaging Preferences user interface:
```
If "Application == HR-Application" and Amount > 2000000" send Voice 
```

If you want to create and send header and name information to an end user for creating their own preference rules, click Advanced.

Figure 17-9 shows the Advanced tab of the User Notification dialog.

Figure 17-9 User Notification Advanced Parameters

Description of "Figure 17-9 User Notification Advanced Parameters "
Click the Add icon to add a row to the Header and Name columns.
In the Header column, click the field to display a list for selecting a value. Otherwise, manually enter a value.
In the Name column, enter a value.
Click OK.