Skip Headers
Oracle® BPEL Process Manager Developer's Guide
10g Release 2 (10.1.2)
Part No. B14448-01
  Go To Documentation Library
Library
Go To Product List
Product
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

17 Oracle BPEL Process Manager Notification Service

The notification service in Oracle BPEL Process Manager enables you to send notifications from a BPEL process using a variety of channels. Oracle BPEL Process Manager can deliver these notifications by e-mail, voice message, or short message service (SMS).

This chapter contains the following topics:

17.1 Use Cases for Notification Service

Various scenarios may require sending e-mail 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, JDeveloper BPEL Designer uses the notification service to alert users by voice or e-mail. In an approval workflow (for example, an expense report approval), you can send notifications to the task assignee when a specific task requires action, or you can notify the task creator by e-mail when the approval is complete. In some cases, contact information (e-mail address or telephone number) is obtained dynamically as part of the process and in other cases these details are looked up from a user directory.

In the PCShop demo, the loan applicant specifies the loan amount and a callback number as part of the request. When the loan application is resolved, the customer is notified by telephone about the status of the loan request.


See:

Oracle_home\integration\orabpel\samples\demo\PCShop

17.2 Overview of Notification Service Concepts

Terms used for the notification service include:

Figure 17-1 shows the notification service interfaces and supported service types.

Figure 17-1 Notification Service Interfaces and Supported Service Types

Description of bpmdg021.gif follows
Description of the illustration bpmdg021.gif

17.3 Configuring Notification Service in JDeveloper BPEL Designer

The diagram view in JDeveloper BPEL Designer includes a Notification activity in the Component Palette, as shown in Figure 17-2.

Figure 17-2 Diagram View in JDeveloper BPEL Designer—Notification Activity

Description of notif1.gif follows
Description of the illustration notif1.gif

To use the notification service, do the following:

  1. In diagram view, select Process Activities from the Component Palette list.

  2. Drag and drop a Notification activity from the Process Activities list to a position below receiveInput and above callbackClient in the diagram.

    The Notification Service wizard starts.

  3. Click Next on the Welcome page.

    The Step 1 of 2: Select a Notification channel page appears. Description of notif2.gif follows
    Description of the illustration notif2.gif

  4. Select a notification channel from the following options and click Next.

    • EMail

    • Voice

    • SMS

    The next step depends on which notification channel you select.


    See:


17.3.1 The E-mail Notification Channel

When you select Email for the notification channel, the Notification Service Wizard - Step 2 of 2: Specify Email Parameters page appears. Figure 17-3 shows the required e-mail notification parameters.

Figure 17-3 Notification Service Wizard - Step 2 of 2: Specify Email Parameters Page

Description of notif3.gif follows
Description of the illustration notif3.gif

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

  1. Table 17-1 E-mail Notification Parameters

    Name Description
    From Account The name of the account used to send this message. The configuration details for this e-mail account name must exist on Oracle BPEL Server.
    To The e-mail address to which the message is to be delivered. This can be a) a static e-mail address entered at the time the message is created, or b) an e-mail address looked up using the identity service, or c) a dynamic address from the payload. The expression builder can be used to get the dynamic e-mail address from the input. See "Setting E-mail Addresses and Telephone Numbers Dynamically".
    CC and Bcc The e-mail 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 e-mail address to use for replies. This can be a static or dynamic address as described for the To address.
    Subject Subject of the e-mail message. This can be free text or dynamic text, or a combination. The expression builder can be used to set dynamic text based on data from process variables that you specify. Dynamic data is automatically enclosed in <% %> when you use the expression builder with free text.
    Body Message body of the e-mail message. This can be plain text, XML, or free text or dynamic text as described for the Subject parameter.
    Multipart message with n attachments Select to specify e-mail attachments. See "Setting E-mail Attachments".

    The number of attachments if Multipart message is selected. The number includes the body. For example, if you have a body and one attachment, specify 2 here.


  1. Click Finish.

    The BPEL fragment that invokes the notification service to send the e-mail message is created.

17.3.1.1 Setting E-mail Attachments

When you send e-mail attachments, you mark the e-mail as a multipart message and set the number of attachments to send. The number of attachments includes the body plus the attachments. (For example, to send an e-mail message with one file as an attachment, set the number to 2.) 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 one attachment an to e-mail message, do the following:

  1. Run the Notification Service wizard and select Email for the channel.

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

  3. Select Multipart and enter 2 for the number of attachments. (Note that the number of attachments must include the body part.)

  4. The Notification Service wizard generates the MultiPart element with two body parts. The first body part is for the message body and the other is used for the attachment. The Notification Service wizard generates the BPEL fragment with an assign activity with multiple copy rules. One of the copy rules copies the attachment, as follows:

    <assign name="Assign">
      <copy>
        <from expression="string('Default')"/>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:FromAccountName"/>
      </copy>
    ...
    <!--   copy statements relate to body and attachment -->
      <copy>
        <from>
          <Content xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
            <MimeType xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">multipart/mixed
            </MimeType>
            <ContentBody xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
              <MultiPart xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
                <BodyPart xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
                  <MimeType xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
                  <ContentBody xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
                  <BodyPartName xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
                </BodyPart>
                <BodyPart xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
                  <MimeType xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
                  <ContentBody xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
                  <BodyPartName xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService"/>
                </BodyPart>
              </MultiPart>
            </ContentBody>
          </Content>
        </from>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content"/>
      </copy>
      <copy>
        <from expression="string('text/html')"/>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[1]/ns1:MimeType"/>
      </copy>
      <copy>
        <from expression="string('NotificationAttachment1.html')"/>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[1]/ns1:BodyPartName"/>
      </copy>
      <copy>
        <from expression="string('This is a test message from John Cooper')"/>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[1]/ns1:ContentBody"/>
      </copy>
      <copy>
        <from expression="string('text/html')"/>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:MimeType"/>
      </copy>
      <copy>
        <from expression="string('NotificationAttachment2.html')"/>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:BodyPartName"/>
      </copy>
      <copy>
        <from expression="string('message2')"/>
        <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:ContentBody"/>
      </copy>
    </assign>
    
    
  5. Search for BodyPart[2] and set the required values. The steps to send the attachment MyImage.gif, for example, are as follows:

    1. Search for BodyPart[2] MimeType and change from expression to copy 'image/gif' as the MimeType (instead of the autogenerated 'text/html').

    2. Search for BodyPart[2] BodyPartName and change from expression to copy 'MyImage.gif' (instead of the autogenerated 'NotificationAttachment2.html'.

    3. Search for BodyPart[2] ContentBody and change from expression to copy the content of MyImage.gif (instead of the autogenerated expression string('message2')).

      You can use the readFile XPath function to read the contents of the file:

      ora:readFile('<name of the file in the project | HTTP URL | File URL>')
      
      

      Examples:

      ora:readFile('MyImage.gif') will read the file from the bpel project directory
      ora:readFile('file://c:/MyImage.gif') will read file from c:\ directory
      ora:readFile('http://www.oracle.com/MyImage.gif') 
      
      

The new BPEL copy statement is as follows:

<copy>
    <from expression="string('image/gif')"/>
    <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:MimeType"/>
  </copy>
  <copy>
    <from expression="string('MyImage.gif')"/>
    <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:BodyPartName"/>
  </copy>
  <copy>
    <from expression="ora:readFile('file://c:/MyImage.gif')"/>
    <to variable="varNotificationReq" part="EmailPayload" query="/EmailPayload/ns1:Content/ns1:ContentBody/ns1:MultiPart/ns1:BodyPart[2]/ns1:ContentBody"/>
  </copy>

See:

Oracle_home\integration\orabpel\samples\tutorials\130.SendEmailWithAttachments for an example of sending attachments using e-mail

17.3.1.2 Configuring the E-mail Server

The file ns_emails.xml in the directory Oracle_home\integration\orabpel\system\services\config contains the configuration for e-mail accounts. Each EmailAccount element sets the configuration of a specific e-mail account. The name attribute in the EmailAccount element is the name of the account.

A default e-mail account is specified in the e-mail configuration file. This account is used when there is no account specified to send an e-mail notification. This account is also used to send task-related notifications. A default e-mail account must always be specified in the configuration file.

The EmailAccount element contains OutgoingServerSettings and IncomingServerSettings attributes. For actionable notifications in a workflow, both IncomingServerSettings and OutgoingServerSettings are required.

Table 17-2 describes the XML elements for the e-mail notification configuration stored in the ns_emails.xml file.

Table 17-2 XML Elements for the E-mail Notification Configuration File

Name Description
EmailAccount/Name
Name of the account. This can be any name, but must be unique within this server.
EmailAccount/GeneralSettings/FromName
Name of the From e-mail address
EmailAccount/GeneralSettings/FromAddress
E-mail address for the From e-mail address
EmailAccount/OutgoingServerSettings/SMTPHost
Name of the outgoing SMTP server
EmailAccount/OutgoingServerSettings/SMTPPort
Port of the outgoing SMTP server
EmailAccount/IncomingServerSettings/Server
Name of the incoming e-mail server
EmailAccount/IncomingServerSettings/Port
Port of the incoming e-mail server
EmailAccount/IncomingServerSettings/UserName
User ID of the e-mail address
EmailAccount/IncomingServerSettings/Password
User password
EmailAccount/IncomingServerSettings/Password[encrypted
Encrypted attribute of the password. true if the password is encrypted and false if it is not. Generally, you should set this to false when you first enter the password. The server automatically encrypts the password the first time it reads the configuration file and sets the attribute to true.
EmailAccount/IncomingServerSettings/UseSSL
Secure sockets layer (SSL) attribute. true if the incoming server requires SSL and false if it does not.
EmailAccount/IncomingServerSettings/Folder
Name of the folder from which to read the incoming messages
EmailAccount/IncomingServerSettings/PollingFrequency
Polling interval for reading messages from the incoming messages folder.

17.3.1.3 Example ns_emails.xml File

EmailAccounts xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
   <EmailAccount>
       <Name>Default</Name>
      <GeneralSettings>
         <FromName>Oracle BPM</FromName>
         <FromAddress>bpm1@dlsun4254.us.oracle.com</FromAddress>
      </GeneralSettings>
      <OutgoingServerSettings>
         <SMTPHost>dlsun4254.us.oracle.com</SMTPHost>
         <SMTPPort>225</SMTPPort>
      </OutgoingServerSettings>
      <IncomingServerSettings>
         <Server>dlsun4254.us.oracle.com</Server>
         <Port>2110</Port>
         <Protocol>pop3</Protocol>
         <UserName>bpm1</UserName>
         <Password ns0:encrypted="false" xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">welcome</Password>
         <UseSSL>false</UseSSL>
         <Folder>Inbox</Folder>
         <PollingFrequency>1</PollingFrequency>
         <PostReadOperation>
            <MarkAsRead/>
         </PostReadOperation>
      </IncomingServerSettings>
   </EmailAccount>
</EmailAccounts>

17.3.2 The Voice Notification Channel

When you select Voice for the notification channel, the Notification Service Wizard - Step 2 of 2: Specify Voice Parameters page appears. Figure 17-4 shows the required voice notification parameters.

Figure 17-4 Notification Service Wizard - Step 2 of 2: Specify Voice Parameters Page

Description of notif4.gif follows
Description of the illustration notif4.gif

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

    Table 17-3 Voice Notification Parameters

    Name Description
    Telephone number The telephone number to which the message is to be delivered. This can be a) a static telephone number entered at the time the message is created, or b) a telephone number looked up using the identity service, or c) a dynamic telephone number from the payload. The expression builder can be used to get the dynamic telephone number from the input.
    Body Message body. This can be plain text or XML. Also, this can be free text or dynamic text, or a combination. The expression builder can be used to set dynamic text based on data from process variables that you specify. Dynamic data is automatically enclosed in <% %> when you use the expression builder with free text.

  1. Click Finish.

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

17.3.2.1 Configuring the Wireless Service Provider for Voice

The configuration for the wireless service provider is stored in an XML file, ns_iaswconfig.xml, which is in

Oracle_home\integration\orabpel\system\services\config

Table 17-4 describes the XML elements for the voice notification configuration stored in ns_iaswconfig.xml on the Oracle_home server.

Table 17-4 XML Elements for the Voice Notification Configuration File

Name Description
/IASWConfiguration/SoapURL
URL of the wireless service provider
/IASWConfiguration/UserName
Name of the user account with the wireless service provider
/IASWConfiguration/Password
User password
/IASWConfiguration/Password[encrypted
Encrypted attribute of the password. true if the password is encrypted and false if it is not. Generally, you should set this to false when you first enter the password. The server automatically encrypts the password the first time it reads the configuration file and sets the attribute to true.
/IASWConfiguration/ProxyHost
Name of the proxy server
/IASWConfiguration/ProxyPort
Port number of the proxy server


Note:

The username and password are intentionally left blank at installation. If a username or password is not specified, the wireless server allows up to 50 notifications from a specific IP address. After 50 notifications, you must get a paid account from

http://messenger.oracle.com

Then you specify the appropriate username and password in the configuration file, ns_iaswconfig.xml, or by using Enterprise Manager.


17.3.2.2 Example ns_iaswconfig.xml File

<?xml version = '1.0' encoding = 'UTF-8'?>
<!--This XML file stores the details of the IAS Wireless Notification Service-->
<IASWConfiguration xmlns="http://xmlns.oracle.com/ias/pcbpel/NotificationService">
  <!-- URL to the SOAP Service -->
  <SoapURL>http://messenger.oracle.com/xms/webservices</SoapURL>

  <!-- UserName - this username should exist in iAS Wireless schema -->
  <UserName>username</UserName>

  <Password ns0:encrypted="false" xmlns:ns0="http://xmlns.oracle.com/ias/pcbpel/NotificationService">password</Password>
</IASWConfiguration>

17.3.3 The SMS Notification Channel

When you select SMS for the notification channel, the Notification Service Wizard - Step 2 of 2: Specify SMS Parameters page appears. Figure 17-5 shows the required voice notification parameters.

Figure 17-5 Notification Service Wizard - Step 2 of 2: Specify SMS Parameters Page

Description of notif5.gif follows
Description of the illustration notif5.gif

  1. 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 the SMS will be sent. This can be a static telephone number entered at the time the message is created or a dynamic telephone number from the payload. The expression builder can be used to get the dynamic telephone number from the input. See "Setting E-mail Addresses and Telephone Numbers Dynamically".
Telephone number The telephone number to which the message is to be delivered. This can be a) a static telephone number entered at the time the message is created, or b) a telephone number looked up using the identity service, or c) a dynamic telephone number from the payload. The expression builder can be used to get the dynamic telephone number from the input.
Subject Subject of the SMS message. This can be free text or dynamic text, or a combination. The expression builder can be used to set dynamic text based on data from process variables that you specify. Dynamic data is automatically enclosed in <% %> when you use the expression builder with free text.
Body SMS message body. This must be plain text. This can be free text or dynamic text as described for the Subject parameter.

  1. Click Finish.

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

17.3.3.1 Configuring the Wireless Service Provider for SMS

As with the voice notification channel, the configuration for the wireless service provider for SMS is stored in the XML file ns_iaswconfig.xml, which is in

Oracle_home\integration\orabpel\system\services\config

See "Configuring the Wireless Service Provider for Voice" to configure a wireless service provider for SMS.

17.3.4 Setting E-mail Addresses and Telephone Numbers Dynamically

You may need to set e-mail 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 e-mail address or telephone number directly from the payload, use the following XPath:

    bpws:getVariableData('<variable name>', '<part>','<input xpath to get an address>')
    
    

    For example, to get the e-mail 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 expression builder to select the function and enter the XPath expression to get an address from the input variable.

  • To get the e-mail address or telephone number dynamically from the payload, use the following XPath:

    ora:getUserProperty(userID, propertyName)
    
    

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

    Table 17-6 Properties for the Dynamic User XPath Function

    Property Name Description
    mail Look up a user's e-mail 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 e-mail address of the user identified by the variable inputVariable, part payload, and query /client:BPELProcessRequest/client:userID:

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

17.3.5 Selecting Notification Recipients by Browsing the User Directory

You can select users or groups to whom you want to send notifications by browsing the user directory (OID, JAZN/XML, LDAP, and so on) that is configured for use by Oracle BPEL Process Manager. Click the first icon (the flashlight) to the right of To (or any recipient field) on any assignee page to start the Identity lookup dialog. See "Selecting Users or Groups by Browsing the User Directory" for more information on the Identity lookup dialog.

17.3.6 Starting Business Processes with the E-mail Activation Agent

You use the e-mail activation agent element activationAgents to start business processes by e-mail.The following steps are required to design a business process to start by e-mail.

  1. Create a business process.

  2. Add the e-mail activation agent activationAgents element to bpel.xml.

  3. Include a corresponding account name configuration file in the project.

Table 17-7 describes the activationAgents element and activationAgent attributes of the activation fragment contained in the bpel.xml file.

Table 17-7 E-mail Activation Element and Respective Attributes in bpel.xml

Element/Attribute Name Description
/activationAgents/activationAgent[className] Name of the activation agent class. Use com.collaxa.cube.activation.mail.MailActivationAgent class as the activation agent.
/activationAgents/activationAgent[heartBeatInterval] Polling interval of the messages in seconds
/activationAgents/activationAgent/property name=ÓaccountNameÓ Name of the e-mail configuration file. For example, if the account name is test_account, then the test_account.xml file is included in all the e-mail-related information.

The activationAgents Element Structure in bpel.xml

The following code example shows the structure of the activationAgents element contained in bpel.xml.

<activationAgents>
  <activationAgent 

className="com.collaxa.cube.activation.mail.MailActivationAgent"
      heartBeatInterval="60">
     <property name="accountName">test_account</property>
  </activationAgent>
</activationAgents>

The accountName XML File Structure

The following code example shows the structure of the accountName XML file.

<mailAccount xmlns="http://services.oracle.com/bpel/mail/account">
   <userInfo>
         <displayName>[display name]</displayName>
         <organization>[organization name]</organization>
         <replyTo>[replyTo email address]</replyTo>
   </userInfo>

   <outgoingServer>
         <protocol>smtp</protocol>
         <host>[outgoing smtp server]</host>
         <authenticationRequired>false</authenticationRequired>
   </outgoingServer>

   <incomingServer>
         <protocol>pop3</protocol>
         <host>[incoming pop3 server]</host>
         <email>[pop user name]</email>
         <password>[plain text email password]</password>
   </incomingServer>

   <!-- IMAP server config -->
   <!--
    <incomingServer>
        <protocol>imap</protocol>
        <host>[incoming imap server]</host>
        <email>[imap user name]</email>
        <password>[plain text email password]</password>
        <folderName>InBox</folderName>
    </incomingServer>
    -->

</mailAccount>

17.4 Summary

This chapter describes how you can send an e-mail, voice, or short message service (SMS) message from Oracle BPEL Process Manager.