Using the AquaLogic Service Bus Console

Proxy Services: Actions

Proxy services are the definitions of services implemented locally on the AquaLogic Service Bus server. Actions allow you to design and configure the message flow in the pipelines, route nodes and branch nodes of a proxy services.

This topic describes how to add actions to stages in pipelines, route nodes, and branch nodes, and describes each of the actions available in AquaLogic Service Bus. It includes the following sections:

Adding an Action

The Edit Stage Configuration page enables you to add actions. Actions are the elements of stages in pipelines and route and branch nodes that define the handling of messages as they flow through a proxy service. To learn more about Message Flow, see Overview of Message Flow.

Note: You must create a pipeline pair node and add a stage before you can add actions. To learn more, see Adding a Pipeline Pair Node and Adding a Stage.

To Add an Action

If you have not already done so, from the left navigation pane, under Change Center, click Create to create a new session for making changes to the current configuration. To learn more, see Using the Change Center.

On the Summary of Proxy Services page, click the Edit Message Flow icon for the appropriate proxy service. Alternatively, if you are in the Project Explorer module, click the Edit Message Flow icon for the appropriate proxy service in the list of resources for a selected project or folder.

The Edit Message Flow page is displayed.

Expand an existing pipeline to view the pipeline, which consists of request and response pipelines.

Click the Stage icon of an existing stage to which you want actions, click Edit, then click Stage. The Edit Stage Configuration page is displayed.

To add an action, click Add an Action, then select an action type.

The following table lists the actions you can configure for AquaLogic Service Bus message flows, and links you to topics that describe the actions, including how to configure them. Table 16-1 AquaLogic Service Bus Actions Action Summary Description Assign Assign the result of an XQuery expression to a context variable Delete Delete a context variable or all the nodes specified by an XPath expression 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 Insert Insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression Log Construct a message to be logged Publish Specify a target service for a message and configure how the message is packaged and sent to that service Publish Table Specify a target service for a message and configure how the message is packaged and sent to that service. Use the Publish Table to wrap a set of routing options in switch-style condition logic Raise Error Raise an exception with a specified error code and description 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 Reply Specify that an immediate reply is sent to the invoker; can be a reply with success or failure Report Enable message reporting for a proxy service Service Callout Configure a synchronous (blocking) callout to an AquaLogic Service Bus-registered proxy or business service 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 Transport Headers Set the transport header values in messages Validate Validate elements selected by an XPath expression against an XML schema element or a WSDL resource

Edit Stage Configuration

After you configure an action, you are returned to the Edit Stage Configuration page, which you can use to add additional actions, add branch nodes, add error handlers, update actions, and so on, as described in the following steps.

To add another action, click the icon for the previous action, click Add an Action, then select an action. Continue adding actions as necessary. To learn more about the type of action you want to add, see the appropriate procedure in Adding an Action. There is no restriction on what actions may be chained together in your message flow.

When you have finished adding actions, you can further configure the stage by moving the actions in the message flow, deleting or disregarding your changes, and so on, as described in the following table.

Table 16-2 Tasks to Use When you Edit Stage Configuration

To...	Complete This Step...
Delete an action	Click the appropriate icon, then click Delete this Action. The action is deleted.
Move an action down	Click the appropriate icon, then click Move Action Down. The action is moved below the next action contained in this stage. Note: This option is displayed only when there are two or more actions contained in the stage.
Move an action up	Click the appropriate icon, then click Move Action Up. The action is moved above the previous action contained in this stage. Note: This option is displayed only when there are two or more actions contained in the stage.
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 from within this stage	Click the appropriate icon, then click Paste Action. Note: You cannot paste actions across stages; you can only paste actions that are inside the same stage.
Save the updates and return to the Edit Message Flow page	Click Save.
Disregard changes and return to the Edit Message Flow page	Click Cancel.
Clear the unsaved changes and remain on the Edit Stage Configuration page	Click Clear.
Discard your changes and exit the message flow	Click Cancel All. When you confirm that you want to exit the Message Flow, the Summary of Proxy Services page is displayed if you initially clicked the Edit Message Flow icon for the proxy service on that page or the Project View or Folder View pages are displayed if you clicked the Edit Message Flow icon for the proxy service on those pages.

When you complete the configuration in the Edit Stage Configuration page, you are returned to the Edit Message Flow page, on which you can complete the tasks described in the following table.

Table 16-3 Tasks to Use When you Edit Message Flow

To...	Complete This Step...
Add a stage to an existing pipeline	Click the appropriate request or response pipeline, then click Add Stage. To learn more, see Adding a Stage.
Add a pipeline pair node	Click the Proxy Service icon, then click Add Pipeline Pair. Alternatively, click an existing Pipeline Pair Node icon, click Add, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node.
Add a route node	Click the Pipeline Pair Node icon, click Add, then click Add Route Node. To learn more, see Adding a Route Node.
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 you created, then click Paste Route Node. Note: This option is not available if you have not cut or copied a route node.
Add a conditional branch node	Click the Pipeline Pair Node icon, click Add, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node.
Add error handling for this proxy service	Click the Proxy Service icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
Edit the stage name and description	Click the appropriate Stage icon, click Edit, then click Name and Description.
Delete a stage	Click the appropriate Stage icon, then click Delete.
Save the updates and return to the Summary of Proxy Services page	Click Save.
Disregard changes and return to the Summary of Proxy Services page	Click Cancel.
Clear the changes and remain on the Edit Message Flow page	Click Clear.
Discard your changes and exit the message flow	Click Cancel All. When you confirm that you want to exit the Message Flow, the Summary of Proxy Services page is displayed if you initially clicked the Edit Message Flow icon for the proxy service on that page or the Project View or Folder View pages are displayed if you clicked the Edit Message Flow icon for the proxy service on those pages.

Note: When you click Save, the Message Flow is updated in the current session. When you have finished making changes to this configuration, from the left navigation pane, click Activate under Change Center. The session ends and the configuration is saved. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Note: To learn more about actions, see Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide for usage scenarios, design patterns, and best practices.

Update Actions

Update actions include Delete, Rename, Insert, and Replace actions. They are evaluated and executed as follows:

The XPath expression you configure for any update actions is evaluated to select the nodes in the message on which to operate.
In the case of Insert and Replace actions, you configure an XQuery expression, which is evaluated to determine the data to insert or replace.
For each node identified by the evaluation of the XPath expression, the appropriate action on that node is performed. In other words:

Delete the variable or the node in the variable identified by the XPath expression
Rename the node identified by the XPath expression
Replace the node (or the contents of the node) identified by the XPath expression with the value returned by the XQuery expression
Insert the value returned by the XQuery expression before, after, or as a child of the node identified by XPath expression

Assign

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

To configure an Assign action:

Click Add an Action, then select Assign.

The Assign action is displayed, which includes the following functionality:

An Expression link that you can click to edit an XQuery expression
A variable field in which you can enter a context variable

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. To learn more, see Using the Inline XQuery Expression Editor.

When you finish editing the expression, enter a context variable in the variable field. To learn more about context variables, see Message Context. Specifically, see Inbound and Outbound Variables and Constructing Messages to Dispatch.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Delete

Use the Delete action to delete a context variable or all the nodes specified by an XPath expression.The Delete action is one of a set of Update actions. To learn more, see Update Actions.

To configure a Delete action:

Click Add an Action, then select Delete.

The Delete action is displayed. It includes the following functionality:

A Variable field and corresponding radio button
An XPath link (and corresponding radio button) that you can click to edit an XPath expression, and an in variable field to specify the context variable upon which the XPath expression is to be executed.

Assign Action

To delete a context variable, select the radio button associated with this option, then enter the name of a context variable in the Variable field. To learn more about context variables, see Message Context.

Alternatively, to delete all nodes selected by an XPath expression, select the radio button associated with the XPath option, then click XPath. The XPath Expression Editor page is displayed. To learn more, see Using the XPath Expression Editor. After you save the expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

For Each

Use the For Each action to iterate over a sequence of values and execute a block of actions.

To configure a For Each action:

Click Add an Action, then select For Each. The For Each action is displayed.

Figure 16-1 The For Each Action Configuration Options

The For Each Action Configuration Options

Enter variable names in the fields provided, click XPath to open the XPath editor to create an XPath expression, and configure the actions in the Do () loop.

Let us use the values shown in the following figure to describe how the For Each action is executed at run time. Figure 16-2 Example Configuration for For Each Action

The block of actions you define in the Do() loop is executed for each value returned as a result of the evaluation of the XPath expression against the body context variable. A sequence of zero or more values is returned by the evaluation of the XPath expression. In the event that a sequence of zero is returned, the Do() loop is not executed.
Before each iteration, the context variable value points to the next value in the sequence and index is assigned the positional index (from 1 to N to match the XPath indices) of this next value.
The context variable total is initialized once with the total count of values.

Specifying values for the value, index, and total variables, and for the XPath expression is optional. In other words, if they are not specified when you design the action, you can still activate the session.

Note: For information about the scope of the context variables in For Each actions, see Scope of Variables in the For Each Action and Nested For Each Actions.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Scope of Variables in the For Each Action

The value context variable is only visible inside the For Each action—when the For Each action finishes execution (whether it finishes successfully or with an error), the value variable falls out of scope and is removed from the message context. However, when the For Each action finishes execution, the index and total count variables remain in the context with their last known values. If the For Each action finishes successfully, then the index variable and the total count variable both have the same numeric value—the total number of items in the sequence.

If an error occurs when an iteration is in progress, the value of the index variable is smaller than the value of the total count variable. However, note that during the final iteration, index has the same value as total count. So, if an error occurs and the values in index and total are equal, then you can determine only that the error occurred either in the final iteration or after the For Each action finished successfully.

You can modify any of the variables (value, index, or total) in the Do() loop.

Value Variable

Because the values in the sequence returned as a result of executing the XPath are references to the content of the variable on which the XPath is run (body, in the example in the preceding figure), any updates to the value variable performed by actions in the For Each loop are reflected in the content of body. Consequently, you can perform in-place updates that are more complex than those you can perform with the Insert and Update Actions.

For example, a For Each action configured as shown in the following figure iterates over a sequence of line items in a purchase order and increases the cost of each item by 10%.

Figure 16-3 Example of For Each Action Configuration

Example of For Each Action Configuration

Index Variable

At the start of each iteration, the value in the index variable is overwritten with the next index value. In other words, the loop behavior and the number of iterations performed is not affected by any changes that are made in the loop for the value of the index variable.

Total Variable

The total count variable is initialized at the beginning of the For Each action. Consequently, any changes to its value, as a result of actions in the Do() loop, are permanent. However, the loop behavior and the number of iterations performed is not affected by any changes to the value of the total variable.

Nested For Each Actions

You can configure nested For Each actions. When you do so, it is recommand that where possible you use unique variable names. If you reuse the variables in nested For Each actions, be aware of the scope of those variables. As described in the preceding section:

The index and total variables remain in scope when a For Each action completes—therefore the values those variables were assigned in an inner (nested) For Each action become available in the outer For Each action
Because the value variable falls out of scope when a given For Each loop finishes, on exit of an inner For Each loop in a nested scenario, the value variable is set to null

If Then

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

To configure an If Then Action:

Click Add an Action, then select If... Then...

The If... Then... action is displayed. It includes the following functionality:

If ( <Condition> ), which is a link from which you can edit the condition.
An Add an Action option within the then clause

Click Condition. The XQuery Condition Editor page is displayed.

The condition you create is used as the test that is executed before the then() clause is entered, per standard if...then logic. To learn more, see Using the XQuery Condition Editor.

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 an Action.

As your logic requires, click the If...Then... icon to add else-if conditions or else conditions, then click Add an Action to associate actions with these conditions.

Note: Condition actions can be nested. However, there is a nesting limit of 4 cumulative levels in the stage editor. If you attempt to add a 5th 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 action (to the last publish table), it is not displayed.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Insert

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. To learn more, see Update Actions.

To configure an Insert action:

Click Add an Action, then select Insert.

The Insert action is displayed, which includes the following functionality:

An Expression link that you can click 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.
A drop-down list from which you can select the relative location at which to insert the data relative to the nodes specified by the subsequent XPath expression
An XPath link that you can click to edit an XPath expression
A field in which you can specify the context variable—the XPath evaluates the contents of this variable.

Click Expression. The XQuery Expression Editor page is displayed. To learn more, see Using the Inline XQuery Expression Editor.

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.

Click XPath. The XPath Expression Editor page is displayed. To learn more, see Using the XPath Expression Editor.

When you finish editing the XPath expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Note: Valid configurations include those in which:

XQuery and XPath expressions both return elements.
The XPath expression does not return elements—in which case, the XQuery expression must return attributes.

Log

Use the Log action to construct a message to be logged and to define a set of attributes with which the message is logged. This topic includes the following sections:

Understanding Log Actions

The Log action allows you to log one or more log messages to the WebLogic Server log each time the stage is executed within a proxy service. One or more instances of a log action can be configured in a message flow.

The contents of the log message can consist of one or more of:

Part(s) of the message context with which a stage is executed—The parts of the message context to be logged are specified through XQuery expressions on context variables.
User-defined text that you want to log.

AquaLogic Service Bus uses the non catalog logger APIs to write messages to the WebLogic Server log. The AquaLogic Service Bus Console does not replicate logging configuration functionality provided by the WebLogic Server Administration Console. If you need specific log file configuration, like those described in the following listing, do the configuration through the WebLogic Server Administration Console:

Specifying the location of the server and domain log files
Specifying which severity levels cause messages to be written to the log files
Specifying the severity levels of messages that will be forwarded from the server logs to the domain log

For information about logging in WebLogic Server, see Configuring Log Files and Filtering Log Messages in the WebLogic Server documentation.

Configuring Log Actions

To configure a Log action:

Click Add an Action, then select Log.

The Log action is displayed, which includes the following functionality:

An Expression link, which you can click to edit an XQuery expression
An Annotation field in which you can enter notes for this log action. These notes are logged along with the result of the previously defined expression
A severity level drop-down list in which you can select the logging level

Click Expression. The XQuery Expression Editor page is displayed. You specify the message context to be logged through XQuery expressions on context variables. To learn more, see Using the Inline XQuery Expression Editor.

In the Annotation field, enter notes for this log action.

In the severity level drop-down list, select one of the options.

Table 16-4 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.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Publish

Use a Publish action to identify a target service for a message and configure how the message is packaged and sent to that service.This topic includes the following sections:

Understanding Publish Actions

The following quality of service and scope of the message context information applies to Publish actions and Publish Table actions.

Quality of Service

When a message is published to another service as the result of a Publish or Publish Table action, the default quality of service (QoS) is best effort, if the proxy service inbound transport and the outbound publish action use the JMS/XA transport. Best effort meaning that there is no reliable messaging and there is no elimination of duplicate messages—however, performance is optimized. To override the default best effort quality of service attribute, you must set the qualityOfService in the outbound message context variable ($outbound). For more information, see Message Context. For information about exactly once reliability, see Adding a Route Node.

For more information about quality of service, see Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide.

Scope of the Message Context

Each publish request transformation maintains its own local copy of message context. The changes to the predefined context variables in the publish request actions are isolated to that publish endpoint and do not affect subsequent processing by the message flow.

For the purposes of instruction, the following questions about working with the message context in publish actions are asked and answered considering an example scenario in which AquaLogic Service Bus receives a SOAP message with attachments (3 parts: SOAP, text, binary).

Are the Changes I Make to the Message Content Using the Request Actions Within a Publish Action Preserved in Subsequent Nodes in the Message Flow?

No. Any changes you make to an outbound message in a publish action only affect the published message. In other words, the changes you make in the publish action are rolled back before the message flow proceeds to any nodes that follow the stage that contains the publish action in your message flow.

An exception to this rule occurs in the case that you configure a Reply action as one of the Publish request actions. In this case, the message content is not rolled back. In other words the message that was sent as the published message is the one returned to the client as a result of the Reply action being executed. For example, for a case in which the sequence of actions configured in a stage are Assign and Reply as follows:

Stage: publish to someservice

Request Actions:
Assign message_x to body Reply with Success

When this stage is executed at run time, the client receives message_x in the reply message.

What is Written if I Publish the Message Using a File Transport?

The nature of the message written to the file system depends on the type of your outbound service:

In the case of SOAP services, the full multipart MIME message is written with the SOAP envelope (<soap:Envelope>) as the root part. (For more information, see SOAP Services.)
In the case of XML services and messaging services, the full multipart MIME message is written with the contents of $body as the root part. (For more information, see XML Services (Non SOAP) and Messaging Services.)

How Do I Publish Only the Binary Part of the Message?

You must copy the binary part into the message body. You can do so in one of the following ways:

Create an outbound transformation and assign the following XQuery to the body variable ($body):

$attachments/ctx:attachment[2]/ctx:body/*

Use a Replace action to replace the contents of $body with the binary part of the attachments:

$attachments/ctx:attachment[2]/ctx:body/*

Delete the content of the attachments context variable. To do so, configure a Delete action using the XPath in variable option, where

./* specifies the XPath
attachments is the variable

Must I Set the Transport Headers if I Want to Publish Using the HTTP Transport?

You need not set any transport headers. The Content-Type is set automatically according to the service type. For more information, see Initializing the attachments Context Variable.

Configuring Publish Actions

To configure a Publish action:

Click Add an Action, then select Publish.

The Publish action is displayed, which includes the following functionality:

A Service link that you can click to select a service to which you want to publish a message
A table in which you can add request actions

Click Service. The Service Browser is displayed.

Select a service from the list, then click Submit. The service is displayed instead of the default link. This is the target service for the message.

In the Request Actions field, to configure how the message is packaged and sent to the service, click 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 types of actions you want to add, see Adding an Action.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Raise Error

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

To configure a Raise Error action:

Click Add an Action, then select Raise Error.

The Raise Error action is displayed. It includes the following functionality:

An error code field in which you must enter the error code
An error message field in which you can enter a description of the error

In the error code field, enter the error code you want to raise.

In the error message field, enter a description of the error code.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Rename

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. To learn more, see Update Actions.

To configure a Rename action:

Click Add an Action, then select Rename.

The Rename action is displayed. It includes the following functionality:

An XPath link that you can click to edit an XPath expression
A field in which to identify the variable that holds the element you want to rename
localname, namespace, and combined localname and namespace radio buttons and fields

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. The XPath expression must select elements, not attributes.

To learn more, see Using the XPath Expression Editor.

Enter a context variable in the in variable field. To learn more about context variables, see Message Context..

Do one of the following:

To rename selected elements using a localname, select the radio button associated with this option, then enter a localname in the localname field.
To rename selected elements using a namespace, select the radio button associated with this option, then enter a namespace in the namespace field.
To rename selected elements using a localname and namespace, select the radio button associated with this option, then enter a localname and namespace in the localname and namespace fields.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Replace

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 or elements (XQuery expressions cannot return attributes). If the XPath identifies attributes, then the XQuery expression must evaluate to a simple value. An XQuery expression that returns nothing is equivalent to making the identified nodes empty or deleting the identified attributes.

The Replace action is one of a set of Update actions. To learn more, see Update Actions.

To configure a Replace action:

Click Add an Action, then select Replace.

The Replace action is displayed, which includes the following functionality:

An XPath link that you can click to edit an XPath expression
An Expression link that you can click to edit an XQuery expression
A field in which to identify the variable that holds the element you want to replace
Radio buttons that allow you to specify whether to replace a node or the contents of a node with the value returned by the XQuery expression

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. To learn more, see Using the XPath Expression Editor.

When you finish editing the XPath expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context.

Click Expression. The XQuery Expression Editor page is displayed. The XQuery expression is used to create the data that replaces the data specificed by the XPath in the named variable.To learn more, see Using the Inline XQuery Expression Editor.

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 ./*

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Reply

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 failure for SOAP services, a HTTP 500 error is returned. The Reply action specifies that an immediate reply is sent to the invoker.

To configure a Reply action:

Click Add an Action, then select Reply.

The Reply action is displayed, which includes the following functionality:

With Success and With Failure options

Select the With Success radio button to reply that the message was successful or select the With Failure radio button to reply that the message has a fault.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Report

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

AquaLogic Service Bus provides the capability to deliver message data and alerts to one or more reporting providers. Message data can be captured from the body of the message or from any other variables associated with the message, such as header or inbound variables. Alert data contains information about Service Level Agreement (SLA) violations or occurrences that you can configure to monitor proxy services. You can use the message or alert data delivered to the reporting provider for functions such as tracking messages or regulatory auditing.

To receive report messages from either the AquaLogic Service Bus JMS Reporting Provider or a user-defined reporting provider, you must first create a Report action in the message flow for the proxy service. The Report action allows you to extract information from each message and write it to the Reporting Data Stream.

You need not configure a report action for alert reporting. Alert data is always available in the Reporting Data Stream.

To configure a Report action:

Click Add an Action, then select Report.

The Report action is displayed. It includes the following functionality:

An Expression link that you can click to edit an XQuery expression
A field in which you can add name and value pairs (key names and key values)

Click Expression. The XQuery Expression Editor page is displayed. To learn more, see Using the Inline XQuery Expression Editor. The XQuery expression is used to create the data that will be reported to the AquaLogic Service Bus dashboard.

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.

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. To learn more, see Listing and Locating Messages and Viewing Message Details.

Enter a key name in the Key Name field.

Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Using the XPath Expression Editor.

Enter a context variable in the in variable field. To learn about context variables, see Message Context.

To add more key values, click the Key icon, then select Add a Key. To delete a key, you can click the Key icon, then select Delete this Key.

For an example of a Report Action configuration and the data reported on the AquaLogic Service Bus dashboard, see Example Report Action Configuration and Resulting Reporting Data.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Example Report Action Configuration and Resulting Reporting Data

Let us take an example in which we configure a Report action on an error handler in a stage. The goal is to report the contents of the fault context variable in the event of an error—we configure the Report action as shown in the following figure.

Figure 16-4 Example Key Name, Key Value Configuration

Example Key Name, Key Value Configuration

Where errorCode is the key name, and the key value is extracted from the fault variable using the following XPath: ./ctx:errorCode

Each time this Report action is executed at run time, a message is reported via the Reporting Data Stream. The following figure shows the Message Report Summary page in the AquaLogic Service Bus Console after the Report action configured with the key and value pair described in Figure 16-4 is executed twice.

Figure 16-5 Run Time Results of Executing Report Action

Run Time Results of Executing Report Action

Resume

The Resume action is used in error handlers. At run time, this action causes the message flow processing to continue as though no error has occurred. Processing continues after the node or stage in which the error handler is configured. You may need to configure the error handler with compensating logic to set the context variables and message state to correspond with the variable and message state expected by subsequent message flow logic.Configure the compensating logic prior to the Resume action.

This action has no parameters and can only be used in error pipelines. To create a Resume action for your message flow:

Click Add an Action, then select Resume. The Resume icon is displayed.

Continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Service Callout

Use a Service Callout action to configure a synchronous (blocking) call to a proxy or business service that is already registered with AquaLogic Service Bus. This topic includes the following sections:

Understanding Service Callout Actions

Service Callouts allow you to make a callout from a proxy service to another service. Input parameters for the called service are constructed from the proxy service message context and outputs from the called service are mapped back to the message context. A service to which call outs are made must have the following characteristics:

All AquaLogic Service Bus service types are supported:

WSDL-based services

Only SOAP document-style, XML (HTTP binding with mime:mimeXml body) and SOAP RPC-style (SOAP 1.1) Web services are supported. SOAP RPC/literal is supported and SOAP RPC/encoded is interpreted as SOAP RPC/literal.
Attachments are not supported.
Note: The endpoint URI for the service to which the callout is being made can be the same as the URI specified by the soap:address element in the WSDL, but it can be a different URI.

Messaging services (text/binary/XML and MFL)

Attachments are not supported

Any XML
Any SOAP

Service transport types can be HTTP, HTTPS or JMS.
For services with HTTP and HTTPS transport types, the request method must be POST, not GET.
The Service Callout operations must be request/response—that is, one-way operations are not supported.

The outbound request uses the AquaLogic Service Bus binding layer to achieve the correct construction of the request payload, based on the service type. Also, WS-Security is supported through the binding layer.

Service Callouts with a JMS transport type are supported only for request/response services with quality-of-service of best effort. In other words, the enqueueing of a message to the JMS service is not done in the same transaction as that used to invoke the proxy service.
For WSDL-based services, you can specify SOAP headers for callout requests and have the SOAP headers on the response, if any, bound to a pipeline variable.
You can specify the set of transport headers for the callout request.

Note About Transport Headers

In addition to any transport headers you specify when configuring the Service Callout action, the following headers are automatically added by the AquaLogic Service Bus binding layer:

Content-Type = text/xml + charset for HTTP/HTTPS services

The charset parameter will be set according to the configuration of the business service.
If you specify a value for the Content-Type transport header when you configure the Service Callout action, the value you specify will be used, not the default text/xml value.

SOAPAction for SOAP document-style or SOAP RPC style HTTP/HTTPS services

Only if present in SOAP Binding operation section of the WSDL.

Configuring Service Callout Actions

Populate the context by specifying a service and operation, and enter context variables to bind to the invocation input and output parameters:

Click Add an Action, then select Service Callout.

The Service Callout action is displayed. It includes a Service link that you can click to select a service.

Click Service. The Service Browser is displayed.

Select a service from the list of already registered proxy or business services, then click Submit.

The name of the service you selected is now displayed on the stage configuration page. The subsequent configuration options depend on whether your service is WSDL-based or not:

When the Service is Based on a WSDL

Select the operation name to be invoked on a service.

In the Request Parameters fields, enter the names of the variables that will be evaluated at run time to provide values for the request parameters.

Warning: You provide only the core payload documents in the input variable—the SOAP package is created for you by AquaLogic 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 following XPath: 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 variable to which the responses will be assigned at run time.

Optionally, you can specify

A variable (in the SOAP Request Header field) that holds the XML of the SOAP Header element for the callout request

Warning: You must wrap the input document for the SOAP Request Header with <soap-env:Header>...</soap-env:Header>.

A variable (in the SOAP Response Header field) to which the XML of the SOAP Headers on the response, if any, are bound.

Service Callout Action

Complete the following steps for each transport header you want to add (header values you specify are added to the message going to the callout service):

In the Transport Headers table, click Add Header. The first row in the Transport Headers table is populated as shown in the following figure.

service callout action configuration

Specify a header either by selecting from the drop-down list pre populated with headers specific to the transport of the target service or by entering a header name in the field provided.

The drop-down list is populated with all of the predefined header names for the target transport (for example, Content-Type for HTTP transports, JMSCorrelationID for JMS transports, and so on). If you enter a header name in the Other field, and 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.

Click <Expression> in Set Header to <Expression> to invoke the XQuery or XSLT expression editior, which you can use 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 AquaLogic 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: Not all of the transport headers and metadata that you can specify in this action are honored at run time. That is, the values of certain headers and metadata can be overwritten, or ignored by the AquaLogic Service Bus run time. For information about which headers and metadata for a given transport you can set, and which of those set are honored at run time, see Understanding How the Run Time Uses the Transport Headers' Settings.

To add additional Headers to the table, click Add Header.

Add Header

Note: In addition to the transport headers you specify, headers are added by the AquaLogic Service Bus binding layer. For more information, see Note About Transport Headers.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

For examples that show how variables and message context is used for Service Callouts, see How are Messages Constructed for Service Callouts?

When the Service is Not Based on a WSDL

In the Request Document Variable field, enter the name of the variable to which a request document is assigned.

The variable is evaluated at run time to construct the body of the SOAP message sent to the service (in the case of SOAP Document-style services), or the body of the XML message sent in the case of Any XML service types.

Warning: You provide only the core payload documents in the input variable—the SOAP package is created for you by AquaLogic 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 following XPath: body/* (to remove the wrapper soap-env:Body), not $body (which results in keeping the soap-env:Body wrapper).

The following restrictions apply to the variables in the case of 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 is assigned.

In the case that the Service Callout is to an Any SOAP service type, you can specify

A variable (in the SOAP Request Header field) that holds the XML of the SOAP Header element for the callout request

Warning: You must wrap the input document for the SOAP Request Header with <soap-env:Header>...</soap-env:Header>.

A variable (in the SOAP Response Header field) to which the XML of the SOAP Headers on the response, if any, are bound.

Add Header

Complete the following steps for each transport header you want to add (header values you specify are added to the message going to the callout service):

In the Transport Headers table, click Add Header. The first row in the Transport Headers table is populated as shown in the following figure.

any xml service callout configuration

Specify a header either by selecting from the drop-down list pre populated with headers specific to the transport of the target service or by entering a header name in the field provided.

The drop-down list is populated with all of the predefined header names for the target transport (for example, Content-Type for HTTP transports, JMSCorrelationID for JMS transports, and so on). If you enter a header name in the Other field, and 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.

Because the AquaLogic 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: Not all of the transport headers and metadata that you can specify in this action are honored at run time. That is, the values of certain headers and metadata can be overwritten, or ignored by the AquaLogic Service Bus run time. For information about which headers and metadata for a given transport you can set, and which of those set are honored at run time, see Understanding How the Run Time Uses the Transport Headers' Settings.

To add additional Headers to the table, click Add Header.

Add Header

Note: In addition to the transport headers you specify, headers are added by the AquaLogic Service Bus binding layer. For more information, see Note About Transport Headers.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

For examples that show how variables and message context is used for Service Callouts, see How are Messages Constructed for Service Callouts?

How are Messages Constructed for Service Callouts?

When AquaLogic Service Bus makes a call to a service via a Service Callout action, the content of the message is constructed using the values of variables in the message context. The message content for outbound messages is handled differently depending upon the type of the target service. How the message content is created depends on the type of the target service, as described in the following topics:

SOAP Document Style Services

In the case of SOAP Document Style services:

The variable assigned for the request document contains the SOAP body.
The variable assigned for the SOAP Request Header contains the SOAP Header.
The response must be a single XML document—it is the content of the SOAP Body plus the SOAP Header (if specified)

To illustrate how messages are constructed during callouts to SOAP Document Style services, take for example a Service Callout action configured as shown in the following figure.

Figure 16-6 Service Callout Action Configuration for a SOAP Document Style Service

Service Callout Action Configuration for a SOAP Document Style Service

Assume also that at run time, the request document variable, myreq, is bound to the following XML.

Listing 16-1 Content of Request Variable (myreq)

<sayHello xmlns="http://www.openuri.org/">
    <intVal>100</intVal>
    <string>Hello AquaLogic</string>
</sayHello>

At run time, the SOAP Request Header variable, reqheader, is bound to the following SOAP header.

Listing 16-2 Content of SOAP Request Header Variable (reqheader)

<soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing">
    <wsa:Action>...</wsa:Action>
    <wsa:To>...</wsa:To>
    <wsa:From>...</wsa:From>
    <wsa:ReplyTo>...</wsa:ReplyTo>
    <wsa:FaultTo>...</wsa:FaultTo>
  </soap:Header>

In this example scenario, the full body of the message sent to the external service is as shown in the following listing (the contents of the myreq and reqheader variables are shown in bold).

Listing 16-3 Message Sent to the Service as a Result of Service Callout Action

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header xmlns:soap=http://schemas.xmlsoap.org/soap/envelope/
    xmlns:wsa="http://schemas.xmlsoap.org/ws/2003/03/addressing">
        <wsa:Action>...</wsa:Action>
        <wsa:To>...</wsa:To>
        <wsa:From>...</wsa:From>
        <wsa:ReplyTo>...</wsa:ReplyTo>
        <wsa:FaultTo>...</wsa:FaultTo>
    </soap:Header>
    <soapenv:Body>
        <sayHello xmlns="http://www.openuri.org/">
            <intVal>100</intVal>
            <string>Hello AquaLogic</string>
        </sayHello>
    </soapenv:Body>
</soapenv:Envelope>

Based on the configuration of the Service Callout action illustrated in the Figure 16-6, the response from the service is assigned to the myresp variable. The full response from the external service is as shown in the following listing.

Listing 16-4 Response Message From the Service as a Result of Service Callout Action

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.
org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <env:Header/>
    <env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <m:sayHelloResponse xmlns:m="http://www.openuri.org/">
            <result xsi:type="xsd:string">This message brought to you by Hello AquaLogic and the number 100
            </result>
        </m:sayHelloResponse>
    </env:Body>
</env:Envelope>

In this scenario, the myresp variable is assigned the value shown in the following listing.

Listing 16-5 Content of Response Variable (myresp) as a Result of Service Callout Action

<m:sayHelloResponse xmlns:m="http://www.openuri.org/">
    <result ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-instance">
This message brought to you by Hello AquaLogic and the number 100
    </result>
</m:sayHelloResponse>

XML Services

In the case of XML services:

The request message is the content of the variable assigned for the request document.
The content of the request variable must be a single XML document.
The output document is the response message

To illustrate how messages are constructed during callouts to XML services, take for example a Service Callout action configured as shown in the following figure.

Figure 16-7 Service Callout Action Configuration for an XML Service

Service Callout Action Configuration for an XML Service

Assume also that at run time, the request document variable, myreq, is bound to the following XML.

Listing 16-6 Content of myreq Variable

<sayHello xmlns="http://www.openuri.org/">
    <intVal>100</intVal>
    <string>Hello AquaLogic</string>
</sayHello>

In this scenario:

The outbound message payload is the value of the myreq variable, as shown in the preceding listing.
The response and the value assigned to the message context variable, myresp, is shown in the following listing.

Listing 16-7 Content of myresp Variable

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <env:Header/>
    <env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <m:sayHelloResponse xmlns:m="http://www.openuri.org/">
            <result xsi:type="xsd:string">This message brought to you by Hello AquaLogic and the number 100
            </result>
        </m:sayHelloResponse>
    </env:Body>
</env:Envelope>

SOAP RPC Style Services

In the case of SOAP RPC Style services:

Request messages are assembled from message context variables using XQuery.

The SOAP Body is built based on the SOAP RPC format (operation wrapper, parameter wrappers, and so on).
The SOAP Header is the content of the variable specified for the SOAP Request Header, if one is specified.
Part as element—the parameter value is the variable content.
Part as simple type—the parameter value is the string representation of the variable content.
Part as complex type—the parameter corresponds to renaming the root of the variable content after the parameter name.

Response messages are assembled as follows:

The output content is the content of SOAP Header, if a SOAP Header is specified.
Part as element—the output content is the child element of the parameter; there is at most one child element.
Part as simple/complex type—the output content is the parameter itself

To illustrate how messages are constructed during callouts to SOAP RPC Style services, take an example with the following configuration:

A message context variable input1 bound to a value 100
A message context variable input2 bound to a string value: Hello AquaLogic.
A Service Callout action configured as shown in the following figure.

Figure 16-8 Service Callout Action Configuration for a RPC Style Service

Service Callout Action Configuration for a RPC Style Service

In this scenario, the body of the outbound message to the service is shown in the following listing.

Listing 16-8 Content of Outbound Message

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <sayHello2 xmlns="http://www.openuri.org/">
            <intVal>100</intVal>
            <string >Hello AquaLogic</string>
        </sayHello2>
    </soapenv:Body>
</soapenv:Envelope>

The response returned by the service to which the call was made is shown in the following listing.

Listing 16-9 Content of Response Message From the helloWorld Service

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <env:Header/>
    <env:Body env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <m:sayHello2Response xmlns:m="http://www.openuri.org/">
            <result xsi:type="n1:HelloWorldResult" xmlns:n1="java:">
                <message xsi:type="xsd:string">
                This message brought to you by Hello AquaLogic and the number 100
                </message>
            </result>
        </m:sayHello2Response>
    </env:Body>
</env:Envelope>

The message context variable output1 is assigned the value shown in the following listing.

Listing 16-10 Content of Output Variable (output1)

<message ns0:type="xsd:string" xmlns:ns0="http://www.w3.org/2001/XMLSchema-intance">
This message brought to you by Hello AquaLogic and the number 100</message>

Messaging Services

In the case of Messaging services:

The request message is the content of the request variable. The content can be simple text, XML, or binary data represented by an instance of <binary-content ref=.../> reference XML.
Response messages are treated as binary, so the response variable will contain an instance of <binary-content ref= ... /> reference XML, regardless of the actual content received.

For example, if the request message context variable myreq is bound to an XML document of the following format: <hello>there</hello>, the outbound message contains exactly this payload. The response message context variable (myresp) is bound to a reference element similar to the following:

<binary-content ref=" cid:1850733759955566502-2ca29e5c.1079b180f61.-7fd8"/>

Handling Errors

You can configure error handling at the Message Flow, pipeline, route node, and stage level. For information about doing so, see Error Messages and Handling. The types of errors that are received from an external service as the result of a Service Callout include transport errors, SOAP faults, responses that do not conform to an expected response, and so on.

The fault context variable is set differently for each type of error returned. You can build your business and error handling logic based on the content of the fault variable. To learn more about $fault, see Fault Variable and Error Codes.

Transport Errors

When a transport error is received from an external service and there is no error response payload returned to AquaLogic Service Bus by the transport provider (for example, in the case that an HTTP 403 error code is returned), the Service Callout action throws an exception, which in turn causes the pipeline to raise an error. The fault variable in a user-configured error handler is bound to a message formatted similarly to that shown in the following listing.

Listing 16-11 Contents of the AquaLogic Service Bus fault Variable—Transport Error, no Error Response Payload

<con:fault xmlns:con="http://www.bea.com/wli/sb/context">
  <con:errorCode>BEA-380000</con:errorCode>
  <con:reason>Not Found</con:reason>
   <con:details>
   ....... 
   </con:details>
    <con:location>
       <con:node>PipelinePairNode1</con:node>
       <con:pipeline>PipelinePairNode1_request</con:pipeline>
    <con:stage>stage1</con:stage>
    </con:location>
</con:fault>

In the case that there is a payload associated with the transport error—for example, when an HTTP 500 error code is received from the business service and there is XML payload in the response—a message context fault is generated with the custom error code: BEA-382502.

The following conditions must be met for a BEA-382502 error response code to be triggered as the result of a response from a service—when that service uses an HTTP or JMS transport:

(HTTP) The response code must be any code other than 200 or 202
(JMS) The response must have a property set to indicate that it is an error response—the transport metadata status code set to1 indicates an error.
The content type must be text/xml
If the service is AnySoap or WSDL-based SOAP, then it must have a SOAP envelope. The body inside the SOAP envelope must be XML format; it cannot be text.
If the service type is AnyXML, or a messaging service of type text returns XML content with a non-successful response code (any code other than 200 or 202).

The ErrorResponseDetail element in the fault contains error response payload received from the service. The following listing shows an example of the ErrorResponseDetail element.

Listing 16-12 Contents of the AquaLogic Service Bus fault Variable—Transport Error, with Error Response Payload

<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context">
    <ctx:errorCode>BEA-382502<ctx:errorCode>
    <ctx:reason> Service callout has received an error response from the server</ctx:reason>
    <ctx:details>
        <alsb:ErrorResponseDetail xmlns:alsb="http://www.bea.com/...">
            <alsb:detail> <![CDATA[
                . . . 
	]]>
            </alsb:detail> 
        </alsb:ReceivedFault>
    </ctx:details>
    <ctx:location>. . .</ctx:location>
</ctx:Fault>

Note: The XML Schema for the Service Callout-generated fault is shown in XML Schema for the Service Callout-Generated Fault Details.

SOAP Faults

In case an external service returns a SOAP fault, the AquaLogic Service Bus run time sets up the context variable $fault with a custom error code and description with the details of the fault. To do so, the contents of the 3 elements under the <SOAP-ENV:Fault> element in the SOAP fault are extracted and used to construct an AquaLogic Service Bus fault element.

Take for example a scenario in which a service returns the following error.

Listing 16-13 SOAP Fault Returned From Service Callout

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> 
  <SOAP-ENV:Body> 
    <SOAP-ENV:Fault> 
      <faultcode>SOAP-ENV:Client</faultcode> 
      <faultstring>Application Error</faultstring> 
      <detail> 
        <message>That's an Error!</message> 
        <errorcode>1006</errorcode> 
      </detail> 
    </SOAP-ENV:Fault> 
  </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

The <faultcode>, <faultstring>, and <detail> elements are extracted and wrapped in an <alsb:ReceivedFault> element. Note that the faultcode element in Listing 16-13 contains a QName—any related namespace declarations are preserved.

The generated <alsb:ReceivedFault> element, along with the custom error code and the error string are used to construct the contents of the fault context variable, which in this example takes a format similar to that shown in the following listing.

Listing 16-14 Contents of the AquaLogic Service Bus fault Variable—SOAP Fault

<ctx:Fault xmlns:ctx="http://www.bea.com/wli/sb/context"> <ctx:errorCode>BEA-382500<ctx:errorCode> <ctx:reason> service callout received a soap Fault response</ctx:reason> <ctx:details> <alsb:ReceivedFault xmlns:alsb="http://www.bea.com/..."> <alsb:faultcode xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">SOAP-ENV:Clien </alsb:faultcode> <alsb:faultstring>Application Error</alsb:faultstring> <alsb:detail> <message>That's an Error!</message> <errorcode>1006</errorcode> </alsb:detail> </alsb:ReceivedFault> </ctx:details> <ctx:location> </ctx:location> </ctx:Fault>

Note: The unique error code BEA-382500 is reserved for the case when Service Callout actions receive SOAP Fault responses.

Unexpected Responses

When a service returns a response message that is not what the proxy service's run time expects, a message context fault will be generated and initialized with the custom error code BEA-382501. The details of the fault include the contents of the SOAP-Body element of the response.

The XML Schema for the Service Callout-generated fault is shown in Listing 16-15.

XML Schema for the Service Callout-Generated Fault Details

The XML schema definition of thje service callout-generated fault datails is shown in the following listing.

Listing 16-15 XML Schema for the Service Callout-Generated Fault Details

<xs:complexType name="ReceivedFaultDetail">
        <xs:sequence>
            <xs:element name="faultcode" type="xs:QName"/>
            <xs:element name="faultstring" type="xs:string"/>
            <xs:element name="detail" minOccurs="0" >
               <xs:complexType>
                 <xs:sequence>
                        <xs:any namespace="##any" minOccurs="0" maxOccurs="unbounded" processContents="lax" /> 
                 </xs:sequence>
        <xs:anyAttribute namespace="##any" processContents="lax" /> 
               </xs:complexType>
            </xs:element>
        </xs:sequence>
</xs:complexType>

<xs:complexType name="UnrecognizedResponseDetail">
        <xs:sequence>
            <xs:element name="detail" minOccurs="0" type="xs:string" />
        </xs:sequence>
</xs:complexType>

<xs:complexType name="ErrorResponseDetail">
        <xs:sequence>
            <xs:element name="detail" minOccurs="0" type="xs:string" />
        </xs:sequence>
</xs:complexType>

Comparing Service Callout Actions and Route Nodes

How does a Service Callout action differ from a Route Node at run time?

The different behavior of the actions configured on a Route node and the Service Callout actions at run time are primarily as follows:

A Service Callout action is synchronous. At run time, it results in the message flow blocking waiting for a response from the callout before proceeding.

Messages are sent asynchronously from Route nodes. At run time, the message flow does not block waiting for a response.

Service Callout actions have no transactional semantics.

Routing configured on Route nodes exhibit transactional semantics.

Skip

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 fault pipelines. To create a Skip action for your message flow:

Click Add an Action, then select Skip. The Skip icon is displayed.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Transport Headers

Use a Transport Header action to easily set the header values in messages.

The Transport Header action allows you to set header values for outbound requests (the messages sent out by a proxy service in Route or Publish actions) and inbound responses (the response messages a proxy service sends back to clients). This specifies to the run time which of the message context locations are to be modified.

After you specify the header set to be modified, you configure the header values. You set the header values as an unordered table of name and value pairs. The run time declares namespaces and places header elements in their proper order when generating the corresponding XML

To configure a Transport Headers action:

Click Add an Action, then select Transport Header. The Transport Header action is displayed.

Figure 16-9 Transport Header Action Configuration—Outbound Request, Inbound Response

Transport Header Action Configuration—Outbound Request, Inbound Response

From the drop-down menu, choose either Outbound Request or Inbound Response.

This is a required field and specifies to the run time whether the header values are to be set for outbound requests (the messages sent out by a proxy service in Route or Publish actions) and inbound responses (the response messages a proxy service sends back to clients).
Selecting Outbound Request or Inbound Response when you configure the Transport Headers action specifies to the run time which of the message context locations are to be modified—these header elements are located in the message context as follows:

For outbound requests—$outbound/ctx:transport/ctx:request/tp:headers
For responses to clients—$inbound/ctx:transport/ctx:response/tp:headers

Figure 16-10 Inbound/Outbound Request, Inbound/Outbound Response

Inbound/Outbound Request, Inbound/Outbound Response

Optionally, select Pass all Headers through Pipeline.

When you select this option, the Transport Headers action will automatically 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.
For information about using this option in conjunction with the header-specific pass through option, see About the Global Pass Through and Header-Specific Copy Options.

Complete the following steps for each Header you want to add:

In the Transport Headers table, click Add Header. The first row in the Transport Headers table is populated as shown in the following figure.

Figure 16-11 Individual Transport Header Action Configuration Options

Individual Transport Header Action Configuration Options

Specify a header either by selecting from the drop-down list pre populated with headers specific to the transport of the target service or by entering a header name in the field provided.

The drop-down list is populated with all of the predefined header names for the target transport (for example, Content-Type for HTTP transports, JMSCorrelationID for JMS transports, and so on). If you enter a header name in the Other field, and 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.

From the options provided in the Action section, specify how to set the headers value:

Set Header to Expression
Selecting this option allows you to use and 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 AquaLogic 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: 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 Understanding How the Run Time Uses the Transport Headers' Settings.
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—see Figure 16-10)
or
Copy Header from Outbound Response (if you are setting transport headers for the Inbound Response—see Figure 16-10)
Specify 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.
In the event that 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. In other words, this Copy Header ... option copies only headers that are present in the source to the target.
For information about using this option in conjunction with the global Pass all Headers through Pipeline option, see About the Global Pass Through and Header-Specific Copy Options.

To add additional Headers to the table, click Add Header.

Add Header

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.
The preceding figure displays a Transport Headers table with two headers; a different action is specified for each header. You can add as many headers as necessary to this table and remove headers from the table using the delete option associated with that header row in the table. You need not 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.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

About the Global Pass Through and Header-Specific Copy Options

As described in the preceding section, the following options are available when you configure a Transport Headers action:

Pass all Headers through Pipeline
Copy Header from Inbound Request or
Copy Header from Outbound Response

Warning: Because transport headers are specific to the transport types, it is recommended that the pass-through (or copy) options only be used to copy headers between services of the same transport type. Passing (or copying) headers between services of different transport types can result in an error if the header being passed is not accepted by the target transport. For the same reasons, be careful when you specify a header name using the Set Header option.

Selecting Pass all Headers through Pipeline specifies that at run time, the Transport Headers action passes all headers through from the inbound message to the outbound message or vice versa. Every header in the source set of headers is copied to the target header set, overwriting any existing values in the target header set.

Selecting a Copy Header option specifies that at run time, the Transport Headers action copies the specific header with which this option is associated from the inbound message to the outbound message or vice versa.

Use the options in a way that best suits your scenario. Both options result in the headers in the source header set being copied to the target header set, overwriting any existing value in the target set. Note that the Pass all Headers through Pipeline option is executed before the header-specific Copy Header options. In other words, for a given Transport Headers action configuration, if you select Pass all Headers through Pipeline, there is no need to select the Copy Header option for given headers.

However, you can select Pass all Headers through Pipeline to copy all headers, and subsequently configure the action such that individual headers are deleted by selecting Delete Header for specific headers.

Understanding How the Run Time Uses the Transport Headers' Settings

The preceding topics describe how the values of the transport headers for outbound requests (the messages sent out by a proxy service in Route or Publish actions) and inbound responses (the response messages a proxy service sends back to clients) can be configured for Transport Headers actions. In general, the header values can be:

Specified using an XQuery expression
Passed through from the source to the target service
Deleted while going from the source to the target service

The Transport Headers action allows you to set, delete or pass-through the headers in $inbound or $outbound. If you set or delete these header and then log $inbound or $outbound, you can see the effects of your changes. However, when the message is sent out, the AquaLogic Service Bus binding layer may modify or remove some headers in $inbound or $outbound and the underlying transport may in turn, ignore some of these headers and use its own values. An important distinction is that any modifications done by the binding layer on a header are done directly to $inbound and $outbound, whereas modifications done by the transport affects only the message's wire format. For example, although you can specify a value for the outbound Content-Length header, the binding layer deletes it from $outbound when sending the message. Consequently, the modification is visible in the response path (for example, you can see the modified value if you log $outbound). If you set the User-Agent header in $outbound, the HTTP transport ignores it and use its own value—however, the value in $outbound is not changed.

The following table describes the transport headers that are ignored or overwritten at run time and other limitations that exist for specific transport headers.

Table 16-5 Limitations to Transport Header Values You Specify in Transport Header Actions

Transport	Description of Limitation . . .	Transport Headers Affected By Limitation . . .
Transport	Description of Limitation . . .	Outbound Request	Inbound Response
HTTP(S)	The AquaLogic Service Bus run time may overwrite these headers in the binding layer when preparing the message for dispatch. If these headers are modified, `$inbound` and `$outbound` are updated accordingly.	Content-Length Content-Type	Content-Length Content-Type
	The underlying transport may ignore these headers and use different values when sending the message. Any changes done by the transport will not be reflected in `$inbound` or `$outbound.`	Accept Content-Length .Connection Host User-Agent	Content-Length Date Transfer-Encoding
JMS	Can only be set when the request is with respect to a one-way service. These headers are overwritten at run time if sending to a request/response service¹.	JMSCorrelationID	JMSCorrelationID
	Should be set to the message time-to-live in milliseconds. The resulting value in the message received is the sum of the time-to-live value specified by the client and the GMT at the time of the send or publish².	JMSExpiration	JMSExpiration
	The AquaLogic Service Bus run time sets these headers. In other words, any specifications you make for these headers at design time are overwritten at run time.	JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount JMSXUserID JMS_IBM_PutDate³ JMS_IBM_PutTime 3 JMS_IBM_PutApplType 3 JMS_IBM_Encoding 3 JMS_IBM_Character_Set 3	JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount JMSXUserID JMS_IBM_PutDate 3 JMS_IBM_PutTime 3 JMS_IBM_PutApplType 3 JMS_IBM_Encoding 3 JMS_IBM_Character_Set 3
	Because IBM MQ does not allow certain properties to be set by a client application, if you set these headers with respect to an IBM MQ destination, a run-time exception is raised.	JMSXDeliveryCount JMSXUserID JMSXAppID	JMSXDeliveryCount JMSXUserID JMSXAppID
	These headers cannot be deleted when the Pass all Headers through Pipeline option is also specified.	JMSDeliveryMode JMSExpiration JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount	JMSDeliveryMode JMSExpiration JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount JMSCorelationID—if the inbound message has the correlation ID set. For example, if the inbound response comes from a registered JMS business service
FTP	No limitations. In other words you can set or delete the header(s)⁴ for File and FTP transports and your specifications are honored by the AquaLogic Service Bus run time.
File
Email	The AquaLogic Service Bus run time sets these headers. In other words, any specifications you make for these headers at design time are overwritten at run time.	Content-Type	Content-Type

1. That is, this header is ignored and overwritten by the run time if the inbound response message has the correlation ID set—for example, if the inbound response comes from a JMS business service that is registered with AquaLogic Service Bus

2. For example, if you set the JMSExpiration header to 1000, and at the time of the send, GMT is 1,000,000 (as a result of System.currentTimeMillis()), the resulting value of the JMSExpiration property in the JMS message is 1,000,1000

3. Header names with the JMS_IBM prefix are to be used with respect to destinations hosted by an IBM MQ server

4. For business services, the header is filename. Its value is appended to the output file name. For proxy services, the filename is the name of the file that is being polled.

Note: The same limitations around setting certain transport headers and metadata are true when you set the the inbound and outbound context variables, and when you use the AquaLogic Service Bus Test Console to test your proxy or business services. For more information , see the following topics:

"Understanding How the Run Time Uses the Transport Settings in the Test Console" in Understanding How the Run Time Uses the Transport Settings in the Test Console.
Inbound and Outbound Variables

Validate

Use a Validate action to validate elements selected by an XPath expression against an XML schema element or a WSDL resource. To configure a Validate action:

Click Add an Action, then select Validate.

The Validate action is displayed, which includes the following functionality:

An XPath link that you can click to edit an XPath expression
An in variable field in which you can enter the name of the variable in which the elements to be validated are located
A resource link from which you can select a type or element from an XML Schema or WSDL

Click XPath. The XPath Expression Editor page is displayed. To learn more, see Using the XPath Expression Editor.

When you finish editing the XPath expression, enter the name of a variable in the in variable field—this variable holds the element to be validated.

Click resource, then select WSDL or Schema. Depending on which resource type you select, the WSDL Browser or XML Schema Browser is displayed.

Select the WSDL or XML schema, select the WSDL or XML schema type or element, then click Submit.

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.

Alternatively, to raise an error if the element fails validation against the WSDL or XML schema element, select Raise Error on validation failure.

When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Note: The Validate action enables you to validate global elements only; AquaLogic Service Bus does not support validation against local elements.

Action	Summary Description
Assign	Assign the result of an XQuery expression to a context variable
Delete	Delete a context variable or all the nodes specified by an XPath expression
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
Insert	Insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression
Log	Construct a message to be logged
Publish	Specify a target service for a message and configure how the message is packaged and sent to that service
Publish Table	Specify a target service for a message and configure how the message is packaged and sent to that service. Use the Publish Table to wrap a set of routing options in switch-style condition logic
Raise Error	Raise an exception with a specified error code and description
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
Reply	Specify that an immediate reply is sent to the invoker; can be a reply with success or failure
Report	Enable message reporting for a proxy service
Service Callout	Configure a synchronous (blocking) callout to an AquaLogic Service Bus-registered proxy or business service
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
Transport Headers	Set the transport header values in messages
Validate	Validate elements selected by an XPath expression against an XML schema element or a WSDL resource

Proxy Services: Actions

Adding an Action

To Add an Action

Edit Stage Configuration

Update Actions

Related Topics

Assign

Related Topics

Delete

For Each

Scope of Variables in the For Each Action

Nested For Each Actions

If Then

Insert

Log

Understanding Log Actions

Configuring Log Actions

Publish

Understanding Publish Actions

Quality of Service

Scope of the Message Context

Are the Changes I Make to the Message Content Using the Request Actions Within a Publish Action Preserved in Subsequent Nodes in the Message Flow?

What is Written if I Publish the Message Using a File Transport?

How Do I Publish Only the Binary Part of the Message?

Must I Set the Transport Headers if I Want to Publish Using the HTTP Transport?

Configuring Publish Actions

Related Topics

Publish Table

Related Topics

Raise Error

Related Topics

Rename

Replace

Reply

Related Topics

Report

Example Report Action Configuration and Resulting Reporting Data

Related Topics

Resume

Related Topics

Service Callout

Understanding Service Callout Actions

Note About Transport Headers

Configuring Service Callout Actions

When the Service is Based on a WSDL

When the Service is Not Based on a WSDL

How are Messages Constructed for Service Callouts?

SOAP Document Style Services

XML Services

SOAP RPC Style Services

Messaging Services

Handling Errors

Transport Errors

SOAP Faults

Unexpected Responses

XML Schema for the Service Callout-Generated Fault Details

Comparing Service Callout Actions and Route Nodes

Related Topics

Skip

Transport Headers

About the Global Pass Through and Header-Specific Copy Options

Understanding How the Run Time Uses the Transport Headers' Settings

Validate