OracleWorld 2002 Whitepaper Session 32781
Leveraging Oracle9IAS Web Services in the Oracle E-Business Suite: An Integration Strategy
Update: The proposed Integration Gateway is what is now known as the Oracle E-Business Suite Integrated SOA Gateway.
How to Effectively Monitor SD-WAN and SASE Environments with ThousandEyes
OracleWorld 2002 Whitepaper Web Services in E-Business Suite
1. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
LEVERAGING ORACLE9IAS WEB SERVICES IN THE ORACLE
E-BUSINESS SUITE: AN INTEGRATION STRATEGY
Rajesh Raheja, Oracle Corporation
Stefan Kiritzov, Oracle Corporation
OVERVIEW
If we cut through the hype, Web services are a set of distributed computing technologies, which promise major
benefits to enterprise software development teams, consulting teams, and customers alike. These benefits include
peer-to-peer interaction and interoperability across data formats, languages, operating systems, object models, and
platforms. However, realizing these benefits requires us to delve deeper than the simple examples currently offered by
toolkit vendors. Rather, we need to focus on more strategic issues involved in the standards-based business
collaboration and the end-to-end business process management of long running transactions.
The goal of this white paper is to describe how the consolidation of the various technologies available within the
Oracle9i Application Server (Oracle9iAS) and the Oracle E-Business Suite will provide an integration strategy in the
context of Web services. As Oracle9iAS Web Services provides the base technology stack and tools, this paper
explains how E-Business Suite technologies such as Oracle Workflow, Business Event System, XML Gateway, and
Web Services technologies complement each other to provide support for complex business Web Services. It first
gives an overview of the technology and explains the detailed architecture of the components involved. It then
proceeds to explain how the various artifacts could be used as Web services. Finally, it describes how to invoke Web
services or Enterprise JavaBeans (EJB) from within the Oracle E-Business Suite.
Note: This paper represents the strategy and direction of the integration technology, which will be made available over upcoming releases of
the Oracle E-Business Suite.
THE ORACLE E-BUSINESS SUITE INTEGRATION APPROACH
ORACLE E-BUSINESS SUITE INTEGRATION GATEWAY
The Oracle E-Business Suite Integration Gateway provides a cohesive functionality and manages all documented
external interfaces – whether based on APIs or Extensible Markup Language (XML).
Oracle E-Business Suite Integration Gateway
Paper 32781
2. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
It builds on top of the base technologies and tools provided by the Oracle E-Business Suite technology stack and
Oracle9iAS Web Services; and interfaces with Oracle9iAS Integration for integration with other ERP/CRM software
or legacy systems.
The Oracle E-Business Suite Integration Gateway provides the following features:
• Exposes key integration points within the Oracle E-Business Suite
• Based on open standards:
o Simple Object Access Protocol (SOAP) and SOAP with Attachments
o Web Service Definition Language (WSDL)
o Universal Description, Discovery and Integration (UDDI)
o Extensible Markup Language (XML)
o Multipurpose Internet Mail Extensions (MIME)
o Java API for XML Messaging (JAXM)
o Java API for XML-Based Remote Procedure Calling (JAX-RPC)
o Java Message Service (JMS)
o Enterprise JavaBeans (EJB)
o J2EE Connector Architecture (JCA)
• Repository of Web services and/or EJBs exposed by the E-Business Suite
• Supports both Remote Procedure Calling (RPC) or XML document-style communication
• Access control for exposed Web services and/or EJBs associating them to E-Business Suite Roles
• Repository of business events and XML Document Type Definitions (DTD) - Open Applications Group (OAG),
commerce eXtensible Markup Language (cXML), etc. - that are exposed by the E-Business Suite
• Builds standards-compliant public document definitions via the Message Designer tool with minimal coding
• Repository of invocations or callouts to other Web services or EJBs
• Support transformation maps for converting incoming and outgoing messages to and from the target public
service definitions
• Interfaces with Oracle9iAS Integration via the JCA Connector for Advanced Queues and Web Services
ORACLE E-BUSINESS SUITE INTEGRATION GATEWAY COMPONENTS
The Oracle E-Business Suite Integration Gateway components interact with each other and with Oracle9iAS
Integration and Oracle9iAS Web Services. They expose the key integration points in two ways:
• XML Documents: standards based business object documents produced via business events
• API: Web services or EJB APIs
The relationships between these technologies and their components are shown in the following diagram.
Paper 32781
3. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
Oracle E-Business Suite Integration Gateway Components
WEB SERVICES INVOCATION CLIENT API
It is not technically feasible for applications within large, complex enterprise systems such as the Oracle E-Business
Suite to use "hard coded" invocations to external systems. . Likewise, customers and consultants need the ability to
modify invocations if there should come the time to point to newer, cheaper, or better Web Services. For example, a
purchasing team wanting to invoke a tax calculation service should not be expected to hard code their product to only
that particular vendor. Furthermore, even minor changes to a Web service may require recompilation of the invoking
product source code. Considering the almost 200 products in the E-Business Suite, that strategy does not scale well.
Therefore, the main function of callout API is to provide controlled, standards-based access to data resources outside
of the application module.
SERVICE REPOSITORY
REGISTERING WEB SERVICES AND EJB APIS – THE SERVICE RECORD
The service repository is the single source of truth about all the Web services exposed by or invoked from the Oracle
E-Business Suite. The services can be registered manually or uploaded from the deployment descriptor generated by
the Oracle9iAS Web Services. See the following screenshot for an example.
The services can be any of the following:
• Java classes exposed Web services
• Workflow processes
• XML documents generated or consumed by the XML Gateway
• EJBs
Paper 32781
4. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
Service Repository showing a java entry
This allows for both RPC-style and Document-style interfaces to the Oracle E-Business Suite. The service record has
basic information about the Web service, such as name, description, type, WSDL, and access control information.
This ensures that only registered Oracle E-Business Suite users with the appropriate roles can invoke that particular
Web service. Services can also be designated as public services, which are not authenticated. The Service Repository
can potentially be stored in an extended version of the Oracle9iAS UDDI registry.
REGISTERING INVOCATIONS – THE INVOCATION RECORD
The service repository is also the single source of truth about the Web Services, third-party EJBs, or third-party APIs
being invoked by the Oracle E-Business Suite. The Web services invocation client API and the runtime layer use the
invocation record entry in the service repository for invoking the services.
If needed, the invocation record entry can be later customized to change the network address or other details of the
invocation. This allows for an abstraction that shields developers from the external public definition. For example, if a
new input parameter is required for a Web service, it could be given a default at the invocation record, thereby
requiring no changes to the calling application. The following screenshots relate to the invocation record:
Paper 32781
5. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
Invocation Record for getAddress Web Service showing parameter mappings
The invocation record contains the following information:
• The name, input parameters and return type for invoking the external service
• The type of external service (for example, Web service or Java/EJB call)
• The target endpoint address URL
• Security credentials needed by the external service, such as user name and password
• Detailed parameter information and default values
• The WSDL
Some of the information in the invocation record may be automatically populated if it is available in the WSDL.
Thus, the invocation record acts as the “deployment descriptor” for a given callout, which is used by the runtime layer.
The abstraction also allows for changes to the service provider should a new service provider be desired for the
services being invoked. For example, assuming similar implementation interfaces between the two services, you can
switch the “getStockQuote” service from Lycos to Yahoo!, without making any changes to the calling application. You
can do this because all binding information is stored in the invocation repository.
Finally, the abstraction is forward thinking. It allows for invocations to not only Web services, but also to any service
that may be introduced in the future. For example, if the external service is a remote EJB or Java program, it can be
invoked directly instead of making a Web service call. It provides the required mediation between the external call and
the internal business object definition, transforming the request and reply messages as appropriate for the destination
call. The service repository therefore contains a superset of UDDI information, due to the mapping functionalities
available in the runtime engine.
Paper 32781
6. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
ORACLE WORKFLOW ®
WORKFLOW ENGINE
Oracle Workflow is a complete business process management system that supports business event-based and business
process-based definition, automation, integration and collaboration. Its technology enables the modeling, automation,
and continuous improvement of business processes, routing information of any type according to user-defined
business rules. Oracle Workflow is a scalable, production workflow system tuned for the high volumes associated with
enterprise applications and long-lived transactions. Oracle Workflow supports traditional application workflows such
as business document approvals, as well as systems integration workflows. It is the engine that provides the long
running transaction support, asynchronous messaging support and complex Web services support for the Oracle E-
Business Suite. The following illustrations are a flowchart of an example Workflow process and a screenshot where a
Workflow process is being monitored.
Example Workflow process for approving a Purchase Requisition.
Monitoring a workflow process at runtime
E-business is accelerating the demand for integration of applications within the enterprise, as well as integration of a
company's systems with trading partners and business-to-business exchanges. Oracle Workflow is unique in providing
a workflow solution for all integration locales: internal processes, business process coordination between applications,
and choreography of Web services. In addition, since the engine resides in the Oracle 9i database, it inherently
supports industry-leading Oracle9i operational characteristics such as high availability, disaster recovery, scalability,
performance, security, and auditing.
ORACLE WORKFLOW BUILDER
Oracle Workflow Builder enables the modeling of sophisticated business processes such as looping, branching, and
rendezvous in a graphical workflow builder.
Additionally, Oracle JDeveloper E-Business Integration uses Oracle Workflow to manage complex user-based
business processes, such as the routing through decision and synchronization points. A JDeveloper UML Activity
Paper 32781
7. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
diagram can contain many integration, decision, and synchronization points. The UML Activity Modeller has the
ability to generate workflows for each individual integration, decision, and synchronization point, and then merge
them together into one workflow for the entire diagram. A screenshot of Oracle Workflow Builder is provided below.
Oracle Workflow Builder
BUSINESS EVENT SYSTEM
The Oracle Workflow Business Event System is an application service that leverages the Oracle Advanced Queuing
(AQ) infrastructure to communicate business events between systems. It consists of the Event Manager and event
activities that represent business events within workflow processes. See the following Event Manager screenshot:
Event Manager Architecture
Paper 32781
8. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
The Event Manager contains a registry of business events, systems, named communication agents within those
systems, and subscriptions indicating that an event is significant to a particular system. Events can be either raised
locally or received through AQ from an external or local system. When a local event occurs, the subscribing code is
executed in the same transaction as the code that raised the event, unless the subscriptions are deferred. To minimize
costly processing, the Event Manager checks whether event information is required by subscriptions on the event
before producing the XML event message.
The Business Event System uses Oracle Advanced Queuing to propagate messages between communication points on
systems, called agents, using a specified protocol. Events received from external systems are processed by an agent
listener that runs on the agent's queue.
XML GATEWAY
XML Gateway is the message generation and consumption engine of the Oracle E-Business Suite Integration
Gateway, which provides a standards-based application view of the XML messages exposed by the E-Business Suite
through business events. It also provides message transformation services for converting the public definition of the
message to the internal object definition (for example, database tables and PL/SQL procedures).
When an application workflow process raises a business event that has an associated message payload, XML Gateway
generates the XML message based on the subscriber properties. The subscribers may be other Workflow processes, E-
Business Suite modules, or external systems. When an XML message is received from a trading partner, the XML
Gateway consumes the XML message and raises a business event to notify any waiting subscribers of the message
arrival.
The message definitions and mappings are registered using the XML Gateway Message Designer tool, which allows
for graphical modeling of standards-based XML messages from the database repository. It has drag-and-drop
capabilities and allows some basic transformations (mathematical, string, OAG, cXML) to formulate documents that
are based on a Document Type Definition (DTD) or XML Schema definitions.
The XML Gateway Message Designer tool can be used for the following mappings:
• To and from the database and the Oracle 9iAS Integration Platform required application view XML format
(OAG/cXML/custom)
• To and from the database or Java object and the WSDL schema section
• To and from the internal object XML format and the public standard OAG or cXML business object document
format
See the following screenshot, which depicts a sample XML Gateway Message Designer transformation.
Paper 32781
9. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
XML Gateway Message Designer Transformation Example for an OAG Document
ORACLE 9IAS INTEGRATION
Oracle9iAS Integration is a complete e-business integration solution delivered as an integral feature of Oracle9iAS. It
provides an open, standards-based infrastructure for enterprise application integration (A2A), business-to-business
(B2B) collaboration, and Web services integration in a single product. The J2EE-based implementation fully leverages
the infrastructure of Oracle9iAS to deliver enterprise-strength performance, scalability, and manageability.
Furthermore, tight integration with the Oracle E-Business Suite Integration Gateway makes it the best solution for
integrating the Oracle E-Business Suite with third-party packaged applications, B2B protocol standards, and Web
services. Oracle9iAS Integration is tightly integrated with Oracle Workflow to provide business process management
and true process-driven integration solutions. A custom “browser” for the Oracle9iAS Integration Studio provides the
Oracle E-Business Suite “view” of the messages and APIs available to connect to for A2A or B2B integration.
Paper 32781
10. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
ORACLE E-BUSINESS SUITE INTEGRATION GATEWAY ARCHITECTURE
The layers of the Oracle E-Business Suite Integration Gateway architecture are shown in the following figure.
Oracle E-Business Suite Integration Gateway Architecture
The business events raised by the Oracle E-Business Suite applications exposes the key integration points in the
repository layer, which contains all the information needed for business process management, documents for business
collaboration, and Web services API and invocation information.
The runtime layer contains the actual workflow engine for business process management, long running transactions,
complex web services, and business collaboration. It also hosts the Business Event System for raising events and
registering subscriptions, which could invoke the XML generation and consumption services to expose standards-
based business object documents. The runtime layer also performs the authorization functions for ensuring that the
user has the appropriate roles to invoke a given Oracle E-Business Suite service.
In addition, the runtime layer performs another key function; it mediates the transformation of the incoming request
format from the public format to the internal object format. It also transforms the outgoing request from the internal
object format to the public format. For example, it would perform the transformation from the public WSDL OAG
document definition of the "createPurchaseOrder" service as input to the internal XML format required by the EJB or
PL/SQL procedures and/or database tables for processing by the E-Business Suite.
The transport layer allows the Web services to be exposed via various protocols, such as HTTP for synchronous RPC
calls and JMS or Advanced Queuing (AQ) for asynchronous RPC calls or XML Document-based services.
The Oracle Applications Manager is an enterprise management console, which allows for monitoring and
administration activities related to the background services needed by the various components of the Integration
Gateway. It is integrated with Oracle Enterprise Manager for raising alerts if an outage occurs in the background
services.
Paper 32781
11. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
EXPOSING ORACLE E-BUSINESS SUITE FUNCTIONALITIES AS WEB SERVICES
EXPOSING ORACLE E-BUSINESS SUITE APIS AS WEB SERVICES
JAVA, PL/SQL, BC4J AND EJB APIS
Application APIs can be exposed as Web Services directly by using the Oracle9iAS Web Services platform. All native
sources supported by Oracle9iAS Web Services can be used, such as Java, Stateless Session EJB, Stateful Session EJB,
or PL/SQL. Service definitions can be manually recorded in the service repository, or uploaded from the deployment
descriptor generated by Oracle9iAS. A developer would use the following steps to expose an API:
1. Write the service code in any native format that is supported by Oracle9iAS Web Services.
2. Deploy the service as a Web service using Oracle9iAS.
3. Upload the Web service deployment descriptor for the service in the service repository.
4. Assign the required access control to the service within the Oracle E-Business Suite.
Note that PL/SQL APIs have to be wrapped in Java before being exposed as described above. The JDeveloper wizard
automatically does this, although there are limitations on the type of procedures that can be wrapped.
EXPOSING WORKFLOW, BUSINESS EVENT SYSTEM, AND XML GATEWAY APIS AS WEB SERVICES
Most Oracle E-Business Suite applications utilize Oracle Workflow technology to create business processes and
business services by managing long running stateful business transactions. These processes can easily be deployed as
Web services, by simply exposing Workflow APIs as Web services.
The following Web services will be provided out of the box, allowing another application to invoke the features using
a standard Web Service interface:
• Start, abort, suspend, or resume a workflow process
• Get the current status and attribute values for a given workflow process
• Restart a given workflow process activity with a given outcome
• Raise a business event
• Receive any business object document (for example, a purchase order as a business event payload)
EXPOSING WORKFLOW PROCESSES AS WEB SERVICES
An individual workflow processes can be exposed as a Web service. When a developer selects which process to
expose, it is automatically registered in the service repository so that access controls can be set up. This allows B2B
transactions for initiating individual processes.
Paper 32781
12. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
This option allows the maximum flexibility from an E-Business Suite perspective, and leverages the existing
investments that customers have with Oracle Workflow, Business Event System and XML Gateway. It gives product
teams and consultants a way of developing complex, long-running stateful business transactions using a familiar,
proven technology and then deploys it as a Web Service with no additional coding!
Supplier Order Process – shown within the Workflow Builder – could be directly deployed as a Web Service
In addition, a WSDL file can be generated for each workflow process from the Workflow engine metadata. The
metadata is strongly typed for that particular workflow process (for example, supplier name, P.O. amount, etc.). This
is different from the generic name-value API definitions, which are exposed by the Workflow APIs themselves. See
the screenshot above for a process, which can be a candidate for deployment as a Web service.
Next, the Web service takes the data required by the workflow process as the input message and hands over the
processing of the incoming request to the Oracle Workflow engine.
EXPOSING XML MESSAGE TRANSACTIONS AS WEB SERVICES
Each XML message (representing a business object document) that is being generated or consumed by XML Gateway
can be exposed as a Document-style Web Service. Incoming documents can be easily exposed as a Web service by
registering them in the service repository. This can generate a strongly typed WSDL for that particular transaction (for
example, Create Purchase Order) which contains the DTD or XML Schema definition of the OAG document that
XML Gateway expects for the inbound message processing.
Note: This functionality is implemented as a standard Web Service servlet, which would supersede the current Oracle Transport Agent
(OTA) feature of XML Gateway.
Paper 32781
13. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
EXPOSING SERVICE BEANS AS WEB SERVICES
Service Beans are message-based objects that are similar to J2EE Message Driven Beans. They provide a “chunky”
network resource-friendly API which acts as a single choke point for all application APIs. They can be used from user
interfaces to provide for page-by-page retrieval of data (e.g. “getWorklist”), and can also be exposed as Web services.
You can utilize the service description metadata to generate a strongly typed WSDL specific to a given Service Bean;
the runtime engine invokes the appropriate Service Bean given an incoming Service Bean request. Alternately, you can
expose a public interface definition describing the Service Bean as you would with any other Java/EJB API. Either
way, a strongly typed interface is generated for the Service Bean.
INVOKING WEB SERVICES FROM THE ORACLE E-BUSINESS SUITE
WEB SERVICES INVOCATION CLIENT API
USAGE
The Invocation Client API is a set of Java API calls that allow developers to invoke Web services (or calls to any other
third party-services), synchronously or asynchronously. It uses the information from the invocation repository to
initiate the callout.
The synchronous API is equivalent of a normal Java method call. The asynchronous API queues the request and
returns back a ticket, which can be used later to retrieve the invocation result. Optionally, a callback can be registered,
which is called back with the invocation result and the calling context.
Application modules would use the Invocation Client API if other wrappers - such as the Workflow Activity, Event
Subscription, or XML Gateway document transport - do not satisfy the requirement.
It is important to note that an invocation is a specific information request from one application module to another.
The calling application typically expects back a strongly typed data object (e.g. calculated tax for a purchase order), as
opposed to business events, which are “signalled” by applications (e.g. purchase order created) so that registered
subscribers receive and process events as appropriate.
CLIENT API FEATURES
The following features are available as part of the Invocation Client API:
• Provides metadata-driven runtime service binding for all invocations or callouts
• Performs transformations of the outgoing invocations and incoming requests to match internal object formats
• Resolves invocations or callouts to Web services and Java programs or EJBs
• Provides message-based mapping to target message formats (e.g. OAG or cXML documents, WSDL)
• Can be used in either synchronous (blocking) or asynchronous (non-blocking) mode
Paper 32781
14. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
INVOKING WEB SERVICES FROM WORKFLOW
Oracle Workflow supports the realization of complex, long running stateful business processes. You can use
Workflow to not only implement complex Web services by deploying individual workflow processes, but also to
manage the interaction of multiple simple Web services, as shown in the following screenshot.
Invoking a Web Service from Oracle Workflow Builder
To this effect, Web services can provide the implementation for a given workflow process activity: the Invoke Web
Service standard process activity is dragged into any workflow process to provide the input required by the Web
Service as activity attributes. The activity internally uses the Invocation Client API to make the external call.
INVOKING WEB SERVICES AS AN EVENT SUBSCRIPTION
A Web service invocation can also be registered as a subscription to a business event. Here, the subscription contains
the pointer to the invocation record, and the event parameters serve as input to the Web service. The default rule
function identifies the subscription as a Web service invocation, and initiates the invocation call.
PUBLISHING XML DOCUMENTS OVER WEB SERVICES TO TRADING PARTNERS
When an application raises a business event and generates a standard business object document using XML Gateway,
it can delivere it to an external system, which has registered a transaction to receive the message as a document-style
SOAP request. To enable this, the Web service call is made using the Invocation Client API passing in the XML
message. In case complex transformations for multiple Trading Partners is needed or the transport format is not via
Web services (perhaps it is by another ERP system or legacy system), then the message is handed over to the
Oracle9iAS Integration Platform to perform the necessary data transformation and protocol conversions.
Paper 32781
15. Oracle9iAS Web Services: An Integration Strategy for the Oracle E-Business Suite
SUMMARY
KEY FEATURES
• Combines the proven business process management technology of Oracle Workflow with Web services
• The industrial strength Workflow engine handles long running transactions and business collaboration
• Provides message generation and consumption engine for OAG and cXML business object documents
• A graphical message mapping tool performs lightweight mapping of E-Business Suite objects to XML
• Supports wrapping Workflow processes, XML message transactions, and Service Beans as Web services
• Offers a graphical Workflow process modeling tool to model and choreograph Web services flow
• Web Services or EJBs can be invoked from Workflow processes
• An abstraction layer transforms incoming and outgoing messages to and from the public service definition
• Supports XSLT style sheets for message transformations
• Provides authorization of Web services or EJBs based on Oracle E-Business Suite Roles
• Provides synchronous and asynchronous APIs for invoking Web services described in the service repository
• It is fully supported with the latest versions of Oracle9iAS certified with the Oracle E-Business Suite
CONCLUSION
By utilizing components in the Oracle E-Business Suite and Oracle9iAS, Oracle enables Web services that are backed
by a proven set of technologies. With little initial effort and the ability to use the workflows, business events, standard
OAG/XML business object documents, APIs, and EJBs that you already have, you can quickly and easily implement
complex Web services. The Oracle E-Business Suite Integration Gateway collates the suite's components into a
comprehensive integration point. It exposes outbound business events as XML business object documents and
inbound RPC/document-style Web services.
The Oracle E-Business Suite Integration Gateway allows the key integration points to be exposed directly as Web
services by utilizing Oracle9iAS Web Services. It also integrates Web services with the Oracle 9iAS Integration
Platform JCA adapter to satisfy complex corporate integration needs.
Paper 32781