53 Defining Composite Sensors

This chapter describes how to define composite sensors that provide a method for implementing trackable fields on messages in a SOA composite application. It describes how to define sensors on binding components and on service components that have subscribed to business events. It also describes restrictions on using composite sensors and how to manage composite sensors during runtime in Oracle SOA Composer.

This chapter includes the following sections:

• Introduction to Composite Sensors

• Adding Composite Sensors

• Monitoring Composite Sensor Data During Runtime

• Creating and Managing Composite Sensors During Runtime from Oracle SOA Composer

For information about activity, fault, and variable sensors in a BPEL process, see Using Sensors and Analytics .

For examples of using composite sensors in business scenarios, see Understanding Oracle SOA Suite.

53.1 Introduction to Composite Sensors

Composite sensors provide a method for implementing trackable fields on messages. Composite sensors enable you to perform the following tasks:

• Monitor incoming and outgoing messages.

• Specify composite sensor details in the search utility of the Flow Instances pages for the SOA Infrastructure, partition, and SOA composite application in Oracle Enterprise Manager Fusion Middleware Control. This action enables you to display details about a particular instance with a composite sensor.

• Publish JMS data computed from incoming and outgoing messages.

• Track composite instances initiated through business event subscriptions.

You define composite sensors on service and reference binding components or on service components that have business event subscriptions in Oracle JDeveloper. This functionality is similar to variable sensors in BPEL processes. During runtime, composite sensor data is persisted in the database.

You can also define composite sensors during runtime in Oracle SOA Composer. Oracle SOA Composer changes are picked up immediately by the runtime, whereas changes made using Oracle JDeveloper require SOA composite application redeployment.

For information about searching for composite sensors in Oracle Enterprise Manager Fusion Middleware Control, see Section "Tracking Business Flow Instances at the SOA Infrastructure or Partition Level" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

53.1.1 Restrictions on Use of Composite Sensors

Note the following restrictions on the use of composite sensors:

• Functions in XPath expressions cannot be used with properties.

• Any composite sensor that is defined by an expression always captures values as strings. This causes the sensor type to always be a string. This action makes the search possible.

  Capturing values as strings may be useful when dealing with XML types derived from a string. The following example provides details:

  <xs:element name="CardNum">
      <xs:simpleType>
          <xs:restriction base="xs:string">
              <xs:length value="16"/>
          </xs:restriction>
      </xs:simpleType>
  </xs:element>
  

  Even if the expression is a number, it is captured as a string. You cannot use other logical operators such as <, >, =, or any combination of these.

• Any composite sensor that is defined by a variable uses the variable type to determine the sensor type. Sensors can be one of the following types:

  • STRING

  • NUMBER

  • DATE

  • DATE_TIME

  • Complex XML

• Composite sensors only support two types of sensor actions: Enterprise Manager and JMS.

• Header-based sensors are only supported for web service bindings.

• Sensor actions for Oracle B2B, service data objects (SDOs), web services invocation framework (WSIF), and Oracle Business Activity Monitoring bindings are not supported.

• When creating an XPath expression for filtering, all functions that return a node set must be explicitly cast as a string:

  xpath20:upper-case(string($in.request/inp1:updateOrderStatus/inp1:orderStatus) ) = "PENDING"
  

• Sensors cannot be configured on service components that publish business events.

• Sensors based on business event headers are not allowed (only payloads are allowed).

• PL/SQL subscriptions are not supported.

53.2 Adding Composite Sensors

You add sensors to the following components of a SOA composite application in the SOA Composite Editor:

• Service or reference binding components

• Service components such as a BPEL process or Oracle Mediator that have subscribed to business events

53.2.1 How to Add Composite Sensors

To add composite sensors:

1. Use one of the following options to add a composite sensor in the SOA Composite Editor:

   • Option 1:

     1. Right-click a specific service or reference binding component in the Exposed Services or External References swimlane or a service component that has a subscribed business event. A service component that has a subscribed business event includes the word Subscribed on it.

     2. Select Configure Sensors.

        Note:

        The service component must already have a subscribed business event for the Configure Sensors option to be displayed.

        If you selected a binding component, the Composite Sensors dialog displays the details shown in Figure 53-1. For this example, a service binding component is selected.

        Figure 53-1 Composite Sensors Dialog for the Selected Binding Component

        
        Description of "Figure 53-1 Composite Sensors Dialog for the Selected Binding Component"

        If you selected a service component, the Composite Sensors dialog displays the details shown in Figure 53-2.

        Figure 53-2 Composite Sensors Dialog for the Selected Service Component

        
        Description of "Figure 53-2 Composite Sensors Dialog for the Selected Service Component"

     3. Select the binding component or service component in the dialog, and click the Add icon.

   • Option 2:

     1. Click the Composite Sensor icon above the SOA Composite Editor, as shown in Figure 53-3.

        Figure 53-3 Composite Sensor Icon

        
        Description of "Figure 53-3 Composite Sensor Icon"

        The Composite Sensors dialog for the SOA composite application appears, as shown in Figure 53-4. This option displays all the service and reference binding components and service components with subscribed business events in the SOA composite application.

        Figure 53-4 Composite Sensors Dialog

        
        Description of "Figure 53-4 Composite Sensors Dialog"

     2. Select the specific service, reference, or business event to which to add a composite sensor, then click the Add icon.

   If you selected a binding component such as a service, the Create Composite Sensor dialog appears as shown in Figure 53-5.

   Figure 53-5 Create Composite Sensor Dialog for a Service Binding Component

   
   Description of "Figure 53-5 Create Composite Sensor Dialog for a Service Binding Component"

   If you selected a service component that has a business event subscription, the Create Composite Sensor dialog appears as shown in Figure 53-6.

   Figure 53-6 Create Composite Sensor Dialog for a Service Component

   
   Description of "Figure 53-6 Create Composite Sensor Dialog for a Service Component"

2. Enter the details shown in Table 53-1.

   Table 53-1 Create Composite Sensor Dialog

   Name	Description
   Name	Enter a name for the composite sensor. You must enter a name to enable the Edit icon of the Expression field.
   Service	Displays the name of the service. This field is only displayed if you are creating a composite sensor for a service binding component. This field cannot be edited. Service sensors monitor the messages that the service receives from the external world or from another composite application.
   Reference	Displays the name of the reference. This field is only displayed if you are creating a composite sensor for a reference binding component. This field cannot be edited. Reference sensors monitor the messages that the reference sends to the external world or to another composite application.
   Operation	Select the operation for the port type of the service or reference. This field only displays for service or reference binding components.
   Event	Displays the name of the service component. This field is only displayed if you are creating a composite sensor for a service component. This field cannot be edited. Event sensors track composite instances initiated through a business event. You can create multiple sensors per business event.
   Event Type	Displays the Subscribe business event type. This field cannot be edited. The publish business event type is not supported.
   Expression	Click the Edit icon to display a dropdown list for selecting the type of expression to create: Variables: Select to create an expression value for a variable. See How to Add a Variable. Expression: Select to open the Expression Builder dialog for creating an XPath expression. This action always captures values as strings. See How to Add an Expression. Properties: Select to create an expression value for a normalized message header property. These are the same properties that display under the Properties tab of the invoke activity, receive activity, reply activity, OnEvent branch of a scope activity (in BPEL 2.0), and OnMessage branch of a pick activity and scope activity (in BPEL 2.0). See How to Add a Property.
   Filter	Click the Edit icon to open the Expression Builder dialog to create an XPath filter for the expression. You must first create an expression to enable this field. For example, you may create an expression for tracking purchase order amounts over 10,000: $in.inDict/tns:inDict/ns2:KeyValueOfstringstring/ns2:Value > 10000.00
   Composite Sensor Actions	Displays the supported sensor actions. This feature enables you to store runtime sensor data. You can select both Enterprise Manager and either JMS Queue or JMS Topic. Enterprise Manager Select to make runtime sensor data searchable in the Flow Instances tab of a SOA composite application in Oracle Enterprise Manager Fusion Middleware Control. This selection is the same as the DBSensorAction selection of previous releases. Note: When Enterprise Manager is selected, sensor data is sent to the trackable fields tables. When it is not selected, data is not sent. However, in both cases, Oracle Enterprise Manager Fusion Middleware Control still displays the fields that enable you to search for composite instances based on that sensor. For more information, see Administering Oracle SOA Suite and Oracle Business Process Management Suite. JMS Queue Select to store composite sensor data (XML payload) in a JMS queue. You must specify the JMS connection factory and queue name. JMS Topic Select to store composite sensor data (XML payload) in a JMS topic. You must specify the JMS connection factory and topic name. Notes: The JMS Queue and JMS Topic selections enable the composite sensor data (XML payload) to be used by other consumers, including Oracle Business Activity Monitoring (BAM) and Oracle Complex Event Processing. Both selections use the native JMS support provided with Oracle WebLogic Server, and not the Oracle SOA Suite JMS adapter described in Understanding Technology Adapters. You can view JMS messages in the Oracle WebLogic Server Administration Console.

3. Click OK.

   For a service or reference binding component, a composite sensor icon displays in the upper right corner, as shown in Figure 53-7.

   Figure 53-7 Sensor Icon on Binding Component

   
   Description of "Figure 53-7 Sensor Icon on Binding Component"

   For a service component, a composite sensor icon also displays in the upper right corner, as shown in Figure 53-8.

   Figure 53-8 Sensor Icon on Service Component

   
   Description of "Figure 53-8 Sensor Icon on Service Component"

4. Place your cursor over the composite sensor icon to display details about the composite sensor.

53.2.1.1 How to Add a Variable

The Select XPath Expression dialog shown in Figure 53-9 enables you to select an element for tracking.

To add a variable:

1. Expand the tree and select the element to track (for this example, an order ID).

   Figure 53-9 Variables

   
   Description of "Figure 53-9 Variables"
2. Click OK when complete.

53.2.1.2 How to Add an Expression

The Expression Builder dialog shown in Figure 53-10 enables you to create an expression for tracking.

For more information, see Building XPath Expressions in the Expression Builder in Oracle JDeveloper.

To add an expression:

1. Build an XPath expression of an element to track.

   Figure 53-10 Expression

   
   Description of "Figure 53-10 Expression"
2. Click OK when complete.

Note:

For variables, Expression Builder inserts $in/variablename. If you are using payload arguments in your expression, you must manually update this syntax to $in.payload/variablename. For example:

concat($in.payload/element, '_', $in.payload/element2)

53.2.1.3 How to Add a Property

The Select Property dialog shown in Figure 53-11 enables you to select a normalized message header property for tracking.

To add a property:

1. Select a normalized message header property to track.

   Figure 53-11 Properties

   
   Description of "Figure 53-11 Properties"
2. Click OK when complete.

For more information about normalized messages, see Propagating Normalized Message Properties Through Message Headers.

53.2.2 What You May Need to Know About Duplicate Composite Sensor Names

Note the following details when using duplicate names for composite sensors.

• If you create composite sensors with duplicate names, the entire contents of their definitions are compared. Duplicate names are permitted where one or more additional parameters are different (for example, either different configuration types or different expressions, filters, operation names, and so on). Something must be different in the definitions for duplicate names to be permitted.

• If you have duplicate sensor definitions, only the last executed sensor value is persisted. Therefore, you can use this type of configuration for mutually exclusive paths (for example, a composite can be invoked through service 1 or service 2). Therefore, you can define the same sensor name on both the services. However, if you define the same names for service 1 and reference 1, only the sensor value from reference 1 (the last executed sensor) is stored.

• You typically use multiple sensors with the same name to point to the same logical entity extracted from different sources (for example, Oracle Enterprise Manager Fusion Middleware Control displays the final sensor value). Therefore, it can be confusing if the same sensor name is used to extract an email value and a social security value from different sources.

• Sensor actions apply to all occurrences of the same sensor name. This situation means the sensor actions on the most recently defined sensor with the same name take precedence.

For the scenario shown in sensor.xml in the following example:

• The first two sensors named Service1 are identical. In addition, the configuration type for both is serviceConfig (composite sensors defined on a service binding component). Therefore, the sensors become one entry (the second one is ignored).

• The third sensor named Service1 has a different configuration type of eventConfig (a composite sensor defined on a business event). Therefore, this sensor is represented with a separate entry.

• The two sensors named PurchaseOrder Id have different configuration types (eventConfig and serviceConfig). Therefore, they are represented with separate entries.

• The two sensors named PurchaseOrder have the same configuration type (eventConfig), but different expressions. Therefore, they are represented with separate entries.

<sensors xmlns="http://xmlns.oracle.com/bpel/sensor">
   <sensor sensorName="Service1" kind="service" target="undefined" filter="">
      <serviceConfig service="OrderPublisher_ep"
 expression="$in.property.tracking.ecid" operation="execute"
 outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
   </sensor>
   <sensor sensorName="Service1" kind="service" target="undefined" filter="">
      <serviceConfig service="OrderPublisher_ep"
 expression="$in.property.tracking.ecid" operation="execute"
 outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
   </sensor>
   <sensor sensorName="Service1" kind="event" target="undefined" filter=""
 xmlns:po="http://www.mycompany.com/ns/order">
      <eventConfig component="EventMediator"
 expression="$in/po:PurchaseOrder/po:OrderID"
 event="{http://mycompany.com/events/orders}OrderReceivedEvent"
 outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
   <sensor sensorName="Event1" kind="event" target="undefined" filter="">
      <eventConfig component="EventMediator" actionType="Subscribe"
 expression="$in.property.tracking.ecid"
 event="{http://mycompany.com/events/orders}OrderReceivedEvent"
 outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
   </sensor>
   <sensor sensorName="PurchaseOrder Id" kind="event" target="undefined" filter=""
 xmlns:po="http://www.mycompany.com/ns/order">
      <eventConfig component="EventMediator"
 expression="$in/po:PurchaseOrder/po:OrderID"
 event="{http://mycompany.com/events/orders}OrderReceivedEvent"
 outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
   </sensor>
  <sensor sensorName="PurchaseOrder Id" kind="service" target="undefined"
 filter="">
      <serviceConfig service="OrderPublisher_ep"
 expression="$in.property.tracking.ecid" operation="execute"
 outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
   </sensor>
   <sensor sensorName="PurchaseOrder" kind="event" target="undefined" filter=""
 xmlns:po="http://www.mycompany.com/ns/order">
      <eventConfig component="EventMediator" expression="$in/po:PurchaseOrder"
 event="{http://mycompany.com/events/orders}OrderReceivedEvent"
 outputDataType="PurchaseOrder"
 outputNamespace="http://mycompany.com/events/orders"/>
   </sensor>
   <sensor sensorName="PurchaseOrder" kind="event" target="undefined" filter=""
 xmlns:po="http://www.mycompany.com/ns/order">
      <eventConfig component="EventMediator"
 expression="$in/po:PurchaseOrder/po:OrderID"
 event="{http://mycompany.com/events/orders}OrderReceivedEvent"
 outputDataType="string" outputNamespace="http://www.w3.org/2001/XMLSchema"/>
   </sensor>
   </sensor>
</sensors>

53.3 Monitoring Composite Sensor Data During Runtime

During runtime, composite sensor data can be monitored in Oracle Enterprise Manager Fusion Middleware Control:

• Composite sensor data displays in the flow trace of a SOA composite application.

• Composite sensor data can be searched for on the Flow Instances page at the SOA Infrastructure, individual partition, and SOA composite application levels.

For more information about searching for composite sensors in Oracle Enterprise Manager Fusion Middleware Control, see Section "Monitoring and Deleting SOA Composite Application Instances at the SOA Infrastructure Level" and Section "Monitoring and Deleting SOA Composite Application Instances from the Application Home Page" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.

53.4 Creating and Managing Composite Sensors During Runtime from Oracle SOA Composer

You can create, update, and delete composite sensors during runtime from Oracle SOA Composer without having to redeploy a SOA composite application. The following example describes how to create a composite sensor. Changes to composite sensors can be carried to new revisions of the composite through patching.

Ensure that you understand the issues around using duplicate names for composite sensors. For more information, see What You May Need to Know About Duplicate Composite Sensor Names.

To create and manage composite sensors during runtime from Oracle SOA Composer:

1. Log in to Oracle SOA Composer.

   http://host:soa_server_port/soa/composer
   

2. Expand the navigator on the left and double-click the composite in which to make changes. Figure 53-12 provides details.

   Figure 53-12 Oracle SOA Composer

   
   Description of "Figure 53-12 Oracle SOA Composer"
3. Click Create Session.

   The page is refreshed to display the Add, Edit, and Delete icons.

4. Click the Add icon and select an option:

   • Create Service Sensor: Data is coming from a service binding component call.

   • Create Reference Sensor: Data is coming from a reference binding component call.

   • Create Event Sensor: Data is coming from a service component that has subscribed to a business event.

   For this example, Create Service Sensor is selected because the data is coming from a service binding component call. Figure 53-13 provides details.

   Figure 53-13 Composite Sensor Creation

   
   Description of "Figure 53-13 Composite Sensor Creation"

   The Create Composite Sensor dialog is displayed.

5. Click the Edit icon in the Expression section, and select an option:

   • Variables: Select to create an expression value for a variable.

   • Expression: Select to invoke the Expression Builder dialog for creating an XPath expression. This action always captures values as strings.

   • Properties: Select to create an expression value for a normalized message header property. These are the same properties that display under the Properties tab of the invoke activity, receive activity, reply activity, OnEvent branch of a scope activity (in BPEL 2.0), and OnMessage branch of a pick activity and scope activity (in BPEL 2.0).

   For this example, Expression is selected to build an XPath expression.

   Figure 53-14 provides details.

   Figure 53-14 XPath Expression Selection of Create Composite Sensor Dialog

   
   Description of "Figure 53-14 XPath Expression Selection of Create Composite Sensor Dialog"

   The selections of variables, expressions, and header properties are the same as with the Create Composite Sensor dialog in Oracle JDeveloper, as described in Table 53-1.

   The Expression Builder dialog is displayed.

6. Build an XPath expression and click OK. You can also select custom XPath expressions that you created.

   You are returned to the Create Composite Sensor dialog.

7. Select the Enterprise Manager check box in Figure 53-15 to make this composite sensor a searchable, trackable field from the Flow Instances page of a SOA composite application in Oracle Enterprise Manager Fusion Middleware Control, and click OK. If you do not select this check box, the composite sensor is not searchable.

   Figure 53-15 Create Composite Sensor

   
   Description of "Figure 53-15 Create Composite Sensor"

   The new composite sensor is displayed, including the sensor name, the type and name of the component in which the sensor is defined, any XPath expression or filter defined on the sensor, the storage location for runtime sensor data (Enterprise Manager or a JMS queue and topic), and any JMS targets. Figure 53-16 provides details.

   Figure 53-16 Composite Sensors in Oracle SOA Composer

   
   Description of "Figure 53-16 Composite Sensors in Oracle SOA Composer"
8. Click Save.
9. In the upper right corner, click Publish to publish this session. Figure 53-17 provides details.

   Figure 53-17 Publish Button

   
   Description of "Figure 53-17 Publish Button"
10. Enter an optional description for the session when prompted, then click OK.

    The composite sensor is now running automatically in the deployed SOA composite application.

11. Go to the Test Web Service page in Oracle Enterprise Manager Fusion Middleware Control to invoke a new instance. For information about the Test Web Service page, see "Initiating a SOA Composite Application Test Instance" of Administering Oracle SOA Suite and Oracle Business Process Management Suite.
12. Create a new instance of the SOA composite application that includes the composite sensor (for this example, named loanAmount), and click Invoke.
13. Go to the Flow Instances page of the SOA Infrastructure.
14. In the Sensor Name field of the Flow Instance part of the Search Options section, specify the composite sensor you added. Figure 53-18 provides details.

    Figure 53-18 Searchable Field

    
    Description of "Figure 53-18 Searchable Field"
15. Click Search.
16. In the Search Results table, select the instance of the SOA composite sensor and click Show Details.

    Instance details are displayed in the Faults, Composite Sensor Values, Composites, and Resequencing Groups tabs at the bottom of the page.

17. Click the Composite Sensor Values tab.

    This tab displays the values of composite sensors detected in the selected business flow.

    • Name: Displays the composite sensor name (for this example, loanAmount).

    • Value: Displays the value assigned to the composite sensor.

    • Location: Displays the service or reference binding component or service component in which the composite sensor is defined.

    • Composite: Displays the SOA composite application in which the composite sensor is defined.

18. If you want to edit or delete the composite sensor, return to Oracle SOA Composer, as shown in Figure 53-16, and click Create Session.

    The page is refreshed to again display the Add, Edit, and Delete icons.

19. If you set the oracle.soacomposer.composite.showSensorXmlFiles Oracle WebLogic Server startup script system property, the Show Sensor XML button appears at the bottom of the page.
20. Click this property to show sensor.xml and sensor-action.xml content. This helps you to test both to see that they are what you expect them to be.

    If you later import this SOA composite application in to Oracle JDeveloper, the composite sensors created during runtime in Oracle SOA Composer are displayed.

53.4.1 What You May Need to Know About Viewing Composite Sensor Changes in Oracle SOA Composer

When you add or remove composite sensors in Oracle SOA Composer, you must close and reopen the project tab above the Composite Sensors table to see the changes. For example:

1. Create and deploy a SOA composite application with a composite sensor (for this example, named p1).
2. Log in to Oracle SOA Composer, and select the composite in the navigator.

   The p1 composite sensor is displayed.

3. Create an additional composite sensor (for this example, named p2) in the composite and redeploy it.
4. In the navigator tree of Oracle SOA Composer, click the Refresh button, and select the composite.

   Only composite sensor p1 is displayed, and not p2.

5. Close the project tab above the Composite Sensors page, as shown in Figure 53-19, and reopen it by selecting the composite in the navigator.

   Figure 53-19 Composite Tab in Composite Sensors Page

   
   Description of "Figure 53-19 Composite Tab in Composite Sensors Page"

   This enables composite sensors p1 and p2 to be displayed.