Oracle Retail

How to Create PL/SQL Web Service Providers Using Oracle Retail SOA Enabler and Oracle Retail Artifact Generator June 2010

Note: 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 Oracles products remains at the sole discretion of Oracle.

Contents
Preface ......................................................................................................................................1 Support Notice .................................................................................................................................. 1 Using this Document........................................................................................................................ 1 Reference Documents....................................................................................................................... 1 Introduction ..............................................................................................................................2 Tool Overview and Relationship ............................................................................................3 Artifact Generator Inputs and Outputs ......................................................................................... 4 Inputs............................................................................................................................................... 4 Outputs............................................................................................................................................ 4 RSE Inputs and Outputs .................................................................................................................. 4 Inputs............................................................................................................................................... 4 Outputs (a .zip file)........................................................................................................................ 4 PL/SQL Web Service Provider Use Case Approaches.........................................................5 Current Version Use Case New Service ..................................................................................... 5 Scenario ........................................................................................................................................... 5 Approach......................................................................................................................................... 5 Back Version Use Case New Service........................................................................................... 7 Scenario ........................................................................................................................................... 7 Approach......................................................................................................................................... 7 Current Version Use Case Extend Existing Web Service Provider Use Case ....................... 8 Scenario ........................................................................................................................................... 8 Approach......................................................................................................................................... 9

Preface
This document discusses how to create PL/SQL Web service providers using Oracle Retail SOA Enabler and Oracle Retail Artifact Generator. Before attempting to download, install, and configure the required tools for this process, understand the information in this Preface, especially the following Support Notice.

Support Notice
The customization and extension of Oracle Retail base products and messages, and the integrations created by these tools are not supported by Oracle Retail, including My Oracle Support. This white paper aims to mitigate the risks of unsupported customization by providing guidance and references for how to attempt to customize safely and effectively. The tools and approaches described in this document are complex and require a high level of skill and knowledge of the product. Any issues that may arise with custom flows, custom APIs, or customized message families are the responsibility of the customer and not Oracle Retail. The Retail SOA Enabler (RSE) tool and the Artifact Generator (AG) tool require the 13.1.x GA business objects. The tool support does not extend to the use of the output beyond the normal support that any tool has; it must conform to its own specifications and documentation.

Using this Document

Before completing the process described in this document, do the following tasks.
1. 2.

Download, install, and configure the Service-Oriented Architecture Enabler Tool and the Functional Artifact Generator. Search My Oracle Support for any patches pertaining to both tools.
Note: It is likely that patches exist for these tools.

3.

Carefully read the documentation for each tool. The process included in this document does not replicate existing information about the tools; rather it refers to specific sections within respective documents.

Reference Documents
See the following documentation for supporting information. Oracle Retail Service-Oriented Architecture Enabler Tool Guide Oracle Retail Functional Artifact Guide Oracle Retail Functional Artifact Generator Guide Oracle Fusion Reference Architecture (Overview) Oracle Practitioner Guide Software Engineering in an SOA Environment Oracle Retail Merchandising System documentation

How to Create PL/SQL Web Service Providers Using Oracle Retail SOA Enabler and Oracle Retail Artifact Generator 1

Introduction
The Retail Service Oriented Architecture Enabler (RSE) tool is used to create the following: Web service provider end-points Consumer clients for Web service providers Templates for the PL/SQL APIs and Java EE APIs that interface with them.

The RSE tool is designed to provide a standards-based way to consistently develop Web services for PL/SQL and Java EE applications that allows exposure to their business logic. Development is focused on the business logic code, not the Web service infrastructure. The tool produces design time and run time artifacts. RSE works in conjunction with another Oracle Retail tool, the Retail Functional Artifact Generator (AG). The AG is a collection of tools designed to create the various artifacts used within the Oracle Retail messaging infrastructure from an XML schema (XSD). These XSDs are called Business Objects. They represent the functional definition and technical structure of a Retail Business Entity.
Note: See Reference Documents.

The purpose of this document is to discuss how the PL/SQL features of the RSE and Artifact Generator tools can be used to create new Web service providers to: support new functionality in a PL/SQL application. customize and extend an existing PL/SQL Web service provider.

2 Oracle Retail

Tool Overview and Relationship

The RSE and AG are companion tools, particularly in the creation of Web service providers. Generally available documents exist for each tool, describing installation, configuration, and use--as well as extensive examples. These documents, combined with the Oracle Retail Integration Bus Implementation Guide, cover the recommended practices and provide examples for customizing business objects. With each release, Quality Assurance testing is completed on the tools and associated documentation, including each example cited. The RSE and AG tools work only with Oracle Retail business objects, release 13.1.x (and higher). They do not work with objects from earlier releases (for example, 13.0.x and 12.x). This restriction is due to the uptake of Business Object standards that support versioning and customization and extension. The tools enforce this separation and will not permit anything except the best practices documented in the Oracle Retail Artifact Standards. This rule helps to preserve changes when a new release is issued. When applying business object upgrades, customers can easily preserve changes by simply reapplying them over the new base objects.
Note: See the Oracle Retail Service-Oriented Architecture Enabler Tool

Guide and the Oracle Retail Functional Artifact Generator Guide for installation and configuration instructions The AG is designed to allow customers to create extensions to base objects using the specified hooks, or to create entirely custom objects that meet Oracle Retail standards. The tools enforce these standards.
Note: See the Oracle Retail Functional Artifact Guide for standards.

For the creation of a Web service provider, the RSE tool expects as one of its inputs one of the outputs of the AG tool to design time artifacts. There is a run-time relationship as well, as shown in the diagram below, which illustrates the relationship for a PL/SQL Web Service Provider.
Retail Artifact Generator
Base XSDs Extof XSDs
custom-retailpublic-payloadxml-samples.zip

Retail SOA Enabler

(PL/SQL Provider)

<service>.zip file
WSDL

Service Def

UDDI Registry
<service>.ear Run Time

Infrastructure Service (UDDI PUB) Retail SOA Enabler Retail Artifact Generator custom-retailpublic-payloadjava-beans.jar

<ServiceName>Provi derImplBody.sql

custom-retailpublic-payloaddatabase-objecttypes.zip

Design Time
<ServiceName>Provid erImplSpec.sql

retail-publicpayload-javabeans.jar

Service Def

PL/SQL App

Oracle Corporation

How to Create PL/SQL Web Service Providers Using Oracle Retail SOA Enabler and Oracle Retail Artifact Generator 3

Artifact Generator Inputs and Outputs

Inputs
The inputs to the AG are the base GA business objects, and the custom or extended base objects. The GA base objects are installed as part of the AG installation and configuration. The creation of extensions or custom XSDs is covered in the Oracle Retail Functional Artifact Generator Guide, including: Base XSDs and Extof XSDs Custom XSDs

Outputs
The following are AG outputs: custom-retail-public-payload-java-beans.jar custom-retail-public-payload-database-object-types.zip

RSE Inputs and Outputs

Inputs
The input for creating a PL/SQL service provider is a Service Definition Library XML file containing details about the Web services that must be created, the generally available business objects, and the output of the AG for extensions or custom XSDs. For example: retail-public-payload-java-beans.jar (GA Base Business Objects) ServiceProviderDefLibrary.xml custom-retail-public-payload-java-beans.jar (Custom and Extended Business Objects) from AG.

Outputs (a .zip file)

Outputs include the following: The deployable .ear with the WSDL conforming to the objects referenced in the ServiceProviderDefLibrary.xml. The PL/SQL specification and body API templates that include hooks for talking to the services. These API templates contain placeholders for business logic and references to the Oracle Object created by the AG. A copy of the ServiceProviderDefLibrary.xml. A static version of the service WSDL.

4 Oracle Retail

PL/SQL Web Service Provider Use Case Approaches

Oracle Retail Service-Oriented Architecture Enabler Tool Guide and the Oracle Retail Functional Artifact Generator Guide contain detailed examples that are not repeated here. However, they are referred to as needed in the solution approach sections.

Current Version Use Case New Service

The most common use case is using the tools in a current version release environment, where the following match to create new Web service providers based on new integration requirements: The Enterprise Release version of the AG and RSE tools The Enterprise Oracle Retail Business Objects The Oracle Retail application version

Scenario
Business analysis has determined that an external integration is needed between RMS and another system. The requirements are such that a request/response pattern is desired. RMS 13.1.1.x. RIB 13.1.1 third party systems

Approach
The steps below correspond to the following approach illustration.

How to Create PL/SQL Web Service Providers Using Oracle Retail SOA Enabler and Oracle Retail Artifact Generator 5

Complete the following steps:

1. 2.

Determine the business case during the Service Analysis Phase. During the Service Definition Phase, determine the service boundaries as well as the construction of the service contracts (XSDs).
Note: See the Oracle Practitioner Guide Software Engineering in an SOA

Environment for details on these phases.

3.

Use the Artifact Generator to extend or create the XSDs to satisfy the business case.
Note: See the Oracle Retail Functional Artifact Guide (Chapter 6,

Customization and Extension) for standards, best practices, and naming conventions. See the Oracle Retail Functional Artifact Generator Guide (Chapter 3, General Usage) for detailed examples.
4.

The outputs of the AG are artifacts appropriate for the type of technology selected (in this case. PL/SQL), the custom-beans and the custom database objects. The custom database objects are loaded into the database for use by APIs. The custom-beans are inputs to the RSE tool.

5.

Create the ServiceProviderDefLibrary.xml. Define the service and operations to satisfy the business case using the defined contracts.
Note: See the Oracle Retail Service-OrientedArchitecture Enabler Tool

Guide (Chapter 5, Service Definition Library XML File).

6. 7.

Execute the RSE tool using inputs, base objects, custom-beans from the AG, and the ServiceProviderDefLibrary.xml The RSE output is a deployable .ear, where the WSDL conforms to the objects referenced in the ServiceProviderDefLibrary.xml and the API templates (which have hooks for talking to the services, placeholders for business logic, and references to the Oracle Object created by the AG). Implement the logic behind the placeholders in the API template, and use the Business Objects.
Note: See the See the Oracle Retail Service-OrientedArchitecture

8.

Enabler Tool Guide (Chapter 8, Implementation Guidelines, PL/SQL Provider Service Implementation Notes).

6 Oracle Retail

Back Version Use Case New Service

This use case employs the tools in a back version release environment (such as 12.x). Although the release of RSE and AG tools is 13.1.x and higher and works only with 13.1.x and higher business objects, users are not prevented from using of the tools to create Web service providers that can be use in conjunction with the back version PL/SQL packages and data.

Scenario
Business analysis and strategy has determined that it is best to create Web service providers from a back version of RMS (such as 12.x) to interface to a newer generation of Oracle technologies, such as those in Service Oriented Architecture suite (including BPEL and OESB) or AIA.

Approach
The steps below correspond to the following approach illustration.
PL/SQL Application Schema Back Version Back Version Oracle Objects

Application PL/SQL packages

Run-time Service Layer

Oracle Objects
WS Client Soap

Application Data

8: Uses

R/R
<name>Service. wsdl

<name>Service.ear

Web Service Schema

8: Uses 8: Uses

<name>ServiceProviderImplSpec.sql <name>ServiceProviderImplBody.sql

Current Version Oracle Objects

8: Uses

New or Extended Oracle Objects

Design Time
4: Extend or create the XSDs to satisfy the business case
7: Deploy ear

Base XSDs, Extof and Custom XSDs

Retail Artifact Generator

4: Custom Objects

3: Designed XSDs 4: Custom Beans

5: Define the Service and operations to satisfy the business case

7: API templates

Retail SOA Enabler

5: Created ServiceDef

Service Def

1.

Create a target schema to be used for the Web service provider APIs and the 13.1.x Oracle objects, base and custom.
Note: For 13.1.x objects and the back version objects to co-exist in

the same database, it is strongly recommended that the Oracle Objects and the Web service APIs are separated from the base application database schema.
2.

Follow steps 1 8 in the Current Version Use Case.

How to Create PL/SQL Web Service Providers Using Oracle Retail SOA Enabler and Oracle Retail Artifact Generator 7

Note: Regarding Step 8, for the Back Version Use Case, if the

new API attempts to reuse back version packages and objects then additional work is required. Because the RSE uses the current versions business objects, Step 8 must also resolve the functional differences between these Oracle Objects and packages from the back version and any required in the current version Oracle Objects. Functional analysis always is required, and there can be substantial functional differences between the current and back versions.
3. 4.

The API templates are loaded in to the Web service schema with the base 13.1.x Oracle objects as needed, and the custom Oracle objects are created by the AG. Grant appropriate database permissions on the packages and database objects that the new APIs need to satisfy the business logic requirements.

Current Version Use Case Extend Existing Web Service Provider Use Case
The 13.1.1.2 release of RMS ships Web service providers for RMS Integration with Financial Applications through Oracle Application Integration Architecture (AIA). These Web service providers are for Supplier, Payment Terms, and Report Locator. Note: See Oracle Retail Merchandising System documentation.
Web Service Layer
Soap

External WS Client

R/R
SupplierService. wsdl

SupplierService (PortFactory)

Supplier Oracle Objects

RMS PL/SQL Application GA Schema SupplierServiceProviderImplSpec.sql SupplierServiceProviderImplBody.sql Current Version Oracle Objects

External WS Client

Soap

R/R
PayTermService. wsdl

PayTermService (PortFactory)

PayTerm Oracle Objects

PayTermServiceProviderImplSpec.sql PayTermServiceProviderImplBody.sql

ReportLocatorServiceProviderImplSpec.sql ReportLocatorServiceProviderImplBody.sql
External WS Client Soap

R/R
ReportLocatorSer vice.wsdl

ReportLocatorService (PortFactory)

ReportLocator Oracle Objects

This use case is extending the existing generally available Supplier Web Service Provider by adding additional elements to one of the existing services business objects.

Scenario
The business has determined that the Supplier Web Service must include two new elements, Cost Type and a Secondary Name, for each Supplier. The business objects for these Web services are packaged and shipped (as generally available) with the Oracle Retail base objects in RibFuncArtifact13.1.xForAll13.1.xApps_eng_ga.tar.

8 Oracle Retail

Approach
The steps below correspond to the following approach illustration.

1.

Using the Artifact Generator tool, extend the XSDs and generate the custom database objects and the custom-beans. Because these are base objects, they will have been installed with the AG tool.
Note: See the Oracle Retail Artifact Generator Guide (Chapter 3,

General Usage, Addition of Optional Elements).

a.

Add the new elements to the ExtOfSupplierDesc.xsd.

<xs:element name="ExtOfSupSite"> <xs:complexType> <xs:sequence> <xs:element name="supplierCostType" type="xs:string" minOccurs="0"/> <xs:element name="supplierNameSecondary" type="xs:string" minOccurs="0"/> </xs:sequence> </xs:complexType> </xs:element>

b. 2.

Generate the Functional Artifacts; custom database objects and the custom-beans.

Use the RMS ServiceProviderDefLibrary.xml and the newly generated custom-beans with the extended business object as inputs to RSE.
Note: A hyperlink to the ServiceProviderDefLibrary.xml is

found in My Oracle Support as part of this How To document (ID 1089955.1).

3.

The RSE tools generate the PL/SQL Provider output zip file.
a.

The service .ear file that can be deployed will have the WSDL changes to expose the additional elements and can be verified by examining the static WSDL packaged in the .zip file The API templates are of no value in this scenario, because the APIs already exist and have logic added.

b.

How to Create PL/SQL Web Service Providers Using Oracle Retail SOA Enabler and Oracle Retail Artifact Generator 9

4. 5.

Load the extended Oracle objects to the database. Implement the logic changes to the existing APIs or other RMS PL/SQL packages as necessary to use the extension to the SupplierDesc Business Object.

10 Oracle Retail

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 2010, Oracle. 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, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.