> Using the AquaLogic Service Bus Console > Proxy Services: Actions

Using the AquaLogic Service Bus Console

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

Proxy Services: Actions

Proxy services are definitions of services implemented locally on the AquaLogic Service Bus server. You design and configure the message flow in the pipelines and route nodes of a proxy services by adding and configuring actions.

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

You add actions to stages on the Edit Stage Configuration page. Actions are the elements of stages in pipelines and route and branch nodes that define how messages are to be defined 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.You can also add actions to Route Nodes and Error Handlers. To learn more, see Adding Route Node Actions, and Error Handler Actions
To Add an Action
  1. 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.
  2. 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.

    3. The Edit Message Flow page is displayed.

  3. Expand an existing pipeline to view the pipeline, which consists of request and response pipelines.
  4. 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.
  5. To add an action, click Add an Action, then select an action type.

    6. 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 run time which services will be used for the publish.
    Routing Options
    Modify any or all of the following properties in the outbound request: URI, Quality of Service, Mode, Retry parameters.
    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.

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

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

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

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

Related Topics

Overview of Proxy Services

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Viewing and Changing Message Flow

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.

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

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?

  1. 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()
  2. 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
  1. Click Add an Action, then select CommunicationArrow symbolPublish. The Publish action is displayed.
    2. 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
  2. Click Service. The Service Browser is displayed.
  3. 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.
  4. If the service has operations defined, you can specify the operation to be invoked by selecting it from the drop-down list.
  5. If you want the outbound operation to be the same as the inbound operation, select the Use inbound operation for outbound check box.
  6. 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.
  7. 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

Overview of Publish Actions

Transport Headers

Message Context

Publish Table

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.

Note: 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 (to the last publish table), the conditional is not displayed.
To Configure a Publish Table Action
  1. Click Add an Action, then select CommunicationArrow symbolPublish Table. The Publish Table action is displayed.
    2. Figure 18-2 Publish Table Action Parameters


    Publish Table Action Parameters

  2. 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.
  3. From the Operator list, select one of these comparison operators: =, !=, <, <=, >, or >=.
  4. In the field provided, enter a value against which the value returned as a result of the XQuery expression is evaluated.
  5. Click Service to select a service to which messages are to be published if the expression evaluates true for the value you specified. The Service Browser is displayed.
  6. 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.
  7. If the service has operations defined, you can specify the operation to be invoked by selecting it from the drop-down list.
  8. If you want the outbound operation to be the same as the inbound operation, select the Use inbound operation for outbound check box.
  9. In the Request Actions field, to configure how the message is packaged and sent to the service, click Add an Action, then select one or more actions that you want to associate with the service. To learn more about the type of action you want to add, see Adding an Action.
  10. To insert a new case, click new case icon, then select Insert New Case. opertors drop-down menu
  11. Repeat steps 3-7 for the new case.
  12. Add additional cases as dictated by your business logic.
  13. 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.
  14. Configure the default case—the configuration of this case specifies the routing behavior in the event that none of the preceding cases is satisfied.
  15. 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

Overview of Publish Actions

Transport Headers

Message Context

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
  1. Click Add an Action, then select CommunicationArrow symbolDynamic 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

  2. Click <Expression>. The XQuery Expression Editor is displayed.
  3. In the XQuery Expression Editor, enter an Xquery expression or select an XQuery resource that provides a result similar to: 
    4. <ctx:route isProxy="false">
    <ctx:service>project/folder/businessservicename</ctx:service>
    <ctx:operation>foo</ctx:operation>
    </ctx:route>
    Note: The element operation is optional.
  4. Click Save.
  5. 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.
  6. 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

Overview of Publish Actions

Transport Headers

Message Context

Publish Table

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 modified using Assign, Insert, Replace, or Delete actions on $outbound, using Routing options provides a simpler way to perform this task, without requiring knowledge of XPath, XQuery, or the structure of the $outbound context variable.

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

To Configure a Routing Options Action
  1. Click Add an Action, then select CommunicationArrow symbolRouting Options.

    2. The Routing Options action is displayed, with check boxes to select the following functionality.

    • URI
    • Quality of Service
    • Mode
    • Retry Interval
    • Retry Count
  2. Complete any or all of the following steps:
    • To set the URI for the outbound message: Select URI, and click the XQuery Expression Editor. Enter an expression that returns a URI. This overrides the URI for the invoked service.
    • To set the Quality of Service element: Select Quality of Service, and choose the Quality of Service option from the drop-down list. This overrides the default that is auto computed.
    • To set the Mode: Select Mode, and 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 set the Retry Interval: Select Retry Interval, and specify the number of seconds between retries. This overrides the default configured with the invoked service.
    • To set the Retry Count: Select Retry Count, and specify the number of retries the system must attempt before discontinuing the action. This overrides the default configured with the invoked service.
  3. 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 proxy service or business 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:

Note About Quality of Service

Use the Routing Options action to set the Quality of Service for a Service Callout. For more information, see Routing Options.

Note About Transport Headers

In addition to any transport headers you specify when configuring the TransportHeader action for a service (see Transport Headers), headers are automatically added by the AquaLogic Service Bus binding layer for SOAP services. The headers differ depending on whether the service uses SOAP 1.1 or SOAP 1.2.

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
  1. Click Add an Action, then select CommunicationArrow symbolService Callout.

    2. A Service Callout action is added to the message flow displayed on the page.

  2. Click <Service>. The Service Browser is displayed.
  3. Select a service from the list of registered proxy or business services, then click Submit.

    4. The name of the selected service is added to the stage configuration page.

  4. If the service you chose in step 3, above, is WSDL-based and has operations that can be invoked on the service, those operations are listed in the invoking <Operation> drop-down list. Select an operation to be invoked on the service.
  5. Specify how you want to configure the request and response messages by selecting one of the following options:
    • Select Configure SOAP Body to configure the SOAP Body. Selecting this option allows you to use $body directly.
      • Note: This option supports SOAP-RPC encoded, which is not supported when configuring payload parameters or document.
    • Select Configure Payload Parameters or Configure Payload Document to configure the payload.
  6. Subsequent configuration options depend on the kind of service you selected in step 3 and on the kind of configuration options you chose for that service in step 5. Table 18-4 shows the options available for each service type.
    Table 18-4 Service Callout Configuration Options for Each Service Type
    Selected Service Type
    “Configure SOAP Body” Options
    “Configure Payload Parameters” Options or
    “Configure Payload Document” Options
    • SOAP RPC
    • SOAP Document
    • Any SOAP
    • XML
    • Any XML
    • Messaging

    7. Table 18-5, below, provides instructions for each of the options listed in Table 18-4, above.

    Table 18-5 Service Callout Configuration Options
    For These Options...
    Follow These Steps...
    SOAP Request Body and
    SOAP Response Body
    To configure these options,
    • In the SOAP Request Body field, enter the name of a variable to hold the XML of the SOAP Body element for the callout request.
    • In the SOAP Response Body field, enter the name of a variable to which the XML of the SOAP Body element on the response will be bound.
    SOAP Request Header and
    SOAP Response Header
    To configure these options,
    • In the SOAP Request Header field, enter the name of a variable to hold the XML of the SOAP Header element for the callout request

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

    • In the SOAP Response Header field, enter the name of a variable to which the XML of the SOAP Headers on the response, if any, will be bound.
    Request Parameters and
    Response Parameters
    To configure options,
    • In the Request Parameters fields, enter names for the variables that will be evaluated at run time to provide values for the request parameters.

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

    • In the Response Parameters fields, enter the names of the variables to which the responses will be assigned at run time.
    Request Document and
    Response Document
    To configure these options,
    • In the Request Document Variable field, enter the name of a variable to assign a request document to.

      • For SOAP Document-type services, the variable is evaluated at runtime to form the body of the SOAP message sent to the service. For Any XML services, the variable is evaluated at runtime to form the body of the XML message sent to the service.

      For SOAP Document-type services and for Any XML services, you provide only the core payload documents in the input variable—the SOAP package is created for you by 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 XPath statement body/* (to remove the wrapper soap-env:Body), not $body (which results in keeping the soap-env:Body wrapper).

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

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

  7. Optionally, add one or more transport headers. For more information, see Transport Headers.
    8. 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.
  8. When you complete the configuration of this action, continue by configuring other actions or saving your stage configuration, as described in Edit Stage Configuration.

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:

Related Topics

Error Messages and Handling

Message Context.

Adding an Action

Transport Headers

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

The Transport Header action allows you to set transport header values for outbound requests (the messages sent out by a proxy service in Route, Publish, or Service Callout 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 automatically handles all namespace and ordering issues when updating $inbound or $outbound.

To Configure a Transport Headers Action
  1. Click Add an Action, then select CommunicationArrow symbolTransport Header. The Transport Header action is displayed.
    2. Figure 18-4 Transport Header Action Configuration—Outbound Request, Inbound Response


    Transport Header Action Configuration—Outbound Request, Inbound Response

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

    3. 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, Publish, or Service Callout 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-5 Inbound/Outbound Request, Inbound/Outbound Response


      Inbound/Outbound Request, Inbound/Outbound Response

  3. Optionally, select Pass all Headers through Pipeline.

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

  4. Complete the following steps for each Header you want to add:
    1. In the Transport Headers table, click Add Header. The first row in the Transport Headers table is populated as shown in the following figure.
      2. Figure 18-6 Individual Transport Header Action Configuration Options


      Individual Transport Header Action Configuration Options

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

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

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

      4. Set Header to Expression

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

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

      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.

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


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

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

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, Publish, or Service Callout 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 headers 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-6 Limitations to Transport Header Values You Specify in Transport Header Actions
Transport
Description of Limitation...
Transport Headers Affected By 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 publish1.
  • 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_PutDate2
  • 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)3 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
 
These headers have no meaning for outbound requests. If they are set dynamically (that is, if they are set in the $outbound headers section), they are ignored.4
These headers are received in $inbound. Date is the time the mail was sent by the sender. From is retrieved from incoming mail headers.
  • From
  • Date
  

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

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

3For FTP and file proxies, there is an transport request header 'fileName'. The value of this request header is the name of the file being polled.

4From and Date headers are also not applicable for $outbound request headers for e-mail business services. So there is no point in setting these headers for e-mail business services.

Note: The same limitations around setting certain transport headers and metadata are true when you set 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:

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
  1. Click Add an Action, then select Flow ControlArrow symbolFor Each. The For Each action is displayed.
    2. Figure 18-7 For Each Action Configuration Parameters


    For Each Action Configuration Parameters

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

    3. Let us use the values shown in the following figure to describe how the For Each action is executed at run time.

    Figure 18-8 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. 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.
  3. 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 18-9 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 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
  1. Click Add an Action, then select Flow ControlArrow symbolIf... Then... The If... Then... action is displayed.
    2. Figure 18-10 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
  2. Click Condition. The XQuery Condition Editor page is displayed.

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

  3. 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.
  4. 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.
    5. 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.
  5. 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
  1. Click Add an Action, then select Flow ControlArrow symbolRaise Error. The Raise Error action is displayed.
    2. Figure 18-11 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
  2. In the error code field, enter the error code you want to raise.
  3. In the error message field, enter a description of the error code.
  4. 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

To learn more about error handling actions, see Error Messages and Handling.

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. 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
  1. Click Add an Action, then select Flow ControlArrow symbolReply. The Reply action is displayed.
    2. Figure 18-12 Reply Action Configuration Parameters


    Reply Action Configuration Parameters

    With Success and With Failure options

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

To learn more about error handling actions, see Error Messages and Handling

For information about using the Reply action as one of the Publish action request actions, see Scope of the Message Context in Overview of Publish Actions

Resume

The