Using the Oracle Service Bus Console

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Proxy Services: Actions

Actions are the elements of pipeline stages, error handler stages, route nodes, and branch nodes that define how messages are to be defined as they flow through a proxy service.

Adding and Editing Actions in Message Flows

Actions are the elements of pipeline stages, error handler stages, route nodes, and branch nodes that define how messages are to be defined as they flow through a proxy service.

Before you begin

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

They also assume you have already added a pipeline stage, a route node, and/or an error handler stage. See:

To add an action to a message flow

  1. Select the component to which you want to add an action. For example, click the  Stage icon, then click Edit Stage, or click the  Route Node icon, then click Edit Route.
  2. Depending on whether actions have already been added to the stage or to the route node, do one of the following:
    • If no actions have yet been added, the Edit Stage Configuration page displays only the Add an Action icon. Click that icon, then select an action type.
    • If one or more actions have already been added, the Edit Stage Configuration page displays one or more icons representing those actions, for example, a  Publish icon or a  Routing icon, etc. Click the appropriate icon, click Add an Action, then select an action type.
    • Some actions, such as request and response actions in publish actions, include an  Add an Action link where an action is appropriate. Click that icon, then select an action type.
    • There are no restrictions on what actions may be chained together in a message flow.

      Table 19-1 lists the actions you can configure for message flows.

      Table 19-1 Message Flow Actions 
      Action
      Description
      More Information
      Communication
         
      Dynamic Publish
      Publish a message to a service identified by an Xquery expression
      Publish
      Publish a message to a statically specified service.
      Publish Table
      Publish a message to zero or more statically specified services. Switch-style condition logic is used to determine at run time which services will be used for the publish.
      Routing Options
      Modify any or all of the following properties in the outbound request: URI, Quality of Service, Mode, Retry parameters, Message Priority.
      Service Callout
      Configure a synchronous (blocking) callout to an Oracle Service Bus-registered proxy or business service.
      Transport headers
      Set the transport header values in messages
      Dynamic Routing
      Assign a route for a message based on routing information available in an XQuery resource.
      Routing
      Identify a target service for the message and configure how the message is routed to that service:
      Routing Table
      Assign a set of routes wrapped in a switch-style condition table.Different routes are selected based upon the results of a single XQuery expression.
      Flow Control
         
      For each
      Iterate over a sequence of values and execute a block of actions
      If...then...
      Perform an action or set of actions conditionally, based on the Boolean result of an XQuery expression.
      Raise error
      Raise an exception with a specified error code (a string) and description.
      Reply
      Specify that an immediate reply be sent to the invoker.
      Resume
      Resume message flow after an error is handled by an error handler.
      Skip
      Specify that at run time, the execution of the current stage is skipped and the processing proceeds to the next stage in the message flow.
      Message Processing
         
      Assign
      Assign the result of an XQuery expression to a context variable.
      Delete
      Delete a context variable or a set of nodes specified by an XPath expression.
      Insert
      Insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression.
      Java callout
      Invoke a Java method from the pipeline.
      MFL transform
      Convert non-XML to XML or XML to non-XML in the pipeline.
      Rename
      Rename elements selected by an XPath expression without modifying the contents of the element.
      Replace
      Replace a node or the contents of a node specified by an XPath expression.
      Validate
      Validate elements selected by an XPath expression against an XML schema element or a WSDL resource.
      Reporting
       
      Reporting
      Alert
      Send an alert notification based on pipeline message context.
      Log
      Construct a message to be logged.
      Report
      Enable message reporting for a proxy service.

  3. When you have finished adding actions, you can further configure the actions in stage or route node, as described in Table 19-2.
  4. Table 19-2 Edit Stage Configuration Tasks 
    To...
    Complete This Step...
    Delete an action
    Click the appropriate icon, then click Delete this Action.
    Move an action down (demote)
    Click the appropriate icon, then click Move Action Down. The action is moved below the next action contained in this stage.
    This option is displayed only when a stage contains two or more actions.
    Move an action up (promote)
    Click the appropriate icon, then click Move Action Up. The action is moved above the previous action contained in this stage.

    This option is displayed only when the stage contains two or more actions.

    Cut an action
    Click the appropriate icon, then click Cut.
    Copy an action
    Click the appropriate icon, then click Copy.
    Paste an action that you have cut or copied
    Click the appropriate icon, then click Paste Action.
    You can copy and paste actions across stages. However, in the case of Assign, Replace or Insert actions, note the following:
    • All variable-related and user-defined namespaces from the source (copied) stage are added as user-defined namespaces in the target (pasted) stage.
    • Duplicate namespaces (identical namespaces in both source and target stage) are not copied.
    • Conflicting namespaces (namespace declarations that use the same prefix but different URIs) are copied. Users will be able to save the configuration, but will not be able activate it until the conflicting namespace declarations in stage B are removed.
    Validate a stage
    In the Edit Stage Configuration page, click Validate to validate all the actions configured in that stage.

  5. Click Save to commit the updates in the current session.
  6. On the Edit Message Flow page, continue to construct the message flow, as described in Creating, Editing, and Viewing Message Flows.
  7. Click Save to commit the updates in the current session.
  8. To end the session and deploy the configuration to the run time, click Activate under Change Center.

Adding Publish Actions

Use a publish action to identify a statically specified target service for a message and to configure how the message is packaged and sent to that service.

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Select Add an Action > Communication > Publish.
  3. Click <Service>. The Select Service page is displayed.
  4. Select a service from the list, then click Submit. This is the target service for the message.
  5. If the service has operations defined, you can specify an operation to be invoked by selecting it from the Operation list.
  6. To make the outbound operation the same as the inbound operation, select the Use inbound operation for outbound check box.
  7. To configure how the message is packaged and sent to the service, in the Request Actions field, click Add an Action. Then select an action to associate with the service. You can add more than one action. See Adding and Editing Actions in Message Flows.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Publish Table Actions

Use a publish table action to publish a message to zero or more statically specified services. Switch-style condition logic is used to determine at run time which services will be used for the publish.

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Select Add an Action > Communication > Publish Table.
  3. Click <Expression>. The XQuery Expression Editor page is displayed. Create an XQuery expression, which at run time returns the value upon which the routing decision will be made. See Creating and Editing Inline XQuery and XPath Expressions.
  4. From the Operator list, select a comparison operator. Then, in the adjacent field, enter a value against which the value returned from the XQuery expression will be evaluated.
  5. Click <Service> to select a service to which messages are to be published if the expression evaluates true for the value you specified. The Select Service page is displayed.
  6. Select a service from the list, then click Submit. This is the target service for the message.
  7. If the service has operations defined, you can specify the operation to be invoked by selecting it from the invoking list.
  8. If you want the outbound operation to be the same as the inbound operation, select the Use inbound operation for outbound check box.
  9. In the Request Actions field, to configure how the message is packaged and sent to the service, click Add an Action, then select one or more actions that you want to associate with the service. To learn more about the type of action you want to add, see Adding and Editing Actions in Message Flows.
  10. Note: There is a nesting limit of four cumulative levels in the stage editor. If you attempt to add a fifth level, nesting action is not displayed. Cumulative levels include all branching actions: if... then... conditions, publish tables, and route tables. For example, you can have 2 levels of conditionals, then a publish table with a route table inside of it, bringing the total to 4 levels. If you attempt to add another conditional (to the last publish table), the conditional is not displayed.
  11. To insert a new case, click the  Case icon, then select Insert New Case.
  12. Repeat steps 4-8 for the new case.
  13. Add additional cases as dictated by your business logic.
  14. Click the  Case icon of the last case you define in the sequence, then select Insert Default Case to add a default case at the end.
  15. Configure the default case—the configuration of this case specifies the routing behavior in the event that none of the preceding cases is satisfied.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Dynamic Publish Actions

Use a dynamic publish action to publish a message to a service specified by an XQuery expression.

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Communication > Dynamic Publish.
  3. Click <Expression>.
  4. In the XQuery Expression Editor, enter an Xquery expression or select an XQuery resource that provides a result similar to:
  5. <ctx:route>
    <ctx:service isProxy="false">project/folder/businessservicename</ctx:service>
    <ctx:operation>foo</ctx:operation>
    </ctx:route>
    Note: The element operation is optional.
  6. Click Save.
  7. In the Request Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you can add, see the table of actions in Adding and Editing Actions in Message Flows.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Routing Options Actions

Use the Routing Options action to modify any or all of the following properties for the outbound request in $outbound: URI, Quality of Service, Mode, Retry parameters. Although these properties can be modified using Assign, Insert, Replace, or Delete actions on $outbound, using Routing options provides a simpler way to perform this task, without requiring knowledge of XPath, XQuery, or the structure of the $outbound context variable.

The Routing Options action can only be used where the context variable $outbound is valid. It can be added to the following actions:

To configure a routing options action:

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Communication > Routing Options.
  3. Complete any or all of the following steps:
    • To set the URI for the outbound message: Select URI, and click the XQuery Expression Editor. Enter an expression that returns a URI. This overrides the URI for the invoked service.
    • To set the Quality of Service element: Select Quality of Service, and select the Quality of Service option from the drop-down list. This overrides the default that is auto computed.
    • To set the Mode: Select Mode, and select either request, or request-response from the drop-down list.
    • Note: This is normally already automatically set, based on the interface of the service invoked. However, in some cases like Any Soap or Any XML services, this is not so.
    • To set the Retry Interval: Select Retry Interval, and specify the number of seconds between retries. This overrides the default configured with the invoked service.
    • To set the Retry Count: Select Retry Count, and specify the number of retries the system must attempt before discontinuing the action. This overrides the default configured with the invoked service.
    • To set the Message Priority: Select Priority, and click the XQuery Expression Editor. Enter an expression that returns a positive integer.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Service Callout Actions

Use a service callout action to configure a synchronous (blocking) callout to an Oracle Service Bus-registered proxy or business service.
  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Communication > Service Callout.
  3. Click <Service>. The Service Browser is displayed.
  4. Select a service from the list of registered proxy or business services, then click Submit.
  5. If the service you chose in step 3, above, is WSDL-based and has operations that can be invoked on the service, those operations are listed in the invoking <Operation> drop-down list. Select an operation to be invoked on the service.
  6. Specify how you want to configure the request and response messages by selecting one of the following options:
    • Select Configure SOAP Body to configure the SOAP Body. Selecting this option allows you to use $body directly.
    • Note: This option supports SOAP-RPC encoded, which is not supported when configuring payload parameters or document.
    • Select Configure Payload Parameters or Configure Payload Document to configure the payload.
  7. Subsequent configuration options depend on the kind of service you selected in step 3 and on the kind of configuration options you chose for that service in step 5. Table 19-3 shows the options available for each service type.
    Table 19-3 Service Callout Configuration Options for Each Service Type 
    Selected Service Type
    Configure SOAP Body” Options
    “Configure Payload Parameters” Options or
    “Configure Payload Document” Options
    • SOAP RPC
    • SOAP Document
    • Any SOAP
    • XML
    • Any XML
    • Messaging
  8. Table 19-4, below, provides instructions for each of the options listed in Table 19-3, above.

    Table 19-4 Service Callout Configuration Options 
    For These Options...
    Follow These Steps...
    SOAP Request Body and
    SOAP Response Body
    To configure these options,
    • In the SOAP Request Body field, enter the name of a variable to hold the XML of the SOAP Body element for the callout request.
    • In the SOAP Response Body field, enter the name of a variable to which the XML of the SOAP Body element on the response will be bound.
    SOAP Request Header and
    SOAP Response Header
    To configure these options,
    • In the SOAP Request Header field, enter the name of a variable to hold the XML of the SOAP Header element for the callout request
    • You must wrap the input document for the SOAP Request Header with <soap-env:Header>...</soap-env:Header>.

    • In the SOAP Response Header field, enter the name of a variable to which the XML of the SOAP Headers on the response, if any, will be bound.
    Request Parameters and
    Response Parameters
    To configure options,
    • In the Request Parameters fields, enter names for the variables that will be evaluated at run time to provide values for the request parameters.
    • You must provide only the core payload documents in the input variable—the SOAP package is created for you by Oracle Service Bus. In other words, do not wrap the input document with <soap-env:Body>...</soap-env:Body>.

      For example, when creating a body input variable that is used for this request parameter, you would define that variable’s contents using the XPath statement body/* (to remove the wrapper soap-env:Body), not $body (which results in keeping the soap-env:Body wrapper).

    • In the Response Parameters fields, enter the names of the variables to which the responses will be assigned at run time.
    Request Document and
    Response Document
    To configure these options,
    • In the Request Document Variable field, enter the name of a variable to assign a request document to.
    • For SOAP Document-type services, the variable is evaluated at runtime to form the body of the SOAP message sent to the service. For Any XML services, the variable is evaluated at runtime to form the body of the XML message sent to the service.

      For SOAP Document-type services and for Any XML services, you provide only the core payload documents in the input variable—the SOAP package is created for you by Oracle Service Bus. In other words, do not wrap the input document with <soap-env:Body>...</soap-env:Body>.

      For example, when creating a body input variable that is used for this request parameter, you would define that variable’s contents using the XPath statement body/* (to remove the wrapper soap-env:Body), not $body (which results in keeping the soap-env:Body wrapper).

      For Messaging services, the variable is evaluated to form the body of the message, based on the type of data expected by the service. The following restrictions apply to variables used with Messaging services:

      • For services that expect binary data, the variables must have a ctx:binary-content element.
      • For services that expect MFL data, the variable must have the XML equivalent.
      • For services that expect text data, the variable is a string.
    • In the Response Document Variable field, enter the name of the variable to which a response document will be assigned at run time.

  9. Optionally, add one or more transport headers. For more information, see Adding Transport Header Actions.
  10. Note: In addition to the transport headers you specify, headers are added by the Oracle Service Bus binding layer. For more information, see Configuring Transport Headers in Message Flows in Oracle Service Bus User Guide.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Transport Header Actions

Use a transport header action to set the header values in messages.

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Communication > Transport Headers.
  3. From the Set Transport Headers for list, select one of the following, to specify to the run time which of the message context locations are to be modified:
    • Outbound Request - Select this option to set header values for outbound requests (the messages sent out by a proxy service in route, publish, or service callout actions). This header element is located in the message context as follows:
    • $outbound/ctx:transport/ctx:request/tp:headers

    • Inbound Response - Select this option to set header values for inbound responses (the response messages a proxy service sends back to clients). This header element is located in the message context as follows:
    • $inbound/ctx:transport/ctx:response/tp:headers

  4. Optionally, select Pass all Headers through Pipeline to pass all headers through from the inbound message to the outbound message or vice versa. Every header in the source set of headers will be copied to the target header set, overwriting any existing values in the target header set.
  5. For information about using this option in conjunction with the header-specific pass through option, see Configuring Transport Headers in Message Flows in Oracle Service Bus User Guide.

  6. Complete the following steps for each Header you want to add:
    1. In the Transport Headers table, click Add Header to display fields for configuring the header.
    2. Specify a header by doing either of the following:
      • From the drop-down list in the Name column, select a header name. The list contains all of the predefined header names for the target transport (for example, Content-Type for HTTP transports, JMSCorrelationID for JMS transports, etc.).
      • Enter a header name in the Other field. If that header name is not one of the predefined headers for this service’s transport, it becomes a user-header, as defined by the transport specification.
    3. Select one of the options in the Action column to specify how to set the headers value:
    4. Set Header to Expression

      Selecting this option allows you to use an XQuery or XSLT expression to set the value of the header. The expression can be simple (for example, “text/xml”) or a complex XQuery or XSLT expression.

      Because the Oracle Service Bus transport layer defines the XML representation of all headers as string values, the result of any expression is converted to a string before the header value is set. Expressions that return nothing result in the header value being set to the empty string. You cannot delete a header using an expression.

WARNING: Warning: Not all of the header settings you can specify in this action are honored at run time.For information about which of the headers for a given transport you can set and which of those set are honored at run time, see Configuring Transport Headers in Message Flows in Oracle Service Bus User Guide.

Delete Header

Specifies that the header is removed from the request or response metadata.

Copy Header from Inbound Request (if you are setting transport headers for the Outbound Request)
      or
Copy Header from Outbound Response (if you are setting transport headers for the Inbound Response)

Specifies that this header is copied directly from the corresponding header of the same name from the inbound message to the outbound message and vice versa. For example, if you want to set the SOAPAction header for an outbound request, selecting Copy Header from Inbound Request causes the run time to copy the value from the SOAPAction request header of $inbound. In the case of inbound response headers, the source of the header to copy is the response headers of $outbound.

If the Copy Header... option is selected for a header that does not exist in the source, this option is ignored and no action is performed on the target for this header.

For information about using this option in conjunction with the global Pass all Headers through Pipeline option, see Configuring Transport Headers in Message Flows in Oracle Service Bus User Guide.

  1. To add additional Headers to the table, click the  Header icon, then click Add Header.
  2. The table is expanded to include an additional row, which includes a new set of options that you can use to configure another transport header. You can add as many headers as necessary to this table. You do not have to order the headers in the table, because the run time declares namespaces and places header elements in their proper order when generating the corresponding XML.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Dynamic Routing to Route Nodes

Assign a route for a message based on routing information available in an XQuery resource.

This is a terminal action, which means you cannot add another action after this one. However, this action can contain request and response actions.

Before you begin

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

To add Dynamic Routing to a Route Node

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the  Route Node icon, then click Edit Route. The Edit Stage Configuration page is displayed.
  3. Click the  Add an Action icon, then select Communication > Dynamic Routing.
  4. Click <Expression>. The XQuery Expression Editor is displayed.
  5. In the XQuery Expression Editor, enter an Xquery expression, the result of which is similar to:
  6. <ctx:route>

        <ctx:service isProxy='true'>{$service}</ctx:service>

        <ctx:operation>{$operation}</ctx:operation>

    </ctx:route>

    Note: If a proxy service is being invoked, isProxy attribute should be set to true.
    Note: – The service name is the fully qualified service name.
    Note: – The operation element is optional
  7. Click Save.
  8. In the Request Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you want to add, see the table of actions in Adding and Editing Actions in Message Flows.
  9. In the Response Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you want to add, see the table of actions in Adding and Editing Actions in Message Flows.
  10. Click Save.
  11. On the Edit Message Flow page, continue to construct the message flow, as described in Creating, Editing, and Viewing Message Flows.
  12. Click Save to commit the updates in the current session.
  13. To end the session and deploy the configuration to the run time, click Activate under Change Center.

Adding Routing Actions to Route Nodes

Identify a target service for the message and configure how the message is routed to that service.

This is a terminal action, which means you cannot add another action after this one. However, this action can contain request and response actions.

Before you begin

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

To add a Routing Action to a Route Node

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the  Route Node icon, then click Edit Route. The Edit Stage Configuration page is displayed.
  3. Click the  Add an Action icon, then select Communication > Routing.
  4. Click Service. The Service Browser is displayed.
  5. Select a service from the list, then click Submit. The service is displayed instead of the default link.
  6. If you want the outbound operation to be the same as the inbound operation, select the Use inbound operation for outbound check box.
  7. In the Request Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you can add, see the table of actions in Adding and Editing Actions in Message Flows.
  8. In the Response Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you can add, see the table of actions in Adding and Editing Actions in Message Flows.
  9. Click Save.
  10. On the Edit Message Flow page, continue to construct the message flow, as described in Creating, Editing, and Viewing Message Flows.
  11. Click Save to commit the updates in the current session.
  12. To end the session and deploy the configuration to the run time, click Activate under Change Center.

Adding Routing Tables to Route Nodes

A routing table is a set of routes wrapped in a switch-style condition table. It is a short-hand construct that allows different routes to be selected based upon the results of a single XQuery expression.

There is a nesting limit of four cumulative levels in the stage editor. If you attempt to add a fifth level, this nesting action is not displayed. Cumulative levels include all branching actions: If... Then... conditions, publish tables, and route tables. For example, you can have 2 levels of conditionals, then a publish table with a route table inside of it, bringing the total to 4 levels. If you attempt to add another conditional (to the last publish table), the conditional is not displayed.

Identify target services for messages and configure how the messages are routed to these services:

This is a terminal action, which means you cannot add another action after this one. However, this action can contain request and response actions.

Before you begin

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

To add a Routing Table to a Route Node

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the  Route Node icon, then click Edit Route. The Edit Stage Configuration page is displayed.
  3. Click the  Add an Action icon, then select Communication > Routing Table. The routing table action is displayed.
  4. From the Operator list, select a comparison operator, then enter a value expression in the adjacent field.
  5. Click <Service>. The Select Service page is displayed.
  6. Select a service from the list, then click Submit.
  7. If you want to invoke an operation on the service, select an operation from the Operation list
  8. If you want the outbound operation to be the same as the inbound operation, select the Use inbound operation for outbound check box.
  9. In the Request Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action.
  10. In the Response Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action.
  11. To learn more about the types of request and response actions you can add, see Adding and Editing Actions in Message Flows.

  12. To insert a new case, click the  Case icon, then select Insert New Case.
  13. Repeat steps 2-7 for the new case. You can click the  Case icon, then select Insert Default Case to add a default case at the end whose routes are selected if none of the preceding cases is satisfied.
  14. Click Save.
  15. On the Edit Message Flow page, continue to construct the message flow, as described in Creating, Editing, and Viewing Message Flows.
  16. Click Save to commit the updates in the current session.
  17. To end the session and deploy the configuration to the run time, click Activate under Change Center.

Adding For Each Actions

Use the for each action to iterate over a sequence of values and execute a block of actions.

Before you begin

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

To add a For Each action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Flow Control > For Each.
  3. Enter variable names in the ...variable fields, click <XPath> to open the XPath editor to create an XPath expression, and configure the actions in the Do () loop.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding If... Then... Actions

Use an if...then... action to perform an action or set of actions conditionally, based on the Boolean result of an XQuery expression.

Before you begin

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

To add an If...Then action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Flow Control > If...Then.
  3. Click <Condition> to display the XQuery Condition Editor page.
  4. The condition you create is used as the test that is executed before the then() clause is entered, per standard if...then logic. See Creating and Editing Inline XQuery and XPath Expressions.

  5. When you finish editing the XQuery condition, click Add an Action, then select an action that you want to associate with the condition. To learn more about the type of action you want to add, see Adding and Editing Actions in Message Flows.
  6. In the route node, you can select only the routing, dynamic routing, or routing table actions. However, these actions can contain request and response actions inside of them.

  7. As your logic requires, click the  If...Then... icon, then click Add else-if Condition or Add else Condition to add else-if conditions or else conditions. Click Add an Action to associate actions with these conditions.
  8. Condition actions can be nested. However, there is a nesting limit of four cumulative levels in the stage editor. If you attempt to add a fifth level, this nesting action is not displayed. Cumulative levels include all branching actions:if...then... conditions, publish tables, and route tables. For example, you can have two levels of conditionals, then a publish table with a route table inside of it, bringing the total to four levels. If you attempt to add another conditional action (to the last publish table), it is not displayed.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Raise Error Actions

Use the raise error action to raise an exception with a specified error code (a string) and description.

Before you begin

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

To add a Raise Error action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Flow Control > Raise Error.
  3. In the error code field, enter the error code you want to raise.
  4. In the error message field, enter a description of the error code.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Transactions

If a service is transactional, a triggered Raise Error action aborts the transaction in the request (asynchronous) or in either the request or response (synchronous). For example, you may introspect messages and determine conditions under which a Raise Error action should occur even if no SOAP fault occurs, and Raise Error causes the transaction to be aborted.

Adding Reply Actions

Use the reply action to specify that an immediate reply be sent to the invoker.

The reply action can be used in the request, response or error pipeline. You can configure it to result in a reply with success or failure. In the case of reply with failure where the inbound transport is HTTP, the reply action specifies that an immediate reply is sent to the invoker.

Before you begin

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

To add a Reply action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Flow Control > Reply.
  3. Select With Success to reply that the message was successful, or select With Failure to reply that the message has a fault.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Resume Actions

Use the resume action to resume message flow after an error is handled by an error handler. This action has no parameters and can only be used in error pipelines.

Before you begin

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

To add a Resume action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Flow Control > Resume.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Skip Actions

Use the skip action to specify that at run time, the execution of this stage is skipped and the processing proceeds to the next stage in the message flow. This action has no parameters and can be used in the request, response or error pipelines.

Before you begin

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

To add a Skip action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Flow Control > Skip.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Assign Actions

Use the assign action to assign the result of an XQuery expression to a context variable.

Before you begin

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

To add an Assign action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Message Processing > Assign.
  3. Click <Expression>. The XQuery Expression Editor page is displayed. The XQuery expression is used to create the data that will be assigned to the named variable. See Creating and Editing Inline XQuery and XPath Expressions.
  4. When you finish editing the expression, enter a context variable in the variable field. To learn more about context variables, see Inbound and Outbound Variables and Constructing Messages to Dispatch in the Oracle Service Bus User Guide.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Delete Actions

Use the delete action to delete a context variable or a set of nodes specified by an XPath expression.The delete action is one of a set of update actions.

Before you begin

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

To add a Delete action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. To delete a context variable, select the Variable radio button, then enter the name of a context variable in the Variable field. To learn more about context variables, see Appendix A, “Message Context.”
  3. Alternatively, to delete all nodes selected by an XPath expression, select the XPath radio button, then click <XPath>. The XPath Expression Editor page is displayed. See Creating and Editing Inline XQuery and XPath Expressions. After you save the expression, enter a context variable in the variable field. To learn more about context variables, see Appendix A, “Message Context.”

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Insert Actions

Use the insert action to insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression. The insert action is one of a set of update actions.

Before you begin

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

To add an Insert action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Message Processing > Insert.
  3. Click <Expression> to edit an XQuery expression. The XQuery expression is used to create the data that will be inserted at a specified location in a named variable. The XQuery Expression Editor page is displayed. See Creating and Editing Inline XQuery and XPath Expressions.
  4. When you finish editing the expression, select the relative location from the drop-down list. The relative location is used to control where the insert is performed relative to the result of the XPath expression:
    • Before—as sibling before each element or attribute selected by the XPath expression
    • After—as sibling after each element or attribute selected by the XPath expression
    • As first child of—as first child of each element identified by the XPath expression. An error occurs if the result of the XPath returns attributes.
    • As last child of—as last child of each element identified by the XPath expression. An error occurs if the XPath returns attributes.
  5. Click XPath. The XPath Expression Editor page is displayed. See Creating and Editing Inline XQuery and XPath Expressions.
  6. Valid configurations include those in which:

    • XQuery and XPath expressions both return elements.
    • The XQuery and XPath expressions both return attributes—in which case, the XQuery expression must return attributes.
  7. When you finish editing the XPath expression, enter a context variable in the in variable field. The XPath evaluates the contents of this variable. To learn more about context variables, see Appendix A, “Message Context.”

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Java Callout Actions

Use the Java callout action to invoke a Java method, or EJB business service, from within the message flow.

Before you begin

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

To add a Java Callout action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Message Processing > Java Callout.
  3. Click <Method>. The Select a JAR page is displayed. Select a JAR resource from the list. The Select a Class and Method page is displayed.
  4. From the list of Java classes listed, click the + beside the appropriate class, to display a list of methods. Select a method and click Submit. The Java callout action is displayed on the Edit Stage page, as follows:
    • <Method> is replaced by the name of the Java method you selected in steps 2 and 3. This name is a link to the Select a Class and Method page. You can click this link to change your selection of Java method.
    • The method must be a static method.

    • Parameters: An <Expression> link to the XQuery Expression Editor page is provided for each argument the Java method requires. A label for each link indicates the data type for the argument, which will be one of the following:
      • Java.lang.String
      • Primitive types, and their corresponding class types (e.g., int vs. java.lang.Integer)
      • java.lang.BigDecimal, and java.lang.BigInteger (these types are used in financial calculations where round-off errors or overflows are not tolerable)
      • only org.apache.xbeans.XmlObject and no typed xml beans.
      • byte[]
      • java.lang.String[] (INPUT ONLY)
      • XmlObject [ ] (INPUT ONLY)
    • Result: A Result field in which you enter the variable to which the result is to be assigned. The label for the field indicates the data type of the result.
    • Note: If the result is a byte array (the only possible array returned), the binary-content XML element is returned.
    • Attach a Service Account: A Service Account link allows you to specify an optional Service Account if there is a security context for this Java method. To learn more about security contexts and service accounts, see Service Accounts.
    • In the case of fixed and mapped service accounts, the userid/password from the service account is authenticated in the local system and the security context propagated to the Java callout. In the case of passthru, the security context is propagated to the Java callout. This context is the message level context if defined (with WS-Security). Else it is the transport level context.

  5. Under Parameters, click <Expression>. The XQuery Expression Editor page is displayed. Use the XQuery Expression Editor to provide the arguments required by the Java method. See Creating and Editing Inline XQuery and XPath Expressions
  6. If the type of the input value you enter does not match the declared input argument type, Oracle Service Bus tries to automatically typecast input values to the declared type of the input argument. For example a string value of "123" will be converted to integer 123 if the declared type of the input argument is java primitive int.

  7. In the Result field, assign a variable for the result returned by the Java method.
  8. If there is a security context for the Java method, select the check box and click <Service Account>. The Select Service Account page is displayed. Select the required service account from the list, and click Submit.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding MFL Transform Actions

Use the MFL (Message Format Language) transform action to convert message content from XML to non-XML, or vice versa, in the message pipeline. An MFL is a specialized XML document used to describe the layout of binary data. It is an Oracle proprietary language used to define rules to transform formatted binary data into XML data, or vice versa. See MFLs.

Before you begin

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

To add an MFL Transform action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Message Processing > MFL Transform.
  3. From the Apply MFL Transformation drop-down list, select XML to Non-XML or Non-XML to XML, according to your requirement.
  4. Click <Expression>. Using the XQuery Expression Editor, specify the variable on which the MFL transformation action is to be performed. This input must be text or binary when transforming to XML, and must be XML when transforming to non-XML. Binary content in the message context is represented by the binary-content XML element. This XML should be the result of the Xquery expression when the input needs to be binary. See Creating and Editing Inline XQuery and XPath Expressions.
  5. Select one of the following options:
    • MFL Resource: click the <resource> link. The Select MFL page is displayed. Select the static MFL resource that will perform the MFL transform action.
    • MFL Resource from: click the Expression link. The XQuery Expression Editor page is displayed. Using the XQuery Expression Editor, create or edit an XQuery expression to dynamically specify an MFL resource that will perform the transform action, in the format project/folder/MFLresourcename. See Creating and Editing Inline XQuery and XPath Expressions.
  6. In the Assign to Variable field, enter the name of the variable to which the result of this transform action is to be assigned. The result will be a binary-content XML element.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Rename Actions

Use the rename action to rename elements selected by an XPath expression without modifying the contents of the element. The rename action is one of a set of update actions.

Before you begin

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

To add a Rename action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Message Processing > Rename.
  3. Click <XPath>. The XPath Expression Editor page is displayed. The XPath expression is used to specify the data (in the named variable) that will be renamed. See Creating and Editing Inline XQuery and XPath Expressions.
  4. In variable field, enter the context variable that holds the element you want to rename. To learn more about context variables, see Appendix A, “Message Context.”.
  5. Do one of the following:
    • To rename selected elements using a localname, select the first localname radio button, then enter a local name in the localname field.
    • To rename selected elements using a namespace, select the first namespace radio button, then enter a namespace in the namespace field.
    • To rename selected elements using a local name and namespace, select the localname and namespace radio button, then enter a local name and namespace in the localname and namespace fields.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Replace Actions

Use a replace action to replace a node or the contents of a node specified by an XPath expression. The node or its contents are replaced with the value returned by an XQuery expression.

A replace action can be used to replace simple values, elements and even attributes. An XQuery expression that returns nothing is equivalent to deleting the identified nodes or making them empty, depending upon whether the action is replacing entire nodes or just node contents.

The replace action is one of a set of update actions.

Before you begin

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

To add a Replace action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Message Processing > Replace.
  3. Click <XPath>. The XPath Expression Editor page is displayed. The XPath expression is used to specify the data (in the named variable) that will be replaced.See Creating and Editing Inline XQuery and XPath Expressions.
  4. When you finish editing the XPath expression, enter a context variable in the in variable field. See Appendix A, “Message Context.”
  5. Click <Expression>. The XQuery Expression Editor page is displayed. The XQuery expression is used to create the data that replaces the data specified by the XPath in the named variable.See Creating and Editing Inline XQuery and XPath Expressions.
  6. When you finish editing the XQuery expression, select one of the options:
    • Replace entire node—to specify that the nodes selected by the XPath expression you defined are replaced along with all of its contents
    • Replace node contents—to specify that the node is not replaced; only the contents are replaced.
    • Note: Selecting the Replace node contents option and leaving the XPath field blank is more efficient than selecting the Replace entire node option and setting the XPath to ./*

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Validate Actions

Use a validate action to validate elements selected by an XPath expression against an XML schema element or a WSDL resource. You can validate global elements only; Oracle Service Bus does not support validation against local elements.

Before you begin

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

To add a Validate action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Message Processing > Validate.
  3. Click XPath. to construct an XPath expression that specifies the elements to be validated. See Creating and Editing Inline XQuery and XPath Expressions. When you are finished constructing the expression in the XPath Expression Editor, click Save. to insert the expression on the Edit Stage Configuration page.
  4. In the in variable field, enter the name of the variable to hold the element to be validated.
  5. Click resource, then select WSDL or Schema.
  6. From the WSDL Browser or XML Schema Browser, do the following:
    1. Select the WSDL or XML schema
    2. Select the WSDL or XML schema type or element
    3. Click Submit.
  7. To save the result of this validation (a boolean result), select Save result of validation in variable and enter the name of the variable in which you want to save the result.
  8. Alternatively, to raise an error if the element fails validation against the WSDL or XML schema element, select Raise Error on validation failure.

After you are finished

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Alert Actions

Use the alert action to generate alerts based on message context in a pipeline, to send to an alert destination. Unlike SLA alerts, notifications generated by the alert action are primarily intended for business purposes, or to report errors, and not for monitoring system health. Alert destinations should be configured and chosen with this in mind. To learn more about alert destinations, see Alert Destinations.

If pipeline alerting is not enabled for the service or at the domain level, the configured alert action is bypassed during message processing.

Before you begin

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

To add an Alert action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Reporting > Alert.
  3. Click <Destination>. The Select Alert Destination page is displayed. Select the required alert destination from the list and click Submit.
  4. By default, the alert will always go to the console.

  5. Click <Expression>. The XQuery Expression Editor page is displayed. You specify the message context to be added to the alert message through XQuery expressions on context variables. See Creating and Editing Inline XQuery and XPath Expressions.
  6. In the alert summary field, enter a short description of the alert. This will be the subject line in the case of an E-mail notification, and can contain no more than 80 characters. If no description is provided, a predefined subject line that reads, “Oracle Service Bus Alert”, will be used instead.
  7. In the severity level drop-down list, select a severity level for this alert from among: Normal, Warning, Minor, Major, Critical, and Fatal.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Tip: In order to prevent exceptions from aborting the message being processed, when generating a pipeline alert, it is recommended that an error handler for the alert action be defined to handle and contain such exceptions locally, rather than having them bubble up to a global error handler.

Adding Log Actions

Use the log action to construct a message to be logged and to define a set of attributes with which the message is logged.

Before you begin

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

To add a Log action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Reporting > Log.
  3. Click <Expression>. The XQuery Expression Editor page is displayed. You specify the message context to be logged through XQuery expressions on context variables. See Creating and Editing Inline XQuery and XPath Expressions.
  4. In the Annotation field, enter notes for this log action. These notes are logged along with the result of the previously defined expression.
  5. In the severity level drop-down list, select one of the options.
  6. Table 19-5 Log Action Severity Levels 
    Severity Level
    Typical Usage
    Info
    Used for reporting normal operations; a low-level informational message.
    Warning
    A suspicious operation or configuration has occurred but it might not affect normal operation.
    Error
    A user error has occurred. The system or application can handle the error with no interruption and limited degradation of service.
    Debug
    While your application is under development, you might find it useful to create and use messages that provide verbose descriptions of low-level activity within the application.

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.

Adding Report Actions

Use the report action to enable message reporting for a proxy service.

Before you begin

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

To add a report action

  1. Navigate to where you want to add the action, as described in Adding and Editing Actions in Message Flows.
  2. Click the appropriate icon, then select Add an Action > Reporting > Report.
  3. Click <Expression>. The XQuery Expression Editor page is displayed. See Creating and Editing Inline XQuery and XPath Expressions. The XQuery expression is used to create the data that will be reported to the Oracle Service Bus dashboard.
  4. When you finish editing the XQuery expression, click Add a Key. Two fields are displayed: a Key Name field and a Key Value field, which includes an XPath link that you can click to edit an XPath expression and an in variable field in which you can enter a context variable.
  5. You use key value pairs to extract key identifiers from any message context variable or message payload, and ignore the rest of the message. The keys are a convenient way to identify a message. They are displayed as report indexes in the Reporting module. See Viewing Reporting Messages and Viewing Message Details.

    1. Enter a key name in the Key Name field.
    2. Click <XPath>. The Edit an XPath Expression page is displayed. See Creating and Editing Inline XQuery and XPath Expressions.
    3. Enter a context variable in the in variable field. To learn about context variables, see Appendix A, “Message Context.”
    4. To add more key values, click the  Key icon, then select Add a Key. To delete a key, click the  Key icon, then select Delete this Key.

For example, consider a report action configured on an error handler in a stage. The action reports the contents of the fault context variable in the event of an error. The report action is configured as follows:

Each time this action is executed at run time, a message is reported via the Reporting Data Stream. The following table shows the results after the report action is executed twice.

Report Index
DB TimeStamp
Inbound Service
Error Code
errorCode=BEA-382505
04/26/07 9:45 AM
MortgageBroker/ProxySvcs/loanGateway3
BEA-382505
errorCode=BEA-382505
04/26/07 9:45 AM
 
BEA-382505

After you finish

When you complete the configuration of this action, continue by configuring other actions or by saving your configuration, as described in Adding and Editing Actions in Message Flows.


  Back to Top       Previous  Next