Guide to Implementing Application Integration Architecture on … · Oracle White Paper—Guide to Implementing Application Integration Architecture on Oracle Service Bus - 2 - Disclaimer

An Oracle White Paper February 2009

Guide to Implementing Application Integration Architecture on Oracle Service Bus

Oracle White Paper—Guide to Implementing Application Integration Architecture on Oracle Service Bus

- 2 -

Disclaimer

The following is intended to outline our general product direction. It is intended for information purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described for Oracle’s products remains at the sole discretion of Oracle.


- 3 -

Table of Contents Application Integration Architecture (AIA) on Oracle Servie Bus (OSB) Error! Bookmark

not defined. Contents ........................................................................................................................ 3

Preface .................................................................................................................. 7

Goal of this document ........................................................................................... 7

Pre-requisites ........................................................................................................ 7

Chapter 1 ...................................................................................................................... 8

EBS Programming Model .............................................................................................. 8

Registering AIA Components with OSB ................................................................ 8

Registering AIA Components as JAR File ......................................................... 8

Developing EBS as OSB Service .......................................................................... 9

External Application Invoking the EBS Using an HTTP Adapter. ................ 10

ABCS Invoking a Remotely Located EBS ................................................... 10

Creating EBS as OSB Proxy Service Using WSDL ........................................ 11

Message Routing ................................................................................................ 11

Configure the Routing Node in the Message Flow of EBS .............................. 12

Using Route-To in the Route Node ............................................................. 12

Using Routing Table in the Route Node ...................................................... 12

Dynamic Routing ......................................................................................... 12

Modeling Route Node in Conjunction with Operational Branch ...................... 14

Error Handling ..................................................................................................... 15

Logging ................................................................................................................ 15

Chapter 2 .................................................................................................................... 16

ABCS Programming Model ......................................................................................... 16

Developing ABCS ................................................................................................ 16

Message Validation ......................................................................................... 16

Message Transformation ................................................................................. 16

XSLT ............................................................................................................ 17

XQuery ........................................................................................................ 18

Message Enrichment ....................................................................................... 18

Inbound Service Interaction ............................................................................. 18


- 4 -

Outbound Service Interaction .......................................................................... 18

Configuring Service Call Out action ................................................................ 20

Invocation of EBS and/or Application Services ............................................... 20

Computing Dynamic Endpoint Location in ABCS ............................................ 21

Using Java Callout for Invoking AIA Configuration API ............................... 21

Configuring the Proxy Pipeline to Determine the Dynamic Endpoint Location

..................................................................................................................... 21

CAVS Enabling ................................................................................................ 21

Developing Provider ABC Services to be CAVS-Enabled ........................... 21

Developing Requestor ABC Services to be CAVS-Enabled ........................ 22

Logging ................................................................................................................ 22

Error handling in ABCS ....................................................................................... 22

Chapter 3 .................................................................................................................... 23

Extending ABCS ......................................................................................................... 23

Developing ABCS Extensibility Service ............................................................... 23

Configuring the ABCS Message Flow to Incorporate ABCS Extensibility ....... 23

Chapter 4 .................................................................................................................... 25

Asynchronous Invocation of ABCS ............................................................................. 25

JMS Consumer Adapter ...................................................................................... 25

JMS Producer Adapter ........................................................................................ 25

Error Handling and Recovery for Guaranteed Message Delivery ....................... 26

Chapter 5 .................................................................................................................... 27

Using Adapters with AIA on OSB ................................................................................ 27

Chapter 6 .................................................................................................................... 28

Implementing Synchronous Request-Response MEP ................................................ 28

Creating and Configuring the EBS as OSB Proxy Service .................................. 28

Transport Configuration ................................................................................... 29

Message Routing In EBS ................................................................................ 30

Adding Operational Branch Node ................................................................ 30

Configuring the EBS for the Dynamic Routing ............................................ 30

EvaluateRoutingRule ................................................................................... 30

Error Handling in EBS ..................................................................................... 33

Developing Requestor ABCS .............................................................................. 33

Configure the Message Flow of the Proxy service .......................................... 36


- 5 -

Error Handling in Requestor ABCS ................................................................. 36

Developing Provider ABCS ................................................................................. 36

Configuring the Proxy Service ......................................................................... 37

Using AIA XPath Functions ............................................................................. 38

Using AIA XPath functions in XSL ............................................................... 38

Chapter 7 .................................................................................................................... 39

Implementing Fire-and-Forget MEP ............................................................................ 39

Developing One-Way ABCS Requestor .............................................................. 39

Developing Requestor ABCS .......................................................................... 39

Configure the Message Flow of the Proxy Service ...................................... 40




Developing JMS Consumer Adapter ................................................................... 42

Chapter 8 .................................................................................................................... 43

Implementing Asynchronous Request–Delayed Response MEP ............................... 43

Developing One-Way ABCS Requestor .............................................................. 44

Developing Requestor ABCS .......................................................................... 44

Configure the Message Flow of the Proxy Service ......................................... 45




Creating and Configuring the Response EBS ..................................................... 47

Chapter 9 .................................................................................................................... 49

Logging Messages in OSB .......................................................................................... 49

Configuring Oracle AIA Processes for Trace Logging ......................................... 49

Describing Details of the isTraceLoggingEnabled Custom XPath Function .... 49

Describing Details of the logTraceMessage Custom XPath Function ............. 50

Describing the Trace Logging Java API .......................................................... 50

Chapter 10 .................................................................................................................. 52

Error Handling in OSB ................................................................................................. 52

Configuring Oracle AIA Processes for Error ........................................................ 52

Configuring OSB Services to Adhere to Error Handling Requirements .............. 52

Understanding OSB Error Handling ................................................................ 52


- 6 -

Service Invocation Errors ............................................................................ 52

Implementing Error Handling ........................................................................... 53

See Also ...................................................................................................... 53

Performing Configurations for OSB Services to Adhere to Error Handling

Requirements ...................................................................................................... 53

Defining Notification Roles for Each Service ................................................... 53

Defining Corrective Action Codes ................................................................... 54

Defining Error Message Codes ....................................................................... 55

Chapter 11 .................................................................................................................. 56

OSB Service Configuration ......................................................................................... 56

Appendix ..................................................................................................................... 59

Uploading AIA Components as a Zipped file ....................................................... 59

Resolving the Schema References in the WSDL ................................................ 60

Updating the WSDL from ESL for Creating OSB Service ................................... 62

Updating WSDL ............................................................................................... 62

Creating SB Configuration JAR File for AIA Components ................................... 68

Constructing a OSB Business Service ................................................................ 68

Creating JMS Resources .................................................................................... 68

Creating new JMS Server ............................................................................... 69

Creating a JMS Module for the JMS server ................................................. 69

Adding Resources to the JMS System Module ........................................... 69

Parameters for Guaranteed delivery ............................................................... 69


- 7 -

Preface Oracle Service Bus (OSB), formerly known as AquaLogic Service Bus is a lightweight ESB targeted for SOA-based integration. It is policy-driven and enables loose coupling between service clients (the service consumers) and business services (the service providers). OSB provides configuration-based approach for developing SOA assets and deploying SOA services. It promises message-processing capabilities such as message validation, message enrichment and message transformation. It also provides support for message routing capabilities and support for multiple service-invocation.

Goal of this document This document describes how to implement AIA on OSB. It defines programming models for developing Enterprise Business Service (EBS), Application Business Connector service, and Message exchange patterns.

Pre-requisites The reader is expected to have a good understanding of OSB as well as AIA architectural principles. For getting a complete understanding of AIA principles, please refer to AIA Concepts and Technologies Guide.


- 8 -

Chapter 1

EBS Programming Model

Registering AIA Components with OSB The AIA artifacts EOL /ESL are shared project resources that need to be uploaded upfront for development of any project developed using AIA programming model. These common resources can be uploaded into the OSB using two approaches:

1. as a Zipped File 2. as a JAR file

The recommended approach is to register the AIA component as JAR file. The AIA Components are subject to enhancements and these enhancements are usually applied as patches or as new versions of the libraries. Hence, updating the existing EOL library should also be made possible. This calls for a model for uploading the EOL/ESL into OSB and managing the enhancements. It is recommended that EOL/ESL be imported as JAR file into OSB. When enhancement/patches are to be applied, a new JAR file with changed artifacts needs to be re-imported into OSB. Thus, the artifacts that require an update would be replaced by the new ones in the new JAR file. The following section lists out the high-level tasks needed to register AIA components using JAR file. Registering AIA components as JAR file Note: It is assumed that a JAR file with AIA Components is available with the user. (This JAR file is a service bus configuration file). There are two issues that the JAR file should address.

1. When WSDLs are uploaded into OSB, the OSB cannot find the schema files referenced by the WSDL automatically. Each schema-file-reference is seen as the ‘invalid dependency’ of the WSDL and each such WSDL‘s invalid dependency is treated as a ‘conflict’. All such conflicts should be resolved manually.

The JAR file must have AIA components with all the conflicts resolved. Please refer to the section on resolving the conflicts for more details.

2. OSB can only create services from WSDLs that have either binding or port information in them. AIA recommends that ‘binding’ information be added to the ESL with SOAP as the binding to be used.

The AIA Components library imported into OSB, as JAR file, should have the all WSDL files updated with details of bindings before it can be used for creating OSB services. Please refer to the section on updating the ESL WSDLs for more details. -AIA recommends that the FP installer should address the above issues. -The steps required for updating the WSDL are detailed here. -A sample WSDL snippet highlighting the updated sections of the WSDL is shown here.


- 9 -

-A high level description of how a service bus configuration JAR file is create with the above two issues addressed is provided here

3. In the OSB console, click on ‘create’, click on ‘System Administration’ and then click on ‘Import’ 4. Browse the file system and select the JAR file to be imported into the OSB.

Developing EBS as OSB Service • Implementation Technology: An EBS would be created as a Proxy Service in OSB. • Service Type : web service • Transport Configuration: The transport protocol to be used would be 'local'. • Operation Selection Configuration : Refer to the section OSB Service Configuration • Message Content Handling: Refer to the section OSB Service Configuration The following diagram shows how an Enterprise Business Service will be invoked using local transport.

• In the scenarios where the EBS needs to be accessed remotely –

o An HTTP adapter (a proxy service using HTTP transport) needs to be built for the EBS. o If it is an external application that needs to access EBS remotely (as shown in the following

diagram), it would directly invoke the HTTP adapter proxy service which in turn will be invoking the local transport based EBS service

o A business service representing this HTTP adapter proxy service would have to be

developed by the clients who would want to access the EBS. The business service will be needed only if the calling service happens to be an OSB based ABCS. It needs to call a business service that represents the HTTP adapter proxy service.

o Please refer to the appendix for the relevant details of developing a Business Service in the

OSB.


- 10 -

External application invoking the EBS using a HTTP adapter.

The following diagram shows how an external application is able to invoke the enterprise business service using a HTTP adapter.

ABCS invoking a remotely located EBS

The following diagram shows how ABCS can invoke a remotely located EBS


- 11 -

Creating EBS as OSB proxy service using WSDL It is a pre-requisite that AIA Components are registered with the OSB. The AIA Components library should be imported into OSB, as JAR file, and should have the all WSDL files updated with details of bindings, before it can be used for creating OSB services. It is assumed here that the imported JAR file addresses all the issues that are mentioned in the previous section.. EBS as OSB proxy service should be created in its own folder as a web service using its WSDL in the ESL. The proxy exposes all the available operations in its WSDL to the clients. The following steps summarize the process required. • Create a folder for the EBS • Create a Proxy Service, select the service type as WSDL web service using the appropriate WSDL.

Select the binding (that has been added to the ESL) • Configure the transport as ‘local’ For AIA recommendations for selection algorithm, message content handling, see here. A later chapter of this document, Creating and Configuring the EBS as OSB Proxy Service, contains a sample detailing how to build an EBS using ESL from the imported JAR having AIA Components. The rest of this section describes how to configure the message flow in an EBS. An EBS built as an OSB Proxy service inherits the intrinsic support, from OSB proxy service, for – • exposing multiple operations defined on it, • creating Routing Rules for each operation, • performing XSLT transformation, • and defining endpoints for each routing rule. The following sections describe in detail – • Configuring the routing rules for the EBS operations • Enable error handling and logging

Message Routing Routing Rules specified for each operation defined on EBS services are used to decide where the incoming request should be routed. The following paragraphs capture the support and the ability provided in the OSB Proxy service for specifying routing rules, evaluating these rules, and determining determine what service to route to. The message flow of an OSB proxy service consists of a set of nodes, of which, the ‘Route’ node has got a specific purpose of dispatching the message to another service. The routing behavior of the message flow is defined by the configuration of the ‘Route’ node.


- 12 -

Recommendations: Even though OSB does have multiple mechanisms to interact with external services, AIA recommends the use of Route node in Enterprise Business Services to dispatch requests to target services. Configure the Routing Node in the Message Flow of EBS OSB Proxy provides support for both context-based/content-based routing and dynamic routing. This section examines different approaches of configuring the route node. The route node configuration determines when and to which target end point the incoming message should be routed. The routing logic performed in the route node using various patterns, are examined, in the section below. The recommended programming model with relevant guidelines for developing it and delivering the routing rules are captured.

Using Route-To in the Route Node

This is the simplest implementation, where the EBS will route the message from the requesting service to the appropriate provider service. The inbound message is always routed to the specified provider service. The endpoint of the provider service is determined at the design time.

Using Routing Table in the Route Node

Consider the case where EBS will route the inbound message by default to a provider application but only after deciding whether it has to route the message to the CAVS or not. This decision is based on the content of the EBMHeader, which determines whether the message should be routed to CAVS, or not. Usually this is expressed as an XPath expression. For ex: - /ebo:QueryCustomerPartyListEBM/corecom:EBMHeader/corecom:MessageProcessingInstruction/corecom:EnvironmentCode/text()='CAVS' Based on the result of evaluation of the above expression, the message is routed to an endpoint. To evaluate an expression and compare it against a given static value, insert a case in the Routing table. In the above model, the EBS will route to the appropriate CAVS service using the Routing Table Action. The routing logic is based on content in the EBM header. Disadvantages of the above Routing models

• Not entirely dynamic • Proxy needs to be modified to change the routing end point.

Due to the disadvantages cited above, the AIA does NOT recommend the constructs Route-To and Routing Table, to be used from an EBS.

Dynamic Routing

We will now examine another routing model in the following section that eliminates the need to modify the Proxy to change the routing endpoint


- 13 -

When we need to determine which of several services to invoke at runtime, we use the Dynamic Route. AIA recommends this approach for configuring the routing from the EBS. Achieved in a route node, dynamic routing

• Eliminates the need to hard code the routing rule expressions in the EBS configuration • Ensures that EBS does not need to be modified to change the routing endpoint • Externalizes the binding between the EBS and target service (could be either proxy or Business)

out of EBS • Allows XQuery expression to be defined in a separate XQuery resource to choose one of the

several services To make the dynamic routing work, we need to have the following in place. 1. An XQuery resource, having an UDF

o to evaluate the routing rule’s filter expression for a specific operation on the EBS. o routing rule’s filter expression is Specified as an XPath expression o Decides where the incoming request should be routed to o The UDF returns a complex XML node that provides fully qualified path to a Service and

also the type of the service as shown below.

<dynamicservice> <servicename>[fully qualified path to a Service]</servicename> <operationname>[name of the operation being invoked] </operationname> <servicetype>[proxy/external]</servicetype> </dynamicservice>

• Every operation defined on EBS would have an XQuery resource specific to it. • The XQuery resource for a given operation is dynamically determined at runtime.

2. An XQuery resource, XQueryResourceFinder, o for a specific operation, returns a fully qualified path to a matching XQuery resource as

described above in #1,

Note: The implementations details of XQueryResourceFinder are yet to be finalized. One of the options that are being considered at this point of time is that the name of the XQuery resource, to be used for a specific operation on EBS, be provided in the file AIAConfigurationProperties.xml. This document would be updated based on the decisions made in this regard. The value of <servicetype> would be either proxy or external depending on whether the EBS needs to route to a proxy or an external service (represented by a OSB Business Service). The dynamic route is achieved by computing the value of pre-defined OSB context variable ctx: route, by using the values of elements <servicename> and <servicetype>. This OSB context variable is used when adding the Dynamic Route node in the message flow. Summarizing, • We use two XQuery resources XqueryResourceFinder and operation-specific XQuery resource that evaluates

the routing rule expression.


- 14 -

• We construct the OSB context variable ctx:route. This variable defines the dynamic endpoint of the service where message will be eventually routed.

• We use the ctx:route in the action ‘Dynamic route to service’ of the Route node. Modeling Route Node in conjunction with Operational Branch In practical situations, multiple operations will be defined on every EBS. Therefore it is necessary to do an operation-specific routing of the inbound message. This can be easily accomplished with using a node that automatically branches based on operations. When an operational branch node is created in a message flow, it is possible to build message routing logic based on the operations defined in the EBS. To add an operational branch to a message flow –

• add Operational Branch node • then, add operation Branch definitions to it

OSB Console presents all the operations defined on EBS in the branch node configuration page, Operation Branch Definitions panel.

AIA recommends that dynamic route be used in conjunction with the Operation Branch construct to model a routing from the EBS. In order to build routing logic for each operation,

• Select a service operation • Add route node in the message flow for the selected operation • Model the dynamic route as described in the section Dynamic routing

A sample EBS configured with Operational Branch that uses a Dynamic Query is given here.


- 15 -

Error Handling See Error handling in OSB

Logging See Logging messages in OSB


- 16 -

Chapter 2

ABCS Programming Model

Developing ABCS Note: OSB technology is recommended only for building the ABCS that is stateless. • Implementation Technology: The ABCS should be built as a proxy service • Service Type : web service • Transport Protocol: AIA recommendation is to use ‘local’ as transport in those cases where

transaction propagation is required. o Transaction is propagated in proxy service only when the transport is ‘local’ o When HTTP transport is used for proxy service, the transaction cannot be propagated even

though the calling service is local and has a transaction • For remotely accessing the ABCS, an HTTP adapter proxy for the ABCS need be developed. AIA

recommends that HTTP adapter needs to be built for the ABCS. • In case of (non-transactional) synchronous-request-response MEP, AIA recommends that ABCS

should be a proxy service using HTTP transport. • EndPoint URI - The end point URI is the URI used by the client for accessing the service. Hence, in

this sample, provide the service name as the endpoint URI. EndPoint URI configuration is required only for non-local transports. In such cases, the service name is generally recommended as the end point URI.

Creation of an ABCS as OSB proxy service with web service as Service Type is illustrated using an example here. The following sections describe the programming model for implementing the core tasks of an ABCS, ex; message validation, message transformation, message enrichment, invocation of EBS, synchronous interaction with applications/services, executing JAVA code, enabling CAVS. Message Validation OSB provides the capability for incoming or outgoing messages to be validated against a WSDL or XML schema with a ‘validation’ action. Messages that fail validation can log the failure or create an error in cases where an error stage can be used to apply alternative actions. Every ABCS needs to have the validation action. By default, it should be turned off and at run time, it should be able to turn on the validation on request basis. Message Transformation OSB adds a message transformation layer that is useful in – • mapping disparate data between source and destination • manipulating the contents of the message OSB provides support for the message transformation using two different technology standards XSLT and XQuery.


- 17 -

XSLT

XSL maps describe XML-to-XML mappings. These transformations (XSL s) can be created by a developer and imported into OSB or the existing XSL resources can be imported into OSB. The message’s content can be manipulated by applying XSLT in conjunction with the message processing actions – assign, replace, insert, etc;, using the XPath Expression Editor of the OSB console. Note: It may be necessary to add definitions for the user-defined namespaces into the OSB for the namespace prefixes used in the XPath expressions. The figure below shows a sample XPath expression and the user defined prefixes used there in.

A sample Replace action in the proxy message flow to apply an XSL transformation on a messages’ content is shown below.

Transformation can be applied to any node in the inbound message. The inbound message is available in the Request Pipeline as a pre-populated variable, body. While applying transformation to a message contents (node), it is possible to either replace the entire node with the reformatted message or just to replace the contents of the node. It is recommended that the ‘Replace node contents; option be used while configuring the stage for applying the transformation. Transformations can be used in the message-flow configuration of the proxy service before the message being sent to the destination service, and also the reverse transformation can be is applied to the service’s response.

Replace [ entire node ] of [ ./ cmu:ListOfCmuAccsyncAccountIo] in [ body ] with [ Xslt Resource: XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM] Input Document: $body


- 18 -

In the former case, for example, to convert and ABM into EBM, the XSLT is in the stage of the Request Pipeline applied with the help of the message processing actions. In the case of reverse transformation, to convert from EBM to ABM, the XSLT can be applied to the response message by adding the message processing actions as the Response actions of the Route node.

XQuery

Maps can describe XML-to-XML, XML to non-XML, and non-XML to XML mappings. The message transformation using XQuery is addressed in detail in a separate document. Message Enrichment In situations, where an ABCS has to query back the participating application to get the information and enrich the message before submitting to EBS, Service Call out action is to be used in a Pipeline pair to call the services. It should be noted that the Service Callout action is used only for invoking synchronous request-response operations. OSB’s service callout action offers greater flexibility for more sophisticated message flows. The service callout action is used inside a message flow to call on another service registered within OSB to perform necessary action on the message. The response returned by that service is assigned to a local variable. The variable can then be used within the current message flow. The service callout action can be used configure a synchronous (blocking) callout to an OSB-registered proxy or business service. The service types that can be called could be – web service, SOAP, Any XML Service and Messaging. Inbound Service Interaction In case of (non-transactional) synchronous-request-response MEP, (requestor) ABCS, by default, is a proxy service using HTTP transport and the applications would access ABCS as a web service. In other cases, since the (requestor) ABCS is built as a proxy service with transport as 'local', it is exposed to the external world via its HTTP adapter proxy service. In case of asynchronous interaction with the (requestor) ABCS, a JMS consumer adapter proxy service, that uses ‘JMS’ as transport, is required. For asynchronous interactions using JMS, see Asynchronous invocation of ABCS Outbound Service Interaction ABCS can be communicating with applications as outbound interaction. The interaction mechanism can be as SOAP Web Service. One of the possible interaction models for outbound communication between ABCS and the application is using Service Callout action, when the outbound interaction is a synchronous request-response MEP, i.e., when the service is invoked using a two-way call. When the outbound interaction is asynchronous, we need to use Publish action.


- 19 -

The following diagram depicts how an ABCS interacts (outbound) with an application, using Service Call-out action and Publish action, for two-way and one-way invocations, respectively.


- 20 -

Configuring Service Call Out action Service callout action is to be added in the message flow of the proxy service. • Left-click an existing in the message flow and follow Add action Communication -> Service

Callout from the pop-up menu. • The service callout action allows us to make a call to an existing service (registered with OSB). Left-

click the Service link, and from the list of registered services displayed, select the required service and click the Submit button.

• Next, select the required operation from the combo box. • Select the Configure Soap Body radio button and enter the value body for the SOAP Request Body

field. Similarly, enter the value of body into the SOAP Response Body field. The Service action should look like as given below.

Invocation of EBS and / or Application Services The ABCS either presents the request to the EBS or services the request received from the EBS by invoking the application services. In the OSB, this is accomplished with Route node in the message flow of a proxy service, which performs request/response communication with another service. Route node is a leaf node in the message flow that handles the request/response dispatching of the message to either a business service or a proxy service, registered with the OSB. • When the EBS is co-located (as a proxy service using ‘local’ transport) with the ABCS, the ABCS

proxy service would use route node to directly invoke the EBS proxy service. An EBS is seen as co-located with ABCS when it is deployed in the same instance of OSB.

• When the EBS is not co-located, developers need to build a business service, representing the HTTP-

adapter-proxy-service of the EBS. ABCS proxy service would then route to this business service. Please refer to the diagram that depicts how ABCS can invoke a remotely located EBS


- 21 -

• In situations where there is a need for ABCS to make multiple calls to Enterprise Business Services, Route node approach should be used for invoking the primary EBS. For invoking a secondary EBS, which is synchronous - two-way, Service Call-Out action is recommended.

Computing dynamic endpoint location in ABCS

Using Java Callout for invoking AIA Configuration API

In a proxy service, in order to invoke a Java method within the message flow, the Java Callout action need to be used. The java method must be public & static and the Java class must be ‘JAR’-red in a file. The JAR file must be registered with the OSB. The allowed data types in the signature of the static method are – • the primitive types and their corresponding class types • java.lang.String, java.lang.BigDecimal, and java.lang.BigInteger, org.apache.xbeans.XmlObject • byte[], the only allowed array type, both as input parameter and return value • java.lang.String[],org.apache.xbeans.XmlObjectXmlObject[], allowed only as input parameters Apart from above types, custom return types are possible from a java call outs, but you can only store them in the pipeline them as parameters to other Java callouts. The return values of custom types cannot be accessed elsewhere in the pipeline.

Configuring the Proxy pipeline to determine the dynamic endpoint location

1. Configure a stage, naming it as, GetRouteToCAVSProperty a. Use java call-out action to

oracle.apps.aia.core.config.Configuration.getServiceProperty() to read the value of Routing.[PartnerlinkName].RouteToCAVS property from the configuration file.

2. Configure a stage, naming it as, GetCAVSEndpointLocation a. Use a flow-control action – if-then- to check if the value of the property is set to ‘true’ b. If the property value is ‘true’, then use java callout as in 1.(a) to read the value of the

property Routing.[PartnerlinkName].CAVS.EndpointURI

CAVS Enabling

Developing Provider ABC Services to be CAVS-Enabled

The following steps describe how to code a provider ABC service for dynamic CAVS-enabled endpoint for invoking target participating application web service. In the request pipeline of the provider ABCS proxy service, 1. Configure a stage, naming it as GetTargetSystemID, with

a. Using Replace action, apply XSLT, AddTargetSystemID.xsl, on the inbound EBM b. Use Assign to set the value of [names pace prefix of

EBM]QueryCustomerPartyEBM/corecom:EBMHeader/ corecom:Target/ corecom:ID to variable ‘SystemID’


- 22 -

2. Configure a stage, naming it as, AssignDynamicPartnerlinkVariables, with Assign action to set the

variables with ServiceName, endpoint name (PartnerLinkName), routeToCavs PropertyName, cavsEndpoint PropertyName

3. Compute the ‘targetEndpointLocation’ as described in the section Configuring the Proxy pipeline to

determine the dynamic endpoint location 4. Add a Service call out action in the proxy and configure it as described below

a. In the Request actions of the Route node, add a flow-control action – if-then- to check if ‘targetEndpointLocation’ has a value.

b. If yes, add a Routing Options action to override the default configuration of the route

node

i. Set the checkbox URI and set its expression with ‘targetEndpointLocation’ ii. Set the Mode to request-response or request, depending on whether the MEP is

a request-response or request-only. iii. For other configuration parameters, please refer to OSB Service Configuration

Developing Requestor ABC Services to be CAVS-Enabled

Some requester ABC services will need to communicate directly back to the calling participating application. For this type of outbound interaction, the requester ABC service is acting similar to a provider ABC service in that it is invoking a participating application web service. For this kind of scenario, configuring the Requestor ABCS is similar to the configuring the Provider ABCS for CAVS-enablement

Logging See Logging messages in OSB

Error handling in ABCS See Error handling in OSB


- 23 -

Chapter 3

Extending ABCS

Developing ABCS Extensibility service • The service implementation at extension point could be a HTTP/SOAP service or could have been

implemented using other technologies. It could be remote or local w.r.t ABCS • To access it from an ABCS, a Business Service is required to be developed to invoke the service at

the extension point. • Business Service representing the service at the extension point needs to be defined with a dummy

endpoint URI. • The design-time URI is overridden with the runtime-URI, which is read from the configuration file,

AIAConfigurationProperties.xml. • ABCS would use a Service-call out action to invoke the Business Service. The steps are detailed

below.

Configuring the ABCS Message flow to incorporate ABCS Extensibility • Add a new Stage in the message flow of the ABCS, prior to a process step, say

pre[process_stepname]ABM • Using Java Call Out action, read the value of the property, ABCSExtension.

pre[process_stepname]ABM • Check if the value of the property in the AIAConfigurationProperties.xml is set to ‘true’ • If yes,


- 24 -

• Using Assign action, set the payload from the node, body, to the variable pre[process_stepname]ABMReqMsg

• Add Service Callout action to the business service, invoking the operation pre[process_stepname]ABM

• Enter pre[process_stepname]ABMReqMsg as Request Document Variable • Enter pre[process_stepname]ABMRespMsg as Response Document Variable • In Request Actions of the Service call-out, use the Java Callout action to read the concrete end point

URL of the service at the extension point. • In Request Actions of the Service call-out, add the action ‘Routing Options’ • Over ride the URI in the Routing Options with the concrete end point URL of the service • Add replace action after the Service Call out action and replace the payload of the variable body with

the value of the variable Enter pre[process_stepname]ABMRespMsg


- 25 -

Chapter 4

Asynchronous invocation of ABCS This section describes how OSB can be configured to provide an asynchronous messaging pattern on a synchronous ABCS implementation. The ABCS is a Proxy Service with transport protocol as ‘local’. JMS is used as the underlying infrastructure. The inbound service request messages are queued in a JMS queue and then dispatched to the synchronous ABCS implementation. The steps required to implement this solution are described below. The pre-requisite is to configure the JMS Connection Factory and the JMS Queue, which are used in the configuration of JMS Consumer Adapter, an OSB proxy service. Please see the Appendix for details.

The following sections describe two OSB Services required for Asynchronous MEP using JMS -

• JMS Consumer Adapter proxy Service to consume messages off the queue • JMS Producer Adapter to feed the queue

JMS Consumer Adapter JMS Consumer Adapter is a Proxy Service that uses JMS transport. The proxy service would consume messages off the queue and would route to Requestor ABCS. The configuration details are as given under.

Transport Configuration

Protocol – jms Endpoint URI - jms://host:port/weblogic.jms.XAConnectionFactory/QueueJndiName

JMS Transport Configuration

Destination Type – Queue Dispatch Policy – default

Advanced Settings

Is XA Required – select the check box The following section describes high-level tasks for building a JMS Produces Adapter for the scenarios where the queue is fed with inbound service requests using OBS.

JMS Producer Adapter

1. Build a Business Service using JMS transport to feed Queue with the messages. The Transport configuration is same as described for the JMS Consumer Adapter. The QueueJndiName should be same as used for JMS Consumer Adapter.

2. For other configuration details, please refer OSB Service Configuration 3. Build a HTTP adapter Proxy Service that can be accessed by external clients. Configure its

message flow by adding a Route Node to the Business Service, described in step 1.


- 26 -

Error Handling and Recovery for Guaranteed Message Delivery

Error handling and recovery for the asynchronous MEP to ensure guaranteed message delivery is implemented as follows: 1. Ensure that each message has a unique message identifier. 2. Populate the enterprise business message (EBM) header with the source milestone identifier. 3. Ensure that the fault notification contains the message identifier and source milestone identifier

of the faulted message. 4. Resolve the JMS destination (or source application) specific to the source milestone identifier in

the AIA Configuration Properties file. 5. Use the Message Resubmission Utility to recover and resubmit a faulted message. For more details, please refer to the Oracle Application Integration Architecture – Foundation Pack: Concepts and Technologies Guide.


- 27 -

Chapter 5

Using Adapters with AIA on OSB AIA recommends using adapters when the applications that are integrated do not have support for web services and standard protocols. As current web service implementations do not have support for transactions, AIA also recommends using adapters when the integration with applications requires transactions.

AIA OSB Adapters Architecture

For outbound communication using adapters, ABCS will call OSB business service defined using JCA transport. In cases you need additional transformation between ABCS and the back end application, AIA recommends creating proxy service with local transport along with business service. For inbound communication using adapters, AIA recommends creating an adapter proxy service with JCA transport. Adapter proxy service will call ABCS. Adapter proxy service may have additional transformation if required. High level steps for using Adapters on OSB

1. Using JDeveloper, Create an empty BPEL or ESB project

2. Configure the Adapter in Jdeveloper

3. Copy the WSDLs, schemas and XML files related to Adapter configuration.

4. From WLS console, create a datasource with the same name you used in configuring the adapter in JDeveloper.

5. From WLS console, optionally configure the datasource on the adapter you are using in deployments with the datasource name.

6. From OSB console, create resources for WSDL and Schema files

7. Create a business Service(outbound communication) or Proxy Service(inbound communication) with JCA transport and use the xml file

For detailed instructions on how to configure each adapter please refer to OSB documentation.


- 28 -

Chapter 6

Implementing Synchronous request-response MEP

Creating and Configuring the EBS as OSB Proxy Service Note: It is assumed that WSDLs & Schemas are already registered as OSB resources. The following steps have to be followed for creating EBS as OSB proxy service • Create a new project, SamplesCustomerPartyEBS • Create a new resource, of type Proxy Service, in the project folder. • Name it as SamplesCustomerPartyEBS. • Select the service type as ‘web service’. • Click on Browse and select customerPartyEBS.wsdl, from the displayed list of registered WSDLs. • From the pop-up, Select a WSDL Definition, select the binding – CustomerPartyEBSBinding


- 29 -

Transport Configuration • Protocol - As mentioned above, we will use ‘local’ transport for EBS proxy service by default. Hence,

for this sample, the protocol for the SampleCustomerPartyEBS would be selected as ‘local’. • EndPoint URI - The end point URI is the URI, which is used by the client for accessing the service.

When using local transport, the service would not have any endpoint. Hence, in this sample, EBS would not have any endpoint URI. Configure the end point URI only for non-local transports. The format of the URI is based on the transport protocol.

The summary page of the EBS proxy service, after the configuration is complete would look as given below.


- 30 -

Message Routing In EBS In this sample, we would want to route from EBS to one of the following endpoint services. -SamplesQueryCustomerPartyPortalProvABCSImpl, developed as a OSB Proxy service -SimulatorService, developed as OSB Business service representing an external service

Adding Operational Branch Node

In the message flow of CustomerPartyEBS proxy services, • Add an operational branch node. • Edit the ‘operational branch’ node to add operation branch definitions for the operation

‘querycustomerparty’ • Edit the branch node ‘querycustomerparty’ to add the dynamic routing flow, as described in the

following section.

Configuring the EBS for the Dynamic Routing

We require two XQuery resources XqueryResourceFinder and EvaluateRoutingRule. The sample XQuery resources used in this example are produced below. XqueryResourceFinder

EvaluateRoutingRule

This XQuery resource evaluates the xpath filter expressions for a specific operation, SamplesQueryCustomerParty, on EBS. It returns one of the available target services as a complex xml element. The function is named has EvaluateRoutingRule and takes QueryCustomerPartyEBM as the parameter. The function tries to evaluate the filter expressions to a logical truth-value and if successful, returns the corresponding complex XML element.

Note: It is a prerequisite that the ABC services where EBS routes to, are built and configured prior.

declare namespace xf = "http://tempuri.org/XQueryResourceFinder/"; declare function xf:XQueryResourceFinder() as xs:string { 'EvaluateRoutingRule' }; xf:XQueryResourceFinder()


- 31 -

The steps involved in message flow configuration are defined below 1. Create XQuery resources XqueryResourceFinder and EvaluateRoutingRule and upload into OSB

a. In the OSB console, navigate to folder SamplesCustomerPartyEBS from the Project Explorer

b. To create new resource, select resource type as XQuery c. Click Browse and upload the existing XQuery file in the file system OR enter the XQuery

text and Save. 2. To configure the EBS, click ‘Edit Message Flow’ for SamplesCustomerPartyEBS 3. Add the Assign action in the stage

a. For Assign Expression, click on ‘XQuery Resources’ and chose XqueryResourceFinder as the resource

b. Assign the result of the above expression to the variable dynamicXQueryResource 4. Add the Assign action in the stage

a. For Assign Expression, click on ‘Dynamic XQuery ‘ and chose EvaluateRoutingRule as the resource

b. To Add Custom Variable, click on ADD and provide QueryCustomerPartyEBMVar as the Variable name

(:: pragma bea:global-element-parameter parameter="$QueryCustomerPartyEBMVar" element="v2:QueryCustomerPartyEBM" ::) declare namespace v2 = "http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2"; declare namespace v21 = "http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2"; declare namespace xf = "http://tempuri.org/EvaluateRoutingRule/"; declare function xf: EvaluateRoutingRule($QueryCustomerPartyEBMVar as element(v2:QueryCustomerPartyEBM)) as element(*){ if(($QueryCustomerPartyEBMVar/v21:EBMHeader/v21:MessageProcessingInstruction/v21:EnvironmentCode='PRODUCTION' or not($QueryCustomerPartyEBMVar/v21:EBMHeader/v21:MessageProcessingInstruction/v21:EnvironmentCode/text())) and ($QueryCustomerPartyEBMVar/v21:EBMHeader/v21:Target/v21:ApplicationTypeCode='PORTAL' or (not($QueryCustomerPartyEBMVar/v21:EBMHeader/v21:Target/v21:ID/text())))) then <dynamicservice> <servicename>SamplesQueryCustomerPartyPortalProvABCSImpl/SamplesQueryCustomerPartyPortalProvABCSImpl</servicename> <operationname>SamplesQueryCustomerParty</operationname> <servicetype>proxy</servicetype> </dynamicservice> else if($QueryCustomerPartyEBMVar/v21:EBMHeader/v21:MessageProcessingInstruction/v21:EnvironmentCode='CAVS') then <dynamicservice> <servicename>Simulator/SimulatorService</servicename> <servicetype>proxy</servicetype> </dynamicservice> else <dynamicservice></dynamicservice> }; declare variable $QueryCustomerPartyEBMVar as element(v2:QueryCustomerPartyEBM) external; xf: EvaluateRoutingRule($QueryCustomerPartyEBMVar)


- 32 -

c. provide the $body/* as the binding input value to the variable QueryCustomerPartyEBMVar

d. Assign the result of the above expression to the variable endPointService

5. Add the Assign action in the stage

a. For assign expression, click on XQuery Text b. Use the value of the variable endPointService and prepare the context variable, ctx: route as

shown below

c. Assign the result of the above expression to the variable, dynamicEndpoint

6. Add Dynamic Route Node in the message flow

a. Create a RouteNode, and add action ‘Dynamic route to service’ b. Edit the expression and provide $dynamicEndpoint as its value

let $servicedetails:=$endPointService return if($servicedetails/servicetype/text()='proxy') then <ctx:route> <ctx:service isProxy='true'>{$servicedetails/servicename} <ctx:operation>{$servicedetails/operationname}</ctx:operation> </ctx:service> </ctx:route> else <ctx:route> <ctx:service isProxy='false'>{$servicedetails/servicename} </ctx:service> </ctx:route>


- 33 -

Error handling in EBS See Error handling in OSB

Developing Requestor ABCS 1. Create Project – SamplesQueryCustomerPartySiebelReqABCSImpl

a. Click on "Project Explorer" on left panel in the OSB console b. Enter project name in text box as SamplesQueryCustomerPartySiebelReqABCSImpl and click on

"Add Project". 2. Upload the WSDL SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl

a. In the projects table, Click on the project that has been just created. b. From “Select Resource type” drop down options, select WSDL c. Click on ‘Browse’ and navigate to the path in the file system to find

SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl and click on ‘save’ d. OSB console displays the following conflict message

e. In order to resolve the conflicts, we need to first upload all the files that are referenced by

SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl. The following files have to be uploaded into the OSB from the file system by following the procedure defined by steps 2(a) through 2(c).

Runtimefault.wsdl, CmuAccsyncAccountIo.xsd Note: Do not upload Meta.xsd as it is already bundled in EOL. Upload CmuAccsyncAccountIo.xsd into the folder SamplesQueryCustomerPartySiebelReqABCSImpl.


- 34 -

f. Now we are ready to resolve the conflicts. Go back to project folder, drilled down into WSDL SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl and go into the “Edit References” screen.

For each resource type, WSDL and XSD, click on the Browse and select an appropriate resource from the browser list popped up by OSB Console. Save the WSDL after resolving all the conflicts. 3. Update the WSDL SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl, fixing the missing port/

binding information in the WSDL. a. Insert the following xml element in the WSDL.

<binding name="SamplesQueryCustomerPartySiebelReqABCSImplBinding" type="tns:SamplesQueryCustomerPartySiebelReqABCSImpl"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="SamplesQueryCustomerParty"> <soap:operation style="document" soapAction="SamplesQueryCustomerParty"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding>

4. Create the Proxy Service SamplesQueryCustomerPartySiebelReqABCSImpl in the project folder a. Create a new resource, of type Proxy Service, in the project folder. b. Name it as SamplesQueryCustomerPartySiebelReqABCSImpl. c. Select the service type as ‘web service’. d. Click on Browse and select SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl, from

the displayed list of registered WSDLs. e. From the pop-up, Select a WSDL Definition, select the binding –

SamplesQueryCustomerPartySiebelReqABCSImplBinding f. Protocol – select ‘http’ from the drop down g. EndPoint URI - The end point URI is the URI, which is used by the client for accessing the

service. Hence, in this sample, provide the service name as the endpoint URI.


- 35 -

The summary page of the proxy service, after the configuration is complete would look as shown below.

5. Uploading the XSL s required for message transformations in the proxy

a. Upload the following XSL resources into OSB

• XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM.xsl • XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM_Custom.xsl • XformQueryCustomerPartyResponseEBMToListOfCmuAccsyncAccountIo.xsl

b. The following changes are required to be made to the XSL resources.

• In the node selection xpath, '/' does not work as the root node is 'soap'. So '/' need to be

replaced with '//' • Comment out the API getEBMHeaderSenderSystemNode and all references to the node

returned by the API • Hard code the BSR values assigned to EBM Header • Comment out Oracle xpath extensions; eg: - orcl:generate-guid() • Comment out Xpath 2.0 functions; eg: - xp20:current-dateTime() • Comment out the Xref and DVM functions

c. For more details

-Refer to the section Using AIA XPath Functions


- 36 -

Configure the message flow of the proxy service 1. Add stage XFORM ABM to EBM

a. To transform from ABM to EBM, use 'replace' action to replace the node ListOfCmuAccsyncAccountIo in the variable 'body' with the expression, which takes the form of XSLT resource. Use the expression. /cmu:ListOfCmuAccsyncAccountIo for the ‘replace’

b. Add user defined namespace prefix variables and URI s for the node ListOfCmuAccsyncAccountIo.

c. Select the XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM.xsl as the XSLT resource and provide the $body as the binding input

2. Assigning EBM Header

d. Assign the expression $body/ebo:QueryCustomerPartyEBM/corecom:EBMHeader to the variable EBM_HEADER

e. Add user defined namespace prefix ebo and with its URI, if required. 3. Routing to the EBS from a Requestor ABCS

f. Add Route Node to message flow g. Edit the Route Node to invoke the SamplesCustomerPartyEBS proxy service invoking the

operation 'QueryCustomerParty' 4. Transforming the response EBM back to ABM

h. Add actions to ‘Response’ action of the Route Node to XFORM EBM to ABM i. To transform from EBM to ABM, add the 'replace' action to the response actions of the

Route node j. Replace the node QueryCustomerPartyResponseEBM in the variable 'body' with the

expression, which takes the form of XSLT resource. k. Select the XformQueryCustomerPartyResponseEBMToListOfCmuAccsyncAccountIo.xsl as

the XSLT resource and provide the $body as the binding input Error Handling in Requestor ABCS See Error handling in OSB

Developing Provider ABCS Follow the instructions given in the section for developing Requestor ABCS and do the following.

• Create the project folder • Upload WSDL and resolve the conflicts • Add binding details to WSDL • Create SamplesQueryCustomerPartyPortalProvABCSImpl as the proxy service


- 37 -

Configuring the Proxy Service Upload all the XSL s required Make changes to the XSL s similar to what we did when configuring the Requestor ABCS Configure the message flow with the steps given below. 1. Get target system ID

a. Use 'replace' action to replace the node QueryCustomerPartyEBM in the variable 'body' with the expression, which takes the form of XSL resource, AddTargetSystemID.xsl

Provide the $body as the binding input b. Assign the result of the XPath expression,

$body/ebo:QueryCustomerPartyEBM/corecom:EBMHeader/corecom:Target/corecom:ID to the variable ‘SystemID’ Note: The name space prefixes used in the expression and the corresponding URI need to be defined.


a. Assign the expression $body/ebo:QueryCustomerPartyEBM/corecom:EBMHeader to the variable EBM_HEADER

b. Add user defined namespace prefix ebo and with its URI, if required.

3. Add stage XformQueryCustomerPartyEBMToPcmOpCustCommitCustomer a. use 'replace' action to replace the node QueryCustomerPartyEBM in the variable 'body' with

the expression, which takes the form of xslt resource, XformQueryCustomerPartyEBMToPcmOpCustCommitCustomer

b. Select the XformQueryCustomerPartyEBMToPcmOpCustCommitCustomer.xsl as the

XSLT resource and provide the $body as the binding input 4. To compute the dynamic endpoint location, and route to it, follow the steps 2,3 & 4 of section

Developing Provider ABC Services to be CAVSEnabled Default design-time Routing to the Provider service from a Provider ABCS

Add a Service call out action to invoke the SamplesCustomerPartyProvider service invoking the operation 'QueryCustomerParty'

5. Error Handling a. In the response actions, check for the ‘Fault’ element in the response actions of the route

node b. If ‘Fault’ element is present raise an error with business error code and the business error

message. 6. Transforming the response from provider service back to EBM

a. Add actions to ‘Response’ action of the Route Node b. add the 'replace' action to the response actions of the Route node c. Replace the node portalabm:PCM_OP_CUST_COMMIT_CUSTOMER_inputFlist in the

variable 'body' with the expression, which takes the form of xslt resource. d. Select the PcmOpCustCommitCustomerToQueryCustomerPartyResponseEBM.xsl as the

XSLT resource and provide the $body as the binding input


- 38 -

Using AIA XPath Functions With regards to the API s in the aia.JAR, the implementation classes of SOA Suite version use oracle-specific libraries and non-JAXP-compliant xml-parsing logic to parse the xml. Hence, modifications to the code are necessary. As a proof of concepts, the sample developed on OSB ports few of AIA functions, onto OSB, after recompiling the code. For ex; functions that retrieve configuration values getServiceProperty(..), getSystemModuleProperty, from the file, AIAConfigurationProperties.xml, are ported onto OSB. The classes, which are modified, are – oracle.apps.aia.core.config. ConfigurationLoader oracle.apps.aia.core.config.Configuration oracle.apps.aia.core.xpath.AIAFunctions It is required to register the underlying drivers used by the XML parsers and transformers – DocumentBuilderFactory, SaxParserFactory and TransformerFactory, with the Weblogic Server. This can be done by configuring the XML resources of WebLogic Server. The default implementations used by WLS are com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl com.sun.org.apache.xerces.internal.jaxp.TransformerFactoryImpl After re-compiling the code and re-creating JAR file, the JAR file must be registered. This is done by way of creating a new resource of type ‘JAR’ for the project from the ALSB console.

Using AIA XPath functions in XSL

Using the java API in the XSL as a custom XPath function is very straight forward (and it is a standard approach). The Java class, oracle.apps.aia.core.xpath.AIAFunctions, with the public-static methods is the interface for accessing all the functions. (The methods have to be static and must return a String as the data type) In order to call the API (of AIA XPath Functions) in the XSL, we need to define a namespace for the Java class and add it to the XSL. To be in consistent with the namespace, which is currently used by XSL s in SOA Suite, the name space is defined as xmlns:aia="http://www.oracle.com/XSL/Transform/java/oracle.apps.aia.core.xpath.AIAFunctions” We can now call the java API as an XPath function in our XSL. For example, in order to call API getServiceProperty (..), we would just use the following code in XSL. <xsl:value-of select=" aia:getServiceProperty (..)"/> This is no different from how we are coding currently in the XSL s on SOA Suite


- 39 -

Chapter 7

Implementing Fire-and-Forget MEP

Developing one-way ABCS Requestor Developing Requestor ABCS The steps to be followed are similar to what is described in the section Developing Requestor ABCS 1. Create Project – SamplesCreateCustomerSiebelReqABCSImpl

a. Click on "Project Explorer" on left panel in the OSB console b. Enter project name in text box as SamplesCreateCustomerSiebelReqABCSImpl and click on "Add

Project".

2. Upload the WSDL SamplesCreateCustomerSiebelReqABCSImpl.wsdl


SamplesCreateCustomerSiebelReqABCSImpl.wsdl and click on ‘save’ d. In order to resolve the conflicts, we need to first upload all the files that are referenced by

SamplesCreateCustomerSiebelReqABCSImpl.wsdl.

e. Runtimefault.wsdl, CmuAccsyncAccountIo.xsd

Note: Do not upload Meta.xsd as it is already bundled in EOL.

f. Upload CmuAccsyncAccountIo.xsd into the folder SamplesCreateCustomerSiebelReqABCSImpl.

g. Now we are ready to resolve the conflicts. Go back to project folder, drilled down into WSDL SamplesCreateCustomerPartySiebelReqABCSImpl.wsdl and go into the “Edit References” screen.

For each resource type, WSDL and XSD, click on the Browse and select an appropriate resource from the browser list popped up by OSB Console. Save the WSDL after resolving all the conflicts.

3. Update the WSDL SamplesCreateCustomerSiebelReqABCSImpl.wsdl, fixing the missing port/ binding

information in the WSDL.

Insert the following xml element in the WSDL.

<binding name=" SamplesCreateCustomerSiebelReqABCSImplBinding" type="tns: SamplesCreateCustomerSiebelReqABCSImpl"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="CreateCustomer"> <soap:operation style="document" soapAction="CreateCustomer"/> <input> <soap:body use="literal"/>


- 40 -

</input> <output> <soap:body use="literal"/> </output> </operation> </binding>

4. Create the Proxy Service SamplesCreateCustomerSiebelReqABCSImpl in the project folder

a. Create a new resource, of type Proxy Service, in the project folder. b. Name it as SamplesCreateCustomerSiebelReqABCSImpl. c. Select the service type as ‘web service’. d. Click on Browse and select SamplesCreateCustomerSiebelReqABCSImpl.wsdl, from the

displayed list of registered WSDL s. e. From the pop-up, Select a WSDL Definition, select the binding –

SamplesCreateCustomerSiebelReqABCSImplBinding f. Protocol – select ‘http’ from the drop down g. EndPoint URI - The end point URI is the URI, which is used by the client for accessing the

service. Hence, in this sample, provide the service name as the endpoint URI. 5. Uploading the XSL s required for message transformations in the proxy

a. Upload the following XSL resources into OSB • XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl • XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM_Custom.xsl


• In the node selection xpath, '/' does not work always as the root node is 'soap:Body'. So in the XPath expression, to select a node, '/’ might be needed to be replaced with '//' whenever a node is to be searched in the document from the current node, no matter where it is.

• Comment out the API getEBMHeaderSenderSystemNode and all references to the node returned by the API

• Hard code the BSR values assigned to EBM Header • Comment out Oracle xpath extensions; eg: - orcl:generate-guid() • Comment out Xpath 2.0 functions; eg: - xp20:current-dateTime() • Comment out the Xref and DVM functions

For more details -Refer to the section Using AIA XPath Functions

Configure the message flow of the proxy service

6. Add stage XFORM ABM to EBM

a. To transform from ABM to EBM, use 'replace' action to replace the node ListOfCmuAccsyncAccountIo in the variable 'body' with the expression, which takes the


- 41 -

form of xslt resource. Use the expression. /cmu:ListOfCmuAccsyncAccountIo for the ‘replace’


c. Select the XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl as the XSLT resource and provide the $body as the binding input


a. Assign the expression $body/ebo: CreateCustomerPartyListEBM/corecom:EBMHeader to the variable EBM_HEADER

b. Add user defined namespace prefix ebo and with its URI, if required. 8. Routing to the EBS from a Requestor ABCS

a. Add Route Node in the message flow. b. Edit the Route Node to invoke the SamplesCustomerPartyEBS proxy service invoking the

operation 'CreateCustomerParty' Error handling in Requestor ABCS See Error handling in OSB



Configuring the Proxy Service Upload all the XSL s required Make changes to the XSL s similar to what we did when configuring the Requestor ABCS Follow the steps listed below. 1. Get target system ID

a. Use 'replace' action to replace the node CreateCustomerPartyListEBM in the variable 'body' with the expression, which takes the form of XSL resource, AddTargetSystemID.xsl

Provide the $body as the binding input b. Assign the result of the XPath expression, $body/ebo:

CreateCustomerPartyListEBM/corecom:EBMHeader/corecom:Target/corecom:ID to the variable ‘SystemID’ Note: The name space prefixes used in the expression and the corresponding URI need to be defined.


- 42 -



b. Add user defined namespace prefix ebo and with its URI, if required.

3. Add stage XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer

a. use 'replace' action to replace the node CreateCustomerPartyListEBM in the variable 'body' with the expression, which takes the form of xslt resource, XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer

b. Select the XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer.xsl as the


Developing Provider ABC Services to be CAVSEnabled 5. Default design-time Routing to the Provider service from a Provider ABCS

Add Service call out action to invoke the SamplesCreateCustomerPartyPortalProvider service invoking the operation 'CreateCustomerParty'

6. Error Handling a. In the response actions, check for the ‘Fault’ element in the response actions of the route

node b. If ‘Fault’ element is present raise an error with business error code and the business error

message. 7. Transforming the response from provider service back to EBM

a. Add actions to ‘Response’ action of the Route Node b. add the 'replace' action to the response actions of the Route node c. Replace the node portalabm:PCM_OP_CUST_COMMIT_CUSTOMER_inputFlist in the

variable 'body' with the expression, which takes the form of xslt resource. d. Select the

XformPcmOpCustCommitCustomerToCreateCustomerPartyListResponseEBM.xsl as the XSLT resource and provide the $body as the binding input

Developing JMS Consumer Adapter The following steps illustrate a jms-based solution for invoking a one-way, synchronous Service, using asynchronous messaging pattern. With an asynchronous messaging pattern, the service consumer's request is queued for later execution. 1. Define and configure a Proxy Service, JMS protocol for transport. This proxy service is now a

message consumer that consumes messages off the JMS Queue. 2. Configure the proxy service defined in step 1, to route the messages to the Requestor ABCS. The details of setting up JMS resources are given here.


- 43 -

Chapter 8

Implementing Asynchronous request –delayed response MEP The following diagram depicts how an Asynchronous request-delayed response is to be implemented.

As shown in the above diagram, the invocation track for sending the request’ to the provider application service is similar to what it is for the Fire-n-Forget MEP. The Provider ABCS, after receiving the response from the Provider application, invokes a second one-way EBS. The invocation to the Response EBS is made using ‘Route’ node. The Response EBS would then route response message to the Response ABCS. The URI of the response ABCS is computed dynamically from the EBM Header in the Response EBM. The sample illustrating this MEP has • One-way Requestor ABCS that routes the inbound request message to the Enterprise Business

Service, CustomerPartyEBS. • The EBS, CustomerPartyEBS that routes the inbound request message to the Provider ABCS. • The Provider ABCS invokes the provider application using ‘Service Call out’ action. The Provider

ABCS uses Route node to route the response from the provider application to the CustomerPartyResponseEBS.

• CustomerPartyResponseEBS sends the response message to the Response ABCS. The process of

dynamically routing to the Response ABCS is similar to how incoming request is routed from the CustomerPartyEBS to the Provider ABCS.


- 44 -

The dynamic XQuery evaluates the routing rule checking the value of following node in the EBM header, to route to the Response ABCS ebo:CreateCustomerPartyListResponseEBM/corecom:EBMHeader/corecom:Sender/corecom:WSAddress/wsa:ReplyTo/wsa:ServiceName

Developing one-way ABCS Requestor Developing Requestor ABCS The steps to be followed are similar to what is described in the section Developing Requestor ABCS 1. Create Project – SamplesAsyncCreateCustomerSiebelReqABCSImpl

a. Click on "Project Explorer" on left panel in the OSB console b. Enter project name in text box as SamplesAsyncCreateCustomerSiebelReqABCSImpland click on

"Add Project".

2) Upload the WSDL SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl


SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl and click on ‘save’ d. In order to resolve the conflicts, we need to first upload all the files that are referenced by

SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl.

e. Runtimefault.wsdl, CmuAccsyncAccountIo.xsd

Note: Do not upload Meta.xsd as it is already bundled in EOL.

f. Upload CmuAccsyncAccountIo.xsd into the folder SamplesAsyncCreateCustomerSiebelReqABCSImpl.

g. Now we are ready to resolve the conflicts. Go back to project folder, drilled down into WSDL

SamplesAsyncCreateCustomerPartySiebelReqABCSImpl.wsdl and go into the “Edit References” screen.

h. For each resource type, WSDL and XSD, click on the Browse and select an appropriate resource

from the browser list popped up by OSB Console. Save the WSDL after resolving all the conflicts.

3) Update the WSDL SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl, fixing the missing port/

binding information in the WSDL.

a. Insert the following xml element in the WSDL.

<binding name=" SamplesAsyncCreateCustomerSiebelReqABCSImplBinding" type="tns: SamplesAsyncCreateCustomerSiebelReqABCSImpl"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="CreateCustomer">


- 45 -

<soap:operation style="document" soapAction="CreateCustomer"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation> </binding>

4) Create the Proxy Service SamplesAsyncCreateCustomerSiebelReqABCSImpl in the project folder

a. Create a new resource, of type Proxy Service, in the project folder. b. Name it as SamplesAsyncCreateCustomerSiebelReqABCSImpl. c. Select the service type as ‘web service’. d. Click on Browse and select SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl, from the

displayed list of registered WSDLs. e. From the pop-up, Select a WSDL Definition, select the binding –

SamplesAsyncCreateCustomerSiebelReqABCSImplBinding f. Protocol – select ‘http’ from the drop down g. EndPoint URI - The end point URI is the URI, which is used by the client for accessing the

service. Hence, in this sample, provide the service name as the endpoint URI. 5) Uploading the XSL s required for message transformations in the proxy

a. Upload the following XSL resources into OSB • XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl • XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM_Custom.xsl


• In the node selection xpath, '/' does not work always as the root node is 'soap:Body'. So in the XPath expression, to select a node, '/’ might be needed to be replaced with '//' whenever a node is to be searched in the document from the current node, no matter where it is.

• Comment out the API getEBMHeaderSenderSystemNode and all references to the node returned by the API

• Hard code the BSR values assigned to EBM Header • Comment out Oracle xpath extensions; eg: - orcl:generate-guid() • Comment out Xpath 2.0 functions; eg: - xp20:current-dateTime() • Comment out the Xref and DVM functions

For more details

-Refer to the section Using AIA XPath Functions

Configure the message flow of the proxy service 6) Add stage XFORM ABM to EBM


- 46 -

a. To transform from ABM to EBM, use 'replace' action to replace the node ListOfCmuAccsyncAccountIo in the variable 'body' with the expression, which takes the form of xslt resource. Use the expression. /cmu:ListOfCmuAccsyncAccountIo for the ‘replace’


c. Select the XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl as the XSLT resource and provide the $body as the binding input

7) Assigning EBM Header


b. Add user defined namespace prefix ebo and with its URI, if required. 8) Routing to the EBS from a Requestor ABCS

a. Add Route Node to EBS b. Edit the Route Node to invoke the SamplesCustomerPartyEBS proxy service invoking the

operation 'CreateCustomerParty' Error handling in Requestor ABCS See Error handling in OSB



Configuring the Proxy Service Upload all the XSL s required Make changes to the XSL s similar to what we did when configuring the Requestor ABCS Follow the steps listed below. 1. Get target system ID

a. Use 'replace' action to replace the node CreateCustomerPartyListEBM in the variable 'body' with the expression, which takes the form of XSL resource, AddTargetSystemID.xsl

Provide the $body as the binding input b. Assign the result of the XPath expression, $body/ebo:

CreateCustomerPartyListEBM/corecom:EBMHeader/corecom:Target/corecom:ID to the variable ‘SystemID’


- 47 -

Note: The name space prefixes used in the expression and the corresponding URI need to be defined.


c. Assign the expression $body/ebo: CreateCustomerPartyListEBM/corecom:EBMHeader to the variable EBM_HEADER

d. Add user defined namespace prefix ebo and with its URI, if required.

3. Add stage XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer e. use 'replace' action to replace the node CreateCustomerPartyListEBM in the variable 'body'

with the expression, which takes the form of xslt resource, XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer

f. Select the XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer.xsl as the


Developing Provider ABC Services to be CAVS Enabled Default design-time Routing to the Provider service from a Provider ABCS

Add Service call out action to invoke the SamplesCreateCustomerPartyPortalProvider service invoking the operation 'CreateCustomerParty'

5. Error Handling g. In the response actions, check for the ‘Fault’ element in the response actions of the route

node h. If ‘Fault’ element is present raise an error with business error code and the business error

message.

6. Transforming the response from provider service back to EBM

• Apply transformation using the XSL, XformPcmOpCustCommitCustomerToCreateCustomerPartyListResponseEBM.xsl.

The transformation copies the ebm header from the request message to the response message 7. Add route node to the pipeline to route the response message to the CustomerPartyResponseEBM.

Creating and Configuring the Response EBS The procedure to create CustomerPartyResponseEBS is similar to developing CustomerPartyEBS. Note: It is assumed that CustomerPartyEBS WSDL has the binding CustomerPartyResponseEBSBinding added to it. When configuring the proxy service, while selecting the CustomerPartyResponseEBS.wsdl, select the binding – CustomerPartyResponseEBSBinding Configuring the CustomerPartyResponseEBS for the Dynamic Routing is as detailed in the section Configure the Routing Node in the Message Flow of EBS


- 48 -

The dynamic XQuery would be as shown in the snippet below.

(:: pragma bea:global-element-parameter parameter="$ CreateCustomerPartyListResponseEBMVar" element="v2:CreateCustomerPartyListEBM" ::) declare namespace ebo = "http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2"; declare namespace corecom = "http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2"; declare namespace xf = "http://tempuri.org/XqueryPrototype/XqueryTransform/EvaluateRR/"; declare function xf:EvaluateRR($CreateCustomerPartyListResponseEBMVar as element(ebo:CreateCustomerPartyListResponseEBM)) as element(*) { if(($CreateCustomerPartyListResponseEBMVar/corecom:EBMHeader/corecom:MessageProcessingInstruction/corecom:EnvironmentCode/text()='PRODUCTION' or not($CreateCustomerPartyListResponseEBMVar/corecom:EBMHeader/corecom:MessageProcessingInstruction/corecom:EnvironmentCode/text())) and ($CreateCustomerPartyListResponseEBMVar/corecom:EBMHeader/corecom:Sender/corecom:WSAddress/wsa:ReplyTo/wsa:ServiceName ='SamplesAsyncCreateCustomerSiebelRespABCSImpl' <dynamicservice> <servicename>SamplesAsyncCreateCustomerSiebelRespABCSImpl/SamplesAsyncCreateCustomerSiebelRespABCSImpl</servicename> <operationname>CreateCustomerResponse</operationname> <servicetype>proxy</servicetype> </dynamicservice> else if($CreateCustomerPartyListResponseEBMVar /corecom:EBMHeader/corecom:MessageProcessingInstruction/corecom:EnvironmentCode/text()='CAVS') then <dynamicservice> <servicename>Simulator/CAVSService</servicename> <operationname></operationname> <servicetype>external</servicetype> </dynamicservice> else <dynamicservice></dynamicservice> }; declare variable $ CreateCustomerPartyListResponseEBMVar as element(ebo: CreateCustomerPartyListResponseEBM) external; xf:EvaluateRR($CreateCustomerPartyListResponseEBMVar)


- 49 -

Chapter 9

Logging messages in OSB Configuring Oracle AIA Processes for Trace Logging The following custom XPath trace logging functions are available to OSB services operating in an Oracle AIA ecosystem. However, the strategy detailed below will require that FP be supported. Hence the interim strategy would be to use logging action. aia:isTraceLoggingEnabled(String logLevel, String processName)

Determines whether trace logging is enabled for the service or at the overall system level.

aia:logTraceMessage(String level, Element ebmHeader, String message)

Generates the actual trace log.

When developing a OSB service, always call the aia:isTraceLoggingEnabled() function first. If it returns a true result, then have the process call the aia:logTraceMessage() function. These log files are stored in the <aia.home>/logs/ directory. In addition to these custom XPath functions, a Java API is also available so that any application developer can use it to log trace messages. Describing Details of the isTraceLoggingEnabled Custom XPath Function The isLoggingEnabled custom XPath function is a utility function that returns a Boolean result. The function signature is as follows: aia : isTraceLoggingEnabled (String logLevel, String processName) . Following are the parameter details: logLevel

Possible values include:

Severe

Warning

Info

Config

Fine

Finer

Finest


- 50 -

processName

Name of the Oracle AIA service using this function.

Describing Details of the logTraceMessage Custom XPath Function The logTraceMessage custom XPath function generates a trace message, which contains the details of the message to be included in the trace log. This function accepts the EBM header and the verbose logging message as parameters. Various elements from the EBM header will be used to populate supplemental attributes to the log message. If the EBM header is not passed, these supplemental attributes are set as empty strings. The function signature is as follows: aia: logTraceMessage (String level, Element ebmHeader, String message). Following are the parameter details: level


Severe

Warning

Info

Config

Fine

Finer

Finest

ebmHeader

EBM header.

message

Verbose text message to be logged.

Describing the Trace Logging Java API In addition to the isTraceLoggingEnabled and logTraceMessage custom XPath functions, a trace Logging Java API is also available so that any application developer can log trace messages. The following functions are available through the trace logging Java API. One of the function signatures is as follows: AIALogger. isTraceLoggingEnabled (String logLevel, String processName) . This function determines whether trace logging is enabled for the service or at the overall system level. Following are the parameter details: logLevel


Severe


- 51 -

Warning

Info

Config

Fine

Finer

Finest

processName

Name of the Oracle AIA service using this function.

Another function signature is as follows: AIALogger. logTraceMessage (String level, Element ebmHeader, String message) . This function generates the actual trace log. Following are the parameter details: level


Severe

Warning

Info

Config

Fine

Finer

Finest

ebmHeader

EBM header.

message

Verbose text message to be logged.


- 52 -

Chapter 10

Error handling in OSB

Configuring Oracle AIA Processes for Error This chapter discusses how to:

• Configure OSB proxy services to adhere to error handling requirements.

• Perform common configurations for OSB proxy services to adhere to error handling requirements.

• Configure OSB proxy services to adhere to trace logging requirements.

• Describe fault message details.

Configuring OSB Services to Adhere to Error Handling Requirements In this section, we provide an overview of OSB error handling and discuss how to implement error handling in OSB for all errors. Understanding OSB Error Handling The Oracle Application Integration Architecture (AIA) Error Handling Framework groups OSB Service errors into two categories:

• Service invocation errors.

• Message flow errors.

In OSB both service invocation and message flow errors are handled in the same way as OSB doesn’t have concept of fault policies to customize error handling at runtime. Whenever a change is required to error handling you need to modify the proxy and re-activate it.

Service invocation errors

A service invocation error can occur in one of two scenarios: The service invocation fails.

The service invocation receives a SOAP fault.

In OSB proxy services, services can be invoked using service callout, publish and route actions. The error handlers behave differently based on which action is used.

Incase of service callout, the error handlers are invoked irrespective of whether it is an invocation failure or the invocation receives a fault.


- 53 -

If route is used to invoke a service, then error handler is not invoked when the invocation receives a SOAP fault. So the implementation should inspect the message in the response actions of the route node to check if it received a SOAP fault and raise a business error. This results in invocation of error handler. Implementing Error Handling To handle all errors in OSB: Main Flow

1. If the service is invoked through route action, inspect the message in response actions and raise a business error with valid code.

2. Configure an error handler at service level

Error Handler flow

1. Add a stage to error handler flow

2. Construct an Oracle AIA fault message for these errors.

3. Throw this fault as a named fault and catch it in a catch block.

4. Invoke the AIAAsyncErrorHandlingBPELProcess with this Oracle AIA fault message as input.

5. If a reply is needed, send this Oracle AIA fault message as the reply.

6. Do a re-throw of the fault that has been caught.

See Also

http://e-docs.bea.com/alsb/docs30/consolehelp/errorcodes.html

Performing Configurations for OSB Services to Adhere to Error Handling Requirements

This section discusses the standard configuration steps that need to be performed when you are handling an OSB error. In this section, we discuss how to:

• Define notification roles.

• Define corrective action codes.

• Define error message codes.

Defining Notification Roles for Each Service

You can define Actor and FYI notification roles for each service in the BSR ERROR NOTIFICATIONS table on the Error Notifications page. See Oracle Application Integration Architecture 2.1 Core Infrastructure Components Guide, "Setting Up Error Notifications and Logging," Setting Up Error Notifications for Oracle AIA Processes


- 54 -

This table contains the following columns of particular interest: SYSTEM_ID

The system ID value is obtained from the EBM header.

ERROR CODE

In the case of OSB, the error code is the fault code.

SERVICE NAME

The service name is the name of the OSB service QName that encountered an error.

PROCESS NAME

The process name value is obtained from the EBM header.

NOTIFICATION ROLE

FYI NOTIFICATION ROLE

The default values for Actor and FYI roles are specified in the AIAConfigurationProperties.xml file located here: <aia.home>/config/.

<Property name="EH.DEFAULT.ACTOR.ROLE">AIAIntegrationAdmin</Property> <Property name="EH.DEFAULT.FYI.ROLE"></Property>

Note. For a given process, if no entry is found in the BSR_ERROR_NOTIFICATIONS table, the default roles specified in AIAConfigurationProperties.xml are used. Therefore, you are not required to populate the BSR_ERROR_NOTIFICATIONS table unless there is an explicit need.

The logic used to determine the appropriate notification roles and corrective action for an error is as follows:

7. If these four input values; SYSTEM_ID, ERROR CODE, SERVICE NAME, and PROCESS NAME; are available and map to a specific entry in the BSR_ERROR_NOTIFICATIONS table, use it.

8. If ERROR_CODE, SERVICE_NAME, and PROCESS_NAME are available and map to an entry in the table, use it.

9. If SERVICE_NAME and PROCESS_NAME are available and map to an entry in the table, use it.

10. If SERVICE_NAME is available and maps to an entry in the table, use it.

11. If none of these values are available, the default values are fetched from the AIAConfigurationProperties .xml file.

Defining Corrective Action Codes For business errors thrown, define corrective action codes and details in the oracle.apps.aia.core.eh.i18n.EHCorrectiveActionRB class. This is a ListResourceBundle and contains the key-value pairs. The following custom XPath function is available to get details from this resource bundle in a localized format:


- 55 -

Signature: aia:getCorrectiveAction (String key, String locale, String delimiter) Parameter details include: Key

The corrective action code.

Locale

This is a concatenated string of language code, country code, and variant. For example, en-US-WIN.

Delimiter

The delimiter used in Locale parameter, such as -.

Defining Error Message Codes For business errors thrown, define error message codes and details in the oracle.apps.aia.core.eh.i18n.EHResourceBundle class. This is a ListResourceBundle and contains the key-value pairs. The following custom XPath function is available to get details from this resource bundle in a localized format: Signature: aia:getErrorMessage (String key, String locale, String delimiter).

Parameter details include: Key

The corrective action code.

Locale

This is a concatenated string of language code, country code, and variant. For example, en-US-WIN.

Delimiter

The delimiter used in Locale parameter


- 56 -

Chapter 11

OSB Service Configuration Category Sub-Category Parameter Recommended

Value Comment

Proxy Service Transport

Configuration

Get All Headers

yes Some PIP require access to headers such as : status

HTTP Transport Configuration

HTTPS required no This is used for SSL

Authentication no Used for security, but we will use OWSM gateway

Dispatch Policy blank by default Used for controlling number of threads for this proxy compared to other proxies

Request Encoding Blank by default Used for content encoding like UTF-8

Response Encoding

Blank by default

Authentication Header

no Used for security, but we will use OWSM gateway

Authentication Token Type

no Used for security, but we will use OWSM gateway

JMS Transport Configuration

Destination Type Queue Is Response

Required Leave as Un-Checked for Asynchronous request-only MEP

this will be the default. We might select this option for certain patterns

Response Correlation Pattern

It will be used only in exceptional cases


- 57 -

Response URI It will be used only in exceptional cases

Response

Connection Factory


Response Message Type


Request Encoding Use default settings, UTF-8

Response Encoding

Client Response Timeout

Dispatch Policy Is XA Required Select as Checked Operation

Selection Configuration

Enforce WS-I Compliance

Leave as Un-Checked

Not required when service type is Web Service

Selection Algorithm

SOAPAction Header

Specifies that operation mapping be done automatically from the WSDL associated with this proxy service.

Message Content Handling

Content Streaming Leave as Un-Checked

When enabled, cannot use certain actions – replace, insert etc; we might use this option in exceptional cases

XOP/MTOM We will use this only in specific use cases

Support Attachments

Business Service Transport


- 58 -

Configuration protocol Load balancing

algorithm

Endpoint URI Retry count Retry interval Retry application

errors

HTTP Transport Configuration

HTTP request method

post This is used for SSL

Authentication no Used for security, but we will use OWSM gateway

Dispatch Policy blank by default Used for controlling number of threads for this service

Request Encoding Blank by default Used for content encoding like UTF-8

Response Encoding

Blank by default


- 59 -

Appendix

Uploading AIA Components as a Zipped file In the sample, AIA Components are initially uploaded into OSB ‘projects’ folder as a .zip file. The following steps illustrate the process of uploading AIA Components as a zip file, using OSB console. (It is a pre-requisite that the AIA component lib is made available as .zip file)

1. Select a project folder where we would like to import AIA components. 2. From the Create Resources drop-down list, select Zipped Resources

3. Browse file system and select the zip file


- 60 -

4. On Review Loaded Resources page, click on Import

Resolving the schema references in the WSDL In the ESL, WSDLs import the type definitions from separate XML schema files. When WSDLs are uploaded into OSB, the OSB cannot find the referenced schema files automatically. (OSB presents a ‘conflict’ message ‘One of the WSDL dependencies is invalid’). Users have to manually resolve these references using the ‘Edit References’ screen on the OSB console, browsing for the schemas and matching them to the schemas expected by the WSDL.

The procedure to resolve the conflict is illustrated below.

1. Select the WSDL file from the Project/Resources explorer 2. OSB presents a ‘conflict’ message ‘One of the WSDL dependencies is invalid’. Click on Edit

References to resolve the conflict manually


- 61 -

3. For each resource type, WSDL (if any) and XSD (if any), click on the Browse and select an appropriate resource from the list presented

4. Select the appropriate schema file from the browser list as shown below


- 62 -

5. Save the WSDL after resolving all the conflicts

Updating the WSDL from ESL for creating OSB Service The WSDL files in the ESL are abstract. However, OSB requires that they also describe how to invoke the service. Hence WSDL files need to be updated by providing with details of bindings before it can be used for creating OSB artifacts – business service/proxy service.

Updating WSDL Add the following details to the CustomerPartyEBS.wsdl. Note that as a sample, only one operation element, QueryCustomerParty, is added in this example. If an EBS provides more than one operation, then it is necessary to include one operation element corresponding to each EBS operation. <binding name="CustomerPartyEBSBinding" type="corecustomerpartyebs:CustomerPartyEBS"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> <operation name="QueryCustomerParty"> <soap:operation style="document" soapAction="SamplesQueryCustomerParty"/> <input> <soap:body use="literal"/> </input> <output> <soap:body use="literal"/> </output> </operation>

Note: OSB can only create services from WSDLs that have binding or port. We recommend that bindings be added to the ESL. AIA recommends SOAP as the binding to be used.


- 63 -

</binding> The sample text of the CustomerPartyEBS.wsdl with the changes highlighted is shown below. <definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:svcdoc="http://xmlns.oracle.com/Services/Documentation/V1" xmlns:corecom="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2" xmlns:customerpartyebo="http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2" xmlns:corecustomerpartyebs="http://xmlns.oracle.com/EnterpriseServices/Core/CustomerParty/V2" name="CustomerPartyEBS" targetNamespace="http://xmlns.oracle.com/EnterpriseServices/Core/CustomerParty/V2"> <documentation> <svcdoc:Service> <svcdoc:Description>Customer Party Enterprise Business Service</svcdoc:Description> <svcdoc:ServiceType>Enterprise Business Service</svcdoc:ServiceType> <svcdoc:DisplayName>CustomerPartyEBS</svcdoc:DisplayName> <svcdoc:Version>2.0</svcdoc:Version> <svcdoc:EBOName>CustomerPartyEBO</svcdoc:EBOName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> <svcdoc:ImplementationTechnology>ESB</svcdoc:ImplementationTechnology> </svcdoc:Service> </documentation> <types> <xsd:schema targetNamespace="http://xmlns.oracle.com/EnterpriseServices/CustomerParty/V2" elementFormDefault="qualified"> <xsd:import namespace="http://xmlns.oracle.com/EnterpriseObjects/Core/EBO/CustomerParty/V2" schemaLocation="http://localhost:7001/AIAComponents/EnterpriseObjectLibrary/Core/EBO/CustomerParty/V2/CustomerPartyEBM.xsd"/> <xsd:import namespace="http://xmlns.oracle.com/EnterpriseObjects/Core/Common/V2" schemaLocation="http://localhost:7001/AIAComponents/EnterpriseObjectLibrary/Core/Common/V2/Meta.xsd"/> </xsd:schema> </types> <message name="FaultMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used for propagating Error Context and Error Message</svcdoc:Description> </svcdoc:Message> </documentation> <part name="AIAFault" element="corecom:Fault"/> </message> <message name="QueryCustomerPartyReqMsg"> <documentation> <svcdoc:Message>


- 64 -

<svcdoc:Description>This message is used as the request payload to the QueryCustomerParty operation</svcdoc:Description> </svcdoc:Message> </documentation> <part name="QueryCustomerPartyEBM" element="customerpartyebo:QueryCustomerPartyEBM"/> </message> <message name="QueryCustomerPartyRespMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used as the response payload to the QueryCustomerParty operation</svcdoc:Description> </svcdoc:Message> </documentation> <part name="QueryCustomerPartyResponseEBM" element="customerpartyebo:QueryCustomerPartyResponseEBM"/> </message> <message name="QueryCustomerPartyListReqMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used as the request payload to the QueryCustomerPartyList operation</svcdoc:Description> </svcdoc:Message> </documentation> <part name="QueryCustomerPartyListEBM" element="customerpartyebo:QueryCustomerPartyListEBM"/> </message> <message name="QueryCustomerPartyListRespMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used as the response payload to the QueryCustomerPartyList operation</svcdoc:Description> </svcdoc:Message> </documentation> <part name="QueryCustomerPartyListResponseEBM" element="customerpartyebo:QueryCustomerPartyListResponseEBM"/> </message> <message name="CreateCustomerPartyReqMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used as the request payload to the CreateCustomerParty operation</svcdoc:Description> </svcdoc:Message> </documentation> <part name="CreateCustomerPartyEBM" element="customerpartyebo:CreateCustomerPartyEBM"/> </message> <message name="CreateCustomerPartyRespMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used as the response payload to the CreateCustomerParty operation</svcdoc:Description> </svcdoc:Message> </documentation>


- 65 -

<part name="CreateCustomerPartyResponseEBM" element="customerpartyebo:CreateCustomerPartyResponseEBM"/> </message> <message name="CreateCustomerPartyListReqMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used as the request payload to the CreateCustomerPartyList operation</svcdoc:Description> </svcdoc:Message> </documentation> <part name="CreateCustomerPartyListEBM" element="customerpartyebo:CreateCustomerPartyListEBM"/> </message> <message name="CreateCustomerPartyListRespMsg"> <documentation> <svcdoc:Message> <svcdoc:Description>This message is used as the response payload to the CreateCustomerPartyList operation</svcdoc:Description> </svcdoc:Message> </documentation> <part name="CreateCustomerPartyListResponseEBM" element="customerpartyebo:CreateCustomerPartyListResponseEBM"/> </message> <portType name="CustomerPartyEBS"> <documentation> <svcdoc:Interface> <svcdoc:Description>This interface contains operations for the Request-Response and Request-Only patterns</svcdoc:Description> <svcdoc:DisplayName>RequestCustomerParty EBS Interface</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> </svcdoc:Interface> </documentation>  <operation name="CreateCustomerParty"> <documentation> <svcdoc:Operation> <svcdoc:Description>This operation is used to create a CustomerParty EBO.</svcdoc:Description> <svcdoc:MEP>REQUEST_ONLY</svcdoc:MEP> <svcdoc:DisplayName>CreateCustomerParty</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> <svcdoc:Scope>Public</svcdoc:Scope> </svcdoc:Operation> </documentation> <input message="corecustomerpartyebs:CreateCustomerPartyReqMsg"/> </operation> <operation name="CreateCustomerPartyList"> <documentation> <svcdoc:Operation>


- 66 -

<svcdoc:Description>This operation is used to create a multiple CustomerParty EBOs</svcdoc:Description> <svcdoc:MEP>REQUEST_ONLY</svcdoc:MEP> <svcdoc:DisplayName>CreateCustomerPartyList</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> <svcdoc:Scope>Public</svcdoc:Scope> </svcdoc:Operation> </documentation> <input message="corecustomerpartyebs:CreateCustomerPartyListReqMsg"/> </operation>  <operation name="QueryCustomerParty"> <documentation> <svcdoc:Operation> <svcdoc:Description>This operation is used to query a CustomerParty EBO</svcdoc:Description> <svcdoc:MEP>SYNC_REQ_RESPONSE</svcdoc:MEP> <svcdoc:DisplayName>QueryCustomerParty</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> <svcdoc:Scope>Public</svcdoc:Scope> </svcdoc:Operation> </documentation> <input message="corecustomerpartyebs:QueryCustomerPartyReqMsg"/> <output message="corecustomerpartyebs:QueryCustomerPartyRespMsg"/> <fault name="fault" message="corecustomerpartyebs:FaultMsg"/> </operation> <operation name="QueryCustomerPartyList"> <documentation> <svcdoc:Operation> <svcdoc:Description>This operation is used to query multiple CustomerParty EBOs</svcdoc:Description> <svcdoc:MEP>SYNC_REQ_RESPONSE</svcdoc:MEP> <svcdoc:DisplayName>QueryCustomerPartyList</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> <svcdoc:Scope>Public</svcdoc:Scope> </svcdoc:Operation> </documentation> <input message="corecustomerpartyebs:QueryCustomerPartyListReqMsg"/> <output message="corecustomerpartyebs:QueryCustomerPartyListRespMsg"/> <fault name="fault" message="corecustomerpartyebs:FaultMsg"/> </operation> </portType> <portType name="CustomerPartyEBSResponse"> <documentation> <svcdoc:Interface> <svcdoc:Description>This interface contains operations for the ResponseCustomerParty EBS</svcdoc:Description>


- 67 -

<svcdoc:DisplayName>ResponseCustomerParty EBS Interface</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> </svcdoc:Interface> </documentation>  <operation name="CreateCustomerPartyResponse"> <documentation> <svcdoc:Operation> <svcdoc:Description>This callback operation will be used to provide the Create Customer Party Response</svcdoc:Description> <svcdoc:MEP>ASYNC_REQ_RESPONSE</svcdoc:MEP> <svcdoc:DisplayName>CreateCustomerPartyResponse</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> <svcdoc:Scope>Public</svcdoc:Scope> <svcdoc:InitiatorService>CustomerPartyEBS</svcdoc:InitiatorService> <svcdoc:InitiatorInterface>CreateCustomerPartyResponseEBM</svcdoc:InitiatorInterface> <svcdoc:InitiatorOperation>CreateCustomerPartyRequest</svcdoc:InitiatorOperation> </svcdoc:Operation> </documentation> <input message="corecustomerpartyebs:CreateCustomerPartyRespMsg"/> </operation> <operation name="CreateCustomerPartyListResponse"> <documentation> <svcdoc:Operation> <svcdoc:Description>This callback operation will be used to provide the Create Customer Party Response</svcdoc:Description> <svcdoc:MEP>ASYNC_REQ_RESPONSE</svcdoc:MEP> <svcdoc:DisplayName>CreateCustomerPartyListResponse</svcdoc:DisplayName> <svcdoc:LifecycleStatus>Active</svcdoc:LifecycleStatus> <svcdoc:Scope>Public</svcdoc:Scope> <svcdoc:InitiatorService>CustomerPartyEBS</svcdoc:InitiatorService> <svcdoc:InitiatorInterface>CreateCustomerPartyResponseEBM</svcdoc:InitiatorInterface> <svcdoc:InitiatorOperation>CreateCustomerPartyListRequest</svcdoc:InitiatorOperation> </svcdoc:Operation> </documentation> <input message="corecustomerpartyebs:CreateCustomerPartyListRespMsg"/> </operation>  </portType>


- 68 -

<binding name="CustomerPartyEBSBinding" type="corecustomerpartyebs:CustomerPartyEBS"> <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" /> <operation name="QueryCustomerParty"> <soap:operation style="document" soapAction="SamplesQueryCustomerParty" /> <input> <soap:body use="literal" /> </input> <output> <soap:body use="literal" /> </output> </operation> </binding> </definitions>

Creating SB Configuration JAR file for AIA Components To create a JAR file for AIA Components, as described in the above sections, a. Upload the AIAComponents.zip file, resolve the conflicts and update the WSDL with the

information for binding b. Save all the changes by selecting ‘Activate’ in the change center c. Click on ‘System Administration’ and select ‘Export Resources’. Select Checkbox ‘Include

Dependencies’ d. From the Resource Summary, Select the resource folder having AIA Components and click on

‘Export’ button. Save as AIAComponents.JAR file

Constructing a OSB Business Service Construction of a business service in OSB is similar to constructing a proxy service. The high level details are presented below. For more details, please refer to the section that describes developing a proxy service. 1. Create a Project folder 2. Upload the XSL referenced and the WSDL of the service for which a business service in OSB is

being developed. This is true if the business service is being developed for a web service. Make sure that WSDL contains binding information in it and has all the conflicts resolved.

3. In the ‘Transport Configuration’ page of the console, a. Select the ‘protocol’ as http for the service type that is being created.

b. Enter the end-point URI format based on the transport protocol that is selected for the field ‘protocol’ in the above step.

4. For the rest of the configuration, please refer to OSB Service Configuration

Creating JMS resources

To create the JMS assets, using the WebLogic console, it is necessary to


- 69 -

• create a new JMS server • create JMS module for newly created JMS server • add resources- JMS connection factory and queues, to the newly created JMS system module

Creating new JMS Server

1. In the WebLogic console, navigate to Services ->Messaging -> JMS Servers. Click the ‘New’

button to create a new JMS server 2. Name the service, (AIAJMSServer) and set the persistent store to None. 3. To target the server. Select ‘AdminServer’ from the drop down list and click the Finish button.

At this point, your JMS server has been created.

Creating a JMS module for the JMS server

JMS connection factories and destinations are categorized as JMS Module Resources in WLS. So, JMS modules for newly created JMS server need to be created. 1. In the WLS console, Navigate to the Services ->Messaging -> JMS Modules section. Click the

New button to create a new JMS module. 2. In the Create JMS System Module window, set the name as AIAJMSResources. Click the Next

button to continue. 3. Target the AdminServer and click the Next button. In the next window, Check the checkbox and

to add resources to the JMS system module and click the Finish button.

Adding resources to the JMS system module

1. In the page, summary of resources for the AIAJMSResources, Click the New button and in the next window, Select the Connection Factory radio button, for the type of resource to create, and click the Next button.

2. Name the connection factory as AIAConnectionFactory and set the JNDI Name to the same. 3. In the next page, Select the AdminServer as the target for the connection factory and click the

Finish button. 4. To create JMS Queue, in the Summary of Resources page, click the New button and select the

Queue radio button. 5. In the next page, JMS Destination Properties, set the name to AIASamplesQueue and set the

JNDI Name to the same value. 6. On the next page, Create a New Subdeployment with the name AIASamplesQueue 7. In the final step, set the AIAJMSServer as the target JMS Server.

Parameters for Guaranteed delivery

The property QoS represents Quality of Service, and can be either EXACTLY_ONCE or BEST_EFFORT. When there’s a transaction associated with the incoming message, you should use EXACTLY_ONCE. OSB will use this value to set the QoS element in the message context variable $inbound, which is available in the pipeline, and controls the default quality of service used for outbound calls.


- 70 -

White Paper Title February 2009 Author: AIA Architecture Team Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: Phone: +1.650.506.7000 Fax: +1.650.506.7200 oracle.com

Copyright © 2009, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without our prior written permission.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

0109

Documents

Guide to Implementing Application Integration Architecture on … · Oracle White Paper—Guide to Implementing Application Integration Architecture on Oracle Service Bus - 2 - Disclaimer