Console Online Help

Proxy Services

This section includes the following topics:

• Overview of Proxy Services
• Adding a Proxy Service
• Listing and Locating Proxy Services
• Viewing and Changing Proxy Services
• Deleting Proxy Services
• Overview of Message Flow
• Viewing and Changing Message Flow
• Adding a Pipeline Pair Node
• Adding a Conditional Branch Node
• Adding an Operational Branch Node
• Adding a Stage
• Adding an Action
• Adding a Route Node
• Adding Route Node Actions
• Viewing and Changing Conditional Branch Details
• Viewing and Changing Operational Branch Details
• Viewing and Changing Stage Configuration Details
• Editing an XQuery Condition
• Editing an XQuery Expression
• Editing an XPath Expression
• Defining a New Message Context Variable
• Error Messages and Handling
• Adding Error Handling for the Proxy Service
• Adding Pipeline Error Handling
• Adding Stage Error Handling
• Adding Error Handling for the Route Node
• Viewing and Changing an Error Handler
• Deleting an Error Handler

 

---

Overview of Proxy Services

This section includes the following topics:

• Service Types
• Service Types and Transports

Proxy services are AquaLogic Service Bus definitions of Web services implemented locally on WebLogic Server. You define a proxy service in terms of WSDLs, pipelines, and policies. If the proxy service requires security credentials, you can create a proxy service provider to manage these security credentials from the AquaLogic Service Bus Console. For information on how to configure a proxy service provider, see Adding a Proxy Service Provider. You can configure access control policies on HTTP/S proxy services. To learn more, see Listing and Locating Access Control Policies.

You implement a proxy service through configuring its Message Flow. Message Flows can include pipeline pairs and the following nodes: Start, Route, Echo, and Branch. To learn more, see Overview of Message Flow and Viewing and Changing Message Flow.

The following table lists the pages you can access from the Project Explorer and Resource Browser modules. The tasks and help topics associated with each are provided.

Table 14-1 Pages Accessed from Project Explorer and Resource Browser Modules

Page	Associated Tasks	Help Topics
Summary of Proxy Services	View a list of proxy services. The service name and alerts are displayed.	Listing and Locating Proxy Services
	Filter the list.
	Delete a proxy service	Deleting Proxy Services
Edit a Proxy Service	Add a proxy service.	Adding a Proxy Service
Proxy Service Details	View and edit details of a specific proxy service.	Viewing and Changing Proxy Services
Edit Message Flow	View the message flow	Viewing and Changing Message Flow
	Change the message flow
	Add a pipeline pair node	Adding a Pipeline Pair Node
	Add a conditional branch node	Adding a Conditional Branch Node
	Add an operational branch node	Adding an Operational Branch Node
	Add a route node	Adding a Route Node
	Add a stage	Adding a Stage
Edit Branch Node	Change branch details and add branch definitions	Viewing and Changing Conditional Branch Details
Edit Stage Configuration	Add an action	Adding an Action
Edit Error Handler	Add an error handler for a proxy service	Adding Error Handling for the Proxy Service
	Add a pipeline error handler	Adding Pipeline Error Handling
	Add a stage error handler	Adding Stage Error Handling
	Add route node error handler	Adding Error Handling for the Route Node
Edit XQuery Expression	Edit an XQuery expression	Editing an XQuery Expression
Edit an XQuery Condition	Edit an XQuery condition	Editing an XQuery Condition
Edit an XPath Expression	Edit an XPath expression	Editing an XPath Expression
Define a New Message Context Variable	Define a new context variable	Defining a New Message Context Variable

 

Service Types

Each service type is modeled following the same pattern. Their configuration is composed of a common part and a service type specific part.

The common configuration consists of the following properties:

Table 14-2 Service Type Configuration

 

Property	Description
Resource Definition	The resource definition consists of: The service name (that is, project, path, and local name) An optional description for the service The service type (read only)
Miscellaneous Configuration	This configuration consists of: The service provider for proxy services Note: A service provider is only required if the proxy service routes messages to HTTPS services that require client-certificate authentication, or in some message-level security scenarios.
Transport Configuration	You can configure the following parameters for each proxy service: Endpoint URI—string, for example: /proxy1 or jms://localhost:7001/QueueConnectionFactory/DestName. (This is required.) To target a target a JMS destination to multiple servers, use the following URI format: jms://host1:port,host2:port/QueueConnectionFactory/DestName Get all headers from request. This is a Boolean value; the default is true. User-specified Headers— a list of string header names, which is only applicable if you select False for the Get all headers option. The transport you select must be able to support the transport mode (that is, request/response, one-way or both) required by the binding definition, and be configured accordingly. For services exchanging messages in both modes, you must configure the binding layer so that it can choose the transport mode accordingly (for any transport implementing the request/response as two asynchronous calls, for example, JMS). This occurs automatically when the service is a concrete type, as it is described in the binding definition. When it is not a concrete type, to configure the binding layer, you must set the mode in the $outbound variable. Based on the transport and WSDL, the transport mode is automatically selected, but you can overwrite it in $inbound or $outbound.

 

Each service type must define the following configurations:

• Binding definition
• Run-time configuration
• Run-time variables ($operation, $body, $header, $attachments)

 

 

 

 

Table 14-3 Service Type Configuration

Property	Description
WSDL Port	You can base SOAP and XML services on an existing WSDL resource. A WSDL document is available for proxy and business services for any transport. This WSDL is used as the base for the final WSDL document. When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL port describes what the actual transport address is. You use it for a concrete interface. For a definition of a WSDL port, see http://www.w3.org/TR/wsdl#_ports. When you create a proxy service based on a WSDL Binding, AquaLogic Service Bus sets the new service and port definitions in the WSDL generated for the proxy service. Regardless of whether you define a proxy service based on a WSDL port or a WSDL binding, the WSDL generated for the proxy service defines only a single port. If the service is generated from port X in the template WSDL, then port X is also defined in the generated WSDL. Any other ports defined in the template WSDL are not included in the generated WSDL. Furthermore, if you base the proxy service on a WSDL port, the generated WSDL uses that port name and preserves any WS-Policies associated with that port. The binding is determined from the port, and in turn, the port type is determined from the binding. If the service is generated from binding Y in the template WSDL, the generated WSDL defines a new service and port (<service-name>QSService and <port-name>QSPort). None of the ports defined in the template WSDL are included in the generated WSDL. If you base the service on a WSDL binding template, there may be multiple ports in that WSDL associated with that binding. Each port can use a different URL and have a different WS-Policy attached to it. Therefore, the generated WSDL uses the binding but generates an artificial port for that binding with no WS-Policy. For all WSDL-based services, the transport type and transport URL can be overwritten in the transport section of the service definition. Note: You can get the WSDL for an HTTP(S)-based proxy service by entering the URL for the service appended with ?WSDL in your browser's Address field.
WSDL Binding	You can base SOAP and XML services on an existing WSDL resource. A WSDL document is available for proxy and business services for any transport. This WSDL is used as the base for the final WSDL document. When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL binding describes the structure of the interface and how it is packaged. You use it to map the transport address. For a definition of a WSDL Binding, see http://www.w3.org/TR/wsdl#_bindings. You may change the transport protocol of a service to another compatible one. The transport attribute of the <soap:binding> element, in the <wsdl:binding> referenced by the service, must reflect the value for the selected transport. For SOAP services, any existing <wsdl:service> definition is removed and a new one containing a single <wsdl:port> is created. This <wsdl:port> is configured based on the <wsdl:binding> referenced by the service and its SOAP address contains the address or the service (as defined by its transport). For XML services, the only standard WSDL binding definition available is the one defined for HTTP. However, BEA has added its own standard definition for JMS. So, except in the case of the JMS transport protocol, the standard HTTP binding is used. As for SOAP, any existing <wsdl:service> is removed and a new one is created to reflect the service address. As only HTTP and JMS one-way are supported as standards, the <wsdl:service> is not generated for any other configuration.
Any SOAP Service	Binding Definition: The only information this service type defines is that the service is receiving or sending SOAP messages—regardless of their WSDL binding definition. Therefore the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, any services (SOAP or XML) do not have any WSDL definition. It is not possible to request a WSDL document for those services. Run-Time Variables: The $body and $header variables respectively hold the <soap:Body> and <soap:Header> of the incoming SOAP message. The $attachments variable contains the SOAP message attachments if any. The $operation variable is not applicable to this service type as you do not define a port type. To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch.
Any XML Services	Binding Definition: The only information this service type defines is that the service is receiving/sending XML messages—regardless of their WSDL binding definition. Therefore, the binding configuration for this type is empty. In addition, as there is no binding configuration, the combination of this type and the content-type of the message is sufficient to determine whether or not there are attachments to the message. As per their definition, any services (SOAP or XML) do not have any WSDL definition. It is not possible to request a WSDL document for those services. Run Time Variables: The $body variable holds the incoming XML message wrapped in a <soap:Body> element. The $attachments variable contains message attachments if there are any. The $header variable is not applicable to this service type and is set to its default value. The $operation variable is not applicable to this service type as you do not define a port type. To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch.
Messaging Services	Binding Definition: The binding definition for messaging services consists of configuring the content-type of the messages that are exchanged. The content-type for the response does not need to be the same as for the request; therefore, the response is configured separately (for example, the service could accept an MFL message and return an XML acknowledgment receipt). As per their definition, messaging-based services do not have any WSDL definition. It is not possible to request a WSDL document for those services. There are four available content types to choose from for the request (and response): Binary Text XML MFL Run Time Variables: This service type is message based. There is no concept of multiple "operations" as for Web services. Therefore, the $operation variable is left empty. The $body variable holds the incoming message wrapped in a <soap:Body> element. The $header variable is not applicable to this service type, and is set to its default value. The $attachments variable contains message attachments if there are any. To learn more about the message context variables, see Message-Related Variables and Constructing Messages to Dispatch.


 

Service Types and Transports

The following types of service types and transports are supported by AquaLogic Service Bus:

Table 14-4 Service Types and Transports Supported by AquaLogic Service Bus

Service Type	Transport Protocols
SOAP or XML WSDL	JMS1 HTTP(S)
SOAP (no WSDL)	JMS HTTP(S)
XML (no WSDL)2	HTTP(S) JMS Email File FTP
Messaging Type (Binary, Text, MFL, XML)	HTTP(S) JMS Email File FTP

1. JMS request and JMS response are not supported if WS-Security is enabled.


2. HTTP GET is only supported for XML with no WSDL.

 

Related Topics

Overview of Business Services

 

---

Adding a Proxy Service

The Edit a Proxy Service - General Configuration page enables you to add a proxy service.

Proxy services are AquaLogic Service Bus definitions of Web services implemented locally on WebLogic Server. You define a proxy service in terms of WSDLs, pipelines, and policies. To learn more, see Overview of Proxy Services.

To add a proxy service, you must first configure general information for the service, configure general and protocol-dependent transport information for the service, then configure operation selection algorithms for the service if it includes operations. If this is a messaging service, you must also configure the message types. You can review the configuration before you create the proxy service.

The tasks in this procedure include:

• To Add a Proxy Service - General Configuration
• To Add a Proxy Service - Messaging Type Configuration
• To Add a Proxy Service - Transport Configuration
• To Add a Proxy Service - Protocol-Dependent Transport Configuration
• To Add a Proxy Service - Operation Selection Configuration
• To Add a Proxy Service - General Configuration Review

To Add a Proxy Service - General Configuration

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.
From the left navigation pane, select Project Explorer. The Project View page is displayed.
Select the project to which you want to add the proxy service. You can add a proxy service directly under the project, or you can add the proxy service under a selected folder.

Note: Click the name of a folder to select it. The Folder View page is displayed.

From the Project View or Folder View page, in the Create Resource field, select Proxy Service. The Edit a Proxy Service - General Configuration page is displayed.
In the Service Name field, enter a unique name for the proxy service.
In the Service Type field, do one of the following:

Note: A service type defines the types and packaging of the messages exchanged by the service. This is a required field.

Table 14-5 Service Type Field

To...	Complete These Steps...
Create a service from WSDL port	1. Select WSDL port from under Create a New Service. 2. Click Browse. The WSDL Browser is displayed. 3. In the WSDL Browser, select a WSDL resource, then select a port in the Definitions pane. 4. Click Submit to close the dialog box and return to the General Configuration page. Note: When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL port describes what the actual transport address is. You use it for a concrete interface. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services. See also Generating WSDLs from a Proxy Service in this topic.
Create a service from WSDL binding	1. Select WSDL binding from under Create a New Service. 2. Click Browse. The WSDL Browser is displayed. 3. In the WSDL Browser, select a WSDL resource, then select a binding in the Definitions pane. 4. Click Submit to close the dialog box and return to the General Configuration page. Note: When you create a business service or proxy service based on a WSDL, you can select only a WSDL port or a WSDL binding, as a WSDL may only have one of these entities defined. The WSDL binding describes the structure of the interface and how it is packaged. You use it to map the transport address. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services. See also Generating WSDLs from a Proxy Service in this topic.
Create a messaging service	Select Messaging Service to create a service that can receive messages of one data type and respond with messages of a different data type. These exchanges can be either request/response or one-way. Unlike Web services, the content-type of the request and response need not be the same. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services.
Create a SOAP service that does not have an explicitly defined, concrete interface	Select Any SOAP Service to create a SOAP service that does not have an explicitly defined, concrete interface. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services.
Create an XML service that does not have an explicitly defined, concrete interface	Select Any XML Service to create an XML service that does not have an explicitly defined, concrete interface. Note: HTTP GET is only supported in the Any XML Service service type. To learn more about this service type, see Service Types and Service Types and Transports in Overview of Proxy Services.
Create a proxy service from an existing business service	1. Select Business Service from under Create from Existing Service. 2. Click Browse. The Service Browser is displayed. 3. In the Service Browser, select a business service. 4. Click Submit to close the dialog box and return to the General Configuration page. This enables you to create a proxy service with a route node that routes to the business service you select. To learn more about business services, see Overview of Business Services.
Create a proxy service from an existing proxy service	1. Select Proxy Service from under Create from Existing Service. 2. Click Browse. The Service Browser is displayed. 3. In the Service Browser, select a proxy service. 4. Click Submit to close the dialog box and return to the General Configuration page. This enables you to clone a new proxy service from the proxy service you select.


 
In the Proxy Service Provider field, select the name of a proxy service provider:
Click Browse. The Service Provider Browser is displayed.
In the Service Provider Browser, select a proxy service provider.
Click Submit to close the dialog box and return to the General Configuration page.

A proxy service provider is only required in certain cases: Outbound 2-way TLS/SSL, where the proxy service routes messages to HTTPS services that require client-certificate authentication, or in some Web service security scenarios; for example, if the proxy service requires messages to be encrypted. To learn more about proxy service providers, see Overview of Proxy Service Providers. To learn how to create a proxy service provider, see Adding a Proxy Service Provider.

Note: To add a Web service security-enabled proxy service, you must create the proxy service from a WSDL (port or binding) with WS-Policy attachments.

Click Next.

If you selected Messaging Service in the Service Type field, the Edit a Proxy Service - Message Type Configuration page is displayed. Continue in To Add a Proxy Service - Messaging Type Configuration.

For all other service types, the Edit a Proxy Service - Transport Configuration page is displayed. Continue in To Add a Proxy Service - Transport Configuration.

To Add a Proxy Service - Messaging Type Configuration

If you selected Messaging Service in the Service Type field, the Edit a Proxy Service - Message Type Configuration page is displayed when you click Next on the Edit a Proxy Service - General Configuration page.

The binding definition for messaging services consists of configuring the content-type of the messages that are exchanged. The content-type for the response does not need to be the same as for the request; therefore, the response is configured separately (for example, the service could accept an MFL message and return an XML acknowledgment receipt).

Select a message type for the request and response messages:
In the Request Message Type field, select a message type for the request message:

Table 14-6 Request Message Type Field

Message Type	Description
Binary	Select Binary if the content-type of the message is unknown or not important.
Text	Select Text if the message can be restricted to text.
MFL	Select MFL if the message is a binary document conforming to an MFL definition. You can configure only one MFL file. Note: For MFLs, you can click Browse to select a MFL from the MFL Browser, then click Submit.
XML	Select XML if the message is an XML document. To provide some type information, you can choose to declare the XML schema type of the XML document exchanged.


 
In the Response Message Type field, select a message type for the response message:

Table 14-7 Response Message Type Field

Message Type	Description
None	Select if there no content-type for the message.
Binary	Select Binary if the content-type of the message is unknown or not important.
Text	Select Text if the message can be restricted to text.
MFL	Select MFL if the message is a binary document conforming to an MFL definition. You can configure only one MFL file. Note: For MFLs, you can click Browse to select a MFL from the MFL Browser, then click Submit.
XML	Select XML if the message is an XML document. To provide some type information, you can choose to declare the XML schema type of the XML document exchanged.


 
Click Next.

The Transport Configuration page is displayed. Continue in To Add a Proxy Service - Transport Configuration.

To Add a Proxy Service - Transport Configuration

The Transport Configuration page is displayed when you click Next on the Edit a Proxy Service - General Configuration page. It is displayed for messaging services when you click Next on the Edit a Proxy Service - Message Type Configuration page.

This page enables you to configure transport information for the proxy service. To learn more about the types of service types and transports supported by AquaLogic Service Bus, see Service Types and Transports.

Note: Inbound transport-level security applies to the client applications and AquaLogic Service Bus proxy services. Outbound transport-level security applies to the connections between AquaLogic Service Bus proxy services and business services. To learn more about transport-level security, see "Transport-Level Security" in Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide.

In the Protocol field, select one of these transport protocols:
• HTTP
• JMS
• HTTPS
• FTP
• Email
• File
In the Endpoint URI field, enter an endpoint URL in the format based on the transport protocol you selected in the Protocol field, then click Add:

Table 14-8 Endpoint URI Field

Transport Protocol	Format
Email	mailfrom:mail-server-hostname:mail-server-port
File	file:///drivename:/somename
FTP	ftp://hostname:port/directory
HTTP	/someName
HTTPS	/someName
JMS	jms://host:port/factoryJndiName/destJndiName To target a target a JMS destination to multiple servers, use the following URI format: jms://host1:port,host2:port/QueueConnectionFactory/DestName


 

Note: You can configure multiple URLs. You can click Delete in the Action column to delete them at any time. At run time, the URLs are selected based on the load balancing algorithm you selected in the Load Balancing Algorithm field.

In the Get All Headers field, select Yes if you want to retrieve all the headers from the transport or select No if you want to retrieve a defined set of headers. If you select No, enter a set of headers in the Header field, then click Add.
Click Next.

An additional Transport Configuration page is displayed. This page enables you to configure protocol-dependent transport information for the proxy service. Continue in To Add a Proxy Service - Protocol-Dependent Transport Configuration.

To Add a Proxy Service - Protocol-Dependent Transport Configuration

The [Protocol] Transport Configuration page is displayed when you click Next on the Edit a Proxy Service - Transport Configuration page. This page enables you to configure additional transport information for the proxy service, based on the transport protocol you selected in the Protocol field.

Based on the transport protocol you selected in the Protocol field, do one of the following:

Table 14-9 Protocol Field

Transport Protocol...	Complete These Steps...
HTTP	1. Select the Basic Authentication Required checkbox to specify that basic authentication is required to access this service, or leave it blank to specify that basic authentication is not required. Basic authentication instructs WebLogic Server to authenticate the client using a username and password against the authentication providers configured in the security realm, such as a Lightweight Directory Access Protocol (LDAP) directory service and Windows Active Directory. The client must send its username and password on the HTTP request header. Note: Basic authentication is strongly discouraged over HTTP because the password is sent in clear text. However, it is safe to send passwords over HTTPS because HTTPS provides an encrypted channel. Warning: When you create an HTTP proxy service endpoint that requires Basic Authentication, a transport-authorization policy is not automatically associated with the inbound endpoint URI. For Basic Authentication to be enforced, you must define a transport-authorization policy for the endpoint. To learn more, see Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide. 2. In the Dispatch Policy field, select a dispatch policy for this endpoint. Leave blank to use the default dispatch policy. Dispatch policy refers to the instance of WLS 9.0 Work Manager that you want to use for the service endpoint. For example, if the proxy service has a JMS transport protocol, the service endpoint is an MDB (message-driven bean) JAR file that you can associate with the specific dispatch policy. 3. In the Request encoding field, accept the default iso-8859-1 as the char set encoding for requests in HTTP transports, or enter a different char set encoding. 4. In the Response encoding field, accept the default iso-8859-1 as the char set encoding for responses in HTTP transports, or enter a different char set encoding.
HTTPS	1. In the Client Authentication field, select the client authentication method: None, Basic, or Client certificates. Warning: When you create an HTTPS proxy service endpoint that requires Basic Authentication, a transport-authorization policy is not automatically associated with the inbound endpoint URI. For Basic Authentication to be enforced, you must define a transport-authorization policy for the endpoint. To learn more, see Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide. 2. In the Dispatch Policy field, select a dispatch policy for this endpoint. Leave blank to use the default dispatch policy. Dispatch policy refers to the instance of WLS 9.0 Work Manager that you want to use for the service endpoint. For example, if the proxy service has a JMS transport protocol, the service endpoint is an MDB (message-driven bean) JAR file that you can associate with the specific dispatch policy. 3. In the Request encoding field, accept the default iso-8859-1 as the char set encoding for requests in HTTPS transports, or enter a different char set encoding. 4. In the Response encoding field, accept the default iso-8859-1 as the char set encoding for requests in HTTPS transports, or enter a different char set encoding.
JMS	1. In the Destination Type field, select Queue or Topic. 2. Select the Use SSL checkbox if the requests are made over a TLS/SSL connection or leave blank if they are not. TLS/SSL (Secure Sockets Layer) provides secure connections by allowing two applications connecting over a network to authenticate the other's identity and by encrypting the data exchanged between the applications. Authentication allows a server, and optionally a client, to verify the identity of the application on the other end of a network connection. Additionally, if the administrator has restricted access to individual JMS destinations (queues or topics) by setting access control on the JNDI entry for the destination, the Business Service must authenticate when looking up the entry in the JNDI tree with a username and password. 3. If you selected Queue in the Destination Type field, select the Is Response Required checkbox or leave it blank. This checkbox determines whether or not a response is expected after an outbound message is sent. When you select the checkbox, you must enter data in an additional field: Response URI. 4. In the Response URI field, enter a response URI in the format jms://host:port/MyFactory/MyQueue.This field is required if you selected Is Response Required. To target multiple servers, use the following URI format: jms://host1:port,host2:port/QueueConnectionFactory/DestName 5. In the Message Type field, select Bytes or Text. if you selected the Is Response Required field. 6. In the Request encoding field, accept the default utf-8 as the char set encoding for requests in JMS transports, or enter a different char set encoding. 7. In the Response encoding field, accept the default utf-8 as the char set encoding for requests in JMS transports, or enter a different char set encoding. 8. In the JMS service account field, select a service account to use for the JMS server connection. A service account is an alias resource for a User ID and its associated password. To learn more about service accounts, see Overview of Service Accounts. 9. In the Dispatch Policy field, select a dispatch policy for this endpoint. Default signifies the default dispatch policy. Dispatch policy refers to the instance of WLS 9.0 Work Manager that you want to use for the service endpoint. For example, if the proxy service has a JMS transport protocol, the service endpoint is an MDB (message-driven bean) JAR file that you can associate with the specific dispatch policy.
Email	1. In the Service Account field, enter a service account. This is a required field. 2. In the Polling Interval field, enter a polling interval, in seconds. This is a required field. 3. In the Email Protocol field, select POP3 or IMAP as the server type for the email account. This is a required field. 4. In the Read Limit field, specify the maximum number of messages to read per polling sweep. Enter 0 to specify no limit. This is a required field. 5. Select the Pass By Reference field to stage the file in the archive directory and pass it as a reference in the headers, or leave the field blank not to do this. 6. In the Post Read Action field, select what happens to a message after it has been read: Archive - the message is archived Delete - the message is deleted Move - the message is moved. Move is only available with the IMAP protocol. Note: This is a required field. 7. In the Attachments field, select how attachments are handled: Archive - Attachments are saved to the Archive Directory Ignore - Attachments are ignored This is a required field. 8. In the IMAP Move Folder field, enter the folder to which the message is moved if the Post Read Action field is set to Move. 9. In the Download Directory field, enter a temporary location for downloading the emails. This is a required field. 10. In the Archive Directory field, specify the path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field. 11. In the Error Directory field, enter the file system directory path to write the message and any attachments if there is a problem. This is a required field. 12. In the Request encoding field, accept the default iso-8859-1 as the character set encoding for requests in Email transports, or enter a different character set encoding.
File	1. In the File Mask field, enter the regular expression for the files to be picked. The default is *.*.This is a required field. 2. In the Polling Interval field, enter a polling interval, in seconds. The default is 60. This is a required field. 3. In the Read Limit field, specify the maximum number of messages to read per polling sweep. Enter 0 to specify no limit. The default is 10. This is a required field. 4. Select the Sort By Arrival checkbox to deliver events in the order of arrival, or leave blank not to do this. 5. Select the Scan SubDirectories checkbox to recursively scan all the directories or leave blank not to do this. 6. Select the Pass By Reference checkbox to stage the file in the archive directory and pass it as a reference in the headers, or leave the field blank not to do this. 7. In the Post Read Action field, select what happens to a message after it has been read: Archive - the message is archived Delete - the message is deleted This is a required field. 8. In the Stage Directory field, enter an intermediate directory to temporarily stage the files while processing them. This is a required field. 9. In the Archive Directory field, specify the path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field. 10. In the Error Directory field, enter the location where messages and attachments are posted if there is a problem. This is a required field. 11. In the Request encoding field, accept the default utf-8 as the char set encoding for requests in File transports, or enter a different char set encoding.
FTP	1. In the User Authentication field, select anonymous if the user of the FTP server is anonymous or select external_user if the user of the FTP server is an externally configured account. 2. In the Mail ID or Service Account field, enter the mail ID for the anonymous user if you selected anonymous in the User Authentication field, or enter the service account if you selected external_user in the User Authentication field. This is a required field if you selected external_user. 3. Select the Scan SubDirectories checkbox to recursively scan all the directories or leave blank not to do this. 4. Select the Pass By Reference checkbox to stage the file in the archive directory and pass it as a reference in the headers. 5. Select the Sort By Arrival checkbox to deliver events in the order of arrival. 6. Select the Remote Streaming checkbox to directly stream the ftp files from the remote server at the time of processing or leave blank not to do this. 7. In the Timeout field, enter the socket timeout interval, in seconds, before the connection is dropped. If you enter 0, there is no timeout. 8. In the Retry Count field, specify the number of retries for FTP connection failures. 9. In the File Mask field, enter the regular expression for the files to be picked. The default is *.*.This is a required field. 10. In the Polling Interval field, enter a polling interval, in seconds. The default is 60. This is a required field. 11. In the Read Limit field, specify the maximum number of messages to read per polling sweep. Enter 0 to specify no limit. The default is 10. This is a required field. 12. In the Post Read Action field, select what happens to a message after it has been read. This is a required field: Archive - the message is archived Delete - the message is deleted 13. In the Transfer Node field, select ascii or binary as the transfer mode. 14. In the Archive Directory field, specify the path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field. 15. In the Download Directory field, enter the directory on your local machine where files are downloaded during the file transfer. This is a required field. 16. In the Error Directory field, enter the location where messages and attachments are posted if there is a problem. This is a required field. 17. In the Request encoding field, accept the default utf-8 as the char set encoding for requests in File transports, or enter a different char set encoding.


 
Click Next.

If this service has operations, the Edit a Proxy Service - Operation Selection Configuration page is displayed. Continue in To Add a Proxy Service - Operation Selection Configuration.

If this service does not have operations, the General Configuration Review page is displayed. Continue in To Add a Proxy Service - General Configuration Review.

To Add a Proxy Service - Operation Selection Configuration

If this service has operations, the Operation Selection Configuration page is displayed when you click Next on the Protocol Transport Configuration page. This page enables you to select the selection algorithm to use to determine the operation called by this proxy service. This option is only available for SOAP or XML services defined from a WSDL.

The WSDL specification defines a default algorithm to compute which operation is called based on the type of the SOAP message received. However, there are cases (for example, performance issues, signature/encryption issues, or the default algorithm is not applicable) when you may need to select the operation based on other means.

AquaLogic Service Bus provides additional algorithms. Each of them follows the same pattern and are based on the evaluation of an expression to get a value that is then used to lookup the corresponding operation in a static table.

In the Selection Algorithm field, select one of the following:

Table 14-10 Selection Algorithm Field

Selection Algorithm	Description
Transport Header	If you select this selection algorithm, you can define the transport header that contains the lookup value.
WS-Addressing	If you select this selection algorithm, the lookup value is contained by the WS-Addressing Action tag located in the SOAP headers of the SOAP message.
SOAP Headers	If you select this selection algorithm, you can define an XPath expression evaluated against the SOAP headers, which allows you to get the lookup value.
SOAP Body Type	This is the default algorithm defined by the WSDL specification to compute which operation is called based on the type of the SOAP message received. Note: If the proxy service is configured for a Web service security pass-through scenario with an encrypted body, you cannot select the SOAP Body Type selection algorithm. A similar caveat applies to pass-through encrypted SOAP headers.


 

Note: If you are creating an XML service type based on a WSDL port or binding, the following selection algorithms are displayed on this page: Transport Header and Payload Type.

Note: Additional fields are displayed depending on the selection algorithm you select.

Based on the algorithm you selected in the Selection Algorithm field, do one of the following:

Table 14-11 Selection Algorithm Field

Selection Algorithm...	Complete These Steps...
Transport Header	1. In the Header Name field, enter the transport header that extracts the value used as a key to select the operation being invoked. 2. Under the Operation Mapping field, specify the value for each operation in the Value field. The value is used as the key of the operation. This is a required field.
WS-Addressing	Under the Operation Mapping field, specify the value for each operation in the Value field. The value is used as the key of the operation. This is a required field.
SOAP Headers	1. In the XPath Expression field, specify the XPath expression that extracts the value used as a key to select the operation being invoked. 2. Under the Operation Mapping field, specify the value for each operation in the Value field. The value is used as the key of the operation. This is a required field.
SOAP Body Type	There are no additional fields displayed for this selection algorithm.
Payload Type	There are no additional fields displayed for this selection algorithm.


 
Click Next.

The General Configuration Review page is displayed. Continue in To Add a Proxy Service - General Configuration Review.

Note: If the proxy service is created from a WSDL (port or binding) that has WS-Policies attached, the Web Services Security Configuration page is displayed when you click Next. This page displays read-only views of the effective request/response WS-Policy for all operations.

Do one of the following:

• Select Process WS-Security Header if you want the proxy service to behave as an active intermediary, which means it performs decryption, signature verification and so on.
• Leave Process WS-Security Header blank if you want the proxy service to behave as pass-through, which means the proxy service does not decrypt the message or verify the digital signature.

To learn more, see see Securing Inbound and Outbound Messages in the BEA AquaLogic Service Bus User Guide.

To Add a Proxy Service - General Configuration Review

The General Configuration Review page is displayed when you click Next on the Operation Selection Configuration page. This page enables you to review the configuration data that you have entered for this proxy service. If necessary, you can click Edit to make changes to the configuration before you save the proxy service.

• Do one of the following:
• To make a change to one of the configuration pages, click Edit for the appropriate page.
• To return to the previous page, click Back.
• To create the proxy service, click Save. The proxy service is created.

The Project View or Folder View page is displayed. The new proxy service is included in the list of resources.

• To disregard changes, click Cancel.

Note: After you create a proxy service, the next step is to configure its Message Flow. Message Flow defines the implementation of a proxy service. Message Flows can include pipeline pairs and the following nodes: Start, Route, Echo, and Branch. To learn more, see Overview of Message Flow and Viewing and Changing Message Flow.

Note: The new proxy service is saved 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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Generating WSDLs from a Proxy Service

When you create a proxy service based on a WSDL Binding, AquaLogic Service Bus sets the new service and port definitions in the WSDL generated for the proxy service. Regardless of whether you define a proxy service based on a WSDL port or a WSDL binding, the WSDL generated for the proxy service defines only a single port. If the service is generated from port X in the template WSDL, then port X is also defined in the generated WSDL. Any other ports defined in the template WSDL are not included in the generated WSDL. Furthermore, if you base the proxy service on a WSDL port, the generated WSDL uses that port name and preserves any WS-Policies associated with that port. The binding is determined from the port, and in turn, the port type is determined from the binding.

If the service is generated from binding Y in the template WSDL, the generated WSDL defines a new service and port (<service-name>QSService and <port-name>QSPort). None of the ports defined in the template WSDL are included in the generated WSDL.

If you base the service on a WSDL binding template, there may be multiple ports in that WSDL associated with that binding. Each port can use a different URL and have a different WS-Policy attached to it. Therefore, the generated WSDL uses the binding but generates an artificial port for that binding with no WS-Policy. For all WSDL-based services, the transport type and transport URL can be overwritten in the transport section of the service definition.

You can get the WSDL for an HTTP(S)-based proxy service by entering the URL for the service appended with ?WSDL in your browser's Address field.

Related Topics

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Deleting Proxy Services

Viewing and Changing Message Flow

 

---

Listing and Locating Proxy Services

The Summary of Proxy Services page enables you to view a list of proxy services. Proxy services are AquaLogic Service Bus definitions of Web services implemented locally on WebLogic Server. To learn more, see Overview of Proxy Services.

To List and Locate Proxy Services

From the left navigation pane, select Proxy Services from under Resource Browser. The Summary of Proxy Services page is displayed. It displays the following information for each business service. For a more detailed description of the properties, see Viewing and Changing Proxy Services:

Table 14-12 Summary of Proxy Services Page

Property	Description
Name	A unique name for the proxy service. The name is a link to the View Details page. To learn more, see Viewing and Changing Proxy Services.
Path	The path is the project name and the name of the folder in which the proxy service resides. It is a link to the project or folder that contains this resource. To learn more, see Viewing Project Details or Viewing Folder Details.
Options	The Options column displays the following: A Manage Monitoring icon. The icon is a link to the Manage Monitoring page, which enables you to view alerts for a specific service. To learn more, see Listing and Locating Alert Rules. An Edit Message Flow icon. The icon is a link that enables you to edit pipelines for a specific service. See Viewing and Changing Message Flow. A Delete icon that enables you to delete a specific service. To learn more, see Deleting Proxy Services. You cannot delete a resource if it is referenced by other resources in AquaLogic Service Bus. Instead of the Delete icon, a Delete icon with a red X is displayed for these resources.


 
To locate a specific proxy service, do one of the following:
• Filter by proxy service name. In the Name and Path fields, enter the name and path of the search target, then click Search. The path is the project name and the name of the folder in which the proxy service resides. The services matching the search criteria are displayed.
• Resort the list. Ascending and descending arrow buttons indicate sortable columns—in this case, the Name and Path columns. Click the button to change the sort order.
• Scroll through the pages. Use the controls in the lower right corner. Go to a page by selecting the page number or by using the arrow buttons to go to the next, previous, first, or last page.

Note: Click View All to display all proxy services.

Related Topics

Adding a Proxy Service

Viewing and Changing Message Flow

 

---

Viewing and Changing Proxy Services

The View Details page enables you to view and edit details of a specific proxy service. To learn more, see Overview of Proxy Services.

To View and Edit Details of a Proxy Service

Locate the proxy service. To learn more, see Listing and Locating Proxy Services.
Click the proxy service name.

The View Details page displays the following information

Table 14-13 View Details Page

Property	Description
Resource Name	The name of this proxy service.
References	The number of objects that this proxy service references. If such references exist, click the link to view a list of the objects. To learn more, see Viewing References.
Referenced by	The number of objects that reference this proxy service. If such references exist, click the link to view a list of the objects. To learn more, see Viewing References.
Description	A description of this proxy service, if one exists.


 

The View Details page displays the following General Configuration information:

Table 14-14 General Configuration Information

Property	Description
Service Type	The service type
Proxy Service Provider	The name of the proxy service provider


 

If the service type for this proxy service is Messaging Service, the page displays the following Message Type Configuration information:

Table 14-15 Message Type Configuration Information

Property	Description
Request Message Type	A message type for the request message: Binary, Text, MFL, or XML.
Response Message Type	A message type for the response message: None, Binary, Text, MFL, or XML.


 

The page displays the following Transport Configuration information:

Table 14-16 Transport Configuration Information

Property	Description
Protocol	The transport protocol
Endpoint URI	The endpoint URI
Get All Headers	Whether all the headers or a defined set of headers are retrieved from the transport


 

If the transport protocol is Email, the page displays the following Email Transport Configuration information:

Table 14-17 Email Transport Configuration Information

Property	Description
Email Protocol	A server type for the email account: pop3 imap
Service Account	The service account for this mail server
Polling Interval	A polling interval, in seconds.
Read Limit	The maximum number of messages read per polling sweep. 0 signifies no limit.
Pass By Reference	Whether or not the file is staged in the archive directory and passed as a reference in the headers
Post Read Action	Whether or not a message is archived, deleted or moved after it has been read: Archive - the message is archived Delete - the message is deleted Move - the message is moved Note: Move is only available with the IMAP protocol.
Attachments	Whether or not attachments are archived or ignored: Archive - Attachments are saved to the Archive Directory Ignore - Attachments are ignored
IMAP Move Folder	The folder to which the message is moved if the Post Read Action field is set to Move.
Download Directory	The temporary location for downloading emails.
Archive Directory	The path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field.
Error Directory	The file system directory path to write the message and any attachments if there is a problem.
Request encoding	Displays the char set encoding for requests in Email transports. The default is iso-8859-1.


 

If the transport protocol is File, the page displays the following File Transport Configuration information:

Table 14-18 File Transport Configuration Information

Property	Description
File Mask	The regular expression applied for this file to be picked.
Polling Interval	The polling interval, in seconds.
Encoding	The encoding of the file if the file is a text file.
Read Limit	The maximum number of messages to read per polling sweep. 0 signifies no limit.
Sort by Arrival	Whether or not events are delivered in the order of arrival.
Scan Subdirectories	Whether or not all the directories are recursively scanned.
Pass By Reference	Whether or not the file is staged in the archive directory and passed as a reference in the headers.
Post Read Action	Whether or not a message is archived or deleted after it has been read: Archive - the message is archived Delete - the message is deleted
Stage Directory	The intermediate directory where files are temporarily staged while they are processed.
Error Directory	The file system directory path to write the message and any attachments if there is a problem.
Archive Directory	The path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field.
Request encoding	Displays the char set encoding for requests in JMS transports. The default is utf-8.


 

If the transport protocol is FTP, the page displays the following FTP Transport Configuration information:

Table 14-19 FTP Transport Configuration Information

Property	Description
Mail ID / Service Account	The mail ID for an anonymous user or service account for an externally configured user.
Timeout	The socket timeout, in seconds
File Mask	The regular expression applied for this file to be picked.
Download Directory	The temporary location for downloading FTP files.
Scan Subdirectories	Whether or not all the directories are recursively scanned.
Pass By Reference	Whether or not the file is staged in the archive directory and passed as a reference in the headers.
Post Read Action	Whether or not a message is archived or deleted after it has been read: Archive - the message is archived Delete - the message is deleted
Archive Directory	The path to the archive location if the Post Read Action field is set to Archive. The Archive Directory field is also a required field if you have selected the Pass By Reference field.
Error Directory	The file system directory path to write the message and any attachments if there is a problem.
Retry Count	The number of retries for FTP connection failures.
Polling Interval	The polling interval, in seconds.
Read Limit	The maximum number of messages to read per polling sweep. 0 signifies no limit.
Sort By Arrival	Whether or not events are delivered in the order of arrival
Transfer Mode	The transfer mode: Binary or ASCII
Request encoding	Displays the char set encoding for requests in JMS transports. The default is utf-8.


 

If the transport protocol is HTTP, the page displays the following HTTP Transport Configuration information:

Table 14-20 HTTP Transport Configuration Information

Property	Description
Basic Authentication Required	Whether or not basic authentication is required: displays Enabled if it is required.
Request encoding	Displays the char set encoding for requests in HTTP transports. The default is iso-8859-1.
Response encoding	Displays the char set encoding for responses in HTTP transports. The default iso-8859-1.


 

If the transport protocol is HTTPS, the page displays the following HTTPS Transport Configuration information:

Table 14-21 HTTPS Transport Configuration Information

Property	Description
Client Authentication	The client authentication method: None, Basic, or Client Certificates.
Request encoding	Displays the char set encoding for requests in HTTPS transports. The default is iso-8859-1.
Response encoding	Displays the char set encoding for responses in HTTPS transports. The default iso-8859-1.


 

If the transport protocol is JMS, the page displays the following JMS Transport Configuration information.

Table 14-22 JMS Transport Configuration Information

Property	Description
Destination Type	The destination type: Queue or Topic.
Use SSL	Whether or not the requests are made over a TLS/SSL connection.
Is Response Required	Whether or not a response is expected after an outbound message is sent.
Request encoding	Displays the char set encoding for requests in JMS transports. The default is utf-8.
Response URI	A response URI in the format jms://host:port/factoryJndiName/destJndiName To target multiple servers, use the following URI format: jms://host1:port,host2:port/QueueConnectionFactory/DestName
JMS service account	The service account to use for the JMS server connection.


 

The page displays the following Operation Selection Configuration information:

Table 14-23 Operation Selection Configuration Information

Property	Description
Selection Algorithm	The selection algorithm that determines the operation called by this proxy service.
Header Name	If you selected Transport Header in the Selection Algorithm field for this proxy service, this field displays the transport header that extracts the value used as a key to select the operation being invoked.
XPath Expression	If you selected SOAP Headers in the Selection Algorithm field for this proxy service, this field displays the XPath expression that extracts the value used as a key to select the operation being invoked.
Operation Mapping	If you selected Transport Headers, WS-Addressing or SOAP Headers in the Selection Algorithm field for this proxy service, this field displays the value for each operation. The value is used as the key of the operation.


 

If you have not already done so, from the left navigation pane, under Change Center, click Create to create a new session or click Edit to enter an existing session to make changes to the current configuration. For more information, see Using the Change Center.
To make a change to the fields on the configuration pages, click Edit for the appropriate page. See Adding a Proxy Service for a description of the pages and fields.

Note: You cannot change the Service Name or Service Type fields.

Do one of the following:
• To return to the previous page, click Back.
• To update the proxy service, click Finish. The Proxy Service is updated.

The Summary of Proxy Services page is displayed.

• To disregard changes and return to the Summary of Proxy Services page, click Cancel.

Note: The proxy service 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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Adding a Proxy Service

Viewing and Changing Message Flow

Deleting Proxy Services

 

---

Deleting Proxy Services

The Summary of Proxy Services page enables you to delete a proxy service. To learn more, see Overview of Proxy Services.

Note: You cannot delete a resource if it is referenced by other resources in AquaLogic Service Bus. Instead of the Delete icon, a Delete icon with a red X is displayed for these resources.

Note: You must delete all service-level access control policies and transport-level access control policies associated with a proxy service before you delete that service from AquaLogic Service Bus.

To Delete a Proxy Service

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.
From the left navigation pane, select Proxy Services from under Resource Browser. The Summary of Proxy Services page is displayed.
In the Options field of the proxy service you want to delete, click the Delete icon.

The proxy service is removed from the list.

Note: If necessary, you can undo the deletion of this resource. To learn more, see Undoing a Task.

The proxy service is deleted 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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Adding a Proxy Service

Viewing and Changing Proxy Services

Viewing and Changing Message Flow

 

---

Overview of Message Flow

Message Flow defines the implementation of a proxy service. Message Flows can include pipeline pairs and the following nodes: Start, Route, Echo, and Branch. To learn how to implement Message Flow, see Viewing and Changing Message Flow.

This section includes the following topics:

• Pipelines
• Message Execution
• Building a Message Flow Tree
• Operational Branching

Pipelines

A pipeline is a named sequence of stages representing a non-branching one-way processing path.

Pipelines are typed into one of three categories:

Table 14-24 Pipeline Categories

Pipeline Category	Description
Request	Request pipelines are used for processing the request path of the Message Flow.
Response	Response pipelines are used for processing the response path of the Message Flow.
Error	Error pipelines are used as error handlers.

 

To create the request and response paths, request and response pipelines are paired together and organized into a single-rooted tree structure. A branch node allows you to conditionally execute these pipeline pairs, and route nodes at the ends of the branches perform any request/response dispatching. This tree structure allows for a clear overview of the Message Flow behavior, making both route actions and branch conditions explicit parts of the overall design, rather than burying them deep inside a pipeline stage.

A message flow tree is constructed by chaining together instances of these top-level components:

Table 14-25 Pipeline Categories

Pipeline Category	Description
Pipeline pair node	The pipeline pair node ties together a single request and a single response pipeline into one top-level element. A pipeline pair node may have only 1 direct descendant in the message flow tree. During request processing, only the request pipeline is executed when visiting a pipeline pair node. When reversing the path for response processing, only the response pipeline is executed. To learn how to add a pipeline pair node, see Adding a Pipeline Pair Node.
Branch node	A branch node allows processing to proceed down exactly one of several possible paths. Branching is driven by a simple lookup table with each branch tagged with a simple but unique string value. A variable in the message context is designated as the lookup variable for that node, and its value is used to determine which branch to follow. If no branch matches the value of the lookup variable, then the always-present default branch is followed. Setting the value of the lookup variable must be done before reaching the branch node. This approach ensures that exceptions do not occur within the branch node itself. A branch node may have several descendants in the message flow tree: one for each branch including the default branch. To learn how to add a branch node, see Adding a Conditional Branch Node.
Route node	The route node is used to perform request/response communication with another service. It represents the boundary between request and response processing for the proxy. When the route node dispatches a request message, request processing is considered finished. When the route node receives a response message, response processing begins. The route node itself has support for conditional routing as well as outbound and response transformations. You can choose whether conditions appear inside the route node or up in the message flow tree as branch nodes—it depends upon whether the condition is important enough to call out as part of the message flow tree structure. As the route node represents the boundary between request and response processing, it cannot have any descendants in the message flow tree. To learn how to add a route node, see Adding a Route Node.
Echo node	An echo node is a node that routes (or echoes) a message from the end of the request pipeline to the start of the response pipeline. In other words, the message is not routed from the proxy service to another service. It remains within the proxy service.

 

Message Execution

The following table demonstrates the journey of a message:

Table 14-26 Message Journey

Node	What Happens to the Message?
Request Processing	Request processing begins at the root of the message flow tree
Pipeline Pair	Executes the request pipeline only
Branch	Evaluates the lookup table and proceeds down the relevant branch
Route	Performs the route along with any outbound/response transformations. Note: Whether or not any routing is performed, the route node represents a change from request processing to response processing. When a response comes in, it reverses the path it took for the request. The same thing occurs for any request path that ends without a route node - it initiates response processing and walks back up the tree, but without waiting for any response.
Response Processing	See Route.
Pipeline Pair	Executes the response pipeline
Branch	Continues with the element that preceded the branch
Root of the Tree	Sends the response back to the client

 

Building a Message Flow Tree

Any element may appear at the root of the message flow tree. One of the simplest of Message Flow designs is to have just a route node at the top representing the entire tree. There is also no restriction on what two elements may be chained together. For example, two pipeline pair nodes may be chained together without a branching node in between. With regards to branching, each branch may start with a different element - one branch may immediately terminate with a route node, another may be followed by a pipeline pair and yet another may have no descendant whatsoever. In the latter case, a branch with no descendants means that response processing begins immediately if that branch is selected. In general, however, a message flow tree is likely to come in two forms: for non-operational services, the tree is likely to consist of a single pipeline pair at the root followed by a route node. For operational services, the tree is likely to consist again of a single pipeline pair at the root, followed by a branch node based on operation, with each branch consisting of a pipeline pair followed by a route node.

Operational Branching

Since Message Flow is typically used with WSDL-based services, there is frequently a need to perform processing that is operation-specific. Rather than requiring you to manually configure a branching node based on operation, AquaLogic Service Bus provides a zero-configuration branching node that automatically branches based on operation. A branch is created for each operation defined on the service; the branching variable is $operation.

To learn how to add an operational branch node, see Adding an Operational Branch Node.

Related Topics

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Adding a Stage

Adding an Action

Adding Route Node Actions

 

---

Viewing and Changing Message Flow

The Edit Message Flow page enables you to view and change the Message Flow of a specific proxy service. To learn more about Message Flow, see Overview of Message Flow. To learn more about proxy services, see Overview of Proxy Services.

To View and Change the Message Flow

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.
From the left navigation pane, select Proxy Services under Resource Browser. The Summary of Proxy Services page is displayed.

Alternatively, you can select a project or folder from under Project Explorer to display the project or folder's list of resources.

On the Summary of Proxy Services page, click the Edit Message Flow icon for the appropriate proxy service.

Alternatively, if you selected a project or folder, click the Edit Message Flow icon for the appropriate proxy service in the list of resources.

The Edit Message Flow page is displayed. The page includes the following functionality:

• An icon that signifies the Start node for the proxy service, which you can click to add pipeline pair nodes, route nodes, and conditional and operational branches, and error handling for the service.
• An icon that signifies the Echo node (End node) for the proxy service, which you can convert to a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow. Click the name of an object to display the page associated with that object. When you add objects, the left navigation pane adds the appropriate links to the Message Flow map. If you have not yet constructed the Message Flow for this proxy service, the Message Flow contains links to the Edit Message Flow page only.
Do one of the following:

Table 14-27 Edit Message Flow Page

To...	Complete This Step...
Add a pipeline pair node	Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node.
Add a route node	Click the Start Node icon, then click Add Route Node. To learn more, see Adding a Route Node.
Add a conditional branch node	Click the Start Node icon, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node.
Add an operational branch node	Click the Start Node icon, then click Add Operational Branch Node. To learn more, see Adding an Operational Branch Node.
Add error handling for this proxy service	Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
Convert the echo node to a route node	Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node.
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.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Deleting Proxy Services

Adding a Stage

Adding an Action

Adding Route Node Actions

 

---

Adding a Pipeline Pair Node

The Edit Message Flow page enables you to add a pipeline pair node. A pipeline pair node consists of a request pipeline and a response pipeline. Message Flows can include zero or more pipeline pair nodes: request and response pipelines for the proxy service (or for the operations on the service), and error handler pipelines that can be defined for stages, pipelines, and proxy services. Pipelines can include one or more stages, which in turn include actions. To learn more, see Overview of Message Flow.

To Add a Pipeline Pair Node

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 in the Resource Browser, 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 for the proxy service you selected. The page includes the following functionality:

• An icon that signifies the Start node for the proxy service, which you can click to add pipeline pair nodes, route nodes, and conditional and operational branches, and error handling for the service.
• An icon that signifies the Echo node (End node) for the proxy service, which you can convert to a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
Click the Start Node icon, then click Add Pipeline Pair.

The Pipeline Pair Node icon and the Name and Description fields are displayed.

In the Name field, enter a name for the pipeline pair node.
In the Description field, enter a description of the pipeline pair node.
Do one of the following:
• To save the pipeline pair node, click Save.

The Pipeline Pair Node icon and the name you assigned to the pipeline pair node are displayed on the Edit Message Flow page.

• To disregard changes and return to the Summary of Proxy Services page, click Cancel.
When you save the pipeline pair node, do one of the following:

Table 14-28 Pipeline Pair Node

To...	Complete This Step...
Add a stage to a pipeline	Click the appropriate request or response pipeline, then click Add Stage. To learn more, see Adding a Stage.
Add actions to a pipeline	Click the Stage icon for the appropriate pipeline (if you have already created a stage), click Edit, then click Stage. To learn more, see Adding an Action.
Add another pipeline pair node	Click the Pipeline Pair Node icon for the pipeline pair you created, click Add, then click Add Pipeline Pair. Alternatively, you can click the Start Node icon again, then click Add Pipeline Pair.
Add a route node	Click the Pipeline Pair Node icon for the pipeline pair you created, click Add, then click Add Route Node. To learn more, see Adding a Route Node.
Add a conditional branch node	Click the Pipeline Pair Node icon for the pipeline pair you created, click Add, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node.
Add error handling for this proxy service	Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
Convert the echo node to a route node	Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node.
Edit the name and description of the pipeline pair node	Click the Pipeline Pair Node icon for the pipeline pair you created, click Edit, then click Name and Description. Note: When you rename a pipeline or a route node, the number of messages displayed on the Dashboard page in the Monitoring module may not correlate with those of other components due to the pipeline counters being reset to zero. This is because AquaLogic Service Bus treats the rename as a delete and recreate action. The numbers should correlate again after a time period equal to the service's monitoring interval has elapsed.
Delete the pipeline pair node	Click the Pipeline Pair Node icon for the pipeline pair you created, 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.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

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

 

---

Adding a Conditional Branch Node

The Edit Message Flow page enables you to add a conditional branch node. A branch node allows processing to proceed down exactly one of several possible paths. To learn more, see Overview of Message Flow.

To Add a Conditional Branch Node

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 for the proxy service you selected. The page includes the following functionality:

• An icon that signifies the Start node for the proxy service, which you can click to add pipeline pair nodes, route nodes, and conditional and operational branches, and add error handling for the service.
• An icon that signifies the Echo node (End node) for the proxy service, which you can convert to a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
• If you have already added a pipeline pair node or service error handler, these icons are displayed.
Click the Start Node icon, then select Add Conditional Branch Node. Alternatively, you can click the Pipeline Pair Node icon of an existing pipeline pair, click Add, then click Add Conditional Branch Node.

The Conditional Branch Node icon and the Name and Description fields are displayed.

In the Name field, enter a name for the branch node.
In the Description field, enter a description of the branch node.
Do one of the following:
• To save the branch node, click Save.

The Conditional Branch Node icon and the name you assigned to the branch node are displayed.

• To disregard changes, click Cancel.
To add branch definitions, select the branch node, click Edit, then click Branch Node. The Edit a Branch page is displayed.
In the Branch Definitions panel, do the following:
In the Selected Path field, click Edit to add an XPath expression. To learn more, see Editing an XPath Expression.
In the Variable field, enter a context variable.
In the Operator field, select =, !=, <, >, <=, or >=.
In the Value field, enter a value for the branch.
In the Label field, enter a label for the branch.
Do one of the following:

Table 14-29 Adding a Conditional Branch Node

To...	Complete This Step...
Add another branch definition	Click Add a New Branch from the flyout menu of the Options column.
Delete a branch definition	Click Delete this Branch from the flyout menu of the Options column.
Move a branch down the list of definitions	Click Move Branch Down from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.
Move a branch up the list of definitions	Click Move Branch Up from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.


 
When you have finished working with the definitions, do one of the following:
• To update the branch, click Save.

The Edit Message Flow page is displayed.

• To disregard changes and return to the Edit Message Flow page, click Cancel.
• To disregard changes and remain on the Edit a Branch page, click Clear.
When you save the branch node, do one of the following:

Table 14-30 Adding a Conditional Branch Node

To...	Complete This Step...
Add a pipeline pair node	Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node.
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 actions to an existing pipeline	Click the Stage icon for the appropriate pipeline, click Edit, then click Stage. To learn more, see Adding an Action.
Add error handling for this proxy service	Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
Edit the branch node name and description	Click the Conditional Branch icon, click Edit, then click Name and Description.
Edit the branch definitions	Click the Conditional Branch icon, click Edit, then click Branch Node.
Delete the branch node	Click the Conditional Branch icon, then click Delete Branch Node.
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.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Viewing and Changing Message Flow

Overview of Proxy Services

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

 

---

Adding an Operational Branch Node

The Edit Message Flow page enables you to add an operational branch node.

To Add an Operational Branch Node

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 for the proxy service you selected. The page includes the following functionality:

• An icon that signifies the Start node for the proxy service, which you can click to add pipeline pair nodes, route nodes, and conditional and operational branches, and add error handling for the service.
• An icon that signifies the Echo node (End node) for the proxy service, which you can convert to a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
• If you have already added a pipeline pair node or service error handler, these icons are displayed.
Click the Start Node icon, then select Add Operational Branch Node. The Operational Branch icon and the Name and Description fields are displayed.
In the Name field, enter a name for the branch.
In the Description field, enter a description of the branch.
Do one of the following:
• To save the branch, click Save.

The Operational Branch icon and the name you assigned to the branch are displayed.

• To disregard changes, click Cancel.
To add branch definitions, select the branch node, click Edit, then click Branch Node. The Edit a Branch page is displayed.
In the Operation Branch Definitions panel, select a service operation.
Do one of the following:

Table 14-31 Adding an Operational Branch Node

To...	Complete This Step...
Add another branch definition	Click Add a New Branch from the flyout menu of the Options column.
Delete a branch definition	Click Delete this Branch from the flyout menu of the Options column.
Move a branch down the list of definitions	Click Move Branch Down from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.
Move a branch up the list of definitions	Click Move Branch Up from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.


 
When you have finished working with the definitions, do one of the following:
• To update the branch, click Save.

The Edit Message Flow page is displayed.

• To disregard changes and return to the Edit Message Flow page, click Cancel.
• To disregard changes and remain on the Edit a Branch page, click Clear.
When you saved the branch node, do one of the following:

Table 14-32 Adding an Operational Branch Node

To...	Complete This Step...
Add a pipeline pair node	Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node.
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 actions to an existing pipeline	Click the Stage icon for the appropriate pipeline, click Edit, then click Stage. To learn more, see Adding an Action.
Add a conditional branch node	Click the Start Node icon, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node.
Add a route node	Click the Start Node icon, then click Add Route Node. To learn more, see Adding a Route Node.
Add error handling for this proxy service	Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
Edit the branch node name and description	Click the Operational Branch icon, click Edit, then click Name and Description.
Edit the branch definitions	Click the Operational Branch icon, click Edit, then click Branch Node.
Delete the branch node	Click the Operational Branch icon, then click Delete Branch Node.
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.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Viewing and Changing Message Flow

Overview of Proxy Services

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

 

---

Adding a Stage

The Edit Message Flow page enables you to add a stage. A stage is a container of actions. To learn more, see Overview of Message Flow.

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

To Add a Stage

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 pair node to view the pipeline pair, which consists of request and response pipelines.
Click the pipeline to which you want to add the stage, then click Add Stage.

The Stage icon and the Name and Description fields are displayed.

In the Name field, accept the default name for the stage or enter a different name.
In the Description field, enter a description of the stage.
Do one of the following:
• To save the stage, click Save.

The Stage icon and the name you assigned to the stage are displayed on the Edit Message Flow page.

• To disregard changes and return to the Edit Message Flow page, click Cancel.
When you save the stage, do one of the following:

Table 14-33 Adding a Stage

To...	Complete This Step...
Add actions	Click the Stage icon, click Edit, then click Stage. To learn more, see Adding an Action.
Add error handling for this pipeline	Click the pipeline, then click Add Pipeline Error Handler. To learn more, see Adding Pipeline Error Handling.
Add another pipeline pair	Click the Start Node icon, then click Add Pipeline Pair. Alternatively, you can click an existing Pipeline Pair Node icon, click Add, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node.
Add a route node	Click the Pipeline Pair Node icon, click Add, then click Add Route Node. To learn more, see Adding a Route Node.
Add a conditional branch node	Click the Pipeline Pair Node icon, click Add, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node.
Add error handling for this proxy service	Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
Convert the echo node to a route node	Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Delete a stage	Click the appropriate Stage icon, then click Delete.
Save the updates and return to the Summary of Proxy Services page	Click Save.
Disregard changes and return to the Summary of Proxy Services page	Click Cancel.
Clear the unsaved changes and remain on the Edit Message Flow page	Click Clear.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Viewing and Changing Message Flow

Viewing and Changing Stage Configuration Details

Overview of Proxy Services

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

 

---

Adding an Action

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

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

To Add an Action

If you have not already done so, from the left navigation pane, under Change Center, click Create to create a new session for making changes to the current configuration. To learn more, see Using the Change Center.
On the Summary of Proxy Services page, click the Edit Message Flow icon for the appropriate proxy service. Alternatively, if you are in the Project Explorer module, click the Edit Message Flow icon for the appropriate proxy service in the list of resources for a selected project or folder.

The Edit Message Flow page is displayed.

Expand an existing pipeline to view the pipeline, which consists of request and response pipelines.
Click the Stage icon of an existing stage to which you want actions, click Edit, then click Stage. The Edit Stage Configuration page is displayed.
To add an action, click Add an Action, then select an action type. The list of action types and the procedures to configure them are displayed in the following table.

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

Table 14-34 Adding an Action

To...	Complete These Steps...
Assign	Assign the result of an XQuery expression to a context variable: 1. Click Add an Action, then select Assign. The Assign action is displayed, which includes the following functionality: An Assign icon An Expression link that you can click to edit an XQuery expression A variable field in which you can enter a context variable 2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression 3. When you have finished editing the expression, enter a context variable in the variable field. To learn more about context variables, see Message Context. 4. Continue to the next step.
Delete	Delete a context variable or all the nodes specified by an XPath expression: 1. Click Add an Action, then select Delete. The Delete action is displayed, which includes the following functionality: A Delete icon 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. 2. To delete a context variable, select the radio button associated with this option, then enter 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 this option, then click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. When you have saved the expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context. 3. Continue to the next step. Note: The Delete action is one of a set of Update actions. To learn more, see Update Actions.
If... Then...	Perform if then else actions based on the Boolean result of an XQuery expression: 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 (to the last publish table), the conditional is not displayed. 1. Click Add an Action, then select If... Then... The If... Then... action is displayed, which includes the following functionality: An If...Then... icon. If... condition then... , which is a link from which you can edit the condition. An Add an Action option 2. Click Condition. The Edit an XQuery Condition page is displayed. To learn more, see Editing an XQuery Condition. 3. When you have finished 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 the appropriate procedure in this table. 4. If necessary, 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. Continue to the next step.
Insert	Insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression: 1. Click Add an Action, then select Insert. The Insert action is displayed, which includes the following functionality: An Insert icon An Expression link that you can click to edit an XQuery expression A drop-down list from which you can select the relative location An XPath link that you can click to edit an XPath expression An in variable field in which you can enter a context variable 2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 3. When you have finished 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/attribute selected by the XPath expression After - as sibling after each element/attribute selected by the XPath expression As first child of - as first child of each element (error if XPath identifies attributes) identified by the XPath expression As last child of - as last child of each element (error if XPath identifies attributes) identified by the XPath expression 4. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 5. When you have finished editing the XPath expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context. 6. Continue to the next step. Note: XQuery and XPath expressions must both return elements. However, if the XPath expression does not return elements, then the XQuery expression must return attributes. Note: The Insert action is one of a set of Update actions. To learn more, see Update Actions.
Log	Define a set of attributes with which the message is logged: 1. Click Add an Action, then select Log. The Log action is displayed, which includes the following functionality: A Log icon An Expression link, which you can click to edit an XQuery expression An Annotation field in which you can enter notes for this log action. The 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 2. Click Expression. The Edit an XQuery Expression page is displayed. You specify the message context to be logged through XQuery expressions on context variables. To learn more, see Editing an XQuery Expression. 3. In the Annotation field, enter notes for this log action. 4. In the severity level drop-down list, select one of the following levels: Info Warning Error Debug 5. Continue to the next step.
Publish	Identify a target service for the message and configure how the message is packaged and sent to that service: 1. Click Add an Action, then select Publish. The Publish action is displayed, which includes the following functionality: A Publish icon A Service link that you can click to select a service A field 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. 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 the appropriate procedure in this table. 5. Continue adding actions as necessary. When you have finished adding request actions, continue to the next step. Note: When a message is published to another service as the result of a Publish or Publish Table action, the default quality of service (QoS) is best effort, if the proxy service inbound transport and the outbound publish action use the JMS/XA transport. Best effort meaning that there is no reliable messaging and there is no elimination of duplicate messages—however, performance is optimized. To override the default best effort quality of service attribute, you must set the qualityOfService in the outbound message context variable ($outbound). For more information, see Message Context Schema. For information about exactly once reliability, see Adding a Route Node. For mor einformation about quality of service, see Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide. Note: Each publish request transformation maintains its own local copy of message context. For more information, see Example Scenarios in Constructing Messages to Dispatch.
Publish Table	A publish table is a set of routes wrapped in a switch-style condition table. It is a short-hand construct that allows different routes to be selected based upon the results of a single XQuery expression. 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. Identify target services for messages and configure how the messages are packaged and sent to these services: 1. Click Add an Action, then select Publish Table. The Publish Table action is displayed, which includes the following functionality: A Publish Table icon, an Expression link in which you can edit an XQuery expression, a Diamond icon that you can use to insert new cases, a field in which you can enter a comparison operator, a field in which you can enter a value, a A Service link that you can click to select a service, and a field in which you can add request actions. 2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 3. Select one of these comparison operators: =, !=, < or >. 4. Enter a value in the field provided. 5. Click Service. 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. 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 type of action you want to add, see the appropriate procedure in this table. 8. Continue adding actions as necessary. When you have finished adding actions, continue to the next step. 9. To insert a new case, click the Diamond icon, then select Insert New Case. 10. Repeat steps 3-8 for the new case. Note: Click the Diamond icon of the last defined case, then select Insert Default Case to add a default case at the end whose routes are selected if none of the preceding cases is satisfied. 11. When you have finished adding cases, continue to the next step.
Raise Error	Raise an exception with a specified error code (a string) and description: 1. Click Add an Action, then select Raise Error. The Raise Error action is displayed, which includes the following functionality: A Raise Error icon 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 field below the error message field, enter a description of the error code. 4. Continue to the next step. Note: To learn more about error handling actions, see Error Messages and Handling.
Rename	Rename elements selected by an XPath expression without modifying contents: 1. Click Add an Action, then select Rename. The Rename action is displayed, which includes the following functionality: A Rename icon An XPath link that you can click to edit an XPath expression An in variable field localname, namespace, and combined localname and namespace radio buttons and fields 2. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 3. Enter a context variable in the in variable field. To learn more about context variables, see Message Context. 4. 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. The XPath expression must select elements, not attributes. 5. Continue to the next step. Note: The Rename action is one of a set of Update actions. To learn more, see Update Actions.
Replace	Replace nodes specified by an XPath expression with the result of an XQuery expression: 1. Click Add an Action, then select Replace. The Replace action is displayed, which includes the following functionality: A Replace icon An XPath link that you can click to edit an XPath expression An Expression link that you can click to edit an XQuery expression An in variable field in which you can enter a context variable Two Replace Node radio buttons 2. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 3. When you have finished editing the XPath expression, enter a context variable in the in variable field. To learn more about context variables, see Message Context.. 4. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 5. When you have finished editing the XQuery expression, select the Replace entire node radio button to replace the nodes your XPath expression selects along with all of its contents, or select the Replace node contents radio button to leave the nodes in place and only replace their contents. 6. Continue to the next step. Note: The Replace action can be used to replace simple values or elements (XQuery expressions cannot return attributes). If the XPath identifies attributes, then the XQuery expression must evaluate to a simple value. An XQuery expression that returns nothing is equivalent to making the identified nodes empty or deleting the identified attributes. 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 ./*. Note: The Replace action is one of a set of Update actions. To learn more, see Update Actions.
Reply	The Reply action can be used in the request, response or error pipeline. It has an option of replying with success or failure. If failure, for SOAP, a HTTP 500 error is returned. Immediately reply to the invoker: 1. Click Add an Action, then select Reply. The Reply action is displayed, which includes the following functionality: A Reply icon With Success and With Failure radio buttons 2. Select the With Success radio button to reply that the message was successful or select the With Failure radio button to reply that the message has a fault. 3. Continue to the next step. Note: To learn more about error handling actions, see Error Messages and Handling.
Report	Enable message reporting for this proxy service: 1. Click Add an Action, then select Report. The Report action is displayed, which includes the following functionality: A Report icon An Expression link that you can click to edit an XQuery expression A field in which you can add key names and key values 2. Click Expression. The Edit an XQuery Expression page is displayed. To learn more, see Editing an XQuery Expression. 3. When you have finished editing the XQuery expression, click Add a Key. Two additional 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. 4. Enter a key name in the Key Name field. 5. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 6. Enter a context variable in the in variable field. To learn more, see Message Context. 7. 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. 8. When you have finished adding key values, continue to the next step.
Skip	Skip execution of this stage and proceed to the next stage: Note: This action has no parameters and can be used in the request, response or fault pipelines: 1. Click Add an Action, then select Skip. The Skip icon is displayed. 2. Continue to the next step.
Validate	Validate elements selected by an XPath expression against a top level XML schema element or WSDL resource: 1. Click Add an Action, then select Validate. The Validate action is displayed, which includes the following functionality: A Validate icon An XPath link that you can click to edit an XPath expression An in variable field in which you can enter an element A resource link from which you can select a type or element from an XML Schema or WSDL 2. Click XPath. The Edit an XPath Expression page is displayed. To learn more, see Editing an XPath Expression. 3. When you have finished editing the XPath expression, enter an element in the in variable field. 4. Click resource, then select WSDL or XML schema. Depending on what you select, the WSDL Browser or XML Schema Browser is displayed. 5. Select the WSDL or XML schema, select the WSDL or XML schema type or element, then click Submit. 6. To save the boolean result of this validation, select the radio button associated with this option and enter a variable in the Save result of validation in variable field. Alternatively, to raise an error if the element fails validation against the WSDL or XML schema element, select the Raise Error on validation failure radio button. 7. Continue to the next step. Note: The Validate action enables you to validate Global elements only; AquaLogic Service Bus does not support validation against local elements.
Web Service Callout	Populate context by specifying a service and operation, and enter context variables to bind to the invocation input and output parameters: 1. Click Add an Action, then select Web Service Callout. The Web Service Callout action is displayed, which includes the following functionality: A Web Service Callout icon A Service link that you can click to select a service Request and Response Parameters fields 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. Note: The service must have a WSDL with a SOAP or XML over HTTP or HTTPS binding without attachments. 4. In the Request Document Variable field, enter a request document variable. 5. In the Response Document Variable field, enter a response document variable. 6. Continue to the next step.

 

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 Step 6. There is no restriction on what actions may be chained together.

When you have finished adding actions, continue to the next step.

Do one of the following:

Table 14-35 Adding an Action

To...	Complete This Step...
Delete an action	Click the appropriate icon, then click Delete this Action. The action is deleted.
Move an action down	Click the appropriate icon, then click Move Action Down. The action is moved below the next action contained in this stage. Note: This option is displayed only when there are two or more actions contained in the stage.
Move an action up	Click the appropriate icon, then click Move Action Up. The action is moved above the previous action contained in this stage. Note: This option is displayed only when there are two or more actions contained in the stage.
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.


 
When you save the actions, do one of the following:

Table 14-36 Adding an Action

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 Start Node icon, then click Add Pipeline Pair. Alternatively, click an existing Pipeline Pair Node icon, click Add, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node.
Add a route node	Click the Pipeline Pair Node icon, click Add, then click Add Route Node. To learn more, see Adding a Route Node.
Add a conditional branch node	Click the Pipeline Pair Node icon, click Add, then click Add Conditional Branch Node. To learn more, see Adding a Conditional Branch Node.
Add error handling for this proxy service	Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
Convert the echo node to a route node	Click the Echo Node icon, then click Convert to Route Node. To learn more, see Adding a Route Node.
Edit the stage name and description	Click the appropriate Stage icon, click Edit, then click Name and Description.
Delete a stage	Click the appropriate Stage icon, then click Delete.
Save the updates and return to the Summary of Proxy Services page	Click Save.
Disregard changes and return to the Summary of Proxy Services page	Click Cancel.
Clear the changes and remain on the Edit Message Flow page	Click Clear.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Update Actions

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

• The XPath expression you configure for any update actions is evaluated to select the nodes in the message on which to operate.
• In the case of Insert and Replace actions, you configure an XQuery expression, which is evaluated to determine the data to insert or replace.
• For each node identified by the evaluation of the XPath expression, the appropriate action on that node is performed. In other words:
• Delete the variable or the node in the variable identified by the XPath expression
• Rename the node identified by the XPath expression
• Replace the node (or the contents of the node) identified by the XPath expression with the value returned by the XQuery expression
• Insert the value returned by the XQuery expression before, after, or as a child of the node identified by XPath expression

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

 

---

Adding a Route Node

The Edit Message Flow page enables you to add a route node. The route node is used to perform one way communication, such as using file or email transport. It represents the boundary between request and response processing for the proxy service. When the route node dispatches a request message, request processing is considered finished. When the route node receives a response message, response processing begins. To learn more about Message Flow, see Overview of Message Flow.

AquaLogic Service Bus supports reliable messaging. When messages are routed to another service from a route node, the default quality of service (QoS) is exactly once if the proxy service transport is defines as JMS/XA; otherwise best effort QoS is supported. Exactly once reliability means that messages are delivered from inbound to outbound exactly once, assuming a terminating error does not occur before the outbound message send is initiated. The exactly once delivery reliability is a hint, not a directive. When exactly once is specified, exactly once reliability is provided if possible. If exactly once is not possible, then at least once delivery semantics are attempted; if that is not possible, best effort delivery is performed.

At least once semantics means the message is delivered to the outbound from the inbound at least once, assuming a terminating error does not occur before the outbound message send is initiated. Delivery is considered satisfied even if the target service responds with a transport-level error. However it is not satisfied in the case of a timeout, a failure to connect, or a broken communication link. If fail over URLs are specified, at least once semantics is provided with respect to at least one of the URLs.

Best effort means that there is no reliable messaging and there is no elimination of duplicate messages—however, performance is optimized.

To override the default exactly once quality of service attribute, you must set the qualityOfService in the outbound message context variable ($outbound). For more information, see Message Context Schema.

To Add a Route Node

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 for the proxy service you selected. The page includes the following functionality:

• An icon that signifies the Start node for the proxy service, which you can click to add pipeline pair nodes, route nodes, and conditional and operational branches, and add error handling for the service.
• An icon that signifies the Echo node (End node) for the proxy service, which you can convert to a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
• If you have already added a pipeline pair node or service error handler, these icons are displayed.
To add a route node, do one of the following:
• Click the Start Node icon, then select Add Route Node.
• Click the Pipeline Pair Node icon of an existing pipeline pair, click Add, then click Add Route Node.

The Route Node icon and the Name and Description fields are displayed.

• Click the Echo Node icon, then select Convert to Route Node.

The Route Node icon and the Name and Description fields are displayed.

In the Name field, enter a name for the route node.
In the Description field, enter a description of the route node.
Do one of the following:
• To save the route node, click Save.

The Route Node icon and the name you assigned to the route node are displayed on the Edit Message Flow page.

• To disregard changes and return to the Message Flow, click Cancel.
Click the route node, click Edit, then click Route Node. The Edit Stage Configuration page is displayed. Continue in Adding Route Node Actions.
When you have finished adding routing node actions and saved the route node, do one of the following:

Table 14-37 Adding a Route Node

To...	Complete This Step...
Add a pipeline pair node	Click the Start Node icon, then click Add Pipeline Pair. To learn more, see Adding a Pipeline Pair Node.
Add error handling for this proxy service	Click the Start Node icon, then click Add Service Error Handler. To learn more, see Adding Error Handling for the Proxy Service.
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 actions to an existing pipeline	Click the Stage icon for the appropriate pipeline, then click Edit Stage. To learn more, see Adding an Action.
Edit the route node name and description	Click the Route Node icon, click Edit, then click Name and Description. Note: When you rename a pipeline or a route node, the number of messages displayed on the Dashboard page in the Monitoring module may not correlate with those of other components due to the pipeline counters being reset to zero. This is because AquaLogic Service Bus treats the rename as a delete and recreate action. The numbers should correlate again after a time period equal to the service's monitoring interval has elapsed.
Edit the route node actions	Click the Route Node icon, click Edit, then click Route Node.
Convert the route node to an echo node	Click the Route Node icon, then click Convert to Echo Node.
Add an error handler for the route node	Click the Route Node icon, then click Add Error Handler. To learn more, see Adding Error Handling for the Route Node.
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.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

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

Modeling Message Flow in AquaLogic Service Bus in the BEA AquaLogic Service Bus User Guide.

 

---

Adding Route Node Actions

The Edit Stage Configuration page enables you to add route node actions when you click Edit, then click Route Node on the Edit Message Flow page. Route node actions define the handling of messages as they flow through the route node of the proxy service. To learn more about Message Flow, see Overview of Message Flow.

To Add a Route Node 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.

Click the Route Node icon, click Edit, then click Route Node. The Edit Stage Configuration page is displayed.
To add a route node action, click Add an Action, then select an action type. The list of action types and the procedures to configure them are displayed in the following table.

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

 

Table 14-38 Adding Route Node Actions

To...	Complete These Steps...
If... Then...	Assign if then else actions based on the Boolean result of an XQuery expression: 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 (to the last publish table), the conditional is not displayed. 1. Click Add an Action, then select If... Then... The If... Then... action is displayed, which includes the following functionality: An If...Then... icon. If... condition then..., which is a link from which you can edit the condition. A field in which you can add request and response actions 2. Click Condition. The Edit an XQuery Condition page is displayed. To learn more, see Editing an XQuery Condition. 3. When you have finished editing the XQuery condition, click Add an Action, then select an action that you want to associate with the condition. Note: In the route node, you can select the Routing or Routing Table actions only. To learn more about these actions, see the appropriate procedure in this table. However, these actions can contain request and response actions inside of them. To learn more, see the table of actions in Adding an Action. 4. If necessary, 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. Continue to the next step.
Routing	Note: This is a terminal action, which means you cannot add another action after this one. However, this action can contain request and response actions inside of it. Identify a target service for the message and configure how the message is routed to that service: 1. Click Add an Action, then select Routing. The Routing action is displayed, which includes the following functionality: A Routing icon A Service link that you can click to select a service A field in which you can add request and response 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. 4. 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. 5. In the Response Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. To learn more about the type of actions you want to add, see the table of actions in Adding an Action. 6. When you have finished adding actions, continue to the next step.
Routing Table	Note: This is a terminal action, which means you cannot add another action after this one. However, this action can contain request and response actions inside of it. A routing table is a set of routes wrapped in a switch-style condition table. It is a short-hand construct that allows different routes to be selected based upon the results of a single XQuery expression. There is a nesting limit of 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. Identify target services for messages and configure how the messages are routed to these services: 1. Click Add an Action, then select Routing Table. The Routing Table action is displayed, which includes the following functionality: A Routing Table icon, an Expression link in which you can edit an XQuery expression, a Diamond icon that you can use to insert new cases, a field in which you can enter a comparison operator, a A field in which you can enter a value, a Service link that you can click to select a service, and a field in which you can add request and response actions. 2. Select one of these comparison operators: =, !=, < , >, <=, or >=, then enter a value expression in the field provided. 3. Click Service. The Service Browser is displayed. 4. Select a service from the list, then click Submit. The service is displayed. 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. 6. In the Response Actions field, click Add an Action to add an action, then select an action that you want to associate with the service. You can add more than one action. Note: To learn more about the types of request and response actions you want to add, see the table of actions in Adding an Action. 7. When you have finished adding actions, continue to the next step. 8. To insert a new case, click the Diamond icon, then select Insert New Case. 9. Repeat steps 2-7 for the new case. You can click the Diamond icon, then select Insert Default Case to add a default case at the end whose routes are selected if none of the preceding cases is satisfied. 10. When you have finished adding cases, continue to the next step.

 

When you have finished adding route node actions, do one of the following:

Table 14-39 Adding Route Node Actions

To...	Complete This Step...
Delete an action	Click the appropriate icon, then click Delete this Action. The action is deleted.
Move an action down	Click the appropriate icon, then click Move Action Down. The action is moved below the next action contained in this stage. Note: This option is displayed only when there are two or more actions contained in the stage.
Move an action up	Click the appropriate icon, then click Move Action Up. The action is moved above the previous action contained in this stage. Note: This option is displayed only when there are two or more actions contained in the stage.
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.


 
When you save the actions, do one of the following:

Table 14-40 Adding Route Node Actions

To...	Complete This Step...
Edit the route node name and description	Click the Route Node icon, click Edit, then click Name and Description.
Convert the route node to an echo node	Click the Route Node icon, then click Convert to Echo Node.
Add an error handler for the route node	Click the Route Node icon, then click Add Error Handler. To learn more, see Adding Error Handling for the Route Node.
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.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

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

 

---

Viewing and Changing Conditional Branch Details

The Edit Branch Node page enables you to view and change conditional branch details. To learn more about branch nodes, see Adding a Conditional Branch Node and Overview of Message Flow.

Note: If you want to edit an operational branch, see Viewing and Changing Operational Branch Details.

To View and Change Conditional Branch Details

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 for the proxy service you selected. The page includes the following functionality:

• A proxy service icon
• The name of the proxy service
• A pipeline pair node icon and name if you have already added a pipeline pair node
• The conditional branch node icon and the name of the branch node
• An echo node icon or a route node icon if you have already added a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
Click the Conditional Branch Node icon, click Edit, then click Branch Node. Alternatively, from the left navigation pane, you can select the branch node from the map of the Message Flow.

The Branch Configuration fields and the Branch Definitions are displayed.

Do one of the following:

Table 14-41 Branch Configuration Fields and Branch Definitions

To	Do This
Edit the XPath expression in the Selected Path field	Click Edit. To learn more, see Editing an XPath Expression.
Add another branch definition	Click Add a New Branch from the flyout menu of the Options column.
Delete a branch definition	Click Delete this Branch from the flyout menu of the Options column.
Move a branch down the list of definitions	Click Move Branch Down from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.
Move a branch up the list of definitions	Click Move Branch Up from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.


 
When you have finished updating the branch, do one of the following:
• To update the branch node, click Save. The Edit Message Flow page is displayed.
• To disregard changes and return to the Edit Message Flow page, click Cancel.
• To clear the branch definitions and remain on the Edit Branch Node page, click Clear.

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

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

 

---

Viewing and Changing Operational Branch Details

The Edit Branch Node page enables you to view and change operational branch details. To learn more about operational branches, see Adding an Operational Branch Node and Overview of Message Flow.

To View and Change Operational Branch Details

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 for the proxy service you selected. The page includes the following functionality:

• A proxy service icon
• The name of the proxy service
• A pipeline pair node icon and name if you have already added a pipeline pair node
• The conditional branch node icon and the name of the branch node
• An echo node icon or a route node icon if you have already added a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
Click the Operational Branch Node icon, click Edit, then click Branch Node. Alternatively, from the left navigation pane, you can select the branch from the map of the Message Flow.

The Branch Configuration fields and the Branch Definitions are displayed.

Do one of the following:

Table 14-42 Branch Configuration Fields and Branch Definitions

To...	Complete This Step...
Add another branch definition	Click Add a New Branch from the flyout menu of the Options column.
Delete a branch definition	Click Delete this Branch from the flyout menu of the Options column.
Move a branch down the list of definitions	Click Move Branch Down from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.
Move a branch up the list of definitions	Click Move Branch Up from the flyout menu of the Options column. Note: This option displays only when more than one branch definition exists.


 
When you have finished updating the branch, do one of the following:
• To update the branch node, click Save. The Edit Message Flow page is displayed.
• To disregard changes and return to the Edit Message Flow page, click Cancel.
• To clear the branch definitions and remain on the Edit Branch Node page, click Clear.

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Overview of Proxy Services

step in Service Types and Transports

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Viewing and Changing Message Flow

 

---

Viewing and Changing Stage Configuration Details

The Edit Stage Configuration page enables you to edit a stage. To learn more about stages, see Adding a Stage, Adding an Action, and Overview of Message Flow.

To View and Change Stage Configuration Details

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 for the proxy service you selected. The page includes the following attributes:

• A proxy service icon
• The name of the proxy service
• A pipeline pair node icon and name if you have already added a pipeline pair node
• An echo node icon or a route node icon if you have already added a route node
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
Select the stage that you want to edit:
Expand an existing pipeline to view the pipeline pair.
In the request or response pipeline, click the Stage icon, click Edit, then click Stage.

The Edit Stage Configuration page is displayed.

Note: Alternatively, from the left navigation pane, you can select the stage from the map of the Message Flow.

Do one of the following:

Table 14-43 Edit Stage Configuration Page

To...	Complete This Step...
Add an action	Click Add an Action, then select the appropriate action. To learn more, see Adding an Action.
Delete an action	Select the action, then click Delete this Action.
Edit a variable field	Make the edits in the appropriate field.
Edit an XQuery expression	Click the expression you want to edit. To learn more, see Editing an XQuery Expression.
Edit an XPath expression	Click the expression you want to edit. To learn more, see Editing an XPath Expression.
Edit an XQuery condition	Click the condition you want to edit. To learn more, see Editing an XQuery Condition.


 
When you have finished making changes, do one of the following:
• To update the stage, click Save. The Edit Message Flow page is displayed.
• To disregard changes and return to the Edit Message Flow page, click Cancel.
• To clear the unsaved edits and remain on the Edit Stage Configuration page, click Clear.

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

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

 

---

Editing an XQuery Condition

The Edit an XQuery Condition page enables you to add or edit an XQuery condition. You can access this page through the Message Flow of a proxy service. To learn more about Message Flow, see Overview of Message Flow.

To Edit an XQuery Condition

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 for the proxy service you selected.

Expand an existing pipeline to view the pipeline pair.
Select the Stage icon for the stage that you want to edit, click Edit, then click Stage. The Edit Stage Configuration page is displayed. If you have previously added actions, the page displays these actions.
To select the XQuery condition you want to edit, locate the action that contains the condition.
To open the Condition editor, click the condition contained within the action.

The Edit an XQuery Condition page is displayed. The page includes the following functionality:

• Text and Condition Builder panes
• Message Context Variables Panel
• Namespace Definitions Panel
• XQuery Functions Palette
Do one of the following:

Table 14-44 Edit an XQuery Condition Page

To...	Complete These Steps...
Generate XPath for message context variable	1. In the Message Context Variables panel, select one of these context variable types from the drop-down list: attachments, header, outbound, body, or inbound. To learn more about message context variables, see Message Context. 2. Click the displayed name to make the variable appear in the XPath field of the Message Context Variables panel. Note: The displayed names are a tree view that may be expanded to reveal sub elements that may in turn be selected. 3. To build the expression, highlight the text, then drag the context variable from the XPath field, and drop it in the Edit the Expression field.
Define a message context variable	To learn more, see Defining a New Message Context Variable.
Define a user namespace	1. In the Namespace Definitions panel, click the + for User Namespaces. The New Namespace Declaration dialog box is displayed. 2. In the Prefix field, enter a prefix. 3. In the Namespace field, enter a namespace. 4. Click OK. Note: An XML namespace is a way of making the element and attribute names globally unique. You qualify the element and attribute names, which are local names, with the namespace prefix to achieve this uniqueness.
Delete a user namespace	In the Namespace Definitions panel, click the - (minus sign) that corresponds to the user namespace you want to delete.
Build the XQuery condition using the Text option	1. Make sure the Text option is selected. 2. Enter or paste text into the Edit an XQuery Condition field. Note: To build the condition, you can drag XQuery functions from the XQuery Functions Palette, or you can drag message context variables from the Message Context Variables Panel, and drop them in the Edit an XQuery Condition field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel. The drag-and-drop feature is supported only on an Internet Explorer browser. Other browsers do not support the JavaScript to set the dragged text. To use the XML schema tree, instead of doing a drag-and-drop, you must click the node you are interested in. The XPath for this node is displayed in the text area at the bottom of the palette. You must then copy and paste the content of this text area into the Edit the Expression field. 3. Do one of the following: To save the condition, click Submit. The Edit Stage Configuration page is displayed. The condition is populated with the text you entered. To learn more, continue in Viewing and Changing Stage Configuration Details. To validate the condition, click Validate. To discard your changes, click Cancel.
Enter a comparison expression using the Condition Builder option	1. Select the Condition Builder option. 2. Make sure the Comparison Expression option is selected. 3. In the left hand pane, enter a context variable, namespace definition or XQuery function. Note: To build the expression, you can drag XQuery functions from the XQuery Functions Palette, and drop them in the Edit an XQuery Transformation field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel. 4. In the middle pane, select =, !=, >, <, >=, or <=. 5. In the right hand pane, enter text or enter a context variable. Note: You must enter the text in quotations—that is, enter "true", not true. 6. Click Add. The text you entered is displayed in the pane below. 7. Repeat steps 2-6 to build additional conditions. Each condition is added to the end of the list of conditions. Note: When you build additional expressions, make sure to select the and or the or options. Note: You can select a condition and click Remove to delete it, click Up to move it up the list of conditions, click Down to move it down the list of conditions, and click Update to update it. 8. Do one of the following: To save the condition, click Submit. The Edit Stage Configuration page is displayed. The condition is populated with the text you entered. To learn more, continue in Viewing and Changing Stage Configuration Details or Adding an Action. To validate the expression, click Validate. To discard your changes, click Cancel.
Enter a unary expression using the Condition Builder option	1. Select the Condition Builder option. 2. Select the Unary Expression option. 3. Enter a context variable, namespace definition or XQuery function. Note: To build the expression, you can drag XQuery functions from the XQuery Functions Palette, and drop them in the Edit an XQuery Transformation field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel. 4. Click Add. The text you entered is displayed in the pane below. 5. Repeat steps 2-6 to build additional conditions. Each condition is added to the end of the list of conditions. Note: When you build additional expressions, make sure to select the and or the or options. Note: You can select a condition and click Remove to delete it, click Up to move it up the list of conditions, click Down to move it down the list of conditions, and click Update to update it. Note: Unary expressions may be intermixed with Comparison expressions in the overall definition of a condition. 6. Do one of the following: To save the condition, click Submit. The Edit Stage Configuration page is displayed. The condition is populated with the text you entered. To learn more, continue in Viewing and Changing Stage Configuration Details or Adding an Action. To validate the expression, click Validate. To discard your changes, click Cancel.


 

 

Note: When you click Submit, 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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Message Context

Overview of Proxy Services

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Viewing and Changing Message Flow

 

---

Editing an XQuery Expression

The Edit an XQuery Expression page enables you to add or change an XQuery expression. You can access this page through the Message Flow of a proxy service. To learn more about Message Flow, see Overview of Message Flow.

Note: The XQuery and XPath editors allow you to declare a variable's structure by mapping it to a type or element and then creating path expressions with a drag and drop action from the graphical representation of the structure. This is an ease-of-use feature. You can also enter the path expressions manually instead.

You can use this feature directly for all user-defined variables, as well as $inbound, $outbound, and $fault. However, you cannot use it directly to access XML attachments in $attachments, headers in $header, or documents and RPC parameters in $body, with one exception— you can use it directly to access documents and parameters in $body for request messages received by a WSDL proxy service.

To Edit an XQuery Expression

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 for the proxy service you selected.

Expand an existing pipeline to view the pipeline pair.
Click the Stage icon for the stage that you want to edit, click Edit, then click Stage. The Edit Stage Configuration page is displayed. If you have previously added actions, the page displays these actions.
To select the XQuery expression you want to edit, locate the action that contains the expression.
To open the Expression editor, click the link for the XQuery expression contained within the action.

The Edit an XQuery Expression page is displayed. The page includes the following functionality:

• Text, XQ Transformation, and XSL Transformation panes
• Message Context Variables Panel
• Namespace Definitions Panel
• XQuery Functions Palette
Do one of the following:

Table 14-45 Edit an XQuery Expression Page

To...	Complete These Steps...
Generate XPath for message context variable	1. In the Message Context Variables panel, select one of these context variable types from the drop-down list: attachments, header, outbound, body, or inbound. To learn more about message context variables, see Message Context. 2. Click the displayed name to make the variable appear in the XPath field of the Message Context Variables panel. Note: The displayed names are a tree view that may be expanded to reveal sub elements that may in turn be selected. 3. To build the expression, highlight the text, then drag the context variable from the XPath field, and drop it in the Edit the Expression field.
Define a message context variable	To learn more, see Defining a New Message Context Variable.
Define a user namespace	1. In the Namespace Definitions panel, click the + for User Namespaces. The New Namespace Declaration dialog box is displayed. 2. In the Prefix field, enter a prefix. 3. In the Namespace field, enter a namespace. 4. Click OK. Note: An XML namespace is a way of making the element and attribute names globally unique. You qualify the element and attribute names, which are local names, with the namespace prefix to achieve this uniqueness.
Delete a user namespace	In the Namespace Definitions panel, click the - (minus sign) that corresponds to the user namespace you want to delete.
Build the XQuery expression manually	1. Make sure the Text option is selected. 2. Enter or paste text into the Edit the Expression field. Note: To build the expression, you can drag XQuery functions from the XQuery Functions Palette, and drop them in the Edit an XQuery Transformation field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel. The drag-and-drop feature is supported only for the Internet Explorer browser. Other browsers do not support the JavaScript required to set the dragged text. To use the XML schema tree, instead of doing a drag-and-drop, you must click the node you are interested in. The XPath for this node is displayed in the text area at the bottom of the palette. You must then copy and paste the content of this text area into the Edit the Expression field. 3. Do one of the following: To save the expression, click Submit. The Edit Stage Configuration page is displayed. The Expression is populated with the text you entered. To learn more, continue in Viewing and Changing Stage Configuration Details. To validate the expression, click Validate. To discard your changes, click Cancel.
Select an XQuery Transformation for execution	1. Select the XQ Transformation option. 2. In the Select the Transformation to execute field, select the XQuery Transformation you want to execute, then click Select. 3. Under the Variable Mapping field, a label and a corresponding text box that you can scroll to see each input parameter of the transformation are displayed. Each label corresponds to the name of a parameter, and each text box is for defining an XQuery expression to be mapped to the parameter. You must define a mapping for each parameter. For example, if an XQuery transformation has two input parameters named one and two, the Variable Mapping field has two labels—one and two. A text box, into which the XQuery expression is entered, is associated with each label. The following XQuery expressions are examples of valid input to this field: $body/*[1] $body/po:PurchaseOrder Note: The following variable name is not a valid entry for this field and results in an exception: body 4. Do one of the following: To save the expression, click Submit. The Edit Stage Configuration page is displayed. The expression is populated with the transformation you selected. To learn more, continue in Viewing and Changing Stage Configuration Details or Adding an Action. To validate the expression, click Validate. To discard your changes, click Cancel.
Select an XSL Transformation for execution	1. Select the XSL Transformation option. 2. In the Select the XSL transformation to execute field, select the XSL Transformation you want to execute, then click Select. 3. Under the Variable Mapping field, a label and a corresponding text box is displayed for each input parameter of the transformation. Each label corresponds to the name of a parameter, and each text box is for defining an XQuery expression to be mapped to the parameter. You must define a mapping for each parameter. For example, if an XSL transformation has two input parameters named one and two, the Variable Mapping field has two labels—one and two—with a text box associated with each into which the XQuery expression is entered. In addition to the mapping for any input variables, you must also specify an XQuery expression for the Input Document to the transformation. The mapping is specified in the text box with the label Input Document. The following XQuery expressions are examples of valid input to this field: $body/*[1] $body/po:PurchaseOrder Note: The following variable name is not a valid entry for this field and results in an exception: body 4. Do one of the following: To save the expression, click Submit. The Edit Stage Configuration page is displayed. The expression is populated with the transformation you selected. To learn more, continue in Viewing and Changing Stage Configuration Details or Adding an Action. To validate the expression, click Validate. To discard your changes, click Cancel.


 

Note: When you click Submit, 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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Message Context

Overview of Proxy Services

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Viewing and Changing Message Flow

 

---

Editing an XPath Expression

The Edit an XPath Expression page enables you to edit an XPath expression. You can access this page through the Message Flow of a proxy service. To learn more about Message Flow, see Overview of Message Flow.

Note: The XQuery and XPath editors allow you to declare a variable's structure by mapping it to a type or element and then creating path expressions with a drag and drop action from the graphical representation of the structure. This is an ease-of-use feature. You can also enter the path expressions manually instead.

You can use this feature directly for all user-defined variables, as well as $inbound, $outbound, and $fault. However, you cannot use it directly to access XML attachments in $attachments, headers in $header, or documents and RPC parameters in $body, with one exception— you can use it directly to access documents and parameters in $body for request messages received by a WSDL proxy service.

To Edit an XPath Expression

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 for the proxy service you selected.

Expand the an existing pipeline to view the pipeline pair.
Click the Stage icon for the stage that you want to edit, click Edit, then click Stage. The Edit Stage Configuration page is displayed. If you have previously added actions, the page displays these actions.
To select the XPath expression you want to edit, locate the action that contains the expression.
To open the Expression editor, click the link for the XPath expression contained within the action.

The Edit an XPath Expression page is displayed. The page includes the following functionality:

• A field in which you can edit the XPath expression
• Message Context Variables Panel
• Namespace Definitions Panel
Do one of the following:

Table 14-46 Edit an XPath Expression Page

To...	Complete These Steps...
Generate XPath for message context variable	1. In the Message Context Variables panel, select one of these context variable types from the drop-down list: attachments, header, outbound, body, or inbound. To learn more about message context variables, see Message Context. 2. Click the displayed name to make the variable appear in the XPath field of the Message Context Variables panel. Note: The displayed names are a tree view that may be expanded to reveal sub elements that may in turn be selected. 3. To build the expression, highlight the text, then drag the context variable from the XPath field, and drop it in the Edit the Expression field.
Define a message context variable	To learn more, see Defining a New Message Context Variable.
Define a user namespace	1. In the Namespace Definitions panel, click the + for User Namespaces. The New Namespace Declaration dialog box is displayed. 2. In the Prefix field, enter a prefix. 3. In the Namespace field, enter a namespace. 4. Click OK. Note: An XML namespace is a way of making the element and attribute names globally unique. You qualify the element and attribute names, which are local names, with the namespace prefix to achieve this uniqueness.
Delete a user namespace	In the Namespace Definitions panel, click the - (minus sign) that corresponds to the user namespace you want to delete.
Build the XPath expression manually	1. Enter or paste text into the Edit an XPath Expression field. Note: To build the expression, you can drag context variables from the Message Context Variables Panel, and drop them in the Edit an XPath Expression field. You can also add predefined default namespaces, variable namespaces, and user-defined namespaces, which are listed in the Namespace Definitions panel. The drag-and-drop feature is supported only on an Internet Explorer browser. Other browsers do not support the JavaScript to set the dragged text. To use the XML schema tree, instead of doing a drag-and-drop, you must click the node you are interested in. The XPath for this node is displayed in the text area at the bottom of the palette. You must then copy and paste the content of this text area into the Edit an XQuery Transformation field. 2. Do one of the following: To save the expression, click Submit. The Edit a Stage Configuration page is displayed. The Expression is populated with the text you entered. To learn more, continue in Viewing and Changing Stage Configuration Details or Adding an Action. To discard your changes, click Cancel.


 

Note: When you click Submit, 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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Message Context

Overview of Proxy Services

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Viewing and Changing Message Flow

 

---

Defining a New Message Context Variable

The Define a New Message Context Variable page enables you to define a new message context variable type. You can access this page from the Edit an XQuery Expression, Edit an XPath Expression, or Edit an XQuery Condition pages. To learn more, see Editing an XQuery Expression, Editing an XPath Expression, or Editing an XQuery Condition.

To Define a New Message Context Variable

In the Message Context Variables panel on the Edit an XQuery Expression, Edit an XPath Expression, or Edit an XQuery Condition pages, click the + icon.

The Define a New Message Context Variable page is displayed.

In the Variable Name field, enter the name of the variable you want to define.
In the Select the type for this Message Context Variable field, select the variable type: String, Untyped XML, XML Schema, WSDL or MFL.

Note: You can click Browse and use the appropriate Browser to select an XML Schema, WSDL, or MFL, then click Submit.

Do one of the following:
• To save the new variable and return to the previous page, click Submit.
• To disregard changes and return to the previous page, click Cancel.

Related Topics

Message Context

Overview of Proxy Services

Adding a Proxy Service

Viewing and Changing Message Flow

 

---

Error Messages and Handling

This section includes the following topics:

• Error Handlers
• Nested Error Handlers
• Empty Error Handlers
• Error Handler Actions
• Error Handler Configuration

Error Handlers

BEA AquaLogic Service Bus enables you to configure your system to format and return error messages.

Errors can occur during Message Flow processing for various reasons. For example, security errors occur if a username is not correctly validated or authorized; transformation errors occur if AquaLogic Service Bus is unable to successfully transform or validate a message; a routing error is raised if a routing service is unavailable, and so on. Typically, these errors originate from a specific stage, route node or from the proxy service, as this is where most of the Message Flow logic is implemented.

AquaLogic Service Bus provides a mechanism to handle these errors by enabling you to define error handlers. An error handler is a pipeline that allows you to perform various actions such as logging, transformation, and publishing to handle errors appropriately.

If an error occurs within a stage a sequence of steps are executed. This sequence of steps constitutes an error pipeline for that stage.

Nested Error Handlers

You can configure an error handler for the entire Message Flow as well as for every pipeline and stage within the Message Flow. You may also configure error handlers for route nodes but not for branch nodes.

When an error occurs, it is handled by the inner-most encompassing error handler. For example, a stage's error handler handles a transformation error if it occurs while executing the assign action in that stage. If there is no error handler configured for the stage, it is handled by the next level error handler, which is that of the pipeline that contains the transformation stage. If that error handler does not exist, it is then handled by the Message Flow-level error handler. If that fails, then a default system-level error handler processes the error.

The next level error handler for uncaught errors that occur in a route node is the Message Flow-level handler. Thus, unlike stage errors which can be handled at 3 levels by user-configured handlers, Message Flow errors can only be caught by at most 2 levels of user-configured handlers.

Every component—stage, pipeline or Message Flow—can have at most 1 error handler. Therefore, only 1 Message Flow-level error handler is used to process any error that occurs during either request or response processing (that is not handled at a lower level by a pipeline or stage error handler). Since the inbound binding layer is not associated with any particular stage or pipeline, errors that occur in the binding layer are always handled by the Message Flow-level error handler. Outbound binding layer errors may occur in several places, depending on what entity is performing communication. For example, binding layer errors that occur during routing can be caught by the routing node's error handler. Similarly, binding layer errors that occur during a publish operation in a publish stage can be caught by the stage-level error handler.

Empty Error Handlers

An empty or unconfigured error handler is identical to not having an error handler. For example, if the stage-level error handler was created but never configured, then the error bubbles-up to the next level handler.

Error Handler Actions

When an error handler processes an error, it can finish with one of two actions:

Table 14-47 Error Handler Actions

Error Actions	Description
Reply	If you assign this action, an error response is immediately created for the proxy service client. All further Message Flow processing stops and a response message is sent based on the message-related context variables. In this instance, you can configure the error handler to send a simple reply to the proxy service or a more detailed reply stating that an error occurred. The difference between HTTP reply with success and reply with failure is as follows: Reply with success sends status code 200 and $body Reply with failure status sends status code 500 and $body
Resume	If you assign this action, Message Flow processing continues as though no error has occurred. Processing continues from the point where the error was successfully consumed. You may be required to configure the error handler to correspond with the context variables as they may be in a state that isn't expected by the rest of the Message Flow. When an error handler consumes an error, processing resumes as though the error handler had finished executing successfully; it does not resume at the point the error occurred.

 

If neither the Reply nor the Resume action is initiated, the error is rethrown. In this case, the error is pushed forward and handled by the next level error handler. Unless otherwise specified, the rethrow action is the default action of an error handler.

To learn how Message Flow chooses among these actions, see Error Handler Configuration.

Error Handler Configuration

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. Some actions, however, are not allowed to appear in an error handler.

In addition to the standard context variables, there is an additional context variable available to an error handler—the $fault variable. The $fault variable contains information about any error that occurs during Message Flow processing. When an error occurs, this variable is populated with information about the error, prior to the error-handler being invoked. The $fault variable is only ever defined within error handlers. It is never defined within a simple request and response pipeline. This is the key difference between an error pipeline and any other pipeline.

There are four core elements within the $fault variable:

Table 14-48 Error Handler Configuration

Element	Description
errorCode	Holds an error code as a string value
Reason	Contains a brief textual description of the error
Details	Contains arbitrary XML content about the error
Location	Identifies the pipeline and the stage where the error occurred

 

You can modify the $fault variable; however it is only relevant inside an error handler.

Related Topics

Adding a Proxy Service

Listing and Locating Proxy Services

Viewing and Changing Proxy Services

Viewing and Changing Message Flow

 

---

Adding Error Handling for the Proxy Service

The Edit Message Flow page enables you to add error handling for the proxy service. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

To Add Error Handling for a Proxy Service

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 for the proxy service you selected. The page includes the following functionality:

• A proxy service icon
• The name of the proxy service
• A pipeline pair node icon and name if you have already added a pipeline pair node
• An echo node icon
• In the left navigation pane, a map of the Message Flow, which enables you to link to the pages associated with the various objects in the Message Flow.
Click the Start Node icon, then click Add Service Error Handler. The Edit Error Handler page is displayed, which includes an Error Handler icon.
Click the Error Handler icon, then click Add Stage. The Stage icon and the Name and Description fields are displayed.
In the Name field, enter a name for the stage.
In the Description field, enter a description of the stage.
To save the name and description of the stage, click Save.
Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.
To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. 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 addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.

When you have finished adding actions, continue to the next step.

Do one of the following:
• To save the actions, click Save. The Edit Error Handler page is displayed.
• To disregard changes and return to the Edit Error Handler page, click Cancel.
• To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.
When you have saved the actions, do one of the following:

Table 14-49 Adding Proxy Service Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Select the Error Handler or Stage icon, then click Add 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 changes and remain on the Edit Error Handler page	Click Clear.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Error Messages and Handling

Adding Pipeline Error Handling

Adding Stage Error Handling

Adding Error Handling for the Route Node

Viewing and Changing Message Flow

Overview of Proxy Services

 

---

Adding Pipeline Error Handling

The Edit Message Flow page enables you to add error handling for a pipeline. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

Note: You must create a pipeline pair node before you can add a pipeline error handler. To learn more, see Adding a Pipeline Pair Node.

To Add Error Handling for a Pipeline

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 for the proxy service you selected.

Expand an existing pipeline pair node to view the pipeline pair, which consists of request and response pipelines.
Click the pipeline to which you want to add error handling, then click Add Pipeline Error Handler. The Edit Error Handler page is displayed.
Click the Error Handler icon, then click Add Stage. The Stage icon and the Name and Description fields are displayed.
In the Name field, enter a name for the stage.
In the Description field, enter a description of the stage.
To save the name and description of the stage, click Save.
Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.
To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. 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 addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.

When you have finished adding actions, continue to the next step.

Do one of the following:
• To save the actions, click Save. The Edit Error Handler page is displayed.
• To disregard changes and return to the Edit Error Handler page, click Cancel.
• To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.
When you have saved the actions, do one of the following:

Table 14-50 Adding Pipeline Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Select the Error Handler or Stage icon, then click Add 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 changes and remain on the Edit Error Handler page	Click Clear.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Error Messages and Handling

Adding Error Handling for the Proxy Service

Adding Stage Error Handling

Adding Error Handling for the Route Node

Viewing and Changing Message Flow

Overview of Proxy Services

 

---

Adding Stage Error Handling

The Edit Message Flow page enables you to add error handling for a stage. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

Note: You must create a stage before you can add a stage error handler. To learn more, see Adding a Stage.

To Add Error Handling for a Stage

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 for the proxy service you selected.

Expand an existing pipeline pair node to view the pipeline pair, which consists of request and response pipelines. If you have previously added stages, the Stage icons are also displayed.
Click the Stage icon for the stage you want to edit, click Add, then click Add Stage Error Handler. The Edit Error Handler page is displayed.
Click the Error Handler icon, then click Add Stage. The Stage icon and the Name and Description fields are displayed.
In the Name field, enter a name for the stage.
In the Description field, enter a description of the stage.
To save the name and description of the stage, click Save.
Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.
To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. 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 addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.

When you have finished adding actions, continue to the next step.

Do one of the following:
• To save the actions, click Save. The Edit Error Handler page is displayed.
• To disregard changes and return to the Edit Error Handler page, click Cancel.
• To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.
When you have saved the actions, do one of the following:

Table 14-51 Adding Stage Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Select the Error Handler or Stage icon, then click Add 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 changes and remain on the Edit Error Handler page	Click Clear.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Error Messages and Handling

Adding Error Handling for the Proxy Service

Adding Pipeline Error Handling

Adding Error Handling for the Route Node

Viewing and Changing Message Flow

Overview of Proxy Services

 

---

Adding Error Handling for the Route Node

The Edit Message Flow page enables you to add error handling for a route node. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

Note: You must create a route node before you can add a route node error handler. To learn more, see Adding a Route Node.

To Add Error Handling for a Route Node

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 for the proxy service you selected.

Click the Route Node icon, then click Add Error Handler. The Edit Error Handler page is displayed.
Click the Error Handler icon, then click Add Stage. The Stage icon and the Name and Description fields are displayed.
In the Name field, enter a name for the stage.
In the Description field, enter a description of the stage.
To save the name and description of the stage, click Save.
Click the Stage icon, click Edit, then click Stage. The Edit Stage Configuration page is displayed.
To add an action, click Add an Action, then select the action you want to add.

Since an error handler is another pipeline, it is configured like any other pipeline. For example, the Publish action may be used to send error notifications to other services, the Assign action may be used to modify the context variables, and so on. 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 addition, three commonly-used error actions are Raise Error, Reply, and Resume. To learn more about these actions, see Error Handler Actions in Error Messages and Handling.

When you have finished adding actions, continue to the next step.

Do one of the following:
• To save the actions, click Save. The Edit Error Handler page is displayed.
• To disregard changes and return to the Edit Error Handler page, click Cancel.
• To clear any unsaved edits and remain on the Edit Stage Configuration page, click Clear.
When you have saved the actions, do one of the following:

Table 14-52 Adding Route Node Error Handling

To...	Complete This Step...
Continue adding actions to configure the error handler	Click the Stage icon, click Edit, then click Stage.
Edit the stage name and description	Click the Stage icon, click Edit, then click Name and Description.
Add another stage	Select the Error Handler or Stage icon, then click Add 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 changes and remain on the Edit Error Handler page	Click Clear.


 

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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Error Messages and Handling

Adding Error Handling for the Proxy Service

Adding Pipeline Error Handling

Adding Stage Error Handling

Viewing and Changing Message Flow

Overview of Proxy Services

 

---

Viewing and Changing an Error Handler

The Edit Message Flow page enables you to view and change error handlers. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

To View and Change an Error Handler

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 for the proxy service you selected.

Do one of the following:

Table 14-53 Viewing and Changing the Error Handler

To...	Complete This Step...
View and change the error handler for the proxy service	Click the Start Node icon, then click Edit Service Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Error Handling for the Proxy Service.
View and change the pipeline error handler	Click the appropriate Pipeline Pair icon, then click Edit Pipeline Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Pipeline Error Handling.
View and change the route node error handler	Click the Route Node icon, click Edit, then click Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Error Handling for the Route Node.
View and change the stage error handler	Click the appropriate Stage icon, click Edit, then Stage Error Handler. The Edit Error Handler page is displayed. To learn more, see Adding Stage Error Handling.


 

Related Topics

Error Messages and Handling

Deleting an Error Handler

Viewing and Changing Message Flow

Overview of Proxy Services

 

---

Deleting an Error Handler

The Edit Message Flow page enables you to delete existing error handlers. You can configure error handling at the Message Flow, pipeline, route node, and stage level. To learn more, see Error Messages and Handling.

To Delete an Error Handler

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 for the proxy service you selected.

Do one of the following:

Table 14-54 Deleting the Error Handler

To...	Complete This Step...
Delete the error handler for the proxy service	Click the Start Node icon, then click Delete Service Error Handler. The service error handler is deleted.
Delete the pipeline error handler	Click the appropriate Pipeline Pair icon, then click Delete Pipeline Error Handler. The pipeline error handler is deleted.
Delete the route node error handler	Click the Route Node icon, click Edit, then click Error Handler. The route node error handler is deleted.
Delete the stage error handler	Click the appropriate Stage icon, click Edit, then Stage Error Handler. The stage error handler is deleted.


 

Note: When you click Delete, 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 core configuration is updated. Alternatively, click Discard at any time during the session to delete the changes you have made so far in the current session.

Related Topics

Error Messages and Handling

Viewing and Changing Message Flow

Adding Error Handling for the Proxy Service

Adding Pipeline Error Handling

Adding Stage Error Handling

Adding Error Handling for the Route Node

Viewing and Changing an Error Handler

Overview of Proxy Services