22 Proxy Services: Message Flow

This chapter describes how to create and configure message flows using the Oracle Service Bus Administration Console. Sections include adding and configuring pipeline pairs, conditional branches, stages, operational branches, and route nodes. For more detailed information on message flows, see Chapter 37, "Modeling Message Flow in Oracle Service Bus."

For more detailed information on message flows and their components, see Chapter 37, "Modeling Message Flow in Oracle Service Bus."

22.1 Viewing and Editing Message Flows

This section describes how to view and edit message flows.

1. If you have not already done so, click Create to create a new session or click Edit to enter an existing session. See Section 3.1, "Using the Change Center."

2. Locate the proxy service whose message flow you want to view or edit. Do either of the following:

   • Select Project Explorer to display the Projects View page or the Project/Folder View page. Then navigate through projects and folders to find the proxy service.

   • Select Resource Browser > Proxy Services to display the Summary of Proxy Services page.

3. Click the Edit Message Flow icon in the row of the proxy service whose message flow you want to view or edit.

   • If no message flow has yet been created for the selected proxy service, the Edit Message Flow page is displayed with a single icon on the page, the Proxy Service icon. This is the starting node for the proxy service. Click this icon to begin constructing the message flow.

   • If the proxy service already has a message flow, the page contains a graphic representation of the flow. Click the icons to view or edit the parts of the message flow.

   See Section 22.2, "Edit Message Flow Page" for information about what you can do to construct a message flow on that page.

4. Click Save to commit the updates in the current session.

5. To end the session and deploy the configuration to the runtime, click Activate under Change Center.

22.2 Edit Message Flow Page

Use the Edit Message Flow page to construct a message flow for a proxy service.

The left navigation pane of the Edit Message Flow page shows a tree view of the nodes and objects in the message flow. When the details of an object are defined on a separate page, you can click the name of the object to display the associated page.

The right pane provides a field upon which to construct the message flow. When a message flow has not yet been defined, the pane includes a single Proxy Service icon that signifies the starting node for the service. Click the icon to add pipeline pair nodes, route nodes, conditional branches, operational branches, and error handling for the service.

When you add objects to the page, icons are displayed on the page to represent the objects. The relationships among the objects are shown with lines and bounding boxes. Click an icon on the Edit Message Flow page to display a menu of the actions you can perform on that object. The options available on the menu may differ, depending on context. See Table 22-1 for a complete list of icons and options.

Table 22-1 Edit Message Flow Page Icons and Options

Icon	Description	Menu Options
Proxy Service	The starting node for the message flow.	Add Pipeline Pair - See Section 22.4, "Adding Pipeline Pair Nodes to Message Flows." Add Route - See Section 22.8, "Adding Route Nodes to Message Flows." Add Conditional Branch - See Section 22.5, "Adding Conditional Branches to Message Flows." Add Operational Branch - See Section 22.6, "Adding Operational Branches to Message Flows." Add Service Error Handler - See Section 24.2, "Adding Proxy Service Error Handlers."
Pipeline Pair Node	A pipeline pair node consists of a request pipeline and a response pipeline.	Edit Name and Annotation Add Pipeline Pair - See Section 22.4, "Adding Pipeline Pair Nodes to Message Flows." Add Conditional Branch - See Section 22.5, "Adding Conditional Branches to Message Flows." Add Operational Branch - See Section 22.6, "Adding Operational Branches to Message Flows." Paste Route - This option is available only if you have cut or copied a route node and it is on the Clipboard.
Response Pipeline	See pipeline pair node above.	Add Stage - See Section 22.7, "Adding Stages to Pipelines." Add Pipeline Error Handler - See Section 24.3, "Adding Pipeline Error Handlers."
Request Pipeline	See pipeline pair node above.	Add Stage - See Section 22.7, "Adding Stages to Pipelines." Add Pipeline Error Handler - See Section 24.3, "Adding Pipeline Error Handlers."
Pipeline with Error Handler	A pipeline with an error handler defined for it.	Edit Pipeline Error Handler - See Section 24.3, "Adding Pipeline Error Handlers." Delete Pipeline Error Handler
Route Node	Route node actions define the handling of messages as they flow through the route node.	Edit Route - See Section 22.8, "Adding Route Nodes to Message Flows." Edit Name and Annotation Add Route Error Handler - See Section 24.5, "Adding Route Node Error Handlers."
Route Node with Error Handler	A route node with an error handler defined for it.	Edit Route Error Handler - See Section 24.5, "Adding Route Node Error Handlers." Delete Route Error Handler
Stage Node	A stage node is a container of actions.	Edit Stage - See Section 22.7, "Adding Stages to Pipelines." Edit Name and Annotation Add Stage - See Section 22.7, "Adding Stages to Pipelines." Add Stage Error Handler - See Section 24.4, "Adding Stage Error Handlers."
Stage Node with Error Handler	A stage node with an error handler defined for it.	Edit Stage Error Handler - See Section 24.4, "Adding Stage Error Handlers." Delete Stage Error Handler
Conditional Branch Node	A conditional branch node allows processing to proceed down exactly one of several possible paths.	Edit Branch - See Section 22.5, "Adding Conditional Branches to Message Flows." Edit Name and Annotation
Operational Branch Node	An operational branch node determines what branch to follow based on specified operations.	Edit Branch - See Section 22.6, "Adding Operational Branches to Message Flows." Edit Name and Annotation
Branch Node	A branch node is one of the alternative nodes defined by a conditional branch node or an operational branch node.	Add Pipeline Pair - See Section 22.4, "Adding Pipeline Pair Nodes to Message Flows." Add Route - See Section 22.8, "Adding Route Nodes to Message Flows." Add Conditional Branch - See Section 22.5, "Adding Conditional Branches to Message Flows." Add Operational Branch - See Section 22.6, "Adding Operational Branches to Message Flows." Paste Route - This option is available only if you have cut or copied a route node and it is on the Clipboard.
Error Handler	An error handler provides the logic for resending errors in the message flow.	Add Service Error Handler - See Section 24.2, "Adding Proxy Service Error Handlers."

22.3 Edit Stage Configuration Page

Use the Edit Stage Configuration page to add actions to pipeline stages, error handler stages, and route nodes in a message flow.

• When nothing has yet been defined on the Edit Stage Configuration page, the only object displayed is the Add an Action icon. Click that icon to get started.

• When a stage or a route node has already been configured, the actions and objects defined for that stage or route node appear on the page. Edit the existing actions, as appropriate, or click any of the icons representing actions to add more actions to the stage.

See Section 21.1, "Adding and Editing Actions in Message Flows" for instructions on working with all the kinds of actions you can add to a stage.

22.4 Adding Pipeline Pair Nodes to Message Flows

Message flows can include zero or more pipeline pair nodes: request and response pipelines for the proxy service (or for the operations on the service), and error handler pipelines that can be defined for stages, pipelines, and proxy services. pipelines can include one or more stages, which in turn include actions.

Before you begin

These instructions assume you are already editing a message flow in the Edit Message Flow page, as explained in Section 22.1, "Viewing and Editing Message Flows."

To add a Pipeline Pair node to a message flow

1. Click the Proxy Service icon, then click Add Pipeline Pair.

2. To change the default name and add a description for the pipeline pair node, do the following:

   1. Click the Pipeline Pair Node icon, then click Edit Name and Annotation.

   2. Change the name and description, as desired.

   3. Click Save.

      Note:

      When you rename a pipeline or a route node, the number of messages displayed on the Dashboard page in the Monitoring module may not correlate with those of other components due to the pipeline counters being reset to zero. This is because Oracle Service Bus treats the rename as a delete and recreate action. The numbers should correlate again after a time period equal to the service's monitoring interval has elapsed.

3. To add stages to the pipeline, see Section 22.7, "Adding Stages to Pipelines."

4. To add actions to stages in the pipeline. See Section 21.1, "Adding and Editing Actions in Message Flows."

5. On the Edit Message Flow page, continue to construct the message flow, as described in Section 22.1, "Viewing and Editing Message Flows."

6. Click Save to commit the updates in the current session.

7. To end the session and deploy the configuration to the runtime, click Activate under Change Center.

22.5 Adding Conditional Branches to Message Flows

A branch node allows processing to proceed along exactly one of several possible paths. Branching is driven by an XPath-based switch table. Each branch in the table specifies a condition (for example, <500) that is evaluated in order down the message flow against a single XPath expression (for example, ./ns: PurchaseOrder/ns:totalCost on $body). Whichever condition is satisfied first determines which branch is followed. If no branch condition is satisfied, then the default branch is followed. A branch node may have several descendants in the message flow: one for each branch, including the default branch.

If the proxy service is not based on a WSDL and receives multiple document types as input, consider using a conditional branch node.

Conditional branching is driven by a lookup table with each branch tagged with a simple, but unique, string value. A variable in the message context is designated as the lookup variable for that node, and at runtime, its value is used to determine which branch to follow. If no branch matches the value of the lookup variable, the default branch is followed. You should design the proxy service in such a way that the value of the lookup variable is set before reaching the branch node.

Before you begin

These instructions assume you are already editing a message flow in the Edit Message Flow page, as explained in Section 22.1, "Viewing and Editing Message Flows."

To add a conditional branch to a message flow

1. Click a Pipeline Pair Node icon or a Branch Node icon, then click Create Conditional Branch. The conditional branch node is added, and any existing nodes after the inserted branch node are moved to the default branch of the new conditional branch node.

2. To change the default name and add a description for the branch node, do the following:

   1. Click the Conditional Branch icon, then click Edit Name and Annotation.

   2. Change the name and description, as desired.

   3. Click Save.

3. To add branch definitions, click the Conditional Branch icon, then click Edit Branch. The Edit Branch Node page is displayed.

4. Do the following:

   1. In the Selected Path field, click Edit to add an XPath expression for specifying the path. See Section 23.1, "Creating and Editing Inline XQuery and XPath Expressions."

   2. In the Variable field, enter a context variable.

   3. From the Operator field, select a comparison operator.

   4. In the Value field, enter a value for the branch.

   5. In the Label field, enter a label for the branch.

5. Optionally, under Options:

   • Click Add a New Branch to add a new branch definition to this branch node.

   • Click Delete this Branch to delete a branch definition.

   • Click Move Branch Up or click Move Branch Down to change the positions of branch definitions. This option displays only when more than one branch definition exists.

6. Click Save to commit the updates in the current session.

7. On the Edit Message Flow page, continue to construct the message flow, as described in Section 22.1, "Viewing and Editing Message Flows."

8. Click Save to commit the updates in the current session.

9. To end the session and deploy the configuration to the runtime, click Activate under Change Center.

22.6 Adding Operational Branches to Message Flows

When message flows define Web Services Description Language (WSDL)-based proxy services, operation-specific processing is required. Instead of configuring a branching node based on operations manually, Oracle Service Bus provides a minimal configuration branching node that automatically branches based on operations. In other words, when you create an operational branch node in a message flow, you can quickly build your branching logic based on the operations defined in the WSDL because the Oracle Service Bus Administration Console presents those operations in the branch node configuration page.

A branch node allows processing to proceed along exactly one of several possible paths. Branching is driven by an XPath-based switch table. Each branch in the table specifies a condition (for example, <500) that is evaluated in order down the message flow against a single XPath expression (for example, ./ns: PurchaseOrder/ns:totalCost on $body). Whichever condition is satisfied first determines which branch is followed. If no branch condition is satisfied, then the default branch is followed. A branch node may have several descendants in the message flow: one for each branch, including the default branch.

Before you begin

These instructions assume you are already editing a message flow in the Edit Message Flow page, as explained in Section 22.1, "Viewing and Editing Message Flows."

To add an operation branch to a message flow

1. Click a Pipeline Pair Node icon or a Branch Node icon, then click Create Operational Branch. The operational branch node is added, and any existing nodes after the inserted branch node are moved to the default branch of the new operational branch node.

2. To change the default name and add a description for the branch node, do the following:

   1. Click the Operational Branch icon, then click Edit Name and Annotation.

   2. Change the name and description, as desired.

   3. Click Save.

3. To add branch definitions, click the Operational Branch icon, then click Edit Branch. The Edit Branch Node page is displayed.

4. In the Operation Branch Definitions panel, select a service operation.

5. Optionally, under Options:

   • Click Add a New Branch to add a new branch definition to this branch node.

   • Click Delete this Branch to delete a branch definition.

   • Click Move Branch Up or click Move Branch Down to change the positions of branch definitions. This option displays only when more than one branch definition exists.

6. Click Save.

7. On the Edit Message Flow page, continue to construct the message flow, as described in Section 22.1, "Viewing and Editing Message Flows."

8. Click Save to commit the updates in the current session.

9. To end the session and deploy the configuration to the runtime, click Activate under Change Center.

22.7 Adding Stages to Pipelines

Before you begin

These instructions assume you are already editing a message flow in the Edit Message Flow page, as explained in Section 22.1, "Viewing and Editing Message Flows."

To add a stage to a Pipeline

1. If necessary, click the plus sign to the left of the Pipeline Pair Node icon to expand it. A pipeline pair contains a Request Pipeline and a Response Pipeline.

2. Click the pipeline to which you want to add the stage, then click Add Stage.

3. To change the default name and add a description for the stage, do the following:

   1. Click the Stage icon, then click Edit Name and Annotation.

   2. Change the name and description, as desired.

   3. Click Save.

4. To add actions to the stage, click the Stage icon, then click Edit Stage. See Section 21.1, "Adding and Editing Actions in Message Flows."

5. To add error handling to the stage, click the Stage icon, then click Add Stage Error Handler. See Section 24.4, "Adding Stage Error Handlers." The Edit Message Flow page is displayed.

6. Continue to construct the message flow, as described in Section 22.1, "Viewing and Editing Message Flows."

7. Click Save to commit the updates in the current session.

8. To end the session and deploy the configuration to the runtime, click Activate under Change Center.

22.8 Adding Route Nodes to Message Flows

Before you begin

These instructions assume you are already editing a message flow in the Edit Message Flow page, as explained in Section 22.1, "Viewing and Editing Message Flows."

To add a Route Node to a Message Flow

1. Click the Pipeline Pair Node icon of a pipeline pair, then click Add Route.

2. To change the default name and add a description for the route node, click the Route Node icon, then click Edit Name and Annotation. Change the name and description, as desired, then click Save.

   Note:

   When you rename a pipeline or a route node, the number of messages displayed on the Dashboard page in the Monitoring module may not correlate with those of other components due to the pipeline counters being reset to zero. This is because Oracle Service Bus treats the rename as a delete and recreate action. The numbers should correlate again after a time period equal to the service's monitoring interval has elapsed.

3. To add actions to the route node, click the Route Node icon, then click Edit Route. The Edit Message Flow page is displayed. See the following sections for information about the actions you can add to route nodes:

   • Section 21.12, "Adding If... Then... Actions"

   • Section 21.8, "Adding Dynamic Routing to Route Nodes"

   • Section 21.9, "Adding Routing Actions to Route Nodes"

   • Section 21.10, "Adding Routing Tables to Route Nodes"

   • Section 24.5, "Adding Route Node Error Handlers"

4. On the Edit Message Flow page, continue to construct the message flow, as described in Section 22.1, "Viewing and Editing Message Flows."

5. Click Save to commit the updates in the current session.

6. To end the session and deploy the configuration to the runtime, click Activate under Change Center.

22.9 Cutting, Copying, and Pasting Stages and Route Nodes

You can cut, copy, and paste stages and route nodes.

• To cut a stage or a route node, click its icon and select Cut or Copy.

• To paste a stage that you cut or copied from a different pipeline pair within the message flow of this proxy service or from the message flow of a different proxy service, do one of the following:

  • Click the Request Pipeline or Response Pipeline icon, then click Paste Stage.

  • Click the Stage icon in a pipeline, then click Paste.

• To paste a route node that you cut or copied from the message flow of another proxy service, click the Pipeline Pair Node icon for the pipeline pair, then click Paste Route.