Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Service Bus
11g Release 1 (11.1.1.6.3)

Part Number E15866-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

4 User Interface Reference

This chapter describes all the views, dialogs, wizards, and other user interface objects in the Oracle Service Bus IDE.

This chapter includes the following sections:

4.1 Alerts

The following pages are provided for managing alerts:

4.1.1 Alert Destination Editor

An alert destination is a destination address for alert notifications in Oracle Service Bus. Use this page to configure an alert destination resource.

Table 4-1 Alert Destination Editor Options

Option Description

Description

Enter a description for this alert destination.

SNMP Trap

If you specify SNMP Trap, alerts are sent as SNMP traps, and can be processed by any third-party enterprise monitoring systems (ESM).

Reporting

If you specify Reporting, alerts are sent to the Oracle Service Bus Reporting module and can be captured using a custom reporting provider that can developed using the reporting APIs provider by Oracle Service Bus. This allows third-parties to receive and process alerts in custom Java code.

Alert Logging

If you select Yes, alerts sent to this alert destination are logged to the alert log.


Continue in the Edit Alert Destination page. Click Add to add e-mail and JMS recipients to an alert destination. See:

4.1.2 Edit E-mail Recipient Page

Use this page to configure the destination target for an alert sent via e-mail (that is, using the e-mail transport).

Table 4-2 E-mail Recipient Options

Option Description

Mail Recipients

Enter an e-mail recipient in the format: mailto:username@hostname

You can specify multiple e-mail recipients by entering the user names and hostnames in a comma-separated list. For example, mailto:username@hostname

[,username_1@hostname_1]...[,username_n@hostname_n]

Only the first mail recipient needs to be prefixed with the text "mailto:". However doing so is optional; the code will add it if it is missing.

SMTP Server

Select the name of the SMTP server for the outgoing e-mail. This field is not required if Mail Session is selected in the next field. These fields are mutually exclusive; it is an error to configure both.

Mail Session

Select an available mail session. This field is not required if an SMTP Server is selected in the previous field. These fields are mutually exclusive; it is an error to configure both.

From Name

Provide a sender's name for the alert notification. This field is optional.

From Address

Provide a valid e-mail address. This field is required if a value for the From Name field is specified.

Reply To Name

Provide a name to which a reply may be addressed. This field is optional.

Reply To Address

Provide an e-mail address to which a reply may be sent. This field is required if a value for the Reply To Name field is specified.

Connection Timeout

Enter the number of seconds a connection must wait for a response from the server before timing out. The default value is 0.

Request Encoding

Enter a character set encoding value. The default encoding value is iso-8859-1.


4.1.3 Edit JMS Destination Page

Use this page to configure the destination target for an alert sent via JMS (that is, using the JMS transport).

Table 4-3 JMS Destination Options

Option Description

Destination URI

Enter a JMS destination URI in the format:

jms://host:port/connection_factory/jndi_destination

Note: While Oracle WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Oracle Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see "Configure foreign servers" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help at http://www.oracle.com/pls/as1111/lookup?id=WLACH.

Destination Type

Select Queue or Topic.

Message Type

Select Bytes or Text.

Request Encoding

Enter a character set encoding value. The default encoding value is iso-8859-1.


4.2 Business Service Configuration

You configure business services in the business service editor after you create the business service. You can view and modify those settings in the Business Service editor: The business service configuration pages are:

4.2.1 Business Service General Configuration Page

Use the Business Service General Configuration page to specify general configuration settings for a business service.

4.2.1.1 Business Service Editor Options

The following table describes the options in the editor:

Table 4-4 Business Service Editor Options

Option Description

Description

Enter or modify a description for this service.

Service Type (editor only)

This option shows the service type of the business service. You can change only some of the properties of some of the service types:

  • WSDL Web Service - Select this option to create a business service based on a WSDL. Then, enter the WSDL name, qualified by its path (for example, myProject/myFolder/myWSDL). Alternatively, click Browse to select a WSDL resource. You can also specify a different WSDL, but by doing so, you are effectively creating a new service and you will have to configure it as if it were a new service.

    (port or binding) - Enter the name of a port (defined in the WSDL) to describe an actual transport address, or enter the name of a binding (defined in the WSDL) to map to a transport address. If you use Browse to select a WSDL, as described above, the Select a WSDL Definition dialog lists any ports and bindings defined in the WSDL. When you choose a port or a binding on that page, the (port or binding) field is filled with the selected name.

  • Transport Typed Service - Select this option to create a service that uses the EJB, JEJB, or Flow (Split-Join) transport.

  • Messaging Service - Select this option to create a service that exchanges messages of different content-types. These exchanges can be either request/response or one-way. They can also have a response with no request when used with the HTTP 'GET' option for the HTTP transport. Unlike Web Services, the content-type of the request and response need not be the same.

  • Any SOAP Service - Select this option to create a SOAP service that does not have an explicitly defined, concrete interface. You can change the SOAP version (SOAP 1.1 or SOAP 1.2)

  • Any XML Service - Select this option to create an XML service that does not have an explicitly defined, concrete interface.

    HTTP GET is only supported for messaging services and this service type.


4.2.2 Business Service Message Type Configuration Page

Use the Business Service Message Type Configuration page to configure message types for a business service whose type is Messaging Service.

The binding definition for messaging services consists of configuring the content-types 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).

Note:

E-mail, File, FTP, or SFTP transport business services whose type is Messaging Service support one-way messaging only; the Response Message Type should be None. If you select an option other than None, the file, ftp, or sftp protocol will not be available on the Transport Configuration page.

Table 4-5 Message Type Business Service Options

Option Description

Request Message Type

Select a message type for the request message:

  • None - Select this option if there is no request message (HTTP GET example)

  • Binary - Select this option if the content-type of the message is unknown or not important.

  • Text - Select this option if the message can be restricted to text.

  • MFL - Select this option if the message is a binary document conforming to an MFL definition. Enter the MFL file name (qualified by its path), or click Browse to select a file.

    You can configure only one MFL file.

    Note: To support multiple MFL files, define the content as binary or text and use the MFL action in the message flow to convert to XML.

  • XML - Select this option if the message is an XML document. Enter the XML file name (qualified by its path), or click Browse to select a file.

    Optionally provide some type information by declaring (in the element or type field) the XML schema type of the XML document exchanged.

  • Java - Select this option if a Java Object is being sent in the request. The JMS transport is used for Java Object messages. For more information, see "Sending and Receiving Java Objects in Messages" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1874.

Response Message Type

Select a message type for the response message:

  • None - Select this option if there is no response message.

  • Binary - Select this option if the content-type of the message is unknown or not important.

  • Text - Select this option if the message can be restricted to text.

  • MFL - Select this option if the message is a binary document conforming to an MFL definition. Enter the MFL file name (qualified by its path), or click Browse to select a file.

    You can configure only one MFL file.

    Note: To support multiple MFL files, define the content as binary or text and use the MFL action in the message flow to convert to XML.

  • XML - Select this option if the message is an XML document. Enter the XML file name (qualified by its path), or click Browse to select a file.

    Optionally provide some type information by declaring (in the element or type field) the XML schema type of the XML document exchanged.

  • Java - Select this option if a Java Object is being received in the response. The JMS transport is used for Java Object messages. For more information, see "Sending and Receiving Java Objects in Messages" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1874.


4.2.3 Business Service SOAP Binding Configuration Page

Use Business Service SOAP Binding Configuration page to configure the SOAP Binding for a business service based on a WSDL.

Select or deselect Enforce WS-I Compliance to specify whether or not the service is to conform to the Basic Profile defined by the Web Services Interoperability Organization. This option is available for or SOAP 1.1 services only

When a service is marked WS-I compliant, checks are performed against the messages sent to and from that service.

4.2.4 Business Service Transport Configuration Page

Use the Business Service Transport Configuration page to select, review, or change the service's transport protocol and to set, review, or change general transport configuration settings.

Outbound transport-level security applies to the connections between Oracle Service Bus proxy services and business services. For more information about transport-level security, see "Configuring Transport-Level Security" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1557.

Table 4-6 Business Service Transport Configuration Options

Option Description

Protocol

Select a transport protocol from the list. The protocols available differ, depending on the service type:

  • WSDL Web Service: soa-direct, bpel-10g, dsp, http, jca, jms, sb, soa-direct, ws

  • Transport-Typed Service: ejb, flow, jejb

  • Messaging Service: email, file, ftp, http, jms, mq (if available), sftp, tuxedo

  • Any SOAP Service: dsp, http, jms, sb

  • Any XML Service: dsp, email, file, ftp, http, jms, mq (if available), sb, sftp, tuxedo

Load Balancing Algorithm

Select one of these load-balancing algorithms:

  • Round-robin - This algorithm dynamically orders the URLs that you enter in the Endpoint URI field for this business service. If the first one fails, it tries the next one, and so on until the retry count is exhausted.

    For every new message, there is a new order of URLs.

  • Random - This algorithm randomly orders the list of URLs that you enter in the Endpoint URI field for this business service. If the first one fails, it tries the next one, and so on until the retry count is exhausted.

  • Random-weighted - This algorithm randomly orders the list of URLs that you enter in the Endpoint URI field for this business service, but some are retried more than others based on the value you enter in the Weight field.

  • None - This algorithm orders the list of URLs that you enter in the Endpoint URI field for this business service from top to bottom.

Endpoint URI

Enter an endpoint URL in the format based on the transport protocol you selected in the Protocol field. Following are descriptions of the URI formats for each transport. Optional URI elements are shown in brackets []. For more information on transport URIs, see the respective transport chapters in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus.

  • bpel-10gprotocol://host[:port] [/protocol-path]/domain/process[/version[/partnerlink/role]]

  • dsp - t3://dsp-ip-address:port/dsp-app-name

  • ejb - ejb:jndi_provider_name:ejb_jndi_name

    In the URI, jndi_provider_name is the name of the Oracle Service Bus JNDI provider resource, and ejb_jndi_name is the JNDI name in the JNDI server for the EJB.

    If the JNDI provider is located on the same server, the JNDI provider need not be specified. The URI then would be ejb::ejb_jndi_name

    Note: If your EJBs are running on IBM WebSphere, ejb_jndi_name must be in the following format:

    cell/nodes/node_name/servers/server_name/ejb_jndi_name

    or

    cell/clusters/cluster_name/ejb_jndi_name

    as described in the IBM WebSphere documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.iseries.doc/info/iseriesnd/ae/rnam_example_prop3.html

  • email - You can enter multiple endpoint URIs in any combination of the following formats:

    mailto:name@domain_name.com

    mailto:name@domain_name.com?smtp=smtp_server_resource

    mailto:name@domain_name.com?mailsession=jndi_mail_session

  • file - file:///root-dir/dir1

  • ftp - ftp://hostname:port/directory

  • http - http://host:port/someService

    The HTTP transport supports both HTTP and HTTPS endpoints.

  • jca - jca://<resource_adapter_jndi>

  • jejb - jndi_provider_name:ejb_jndi_name

    In the URI, jndi_provider_name is the name of the Oracle Service Bus JNDI provider resource, and ejb_jndi_name is the JNDI name in the JNDI server for the EJB.

    EJB 2.1 example: jejb:myProvider:osb.jejb.myJejbBiz21

    EJB 3.0 example: jejb:myProvider:myBiz31#osb.jejb.myJejbBiz

    Note: If your EJBs are running on IBM WebSphere, ejb_jndi_name must be in the following format:

    cell/nodes/node_name/servers/server_name/ejb_jndi_name

    or

    cell/clusters/cluster_name/ejb_jndi_name

    as described in the IBM WebSphere documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.iseries.doc/info/iseriesnd/ae/rnam_example_prop3.html

Endpoint URI (continued)

  • jms - jms://host:port[,host:port]*/connection_factory/jndi_destination

    To target a JMS destination to multiple servers, use the following URI format: jms://host1:port,host2:port/connection_factory/jndi_destination

    You can also omit host and port from the URI to have the lookup performed on the local machine. For example:

    jms:///connection_factory/jndi_destination

    Note: While Oracle WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Oracle Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see "Configure foreign servers" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help at http://www.oracle.com/pls/as1111/lookup?id=WLACH.

    In a cluster: The host names in the JMS URI must exactly match the host names of the cluster servers as they are configured in Oracle WebLogic Server.

  • mq - mq://local-queue-name?conn=mq-connection-resource-ref

    local-queue-name is the name of the MQ queue from which the business service reads messages.

    mq-connection-resource-ref is the path (project/folder) and name of the MQ connection resource; for example, default/my_MQconnection.

    Note: The Endpoint URI cannot contain spaces, so do not create MQ Connection resources or projects/folders with spaces in the names.

    To make the MQ transport available in Oracle Service Bus, see "MQ Transport" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1117.

  • sb - sb://<jndi_provider_name/>service_name

    jndi_provider_name (optional) is the name of the Oracle Service Bus JNDI provider resource. When omitted, the default context is used.

    service_name is a target service and corresponds to the remote proxy service URI.

  • sftp - sftp://hostname:port/directory

  • soa-direct[protocol://authority]/default/compositeName[!versionNumber[*label]]/serviceName

    The protocol and authority are optional when the SOA services are co-located on the same server as Oracle Service Bus.

  • tuxedo - tuxedo:resourcename/remotename

    tuxedo-queue:sendQSpace/sendQName[/[rcvQspace:]rvcQname][/failureQname]

    In the URI, resourcename corresponds to a WTC Import name and remotename corresponds to the service name exported by the remote Tuxedo domain. The URI resourcename is required, and the remotename is optional.

    If more than one URI is specified, you must have unique resource names for the endpoints. If no remote name is specified, its value is the value of the resource name. If no remote name is entered or if remote and resource name are the same, only one URI is allowed. In this case resource name and remote name have the same value. This allows already defined WTC Imports to make use of WTC load-balancing and failover.

  • ws - http://host:port/someService

    Note: Oracle Service Bus no longer supports duplicate endpoint URIs within the same business service.

    Click Add to add one or more additional URIs. At run time, the URLs are selected based on the load balancing algorithm you selected in the Load Balancing Algorithm field.

    If you selected Random-weighted in the Load Balancing Algorithm field, you can also enter a weight in the Endpoint URI field. The default is 1.

    If you have multiple endpoint defined, and you selected None in the Load Balancing Algorithm field, the order of endpoints is significant. You can reorder the endpoints using the Up and Down buttons.

    Oracle Service Bus does not support duplicate endpoint URIs within the same business service.

Retry count

In case of delivery failure when sending outbound requests, specify the number of times to retry individual URL endpoints; in other words, the number of failover attempts.

For example, a business service has one configured URI (U1) and the number of retries is set to 3. If U1 fails on the first attempt, the system retries the U1 endpoint 3 more times.

If a business service has 2 configured URIs (U1 and U2) and a retry count of 3, if the first attempt (for example, to U1) fails, the system tries (fails over to) the next URI (U2). If that also fails, the system makes two more attempts, once to U1 and once to U2.

Retry Iteration Interval

Specify the number of seconds the system pauses before iterating over all the endpoint URIs in the list again.

For example, a business service has two configured URIs (U1 and U2) and a retry count of 2 with a retry iteration interval of 5 seconds. If the first attempt (to U1) fails, the system tries U2 right away. But if U2 also fails, the system waits for 5 seconds and retries U1 once more.

Retry Application Errors

Select Yes or No.

In case of delivery failure when sending outbound requests, specify whether or not to retry endpoint URIs based on application errors (for example, a SOAP fault).


4.2.5 Business Service Message Handling Configuration Page

Use the Business Service Message Handling Configuration page to specify how Oracle Service Bus is to encode outbound messages sent by business services and whether Oracle Service Bus should stream attachments in outbound response messages instead of buffering the attachment contents in memory.

Using this page, you can enable the business service to encode outbound messages in MTOM/XOP format. SOAP Message Transmission Optimization Mechanism (MTOM) is a method of sending binary data to and from Web services. MTOM uses XML-binary Optimized Packaging (XOP) to transfer the binary data.

Using this page, you can also enable the business service to store attachments in outbound response messages to a disk file and then process the data in a streaming fashion without buffering the attachment contents in memory. This enables the business service to process large attachments robustly and efficiently.

Table 4-7 Business Service Message Handling Options

Option Description

XOP/MTOM Support

Oracle Service Bus supports XOP/MTOM using the following transports:

  • HTTP/S

  • Local

  • SB

Select the Enabled check box to enable the business service to encode outbound messages in MTOM/XOP format. Note that this option is disabled for imported business services that are based on previous release configurations.

If XOP/MTOM Support is enabled, select how to handle binary data in the $header and $body message context variables from among the following options:

  • Include Binary Data by Reference: (Default) In an outbound response message, replace xop:Include elements with ctx:binary-content elements when setting up the $body message context variable.

  • Include Binary Data by Value: In an outbound response message, replace xop:Include elements with base64-encoded text versions of corresponding binary data when setting up the $body message context variable.

Note that if XOP/MTOM Support is enabled for a business service, it is not required that every outbound message be in the MTOM format. Instead, this setting specifies that the business service is capable of handling an MTOM payload.

Since Oracle Service Bus does not support a combination of MTOM and SwA, the system issues a runtime error when Oracle Service Bus attempts to dispatch an outbound request to a business service and the business service is both MTOM/XOP-enabled and the $attachments message context variable is not null.

Attachments

Oracle Service Bus supports streaming MIME attachments using the HTTP/S transport.

Select the Page Attachments to Disk check box to enable the business service to stream attachments in outbound response messages.

Note that if you enable XOP/MTOM Support, the Attachments option is only available if you choose the Include Binary Data by Reference option under XOP/MTOM Support. Note also that payloads that contain attachments must conform to RFC 822. Specifically, lines containing Internet headers need to be terminated with CRLF (carriage return line feed).

Result Caching

If you invoke business services whose results seldom change, result caching improves business service performance by returning cached results to the client instead of invoking an external service directly.

To use result caching for business services, you must first enable it globally, as described in "Enabling Result Caching Globally" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG1294.

Configure result caching in the Advanced Settings section using the following guidelines:

  • Select the Supported option. When you do, the remaining fields are enabled.

  • Cache Token Expression – Oracle Service Bus uses a cache key to identify cached results for retrieval or population, and the cache token portion of the cache key provides the unique identifier. You can use an expression—the Cache Token Expression—to generate the cache token part of the cache key to uniquely identify a cached result for the business service. Click Expression to build the expression.

    To generate the cache token from a value in the request, use an expression that gets the value from the message $body, $header, $operation, or $transportMetaData ($outbound/ctx:transport/ctx:request or $outbound/ctx:transport/ctx:response). For example, you can populate the cache-token from a customer ID in the $body.

    In the Service Result Caching Expression builder, you can also select the namespace for the expression in the Namespace Definitions tab.

    The Cache Token Expression must resolve to a String or the value of simple content, such as an attribute or an element with no child elements. If the expression evaluates to null or causes an error, results are not cached.

    Note: You can also generate the cache token from the request (in the proxy service message flow that invokes the business service), without setting a Cache Token Expression in the business service configuration. To do this, include a value in $outbound/ctx:transport/ctx:request/ctx:cache-token in the proxy service pipeline. Any value in that cache-token overrides the Cache Token Expression in the business service configuration.

Result Caching continued

  • Expiration Time – Expiration Time, or time-to-live (TTL), determines when an entry in the business service's result cache is flushed. A duration of zero (0) means no expiration. A negative duration means do not cache. Select one of the following:

    Use Default – The default is the expiry-delay value in DOMAIN_HOME/config/osb/coherence/osb-coherence-config.xml. The default is 5 minutes.

    Duration – Set a specific length of time.

    XQuery Expression – You can enter an XQuery expression that gets an Expiration Time value from the request or response. Select Request or Response.

    To generate the expiration time from a value in the request or response, use an expression that gets the value from the $body, $header, $operation, or $transportMetaData ($outbound/ctx:transport/ctx:request or $outbound/ctx:transport/ctx:response). For example, use a value you have set in the Cache-Control HTTP header.

    In the Caching Expression builder, you can also select the namespace for the expression using the Namespace Definitions tab.

    Expiration Time must resolve to an Integer (representing seconds), an XQuery dayTimeDuration (XSD type), or the integer value of simple content representing seconds, such as an attribute or an element with no child elements. If the expression evaluates to null or causes an error, results are not cached.

    Note: You can also generate the expiration from the request, without setting an Expiration Time in the business service configuration. To do this, include a value in $outbound/ctx:transport/ctx:request/ctx:cache-ttl in the proxy service pipeline. Any value in the cache-ttl element overrides the Expiration Time in the business service configuration.

For a more detailed description of result caching, see “Improving Performance by Caching Business Service Results” in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG170.


4.2.6 Business Service - Service Policy Configuration Page

Use the Business Service - Service Policy Configuration page to configure service policy settings for a business service.

Note: The policy binding models are mutually exclusive. You must use only one type of policy in a service. If you bind policies directly to the service, all WSDL-based policies are ignored.

Table 4-8 Business Service Service Policy Configuration Options

Option Description

From OWSM Policy Store

Policies are defined in the central Oracle Web Services Manager Policy Store managed by Oracle Enterprise Manager. These policies support WS-Security 1.0/1.1, SAML 1.1/2.0, KerberosToken Profile, and other industry standards.

To add Oracle Web Services Manager policies to services in the IDE, you must be connected to a running server that has Oracle Web Services Manager enabled. For information, see "Securing Oracle Service Bus with Oracle Web Services Manager" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1681.

Note: When working with multiple servers in Eclipse, Eclipse chooses the first valid Oracle Service Bus server in the list of servers for retrieval of Oracle Web Services Manager policies.

Use category filtering to help you find the policy you want. For business services, only client-side policies are displayed.

If a WSDL used to create a business service contains embedded standard WS-Security policies, Oracle Service Bus throws an error and displays a conflict. To resolve this conflict, replace the embedded WSDL policies with compatible Oracle Web Services Manager policies by selecting From OWSM Policy Store and clicking Add Compatible Policies. Oracle Service Bus makes a best-effort attempt at finding the closest matching policy from the Oracle Web Services Manager policy store based on the standard policy embedded in the WSDL. The algorithm may return zero, one, or multiple matching policies.

If after clicking Add Compatible Policies Oracle Service Bus finds no compatible policies, click Add and select the appropriate Oracle Web Services Manager policies. If Oracle Service Bus returns more than one compatible policy, delete the policies you do not want to use.

After adding policies, you can provide overrides on the Security page.

From WSDL

Select this option if the service policy is associated with the WSDL upon which the service is based. These policies support WS-Security 1.0, SAML 1.1, and other industry standards.

Note: If you receive an error in the business service configuration about WS-Security Policies not supported by Oracle Service Bus, use the From OWSM Policy Store option to replace the embedded WSDL policies with compatible OWSM policies.

From Pre-defined Policy or WS-Policy Resource

Select this option to add service-level policies, operation-level policies (in which case the policy applies to both the request and response messages), request policies, and response policies directly.

Policies are either pre-defined in Oracle WebLogic Server or user-defined in Oracle Service Bus with a WS-Policy resource. These policies support WS-Security 1.0, SAML 1.1, and other industry standards.


4.2.7 Business Service Security Configuration Page

Use the Security configuration page to provide overrides to security policies used in the business service.

Table 4-9 Business Service Security Configuration Options

Option Description

Service Account

Click Browse and select a service account from the list displayed. If no service account is specified, an anonymous subject is used.

Note: This option is not available for services that use Oracle Web Services Manager policies, because user credentials are provided by override keys.

For more information, see Section 4.19, "Service Accounts".

Policy Overrides

For OWSM policies, provide any desired overrides that are allowed.

For more information, see Table 4-8 and "Securing Oracle Service Bus with Oracle Web Services Manager" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1681.


4.3 Proxy Service Configuration

You configure new proxy services in the proxy service editor after you create a new proxy service. You can view and modify those settings in the Proxy Service editor: The proxy service configuration pages are:

4.3.1 Proxy Service General Configuration Page

Use the Proxy Service General Configuration page to set or modify general configuration properties for a proxy service.

4.3.1.1 Proxy Service Editor Options

The following table describes the options in the editor:

Table 4-10 Proxy Service Editor Options

Option Description

Description

Enter a description for this proxy service.

Service Type (editor only)

This option shows the service type of the proxy service. You can change only some of the properties of some of the service types:

  • WSDL Web Service - Select this option to create a proxy service based on a WSDL. Then enter the WSDL name, qualified by its path (for example, myProject/myFolder/myWSDL). Alternatively, click Browse to select a WSDL resource. You can enter (or click Browse to select) a different port or binding from the same WSDL. You can also specify a different WSDL, but by doing so, you are effectively creating a new service and you will have to configure it as if it were a new service.

    (port or binding) - Enter the name of a port (defined in the WSDL) to describe an actual transport address, or enter the name of a binding (defined in the WSDL) to map to a transport address. If you use Browse to select a WSDL, the Select a WSDL Definition dialog lists any defined ports and bindings.

    Note: If you are going to use the SOAP Body Type for operations, ensure that the WSDL does not have two operations with the same input message. The SOAP Body Type operation cannot be uniquely identified by inspecting the input message.

  • Transport Typed Service - Select this option to create a JEJB proxy service.

  • Messaging Service - Select this option 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.

    (HTTP GET is supported only in the Any XML Service and Messaging Service service types.)

  • Any SOAP Service - Select this option to create a SOAP service that does not have an explicitly defined, concrete interface. You can change the SOAP version (SOAP 1.1 or SOAP 1.2)

  • Any XML Service - Select this option to create an XML service that does not have an explicitly defined, concrete interface.

    (HTTP GET is supported only in the Any XML Service and Messaging Service service types.)


4.3.2 Proxy Service Message Type Configuration Page

Use Proxy Service Message Type Configuration page to configure message types for a proxy service whose type is Messaging Service.

The binding definition for messaging services consists of configuring the content-types of the messages that are exchanged. The content-type for the response does not have 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).

Note:

E-mail, File, FTP, or SFTP transport proxy services whose type is Messaging Service support one-way messaging only; the Response Message Type should be None. If you select an option other than None, the E-mail, File, FTP, or SFTP protocols will not be available on the Transport Configuration page.

Table 4-11 Proxy Service Message Type Options

Option Description

Request Message Type

Select a message type for the request message:

  • None - Select this option if there is no request message.

  • Binary - Select this option if the content-type of the message is unknown or not important.

  • Text - Select this option if the message can be restricted to text.

  • MFL - Select this option if the message is a binary document conforming to an MFL definition. Enter the MFL file name (qualified by its path), or click Browse to select a file.

    You can configure only one MFL file.

    Note: To support multiple MFL files, define the content as binary or text and use the MFL action in the message flow to convert to XML.

  • XML - Select this option if the message is an XML document. Enter the XML file name (qualified by its path), or click Browse to select a file.

    Optionally provide some type information by declaring (in the element or type field) the XML schema type of the XML document exchanged.

  • Java - Select this option if a Java Object is being sent in the request. The JMS transport is used for Java Object messages. For more information, see "Sending and Receiving Java Objects in Messages" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1874.

Response Message Type

Select a message type for the response message:

  • None - Select this option if there is no response message.

    Note: If you are using a Reply action in the pipeline to propagate success or failure messages from a service to the calling client, select an option other than None. The None option blocks the reply.

  • Binary - Select this option if the content-type of the message is unknown or not important.

  • Text - Select this option if the message can be restricted to text.

  • MFL - Select this option if the message is a binary document conforming to an MFL definition. Enter the MFL file name (qualified by its path), or click Browse to select a file.

    You can configure only one MFL file.

    Note: To support multiple MFL files, define the content as binary or text and use the MFL action in the message flow to convert to XML.

  • XML - Select this option if the message is an XML document. Enter the XML file name (qualified by its path), or click Browse to select a file.

    Optionally provide some type information by declaring (in the element or type field) the XML schema type of the XML document exchanged.

  • Java - Select this option if a Java Object is being received in the response. The JMS transport is used for Java Object messages. For more information, see "Sending and Receiving Java Objects in Messages" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1874.


4.3.3 Proxy Service Operation Selection Configuration Page

Use Proxy Service Operation Selection Configuration page to enforce WS-I compliance (for SOAP 1.1 services only) and 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.

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

Oracle Service Bus is generally very forgiving if an inbound message is either missing data such that the operation cannot be determined, or has data that does not correspond to a valid operation. Both of these conditions result in $operation being empty. Rather than reject all such messages, Oracle Service Bus does not initialize the operation variable in the context but otherwise continues to process the message.

However, security requirements are enforced if the proxy service is WSDL-based and at least one of the following conditions is true:

  • The WSDL has a WS-Security policy and the proxy is an active intermediary.

  • The proxy has message-level custom authentication (either custom token or username/password).

If these conditions are met, then there is a runtime check to make sure the operation selection algorithm returns a valid operation name. If the operation selection returns null or an operation that is not in the WSDL, then the message is rejected and an error is raised.

Table 4-12 Proxy Service Operation Selection Options

Option Description

Enforce WS-I Compliance

Select or deselect this check box to specify whether or not the service is to conform to the Basic Profile defined by the Web Services Interoperability Organization. This option is available for or SOAP 1.1 services only

When a service is marked WS-I compliant, checks are performed against the messages sent to and from that service.

For proxies, checks are performed against request messages received by the proxy. For invoked services (i.e. services invoked by a proxy via service callout action or route node), checks are performed against the response messages received from those services. Note that it is the WS-I compliance property of the invoked service and not the proxy that determines whether or not checks are performed against messages received from the invoked service. If you specify WS-I compliance testing for an invoked service, the message flow generates a fault for response errors.

Selection Algorithm

Select one of the following and perform any required additional steps:

  • Transport Header - Select this algorithm to define the transport header that contains the lookup value. Then:

  • In the Header Name field, enter the transport header that extracts the value used as a key to select the operation being invoked.

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

  • SOAPAction Header - Select this algorithm to specify that operation mapping be done automatically from the WSDL associated with this proxy service.

  • WS-Addressing - Select this algorithm to specify that the lookup value is contained by the WS-Addressing Action tag located in the SOAP headers of the SOAP message. Then, 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.

  • SOAP Header - Select this algorithm to define an XPath expression to be evaluated against the SOAP headers. This allows you to get the lookup value. Then:

  • In the XPath Expression field, specify the XPath expression that extracts the value used as a key to select the operation being invoked.

  • In the Operation Mapping field, specify the value for each operation in the Value field. The value is used as the key of the operation.

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

    If the proxy service is configured for a Web Service security pass-through scenario with an encrypted body, you cannot select this algorithm. A similar caveat applies to pass-through encrypted SOAP headers.

    If you have a WSDL that has two operations with the same input message, do not select this algorithm for operations, because the operation cannot be uniquely identified by inspecting the input message.

  • Payload Type - Available only for XML services based on a WSDL port or WSDL binding.

Header Name

This option is available only when the Selection Algorithm option is set to Transport Header.

Enter the transport header that extracts the value used as a key to select the operation being invoked.

XPath Expression

This option is available only when the Selection Algorithm option is set to SOAPHeader.

Specify the XPath expression that extracts the value used as a key to select the operation being invoked.

Operation Mapping

This option is available only when the Selection Algorithm option is set to Transport Header, WS-Addressing, or SOAP Body Type.

Specify the value for each operation in the Value field. The value is used as the key of the operation.


4.3.4 Proxy Service Message Handling Configuration Page

Use the Proxy Service Message Handling Configuration page to specify different aspects of message handling, as described in Table 4-13.

Table 4-13 Proxy Service Message Handling Options

Option Description

Transaction Required

Select this option to ensure Oracle Service Bus executes the proxy service message flow in the context of a transaction. If a global transaction already exists, the transport provider propagates it in the request (even if you do not select this option). If no global transaction exists, the message flow run time starts a transaction. If the message flow run time starts a transaction, the transaction context begins before the service configuration is validated or run (for example, security checking or WS-I validation), and before message flow execution, ensuring that all processing and execution occurs in the transaction context.

If the message flow run time starts a transaction, quality of service is exactly-once. However, if Service Callouts or Publish actions have the outbound quality of service parameter set to best-effort (the default), Oracle Service Bus executes those actions outside of the transaction context. To have Oracle Service Bus execute those actions in the same request transaction context, set quality of service on those actions to exactly-once.

The service maintains its messaging pattern (synchronous, asynchronous, one-way) regardless of the setting on this option.

For transaction timeouts, the global transaction timeout value configured in the Oracle WebLogic Server Console applies.

Exceptions in Transactions

Oracle Service Bus invokes the system error handler for failed transactions. You cannot catch failed transaction exceptions in a user-configured error handler. For synchronous patterns, a transaction exception is returned through the response. For asynchronous patterns, where the transaction is designed to be committed in the request, the exception is sent back on the request thread.

Note that in asynchronous patterns, an error in the response that occurs after transaction committal in the request does not affect the transaction.

Same Transaction for Response

This option applies only to one-way and asynchronous messaging patterns.

If you select this option, Oracle Service Bus propagates the transaction context from the request thread to the response thread.

If you select this option, the message pattern becomes synchronous automatically, regardless of the initial message pattern setting (such as asynchronous or one-way).

You would not use this option, for example, if the business service in the request required a transaction committal before sending the response, such as in a one-way pattern.

For transaction timeouts, the global transaction timeout value configured in the Oracle WebLogic Server Console applies.

Content Streaming

Select this option to stream message content rather than store it in memory.

Select the Enabled check box and choose the following:

  • Whether to buffer the intermediate content in memory (Memory Buffer) or to a disk file (Disk Buffer)

  • Whether to enable Compression

For more information, see "Streaming body Content" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG314.

XOP/MTOM Support

SOAP Message Transmission Optimization Mechanism (MTOM) is a method of sending binary data to and from Web services. MTOM uses XML-binary Optimized Packaging (XOP) to transfer the binary data.

Use this option to decode and parse inbound messages in MTOM/XOP format and to send responses using the MTOM/XOP format, when appropriate.

Oracle Service Bus supports XOP/MTOM using the following transports:

  • HTTP/S

  • Local

  • SB

Select the Enabled check box to enable the proxy service to decode and parse inbound messages in MTOM/XOP format and to send responses using the MTOM/XOP format, when appropriate. Note that this option is disabled for imported proxy services that are based on previous release configurations.

If XOP/MTOM Support is enabled, select how to handle binary data in the $header and $body message context variables from among the following options:

  • Include Binary Data by Reference: (Default) In an inbound request message, replace xop:Include elements with ctx:binary-content elements when setting up the $header and $body message context variables.

  • Include Binary Data by Value: In an inbound request message, replace xop:Include elements with base64-encoded text versions of corresponding binary data when setting up the $header and $body message context variables.

Use Include Binary Data by Reference when you need direct access to binary data, for example to pass data to a Java callout or Message Format Language (MFL) transform.

Use Include Binary Data by Value in the following cases:

  • To bridge between MTOM and non-MTOM services. For example, consider an MTOM-enabled proxy service that receives a request that is then routed to a non-MTOM-enabled service. You could use this option to comply with existing standards for sending binary data in XML in base64-encoded form.

  • To validate the contents of the message against an XML schema that requires a base64binary element to be used in place of binary data

Note that if XOP/MTOM Support is enabled for a proxy service, it is not required that every inbound message be in the MTOM format. Instead, this setting specifies that when an MTOM-formatted message arrives, the proxy service should handle it accordingly.

Note also that when proxy services not enabled for XOP/MTOM Support receive an MTOM-formatted message, the service rejects the message and issues a runtime error.

Attachments

Use this option to have the proxy service store MIME attachment content to a disk file and then process the data in a streaming fashion without buffering the attachment contents in memory. This enables the proxy service to process large attachments robustly and efficiently.

Oracle Service Bus supports streaming MIME attachments using the following transports:

  • HTTP/S

  • Local (when chained through an HTTP proxy with streaming attachments enabled)

Select the Page Attachments to Disk check box to enable the proxy service to stream MIME attachments. When enabled for HTTP proxy services, the option applies to proxy service inbound request messages.

Note that if you select XOP/MTOM Support, the Attachments option is only available if you choose the Include Binary Data by Reference option under XOP/MTOM Support. Note also that payloads that contain attachments must conform to RFC 822. Specifically, lines containing Internet headers need to be terminated with CRLF (carriage return line feed).


4.3.5 Proxy Service SOAP Binding Configuration Page

This page is displayed only if the service you are creating has operations.

Use the Proxy Service SOAP Binding Configuration page to enforce WS-I compliance (for SOAP 1.1 services only) and 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.

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

Oracle Service Bus is generally very forgiving if an inbound message is either missing data such that the operation cannot be determined, or has data that does not correspond to a valid operation. Both of these conditions result in $operation being empty. Rather than reject all such messages, Oracle Service Bus does not initialize the operation variable in the context but otherwise continues to process the message.

However, security requirements are enforced if the proxy service is WSDL-based and at least one of the following conditions is true:

  • The WSDL has a WS-Security policy and the proxy is an active intermediary.

  • The proxy has message-level custom authentication (either custom token or user name/password).

If these conditions are met, then there is a runtime check to make sure the operation selection algorithm returns a valid operation name. If the operation selection returns null or an operation that is not in the WSDL, then the message is rejected and an error is raised.

Table 4-14 Proxy Service SOAP Binding Options

Option Description

Enforce WS-I Compliance

For SOAP 1.1 services only:

Select or deselect this check box if you want to specify whether or not the service is to conform to the Basic Profile defined by the Web Services Interoperability Organization.

When a service is marked WS-I compliant, checks are performed against the messages sent to and from that service. For proxies, checks are performed against request messages received by the proxy. For invoked services (i.e. services invoked by a proxy via service callout action or route node), checks are performed against the response messages received from those services. Note that it is the WS-I compliance property of the invoked service and not the proxy that determines whether or not checks are performed against messages received from the invoked service. If you specify WS-I compliance testing for an invoked service, the message flow generates a fault for response errors.


4.3.6 Proxy Service Transport Configuration Page

Use the Proxy Service Transport Configuration page to select a transport protocol for the proxy service and to set other general transport configuration settings.

Note:

Inbound transport-level security applies to the client applications and Oracle Service Bus proxy services. Outbound transport-level security applies to the connections between Oracle Service Bus proxy services and business services.

Table 4-15 Proxy Service Transport Configuration Options

Option Description

Protocol

Select a transport protocol from the list. The protocols available differ, depending on the service type you are creating:

  • WSDL Web Service: http, jca, jms, local, sb, ws

  • Transport Typed Service: jejb

  • Messaging Service: email, file, ftp, http, jms, local, mq (if available), sftp, tuxedo

  • Any SOAP Service: http, jms, local, sb

  • Any XML Service: email, file, ftp, http, jms, local, mq (if available), sb, sftp, tuxedo

Endpoint URI

Enter an endpoint URI in the format based on the transport protocol you selected in the Protocol field, above: The formats are:

  • email - mailfrom:mail-server-host:port

  • file - file:///root-dir/dir1

  • ftp - ftp://hostname:port/directory

  • http - /someName

    The HTTP transport supports both HTTP and HTTPS endpoints.

  • jca - jca://<resource_adapter_jndi>

  • jejb – The URL format is ejb_jndi_name. The URI configured for a JEJB proxy service becomes the global JNDI name for locating the stateless session bean generated by the JEJB transport from the remote/business interface in the client JAR.

    Note: For EJB 3.0, ejb_jndi_name is the mappedName attribute of the @javax.ejb.Stateless annotation in the generated bean. The lookup JNDI name for the generated EJB service is suffixed with #interface_class, which is the fully qualified name of the business interface.

    You can access the JEJB proxy service as:

    EJB 2.1 - protocol://host:port/_ejb_jndi_name

    EJB 3.0 - protocol://host:port/ejb_jndi_name#interface_class

    Note: If your EJBs are running on IBM WebSphere, ejb_jndi_name must be in the following format:

    cell/nodes/node_name/servers/server_name/ejb_jndi_name

    or

    cell/clusters/cluster_name/ejb_jndi_name

    as described in the IBM WebSphere documentation at http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.iseries.doc/info/iseriesnd/ae/rnam_example_prop3.html

  • jms - jms://host:port[,host:port]*/connection_factory/jndi_destination

    To target a target a JMS destination to multiple servers, use the following URI format:

    jms://host1:port,host2:port/QueueConnectionFactory/DestName

    Note that when you create a proxy service, you can configure a JMS endpoint URI even if the server at that endpoint if not available. However, in the case of JMS, when you activate the session, the endpoint must be available.

    You can also omit host and port from the URI to have the lookup performed on the local machine. For example:

    jms:///connection_factory/jndi_destination

    Note: While Oracle WebLogic Server allows forward slashes in JNDI names, such as "myqueues/myqueue", JNDI names with forward slashes interfere with the URI format required by Oracle Service Bus, and you cannot use those names. To work around this issue, define a JMS foreign server and reference that foreign server in the URI. For more information, see "Configure foreign servers" in the Oracle Fusion Middleware Oracle WebLogic Server Administration Console Online Help at http://www.oracle.com/pls/as1111/lookup?id=WLACH.

    In a cluster: The host names in the JMS URI must exactly match the host names of the cluster servers as they are configured in Oracle WebLogic Server.

  • local

    This transport does not require an endpoint URI.

Endpoint URI (continued)

  • mq - mq://local-queue-name?conn=mq-connection-resource-ref

    local-queue-name is the name of the MQ queue from which the proxy service reads messages.

    mq-connection-resource-ref is the path (project/folder) and name of the MQ connection resource; for example, default/my_MQconnection.

    Note: The Endpoint URI cannot contain spaces, so do not create MQ Connection resources or projects/folders with spaces in the names.

    To make the MQ transport available in Oracle Service Bus, see "MQ Transport" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1117.

  • sb - service_name

    service_name is the unique identifier for the proxy service. By default, this name will be the proxy service name.

    service_name must only contain characters permitted in URIs (as described in RFC2396 at http://www.ietf.org/rfc/rfc2396.txt), except it cannot contain forward slash (/) or colon (:) characters.

  • sftp - sftp://hostname:port/directory

  • tuxedo - servicename

    The URI servicename corresponds to a WTC Export that the remote Tuxedo domain identifies as a Tuxedo service.

    If more than one URI is specified, you must have unique resource names for the endpoints. If no remote name is specified, its value is the value of the resource name. If no remote name is entered or if remote and resource name are the same, only one URI is allowed. In this case resource name and remote name will have the same value. This allows users using already defined WTC Imports to make use of WTC load-balancing and failover.

    Note: If you configure two identical URIs, an error indicates that the service name already exists.

  • ws - /contextPath

    contextPath must be unique for proxy services that use either HTTP or WS transport.

Get All Headers

Select Yes to retrieve all the headers from the transport.

Select No to retrieve a defined set of headers. If you select No, enter a set of headers in the Header field, then click Add. (This step does not apply to Local transport.)

Note: Oracle Service Bus does not pass the HTTP Authorization header from the request to the pipeline because it opens a security vulnerability. You could inadvertently create a log action that writes the user name and unencrypted password to a log file. If your design pattern requires the HTTP Authorization header to be in the pipeline, do the following:

  1. In the startup command for Oracle Service Bus, set the following system property to true: com.bea.wli.sb.transports.http.GetHttpAuthorizationHeaderAllowed

  2. In Eclipse, on the Transport Configuration page, select Yes for Get All Headers or select No and specify Authorization.

  3. Restart Oracle Service Bus.

Oracle Service Bus will pass the Authorization header to the pipeline.


4.3.7 Proxy Service - Service Policy Configuration Page

Use Proxy Service - Service Policy Configuration page to configure service policies for a proxy service.

Table 4-16 Proxy Service Service Policy Options

Option Description

From OWSM Policy Store

Policies are defined in the central Oracle Web Services Manager Policy Store managed by Oracle Enterprise Manager. These policies support WS-Security 1.0/1.1, SAML 1.1/2.0, KerberosToken Profile, and other industry standards.

To add Oracle Web Services Manager policies to services in the IDE, you must be connected to a running server that has Oracle Web Services Manager enabled.

Note: When working with multiple servers in Eclipse, Eclipse chooses the first valid Oracle Service Bus server in the list of servers for retrieval of Oracle Web Services Manager policies.

Use category filtering to help you find the policy you want. For proxy services, only service policies are displayed.

After adding policies, you can provide overrides on the Security page.

For information, see "Securing Oracle Service Bus with Oracle Web Services Manager" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1681.

From WSDL

Select this option if the service policy is associated with the WSDL upon which the service is based. These policies support WS-Security 1.0, SAML 1.1, and other industry standards.

From Pre-defined Policy or WS-Policy Resource

Select this option to add service-level policies, operation-level policies (in which case the policy applies to both the request and response messages), request policies, and response policies directly.

Policies are either pre-defined in Oracle WebLogic Server or user-defined in Oracle Service Bus with a WS-Policy resource. These policies support WS-Security 1.0, SAML 1.1, and other industry standards.


4.3.8 Proxy Service Security Configuration Page

Use the Proxy Service Message Level Security Configuration page to configure security for proxy services.

For WLS 9.2 policies, message-level custom tokens and message-level user name and password are supported on proxy services of the following binding types:

  • WSDL-SOAP

  • WSDL-XML

  • Abstract SOAP

  • Abstract XML

  • Mixed - XML (in the request)

  • Mixed - MFL (in the request)

The configuration for both custom user name/password and custom token is similar. In both cases, you specify XPath expressions that enable Oracle Service Bus to locate the necessary information. The root of these XPath expressions is as follows:

  • Use soap-env:Envelope/soap-env:Header if the service binding is AnySOAP or WSDL-SOAP.

  • Use soap-env:Body if the service binding is not SOAP based.

All XPath expressions must be in a valid XPath 2.0 format. The XPath expressions must use the XPath "declare namespace" syntax to declare any namespaces used, as follows:

declare namespace ns='http://webservices.mycompany.com/MyExampleService';)

Table 4-17 Proxy Service Message-Level Security Options

Option Description

Service Key Provider

The name of a service key provider to be used by the service.

You can enter the path (project/folder) and name of a service key provider, or click Browse to select one.

A service key provider is only required in certain cases:

  • Outbound two-way TLS/SSL, where the proxy service routes messages to HTTPS services that require client-certificate authentication.

  • In some Web Service security scenarios, for example, if the proxy service requires messages to be encrypted.

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.

Policy Overrides

For OWSM policies, provide any desired overrides that are allowed.

For more information, see Table 4-16 and "Securing Oracle Service Bus with Oracle Web Services Manager" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1681.

Process WS-Security Header

If a client request includes a WS-Security security header, decide whether or not to process this header:

  • Select Yes: In an active intermediary scenario, the client applies WS-Security to the request and/or response messages. The proxy service processes the security header and enforces the WS-Security policy.

    This option is automatically set to Yes when a proxy service is based on a WSDL that has a security policy or when you attach a policy to the service on the Service Policy Configuration page.

  • Select No: In a WS-Security pass-through scenario, the client applies WS-Security to the request and/or response messages. The proxy service does not process the security header. Instead, it passes the secured request message untouched to a business service.

Custom Authentication Settings

Select one of the following:

  • None - if the service will not use custom authentication.

  • Custom User Name and Password - if the service will use a custom name and password, specified as XPath expressions

  • Custom Token - if the service will use a custom token

Custom User Name and Password - User Name XPath

The user name, specified as an XPath expression.

The XPath expression is evaluated against the message headers or payload, as appropriate, which allows Oracle Service Bus to obtain the user name and for custom authentication.

Custom User Name and Password - User Password XPath

The password, specified as an XPath expression.

The XPath expression is evaluated against the message headers or payload, as appropriate, which allows Oracle Service Bus to obtain the password values for custom authentication.

Custom Token - Token Type

Enter the type for the custom token type. Only the active token types configured for an Oracle WebLogic Server Identity Assertion provider can be used.

Custom Token - Token XPath

An XPath expression that specifies a path to the custom token. Oracle Service Bus evaluates the Token XPath expression against the message headers or payload, as appropriate, to obtain the token for custom authentication.

To create or edit an expression, click <XPath> (or the expression_fragment, if one is already defined) to display the XPath Expression Editor.

Custom User Name and Password - Context Properties

or

Custom Token - Context Properties

Optionally, specify one or more context properties to pass additional context information to the Authentication (Custom User Name and Password) or Identity Assertion (Custom Token) security provider.

Context Properties provide a way (the ContextHandler interface) to pass additional information to the WebLogic Security Framework so that a security provider can obtain contextual information.

Enter the Property Name as a literal string, and the Value Selector as a valid XPath expression. (XPath expressions can also be literal strings.)

The XPath expressions are evaluated against the same message-part that is used for the custom token or custom user name/password. That is, the Value Selector XPath expressions for SOAP-based proxy services evaluate against the header and against the payload for non-SOAP-based proxy services.

The XPath expression is evaluated at runtime to produce the property's value. A ContextHandler is essentially a name/value list and, as such, it requires that a security provider know what names to look for. Therefore, the XPath expressions are evaluated only if a security provider asks for the value of one of these user-defined properties.

Click Add Property to add this context property. You can add multiple context properties.


4.4 Oracle Service Bus Configurations and Projects

The following are provided for working with Oracle Service Bus configurations and projects.

4.4.1 Oracle Service Bus Configurations View

This view displays a hierarchical list of all your Oracle Service Bus configurations and the projects they contain. See also Section 4.4.2, "New Oracle Service Bus Configuration Project Wizard."

You can do the following in the Configurations view:

  • Edit the configuration:

    1. Right click the configuration you want to edit.

    2. Select Properties from the menu.

    3. Modify information as needed in the Oracle Service Bus Configuration Page.

  • Create a new configuration:

    1. Right-click anywhere in the view.

    2. Select New Oracle Service Bus Configuration from the menu.

    3. Enter information as needed in the Oracle Service Bus Configuration Page.

  • Move a project from one configuration to another by dragging it from the source configuration to the target configuration. You can also drag a project from the Project Explorer.

  • Delete a configuration project:

    1. Right-click the configuration you want to delete.

    2. Select Delete from the menu.

4.4.2 New Oracle Service Bus Configuration Project Wizard

Use this wizard to create an Oracle Service Bus configuration project. For configuration options, see Section 4.4.3, "Oracle Service Bus Configuration Page."

4.4.3 Oracle Service Bus Configuration Page

An Oracle Service Bus configuration project is a grouping of Oracle Service Bus projects and resources destined for a server, a location for system resources (SMTP, UDDI, and such), and a container for validation; for example, a resource in a project associated with one Oracle Service Bus configuration cannot refer to a resource in a project associated to another Oracle Service Bus configuration.

Use this page to create a new Oracle Service Bus configuration project (in the New Oracle Service Bus Configuration Project wizard) or to configure an existing one (in the Properties for Oracle Service Bus Configuration editor).

The preserve, session, and customization file settings are used when publishing an Oracle Service Bus configuration to the server, and used as defaults when configuring the Export Wizard - Export to Server - Select Resources Page.

Table 4-18 Oracle Service Bus Configuration Options

Option Description

Configuration name

Enter a name for this Oracle Service Bus configuration or keep the default.

Preserve environment variable values

Select this check box when you are re-importing a resource but want to preserve environment variable values in the existing resource.

Preserve security and policy settings

Select this check box to preserve the security configuration (excluding access control policies) and the references to the WS-policies bound directly to the service (instead of bound to the WSDL).

Preserve credentials (user name and password)

Select this check box to preserve PKI credentials in service key providers, user name and passwords in service accounts, and user name and password credentials in SMTP servers, JNDI providers, and UDDI registries.

Discard session if activation fails

Select this check box to discard the session if the activation fails (for example, due to conflicts).

Session Name

The session name.

Description

The session description.

Deployment customization file

Specify a customization.xml file or click Browse, locate the file, then click Open. For information on customization, see "Creating Customization Files" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG1360.

Keystore file

Specify a keystore.jks file or click Browse, locate the file, then click Open.

The key store settings are used when configuring a service key provider.

Password

Enter the password that you use to secure access to the key store.

Server

The name of the server associated with this Oracle Service Bus configuration. This setting is automatically configured unless there is more than one server from which to choose. When multiple servers are associated with the same Oracle Service Bus configuration, use the list to select the server you want to associate with this Oracle Service Bus configuration.

The server setting is only used for transport specific configuration, when the transport benefits from being connected to a server (for example, when configuring the dispatch policy setting in the HTTP transport).


4.4.4 New Oracle Service Bus Project

Use this page to create a new Oracle Service Bus project.

Table 4-19 New Oracle Service Bus Project Options

Option Description

Project name

Enter a unique name for the project.

Oracle Service Bus Configuration

Select an existing Oracle Service Bus configuration or click New to open the New Oracle Service Bus Configuration Project Wizard, where you can create a new configuration.


4.5 Custom Resources

You can define custom resources for use by Oracle Service Bus using the New Custom Resource wizard and the Custom Resource editor, as described in the following topics:

4.5.1 New Custom Resource Wizard

Use this wizard to create a new custom resource.

4.5.2 New Custom Resource Editor

Use this editor to modify the configuration of a custom resource. The General page identifies the type of custom resource. The Custom page provides options for editing the configuration for that type of custom resource.

4.5.3 New Custom Resource - Resource Type Page

Use this page to select the type of custom resource to create. Select the type of custom resource to create from the list of available resource type.

4.5.4 Custom MQ Resource Configuration Page

Use this page to configure a custom MQ connection resource. For information on MQ connection resources and MQ transports, see the following:

Table 4-20 MQ Resource Options

Option Description

Connection Type

Select one of the following modes for connecting to the MQ queue manager:

  • tcp mode—Use TCP/IP to connect to a queue manager that does not reside on the same machine as Oracle Service Bus.

  • binding mode—Use the bindings mode to connect to a queue manager that is located on the same machine as Oracle Service Bus.

MQ Host Name

For tcp mode connections only:

Enter the host name of the MQ queue manager.

MQ Port Number

For tcp mode connections only:

Enter the port number of the MQ queue manager listener.

MQ Queue Manager Name

Enter the name of the MQ queue manager to which to connect.

Queue Manager CCSID

For tcp mode connections only:

The coded character set identifier (CCSID) to be used when establishing a connection. The CCSID is used mainly for internationalization support.

To learn more, see IBM's WebSphere MQ Fundamentals at http://www.redbooks.ibm.com/redbooks/SG247128/wwhelp/wwhimpl/java/html/wwhelp.htm.

MQ Queue Manager Channel Name

For tcp mode connections only:

Enter the queue manager server connection channel name.

SSL Required

For tcp mode connections:

Select the check box to use SSL for sending messages. Only server-side SSL is enabled when the 2-way SSL Required option is not selected.

Cipher Suite

This option is available only when the SSL Required check box is selected.

Select the Cipher Suite algorithm to be used by SSL.

The Cipher Suite algorithm is used to encrypt and decrypt message communications between the WebSphere MQ server and the WebSphere MQ client. Thus a Cipher Suite algorithm must be specified when using SSL to communicate with a WebSphere MQ server.

2-way SSL Required

This option is available only when the SSL Required check box is selected.

Select the check box to enable both client-side and server-side SSL authentication.

Reference to the Service Key Provider

If you selected 2-way SSL Required, you must provide a reference to the service key provider for obtaining the appropriate key store and trust store information.

Enter the path (project/folder) and name of a service key provider, or click Browse to select one from the Select Service Key Provider page.

Reference to the Static Service Account

For tcp mode connections only:

Required for user name and password authentication. Enter the path (project/folder) and name of a static service account, or click Browse to select service accounts from a browser.

WebSphere MQ Version

Select the WebSphere MQ version:

  • 5.3

  • 6.0

  • 7.0

MQ Connection Pool Size

Enter the size of the MQ connection pool.

MQ Connection Timeout

Enter the time interval in seconds after which unused connections are destroyed. The default is 1800 seconds.

MQ Connection Max Wait

Enter the Max Wait in seconds for the amount of time to wait for a connection to become available. If a connection is not made within that time interval, Oracle Service Bus throws an exception. The default is 3 seconds.


4.6 Export Wizard

The Export wizard contains the following pages:

4.6.1 Export Wizard - Oracle Service Bus Configuration JAR Export Page

Use this page to export Oracle Service Bus resources to a configuration JAR file. For more information, see "Exporting Resources" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG1320.

Table 4-21 Configuration JAR Export Options

Option Description

Oracle Service Bus Configuration

Select an existing Oracle Service Bus configuration and resources to export. Deselect resources you do not want to export.

Export Level

Select whether to export projects or resources.

Notes

A System project cannot be exported at the project level.

Exporting projects might cause resource deletion when you import the full project JAR file.

Include Dependencies

If you selected to export resources, select or clear this check box. Use the Include Dependencies option to export any other resources that this resource references

Export Destination

Enter the fully qualified name of a JAR file to export, or click Browse to select it.


4.6.2 Export Wizard - Export to Server - Select Resources Page

Use this page to select the projects or resources you want to export. Clear the check boxes next to any resources that you do not want to include in this export.

Table 4-22 Resource Export Options

Option Description

Resource

The name of the project and resource.

Deselect resources you do not want to export.

Operation

Create or update. The operation that will be performed on the resource.

Include Dependencies

Select this check box if you are exporting resources (not projects) and want to ensure that all the associated resources are exported.

Preserve environment variable values

Select this check box when you want to preserve (protect against overwriting) the environment variables values in the resource you are exporting.

Preserve security and policy settings

Select this check box to preserve the security configuration (excluding access control policies) and the references to the WS-policies bound directly to the service (instead of bound to the WSDL).

Preserve credentials (user name and password)

Select this check box to preserve PKI credentials in service key providers, user name and passwords in service accounts, and user name and password credentials in SMTP servers, JNDI providers, and UDDI registries.

Activate session after publish

Select this check box to create and activate a session in the Oracle Service Bus Administration Console.

Discard session if activation fails

Select this check box to discard the session if the activation fails (for example, due to conflicts).

Description

The session description.

Customization File

Specify a customization file or click Browse, locate the file, then click Open. For information on customization, see "Creating Customization Files" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG1360.


4.6.3 Export Wizard - Export to Server - Review Resources Page

Use this page to select the projects or resources you want to export.

Table 4-23 Resource Export Options

Option Description

Oracle Service Bus Configuration

Select an existing Oracle Service Bus configuration and resources to export.

Export Level

Select whether to export projects or resources.

Server

From the list, select an Oracle Service Bus destination server.

Session

The session name.


4.7 Import Wizard

The Import wizard has the following pages:

4.7.1 Import Wizard - Config JAR Import - Load Resources Page

Use this page to select a configuration JAR to import and an import destination. For more information, see "Importing Resources" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG1312.

Table 4-24 Configuration JAR Import

Option Description

Oracle Service Bus Configuration

Select an existing Oracle Service Bus configuration or click New to open the New Oracle Service Bus Configuration Project Wizard, where you can create a new configuration.

Jar

Select a full project JAR file or a resource JAR file that has been previously exported from another Oracle Service Bus domain.


4.7.2 Import Wizard - Config JAR Import - Review Resources Page

Use this page to select the objects on which you want to operate (create, update, or delete). Resources are only scheduled for deletion when the JAR being imported is a full project JAR and there are project resources in the importing system that are not present in the imported JAR file. To prevent resources from being deleted, deselect them.

Table 4-25 Configuration JAR Import Options

Option Description

Resources

The name of the project and resource.

Operation

Expand the Project folder to display the operations (create, update, delete) that will be performed on the resources.

To prevent resources from being deleted, deselect them. Resources are only scheduled for deletion when the JAR being imported is a full project JAR and there are project resources in the importing system that are not present in the imported JAR file.

Include Dependencies

Select this check box if you are importing a resource JAR file and want to ensure that all its associated resources are imported.

Passphrase

Enter the password that was used to encrypt the data.

Preserve environment variable values

Select this check box when you are re-importing a resource but want to preserve environment variable values in the existing resource.

Preserve security and policy settings

Select this check box to preserve the security configuration (excluding access control policies) and the references to the WS-Policies bound directly to the service (instead of bound to the WSDL).

Preserve credentials (user name and password)

Select this check box to preserve PKI credentials in service key providers, user name and passwords in service accounts, and user name and password credentials in SMTP servers, JNDI providers, and UDDI registries.


4.7.3 Import Wizard - Config ZIP Import - Load Resources Page

Use this page to select a ZIP file with resources to import and an import destination.

Table 4-26 Configuration ZIP Import

Option Description

Oracle Service Bus Configuration

Select an existing Oracle Service Bus configuration and an import destination (project or folder).

File Name

Enter the fully qualified name of a ZIP file to import, or click Browse to select it.


4.7.4 Import Wizard - Config ZIP Import - Review Resources Page

Use this page to select the objects you want to import. Clear the check boxes next to any resources that you do not want to include in this import.

Table 4-27 Configuration ZIP Import Options

Option Description

Resource

The name of the project and resource.

Operation

Create or update. The operation that will be performed on the resource.

File Name

The file name of the resource, including the file extension.


4.7.5 Import Wizard - URL Import - Load Resources Page

Use this page to import resources such as WSDLs or XML schemas that are available on the Web. You can import them, along with all their dependents, by specifying the URL of the root resource.

Table 4-28 URL Import Options

Option Description

Oracle Service Bus Configuration

Select an existing Oracle Service Bus configuration and an import destination (project or folder).

URL

Enter the URL where the file is located.

To specify a local resource, you can use the file protocol with a file name fully qualified by its path, for example, file:///c:/alsbresources/ForeachAction.jar.

Resource Name

Enter a name for the resource.

Resource Type

Select the type of resource from the list.


4.7.6 Import Wizard - URL Import - Review Resources Page

Use this page to select the objects you want to import. Clear the check boxes next to any resources that you do not want to include in this import.

Table 4-29 URL Import Options

Option Description

Resource

The name of the project and resource.

Operation

Create or update. The operation that will be performed on the resource.

URL

Enter the URL where the file is located.

To specify a local resource, you can use the file protocol with a file name fully qualified by its path, for example, file:///c:/alsbresources/ForeachAction.jar.


4.8 JNDI Providers

The following are provided for working with JNDI providers:

4.8.1 JNDI Provider Editor

Use this editor to modify an existing JNDI provider configuration. For descriptions of the fields, see the Section 4.8.2, "New JNDI Provider Resource Wizard."

4.8.2 New JNDI Provider Resource Wizard

Use this page to configure a new JNDI provider resource.

Table 4-30 New JNDI Provider Resource Options

Option Description

Description

Enter a description for the JNDI provider.

JNDI Cache

Keep the default Enabled option or select Disabled.

When enabled, the JNDI context and JNDI objects are cached locally which improves performance when doing an object lookup. Oracle recommends that you keep the JNDI cache enabled.

Provider URL

Enter the URL for the JNDI provider in the format: protocol://host:port

You can use any protocol, for example:

http, https, t3, t3s, iiop, iiops

JNDI Request Timeout

The JNDI request timeout in milliseconds. The default of zero (0) means no timeout.

User Name

If access to the target JNDI provider requires a user name and password, enter a user name in the User Name field, and the associated password in the Password and Confirm Password fields.

These fields are optional, and required only if the JNDI tree is secured.

Password

Enter the associated password.

Confirm Password

Enter the same password you entered for the Password field.


4.9 Proxy Servers

Use this page to configure and edit a proxy server resource after you create a new proxy server.

Table 4-31 Proxy Server Configuration Options

Option Description

Description

Enter a description of the proxy server resource.

User Name

Enter the user name used for proxy authentication.

Password

Enter the password associated with the user name.

Confirm Password

Enter the same password you entered for the Password field.

Host-Port Parameters

The list of proxy server hosts. You can configure multiple proxy servers for each proxy server resource. This enables Oracle Service Bus to perform load balancing and offer fault tolerance features for the proxy server resource.

The following options are available:

  • Click Add and specify the following information to configure a new proxy server for the resource:

  • Server Host: The host name or IP address of the proxy server.

    The Server Host name for the Oracle Service Bus proxy server must be identical to the server host name of the actual proxy server.

  • Clear Text Port: The proxy server clear-text port number.

  • SSL Port: The proxy server SSL port number.

  • Select a proxy server in the list and edit the Host-Port Parameters.

  • Select a proxy server in the list and click Delete to remove it from the resource configuration.


4.10 Message Flow Design Palette

The Message Flow Design Palette lists all the nodes and actions you can use to construct a message flow for a proxy service. To insert a node or an action into a message flow, drag the item from the palette to the Message Flow Editor. When you drag an item to the palette, one or more target icons indicate that you can drop the dragged item in that position on the palette. When you drag the item onto a target, the target icon is highlighted to show that you can drop the item there.

You can also add nodes and actions to message flows by right-clicking an object in the Message Flow Editor and choosing a node or action from the Insert, Insert Into, or Insert After submenus. You can also add an error handler by selecting the Add Error Handler command. These submenus and commands are context sensitive. That is, they appear only when it is legal to add the item into the selected context in the message flow.

The Message Flow Design Palette is organized into the following categories:

4.10.1 Message Flow Nodes

The following table describes the nodes you can add to a message flow:

Table 4-32 Message Flow Nodes

Node Description

Conditional branch

A branch node allows processing to proceed down exactly one of several possible paths.

For configuration properties, see Section 4.11.3, "Conditional Branch Node Properties."

Operational branch

An operational branch node determines what branch to follow based on specified operations.

For configuration properties, see Section 4.11.17, "Operational Branch Node Properties."

Pipeline pair

A pipeline pair node consists of a request pipeline and a response pipeline.

For configuration properties, see Section 4.11.18, "Pipeline Pair Node Properties."

Route

Route node actions define the handling of messages as they flow through the route node.

For configuration properties, see Section 4.11.27, "Route Node Properties."

Stage

A stage node is a container of actions.

For configuration properties, see Section 4.11.33, "Stage Node Properties."

Error handler

An error handler provides the logic for resending errors in the message flow.

For configuration properties, see Section 4.11.7, "Error Handler Node Properties."


4.10.2 Message Flow Route Actions - Communication Actions

The following table describes the communication actions you can add to a route in a message flow:

Table 4-33 Message Flow Route Node Communication Actions

Action Description

Dynamic routing

A dynamic routing action assigns a route for a message based on routing information available in an XQuery resource.

For configuration properties, see Section 4.11.6, "Dynamic Routing Action Properties."

Routing

A routing action identifies a target service for the message and configures how the message is routed to that service:

For configuration properties, see Section 4.11.28, "Routing Action Properties."

Routing table

A routing table action assigns a set of routes wrapped in a switch-style condition table. Different routes are selected based upon the results of a single XQuery expression.

For configuration properties, see Section 4.11.30, "Routing Table Action Properties."


4.10.3 Message Flow Route Actions - Flow Control Actions

The following table describes the flow control action you can add to a route in a message flow:

Table 4-34 Message Flow Route Node Flow Control Actions

Action Description

If-then

An if-then action performs an action or a set of actions conditionally, based on the Boolean result of an XQuery expression.

For configuration properties, see Section 4.11.9, "If-Then Action Properties."


4.10.4 Message Flow Stage Actions - Communication Actions

The following table describes the communication actions you can add to a stage in a message flow:

Table 4-35 Message Flow Stage Node Communication Actions

Action Description

Dynamic Publish

A dynamic publish action publishes a message to a service identified by an XQuery expression

For configuration properties, see Section 4.11.5, "Dynamic Publish Action Properties."

Publish

A publish action publishes a message to a statically specified service.

For configuration properties, see Section 4.11.19, "Publish Action Properties."

Publish Table

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

For configuration properties, see Section 4.11.20, "Publish Table Action Properties."

Routing Options

A routing options action modifies any or all of the following properties in the outbound request: URI, Quality of Service, Mode, Retry parameters, Message Priority.

For configuration properties, see Section 4.11.29, "Routing Options Action Properties."

Service Callout

A service callout action configures a synchronous (blocking) callout to an Oracle Service Bus-registered proxy or business service.

For configuration properties, see Section 4.11.31, "Service Callout Action Properties."

Transport Headers

A transport header action sets the transport header values in messages

For configuration properties, see Section 4.11.34, "Transport Headers Action Properties."


4.10.5 Message Flow Stage Actions - Flow Control Actions

The following table describes the flow control actions you can add to a stage in a message flow:

Table 4-36 Message Flow Stage Node Flow Control Actions

Action Description

For-Each

A for-each action iterates over a sequence of values and executes a block of actions

For configuration properties, see Section 4.11.8, "For-Each Action Properties."

If-Then

An if-then action performs an action or set of actions conditionally, based on the Boolean result of an XQuery expression.

For configuration properties, see Section 4.11.9.1, "If Action and Else-If Action Properties."

Raise error

A raise-error action raises an exception with a specified error code (a string) and description.

For configuration properties, see Section 4.11.21, "Raise Error Action Properties."

Reply

A reply action specifies that an immediate reply be sent to the invoker.

For configuration properties, see Section 4.11.24, "Reply Action Properties."

Skip

A skip action specifies that at run time, the execution of the current stage is skipped and the processing proceeds to the next stage in the message flow.

For configuration properties, see Section 4.11.32, "Skip Action Properties."

Resume

A resume action resumes message flow after an error is handled by an error handler.

For configuration properties, see Section 4.11.26, "Resume Action Properties."


4.10.6 Message Flow Stage Actions - Message Processing Actions

The following table describes the message processing actions you can add to a stage in a message flow:

Table 4-37 Message Flow Stage Node Message Processing Actions

Action Description

Assign

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

For configuration properties, see Section 4.11.2, "Assign Action Properties."

Delete

A delete action deletes a context variable or a set of nodes specified by an XPath expression.

For configuration properties, see Section 4.11.4, "Delete Action Properties."

Insert

An insert action inserts the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression.

For configuration properties, see Section 4.11.10, "Insert Action Properties."

Java callout

A Java callout action invokes a Java method from the pipeline.

For configuration properties, see Section 4.11.11, "Java Callout Action Properties."

MFL transform

A MFL transform action converts non-XML to XML or XML to non-XML in the pipeline.

For configuration properties, see Section 4.11.16, "MFL Transform Action Properties."

Rename

A rename action renames elements selected by an XPath expression without modifying the contents of the element.

For configuration properties, see Section 4.11.22, "Rename Action Properties."

Replace

A replace action replaces a node or the contents of a node specified by an XPath expression.

For configuration properties, see Section 4.11.23, "Replace Action Properties."

Validate

A validate action validates elements selected by an XPath expression against an XML schema element or a WSDL resource.

For configuration properties, see Section 4.11.35, "Validate Action Properties."


4.10.7 Message Flow Stage Actions - Reporting Actions

The following table describes the reporting actions you can add to a stage in a message flow:

Table 4-38 Message Flow Stage Node Reporting Actions

Action Description

Alert

An alert action ends an alert notification based on pipeline message context.

For configuration properties, see Section 4.11.1, "Alert Action Properties."

Log

A log action constructs a message to be logged.

For configuration properties, see Section 4.11.12, "Log Action Properties."

Report

A report action enables message reporting for a proxy service.

For configuration properties, see Section 4.11.25, "Report Action Properties."


4.11 Message Flow Editor

Use this editor to construct a proxy service message flow. To insert a node or an action into a message flow, drag the item from the Message Flow Design Palette to the editor. When you drag an item to the editor, one or more target icons indicate that you can drop the dragged item in that position on the palette. When you drag the item onto a target, the target icon is highlighted to show that you can drop the item there.

You can also add nodes and actions to message flows by right-clicking an object in the Message Flow Editor and choosing a node or action from the Insert, Insert Into, or Insert After submenus. You can also add an error handler by selecting the Add Error Handler command. These submenus and commands are context sensitive. That is, they appear only when it is legal to add the item into the selected context in the message flow.

When you select a node or action in the editor, a configuration page for that item is displayed in the Properties view. You can add or modify configuration properties in those pages. The message flow node and action properties configuration pages are:

4.11.1 Alert Action Properties

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

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

In the Message Flow Editor, click an alert action to display its properties in the Properties view. Use these properties pages to configure the selected alert action. The pages are:

  • Alert

  • Comment

  • Namespaces

  • Variables

The Alert page has the following options:

Table 4-39 Alert Action Options

Option Description

Expression

An XQuery expression that specifies the message context to be added to the alert message.

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Summary

A short description of the alert. This will be the subject line in the case of an e-mail notification and can contain no more than 80 characters. If no description is provided, a predefined subject line that reads, "ALSB Alert," will be used instead.

Severity

The severity level for this alert. Select a level from the list.

Destination

The destination for the alert. To specify a destination, click Browse to select an appropriate resource.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.2 Assign Action Properties

In a message flow, use an assign action to assign the result of an XQuery expression to a context variable.

In the Message Flow Editor, click an assign action to display its properties in the Properties view. Use these properties pages to configure the selected assign action. The pages are:

  • Assign

  • Comment

  • Namespaces

  • Variables

The Assign page has the following options:

Table 4-40 Assign Action Options

Option Description

Expression

An expression that creates the data that is assigned to variable named in the Variable field, described below.

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Variable

The variable to which the value created in the XQuery expression described above is assigned.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.3 Conditional Branch Node Properties

In a message flow, use a conditional branch node to specify that message processing is to proceed along exactly one of several possible paths, based on a result returned by an XPath condition.

Conditional branching is driven by a 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 at run time, its value is used to determine which branch to follow. If no branch matches the value of the lookup variable, the default branch is followed. You should design the proxy service in such a way that the value of the lookup variable is set before reaching the branch node.

In the Message Flow Editor, click a conditional branch node to display its properties in the Properties view. Use these properties pages to configure the selected conditional branch node. The pages are:

  • Flow

  • Conditional Branch

The Flow page has the following options:

Table 4-41 Flow Options

Option Description

Name

Enter a name for the conditional branch node.

Description

Enter a description for the conditional branch node.


The Conditional Branch page has the following options:

Table 4-42 Conditional Branch Options

Option Description

XPath

The XPath expression that defines the condition to be evaluated for determining the branch to follow.

To create or edit the XPath expression, click <XPath> (or the XPath_fragment, if one is already defined) to display the XPath Expression Editor.

Variable

Enter a context variable.


A conditional branch node also always contains one or more branches, which are configured as part of the node.

Click a Branch icon in a conditional branch node to display the Branch properties page in the Properties view. Use these properties pages to configure the selected branch node in a message flow. This page has the following options.

Table 4-43 Branch Options

Option Description

Label

A label for the branch. This label appears as the label for the branch in the Message Flow Editor.

Operator

Select an operator from the list to be used with the value in the next field, for creating the condition on which the branch is based.

Value

Enter a value to be used with the operator in the previous field, for creating the condition


4.11.4 Delete Action Properties

In a message flow, use a delete action to delete a context variable or a set of nodes specified by an XPath expression.

In the Message Flow Editor, click a delete action to display its properties in the Properties view. Use these properties pages to configure the selected delete action. The pages are:

  • Delete

  • Comment

  • Namespaces

  • Variables

The Delete page has the following options. Select Variable to delete a variable, or select XPath to delete an XPath expression.

Table 4-44 Delete Action Options

Option Description

Variable

Select this radio button to delete a context variable. Enter the name of the context variable to delete in the adjacent text field.

XPath

Select this radio button to delete all nodes selected by an XPath expression. Then:

  • To create or edit the XPath expression, click <XPath> (or the XPath_fragment, if one is already defined) to display the XPath Expression Editor.

  • After saving the expression, in the In Variable field, enter the context variable containing the nodes specified in the XPath expression.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.5 Dynamic Publish Action Properties

In a message flow, use a dynamic publish action to publish a message to a service specified by an XQuery expression.

In the Message Flow Editor, click a dynamic publish action to display its properties in the Properties view. Use these properties pages to configure the selected dynamic publish action. The pages are:

  • Dynamic Publish

  • Comment

  • Namespaces

  • Variables

The Dynamic Publish page has the following options:

Table 4-45 Dynamic Publish Action Options

Option Description

Service

An XQuery expression that defines the service to which a message is to be published.

To create or edit the expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

In the editor, enter an Xquery expression or select an XQuery resource that provides a result similar to:

<ctx:route>
<ctx:service isProxy="false">project/folder/businessservicename</ctx:service>
<ctx:operation>foo</ctx:operation>
</ctx:route>

Note: The element operation is optional.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.6 Dynamic Routing Action Properties

In a message flow, use a dynamic routing action to assign a route for a message based on routing information available in an XQuery resource.

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

In the Message Flow Editor, click a dynamic routing action to display its properties in the Properties view. Use these properties pages to configure the selected dynamic routing action. The pages are:

  • Dynamic Routing

  • Comment

  • Namespaces

  • Variables

The Dynamic Routing page has the following option:

Table 4-46 Dynamic Routing Action Properties

Option Description

Service

An XQuery expression that defines the route to be taken by a message.

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

In the XQuery/XSLT Expression editor, enter an Xquery expression, the result of which is similar to:

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

Note: If a proxy service is being invoked, isProxy attribute should be set to true.

  • The service name is the fully qualified service name.

  • The operation element is optional


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.7 Error Handler Node Properties

Use an error handler to specify what should happen if an error occurs in a specific location in the message flow.

All configuration for an error handler is in one or more stages contained by the error handler. See Section 4.11.33, "Stage Node Properties."

4.11.8 For-Each Action Properties

In a message flow, use the for-each action to iterate over a sequence of values and execute a block of actions.

In the Message Flow Editor, click a for-each action to display its properties in the Properties view. Use these properties pages to configure the selected for-each action. The pages are:

  • For Each

  • Comment

  • Namespaces

  • Variables

The For Each page has the following options:

Table 4-47 For-Each Action Properties

Option Description

For Each Variable

Enter the name of the variable on whose contents the for-each action(s) will be executed.

XPath

An XPath expression that specifies where in the structure of the containing context variable the variable specified in the For Each Variable field is located.

To create or edit the XPath expression, click <XPath> (or the XPath_fragment, if one is already defined) to display the XPath Expression Editor.

In Variable

The context variable containing the variable on whose contents the for-each action(s) will be executed.

Index Variable

A variable containing the current number of iterations in the loop.

Count Variable

A variable containing the total number of iterations.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.9 If-Then Action Properties

In a message flow, use an if-then action to perform an action or a set of actions conditionally, based on the Boolean result of an XQuery expression.

In the Message Flow Editor, click an if-then action to display its properties in the Properties view. Use this page to review and configure general properties of the if-then action. The pages are:

  • Comment

  • Namespaces

  • Variables

An if-then action always contains an if condition plus zero or more else-if condition, where you define the conditions for the if-then action. An if-then action also always contains an else condition, which defines the default path when no other condition is met.

Click an If:condition icon or an Else-If:condition icon in an if-then action to display their properties in the Properties view. Use these properties pages to configure the selected condition. This If condition properties page has the following option.

4.11.9.1 If Action and Else-If Action Properties

If actions and else-if actions are always contained by an if-then action. The message follows the path associated with the first if action or else-id action that returns true.

Table 4-48 If and Else-If Action Options

Option Description

Condition

A condition in an if action or an if-else action that contains one of the tests for following alternative paths in the flow.

To add or edit a condition 

  1. Click <Condition> (or condition_fragment, if one is already defined) to display the Condition Editor. Define a condition to be evaluated in the if-then action.

  2. When you finish editing the condition, add one or more action that will be executed when the condition evaluates to true. To add an action, drag it from the Design Palette to associate with the condition.

In the route node, you can select only the routing, dynamic routing, or routing table actions. However, these actions can contain request and response actions.

To add an Else-If condition:

Click add condition. Then add one or more actions to this else-if condition, as described above for the If condition. Continue with as many else-if conditions as your logic requires.

Condition actions can be nested.


4.11.9.2 Else Action Properties

The else action does not have associate properties. When all if and else-if conditions return false, the message proceeds down the path associated with the else action.

Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.10 Insert Action Properties

In a message flow, use an insert action to insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath expression.

In the Message Flow Editor, click an insert action to display its properties in the Properties view. Use these properties pages to configure the selected insert action. The pages are:

  • Insert

  • Comment

  • Namespaces

  • Variables

The Insert page has the following options:

Table 4-49 Insert Action Options

Option Description

Expression

The XQuery expression used to create the data that will be inserted at a specified location in a named variable.

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Location

The location where the insert is performed, relative to the result of the XPath expression: Options are:

  • Before—as sibling before each element or attribute selected by the XPath expression

  • After—as sibling after each element or attribute selected by the XPath expression

  • As first child of—as first child of each element identified by the XPath expression. An error occurs if the result of the XPath returns attributes.

  • As last child of—as last child of each element identified by the XPath expression. An error occurs if the XPath returns attributes.

XPath

Valid configurations include those in which:

  • XQuery and XPath expressions both return elements.

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

To create or edit the XPath expression, click <XPath> (or the XPath_fragment, if one is already defined) to display the XPath Expression Editor.

Variable

The context variable whose contents are evaluated by the XPath variable defined above. Enter the name of the variable in the text field.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.11 Java Callout Action Properties

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

In the Message Flow Editor, click a Java Callout action to display its properties in the Properties view. Use these properties pages to configure the selected Java callout action. The pages are:

  • Java Callout

  • Comment

  • Namespaces

  • Variables

The Java Callout page has the following options:

Table 4-50 Java Callout Action Options

Option Description

Method

An external Java method to be called from the message flow.

Click Browse to select a class and a static method from an archived resource. Once you have selected the class and method, a table appears on the Java Callout Properties page:

The Name column lists all the method's arguments.

The Action column provides an <Expression> or expression_fragment link to the XQuery/XSLT Expression Editor, where you can create an expression to retrieve a value for the argument.

Data types for the arguments must be one of the following:

  • Java.lang.String

  • Primitive types, and their corresponding class types (e.g., int vs. java.lang.Integer)

  • java.lang.BigDecimal, and java.lang.BigInteger (these types are used in financial calculations where round-off errors or overflows are not tolerable)

  • only org.apache.xbeans.XmlObject and no typed XML beans.

  • byte[]

  • java.lang.String[] (INPUT ONLY)

  • XmlObject [ ] (INPUT ONLY)

  • javax.activation.DataSource

If the type of the input value you enter does not match the declared input argument type, Oracle Service Bus tries to automatically typecast input values to the declared type of the input argument. For example a string value of "123" will be converted to integer 123 if the declared type of the input argument is java primitive int.

Return Parameter as Reference

Return Parameter as Reference: This option makes the return value of a Java Callout invocation a <java-content ref="jcid"> reference element regardless of its actual type, where jcid is the key to the object in the pipeline object repository. In the Result value field, enter the name of the variable to contain the java-content reference. This option lets you work with a referenced object in the message flow in addition to the pipeline XML for providing passthrough, performing message enrichment with Java Callout and inline actions, or performing message transformation between Java and non-Java transports. For more information, see "Sending and Receiving Java Objects in Messages" in the Oracle Fusion Middleware Developer's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBDV1874.

Result Type

The variable to which the result is assigned. The label for the field indicates the data type of the result.

If the result is a byte array (the only possible array returned), the binary-content XML element is returned.

Service Account

An optional Service Account, which can be specified if there is a security context for this Java method.

Click Browse to select a service account.

In the case of fixed and mapped service accounts, the userid/password from the service account is authenticated in the local system and the security context propagated to the Java callout. In the case of passthru, the security context is propagated to the Java callout. This context is the message level context if defined (with WS-Security). Otherwise, it is the transport level context.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.12 Log Action Properties

In a message flow, use the log action to construct a message to be logged and to define a set of attributes with which it will be logged.

In the Message Flow Editor, click a log action to display its properties in the Properties view. Use these properties pages to configure the selected log action. The pages are:

  • Log

  • Comment

  • Namespaces

  • Variables

The Log page has the following options:

Table 4-51 Log Action Options

Option Description

Expression

The message context to be logged through XQuery expressions on context variables.

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Annotation

Notes for this log action. These notes are logged along with the result of the previously defined expression.

Severity

The severity of the log message. Options are:

  • Debug - While your application is under development, you might find it useful to create and use messages that provide verbose descriptions of low-level activity within the application.

  • Info -Used for reporting normal operations; a low-level informational message.

  • Warning - A suspicious operation or configuration has occurred but it might not affect normal operation.

  • Error - A user error has occurred. The system or application can handle the error with no interruption and limited degradation of service.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.13 Message Flow Properties - Comment

In the Message Flow Editor, click a node or an action to display its properties in the Properties view. For most nodes and actions, one of the properties pages displayed (as a tab) is the Comment page. Use this page to add an optional comment about the item selected in the message flow.

4.11.14 Message Flow Properties - Namespaces

In the Message Flow Editor, click a node or an action to display its properties in the Properties view. For most nodes and actions, one of the properties pages displayed (as a tab) is the Namespaces page. Use this page to see a list of defined namespaces or to create a new namespace.

4.11.15 Message Flow Properties - Variables

In the Message Flow Editor, click a node or an action to display its properties in the Properties view. For many nodes and actions, one of the properties pages displayed (as a tab) is the Variables page. Use this page to see a list of all the predefined and user-defined context variables. Click Add to define a new variable.

4.11.16 MFL Transform Action Properties

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

In the Message Flow Editor, click a MFL transform action to display its properties in the Properties view. Use these properties pages to configure the selected MFL transform action. The pages are:

  • MFL Transform

  • Comment

  • Namespaces

  • Variables

The MFL Transform page has the following options:

Table 4-52 MFL Transform Action Options

Option Description

Apply Transform

The type of transform to be applied.

Select XML to Non-XML or Non-XML to XML, according to your requirement.

on <Expression>

The variable on which the MFL transformation action is to be performed.

Click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor, where you can specify the variable.

This input must be text or binary when transforming to XML, and must be XML when transforming to non-XML. Binary content in the message context is represented by the binary-content XML element. This XML should be the result of the Xquery expression when the input needs to be binary.

Resource

Select this option to perform an MFL transform action using a static MFL resource. Click Browse to select the resource.

Resource From

Select this option to specify an MFL resource that will perform the transform action.

Click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor, where you can specify the MFL resource that will perform the action, in the format project/folder/MFLresourcename.

Variable

The name of the variable to which the result of this transform action is to be assigned. The result will be a binary-content XML element.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.17 Operational Branch Node Properties

In a message flow, use an operational branch node to configure branching based on operations defined in a WSDL.

When message flows define WSDL-based proxy services, operation-specific processing is required. Instead of configuring a branching node based on operations manually, Oracle Service Bus provides a branching node that automatically branches based on operations. In other words, when you create an operational branch node in a message flow, you can quickly build your branching logic based on the operations defined in the WSDL, because the Oracle Service Bus plug-ins present those operations in the operational branch node configuration page.

A branch node allows processing to proceed along exactly one of several possible paths. Branching is driven by an XPath-based switch table. Each branch in the table specifies a condition (for example, <500) that is evaluated in order down the message flow against a single XPath expression (for example, ./ns: PurchaseOrder/ns:totalCost on $body). Whichever condition is satisfied first determines which branch is followed. If no branch condition is satisfied, then the default branch is followed. A branch node may have several descendants in the message flow: one for each branch, including the default branch.

When you add an operational branch node to a message flow in the Message Flow Editor, the node contains an initial conditional branches based on the first operation defined in the WSDL, plus a default branch, as shown in Figure 4-1.

Figure 4-1 Branch Node With "Submit" Operation From WSDL and "Default" Branch

Description of Figure 4-1 follows
Description of "Figure 4-1 Branch Node With "Submit" Operation From WSDL and "Default" Branch"

Click the node itself (the Operational Branch Node icon or the bounding box connected to the icon) to display the Flow properties page in the Properties view. You can provide a name and a description for the node on that page.

Click an operational branch icon to display the properties for that operational branch on the Operational Branch page. That page contains a list of all the operations defined in the WSDL. You can select a different operation for that branch. You can also click the plus sign in the operational branch node, in the Message Flow Editor, to add another operation branch.

After you have added all the branches, add nodes and stages to them to define the processing for each branch.

4.11.18 Pipeline Pair Node Properties

In a message flow, use a pipeline pair node to define request and response processing.

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.

A pipeline pair always contains a request pipeline and a response pipeline. Add stages and actions to those pipelines, as needed.

In the Message Flow Editor, click a pipeline pair node to display its properties in the Properties view. Use this properties page to configure the selected pipeline pair node. The options are:

Table 4-53 Pipeline Pair Node Options

Option Description

Name

Enter a name for the pipeline pair node.

Description

Enter a description for the pipeline pair node.


4.11.19 Publish Action Properties

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

In the Message Flow Editor, click a publish action to display its properties in the Properties view. Use these properties pages to configure the selected publish action. The pages are:

  • Publish

  • Comment

  • Namespaces

  • Variables

The Publish page has the following options:

Table 4-54 Publish Action Options

Option Description

Service

The target service for the publish action. Click Browse to select a proxy service or business service from a list.

Invoking

The operation to be invoked on the target service.

This option appears only if the selected service defines any operations.

To configure how the message is packaged and sent to the service, in the Request Actions field, click Add an Action. Then select an action to associate with the service. You can add more than one action.

Use inbound operation for outbound

Select this option to make the outbound operation the same as the inbound operation.

This option appears only if the selected service defines any operations.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.20 Publish Table Action Properties

In a message flow, use a publish table action to publish a message to zero or more statically specified services. Switch-style condition logic is used to determine at run time which services will be used for the publish. A publish table action contains one or more case actions to define conditions for following alternative paths (by default, via publish actions), as well as a default path to a default publish action. To fully define a publish table action, you must configure the publish table action, its case actions, and its publish actions (and any other actions you may add).

When you add a publish table action to a message flow in the Message Flow Editor, the publish table action contains a case action with a path to a publish action plus a default case action with a path to a default publish action, as shown in Figure 4-2. Click add condition to add another condition to the publish table.

Figure 4-2 Publish Table Action

Description of Figure 4-2 follows
Description of "Figure 4-2 Publish Table Action"

4.11.20.1 Publish Table Properties

In the Message Flow Editor, click the publish table action itself (the Publish Table icon or the bounding box connected to the icon) to display the Publish Tables properties page in the Properties view. Use these properties pages to configure the selected publish table action. The pages are:

  • Publish Table

  • Comment

  • Namespaces

  • Variables

The Publish Table properties page has the following option:

Table 4-55 Publish Table Options

Option Description

Expression

An XQuery expression, which at run time returns the value upon which the routing decision will be made.

To create or edit an XQuery expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.20.2 Case Action Properties

In the Message Flow Editor, click a case action to display its properties in the Properties view. Use this properties page to configure the selected case action, as described below:

Table 4-56 Case Action Options

Option Description

Operator and Value

Select a comparison operator from the list. Then enter a value against which the value returned from the XQuery expression defined for the publish table action will be evaluate


4.11.20.3 Publish Action Properties

See Section 4.11.19, "Publish Action Properties."

4.11.21 Raise Error Action Properties

In a message flow, use the raise error action to raise an exception with a specified error code (a string) and description.

In the Message Flow Editor, click a raise error action to display its properties in the Properties view. Use these properties pages to configure the selected raise error action. The pages are:

  • Raise Error

  • Comment

  • Namespaces

  • Variables

The Raise Error page has the following options:

Table 4-57 Raise Error Action Options

Option Description

Code

The error code to be raised.

Message

Description of the error code


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.21.1 Transactions

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

4.11.22 Rename Action Properties

In a message flow, use the rename action to rename elements selected by an XPath expression without modifying the contents of the element.

In the Message Flow Editor, click a rename action to display its properties in the Properties view. Use these properties pages to configure the selected rename action. The pages are:

  • Rename

  • Comment

  • Namespaces

  • Variables

The Rename page has the following options:

Table 4-58 Rename Action Options

Option Description

XPath

An XPath expression used to specify the data (in the named variable) that will be renamed.

To create or edit the XPath expression, click <XPath> (or the XPath_fragment, if one is already defined) to display the XPath Expression Editor.

In Variable

The context variable that holds the element you want to rename.

Enter the name of the variable in this field.

Localname

A local name to use to rename the selected elements.

Enter the local name in this field.

Namespace

A namespace to use when renaming the selected elements.

Enter the namespace in this field.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.23 Replace Action Properties

In a message flow, use a replace action to replace a node or the contents of a node specified by an XPath expression. The node or its contents are replaced with the value returned by an XQuery expression.

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

In the Message Flow Editor, click a replace action to display its properties in the Properties view. Use these properties pages to configure the selected replace action. The pages are:

  • Replace

  • Comment

  • Namespaces

  • Variables

The Replace page has the following options:

Table 4-59 Replace Action Options

Option Description

XPath

The XPath expression used to specify the data (in the named variable) that will be replaced.

To create or edit the XPath expression, click <XPath> (or the XPath_fragment, if one is already defined) to display the XPath Expression Editor.

Variable

Enter a context variable.

Expression

The XQuery expression used to create the data that replaces the data specified by the XPath in the named variable.

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Replace entire node

or

Replace node contents

When you finish editing the XQuery expression, select one of the options:

  • Replace entire node—to specify that the nodes selected by the XPath expression you defined are replaced along with all of its contents

  • Replace node contents—to specify that the node is not replaced; only the contents are replaced.

Note: Selecting the Replace node contents option and leaving the XPath field blank is more efficient than selecting the Replace entire node option and setting the XPath to ./*


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.24 Reply Action Properties

In a message flow, use the reply action to specify that an immediate reply be sent to the invoker.

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

In the Message Flow Editor, click a reply action to display its properties in the Properties view. Use these properties pages to configure the selected reply action. The pages are:

  • Assign

  • Comment

  • Namespaces

  • Variables

The Reply page has the following options:

Table 4-60 Reply Action Options

Option Description

With Success

or

With Failure

Select With Success to reply that the message was successful, or select With Failure to reply that the message has a fault. Reply With Failure will cause a transaction, if started by Oracle Service Bus, to be aborted.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.25 Report Action Properties

In a message flow, use the report action to enable message reporting for a proxy service.

In the Message Flow Editor, click a report action to display its properties in the Properties view. Use these properties pages to configure the selected report action. The pages are:

  • Report

  • Comment

  • Namespaces

  • Variables

The Report page has the following option:

Table 4-61 Report Action Options

Option Description

Expression

The XQuery expression used to create the data that will be reported.

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Search Keys

When you finish editing the XQuery expression, click Add a Key to add one or more key value pairs to be used to extract key identifiers from any message context variable or message payload. (The rest of the message is ignored.) The keys are a convenient way to identify a message.

In the Key Name: Name field enter a name for the key.In the Key Value column, click <XPath> to create the XPath expression in the XPath Expression Editor.In the In variable field, enter the name of the variable on which the expression will be executed.


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

  • Key name = errorCode

  • Key value = ./ctx:errorCode in variable fault

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

Table 4-62 Report Action Execution Results

Report Index DB TimeStamp Inbound Service Error Code

errorCode=BEA-382505

04/26/07 9:45 AM

MortgageBroker/ProxySvcs/loanGateway3

BEA-382505

errorCode=BEA-382505

04/26/07 9:45 AM

same

BEA-382505


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.26 Resume Action Properties

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

In the Message Flow Editor, click a resume action to display its properties in the Properties view. Use these properties pages to configure the selected resume action. The pages are:

  • Comment

  • Namespaces

  • Variables

Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.27 Route Node Properties

In a message flow, use the route node to handle request and response dispatching of messages to and from business services. No other nodes can follow a route node.

In the Message Flow Editor, click a route node to display its properties in the Properties view. Use these properties pages to configure the selected route node. The pages are:

  • Route

  • Namespaces

  • Variables

The Route page has the following option:

Table 4-63 Route Node Options

Option Description

Name

Enter a name for the route node.

Description

Enter a description for the route node.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.28 Routing Action Properties

In a message flow, use a routing action to identify a target service for the message and configure how the message is routed to that service.

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

In the Message Flow Editor, click a routing action to display its properties in the Properties view. Use these properties pages to configure the selected routing action. The pages are:

  • Routing

  • Comment

  • Namespaces

  • Variables

The Routing page has the following option:

Table 4-64 Routing Action Options

Option Description

Service

The target service for the routing action. Click Browse to select a proxy service or business service from a list.

Invoking

The operation to be invoked on the target service.

This option appears only if the selected service defines any operations.

To configure how the message is packaged and sent to the service, in the Request Actions field, click Add an Action. Then select an action to associate with the service. You can add more than one action.

Use inbound operation for outbound

Select this option to make the outbound operation the same as the inbound operation.

This option appears only if the selected service defines any operations.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.29 Routing Options Action Properties

In a message flow, use a routing options action to modify any or all of the following properties in the outbound request: URI, Quality of Service, Mode, Retry parameters, Message Priority.

In the Message Flow Editor, click a routing options action to display its properties in the Properties view. Use these properties pages to configure the selected routing options action. The pages are:

  • Routing Options

  • Comment

  • Namespaces

  • Variables

The Routing Options page has the following option:

Table 4-65 Routing Options Action Properties

Option Description

URI

Select this option to set the URI for the outbound message:

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Enter an expression that returns a URI. This overrides the URI for the invoked service.

Note: When routing to another proxy service, the URI override has no effect.

QoS

Select this option to set the Quality of Service element:

Select a QoS option from the list. This overrides the default.

Mode

Select this option to set the mode to Request or Request-Response.

Select the mode from the list.

Note: This is normally already automatically set, based on the interface of the service invoked. However, in some cases like Any Soap or Any XML services, this is not so.

Retry Interval

Select this option to set the retry interval.

Specify the number of seconds between retries. This overrides the default configured with the invoked service.

Retry Count

Select this option to set the retry count.

Specify the number of retries the system must attempt before discontinuing the action. This overrides the default configured with the invoked service.

Priority

Select this option to set the message priority:

To create or edit an expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.

Enter an expression that returns a positive integer.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.30 Routing Table Action Properties

In a message flow, use a routing table to select different routes based upon the results of a single XQuery expression. A routing table action contains a set of routes wrapped in a switch-style condition table.

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

When you add a routing table action to a message flow in the Message Flow Editor, the routing table action contains a case action with a path to a routing action plus a default case action with a path to a default routing action, as shown in Figure 4-3. Click add condition to add another condition to the routing table.

Figure 4-3 Routing Table Action

Description of Figure 4-3 follows
Description of "Figure 4-3 Routing Table Action"

4.11.30.1 Routing Table Properties

In the Message Flow Editor, click the publish table action itself (the Publish Table icon or the bounding box connected to the icon) to display the Publish Tables properties page in the Properties view. Use these properties pages to configure the selected publish table action. The pages are:

  • Routing Table

  • Comment

  • Namespaces

  • Variables

The Routing Table properties page has the following option:

Table 4-66 Routing Table Options

Option Description

Expression

An XQuery expression, which at run time returns the value upon which the routing decision will be made.

To create or edit an XQuery expression, click <Expression> (or the expression_fragment, if one is already defined) to display the XQuery/XSLT Expression Editor.


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.30.2 Case Action Properties

In the Message Flow Editor, click a case action to display its properties in the Properties view. Use this properties page to configure the selected case action, as described below:

Table 4-67 Case Action Options

Option Description

Operator and Value

Select a comparison operator from the list. Then enter a value against which the value returned from the XQuery expression defined for the routing table action will be evaluate


4.11.30.3 Routing Action Properties

See Section 4.11.28, "Routing Action Properties."

4.11.31 Service Callout Action Properties

In a message flow, use a service callout action to configure a synchronous (blocking) callout to an Oracle Service Bus-registered proxy or business service.

In the Message Flow Editor, click a service callout action to display its properties in the Properties view. Use these properties pages to configure the selected service callout action. The pages are:

  • Service Callout

  • Comment

  • Namespaces

  • Variables

The Service Callout page has the following options:

Table 4-68 Service Callout Action Options

Option Description

Service

The target service for the service callout action. Click Browse to select a proxy service or business service from a list.

Invoking

The operation to be invoked on the target service.

This option appears only if the selected service is WSDL-based and has operations that can be invoked on the service.

Note: Selecting an operation, which Oracle Service Bus requires for many reasons, does not guarantee that only the selected operation is invoked. For example, if you select OperationA, but a message also contains an invocation for Operation B, then OperationB will be invoked as well.

Configure Soap Body

or

Configure Payload Document

Specify how you want to configure the request and response messages by selecting one of the following options:

  • Select Configure SOAP Body to configure the SOAP Body. Selecting this option allows you to use $body directly.

    This option supports SOAP-RPC encoded, which is not supported when configuring payload parameters or document.

  • Select Configure Payload Parameters or Configure Payload Document to configure the payload.


Subsequent configuration options depend on the kind of service you selected and on the kind of configuration options you chose. Table 4-69 shows the options available for each service type.

Table 4-69 SOAP Body, Payload Parameters, and Payload Document Options

Selected Service Type "Configure SOAP Body" Options "Configure Payload Parameters" Options or "Configure Payload Document" Options

SOAP RPC

See "SOAP Request Body and SOAP Response Body" in the following table.

(Optional) See "SOAP Request Header and SOAP Response Header" in the following table.

See "Request Parameters and Response Parameters" (optional)

(Optional) See "SOAP Request Header and SOAP Response Header" in the following table.

SOAP Document and Any SOAP

See "SOAP Request Body and SOAP Response Body" in the following table.

(Optional) See "SOAP Request Header and SOAP Response Header" in the following table.

See "Request Document and Response Document" in the following table.

(Optional) See "SOAP Request Header and SOAP Response Header" in the following table.

XML, Any XML, and Messaging

See "SOAP Request Body and SOAP Response Body" in the following table.

See "Request Document and Response Document" in the following table.


The following table provides instructions for each of the options listed in the previous table.

Table 4-70 SOAP Body, Payload Parameters, and Payload Document Option Descriptions

For These Options... Follow These Steps...

SOAP Request Body and SOAP Response Body

To configure these options:

  • In the SOAP Request Body field, enter the name of a variable to hold the XML of the SOAP Body element for the callout request.

  • In the SOAP Response Body field, enter the name of a variable to which the XML of the SOAP Body element on the response will be bound.

SOAP Request Header and SOAP Response Header

To configure these options:

  • In the SOAP Request Header field, enter the name of a variable to hold the XML of the SOAP Header element for the callout request

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

  • In the SOAP Response Header field, enter the name of a variable to which the XML of the SOAP Headers on the response, if any, will be bound.

Request Parameters and Response Parameters

To configure options:

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

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

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

  • In the Response Parameters fields, enter the names of the variables to which the responses will be assigned at run time.

Request Document and Response Document

To configure these options:

  • In the Request Document Variable field, enter the name of a variable to assign a request document to.

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

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

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

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

  • For services that expect binary data, the variables must have a ctx:binary-content element.

  • For services that expect MFL data, the variable must have the XML equivalent.

  • For services that expect text data, the variable is a string.

  • In the Response Document Variable field, enter the name of the variable to which a response document will be assigned at run time.


Optionally, add one or more transport header actions. For more information about transport header actions, see Section 4.11.34, "Transport Headers Action Properties."

Note:

In addition to the transport headers you specify, headers are added by the Oracle Service Bus binding layer.

Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

4.11.32 Skip Action Properties

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

In the Message Flow Editor, click a skip action to display its properties in the Properties view. Use these properties pages to configure the selected skip action. The pages are:

  • Comment

  • Namespaces

  • Variables

Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.33 Stage Node Properties

In a message flow, use a stage node as a container for actions in a message flow. You can string multiple stages together, to compartmentalize processing logic.

In the Message Flow Editor, click a stage node to display its properties in the Properties view. Use these properties pages to configure the selected stage node. The pages are:

  • Stage

  • Namespaces

  • Variables

The Stage page has the following options:

Table 4-71 Start Node Options

Option Description

Name

Enter a name for the stage node.

Description

Enter a description of the stage node.


Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.34 Transport Headers Action Properties

In a message flow, use a transport header action to set header values in messages.

In the Message Flow Editor, click a transport headers action to display its properties in the Properties view. Use these properties pages to configure the selected transport headers action. The pages are:

  • Transport Headers

  • Comment

  • Namespaces

  • Variables

The Transport Header page has the following options:

Table 4-72 Transport Header Action Options

Option Description

Direction

From the Set Transport Headers for list, select one of the following, to specify to the run time which of the message context locations are to be modified:

  • Outbound Request - Select this option to set header values for outbound requests (the messages sent out by a proxy service in route, publish, or service callout actions). This header element is located in the message context as follows:

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

    $inbound/ctx:transport/ctx:response/tp:headers 
    

Pass All Headers

Select this option to pass all headers through from the inbound message to the outbound message or vice versa. Every header in the source set of headers will be copied to the target header set, overwriting any existing values in the target header set.

Headers

Click Add Header to add a header to the Headers table. Then configure each header as described in the following rows.

You can add as many headers as necessary to this table. You do not have to order the headers in the table, because the run time declares namespaces and places header elements in their proper order when generating the corresponding XML.

Headers: Name:

Specify a header by doing either of the following:

  • From the list in the Name column, select a header name. The list contains all of the predefined header names for the target transport (for example, Content-Type for HTTP transports, JMSCorrelationID for JMS transports, etc.).

  • Enter a header name in the Other field. If that header name is not one of the predefined headers for this service's transport, it becomes a user-header, as defined by the transport specification.

Headers: Action

Select one of the options in this column to specify how to set the header's value:

  • Set Header to Expression

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

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

    Caution: Not all of the header settings you can specify in this action are honored at run time.

  • Delete Header

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

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

    or

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

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

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


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.11.35 Validate Action Properties

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

In the Message Flow Editor, click a validate action to display its properties in the Properties view. Use these properties pages to configure the selected validate action. The pages are:

  • Validate

  • Comment

  • Namespaces

  • Variables

The Validate page has the following options:

Table 4-73 Validate Action Options

Option Description

XPath

An XPath expression that specifies the elements to be validated.

To create or edit the XPath expression, click <XPath> (or the XPath_fragment, if one is already defined) to display the XPath Expression Editor.

In Variable

The name of the variable to hold the element to be validated. Enter the name of the variable, or, if Content Assist is on, press Ctrl-Space to display a list of declared variables.

Against Resource

An XML schema element or a WSDL resource against which the elements selected by the XPath expression (in the XPath field described above) are validated.

Save Variable

or

Raise Error

To save the result of this validation (a boolean result), select Save Variable and enter the name of the variable in which you want to save the result.

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


Use the Comment page to add a comment, if desired:

Use the Namespaces page to see a list of defined namespaces or to create a new one.

Use the Variables page to see a list of defined context variables or to create a new one.

4.12 Modify JAR Dependencies Dialog

In Oracle Service Bus, JAR resources can contain classes that depend on other classes in different JARs. Use the Modify JAR Dependencies page to add or remove referenced JAR resources. Use the Up and Down buttons to reorder the hierarchy (order of precedence) of referenced JARs. For more information, see "JARs" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG898.

Table 4-74 Modify JAR Dependencies Properties

Option Description

Available JARs

The project name and the name of the folder, if applicable, in which the JAR resources reside. This column shows all available JARs in the current workspace.

JAR references

The name and path of the referenced JAR resources. This column shows all the JARs currently configured as dependencies.


4.13 SMTP Servers

The following editor and wizard are provided for working with SMTP servers:

4.13.1 Edit SMTP Server Page

Use this page to view the details of an SMTP server and edit the configuration, if required. For descriptions of the fields, see the Section 4.13.2, "New SMTP Server Resource Wizard."

If you rename an SMTP resource, the new name is automatically updated in the any e-mail business services that reference the SMTP resource in the endpoint URI.

4.13.2 New SMTP Server Resource Wizard

Use this page to configure a new SMTP server resource.

Table 4-75 New SMTP Server Options

Option Description

Description

Enter a description for this SMTP server resource.

Server URL

Enter the URL that points to the SMTP server. This is a required field.

Port Number

Enter a port number for the SMTP server (the default port is 25). This is a required field.

User Name

If access to the target SMTP server requires a user name and password, enter a user name in the User Name field, and the associated password in the Password and Confirm Password fields.

These fields are optional, and required only if the SMTP server is secured.

Password

Enter the associated password.

Confirm Password

Enter the same password you entered for the Password field.


4.14 UDDI Registry Configuration Page

Use this page to configure a UDDI registry resource. This page is displayed in the New UDDI Registry Resource wizard and in the UDDI Configuration editor.

For more information, see "UDDI" in the Oracle Fusion Middleware Administrator's Guide for Oracle Service Bus at http://www.oracle.com/pls/as1111/lookup?id=OSBAG392.

Table 4-76 UDDI Registry Options

Option Description

Description

Enter a description of the registry.

Inquiry URL

The URL of the Inquiry API endpoint used for locating and importing services. Enter an inquiry URL in the format: http://host:port/APPLICATION_SERVER_CONTEXT/uddi/inquiry

Publish URL

The URL of the Publish API endpoint used for publishing services. Enter a publish URL in the format: http://host:port/APPLICATION_SERVER_CONTEXT/uddi/publishing

Security URL

The URL of the Security API endpoint used for getting an authentication token so that you can publish to the registry. Enter a security URL in the format: http://host:port/APPLICATION_SERVER_CONTEXT/uddi/security

Subscription URL

The URL of the Subscription API endpoint used for subscribing to registry changes, creating a registry subscription, and listening for changes to imported services. Enter a subscription URL in the format:

http://host:port/APPLICATION_SERVER_CONTEXT/uddi/subscription

By default, the value for APPLICATION_SERVER_CONTEXT in the installer is registry.

User Name

Enter the user name to log into the registry console.

Password (Confirm Password)

Enter the password to log into the registry console.

Validate

Click Validate to validate that a connection can be made to the configured registry.


4.15 Outline view - Oracle Service Bus

This view displays a hierarchical view, or outline, of a structured file that is currently open in the editor area. The contents of this view are editor-specific.

In Oracle Service Bus, when the proxy service is editor is open and the Message Flow Editor is selected, the Outline view displays a hierarchical view of the nodes and actions in the message flow. When the Message Flow Editor is displayed, you can switch between the hierarchical view and a thumbnail view of the service.

In thumbnail view, when the entire message flow does not fit in the editor, a blue mask appears in the outline view to show what portion of the flow is visible in the editor. To display a different portion of the flow, you can drag the mask to the portion of the flow you want to display in the editor.

4.16 Resource Management

The following are provided for managing resources:

4.16.1 Preferences dialog - Oracle Service Bus - Type Associations Page

Use this page to associate one or more file extensions with an Oracle Service Bus resource type.

Table 4-77 Type Association Properties

Option Description

Resource Types

This pane lists all the available types of Oracle Service Bus resources. Select a type to display its assigned file extension associated with the type.


4.16.2 References View

Use this page to view resource dependencies. This view shows your current selection whether it is in the Project Explorer or the active editor.

Table 4-78 Reference Dependency Properties

Option Description

Referenced By

A list of the resources outside of this project, folder, or resource that are dependent on resources inside this project or folder, or this resource.

References

A list of the resources outside of this project, folder, or resource on which resources inside this project or folder, or this resource depends.


4.16.3 Select Clone Target Dialog

Use this dialog to specify where to clone a project, as a new project or as a folder under a different project.

Table 4-79 Clone Project Options

Option Description

Name

Enter a name for the new (cloned) project.

As project

or

As folder in location

Select As project to clone the project as another project, that is, as a peer to the other projects.

Select As folder in location to convert a project (and its contents) into a folder under a project. When you select this option, you must also select the new location.


4.16.4 Select a Resource Dialog

Use this dialog to select a resource, appropriate to the context, that has been created in or imported into the Oracle Service Bus plug-ins. When you click Browse from an editor or a wizard, this dialog displays the available resources that are appropriate for the context. The dialog has different names, depending on the type of resource displayed, for example, Select a WSDL, Select a MFL, Select an XML Schema, etc. In some cases, the dialog displays a hierarchical list of items contained in each resource. For example, the Select an XML Schema dialog lists elements and types defined in the schemas. The Select a WSDL dialog displays ports and bindings defined in the WSDLs.

In some cases, for example, the Select a WSDL dialog, you can click the Consume button to open the Service Consumption dialog, where you can consume services from the following resource types: Oracle Enterprise Repository, file system, UDDI, URI, workspace: consume a service residing in the current workspace.

4.17 New Service Key Provider Resource

Use this page to configure a service key provider resource after you create one.

Table 4-80 New Service Key Provider Options

Option Description

Description

Enter a description for the service key provider.

Encryption Key

To enter an Encryption Key:

  1. Next to Encryption Key, select the Key check box.

  2. Enter a key alias that maps to an X.509 certificate and that supports encryption, or click Browse to display the key aliases from the key store that your realm's PKI credential mapper is using.

  3. Enter the password that you use to secure access to the key store. (You set the password when you create the key store.)

When you associate this service key provider with a proxy service, Oracle Service Bus embeds the X.509 certificate into the proxy service's WSDL. The proxy service then uses this certificate to encrypt the messages that it sends to its endpoint. The proxy service uses the private key in the PKI credential to decrypt the messages that the endpoint returns.

Digital Signature Key

To enter a Digital Signature Key:

  1. Next to Digital Signature Key, select the Key check box.

  2. Enter a key alias, or click Browse to display the key aliases from the key store that your realm's PKI credential mapper is using.

  3. Enter the password that you use to secure access to the key store. (You set the password when you create the key store.)

SSL Client Authentication Key

To enter an SSL Client Authentication Key:

  1. Next to SSL Client Authentication Key, select the Key check box.

  2. Enter a key alias, or click Browse to display the key aliases from the key store that your realm's PKI credential mapper is using.

  3. Enter the password that you use to secure access to the key store. (You set the password when you create the key store.)


4.18 New WS-Policy

Web Services Policy Framework (WS-Policy) is an extensible XML-based framework that extends the configuration of a Web Service with domain specific security assertions and specifies the security requirements, expectations, and capabilities of the Web Service. In Oracle Service Bus, one of the primary uses of WS-Policy is configuring message-level security in proxy services and business services.

Use this page to select a name and location for a new WS-Policy resource.

Table 4-81 New WS-Policy Options

Option Description

Enter or select the parent folder

Enter or select the name of the project or folder in which to locate a new WS-Policy resource.

File Name

Enter a name for this WS-Policy.


4.19 Service Accounts

The following are provided for working with service accounts:

4.19.1 New Service Account Resource

Use the Service Account Resource editor to configure service account resource after you create it.

Table 4-82 New Service Account Options

Option Description

Description

Enter a description for the service account.

Resource Type


4.19.2 Service Account Editor - General Configuration Page

Use this page to configure a service account resource, as described in the following table.

Table 4-83 Service Account General Options

Option Description

Description

Enter a description for the service account.

Resource Type

Leave the resource type as is, or select a different resource type:


4.19.3 Service Account Editor - Static User Configuration Page

Use this to page to save a user name and password with the service account configuration. The service account encodes this user name and password in the outbound request.

Table 4-84 Service Account Static User Options

Option Description

User Name

Enter a user name for this service account.

Password

Enter the associated password.

Confirm Password

Enter the same password you entered for the Password field.


4.19.4 Service Account Editor - User Mappings Configuration Page

Use this to page to create a service account that maps the user name from one or more clients to user names and passwords that you specify.

Table 4-85 Service Account User Mappings Options

Option Description

Remote Users

In the Remote User Name and Remote Password fields, enter the user name and password that you want to send in outbound requests.

(Optional) Add additional remote users in the Remote Users table.

Local User Mappings

To map authorized clients to remote user names and passwords, in the Local User Name field, enter the name that identifies a client that has been authenticated on its inbound request.

If you have not already added this user in the Security Configuration module of the Oracle Service Bus Administration Console, do so before you use this mapping in a runtime environment. Oracle Service Bus lets you create a mapping for a non-existent local user, but the mapping will never match an authenticated user and will never be used.

From the Remote User Name list, select the user name that you want to send in outbound requests for the authenticated user you specified in the Local User Name field.

Map Anonymous Requests

To map anonymous clients to remote user names, select the Map Anonymous Requests check box.

From the Select Remote User list, select the user name that you want to send in outbound requests for all anonymous users.


4.20 Expression Editors

The following editors help you to write expressions for use in services.

4.20.1 XQuery/XSLT Expression Editor

Use the XQuery/XSLT Expression editor to create variable structures, define user namespaces, use predefined message context variables to build inline XQuery expressions, build inline XQuery expressions manually, and select XQuery or XSLT resources for execution as inline XQueries.

The XQuery/XSLT Expression editor contains two panels, each containing three tabs.

Use the panel on the left to write or construct the expression. The panel contains these pages (tabs):

Use the tabs in the panel on the right to manage the variables, namespaces, and XQuery functions you can use to construct an XQuery or XSLT. The panel contains these pages (tabs):

4.20.2 XPath Expression Editor

Use the XPath Expression Editor to create an XPath expression, which is then inserted into the location from which you launched the editor.

The XPath Expression Editor contains these pages:

You can write an expression directly in the Expression text field, or you can drag variables from the Variable Structure page and drag XQuery functions from the XQuery Functions page to construct a valid XPath expression.

When you are finished constructing the expression, you can click Test to test the expression on a running server. Or click OK to insert the expression without testing it.

4.20.3 Condition Editor

Use the Condition Editor to create an inline XQuery condition.

Use the panel on the left to write or construct the condition. The panel contains these tabs, each of which is described below:

Use the tabs in the panel on the right to manage the variables, namespaces, and XQuery functions you can use to construct a condition. The panel contains the following tabs. They are the same as the tabs in the right-hand panel of the XQuery/XSLT Expression Editor, and the following links display the help for those tabs in the XQuery/XSLT Expression Editor.

4.20.4 Condition Builder Page

Use the Condition Builder page to build an inline condition. This page appears only in the Condition Editor.

Build an expression in the Condition Builder as follows:

  1. Select Comparison Expression to build a comparison expression or select Unary Expression to build a unary expression.

  2. If you chose Comparison Expression, do the following:

    1. In the Operand field, enter the name of the operand you want to compare to a value. Alternatively, drag an item from the Variable Structures tab on the right to the Operand field.

    2. In the Value field, enter the value against which to compare the operand. Alternatively, drag item from the Variable Structures tab on the right to the Value field.

    3. Select a comparison operator from the Operator list.

    4. Go to step 4.

  3. If you chose Unary Expression, do the following:

    1. Select or deselect the Not check box to indicate whether to evaluate the expression as true or not true, that is, to specify whether the expression should be enclosed by not().

    2. Enter an expression in the text field, or construct it by dragging items from the Variable Structures tab on the right.

  4. Do either of the following:

    • Click Add to add a new statement to the expression in the Condition Expression field.

    • Select a statement in the Condition Expression field, then click Update to modify the statement.

  5. Click Test to test the expression in a running server, or click OK to insert the condition in the message flow.

4.20.5 Expression Page

This page appears on the XQuery/XSLT Expression Editor, the XPath Expression Editor, and the Condition Editor.

The Expression page contains a text field where you can build expressions by typing directly into the field or by dragging items from the Variable Structures Page or the XQuery Functions Page on the right side of the editor.

Click Test to test the expression in an Oracle Service Bus domain on a running server. Oracle WebLogic Server is packaged with Oracle Service Bus, so an installation of Oracle Service Bus includes an embedded server you can use for testing purposes.

4.20.6 XQuery Resource Page

This page appears in the XQuery/XSLT Expression Editor only.

In the message flow of a proxy service, you can assign XQuery expressions to message context variables, assign if-then-else actions based on the Boolean result of an XQuery expression, insert the result of an XQuery expression at an identified place relative to an XPath expression, specify the message context that you want to log through XQuery expressions on context variables, and so on.

Use the XQuery Resource page to configure an XQuery transformation to be executed in the message flow of a proxy service.

Table 4-86 XQuery Resource Options

Field Description

XQuery

The XQuery resource to be executed. Click Browse to find and open an XQuery resource that has been registered in Oracle Service Bus.

Bind Variables

When you select a resource, each input parameter of the transformation is 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. Enter the expression directly, or drag variables and structures from the right panel.


4.20.7 XSLT Resource Page

This page appears in the XQuery/XSLT Expression Editor only.

Use the XSLT Resource tab to configure an XSLT transformation to be executed in the message flow of a proxy service.

Table 4-87 XSLT Resource Options

Field Description

XSLT

The XSLT resource to execute. Click Browse to find and open a resource registered with Oracle Service Bus.

Input Document

An XQuery expression for the input document to the transformation, for example $body.

Bind Variables

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 bound to the parameter. You must define a binding for each parameter. For example, if an XSL transformation has two input parameters named one and two, the Variable Name field has two labels one and two, with a text box associated with each into which the XQuery expression is entered.

Enter the expression directly, or drag variables and structures from the right panel.

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.20.8 Dynamic XQuery Page

This page appears in the XQuery/XSLT Expression Editor only.

You can specify a dynamic XQuery expression that evaluates at runtime to the name of a pre-registered XQuery resource. Oracle Service Bus executes this XQuery resource, with optional variable bindings, against the message context to produce the required transformation.

Use the XQuery Resource page to configure a dynamic XQuery transformation to be executed in the message flow of a proxy service.

Table 4-88 Dynamic XQuery Options

Field Description

Expression

The XQuery expression that will evaluate at runtime to the name of a pre-registered XQuery resource.

The following shows the syntax for the XQuery resource (representing the full name of the resource):

Project/folder1/folder2/XQueryResourceName

Select XQuery Template

The resource to serve as a template for the shape of the query (the number and names of the variables). Click Browse to select an existing registered resource. After selecting a template, the variables appear in the Bind Variables area. Note that the template is not persisted with the configuration. Instead, the template serves as a quick start to help you specify the variables for the query.

Add Custom Variable

An input parameter of the transformation. Type a variable name in the Add Custom Variable field, and click Add.

Bind Variables

When you add a custom variable, it appears in the Bind Variables area. Similarly, when you select an XQuery template, each input parameter of the transformation is 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. Enter the expression directly, or drag variables and structures from the right panel.


4.20.9 Variable Structures Page

This page appears in the XQuery/XSLT Expression Editor, the XPath Expression Editor, and the Condition Editor.

The Variable Structures page displays variables and their contents as trees. It includes the built-in message context variables attachments, body, header, outbound, and inbound, as well as any user-defined variables. It includes fault if the context of the expression is appropriate (that is, in an error handler). The outbound variable is always listed; even though it is not valid in every context. If outbound is used in invalid contexts, it will be reported when validating.

Each variable structure mapping entry has a label and maps a variable or variable path to one or more structures. The scope of these mappings is a stage or a route node.

You can drag items from this page to the editor's Expression Page to insert them into the current expression. They are inserted as XPath expressions.

To define a new variable and add it to the variable structure tree, click Add to open the Add Variable Structure Dialog.

4.20.10 Namespace Definitions Page

This page appears in the XQuery/XSLT Expression Editor, the XPath Expression Editor, and the Condition Editor.

The Namespace Definitions page lists default Oracle Service Bus namespaces, variable namespaces, and user-defined namespaces. Click Add to define a new namespace, which is then added to the list of user-defined namespaces. To modify a user-defined namespace, select it in the list, then click Edit.

4.20.11 XQuery Functions Page

This page appears in the XQuery/XSLT Expression Editor, the XPath Expression Editor, and the Condition Editor.

The XQuery Functions page lists a set of standard XQuery functions, organized alphabetically and by type. You can drag functions from this page to the editor's Section 4.20.5, "Expression Page" to insert them into the current expression. When you insert a function into an expression, placeholders are used for parameter values you must supply.

4.20.12 Add Variable Structure Dialog

Use this dialog to define a variable and add it to the tree of variable structures in the Variable Structures Page of the Expression Editors.

You create variable structures in this dialog to define the structure of a variable for design purposes. For example, it is easier to browse the XPath variable in the structure view rather than viewing the XML schema of the XPath variable. Variable structures do not create variables. Variables are created at runtime as the target of the assign action in the stage.

You can declare your own variable structures based on:

  • XML types, including

    • Schema elements

    • WSDL elements

    • Schema types

    • WSDL types

  • MFLs

  • Service interfaces

  • Simple types (string or any XML)

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.

When you create a variable structure based on XML types, MFLs, or service interfaces, you must enter the following information into the fields at the top of the page:

Table 4-89 Variable Structure Options

Option Description

Structure Label

A display name for the variable you want to create. This display name enables you to give a meaningful name to the structure so you can recognize it at design time but it has no impact at run time.

Structure Path

The path of the variable structure at run time


4.21 New XSL Transformation

Transformation maps describe the mapping between two data types. eXtensible Stylesheet Language Transformation (XSLT) maps describe XML-to-XML mappings.

Use this page to select a name and location for a new XSL transformation. This wizard creates a skeleton for the XSLT. Add details in the XSLT editor.

Table 4-90 New XSL Transformation Options

Option Description

Enter or select the parent folder

Enter or select the name of the project or folder in which to locate a new XSL transformation.

File Name

Enter a name for this new XSL transformation.


4.22 Split-Join User Interface Reference

The following sections describe the fields and user interface components involved with creating and configuring Split-Joins in Oracle Service Bus.

4.22.1 Split-Join Design Palette

The Split-Join Design Palette lists all the operations you can use to construct a Split-Join. To insert a control into a Split-Join, drag the icon from the palette to the Split-Join editor. When you drag an item to the editor, one or more target icons indicate that you can drop the dragged item in that position on the editor. When you drag the item into a target icon, it is highlighted to show that you can drop the item there.

4.22.1.1 Operations

The Split-Join Design palette is organized into the following categories:

  • Communication

  • Flow Control

  • Assign Operations

The following tables describe the operations you can add to a Split-Join:

Table 4-91 Split-Join Communication Operations

Operation Description

Invoke Service

Invoke Service invokes a WSDL-based, non-transport-typed Business Service, a WSDL-based Proxy Service, or a Split-Join.

For configuration properties, see Section 4.22.5, "Invoke Service Properties."

Reply

Reply sends a response or fault back to the Oracle Service Bus Message Flow.

For configuration properties, see Section 4.22.6, "Reply Properties."


Table 4-92 Split-Join Flow Control Operations

Operation Description

For Each

For Each executes logic configured within its Scope a specified number of times.

For configuration properties, see Section 4.22.7, "For Each Properties."

If

If provides conditional behavior within a Split-Join.

For configuration properties, see Section 4.22.8, "If Properties."

Parallel

Parallel creates a fixed number of configured parallel branches.

For configuration properties, see Section 4.22.10, "Parallel Properties."

Raise Error

Raise Error generates an error that causes the Split-Join to stop normal processing. If the error is not handled using an Error Handler, the Split-Join will terminate and a Fault will be sent to the Oracle Service Bus Message Flow.

For configuration properties, see Section 4.22.11, "Raise Error Properties."

Repeat Until

Repeat Until lets you repeat operations until a condition evaluates to true within a Split-Join. The condition is evaluated after each loop finishes.

For configuration properties, see Section 4.22.12, "Repeat Until Properties."

Re-Raise Error

Re-Raise Error lets you re-raise an error caught by an Error Handler Catch or CatchAll.

For configuration properties, see Section 4.22.13, "Re-Raise Error Properties."

Scope

Scope creates a context which influences the behavior of its enclosed operations.

For configuration properties, see Section 4.22.14, "Scope Properties."

While

While lets you repeat operations until a condition evaluates to false within a Split-Join. The condition is evaluated before each loop commences.

For configuration properties, see Section 4.22.15, "While Properties."


Table 4-93 Split-Join Assign Operations

Operation Description

Assign

Lets you assigns the result of an XQuery expression to a Variable.

For configuration properties, see Section 4.22.17.1, "Assign Operation Properties."

Copy

Lets you copy the information specified by an XPath expression from a source document to a destination document.

For configuration properties, see Section 4.22.18, "Copy Properties."

Delete

Lets you delete a set of nodes specified by an XPath Expression.

For configuration properties, see Section 4.22.19, "Delete Properties."

Insert

Lets you insert the result of an XQuery expression at an identified place relative to nodes selected by an XPath Expression.

For configuration properties, see Section 4.22.20, "Insert Properties."

Java Callout

Lets you invoke a static Java method from a Split-Join for custom actions such to be handled in Java such as validation, transformation, and logging.

For configuration properties, see Section 4.22.21, "Java Callout Properties."

Log

Lets you log data at a specified severity so that administrators can take appropriate action.

For configuration properties, see Section 4.22.22, "Log Properties."

Replace

Lets you replace a node or the contents of a node specified by an XPath expression.s

For configuration properties, see Section 4.22.23, "Replace Properties."


Operations have a General properties tab for changing the node's label and providing comments.

4.22.2 Global / Start Node Properties

The start node in a Split-Join specifies its global properties. Among these properties, global variables and associated External Services can be reviewed and configured by expanding the left-side arrow. The global Error Handler can be reviewed and configured by expanding the right-side arrow.

Use the Properties view to review and configure the Global Properties of the selected Split-Join.

This page has two tabs:

  • Imports

  • General

The Imports tab has the following options:

Table 4-94 Split-Join Start Node Options - Imports Tab

Option Description

WSDL Imports

Displays WSDL Imports used by the Split-Join.

Select a WSDL in the list and right-click to delete it.

Schema Imports

Displays Schema Imports used by the Split-Join.

Select a Schema in the list and right-click to delete it.


The General tab has the following options:

Table 4-95 Split-Join Start Node Options - General Tab

Option Description

Label

Enter a label for the file defining the Process Node.

Documentation

Enter a description and/or comments.


4.22.3 Variable Properties

Use the Properties view to review and configure Variables in the selected Split-Join.

Table 4-96 Split-Join Variable Options

Option Description

(tree)

Depicts the hierarchical structure of the Variable's type.

Edit

Click to display the Create/Edit Variable Dialog, where you can modify the Variable's name and type.


4.22.4 Error Handler Properties

The Error Handler receives and handles all of the errors that are raised in a Split-Join.

An Error Handler lets you add Catch and CatchAll operations.

Use the Properties view to review and configure the selected Error Handler in a Split-Join.

The Catch tab has the following options.

Table 4-97 Split-Join Error Handler Options - Catch Tab

Option Description

SOAP Fault Variable Name

Defines a variable to contain SOAP (1.1 or 1.2) faults. If the Error Handler is executed due to a SOAP fault received from invoked external services, this variable is populated with the received SOAP fault.

Fault Name – Define Fault

Lets you define a custom local fault.

Click Define Fault to enter a Namespace and Fault Name.

Fault Name – Predefined

Lets you select an existing WSDL, Application, or Standard fault.

Click Pick Fault to select an existing fault.


The catchAll tab has the following options.

Table 4-98 Split-Join Error Handler Options - CatchAll Tab

Option Description

SOAP Fault Variable Name

Defines a variable to contain SOAP (1.1 or 1.2) faults. If the Error Handler is executed due to a SOAP fault received from invoked external services, this variable is populated with the received SOAP fault.


4.22.5 Invoke Service Properties

The Invoke Service invokes a WSDL-based, non-transport-typed Business Service, a WSDL-based Proxy Service, or another Split-Join.

Use the Properties view to review and configure the selected Invoke Service in a Split-Join.

The Operation tab has the following options:

Table 4-99 Split-Join Invoke Service Options - Operation Tab

Option Description

Operation

The operation to be invoked by the Service.

Click Browse to select the operation you want to invoke.

When you select an operation, a dashed blue line appears pointing to the external service in the Split-Join editor.

Service Location

The location of the invoked Service.

Click the location path to open the service file.

Qos

The quality of service option that controls transaction support. Select one of the following:

  • Best Effort – The operation does not execute in the context of an existing transaction.

  • Exactly Once – The operation executes in the context of an existing transaction.


The Input Variable tab has the following options:

Table 4-100 Split-Join Invoke Service Options - Input Variable Tab

Option Description

Message Variable

A list of message type variables with the type matching the operation's input message type.

Select Create Message Variable to define a new message variable.

Note: If message type variables with the type matching the operation's input message type do not exist, you must define a new message type variable with the required type.

Message Type Namespace

The namespace of the operation's input message type.

Message Type

The operation's input message type.


The Output Variable tab has the following options:

Table 4-101 Split-Join Invoke Service Options - Output Variable Tab

Option Description

Message Variable

A list of message type variables with the type matching the operation's output message type.

Select Create Message Variable to define a new message variable.

Note: If message type variables with the type matching the operation's output message type do not exist, you must define a new message type variable with the required type.

Message Type Namespace

The namespace of the operation's output message type.

Message Type

The operation's output message type.


4.22.5.1 Invoking Another Split-Join

A Split-Join can invoke another Split-Join in the same Oracle Service Bus configuration. This functionality provides more flexibility in service design, letting you split up complex Split-Join functionality into multiple Split-Joins, allowing for componentization and re-use of Split-Join functionality. Performance is maintained, because there is no marshalling and unmarshalling of data between the Split-Joins.

You must ensure that you do not create circular Split-Join references. Oracle Service Bus does not check for circular references.

4.22.6 Reply Properties

Reply sends a response or fault back to the Oracle Service Bus message flow.

Use the Properties view to review and configure the selected Reply in a Split-Join.

The Operation tab has the following options:

Table 4-102 Split-Join Reply Options - Operation Tab

Option Description

Operation

The operation to be invoked by the Reply.


The Variable tab has the following Select options:

Table 4-103 Split-Join Reply Options - Variable Tab

Response Options Description

Message Variable

A list of the message variables whose type matches the operation's output message type.

Select Create Message Variable to define a new message variable.

Note: If message type variables with the type matching the operation's output message-type do not exist, you must define a new message type variable with the required type.

Message Type Namespace

The namespace of the operation's output message type.

Message Type

The operation's output message type.

Pick WSDL Fault/SOAP Fault

Determine whether the fault reply is a fault message defined in the operation of the WSDL or an explicit SOAP fault message.

WSDL Fault Name

Select a fault name from the list of faults defined in the operation of the WSDL.

Message Variable

A list of the Message Variables whose type matches the operation's output message type.

Select Create Message Variable to define a new message variable.

Note: If message type variables with the type matching the operation's output message-type do not exist, you must define a new message type variable with the required type.

Message Type Namespace

The namespace of the operation's output message type.

Message Type

The operation's output message type.

SOAP Fault

Select SOAP Fault

See Section 4.22.29, "SOAP Fault Variable Dialog."

Propagate SOAP Fault

Propagate the SOAP fault in the SOAP fault variable defined in the Error Handler.

See Section 4.22.4, "Error Handler Properties."


Reply automatically includes an implicit Exit operation to end that instance of the flow without triggering a fault. The Exit operation is not visible in the development environment.

4.22.7 For Each Properties

For Each executes logic configured within its Scope a specified number of times.

Use the Properties view to review and configure the selected For Each in a Split-Join.

The Counter Variables tab has the following options:

Table 4-104 Split-Join For Each Options - Counter Variables Tab

Option Description

Parallel

Select one of the following options:

  • If you select yes, each iteration of For Each is executed in parallel.

  • If no, each iteration of For Each is executed sequentially.

Counter Variable Name

Defines an implicit variable within the Scope of the For Each. Each iteration of the For Each contains an isolated instance of this variable. In turn, every instance is set to an iteration number; for example, the first iteration has its value set to Start Counter Value, the second iteration to Start Counter Value+1, etc.

Start Counter Value

The value of the Counter Variable for the first iteration of For Each. Determined as the result of an XPath expression. The result must be "1" or more. ("0" is not a valid Start Counter Value.)

The browse button launches the expression builder. The expression should generate an integer for the initial Start Count Value.

Final Counter Value

The value of the Counter Variable for the final iteration of For Each. Determined as the result of an XPath expression. The result must be "1" or more. ("0" is not a valid Final Counter Value.)

The browse button launches the expression builder. The expression should generate an integer for the Final Count Value.


The Completion Condition tab has the following options:

Table 4-105 Split-Join For Each Options - Completion Condition

Option Description

Number of Finished Branches

An optional expression that determines when to stop creating branches. Depending on the context in the Split-Join, the expression prevents some of the children from executing or forces early termination of some children.

The browse button launches the expression builder.

Successful Branches Only?

Select this option if you want only successfully completed branches to be counted when determining if the completion condition has been met.


4.22.8 If Properties

If nodes contain If, Else If, and Else operations. See Section 4.22.9, "If and Else If Properties."

Use the Properties view to review and configure the selected If in a Split-Join.

4.22.9 If and Else If Properties

The If and Else If operations provide conditional behavior within a Split-Join.

Use the Properties view to review and configure the selected If or Else If in a Split-Join.

If and Else If have the following options:

Table 4-106 Split-Join If and Else If Options

Option Description

Condition

Define an XPath expression that evaluates to true or false. If the condition evaluates to true, the associated If/Else If branch is executed.

Click the browse icon to launch the expression builder.


4.22.10 Parallel Properties

Parallel lets you create a static Split-Join that handles fixed number of message requests. Parallels contain one or more Scope branches.

Use the Properties view to review and configure the selected Parallel in a Split-Join.

4.22.11 Raise Error Properties

Raise Error establishes an error condition under which the execution of the process will halt.

Use the Properties view to review and configure the selected Raise Error in a Split-Join.

The Raise Error tab has the following options:

Table 4-107 Split-Join Raise Error Options

Option Description

Define Fault

Lets you specify a custom local fault not contained in the WSDL.

Click the Fault link to specify the fault Namespace and Fault Name.

Pick Fault From WSDL

Lets you select an existing fault specified in the WSDL.

Click the Pick Fault link to select the WSDL fault.


4.22.12 Repeat Until Properties

Repeat Until lets you repeat operations until a condition evaluates to true within a Split-Join. The condition is evaluated after each loop finishes.

Use the Properties view to review and configure the selected Repeat Until in a Split-Join.

The Condition tab has the following options:

Table 4-108 Split-Join Repeat Until Options

Option Description

Condition

Define an XPath expression that evaluates to true or false. The operation(s) in the Repeat Until are executed until the condition evaluates to true.

Click the browse icon to launch the expression builder.


4.22.13 Re-Raise Error Properties

Use Re-Raise Error within an Error Handler to re-raise an error caught by a Catch or a CatchAll. In the Properties view you can rename and enter comments about the Re-Raise Error node.

Use the Properties view to review and configure the selected Re-Raise Error in a Split-Join.

4.22.14 Scope Properties

The Scope creates a context which influences the behavior of its enclosed operations. Local variables and the Error Handler defined within the Scope are restricted to this context.

Use the Properties view to review and configure the selected Scope in a Split-Join.

Related Topics

Section 4.22.26.1, "Scope and Variables"

4.22.15 While Properties

While lets you repeat operations until a condition evaluates to false within a Split-Join. The condition is evaluated before each loop commences.

Use the Properties view to review and configure the selected While in a Split-Join.

The Condition tab has the following options:

Table 4-109 Split-Join While Options

Option Description

Condition

Define an XPath expression that evaluates to true or false. If the condition evaluates to true, the associated operations is executed.

Click the browse icon to launch the expression builder.


4.22.16 Wait Properties

Wait lets you insert a pause in the Split-Join flow for a short duration to wait for other dependent jobs to complete. After the short duration, the Wait continues the Split-Join execution.

Use the Properties view to review and configure the selected Wait in a Split-Join.

The Wait tab has the following options:

Table 4-110 Split-Join Wait Options

Option Description

Duration

Define an XPath expression that evaluates to a duration type of xsd:duration in the following format:

nYnMnDTnHnMnS (number of years, months, days, hours, minutes, and seconds, with a date/time separator, represented by "T".)

Be sure the expression resolves to a correct duration type. The Wait operation does not validate the results of the expression.

When the duration is reached, the Wait resumes the Split-Join execution.

Click the browse icon to launch the expression builder.


4.22.17 Assign Properties

Assign lets you perform data manipulation, including initializing and updating a Variable. You can perform the following operations in an Assign node: Assign, Copy, Delete, Insert, Java Callout, Log, and Replace.

Use the Properties view to review and configure the selected Assign in a Split-Join.

4.22.17.1 Assign Operation Properties

The Assign tab has the following options:

Table 4-111 Split-Join Assign Operation Options

Option Description

Expression

An XQuery expression used to create the data that will be assigned to the Variable.

Clicking the expression launches the XQuery editor.

When Oracle Service Bus binds variables in an inline XQuery, it assumes the type xs:string. This can cause parser errors in operations with constants that are incompatible with xs:string. To ensure compatible types, use an explicit XQuery cast. For example, the following inline XQuery will fail. Although the $itemsTotal is of type xs:double, it is bound as an xs:string, which is incompatible in the test against 10000.

if ($itemsTotal < 10000) then . . .

To make this inline XQuery work, explicitly cast the $itemsTotal to an xs:double:

if (($itemsTotal cast as xs:double) < 10000) then . . .

Also, when creating an Assign action to a String result or variable, ensure that your expression returns a String value. Assigning a non-String value to a String result or String global variable does not cause a MismatchedAssignmentFailure exception, as specified by the WS-BPEL specification.

Variable

A variable to which the result of the XQuery expression is assigned.

Only previously defined Variables, the Counter Variable, and SOAP Fault Variables (for Error Handlers) are available.

Qos

The quality of service option that controls transaction support. Select one of the following:

  • Best Effort – The operation does not execute in the context of an existing transaction.

  • Exactly Once – The operation executes in the context of an existing transaction.


Oracle Service Bus's Assign functionality in Split-Joins conforms to the WS-BPEL specification for resolution of XPath/XQuery expressions to simple type variables. Supported simple types for binding XPath/XQuery expressions to variables in Split-Joins are String, Boolean, and Float. The Assign converts the value you provide the type with which the variable is defined.

For example:

  • If you assign <foo><bar>4</bar></foo> to a response variable defined as a String ($response.result), Oracle Service Bus returns <bar>4</bar> as a String in the <result> through a simple copy of the child element and value.

  • If you map <foo><bar>4</bar></foo> to a String variable (such as myStr), then assign $myStr to $response.result, Oracle Service Bus returns <result>4</result>, because it first converts the value in $myStr to a String before it makes the assignment to the $response.result String variable.

4.22.18 Copy Properties

The Copy operation copies the information specified by an XPath expression from a source document to a destination document.

Use the Properties view to configure a Copy Operation in an Assign. Configure Select From and Select To using the following guidance.

The Copy tab has the following options:

Table 4-112 Split-Join Copy Options

Option Description

Keep Source Element

Lets you determine which element name (source or destination) is used when values are copied from a source to a destination.

If you do not select this option, the existing element name in the destination is used to hold the copied value.

If you select this option, the name of the source element is used in the destination to hold the copied value.

For example, if you are copying a zip code value from <zipCode>80303</zipCode> in the source, selecting Keep Source Element uses the <zipCode> element in the destination. If you do not select the option, the zip code value is copied to the existing destination element, such as <pinCode>80303</pinCode>.

Choose Type

Allows the user to select the desired type: Variable, Expression, Literal, or XML Fragment. Literals and XML fragments are available only in the Select From menu.

Choose Type - Variable

Select an XPath on a Variable. Use this option when simple node selection on a Variable is required.

When a node is selected by expanding the Variable tree, an Xpath expression is automatically generated.

Choose Type - Expression

Create an Xpath expression to select a node from a Variable. Use this option when more complex Xpaths (potentially with predicates) are required to select a node on a Variable.

Click the Expression link to use the XPath Expression Builder.

Note: The entered Xpath expression should only copy to one XML node/element, or there will be run-time errors.

Choose Type - Literal (Select From only)

A Literal string entered by the user.

Click the Literal link to enter the string.

Choose Type - XML Fragment (Select From only)

An XML fragment entered by the user.

Click the XML Fragment link to enter the fragment.


4.22.19 Delete Properties

The Delete operation deletes a set of nodes specified by an XPath Expression.

Use the Properties view to configure a Delete Operation in an Assign.

Note:

Unlike a Delete operation in a proxy service message flow, a Delete operation in a Split-Join does not allow deleting a variable directly.

The Delete tab has the following options:

Table 4-113 Split-Join Delete Options

Option Description

XPath

An XPath Expression that selects the nodes to be deleted.

Click the XPath link to launch the expression editor.

In Variable

Variable on which the XPath expression is executed to select the nodes to be deleted.

Qos

The quality of service option that controls transaction support. Select one of the following:

  • Best Effort – The operation does not execute in the context of an existing transaction.

  • Exactly Once – The operation executes in the context of an existing transaction.


4.22.20 Insert Properties

The Insert operation inserts the result of an XQuery expression at an identified place relative to nodes selected by an XPath Expression.

Use the Properties view to configure an Insert Action in an Assign.

The Insert tab has the following options:

Table 4-114 Split-Join Insert Options

Option Description

Expression

An XQuery expression used to create the data that will be inserted at a specified location in a Variable.

Click the Expression link to launch the expression editor.

Location

The location used to control where the Insert operation is performed relative to the result of the XPath Expression. Options include:

  • before: Immediately before the element specified by the result of the Xpath Expression.

  • after: Immediately after the element specified by the result of the Xpath Expression.

  • as first child of: The first child element of the element specified by the result of the Xpath Expression.

  • as last child of: The last child element belonging to the element specified by the result of the Xpath Expression.

XPath

An XPath that determines the nodes to be selected.

Click the Xpath link to launch the expression editor.

Variable

A Variable to be evaluated by the XPath.

Qos

The quality of service option that controls transaction support. Select one of the following:

  • Best Effort – The operation does not execute in the context of an existing transaction.

  • Exactly Once – The operation executes in the context of an existing transaction.


4.22.21 Java Callout Properties

A Java Callout operation lets you invoke a static Java method from a Split-Join for custom actions such to be handled in Java such as validation, transformation, and logging.

Use the Properties view to configure a Java Callout operation in an Assign.

The Java Callout tab has the following options:

Table 4-115 Split-Join Java Callout Options

Option Description

Method

Package your Java class in a JAR file in your Oracle Service Bus project. Click Browse to first select the JAR, then the method you want to invoke.

Using the following guidelines for the Java callout method:

  • The method must be static.

    Only the following Java types are supported for input parameters:

  • boolean, byte, char, double, float, int, long, short and arrays of these types

  • java.lang.[Boolean | Byte | Character | Double | Float | Integer | Long | Short | String] and arrays of these types

  • java.math.[BigInteger | BigDecimal] and arrays of these types

  • org.apache.xmlbeans.XmlObject and arrays of this type

Only the following Java types are supported for method return:

  • All types supported for input parameters except their array equivalent

  • void

Expression

An XQuery expression used to map data to the input parameters of the static Java method. Click the Expression link to launch the expression editor.

Result Value

Select the variable to contain the result value for the Java method.

Service Account

You can use Service Account to put the appropriate subject on the thread when executing the Java callout.

Click Browse to select a service account.

Qos

The quality of service option that controls transaction support. Select one of the following:

  • Best Effort – The operation does not execute in the context of an existing transaction.

  • Exactly Once – The operation executes in the context of an existing transaction.


Oracle Service Bus provides the following errors for Java callouts:

  • 2031350 – Received more than one element when only one is expected during conversion to Java

  • 2031351 – Found simple type instead of XmlObject when converting to Java

  • 2031352 – Error converting simple type to its corresponding Java type

  • 2031353 – Received exception during invocation of the Java method

  • 2031354 – Errors setting the security context

4.22.22 Log Properties

The Log operation lets you log Split-Join data at a specified severity to the server log file. Administrators can use log information to take appropriate action based on the severity of the data logged.

Use the Properties view to configure a Log operation in an Assign.

The Log tab has the following options:

Table 4-116 Split-Join Log Options

Option Description

Expression

An XQuery expression used to select the data to be logged.

Click the Expression link to launch the expression editor.

Annotation

Optionally specify a note for the log. The annotation is logged along with the data selected by the expression.

Severity

Select one of the following the severity levels for the log:

  • Debug

  • Info

  • Warning

  • Error


4.22.23 Replace Properties

The Replace operation lets you replace a node or the contents of a node specified by an XPath expression.

Use the Properties view to configure a Replace operation in an Assign.

The Replace tab has the following options:

Table 4-117 Split-Join Replace Options

Option Description

XPath

An XPath Expression used to specify the data (in the Variable) that will be replaced.

Click the XPath link to launch the expression editor.

Variable

The Variable that contains the data to be replaced.

Expression

An XQuery expression used to create the data that replaces the data specified by the XPath in the named Variable.

Click the Expression link to launch the expression editor.

Replace entire node

Specifies that the nodes selected by the expression are replaced along with all of its contents.

Replace node contents

Specifies that the node is not replaced. Only the contents are replaced.

Qos

The quality of service option that controls transaction support. Select one of the following:

  • Best Effort – The operation does not execute in the context of an existing transaction.

  • Exactly Once – The operation executes in the context of an existing transaction.


4.22.24 Receive Properties

Use the Properties view to review and configure the selected Receive in a Split-Join.

The Operation tab has the following options:

Table 4-118 Split-Join Receive Options - Operation Tab

Option Description

Operation

The operation to be invoked by the Receive.

Browse to select an operation from the WSDL Browser.


The Variable tab has the following options:

Table 4-119 Split-Join Receive Options - Variable Tab

Option Description

Message Variable

A list of the message variables whose type matches the operation's output message type

Select Create New Variable to define a new message variable.

Note: If message type variables with the type matching the operation's output message-type do not exist, you must define a new message type variable with the required type.

Message Type Namespace

The namespace of the operation's output message type.

Message Type

The operation's output message type.


4.22.25 Counter Variable Dialog

Use this dialog to create a Counter Variable.

Table 4-120 Split-Join Counter Variable Options

Option Description

Counter Variable Name

The name of the Counter Variable


4.22.26 Create/Edit Variable Dialog

Use this dialog to review and/or configure Variables in the Split-Join.

4.22.26.1 Scope and Variables

Although variables are visible in the scope in which they are defined and in all scopes nested within that scope, a variable declared in an outer scope is hidden when you declare a variable with an identical name in an inner scope. For example, if you define variable myVar in an outer scope (So) and then define variable myVar again in an inner scope (Si) which is contained by scope So, then you can only access the myVar you defined in the inner scope Si. This myVar overrides the myVar you defined in scope So.

Table 4-121 Split-Join Variable Options

Option Description

Name

Enter a name for the Variable that is unique within the Scope.

Select Variable Type

Select one of the following Variable Types:

  • Built-in Types

  • Schema Types

  • Message Types

Select Variable Type - Built-in Types

When selected, only Built-in Type Variables are displayed.

Select Variable Type- Schema Types

When selected, all Schema Types in the current Oracle Service Bus Configuration are displayed.

If "Show only applicable schema types/elements for this Split-Join" is selected, only Schema Types directly applicable to the current Split-Join are displayed. This is checked by default.

Select Variable Type - Message Types

When selected, only message types are displayed.

If "Show only applicable schema types/elements for this Split-Join" is selected, only Message Types directly applicable to the current Split-Join are displayed. This is checked by default.

Type

The Variable type.

Namespace

The namespace of the Variable's type.


4.22.27 Create Message Variable Dialog

Use this dialog to create a new message variable.

Table 4-122 Split-Join New Message Variable Options

Option Description

Name

Enter a unique name for the Variable.

Type

One of the following Variable types: WSDL message, XSD element, or XSD type (simple, complex, built-in).

Namespace

The namespace of the Variable's type.


4.22.28 Service Browser

Use this dialog to browse for and select an operation from a business service, a proxy service, or a Split-Join in the tree.

4.22.29 SOAP Fault Variable Dialog

Use this dialog to create a SOAP fault variable.

Table 4-123 Split-Join SOAP Fault Variable Options

Option Description

SOAP Fault Variable Name

The name of the SOAP fault variable.


4.22.30 WSDL Browser

Use this dialog to browse for and select an operation from a WSDL in the depicted tree.

4.22.31 Split-Join Wizard - New Split-Join

Use this page to locate and name the new Split-Join

Table 4-124 New Split-Join Options

Option Description

Enter or select the parent folder

Enter the name of the folder to contain this Split-Join, or select a folder from the list.

File Name

Enter a name for the file defining the Split-Join.


4.22.32 Split-Join Wizard - Specify Operations

Use this page to select an operation for the new Split-Join.

Table 4-125 New Split-Join Options - Selecting an Operation

Option Description

Select Operation

Select the operation from those available in the tree.

Consume

Click this button to import WSDLs from outside your current Oracle Service Bus configuration that can subsequently be used to select an operation.