| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
| Oracle® BPEL Process Manager Developer's Guide 10g (10.1.3.1.0) Part Number B28981-03 |
|
|
View PDF |
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, fax, pager, or short message service (SMS).
This chapter contains the following topics:
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, Oracle JDeveloper uses the notification service to alert users by voice, SMS, fax, pager, 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 the details are looked up from a user directory.
The tutorial 130.SendEmailWithAttachments demonstrates how to model a notification in Oracle JDeveloper and send an e-mail with an attachment.
See:
SOA_Oracle_Home\bpel\samples\tutorials\130.SendEmailWithAttachmentsThe OrderBooking tutorial demonstrates how to add an e-mail notification to the POAcknowledge process.
Terms used for the notification service include:
Notification—an asynchronous message sent to a user by a specific channel. The message can be sent as an e-mail message, a voice message, a fax message, a pager message, or an SMS message.
Actionable notification—a notification to which the user can respond. For example, workflow sends an e-mail message to a manager to approve or reject a purchase order. The manager approves or rejects the request by replying to the e-mail with appropriate content.
Oracle Application Server Wireless—the wireless and voice component of Oracle Application Server. OracleAS Wireless includes a messaging component that handles the sending and receiving of messages to and from devices. When you install OracleAS Wireless, you can specify one of the following notification service options:
Connect to an external server to deliver messages, such as e-mail, SMS, fax, voice, or pager.
Use Oracle's hosted service at
Oracle BPEL Process Manager is preconfigured to send notifications using Oracle's hosted wireless service.
The notification service supports sending e-mail through the SMTP protocol and receiving e-mail from IMAP- and POP-based e-mail accounts.
Figure 14-1 shows the notification service interfaces and supported service types.
Figure 14-1 Notification Service Interfaces and Supported Service Types
Oracle BPEL Process Manager provides support for the reliable notification service. The outbound notification service creates a notification message with a unique notification ID and stores the message and unique ID in the dehydration store. It then enqueues this unique ID in the JMS queue and commits the transaction. A message driven-bean (MDB) listening on this queue dequeues the message and sends a notification to the user. If there is any notification failure, the notification service retries three times. If the retries all fail, it marks this notification as errored.
To send an error notification after resolving the problem, you must write a script to update the BPELNotification table status to SEND. For example:
UPDATE BPELNotification
SET status = 'RETRY',
ATTEMPTEDNUMBER = 0
WHERE ID = <notification id>
By default, the notification service retries three time. If you want to add more retries (for example, 5), add the following property in SOA_Oracle_Home/bpel\system\services\config\wf_config.xml and restart Oracle BPEL Server:
<property name="oracle.bpel.services.notification.maxattempt" value="5" />
The notification thread that is running tries to send the notification every 15 minutes. You can change this interval by adding the following property in wf_config.xml. For example, to retry every 10 minutes:
<property name="oracle.bpel.services.notification.publisher_interval" value="10" />
The diagram window in Oracle JDeveloper includes the notification channels in the Component Palette, as shown in Figure 14-2.
Figure 14-2 Diagram Window in Oracle JDeveloper—Notification Activity
To use a notification channel, do the following:
Select Process Activities from the Component Palette list.
Drag and drop a notification channel from the Component Palette list:
Fax
Pager
SMS
Voice
See the following section based on the notification channel you selected.
| If You Selected... | See... |
|---|---|
| "The E-mail Notification Channel" to configure e-mail notification | |
| Fax | "The Fax Notification Channel" to configure fax notification |
| Pager | "The Pager Notification Channel" to configure pager notification |
| SMS | "The SMS Notification Channel" to configure SMS notification |
| Voice | "The Voice Notification Channel" to configure voice message notification |
When you select Email from the Component Palette, the Edit Email window appears. Figure 14-3 shows the required e-mail notification parameters.
Enter information for each field as described in Table 14-1.
Table 14-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 XPath 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. The XPath Expression Builder can be used to set dynamic text based on data from process variables that you specify. |
| Body | Message body of the e-mail message. This can be plain text, XML, 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 |
Click OK.
The BPEL fragment that invokes the notification service to send the e-mail message is created.
See Also:
Oracle BPEL Process Manager Administrator's Guide for details about e-mail configuration instructions to perform outside of Oracle JDeveloperWhen 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 to an e-mail message, do the following:
Select Email as the notification channel from the Component Palette.
Specify values for To, Subject, and Body.
Select Multipart message and enter 2 for the number of attachments. (Note that the number of attachments must include the body part.)
The MultiPart element with two body parts is generated. The first body part is for the message body and the other is used for the attachment. The BPEL fragment with an assign activity with multiple copy rules is generated. 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>
Search for BodyPart[2] and set the required values. The steps to send the attachment MyImage.gif, for example, are as follows:
Search for BodyPart[2] MimeType and change the from expression to copy 'image/gif' as the MimeType (instead of the autogenerated 'text/html').
Search for BodyPart[2] BodyPartName and change the from expression to copy 'MyImage.gif' (instead of the autogenerated 'NotificationAttachment2.html').
Search for BodyPart[2] ContentBody and change the 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>')
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:
SOA_Oracle_Home\bpel\samples\tutorials\130.SendEmailWithAttachments for an example of sending attachments using e-mailYou can format the body of an e-mail message as HTML rather than as straight text. To do this, apply an XSLT transform to generate the e-mail 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 e-mail notification assignment should look as follows:
<copy>
<from
expression="ora:processXSLT('TransformPositionSummary7.xslt',bpws:
getVariableData('ClientPositionSummary'))"/>
<to variable="varNotificationReq" part="EmailPayload"
query="/EmailPayload/ns9:Content/ns9:ContentBody"/>
</copy>
When you select Fax from the Component Palette, the Edit Fax window appears. Figure 14-4 shows the required fax notification parameters.
Enter information for each field as described in Table 14-2.
Table 14-2 Fax Notification Parameters
| Name | Description |
|---|---|
| Fax Number | The fax number to which the message is to be delivered. This can be a) a static fax number entered at the time the message is created, or b) a fax number looked up using the identity service, or c) a dynamic fax number from the payload. The XPath Expression Builder can be used to get the dynamic fax number from the input. |
| Cover Page | The cover page name. The cover page details must exist on the server. The cover page can be in PDF, Microsoft Word, HTML, or plain text format. (This field is optional.) The XPath Expression Builder can be used to set dynamic text based on data from process variables that you specify. |
| Body | Fax message body. This must be plain text or HTML. This can be free text or dynamic text as described for the Cover page parameter. |
Click OK.
The BPEL fragment that invokes the notification service for fax notification is created.
See Also:
Oracle BPEL Process Manager Administrator's Guide for details about fax configuration instructions to perform outside of Oracle JDeveloperWhen you select Pager from the Component Palette, the Edit Pager window appears. Figure 14-5 shows the required pager notification parameters.
Enter information for each field as described in Table 14-3.
Table 14-3 Pager Notification Parameters
| Name | Description |
|---|---|
| From Number | The pager number from which the message is to be sent. This can be a) a static pager number entered at the time the message is created, or b) a dynamic pager number from the payload. The XPath Expression Builder can be used to get the dynamic pager number from the input. |
| Pager Number | The number of the recipient of this message. This can be a) a static pager number entered at the time the message is created, or b) a pager number looked up using the identity service, or c) a dynamic pager number from the payload. The XPath Expression Builder can be used to get the dynamic pager number from the input. |
| Body | Pager message body. This must be plain text. This can be free text or dynamic text as described for the From Number parameter. |
Click OK.
The BPEL fragment that invokes the notification service for pager notification is created.
See Also:
Oracle BPEL Process Manager Administrator's Guide for details about pager configuration instructions to perform outside of Oracle JDeveloperWhen you select SMS from the Component Palette, the Edit SMS window appears. Figure 14-6 shows the required SMS notification parameters.
Enter information for each field as described in Table 14-4.
Table 14-4 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 "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 XPath 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. The XPath Expression Builder can be used to set dynamic text based on data from process variables that you specify. |
| Body | SMS message body. This must be plain text. This can be free 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 Also:
Oracle BPEL Process Manager Administrator's Guide for details about SMS configuration instructions to perform outside of Oracle JDeveloperWhen you select Voice from the Component Palette, the Edit Voice window appears. Figure 14-7 shows the required voice notification parameters.
Enter information for each field as described in Table 14-5.
Table 14-5 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 XPath 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. The XPath Expression Builder can be used to 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 Also:
Oracle BPEL Process Manager Administrator's Guide for details about voice configuration instructions to perform outside of Oracle JDeveloperYou 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 XPath 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:
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 14-6 lists the property names that can be used in this XPath function.
Table 14-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:
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');
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 window to start the Identity lookup dialog.
See Also:
Chapter 15, "Oracle BPEL Process Manager Workflow Services" for additional details about using the Identity lookup dialogActivation agents define process agents that initiate a process. 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.
Create a business process.
Add the e-mail activation agent activationAgents element to bpel.xml.
Include a corresponding account name configuration file in the project.
Name the file the same as the name of the accountName attribute of activationAgents in bpel.xml. See "The accountName XML File Structure".
Table 14-7 describes the activationAgents element and activationAgent attributes of the activation fragment contained in the bpel.xml file.
Table 14-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 the 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>
If you set the validateXML property to true (the default is false) on the Manage BPEL Domain window of Oracle BPEL Control, each message exchanged with each of the Web services is validated against its schema. However, notification services fail during XML validity checks at run time. This is because the BPEL variables exchanged with the notification service are not completely initialized in the BPEL process. Part of the initialization happens in the service itself.
