Guide to Implementing Application Integration Architecture - Oracle

An Oracle White Paper

March 2011

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

Table of Contents ........................................................................................................ 3

Preface ........................................................................................................................ 8

Goal of this Document ............................................................................................................ 8

Pre-requisites .......................................................................................................................... 8

Oracle OSB and Oracle AIA Documentation .......................................................................... 8

Additional Resources .............................................................................................................. 9

Part I: Designing AIA Services Using OSB. .............................................................. 10

Chapter 1: Introducing OSB and AIA ......................................................................... 11

Oracle Service Bus (OSB) .................................................................................................... 11

Applications Integration Architecture (AIA) ........................................................................... 12

AIA Service Artifacts ......................................................................................................... 13

Enterprise Business Services (EBS) ............................................................................ 14

Enterprise Business Flow (EBF) .................................................................................. 15

Application Business Connector Services (ABCS) ...................................................... 17

Chapter 2: Designing SOA Integrations Leveraging OSB and AIA ............................ 19

Building End-to-End Integration Flows ................................................................................. 19

Synchronous Request-Response ..................................................................................... 20

Use Case...................................................................................................................... 20

Points to Consider ........................................................................................................ 20

Implementing a Synchronous Request-Response Pattern Using OSB ....................... 21

Fire-and-Forget ................................................................................................................. 21

Use Case...................................................................................................................... 21

Points to Consider ........................................................................................................ 22

Implementing a Fire-and-Forget Pattern Using OSB ................................................... 22

Chapter 3: Extending a PIP ....................................................................................... 23

Introduction ........................................................................................................................... 23

Building a New Connector Service ....................................................................................... 23

Extending ABCS ................................................................................................................... 24

Chapter 4: Common Services Platform ..................................................................... 25

Virtualizing AIA Shared Services .......................................................................................... 25

Chapter 5: Gateway for Accessing Existing Systems ................................................ 28

Introduction ........................................................................................................................... 28


- 4 -

Accessing Services on Applications ..................................................................................... 28

Accessing Services on EAI Infrastructure ............................................................................. 29

Part II: Building AIA Services Using OSB .................................................................. 31

Chapter 6: Building AIA Artifacts using OSB – Preparatory Steps ............................. 32

Getting AIA Components from FP Install .............................................................................. 32

Registering AIA Components with OSB ............................................................................... 32

Registering AIA Components as a jar File ....................................................................... 33

Working with AIA Configuration File ..................................................................................... 33

Chapter 7: Designing and Developing Enterprise Business Services ........................ 35

Introduction ........................................................................................................................... 35

Developing EBS as an OSB Service .................................................................................... 35

Consuming Enterprise Business Services ....................................................................... 36

ABCS Invoking a Co-located EBS ............................................................................... 36

Inter-Communication between Enterprise Business Services ..................................... 36

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

ABCS Invoking a Remotely Located EBS .................................................................... 37

Creating EBS as OSB Proxy Service using WSDL ..................................................... 38

Message Routing .............................................................................................................. 39

Configure the Route Node in the Message Flow of EBS ............................................. 39

Modeling Route Node in conjunction with Operational Branch .................................... 41

Error Handling................................................................................................................... 42

Logging ............................................................................................................................. 42

Chapter 8: Designing and Developing Application Business Connector Services ...... 43

Introduction to Application Business Connector Services .................................................... 43

Designing ABCS ................................................................................................................... 44

Key Tasks ......................................................................................................................... 44

Defining the ABCS Contract ............................................................................................. 45

Defining the Role of the ABCS ......................................................................................... 45

Designing an ABCS to Participate in a Requester Role .............................................. 46

Designing an ABCS to Participate in a Provider Role ................................................. 46

Developing ABCS ................................................................................................................. 47

Message Validation ...................................................................................................... 48

Message Transformation ............................................................................................. 48

Message Enrichment ................................................................................................... 50

Inbound Service Interaction ......................................................................................... 50

Outbound Service Interaction ...................................................................................... 51


- 5 -

Configuring Service Callout Action ................................................................................... 52

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

Computing Dynamic Endpoint Location in ABCS ........................................................ 53

CAVS Enabling ............................................................................................................ 54

Logging ............................................................................................................................. 54

Error Handling in ABCS .................................................................................................... 54

Chapter 9: Extending ABCS ...................................................................................... 55

Developing Extensible ABCS ................................................................................................ 55

Developing an ABCS Extensibility Service ........................................................................... 56

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

Chapter 10: Asynchronous Invocation of ABCS ........................................................ 59

Introduction ........................................................................................................................... 59

JMS Consumer Adapter ........................................................................................................ 60

JMS Producer Adapter .......................................................................................................... 60

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

Chapter 11: Using Adapters with AIA on OSB ........................................................... 62

Introduction ........................................................................................................................... 62

Using Adapters on OSB ........................................................................................................ 62

Chapter 12: Interoperating with SCA-based AIA Services ......................................... 64

Introduction ........................................................................................................................... 64

Calling SCA Service from OSB ............................................................................................. 64

Transport Configuration .................................................................................................... 66

Calling OSB Proxy Service from aSOA Composite.......................................................... 67


Chapter 13: Securing AIA OSB Services ................................................................... 70

Using OWSM Policies to Secure AIA Services ..................................................................... 70

Chapter 14: Implementing Synchronous Request-Response MEP ............................ 72

Introduction ........................................................................................................................... 72

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


Message Routing In EBS ............................................................................................. 74

Error Handling in EBS ...................................................................................................... 76

Developing Requester ABCS ........................................................................................... 76

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

Error Handling in Requester ABCS .................................................................................. 80

Developing Provider ABCS .............................................................................................. 80


- 6 -

Configuring the Proxy Service...................................................................................... 80

Using AIA XPath Functions .......................................................................................... 82

Chapter 15: Implementing the Fire-and-Forget MEP ................................................. 85

Introduction ........................................................................................................................... 85

Developing One-Way Requester ABCS ............................................................................... 86


Error handling in Requester ABCS ................................................................................... 88

Developing Provider ABCS ................................................................................................... 88

Configuring the Proxy Service .......................................................................................... 88

Developing JMS Consumer Adapter ................................................................................ 90

Chapter 16: Implementing Asynchronous Request –Delayed Response MEP .......... 91

Introduction ........................................................................................................................... 91

Developing One-Way Requester ABCS ............................................................................... 92


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

Error handling in Requester ABCS ................................................................................... 94

Developing Provider ABCS ................................................................................................... 95

Configuring the Proxy Service .......................................................................................... 95

Creating and Configuring the Response EBS .................................................................. 96

Chapter 17: Logging Messages in OSB ..................................................................... 98

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

isTraceLoggingEnabled Custom XPath Function............................................................. 98

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

Describing the Trace Logging Java API ........................................................................... 99

Chapter 18: Error Handling in OSB ......................................................................... 101

Configuring Oracle AIA Processes for Error Handling ........................................................ 101

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

Understanding OSB Error Handling ............................................................................... 101

Service Invocation Errors ........................................................................................... 101

Implementing Error Handling ..................................................................................... 102

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

Defining Notification Roles for Each Service .................................................................. 103

Defining Corrective Action Codes .................................................................................. 104

Defining Error Message Codes ...................................................................................... 104

Chapter 19: OSB Service Configuration .................................................................. 106

Appendix ................................................................................................................. 109


- 7 -

Uploading AIA Components as a Zipped File ..................................................................... 109

Updating the WSDL from Enterprise Services Library for Creating OSB Service .............. 110

Updating WSDL .............................................................................................................. 111

Creating SB Configuration Jar File for AIA Components ............................................... 111

Constructing a OSB Business Service ........................................................................... 111

Creating JMS Resources ................................................................................................ 112

How to Create a New JMS Server ............................................................................. 112

How to Create a JMS Module for the JMS Server ..................................................... 112

How to Add Resources to the JMS System Module .................................................. 112

Parameters for Guaranteed delivery .......................................................................... 113


- 8 -

Preface

Oracle Service Bus (OSB), formerly known as Aqualogic Service Bus is a lightweight Enterprise Service Bus 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 a configuration-based approach for developing SOA assets and deploying SOA services. It delivers 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-invocations.

Goal of this Document

This document describes how to implement end-to-end flows as well as service layers using AIA based design patterns leveraging OSB technology. It defines programming models for developing Enterprise Business Service (EBS), Application Business Connector services, and Message exchange patterns. In addition, this document discusses the various use cases that warrant the use of OSB with respect to AIA

Pre-requisites

The reader is expected to have a good understanding of OSB as well as AIA architectural principles.

For detailed information about AIA principles, see Oracle Fusion Middleware Concepts and Technologies Guide for Oracle Application Integration Architecture Foundation Pack.

For more information about OSB, see Oracle Fusion Middleware Concepts and Architecture for Oracle Service Bus.

Oracle OSB and Oracle AIA Documentation

Oracle OSB provides the following guides for the latest release:

Oracle Fusion Middleware Concepts and Architecture for Oracle Service Bus

Oracle Fusion Middleware Developers Guide for Oracle Service Bus

Oracle Fusion Middleware Administrators Guide for Oracle Service Bus

Oracle Fusion Middleware Deployment Guide for Oracle Service Bus

Oracle Application Integration Architecture (AIA) provides the following guides and resources for the latest release:

Oracle Fusion Middleware Product-to-Guide Index for Oracle Application Integration

Architecture Foundation Pack

Oracle Fusion Middleware Installation and Upgrade Guide for Oracle Application Integration

Architecture Foundation Pack


- 9 -

Oracle Fusion Middleware Migration Guide for Oracle Application Integration Architecture

Foundation Pack

Oracle Fusion Middleware Concepts and Technologies Guide for Oracle Application

Integration Architecture Foundation Pack

Oracle Fusion Middleware Developer’s Guide for Oracle Application Integration Architecture

Foundation Pack

Oracle Fusion Middleware Infrastructure Components and Utilities Users Guide for Oracle

Application Integration Architecture Foundation Pack

Oracle Fusion Middleware Enterprise Business Object Designer Users Guide for Oracle


Oracle Fusion Middleware Reference Process Models Users Guide for Oracle Application

Integration Architecture Foundation Pack

Additional Resources

The following resources are also available:

Resource Location

Oracle Application Integration Architecture: Product-to-

Guide Index

My Oracle Support: https://support.oracle.com/

Known Issues and Workarounds My Oracle Support: https://support.oracle.com/

Release Notes Oracle Technology Network:

http://www.oracle.com/technology/

Documentation updates My Oracle Support: https://support.oracle.com/

https://support.oracle.com/


http://www.oracle.com/technology/



- 10 -

Part I: Designing AIA Services Using OSB.


- 11 -

Chapter 1: Introducing OSB and AIA

This chapter includes the following sections:

Oracle Service Bus (OSB)

Applications Integration Architecture (AIA)

Oracle Service Bus (OSB)

Oracle Service Bus is a proven market-leading Enterprise Service Bus (ESB) built from the ground up for SOA lifecycle management that provides foundation capabilities for service discovery and intermediation, rapid service provisioning and deployment, and governance. This service-infrastructure software adheres to the SOA principles of building coarse-grained, loosely coupled, and standards-based services, creating a "neutral container" in which business functions may connect service consumers and back-end business services, regardless of underlying infrastructure. The following figure illustrates the role of Oracle Service Bus as a service intermediary in an enterprise IT SOA landscape:

Built to meet exacting standards for reliability, availability, scalability, and performance, Oracle Service Bus uniquely combines the integration capabilities of an Enterprise Service Bus with operational service management, into a single enterprise-class software product, with a layered functional architecture.

Oracle Service Bus provides message delivery services, based on standards including SOAP, HTTP and Java Messaging Service (JMS). It is typically designed for high-throughput, guaranteed message delivery to a variety of service producers and consumers. It supports XML as a native data format, while offering alternatives for handling other data formats.


- 12 -

Oracle Service Bus is policy driven and enables you to establish loose coupling between service clients and business services, while maintaining a centralized point of security control and monitoring. It stores persistent policy, proxy service, and related resource configurations in metadata, that can be customized and propagated from development through staging to production environments required. The message-brokering engine accesses this configuration information from its metadata cache.

Oracle Service Bus is an intermediary that processes incoming service request messages, determines routing logic, and transforms these messages for compatibility with other service consumers. It receives messages through a transport protocol such as HTTP(S), JMS, File, and FTP, and sends messages through the same or a different transport protocol. Service response messages follow the inverse path. The message processing by Oracle Service Bus is driven by metadata, specified in the message flow definition of a proxy service.

For more information about OSB architecture, refer to Oracle Fusion Middleware Concepts and Architecture for Oracle Service Bus.

Applications Integration Architecture (AIA)

Oracle Application Integration Architecture (AIA) is an integration solution for orchestrating agile, user-centric business processes across enterprise applications. Oracle AIA offers pre-built solutions at the data, process and user interface levels delivering a complete process solution to business end users. All the AIA components are designed to work together in a mix and match fashion. They are built for configurability, ultimately lowering the IT cost and burden of building, extending and maintaining integrations.

Powered by Oracle Fusion Middleware, Oracles Application Integration Architecture enables organizations to utilize the applications of their choice and create composite business processes following guiding principles that define the ground rules for development, maintenance, and usage of the Service Oriented Architecture:

Reuse, granularity, modularity, compose ability, componentization and interoperability

Standards compliance (both common and industry-specific)

Services identification and categorization, provisioning and delivery, and monitoring and

tracking

The following diagram provides a high-level overview of the functional architecture of AIA. It depicts how a customer’s IT portfolio is implemented in the form of layered services which helps to break out the limitations of monolithic applications and shorten the development, test, and release cycles.


- 13 -

AIA Service Artifacts

Service layering addresses the separation of concerns thereby increasing the reusability as well as service composition resulted in the creation of various AIA artifacts; the following sections give an overview of the artifacts.

For more information about AIA Service Artifacts, see Oracle Fusion Middleware Concepts and Technologies Guide for Oracle Application Integration Architecture Foundation Pack.

The following diagram gives you a high-level overview of the artifacts and the relevant technologies that can be used to implement them. The subsequent sections provide details on each of the artifacts.


- 14 -

Enterprise Business Services (EBS)

Enterprise Business Services are first-class objects exposed on the enterprise service bus. EBS are coarse-grained and perform a specific business activity or a business task and are of type Activity Service or Data Service. For example, the activity performed could be one of the following:

Creating an account in a billing system.

Checking for the presence of an account in a billing system.

Getting the balance details for an account from a billing system.

The EBS is agnostic of a specific backend implementation. Any backend implementations that can support the interface standards defined by an EBS can be automatically considered as service providers. These services expose coarse-grained, message-driven interfaces for the purpose of exchanging data between applications, both synchronously and asynchronously.

The salient features of the EBS are:

Ability to reuse the available assets in the Oracle portfolio.

Ability to substitute a service provider with another without any impact to the client.

The following figure shows how an EBS enables the loose-coupling of requesters with actual service providers.


- 15 -

Oracle Service Bus as well as Oracle Mediator technologies can be used to implement EBS.

Note that Oracle Service Bus does not have the same capabilities as that of Oracle Mediator with

respect to processing of messages in an ordered manner even if they arrive in an unordered

manner.

In situations where the ordered processing of messages does matter, refer to Oracle Fusion

Middleware Developers Guide for Oracle SOA Suite and Oracle Fusion Middleware Developers

Guide for Oracle Service Bus for information about choosing the right technology.

To build Enterprise Business Services using OSB, refer to the chapters in Part II: Building AIA Services Using OSB.

For complete details about developing EBS using Oracle Mediator, see Oracle Fusion Middleware Developers Guide for Oracle Application Integration Architecture Foundation Pack.

Enterprise Business Flow (EBF)

The Enterprise Business Flow is used to implement a business activity or a task that involves leveraging capabilities available in multiple applications. The EBF strings together a set of capabilities available in applications to implement a coarse-grained business activity or task and composing a new service leveraging existing capabilities.

In AIA, the high-level over arching business processes can be implemented, managed and monitored as a single SOA composite using SOA BPMN / BPEL technologies along with SOA Mediator, SOA Human Workflow, and SOA Business Rules components. The BPMN / BPEL components are the orchestrators of the flow.


- 16 -

In a canonical integration, the EBF is an implementation of an enterprise business service (EBS) operation and calls other EBS. It will never call an application business connector service (ABCS) or the applications directly. In other integration styles, the caller invoking the EBF can either be an application or any other service. EBF can be implemented using BPM / BPEL technologies.

The following diagram illustrates how various types of activities are strung together to implement a Business Process Service.

The following diagram illustrates a business process calling multiple activities. This diagram shows a business process implemented to leverage existing capabilities exposed as Enterprise Business Service operations.


- 17 -

Application Business Connector Services (ABCS)

Application Business Connector Services implement the EBS interface by exposing the business functions provided by the participating application.

The ABCS is responsible for the coordination of the various steps that are provided by a number of business functions exposed by a provider application:

Validation

Transformations – message translation, content enrichment, and normalisations

Invocation of application functions

Error handling and message generation

Security

The following diagram gives a high-level overview of the roles played by ABCS in an end to end flow.

BPEL, as well as OSB technologies, can be used to build ABCS. If the ABCS needs to manage the state in the integration layer or to implement an asynchronous request-response message exchange pattern, then you should leverage BPEL technologies.


- 18 -

To build ABCS using OSB, refer to the chapters in Part II: Building AIA Services Using OSB.

To build ABCS using BPEL, refer to Oracle Fusion Middleware Developers Guide for Oracle Application Integration Architecture Foundation Pack.

The remaining chapters in Part I discuss the various AIA related use cases that warrant the use of OSB.


- 19 -

Chapter 2: Designing SOA Integrations Leveraging OSB and AIA

This chapter discusses use cases that warrant the leveraging of OSB and AIA technologies.

This chapter includes the following section:

Building End-to-End Integration Flows

Building End-to-End Integration Flows

There are certain end-to-end flows where OSB can be used as implementation technology for building all the artifacts leveraging AIA methodology. These flows need to exhibit the following characteristics:

Completely stateless - there is absolutely no need to persist any state in the integration layer

Short-lived processes

Synchronous responses from downstream services or applications in case of flows involving

federated queries

No inter-dependencies between messages

Note that AIA Foundation Pack does not provide native support listed below for the AIA artifacts built using OSB:

Life cycle management of OSB services

AIA Custom xpath functions

Instance level monitoring

AIA Xref and DVM functions

The following sections describe the common end-to-end flow related use cases that can be implemented leveraging the OSB technology based on AIA methodology and points to consider for those implementations:

Synchronous Request-Response

Fire-and-Forget


- 20 -

Synchronous Request-Response

Many use cases warrant consumers to send requests synchronously to service providers and get immediate responses to each of their requests. These use cases need the consumers to wait until the responses are received before proceeding to their next tasks.

Use Case

For example, Customer Relationship Management (CRM) applications may provide features such as allowing customer service representatives to send requests to providers for performing tasks such as account balance retrieval, credit check, ATP (advanced time to promise) calculation, and so on. Since CRM applications expect the responses to be used in the subsequent tasks, this precludes the users from performing other tasks until the responses are received.

Points to Consider

AIA recommends using the synchronous request-response service interface for all the composites involved in processing or connecting the back-end systems. There should not be any singleton service in the services involved in the query processing.

The general recommendation is for all of the intermediary services and the service exposed by the provider application to implement a request-response based interface - a two-way operation. Even though it is technically possible to design all services but the initial caller to implement two one-way requests, this implementation technique should be avoided if possible.


- 21 -

Implementation should strive to ensure that no persistence of state information (dehydration) or audit details is done by any of the intermediary services or by the ultimate service provider. These techniques help keep the latency as low as possible.

AIA also recommends that the intermediary services are co-located to eliminate the overheads normally caused by marshalling and un-marshalling of SOAP documents.

In the case of a (non-transactional) synchronous-request-response MEP, the requester ABCS, by default, is a proxy service using HTTP transport and the applications access Requester ABCS as a web service.

Implementing a Synchronous Request-Response Pattern Using OSB

The following diagram illustrates how an end to end flow leveraging AIA canonical objects implements a synchronous request-response pattern using OSB.

Flow implementation using OSB

Fire-and-Forget

The requester application should be able to continue its processing after submitting a request regardless of whether the service providers needed to perform the tasks are immediately available or not. Besides that, the user initiating the request does not have a functional need to wait until the request is fully processed. The service requesters and service providers must have the capability to produce and consume messages at their own pace without directly depending upon each other to be present.

Use Case

For example, order capture applications should be able to keep taking orders regardless of whether the back end systems such as order fulfillment systems are available at that time. You do not want the order capturing capability to be stopped because of non-availability of any of the services or applications participating in the execution of order fulfillment process.


- 22 -

Points to Consider

AIA recommends the fire-and-forget pattern using queuing technology with a database or file as a persistence store to decouple the participating application from the integration layer. The queue acts as a staging area allowing the requester applications to place the request messages. The request messages are subsequently forwarded to service providers on behalf of requester as and when the service providers are ready to process them. It is highly recommended that the enqueueing of the request message into the queue is within the same transaction initiated by the requester application to perform its work. This ensures that the request message is enqueued into the queue only when the participating applications transaction is successful. The request message is not enqueued in situations where the transaction is not successful. Care must be taken to ensure that the services residing between two consecutive milestones enlist themselves into a single global transaction.

In other cases (transactional flows), since the requester 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 the case of an asynchronous interaction with the requester ABCS, a JMS consumer adapter proxy service that uses JMS as transport is required.

Implementing a Fire-and-Forget Pattern Using OSB

The following diagram illustrates how an end to end flow leveraging AIA canonical objects implements a fire-and-forget pattern using OSB.

Flow implementation using OSB


- 23 -

Chapter 3: Extending a PIP


Introduction

Building a New Connector Service

Extending ABCS

Introduction

AIA architecture provides a robust extensibility framework for you to extend an existing PIP. You can use OSB for building extensions for the flows when OSB is the right technology.

Building a New Connector Service

AIA is a flexible architecture which provides multiple technology options to implement services. Customers who standardized on OSB can buy a PIP and implement connector services to complement PIP functionality on OSB. These services must exhibit the following characteristics:

Completely stateless - there is absolutely no need to persist any state in the integration layer


- 24 -

Not long running orchestration processes

Synchronous responses from downstream services or applications in case of flows involving

federated queries

No need to sequence messages in case of asynchronous communication

Note that AIA Foundation Pack does not provide native support for the AIA artifacts built using OSB:

Life cycle management of OSB services

AIA Custom xpath functions

Instance level monitoring

AIA Xref and DVM functions

If you are building new Connector Services that need to modify or access cross reference data

you should refrain from using OSB. If you are willing to build the cross reference data access

functions on their own alone should consider building these types of connector services using

OSB.

Extending ABCS

An ABCS, regardless of whether it is requester- or provider-specific, has the ability to invoke custom code either two or four times during its execution. These serve as extensibility call-outs.

The ABCS supporting a request-response pattern in either synchronous or asynchronous mode has four extensibility points. An ABCS supporting a fire-and-forget pattern has two extensibility points. You can develop custom implementations and have them hooked to these extensibility points. These custom developed services behave as an extension to the delivered ABCS. Each extension point allows one hook so only a single customer extension can be plugged in.

Each ABCS is accompanied by a corresponding customer extension service. A request-response ABCS has four extensibility points, therefore, the ABCS extension service will have four service operations. For a fire-and-forget ABCS, the corresponding ABCS extension service will have two service operations

If you have chosen OSB as the strategic ESB for your company and implemented several services on OSB, you can use OSB to implement the ABCS extension service to complement the PIP functionality. If the use case requires calling the extension service within the same transaction as the Application Business Connector Service, then the ABCS needs to call a Mediator Service which in turn calls OSB service using direct binding.


- 25 -

Chapter 4: Common Services Platform This chapter includes the following section:

Virtualizing AIA Shared Services

Virtualizing AIA Shared Services

Virtualizing AIA shared services is applicable if you plan to have a common services platform that will host services developed internally as well as services delivered by vendors in the form of packaged integrations or applications. The main purpose of the common services platform is to ensure that all the services, regardless of the implementation technologies, and the vendors will be hosted on a single platform and made available to various types of clients in a consistent manner. This approach allows you to expose the existing capabilities to the newer clients as well as newer channels in a consistent manner. In addition, it allows you to implement your consolidation and retirement strategies – the ability to retire the old legacy systems and introduce modernized services with no disruption to the clients.

AIA Process Integration Packs (PIPs) expose participating applications capabilities as shared services in the form of Enterprise Business Services (EBS). The EBS abstracts the implementation details from the requester applications and establishes the decoupling between the service requester and the providers. These services are implemented leveraging the Oracle Mediator service component engine.

By leveraging Oracle Service Bus to construct your common services platform, you can host AIA EBS by creating an OSB proxy service wrapper. The OSB proxy service communicates with the Mediator-based EBS, exposed via Direct Binding, and the Mediator-based EBS communicates with the OSB proxy service using Direct Binding. The Direct Binding allows for the propagation of identity as well as the transaction.

For more information about Direct Binding, see Oracle Fusion Middleware Developers Guide for Oracle SOA Suite and Oracle Fusion Middleware Developers Guide for Oracle Service Bus.

This OSB proxy service becomes the entry point for all consumers. Any external clients or applications wanting to consume the shared services can invoke the OSB services using your virtualization architecture. By using the OSB based virtualization layer you have the ability to cache the services results using coherence by declaratively specifying them.

Refer to the chapters in Part II: Building AIA Services Using OSB for more information on integrating BPEL / Mediator Service with OSB service.

The following diagram illustrates how the virtualization layer is created by leveraging the services delivered by Oracle PIPs.


- 26 -

Virtualization using OSB

In situations where you have built end-to-end flows using OSB technologies, an additional OSB proxy service is created with inbound support for HTTP transport; and this proxy service communicates with the existing EBS using local transport.

The following diagram illustrates how the virtualization layer is created by leveraging the OSB based shared services. Refer to Chapter 6: Building AIA Artifacts using OSB – Preparatory Steps more information.


- 27 -


- 28 -

Chapter 5: Gateway for Accessing Existing

Systems This chapter includes the following sections:

Introduction

Accessing Services on Applications

Accessing Services on EAI Infrastructure

Introduction

Many customers have significant investments in legacy and proprietary technologies that support critical applications functions and data access. These systems may host functions such as account inquiry, order status inquiry, new order creation and so on. There is enormous value in exposing these capabilities in a semantically consistent open manner to multiple clients and channels. These services are either hosted on legacy applications directly or created on legacy EAI middleware. In either case, this pattern can be used to access these services so that coarse grained business services implement business logic without the need to deal with low level application accessing details.

Accessing Services on Applications

This pattern applies if you would like your Process Integration Packs as well as new service oriented integrations that you build to leverage application functions directly. You want these capabilities to be accessible via a common services platform thereby allowing newer clients and newer channels to have access to them. In addition, the newer channels may not be available to the existing applications either because they are beyond it or they are providing support for incompatible communication mechanisms.

In this situation, there is no difference with respect to the way the clients interface with the system – the OSB-based proxy service is the entry point – and this in turn interacts with either a Mediator- or OSB-based Enterprise Business Service. The provider ABCS communicates with the application that hosts the critical business functions via an OSB based gateway.

The provider ABCS uses the relevant protocols to communicate with the OSB proxy depending upon the implementation technologies. The BPEL-based provider ABCS uses Direct Binding to invoke the OSB proxy; the OSB-based provider ABCS uses local transport to invoke the OSB proxy. The OSB proxy gateway can either publish a message to JMS or invoke the service exposed on the application after doing the necessary transport protocol transformations.


- 29 -

Accessing Services on EAI Infrastructure

Use this pattern if you would like the PIPs and new service oriented integrations that you build to leverage applications functions and data exposed through another Enterprise Application Integration (EAI) infrastructure. Even though the existing applications are already hosted on an EAI infrastructure, you may want these capabilities to be accessible via a common services platform thereby allowing newer clients and newer channels to have access to them. In addition, the newer channels may not be available to the existing EAI infrastructure either because they are beyond it or they are providing support for incompatible communication mechanisms.

In this situation, there is no difference with respect to the way the clients interface with the system – the OSB-based proxy service is the entry point – and this in turn interacts with either a Mediator- or OSB-based Enterprise Business Service. The provider ABCS communicates with the EAI infrastructure that hosts the critical business functions via an OSB-based gateway.

The provider ABCS uses the relevant protocols to communicate with the OSB proxy depending upon the implementation technologies. The BPEL-based provider ABCS uses Direct Binding to invoke the OSB proxy; the OSB-based provider ABCS uses local transport to invoke the OSB proxy. The OSB proxy gateway can either publish a message to JMS or invoke the service exposed on the EAI infrastructure after doing the necessary transport protocol transformations.


- 30 -


- 31 -

Part II: Building AIA Services Using OSB


- 32 -

Chapter 6: Building AIA Artifacts using OSB – Preparatory Steps

This chapter lists out the pre-requisite tasks that must be carried out prior to the development of AIA services using OSB.


Getting AIA Components from FP Install

Registering AIA Components with OSB

Registering AIA Components as a jar File

Working with AIA Configuration File

Getting AIA Components from FP Install

AIA components are located under %AIA_HOME% on the machine where FP is installed. You must copy those files on to the machine where you are accessing the OSB console and create a jar or zip file.

Registering AIA Components with OSB

The AIA artifacts Enterprise Object Library and Enterprise Service Library (EOL /ESL) are shared project resources that must be uploaded for development of any project using the AIA programming model.

These common resources can be uploaded into the OSB using two approaches:

As a zipped file

As a jar file

The recommended approach is to register the AIA component as a jar file.

AIA components are subject to enhancements and these enhancements are usually applied as patches, or as new versions of the libraries. To update the existing EOL library you must upload the EOL/ESL into OSB and manage the enhancements. AIA recommends that the EOL/ESL be imported as a jar file into OSB. When enhancements/patches are to be applied, a new jar file with changed artifacts must be re-imported into OSB. Thus, the artifacts that require an update are replaced by the new ones in the new jar file.

Note: If you change or extend an Enterprise Business Object or an Enterprise Business Service,

you need to reimport it into OSB. You can either import those artifacts alone or you can zip the

whole library again and import. AIA recommends importing only those objects that have changed.


- 33 -

The following section lists out the high-level tasks needed to register AIA components using a jar file.

Registering AIA Components as a jar File

Note: It is assumed that a jar file with AIA Components is available. (This jar file is a service bus

configuration file.) The following issue should be addressed by jar file

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.

The AIA Components library, imported into the OSB as a jar file, should have the all WSDL files updated with details of bindings before it is used for creating OSB services.

Please refer to Updating the WSDL from Enterprise Services Library for Creating OSB Service for more details including:

The steps required for updating the WSDL

A sample WSDL snippet highlighting the updated sections of the WSDL.

A high level description of how a service bus configuration jar file is created with the above

two issues addressed

1. In the OSB console, click Create, click System Administration and then click Import.

2. Browse the file system and select the jar file to be imported into the OSB.

Working with AIA Configuration File

The AIA configuration file externalizes several configuration parameters so that they can easily be changed at runtime for the target environment without changing and deploying the code. These changes can be performed by a system administrator.

To access the AIAconfiguration file from OSB:

1. Place AIAconfiguration file a in a folder.

2. Set aia.home=%above folder% You can either set it as environment property or in startWeblogic script under %domain_home%/bin.

3. On Windows, the command is Set aia.home=%above folder%

4. On Unix aia.home=%abovefolder% export aia.home


- 34 -

The AIA configuration file can be accessed using either xslt through custom xpath functions or in OSB pipeline through java callout. For xslt, refer to Using AIA XPath Functions and for java callout refer to “Using Java Callout for Invoking AIA Configuration API” in Computing Dynamic Endpoint Location in ABCS.


- 35 -

Chapter 7: Designing and Developing Enterprise Business Services

This chapter describes how to design and develop Enterprise Business Services (ESB) as OSB services.


Introduction

Developing EBS as an OSB Service

Introduction

EBSs are the foundation blocks in Oracle Application Integration Architecture (AIA).

An EBS represents the application- or implementation-independent Web service definition for performing a business task, and the architecture facilitates distributed processing using EBS. Since an EBS is self-contained, it can be used independently of any other services. In addition, it can be used within another EBS.

For more information about EBS, see "Understanding Enterprise Business Services" in the Oracle Fusion Middleware Concepts and Technologies Guide for Oracle Application Integration Architecture Foundation Pack.

You must construct an EBS when the business process integration is between multiple source applications and target applications using the canonical model.

The purpose of the EBS is to:

Provide the mediation between the requesting services and providing services.

Provide different operations invoked from a requester Application Business Connector

Service (ABCS), an EBS, or an Enterprise Business Flow (EBF).

Route an operation to a suitable EBS, EBF, or provider ABCS based on the evaluation of

the various routing rules for an operation.

Developing EBS as an OSB Service

Implementation Technology: An EBS is created as a Proxy Service in OSB.

Service Type : web service

Transport Configuration: The transport protocol to be used is local.

Operation Selection Configuration : Refer to the section OSB Service Configuration

Message Content Handling: Refer to the section OSB Service Configuration


- 36 -

Consuming Enterprise Business Services

The following sections describe use cases that illustrate the invocation of EBSs via various mechanisms.

ABCS Invoking a Co-located EBS

The following diagram shows how an Enterprise Business Service is invoked using local transport. This methodology is used when all of the integration components participating in a fine-grained end-to-end flow are co-located.

Inter-Communication between Enterprise Business Services

There are scenarios where order-related end-to-end flows including the relevant EBS are hosted on one cluster; and the customer-related end-to-end flows including the relevant EBS are hosted on another cluster. In this topology, there are use cases where a customer-specific flow may need to consume order-related services. In these scenarios where the EBS must be accessed remotely:

An HTTP adapter (a proxy service using HTTP transport) needs to be built for the EBS.

If it is an external application that needs to access EBS remotely (as shown in the following

diagram), it directly invokes the HTTP adapter proxy service which in turn invokes the local

transport based EBS service.

A business service representing this HTTP adapter proxy service must be developed by the

clients who want to access the EBS.

The business service is needed only if the calling service happens to be an OSB based

ABCS. It must call a business service that represents the HTTP adapter proxy service.

Refer to the appendix for the relevant details of developing a Business Service in the OSB.


- 37 -

External Application Invoking the EBS Using an HTTP Adapter

The following diagram shows how an external application is able to invoke the EBS using an HTTP adapter. This design pattern is used in situations where a home-grown application is able to directly consume the Enterprise Business Service. Since the default transport for an OSB based Enterprise Business Service is Local, an HTTP transport-based proxy service must be available for external clients to consume the service.

ABCS Invoking a Remotely Located EBS

The following diagram shows how the ABCS can invoke a remotely located EBS. The Customer – Order invocation use case mentioned above is implemented using the following design pattern.


- 38 -

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.. Please refer to Chapter 1 – Designing and Building AIA Services using OSB – Preparatory Steps for more information.

EBS as OSB proxy service should be created in its own folder as a web service using its WSDL in the Enterprise Services Library. The proxy exposes all the available operations in its WSDL to the clients. The following steps summarize the process required.

1. Create a folder for the EBS

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

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

An EBS built as an OSB Proxy service inherits the intrinsic support from OSB proxy service to:

Expose multiple operations defined on it

Create Routing Rules for each operation

Perform XSLT transformation

Define endpoints for each routing rule.

The following sections describe how to:

Configure the routing rules for the EBS operations


- 39 -

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 sections capture the support and the ability provided in the OSB Proxy service for specifying routing rules, evaluating these rules, and determining what service to route to.

The message flow of an OSB proxy service consists of a set of nodes. The Route node dispatches the message to another service. The routing behavior of the message flow is defined by the configuration of the Route node.

Recommendations: Even though OSB does have multiple mechanisms to interact with external services, AIA recommends the use of the Route node in Enterprise Business Services to dispatch requests to target services.

Configure the Route 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 following sections discuss the routing logic performed in the Route node using various patterns. 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 routes 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 design time.

Using Routing Table in the Route Node

Consider the case where the EBS routes 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 example,

/ebo:QueryCustomerPartyListEBM/corecom:EBMHeader/corecom:MessageProc

essingInstruction/corecom:EnvironmentCode/text()=CAVS

After evaluating the 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 previous model, the EBS routes to the appropriate CAVS service using the Routing Table Action. The routing logic is based on content in the EBM header.

The primary disadvantages to using the Route To or Routing Table models are:

They are not entirely dynamic


- 40 -

Proxy needs to be modified to change the routing end point.

Because of these issues, AIA does NOT recommend the constructs Route-To and Routing Table to be used from an EBS.

Dynamic Routing

Dynamic Routing eliminates the need to modify the Proxy to change the routing endpoint.

When you need to determine which of several services to invoke at runtime, use Dynamic Routing.

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 the 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, you need to have the following in place.

1. An XQuery resource, having an UDF

a. To evaluate the routing rules filter expression for a specific operation on the EBS.

b. Routing rules filter expression is specified as an XPath expression

c. Decides where the incoming request should be routed to

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

e. Every operation defined on EBS would have an XQuery resource specific to it.

f. The XQuery resource for a given operation is dynamically determined at runtime.

2. An XQuery resource, XQueryResourceFinder,

For a specific operation, returns a fully qualified path to a matching XQuery resource as

described the previous step.

The value of <servicetype> is 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).


- 41 -

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.

In summary:

Use two XQuery resources XqueryResourceFinder and operation-specific XQuery resource

that evaluate the routing rule expression.

Construct the OSB context variable ctx:route. This variable defines the dynamic endpoint of

the service where the message will be eventually routed.

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

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 Routing be used in conjunction with the Operation Branch construct to model a routing from the EBS.

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


- 42 -

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

Error Handling

See Chapter 18: Error Handling in OSB

Logging

See Chapter 17: Logging Messages in OSB


- 43 -

Chapter 8: Designing and Developing Application Business Connector Services

This chapter included the following sections:

Introduction to Application Business Connector Services

Designing ABCS

Developing ABCS

Introduction to Application Business Connector Services

The role of the ABCS is to expose the business functions provided by the participating application in a representation that is agreeable to Enterprise Business Services (EBSs). It can also play another role in which it serves as a glue to allow the participating application to invoke the EBSs. The following diagram illustrates a scenario in which the E-Business Suite application is using an ABCS to invoke an EBS. In this scenario, the ABCS is playing a requester role. The same diagram also illustrates how the EBS invokes one of three ABCS to perform a specific task. Here, the three ABCS are playing provider roles.


- 44 -

The ABCS enables participating applications to become service providers as well as service consumers. It also enables applications having nonstandard connectivity to expose their functionality as web services.

For more information about ABCS, see "Understanding Application Business Connector Services" in the Oracle Fusion Middleware Concepts and Technologies Guide for Oracle Application Integration Architecture Foundation Pack.

Designing ABCS

This section includes the following topics:

Key Tasks

Defining the ABCS Contract

Defining the Role of the ABCS

Key Tasks

An ABCS architect or developer must perform the following tasks as part of the design activity:

■Understand the ABCS role


- 45 -

■Identify the business events triggering the invocation of ABCS

■Identify the interactions between application and the ABCS and vice versa

■Identify the appropriate technologies to be used to facilitate the interaction

■Define the ABCS contract

Defining the ABCS Contract

The ABCS contract (WSDL) specifies how a caller interacts with its Business Connector Service. The caller could either be a participating application or another service such as EBS. The following diagram illustrates the decision flow for defining the contract (WSDL) for the ABCS.

Defining the Role of the ABCS

This section discusses design decisions that you must make to enable the ABCS to participate in either a requester or provider role.


- 46 -

Designing an ABCS to Participate in a Requester Role

1. Determine how the ABCS is invoked or triggered. This analysis tells you how the ABCS is invoked by the application. Determine:

a. Whether the application can make a SOAP-based invocation of ABCS.

b. Whether the application service can invoke the ABCS using JCA adapter.

c. Whether the ABCS must subscribe to messages published by the application due to occurrence of business events.

2. Determine what interaction pattern is needed.

The following questions help the architect in identifying the optimal message exchange

pattern.

What business events will cause the invocation of requester ABCS?

Is the application expecting a response from the requester ABCS?

Does the application need to wait until the response is received for performing the next

task?

Does the application need to wait until the request is fully processed by the provider

application?

For more information about choosing a MEP, see "Choosing the Appropriate MEP." in Oracle Fusion Middleware Developer's Guide for Oracle Application Integration Architecture Foundation Pack.

3. Determine what Enterprise Business Services or operations need to be invoked.

4. Does the message sent by the requester application have all the information necessary for requester ABCS to construct the EBM?

a. If not, does it have to reach out to applications to get the additional information?

b. If yes, what technologies are available? What application interfaces are to be used to get the additional information?

For more information, see Oracle Fusion Middleware Developer's Guide for Oracle


5. Can the application possibly publish a message with incomplete information?

a. Should the ABCS wait until the message with complete information is published?

In such a scenario, an aggregator should collect and store individual messages until a

complete set of related messages has been received

b. If yes, what is the application service and how does it communicate with it?

Designing an ABCS to Participate in a Provider Role

To determine how to enable the ABCS to participate in a provider role:


- 47 -

1. Decide whether the application can directly consume the information sent by EBS.

2. Determine how the ABCS interacts with provider applications.

3. Define the tasks that must be done by this ABCS.

4. Determine what message exchange pattern (MEP) is used to communicate with the application.

5. Determine whether data validation must be done on the EBM sent by the EBS prior to sending the request to the provider application.

6. Decide whether you need guaranteed delivery of messages.

7. Determine whether it is a single message containing data for multiple instances.

8. Decide whether the entire message should be processed as a single unit of work.

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.

Transaction is propagated in proxy service only when the transport is local

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.

For the creation of an ABCS as an OSB proxy service with web service as Service Type refer to Chapter 14: Implementing Synchronous Request-Response MEP.

The following sections describe the programming model for implementing the core tasks of an ABCS, including:

Message validation

Message transformation


- 48 -

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 turn on the validation on request basis.

Message Transformation

OSB adds a message transformation layer that is useful for:

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.

XSLT

XSL maps describe XML-to-XML mappings. These transformations (XSLs) can be created by a developer and imported into OSB or the existing XSL resources can be imported into OSB.

The messages content can be manipulated by applying XSLT in conjunction with the message processing actions – assign, replace, insert, and so on 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.


- 49 -

The following sample shows a Replace action in the proxy message flow to apply an XSL transformation on a message’s content.

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.

AIA recommends that the Replace node contents option is 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 is sent to the destination service, and also the reverse transformation can be applied to the services response.

In the former case, for example, to convert an ABM into an EBM, the XSLT is in 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 this document: http://download.oracle.com/docs/cd/E17904_01/doc.1111/e15867/xquery_transforms.htm#OSBAG926.

Replace [ entire node ] of [ ./ cmu:ListOfCmuAccsyncAccountIo]

in [ body ] with [ Xslt Resource:

XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM]

Input Document: $body

http://download.oracle.com/docs/cd/E17904_01/doc.1111/e15867/xquery_transforms.htm#OSBAG926

http://download.oracle.com/docs/cd/E17904_01/doc.1111/e15867/xquery_transforms.htm#OSBAG926


- 50 -

Message Enrichment

In situations where an ABCS has to query the participating application to get the information and enrich the message before submitting to EBS, Service Callout action is 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.

OSBs 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

For synchronous-request-response MEP (non-transactional), the requester ABCS, by default, is a proxy service using HTTP transport. The applications access ABCS as a web service.

In other cases (transactional flows), since the requester ABCS is built as a proxy service with transport as local, it is exposed to the external world via its HTTP adapter proxy service.

For asynchronous interaction with the requester ABCS, a JMS consumer adapter proxy service that uses JMS as transport is required.


- 51 -

For asynchronous interactions using JMS, see Chapter 10: Asynchronous Invocation of ABCS.

Outbound Service Interaction

An ABCS can communicate with applications as an outbound interaction. using a SOAP Web Service. One interaction model for outbound communication between ABCS and the application is the Service Callout action, used when the outbound interaction is a synchronous request-response MEP, that is., when the service is invoked using a two-way call. When the outbound interaction is asynchronous, you must use the Publish action.

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


- 52 -

Configuring Service Callout Action

To add service callout action in the message flow of the proxy service:

1. Left-click an existing Assign action in the message flow and navigate to Add action > Communication > Service Callout from the popup menu.

2. The service callout action allows you 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.

3. Next, select the required operation from the combo box.

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

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 the Route node in the message flow of a proxy service, which performs request or response communication with another service.

The 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 uses route node to directly invoke the EBS proxy service. An EBS is considered co-located with ABCS when it is deployed in the same instance of OSB.

When the EBS is not co-located, you need to build a business service representing the HTTP-adapter-proxy-service of the EBS. The ABCS proxy service then routes to this business service.

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


- 53 -

Computing Dynamic Endpoint Location in ABCS

Using Java Callout for Invoking AIA Configuration API

For a proxy service, in order to invoke a Java method within the message flow, use the Java Callout action. The Java method must be public and static and the Java class must be jar-red in a file. The jar file must be registered with the OSB.

The following data types are permitted in the signature of the static method:

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 these types, custom return types are possible from Java callouts, but you can only store them in the pipeline 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 GetRouteToCAVSProperty

a. Use java callout 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 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

Developing Provider ABCS with Dynamic Endpoint

To code a provider ABCS 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 GetTargetSystemID,

a. Use the 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

2. Configure a stage, naming it AssignDynamicPartnerlinkVariables, with Assign action to set the variables with ServiceName, endpoint name (PartnerLinkName), routeToCavs PropertyName, and cavsEndpoint PropertyName

3. Compute the targetEndpointLocation as described in Configuring Service Callout Action.

4. Add a Service callout action in the proxy and configure it:


- 54 -

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

Set the checkbox URI and set its expression with targetEndpointLocation

Set the Mode to request-response or request, depending on whether the MEP is

request-response or request-only.

For other configuration parameters, refer to Chapter 19: OSB Service Configuration

CAVS Enabling

Developing Provider ABC Services to be CAVS-Enabled

To enable CAVS on a provider ABCS, follow the steps documented in “Developing Provider ABCS with Dynamic Endpoint

Developing Requester ABC Services to be CAVS-Enabled

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

Logging

See Chapter 17: Logging Messages in OSB

Error Handling in ABCS



- 55 -

Chapter 9: Extending ABCS


Developing Extensible ABCS

Developing an ABCS Extensibility Service

Developing Extensible ABCS

An ABCS, regardless of whether it is requester or provider specific, can invoke custom code a minimum of either two or four times during its execution. These serve as extensibility points.

The ABCS supporting a request-response pattern in either synchronous or asynchronous mode has four extensibility points. An ABCS supporting fire-and-forget patterns has two extensibility points. You can develop "add-ins" and have them hooked to these extensibility points. These "add-ins" - customer-developed services - behave as an extension to the delivered ABCS. Each extension point allows one hook.

Only a single customer extension can be plugged in. This section describes the mechanism for creating ABCSs with extensible services, which enables you to have service implementations that require no modifications to the delivered ABCS.

The following diagram shows you how an ABCS can be made extension aware. Here it assumes that the EBS with which it is interacting employs a request-response interaction style. Note that the steps for executing the customer extension to do additional tasks are optional.


- 56 -

For more information, refer to sections “Introduction to Enabling Requester ABCS for Extension” and “Introduction to Enabling Provider ABCS for Extension” in Oracle Fusion Middleware Developer’s Guide for Oracle Application Integration Architecture Foundation Pack.

Developing an ABCS Extensibility Service

The service implementation at an extension point could be an HTTP/SOAP service or could

have been implemented using other technologies. It could be remote or local with respect to

the ABCS.

To access a Business Service from an ABCS, the ABCS must be developed to invoke the


- 57 -

service at the extension point.

A Business Service representing the service at the extension point must 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 uses a Service callout action to invoke the Business Service. The steps are detailed

below.

Configuring the ABCS Message Flow to Incorporate ABCS Extensibility

To configure the ABCS message flow to incorporate ABCS extensibility:

1. Add a new Stage in the message flow of the ABCS, prior to a process step, called pre[process_stepname]ABM

2. Using Java Callout action, read the value of the property, ABCSExtension. pre[process_stepname]ABM

3. Check if the value of the property in the AIAConfigurationProperties.xml is set to true

4. If yes, use the Assign action and set the payload from the node, body, to the variable pre[process_stepname]ABMReqMsg

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

6. Enter pre[process_stepname]ABMReqMsg as the Request Document Variable


- 58 -

7. Enter pre[process_stepname]ABMRespMsg as the Response Document Variable

8. In Request Actions of the Service callout, use the Java Callout action to read the concrete end point URL of the service at the extension point.

9. In Request Actions of the Service callout, add the action Routing Options

10. Override the URI in the Routing Options with the concrete end point URL of the service

11. Add a Replace action after the Service Callout action and replace the payload of the variable body with the value of the variable Enter pre[process_stepname]ABMRespMsg


- 59 -

Chapter 10: Asynchronous Invocation of ABCS


JMS Consumer Adapter

JMS Producer Adapter

Error Handling and Recovery for Guaranteed Message Delivery

Introduction

This chapter 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 prerequisite 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. 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


- 60 -

JMS Consumer Adapter

The JMS Consumer Adapter is a proxy service that uses JMS transport. The proxy service consumes messages off the queue and routes to the Requester ABCS. The configuration details are:.

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 Producer Adapter for the scenarios where the queue is fed with inbound service requests using OSB.

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, refer to Chapter 19: OSB Service Configuration

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

Error Handling and Recovery for Guaranteed Message Delivery

To implement error handling and recovery for the asynchronous MEP to ensure guaranteed message delivery:

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.


- 61 -

For more details, refer to Oracle Fusion Middleware Concepts and Technologies Guide for Oracle Application Integration Architecture Foundation Pack.


- 62 -

Chapter 11: Using Adapters with AIA on OSB


Introduction

Using Adapters on OSB

Introduction

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.

For outbound communication using adapters, ABCS calls the OSB business service defined using JCA transport. If you need additional transformation between ABCS and the back-end application, AIA recommends creating a proxy service with local transport along with a business service.

For inbound communication using adapters, AIA recommends creating an adapter proxy service with JCA transport. The Adapter proxy service calls the ABCS. The Adapter proxy service may have additional transformation if required.

Using Adapters on OSB

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.


- 63 -

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

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

6. From the 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 refer to Oracle Fusion Middleware Developers Guide for Oracle Service Bus.


- 64 -

Chapter 12: Interoperating with SCA-based AIA Services


Introduction

Calling SCA Service from OSB

Introduction

AIA recommends using best-of-breed technologies to implement AIA integrations. There may be some uses which warrant the OSB- based AIA services to interoperate with AIA services implemented using other technologies such as BPEL and Mediator. The following methods can be used to facilitate the interoperability with SCA-based technologies:

Web services

Queues

SOA – Direct transport

AIA recommends using SOA – direct transport because it is transactional and high performant due to runtime optimization.

Calling SCA Service from OSB

To call the SCA service from OSB:

1. Add a new service interface with direct binding. The diagram illustrates how to complete the fields.


- 65 -

2. Create a business service with SOA-direct transport.

Note: It is assumed that WSDLs and schemas are already registered as OSB resources.

To create a business service:

1. Create a new resource, of type Business Service, in the project folder.

2. Select the service type web service.

3. Click Browse and select customerPartyEBS.wsdl from the displayed list of registered WSDLs.

4. From the pop-up, Select a WSDL Definition, select the binding – CustomerPartyEBSBinding


- 66 -


Protocol - Use SOA-direct transport for business service.

EndPoint URI - The end point URI is the URI which is used to access the service. When using SOA-direct transport, refer to the following link for URI format:

http://download.oracle.com/docs/cd/E14571_01/doc.1111/e15866/soa.htm#BABJAEFJ

The summary page of the business service, after the configuration is complete, is shown below.

http://download.oracle.com/docs/cd/E14571_01/doc.1111/e15866/soa.htm#BABJAEFJ


- 67 -

Calling OSB Proxy Service from aSOA Composite

To call an OSB service from a composite:

1. Create a transport adapter proxy service with sb transport.

Note: It is assumed that WSDLs and schemas are already registered as OSB resources. The

following steps have to be followed for creating EBS as OSB proxy service.

2. Create a new project, SamplesCustomerPartyEBS.

3. Create a new resource, of type Proxy Service, in the project folder.

4. Name it SamplesCustomerPartyEBS.

5. Select the service type as web service.

6. Click Browse and select customerPartyEBS.wsdl, from the displayed list of registered WSDLs.

7. From the pop-up, Select a WSDL Definition, select the binding – CustomerPartyEBSBinding.


- 68 -


Protocol - Use sb transport for sb adapter proxy service

EndPoint URI - The end point URI is the URI used by the client for accessing the service. When using sb transport, the service would not have <service name>. Please refer to the following url for complete details

http://download.oracle.com/docs/cd/E14571_01/doc.1111/e15866/sb.htm#i1103399

The following screenshot shows the summary page of the proxy service, after the configuration is complete.

To configure a composite:

1. Add a new reference to composite with direct binding.


- 69 -

2. Drag and drop direct binding on to reference lane.

3. Make the following changes:

a. Reference Target : Oracle Service Bus

b. WSDL URL : Point to abstract WSDL in the mds

c. Address : sb:/<proxy name given for sb adapter proxy service>

d. Provider URL : t3://<host:port>


- 70 -

Chapter 13: Securing AIA OSB Services

This chapter describes how to use OWSM polices to secure AIA services.

Using OWSM Policies to Secure AIA Services

AIA recommends using OWSM policies to secure AIA services. This enhances interoperability with SCA-based services as well as provides a consistence configuration experience across all AIA services.

To apply OWSM policy:

1. Click on Policies tab.

2. Select OWSM Policy Bindings under Service Policy Configuration. Click the + sign next to the service name.

3. Click Add to see the list of the policies and select the policy.

4. Click Submit.


- 71 -

5. Click Update.


- 72 -

Chapter 14: Implementing Synchronous Request-Response MEP


Introduction

Creating and Configuring the EBS as OSB Proxy Service

Introduction

You may have use cases where you need to send requests synchronously to service providers and get immediate responses to each of the requests. These use cases require that you wait until the responses are received before proceeding to the next tasks.

For example, Customer Relationship Management (CRM) applications may provide features such as allowing customer service representatives and systems to send requests to providers for performing tasks such as account balance retrieval, credit check, ATP (advanced time to promise) calculation, and so on. Since CRM applications expect the responses to be used in the subsequent tasks, this precludes the users from performing other tasks until the responses are received.

Creating and Configuring the EBS as OSB Proxy Service

Note: It is assumed that WSDLs and Schemas are already registered as OSB resources.

To create the EBS as an OSB proxy service:


- 73 -

Create a new project, SamplesCustomerPartyEBS.

Create a new resource, of type Proxy Service, in the project folder.

Name it SamplesCustomerPartyEBS.

Select the Service Type as WSDL Web Service.

Click Browse and select customerPartyEBS.wsdl, from the displayed list of registered

WSDLs.

From the pop-up, Select a WSDL Definition, select the binding CustomerPartyEBSBinding.


Protocol - Use local transport for EBS proxy service by default. Hence, for this sample, the protocol selected for the SampleCustomerPartyEBS is local.

EndPoint URI - The end point URI is the URI used by the client for accessing the service. When using local transport, the service does not have an endpoint. In this sample, the 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.

This page shows the summary page of the EBS proxy service, after the configuration is complete.


- 74 -

Message Routing In EBS

In this sample, you 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

Note: It is a prerequisite that the ABC services that the EBS routes to, are already built and

configured.

Adding Operational Branch Node

In the message flow of CustomerPartyEBS proxy services:

1. Add an operational branch node.

2. Edit the operational branch node to add operation branch definitions for the operation querycustomerparty.

3. Edit the branch node querycustomerparty to add the dynamic routing flow, as described in the following section.

Configuring the EBS for the Dynamic Routing

Two XQuery resources XqueryResourceFinder and EvaluateRoutingRule are required. The

sample XQuery resources used in this example are shown below.

XqueryResourceFinder

declare namespace xf = "http://tempuri.org/XQueryResourceFinder/";

declare function xf:XQueryResourceFinder() as xs:string {

'EvaluateRoutingRule'

};

xf:XQueryResourceFinder()


- 75 -

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

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 a new resource, select Resource Type XQuery.

c. Click Browse and upload the existing XQuery file in the file system, OR enter the XQuery text and click 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 XQuery Resources and choose XqueryResourceFinder as the resource.

b. Assign the result of this expression to the variable dynamicXQueryResource.

4. Add the Assign action in the stage:

a. For Assign Expression, click Dynamic XQuery and choose EvaluateRoutingRule as the resource.

b. To add a custom variable, click Add and provide QueryCustomerPartyEBMVar as the Variable name.

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

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

5. Add the Assign action in the stage


- 76 -

a. For the Assign expression, click XQuery Text.

b. Use the value of the variable endPointService and prepare the context variable, ctx: route as shown below

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>

c. Assign the result of this 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 enter $dynamicEndpoint as the value

Error Handling in EBS

See Chapter 18: Error Handling in OSB.

Developing Requester ABCS

1. Create Project – SamplesQueryCustomerPartySiebelReqABCSImpl


- 77 -

a. Click Project Explorer on the left panel in the OSB console.

b. Enter the project name in the text box as SamplesQueryCustomerPartySiebelReqABCSImpl and click Add Project.

2. Upload the WSDL SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl

a. In the projects table, click the project that has been just created.

b. From Select Resource type drop down options, select WSDL

c. Click Browse and navigate to the path in the file system to find SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl. Click Save.

d. The OSB console displays the following conflict message:

e. In order to resolve the conflicts, you need to 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.

f. To resolve the conflicts, go back to project folder and drill down into WSDL SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl. Go into the Edit References screen.

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


- 78 -

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>


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

c. Select the Service Type Web Service.

d. Click Browse and select SamplesQueryCustomerPartySiebelReqABCSImpl.wsdl, from the displayed list of registered wsdl s.

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 used by the client for accessing the service. In this sample, provide the service name as the endpoint URI.

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


- 79 -

5. Upload the XSLs required for message transformations in the proxy

a. Upload the following XSL resources into OSB

XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM.xsl

XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM_Custom.xsl

XformQueryCustomerPartyResponseEBMToListOfCmuAccsyncAccountIo.xsl

b. Make the following changes to the XSL resources:

In the Node Selection xpath, / does not work because the root node is soap.

Replace / 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 such as orcl:generate-guid().

Comment out Xpath 2.0 functions such as xp20:current-dateTime().

Comment out the Xref and DVM functions.

For more details refer Using AIA XPath Functions.

(The Appendix of this document contains the XSL s used by this POC)

Configure the Message Flow of the Proxy Service

1. Add stage XFORM ABM to EBM.

a. To transform from ABM to EBM, use the 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.


- 80 -

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

c. Select the XformListOfCmuAccsyncAccountIoToQueryCustomerPartyEBM.xsl as the XSLT Resource and enter $body as the Binding input.

2. Assign EBM Header

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

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

3. Route to the EBS from a Requester ABCS

a. Add Route Node to the message flow.

b. Edit the Route Node to invoke the SamplesCustomerPartyEBS proxy service invoking the operation QueryCustomerParty.

4. Transform the response EBM back to ABM

a. Add actions to Response action of the Route Node to XFORM EBM to ABM

b. To transform from EBM to ABM, add the Replace action to the response actions of the Route node.

c. Replace the node QueryCustomerPartyResponseEBM in the variable body with the expression, which takes the form of XSLT resource.

d. Select XformQueryCustomerPartyResponseEBMToListOfCmuAccsyncAccountIo.xsl as the XSLT resource and enter $body as the binding input.

Error Handling in Requester ABCS


Developing Provider ABCS

Follow the instructions given in the section for developing Requester ABCS and do the following.

1. Create the project folder.

2. Upload the WSDL and resolve the conflicts.

3. Add binding details to the WSDL.

4. Create SamplesQueryCustomerPartyPortalProvABCSImpl as the proxy service.

Configuring the Proxy Service

Upload all the required XSLs.

Make changes to the XSLs as described in Developing the Requester ABCS.

To configure the message flow:

1. Get target system ID


- 81 -

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

Enter $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 must be

defined.


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

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

3. Add stage XformQueryCustomerPartyEBMToPcmOpCustCommitCustomer

a. Use the 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 enter $body as the binding input.

4. To compute the dynamic endpoint location, and route to it, follow the steps 2,3, and 4 of Developing Provider ABCS with Dynamic Endpoint

a. Default design-time Routing to the Provider service from a Provider ABCS.

b. 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 the Fault element is present, raise an error with business error code and the business error message.

6. Transform 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 enter $body as the binding input


- 82 -

Using AIA XPath Functions

To use AIA XPath functions in OSB, copy the aia.jar file from the Foundation Pack install into OSB_ORACLE_HOME/config/xpath-functions/ folder.

Using AIA XPath functions in XSL

Using the Java API in the XSL as a custom XPath function is very straightforward (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 the AIA XPath Functions in the XSL, you must 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 XSLs in SOA Suite, the name space is defined as:

xmlns:aia="http://www.oracle.com/XSL/Transform/java/oracle.apps.aia.

core.xpath.AIAFunctions”

You can now call the Java API as an XPath function in your XSL.

For example, in order to call API getServiceProperty (..),use the following code in XSL:

<xsl:value-of select=" aia:getServiceProperty (..)"/>

Using AIA XPath functions in XQuery

To use AIA Xpath functions in XQuery, you need to register with the XQuery engine.

To register the XPath functions:

1. Follow the instructions in Using AIA XPath Functions to copy the jar file with Java files to OSB_ORACLE_HOME/config/xpath-functions/ folder.

2. Create an xml file called aia-built-in.xml with the descriptions of the xpath functions

<?xml version="1.0" encoding="UTF-8"?>

<xpf:xpathFunctions

xmlns:xpf="http://www.bea.com/wli/sb/xpath/config">

<xpf:category id="AIAFunctions">

<xpf:function>

<xpf:name>getServiceProperty</xpf:name>

<xpf:comment>function to get aia service property from

aia configuration file</xpf:comment>

<xpf:namespaceURI>http://www.oracle.com/XSL/Transform/java/oracle.ap

ps.aia.core.xpath.AIAFunctions</xpf:namespaceURI>

<xpf:className>oracle.apps.aia.core.xpath.AIAFunctions

</xpf:className>

<xpf:method>java.lang.String

getServiceProperty(java.lang.String, java.lang.String,

boolean)</xpf:method>

<xpf:isDeterministic>false</xpf:isDeterministic>

<xpf:scope>Pipeline</xpf:scope>

<xpf:scope>SplitJoin</xpf:scope>

</xpf:function>

</xpf:category>


- 83 -

</xpf:xpathFunctions>

3. Click the expression on any of the message manipulation actions such as Assign.

4. Click XQuery Functions on left and identify the function by scrolling through the Functions

window.

5. Drag and drop the function into XQuery/XSLT Expression Editor and change values for parameters.


- 84 -


- 85 -

Chapter 15: Implementing the Fire-and-Forget MEP


Introduction

Developing One-Way Requester ABCS


Introduction

The requester application should be able to continue its processing after submitting a request regardless of whether the service providers needed to perform the tasks are immediately available or not. Besides that, the user initiating the request does not have a functional need to wait until the request is fully processed. The service requesters and service providers must have the capability to produce and consume messages at their own pace without directly depending upon each other to be present.

Composite business processes should be able to support the infrastructure services like error handling and business activity monitoring services in a decoupled fashion without depending on the participating application or the AIA functional process flows.

For example, order capture applications should be able to keep taking orders regardless of whether the back end systems such as order fulfillment systems are available at that time. You do not want the order capturing capability to be stopped because of non-availability of any of the services or applications participating in the execution of order fulfillment process.


- 86 -



The steps to be followed are similar to those in Developing Requester ABCS.

1. Create Project – SamplesCreateCustomerSiebelReqABCSImpl

a. Click "Project Explorer" on the left panel in the OSB console.

b. Enter the project name in the text box as SamplesCreateCustomerSiebelReqABCSImpl and click "Add Project".

2. Upload the WSDL SamplesCreateCustomerSiebelReqABCSImpl.wsdl

a. In the projects table, click the project that has just been created.

b. From “Select Resource Type” options, select WSDL.

c. Click Browse and navigate to the path in the file system to find SamplesCreateCustomerSiebelReqABCSImpl.wsdl. Click Save.

d. To resolve the conflicts, upload all the files that are referenced by SamplesCreateCustomerSiebelReqABCSImpl.wsdl.

Runtimefault.wsdl,



e. Upload CmuAccsyncAccountIo.xsd into the folder SamplesCreateCustomerSiebelReqABCSImpl.

f. Go back to project folder, drill down into WSDL SamplesCreateCustomerPartySiebelReqABCSImpl.wsdl and go to the Edit References screen.

For each resource type, WSDL and XSD, click Browse and select an appropriate

resource from the browser list displayed by the 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">



<operation name="CreateCustomer">


soapAction="CreateCustomer"/>


- 87 -

<input>


</input>

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

4. Create the Proxy Service SamplesCreateCustomerSiebelReqABCSImpl in the project folder


b. Name it SamplesCreateCustomerSiebelReqABCSImpl.

c. Select the Service Type as Web Service.

d. Click Browse and select SamplesCreateCustomerSiebelReqABCSImpl.wsdl from the list of registered WSDLs.

e. In the Select a WSDL Definition window, select the binding – SamplesCreateCustomerSiebelReqABCSImplBinding.

f. Protocol – select http from the drop down

g. EndPoint URI - The end point URI is the URI used by the client for accessing the service.Provide the service name as the endpoint URI.



XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl

XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM_Custom.xsl

6. Make the following changes to the XSL resources.

a. In the node selection xpath, / does not work always because the root node is soap:Body. 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.

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

c. Hard code the BSR values assigned to EBM Header.

d. Comment out Oracle xpath extensions such as orcl:generate-guid().

e. Comment out Xpath 2.0 functions such as xp20:current-dateTime().

f. Comment out the Xref and DVM functions.

For more details refer to the section Using AIA XPath Functions



1. Add stage XFORM ABM to EBM


- 88 -

a. To transform from ABM to EBM, use the 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 XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl as the XSLT resource and enter $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 its URI, if required.


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



Follow the instructions given in the section for developing Requester 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


Upload all the required XSLs.

Make changes to the XSLs similar to configuring the Requester ABCS

To configure the proxy service:


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


- 89 -

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.

2. Assigning EBM Header

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.

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.

c. Select the XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer.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 ABCS with Dynamic Endpoint

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


- 90 -

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 consumers 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 Requester ABCS.

For more details about setting up JMS resources, refer to Creating JMS Resources.


- 91 -

Chapter 16: Implementing Asynchronous Request –Delayed Response MEP


Introduction



Introduction

When a service provider has to take a large amount of time to process a request, how can the requester receive the outcome without keeping the requester in a suspended mode during the entire processing?

For example, the order capture application submits a request for fulfillment of an order. The order fulfillment process itself could take anywhere from several minutes to several days depending upon the complexity of tasks involved. Even though the order capture application would like to know the outcome of the fulfillment request, it cannot afford to wait idly until the process is completed to know the outcome.

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.


- 92 -

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

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

m:WSAddress/wsa:ReplyTo/wsa:ServiceName



The steps to be followed are similar to Developing Requester ABCS.

1. Create project – SamplesAsyncCreateCustomerSiebelReqABCSImpl

a. Click Project Explorer on left panel in the OSB console

b. Enter the project name in the text box as SamplesAsyncCreateCustomerSiebelReqABCSImpl and click Add Project.

2. Upload the WSDL SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl

a. In the projects table, click the project that has been just created.

b. From Select Resource type options, select WSDL.

c. Click Browse and navigate to the path in the file system to find SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl. Click Save

d. In order to resolve the conflicts, upload all the files that are referenced by SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl.

Runtimefault.wsdl,



- 93 -


e. Upload CmuAccsyncAccountIo.xsd into the folder SamplesAsyncCreateCustomerSiebelReqABCSImpl.

f. Go back to project folder, drill down into the WSDL SamplesAsyncCreateCustomerPartySiebelReqABCSImpl.wsdl and go into the Edit References screen.

g. For each resource type, WSDL and XSD, click Browse and select an appropriate resource from the browser list displayed 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">



<operation name="CreateCustomer">


soapAction="CreateCustomer"/>

<input>


</input>

<output>


</output>

</operation>

</binding>

4. Create the Proxy Service SamplesAsyncCreateCustomerSiebelReqABCSImpl in the project folder


b. Name it SamplesAsyncCreateCustomerSiebelReqABCSImpl.

c. Select the Service Type as Web Service.

d. Click Browse and select SamplesAsyncCreateCustomerSiebelReqABCSImpl.wsdl, from the displayed list of registered wsdl s.

e. From the pop-up, select a WSDL Definition and select the binding – SamplesAsyncCreateCustomerSiebelReqABCSImplBinding

f. Protocol – select http from the drop down

g. EndPoint URI - The end point URI is the URI used by the client for accessing the service. In this sample, provide the service name as the endpoint URI.



XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl


- 94 -

XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM_Custom.xsl

b. Make the following changes to the XSL resources:

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 extensionssuch as orcl:generate-guid()

Comment out Xpath 2.0 functions such as xp20:current-dateTime()

Comment out the Xref and DVM functions

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



1. Add stage XFORM ABM to EBM

a. To transform from ABM to EBM, use the 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 XformListOfCmuAccsyncAccountIoToCreateCustomerPartyListEBM.xsl as the XSLT resource and enter $body as the binding input



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


a. Add Route Node to EBS

b. Edit the Route Node to invoke the SamplesCustomerPartyEBS proxy service invoking the operation CreateCustomerParty

Error handling in Requester ABCS



- 95 -


Follow the instructions for developing Requester 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


Upload all the XSL s required

Make changes to the XSLs similar to configuring the Requester ABCS

To configure the Proxy Service:


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. Enter $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 must be

defined.



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

3. Add stage XformCreateCustomerPartyListEBMToPcmOpCustCommitCustomer

a. Use the 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 XSLT resource and enter $body as the binding input

4. To compute the dynamic endpoint location, and route to it, follow the steps 2,3, and 4 of Developing Provider ABCS with Dynamic Endpoint.

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


- 96 -

5. Error Handling

a. In the response actions, check for the Fault element in the response actions of the route node.

b. If the Fault element is present, raise an error with business error code and the business error message.

6. Transform 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 a 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 WSDLs has the binding CustomerPartyResponseEBSBinding added to it.

When configuring the proxy service, select the CustomerPartyResponseEBS.wsdl, and select the binding CustomerPartyResponseEBSBinding.

For more information about configuring the CustomerPartyResponseEBS for the Dynamic Routing see Configure the Route Node in the Message Flow of EBS

The dynamic XQuery is shown 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()='PRODUC

TION' or

not($CreateCustomerPartyListResponseEBMVar/corecom:EBMHeader/corecom


- 97 -

:MessageProcessingInstruction/corecom:EnvironmentCode/text())) and

($CreateCustomerPartyListResponseEBMVar/corecom:EBMHeader/corecom:Se

nder/corecom:WSAddress/wsa:ReplyTo/wsa:ServiceName

='SamplesAsyncCreateCustomerSiebelRespABCSImpl'

<dynamicservice>

<servicename>SamplesAsyncCreateCustomerSiebelRespABCSImpl/SamplesAsy

ncCreateCustomerSiebelRespABCSImpl</servicename>

<operationname>CreateCustomerResponse</operationname>

<servicetype>proxy</servicetype>

</dynamicservice>

else if($CreateCustomerPartyListResponseEBMVar

/corecom:EBMHeader/corecom:MessageProcessingInstruction/corecom:Envi

ronmentCode/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)


- 98 -

Chapter 17: Logging Messages in OSB

This chapter includes the following section:

Configuring Oracle AIA Processes for Trace Logging

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.

Use the logging actions:

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 you can use it to log trace messages.

isTraceLoggingEnabled Custom XPath Function

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


- 99 -

Finer

Finest

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


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 you can log trace messages. The following functions are available through the trace logging Java API:


- 100 -

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.


logLevel


Severe

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.


level


Severe

Warning

Info

Config

Fine

Finer

Finest

ebmHeader

EBM header.

message

Verbose text message to be logged.


- 101 -

Chapter 18: Error Handling in OSB


Configuring Oracle AIA Processes for Error Handling

Configuring OSB Services to Adhere to Error Handling Requirements


Configuring Oracle AIA Processes for Error Handling

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.


This section provides an overview of OSB error handling and discusses 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 because OSB does not 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.


- 102 -

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.

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

If route is used to invoke a service, then the 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


This section discusses the standard configuration steps that need to be performed when you are handling an OSB error.

This section discusses how to:

Define notification roles.

Define corrective action codes.

Define error message codes.

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


- 103 -

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 Fusion Middleware Infrastructure Components and Utilities User's Guide for Oracle Application Integration Architecture Foundation Pack, "Setting Up Error Notifications and Logging ," Setting Up Error Notifications for Oracle AIA Processes

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:

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.

If ERROR_CODE, SERVICE_NAME, and PROCESS_NAME are available and map to an

entry in the table, use it.

If SERVICE_NAME and PROCESS_NAME are available and map to an entry in the table,

use it.

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


- 104 -

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:

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

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


- 105 -

Note: OSB invokes AIA error handler for single view of errors as well as they can be re-

submitted. The link in the error notification will be broken because OSB does not have instance

level monitoring.


- 106 -

Chapter 19: 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

Message Content

Handling

Transaction

Required

Enabled

Same Transaction

for Response

Enabled

JMS Transport

Configuration

Destination Type Queue


- 107 -

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

Response URI It will be used only in

exceptional cases

Response

Connection Factory


exceptional cases

Response Message

Type


exceptional cases

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


- 108 -

Business Service

Transport

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


- 109 -

Appendix

This appendix contains the following sections:

Uploading AIA Components as a Zipped File

Updating the WSDL from Enterprise Services Library for Creating OSB Service

Creating JMS Resources

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)

To upload AIA components as a zip file using the OSB console:

1. Select a project folder where you 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.


- 110 -

4. On Review Loaded Resources page, click Import.

Updating the WSDL from Enterprise Services Library 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 details of bindings before they can be used for creating OSB artifacts – business service/proxy service. In OSB 11g, all operations in the wsdl need to be updated with binding before they can be used for creating services.

Note: OSB can only create services from WSDLs that have binding or port. AIA recommends that

bindings be added to the ESL. AIA recommends SOAP as the binding to be used.


- 111 -

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



<operation name="QueryCustomerParty">


soapAction="SamplesQueryCustomerParty"/>

<input>


</input>

<output>


</output>

</operation>

</binding>

Add the above binding section after all the PortTypes in the WSDL.

Creating SB Configuration Jar File for AIA Components

To create a jar file for AIA components:

1. Upload the AIAComponents.zip file, resolve the conflicts, and update the WSDL with the information for binding.

2. Save all the changes by selecting Activate in the change center.

3. Click System Administration and select Export Resources. Select Include Dependencies.

4. From the Resource Summary, select the resource folder holding AIA components and click the 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,


- 112 -

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 Chapter 19: OSB Service Configuration

Creating JMS Resources

To create the JMS assets, using the WebLogic console, you need to:

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

How to Create a 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.

How to Create 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 must 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 to add resources to the JMS system module and click the Finish button.

How to Add Resources to the JMS System Module

1. In the page, Summary of Resources for the AIAJMSResources, click the New button. In the next window, select the Connection Factory radio button for the type of resource to create. Click the Next button.

2. Name the connection factory AIAConnectionFactory and set the JNDI Name to the same value.

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.


- 113 -

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 is a transaction associated with the incoming message, use EXACTLY_ONCE. OSB uses 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.


- 114 -

White Paper :Guide to Implementing Application

Integration Architecture on Oracle Service Bus

March 2011

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

Guide to Implementing Application Integration Architecture - Oracle

Documents

Transcript of Guide to Implementing Application Integration Architecture - Oracle