The Edit Stage Configuration page allows 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.

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

This topic describes how to add actions to stages in pipelines, route 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 allows 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.

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 18-1 Message Flow Actions
Action	Summary Description
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 runtime 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.
Service Callout	Configure a synchronous (blocking) callout to an AquaLogic Service Bus-registered proxy or business service
Transport Headers	Set the transport header values in messages
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 and description
Reply	Specify that an immediate reply is sent to the invoker; can be a reply with success or failure
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
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

Edit Stage Configuration

After you configure an action, you are returned to the Edit Stage Configuration page, in which you can perform further operations as listed in Table 18-2.

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 stage, deleting or disregarding your changes, and so on, as described in the following table.

Table 18-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 (demote)

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

Note:

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.

Note:

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.

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 18-3 Tasks to Use When you Edit Message Flows

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

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.

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 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

Update Actions

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

Related Topics

Overview of Publish Actions

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, Dynamic Publish, or Publish Table action, the default quality of service (QoS) is best effort. The QoS best effort essentially means that there is no reliable messaging—however, performance is optimized. To override the default best effort quality of service attribute, you must use the Routing Options action to set the Quality of Service. For more information, see Routing Options. For information about exactly once reliability, see Adding a Route Node.

Scope of the Message Context

Each publish request transformation maintains its own local copy of a message context. The changes to the predefined context variables ($headers, $body, $attachments, $outbound) in the publish request actions are isolated to that publish endpoint and do not affect subsequent processing by the message flow. For more information on context variables, see Predefined Context Variables

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 or $Outbound Using the Request Actions Within a Publish Action Preserved in Subsequent Nodes in the Message Flow?

No. Any changes you, or the transport, make to an outbound message (or $outbound)in a publish action only affect the published message. In other words, the changes you, or the transport, make in the publish action (or $outbound) are rolled back before the message flow proceeds to any actions or nodes that immediately follow the publish action.

Likewise, the $outbound variable is also reverted to its original state after the Publish action has completed. Ordinarily, after a communication operation, the $outbound variable will contain useful information such as the response metadata, the actual URI used when communicating with a service, and, in the case of File Transport, the name of the file that was created. However, due to Publish reverting $outbound to its original state, this information will be unavailable. If this information is important, the user should do a service callout to a local transport proxy that routes to the business service. The local transport proxy can then return relevant portions of $outbound as the response from the Service Callout.

When you use a Reply action as one of the Publish request actions, the message content is not rolled back. In other words the message that is in the message context, is the one returned to the client as a result of the Reply action being executed.

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:

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

You must copy the attachment content 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):

<soap-env:Body>{ $attachments/ctx:attachment[2]/ctx:body/node() }</soap-env:Body>

Use a Replace action to replace the contents of $body with the contents of the attachment:

$attachments/ctx:attachment[2]/ctx:body/node()

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

Note:

As a shortcut, you can also simply delete the entire attachments variable without specifying an XPath.

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.

Publish

To Configure a Publish Action

Click Add an Action, then select CommunicationPublish. The Publish action is displayed.

Figure 18-1 Publish Action Configuration Parameters

Publish Action Configuration Parameters

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.
If the service has operations defined, you can specify the operation to be invoked by selecting it from the drop-down list.
If you want the outbound operation to be the same as the inbound operation, select the Use inbound operation for outbound checkbox.
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.

Related Topics

Publish Table

A publish table is a set of publish actions 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. Use a Publish Table action to identify target services for messages and configure how the messages are packaged and sent to these services.

For information about the default quality of service and the scope of the message context for Publish actions, see Understanding Publish Actions.

To Configure a Publish Table Action

Click Add an Action, then select CommunicationPublish Table. The Publish Table action is displayed.

Figure 18-2 Publish Table Action Parameters

Publish Table Action Parameters

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 is made. To learn more, see Using the Inline XQuery Expression Editor.
From the Operator list, select one of these comparison operators: =, !=, <, <=, >, or >=.
In the field provided, enter a value against which the value returned as a result of the XQuery expression is evaluated.
Click Service to select a service to which messages are to be published if the expression evaluates true for the value you specified. 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.
If the service has operations defined, you can specify the operation to be invoked by selecting it from the drop-down list.
If you want the outbound operation to be the same as the inbound operation, select the Use inbound operation for outbound checkbox.
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 an Action.
To insert a new case, click , then select Insert New Case.
Repeat steps 3-7 for the new case.
Add additional cases as dictated by your business logic.
Click the Diamond icon of the last case you define in the sequence, then select Insert Default Case to add a default case at the end.
Configure the default case—the configuration of this case specifies the routing behavior in the event that none of the preceding cases is satisfied.
When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Related Topics

Dynamic Publish

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

To Configure a Dynamic Publish Action

Click Add an Action, then select CommunicationDynamic Publish. The Dynamic Publish action is displayed, which includes the following functionality:

An Expression link to the XQuery Expression Editor.
An Add an Action link to the Action menu.

Figure 18-3 Dynamic Publish Action Parameters

Dynamic Publish Action Parameters

Click <Expression>. The XQuery Expression Editor is displayed.
In the XQuery Expression Editor, enter an Xquery expression or select an XQuery resource that provides a result similar to:

<ctx:route isProxy="false">

<ctx:service>project/folder/businessservicename</ctx:service>

<ctx:operation>foo</ctx:operation>

</ctx:route>

Note: The element operation is optional.

Click Save.
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 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.

Related Topics

Routing Options

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 performed 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.

To Configure a Routing Options Action

Click Add an Action, then select CommunicationRouting Options.

The Routing Options action is displayed, with checkboxes to select the following functionality.

URI
Quality of Service
Mode
Retry Interval
Retry Count

Figure 18-4 Routing Options Action Parameters

Routing Options Action Parameters

Complete any or all of the following steps:

To reset 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 reset the Quality of Service element: Select Quality of Service, and choose the Quality of Service option from the drop-down list. This overrides the default that is auto computed.
To reset the Mode: Select Mode, and choose 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 reset the Retry Interval: Select Retry Interval, and specify the number of seconds between retries. This overrides the default configured with the invoked service.
To reset 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.

When you complete the configuration of this action, 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
Transport-typed

Service transport types can be HTTP, HTTPS, JMS, EJB, or Tuxedo.
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:

Configuring Service Callout Actions

Configuring a Service Callout action involves populating the context by specifying a service and operation, and entering context variables to bind to the invocation input and output parameters.

To Configure a Service Callout Action

Click Add an Action, then select CommunicationService Callout.

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

Figure 18-5 Service Callout Action Parameters Before Selecting a Service

Service Callout Action Parameters Before Selecting 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.

If the selected business service uses transactional EJB or Tuxedo transports, select the checkbox to set the Quality of Service Level to "Exactly Once".

The subsequent configuration options depend on whether the service selected in step 3 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.

Figure 18-6 Service Callout Action Parameters for a WSDL-Based Service

Service Callout Action Parameters for a WSDL-Based Service

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.

Figure 18-7 TransPort Headers Configuration Parameters

TransPort Headers Configuration Parameters

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 editor, 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.

Figure 18-8 Additional Transport Headers Configuration Parameters

Additional Transport Headers Configuration Parameters

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.

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.

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.

Figure 18-9 Service Callout Action Parameters for a Service Not Based on a WSDL

Service Callout Action Parameters for a Service Not Based on a WSDL

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.

Figure 18-10 Transport Headers Configuration Parameters

Transport Headers Configuration Parameters

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.

Click <Expression> in Set Header to <Expression> to invoke the XQuery or XSLT expression editor, 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.:

WARNING:

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

Figure 18-11 Additional Transport Headers Configuration Information

Additional Transport Headers Configuration Information

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.

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, including EJB document and document-wrapped services:

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.

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

At run time, the SOAP Request Header variable, reqheader, is bound to the following 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).

Based on the configuration of the Service Callout action illustrated in Figure 18-12, 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.

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

XML Services

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.

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

SOAP RPC Style Services

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

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

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

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

Messaging Services

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:

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.

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:

If the transport is HTTP, the ErrorResponseDetail element will also contain the HTTP error code returned with the response. The ErrorResponseDetail element in the fault contains error response payload received from the service. The following listing shows an example of the ErrorResponseDetail element.

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.

The <faultcode>, <faultstring>, and <detail> elements are extracted and wrapped in an <alsb:ReceivedFault> element. Note that the faultcode element in Listing 18-13 contains a QName—any related namespace declarations are preserved. If the transport is HTTP, the ReceivedFault element will also contain the HTTP error code returned with the fault response.

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.

<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>T

hat's an Error!

</message> 
                <errorcode>1006</errorcode> 
            </alsb:detail>

          <alsb:http-response-code>500</alsb:http-response-code>
        </alsb:ReceivedFault>
    </ctx:details>
    <ctx:location> </ctx:location>
</ctx:Fault>

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. If the transport is HTTP, the ReceivedFault element will also contain the HTTP error code returned with the fault response.

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

XML Schema for the Service Callout-Generated Fault Details

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

Comparing Service Callout Actions and Route Nodes

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

Related Topics

Transport Headers

The Transport Header action allows you to set transport 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 runtime will automatically handle all namespace and ordering issues when updating $inbound or $outbound.

To Configure a Transport Headers Action

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

Figure 18-15 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 18-16 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 18-17 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.

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 18-16)
or
Copy Header from Outbound Response (if you are setting transport headers for the Inbound Response—see Figure 18-16)

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.

Individual Transport Header Action Configuration Options

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.

Individual Transport Header Action Configuration Options

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 Individual Transport Header Action Configuration Options 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:

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:

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 18-4 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)	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 or a request/response service based on JMSMessageID correlation. If sending to a request/response service based on JMSCorrelationID correlation, these headers are overwritten at run time.	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 2 JMS_IBM_PutApplType 2 JMS_IBM_Encoding 2 JMS_IBM_Character_Set 2	JMSMessageID JMSRedelivered JMSTimestamp JMSXDeliveryCount JMSXUserID JMS_IBM_PutDate 2 JMS_IBM_PutTime 2 JMS_IBM_PutApplType 2 JMS_IBM_Encoding 2 JMS_IBM_Character_Set 2
	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
E-mail	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

¹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

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

³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.

Related Topics

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 Flow ControlFor Each. The For Each action is displayed.

Figure 18-18 For Each Action Configuration Parameters

For Each Action Configuration Parameters

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 18-19 Example Configuration for For Each Action

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. In this example for instance the body variable might contain the following XML and the XPath might be the following:

./*:processCust/*:commonCust/*:Order_Items/*:Item

Listing 18-16

<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <SOAP-ENV:Body>

  <processCust xmlns="http://www.openuri.org/" xmlns:com="bea.com/demo/orders/commonCust">

    <com:commonCust>

    <com:Order_Number>200</com:Order_Number>

    <com:Customer_ID>200</com:Customer_ID>

    <com:Customer_Name>string</com:Customer_Name>

    <com:Requested_Provision_Date>2008-09-28</com:Requested_Provision_Date>

    <com:Order_Items>

      <com:Item>

        <com:Part_Number>100</com:Part_Number>

        <com:Quantity>100</com:Quantity>

        <com:Description>string</com:Description>

      </com:Item>

      <com:Item>

        <com:Part_Number>200</com:Part_Number>

        <com:Quantity>200</com:Quantity>

        <com:Description>string</com:Description>

      </com:Item>

    </com:Order_Items>

    <com:Product_Type>string</com:Product_Type>

    </com:commonCust>

  </processCust>

  </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

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

Index Variable

Total Variable

Nested For Each Actions

You can configure nested For Each actions. When you do so, it is recommend 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:

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 Flow ControlIf... Then... The If... Then... action is displayed.

Figure 18-21 If...Then... Action Configuration Parameters

If...Then... Action Configuration Parameters

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.

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 Flow ControlRaise Error. The Raise Error action is displayed.

Figure 18-22 Raise Error Action Configuration Parameters

Raise Error Action Configuration Parameters

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.

Related Topics

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. n 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.

To Configure a Reply Action

Click Add an Action, then select Flow ControlReply. The Reply action is displayed.

Figure 18-23 Reply Action Configuration Parameters

Reply Action Configuration Parameters

With Success and With Failure options

Select With Success to reply that the message was successful or select With Failure 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.

Related Topics

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.

To Configure a Resume Action

Click Add an Action, then select Flow ControlResume. The Resume icon is displayed.
Continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

Related Topics

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

Click Add an Action, then select Flow ControlSkip. 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.

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 Message ProcessingAssign. 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

Figure 18-24 Assign Action Configuration Parameters

Assign Action Configuration Parameters

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.

Related Topics

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 Message ProcessingDelete. 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.

Figure 18-25 Delete Action Configuration Parameters

Delete Action Configuration Parameters

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.

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 Message ProcessingInsert. The Insert action is displayed.

Figure 18-26 Insert Action Configuration Parameters

Insert Action Configuration Parameters

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.

Java Callout

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

To Configure a Java Callout Action

Click Add an Action, then select Message Processing Java Callout. The Java Callout action is displayed.

Figure 18-27 Java Callout Configuration Parameter Before Selecting a Method

Java Callout Configuration Parameter Before Selecting a Method

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.
From the list of Java classes listed, click the + beside the required class, to display a list of methods. Select a method and click Submit. You are returned to the Edit Stage page. The Java Callout action is displayed.

Figure 18-28 Java Callout Configuration Parameters After Selecting a Method

Java Callout Configuration Parameters After Selecting a Method

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

Note:

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 Overview of Service Accounts.

Note: 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.

Under Parameters, click the Expression link. The XQuery Expression Editor page is displayed. Use the XQuery Expression Editor to provide the arguments required by the Java Method.

Note:

If the type of the input value you enter does not match the declared input argument type, AquaLogic 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".

In the Result field, assign a variable for the result returned by the Java method.
If there is a security context for the Java method, select the checkbox and click <Service Account>. The Select Service Account page is displayed. Select the required service account from the list and click Submit.
When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

MFL Transform

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 a BEA proprietary language used to define rules to transform formatted binary data into XML data, or vice versa. To learn more, see Overview of MFLs.

To Configure an MFL Transform Action

Click Add an Action, then select Message ProcessingMFL Transform. The MFL Transform Action is displayed.

Figure 18-29 MFL Transform Configuration Parameters

MFL Transform Configuration Parameters

An Apply MFL Transformation drop-down list, which includes two options:

convert XML to Non-XML
convert Non-XML to XML

An Expression link which you can click to edit an XQuery expression, which is the input to the transform. 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.
An MFL Resource option with a <resource> link that you can use to select a static MFL resource for the transform action.
An MFL Resource from option with an <Expression> link that you can use to edit an XQuery expression to dynamically select an MFL resource for the transform action, in the format:

project/folder/MFLresourcename

An Assign to Variable field in which you can specify the variable to which the transformation result is to be assigned. The result will be a binary-content XML element.
Under Apply MFL Transformation, select XML to Non-XML or Non-XML to XML, according to your requirement.
Click Expression. The XQuery Expression Editor page is displayed. Using the XQuery Expression Editor, specify the variable on which the MFL transformation action is to be performed. To learn more, see Using the Inline XQuery Expression Editor.
Select one of the following options:

MFL Resource: click the <resource> link. The Select MFL page is displayed. Select the 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. To learn more, see Using the Inline XQuery Expression Editor.

In the Assign to Variable field, enter the name of the variable to which the result of this transform action is to be assigned.
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 Message ProcessingRename. The Rename action is displayed.

Figure 18-30 Rename Action Configuration Parameters

Rename Action Configuration Parameters

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

To Configure a Replace Action

Click Add an Action, then select Message ProcessingReplace. The Replace action is displayed.

Figure 18-31 Replace Action Configuration Parameters

Replace Action Configuration Parameters

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 specified 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.

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 Message ProcessingValidate. The Validate action is displayed.

Figure 18-32 Validate Action Configuration Parameters

Validate Action Configuration Parameters

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.

Alert

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 destination should be configured and chosen with this in mind. To learn more about Alert Destinations, see Overview of Alert Destinations.

To Configure an Alert Action

Click Add an Action, then select ReportingAlert. The Assign action is displayed, which includes the following functionality:

An Alert Destination link that you can use to select an Alert Destination resource.
An <expression> link that you can click to edit an XQuery expression.
An alert summary field in which you can enter a short description for this alert.
A severity level drop-down list from which you can select a severity level for this alert.

Figure 18-33 Alert Action Configuration Parameters

Alert Action Configuration Parameters

Click Destination. The Select Alert Destination page is displayed. Select the required alert destination from the list and click Submit.
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. To learn more, see Using the Inline XQuery Expression Editor.
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, "AquaLogic Service Bus Alert", will be used instead.
In the severity level drop-down list, select a severity level for this alert from among: Normal, Warning, Minor, Major, Critical, and Fatal.
When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.
Ensure that monitoring is enabled for the service.
If monitoring is not enabled for this service. For information on how to enable monitoring for a service, see Configuring Monitoring for Specific Services

Related Topics

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.

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:

Configuring Log Actions

To Configure a Log Action

Click Add an Action, then select ReportingLog. The Log action is displayed.

Figure 18-34 Log Action Configuration Parameters

Log Action Configuration Parameters

An Expression link that 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 18-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.

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

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 ReportingReport. The Report action is displayed.

Figure 18-35 Report Action Configuration Parameters

Report Action Configuration Parameters

An Expression link that you can click to edit an XQuery expression
A field in which you can add name and value key 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.

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 18-36 is executed twice.

Using the AquaLogic Service Bus Console

Proxy Services: Actions

Adding an Action

To Add an Action

Edit Stage Configuration

Update Actions

Related Topics

Overview of Publish Actions

Understanding Publish Actions

Quality of Service

Scope of the Message Context

Are the Changes I Make to the Message Content or $Outbound 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?

Publish

To Configure a Publish Action

Related Topics

Publish Table

To Configure a Publish Table Action

Related Topics

Dynamic Publish

To Configure a Dynamic Publish Action

Related Topics

Routing Options

To Configure a Routing Options Action

Service Callout

Understanding Service Callout Actions

Note About Transport Headers

Configuring Service Callout Actions

To Configure a Service Callout Action

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

Transport Headers

To Configure a Transport Headers Action

About the Global Pass Through and Header-Specific Copy Options

Understanding How the Run Time Uses the Transport Headers' Settings

Related Topics

For Each

To Configure a For Each Action

Scope of Variables in the For Each Action

Value Variable

Index Variable

Total Variable

Nested For Each Actions

If... Then...

To Configure an If... Then... Action

Raise Error

To Configure a Raise Error Action

Related Topics

Reply

To Configure a Reply Action

Related Topics

Resume

To Configure a Resume Action

Related Topics

Skip

Assign

To Configure an Assign Action

Related Topics

Delete

To Configure a Delete Action

Insert

To Configure an Insert Action

Java Callout

To Configure a Java Callout Action

MFL Transform

To Configure an MFL Transform Action