Using the Notification Service 16-5
Figure 16–2 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 ;.
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 Administrators 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.
16-6 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
2. Click OK.
The BPEL fragment that invokes the notification service to send the email message is created.
3.
See Table 16–1
on page 16-3 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:getVariableDatagCustomerInfoVariable,parameters,ns3:findCustome
rInfoVO1CustomerInfoVOCriteriaResponsens3:resultns2:ConfirmedEmail
■
A combination of manually-entered text and an XPath expression specifies the ID of the order:
Order with id bpws:getVariableDatagOrderInfoVariable,ns2:orderInfoVOSDOns2:OrderI
d shipped
■
A combination of manually-entered text and an XPath expression specifies the body of the email message:
Dear bpws:getVariableDatagCustomerInfoVariable,parameters,ns6:findCusto
merInfoVO1CustomerInfoVOCriteriaResponsens6:resultns4:FirstName, your order has been shipped.
Figure 16–3 provides details.
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.
Table 16–3 Cont. Email Notification Parameters
Name Description
Using the Notification Service 16-7
Figure 16–3 Email Dialog
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
.
16-8 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
Figure 16–4 EmailParamsAssign Assign Activity
For more information about sending attachments using email, see the following documentation:
■
Appendix J, Oracle User Messaging Service Applications
■
The notification-101 sample, which is available at the following URL: https:soasamples.samplecode.oracle.com
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’texthtml;charset=UTF-8’.
The email notification assignment looks as shown in Example 16–1
:
Using the Notification Service 16-9
Example 16–1 Email Notification Assignment
copy from
expression=ora:processXSLTTransformPositionSummary7.xslt,bpws: getVariableDataClientPositionSummary
to variable=varNotificationReq part=EmailPayload query=EmailPayloadns9:Contentns9: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 XMLHTML content of the message body and BPELs 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:processXSLTxslemail.xslt,bpws:getVariableDataVariable_1 bpelx:to variable=varNotificationReq part=EmailPayload
query=EmailPayloadns1:Contentns1:ContentBodyns1:MultiPartns1: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:toCDATAxdk:processXSLTxslemail.xslt, bpws:getVariableDatainputVariable,payload,client:processclient: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.
16-10 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
Figure 16–5 IM Dialog
To configure the IM notification channel: 1.
Enter information for each field as described in Table 16–4
.
2. Click OK.
The BPEL fragment that invokes the notification service for IM notification is created.
3.
See Table 16–1
on page 16-3 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.
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.
Using the Notification Service 16-11
Figure 16–6 SMS Dialog
To configure the SMS notification channel: 1.
Enter information for each field as described in Table 16–5
.
2. Click OK.
The BPEL fragment that invokes the notification service for SMS notification is created.
3.
See Table 16–1
on page 16-3 for additional configuration procedures to perform.
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.
16-12 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
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.
Figure 16–7 Voice Dialog
To configure the voice notification channel: 1.
Enter information for each field as described in Table 16–6
.
2. Click OK.
The BPEL fragment that invokes the notification service for voice notification is created.
3. See
Table 16–1 on page 16-3 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:
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.
Using the Notification Service 16-13
■
To get the email address or telephone number directly from the payload, use the following XPath expression:
bpws:getVariableDatavariable name, part,input_xpath_to_get_an_ address
For example, to get the email address from variable inputVariable and part payload based on XPath clientBPELProcessRequestclientmail:
bpws:getVariableDatainputVariable,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:getUserPropertyuserName, 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.
The following example gets the email address of the user identified by the variable inputVariable, part payload, and queries
client:BPELProcessRequestclient:userID:
ids:getUserPropertybpws:getVariableData‘inputVariable’, ‘payload’,‘client:BPELProcessRequestclient: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:getUserPropertyjcooper, 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:getUserPropertyjcooper, 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
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.
16-14 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
■
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:
■
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.
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.
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.
Using the Notification Service 16-15
Figure 16–8 User Notification Dialog
4.
Enter information for each field as described in Table 16–8
.
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.
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.
16-16 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
■
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
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.
17
Using Oracle BPEL Process Manager Sensors 17-1
17
Using Oracle BPEL Process Manager Sensors
This chapter describes how to use sensors to select BPEL activities, variables, and faults to monitor during runtime. This chapter describes how to use and set up sensors
for a BPEL process.
This chapter includes the following sections:
■
Section 17.1, Introduction to Sensors
■
Section 17.2, Configuring Sensors and Sensor Actions in Oracle JDeveloper
■
Section 17.3, Viewing Sensors and Sensor Action Definitions in Oracle Enterprise Manager Fusion Middleware Control
For more information about sensors, see the following sections:
■
Section 50.7, Integrating BPEL Sensors Using Oracle BAM Sensor Action for how
to create sensor actions in Oracle BPEL Process Manager to publish sensor data as data objects in an Oracle BAM Server
■
Appendix D, Understanding Sensor Public Views and the Sensor Actions XSD
17.1 Introduction to Sensors
Sensors are used to declare interest in specific events throughout the life cycle of a BPEL process instance. In a business process, that can be the activation and completion
of a specific activity or the modification of a variable value in the business process.
When a sensor is triggered, a specific sensor value is created. For example, if a sensor declares interest in the completion of a BPEL scope, the sensor value consists of the
name of the BPEL scope and a time stamp value of when the activity was completed. If a sensor value declares interest in a BPEL process variable, then the sensor value
consists of the value of the variable at the moment it was modified, a time stamp when the variable was modified, and the activity name and type that modified the BPEL
variable.
The data format for sensor values is normalized and well-defined using XML schema. A sensor action is an instruction on how to process sensor values. When a sensor is
triggered by Oracle BPEL Process Manager, a new sensor value for that sensor is created. After that, all the sensor actions associated with that sensor are performed. A
sensor action typically persists the sensor value in a database or sends the normalized sensor value data to a JMS queue or topic. For integration with Oracle Business
Activity Monitoring, the sensor value can be sent to the BAM adapter.
17-2 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
You can define the following types of sensors, either through Oracle JDeveloper or manually by providing sensor configuration files.
■
Activity sensors Activity sensors are used to monitor the execution of activities within a BPEL
process. For example, they can monitor the execution time of an invoke activity or how long it takes to complete a scope. Along with the activity sensor, you can also
monitor variables of the activity.
■
Variable sensors Variable sensors are used to monitor variables or parts of a variable of a BPEL
process. For example, variable sensors can monitor the input and output data of a BPEL process.
■
Fault sensors Fault sensors are used to monitor BPEL faults.
You typically add or edit sensors as part of the BPEL modeling of activities, faults, and variables.
These sensors are exposed through the following public SQL views:
■
BPEL_ACTIVITY_SENSOR_VALUES
■
BPEL_FAULT_SENSOR_VALUES
■
BPEL_VARIABLE_SENSOR_VALUES These views can be joined with the BPEL_PROCESS_INSTANCES view to associate the
sensor value with the BPEL process instance that created the sensor values. For more information, see
Appendix D, Understanding Sensor Public Views and the Sensor Actions XSD.
When you model sensors in Oracle JDeveloper, two new files are created as part of the BPEL process archive:
■
bpel_process_name _sensor.xml
Contains the sensor definitions of a BPEL process
■
bpel_process_name _sensorAction.xml
Contains the sensor action definitions of a BPEL process See
Section 17.2.2, How to Configure Sensors and
Section 17.2.3, How to Configure Sensor Actions
for how these files are created. After you define sensors for a BPEL process, you must configure sensor actions to
publish the sensor data to a specified destination. If no sensor action is defined for a sensor, then nothing happens at runtime.
The following information is required for a sensor action:
■
Name
■
Publish type The publish type specifies the destination in which the sensor data must be
presented. You can publish sensor data to the following destination types.
– Database
Publishes the sensor data to the reports schema in the database. The sensor data can then be queried using SQL.
Using Oracle BPEL Process Manager Sensors 17-3
– JMS queue
Publishes the sensor data to a JMS queue. The XML data is posted in accordance with the Sensor.xsd file. This file is included with Oracle
JDeveloper in the JDEV_ HOME
\jdeveloper\integration\seed\soa\shared\bpel directory.
– JMS topic
Publishes the sensor data to a JMS topic. The XML data is posted in accordance with the same Sensor.xsd file used with JMS queues.
– Custom
Publishes the data to a custom Java class.
– JMS Adapter
Uses the JMS adapter to publish to remote queues or topics and a variety of different JMS providers. The JMS queue and JMS topic publish types only
publish to local JMS destinations.
■
List of sensors The sensors for a sensor action.
Oracle BAM sensors publish information and events from Oracle BPEL Process Manager to Oracle BAM. Oracle BAM can display the data in rich real-time
dashboards for end-to-end monitoring of an application. For more information, see Section 50.7, Integrating BPEL Sensors Using Oracle BAM Sensor Action.
17.2 Configuring Sensors and Sensor Actions in Oracle JDeveloper
In Oracle JDeveloper, sensor actions and sensors are displayed as part of Monitor view.
17.2.1 How to Access Sensors and Sensor Actions
To access sensors and sensor actions: 1.
Select Monitor at the top of Oracle BPEL Designer, as shown in Figure 17–1
.
Figure 17–1 Monitor View
Figure 17–2 shows the sensor actions and sensors in the Structure window.
17-4 Oracle Fusion Middleware Developers Guide for Oracle SOA Suite
Figure 17–2 Sensors and Sensor Actions Displayed in Oracle JDeveloper
You typically add or edit sensors as part of the BPEL modeling of activities, faults, and variables.
2. Add sensor actions by right-clicking the Sensor Actions folders and selecting
Create Sensor Action.
3.
Add activity sensors, variable sensors, or fault sensors as follows:
a. Expand the Sensors folder.
b. Right-click the appropriate Activity, Variable, or Fault subfolder.
c. Click Create.
4.
Add sensors to individual activities by right-clicking an activity and selecting Create
Sensor. Figure 17–3
provides details.
Figure 17–3 Creating an Activity Sensor
The following sections describe how to configure sensors and sensor actions.
17.2.2 How to Configure Sensors
This section describes how to configure activity, variable, and fault sensors.
To configure an activity sensor: Assume you are monitoring a loan flow application, and want to know the following:
■
When a scope named GetCreditRating is initiated
■
When it is completed
■
At completion, what is the credit rating for the customer
Using Oracle BPEL Process Manager Sensors 17-5
The solution is to create an activity sensor for the GetCreditRating scope in Oracle BPEL Designer, as shown in
Figure 17–4 .
1. Select Monitor at the top of Oracle BPEL Designer.
2. In the Structure window, expand the Sensors folder.
3. Right-click Activity, and select Create.
4. To the right of the Activity Name field, click the Browse icon to select the activity
for which to create the sensor. This is a required field.
Figure 17–4 Creating an Activity Sensor
Activities that have sensors associated with them are identified with a magnifying glass in Oracle BPEL Designer.
The Evaluation Time list shown in Figure 17–4
controls the point at which the sensor is fired.
5.
Select from the following:
■
All :
The sensor monitors during the activation, completion, fault, compensation, and retry phases.
■
Activation
The sensor is fired just before the activity is executed.
■
Completion
The sensor is fired just after the activity is executed.
■
Fault
The sensor is fired if a fault occurs during the execution of the activity. Select this value only for sensors that monitor simple activities.
