16 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 16.1, "Introduction to the Notification Service"

• Section 16.2, "Introduction to Notification Channel Setup"

• Section 16.3, "Selecting Notification Channels During BPEL Process Design"

• Section 16.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).

16.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 [e-mail]) or obtained dynamically during runtime. To obtain the contact information dynamically, XPath expressions can be used to 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 39, "Oracle User Messaging Service."

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

  Figure 16-1 Service Interfaces and Supported Service Types

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

For more information about notifications, see the following section:

• Section 29.2, "Notifications from Human Workflow"

• Section 25.3.9, "How to Specify Participant Notification Preferences" for instructions on specifying email notifications in the Human Task Editor

• Part VII, "Using Oracle User Messaging Service"

16.2 Introduction to Notification Channel Setup

Notification setup is a multiple-step process that involves three user interface tools. Table 16-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 16-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 16.3, "Selecting Notification Channels During BPEL Process Design" or Section 16.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 Console	Oracle Fusion Middleware Administrator's Guide for Oracle SOA 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 Console	Oracle Fusion Middleware Administrator's Guide for Oracle SOA 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. Note that 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	Part VII, "Using Oracle User Messaging Service"

16.3 Selecting Notification Channels During BPEL Process Design

Oracle JDeveloper includes the notification channels in the Component Palette, as shown in Figure 16-2. 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.

Figure 16-2 Oracle JDeveloper—Notification Channels

Description of "Figure 16-2 Oracle JDeveloper—Notification Channels"

To select the notification channel during BPEL process design:

1. From the Component Palette list, select BPEL.

2. Expand BPEL Activities and Components.

3. From the Component Palette, drag a notification channel into the designer:

   • Email

   • IM

   • SMS

   • Voice

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

   Table 16-2 Notification Channels

   If You Selected...	See...
   Email	Section 16.3.1, "How To Configure the Email Notification Channel" to configure email notification
   IM	Section 16.3.2, "How to Configure the IM Notification Channel" to configure IM notification
   SMS	Section 16.3.3, "How to Configure the SMS Notification Channel" to configure SMS notification
   Voice	Section 16.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.

16.3.1 How To Configure the Email Notification Channel

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

Figure 16-3 Email Dialog

Description of "Figure 16-3 Email Dialog"

To configure the email notification channel:

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

   Note:

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

1. Table 16-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 Console. To add additional accounts, you must use the System MBean Browser in Oracle Enterprise Manager Fusion Middleware Control Console. For information on editing this property in Oracle Enterprise Manager Fusion Middleware Control Console, see Oracle Fusion Middleware Administrator's Guide for Oracle SOA 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 be used to get the dynamic email address from the input. See Section 16.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 be used to 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 16.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.

   
   

2. Click OK.

   The BPEL fragment that invokes the notification service to send the email message is created.

3. See Table 16-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 16-4 provides details.

Figure 16-4 Email Dialog

Description of "Figure 16-4 Email Dialog"

16.3.1.1 Setting Email Attachments

When you send email attachments, you mark the email as a multipart message and set the number of attachments to send. The number of attachments does not need to include the body plus the attachments. For example, to send an email message with one file as an attachment, set the number to 1. When sending attachments, set the content body to have a MultiPart element that contains as many BodyPart elements as the number of attachments. Each BodyPart has three elements: ContentBody, MimeType, and BodyPartName. All three elements must be set for each attachment.

To add an attachment to an email message:

1. From the Component Palette, select Email as the notification channel.

2. Specify values for To, Subject, and Body.

3. Select Multipart message and enter 1 for the number of attachments. (Note that the number of attachments does not need to include the body part.)

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

4. Click OK.

5. Expand the email activity.

   Note that an assign activity named EmailParamsAssign appears.

   Each body part has three attributes: ContentBody, MimeType, and BodyPartName. Default names, MIME types, and contents are generated for each attachment in this assign activity.

6. Double-click EmailParamsAssign.

   Note the default settings in EmailParamsAssign.

   Figure 16-5 EmailParamsAssign Assign Activity

   
   Description of "Figure 16-5 EmailParamsAssign Assign Activity"
   
   

7. Change the default values for ContentBody, MimeType, and BodyPartName to values specific to your environment.

8. Save your changes.

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

• Appendix I, "Oracle User Messaging Service Applications"

• The notification-101 sample, which is available at the following URL:

  http://www.oracle.com/technology/sample_code/products/hwf 
  

16.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 16-1:

Example 16-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>

16.3.2 How to Configure the IM Notification Channel

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

Figure 16-6 IM Dialog

Description of "Figure 16-6 IM Dialog"

To configure the IM notification channel:

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

   Table 16-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 be used to set dynamic text based on data from process variables that you specify.

   
   

2. Click OK.

   The BPEL fragment that invokes the notification service for IM notification is created.

3. See Table 16-1 for additional configuration procedures to perform.

16.3.3 How to Configure the SMS Notification Channel

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

Figure 16-7 SMS Dialog

Description of "Figure 16-7 SMS Dialog"

To configure the SMS notification channel:

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

Table 16-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 be used to get the dynamic telephone number from the input. See Section 16.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 be used to 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 be used to 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.

2. Click OK.

   The BPEL fragment that invokes the notification service for SMS notification is created.

3. See Table 16-1 for additional configuration procedures to perform.

16.3.4 How to Configure the Voice Notification Channel

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

Figure 16-8 Voice Dialog

Description of "Figure 16-8 Voice Dialog"

To configure the voice notification channel:

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

   Table 16-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 be used to 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 be used to set dynamic text based on data from process variables that you specify.

   
   

2. Click OK.

   The BPEL fragment that invokes the notification service for voice notification is created.

3. See Table 16-1 for additional configuration procedures to perform.

16.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 16-7 lists the property names that can be used in this XPath function.

  Table 16-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');
  

16.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 29, "Introduction to Human Workflow Services"

16.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 Console 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 25.3.9.7, "Sending Task Attachments with Email Notifications."

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

16.4.1 How to Allow the End User to Select Notification Channels

To allow the end user to select notification channels:

1. From the Component Palette list, select BPEL.

2. Expand BPEL Activities and Components.

3. From the Component Palette, drag the User Notification activity into the designer. Figure 16-9 shows the required user notification parameters.

   Figure 16-9 User Notification Dialog

   
   Description of "Figure 16-9 User Notification Dialog"
   
   

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

   Table 16-8 User Notification Parameters

   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.

   
   

5. Click Apply.

16.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 Console.

• 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 
  

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

   Figure 16-10 shows the Advanced tab of the User Notification dialog.

   Figure 16-10 User Notification Advanced Parameters

   
   Description of "Figure 16-10 User Notification Advanced Parameters "
   
   

2. Click the Add icon to add a row to the Header and Name columns.

3. In the Header column, click the field to display a list for selecting a value. Otherwise, manually enter a value.

4. In the Name column, enter a value.

5. Click OK.