Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle SOA Suite
11g Release 1 (11.1.1.5.0)

Part Number E10224-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

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:

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 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:

For more information about notifications, see the following section:

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

Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite and Oracle BPM 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 BPM 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. You can access this interface by selecting Preferences > Notification in Oracle BPM Worklist.

Part XI, "Using Oracle User Messaging Service"


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

To select the notification channel during BPEL process design:

  1. In the Component Palette, expand Oracle Extensions.

  2. Drag a notification channel into the designer:

    • Email

    • IM

    • SMS

    • Voice

  3. 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-2 shows the required email notification parameters.

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 (;).

    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. 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 BPM 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 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 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-3 provides details.

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

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

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

  3. Click the Attachments tab.

  4. Click the Add icon to add as many attachments as you require. (Note that the number of attachments does not need to include the body part.)

  5. In the Name field, change the name or accept the default value of Attachmentnumber.

  6. In the Mime Type field, click the Browse icon to invoke the Expression Builder dialog for adding MIME type contents.

  7. When complete, click OK to return to the Attachments tab.

  8. In the Value field, click the Browse icon to invoke the Expression Builder dialog for adding the contents of the attachment.

  9. 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.

  10. Click OK.

  11. Expand the email activity.

    Note that an assign activity named EmailParamsAssign appears.

  12. Double-click EmailParamsAssign.

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

    Figure 16-4 EmailParamsAssign Assign Activity

    Description of Figure 16-4 follows
    Description of "Figure 16-4 EmailParamsAssign Assign Activity"

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

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.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 16-2 for the message content inside the email activity:

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

Example 16-3 CDATA() Function

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

16.3.2 How to Configure the IM Notification Channel

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

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 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-6 shows the required SMS notification parameters.

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


  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-7 shows the required voice notification parameters.

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


  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 31, "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 by the administrator.

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

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

For more information about the User Messaging Preferences user interface, see Chapter 64, "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-8 shows the required user notification parameters.

    Figure 16-8 User Notification Dialog

    Description of Figure 16-8 follows
    Description of "Figure 16-8 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.

  • 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-9 shows the Advanced tab of the User Notification dialog.

    Figure 16-9 User Notification Advanced Parameters

    Description of Figure 16-9 follows
    Description of "Figure 16-9 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.