Integrating Apex With Google Maps 169532

Web Services Best Practices
Oracle Utilities Application Framew ork

OR AC L E W HI TE P AP E R | DE CE M BE R 2 01 6 ( 4. 3. 0. 3. 0 )
Table of Contents
Introduction 6
Web Services Capabilities 6
Web Services Overview 7
Basic Concepts 7
XML Based Services 7
Page Based Services 9
Simple Object Access Protocol Style 9
Web Service Standards 9
Web Services in the Container 10
Inbound Web Services Overview 11
Message Driven Beans (MDB) Overview 12
REST Based Support 13
Real Time Adapters Overview 13
Outbound Messages Overview 14
Oracle Service Bus Overview 14
SOA Suite Integration Overview 15
Web Services Adapter Overview 15
Inbound Web Services 16
Overview 16
The Inbound Web Service Development Process 17
Designing Web Services 18
Defining an Inbound Web Service 19
1 | Web Services Best Practices - Oracle Utilities Application Framework

Multiple Operations 20
Transaction Types 21
Enabling Page Services in Inbound Web Services 22
Translation of formats using XSL 23
External Schemas 26
Deployment of Inbound Web Services 26
Online Inbound Web Service Deployment 27
Command-based Web Service Deployment 28
Configuration of Inbound Web Services Deployment Name 30
Architecture Advice 31
Querying WSDL for a Service 31
Legacy Customer Support 32
Testing and Using Inbound Web Services 32
Monitoring Inbound Web Services 33
Monitoring Inbound Web Services Using Oracle WebLogic console 33
Monitoring Inbound Web Services Using Oracle Enterprise Manager 34
Security Considerations 35
Inbuilt Security Annotation Support 35
Defining your own policies 36
WS-Policy Support 37
Setting Default Security Policy 37
Order of Precedence 38

Web Services Manager Support 39
Real Time Adapters 40
Overview of Real Time Adapters 40
Use Of Real Time Adapters 41
Email Adapter 41
HTTP/S Adapter 42
Supporting HTTPS 43
Supporting JSON 44
SOAP Header Support 45
Real Time JMS Adapter 46
Setting up the JMS Resources 46
Defining your JMS resources to the Product 47
Setting up the Message Information 47
SOAP Adapter 48
Outbound Messages 48
Overview of Outbound Messages 48
Supported Adapters 49
Designing Outbound Messages 49
Designing External Systems 50
Processing Methods 51
JSON Support for Outbound Messages 51
REST Based Web Services 52

Limitations of REST Support 52
REST Security Fundamentals 53
Setting Up REST Services 53
Invoking REST Services 54
REST Formats 54
Mapping XML to JSON 54
REST Services Security 55
Guaranteed Delivery 55
REST Error Format 56
Oracle Service Bus Adapter 57
Invoking Remote Web Services 58
Web Services Adapter 58
Limitations of interface 61
Advanced Configuration 61
Migrating Web Services 61
Using Inbound Web Services with Oracle SOA Suite 61
Registry Support 62
Oracle Integration Cloud Service Support 62
Error Processing in Web Services 64
High Availability Considerations 65
Message Driven Beans 66
Architecture and Features 66
Oracle WebLogic JMS Resource Guidelines 67

JMS Setup Tips and Techniques 67
Configuration 68
config.xml configuration 70
ejb-jar.xml Configuration 72
weblogic.ejb-jar.xml Configuration 74
JMS Selector Support (Inbound) 75
MDB versus Oracle SOA Suite 75
SPML Web Service Support 76
Frequently Asked Questions 77
Why doesn't my Web Service appear in Oracle WebLogic? 77
Why doesn't my Web Service appear in Oracle Enterprise Manager? 77
How do I turn a query portal into a Web Service? 78
How does the internal security model work with Web Services? 79
Can I use Self Signed Certificates? 79
Do I need to include timestamps in my web services calls? 79
What is not supported in IBM WebSphere for Web Services? 80
What are poison requests? 80

Introduction
Note:
Customers on releases earlier than Oracle Utilities Application Framework 4.2.0.2.0 should use the XAI Best
Practices (Doc Id: 942074.1) and MPL Best Practices (Doc Id: 1308165.1) whitepapers, available from My
Oracle Support, instead of this whitepaper.
Note:
This whitepaper primarily covers the Web Services capabilities of the Oracle WebLogic implementation of
Web Services within Oracle Utilities Application Framework. For IBM WebSphere implementations, some
variations may exist.
Note:
This whitepaper covers functionality up to and including Oracle Utilities Application Framework V4.3.0.3.0.
Web Services are a common method for integration between application to application using either peer to peer
communication or via service-orientated middleware. The main concept of this type of integration is to be able to
share data and functions from application to application using standard protocols and formats.
Oracle Utilities Application Framework includes a facility to allow integration for inbound and outbound
communications using Web Services. The key principles for the integration are:
» Exposing the functionality of the Oracle Utilities Application Framework based product as a Web Service including
any maintenance objects, business objects, business services, query portals1 and service scripts. This means any
of the functionality provided by the product can be exposed as a Web Service.
» Supporting standard protocols including Simple Object Access Protocol (SOAP) and well as REST2 over HTTP or
HTTPS.
» Supporting standard formats like WSDL and UDDI to define and manage the definitions used for the Web
Services.
» Allowing external Web Services to be imported and defined as callable Business Services within the product.
» Supporting a wide range of J2EE Server based Web Services standards including WS-Security, WS-Policy, etc.
» Providing J2EE based adapters to delivery mechanisms such as JMS sources (queues and topics).
» Participating in integration and orchestration via Service Orientated middleware using Web Services.
» Providing Oracle Service Bus adapters to provide scalable outbound communications.
This whitepaper will outline these capabilities as well as provide implementation advice on the Web Services
capabilities.
Web Services Capabilities
With the release of Oracle Utilities Application Framework V4.2.x and above, the Web Services capability of the
Oracle Utilities Application Framework has been enhanced to support a number of key web service-related
integrations:
1 Via Business Services
2 JSON is supported

» Inbound Web Services - Deployment of SOAP JAX-WS based Web Services within the product deployed to the
J2EE Web Application Server. This replaces the servlet deployment available in XML Application Integration
(XAI).
Note:
Customers using XML Application Integration (XAI) should migrate to Inbound Web Services as outlined
in Migrating from XAI to IWS (Doc Id: 1644914.1) available from My Oracle Support.
» Message Driven Beans (MDB) - Inbound JMS resources integration directly from the J2EE container using
Message Driven beans.
» Real Time Adapters - A set of adapters to allow common integrations directly accessible from objects within the
product to provide interfaces within the scope of the active transaction.
» Representational State Transfer (REST) Support - A capability to expose business objects and services as
REST based API's.
» Outbound Messages - A set of infrastructure to provide asynchronous integration from the product to external
systems.
Note:
Customers of Oracle Utilities Customer Care and Billing should use Outbound Messages instead of
Notification And Workflow.
» Oracle Service Bus Integration - Inbound and Outbound communication between Oracle Service Bus and the
Oracle Utilities Application Framework based products. This replaces the Multi-purpose Listener (MPL) available
in previous releases.
» SOA Suite Integration - Integration with the SOA Suite to provide service orchestration and other services.
» Web Services Adapter - Direct calling external web services from ConfigTools code for real time integration.
This whitepaper outlines the capabilities, configuration guidelines and advice for implementation of the above
facilities.
Web Services Overview

Web Services provide an integration mechanism between an external system and the Oracle Utilities Application
Framework based product. This integration mechanism complements the online and batch channels available for
the Oracle Utilities Application Framework.
Basic Concepts
Before discussing Web Services capabilities of the Oracle Utilities Application Framework it is important to
understand a number of key concepts that are the basis of Web Services within the Oracle Utilities Application
Framework.
XML Based Services
Inbound Web Services can talk directly to various XML based configuration tools objects within the Oracle Utilities
Application Framework. The definition of the configuration object dictates the format and elements contained within
the Web Service.
The product supports the definition of the following objects as part of an Inbound Web Service:

» Business Objects - Business Objects are user-defined views of Maintenance Objects or parent Business
Objects using meta data to define the specific structures used for processing data. A maintenance object or
business object can have multiple child business objects which represent different ways of interpreting the
functionality. Structures, expressed as an XML based schema, within the Business Object, can either directly
mirror the structure of the Maintenance Object/Parent Business Object or remap the underlying structure to an
alternative structure (for example, it is possible to flatten collections of data). The following figure outlines these
relationships:
Maintenance Inbound Web

Business Object
Object Services
Child Business
Object
Figure 1 – Relationships with Business Objects
» Business Services - Business Services are user-defined views of Application Services using meta data to define
specific structures to used to call the service. It is possible to directly reference application services or convert a
query zone to a business service3. The interface to the object is defined as an XML-based schema. The following
figure outlines these relationships:
Application
Business Service
Service
Inbound Web
Services
Business Service
Query Portal
(FWLZDEXP)
Figure 2 – Relationships with Business Services
» Service Scripts - Service scripts are scripts that contain logic, calls to other objects (Scripts, Business Services,
and Business Objects) to provide composite functionality in a single callable function. Service Scripts can be used
as simple functions, algorithms, or Web Services. As with other objects, an XML schema defines the structure of
the interface. The following figure outlines these relationships:
Business Object
Inbound Web
Business Service Service Script
Services
Service Script
3 Using the FWLZDEXP Business Service

Figure 3 – Relationships with Service Scripts
Note:
BPA Scripts cannot be defined as Inbound Web Services. The recommended approach is to replicate the flow
of functions used in a BPA script as a Service Script to use it as an Inbound Web Service.
Inbound Web Services have the following features:
» Inbound Web Services support more than one XML based object to support multiple operations. Business
Objects can support multiple transaction types.
» The schema used for each operation is defined in the schema object attached to the Inbound Web Service
Note:
For more information about Business Objects, Business Services and Service Scripts refer to the online
help and ConfigTools Best Practices (Doc Id: 1929040.1), available from My Oracle Support.
Each of the objects above can be exposed as a Web Service with the schema attached to the object used as the
structure for the Web Service. These objects represent Business Adapters to the Web Services.
Page Based Services
In past releases of Oracle Utilities Application Framework, the XML Application Integration (XAI) facility supported
Web Service based upon Maintenance Objects using Page Services. It is possible, in Oracle Utilities Application
Framework 4.3.0.1.0 and above, to deploy Page Services as Inbound Web Services.
Refer to Legacy Customer Support for more information about this facility.
Simple Object Access Protocol Style
The Simple Object Access protocol (SOAP) is a protocol specification defining the structure for exchanging
information via Web Services. The protocol uses an XML format that conforms to the SOAP specification. The
protocol is a message format and relies on transports such as HTTP/S, JMS and SMTP to request and receive the
data.
The Web Services capability within the Oracle Utilities Application Framework supports SOAP 1.1 over
HTTP/HTTPS and JMS4 transports.
Web Service Standards
Note:
The standards documented in this section are supported using Inbound Web Services only. XML Application
Integration (XAI) supports a subset of these standards as outlined in the XAI Best Practices (Doc Id: 942074.1)
available from My Oracle Support.
The Web Services specification includes a number of additional standards that can optionally be used with Web
Services. These standards cover additional facilities, security facilities and operational functions to apply to Web
Services transactions. These standards are typically implemented by the J2EE Web Application Server itself.
The table below lists a subset of standard supported by the J2EE Web Application Server and that can be used with
Oracle Utilities Application Framework JAX-WS based Web Services:
4 JMS is supported via the Message Driven Bean or Oracle Service Bus.

WS Standard Applicability Comments
JAX-WS Java based Web Services Inbound Web Services generates JAX-WS based Web
Services.
WS-Policy Security Policies for transport and data Support Policies supported by J2EE Web Application
Server, custom policies5, Oracle Web Services Manager
policies.
Universal Description, Discovery Web Service Registry Loads Web Services into registry for centralized
and Integration (UDDI) development.
Web Services Schema Language for Web Services Oracle Utilities Application Framework generates WSDL
Definition/Description Language from schema definition automatically.
(WSDL)
WS-Security (WSS) Base security standards for Web Largely replaced by WS-Policy but WSS based security is
Services supported for backward compatibility.
WS-SecurityPolicy Policies that span WS-Policy and WS- Supported directly by J2EE Web Application Server.
Trust.
WS-Addressing Dynamic addressing This is only supported programmatically using appropriate

middleware.
WS-ReliableMessaging Reliability for Web Services within This is only supported with server to server
container communications, using middleware or for Inbound Web
Services for connection pooling control.
WS-Trust Extensions to WS-Security for Security Supported directly by J2EE Web Application Server.
tokens
WS-Utility Extensions to WS-Security Supported directly (especially for timestamps)
Note:
The above table is based upon Oracle WebLogic 12c and above. For alternative versions of Oracle WebLogic
and IBM WebSphere refer to the documentation supplied with that installation.
Web Services in the Container
The Web Services capability uses the Web Services capabilities within the J2EE Web Application Server.
Essentially the following applies to describe the relationship between the Web Services capability and the J2EE
Web Services capability:
» The Web Services are generated in JAX-WS format within the Oracle Utilities Application Framework into a
deployable EAR6 file. The deployed file contains the generated Web Service JAX-WS code, generated WSDL and
any attached WS-Policy files.
» The EAR file is now available for deployment, using the J2EE Web Application Server utilities, into an appropriate
J2EE container such as a cluster or a server.
5 Custom policies must be supported by J2EE Web Application Server.
6 Web Services are deployed in WAR format in Oracle Utilities Application Framework V4.2.x and EAR format in Oracle Utilities Application Framework
V4.3.0.1.0 and above.

» Deployment extensions such as deployment plans, additional WS-Policies, Authentication Providers and Web
Service Manager polices and access controls can be added as part of the deployment.
For more information about Web Services capabilities of J2EE Web Application Servers refer to:
J2EE Web Application Server Reference information
Oracle WebLogic Develop and Secure Web Services - Tasks
IBM WebSphere IBM WebSphere Application Server Concepts, Planning and Design Guide
Inbound Web Services Overview
One of the major Web Services capabilities is the Inbound Web Services set of functionality. This functionality allows
Business Objects, Business Services and Service Scripts to be exposed as Web Services. The features of Inbound
Web Services are:
» Support for in-line security policies and/or J2EE Web Application security policies attached at deployment time.
» Support for multiple operations within a single Web Services using single or multiple Business Objects, Business
Services and/or Service Scripts.
» Uses Web Services capabilities within J2EE Web Application Server including advanced deployment options,
configuration, additional security and additional monitoring capabilities.
» Support for Security facilities within J2EE Web Application server including WS-Security support and WS-Policy
support.
» Support for performance metrics based monitoring from the J2EE Web Application Server console or Oracle
Enterprise Manager.
» Support for the high availability facilities including clustering and failover within the J2EE Web Application Server.
The Inbound Web Services capability allows web services to be defined in meta data and then JAX-WS code is
generated and deployed on the Web Application Server in a WAR or EAR7 file. The code then connects to the
Application Server to call services. Architecturally the capability is shown below:
7 In Oracle Utilities Application Framework V4.3.0.1.0, Inbound Web Services is deployed in an EAR file rather than in a WAR file as in previous
releases.

Oracle WebLogic/IBM WebSphere
SPLWeb Web Services/Integration

User Web
Interface Services
SPLService SPLService
Services Services
Database
Database Server
Database Schema
Figure 4 – Web Service Architecture
For more information about Inbound Web Services refer to the Inbound Web Services section of this document.
Message Driven Beans (MDB) Overview
Note:
Message Driven Beans are only used for inbound communication from JMS resources. Customers using
Oracle Service Bus should use the JMS support provided with that product, in preference to the Message
Driven Bean functionality described in this section.
Note:
Customers using IBM WebSphere should use the implementation of Message Driven Bean contained within
the online server8. Customers using Oracle WebLogic should use the implementation of the Message Driven
Bean in the Integration Server (IWS).
One of the major features of Oracle Utilities Application Framework is the inbuilt JMS integration using Message
Driven Beans (MDB). This feature allows the J2EE container to define some inbound communication integration
points, via MDBs, to process local or remote JMS resources in the background. The Message Driven Bean
implementation is part of the service application and is configuration only as the Oracle Utilities Application
Framework includes an inbuilt Message Driven Bean implementation.
In Oracle Utilities Application Framework V4.3.0.1.0 and above, the Message Driven bean has been included in the
Inbound Web Services implementation. In past releases it has been included in the online (SPLService)
application. The following diagram illustrates the MDB architecture:
8 The Message Driven Bean implementation in the online server contains additional features for error processing in IBM WebSphere. These features do
not exist in the Integration Server implementation.

Web Services/SPLService
MDB Definitions
Services MDB
JMS Resources
MDB
Database Server
Database Schema
Figure 5 – Message Driven Bean Architecture
The features of the Message Driven Bean architecture are as follows:
» The Message Driven Bean is defined within the J2EE Application Server. The bean is defined within the
configuration files that define the configuration of the J2EE Application Server. For Oracle WebLogic customers
refer to Configuring and Deploying MDB's Using JMS Topics and Programming and Configuring MDB's.
» Message Driven Beans can be clustered for high availability solutions.

» Message Driven Beans can access local or remote JMS resources. This includes distributed queues and foreign
queues.
» Message Driven Beans support both JMS Queues for point to point interfaces or JMS Topics for publish and
subscribe interfaces.
» The definition of the Message Driven Bean includes the identifier for the interface, used for monitoring purposes
as well we tolerances for connection pooling and error rules. This identifier is visible within the J2EE server
administration console and/or Oracle Enterprise Manager for metrics purposes.
» Customers using Oracle WebLogic can use the inbuilt error trapping facility to route invalid requests automatically
to an error queue. This avoids attempted processing of poison requests by the product.
More information about the Message Driven Bean implementation is contained in the Oracle WebLogic JMS
Integration (Doc Id: 1308181.1) whitepaper available from My Oracle Support.
REST Based Support
Note:
This facility is available in Oracle Utilities Application Framework V4.3.0.2.0 and above only. It was introduced
in earlier versions but it was only enabled for approved products.
The Representational State Transfer (REST) style is a newer specification of Web Services which provides a simple
data driven approach to Web Services. The implementation of REST based services is simpler alternative to SOAP
based services. REST services are the preferred integration for mobile platforms.
The Web Services capability within the Oracle Utilities Application Framework supports REST via Jersey.
Real Time Adapters Overview
In Oracle Utilities Application Framework there are a number of real time adapters that allow an integration to be
invoked as part of an online transaction. For example, as part of a customer interaction in a call center you might
need to send an urgent email as part of the interaction. The following adapters are supplied with the product:

Adapter Usage
RTEMAILSNDR Real Time Email Adapter (SMTP)
9
RTEHTTPSNDR Real Time HTTP Adapter
RTJMSQSNDR Real Time JMS Adapter (Queue)
RTJMSTSNDR Real Time JMS Adapter (Topic)
RTJSONSNDR Real Time JSON Sender
These adapters have the following features:
» Configuration of the adapter, in Message Sender, includes technical connectivity configuration to the target
technology. Adapter definitions are designed for reuse.
» Integration is provided via the Outbound Message infrastructure.
» Programmatically an outbound message of a type with an appropriate payload is created as part of the desired
transaction. This is typically done via algorithms, change handlers, BPA scripts or service scripts.
» The adapter will invoke the technology and provide return codes as part of the interaction and part of the
transaction time that invoked the adapter. Therefore their use is only recommended if the transmission of the data
must be completed as part of an online transaction scope. Alternatives to this are using the Oracle Service Bus
integration to send the same data asynchronously via Outbound Messages.
Outbound Messages Overview
One of the common objects within the Oracle Utilities Application Framework is Outbound Messages. This object will
be used to hold a business event, and its payload, to initiate a real time or asynchronous outbound communications
from the product.
The Outbound Message facility has the following features:
 Supporting Outbound Message Types which allow identification of the message and the configuration of
the format of the payload, in the format of a schema, to be sent out.
 Supporting an Outbound Message staging table which holds the message and its payload as well the
status of the transmission.
 Support an External System object that defines the collection of Outbound Messages, processing
methods, transformations and communications technology that represents an interface.
Outbound Messages are the primary outbound communications mechanism used internally as well as used by
Oracle Service Bus.
Oracle Service Bus Overview
Oracle's Service Bus is an enterprise level service bus that allows information to be processed into the product and
out of the product using a wide variety of transports. The basic concept of the integration is that information is
sourced from an external system or the product from an appropriate transport, the data is then manipulated or
transformed, if required before sending to an external system or the product from an appropriate transport. Oracle
Service Bus defines the flow of the data and is responsible to perform the integration. The following diagram
illustrates the flows:
9 This adapter has been extended to support HTTPS. POST is only supported as at the present release.

Inbound OSB communication:
Source
Application Transport Transport
OUAF Product
Transform
Figure 6 – Inbound OSB Flow
Outbound OSB Communication:
OUAF Product Transport

Transport Target
(OMSG, NDS) Application
Transform
Figure 7 – Outbound OSB Flow
In summary Oracle Service Bus performs the following:
» Defines the source and target applications via their respective API.
» Defines the transport to be used to deliver the transaction from the sources. The transport can differ from source
to target.
» If the payload needed by a target is different to the source, it is possible to manipulate and transform the payload
into a compatible format supported by the target.
» Execution tracking and metrics for integration are also available.

Refer to Oracle Service Bus Integration (Doc Id: 1558279.1) available from My Oracle Support and Oracle Service
Bus documentation for more information.
SOA Suite Integration Overview
Oracle's SOA Suite is a series of SOA based products that allow implementations a wide range of SOA based
integrations. The key components of SOA Suite10 are as follows:
» Oracle BPEL Process Manager - Business Process Execution Language based process manager that allows a
set of discrete services to be assembled in an end to end process flow.
» Oracle Business Rules - Externalization of business rules used across the SOA Suite components.
» Oracle Service Bus - Enterprise Service Bus for large loads in and out of products using common transports.
» Oracle Business Activity Monitoring - Rapid analytics based on real time visibility of key business events.
» Oracle Event Processing - Correlation of data across multiple streams for high volume of data transmission.
Oracle SOA Suite is the foundation of flexible and powerful integration. Refer to Oracle SOA Suite Integration (Doc
Id: 1308161.1) available from My Oracle Support and Oracle SOA Suite documentation for more information.
Web Services Adapter Overview
10 The products shipped with SOA Suite vary from release to release. Refer to the SOA documentation for the complete list.

Most of the above technologies utilize the Web Services capabilities within the product but in some situations the
product itself must directly call an external Web Service as part of a transaction. The Web Services Adapter is a
feature which will import an external Web Service, allow definition of mappings to objects within the product and
allow for real time integration to that defined Web Services adapter as part of a service or BPA script.
The Web Services Adapter supports the following:
» Imports WSDL from an external Web Service into the product.

» Allows the implementer to map the elements of the WSDL to data elements in product objects.
» Generates a pair of Data Areas, one for the request and one for the response, to interface to the external Web
Service including the mapping of the elements of that Web Service. The Business Service to invoke with these
data areas is provided (F1-InvokeWebService). The Business Service with the pair of data areas can then be
included as part of a Service Script or BPA script to control business conditions for executing that external Web
Service.
Note:
The Web Services Adapter uses the same Fusion WSDL import libraries associated with Oracle development
products, such as Oracle JDeveloper. The types of WSDL that can be imported using these libraries will need
to conform to WSDL standards supported by Oracle JDeveloper and also be able to be mapped using the
Oracle Utilities Application Framework schema format. Whilst simple WSDL's will be able to be imported, some
complex formats may not import correctly.
Inbound Web Services

In Oracle Utilities Application Framework V4.2.0.2.0 and above, a new Web Services based capability was
introduced named Inbound Web Services (IWS).
Overview
Inbound Web Services is a JAX-WS SOAP based web service capability that allows product objects to be exposed
as web services within the J2EE web application server container (such as Oracle WebLogic and IBM WebSphere).
This has the advantages of allowing product functionality to be exposed for integration but also utilizes the
availability, scalability and security features of the J2EE web application server to provide a robust but flexible
solution.
The Inbound Web Services feature supports the following:
» Web Services definitions - There are a series of Inbound Web Services defining the interface definition including
linking Business Objects, Business Services and Service Scripts to operations within the web service.
» Enumerations - The Web Service Definition Language (WSDL) generated for the service will generate element
enumerations for administration lookups.
» Deployment tools - A set of online or command line tools to register and deploy web services within the J2EE
web application server. This is used to initially define the web service as well update the WSDL for any changes
to the underlying schema.
» Availability/Scalability - As the web services are deployed natively to the J2EE web application server, the web
services can exploit the native availability and scalability features of the J2EE web application server to provide a
viable integration channel to the product.
» Monitoring Capabilities - As the web services are deployed natively to the J2EE web application server, a set of
comprehensive monitoring metrics are available to track individual executions as well as consolidated metrics.

» Enhanced Security - Each J2EE web application server supports a wide range of transport and message
standards to apply to the deployed web services. It is possible to support WS-Security and the variations of
security supported by WS-Policy support. Oracle WebLogic customers can also take advantage of Oracle Web
Services Manager to provide additional WS-Policy support and configurable access controls for individual web
services.
The Inbound Web Service Development Process
The process of creating a Web Service to expose functionality to an interface is relatively simple. The process is as
follows:
» Design the Web Service - Create a Business Object, Business Service or Service Script that expresses the format
and functionality that is required from the interface. The schema on the object will define the data structures for
the Web Service.
Note:
If you want to expose a query portal as a Web Service you must create a Business Service as outlined in
How Do I turn a query portal into a Web Service?.
» Define an Inbound Web Service - Define the service as an Inbound Web Service object.
» Deploy the Inbound Web Service - Generate and deploy the Inbound Web Service to the J2EE Web container.
There are two methods to perform this task:
» Run online deployment - If you are a developer and want to seamlessly want to generate and deploy the
Web Service, there is an online deployment facility.
» Run the command line generator - For production or installs using the native method11 it is recommended
that the command line utility be used to build the deployment file and then you can manually redeploy (i.e.
updating the deployment) the deployment file using command line utilities like WLST, Oracle WebLogic
console or using Oracle Enterprise Manager.
The following figure outlines the development and deployment process:
11 In a native install for development environments it is possible to use the online deployment tool. Refer to the Server Administration Guide for options
and configuration.

Define Business Object,
Business Service or Service
Script
Define Inbound Web Service
Run Inbound Web Services

Run iwsdeploy
Deployment
Update Deployment
Figure 8 – Inbound Web Services flow
Designing Web Services
The first step in the process is to design the functions in the product to use as a web service. Any function or object
in the product can become a web service via the appropriate adapter. The following object types can be exposed as
a Web Service:
Object Comments
Business Object The schema attached to the business object becomes the structure of the web service.
Business Service The schema attached to the business service becomes the structure of the web service.
Service Script The schema (not the data areas) attached to the service script becomes the structure of the web
service.
Before defining the Inbound Web Service the corresponding object should be built and saved with the following
recommendations:
» Generally the same objects used for other channels can be reused in Inbound Web Services. Features not
appropriate for Inbound Web Services, are not included in the web service. For example, UI Hints are not carried
over to the web service as they are not appropriate.
» Attributes in web services are not supported without the need for an XSLT which can be attached in the Inbound
Web Services definition. Refer to Translation of formats using XSL for more discussion.
» The naming of the service should include a CM prefix to prevent the service from being removed during upgrades.
» The names for the operations should conform to java standards using camelCase. Do not embed blanks in
names of services or operations.
» If you specify a default transaction type, for Business Object based services, that operation will only accept that
transaction type as input. Leaving it blank will support multiple transaction types per operation. Generally it is a
good idea to restrict the one transaction type per operation to define the API's you want to expose.

» It is possible to register different objects and functionality in a single Inbound Web Service via the operations.
Each operation can refer to the same or different objects within the product. This reduces the number of web
services exposed from the product and reduces maintenance costs.
» The schema format used by the product does not natively support XML attributes. If these are require it is
recommended to use transformations. Refer to the Translation of formats using XSL section for more details.
» The schema format used by the product includes additional tags used for UI Hints and other functions such as
embedding HTML in the schema to reduce the need for additional code objects. These facilities are not applicable
to Web Services and will be filtered out. The following tag types are not used in the Web Service definition:
» UI Hint Namespace and related tags.
» The private descriptive attribute is ignored in the Inbound Web Service and therefore these elements are
attached to are included in the Web Service schema12. To avoid this situation create a specialized additional
schema that specifies the interface for the Web Service with the fields required only for that interface.
Defining an Inbound Web Service
Once a set of Business Objects, Business Services and Service Scripts are defined the next step is to define the
Inbound Web Service.
The Inbound Web Service maintenance function is available from the Administration menu of the product. The
function includes the following:
» Web Service Name - This is the name of the web service to deploy. This will be the service name called by the
interfacing web services client. To avoid upgrade conflicts with base delivered services it is recommended to
prefix the Web Service Name with CM. For example, CM-SomeService.
» Description and Detailed Description - A short and long description used to document the service. It is highly
recommended that the service be documented using these fields so that other developers and repositories can
identify the service.
» Trace - This enables or disables tracing to spl-iws.log or the container log, such as server logs or domain
logs, for services. This is primarily used for developers for tracing services. It is recommended to be set to false
for non-development environments.
Note:
Customers familiar with XML Application Interface (XAI) should be aware that tracing in Inbound Web
Services does not include the same performance information as XAI used to include. The performance
information is not automatically collated by the J2EE Web Application Server JMX interface itself. Refer
to Monitoring Inbound Web Services for details of these monitoring API's.
» Debug - This enables detailed debug of the underlying services within the product. This will write the debug
information to the same locations as the trace. This is primarily used for developers for debugging services. It is
recommended to be set to false for non-development environments.
» Active - This is an important message option which controls whether the service is active or not. Only active
services, set to true, will be deployed and made available as Inbound Web Services. The following advice is
recommended for optimal use of this message option:
» This message option is only applicable at deployment time. Toggling the value does not affect the runtime of
the service.
12 This will be addressed in a future release.

Note:
Allowing Inbound Web Services to be enabled or disabled, dynamically at run time, can be achieved
using Oracle Web Services Manager.
» If the service is initially built but not finalized then it is recommended to set this value to false till the service
is finalized or in a state ready for release. This is typically within development environments only.
» Generally the status should be set to true to permit the service to be built and deployed at deployment time.
» Setting the value from true (active) to false (not active) for an already deployed service removes the
service from the deployment upon the next deployment activity.
» Annotations - This is a list of web service annotations to attach to the Inbound Web Service to set policies at the
definition level. These are attached as part of the deployment activity.
Note:
In the current release of Inbound Web Services, only security based policies that conform to WS-Policy are
supported as annotations. Refer to the Security Considerations for more information.
» Operations - One of the major features of Inbound Web Services is that multiple web service operations are
supported and that each operation can be attached to the same object or different objects to other operations
within the Inbound Web Service. This allows for possible consolidation of individual web services. Refer to
Multiple Operations for more information.
Once the Inbound Web Service is defined it is available to be deployed (if the Active message option is set to true).
Refer to the Deployment of Inbound Web Services for a description of this process.
Multiple Operations
One of the major features of the Inbound Web Services is ability to support multiple operations. This allows a single
web service to support multiple objects and/or multiple types of transactions with different schemas. The operations
have the following features:
» You can define multiple operations if you want to support multiple operations in the Inbound Web Service
definition. If you use multiple operations then you cannot specify a default operation (as this is non-standard). If
you want to use a simpler web service call, then specify a single operation which has the same name as the
Inbound Web Service. This is available to be compatible with XML Application Integration (XAI).
» Each operation has the following attributes:

» Operation Name - Each operation has a name which is used in the web service client call that denotes the
operation to invoke. It is recommended to use camelCase for the operation name and make it descriptive.
For example, updateName, addUser etc.
» Schema Type - This denotes the type of object to be used in the operation. Inbound Web Services supports
schemas from Business Objects, Business Services and Service Scripts.
» Schema Name - The name of the object, as expressed by the Schema Type, which describes the schema
for the operation.
» Request Schema - This is an optional external file that describes the schema used for the request. This is to
support overriding inbuilt schemas if required. Refer to External Schemas for additional information.
» Response Schema - This is an optional external file that describes the schema used for the response. This
is to support overriding inbuilt schemas if required. Refer to External Schemas for additional information

» Request XSL - This is an optional external XSLT file to transform the request into the expected schema for
the request if the format from the web services client is different. Refer to Translation of formats using XSL
for additional information.
» Response XSL - This is an optional external XSLT file to transform the response into the expected schema
for the request if the format from the web services client is different. Refer to Translation of formats using
XSL for additional information.
» Transaction Type (Business Object based services only) - This is the transaction type associated with
the operation. If it is none is specified it is assumed to be passed at runtime. If it is set on multiple operations
then it will be used as the transactionType. For web service with a single operation where the Operation
Name matches the name of the Inbound Web Service then the transactionType is treated as the default
used if no transactionType is passed at runtime.
» The operation can be invoked from a Web Services client and selecting the operation from the list within the
relevant development environment. The request and response for that operation are available.
» It is optionally possible to also call the operation using the URL specified below. This is not recommended for
direct calls. It is provided for development purposes only. A typical URL for operations is:
http://<host>:<port>/<context>/webservices/<webservicename>#<operation>
where
<host> Product host name
<port> Product port number
<context> The context used for the product
<webservicename> Web Service Name from Inbound Web Services
<operation> Operation within the Inbound Web Service to invoke.
A combination of operation and transactionType allows for reusability within each Inbound Web Services.
Transaction Types
One of features of the business objects within the product is that they can support multiple types of transaction. This
is used in conjunction with operations on an Inbound Web Service.
These types of transaction are typically expressed as one of the following values:
Transaction Type Comments
Add Create a new instance of the business object.
Delete Delete an instance of the business object. If the object is referred to by other objects then the delete action will
fail.
Read Retrieve an existing instance of the business object.
Update Change an element(s) of the business object. The schema only needs to include the elements changed. This
option can be used for other functions within the lifecycle of a business object.
There is an element added by Inbound Web Services named transactionType that is an attribute of the schema
that can be populated by the client application.

Note:
The transactionType attribute is not added to schemas where there are multiple operations and the
transaction type is specified design time on the Inbound Web Service definition.
There are a few guidelines for using transaction types:
» It is possible to specify the transactionType at runtime by leaving the transaction type blank on the definition
of the operation.
» It is possible to link each individual transaction type to individual operations, including multiple operations. This
allows for greater granularity. For example, you can use the generic update transaction on the complete User
business object to update the user name or create a specific updateUserName operation, with an optimized
schema that only includes the name to update, as valid operations for individual interfaces.
» If there is a single solitary operation specified on the Inbound Web Service and a transaction type is specified
then this is the default transaction type if no transaction type is specified at runtime. In this case, if a transaction
type is specified at run time then the value specified at runtime will override the default specified on the Inbound
Web Service.
» For transaction types of update and add it is possible to define multiple operations with different schemas to
implement different interfaces. This allows interfaces to be targeted to specific information and also supports
consolidated Inbound Web Services.
» For customers migrating from XML Application Integration (XAI) interfaces, it is possible to emulate your existing
interfaces or consolidate your interfaces to the smaller number of web services if desired. Refer to Migrating from
XAI to IWS whitepaper (Doc Id: 1644914.1) from My Oracle Support for more information.
Note:
In Oracle Utilities Application Framework 4.3.0.3.0 and above, schema elements that include the
private=true attribute are filtered out of the resulting WSDL to encourage schema reusability.
Enabling Page Services in Inbound Web Services
Note:
This facility is only available in Oracle Utilities Application Framework V4.3.x and above.
By default, Inbound Web Service supports Business Objects, Business Services and Service Scripts only.
Customers who have migrated from XML Application Integration (XAI) also supported Maintenance Objects (also
known as Page Services. It is now possible to support Page Services in Inbound Web Services by creating an
External Message feature in Feature Configuration and enabling the Support XAI Deployment via IWS by setting the
value to true. For example:
Figure 9 – Configuring Page Services to be exposed to Inbound Web Services.

This will automatically deploy any Page Services to the Inbound Web Services container with backward compatibility
enabled for those deployed services. This allows customers who have an existing investment in Page Services to
use the Inbound Web Services facility with these benefits:
» Page Services are automatically generated and included in the Inbound Web Services deployment file. This can
be deployed to the J2EE container using the facilities provided.
» Page Services can be monitored using the Web Services metrics available in the container.
» Page Services can be secured additionally with Oracle WebLogic WS-Policy support and/or Oracle Web Services
Manager. This can only be performed from the Oracle WebLogic console.
» Additional features such as annotations and multiple operations are not supported for Page Services.
» Posting of Errors to staging is not supported in Inbound Web Services.

At this point, Page Services are automatically available from the Inbound Web Services capability which will change
the URL from:
http://<host>:<port>/<context>/XAIApp/<webservicename>
to
http://<host>:<port>/<context>/webservices/<webservicename>
where
<host> Product host name
<port> Product port number
<context> The context used for the product
<webservicename> Web Service Name from Inbound Web Services or XAI Inbound Services.
Translation of formats using XSL
Note:
The default parser and version of XSLT is configured on the XML Type associated with the product within
Oracle WebLogic. This parser may be altered but should not be used with the online application as that uses
a specific parser to render the screen assets correctly. Refer to the Installation Guide supplied with the
product for more details.
The schemas used by Inbound Web Services specify the interface format that is expected as a request and reply
from the Inbound Web Service. In most cases it is possible to model the format of the interface within the schema
using the existing schema language. But in some cases the format expected by the web services client, the
application calling the Inbound Web Services, may not be able to be modeled in the schema.
If the web services client is not able to use the schema supplied with the Inbound Web Service it is possible to use a
XSL transform on the request and/or response schema to adjust the Inbound Web Service into a format that is
expected for the request and/or response from the Inbound Web Service.
The XSLT file can be used to transform the format of the schema from one format to another so that is can be match
the expected request and/or response. The transform uses the parser and does the following:
» When used with the request, the service uses the specified transformation to transform the structure sent by the
web service client sent to the format as expected by the Inbound Web Service as configured as the schema for
the operation to be performed.

» When used with the response, the Inbound Web Service creates the structure as dictated by the schema attached
to the operation performed and then uses the translation specified on the operation, if specified, to transform the
response prior to sending that response to the web services client that requested the response.
Note:
SOAP Faults cannot be transformed.
To use a transform for request and/or response the following process can be used:
» Create a sample request or response by generating a call to the schema directly from an appropriate tool. For an
example of these tools refer to Testing Inbound Web Services.
» Open your desired XSLT development tool and create an XSLT file (with extension .xsl) for your desired
transform. It is recommended to test the XSLT with multiple variations of samples for your web service request
and/or response to verify the transform.
Note:
Ensure the name of the XSLT file confirms to the naming standards supported by the underlying operating
system. To avoid issues, it is recommended to avoid embedded blanks in names of files. It is also
recommended to prefix the file with cm to avoid conflicts with base provided transforms.
» Place the transformation in the $SPLEBASE/splapp/iws/resources directory (or

%SPLEBASE%\splapp\iws\resources on Windows platforms) with a minimum of read permission for the
product administration user.
» Specify the name of the XSLT (including extension) in the Inbound Web Service in the appropriate operation and
appropriate request/response field. The web services will need to be redeployed for the XSLT file to be included
in the deployed file.
Note:
If a transformation is used on an operation then it is highly recommend to also attach an External Schema
describing the final format be also defined on the same operation. This will allow the WSDL for the web
service to reflect the desired output format.
Transforming between elements and attributes

One of the most common transformations needed is to transform between elements to attributes and visa versa.
The schemas used in the product are element based and whilst the majority of interfaces use that standard, some
interface may use attributes. To support attributes an XSLT transform is needed to identify which elements should
be converted to attributes and which element those attributes should be aligned with.
The following examples illustrate common techniques to transform between elements and attributes.
Note:
The examples provided in this section are generic and are not extensive. They are only there to illustrate
possibilities. For developers not familiar with XSLT should use a tool such as Oracle JDeveloper or similar to
build your XSLT code.
Here is an example of an attribute based schema, which is the format commonly used by the product to represent
the objects within the product.
<someService>
<someGroup>

<field1>value1</field1>
</someGroup>
</someService>
Here is an example of the same above schema but using attributes:
<someService>
<someGroup field1="value1" field2="value2" field3="value3">

</someGroup>
</someService>
Here is an example of an XSLT transformation to transform from elements to attributes:
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="someService">
<someService>
<xsl:apply-templates/>
</someService>
</xsl:template>
<xsl:template match="someGroup">
<someGroup>
<xsl:for-each select="*">
<xsl:attribute name="{name()}">
<xsl:value-of select="text()"/>
</xsl:attribute>
</xsl:for-each>
</someGroup>
</xsl:template>
</xsl:stylesheet>
Here is an example of an XSLT transformation to transform attributes to elements
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output method="xml" indent="yes"/>

<xsl:template match="@* | node()">
<xsl:copy>
<xsl:apply-templates select="@* | node()"/>
</xsl:copy>

</xsl:template>
<xsl:template match="@*">
<xsl:element name="{name()}"><xsl:value-of select="."/></xsl:element>
</xsl:template>
</xsl:stylesheet>
External Schemas
If the transformation features are used on an operation, it is recommended to attach the schema, in XSD format, to
allow the WSDL generator in the J2EE container show the translated schema rather than the internal schema.
To build an external schema, XSD compatible tools can be used, provided by the target system or the XSD can be
generated using the View XSD option on the product schema editor and edited appropriately. For example:
Figure 10 – Example View XSD.
As with the transformations, place the schema in the $SPLEBASE/splapp/iws/resources directory (or
%SPLEBASE%\splapp\iws\resources on Windows platforms) with a minimum of read permission for the
product administration user.
Note:
Ensure the schema conforms to the XSD format.
Deployment of Inbound Web Services
Before an Inbound Web Service can be used it must be deployed to the J2EE container. The deployment process
performs the following:
» The deployment utilities generate JAX-WS complaint infrastructure to implement the web services interface for all
active Inbound Web Services. If Page Services are used, the Page Service is active and the Page Service
Inbound Web Services interface is enabled, then JAX-WS compliant infrastructures are generated to implement
the web services.
» The infrastructure includes the web service code, WSDL, annotations and any transformations/external schemas
that are defined on the relevant objects.

» The infrastructure is implemented into a J2EE compliant EAR/WAR file13 for deployment. This includes any
deployment infrastructure for the container.
» Depending on the technique used to deploy the EAR/WAR file, the file will be deployed and managed by the
J2EE container. The techniques that can be used are:
» Online deployment - An online transaction that will build and deploy the web services to the container. This
method is primarily designed for developers to manage the process.
» Command based deployment - A command line utility to build and optionally deploy the web services to
the container. This method is designed where IT groups manage the deployment independently of
developers such as in Production environments.
The web services are now available from the J2EE container. For example:
Figure 11 – Example deployed Inbound Web Services within Oracle WebLogic console.
A following set of guidelines should be applied to the deployment process:
» The deployment activity builds and deploys the web services to the container. The deployment locks the records
for the duration of the deployment to avoid conflicts for multiple developers. Avoid multiple deployments at the
same time by multiple developers. Co-ordinate deployment for greater efficiency.
» There is no cache internally within the product for the services but the J2EE container will cache the services for
performance reasons. This is automatically managed by the deployment process.
» Avoid deployment while web services are used as the J2EE container will delay the deployment activity till active
transactions are complete. This may cause delays.
» No outage is required for the deployment activity but avoid deployments at peak traffic times.
» A deployment is required for Inbound Web Services changes, changes to any schema in any object referred to
any operation in any Inbound Web Service and if external XSLT/XSD files are changed. This also applies to
legacy Page Services.
Online Inbound Web Service Deployment
One of the deployment methods supported is the online deployment which allows the build and deployment process
to be initiated online. This method is primarily to be used by developers who are designing, building and deploying
the web services to the container.
The online transaction is available from the Administration menu, when enabled. This facility displays the
deployment status of each service as well as a summary of other information. For example:
13 In Oracle Utilities Application Framework versions prior to V4.3.0.1.0 the deployment was a WAR file. It is now an EAR file as it includes Message
Driven Beans (MDB) deployment as well.

Figure 12 – Example online deployment
Note:
The online deployment utility may not reflect the state of any command based deployments (install patch
21793436 for Oracle Utilities Application Framework V4.3.0.1.0). It should not be used in environments that
will use the command based deployment. You can disable the online deployment facility by ensuring the
Application Service F1IWSDPL is not included in any User Group. It is highly recommended that the online
deployment be disabled in Production environments.
A few guidelines apply to the use of this facility:
» The tracking of Page Services, if enabled for use in Inbound Web Services, is not covered in the facility.
» The number of deployed Inbound Web Services includes the Inbound Web Services and the Page Services
deployed, if enabled. This is why the number may not match the number of Inbound Web Services exclusively.
» The deployment activity relies on the settings configured at the configuration level. For example, the server to
deploy to is contained in the configuration file.
» The online deployment is recommended for development use only and therefore does not support clustered
environments.
» The service revision reflects the internal deployed version not the version of the object deployed. Each time the
Inbound Web Service or underlying object in any of the operations changes, the status of the service is set to
Needs Deploy. When it is updated to Deployed as part of the process the service revision is incremented. It is
only incremented if it needs to be deployed and then successfully redeployed.
» The Last Deployment reflects the last successful deployment.
Command-based Web Service Deployment
A command line version of the deployment is available for use where developers are not responsible for deployment
activities. This facility is recommended for production environments, clustered environments, native installed
environments and IBM WebSphere environments.
The command based facility has some differences from the online deployment facility:
» The build part of the process can be done separately from the deployment activity. This is useful in production
environments where you can prepare the EAR file and the deployment can be done later.

» Alternative deployment tools can be used such as WLST, Oracle Enterprise Manager or Oracle WebLogic
console to deploy or refresh the deployment files. Refreshing a deployment is much quicker than a deployment
which saves time.
» Failures in the deployment are automatically logged into a deployment log

($SPLEBASE/logs/system/iwsdeploy.log or %SPLEBASE%\logs\system\iwsdeploy.log) which can
be checked if there is an issue.
To execute the script the following process:
» Login to the machine as the product administrator.

» Logon to the environment using the splenviron[.sh] utility
» Use the iwsdeploy[.sh] utility to build and/or deploy. Refer to the Server Administration Guide for the various
options for the utility.
To effectively use the facility the following guidelines should be used:
» For production implementations, which includes clustered environments, it is recommended to use the -b option
to build the EAR file and then use the appropriate deployment utility to complete the deployment. For clustered
environments, tools in Oracle Enterprise Manager or Oracle WebLogic can be used to deploy in parallel or serial
fashion.
» The build process can be prepared before the deployment to optimize the deployment time.
» For customers using native installations, it is recommended to use the command line utility to allow for micro-
management of the deployment files and use the deployment tools provided within Oracle WebLogic to deploy the
new version. It is highly recommended to use the Update feature of the deployment to efficiently update the
deployment files. For example:

Figure 13 – Example Update Deployment feature
Configuration of Inbound Web Services Deployment Name
Note:
This technique is recommended if you have multiple deployments in the same domain or use the new multi-
tenancy feature of Oracle WebLogic 12.2.x and above.
By default the Web Services Deployment Name will be set to Webservices14. Whilst this is recommended as the
value to use, it is possible to set the deployment to an alternative value using custom templates using the following
process:
» As the product administrator account logon to the machine that you wish to alter.
» Set the environment variables for the environment you wish to alter using the following command:
splenviron[.sh] -e <environment>
where
14 In IBM WebSphere implementations the name of the deployment is Webservices-{ServerName} where {ServerName} is the name of the
WebSphere server.

<environment> Environment Identifier
» Navigate to the templates directory under the directory designated by the $SPLEBASE environment variable (or
%SPLEBASE% on Windows).
» Copy the iws-build-WLS.xml.iws.template to cm.iws-build-WLS.xml.iws.template. This will tell

the system to override the product supplied template with a custom template. For IBM WebSphere
implementations use iws-build-WAS.xml.iws.template instead.
» Edit the file cm.iws-build-WLS.xml.iws.template and replace the WebServices value in the
deploy.name section with one you wish to use for the custom deployment name. Save the changes.
» Execute the initialSetup[.sh] utility as outlined in the Server Administration Guide to register the new
template and reflect the changes.
» Execute the online deployment or command line-based deployment utility to rebuild and deploy the Web Services
deployment.
Architecture Advice
The web services capability is recognized as an integration channel and an alternative to the online for integration
purposes. In production architectures, where both online and web services are used, it is recommended to separate
the deployments architecturally to allow for optimization of resource usage, security and administration.
When deploying the Web Services capability the following advice is recommended:
» In non-production environments it is highly recommended to deploy the Web Services capability to the same
servers as the online to minimize resources allocated and used by the environment. For customers using
embedded installations this is the default installation provided.
» In production environments, where clusters or multiple servers are used, it is recommended to deploy the Web
Services capability to a separate cluster or servers than the online capabilities. This will ensure that the channels
are separated accordingly. This requires a native installation rather than using embedded installations.
» In native installations, it is recommended to deploy to the same server as online for non-production environments.
For production environments use the previous outlined advice.
Querying WSDL for a Service
One of the deployment artifacts with each service is a generated Web Service Definition Language (WSDL) file that
contains the structure and security specification for the desired web service. Typically web service clients will import
the WSDL into their development platforms, directly or via web services repositories, to build the necessary
interfaces for that web service.
For these development platforms the URL to display the WSDL is in the following format:
http[s]://<hostname>:<port>/<context>/webservices/<webservicename>?WSDL
where:
<hostname> Host of product
<port> Port number allocated to Web Services
<context> Context configured for environment
<webservicename> Name of Inbound Web Service to get WSDL for

For example:
https://somehost:6500/ouaf/webservices/CM-User?WSDL
This will return the WSDL in the format that can be used by the web service client.
Legacy Customer Support
In Oracle Utilities Application Framework 4.2.0.2.0 and above, the Inbound Web Services capability was introduced
to replace the existing XML Application Integration (XAI). Customers using XAI should migrate to Inbound Web
Services with the following guidelines:
» Customers using the legacy XAI Base/CorDaptix Adapter, which uses attribute based external schemas, can use
the Page Service support, which negates the need to migrate to element based schemas in Inbound Web
Services.
» Customers using the legacy XAI Business Adaptor, should migrate each XAI Inbound Service definition to
Inbound Web Services an interface at a time. The following guidelines apply:
» The payload used in the Inbound Web Service will match the XML Application Integration service.
» Customers using the WS-Security feature of XML Application Integration should attach the default F1-
USERNAM15 security policy, as a Web Service Attachment, to each Inbound Web Service.
» XML Application Integration supported single operations in Web Services. Whilst Inbound Web Services
supports multiple operations it is recommended, for backward compatibility, to configure and name a single
operation the same as the Inbound Web Service name.
» The URL to invoke the Inbound Web Service will differ from the URL from XML Application Integration to
reflect the migration.
» Existing XML Application Integration services can co-exist with their Inbound Web Services equivalents till
the migration of the interface is complete. It is recommended to disable the XML Application Integration
service after it has been migrated.
» Customers migrating to Inbound Web Services should consider using the multiple operation capability to
consolidate your XML Application Integration services to reduce maintenance costs.
» Customers who migrate to Inbound Web Services can use Oracle Web Services Manager to add other transport
/message security and access rules.
» Customers who migrate to Inbound Web Services can monitor at the Service/Operation level using Oracle
WebLogic console and/or Oracle Enterprise Manager.
Note:
For more advice on migrating from XML Application Integration to Inbound Web Services should refer to the
Migrating from XAI to IWS whitepaper (Doc Id: 1644914.1) available from My Oracle Support.
Testing and Using Inbound Web Services
With the introduction of the Inbound Web Services, inbuilt testing facilities have been removed as typically the
development environment for the web services client application is used to test the web services rather than the
source environment itself. This section outlines a few common ways of testing web services that are available.
There are a number of resources that may assist in this area:
15 This is not supplied in Oracle Utilities Application Framework V4.3.0.3.0 and above as it is inbuilt.

» Using and Testing a Web Service from Oracle JDeveloper - Refer to Tutorials.
» Using and Testing a Web Service from Oracle Service Bus - Refer to Business Services. The resulting
Business Service can be used as Proxy Service as well.
» Using and Testing a Web Service from Oracle BPEL Manager - Refer to Synchronous Services.
» Using and Testing a Web Service using Oracle Data Integrator - Refer to Using Web Services.
» Testing using the Oracle WebLogic Web Services Test Client - Refer to Testing Web Services. This can be
used if the domain has Enable Web Service Test Page is enabled in the Advanced section for domain
configuration.
» Testing using SOAPUI - Refer to the Tutorial section. This will work for SOAPUI and SOAPUI Pro.
Note:
When using SOAPUI ensure your Web Service request conforms to the security protocols configured on the
server. You will need to provide credentials and perhaps transaction timestamps to test Web Services.
» Using and Testing a Web Service using Oracle API Catalog - Refer to Asset Lifecycle Administration Tasks.
Monitoring Inbound Web Services
Note:
The J2EE Web Application Servers have JMX based interfaces that can also be used at a raw level to
monitor Web Services and other server assets. Refer to the J2EE Web Application Server for more
information.
Once the Inbound Web Services are deployed they can be monitored using the metrics provided by the consoles
and administration tools.
Monitoring Inbound Web Services Using Oracle WebLogic console
One of the advantages of Inbound Web Services is that the Oracle WebLogic Web Service based metrics are
available to monitor the individual web services and even individual operations. These metrics are outlined in the
Web Services metrics documentation and Web Client Metrics. The metrics include tracking for execution and error
conditions. Details of metrics are also available from the Help pages from the console.
Note:
Customers using Oracle Web Services Manager can also use additional metrics available from that product.
Refer to Monitoring and Auditing Web Services for more information.
The Web Services Metrics are available from the Oracle WebLogic console using the following process:
» Login to the Oracle WebLogic console for the domain you wish to monitor using the appropriate credentials.
» Under Deployments select the Web Services deployment using the name you specified in the deployment
descriptor (the default is Webservices).
» On the Monitoring Tab, select the Web Service Clients tab to display the current metrics available. The metrics
displayed on this page are customizable using Customize this table. For example:

Figure 14 – Example Web Services Metrics
» By selecting individual services you can get a full list of metrics available for General, Invocations, Security and
Server specific metrics.
There are a few guidelines in using these metrics:
» The counts in the metrics are handy to ascertain how busy that service is as well as overall error rates.
» Authentication metrics and security metrics are useful for tracking compliance with the policies you have set
against the web service.
» Dispatch metrics represent the time from the invocation and sending the response to the client. This typically
includes execution time.
» Execution metrics represent the time the operation was invoked from WebLogic to the product and back.
» Response time represents the time the response was generated from the invocation.
» Last error metrics are useful for tracking how healthy the system is at the present time. If the last error metrics are
stale (old) then the issue may have been resolved. If they are fresh, then the issue is currently happening.
Monitoring Inbound Web Services Using Oracle Enterprise Manager
The metrics available from Oracle WebLogic are also available as metrics to Oracle Enterprise Manager. As
invocations are completed a summary of the metrics may be sent to the Oracle Enterprise Manager console. These
can be used in monitoring, SLA tracking and incident rules.
For more information about the Web Services metrics available from Oracle Enterprise Manager refer to Java EE
Web Service Endpoint Metrics. Additionally all the Oracle WebLogic Metrics are available from the Metric Palette for
Oracle WebLogic targets for specific web services. For example:

Figure 15 – Example Web Services Metric Palette
Note:
Metrics are only shown for executed Web Services. If your service is not executed in the selected period,
metrics may not be shown.
Note:
In some releases of Oracle Enterprise Manager, Web Services metrics are disabled by default. These can be
enabled by selecting them on individual targets or applying the Monitoring Template named Oracle Certified
FMW Web Service Template for J2EE Web Applications against the Web Services deployments.
Security Considerations
One of the major features of Inbound Web Services is the extended support for many security standards applicable
to the technology. This section summarizes the security facilities available for Inbound Web Services.
Inbuilt Security Annotation Support
The base functionality of Inbound Web Services supports security based annotations for backward compatibility. On
the Inbound Web Services, it is possible to attach a Web Services Annotation which defines the WS-Policy used
internally by the Inbound Web Service.
Note:
The use of inbuilt policy files is optional and is primarily designed for customers who are migrating from XML
Application Integration (XAI) to Inbound Web Services. It is recommended to avoid inbuilt annotations in
favor of policies attached at the J2EE container level.
The Inbound Web Services facility supports the concept of attaching a Policy Annotation, that is compliant with WS-
Policy to Inbound Web Services internally. This policy is defined as a Web Service Annotation of type Policy
Annotation. For example:

Figure 16 – Example Web Services Annotation
By default, the product ships with a default policy F1-USERNAM16 which is compatible with the WS-Security policy
supported by XML Application Integration.
Note:
In Oracle Utilities Application Framework 4.3.0.2.0 and above, it is possible to set the inbuilt policy at a global
level using the Feature Configuration for External Messages as Default Security Policy. This should be used
for customer migrating from XAI to IWS if they do not want to specify the inbuilt policy on all Inbound Web
Services. It is recommended customers using WS-Policy Support in the J2EE container refrain from setting a
global default. Refer to the online help for more additional information.
Note:
In Oracle Utilities Application Framework 4.3.0.2.0 and above, it is not required to attach a policy to every
Inbound Web Service. If no policy is attached to any service, internally or using Oracle Web Services
Manager, then a default HTTP Basic over HTTPS with a WS-Utility (WS-U) compliant timestamp is used.
Defining your own policies
Note:
The use of inbuilt policy files is optional and is primarily designed for customers who are migrating from XML
Application Integration to Inbound Web Services. It is recommended to avoid inbuilt annotations in favor of
policies attached at the J2EE container level.
It is possible to add your own inbuilt custom policies using the following process:
16 This is not supplied in Oracle Utilities Application Framework 4.3.0.3.0 and above as it is inbuilt.

» Build the custom policy file, in XML format, to comply with WS-Policy and the standards supported by the version
of the J2EE Web Application Server supported. For Oracle WebLogic customers, refer to the Security Policy
Assertions section of the documentation.
» Place the custom policy file in the $SPLEBASE/splapp/iws/resources directory (or

%SPLEBASE%\splapp\iws\resources directory on Windows).
» Create a Web Service Annotation record with the following information:

» Specify the first parameter as the uri with the format: "policy:<policyxmlname>" where
<policyxmlname> is the qualified name of the xml file that holds the custom policy.
» Set the attachToWsdl parameter to true to ensure the policy is attached to the WSDL for the web
service. This ensures that the calling web services client is notified in the WSDL of the policy applicable to
the Inbound Web Service. A value of false will not attach the policy to the WSDL. Regardless of the value,
the policy will be enforced. The value of this parameter should in line with your corporate security policies.
» Attach the policy to the Inbound Web Services you want it to be used upon.
» Rebuild and redeploy the Web Services deployment using the various deployment methods. This will bundle and
publish the policy.
WS-Policy Support
The J2EE Container (Oracle WebLogic and IBM WebSphere) supports various WS-Policy message and
authentication security policies. The Inbound Web Services capabilities support the following:
 A simple WS-Security user token policy, F1-USERNAM17, is supplied with Inbound Web Services. This is
primarily for development purposes or backward compatibility purposes with XML Application Integration
supported in past releases.
 Implementations can attach any valid WS-Policy that is supported by the J2EE Container that is used.
 Multiple policies can be attached to any Inbound Web Service. A calling web service client must adhere to
at least one of the policies attached.
 Custom Policies can be created as long as they are supported by the standards supported by the J2EE
Container.
 Message level and transport level policies are supported. Policies cannot be applied to part of a Web
Service only in the current release.
 Any policy can be attached within the Inbound Web Service before deployment or within the J2EE
Container after deployment. It is recommended that any container based or custom policy be attached
after deployment using the container console to reduce maintenance costs and increase flexibility.
Attaching the policy as part of the Inbound Web Service requires redeployment, whereas attaching it after
deployment in the J2EE container rarely requires outages or redeployment.
Container WS-Policy Information
Oracle WebLogic Oracle WebLogic Policies, Oracle Web Service Manager Policies and Securing Web Services.
IBM WebSphere Using WS-Policy to exchange policies in a standard format
Setting Default Security Policy
17 This is not supplied in Oracle Utilities Application Framework 4.3.0.3.0 and above as it is inbuilt.

Note:
This feature is available in Oracle Utilities Application Framework V4.3.0.2.0 and above via Patch 21890007.
It is possible to set a Web Services security policy internally within the product or externally via Oracle Web Services
Manager. If the policy is set internally, it can be set on each Inbound Web Services or globally as a default. To
configure the latter, it is recommended to modify a Feature Configuration of Feature Type External Messages with
a Default security policy in the format:
policy:<policy name>
where:
<policy name> Name of Policy XML file (including the .xml file name suffix). This can be
Oracle WebLogic, Oracle Web Services Manager or custom policies. For
example Wssp1.2-2007-Https-BasicAuth.xml
A Feature Configuration example is shown below:
Figure 17 – Example Security Feature Configuration
It is also possible to define the policy the spl.properties for the IWS deployment. Refer to the Server
Administration Guide supplied with your product for instructions on how to perform this task:
Parameter Usage
ouaf.webservices.security.defaultPolicy=policy:UsernameToken.xml This sets the WS-Security policy to use for

Inbound Web Services. Any Oracle
WebLogic, Oracle Web Services Manager
or custom policy can be specified.
Order of Precedence
As there are multiple places to define the default the following preferences are used to determine the setting:
 The Oracle Security default policy (Wssp1.2-2007-Https-BasicAuth.xml) is used if no default is

specified in any facility or on any Inbound Web Service.
 If the ouaf.webservices.security.defaultPolicy parameter is set on the spl.properties file

then this is used as the default.

 If the Feature Configuration of type External Systems contains a WS-Policy override then this value is
used.
 If there is a WS-Security based annotation is specified on the individual Inbound Web Service then this is
used for that service.
Web Services Manager Support
Customers using Oracle WebLogic Enterprise Edition can use the Oracle Web Services Manager that is bundled
with that product to use additional security facilities with Inbound Web Services:
» Oracle Web Services Manager supplies additional WS-Policy files to support advanced security at the transport
and message level. These additional policies are interoperable with base Oracle WebLogic policies.
» Oracle Web Services Manager allows access rules, known as policy conditions, to be configured for additional
security configuration based upon basic information, time and date as well as context values. For example it is
possible to configure conditions to control when and who has access to individual Inbound Web Services at the
container level. Simple and complex conditions are supported. For example:
Figure 18 – Example Web Services Policy Condition section

Figure 19 – Example Web Services Policy Condition predicates
Policies and rules attached from Web Services Manager are attached to the domain directly. They do not need a
rebuild or redeployment of the Inbound Web Services for each change.
Real Time Adapters

One of the major features of the Oracle Utilities Application Framework integration is the provision of Real Time
Adapters for outbound communications within a transactional context.
Overview of Real Time Adapters
The Oracle Utilities Application Framework supplies a number of adapters that can be called from within business
processes to provide near real time outbound communications within a transaction context. Typically outbound
communications are done asynchronously using Outbound Messages via the Oracle Service Bus adapters. In some
use cases, it may be necessary to process an outbound message as part of a business transaction while the
transaction is active. For example, the call center may need to send some email correspondence to a customer
while the customer is on the phone. The advantage of providing real time adapters is not only the processing of the
outbound message is done within the transaction context but the outcome of the transmission can be recorded as
part of that business process. Using the email example, the outcome of sending the message could be recorded as
a contact with the customer as part of the transaction.
One disadvantage of the use of these adapters is that if the transmission fails then the transaction may rollback
unless otherwise configured, which may not be desirable.
The following adapters are available:
» Email Adapter - Sending emails via SMTP servers.

» HTTPS Adapter - Sending information to external web applications
» JMS Adapter - Sending information to JMS resources such as JMS Queues and/or JMS Topics.

» SOAP Adapter – Sending information to SOAP based services.
Note:
In Oracle Utilities Application Framework 4.3.0.3.0 and above, there are separate Message Classes for JMS
Queues (RTJMSQSNDR) and JMS Topics (RTJMSTSNDR).
All these adapters are defined as Message Senders and Business Services.
Use Of Real Time Adapters
The Real Time Adapters can be used using two related techniques:
 Message Class on Message Sender - Each physical adapter is defined as a Message sender using a
Real Time Message Class. The invocation method of the adapter is marked as Real-Time. This sender
defines the physical attributes for the adapter such as the server and any credentials. This sender is
configured on the outbound message, external system etc as outlined in Outbound Messages.
 Business Services/Business Object - To initiate the real time integration, adapters use business
services or business objects to integrate into service scripts as part of the business process. In some
cases, these are dedicated services or a service that allow the formatting the message in a particular
format or using a Business Object on the Outbound Message object to format the message.
To use the adapter the following must be done:

» You must configure a message sender with the relevant context values per interface you wish to utilize.
» An outbound message type must be configured which corresponds to the interface that needs to exported. The
schema on the outbound message type should outline the data elements and format to be used by the adapter.
The exception to this rule is the email adapter. For more information refer to the Email Adapter section.
» An external system outlining the processing required for the message should be created.
» Code must be added to your business process as part of a service script in an algorithm or relevant location in the
processing. This code must add an outbound message of the type configured with the required data and await the
response from the adapter.
Email Adapter
The Email sender (Message Class RTEMAILSNDR) allows an email to be sent via the business service F1-
EmailService. This adapter is different in that it does not require an outbound message and external system to
complete. The Adapter uses the business service invocation with the email sender to send the information to the
SMTP server. The format of the email message is contained in the schema for the F1-EmailService. The
facilities supported in the SMTP server will depend on facilities provided by the SMTP server used for the execution.
For example, you cannot include images if the SMTP server used cannot support images.
The schema of the business service outlines the standard email schema with the following additions:
» Attachments can be file system based or use the Attachment object within the product.
» It is possible to reformat the raw XML using XSLT to provide standard formatting and branding.
» The format of the email must be supported by the SMTP server. It is possible to insert HTML, RTF, plain text etc
into an email message if the SMTP server supports the format.
» It is possible to specify one or more email senders, in list format, that contain the connection information for
sending emails. It is also possible to bypass the email sender and specify the SMTP connection information as
part of the interface directly for dynamic sending.

» Character sets specified in RFC 6531, RFC 2047, RFC 5890 and RFC 6532 can be used in the specification of
the charset parameter in the relevant section of the email schema.
Note:
Refer to the online documentation for examples and additional advice on the parameters.
For effective use of this adapter, it is recommended to consider the following:
» Avoid specifying the SMTP connection information on the F1-EmailService directly. Setup your Email Senders
with the connection information for the SMTP servers. Only use the override in the service for last resort
interfaces.
» Avoid specifying more than one SMTP server unless you are sending bulk emails.
» If bulk emails are necessary do not use the real time adapters as the transaction will not return until all emails
have been sent, which can cause unnecessary delays. Response codes for individual emails, within a bulk email
transmission, is not supported by the adapter.
» Work within the size and performance restrictions of your SMTP servers. Organizations will impose limits on
SMTP servers to avoid performance and denial of service issues.
» There is a Feature Configuration of type External Messages that has additional global settings:
» Number of Concurrent Email Senders - Use this value to avoid flooding email servers and avoiding false
denial of service attack messages. This would be the number of concurrent messages to be sent per sender.
This cannot be overridden on individual senders.
» Default Security Policy - This applies to all Inbound Web Services (as the feature configuration is for
external messages). If set this will auto attach the policy indicated to all deployments if no additional policies
are specified on the individual Inbound Web Service.
HTTP/S Adapter
Note:
In Oracle Utilities Application Framework V4.3.0.2.0 and above, there is a variation of the HTTP adapter that
sends the output in JSON format rather than HTTP format.
One of the adapters provided for real time integration is passing data to a form on an external web site. The format
of the transmission and its responses are dictated by the target system. The adapter sends the message to the
external web site with the following context parameters:
» Up to 9 parts (URL1 - URL9) of the URL - This allows for a dynamic URL that may need to be supported for the
target web application.
» HTTP Method - The HTTP standard method (POST or GET) required by the target web application.
» HTTP Proxy information - If the target web application is accessible via a proxy connection then the proxy host
and port must be specified.
» HTTP Transport Method - Whether the response from the target web application needs to be waited before
proceeding (Send or SendReceive)
» HTTP Form Data - The data to send to the target web application in the format required.
» Additional Parameters - Set of parameters that control the security access and connectivity.

Note:
Refer to the online documentation for examples and additional advice on the parameters.
There are two Message Classes available for this adapter RTHTTPSNDR or RTJSONSNDR. The classes support
HTTP (and HTTPS) as well as JSON format for REST based applications.
There are a number of guidelines that should be considered when using this adapter:
» This interface is a classic point to point integration between two web applications. Performance of the transaction
will be tied to performance of both applications. It is important to include a timeout on the interface to avoid issues
with slow responding target applications.
» The format of the request will be dictated by the requirements of the target application. You can use a schema to
model the required format. If attributes are needed, then an XSLT will be required as the schema format does not
support attributes.
» The format of the response (if you use SendRecieve) will be dictated by the target application. It may need to be
formatted, via XSLT, to be reprocessed by the product.
To use this adapter the following must be performed:
» Message Sender - Create a Message Sender using the real time HTTP Sender using the Message Class
RTHTTPSNDR. Specify on the context the values that are necessary for the interface. You can also
programmatically dynamically alter the adapter values using the Message Sender object with a Business Object
inside a Service Script.
» Outbound Message - Create an Outbound message type, including a format schema, which will be used to
initiate the transmission of this information. Your business process needs to add an outbound message of this
type for the sender to process.
» External System - Create or alter an External System to link the outbound message type to the Message Sender
with the Processing Method set to Real-time.
» Specify any translations on the message using XSL using the External System specification.
Supporting HTTPS
Note:
In Oracle Utilities Application Framework 4.3.x support for SSLv3 has been removed from this adapter in line
with Oracle directions. Customers using this adapter with SSL should migrate to TLS 1.2.
Note:
Oracle strongly recommends using certificates from trusted certificate issue authorities rather than using self
signed certificates.
One of the important features of the interface is to support encrypted communication across the network using
HTTPS over TLS. This protects the transmission of data across the network across sites. To use this facility a trust
store for the external application needs to be configured to support network encryption. Refer to the following
documentation on how to setup a trust store:
» Server Administration Guide - The specification of the trust store and its integration with the keystore.

» Keystore Configuration (Doc ID 2014161.1) - Additional instructions on how to create, manage and import to the
keystore/trust store for external applications.
Once the trust store is set, then the url should be prefixed with https to enable support.
Supporting JSON
Note:
This feature is available in Oracle Utilities Application Framework V4.3.0.2.0 and above only.
By default the format supported by the HTTP/S Real Time Sender is HTML or a variation of that format used by the
target application. It is now possible to also use JSON as the output format. This facility will automatically translate
the schema into JSON format using the following process:
» Create a Real Time JSON Message Sender - Create a message sender using the Message Class
RTJSONSNDR. On the context specify the URL and other parameters necessary to define the external address.
You can also programmatically dynamically alter the adapter values using the Message Sender object with a
Business Object inside a Service Script.
» Outbound Message Type - Create an Outbound message type with schema that will initiate the transmission of
this information. Your business process needs to add an outbound message of this type using the schema
provided for the sender to process.
» Additionally for JSON you need to specify the JSON Conversion Method. This will determine the parser that
will generate JSON from the schema. The following options are available:
Option Comments
Base JSON Conversion This uses a custom algorithm that can be added using the Oracle Utilities Application Framework SDK.
Standard API Conversion This uses the Jettison conversion algorithm (refer to ouaf_jar_versions.txt for details of the
version used)
XSL Transformation Use an XSL transformation (specified on the External System) to translate to JSON.
Note:
It is recommended to use the Standard API Conversion unless customization is required.
For example:

Figure 20 – Example JSON specification
Note:
Refer to the online documentation for additional advice.
SOAP Header Support
Note:
This feature is available for the Real Time HTTP and SOAP senders for Oracle Utilities Application
Framework V4.3.0.3.0 and above only.
When sending information across HTTP/HTTPS/SOAP to an external system then additional information may need
to be provided in the SOAP header for the target external system. It is possible to specify the following additional
information as part of the Message Sender specification:
Option Comments
SOAP Expiration Delay This is the timestamp duration, in seconds, for the transaction if WSSE is used. This is used with SOAP
Insert Timestamp to generate the end timestamp.
SOAP Insert Timestamp This will insert a WSSE format timestamp to set the freshness of the transaction. This generates a
Created and Expires elements containing timestamps based upon SOAP Expiration Delay.
SOAP Username Security Type The SOAP username security standard that the target system uses. Valid values are: BASIC, TEXT or

Option Comments
DIGEST.
To use any of these options, the values can be specified on the Real Time HTTP Message Sender Context. For
example:
Figure 21 – Example SOAP Header Context
Note:
Real Time JMS Adapter
One of the real time facilities is the ability to put a message on a JMS Resource within the J2EE Container. This
adapter supports the following:
» Local or Remote Resources - The JMS resources can be local (default) or remotely defined.
» Clustering/Distributed Support - The JMS resources can be housed in servers or a cluster using the facilities in
the J2EE Container.
» Support for native or foreign JMS resources - The JMS resources can be housed within the J2EE container or
using foreign JMS resources. For customers using foreign JMS providers need to specify the JMS provider within
a Oracle WebLogic domain initially.
» Support Topics and Queues - The JMS resources can be point to point or publish/subscribe.
Note:
Support for the Distributed Destinations and JMS Store And Forward features are transparent to the product
and can be used via configuration only within the Oracle WebLogic domain.
Setting up the JMS Resources
The first part of the process is to setup the JMS resources in your JMS container. For Oracle WebLogic customers
refer to the Oracle WebLogic JMS Integration whitepaper (Doc Id: 1308181.1) available from My Oracle Support for
additional JMS advice. For IBM WebSphere customers refer to the IBM documentation.
For Oracle WebLogic the process can be summarized as follows:
» JMS Server - Create a JMS server within the domain to house the JMS resources and target it to an appropriate
server. It is possible to house the resources in the product server for non-production but in production, it is
recommended to house in a dedicated server for resource management.

» JMS Module - Create JMS Modules to group JMS resources appropriately. It is possible to create a single JMS
Module to house all JMS resources but as management and monitoring metrics are available at JMS Module level
it is recommended to group appropriate resources in an appropriate number of JMS Modules.
» JMS Connection Factory - Create a connection factory per interface. This will be used by the product to connect
to the JMS Resources. This is important as connection pool attributes such as number of connections are
configured against the factory.
» JMS Queue/JMS Topic - Create a JMS Queue (point to point) or JMS Topic (publish/subscribe) within domain to
house the messages.
Note:
For additional configuration and advanced configuration refer to the Oracle WebLogic JMS documentation.
Note:
Ensure the JNDI name for the resources is prefixed appropriately (usually jms/) and is named appropriately.
Defining your JMS resources to the Product
Before any interface to JMS can be used the JMS resources defined in the last section must be defined to the
product with additional objects. The following must be defined:
» JNDI Server Connection - Define the location of the JNDI on the domain that holds the registry information for
the JMS resources in a JNDI Server object. This connection should locate the JNDI in URI format as well as
define the Initial Context Factory for connecting to the JNDI Server.
Note:
For Oracle WebLogic customers, ensure the protocol is t3 or t3s and use the Initial Context Factory as
weblogic.jndi.WLInitialContextFactory.
» JMS Connection - Define the connection factories defined on the JNDI Servers defined using the JNDI name of
the connection factory in JMS Connection objects. Connections are not linked to JMS resources till they are used
in the External System.
» JMS Queue/JMS Topic - Define each JMS Queue/Topic including its JNDI Name and JNDI Server in a JMS
Queue/JMS Topic object. For JMS Queues, if you are using IBM WebSphere MQ series the Target Client Flag
should be set to MQ otherwise JMS should be used as the JMS client. IBM WebSphere MQ series customers must
install the MQ Series JMS client in the CLASSPATH to use this client.
Note:
Setting up the Message Information
Once the JMS resources are defined in the product, the next stage is to use them to provide the configuration for the
integration:
» Create a Real Time JMS Message Sender - Create a Message Sender using the Message Class RTJMSQSNDR
for JMS Queues (for JMS Topics use RTJMSQSNDR instead available in Oracle Utilities Application Framework

V4.3.0.3.0 and above18) with the related JMS Connection and JMS Queue/JMS Topic linked. Refer to the online
documentation for additional advice on context values.
» Outbound Message Type - Create an Outbound message type with schema that will initiate the transmission of
this information. Your business process needs to add an outbound message of this type using the schema
provided for the sender to process.
SOAP Adapter
Note:
This sender is available in Oracle Utilities Application Framework 4.3.0.3.0 and above only.
If the target system is a SOAP based service, it is recommended to use the new SOAP Sender (SOAPSNDR) in
preference to other senders. This sender has the following advantages:
» Supports WS-Utility timestamps – The default Oracle WebLogic policy requires WS-Utility compliant
timestamps to be include in the header to avoid security issues. This adapter allows for the configuration of these
timestamps.
» Supports SOAP Headers – This adapter allows configuration of selected SOAP header elements. Refer to
SOAP Header Support for more details.
» HTTPS/HTTP Configuration – This adapter shares the functions of the HTTP/HTTPS adapter but is optimized
for SOAP services. Refer to HTTP/S Adapter for more information.
Outbound Messages
One of the most common integration scenarios is providing information from the product to external systems using a
variety of transports. The main interface is for this is the provision of outbound messages which register that an
event occurs for initiation of communication.
Overview of Outbound Messages
The outbound communications facility in the product uses the concept of outbound messages to register that a
business event has occurred. The outbound message has the following attributes:
» Outbound Messages are defined via an Outbound Message Type which determines the format and content of the
message to process from a product perspective. The Outbound Message Type includes an identifier to
individualize the communications formats used.
» Outbound Messages include a schema represented by a Business Object. This defines the unique view of the
F1-OUTMSG (Outbound Message) object used for the interface. The format is specified as redefinition of the
XML_SOURCE element within the schema.
» The Outbound Message can be created from any business event location within the product such as algorithms,
change handler etc. Typically this is achieved by interfacing to the Business Object with an add action. This is
typically done at a time the event that it is related to is created.
18 For customers on earlier versions, temporarily use the Real Time Queue Sender which supports both Queues and Topics.

Supported Adapters
Once the outbound message has been defined the next most important decision is to how it will be transported to
the target application via Message Senders. The transport adapters that are available in the product are:
» Email Sender - Send an email asynchronously in the background. This is also available as a Real Time Adapter.
» HTTP Sender - Send to a Web Application asynchronously in the background. This is also available as a Real
Time Adapter. When using this sender to send to Inbound Web Services on another Utilities product it is
recommend to use the SOAP sender (SOAPSNDR) to ensure timestamp compliance.
» JMS Senders - Send to a JMS Senders asynchronously in the background. This is also available as a Real Time
Adapter.
» Batch Senders - Send files etc asynchronously in the background.
» SOA Senders – Use Oracle Service Bus, using the Oracle Utilities Adapters for Oracle Service Bus to process
the outbound message.
Note:
For more information about these adapters refer to the online documentation.
Designing Outbound Messages
One of the key objects in outbound communications is the definition of the Outbound Message to be used for the
interface. The Outbound Message is defined using the Outbound Message Type object with the following
information:
» The identifier that will tell the product an event of a specific type has occurred.
» The schema, which represents the payload recording the information about the business event and any other
information needed for processing. The payload needs to define the information about the event that needs to be
processed and must be populated by the business process at the time the event occurred.
» The Priority of the event should be configured to tell the system the relative priority of the event with other events.
This is only used if multiple events exist to be processed and this is used to determine the relative priority of each
request. In this case the lower priority events are processed first.
» If this Outbound Message Type is used in the system, the cross reference objects are listed to show where it is
applicable.
An example of an Outbound Message Type is shown below:
Figure 22 – Example Outbound Message Type

When designing an Outbound Message Type the following is recommended:
» The payload should be designed against the F1-OUTMSG (Outbound Message) object. The XML_SOURCE should
be redefined to specify the payload.
» Ensure you include the F1-OutboundMessage data area in your schema. These attributes are needed for all
messages regardless of their type. It includes identifiers as well as control fields used by the Processing Methods
when it is processed.
» When creating the event, ensure that you specify the outboundMessageType to denote the event you are
registering.
» Ensure the payload is designed correctly to include ALL the information that is needed to be transmitted. Whilst it
is possible to update the information AFTER it is created it is recommended to capture as much as possible in the
initial creation event for efficiency reasons.
» Error conditions for the creation and processing of the message are recorded on the Outbound Message
automatically by the Processing Method used.
Designing External Systems
The last object to create when processing outbound communications is the External System. This object is designed
to define the external interfaces, the related outbound messages and how to process each message for the system.
Note:
For customer of older versions of Oracle Utilities Customer Care And Billing, the External System can use
the Notification and Workflow component of that product. As that component has been replaced with
Outbound Messages, any configuration relating to Notification and Workflow will not be discussed in this
whitepaper.
When defining an External System the following guidelines apply:
» Define an external system for each interface application or destination for outbound messages.
» Only use the Our Name in Their System if the target system needs to use a source provider that is separate to the
outbound message. This will need to be added in your transport layer using the Processing Method used.
» Template Systems encourage reuse if you have multiple external systems that use the same processing. For
example if you need to create a common set of systems to send the data, then templates can be used. The
Template Use tab will show where the template system is reused. Changes to a template are propagated to other
external system where it is referenced.
» The next crucial component of an external system is to define the Outbound Message Types that are applicable
to that external system. For each Outbound Message Type the following needs to be defined:
» The Outbound Message Type to be used for this external system.
» The preferred Processing Method for the interface. This will determine what technology within the product
will be used to process the outbound message.
» For some Processing Methods, the Message Sender to process the message which will contain the
transport to use as well as the connection details.
» The preferred Date Time format for the dates and times in the output. By default the product will use the
internally defined format, expressed as OUAF, but that format can be overridden if specified in an XSD format
schema which needs to be attached as part of this specification.
» If transformation from the Outbound Message schema is required by the target system, then it is possible to
specify a Message XSL file that contains the transformation.

» If the target system requires or specifies an XSD schema for the formatting, then this can be attached to the
external system for compliance. This configuration is used to specify external date and time formats.
An example of an External System definition is shown below:
Figure 23 – Example Outbound Message Type
Processing Methods
One of the main considerations for outbound messages is the way the outbound message will be processed within
the External System definition. There are a number of techniques available:
» Batch - This processing method indicates that the next execution of a batch process will process this data. The
Batch Control is attached to this method in the External System.
» Real Time - This processing method indicates the outbound message will be processed by the Real-Time
adapters.
» SOA - This processing method indicates that the outbound message will be processed by the Oracle Service Bus
Adapter. No Message Sender needs to be defined for this processing method as Oracle Service Bus is used to
determine how it is sent using its vast library of transports.
Note:
For more information this interface refer to the Oracle Service Bus Integration whitepaper (Doc Id:
1558279.1) from My Oracle Support.
» XAI - This is a legacy processing methods for customers using the deprecated Multi-Purpose Listener (MPL). This
is not recommended for use and this method is not documented in any example in this document. Customer on
older versions, using this adapter, should refer to MPL Best Practices (Doc Id: 1308165.1) and XAI Best Practices
(Doc Id: 942074.1) available from My Oracle Support.
JSON Support for Outbound Messages
In Oracle Utilities Application Framework V4.3.0.2.0 and above, it is possible to specify JSON as the output format
using the following configuration principles:

» If JSON is to be used then a Message Sender using the RTJSONSNDR message class must be used.
» The JSON conversion method is configured on the External System entry for the processing. The conversions
supported are documented in Mapping XML to JSON.
» On the Message Sender the following context values should be configured:
Context Type Suggested Values
HTTP Header19 Add the following values:

» Accept:application/json
» Content-Type:application/json
» Cookie:JSESSIONID=<jsessioncookie>
» OUAF-Security-Token:<sessiontoken>
HTTP Method POST or GET.
HTTP URL The URL for the call. This can be using the multiple URL context values or single context value.
Note:
Refer to the online help for more advice and information.
REST Based Web Services
Note:
REST Support is available in Oracle Utilities Application Framework 4.3.0.2.0 and above.
One of the newest methods for integration is Restful Services. REST based web services allow requesting systems
to access and manipulate textual representations of web resources using a uniform and predefined set of stateless
operations.
Limitations of REST Support
This implementation of REST is an initial set of facilities available for integration and is bundled in the online server
in this release. In future releases, this facility will be expanded to support additional functionality and be moved to an
integration implementation, along with Inbound Web Services.
The following limitations apply to this release of the REST support:
» IBM WebSphere not supported – In the present release only Oracle WebLogic is supported for REST
integration.
» Limited method support – Only the POST and GET methods are supported in the current release.
» Bundled in the Online Server - REST support is currently bundled within the online server channel. This is
planned to be implemented in the integration channel with IWS and MDB in a future release.
» No registry support - REST registry support is not available in the current release.
» Business Adapter Support - The REST support only extends to Business Services, Business Objects and
Service Scripts20 only.
19 The security session values are examples only. It will depend on the security of the target system.

» No WADL support - WADL file generation is not supported in the current release. It is recommended that in the
interim, invocations via JSON should use a generated sample transaction for definition purposes.
» No Oracle Web Services Manager Support - Integration between Oracle Web Services Manager and the REST
capability is not available in the present release.
» Limited monitoring capabilities - Monitoring of REST services is limited to monitoring the REST calls via servlet
metrics using Oracle WebLogic console or Oracle Enterprise Manager via the Oracle WebLogic management
monitoring API's.
» Open API Set - The REST Support may expose all the Business Objects, Business Services and Service Scripts
available in the product, subject to security controls.
» No Translation Support - The Inbound Web Services feature allows implementations to translate the request
and/or response using XLST based translations. This is not supported in the current release.
REST Security Fundamentals
Fundamentally REST is a conversational protocol which reuses the existing HTTP/S protocol. This is important to
understand for a number of reasons:
» To invoke a REST service a session token must be obtained for all subsequent calls from that location. In the
implementation of REST you must invoke a call from the location using the URL shown below, with the
authentication credentials, as a POST, and retrieve the session token generated by the J2EE Web Application
Server:
http://<host>:<port>/<context>/restSecurityToken
where:
<host> Host for the online server
<port> Port number for the cluster or server for online
<context> Context root set at installation time.
» This session token must be used for ALL subsequent calls from that client till either the non-activity timeout is
reached or the session is terminated by the J2EE Web Application Server.
» You cannot generate a new session token for each call as that may be interpreted as an invalid call by the J2EE
Web Application Service.
» The ouafSecurityToken (OUAF-Security-Token) value will be returned in the header that needs to be
reused for each subsequent call.
Setting Up REST Services
By default a REST based servlet is deployed to the online server with a predefined context to support REST based
services. By default all the following object types are exposed as Web Services:
» Business Objects
» Business Services
» Service Scripts
20 BPA and Plug-in scripts are not directly supported.

The associated schemas with these objects can be exposed in XML or JSON format for the interface.
Invoking REST Services
After getting a session token, the REST service can be invoked using a POST:
Object Invocation URL
Business Object https://<host>:<port>/<context>/<servletRoot>/ouaf/busObj/<businessObject>
Business Service https://<host>:<port>/<context>/<servletRoot>/ouaf/busSvc/<businessService>
Service Script https://<host>:<port>/<context>/<servletRoot>/ouaf/script/<serviceScript>
Where:
<host> Host Name for product server
<port> Port Number for online server
<context> Context set for the environment
<servletRoot> REST Servlet Root context. In Oracle Utilities Application Framework 4.2.0.2 and above the value
is rest and for Oracle Utilities Application Framework V4.3.0.4 and above, the value is
resources.
<businessObject> Business Object Name
<businessService> Business Service Name
<serviceScript> Service Script Name
For example:
http://somehost:6500/ouaf/rest/ouaf/message/busSvc/F1User
REST Formats
By default the transmission of data in REST is in XML format (application/xml). JSON is also supported by
setting the following variables in the header:
Header Variable Value
Content-Type Content-Type: application/json
Accept Accept: application/json
When using JSON the request payload may look like:
{"scriptname": {"input": {"fieldA": "ABC", "fieldB": 12345} } }

The corresponding output may look like:
{"scriptname": {"input": {"fieldA": "ABC", "fieldB": 12345}, "output": {"result":

"def"} } }
For schemas that include lists the JSON returns an instance for each row. For example:
{"scriptName": {"outputList": [ {"item": "one"}, {"item": "two"} ] }}
Mapping XML to JSON

The Oracle Utilities Application Framework automatically transforms XML to JSON when JSON is specified as the
output format. The transform uses the following rules:
» There are three different techniques available to convert between XML and JSON. These are available using the
JSON_CONVRSN_METH_FLG lookup. The three methods are:
» Standard API Conversion – This is a Jettison based conversion method.

» XSL Transformation – This allows an implementation custom method for transforming XML to JSON and
vice-versa. You must configure the custom XSL used for the transformation. Refer to the online help for
details of this configuration.
» OUAF JSON Conversion – This is the internal converter supplied with the Oracle Utilities Application
Framework. This section will document the transformation rules used by this conversion.
» The Oracle Utilities Application Framework schema data types are mapped to corresponding JSON data types.
The table below list the mapping:
Schema Data Type JSON Data Type
Group Object
List Array
String String
Lookup String
Number Number
Money Number
Date String
Date / Time String
Time String
Boolean Boolean
REST Services Security
REST based services uses session-based authentication, either by establishing a session token via a POST or by
using an API key as a POST body argument or as a cookie.
Note:
Oracle highly recommends that usernames, passwords, session tokens, and API keys should not appear in
the URL.
Guaranteed Delivery
By default, the REST support provides a real time request and response architecture. If the server cannot process
the REST call then an appropriate error is issued. For some implementations, it is necessary to guarantee the
transaction is completed, even asynchronously. A facility in the product allows an object to be specified as a
repository to persist the inbound transaction to process it when the resources are available.

The facility is specified as an algorithm on the installation record for the Guaranteed Delivery system event.
Note:
Individual products may ship algorithms for use in implementations. If no algorithm is supplied, then the
product cannot use this facility.
Note:
For more information about this facility refer to the online documentation and the F1-
GuaranteedDelivery business service.
REST Error Format
The REST interface produces a Problem Detail document in XML/JSON format that outlines the information about
the error that has occurred. The format is as outlined below:
Element Usage
problemType URL of format:

<protocol>://<host>:<port>/<context>/<restcontext>/ouaf/message/<category>/<message
>
Where:
<protocol> - Protocol used. Usually http or https.
<host> - Hostname or IP address of server generating error.
<port> - Port number of environment generating error.
<context> - Server context set at installation time.
<restcontext> - REST servlet context. Varies according to version (either rest or resources)
<category> - Message category within Oracle Utilities Application Framework
<message> - Message Number within Oracle Utilities Application Framework
title Fully qualified error message from Oracle Utilities Application Framework in CDATA format
httpStatus The HTTP Status code for the error
detail The long message description from the Oracle Utilities Application Framework in CDATA format
problemInstance Fully qualified URL with data and identity in format:

<protocol>://<host>:<port>/<context>/<restcontext>/ouaf/errorMessageInstance/<times
tamp>/<user>/<category>/<message>?request=<request>;method=<method>
Where:
<protocol> - Protocol used. Usually http or https.
<host> - Hostname or IP address of server generating error.
<port> - Port number of environment generating error.
<context> - Server context set at installation time.
<restcontext> - REST servlet context. Varies according to version (either rest or resources)
<timestamp> - Timestamp of error in ISO format.
<user> - User used for transaction.
<category> - Message category within Oracle Utilities Application Framework
<message> - Message Number within Oracle Utilities Application Framework

Element Usage
<request> - Request URL

<method> - HTTP method used for transaction
serverMessage Server Message group
messageCategory Message category within Oracle Utilities Application Framework
messageNbr Message Number within Oracle Utilities Application Framework
callSequence Delimited sequence of programs called.
messageText Fully qualified error message from Oracle Utilities Application Framework in CDATA format
longDescription The long message description from the Oracle Utilities Application Framework in CDATA format
For example:
Oracle Service Bus Adapter

It is possible to use the Oracle SOA Suite with the product to process inbound transactions from external sources by
just importing the Inbound Web Services as a target resource in any of the Oracle SOA Suite products. This is not
the same for outbound communications. In this case, it is recommended to use the Oracle Service Bus Adapters
specifically designed to provide outbound integration from the product.
The Oracle Service Bus Adapters allow two integrations for outbound communications from the product to other
targets via Oracle Service Bus:
» Outbound Messages - Communication from outbound messages via external system definitions to Oracle
Service Bus.
» Notification (Oracle Utilities Customer Care and Billing Only) - Able to instigate outbound communications
using the Notification and Workflow subsystem for legacy support.

The adapters allow the interface to be exposed as an adapter, business service or proxy service within Oracle
Service Bus as a source. Using Oracle Service Bus facilities, the payload from the product can be transformed
and/or sent to targets. Once the adapter is used, the full facilities within Oracle Service Bus are available to process
the transaction data.
For details of the adapters and advice on how to implement Oracle Service Bus refer to the Oracle Service Bus
Integration whitepaper (Doc Id: 1558279.1) available from My Oracle Support.
For details of Oracle SOA Suite integration refer to the Oracle SOA Suite Integration whitepaper (Doc Id: 1308161.1)
available from My Oracle Support.
Invoking Remote Web Services

For the majority of product implementations, inbound communications via Inbound Web Services will be the main
integration method but it may be necessary to invoke remote web services as part of an online transaction. The
product allows an external web service to be imported and mapped to data structures in the product to allow for
integration.
Web Services Adapter
Note:
Before using this adapter, familiarize yourself with the limitations of the interface to ascertain whether it is
appropriate for your use.
Note:
The Web Services Import feature supports Oracle Policy Automation rule bases and generic Web Services.
This section outlines the generic Web Services capability only.
The Web Services Adapter allows an external SOAP based Web Service to be invoked from a service script as part
of a transaction. To use this facility the following process needs to be completed:
» Build a schema to hold the Web Service - Create a schema based object to translate to within the product, for
the request and the response, from the Web Service. This will be used to process the payload from the Web
Service to internal product objects. This schema can be a single object as represented by the appropriate
Business Object or Business Service or multiple objects represented by a service script. The schema should
match the names and structure of the external service to minimize the need for mapping and translation. For
example:

Figure 24 – Example Web Services schema.
» Import the external web service using the Web Services Adapter. For example:
Figure 25 – Example Web Services Adapter menu item.
Note:
The Web Application server must have access to the external service either via the intranet or internet, as
appropriate. Failure to do so will result in a connection refusal.
» Specify the Adapter Name as well the physical implementation of the Web Service. Ensure that the security is
setup as per the specifications of the external Web Service.

Figure 26 – Example Web Services Adapter definition.
The following recommendations apply to the specification of the Web Service:
» Choose the Web Services Adapter for the Web Service Adapter Business Object rather than the Rulebase Web
Services Adapter, as the latter is reserved for Oracle Policy Automation support.
Note:
Not all products support integration to Oracle Policy Automation. Check with the product documentation for
clarification.
» The Data Areas are available to be generated after saving the Web Service Import as a Pending service. The
operations you want to generate Data Areas against must be Active.
» After generating the Data Areas, they can be edited but any changes are verified at runtime not design time like
other data areas are. The Data Areas are added as either the Request Data Area or Response Data Area on the
Web Service Adapter definition for each operation.
» A Service Script is needed to complete the processing which has the following basic flow:
» The Request Data Area needs to be populated according to your requirements. This needs to be done
before the service is invoked.
» The Web Service needs to be invoked using the F1-InvokeWebService Business Service with the Web
Service Adapter Name and Operation Name to invoke. This will initiate the call to the external web service.
» The Response Data Area is populated with response from the service and needs to be processed in other
objects or processed in the Service Script to complete the processing.
» Depending the WSDL format, the Request and Response Data Areas may be identical. It is recommended to
keep them separate from each other regardless to mitigate any future changes.
» Changes to the target Web Service will need the data areas to be regenerated. This can be done by editing the
Web Services Adapter and invoking the Generate function again.

Limitations of interface
The following limitations apply to the interface:

» Not all Web Services can be imported - The interface uses the Oracle JDeveloper libraries for importing Web
Services. These libraries do not support complex input parameters for RPC style Web Services and do not
support Document Style Web Services. The libraries also may have issues with very complex services and
services accessible via multiple proxies. It is recommended to attempt to import the service to ascertain
supportability.
» Attributes are not supported - The schema objects within the product are element based and do not support
attributes within Web Services without translation. It is not possible to directly map an attribute to an element in
the interface.
» Different Schemas for Request and Response - It is recommended to build different schemas to match the
request and the response for the Web Service call. If the Web Service has multiple operations, then a request and
response schema will be required for each operation.
Advanced Configuration
The following sections outline some advanced techniques for effective management and configuration of Web
Services.
Migrating Web Services
To migrate Web Services definitions it is recommended to use the Configuration Migration Assistant under the
following conditions:
» Use an existing Migration Request that contains the F1-FrameworkAdmin and/or F1-XAI-Admin Migration
Requests. This contains the steps for migrating Inbound Web Services. This Migration Request is also useful for
Outbound Message Type and External Systems.
» Build a custom Migration Request that contains the F1-InboundWebService, F1-OutboundMsgType, F1-
XAI-Sender and/or F1-ExternalSystem Migration Plans. This will migrate the meta-data definitions for
Inbound Web Services and related services.
Once the definitions are migrated it is recommended to run the deployment utilities to implement the definitions in
the target container.
Using Inbound Web Services with Oracle SOA Suite
The product can provide source and target services for use in Oracle SOA Suite. Using SOA Suite as the conduit for
integration has advantages:
» Oracle SOA Suite allows complex structures to be built to support complex processing scenarios from many
sources to many targets.
» Oracle SOA Suite supports proxy services, which allow implementations to isolate changes to the physical
implementation of the service to reduce maintenance costs.
» Oracle SOA Suite integrates with Oracle's security products to support complex security requirements.
» Oracle SOA Suite allows for diverse integration scenarios to be implemented acting as a central control point for
integration.
» Oracle SOA Suite has inbuilt management and monitoring capabilities to support accountability in integration.

» Oracle SOA Suite contains a wide range of technology adapters to support flexible integration scenarios across
multiple technologies.
Refer to Oracle SOA Suite Integration (Doc Id: 1308161.1) available from My Oracle Support for more information
about integration.
Registry Support
Note:
Inbuilt UDDI Support and UDDIExplorer have been removed from Oracle WebLogic 12c and above.
The integration capabilities outlined in this whitepaper can be registered in a Web Services registry for use across
an organization or for provisioning to partners. The advantages of using a registry for development include:
» Service definitions can be centralized across an enterprise. Developers who want to write cross application
integrations or product interfaces can use the repository rather than direct connection to product via their
development tools. For example, registries are supported from Oracle JDeveloper and Eclipse for enterprise
development.
» Service definitions can have additional information attached within the registry to help developers find and
manage the service interfaces.
The product does not include any registry capabilities and any registry interface is via the JNDI available from the
J2EE container. Customers who wish to use registry capabilities are recommended to consider registry applications
such as:
» Oracle Service Registry
» Oracle Enterprise Repository
» Oracle API Catalog

» Oracle API Manager
» Oracle API Gateway
» Oracle API Manager Cloud Service

The above registries natively hook into the JNDI of the product domain to load the Inbound Web Services into their
registries. Refer to the documentation supplied with these products to load and maintain Web Service catalog
entries.
Note:
Registries for REST based services provided by the Utilities products are not supported in the current release
of the Oracle Utilities Application Framework.
Oracle Integration Cloud Service Support
Note:
This registry facility currently is only certified for use with the Oracle Integration Cloud Service.
One of the integration scenarios is exposing a set of Inbound Web Services for use with the Oracle Integration
Cloud Service. The Oracle Utilities Application Framework supports a Web Service catalog feature that allows the

implementation to enable a subset of the available services to be accessible via the Oracle Integration Cloud
Service adapter for Oracle Utilities products.
This facility is available from the Administration Menu. For example:
Figure 27 – Web Service Catalog menu item
The Web Service Catalog will list the current services enabled in the catalog as well as the candidate services that
can be added to the catalog. From this function, it is possible to add services to the catalog or remove services from
the catalog. For example:
Figure 28 – Example Web Service Catalog
The following services are supported in the current release:

» Inbound Web Services - Services defined as Inbound Web Services. Refer to Inbound Web Services for more
information.
» XAI Inbound Services - Legacy services can be defined as long as they are defined as Inbound Web Services
as indicated in Legacy Customer Support.

» External Systems - The external system must have at least one Outbound Message Type and support
HTTP/HTTPS.
For more information about the use of these services for integration refer to the Oracle Integration Cloud Service.
Error Processing in Web Services
When an error occurs, whether it is infrastructure related or a violation of rules within the product, the Web Service
capability will generate an error message in the form of a SOAP Fault. When the error is generated from the product
it will contain the error message, message category and message number that is generated from the product as
attributes in the ResponseData element. For example:
Tag Content
faultcode Always set to env:Client
faultstring Always set to Client error
ResponseStatus Always set to F
ResponseText Always set to Error message or Java error.

ResponseCode Set to the message number within the product.
ResponseData Set to a number of attribute values:
» number - Set to the message number for the error within the product
» category - Set to the message category related to the area within the product
» text - Fully rendered and translated error text from message within the product
» numParm - Number of parameters associated with the message (used for substitutions)
» parmx - A list of parameter values associated with this message for some context.
Technical errors will contain java error message.
Category Set to the message category related to the area within the product
Number Set to the message number for the error within the product
CallSequence Delimited sequence of called objects if error was generated at a low level in call structure.
ProgramName Program or method that generated the message
Text Fully rendered and translated error text from message within the product
Description Description obtained from the message with the product
Table If the database generated the error, the table name associated with the error.
Field If the database generated the error, the field name within the table name associated with
the error.
High Availability Considerations
One of the architectural decisions to make during an implementation is the level of high availability needed to be
implemented to protect your availability. The Web Services capability has been designed to be flexible in terms of
architecture to support a wide range of high availability solutions.
The following guidelines should be considered when choosing an appropriate Web Services architecture:
» For non-production it is recommended to house the Web Services capability within the same servers as the rest
of the product. This will reduce maintenance costs and simplify environment management.
» In production, it is recommended to deploy the Web Services capability in dedicated servers to isolate channels
from other modes of access. This will allow for resource management for the Web Services capability to ensure
multiple channels can live within your capacity.

» For high availability, it is recommended to deploy the Web Services capability in a clustered environment 21.
Whilst, managed servers are supported, clustering usually represents lower costs in maintenance. Managed
servers require additional load balancing setup within the infrastructure or within middleware.
Refer to the Oracle WebLogic High Availability Concepts and Oracle Maximum Availability Architecture for additional
advice.
Refer to Oracle Utilities Application Framework Architecture Guidelines (Doc Id: 807068.1) available from My Oracle
Support for additional information and advice.
Message Driven Beans

In Oracle Utilities Application Framework V4.1.x and above, a Message Driven Bean approach was implemented to
allow for processing of transactions from JMS resources into the product. The approach was configuration based to
allow the Message Driven Bean implementation in the J2EE container to be hooked into the product object model as
a basic integration with JMS resources.
Architecture and Features
The architecture of the Message Driven Bean can be explained as follows:
» A set of JMS resources are defined in the JNDI associated with the product domain. These JMS resources can be
local or remote depending on the interface architecture. The resources typically defined includes:
» JMS Connection Factories which represent the connection used by the product to the JMS resources.
» JMS Queue/Topics which are the JMS resources that implement point to point and publish/subscribe
integrations respectively.
» A Message Driven Bean within the domain is defined per JMS resource to connect to that resource to process the
available messages in the JMS resources. The Message Driven Bean definition includes the product class to
implement the interface.
» Messages processed by the Message Driven Bean reference objects within the product including the type of
transaction and the payload to be used for the interface. The Message Driven Bean sends the payload to the
indicated object.
The following figure outlined this architecture:
21 It is recommended that a dedicated integration cluster be implemented.

J2EE Container (WebLogic/WebSphere)
JNDI
Message JMS Queue/Topic
JMS Connection Factory

Driven Bean
External Source
Message
Driven Bean JMS Queue/Topic
Objects
Oracle Utilities Application Framework
Figure 29 – Example Web Service Catalog
The architecture can be housed in individual servers, combined with other product channels and/or
managed/clustered environments.
Oracle WebLogic JMS Resource Guidelines
Prior to using the Message Driven Beans within the JMS configuration within Oracle WebLogic must be completed.
This will establish the JMS resources that the integration would use with Message Driven Beans.
The following needs to be setup within Oracle WebLogic, using user exits or the Oracle WebLogic console:
» JMS Servers – Servers to actually hold the JMS resources need to be defined within the Oracle
WebLogic domain.
» JMS Resources – A generic set of resources that must be deployed to the JMS Servers or to the main server
used by the product. At a minimum the following should be created:
» JMS Connection Factories – These provide the connection point for the product to access the
JMS Resources. These factories should be deployed (or subdeployed) to the Oracle WebLogic server(s)
definitions used by the Message Driven Bean. A connection factory should exit per JMS Queue created.
» JMS Queue – These are the actual queues used by the JMS to hold the transactions to be input or output.
At a minimum you should create a JMS Queue per channel. The created queues should be deployed
to the JMS Servers created earlier. It is also recommended to create error queues for each queue for use in
error processing within Oracle WebLogic.
» JMS Topic - These are the actual topics, for publish and subscribe transactions, used by the JMS to hold
the transactions to be input or output. At a minimum you should create a JMS Topic per channel per
transaction type. The created topics should be deployed to the JMS Servers created earlier.
Additional JMS objects such as JMS Modules and JMS Sub-deployments can also be used for management
purposes.
JMS Setup Tips and Techniques

When defining JMS resources within Oracle WebLogic the following guidelines should be considered:
» Name the JMS resources appropriately for your implementations and their purpose. This will aid in monitoring
from the Oracle WebLogic console or Oracle Enterprise Manager. Typical styles of names are to indicate the
target system or the type of transaction supported by the resource.
» The JMS Servers created can be deployed to dedicated server definitions within the Oracle WebLogic domain.
For non-production environments, it is possible to deploy the JMS server to the servers used by the product but
this is not recommended for production.
» It is recommended to define and specify error queues for Error Destinations to prevent poison requests potentially
clogging the queues. This will be used for failed deliveries, such as malformed messages, and expired deliveries.
» JMS Modules are used by Oracle WebLogic to allow for grouping of resources. If your implementation has a lot of
integrations then consider segmenting your interfaces into individual JMS Modules for monitoring and
management purposes.
» Subdeployments, like JMS Modules, are used by Oracle WebLogic for management purposes. They offer a
technique of monitoring individual channels using subdeployment name as a filter. Consider using the
subdeployments as a preference where appropriate. A technique is to name the subdeployment the same as the
resource it applies to.
» When creating JMS resources add the jms/ prefix to the JNDI names to provide a level of isolation from the
product resources for the JMS implementation. Descriptors will be generated within a jms subdirectory within
Oracle WebLogic containing the physical and configuration of your JMS resources.
» Message Driven beans support local and remote JMS resources. Additional configuration is required for remote
resources.
Note:
JMS Connection Factories should always be local for performance reasons.
» The product Message Driven Bean implementation does not support the JTA, Unit-Of-Order and Unit-Of-Work
features of Oracle WebLogic in the current release. If this feature is required, it is recommended to use Oracle
SOA Suite to implement these features.
» JMS resources can become part of domain templates, if this feature is used within Oracle WebLogic, to save time
in creating JMS resources in subsequent product environments.
For more information about JMS and additional best practices refer to Fusion Middleware Programming JMS for
Oracle WebLogic Server.
Configuration
Note:
This section uses user exits to create custom MDB definitions. Where appropriate the alternative use of the
Oracle WebLogic console will be highlighted in the process.
To implement inbound messages the Message Driven beans within the product need to be enabled and configured
to poll the queues and send the payload in those queues to the server. To do this a MDB needs to be defined to the
product for each queue to monitor for transactions. The definition of the MDB is contained in the ejb-jar.xml and
weblogic-ejb-jar.xml configuration files. These configuration files are used by the product at runtime to
execute object functionality within the product.
The process can be summarized as follows:

» Create the JMS resources in the Oracle WebLogic instance you wish to house them. This can be done from the
Oracle WebLogic console.
» Configure ejb-jar.xml located in the $SPLEBASE/splapp/businessapp/config/META-INF subdirectory

to define message bean and the container transaction configuration of the MDB. Refer to ejb-jar.xml
Configuration section of this document for details of the user exits to change.
» Configure the weblogic-ejb-jar.xml located in the $SPLEBASE/splapp/businessapp/config/META-

INF subdirectory to associate the message bean with the JMS resources allocated to the interface. Refer to
weblogic-ejb-jar.xml Configuration section of this document for details of the user exits to change.
The figure below summarizes the process and the user exits that will be discussed in subsequent sections of this
document.
Define JMS Servers
Define JMS resources

Oracle WebLogic
Define JMS Queues/Topics
Define JMS Connection Factories
Configure MDB
CM_config.xml.win.jms.include (Windows)
Configure config.xml CM_config.xml.jms.include (Linux/Unix)
CM_config.xml.win.exit_4.include (Windows)
CM_config.xml.exit_4.include (Linux/Unix)
CM_ejb-jar.xml.wls.jms_1.include
Configure ejb-jar.xml CM_ejb-jar.xml.wls.mdb.include
Configure weblogic-ejb-jar.xml CM_weblogic-ejb-jar.xml.jms.include
Figure 30 – MDB Configuration flow
Note:
The names used in this sample are for illustrative purposes only.
For publishing purposes an example configuration is used to illustrate the configuration. The configuration has the
following attributes:
» Two JMS Servers with one for inbound transactions and one for outbound (for error processing).
» Two sets of JMS Resources with one for inbound transactions and one for outbound. Each resource contains a
JMS Connection Factory which is subdeployed to the default myserver and a JMS Queue that is deployed to the
relevant JMS Server.
The figure below summarizes this configuration (with the relevant assigned names):

JNDI
Myserver (OUAF)
InConnect OutConnect
Connection Factory Connection Factory
JMS Server (asTestJMSIn)

Subdeployment ASTestIn
Queue
(asTestJMSIn)
JMS Server (asTestJMSIn)

Subdeployment ASTestIOut
Queue
(asTestJMSOut)
Oracle WebLogic
Figure 31 – Sample WebLogic JMS configuration
config.xml configuration
Note:
This section applies to embedded implementation only. Customers using native installations can perform the
steps in this section using the Oracle WebLogic console.
The embedded base installation of the product uses a template to generate the config.xml configuration file required
by Oracle WebLogic default domain to execute. Refer to the Server Administration Guide for details of the template
used and the available process for customizing the template.
When the initialSetup utility is executed the product resets back to the template. Any customizations to the
config.xml made using the console will be lost unless a custom template or user exits are not used.
Note:
All user exits outlined in this section must exist in the $SPLEBASE/templates directory.
To implement the JMS configuration in the config.xml using user exits the following process needs to be followed:
» Create or update the CM_config.xml.exit_4.include file (or CM_config.xml.win.exit_4.include

file on Windows). This user exit will define the JMS Servers defined to the Oracle WebLogic server. The format of
the include fragment is as the sample below:

Tag Contents
jms-server Root Tag for JMS Server (one per server)
name Name of the JMS Server (unique for Oracle WebLogic instance)
target Target server (myserver is the default installation)
» Create or update the CM_config.xml.jms.include file (or CM_config.xml.win.jms.include file on

Windows). This user exit will define the JMS Resources defined to the Oracle WebLogic server. The format of the
include fragment is as the sample below:
Tag Contents
jms-system-resource Root Tag for each JMS Resource

Tag Contents
name Name of the JMS Resource (unique for Oracle WebLogic instance)
target Target server (myserver is the default installation)
sub-deployment Subdeployment specification
name Name of Subdeployment
target Subdeployment target
descriptor-file-name Descriptor generated by Oracle WebLogic console that describes the internals of the
resource. This file will exist under $SPLEBASE/splapp/config. Initially this file will
not exist for embedded applications. In this case, it is recommended to generate the
initial file by using the Oracle WebLogic console.
These user exits will be included in the configuration files whenever initialSetup is executed.
Note:
Note:
The contents of user exit shown above are samples only and are XML fragments of the config.xml. Refer
to the Oracle WebLogic documentation for more information about the formats and tags used in the
fragments.
ejb-jar.xml Configuration
The next part of the process is to configure the ejb-jar.xml configuration file, in the
$SPLEBASE/splapp/businessapp/config/META-INF subdirectory, to define the MDB configuration for the
interfaces.
To make the changes to the ejb-jar.xml file using user exits the following process must be followed:
» Create or update the CM_ejb-jar.xml.wls.jms_1.include file to define a MDB definition for each inbound
queue you wish to monitor. Each entry would be an XML fragment similar to the example format:
Tag Contents
message-driven Root Tag for each MDB server (one per queue to monitor)

Tag Contents
description Short description of the MDB (for documentation purposes only)
display-name Name used for display within console for monitoring
ejb-name Name used for configuration (remember this)
ejb-class Must be set to com.splwg.ejb.mdb.MessageProcessor
messaging-type Must be set to javax.jms.MessageListener
transaction-type Must be set to Bean (or container for JMS Topics)
message-destination-type Must be set to javax.jms.Queue for JMS Queues (or javax.jms.Topic

for JMS Topics)
» Create or update the CM_ejb-jar.xml.wls.mdb.include file to define a MDB container definition for each
inbound ejb-name you defined earlier. Each entry would be an XML fragment similar to the example format:
Tag Contents
container-transaction Root Tag for each ejb-name (one per ejb-name)
method Tag to describe methods used by ejb-name (one per ejb-name)
ejb-name Name of ejb-name to associate with this method. You must use a valid ejb-
name from the last user exit.
method-name Must be set to onMessage
trans-attribute Must be set to NotSupported
Note:

Refer to the ejb-jar.xml schema for details of each of the tags.
weblogic.ejb-jar.xml Configuration
The last step is to associate the MDB configuration with the Oracle WebLogic resources. This involves changing the
weblogic-ejb-jar.xml configuration file, in the $SPLEBASE/splapp/businessapp/config/META-INF
subdirectory, to complete the configuration of the MDB.
To make the changes to the weblogic-ejb-jar.xml file using user exits the following process must be followed:
» Create or update the CM_weblogic-ejb-jar.xml.jms.include file to define an Oracle WebLogic JMS
resources and the linkage to the ejb-name for each MDB defined. Each entry would be an XML fragment similar
to the example format:
Tag Contents
weblogic-enterprise-bean Root Tag for each ejb-name (one per ejb-name)
ejb-name Name of ejb-name to associate with this method. You must use a
valid ejb-name from the ejb-jar.xml file.
message-driven-descriptor Root tag for the pool definitions
pool Must be set to NotSupported
max-beans-in-free-pool Maximum Number of concurrent threads for the MDB to read the pool
initial-beans-in-free-pool Number of threads available at MDB startup time
destination-jndi-name JNDI name of Queue/Topic for this MDB to monitor
connection-factory-jndi-name JMS Connection Factory for this MDB to use to connect to the above
queue.
Note:
Refer to for weblogic-ejb-jar.xml Deployment Descriptor Reference for more description of the above

tags and other tags available.
JMS Selector Support (Inbound)
In most cases the transactions in a JMS Queue or JMS Topic are single types of transactions or multiple transaction
types for a single source/target location. At some sites, common queues and topics can be implemented with
multiple messages inside for hub style interfaces. If not all messages in a Queue or Topic are for all products then
you must somehow indicate which messages are for what products.
There is a mechanism built into the JMS standard to address this. It is possible to place custom keywords in the
JMS Header or JMS Message Properties section of the JMS Message to help delineate the message for application
side filtering. The JMS subscriber (Topics) or JMS consumer (Queues) can then use JMS Selectors to configure
which messages should be read. JMS Selectors can be used to filter using custom keywords in the Header and
Message Properties (JMS Selectors cannot filter on the body of the message).
To use JMS Selectors with the MDB the CM_ejb-jar.xml.wls.jms_1.include configuration file must be
altered to include the activation-config set of configuration entries. The example below illustrates a JMS
Selector for a JMS Topic with a JMS Selector where the value is ProcessMe is set to YES in the JMS Message
Properties (as ProcessMe is not a valid JMS Header attribute).
You are limited to one messageSelector but the *value element supports multiple criteria. JMS Selectors can be
as simple as this or more complex within the JMS standard.
MDB versus Oracle SOA Suite
The Message Driven Bean is a basic interface to JMS resources for processing information inbound to the product
from those resources. It is not the only method of processing JMS resources available for implementations. It is
possible to use components of Oracle SOA Suite such as Oracle BPEL Manager and Oracle Service Bus to
interface to JMS resources to send information to the product.
The use of Oracle SOA Suite for interfacing from JMS resources has the following advantages over the native
Message Driven Bean approach:
» Oracle SOA Suite allows for greater control of messages - The capabilities of the JMS JCA compliant
adapters for SOA Suite allow for control of messages within those products at the interface level as well as
allowing pre-processing before it is sent to the product. For example, it is possible to filter payload data within
SOA Suite before sending the data to the product for processing. The MDB cannot access the payload only the
header information for filtering.

» Oracle SOA Suite has better header support - The JMS Adapters for SOA Suite can retain header information
for use with the product. Typically the MDB strips off the header to send only the payload to the product. It is
possible to transform elements within the JMS header to include it as part of the payload if required.
» Oracle SOA Suite has better high availability support - Whilst SOA Suite can use the same clustering facilities
as the MDB approach, it also has proxy support to isolate the transactions from their physical implementations.
This can reduce maintenance effort when managing product interfaces.
» Oracle SOA Suite has inbuilt maintenance capabilities - Transferring of JMS resources and SOA Suite assets
are managed within the SOA Suite directly, thus avoiding the need for user-exits.
» Oracle SOA Suite has inbuilt monitoring capabilities - The MDB approach relies on the Oracle WebLogic JMX
interface to provide monitoring capabilities and metrics which can be limiting for low level monitoring. Oracle SOA
Suite, on the other hand, includes additional dedicated monitoring capabilities to allow for varying levels of
monitoring.
Generally the MDB is recommended for simple interface needs whereas SOA Suite is recommended for more
complex and more critical integrations where low level monitoring is required.
SPML Web Service Support
Note:
This facility is designed for legacy Oracle Identity Manager integration support. Refer to Oracle Identity
Management Suite Integration (Doc Id: 1375600.1) available from My Oracle Support for more details.
In past releases of the Oracle Utilities Application Framework, the XML Application Integration layer provided a
Service Provisioning Markup Language (SPML) compliant adapter to allow older Oracle Identity Manager releases22
to provision, maintain and disable user identities.
Set the following properties in the spl.properties for the IWS deployment to enable this facility. Refer to the
Server Administration Guide supplied with your product for instructions on how to perform this task:
Parameter Usage
ouaf.ws.deploy.spml=[true | false] Set this parameter to enable SPML support.

This should only be used if the version of
Oracle Identity Manager uses the SPML
based adapter.
com.oracle.ouaf.ws.spml.trace=[true | false] If the SPML adapter is enabled, this

parameter can write diagnostic information
to log files. This is useful for diagnosis in
initial configuration. It is recommended to
be set to false in production.
com.oracle.ouaf.ws.spml.securityPolicy=policy:UsernameToken.xml This sets the WS-Security policy to use for

SPML. If not set then this will inherit the
value from the IWS container.
22 Later versions of Oracle Identity Manager use the IWS services natively.

It is also possible to set the above settings in a Feature Configuration of Feature Type External Message with the
following:
Parameter Usage
Default SPML Service Security Policy Default WS-Security policy to use with the SPML interface. The
format is:
policy:<policy name>
where
<policy name> is the WS-Policy name XML file (including the
.xml file suffix). Oracle WebLogic, Oracle Web Services Manager or
custom policies are supported.
Support SPML Deployment in IWS Set to true to deploy the SPML interface within Inbound Web
Services. Default: false
For example:
Figure 32 – Sample SPML Feature Configuration
Frequently Asked Questions
Why doesn't my Web Service appear in Oracle WebLogic?
Ensure that it is active prior to deployment. Only active web services are deployed to the container.
Why doesn't my Web Service appear in Oracle Enterprise Manager?
Note:
Web Service metrics only apply to all Inbound Web Services (IWS) based web services. They do not apply to
XML Application Integration (XAI) Inbound Services.

You must enable Web Services metrics using the Oracle Certified FMW Web Service Template for J2EE
Application, against the Application Deployment that houses the Inbound Web Services, in the Monitoring
Templates within Oracle Enterprise Manager to view timely Web Services metrics. Oracle Enterprise Manager only
displays metrics for Web Services that have been executed. Definitions of Web Services are displayed in the Oracle
WebLogic console or Oracle Fusion Middleware Control.
How do I turn a query portal into a Web Service?
One of the most common scenarios is to expose a query service which uses SQL to filter a set of rows in a table or
group of tables and expose that as a Web Service.
The first step in the process is to create the SQL you want to use for the interface. It can be any valid static SQL or
use host variables for the WHERE clause (filtered). Once complete the SQL you can incorporate that SQL into a Info-
Explorer Zone. You can use any of the explorer zone types but F1-DE-SINGLE is the most commonly used, as it
supports a single SQL statement with multiple filters (up to 15) as well as hidden filters (up to 5). Hidden filters are
typically not displayed in the UI for criteria (remember explorer zones can be used on the user Interface as well) but
for web services they can be used as normal filters (this means you can use up to 20 filters all up).
Once the zone is complete, you now need to define it as a Business Service. The product ships with a generic
service called FWLZDEXP which allows a explorer zone to be defined as a Business Service. If you open any
Business Service based upon FWLZDEXP you will see some examples. The schema is standard and self
explanatory in terms of the structure. The schema pattern looks like this:
» Zone element - maps to the ZONE_CD element and the default value is the zone name you just created. This
links the business service to the zone.
» Filter elements - You name the filters as you like but the mapField is set to Fx_VALUE where x is the filter
number corresponding to the filter element in the zone definition.
» Hidden filter elements - You name the filters as you like but the mapField is set to Hx_VALUE where x is the
filter number corresponding to the hidden filter element in the zone definition.
» results group - this holds the elements of the result set. Each element in your result set has a tag name and is
linked to the COL_VALUE mapField and the row element is lists the SEQNO of the column. This corresponds to
the column number in the results set in the zone.
An example schema is shown below for the F1-USGRACML zone, which returns the access modes for a user group
and application service filters.
In the example, the userGroup and applicationService elements are the filters and the rows would contain a
list of accessModeDescr. This is just a simple example to illustrate the point. Products do supply examples that
can be used as illustrations of the interface.
Once the Business Service is defined it can simply be defined as a Web Service by registering an Inbound Web
Service using the Business Service definition as a basis.

How does the internal security model work with Web Services?
The security model within the product uses an application service specification connected to the underlying services
to ascertain which groups of users have access to that service. The application service is linked to the appropriate
user groups outlining the level of access granted to the users attached to that user group.
The Web Service definitions specify an application service to set the security settings for that service. This has the
following flexibility:
» Macro or micro level security - It is possible to allocate individual application services to individual web services
or allocate common application services across web services. This allows a balance between security and
maintainability. To minimize costs of maintenance, it is recommended to share application services across web
services unless your security requirements dictate otherwise.
» User Groups define access - Regardless of the application service the level of access is defined on the
connection to the user group. This means the application service entry can be reusable across user groups
supporting differing levels of access.
The style of the implementation of the combination of Web Services to application services and application services
to user groups, with level of access, is as flexible as your requirements.
Can I use Self Signed Certificates?
Whilst it is possible to use self signed certificates for traffic encryption, it is highly recommended that certificates from
a recognized certificate issuer be used for the transmission of data for the product.
Do I need to include timestamps in my web services calls?
Whilst the default security does not require timestamps for transactions in the SOAP headers for inbound and
outbound communications, Oracle recommends using this facility to avoid security timing and replay issues. The
provided SOAP header needs to conform to the SOAP 1.1 standards for these elements.
This can be configured to be generated for outbound communications from the product but the calling application
must provide this information for inbound communications.
For example:
Note:
If the WS-Policy used is compliant with the WSSE standard then the timestamps will be required. Failure to do
so will generate SOAP Faults such as Timestamp validation failed (InvalidSecurity) or Message
Expires time has passed (MessageExpired).
Note:
Customers using Oracle Service Bus can configure the Business Service or Proxy Service to include this
information using Message Level Security or Oracle Web Services Manager. Customers using other
components in Oracle SOA Suite refer to the Security Guides for instructions on providing this information.

What is not supported in IBM WebSphere for Web Services?
The functionality outlined in this whitepaper is available in Oracle WebLogic implementations of the product. Due to
the differences in standards supported and features of IBM WebSphere the following restrictions are applicable to
IBM WebSphere implementations:
» No Oracle Web Services Manager Support - The access control and WS-Policy features of Oracle Web
Services Manager are not supported on IBM WebSphere.
» Limited MDB Support - The Message Driven Beans implemented in Oracle Utilities Application Framework has
limited features in IBM WebSphere directly without additional products from IBM. The following are what is not
supported in IBM WebSphere in the MDB:
» No Inbound Web Services MDB Server Support - The Message Driven Bean implementation in the
Inbound Web Services EAR implementation is not available for IBM WebSphere implementations.
Customers wishing to use MDB within IBM WebSphere should use the WAR file implementation that is
included in the online server EAR file or additional products. Refer to the product installation
documentation for more information.
» Error Queue Support - Automatic support for error queues are not supported for IBM WebSphere. In
Oracle WebLogic implementations, when the product refuses an inbound JMS Message from a JMS
resource, also known as a poisoned message; it will automatically place the message on the designated
error JMS resource, if configured within Oracle WebLogic. This is not supported within the IBM
WebSphere JMS implementation. Refer to the IBM WebSphere documentation for techniques pertaining
to poison messages and backout queues that can be used to replicate this feature.
» Different WS-Policy Support - The WS-Policies supported by IBM WebSphere vary to the policies supported by
Oracle WebLogic. Refer to the IBM WebSphere documentation for WS-Policy support. WS-Policy files can only
be attached directly from the console. Annotations and defaults are not supported by IBM WebSphere.
» No Oracle Service Bus Support - The Oracle Service Bus adapters are not certified for use with IBM
WebSphere as Oracle Service Bus is not certified for IBM WebSphere. Customer wanting to use the adapters
must implement Oracle Service Bus and the adapters within Oracle WebLogic.
» Limited Oracle Enterprise Manager Support - Web Service Metrics from IBM WebSphere are not supported by
Oracle Enterprise Manager unless using the Non-Oracle Middleware Pack.
What are poison requests?
A poison request is an inbound request that is so malformed or invalid that the product cannot recognize it enough
to even start processing. Typical examples are malformed request messages that have insufficient content to even
be processed by the product.
Typically these messages are handled a number of ways:
» Inbound Web Services - A SOAP Fault will be sent as a response indicating the appropriate error.
» Message Driven Bean - The JMS resources should be configured to include an error destination which will
receive the message. Refer to the Delivery Failure settings in Oracle WebLogic for more information.
It is recommended that poison requests should never enter the target system and are the responsibility of the source
system. Refer to the Avoiding the Inbound Monkey discussion of these principles.

Oracle Corporation, World Headquarters Worldwide Inquiries
500 Oracle Parkway Phone: +1.650.506.7000
Redwood Shores, CA 94065, USA Fax: +1.650.506.7200
CONNECT W ITH US
blogs.oracle.com/theshortenspot Copyright © 2007 - 2016, 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
facebook.com/oracle 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
twitter.com/theshortenspot means, electronic or mechanical, for any purpose, without our prior written permission.
oracle.com Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and
are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are
trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. 1216

Integrating Apex With Google Maps 169532

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Integrating Apex With Google Maps 169532

Загружено:

Авторское право:

Доступные форматы

Web Services Best Practices

Oracle Utilities Application Framew ork

Web Services Capabilities 6

Web Services Overview 7

XML Based Services 7

Page Based Services 9

Simple Object Access Protocol Style 9

Web Service Standards 9

Web Services in the Container 10

Inbound Web Services Overview 11

Message Driven Beans (MDB) Overview 12

REST Based Support 13

Real Time Adapters Overview 13

Outbound Messages Overview 14

Oracle Service Bus Overview 14

SOA Suite Integration Overview 15

Web Services Adapter Overview 15

Inbound Web Services 16

The Inbound Web Service Development Process 17

Designing Web Services 18

Defining an Inbound Web Service 19

1 | Web Services Best Practices - Oracle Utilities Application Framework

Enabling Page Services in Inbound Web Services 22

Translation of formats using XSL 23

Deployment of Inbound Web Services 26

Online Inbound Web Service Deployment 27

Command-based Web Service Deployment 28

Configuration of Inbound Web Services Deployment Name 30

Querying WSDL for a Service 31

Legacy Customer Support 32

Testing and Using Inbound Web Services 32

Monitoring Inbound Web Services 33

Monitoring Inbound Web Services Using Oracle WebLogic console 33

Monitoring Inbound Web Services Using Oracle Enterprise Manager 34

Inbuilt Security Annotation Support 35

Defining your own policies 36

Setting Default Security Policy 37

2 | Web Services Best Practices - Oracle Utilities Application Framework

Real Time Adapters 40

Overview of Real Time Adapters 40

Use Of Real Time Adapters 41

SOAP Header Support 45

Real Time JMS Adapter 46

Setting up the JMS Resources 46

Defining your JMS resources to the Product 47

Setting up the Message Information 47

Overview of Outbound Messages 48

Designing Outbound Messages 49

Designing External Systems 50

JSON Support for Outbound Messages 51

REST Based Web Services 52

3 | Web Services Best Practices - Oracle Utilities Application Framework

REST Security Fundamentals 53

Setting Up REST Services 53

Invoking REST Services 54

Mapping XML to JSON 54

REST Services Security 55

REST Error Format 56

Oracle Service Bus Adapter 57

Invoking Remote Web Services 58

Web Services Adapter 58

Migrating Web Services 61

Using Inbound Web Services with Oracle SOA Suite 61

Oracle Integration Cloud Service Support 62