XAI Best Practices

An Oracle White Paper
April 2010
XAI Best Practices

Oracle Utilities Application Framework
XAI Best Practices Oracle Utilities Application Framework
Introduction ....................................................................................... 4
Conventions used in this document ............................................... 4
XAI Introduction ................................................................................. 5
Features of XAI ............................................................................. 6
Maintenance Objects versus Configuration Objects....................... 9
XAI Receivers .............................................................................. 10
XAI Senders ................................................................................ 12
XAI Maintenance Object Based Services ........................................ 13
Installing and Configuring the XAI Schema Editor........................ 14
Defining a Maintenance Object Based Schema ........................... 16
Testing Services .......................................................................... 21
Using The Schema Editor with non-Windows server platforms .... 21
XAI Configuration Objects Based Processes ................................... 22
Registering Objects as XAI Inbound Services.............................. 22
Testing Configuration Object Based XAI Inbound Services ......... 24
Web Services Integration................................................................. 24
Generating Web Service Definition Language ............................. 24
Using Web Service Discovery with a UDDI Server ...................... 25
Transaction Types instead of Methods ........................................ 26
Using XAI Services with Fusion Middleware ................................ 28
MPL Based Processes .................................................................... 29
Senders and Receivers ............................................................... 29
The Role of XAI Staging Object ................................................... 30
Configuring a File based input ..................................................... 33

Configuring an XML File based input ........................................... 38
Configuring a JMS based input .................................................... 43
Configuring an LDAP based input ................................................ 50
Configuring Outbound Messages ................................................ 50
Configuring a File based output ................................................... 55
Configuring a JMS based output .................................................. 58
Configuring an email based output .............................................. 65
Configuring a HTTP Server based output .................................... 69
Best Practices ................................................................................. 74
Maximize Reuse .......................................................................... 74
Validation of schemas ................................................................. 76
Defaulting Transaction Types/Search Types ............................... 76
Use Configuration Objects rather than Maintenance Objects ....... 77
Minimize use of the Schema Editor Client.................................... 78
Migrating between Classic and XAI Servlet ................................. 79
Flushing the XAI and MPL Caches .............................................. 80
Migrating XAI Inbound Services between environments .............. 81
When do I need the MPL? ........................................................... 82
Runtime Security of XAI Inbound Services .................................. 83
Security of the Multi-purpose Listener.......................................... 85
Use of Real Time Senders........................................................... 86
Use of JMS reply and error queues ............................................. 87
JDBC Pooling .............................................................................. 87

Setting Error Tolerances .............................................................. 88
Use of character sets within XAI .................................................. 88
Setting locations for use with XAI ................................................ 89
Error messages in XAI ................................................................. 89
XAI Log File Management ........................................................... 90
MPL Thread Pooling .................................................................... 91
Outbound Messages Configuration Options ................................ 93
XAI Administration ....................................................................... 94
Activating and Deactivating Services ........................................... 96
Activating and Deactivating Receivers ......................................... 96
Receiver Best Practices............................................................... 97
Sender Best Practices ................................................................. 98
Files Processing Best Practices................................................... 99
Overriding the XAI Options using Adhoc Parameters
JAAS Based Security
Support of Effective User
......... 99
....................................................... 100
................................................. 103
Introduction
This white paper outlines the common and best practices used for the XML Application
Integration (XAI) component of the Oracle Utilities Application Framework. The advice in this
whitepaper is based upon Oracle internal studies and customer feedback around the world. This
information is provided to guide other sites in implementing or maintaining the product in
production.
While all care has been taken in providing this information, implementation of the practices
outlined in this document may NOT guarantee the same level of (or any) improvement. Not all
practices outlined in this document will be appropriate for your site. It is recommended that each
practice be examined in light of your particular organizational policies and use of the product. If
the practice is deemed beneficial to your site, then consider implementing it. If the practice is not
appropriate (e.g. for cost and other reasons), then it should not be considered.
This whitepaper covers the latest version of the Oracle Utilities Application Framework. Where
advice is applicable to other versions of the product, a specific reference to that version is
displayed.
Note: For publishing purposes, the word "product" will be used to be denote all Oracle Utilities Application
Framework based products.
Note: Advice in this document is primarily applicable to the latest version of the Oracle Utilities Application
Framework at time of publication. Some of this advice may apply to other versions of the Oracle Utilities
Application Framework and may be applied at site discretion.
Note: In some sections of this document the environment variable $SPLEBASE (or %SPLEBASE%) is used.
This denotes the root location of the product install. Substitute the appropriate value for the environment used at
your site.
Conventions used in this document

The advice in this document applies to any Oracle Tax and Utilities product based upon Oracle
Utilities Application Framework versions 2.1 and above. Refer to the installation documentation
to verify which version of the framework applies to your version of the product. For publishing
purposes the specific facilities and instructions for specific framework versions will be indicated
with icons:
Advice or instructions marked with this icon apply to Oracle Utilities Application
Framework V2.1 based products and above.
XAI Introduction
One of the major components of the Oracle Utilities Application Framework is the ability to
interface to the product using XML with multiple sources using multiple channels to interface in
and out of the product. The XML Application Integration (XAI) component of the Oracle
Utilities Application Framework is used to interface in and out of the product using XML. The
figure below illustrates the basic flow between the interface channels, the various parts of XAI
and the objects within the product:
Figure 1 - Overview of XML Application Integration
The XAI component is made up of a number of parts:
XAI Client An optional Software Development Kit to build XML Schemas

describing the XML interface between external systems and the product's maintenance
objects.
Note: The XAI Client has been largely replaced with the use of Configurable Objects (see later) to
define richer interfaces.
XAI Server The servlet based runtime that interfaces the XML request with the
appropriate base service and formats the response according to the specification of the
XAI Inbound Service. The XAI Server includes a table based registry, which is loaded
into a cache at startup time, which contains service and XAI servlet configuration
information. From a runtime perspective, the XAI Server accepts XML requests over
HTTP/HTTPS protocol.
Multi-purpose Listener (MPL) An optional java based Enterprise Service Bus based
server that interfaces to a number of alternative data sources to offer interfacing from
near real time sources. The MPL has its own cache to load its configuration into at
startup time. This server can be replaced with an alternative SOA based Enterprise
Service Bus if required.
Note: Some of the internal functionality is exclusive to the MPL at the present time. Even though an
external SOA ESB is used the MPL may still have a role to play.
These parts work in conjunction to provide a comprehensive set of possibilities for interfacing.
While all sites use the XAI Server, some sites use the MPL and the XAI Client. The XAI Client is
popular with V1.x V2.0 customers.
The concept behind the XAI component is as follows:
A service or number of services are used within the product are used as a basic of an
interface known as an XAI Inbound Service. The interface for this service is specified, in a
number of formats using the XAI Client or the browser interface.
The service is registered within the XAI and is loaded into the XAI registry at startup
time or when the registry is cleared manually. This defines the service as an API into the
product made available via XAI.
At this point the XAI Inbound Service can be called directly using Simple Object Access
Protocol (SOAP) via the HTTP protocol. WS-Security or HTTP Basic Digest
Authentication can be used.
If the service is to be accessed from an indirect channel then the Multi-Purpose Listener
(MPL) is used to configure the data sources or destinations for the transactions. The
MPL receives from and sends transactions to configured channels via the XAI Server.
The XAI component of the Oracle Utilities Application Framework is used for interfacing
foreign systems in and out of the product.
Features of XAI
The XAI component of the Oracle Utilities Application Framework has a multitude of features.
The following is a summary of the major features of XAI:
Any product service (including internal framework services and custom services) can be
used as a XAI Inbound Service for interfacing. The product provides for registration of
services in the XAI registry used at runtime.
The XAI server allows manipulation of data into the product and out of the product
using Extensible Stylesheet Language (XSL). This means that foreign (non-XML and
XML) formats may be supported through translation. The stylesheet definition exists on
the definition of the XAI Inbound Service as well as other XAI objects.
The XAI Server can support raw XML and Web Service formatted XML synchronously
and asynchronously.
The XAI Server supports a registry for configuration. This registry of information is
loaded at startup time for performance and configuration. The registry can be
manipulated at runtime using administration commands.
The XAI Schema Editor Client allows the base maintenance object schemas to be
created in schema format. This allows the specification of a site specific view of the base
maintenance object. The schema may be generated in W3C or XDR (XML Data
Reduced) formats. The XAI Schema Editor Client also allows the schema to be
generated in DTD format.
The XAI Schema Editor Client can generate schemas for files and databases for
integration purposes.
The XAI Server supports the Simple Object Access Protocol (SOAP) over
HTTP/HTTPS network protocol for delivery of transaction from all channels. The
HTTP Header Basic Digest Authentication standard or WS-Security may be used for
securing the transactions.
The SOAP Fault format is used to return error messages to the calling application. In
the fault, the same error message that appears to other channels is displayed.
Note: Product messages are stored in meta-data and can be altered for your site.
The XAI Server can generate Web Services definitions (WSDL) for all incoming
Services. The XAI Server also supports UDDI Discovery of the XAI Inbound Services.
WSDL can also be generated from the XAI Schema Editor Client, but this only applies
to objects generated from Maintenance objects. The WSDL interaction is used for
Oracle Fusion Middleware integration and other Service Orientated Architecture
integration.
The Multi-purpose Listener (MPL) component of XAI send transactions to the XAI
Server using the following channels:
File Based It is possible to load files of CSV, fixed structure or XML format
into objects in the product. The MPL also allows files to be exported from
objects within the product on a regular basis.
Database It is possible to poll an external database table to load data. This

interface is read only to the external database table.
Java Message Service (JMS) It is possible to take input from and send
output to JMS compliant queues and topics.
SMTP Server (Email) It is possible to send emails from the product to an

email server.
Web Server (HTTP) It is possible to send data to an existing Web

Application (or any application that can accept HTTP requests).
LDAP Import It is possible to import security information from an LDAP

based security repository.
The XAI Server is a J2EE Servlet that can be deployed locally or on a cluster.
The diagram below summarizes the flows and facilities supported by the XAI:
UDDI Server
XAI Schema
Editor Client
XML Schema
WSDL
Fusion
Middleware
Maintenance
Object
Receivers
JMS
XAI Registry
Database
XAI Servlet
File Directory
SMTP Server
Application
Business
Object
Business
Service
Service
Script
Senders
Web Server
LDAP
Multi-Purpose Listener
XAI Server
Product
Figure 2 Detailed View of XAI
This whitepaper will outline the processes for each flow as well as guidelines to help optimize the
configuration.
Maintenance Objects versus Configuration Objects

Note: This section is not an indepth discussion of Maintenance Objects and Configuration Objects. Refer to the
online help or SDK documentation for more information about the facilities supported by these object types.
The products that use the Oracle Utilities Application Framework are object based. From a
functionality point of view, objects encapsulate reusable business rules and processing required
by the various access methods. The objects within the product are accessible from programmable
code as well as configuration.
In previous versions of the Oracle Utilities Application Framework (v2.0 and below) the only
objects within the product were Maintenance Objects. These objects provide all the maintenance,
searches and list management capabilities within the product. Traditionally these objects are
based upon programmable objects such as Java or COBOL. Every function in the product is
represented or uses by at least one maintenance object.
From an XAI point of view, views of Maintenance objects are generated as schemas, which
represent the subset of the maintenance object required for the interface used at the site. The
XAI Schema Editor Client is used to generate and maintain the schemas.
In Oracle Utilities Application Framework V2.1 and above, the concept of Configuration objects
were introduced. These objects exist as purely configuration data as code or mappings to existing
maintenance objects. The use of Configurable Objects allows sites to remap the objects into site
specific objects whilst utilizing the power of the maintenance objects to maintain integrity and
support customization.
From an XAI point of view, the configuration object schema specifications are used to specify a
service definition. This represents the subset of the maintenance object that is represented by the
configuration object schema specification. Additionally any mapping rules contained in the
configuration object schema are also used by XAI. At the time of writing the Configuration
Object types of Business Object, Business Service and Service Script were supported by XAI as services.
Whilst the XAI Server supports both Maintenance Object and Configuration based Object based
XAI Servers there are advantages and disadvantages to using the Maintenance Object approach:
Structure - Maintenance object structures are basically fixed with little room for
manipulation. If the structure needs to be altered then it is suggested that an XSL object
be used to manipulate the information as part of the interface. Configuration based
objects on the other hand, allow the manipulation of the tags and structure of the object
(within limitations of configuration objects). If the structure of the interface needs to be altered
then it is recommended to use Configuration based objects.
XML Standards - Maintenance Objects are XML attribute based, whereas

Configuration Objects are XML element based. Most sites prefer XML elements to
attributes.
XAI Formats It is possible to define custom formatting for select data types in XAI
(e.g. Dates and Times). This functionality is only supported in Maintenance Object
based services at the present time.
Reuse The root element of Maintenance Objects is fixed at the time the schema is
built. This means that while Maintenance Object based schemas can be reused it is not
efficient to do so. The root element of the Configuration Object based service is the
XAI Inbound Service Name. This promotes reuse as a Configuration Object based
schema can be shared across many XAI Inbound Services. Configuration Object based
schemas are also reused by other Configuration Objects.
It is suggested that sites use the Configuration Object based approach unless this approach is
deemed not suitable.
XAI Receivers
Note: If your site is not using the Multi-purpose Listener, this section can be ignored.
The Multi-purpose Listener (MPL) supports near real time integration to a number of interface
channels. These channels need to be registered with the MPL as XAI Receivers. The XAI Receiver
contains the definition of the logical attributes of the channel (some channels require physical definitions
outside of the XAI registry as well) as well as polling frequency and some basic timetable information.
The Receivers have configurable behavior in relation to what to do with responses from the
outcomes of transactions. The options are as follows:
Never send a response (i.e. ignore responses).
Send a response if the request was successful
Send a response if the request was unsuccessful due to a system error
Send a response if the request was unsuccessful due to an application error
The response then can be routed to the appropriate sender to help ensure delivery of the
appropriate information.
From an implementation point of view, your implementation will create a number of XAI
Receivers for the interface channels used at your site. There are also a number of preconfigured
internal XAI Receivers that are used by some of your XAI Receivers to complete processing.
The internal XAI Receivers are:
Staging Upload Receiver This receiver polls the XAI Staging Upload objects for
pending transactions deposited by other receivers.
Staging Control Receiver This receiver polls the XAI Staging Control objects for
pending initiated transactions deposited by other receivers.
10
Outbound Message Receiver This receiver polls the Outgoing Message staging
objects for pending outgoing transactions deposited by relevant transactions.
The context of these receivers and their significance will be discussed in the relevant sections of
"MPL Based Processes".
Note: These internal XAI Receivers should NOT be removed from the product. If they are NOT used then they
can be marked as Inactive to disable them.
Configuring XAI Receivers
The XAI Receivers used at a site are configured using the Admin X XAI Receiver menu
option on the browser user interface of the product. The following table lists all the configurable
attributes of the XAI Receiver:
TABLE 1 - XAI RECEIVER PARAMETERS
PARAMETER
COMMENT
Receiver Id
The identifier used for the Receiver. This is used by the XAI Server and MPL to identify the configuration. It
is suggested to prefix all receivers with CM to avoid conflicts with base product receivers.
Description
XAI Class
This is a short description of the receiver used for documentation purposes.

This is the type of XAI Receiver. There are a number of XAI classes shipped with the base product that can
be used. The recommended values of specific XAI Classes used for XAI Receivers will be discussed in later
subsections of this document.
Active
The status of the receiver can be set. Active XAI Receivers are used by the XAI Server and MPL. Inactive
XAI Receivers are ignored. This is useful for switching receivers on and off at configuration time. Refer to
"MPL Administration" for a discussion of runtime management of XAI Receivers. Refer to "Activating and
Deactivating Receivers" for a discussion of this facility
Executer Id
The location of the XAI Server can be set for individual senders. By default it is assumed that the XAI
Server is local but the XAI server can be remote on a cluster or on a dedicated server if necessary. This
setting allows the location of that server to be set. In most cases the XAILOCAL setting is sufficient.
Note: There is an option to bypass the XAI server (BYPASSXAI). This is for real time receivers only. This
option will be discussed later in this document.
MSG Encoding
By default all messages are in ANSI format, but for non-ANSI languages this setting can be changed to
UTF-8.
Read Interval
This is the interval, in seconds, between read cycles for this receiver. It is suggested that this parameter
never be set lower than ten (10) seconds.
Start At Time
Reserved for future use
Duration
Reserved for future use
XAI JDBC
The parameter will specify a specific JDBC connection to use for the XAI Receiver. Typically this parameter
Connection
is left blank which reuses the environments database connections. If the implementation uses separate XAI
registry database then this setting would point to the location of the registry. Refer to the "XAI JDBC
Connection" documentation for details of the format and functionality of this parameter.
Sequential
The parameter controls the behavior of the Receiver when processing multiple requests. It indicates
11
PARAMETER
COMMENT
Execution
whether the Receiver will process the requests in sequential order (on) or multi-threaded (off). If this value
is turned on then XAI staging control records created by the Receiver are marked for sequential execution.
Context
The Context parameters define the Receiver specific configuration settings required by the XAI Class. Refer
to the specific situations described in later sections of this document for guidance of values specified in this
configuration area.
Response
The Response parameters define the destination of any response received when the transaction is
processed by the XAI Server. The responses can be sent to multiple destinations, indicated by senders,
based upon the type of response received. At least one entry must exist in this collection, it is therefore
recommended to use the "All events" event for this purpose.
Groups
The Groups parameters define group constructs to be processed for the XML File Receiver. Refer to the
"Configuring an XML File based input" section for a description of the group of parameters.
XAI Senders
Note: If your site is not using the Multi-purpose Listener, this section can be ignored.
As part of transactions it may be necessary to send information to other parts of the product or
to another external system. The Multi-purpose Listener (MPL) allows the registration of these
channel destinations as XAI Senders. The XAI Sender contains the definition of the logical
attributes of the channel (some channels require physical definitions outside of the XAI registry
as well) as well as what to do in case of transaction failure, success or error.
As with XAI Receivers, your implementation will create a number of XAI Senders for the
interface channels used at your site. There are also a number of preconfigured internal XAI
Senders that are used by some of your XAI Receivers and XAI Senders to complete processing.
The internal XAI Senders are:
Staging Upload Sender This sender updates the XAI Staging Upload objects with
the appropriate responses.
Staging Control Sender This sender updates the XAI Staging objects with the
appropriate responses.
Outgoing Message Sender This sender processes the Outgoing messages to the
appropriate sender configured for transactions initiated from the product to the
interface.
The context of these senders and their significance will be discussed in the relevant sections of
"MPL Based Processes".
Note: These internal XAI Senders should NOT be removed from the product. If they are NOT used then they
can be marked as Inactive to disable them.
12
Configuring XAI Senders
The XAI Senders used at a site are configured using the Admin X XAI Sender menu option
on the browser user interface of the product. The following table lists all the configurable
attributes of the XAI Sender:
TABLE 2 - XAI SENDER PARAMETERS
PARAMETER
COMMENT
XAI Sender
The identifier used for the Sender. This is used by the XAI Server and MPL to identify the configuration. It
is suggested to prefix all senders with CM to avoid conflicts with base product senders.
Description
This is a short description of the sender used for documentation purposes.
Invocation Type
The type of processing for this sender. There are two possible values:
MPL This sender is managed and executed by the MPL.
Real-Time This sender can be managed by the XAI server directly and does not need
MPL. Only the Email and Outgoing Message Senders supports Real-Time at the present
version.
XAI Class
This is the type of sender. There are a number of XAI Classes shipped with the base product that can be
used. The recommended values of specific XAI Classes for XAI Senders will be discussed in later
subsections of this document
Active
The status of the sender can be set. Active XAI Senders are used by the XAI Server and MPL. Inactive
XAI Senders are ignored. This is useful for switching senders on and off while confirming the
configuration.
MSG Encoding
By default all messages are in ANSI format, but for non-ANSI languages this setting can be changed to
UTF-8.
XAI JMS
The JMS Senders require a number of logical JMS settings to define the configuration. Refer to the
Connection/ XAI
"Configuring a JMS based output" for more information about these parameters.
JMS Queue/ XAI

JMS Topic
XAI JDBC
The parameter will specify a specific JDBC connection to use for the XAI Sender. Typically this
Connection
parameter is left blank which reuses the environments database connections. If the implementation uses
separate XAI registry database then this setting would point to the location of the registry. Refer to the
"XAI JDBC Connection" documentation for details of the format and functionality of this parameter.
Context
The Context parameters define the XAI Sender specific configuration settings required by the XAI Class.
Refer to the specific situations described in later sections of this document for guidance of values
specified in this configuration area.
XAI Maintenance Object Based Services

XAI supports transactions based upon the Maintenance Objects within the product. This is the
traditional integration method that is supported all versions of the Oracle Utilities Application
Framework. This section outlines the common processes used to define and execute real time
service calls using Maintenance based services.
13
Installing and Configuring the XAI Schema Editor

To use the Maintenance Object based approach, the XAI Schema Editor Client must be installed
and configured for your site. The XAI Schema Editor Client is available from
http://edelivery.oracle.com for the version of the product you are executing.
Note: The XAI Schema Editor Client is part of the Oracle Utilities Software Development Kit and therefore
runs only on Windows clients.
The XAI Schema Editor Client provides the developer with the following functionality:
Generation of Schemas from base services.
Generation of Schemas from external sources such as CSV files, Databases and fixed
structure files (via a copybook).
Registration of the schemas as XAI Inbound Services (this is also available from the
browser based XAI Inbound Service transaction).
Validation of schemas for upgrade purposes. Base schemas can change (this is not a
common occurrence) so as part of the upgrade process there is a validation to identify
and resolve issues with schemas.
Basic Unit Testing of XAI Inbound Services (Maintenance Object based services only).
Log File Viewing Analysis and display of trace information for transactions.
Once the software has been downloaded the process outlined in the following figure, needs to be
completed to install and configure the XAI Schema Editor Client:
Start
Install
Database
Client
Setup ODBC
Connection
Install Schema
Editor
Setup Schema
Editor
Stop
Install Product
Figure 3 - Installing and Configuring the XAI Schema Editor Client
The Database client software for Windows should be installed. It is highly

recommended that the relevant version of the client for the database be installed from
the database vendor. Generic database drivers may not operate as expected. This step
will allow an ODBC connection to be created for the generation process.
Install the development version of the product according to the Installation

documentation.
The location of the XAI schema's directory for the server should be noted. Usually this
value is %SPLEBASE%\splapp\xai\schemas. If the development server is
14
centralized then an appropriate share should be created to allow developers to read and
write to this directory.
The location of the base schemas for the server should be noted. These are read by the
XAI Schema Editor Client to generate the custom schemas. Usually this value is
%SPLEBASE%\splapp\xmlMetaInfo. If the development server is centralized,
then an appropriate share should be created to allow developers to read this directory.
Note: It is assumed that the development platform is Windows based. The XAI Schema Editor Client
has only been tested against a Windows based development server.
Setup an ODBC connection to your nominated development environment. This should

use the database client previously installed. The name should be noted for configuration
later.
Run the installer for the XAI Schema Editor Client and install the client in an
appropriate location your development workstation according to your site standards.
Note: For maximum compatibility you should use the version of the client associated with the version of
the product you are using it against.
Start the XAI Schema Editor from the Start XAI Client Vx.x Schema Editor on the
developer workstation. The initial startup of the product a Preferences Dialog will
display. The following values should be used to complete the configuration:
Default Date Time Value The default format for dates and times in
generated schemas. It is suggested that the default value displayed is used
unless otherwise needed.
Schema Directory Directory or share where the schemas generated will be

stored. This was set as part of the development environment install.
MetaInfo Directory Directory or share where the base product schemas

generated will be read from. This was set as part of the development
environment install.
XAI Servlet URL The URL of the development environment referencing

the port, host and XAI Servlet. In most cases the format
http://<host>:<port>/<server>/XAIApp/xaiserver
Where <host> is the host name of the development machine, <port> is the
port number allocated to the development environment and <server> is the
server identifier set by the installation process (usually spl or splapp).
Default Account Id Default product account id used for testing account

based services. This can be blank or a test account used to verify the service.
Account is the most common object in the products.
15
Language The Language to be used for messages and processing. The

default is ENG for English. If other languages are required then the appropriate
language pack must be installed on the development environment prior to
using the XAI Schema Editor.
Note: In some earlier versions of the XAI Schema Editor Client there is an additional parameter to set
the Default Version for Schemas. For compatibility it is suggested that this be set to no value to disable
the functionality if using an older version of the editor.
The XAI Schema Editor Client is now setup and configured for use.
Defining a Maintenance Object Based Schema

Once the XAI Schema Editor Client is installed and configured the next logical step is to use the
client to generate schemas, register and test services. Remember the XAI Schema Editor Client is
only used for generating schemas against Maintenance Objects. This tool will not work with
Configuration based objects.
To generate a schema, register a service and test a service from the XAI Schema Editor Client
use the following service:
Verify
Configuration
Generate
WSDL
New Schema
Find MO
Start
Generate
Schema
Start Schema
Editor
Save Schema
Open Schema
Register
Service
Stop
Maintain
Schema
Existing Schema
Clear Cache
Test Service
Validate
Schema
Note: The process below only describes the generation of schemas using services. It is possible to generate schemas
from other sources such as files, database and other object types. These will be covered as addendums to this process
in the relevant subsection of this document. In general the schema building and maintenance process does not vary
from source to source.
To generate a schema the following process is used:
Start Schema Editor - Start the XAI Schema Editor from the Start XAI Client Vx.x
Schema Editor on the developer workstation. You will be asked to login.
The Data Source should use the ODBC link name you created for the
development environment in the installation steps
16
Specify the userid, the userid and password to access the database. It is
suggested that the default user read-write user associated with the database be
used. It is possible to use any database user to access the schema but this
schema must be given read-write permissions to the product schema as
documented in the Installation Guide for the product.
The owner of the database schema must be provided so that the generation
process can connect to the right schema.
Verify Configuration - Optionally, it is recommended to check your preferences are set

to the development environment on occasion to verify that you are using the right
source environment. It is recommended to check the following settings are correct for
your session:
Schema Directory This should be set to the directory or share on the

development server that is the location of the generated schemas. The
developer must have read and write permission to this location.
MetaInfo Directory This should be set to the directory or share on the

development server that is the location of the product base service schemas
(i.e. xmlMetaInfo). The developer must have read permission to this location.
XAI Servlet URL This should be set to the URL for XAI Servlet for the
development server.
To create a schema, select the Schemas Service menu option to generate a schema off a
base product service. It is possible to create a schema from other sources; these will be
covered in subsequent sections of this documentation.
Find Maintenance Object - To generate the appropriate schema the first step is to
find the Maintenance object to use as a basis for your schema. To do this you must
Search the base service to identify it. The XAI Schema Editor Client allows the
maintenance object to be found using the internal service name or the object name. A
common technique of finding the service is to use the name of the screen that
manipulates the object in the search dialog. Typically the screen name and the object
name are similar enough to identify a service. Any service available to the product can
be used for the basis of your schema including search and list services.
Note: The search dialog for finding a service supports the '%' wildcard.
Once the service is identified a service name must be assigned to the service. This name
will be used as the root element in the schema. It is recommended for upgradability
purposes that the service name be prefixed by 'cm'.
Generate Schema - The XAI Schema Editor Client will read the base schema from the
identified service (in the configured xmlMetaInfo directory) and generates a custom
17
schema based upon the base one. The format of the generated schema follows the
pattern:
Header A header is generated from the keys used in the Maintenance

Object.
Details The rest of the elements of the object are contained in the Details
element of the service. This section of the schema will mirror the structure of
the maintenance object and may contain list sub-objects for related objects.
Maintain Schema - Before saving the schema it may be edited to suit your needs. The
following are the supported actions on the schema:
Individual elements can be renamed. These elements become the attribute tags
used in the schema so therefore names must comply with XML tag standards.
The default and/or fixed values for an element can be specified. A default
value is used if the element is not specified; a fixed value is used regardless
whether the value is specified or not.
Data formats can be modified (within the bounds of the original format). For
example, date formats for individual date elements can be specified on the
schema.
New code elements can be added. It is possible to add some descriptions of

related code elements.
Temporary elements can be added. It is possible to add an attribute that is not

used in the underlying maintenance object for temporary purposes. For
example, elements in a calculation etc.
Individual elements can be removed. Not all elements in the schema are
necessary for your particular interface. They can be removed.
Note: If a particular element is required for the maintenance object (directly or indirectly), the
runtime execution of a transaction will error with the appropriate error message indicating
this.
The following actions are NOT recommended for maintaining schemas:
Structure cannot be altered The service structure is set in the

XMLMetaInfo and that cannot be altered (flattened or expanded) as the
XPATH mappings will not work.
You cannot change internal formats The service and maintenance objects
will expect data in the formats that are in the XMLMetaInfo. For example,
you cannot use strings if numeric values are required by the service or
maintenance object.
18
You cannot change Internal names The service uses the Internal to map
your schema to the internal schema. Altering this will invalidate the connection.
Save Schema - After the schema has been edited it must be saved prior to its use. The
location of the saved schemas is set as part of the preferences. By default, the location is
the %SPLEBASE%\splapp\xai\schemas directory of your development
environment. The XAI Schema Editor Client allows the schema to be saved in W3C
(.xsd) or XDR format (.xml). It is recommended to use W3C format for all schemas.
Validate Schema - During the saving process, the schema is validated against the base
schema. This is to help ensure no edits will result in invalidated calls to the underlying
maintenance objects. This process is automatic and any errors should be corrected prior
to using the schema. This process can also be manually initiated using the Validate
option in the XAI Schema Editor Client. Refer to "Validation Of Schemas" for more
guidance on this functionality.
Note: It is recommended to use the Mass Validation function in the XAI Schema Editor Client to
validate all schemas during a product upgrade.
Open Schema The custom schema can be built in one session or across multiple
sessions by re-opening schema in the XAI Schema Editor Client.
Note: Whilst the schema is in an open format, any edits to the schema file outside the XAI Schema
Editor Client may result in a schema that cannot be maintained or supported by the XAI Schema
Editor Client.
Register Service To use the schema, a XAI Inbound Service must be registered to
use the schema for processing. The registration process can be initiated from the XAI
Schema Editor Client or from the XAI Inbound Service maintenance transaction on the
product browser user interface. The following information is to included in the
registration:
TABLE 3 - XAI INBOUND SERVICE PARAMETERS FOR MAINTENANCE BASED SERVICES
SETTING
COMMENT
Service Name
The service name must match the root element name for Maintenance object based
services. This is used by XAI as an identification of the underlying service. The service
name will appear after the SOAP envelope in the transaction.
Adapter
The adapter is the XAI Class that is used by XAI to process the request. Depending on
the type of request, the relevant XAI Class is selected.
Service Name
This is the name of the underlying service used to generate the schema. If the XAI
Schema Editor Client is being used then this will be automatically read from the
schema. For basic services use the Base adapter.
Description/Detailed
It is important to document the service to allow interfaces to understand the facilities of
Description
the service.
19
SETTING
COMMENT
Active
The service should be marked as active to use the service. Refer to "Activating and
Deactivating Services" for a discussion of this facility.
Post Error
For services that do not use the XAI Staging tables, messages where errors should not
be returned to the originator, but should be highlighted in this system for resolution then
mark this flag. When this switch is turned on and an application error is received by XAI
when processing the message an XAI upload staging record is created (along with a
staging control record) and marked in error.
Trace
This switch is activated then trace records will be written to the server logs for this
service regardless whether global tracing is active or not.
Debug
This switch is activated when debug information for the service and its underlying
objects need to be displayed in the product logs for diagnostic purposes. This switch is
primarily used by developers.
Request/Response
The Schema name generated should be registered. It is possible to generate a
Schema
separate request and response schema or reuse the same schema.
Request/Response
If transaction of the schema needs processing coming in (request) or going out
XSL
(response), then XSL scripts to perform this function should be specified. By default the
XSL scripts are located in the same directory as the schemas.
Transaction Type
Each transaction has a transaction type or search type (depending on the type of
service used). It is possible to provide a default transaction type/search type if none is
provided as part of the transaction. Refer to "Transaction Types/Search Types" for
more guidance on this functionality.
Once the service is registered the Id of the XAI Inbound Service is populated.
Note: Other tabs on this dialog are not used for the basic XAI Inbound Service. These will be used for
specific other adapter types.
Clear Cache All the definitions of the XAI Registry are cached, for performance
reasons, as part of the XAI Server runtime execution. To reflect any changes in the
registry in the runtime operation, the XAI Server cache must be reset. This can be done
from the XAI Schema Editor Client or the product browser user interface using the
XAI Command functionality. Refer to "Flushing the XAI and MPL Caches" for more
guidance on this functionality.
Test Service It is possible to perform rudimentary testing from the XAI Schema
Editor. Refer to "Testing Services" for more guidance on this functionality.
Generate WSDL After a service has been registered and is loaded into the XAI
Registry, it is possible to generate Web Services Definition Language (WSDL) file for
the service for use in tools such as Oracle Fusion Middleware or Oracle JDeveloper.
The XAI Schema Editor allows generation of WSDL for Maintenance Object based
services. Refer to "Generating Web Service Definition Language" for more guidance on
this functionality.
20
At this time the service is now available for use directly or via the MPL.
Testing Services
Once a service has been registered it is possible to test the service without the need for a calling
application. The XAI Schema Editor Client and product browser feature a number of basic test
harnesses to unit test your service.
The XAI Schema Editor Client allows the service to be tested after it has been loaded
and registered. The test facility generates a simple request dialog that allows basic data
entry and then allows submission of the service directly. Given that the XAI Schema
Editor Client is seen as an external client to XAI Server there is usually an initial logon
that must be performed for the first transaction to establish communications. The
results of the test (i.e. the response) can be seen in tabular or XML format.
The XAI Dynamic Submission functionality is available from the product browser user
interface (Admin Menu X XAI Dynamic Subm ission). This functionality allows the
specification of the XAI Inbound Service to dynamically generate a screen for the
service. This will generate a browser interface based upon the tags within the schema
and the product metadata. The facility allows basic data entry on the generated screen to
produce a request schema. The response is displayed in XML format.
Note: This facility only supports Maintenance Object based XAI Inbound Services. Any attempt to
execute against non-Maintenance Object based services will result in an error.
The XAI Submission facility is available from the product browser user interface (Admin
Menu X XAI Submission). This facility allows raw XML to be used as a request to
execute against the XAI Server. The response is posted in XML format. This
submission method supports any XAI Inbound Service but the request XML must be
provided. This facility is popular for testing existing XML instances of a transactions
and whether they work.
While the above methods are available to test XAI from the product, given XAI supports a
Service Oriented Architecture, other third party tools can be used to test XAI as long as they
support either XSD or WSDL format for the schema, support SOAP and support the required
authentication methods (see "Runtime Security of XAI Inbound Services" for more details about
XAI security).
Using The Schema Editor with non-Windows server platforms

The XAI Schema Editor Client has been designed to work with a development copy of the
product. The Oracle Utilities SDK platform runs on Windows only but some customers have
reported limited success in using the XAI Schema Editor Client on non-Windows platforms:
21
Shares to critical directories on the server must be allowed between the Windows based
machine and the non-Windows machine. This can be achieved using NFS or SAMBA to
allow Windows to map a drive to the relevant subdirectories on non-Windows
platforms. The $SPLEBASE/splapp/xai/schemas directory must be shared
with read-write permission and $SPLEBASE/splapp/xmlMetaInfo must be
shared with read permission.
Files created in the $SPLEBASE/splapp/xai/schemas directory must be

readable by the target system. When a file is written or updated on this directory,
SAMBA/NFS typically uses the Windows user (or a mapped user) to set the user
permissions on the file. It is recommended that this user be set to the administration
account (with appropriate read permissions) so that the product runtime can read the files
generated.
The ODBC connection and HTTP server connections used by the XAI Schema Editor Client
should work as is on a non-Windows platform.
Note: The above techniques are not guaranteed to work for all situations.
XAI Configuration Objects Based Processes

Note: This section is NOT a detailed analysis of the configuration objects facility. Please refer to the relevant
product documentation for more details of this facility.
With Oracle Utilities Application Framework V2.1 and above, a facility to allow customers to
define their own objects using the maintenance objects as a base was introduced. This facility
allows customers and partners to redefine the base object model to resemble objects used at the
site for interfacing or any processing.
This facility has three object types that are applicable to XAI:
Business Objects The ability to map and create an object based upon a single
maintenance object.
Business Services - The ability to map and create an object based upon a single
product service.
Service Scripts The ability to create generic functions or combine objects into a
single object.
These three object types can be configured within the browser user interface and registered as
XAI Inbound Services.
Registering Objects as XAI Inbound Services
22
To use a Configuration Object as a Web Service or as an XAI Inbound Service the following
must be done:
The Business Object, Business Service or Service Script must be configured using the
relevant browser user interface object.
The schema definition for the Business Object, Business Service or Service Script will
be used as the service definition.
When registering such an XAI Inbound Service for the configuration object the following
information should be included with the definition:
TABLE 4 - XAI INBOUND SERVICE PARAMETERS FOR CONFIGURATION OBJECT BASED SERVICES
SETTING
COMMENT
Service Name
The service name is used for the root element in the request and response. It is recommended to prefix
any service with 'cm' to avoid conflicts with base services.
Adapter
The BusinessAdaptor adapter is used for Configuration based objects. The object type will be used
specified as well as the name of the configuration object (Business Object, Business Service or Service
Script) to be attached to the service definition
Schema Type
This is the Configuration Object type. Currently, only Business Object, Business Service or Service
Script are supported.
Schema Name
This is the name of the underlying Configuration object used for the service.
Description/Detailed
It is important to document the service to allow interfaces to understand the facilities of the service.
Description
Active
The service should be marked as active to use the service. Refer to "Activating and Deactivating
Services" for a discussion of this facility.
Post Error
For services that do not use the XAI Staging tables, messages where errors should not be returned to
the originator, but should be highlighted in this system for resolution then mark this flag. When this
switch is turned on and an application error is received by XAI when processing the message an XAI
upload staging record is created (along with a staging control record) and marked in error.
Trace
This switch is activated then trace records will be written to the server logs for this service regardless
whether global tracing is active or not.
Debug
This switch is activated when debug information for the service and its underlying objects need to be
displayed in the product logs for diagnostic purposes. This switch is primarily used by developers.
Request/Response
Not used.
Schema
Request/Response
If transaction of the schema needs processing coming in (request) or going out (response), then XSL
XSL
scripts to perform this function should be specified. By default the XSL scripts are located in the same
directory as the schemas.
Transaction Type
Each transaction has a transaction type or search type (depending on the type of service used). It is
possible to provide a default transaction type/search type if none is provided as part of the transaction.
Refer to "Transaction Types/Search Types" for more guidance on this functionality.
Once the service is registered the Id of the XAI Inbound Service is populated.
23
Note: Other tabs on this dialog are not used for the basic XAI Inbound Service. These will be used for specific
other adapter types.
Note: For XAI Inbound Services based upon Configuration based objects, it is possible to register multiple XAI
Services for the same Configuration object.
Testing Configuration Object Based XAI Inbound Services

Once the XAI Inbound Service for a Configuration based object is registered and loaded into
cache, it can be tested. As the XAI Inbound Services associated with Configuration based objects
do not have an external schema associated with them, the only product based technique available
is to use the XAI Submission facility available from the product browser user interface (Admin
Menu X XAI Submission). This facility allows raw XML to be used as a request to execute
against the XAI Server. The response is posted in XML format.
While the above method is available to test XAI Inbound Services based upon Configuration
based objects, from the product, XAI supports a Service Oriented Architecture, other third party
tools can be used to test XAI as long as they support WSDL format for the schema, support
SOAP and support the required authentication methods (see "Runtime Security of XAI Inbound
Services" for more details about XAI security).
Web Services Integration

While XAI was built before the wide adoption of Web Services in the marketplace it is possible
to use the Web Services architecture to execute services from the product using XAI. This
section will outline some techniques and facilities specifically targeting Web Services
functionality.
Generating Web Service Definition Language

One of the core components of the Service Oriented Architecture (SOA) is the provision of a
Web Service Definition Language (WSDL) for the service. This definition file can be then used
by SOA components such as development tools, middleware etc to form the interface definition
for interfacing.
XAI supports the generation of WSDL using a number of techniques:
XAI Schema Editor It is possible to generate WSDL files from registered and cached
Maintenance based objects (they must have W3C schemas). The WSDL generator is
available from the Tools menu.
24
Directly using the XAI Server The XAI Server supports the on the fly generation of
WSDL for any XAI Inbound Services using the standard URL:
http://<host>:<port>/<server>/XAIApp/xaiserver/<service>?WSDL
where
<host>
Host of the environment
<port>
Port Number assigned to the environment
<server>
Server assigned by Web Application Server
<service>
XAI Inbound Service name
The latter method is preferred as it applies to any XAI Inbound Service regardless of service
type. The WSDL that is generated can then be consumed by other tools such as Oracle
JDeveloper, Oracle SOA Suite etc.
Using Web Service Discovery with a UDDI Server

Note: The use of an UDDI server is not required for the product to integrate and its use is purely site preference.
Given that the product XAI Inbound Services can be used as Web Services and that through
Maintenance objects and Configuration Objects a large number of services can be generated,
some level of developer control may need to be considered. Typically the product is just one of
the applications in a potential service oriented architecture landscape at a site.
To have some level of control and provide additional information to developers at a site,
consider using a Universal Description, Discovery and Integration (UDDI) server. UDDI is a
platform-independent, Extensible Markup Language (XML)-based registry for applications to
registers its available services. UDDI represents an open industry initiative, enabling site
applications to publish service listings and discover each other and define how the services or
software applications interact within an enterprise. UDDI covers services within an organization
as well as services outside the organization that may be of benefit.
In an enterprise where a number of applications expose a number of Web Services, it is possible
to register the service definitions in a central place (a UDDI server) which all programmers can
reference during development.
The advantage of a UDDI server is that additional control and context information can be
annotated on the entries in the registry to help control and manage the Web Service outside the
application. For example, you can set security up so that certain services are not visible to some
developers. Typically this additional annotation information falls into three categories:
White Pages address, contact, and known identifiers;
Yellow Pages service categorizations based on taxonomies;
Green Pages technical information about services exposed by the product.
25
The process that the service is registered in the source application and the UDDI server runs a
discovery process to query the source application about the Web Services it offers. Each service
discovered is registered in the UDDI repository. Additional information is annotated onto the
server.
The developer queries the UDDI server during the development process to incorporate the
appropriate Web Service in their application.
The XAI Server allows an UDI server to discover the services using a standard UDDI Discovery
URL:
http://<host>:<port>/<server>/XAIApp/xaiserver?WSDL where
<host>
<port>
<server>
The call will return a list of all the services that have been registered for use within the XAI
Registry. The UDDI server then can use that basic information to load the service definitions
into its repository. Once loaded into the UDDI, the additional annotations can be added to the
definition within the UDDI to allow developers appropriate access.
Transaction Types instead of Methods

By defaults all XAI Inbound Services have a transaction type (field name transactionType)
associated with the Web Service as a service indicator. In normal Web Services this is
functionality is usually provided by methods. Each method typically provides a specific
programmatic interface to the object.
As the Web Service capability in the product set actually predates Web Services and also supports
raw XML calls, the lowest common denominator is using transactionType. This means
that the same XAI Inbound Service can be used from both SOA and non-SOA infrastructure.
Note: The transactionType element does not have to be explicitly defined in the XAI Inbound Service
is included automatically by the runtime of the XAI Server.
The following lists the common values supported by the transactionType element:
TABLE 5 TRANSACTIONTYPE VALID VALUES
TRANSACTION TYPE
COMMENTS
READ (default)
Retrieve an object. The identifier of the object to retrieve must be provided as a minimum.
ADD
Add a new object. For system generated identifiers, as indicated on the primary table definition in the
meta data, you do not need to specify an identifier.
UPDATE
Make a change to an existing object. The identifier of the object to update and the fields to update must
be provided as a minimum. You do not have to specify fields that have not changed. This means that
the fields specified in a XAI Inbound Service can be a super set of all possible combinations of
26
TRANSACTION TYPE
COMMENTS
changes.
CHANGE
Similar to UPDATE except where fields you have not specified will be reset to NULL or defaults. Used
for specialist interfaces.
DELETE
Delete an object. The identifier of the object to delete must be provided as a minimum. This will only
delete the object if the deletion is valid (the object has not been referenced by another object)
LIST
This is reserved for List Object based services that use Maintenance Objects.
SEARCH
This is reserved for Search Object based services that use Maintenance Objects.
Search Type Objects (Suffix 'S')
For Maintenance Object based XAI Inbound Services, suffixed with an 'S', there is an additional
transaction type like element named searchType (transactionType must be set to
SEARCH). This element contains the type of search to invoke. Most search services are in fact
multiple searches usually with a number of searches with varying criterion. When a search service
is invoked the invoker must indicate which particular search you are interested in executing as
part of the transaction.
The value of the searchType depends on the position of the search criterion on the screen
that uses the service. Each search criterion is separated on the search screens by a search icon
(binoculars by default) and a separator (usually a line). The topmost search criterion is denoted by
the MAIN searchType, the next lowest is denoted by ALT searchType, the next lowest
ALT1, next lowest ALT2 and so on. An example of the searchType is shown below for the
example search service below.
MAIN
ALT
ALT1
ALT2
ALT3
Figure 4 - Sample Search Screen and related searchTypes
The searchType has a number of values to indicate which search to invoke:

TABLE 6 SEARCHTYPE VALID VALUES
SEARCHTYPE
COMMENTS
MAIN
The topmost most common search criterion.
ALT
The next level common search criterion
ALT1 ALT9
Alternative levels of search criterion.
Note: Up to 11 criteria can be specified. Only one searchType can be specified per transaction.
27
List Type Objects (Suffix 'L')
Services suffixed with 'L' are actually list services. These services are usually included within page
maintenance services or can be invoked directly. This allows more than one object of a set to be
manipulated within a single transaction scope. To support actions on individual rows a
rowAction element was introduced in the collection of objects (transactionType must
be set to LIST). Each individual object of the list collection has a rowAction:
TABLE 7 ROWACTION VALID VALUES
ROWACTION
COMMENTS
ADD
Add a row to the collection. The relevant elements of the object must be provided.
UPDATE
Update an existing row in the collection. The identifier of the row must be provided as well as the
updated elements.
UPADD
If the row already exists, issue the UPDATE action else use the ADD action. This is very useful as the
default maintenance rowAction.
DELETE
Delete an existing row from the collection.
Note: The READ rowAction is implied.

If the list maintenance is invoked as part of an existing maintenance object transaction then the
transactionType must be set to UPDATE and the appropriate rowAction used.
Using XAI Services with Fusion Middleware

One of the scenarios of using XAI is with the Oracle Fusion Middleware suite of products. The
product uses this type of integration as part of Oracle Application Integration Architecture
http://www.oracle.com/us/products/applications/application-integration(Refer
to
architecture/index.htm for more information on AIA).
It is possible to use XAI with any of the Oracle Fusion Middleware components as long as the
following guidelines are adhered to:
The security settings should favor using WS-Security. Refer to "Runtime Security of XAI
Inbound Services" for a discussion of the various security settings. The security settings
may be globalized or specified on individual transactions.
XAI Server supports the SOAP protocol within the middleware. SOAP Faults are
returned for any error.
The WSDL should be generated from the XAI Server rather than using the WSDL
Generator from the XAI Schema Editor Client. The WSDL can be made available from
a UDDI server or directly.
The transactionType, searchType and/or rowAction needs to be

populated as part of any call to the XAI Server. If the value is not supplied then the
value specified on the XAI Inbound Service will be used.
28
The XAI Server becomes the server end point. As part of the WSDL specification the
URL of the original generated environment will be listed in the file. This may need to be
overridden at runtime. In Oracle Fusion, this is possible at deployment time.
MPL Based Processes

The Multi-Purpose Listener (MPL) is a light enterprise service bus that allows a number of
channels to be polled on a regular basis to send information into the XAI Server in near real
time. The MPL is also responsible for initiating traffic outgoing from the product to external
channels.
The use of the MPL is optional and is not used by all sites. Typically the MPL is used in the
following situations:
The site needs to initiate outbound messages from the product.
The site needs to provide file, database and JMS channel integration for inbound
message and does not have an Enterprise Service Bus in use at the site.
If the site is only sending inbound requests to the XAI Server via HTTP, for interfaces, then the
MPL is not required.
Senders and Receivers

As outlined in the last section the MPL has a uses senders and receivers to define the
destinations and sources of transactions processed by the MPL. The Senders and Receivers
define the logical configuration of the destinations and sources of information for the MPL to
use. The following Senders and Receivers are provided with the XAI component:
TABLE 8 SENDERS AND RECEIVERS
COMPONENT
SENDER/RECEIVER CLASS
INCLUDED
COMMENTS
Receivers
Download Staging
Receiver to poll Notification Download Staging (Oracle Utilities

Customer Care And Billing only)
File Scan
Receiver to poll directories for flat files (CSV or Database)
JMS Queue
Receiver to poll JMS inbound Queues
JMS Topic
Receiver to poll JMS inbound Topics
Outbound Message
Receiver to poll Outbound message tables
Staging Control
Receiver to poll XAI Staging Control tables
Staging Upload
Receiver to poll XAI Staging tables
XML File
Senders
Download Staging
Receiver to poll directories for XML files
Sender to update Notification Download Staging (Oracle Utilities

Customer Care And Billing only)
Email
Sender to send response as email
29
COMPONENT
SENDER/RECEIVER CLASS
INCLUDED
COMMENTS
Flat File
Sender to produce an external flat file.
HTTP
Sender to write response to web application using HTTP
JMS Queue
Sender to write response to JMS outbound queue
JMS Topic
Sender to write response to JMS outbound topic
Outbound Message
Sender to update Outbound message tables and send response.
Staging Control
Sender to update staging control
Upload Staging
Sender to update XAI Staging tables
Note: The "Included" column indicates that a sender/receiver definition is provided with the base product. This
definition can be reused or deleted and recreated according to your site requirements.
Note: Notification Download Staging is not recommended for use for V2 implementations. It is provided for
backward compatibility for V1 customers.
Later subsections of this document will outline the configuration and runtime execution of each
of these senders and receivers.
The Role of XAI Staging Object

Some of the receivers and senders require object persistence; therefore they use the XAI Staging
tables to store the request and/or response to a particular transaction as well as its status. This
object is useful for tracking the status of a transaction and also dealing with any data errors.
The XAI Staging tables include a set of browser based transactions that allow the end users to
browse, edit and resubmit transactions within a transaction flow. The main use of the browser
transactions is to provide a means for end users to correct transactions in error and resubmit
them.
XAI Staging flow
The XAI Staging object has a set of senders and receivers that are attached to process
transactions from the MPL to and from the staging area. These are the XAI Staging Receiver and
XAI Staging Sender. This technique is used by a number of sender and receiver classes.
The processing flow of the staging receivers and senders:
30
Transform using
Record XSL
Read Pending Staging

Record
Send to XAI Servlet
XAI Staging
Post outcome to
Staging Table
Staging Upload
Sender
XAI Upload
Exception
Figure 5 - XAI Staging Upload processing flow
The XAI Staging Upload Receivers scans the XAI Staging tables for records of pending
status. Records are placed in the XAI Staging area by a number of Receiver and Sender
classes.
If the transaction requires translation then the XSL stylesheet specified on the XAI
Inbound Service definition is applied.
The transaction is then posted to the XAI Server directly (the URL is specified on the
sender as the XAI Executer).
The response, as defined in the XAI Incoming Transaction, will be posted to the sender
as outlined the configuration of the XAI Staging Receiver. This can be to multiple
sources depending on the outcome of the transaction (transaction successful, system
error, application error or all events).
The status of the Staging record is updated by the Receiver to indicate the status of the
transaction.
The Main XAI XAI Upload Staging menu option on the browser user interface for the
product can be used to query the status and address any issues with the transaction if an error has
occurred. It is possible to resubmit a staging record by changing the status of the individual
staging record back to Pending. Completed transactions will remain in the XAI staging area until
the XMLUP-PR background process is executed. It is recommended to run this process on a
regular basis according to site data retention policies.
31
Configuring the XAI Staging Receivers
By default the installation of the product a number of predefined XAI Receivers are provided to
support the staging activities of the product. These can be used with appropriate alteration or
used as a basis for custom XAI Receivers. While the staging XAI Receivers have limited
configuration parameters available the following guidelines are applicable to their configuration:
In most cases only one XAI Receiver per staging object is allowed. If your site does not
use the base defined XAI staging Receivers then they should be removed from the
registry.
The Read Interval (in seconds) is configurable and should not be set to a value less than
ten (10).
The Executer Id can be altered to suit your sites needs.
The Staging Receivers used by your site should be active. Conversely the XAI Staging
Receivers not used by your site should be inactive.
The Response configuration for the XAI Staging Receivers represents the minimum
configuration expected for the correct operation of the Receiver. If your site needs to
alter this it should only be extended and existing response configuration retained to
ensure correct operation.
The provided XAI Staging Receivers are shown in the table below:
TABLE 9 PROVIDED XAI STAGING RECEIVERS
RECEIVER IDENTIFIER
USAGE
XAI CLASS
DOWNLOADSTG
Download Staging Receiver (Oracle Customer Care
DWNSTGRCVR
And Billing use only)

F1OUTBNDMSG
Receiver to poll Outbound Message Records
OUTMSGRCVR
STAGINGCTRL
Staging Control Receiver
STGCTLRCVR
UPLOADSTG
Upload Staging Receiver
STGRCVR
Configuring the XAI Staging Senders
By default the installation of the product a number of predefined XAI Senders are provided to
support the staging activities of the product. These can be used with appropriate alteration or
used as a basis for custom XAI Senders. While the staging XAI Senders have limited
configuration parameters available the following guidelines are applicable to their configuration:
In most cases only one XAI Sender per staging object is allowed. If your site does not
use the base defined XAI staging Sender then they should be removed from the registry.
The Invocation Method can be altered to suit your sites needs but not all XAI Senders
support Real-Time. Refer to the specific configuration and processing flows to find
out which XAI Senders support Real-Time.
32
The XAI Staging Senders used by your site should be active. Conversely the XAI Staging
Senders not used by your site should be inactive.
The provided XAI Staging Senders are shown in the table below:
TABLE 10 PROVIDED XAI STAGING SENDERS
SENDER
USAGE
XAI CLASS
DOWNLOADSTG
Posts responses to XAI Download Staging (Oracle Customer Care
DWNSTGSNDR
And Billing use only)

F1OUTBNDMSG
Sender for routing outbound messages to its destination
OUTMSGSNDR
STAGINGCTRL
Sender to process XAI staging control records in error
UPLDERRHNDLR
UPLOADSTG
Populates responses to XAI Upload Staging
STGSENDER
Configuring a File based input

One of the most common sources of information that are processed in near real time are files.
The files can be in CSV or fixed format (as described by a copy book). The file scan receiver is
used to find and process files where the file contents contain data for a single object and are
unrelated.
To use this feature of the product you must have the following available for the development
and configuration process:
A sample file to use as a basis for configuration. It is recommended that the sample also
include tags for the data (for a CSV file the first record could contain field names; for a
fixed format file a COBOL copybook describing the structure can be used).
An appropriate XML editor that can generate XSL between XSD schemas or WSDL
files, for example Oracle JDeveloper.
The process for configuration is outlined in the figure below as follows:
Start
Flush XAI
Cache
Sample
File
XSL Mapping
Build & Register

XAI Inbound
Service
Generate Input
Schema to
describe File
Generate
XSL
Mapping
Input Schema
Register XAI
Inbound Service
for File
Register File
Scan Receiver
Flush XAI
Cache
Flush MPL
Cache
Stop
Target Schema
Figure 6 - File Based Input Configuration Flow
33
Build & Register XAI Inbound Service - The XAI Inbound Service that will accept
the data into the system has to be configured and registered. For example if the file
contains Customer Contact records then an XAI Inbound Service on the Customer
Contact Object (Maintenance or Configuration Object) has to be created. Using the
XAI Schema Editor Client or Configuration Objects, register the XAI Inbound Service.
The instructions for Maintenance object based services are contained in "Defining a
Maintenance Object Based Schema" and instructions for Configurable Objects are
located at "Registering Objects as XAI Inbound Services". This service needs to be
created initially as it will be required for later steps in the process. This service can be
created per interface or shared across interfaces.
Flush the XAI Server Cache (optional) - Before an XAI Inbound Service can be used
the XAI cache must be reset to reflect the definitions of the service for the XAI Server.
Refer to "Flushing the XAI and MPL Caches" for details of this process. This can be
done immediately or at any time before the XAI Inbound Service is used.
Generate Input Schema to describe file A schema or WSDL file must be generated
to describe the format and structure of the input file using the following methods:
Schema The XAI Schema Editor Client can be used to generate an input schema
providing a sample file is provided. The functionality is available from the Schemas
Create CSV (Comma Delimited) File. It is possible to also generate a schema
on a fixed format using a COBOL copybook. After the schema is generated it may
be maintained as outlined in "Defining a Maintenance Object Based Schema"
section of this document. Save the schema in the desired format.
Note: Do not register the service yet using this schema.
WSDL A WSDL development tool can be used to generate a schema (or WSDL)
that describes the contents of the file. Refer to the documentation provided with
your WSDL tool.
Generate XSL Mapping The input schema/WSDL must be mapped to the XAI
Inbound Service schema/WSDL using an appropriate XSL development tool. When
generating the XSL mapping the following is recommended:
Do not use custom extensions provided by the tool as the MPL uses a standard
XSL engine and extensions may not be supported.
Ensure the mapping does not refer to namespaces and custom libraries that are
not available in the product.
When using the mapping tool, ensure the file types mapped are of the same
type (WSDL WSDL, XSD XSD). Foreign format mappings a re not
supported.
34
Save the XSL mapping to the location of the schemas delivered with the
product. This is typically $SPLEBASE/splapp/xai/schemas (or
%SPLEBASE%\splapp\xai\schemas on Windows).
Register XAI Inbound Service for file To complete the registration of the services
for the file an incoming service a service must be created as follows:
TABLE 11 XAI INBOUND SERVICE SETTING FOR FILE INPUT
SETTING
COMMENT
Service Name
This service name must match the root service name in the Input Schema
for the file.
Adapter
This should be set to "CISStagingUpload" for the staging adapter.
Service Name
This setting is not used but a valid service name must be provided. It is
recommended to use the maintenance based service that represents the
target transaction.
Request/Response Schema
Not used
Request/Response XSL
Not used
Transaction Type
Not used. Use the ADD action as the object requires a default action.
Record XSL (Staging Tab)
Specify the name of the generated mapping file (XSL).
Staging File Type (Staging Tab)
Indicate whether the file is CSV, fixed format or Database extract.
Interface Name (Staging Tab)
This is a field used to denote the staging records on the XAI Staging table.
Note: Fields not listed in this table can have values as outlined in "Defining a Maintenance Object
Based Schema" or "Registering Objects as XAI Inbound Services".
Register File Scan Receiver Once the services are in place and the cache has been
refreshed the File Scan Receiver can be created using the Admin X XAI Receiver
menu option on the browser user interface of the product. The specific settings for the
File Scan Receiver are described in the table below:
TABLE 12 FILE SCAN RECEIVER PARAMETERS
PARAMETER
COMMENT
XAI Class
For processing files use the FILESCANRCVR (Receiver to poll files in a given
directory) XAI Class
Read Interval
This is the interval, in seconds, between read cycles for the receiver will poll the
"Scan Directory" looking for files of file pattern "Scan File". It is suggested that this
parameter never be set lower that 10 seconds.
Sequential Execution
The parameter controls the behavior of the Receiver when processing multiple
requests. It indicates whether the Receiver will process the requests in sequential
35
PARAMETER
COMMENT
order (on) or multi-threaded (off). If this value is turned on then XAI staging control
records created by the Receiver are marked for sequential execution.
Scan Directory
The fully qualified path to the directory on the server where the source files will be
located. The location specified must be accessible from the Business Application
server and by the product administrator account.
Scan File
The file or file pattern to search in the scan directory. There are a number of
supported possibilities:
Blank value or not provided at all (default) Process any file in the
Scan Directory.
Wildcard A wild carded file name with "*" used for multiple characters
or "?" for single character substitution.
Specific filename A single filename may be specified for fixed

interfaces. This is rarely used.
XAI Inbound Service
This is the underlying XAI Incoming Input Service that represents the contents and
format of the input file. This was generated against the sample to produce a
description and a XAI Inbound Service was registered for this.
Append
Time
Stamp
Format (Context)
When a file is processed the suffix '.xai' is appended to the file name to indicate it has
been processed. It is possible to also append a timestamp to the filename if desired.
The format of the timestamp is configured on the context tab. The supported formats
are outlined under "Designing XAI Formats".
Character
Encoding
(Context)
Indicates that the message is character encoded.
When the receiver creates a
staging control entry for a file, it will add ?enc=?x to the name of the file in the table
where x is the value of this parameter. The values UTF-8 and UTF-16 are
supported. The UTF-8 value should be used for WE8ISO based character sets.
File Preprocessor Class
If the file is fixed format and there is a custom java class that describes the format or
Name (Context)
custom processing of the file, then that java class can be specified.
Response
The Response parameters define the destination of any response received when the
transaction is processed by the XAI Server. The responses can be sent to multiple
destinations, indicated by senders, based upon the type of response received. The
STGSENDER can be used to register the response against the staging record
associated with the transaction.
Groups
Not used.
Note: Other parameters not listed in the above table should be entered as suggested in "XAI Receivers".
Flush the MPL Server Cache (optional) - Before an XAI Receiver can be used the
MPL cache must be reset to reflect the definitions of the service for the MPL. Refer to
"Flushing the XAI and MPL Caches" for details of this process. This can be done
immediately or at any time before the XAI Receiver is used.
The system is ready to process files using the receiver definition. It is suggested that the above
process be repeated for each transaction/directory combination at your site that wants to use the
36
File Scan Receiver. It is suggested that separate File Scan Receivers be defined per
transaction/directory combination to avoid conflicts.
File based Input Processing Flow
Once the configuration has been completed and the XAI Server and MPL have either been
restarted or the cache refreshed, the MPL will start to process any files matching the Scan File
pattern located in the Scan Directory using the following flow:
XML Message
based on input
schema
Column
Delimited
File
Read record from

input file
Staging Control
Input
CSV File
Create XML Message

using Input Schema
Transform using
Record XSL
Store XML Message

In XAI Staging
Staging Upload
Receiver Process
XML Message
based on target
schema
Figure 7 - File Based Input Processing Flow
A file is located matching the Scan File pattern, is placed in the Scan Directory manually
or automatically by the source system. Alternatively an appropriately authorized user can
manually initiate a File scan transaction by manually specifying the file name and
directory using the Main XAI XAI Staging Control menu option on the browser
user interface of the product. This is used for one off transfers or where specialist files are
required outside the configured File Scan Receiver Scan Directory or File Scan Receiver
Scan File pattern. The File Scan Receiver is not used for this process as it is entered
directly by the end user. Refer to the online documentation for a detailed description of
this process.
A Staging Control record is created by the File Scan Receiver that detected the file for
processing.
Records are read from the file indicated on the Staging Control record till the end of the
file is reached and processed in the following way:
The XAI Inbound Service configured on the File Scan Receiver is used build an input
XML message.
The translation configured in the Staging configuration on the XAI Inbound

Service is used to translate the input request into the desired target transaction.
The XML message generated is stored in the staging area as a request.
37
Once all the records the Staging control record is updated and the file renamed
according to the Context configuration on the File Scan Receiver.
The staging records created are processed individually by the Staging Receiver as
outlined in "XAI Staging flow".
Configuring an XML File based input

The File Scan Receiver outlined in the previous section has a few limitations, it cannot process
XML files and the file must only contain the data for a single common transaction (though you
can process many instances of that transaction. If the data is related, comes from many
transactions or is in XML format then the XML File Scan Receiver must be used.
The XML File Scan Receiver can process an XML file of independent transactions, transactions
that are related and a mix of related and non-related transactions. If the transactions within the
file are related, they must be sequenced within the XML file in the desired sequence for correct
processing. Therefore parent transactions must be sequenced earlier then child transactions.
Note: While the XML File Scan Receiver can process related transactions, if a parent transaction
fails for any reason, then related child transaction will also fail. Given that the XML File Scan
Receiver uses the XAI Staging process, the transaction history is stored within the XAI Upload
Staging process and can be resolved manually using the Admin X XAI Staging Upload menu
option on the browser user interface of the product.
To use this feature of the product you must have the following available for the development
and configuration process:
A sample file to use as a basis for configuration. It is recommended that the sample also
include tags for the data.
An appropriate XML editor that can generate XSL between XSD schemas or WSDL
files, for example Oracle JDeveloper.
The process for configuration of an XML File Scan Receiver is outlined as follows:
38
Flush XAI
Cache
Build & Register

XAI Inbound
Services
Start
Flush MPL
Cache
Specify XAI
Group
Register XML
File Scan
Receiver
Stop
Sample
File
Figure 8 - XML File Input Configuration
Build & Register XAI Inbound Services - The XAI Inbound Services that will accept
the data into the system have to be configured and registered. For each unique
transaction contained in the XML file an XAI Incoming Service must exist. Using the
XAI Schema Editor Client or Configuration Objects, register the XAI Inbound
Services. The instructions for Maintenance object based services are contained in
"Defining a Maintenance Object Based Schema" and instructions for Configurable
Objects are located at "Registering Objects as XAI Inbound Services". This services
need to be created before the interface is executed.
Specify XAI Group Each instance of a transaction within an XML schema must be
delimited by a tag denoting the start and end of each instance within the XML. This is
achieved by specifying the XAI Group using the Admin X XAI Group menu
option on the browser user interface of the product. The following table outlines what
to configure for the group:
TABLE 13 XAI GROUP PARAMETERS
SETTING
COMMENT
Group
The identifier for the group used for configuration purposes only.
Description
Short description of the group for documentation purposes only
Parser
Indication of the parser to use for this group. There is a choice of the following:
Dom Parser Support defining elements at a lower level than the root
element.
XPath
Stax Parser - Support defining elements at root element level.
XPath query to transaction delimiter. The parser determines the scope of the XPath
statement.
XPath Value
The tag value for the delimiter at the XPath specification.
After identifying the appropriate group to which an XML file belongs, the system takes
each message in the file and applies the appropriate XSL transformation to the message
to produce a record on the upload staging table. To process the messages in a file, the
39
system needs to know how to identify each message in a file containing multiple
messages. A file may use the same root element for each message or different root
elements for different types of messages. For each XAI group, you must indicate the
root element(s) that identifies a message by defining one or more attachments. Each
attachment defines a root element, which tells the system when a new message begins.
Once the system has identified each separate message in the file, it must determine the
correct XSL transformation script to apply. Once again the system uses an XPath query
and XPath value to identify the correct XSL to apply. For each XAI group, you define
one XAI rule for every possible type of message you may receive in the file. Each XAI
rule defines an XPath query, XPath value and XSL transformation script.
Note: Rules are only required if XSL translation is required for the individual transaction.
The following table outlines the configuration of the Attachments:

TABLE 14 XAI GROUP ATTACHEMENT PARAMETERS
SETTING
COMMENT
Sequence
The sequence number of processing the attachment.
Root Element
The root element of the attachment
Include Elements
If the XML message includes parent elements (such as a transmission id or a date/time)

that are needed for any of the separate child messages that are posted to the upload
staging table, you can configure the appropriate attachment to include parent elements
The following table outlines the configuration of the rules:

TABLE 15 XAI GROUP RULES PARAMETERS
SETTING
COMMENT
Sequence
The sequence number of processing the rule.
Priority
You may assign a priority to each of your rules. The rules for more common messages
may be assigned a higher priority. This enhances performance by ensuring that rules
for more common messages are processed before rules for less common messages.
XPath
The XPath statement for the rule
XPath Value
The XPath Value of the rule (the identifier of the transaction to translate)
XSL File Name
The XSL file that is used to translate the contents of the transaction.
Once the XAI Groups have been created the XML File Receiver may be created using
the Admin X XAI Receiver menu option on the browser user interface of the
product. The specific settings for the XML File Receiver are described in the table
below:
TABLE 16 XAI RECEIVER SETTINGS FOR XML FILE RECEIVER
PARAMETER
XAI Class
COMMENT
For processing files use the XMLSCANRCVR (Receiver to poll XML files in a given
directory) XAI Class
40
PARAMETER
COMMENT
Read Interval
This is the interval, in seconds, between read cycles for the receiver will poll the "Scan
Directory" looking for files of file pattern "Scan File". It is suggested that this parameter
never be set lower that 10 seconds.
Sequential Execution
The parameter controls the behavior of the Receiver when processing multiple
requests. It indicates whether the Receiver will process the requests in sequential order
(on) or multi-threaded (off). If this value is turned on then XAI staging control records
created by the Receiver are marked for sequential execution.
Scan Directory
The fully qualified path to the directory on the server where the source files will be
located. The location specified must be accessible from the Business Application server
and by the product administrator account.
Scan File
The file or file pattern to search in the scan directory. There are a number of supported
possibilities:
Blank value (default) Process any file in the Scan Directory.
Wildcard A wild carded file name with "*" used for multiple characters or
"?" for single character substitution.
Specific filename A single filename may be specified for fixed interfaces.

This is rarely used.
XAI Inbound Service
Not used for XML File Scan Receiver
Append Time Stamp
When a file is processed the suffix '.xai' is appended to the file name. It is possible to
Format (Context)
also append a timestamp to the filename if desired. The format of the timestamp is
configured on the context tab. Refer to the online documentation provided with your
product for formats that are supported.
Character
(Context)
Encoding
Indicates that the message is character encoded. When the receiver creates a staging
control entry for a file, it will add ?enc=?x to the name of the file in the table where x is
the value of this parameter. The values UTF-8 and UTF-16 are supported. The UTF-8
value should be used for WE8ISO based character sets.
Response
The Response parameters define the destination of any response received when the
transaction is processed by the XAI Server. The responses can be sent to multiple
destinations, indicated by senders, based upon the type of response received. The
STGSENDER can be used to register the response against the staging record associated
with the transaction.
Groups
Not used.
Flush the MPL Server Cache (optional) - Before an XAI Receiver can be used the MPL
cache must be reset to reflect the definitions of the service for the MPL. Refer to
The product is ready to process files using the receiver definition. It is suggested that the above
process be repeated for each directory/pattern combination used at your site that wants to use
41
the XML File Scan Receiver. It is suggested that separate XML File Scan Receivers be defined
per directory/pattern combination to avoid conflicts.
XML File based Input Processing Flow
Once the configuration has been completed and the XAI Server and MPL have either been
restarted or the cache refreshed, the MPL will start to process any files matching the Scan File
pattern located in the Scan Directory as indicated by the XML File Scan Receiver using the
following flow:
XML Message
based on input
schema
Read XML
Message from input
file
Staging Control
Use XAI Group to

identify message
Transform using
Record XSL
Store XML
Message
In XAI Staging
Staging Upload
Receiver Process
XML Message
based on target
schema
XML
Figure 9 XML File Processing Flow
A file is located matching the Scan File pattern, is placed in the Scan Directory manually or
automatically by the source system. Alternatively an appropriately authorized user can
manually initiate a File scan transaction by manually specifying the file name and
directory using the Main XAI XAI Staging Control menu option on the browser
user interface of the product. This is used for one off transfers or where specialist files are
required outside the configured XML File Scan Receiver Scan Directory or XML File
Scan Receiver Scan File pattern. The XML File Scan Receiver is not used for this
process as it is entered directly by the end user. Refer to the online documentation for a
detailed description of this process.
A Staging Control record is created by the XML File Scan Receiver that detected the file
for processing.
Records are read from the file indicated on the Staging Control record till the end of the
file is reached and processed in the following way:
The XAI Groups are used to find the relevant messages (attachments) in the
XML file.
If a rule applies to the attachment the indicated XSL is applied to translate the
input into the relevant transaction message. If no rule is applicable the
attachment is used as the transaction message.
42
The XML transaction message generated is stored in the staging tables as a

request.
Once all the records the Staging control record is updated and the file renamed
according to the Context configuration on the XML File Scan Receiver.
The staging records created are processed individually by the Staging Receiver as
outlined in "XAI Staging flow".
The XML file processor is quite simple in execution but can be quite daunting in configuration at
first. The XAI Staging receiver will detect the sequence of the transactions in the XML (as they
may be related) and processes them in the sequence they are received in the source file.
Configuring a JMS based input

The Java Message Service (JMS) is part of the J2EE specification and provides a java interface to
Message Oriented Middleware which allows loosely coupled distributed communications. The
XAI component allows the product to read JMS resources from an external JMS Provider (such
as Oracle Fusion Middleware, Tibco or IBM WebSphere MQ Series) as an input into the
product.
There are two types of JMS resources that can be interfaced into the product:
JMS Queue A queue is a staging area within the JMS Provider that contains messages
that have been sent and are waiting to be read. This method is also known as the pointto-point or queuing model. As the name queue suggests, the messages are delivered in
the order sent. A message is removed from the queue once it has been read. A source
application posts messages to a particular queue and XAI reads messages from the
queue. Here, the source application knows the destination of the message and posts the
message directly to the relevant queue. The attributes of a queue are:
XAI is the only receiver of the messages. Other potential interested parties
cannot receive the same message at the same time.
The source application does not have to be running at the time the XAI
consumes the message, nor does the XAI need to be running at the time the
message is sent.
Every message successfully processed is acknowledged by the XAI which

signals the queue to delete the message from the queue.
JMS Topic A topic is a distribution mechanism for publishing messages that are
delivered to multiple subscribers. Subscribers
may register interest in receiving
messages on a particular message topic. This method is also known the
publish/subscribe model. In this model, neither the source application nor the
43
subscriber knows about each other. A good metaphor for this is an anonymous bulletin
board. The attributes of a topic are:
Multiple interested parties can get the message.
There is a timing dependency between source applications and subscribers. The

source application has to create a subscription in the JMS Provider in order for
clients to be able to subscribe. The subscriber has to remain continuously
active to receive messages, unless it has established a durable subscription. In
that case, messages published while the subscriber is not connected will be
redistributed whenever it reconnects. XAI uses durable subscriptions as the
MPL polls the desired topic according the JMS Topic Receiver configuration.
For more information about JMS it is recommended to review the Java Message Service
specification located at http://java.sun.com/products/jms.
Prior to configuring the JMS interface to the product the following must be in place:
A JMS Provider must be installed within your site. Any JMS compliant Provider may be
used.
If the JMS Providers uses a proprietary JMS client (such as IBM WebSphere MQ), it
must be installed on the same machine as the MPL or XAI Server and the client must be
in the PATH as well as CLASSPATH prior to accessing the JMS Provider. The XAI
Components uses a standard JMS client which is usually sufficient for most JMS
Providers. Refer to the "Extending the splenviron Command" section of the product
Configuration and Operations Guide on the various techniques used to achieve this.
The JMS Provider must be configured to meet site needs with the relevant JMS Queues
and/or JMS Topics to suite your interfacing requirements. Refer to the documentation
provided by your JMS Provider
The JMS Queue, JMS Topics and JMS Connection Factory must be defined to a Java
Naming and Directory Interface (JNDI) server available to the XAI Component. This
JNDI may be housed with the same J2EE Web Application Server as the XAI
Component or distributed. This is akin to linking the physical attributes of the JMS
Provider with the logical configuration to be used for XAI Component. These
attributes, as well as the location of the JNDI server, need to be noted to link the
physical setup with the configuration with the XAI JMS setup.
The process for configuration of a JMS source of information is outlined in the diagram below:
44
JMS Provider
JNDI Server
JMS Queue
JNDI Server
Definitions
JMS Topic
Flush MPL
Cache
Start
Build & Register

XAI Inbound
Service
Define JNDI
Server
Define JMS
Connection
Factory
Define JMS
Topic/Queue
Define the JMS

Receiver
Define JMS
Reply
Destination
Flush XAI
Cache
Stop
Define Sender
For The Reply
Figure 10 - JMS Input Configuration Process
Build & Register XAI Inbound Service - The XAI Inbound Service that will accept
the data into the system has to be configured and registered. For example if the JMS
message contains Customer Contact records then an XAI Inbound Service on the
Customer Contact Object (Maintenance or Configuration Object) has to be created.
Using the XAI Schema Editor Client or Configuration Objects, register the XAI
Inbound Service. The instructions for Maintenance object based services are contained
in "Defining a Maintenance Object Based Schema" and instructions for Configurable
Objects are located at "Registering Objects as XAI Inbound Services". This service
needs to be created initially as it will be required for later steps in the process. This
service can be created per interface or shared across interfaces.
Define JNDI Server - For the interface to work, the XAI Server and MPL need to
know where to get the physical definitions. The JNDI server that holds the definitions
must be defined to the XAI registry for use by the MPL and XAI Server. This is
achieved by specifying the XAI JNDI Server using the Admin X XAI JNDI Server
menu option on the browser user interface of the product. The table below summarizes
the key settings for the JNDI Server:
TABLE 17 JNDI SETTINGS FOR JMS INPUTS
SETTING
COMMENT
XAI JNDI Server
This is the identifier used by the XAI component to identify the JNDI Server within
the registry. This has no relation to the physical location of the server, it is merely a
tag used by XAI to find the definition in the registry.
Description
Short description for documentation purposes only
45
SETTING
COMMENT
Provider URL
The URL used for the JNDI Server. This may be a cluster or standalone reference.
Include the relevant protocol for the J2EE Web Application server used at your site
(see table below).
Initial Context Factory
This is the server class provided by the J2EE Web Application Server to access
the JNDI. The value varies from vendor to vendor ((see table below).
For the Initial Context Factory the following Web Application Server values apply:
TABLE 18 VALID VALUES FOR INITIAL CONTEXT FACTORY SETTINGS FOR JMS INPUTS
WEB SERVER
CONTEXT LIBRARY SETTING
PROTOCOL
Weblogic
weblogic.jndi.WLInitialContextFactory
t3
WebSphere
com.ibm.websphere.naming.WsnInitialContextFactory
iiop
OAS
oracle.j2ee.server.ApplicationClientInitialContextFactory
opmn:ormi
Tomcat
org.apache.naming.java.javaURLContextFactory
java
Define JMS Connection Factory - When setting up JMS resources on the JNDI, a
JMS Connection Factory is required to hold the configuration information for any java
interface to use. The JMS Connection Factory configured in the JNDI must be defined
to the XAI registry for use with the MPL and XAI Server. This is achieved by specifying
the XAI JMS Connection Factory using the Admin X XAI JMS Connection menu
option on the browser user interface of the product. The table below summarizes the
key settings for the JMS Connection:
TABLE 19 JMS CONNECTION SETTINGS FOR JMS INPUTS
SETTING
COMMENT
XAI JMS Connection
This is the identifier used by the XAI component to identify the JMS Connection
within the registry. This has no relation to the physical location of the server, it is
merely a tag used by XAI to find the definition in the registry.
Description
XAI JNDI Server
This the identifier of the XAI JNDI Server created in the previous step.
JNDI Connection Factory
This is the physical name of the JMS Connection Factory defined within the JNDI
server.
Define JMS Queue - If the interface is using a JMS Queue, The JMS Queue is required
to be defined to the XAI registry for use with the MPL and XAI Server. This is achieved
by specifying the XAI JMS Queue using the Admin X XAI JMS Queue menu
key settings for the JMS Queue:
TABLE 20 JMS QUEUE SETTINGS FOR JMS INPUTS
SETTING
COMMENT
XAI JMS Queue
This is the identifier used by the XAI component to identify the JMS Queue within
46
SETTING
COMMENT
Description
Queue Name
This is the physical JMS Queue name defined within the JNDI server.
Target Client Flag
This denotes whether the JMS client to be used is the standard JMS client or the
WebSphere MQ Series client (the latter only applies to WebSphere MQ
implementations).
XAI JNDI Server
Define JMS Topic. If the interface is using a JMS Topic, The JMS Topic is required to
be defined to the XAI registry for use with the MPL and XAI Server. This is achieved
by specifying the XAI JMS Topic using the Admin X XAI JMS Topic menu option
on the browser user interface of the product. The table below summarizes the key
settings for the JMS Topic:
TABLE 21 JMS TOPIC SETTINGS FOR JMS INPUTS
SETTING
COMMENT
XAI JMS Topic
This is the identifier used by the XAI component to identify the JMS Topic within
Description
XAI JNDI Server
Topic Name
This is the physical JMS Topic name defined within the JNDI server.
Define JMS Senders for response management - Once a transaction has been
processed the response must be sent to the appropriate destination (or ignored). For
JMS transactions, the response can be sent via any XAI sender type, but typically a JMS
related sender is required. You can set up separate JMS Senders for successful
transactions, system errors or application errors. This is achieved by specifying the XAI
Sender using the Admin X XAI Sender menu option on the browser user interface
of the product. The table below summarizes the key settings for the XAI Sender:
TABLE 22 JMS SENDER SETTINGS FOR RESPONSES FOR JMS INPUTS
PARAMETER
COMMENT
XAI Sender
This is the identifier used by the XAI component to identify the XAI Sender within
the registry.
Invocation Class
This is the Sender type supported by the XAI Server and MPL. For JMS
Senders, only MPL execution is supported at the present time.
XAI Class
To send responses to JMS Queues use the JMSSENDER (Sender to route

messages via JMS Queue) XAI Class. For processing JMS Topics use the
TPCSNDR (Sender to route messages via JMS Topic) XAI Class.
XAI JMS Connection
This the identifier of the XAI JMS Connection created in the previous step.
XAI JMS Queue
This the identifier of the XAI JMS Queue created in the previous step, if JMS
Queues used.
47
PARAMETER
COMMENT
XAI JMS Topic
This the identifier of the XAI JMS Topic created in the previous step, if JMS Topic
used.
JMS Provider (Context)
This is similar to the Target Client Flag. This value overrides the value on the
JMS Queue or JMS Topic. The valid value is IBM (for WebSphere MQ) or blank
(or no value) for standard JMS.
JMS Target Client (Context)
implementations).
Note: Other parameters not listed in the above table should be entered as suggested in "XAI Senders".
Define JMS Receiver - The final part of the configuration it to define the JMS
Receivers to read the JMS Queues or JMS Topics defined earlier. This is achieved by
specifying the XAI Receiver using the Admin X XAI Receiver menu option on the
browser user interface of the product. The table below summarizes the key settings for
the XAI Receiver:
TABLE 23 JMS RECEIVER SETTINGS JMS INPUTS
PARAMETER
COMMENT
XAI Receiver
This is the identifier used by the XAI component to identify the XAI Receiver within
the registry.
XAI Class
For processing JMS Queues use the JMSRCVR (Receiver to poll JMS Queue) XAI
Class. For processing JMS Topics use the TPCRCVR (Receiver to poll JMS Topic)
XAI Class.
Read Interval
This is the interval, in seconds, between read cycles for the receiver will poll the JMS
resources. It is suggested that this parameter never be set lower that 10 seconds.
XAI JMS Connection
This the identifier of the XAI JMS Connection created in the previous step relating to
the JMS Queue or JMS Topic
XAI JMS Queue
If JMS Queues are used, then specify the identifier of the JMS Queue added earlier
XAI JMS Topic
If JMS Topics are used, then specify the identifier of the JMS Topic added earlier.
This is similar to the Target Client Flag. This value overrides the value on the JMS
Queue or JMS Topic. The valid value is IBM (for WebSphere MQ) or blank (or no
value) for standard JMS.
Response
This defines how to processes the response based upon the status of the call from
the underlying object. There are a number of options:
All Events This is a catch all option which is typically used when no
other events are defined. This defines the XAI Sender(s) to route the
message regardless of the outcome.
Application Error Which XAI sender(s) to route the response to when

the underlying object returns a business related error or configuration rule
that has been violated.
System Error Which XAI Sender(s) to route the response to when the
infrastructure returns an error (e.g. database error, program error etc) has
48
PARAMETER
COMMENT
been detected.
Message Sent Ok - Which XAI Sender(s) to route the response to when

the transaction completes successfully.
Each of these options can be defined more than once.

Groups
Not used.
Flush the MPL Server Cache (optional) - Before an XAI Receiver can be used the
JMS Input Processing Flow
Once the JMS Receiver has been configured and the XAI Server/MPL caches have been
refreshed the JMS integration is ready to operate. The flow diagram below illustrates the
common flow of processing:
No
JMS
Client
Read record from

JMS Queue/Topic
Transform using
Record XSL
Execute Against
XAI Servlet
Successful?
Yes
JMS Queue/Topic
Send SOAP
Error to
Error
Destination
Send Reply
to Reply
Destination
XML Message
based on target
schema
Figure 11 - JMS Input processing flow
The JMS Receiver polls the JMS Queue/JMS Topic configured using the JMS
Connection Factory. The JMS Connection Factory is created using the JNDI server
indicated at MPL startup time (or when the receiver is made active).
If a message is found on the JMS Queue/JMS Topic it is read and the message is
marked as read on the JMS Queue/JMS Topic in the JMS Provider.
If the message requires transformation as outlined on the XAI Inbound Service, then it
is transformed prior to execution.
The message is sent to the XAI Server directly, it does not use XAI staging.
49
The response is routed to the XAI Sender(s) indicated on the XAI Receiver Response
configuration depending on the outcome of the transaction.
Configuring an LDAP based input

Refer to the "LDAP Integration for ORACLE Utilities Application Framework based products"
whitepaper for details of this process.
Configuring Outbound Messages

Note: For Oracle Utilities Customer Care And Billing customers, Outgoing Messages replaces the Workflow and
Notification functionality available in previous versions of that product. While Workflow and Notification
functionality is still provided, it is strongly recommended that Outgoing messages be used for implementation
instead.
To send data out of the product to an external system (or market) the general approach is to use
the Outgoing Message functionality built into the Oracle Utilities Application Framework. The
functionality provides a series of prebuilt XAI Senders and XAI Receivers to recognize outgoing
messages and help ensure they are sent to the desired targets.
The concepts behind the Outgoing Message functionality are as follows:
A recognized business event triggers and a message is registered within the framework
to trigger the sending of the output.
The XAI component detects that a message needs to be sent then using the Outgoing
Message configuration and formats it according to the specification of the outgoing
message in XAI.
Note: XAI and MPL are only a subset of options of sending messages out of the product. Refer to the
Outgoing Message functionality for a discussion of other options.
The XAI Server will send the information to the configured targets using the relevant
Senders.
The process for configuration of an Outgoing Message is outlined as follows:
50
W3C Schema
Configure XAI
Sender
Configure
Outbound To Do
Type
Start
Configure
Outbound Message
Receiver
Configure External
System
Stop
Configure
Outbound Message
Type per Business
Object
XSL Mapping
Business
Object
Figure 12 Outbound Message Configuration Process
Before the specific message configuration is started, the first thing to ensure that the To
Do Type used by the Outgoing Message functionality is configured. This To Do Type is
used by the product when it detects an error during the processing of a message and
needs to alert someone to address the error. The configuration of the To Do Type is
available on the "To Do Type for Outbound Message Errors" option on the Admin
X XAI Options menu option on the browser user interface of the product. Refer to
the To Do configuration section of the online help for a description of setting this
option and using custom To Do types for this parameter. By default, the F1-OUTMS
To Do Type is provided as a predefined component.
The next step in the configuration process is to ensure that an Outgoing Receiver has
been configured for your site. By default, the product ships with OUTMSGRCVR as the
Outbound Message Receiver which is preconfigured. This receiver can be reused (with
appropriate setting for your site) or used as a basis for your own receiver.
Note: Only one (1) Outbound Message Receiver should exist per environment.
For each message to be sent an Outbound Message must be configured to detail the
format of the outgoing message in terms of data. The Outbound Message Type is used
by the trigger event to indicate a business even has occurred. The Outbound Message
Type is configured using the Admin O Outbound Message menu option on the
browser user interface of the product. The following table summarizes the typical
configuration of an Outbound Message Type:
TABLE 24 JMS RECEIVER SETTINGS FOR JMS INPUTS
SETTING
COMMENT
Outbound Message Type
An identifier for the message type. This is used for configuration purposes
only and does not form part of the message.
Description/Detailed Description
The summary and detailed documentation for the Outbound Message
51
SETTING
COMMENT
type.
Business Object
The business object that represents the data and format of the message
to be sent. This is configured using the Business Object functionality of
the product. Refer to the "Business Object" online documentation for
details of this process.
Priority
This is the priority of the message relative to other messages. This

instructs the order of processing to optimize higher priority messages.
To send the message to the required target using the required protocol, the XAI Senders
required for your interface must be created. Refer to the "XAI Senders" section of this
document for general sender setup advice and the relevant subsection on specific XAI
Senders. An XAI Sender must be setup per destination of the outbound messages. XAI
Senders can be reused across outbound message types.
To bring the configuration together the definition of an External System must be

completed. This represents the definition of an external target system and a definition of
the Outbound Messages to be sent to that system as well as how they should be sent.
The Outbound Message Type is configured using the Admin E External System
menu option on the browser user interface of the product. The following table
summarizes the typical configuration of an External System:
TABLE 25 EXTERNAL SYSTEM SETTINGS FOR JMS INPUTS
SETTING
COMMENT
External System
An identifier for the External System. This is used for configuration purposes only
and does not form part of the interface.
Description
The documentation for the External System.
Out Name In Their System
The name of our interface in the target system. This can be used by the transaction
as part of the identifier if desired.
W/F Process Profile
Not Used. Provided for legacy support for Workflow and Notification subsystem of
Oracle Utilities Customer Care And Billing.
Notification DL Profile
Not Used. Provided for legacy support for Workflow and Notification subsystem of
Oracle Utilities Customer Care And Billing.
Usage
Allows Outgoing Message types to be shared from another External System

definition if set to "Template External System". This supports the ability to
send the same messages to multiple systems and only specify them once.
Template External System
If Usage is set to "Template External System" then specify the External

System to be used as a template.
The collection of Outbound Messages for this External System are then defined in the
"Outbound Messages Type" section:
TABLE 26 OUTBOUND MESSAGE SETTINGS FOR JMS INPUTS
SETTING
COMMENT
52
SETTING
COMMENT
Outbound Message Type
The Outbound Message Type to be assigned to the External System.
Processing Method
The processing method to be used for the Outbound Message. The valid
values are XAI or Batch. For the purposes of this document, you should
choose XAI. Refer to the online documentation for a full discussion of the
different processing methods available.
XAI Sender
If the processing method is XAI, then indicate which XAI Sender should be
used to send the information to the External System.
Batch Control
If the processing method is Batch, then indicate which background process
Message XSL
If the message generated needs some further transformation before sending
should be used to send the information to the External System.
to the external system, then indicate the name of the XSL.

W3C Schema
If the message requires validation before it is sent to the external system then
indicate the W3C schema used for the validation. Refer to "Outbound
Message Schema Validation" in the online help for more details.
All the Outbound Message Types applicable for the particular External System entry
should be listed regardless of Processing Method.
Note: Outgoing Message Types only need to specified if the Usage on the external system is not set to "Template
External System".
The product is ready to process files using the XAI Receiver and External System definition. It is
suggested that the above process be repeated for each External System that requires information
at your site.
Outbound Message Flow
Note: This is a summary of the outgoing message process only. Refer to the "Outgoing Messages" section of the
"Framework Business Process Guide" for more information and additional processing required for processing
outgoing messages.
Once the Outbound Messages and External System are configured the XAI component can start
sending messages to external systems. The execution of this process is summarized below:
53
Business Triggers
Algorithm
XSL Mapping
W3C Schema
Translate
Message
Validate
Message
Change handler
Insert Outbound
Message into
staging
Server Side
User Exit
Pending Record
identified by
Outbound Staging
Receiver
Create Outbound
Message
Send Out using

XAI Sender
identified
on external
system
Service Script
External
System
definition
Database
Trigger
Figure 13 Outbound Message Processing Flow
A business event is detected by the product and an Outbound Message of the required
Outbound Message Type is created in Outbound Staging object with a status of Pending.
As part of that registration process, the context (i.e. key values) required for the
transaction and the external system is also lodged. The registration can be
programmatically achieved using an algorithm (Java/COBOL/script), change handler
(Java), server side user exit (COBOL), service script or database trigger.
Note: Refer to the Oracle Utilities SDK documentation more information about these registration
methods.
The Outbound Staging Receivers polls the staging area for pending record. When it
detects a pending record the following processing is performed:
The External System and the Outbound Message Type are used to determine
the XAI Sender and any translations that need to be performed.
The Outbound Message is created using the format of the Business Object on
the Outbound Message Type.
If the External System definition includes a XSL to translate the message it is

translated.
The resulting message (whether it is translated or not) is validated a provided

W3C schema (if provided).
The Outgoing Staging Receivers sends the message to the XAI Sender to
complete the transmission.
The Outgoing Staging record is updated with the status of the transaction
(error or complete) and the response is also stored for reference.
54
The above process is repeated for all Pending requests found by the Outbound Message
Receiver.
Note: Outbound Messages that have resulted in an Error can be sent for reprocessing, after resolving the cause of
the error, using the Main XAI Outbound Message menu option on the browser user interface of the
product.
Configuring a File based output

Note: This technique will show how extract a single business/maintenance object in XML format. With a few
extra design steps this can be extended to multiple records in any format.
One of the common ways of extracting information is to output the information to a file. The
file paradigm is used by a number of interfaces primarily interfacing to legacy external systems.
Note: For guidelines for the effective use of the Flat File Sender refer to "Extracting Files Best Practices".
The process for configuration is outlined in the figure bellow:
Flush XAI
Cache
WSDL
Schemas
Start
Identify
Business
Object
Register
Business Object
as XAI Inbound
Service for File
Generate
XSL
Mapping
Configure
Outbound
Messages
Register Flat
File Sender
Stop
Flush MPL
Cache
XSL Mapping
Figure 14 File based Output configuration process
Identify Business Object - The first step of the process is to find or define a business
object which represents the data you wish to extract. This can be done using the Admin
B Business Object menu option on the browser user interface of the product.
Regardless of the object used, the schema defined for that object will be used as the
default format for the extract.
Build & Register XAI Inbound Service - The XAI Inbound Service that will format
the data for sending out has to be configured and registered. For example if the file
contains Customer Contact records then an XAI Inbound Service on the Customer
Contact Object (Configuration Object) has to be created. Instructions for Configurable
Objects are located at "Registering Objects as XAI Inbound Services". This service
needs to be created initially as it will be required for later steps in the process. This
service can be created per interface or shared across interfaces.
55
Generate XSL Mapping - If the format of the outgoing record is different to the
schema format then it must be translated using an XSL (specified on the inbound
service or Outbound Message configuration) or use a File Name Processor.
Register Flat File Sender Once the services are in place and the cache has been
refreshed the Flat File Sender can be created using the Admin X XAI Sender menu
option on the browser user interface of the product. The specific settings for the Flat
File Sender are described in the table below:
TABLE 27 FLAT FILE SENDER SETTINGS
PARAMETER
COMMENT
XAI Sender
This is the identifier used by the XAI component to identify the XAI
Sender within the registry.
Invocation Class
This is the Sender type supported by the XAI Server and MPL. For
File based Senders, only MPL execution is supported at the present
time.
XAI Class
To send responses to Files use the FLATFILESNDR (Sender to post

messages to a flat file) XAI Class.
Append Time Stamp Format (Context)
The format of the time stamp at the end of the file. If blank (or
missing) then no timestamp is appended. The supported format
string values are outlined under "Designing XAI Formats" in the
online documentation.
Append Data to File (Context)
This parameter controls whether the content of the response

message is appended to an existing file, or a new file is created
(possibly replacing an existing one). Valid Values: YES or NO.
File Name Processor Name (Context)
If the file is a fixed format and there is a custom java class that
describes the format or custom processing of the file, then that java
class can be specified.
Flat File Pattern (Context)
The name of the output file. The file name may be a literal constant,
or generated dynamically.
To create a dynamic filename use <file name prefix>$$ID,
where $$ID is replaced at run time by the ID of the outgoing
message that triggered the response message and <file name
prefix> is the prefix literal you assign manually. If no file name is

defined for the sender, the <file name prefix> of XAI is used
(i.e. 'XAI$$ID.xai').
Flat File Output Directory (Context)
Directory in the file system where to write the file. This directory must
be accessible and writeable from the server that MPL is running
against.
Character Encoding (Context)
Indicates if the message should be sent with character encoding.

The sender will write the content of the file with encoding specified in
the context value.
If no value is specified, the sender uses the
default Java system encoding, which is determined according to the

operating system locale. Valid Values: UTF-8 or UTF-16.
56
To complete the configuration of the interface an Outgoing Message must be

configured, as outlined in "Configuring Outbound Messages", with the following
guidelines:
An appropriate Outgoing Message Type must be configured to detect when a file

transfer is to be initiated. This will reference the Business Object that was identified for
the extract.
Configure an External system (or reuse an existing one) to define the complete
integration including:
Reference the Outgoing Message Type created in the previous step.
Specify the Processing Method as XAI.
Reference the XAI Flat File sender as the XAI Sender.
If an XSL is used to manipulate the object prior to writing the record to the file
then include the XSL as the Message XSL. This XSL must be placed in the
common
XSL
location
for
XAI
(usually
$SPLEBASE/splapp/xai/schemas
or
%SPLEBASE%\splapp\xai\schemas).
Note: This is a focused subset of the configuration parameters necessary to defining an
External System. Refer to "Configuring Outbound Messages" for additional guidance.
To initiate a record to the Flat File to be written, you must code a business trigger to
insert a record with the appropriate Outgoing Message Type and External System using
an Algorithm (COBOL or Java), Change Handler (Java), Service Side User Exit
(COBOL) or Service Script. Refer to the Oracle Utilities SDK or online documentation
for further information of this process.
Flush the MPL Server Cache (optional) - Before an XAI Sender can be used the
immediately or at any time before the XAI Sender is used.
File based output flow
Once the Flat File Sender, Outgoing Message and External System have been configured and the
XAI Server and MPL's caches have been refreshed the interface is ready to execute.
The process flow for the file based output is shown in the figure below:
57
XML Message
based on input
schema
Outbound
Message Flow
Create XML from

Outgoing Message
Schema
Write record to
location in Sender
Context
Transform using
Record XSL
Record based
upon target
schema
Figure 15 File based Output Processing Flow
The Outbound Message is initiated as per the "Outbound Message Flow". The business
event creates a record of the appropriate Outbound Message Type with the relevant
context to indicate which records to extract.
The Outbound Message Receiver finds the records and processes them according to the
External System indicated on the Outbound Message Staging record as follows:
The Outbound Message context is used to retrieve the Business Object

configured on the Outbound Message Type to create an outgoing message
formatted as per the schema of the Business Object.
If the External System definition specifies an XSL file the object is translated
into the target format.
The record is written to the file in the target format as per the XAI Sender
specification for the Flat File Sender.
The Outbound Message is updated with the appropriate status.
Configuring a JMS based output

The Java Message Service (JMS) is part of the J2EE specification and provides a java interface to
Message Oriented Middleware which allows loosely coupled distributed communications. The
XAI component allows the product to send messages to JMS resources using an external JMS
Provider (such as Oracle Fusion Middleware, Tibco or IBM WebSphere MQ Series) as a target
for output from the product.
There are two types of JMS resources that can be interfaced from the product:
JMS Queue A queue is a staging area within the JMS Provider that contains messages
that have been sent and are waiting to be read. This method is also known as the point-to-
58
point or queuing model. As the name queue suggests, the messages are delivered in the
order sent. A message is removed from the queue once it has been read. XAI can post
messages into a particular queue and the target application can consume those messages
from that queue. Here, the XAI knows the destination of the message and posts the
message directly to the relevant queue. The attributes of a queue are:
The target application is the only receiver of the messages. Other potential
interested parties cannot receive the same message at the same time.
The target application does not have to be running at the time the XAI posts
the message, nor does the target application need to be running at the time the
message is sent.
Every message successfully processed is acknowledged by the target application

which signals the queue to delete the message from the queue. This is the
assumed responsibility of the target application.
JMS Topic A topic is a distribution mechanism for publishing messages that are
delivered to multiple subscribers. Subscribers
may register interest in receiving
messages on a particular message topic. This method is also known the
publish/subscribe model. In this model, neither the source application nor the
subscriber knows about each other. A good metaphor for this is an anonymous bulletin
board. The attributes of a topic are:
Multiple interested parties can get the message.
There is a timing dependency between source applications and subscribers. The

subscription must be created in the JMS Provider in order for interested parties
to be able to subscribe.
For more information about JMS it is recommended to review the Java Message Service
specification located at http://java.sun.com/products/jms.
Prior to configuring the JMS interface to the product the following must be in place:
A JMS Provider must be installed within your site. Any JMS compliant Provider may be
used.
If the JMS Providers uses a proprietary JMS client (such as IBM WebSphere MQ), it
must be installed on the same machine as the MPL or XAI Server and the client must be
in the PATH as well as CLASSPATH prior to accessing the JMS Provider. The XAI
Components uses a standard JMS client which is usually sufficient for most JMS
Providers. Refer to the "Extending the splenviron Command" section of the product
Configuration and Operations Guide on the various techniques used to achieve this.
59
The JMS Provider must be configured to meet site needs with the relevant JMS Queues
and/or JMS Topics to suite your interfacing requirements. Refer to the documentation
provided by your JMS Provider
The JMS Queue, JMS Topics and JMS Connection Factory must be defined to a Java
Naming and Directory Interface (JNDI) server available to the XAI Component. This
JNDI may be housed with the same J2EE Web Application Server as the XAI
Component or distributed. This is akin to linking the physical attributes of the JMS
Provider with the logical configuration to be used for XAI Component. These
attributes, as well as the location of the JNDI server, need to be noted to link the
physical setup with the configuration with the XAI JMS setup.
The process for configuration of outputting information to an JMS resource is outlined in the
figure below:
WSDL
Generate
XSL
Mapping
Schemas
Start
Identify
Business
Object
Register
Business Object
as XAI Inbound
Service for JMS
Define JNDI
Server
JNDI Server
Flush XAI
Cache
XSL Mapping
Define JMS
Connection
Factory
Define JMS
Topic/Queue
Configure
Outbound
Messages
Register JMS
Sender
Stop
Flush MPL
Cache
JNDI Server
Definitions
JMS Technology
JMS Topic
JMS Queue
Figure 16 JMS Output configuration process
The first step of the process is to find or define a business object which represents the
data you wish to extract. This can be done using the Admin B Business Object menu
option on the browser user interface of the product. Regardless of the object used, the
schema defined for that object will be used as the default format for the extract.
the data for sending out has to be configured and registered. Instructions for
Configurable Objects are located at "Registering Objects as XAI Inbound Services".
This service needs to be created initially as it will be required for later steps in the
process. This service can be created per interface or shared across interfaces.
60
Generate XSL Mapping (optional) If the output format differs from the business
object schema format then an XSL must be created to perform the translation. This
XSL can be built using any XSL tool using templates (i.e. schemas or Web Services) or
samples. This XSL must be placed in the common XSL location for XAI (usually
or
Define JNDI Server - For the interface to work, the XAI Server and MPL need to
know where to get the physical definitions to send the information to the correct
location. The JNDI server that holds the definitions must be defined to the XAI registry
for use by the MPL and XAI Server. This is achieved by specifying the XAI JNDI
Server using the Admin X XAI JNDI Server menu option on the browser user
interface of the product. The table below summarizes the key settings for the JNDI
Server:
TABLE 28 JNDI SETTINGS FOR JMS OUTPUTS
SETTING
COMMENT
XAI JNDI Server
This is the identifier used by the XAI component to identify the JNDI Server within
Description
Provider URL
The URL used for the JNDI Server. This may be a cluster or standalone reference.
Include the relevant protocol for the J2EE Web Application server used at your site
(see table below).
Initial Context Factory
This is the server class provided by the J2EE Web Application Server to access
the JNDI. The value varies from vendor to vendor (see table below).
For the Initial Context Factory, the following Web Application Server values apply:
TABLE 29 VALID VALUES FOR INITIAL CONTEXT FACTORY SETTINGS FOR JMS OUTPUTS
WEB SERVER
CONTEXT LIBRARY SETTING
PROTOCOL
Weblogic
weblogic.jndi.WLInitialContextFactory
t3
IWebSphere
com.ibm.websphere.naming.WsnInitialContextFactory
iiop
OAS
oracle.j2ee.server.ApplicationClientInitialContextFactory
opmn:ormi
Tomcat
org.apache.naming.java.javaURLContextFactory
java
Define JMS Connection Factory - When setting up JMS resources on the JNDI, a
JMS Connection Factory is required to hold the configuration information for any java
interface to use. The JMS Connection Factory configured in the JNDI must be defined
to the XAI registry for use with the MPL and XAI Server. This is achieved by specifying
the XAI JMS Connection Factory using the Admin X XAI JMS Connection menu
61
key settings for the JMS Connection:
TABLE 30 JMS CONNECTION SETTINGS FOR JMS OUTPUTS
SETTING
COMMENT
XAI JMS Connection
This is the identifier used by the XAI component to identify the JMS Connection
within the registry. This has no relation to the physical location of the server, it is
merely a tag used by XAI to find the definition in the registry.
Description
XAI JNDI Server
JNDI Connection Factory
This is the physical name of the JMS Connection Factory defined within the JNDI
server.
Define JMS Queue - If the interface is using a JMS Queue, The JMS Queue is required
to be defined to the XAI registry for use with the MPL and XAI Server. This is achieved
by specifying the XAI JMS Queue using the Admin X XAI JMS Queue menu
key settings for the JMS Queue:
TABLE 31 JMS QUEUE SETTINGS FOR JMS OUTPUTS
SETTING
COMMENT
XAI JMS Queue
This is the identifier used by the XAI component to identify the JMS Queue within
Description
Queue Name
This is the physical JMS Queue name defined within the JNDI server.
Target Client Flag
implementations).
XAI JNDI Server
Define JMS Topic - If the interface is using a JMS Topic, The JMS Topic is required to
be defined to the XAI registry for use with the MPL and XAI Server. This is achieved
by specifying the XAI JMS Topic using the Admin X XAI JMS Topic menu option
on the browser user interface of the product. The table below summarizes the key
settings for the JMS Topic:
TABLE 32 JMS TOPIC SETTINGS FOR JMS OUTPUTS
SETTING
COMMENT
XAI JMS Topic
This is the identifier used by the XAI component to identify the JMS Topic within
Description
XAI JNDI Server
62
SETTING
COMMENT
Topic Name
This is the physical JMS Topic name defined within the JNDI server.
Define JMS Sender To send transactions to a JMS resource a JMS Sender must be
created. This is achieved by specifying the XAI Sender using the Admin X XAI
Sender menu option on the browser user interface of the product. The table below
summarizes the key settings for the XAI Sender:
TABLE 33 JMS SENDER CONFIGURATION SETTINGS
PARAMETER
COMMENT
XAI Sender
This is the identifier used by the XAI component to identify the XAI Sender
within the registry.
Invocation Class
This is the Sender type supported by the XAI Server and MPL. For JMS
Senders, only MPL execution is supported at the present time.
XAI Class
To send messages to JMS Queues use the JMSSENDER (Sender to route

messages via JMS Queue) XAI Class.
For processing JMS Topics use the TPCSNDR (Sender to route messages
via JMS Topic) XAI Class.
XAI JMS Connection
This the identifier of the XAI JMS Connection created in the previous step.
XAI JMS Queue
This the identifier of the XAI JMS Queue created in the previous step, if
JMS Queues used.
XAI JMS Topic
This the identifier of the XAI JMS Topic created in the previous step, if
JMS Topic used.
This is similar to the Target Client Flag. This value overrides the value on
the JMS Queue or JMS Topic. The valid value is IBM (for WebSphere
MQ) or blank (or no value) for standard JMS.
JMS Target Client (Context)
This denotes whether the JMS client to be used is the standard JMS client
or the WebSphere MQ Series client (the latter only applies to WebSphere
MQ implementations).
Flush the MPL Server Cache (optional) - Before an XAI Sender can be used the MPL
cache must be reset to reflect the definitions of the service for the MPL. Refer to

guidelines:
An appropriate Outgoing Message Type must be configured to detect when to send

the message to the JMS resource is to be initiated. This will reference the Business
Object that was identified for the extract.
63
Reference the XAI JMS based Sender as the XAI Sender.
If an XSL is used to manipulate the object prior to writing the record to the file
then include the XSL as the Message XSL. This XSL must be placed in the
common XSL location for XAI (usually $SPLEBASE/splapp/xai/schemas
or %SPLEBASE%\splapp\xai\schemas).
Note: This is a focused subset of the configuration parameters necessary to defining an External
System. Refer to "Configuring Outbound Messages" for additional guidance.
To initiate a message to be sent to the JMS resource, you must code a business trigger to
insert a record with the appropriate Outgoing Message Type and External System using
an Algorithm (COBOL or Java), Change Handler (Java), Service Side User Exit
(COBOL) or Service Script.
JMS based output flow
Once the JMS based Sender, Outgoing Message and External System have been configured and
the XAI Server and MPL's caches have been refreshed the interface is ready to execute.
The process flow for the JMS based output is shown in the figure below:
Transform using
Record XSL
Outbound
Message Flow
Create XML from

Outgoing Message
Schema
Send Message to
JMS
Queue/Topic
Figure 17 JMS based Output Processing Flow
64

The record is written to the file in the target format as per the XAI Sender
specification for the JMS based Sender.
Configuring an email based output

Note: The examples in this document are only one method of sending emails out of the product. The Oracle
Utilities Application Framework Business Service F1-EmailService can be used programmatically to
achieve the same results.
Note: The XAI based email service is restricted to the functionality of the underlying email server configured. For
example, if the Email Server configured only supports text based emails then text will only be supported.
One of the most common customer contact patterns to initiate an email from the product to the
customer. The product offers a number of ways of achieving this using programmatic means
(through configurable objects) or using XAI/MPL. This section will outline the XAI/MPL
method only. Refer to the online documentation for a description of the alternative.
This interface assumes that there is an Email/SMTP server available to the server to send the
messages and that server is accessible to the server housing the product.
The process for configuration is very similar to the other methods documented in this
whitepaper:
65
W3C Email
Schema
Schemas
WSDL
Generate
XSL
Mapping
Identify
Business
Object
Start
Register
Business Object
as XAI Inbound
Service for
email
XSL Mapping
Register email
Sender
Flush XAI
Cache
Configure
Outbound
Messages
Stop
Flush MPL
Cache
Figure 18 Email output configuration process
The first step of the process is to find or define a business object which represents the
data you wish to put in the email. This can be done using the Admin B Business
Object menu option on the browser user interface of the product. Regardless of the
object used, the schema defined for that object will be used as the default format for the
extract.
the data for sending out has to be configured and registered. Instructions for
Generate XSL Mapping to W3C Email Schema To send an email in the correct
format the Email Sender requires the message to be in the format as outlined in the
standard W3C Email Schema. A copy of the schema is provided in the schemas
directory as the file CDxEmailSchema.xml. This XSL must define the required
elements in that schema including the following:
TABLE 34 EMAIL SCHEMA ELEMENTS
ELEMENT
COMMENT
From
This the userid that sends the message. It is recommended to use a dummy/null but
valid email address (i.e. a no-reply email account) to prevent it being the target of spam.
To
The list of userids to send the message to. This can be individual valid email addresses
or email groups. The delimiter for the userids is dependent on the email server used.
66
ELEMENT
COMMENT
Refer to the documentation provided with your email server for the correct delimiter.
CC (optional)
The Carbon Copy list of recipients. This can be individual valid email addresses or
email groups. The delimiter for the userids is dependent on the email server used.
BCC
The Blind Carbon Copy list of recipients. This can be individual valid email addresses or
email groups. The delimiter for the userids is dependent on the email server used.
Subject
The subject used for the email message.
MessageText
The text of the message. This needs to built in the XSL and can be in plain text or in
HTML format. The latter will require the appropriate tags.
Attachment
The filename(s) for any attachments. The full path to the attachment must be included
and accessible from the server running the XAI Server/MPL.
The XSL can be built using any XSL tool using templates (i.e. schemas or Web Services)
or samples. This XSL must be placed in the common XSL location for XAI (usually
or
%SPLEBASE%\splapp\xai\schemas). A sample is provided called F1Email.xsl.
Note: This sample should NOT be altered. Use a copy of the file as a basis for your translation.
To send messages via an Email Server resource an Email Sender must be created
outlining the physical attributes of the email server to use. This sender can be set once
per SMTP server and reused across configurations. To define an Email Sender use the
Admin X XAI Sender menu option on the browser user interface of the product.
The table below summarizes the key settings for the XAI Sender:
TABLE 35 EMAIL XAI SENDER SETTINGS
PARAMETER
COMMENT
XAI Sender
This is the identifier used by the XAI component to identify the XAI Sender within
the registry.
Invocation Class
This is the Sender type supported by the XAI Server and MPL. For Email
Senders, MPL or Real-time invocation classes are supported. If the latter is used
then the MPL will not be used to send emails.
XAI Class
The Email Server uses the EMAILSENDER XAI Class.
SMTP Host Name (Context)
This is the hostname for the Email/SMTP server
SMTP Userid (Context)
If the Email/SMTP server requires a logon to send messages the userid must be
provided.
SMTP Password (Context)
If the Email/SMTP server requires a password to send messages the password

must be provided.
67

guidelines:
An appropriate Outgoing Message Type must be configured to detect when to

send the message to the Email server is to be initiated. This will reference the
Business Object that was identified for the email contents.
Reference the Email Sender as the XAI Sender.
The XSL used to create the individual email is indicated as the Message XSL.
This XSL must be placed in the common XSL location for XAI (usually
or
Email based output flow
Once the Email Sender, Outgoing Message and External System have been configured and the
The process flow for the Email processing is shown below:
68
W3C Email
Schema
Transform using
Record XSL
Outbound
Message Flow
Create XML from

Outgoing
Message Schema
Send Message to
Email Server
SMTP
Server
Figure 19 Email based Output Processing Flow
context to indicate which data to email.

The XSL attached to the Outbound Message configuration within the External
System configuration is used to create the email message.
The completed email is sent to the SMTP Server configured on the Email
Sender.
The Outbound Message is updated with the appropriate status returned from
the Email Sender.
Configuring a HTTP Server based output

In some integration scenarios the output from the system has to be sent to a web based
application via HTTP. This is common in market participation scenarios and in some Enterprise
Application Integration (EAI) hub scenarios (though JMS is starting to become popular for EAI).
The MPL has an adapter to allow outgoing messages to be sent to an external web application
using the HTTP protocol.
69
The process for configuration is outlined in the figure bellow:

Flush XAI
Cache
WSDL
Schemas
Start
Identify
Business
Object
Register
Business Object
as XAI Inbound
Service
Generate
XSL
Mapping
Configure
Outbound
Messages
Register HTTP
Sender
Stop
Flush MPL
Cache
XSL Mapping
Figure 20 HTTP Server Output configuration process
Identify Business Object - The first step of the process is to find or define a business
object which represents the data you wish to send to the HTTP application. This can be
done using the Admin B Business Object menu option on the browser user interface
of the product. Regardless of the object used, the schema defined for that object will be
used as the default format for the extract.
the data for sending out has to be configured and registered. For example if the
application wants Customer Contact records then an XAI Inbound Service on the
Customer Contact Object (Configuration Object) has to be created. Instructions for
Generate XSL Mapping - If the web application expects the HTTP payload to be in a
specific format and that format is different to the schema format then the output must
be translated using an XSL (specified on the inbound service or Outbound Message
configuration).
Register HTTP Sender Once the services are in place and the cache has been
refreshed the HTTP Sender can be created using the Admin X XAI Sender menu
option on the browser user interface of the product. The configuration used for this
sender should match the expectations of the target web application. The specific settings
for the HTTP Sender are described in the table below:
TABLE 36 HTTP SENDER SETTINGS
PARAMETER
COMMENT
XAI Sender
This is the identifier used by the XAI component to identify the XAI
Sender within the registry.
Invocation Class
This is the Sender type supported by the XAI Server and MPL. For
File based Senders, only MPL execution is supported at the present
70
PARAMETER
COMMENT
time.
XAI Class
To send responses to Files use the HTTPSNDR (Sender to post

messages to a flat file) XAI Class.
HTTP Form Data (Context)
Used when the message is in the format of an HTML Form (ContentType: application/x-www-form-urlencoded).
This context specifies the form parameters (data) that should be
passed in the HTTP message.
Since a form may have multiple
parameters, you should add a context record for each form

parameter.
The value of a form parameter takes the format of x=y where x is the
form parameter name and y is its value. If y contains the string
@XMLMSG@ (case sensitive) then this string is replaced by the content
of the service response XML message.
If a context record of this type is defined for a sender, the sender
uses the HTML Form message format to send the message even if
@XMLMSG@ is not specified in one of the context records.
If a context record of this type is not defined for a sender, then the
XML is sent with Content-Type: text/plain. When using POST it is put
in the HTTP message body.
Always required when using the GET method. If you are using the
GET method and do not specify a Form Data context record, no
message is transferred to the HTTP server.
The MPL server builds form Data by concatenating the individual
parts.
You may use substitution variables when entering values for Form
Data.
HTTP Header (Context)
Sometimes the HTTP server on the other side may require the
addition of HTTP headers to the message.
For each HTTP header that has to be specified you should add a
context record with a value having the following format x:y where x is
the header name and y is the value for the header
HTTP Login Password (Context)
The HTTP server may require authentication. Add a context record

of this type to specify the login password to use.
HTTP Login User (Context)
The HTTP server may require authentication. Add a context record

of this type to specify the login user to use.
HTTP Method (Context)
The HTTP method used to send the message. Valid values are:
POST or GET. POST is the most common method.
HTTP Proxy Host (Context)
If connecting to the remote system requires using an HTTP Proxy,

then this context field can be used to configure the HTTP Proxy Host.
If the Proxy Host is set, the Sender class must use the value
specified to connect to the remote system via a proxy.
HTTP Proxy Port (Context)
If connecting to the remote system requires using an HTTP Proxy,
71
PARAMETER
COMMENT
then this context field can be used to configure the HTTP Proxy Port.
If the Proxy Port is set, the Sender class must use the value specified
to connect to the remote system via a proxy. If the HTTP Proxy Host
is not set, HTTP Proxy Port is ignored and the connection will be
made directly to the remote system.
HTTP Transport Method (Context)
Specifies the type of the message. You can either send the message
or send and wait for a response. Valid values:
Send Send a message but do not wait for a response.
SendReceive - Send a message but wait for a

response.
HTTP Timeout (Context)
Timeout to detect long connect times to HTTP Sender destination.

Refer to "Setting Error Tolerances" for further discussion.
HTTP URL 1 -9 (Context)
Used to construct the URL of the target HTTP server.

Since the URL may be long and complex, you can break it into
smaller parts, each defined by a separate context record. The MPL
server builds the full URL by concatenating the values in URL1
through URL9.
You may use substitution variables when entering values for URL
parts.
Character Encoding (Context)
Indicates if the message should be sent with character encoding.

The sender will write the content of the file with encoding specified in
the context value.
If no value is specified, the sender uses the
default Java system encoding, which is determined according to the

operating system locale. Valid Values: UTF-8 or UTF-16.

guidelines:
An appropriate Outgoing Message Type must be configured to detect when the server
transfer is to be initiated. This will reference the Business Object that was identified for
the extract for the transmission.
Reference the XAI HTTP sender as the XAI Sender.
If an XSL is used to manipulate the object prior to sending to the HTTP based
destination then include the XSL as the Message XSL. This XSL must be
placed
in
the
common
XSL
location
for
XAI
(usually
72
or

To initiate a HTTP Sender, you must code a business trigger to insert a record with the
appropriate Outgoing Message Type and External System using an Algorithm (COBOL
or Java), Change Handler (Java), Service Side User Exit (COBOL) or Service Script.
Refer to the Oracle Utilities SDK or online documentation for further information of
this process.
HTTP Server output flow
Once the HTTP Sender, Outgoing Message and External System have been configured and the
The process flow for the HTTP based output is shown in the figure below:
XML Message
based on input
schema
Outbound
Message Flow
Create XML from

Outgoing Message
Schema
Send to HTTP
Server in Sender
Context
Transform using
Record XSL
Record based
upon target
schema
Figure 21 HTTP Server Output Processing Flow
73

The record sent to the file in the target format as per the XAI Sender
specification for the HTTP Sender using the following rules:
The URL of the server is built using the XAI Sender context values
for HTTP URL 1 to HTTP URL 9. This includes using substitution
variables. Refer to the online documentation for a description of the
available substitution variables.
The Message contents are built according to the HTTP Form Data
rules.
A connection is attempted to the URL built for the HTTP Server in

an earlier step. If a Proxy is specified then this is used as part of the
connection process.
Upon establishing a connection, if the HTTP Server requires

authentication then the appropriate HTTP Userid and HTTP
Password are processed in the HTTP Header.
The Header and Message contents are sent to the destination HTTP
Server using the configured HTTP Method. At this point the process
may wait for a response (SendReceive) or simply send and not
wait (Send).
Best Practices
The XAI component is used by most sites for integration between the product and other systems
within the site inventory of systems. While the XAI component is quite open and powerful, there
are practices that help optimize the configuration and operations of the component for a site.
This section will outline some general advice and practices that may prove beneficial in some way
to your site.
Maximize Reuse
One of the key practices for minimizing maintenance effort is to reuse as much of your XAI
configuration as possible across multiple interfaces. This requires some planning
74
Reuse XAI Inbound Services across interfaces While it is possible define an XAI
Inbound Service per interface, it is also possible to design your services to be shared
across interfaces. Given most XAI calls can represent subsets of data then a single XAI
Inbound Service can become a superset of all the elements needed for all interfaces
needing that particular data. For example, if an object offers elements A, B, C, D, E, F
and G and Interface 1 requires access to A, B, C and D and Interface 2 requires access
to A, D, E and F, then a single XAI Inbound Service can be created with A, B,C, D, E
and F to share across Interface 1 and Interface 2. In this example, the unused element
"G" can be also included, if desired, just in case Interface 1 or Interface 2 requires it
sometime in the future. This is an example of service reuse. It is also valid to define
separate XAI Inbound Services for Interface 1 and Interface 2, this just incurs a higher
maintenance cost over time.
Reuse XAI Inbound Services across Transaction Types Given that the
transactionType is an element in all the XAI Inbound Services, it is possible to
share XAI Inbound Services across different transactionType values. For
example, the same XAI Inbound Service can be used to READ data as well as UPDATE
data. In the latter case, only the elements that require update need to be specified in the
request to XAI.
Reuse Senders A sender is a record of a target channel for information to be sent to.
In most implementations each discrete target channel is defined once. Several
transactions and formats can be sent to the same channel (if required) using the External
System definition.
Reuse Receivers Reuse of XAI Receivers is limited in nature as Receivers represent

individual sources of information. Typically, sources of information are discrete and
therefore discrete Receiver definitions are required.
Reuse JNDI Servers One configuration needs to exist per JNDI server where the
physical attributes JMS resources are defined. If all your JMS resources are defined in
one central JNDI server then this server only needs to be configured once. If the JNDI
definitions are spread across multiple servers then define each server in the XAI registry
and link them to the relevant JMS definitions. This advice also applies to the JNDI
definition for the LDAP integration.
Reuse JMS Connections Each JNDI Server willed fine at last one JMS Connection
Factory for accessing JMS resource definitions. Define as many JMS Connections as
there are defined in the JNDI Server.
Reuse JMS Topics/Queue Queues and Topics can be reused under certain
circumstances. Typically a JMS Queue or JMS Topic is setup per interface per
transaction content type but this is not a rule imposed within XAI. The JMS resources
that are defined to the JNDI server need to be configured as per the server definitions
75
(i.e. there should be an entry per JMS resource defined at least). The reuse aspect of JMS
resources in XAI is typically used in defining error or reply queues. Refer to "Use of
JMS reply and error queues" for a more in-depth discussion of this facility.
Reuse Outgoing Message Types and External Systems Define a common set of
outgoing messages that can be related to specific data streams. At the time of the
initiation of an outgoing message transfer the outgoing message type and external
system are used as keys to decide what action to perform. Creating a single External
System definition per actual interface system is a common technique which can include
multiple outgoing message types and processing types.
Reuse can be used (or can be ignored altogether with multiple entries being created) to help save
maintenance costs. It is up to the site specific design and preferences in configuration but it is
suggested to consider the above guidelines for reuse to help minimize maintenance effort.
Validation of schemas
The XAI Component can validate schemas against the base product object definitions to ensure
consistency and compliance across versions of the product From time to time the object
definitions change with new versions of the product (i.e. new features added or existing features
updated). While all changes are planned around backward compatibility, objects should be
checked against new versions of the objects to ensure smooth transition in upgrades.
Note: While deletion of elements is rare, it can happen. Check the release notes when upgrading for announcements
of object changes.
If your XAI Inbound Service is Maintenance Object based then the XAI Schema Editor Client
will validate the schema used in the XAI Inbound Service if it is reopened in the XAI Schema
Editor Client and re-saved. The schema is automatically checked against the base definition and
any inconsistency highlighted. Additionally the XAI Schema Editor Client allows for mass
validation of schemas, this is useful for checking ALL the custom Maintenance Object based
schemas. Inconsistencies are highlighted for fixing (usually as simple as a click).
If your XAI Inbound Service is Configuration Object based then opening the object in the
relevant maintenance function (Business Object, Business Service or Service Script) and re-saving
the schema will result in a validation against the base object definition and errors highlighted.
Defaulting Transaction Types/Search Types

As discussed earlier in "Transaction Types instead of Methods" XAI uses Transaction Types
(also Search Types and Row Actions) to indicate the action to be performed against an object.
Whilst you can set an individual value per call of the same service, you can also define a default
value to use. If the call for the service does not contain the transactionType element then
the default is used.
76
When registering an XAI Inbound Service, consider setting the default Transaction Type to the
most common value to be used for the service. This applies to Search Type as well. For
Maintenance Object based services using a search service, the most common search type should
be used as the default. In practices, using when search services the XAI Inbound Service usually
only uses one search type to optimize the criteria section of the schema.
Using default values can remove the need for the transaction type. Using defaults can assist if
your interfaces do not want to use transactionType or searchType. In this case be
careful that you do not alter the default Transaction Type or Search Type on the XAI Inbound
Service, after it has been set, as it may cause unexpected results.
Use Configuration Objects rather than Maintenance Objects

Note: Refer to the online documentation on Configuration Objects for a detailed discussion of the features
available.
Since Oracle Utilities Application Framework V2.1, the concept of configurable objects was
introduced to allow customers to build their own objects based on the Maintenance Objects
shipped with the product. This allows a site to specify a custom view of the object targeted for
their needs whilst using the existing power of the existing Maintenance Object.
It is recommended that when building XAI Inbound Services for your site, you consider using
Configuration Objects instead of Maintenance Object services. Using the schema language saves
the necessity of using an XSL mapping against an object as the mapping is built into the object
definition.
The Configuration Object approach offers lots of advantages for XAI Inbound Services:
Configuration Object schemas result in element based schemas rather than attribute
based schemas of the Maintenance Object based approach. Most sites use element
based XML rather than attributes.
Build once use many times. Just like most of the objects within the system and the concept
of Java, you can build a schema in a Configuration Object to use in a screen or as a call
out from another object or as an XAI Inbound Service. This means that the
configuration effort used to define the sites own objects can be reused for interfaces as
well.
Configuration Objects allow the interface to decide the structure of the object not the
Maintenance Objects themselves. The Configuration Object specification allows for a
mapping and restructuring of the object to map more closely the business requirements
for a site. In the Maintenance Object approach, the interface was restricted to using the
product provided structures which may not be optimal for interfacing.
77
It is possible to use Query Portal specifications as XAI Inbound Services via Business
Services. This means that a site can use Query Portals to search for data using custom
SQL functions and multiple criteria and then through Business Services, expose that
Portal as an XAI Inbound Service to extract data from the product.
Whilst, use of Configuration Objects in XAI Inbound Services is encouraged there are a few
things that can prevent its use at a site:
Only Business Objects, Business Services and Service Scripts can be exposed as XAI
Inbound Services. All other object types (UI Maps, Data Areas etc) cannot be used as
XAI Inbound Services.
If the site uses attributes (even if attributes are combined with elements) then
Maintenance Object based services must be used in association with XSL to transform
the schema into the required format for the specification.
If the interface requires custom formatting of dates, times and other enumerated fields
as expressed in XAI Formats, then the Maintenance Object based approach is the only
method, at the present time, that supports XAI Formats.
Minimize use of the Schema Editor Client

The XAI Schema Editor Client is a component of the Oracle Utilities SDK. It is designed to
assist in the building and management of Maintenance Object based Schemas and Services. It not
designed to be used with Configuration Object based Schemas and Services.
Over the last few releases more and more of the common functionality has been moved from the
XAI Schema Editor to the browser user interface provided with the product. The browser user
interface versions of the functionality have been extended to provide additional capabilities and
to support the myriad of object types now supported by the XAI Inbound Service registration
process.
The table below illustrates the various functions available and the mapping to the browser user
interface:
TABLE 37 XAI SCHEMA EDITOR CLIENT FUNCTIONS VS BROWSER UI
FEATURE
Export
USAGE
Schema
to
SCHEMA EDITOR
Exports Schema to BizTalk and DTD formats
Generates a schema from a base Maintenance Object
BROWSER UI
foreign formats
Generate Schema
78
FEATURE
USAGE
SCHEMA EDITOR
Generate WSDL
Generates Web Services Definition Language for Schema
Maintain Schema
Maintains existing schemas
Register Service
Registers a XAI Inbound Service
Test Service
Tests a XAI Inbound Service
Validate Schema
Validates individual (or Mass Validate) of schemas
BROWSER UI
It is suggested that the browser user interface functions be used where there is overlap to provide
maximum compatibility. Therefore the XAI Schema Editor client should only be used for
building, maintaining and validating Maintenance Object Schemas.
Migrating between Classic and XAI Servlet

In Oracle Utilities Application Framework V2.2, several key changes were introduced to the XAI
Server to allow advanced support for Web Services and enhancements around security. In
summary these facilities are as follows:
Support for WS-Security The XAI Server supports a number of security mechanisms
which includes WS-Security. Refer to "Runtime Security of XAI Inbound Services" for
advice pertaining to this facility.
Dynamic WSDL generation The ability to generate WSDL for any XAI Inbound
Service from a standard URL for supporting development. Refer to "Generating Web
Service Definition Language" for more information about this facility.
UDDI Discovery of Services The ability for a UDDI Server to query the product
using a standard URL to load service definitions into the UDDI repository for
supporting development.
For customers of earlier versions of the product these facilities may not want to introduce these
facilities into their existing configurations. Whilst it is possible to enable or disable specific
facilities in the product (these will be discussed in subsequent sections of this document), a new
URL has been introduced that automatically disables all new functionality for maximum
backward compatibility. This allows a site to progressively introduce the new facilities in a time
frame that best suits their constraints.
To disable all the new facilities the URL to submit XAI Inbound Services to is:
http://<host>:<port>/<server>/XAIApp/classicxai where
Natively supported by XAI Server
79
<host>
<port>
<server>
To introduce the new features as required the following URL must be used (this is the default URL
for all XAI Server calls):
http://<host>:<port>/<server>/XAIApp/xaiserver where
<host>
<port>
<server>
Refer to "Runtime Security of XAI Inbound Services" for a description of new features.
Flushing the XAI and MPL Caches

For performance reasons the XAI Registry information is loaded into cache memory for the XAI
Server and MPL. These processes refer to the cached information during processing and
therefore any changes to XAI Registry objects would require the cache to be reloaded,
commonly called "flushing" which describes that the cache is cleared and forces the server
processes to reload the cache from the store definitions of the objects, or the server has to be
restarted.
The following table lists the commonly used XAI Object types that are cached for performance
reasons:
TABLE 38 COMMONLY CACHED XAI RELATED OBJECT TYPES
PARAMETER
COMMENT
External Systems
External System definitions
Outgoing Message Types
The Outgoing Message Types used by XAI to process outgoing data.
Schemas
Schemas used in Maintenance Objects
XAI Adapters
Internal Adapter definitions for runtime
XAI Executers
URL's used by the MPL to access XAI Server
XAI Formats
Custom and base data formats used for processing
XAI Groups
Groups used for XML file processing
XAI Inbound Services
Service definitions (regardless of Adapter used)
XAI JDBC Connections
If any XAI Object has a custom JDBC connection then the database connection information
is cached.
XAI JMS Connections
JMS Connection factories specified
XAI JMS Queues
JMS Queues specified in configuration
XAI JMS Topics
JMS Topics specified in configuration
XAI JNDI Servers
JNDI Servers used for JMS and LDAP integration
80
PARAMETER
COMMENT
XAI Options
XAI Configuration options
XAI Receivers
XAI Receiver definitions including context and response targets
XAI Senders
XAI Sender definitions including context
XSL Transformation Scripts
Any scripts defined in any XAI object for transformation
There are a number of ways of forcing the cached data to reload:
Using the "Refresh XAI Server Cache" menu option or toolbar button from the XAI
Schema Editor Client. This only refreshes the XAI Server cache.
Using the Admin X XAI Command on the browser user interface of the product
and selecting "Refresh Registry" from the command dropdown. This option also
allows the command to be sent to both the XAI Server and MPL or to the XAI Server
only. If the command is to be sent to the MPL ensure the MPL Administration Port is
correct on the screen before submitting. This option also allows some subset of the
cache to be refreshed:
Refresh Code and Description Allows custom attributes from Maintenance

Objects to be reloaded from definitions. Refer to "How to Create Code
Description Attribute" section of the online documentation for more
information
Refresh Schema Allows schema definitions to be refreshed.
Refresh Service Allows XAI Inbound Service definitions to be refreshed.

An individual service can be refreshed.
Refresh XSL - Allows XSL Transformation Scripts to be refreshed.
Once the command is sent, processing is temporarily halted while the cache is reloaded from
scratch. This delay is usually negligible.
Note: Avoid sending multiple refresh requests as while individual requests cause negligible delays, the cumulative
effect of multiple refresh requests can cause longer delays.
Migrating XAI Inbound Services between environments

Note: Using the ConfigLab or the Bundling facility in the product is not covered in this section. Refer to the online
documentation for an overview of these facilities.
As part of the development process XAI Inbound Services need to be transferred between
environments. While XAI Inbound Service definitions (as well as any other XAI Registry
information) can be transmitted using ConfigLab and the new Bundling facility provided with
Configuration Objects, it is possible to export existing XAI Inbound Service definitions and
import those service definitions into a target environment.
81
Note: This process only processes XAI Inbound Services definitions not any related schemas or XSL related to the
Service definition. These must be migrated manually or using the migration utilities provided with the Oracle
Utilities SDK.
To export the XAI Inbound Service definitions, use the Admin X XAI Service Export menu
option on the browser user interface of the product. This functionality will allow you to manually
select all or individual service definitions to export and when the Export is initiated it will ask for
a file name to export the information into. This file is an XML description of the XAI Inbound
Service definitions. This definition file is usually saved to your local client machine (or a
accessible storage device).
To import the exported XAI Inbound Service definitions, use the Admin X XAI Service
Import menu option on the browser user interface of the product on the target environment. This
dialog will ask for name of the export file name to load (this file does not have to exist on the
server but your local client machine). It will then provide a facility to allow selective
installation/update of the XAI Inbound Services on the target environment. It also provides the
facility to selectively overwrite existing XAI Inbound Services on the target.
Note: Before any XAI Inbound Services can be used any related object data, schemas or XSL must exist on the
target platform
Note: As the XAI Registry is altered a refresh of the server cache must be performed to implement the changes.
Refer to "Flushing the XAI and MPL Caches" for more details of this process.
When do I need the MPL?

The Multi-Purpose Listener (MPL) is an optional part of the XAI component. Not all
implementations choose to use the provided MPL as they either do not require the functionality
or use an alternative Enterprise Service Bus. Remember the MPL is not a fully featured
Enterprise Service Bus (ESB) but a simple listener process that can provide basic near real time
integration functionality.
Currently there are definite reasons to use the MPL (even in conjunction with an existing ESB).
The reasons are as follows:
The interface needs to send information from the product to other systems. At the
present version, the MPL is the only interface to the Outgoing Message component
used to initiate and track outgoing messages.
The XAI Staging process is required for processing and tracking. The XAI Staging
Senders and Receivers cannot be called from an external ESB.
Data from the LDAP Data Store needs to be synchronized with the Oracle Utilities
Application Framework authorization model.
82
If any of the above apply to your site then the MPL needs to be implemented in at least a
minimal state.
If you already have an ESB at your site that can call Web Services then the following can be done
with the ESB replacing the MPL:
XML/File Scan Receiver This can be replaced with the ESB polling the directory,
translating the record format into a Web Services call using HTTP real time calls.
JMS Receiver (Queue And Topic) This can be replaced with the ESB polling the
JMS resources, translating the record format into a Web Services call using HTTP real
time calls. The response can also be forwarded to another JMS resource (like the MPL
does).
Database Polling This can be replaced with the ESB polling the source database,
translating the record format into a Web Services call using HTTP real time calls. The
ESB may even have functionality to mark the records in the source database (something
the MPL does not do).
The integration between an ESB and XAI is the ability to send real time HTTP requests to XAI
Server directly using SOAP with WS-Security.
Runtime Security of XAI Inbound Services

One of the major areas of change in XAI is security. As with any other mode of access to the
product the access is governed by the security setup at a site.
Security is typically divided into authentication and authorization. Authentication is where the
channel trying to access the system must identify themselves to the product. This is typically a
challenge-response style of security where the channel provides security credentials such as a valid
userid and password combination. If the authentication is successful, then the next level of
security is to verify that the valid user can do the function they are requesting (hence the term
authorization).
The authorization of the security is handled by the Oracle Utilities Application Framework
security model. For more information on this model refer to the "Oracle Utilities Application
Framework Security Overview" whitepaper available from My Oracle Support. From an
authorization point of view the user used to run the transaction must have access to the objects
related to the XAI Inbound Service which has the following variations:
Maintenance Object based services Each Maintenance Object based Service is

based upon a base service schema, registered under "Service Name". This schema is
associated with a function in the system. The user used for the XAI transaction must be
a member of a user group that has the appropriate permission to the Service Name
registered on the XAI Inbound Service.
83
Configuration Object based services Each Configuration Object based service is

based upon a Configuration Object within that system. As part of the Configuration
Object specification an Application Service used for security is configured. This
Application Service can be generic (such as F1-DFLTS) or specifically setup for the
Configuration Object. The user used for the XAI transaction must be a member of a
user group that has the appropriate permission to that Application Server to access the
object data.
From an authentication perspective the credentials of the transaction can be sent to the XAI
Server in one of the following ways:
The Userid and Password can be sent as per WS-Security SOAP header authentication 2.
The Password can be sent in plain text or encrypted (the Encoding tag must be
provided for encrypted passwords). Refer to "Server Security" section of "XML
Application Integration" of the "Framework Administration" online help for examples
and guidelines.
The Userid and Password can be taken from the XAI Registry. Certain transaction types
within MPL cannot pass credentials so require a default user to be configured to allow
secure transactions.
Note: It is suggested that a separate recognizable userid be setup for this purpose as any audit records
will be associated with this user.
The security configuration of the XAI component is accessible from the Admin X XAI
Options menu option on the browser user interface of the product. The table below lists the
settings that affect security:
TABLE 39 XAI SECURITY RELATED CONFIGURATIONSETTINGS
OPTION
Attempt
Authentication
Classic
XAI_OPTION_FLG
COMMENT
SDCA
Authentication information may be sent across in the SOAP header or in the

HTTP header (Classic). When set to Y, the system first attempts to authenticate
using information on the SOAP header. If none provided, the system attempts
to authenticate this time using information on the HTTP header. This is the
default option. When set to N, the system solely uses the authenticate
information provided on the SOAP header. This option is primarily provided for
customers migrating from the classicxai to the xaiserver servlet.
Note: This setting is deprecated in Oracle Utilities Application Framework
Version 4.0 and above
X.509 and SAML are not support in the current release of XAI.
84
OPTION
XAI_OPTION_FLG
COMMENT
Default User
DFUS
The default user is used by XAI to access your product when no other user is
explicitly specified. Refer to Server Security for more information. Additionally,
the Default User is used for MPL transactions where there is no facility to
provide a User ID. For example, no facility exists to provide a user id when
reading messages from a JMS Queue. In these messaging scenarios, the
system will use the Default User for authorization purposes.
Enforce
SOAP
SDSA
By default, even if the container has already authenticated a web service

request, the system would further attempt to authenticate it using SOAP header
Authentication
information. Set this option to N if you want to not re-authenticate a request

already authenticated by the container.
By default, if SOAP authentication information is not available, the system
attempts to further authenticate using basic HTTP authentication. Refer to the
"Attempt Classic Authentication" XAI option for more information.
System
Authentication
SDAC
Use this option to override the base product's default authentication method.
Value must be a valid XAI Class that implements the base package
Class
WSAuthentication javainterface.
System
Authentication
SDAP
This option enforces the mode in which user credentials are sent to the system.
When set to USER only the user name is authenticated. When set to FULL, user
Profile
and password are authenticated. This is the default value.

Note: These settings are loaded into the XAI Server and MPL caches at startup time.
Security of the Multi-purpose Listener

The MPL needs to communicate to the XAI Server in a secure way. When a transaction is sent
from the MPL to the XAI Server the transaction must be authenticated by the Web Application
Server that houses the XAI Server and then the Oracle Utilities Application Framework security
model must ascertain whether the user has correct permissions to execute the transaction.
The security settings pertaining to the MPL are configured from the Admin X XAI Options
menu option on the browser user interface of the product. The table below lists the settings that
affect security:
TABLE 40 MPL SECURITY RELATED CONFIGURATIONSETTINGS
OPTION
MPL
HTTP
Authentication Method
Server
XAI_OPTION_FLG
COMMENT
MHAM
This setting, along with the MPL HTTP Server User and Password are
used to secure commands received by your MPL (such as those issued
via XAI Command) through HTTP. Currently only BASIC authentication
85
OPTION
XAI_OPTION_FLG
COMMENT
is supported.
MPL HTTP Server User
MHAU
This setting, along with the MPL HTTP Server Authentication Method
and Password are used to secure commands received by your MPL
(such as those issued via XAI Command) through HTTP.
MPL HTTP Server Password
MHAP
This setting, along with the MPL HTTP Server Authentication Method
and User are used to secure commands received by your MPL (such as
those issued via XAI Command) through HTTP. The password should
be in encrypted form, using the same encryption that is used for the
database password.
Privileged Users
SUSR
comma delimited list of
users
that are
permitted
to
use
effectiveUser and effectiveUserId.

XAI Authentication Password
HBAP
The multi-purpose listener uses this field in combination with the XAI
Authentication User when attempting to communicate with the XAI
server over HTTP, which is running on a secured servlet and requires
authentication.
XAI Authentication User
HBAU
The multi-purpose listener uses this field in combination with the XAI
Authentication Password when attempting to communicate with the XAI
server over HTTP, which is running on a secured servlet and requires
authentication.
Note: These settings are loaded into the XAI Server and MPL caches at startup time.
Use of Real Time Senders

In Oracle Utilities Application Framework V2.2, the concept of Real-Time Senders was
introduced. This allows a particular sender class to bypass using the MPL and have the XAI
Server send the information in real time. In the current release of the product, only senders that
communicate via HTTP are supported. The following list of XAI Senders supports Real-time
Sending:
Email Sender It is possible to send emails directly from the XAI Server.
Outgoing Message Sender It is possible to send messages to specific resource. For

this to work the processing method defined for the outbound message type and an
external system must be Real-time and the XAI sender defined for the outbound
message type and an external system has to be set up with Real-time invocation
type. Just like near real-time messages, you can easily create outbound message records
from a script. When a real time message is added, the system immediately routes it to
the external system. If the external system provided a response message back, the
system captures the response on the outbound message. If the outbound message type
for the external system is associated with a response XSL it is applied to transform the
response. In this case the system captures the raw response as well on the outbound
message. Any error (that can be trapped) causes the outbound message to be in a state
86
of Error. It is the responsibility of the calling process to check upon the state of the
outbound message and take a programmatic action. When the outbound message state
is changed back to Pending the message will be retried.
Use of JMS reply and error queues

One of the features outlined as part of the XAI Receivers is the ability to route responses from
requests to different XAI Senders depending on the status of the request. The XAI Receiver can
send responses based upon success or failure (and different types of failure) to multiple XAI
Senders.
If you are considering using JMS based Senders for responses, consider using different JMS
resources (JMS Topics or JMS Queues) for different status values. Some sites avoid sending
responses with error conditions 3 to same JMS resource as the successful transactions. This may
avoid complex processing on the target application to deal with errors. Of course, if the site
wishes to send responses regardless of status to the same XAI Sender then this can also be
configured.
JDBC Pooling
The MPL is regarded as a client component in relation to the XAI Server. As part of its operation
it needs to access the database directly to load the XAI Registry into its cache as well process
some of the types of messages that are sent to it. As with the rest of the product, a pool of
database connections is configured for the MPL for performance.
Note: The MPL does not use Hibernate/c3p0.
The database connection pool settings for the MPL are configured from the Admin X XAI
relevant settings:
TABLE 41 JDBC RELATED CONFIGURATIONSETTINGS
OPTION
XAI_OPTION_FLG
COMMENT
JDBC Connection Pool
JPMS
The MPL uses a pool of JDBC connections to connect to the database. This
Max size
option determines the maximum number of JDBC connections that can be

opened in the pool. The default value is 100. This represents the maximum
not the actual number of connections used by the MPL.
At a minimum consider a different JMS resource for different error types (application vs system
errors).
87
Unless testing indicates otherwise this default setting should be used.
Setting Error Tolerances

When an error occurs in an XAI Sender transmission the product can be configured to either log
the error to continue on to the next message to process or retry to send the message till it is
successful or till a tolerance is reached and the sender is marked as unavailable. If the latter
situation occurs the XAI Sender can be reactivated manually or after a time limit has expired.
Deactivating and automatically reactivating unresponsive XAI Senders after a period of time can
prevent endless error messages appearing when some infrastructure is not available that the XAI
Sender needs. This facility avoids multitudes of error messages appearing in the logs for the
duration of the outage.
This process also applies to the internals of the product when it encounters an error and cannot
register the error. This can occur when the XAI Server is unavailable.
The error tolerances described above settings pertaining to the MPL are configured from the
Admin X XAI Options menu option on the browser user interface of the product. The table
below lists the relevant settings:
TABLE 42 JDBC RELATED CONFIGURATIONSETTINGS
OPTION
XAI_OPTION_FLG
Automatically
Attempt
ARSD
COMMENT
Set to Y if you wish to enable Automatic Resend. Set to N if you wish to log
Resending to Unavailable
errors when the system fails to send an outgoing message. This setting
Senders (Y/N)
covers all XAI Senders.
Maximum Errors for a
MSER
Sender
This value is required if you have enabled Automatic Resend. It defines how
many errors you receive from a sender when attempting to send an outgoing
message before you mark the sender unavailable.
Seconds to Wait Before

Marking
SNWT
This value is required if you have enabled Automatic Resend. It defines how
many minutes to wait after marking a sender unavailable before you mark the
Sender
sender available again (and retry sending messages to it).
Available
System Error Max Retry
SEMR
When a request fails to execute due to a system error, the MPL retries its
execution several times until a maximum number of retries is reached. This
option specifies the maximum number of retries.
System
Interval
Error
Retry
SERI
execution several times. This option specifies the number of seconds the MPL
server waits between retries.
It is possible to manually activate and deactivate individual senders using the MPL
Administration commands outlined in "MPL Administration".
Use of character sets within XAI
88
The Oracle Utilities Application Framework is multi-lingual and supports many character sets. If
your site uses a double byte or complex character set (i.e. non-west European) then it is possible
to set the extended character set UTF-16 for transactions.
The configuration settings used by the XAI components are configured from the Admin X
XAI Options menu option on the browser user interface of the product. The table below lists the
settings that affect character sets:
TABLE 43 CHARACTER SETS RELATED CONFIGURATIONSETTINGS
OPTION
Default
Response
XAI_OPTION_FLG
COMMENT
DRSE
Determines the character encoding to be used when a response is sent. For

example, you may specify UTF-8 or UTF-16. If no value is specified then the
Character Encoding
default is UTF-8. If no special encoding should be done, then enter the value
none
This is a global setting that can be overwritten using the context values for individual XAI
Receivers or XAI Senders.
Setting locations for use with XAI

When the product is installed a number of key locations for files are automatically registered as
part of the installation process. In most cases these settings are not changed but the product
allows them to be changed if deemed necessary. These location settings are configured from the
below lists the settings that store locations:
TABLE 44 LOCATION RELATED CONFIGURATIONSETTINGS
OPTION
XAI_OPTION_FLG
COMMENT
XSL Directory
XSDR
The full path of the virtual directory where XSL transformation scripts are
located. XSL transformation scripts can be defined for each service. By
default, this is the same directory as the schemas directory.
Outbound
Message
XLOC
Schema Directory
Enter the full path of the virtual directory where valid W3C schemas are
stored if your implementation wants to validate outbound message schemas.
Schema Location
SCDR
The full path of the virtual directory where XML schemas are stored. If this
option is not specified, the XAI uses the current directory, from where it is
being run, to locate schemas.
Error messages in XAI

When an error occurs in XAI (including the MPL) it retrieves the error message (based upon
your language setting) from the Oracle Utilities Application Framework repository. It then
formats the error message into a SOAP Fault to return to the calling application. This behavior
can be altered to suit your sites needs.
89
Note: The online documentation explains the process of changing the error text for error messages if that is
necessary for your site.
The settings pertaining to the configuration of error messages are configured from the Admin
X XAI Options menu option on the browser user interface of the product. The table below
lists the settings that affect error message processing within XAI:
TABLE 45 ERROR MESSAGE RELATED CONFIGURATIONSETTINGS
OPTION
Messages
JDBC
XAI_OPTION_FLG
COMMENT
MSJC
Specifies the JDBC connection that XAI uses to read the text for its
messages. In most cases this should be blank to indicate to use the same
Connection
database as used for the product itself.

Messages Language
LANG
The default language to use for the messages. The valid language pack
should be installed. The default is ENG (this language pack is automatically
installed at all sites).
Send SOAP Fault as
SEH5
System
Enter Y to ensure that a SOAP error is reported as an HTTP 500 "internal

server error". Enter N to report the actual error as the SOAP Fault.
HTTP 500
Error
JDBC
SEJC
execution several times. The MPL registers the system error in a table and
Connection
uses this table for the retries. This setting specifies the JDBC connection
required to access this table. Only enter a value in this field if it is different
from the database environment used to read the XAI registry.
XAI Log File Management

The XAI component features a number of logs that provide developers and administrators
debugging information. The locations and names of these logs are customizable for a site. The
installation process creates default names and locations of these files. In most cases they do not
need to be altered.
The logging settings are configured from the Admin X XAI Options menu option on the
browser user interface of the product. The table below lists the settings that affect security:
TABLE 46 LOG RELATED CONFIGURATIONSETTINGS
OPTION
XAI_OPTION_FLG
COMMENT
MPL Log File
MLOG
The MPL Log File setting is used to specify the name of the file where MPL log
information is to be written. The log contains technical information about the
operation of the MPL such as connection status and connection issues.
MPL Trace File
MTRF
The MPL Trace File setting is used to specify the name of the file where MPL
trace information is to be written. This log contains information about individual
transactions that have been accepted by the MPL and/or transactions that have
been initiated by the MPL. This trace file is typically used by developers or
during the initial configuration process to check that the transactions are working
as expected.
MPL Trace Type
MTRT
The MPL Trace Type is used to enable or disable tracing of the MPL. The
90
OPTION
XAI_OPTION_FLG
COMMENT
possible values are FULL - All trace messages are written to the log file and
NOLOG - No information is written to the log file. This can be overridden at
runtime using the XAI Command facility. Refer to "MPL Administration" for more
details.
XAI Trace File
XTRF
The full path name for the file, where the XML messages should be written. This
trace file is typically used by developers or during the initial configuration
process to check that the transactions are working as expected within XAI. A log
viewer is provided with the XAI Schema Editor Client to post-process this trace
file.
XAI Trace Type
XTRT
Use this option to specify the level of logging. The possible values are FULL - All
XML messages are written to the log file and NOLOG No information is written
to the log file. This can be overridden at runtime using the XAI Command
facility. Refer to "MPL Administration" for more details.
Refer to the "Technical Best Practices for Oracle Utilities Application Framework based
products" for advice on managing the number and rotation of logs.
Note: All XAI Server related error messages and commands are logged to the spl_xai.log located in the
$SPLSYSTEMLOGS (or %SPLSYSTEMLOGS%) directory. Refer to the Operations and Configuration
Guides for your product on the format and log management capabilities of the Oracle Utilities Application
Framework.
MPL Thread Pooling

When the MPL processes a message it uses a thread to perform the execution of creating and
formatting the message. These threads are pooled for performance reasons and are shared across
messages to be processed. The size of the thread pool will depend on the amount of work the
MPL needs to complete at any time. If there are too few threads available, then messages will
wait for an available thread causing delays in the transaction completion. If there are too many
threads then there is inefficient memory and processing usage for the MPL. The ideal
configuration is to have a constant minimum number of threads with the necessary thread
growth for peak periods.
The thread pool size used for the MPL is a configurable option to allow specification of the
initial size of the pool, the maximum size (to prevent too many threads overwhelming the
system) and a non-activity timeout to reduce the size of the pool back to its minimum when the
peak load has subsided.
There size of the thread pool is influenced by number of concurrent messages to be processed by
the MPL at any point of time. This includes volume from every XAI Sender and XAI Receiver at
any point in time. It is also influenced by the time each transaction takes. For example, if there is
an estimate of 100 messages per second (from the sum of all the XAI Senders and XAI Receivers
at any time) it would sound logical to allow for 100 threads but if each transaction takes on
91
average half a second then the MPL would only have 50 threads active at any time. This is a
simple example as the variations of transaction times across all XAI Senders and XAI Receivers
can vary considerably from one time to another. Typically, sites choose an average transaction
time and use that to help determine the minimum and maximum pool sizes.
To help determine the appropriate settings for your site, use the following guidelines:
During testing cycles, enable the tracing for the MPL and XAI. This will allow you to
capture the average execution times for each transaction that your site uses.
Determine the average, best and worst times for the transactions based on the data. The
Log Viewer provided with the XAI Schema Editor Client can be used to help you post
process the trace information.
Depending on the risk level your site, use the best, average or worst times 4 as a
multiplication factor on the expected overall volume of messages expected to be
processed by the MPL. Remember to include traffic from all XAI Senders and XAI
Receivers (including internal staging XAI Senders and XAI Receivers). You want to
reduce the load to a figure of expected number of messages per second (another time
interval can be used but seconds are the most common).
Discuss the peak period with your business, they will give you a rough (or a very
detailed) indicator how much more traffic is expected at peak times. This can be
converted into a multiplier against the minimum to determine your maximum.
When implementing these values, monitor the MPL to see if the values are working as
expected. If not, you can adjust the values as needed.
Note: Changing the MPL Thread Pool size requires a restart of the MPL.
The thread pool settings pertaining to the MPL are configured from the Admin X XAI
relevant settings:
TABLE 47 MPL THREAD POOL RELATED CONFIGURATIONSETTINGS
OPTION
Thread
Size
Pool
Initial
XAI_OPTION_FLG
COMMENT
TPIS
The MPL uses a thread of pools to enhance performance. The MPL starts with a
minimum number of threads and grows/shrinks the pool based on the MPL
system load. This option specifies the initial number of threads in the thread
4 Low risk tolerance uses the highest value; High risk tolerance uses the lowest value. If in doubt, use
either the average value or the highest value.
92
OPTION
XAI_OPTION_FLG
COMMENT
pool. The default minimum number of threads is 12.

Thread Pool Max Size
TPMS
This option specifies the maximum number of threads in the thread pool.
Thread
TPNA
This option specifies how long a thread in the pool may be inactive before it is
Pool
Non
timed out and released from the pool. The default is usually sufficient but may
Activity Time
be adjust according to your expected Service Level Targets.
Outbound Messages Configuration Options

Note: Refer to the "Configuring Outbound Messages" section of this document and the online documentation for a
more detailed description of the Outgoing Message functionality.
The Outbound Message component of XAI can be configured at the global level for specific
functionality.
Whenever an error in the Outbound Message infrastructure occurs the relevant part of the
business needs to be informed to take some action to remedy the error from a business
perspective. The Oracle Utilities Application Framework provides a To Do facility which informs
the relevant part of the business (in the form of a customizable To Do list) that some action is
required. To configure this action a To Do Type must be provided that is used to inform the
business of Outbound Messages that have not completed successfully. This will inform the
relevant part of the business (the To Do Type is attached to the relevant individuals as part of the
security process).
As part of the Outbound Message infrastructure an Outbound Message may be validated against
an external schema for compliance checking before sending to the destination. This is an
optional facility that is configured on individual Outbound Message Types as part of the External
System configuration. This facility can be enabled or disabled globally as part of the
configuration process 5.
The Outbound Message To Do Type and global schema validation settings configured from the
below lists the settings pertaining to these facilities:
TABLE 48 OUTBOUND MESSAGE RELATED CONFIGURATIONSETTINGS
OPTION
To
Do
Outbound
Type
for
Message
XAI_OPTION_FLG
COMMENT
TODO
To Do type for outbound message errors. The outbound message receiver uses
this To Do type when creating To Do entries for outbound messages that
It is expected that in Production the facility is enabled if the schemas are used. The ability to enable
or disable schema validation globally is usually restricted to development or testing use only.
93
OPTION
XAI_OPTION_FLG
COMMENT
cannot be successfully processed. The system provides the To Do type F1-
Errors
OUTMS that may be used here

Schema Validation Flag
XCHK
Enter Y to turn on schema validation for outbound messages. Enter N to turn

this off.
Note: Changing these settings requires a restart of the MPL and a refresh of the XAI cache.
XAI Administration
The XAI component can be managed using various operational commands. These commands
can query information or affect operational aspects of the XAI Server and MPL at runtime.
Currently, the commands can only be sent from the browser user interface provided with the
product.
At installation time the administrator specifies a unique administration port numbers per
environment for the MPL and the XAI Server 6. These port numbers are used by the product
command line utilities to start and stop the MPL and XAI Server. These ports are also used by
the browser command option to administer the XAI Server and MPL.
Whilst the MPL Administration port is specified at installation time, it must be manually
configured to use the browser user interface. The MPL Administration port specification for the
browser command function can be configured from the Admin X XAI Options menu
option on the browser user interface of the product. The table below lists the setting that
specifies the MPL Administration Port for use with the browser administration function:
TABLE 49 MPL RELATED CONFIGURATIONSETTINGS
OPTION
XAI_OPTION_FLG
COMMENT
MPL Administrator Port
ADPO
The port number to be used for receiving MPL operator commands. This must
match the value of the MPLADMINPORT parameter from the ENVIRON.INI
located in the $SPLEBASE/etc (or %SPLEBASE%\etc) directory
Once the administration ports have been configured a suitably authorized user can administrate
the XAI component using the Admin X XAI Options menu option on the browser user
interface of the product. The table below lists the commands that can be sent to the XAI
components:
The XAI Server administration port, for command options, is actually the HTTP Port allocated by
the Web Application Server at installation time. Other administration ports are used for Web
Application Server administration.
94
TABLE 50 XAI COMMANDS

XAI COMMAND
COMMENT
Display Registry
Use this command to display the current registry information that the XAI instance is
XAI
MPL
running with.
MPL
Refresh
Executer definitions are stored in cache memory. As a result, adding or modifying

executer definitions has no effect on the runtime server. Use this command to refresh
Executer
executer definitions. You are prompted to indicate the executer to refresh.

MPL
Refresh
Receiver definitions are stored in cache memory. As a result, adding or modifying

receiver definitions has no effect on the runtime server. Use this command to refresh
Receiver
receiver definitions. You are prompted to indicate the receiver to refresh.

MPL
Refresh
Sender definitions are stored in cache memory. As a result, adding or modifying

sender definitions has no effect on the runtime server. Use this command to refresh
Sender
sender definitions. You are prompted to indicate the sender to refresh.

MPL
Start
Use this command to start a particular receiver. You are prompted to indicate the
Receiver
receiver to start.
MPL Stop
Use this command to stop all MPL activity. It stops all receivers and waits for all
executers and senders to complete.

MPL
Stop
Use this command to stop a particular receiver. You are prompted to indicate the
Receiver
receiver to stop.
MPL Trace Off
Use this command to stop the MPL server trace.
MPL Trace On
Use this command to start the MPL server trace.
Refresh
This is related to an attribute in the schema editor where you may indicate that the
Code
and Description
description of a control table code should be returned along with the code itself. This
information is kept in cache memory in the server. As a result, changes made to
descriptions have no effect on the runtime server. This command clears the cache of
control table codes and descriptions accessed by the server. Refer to "How to Create
Code Description Attributes" On the online documentation for more information.
Refresh
The registry contents are kept in cache memory in the server. As a result, making
Registry
changes to the registry control tables has no effect on the runtime server. Use this
command to refresh the contents of the registry cache with the new values in the
registry control tables. The command reloads all registry control table data into the
server.
Refresh
Schema definitions are stored in cache memory on the XAI server. As a result,
Schema
modifying a schema definition has no effect on the runtime server. To refresh schema
definitions, use the Refresh Schemas command.

Refresh Service
Service definitions are stored in cache memory on the XAI server.
As a result,
modifying an XAI inbound service definition has no effect on the runtime server. To
refresh service definitions, use the Refresh Service command. You are prompted to
indicate which service to refresh.
Refresh XSL
XSL Transformation script definitions are stored in cache memory on the XAI server.
As a result, modifying an XSL transformation definition has no effect on the runtime
95
XAI COMMAND
COMMENT
XAI
MPL
server. To refresh XSL transformation definitions, use the Refresh XSL command.
Trace Off
Use this command to stop the XAI server trace.
Trace On
Use this command to start the XAI server trace.
XAI Trace Clear
Use this command to clear the contents of the trace file.
XAI Trace Swap
Use this command to rename the current trace file by appending the date and time to
the end. A new trace file is then created with the name as defined in the XAI option
page.
Legend: Component can accept command. XAI XAI Server can accept command, MPL MPL can accept command.
The Send button on the XAI Command Screen will initiate the command.
Note: If the command is to be sent to the MPL as well then ensure the URL in the dialog is correct for the URL
on your machine as well as the port number.
The results of the commands will displayed in the dialog. The top part of the screen is reserved
for the output from the XAI Server and the bottom part of the screen is reserved for the MPL.
In some cases only the command sent is shown (depending on the command). All command
requests are logged in the relevant log.
Activating and Deactivating Services

One of the operations that operations personnel may perform is to enable or disable a specific
XAI Inbound Service. This can occur for a number of reasons:
The service definition is not complete and the developer may not want to release an
incomplete service definition.
An operator may want to manually enable or disable a real-time (HTTP) interface. If the
interface uses the MPL, then there are other options outlined in "Activating and
Deactivating Receivers".
The service is to be retired but the definition needs to be retained for auditing purposes.
The Admin X XAI Inbound Service menu option on the browser user interface of the
product has a status flag ("Active") on the definition. By toggling this flag on or off the Service
can be enabled or disabled, respectively after a cache refresh is performed on the XAI Server.
The state of the service in the XAI Server runtime can be determined by executing the "Display
Registry" XAI command from Admin X XAI Command menu option on the browser user
interface of the product and examining the output for the service information.
Activating and Deactivating Receivers

One of the operations that operations personnel may perform is to enable or disable a specific
XAI Receiver. This can occur for a number of reasons:
96
The XAI Receiver definition is not complete and the developer may not want to release
an incomplete definition.
An operator may want to manually enable or disable a near real-time interface.
The XAI Receiver is to be retired but the definition needs to be retained for auditing
purposes.
The state of XAI Receiver can be manually manipulated within the MPL using the following
commands, outlined in the table below, in the Admin X XAI Command menu option on the
browser user interface of the product.
TABLE 51 MPL XAI RECEIVER COMMANDS
XAI COMMAND
COMMENT
MPL Start Receiver
Use this command to start a particular receiver. You are prompted to indicate the receiver to
start.
MPL Stop Receiver
Use this command to stop a particular receiver. You are prompted to indicate the receiver to
stop.
The state of the XAI Receiver in the MPL runtime can be determined by executing the "Display
Registry" XAI command sent to the MPL from Admin X XAI Command menu option on
the browser user interface of the product and examining the output for the XAI Receiver
information.
Note: It is not possible to manually start or stop a XAI Sender as the sender requires data to be sent to it. By
stopping the relevant XAI Receivers (including internal ones), effectively stops the XAI Sender.
Receiver Best Practices

While setting up XAI Receivers is straightforward there are a number of practices to help
optimize the settings and avoid common configuration mistakes. The following guidelines should
be considered when creating XAI Receivers for your site:
The XAI Receiver Id is a tag used by the XAI components to identify the XAI Receiver
in the Registry. The identifier used does not impact the technical aspects of the product
but the name used should be meaningful for the interface it is used for and prefixed
with CM to avoid conflicts with base provided information.
The Description assigned to the XAI Receiver may seem an annoyance at first but
summarizing the use of the XAI Receiver can help other people identify it quickly.
Ensure that the Context values for the XAI Class selected are correct for the XAI
Receiver. Invalid values can cause connection failures and unnecessary processing
errors.
Avoid duplicate XAI Receivers. While you cannot create a XAI Receiver with the same
Receiver Id you can create Receivers with the same configuration. While it is acceptable
97
during the development to experiment with different XAI Receiver configurations, the
production configuration should be rationalized to save maintenance effort.
Avoid dummy XAI Receivers. Some implementations have created ghost Receivers that
refer to resources that are empty most of the time and are only needed in an ad-hoc
fashion. An example of this is the File Scan Receiver based XAI Receivers. If a file is a
one off import of data using the MPL then it is more efficient to use the XAI Staging
Control method of initiating the input rather than creating a XAI File Scan Receiver for
it. XAI Receivers in the MPL are constantly polled, according to their configuration.
This takes time for the MPL to connect and check the source. Avoiding unnecessary
XAI Receiver definitions can reduce resource wastage.
Think about what you want to do with responses generated by XAI Receivers. If you
want to track the information consider using the XAI staging Sender to store a record of
the transaction in XAI Staging. This makes the transaction traceable from the business
perspective.
You can send a response from an XAI Receiver to multiple destinations. This may seem
like a good idea but can complicate a configuration unnecessarily. Consider each
destination carefully in relation to the other. A common mistake is to choose a XAI
Sender which is not appropriate. For example, it may seem logical to send an email as
part of a transaction but if the XAI Senders sends hundreds or thousands of messages
in emails then this may not be as efficient as it first seems.
Sender Best Practices

While setting up XAI Sender is straightforward there are a number of practices to help optimize
the settings and avoid common configuration mistakes. The following guidelines should be
considered when creating XAI Senders for your site:
The XAI Sender Id is a tag used by the XAI components to identify the XAI Sender in
the Registry. The identifier used does not impact the technical aspects of the product
but the name used should be meaningful for the interface it is used for and prefixed
with CM to avoid conflicts with base provided information.
The Description assigned to the XAI Sender may seem an annoyance at first but
summarizing the use of the XAI Sender can help avoid selecting the wrong receivers in
related configuration (such as on the Response configuration for an XAI Receiver or in
an External System configuration).
Ensure that the Context values for the XAI Class selected are correct for the XAI
Sender. Invalid values can cause connection failures and unnecessary processing errors.
Avoid duplicate XAI Sender. While you cannot create a XAI Sender with the same
Sender Id you can create Senders with the same configuration. While it is acceptable
98
during the development to experiment with different XAI Sender configurations, the
production configuration should be rationalized to save maintenance effort.
Files Processing Best Practices

The XAI File Scan Receiver, XML File Receiver and XAI File Sender are powerful features of
the MPL. It is a common mistake to think that they should be used for all file based interface
replacing the traditional batch loading and unload of data. They do have their place but they are
not the solution for your entire file interfacing needs.
The XAI file based Senders and Receivers are designed for small trickle based interfaces where
the file formats are relatively simple. They usually expect a common transaction structures in the
file and are not recommended for transfers of records over several thousand (this can be reduced to
a smaller amount for more complex objects such as Case or Fact). To format a file into a complex format
(with multiple formatted records etc) can be quite a complex XSL task and not considered
optimal.
The XAI file based approach should be considered alongside the more traditional batch
processing aspects of interfacing. The batch processing is becoming more and more considered
as legacy but that is not doing the paradigm justice. Certainly batch processing is programmatic
over the configuration focus of XAI but operationally batch is more integration with the rest of
the multi-object operations of the product.
Background processing (a.k.a. Batch) is an integral component of the product line and having all
your key interfaces cross linked, in a background scheduler, is far more efficient that trying to
initiate XAI transactions as part of a batch scheduler (most scheduler cannot handle Web
Services let along communicate with SOA based platforms some can but not easily).
Consider XAI file based approaches where is appropriate for smaller trickle feed interfaces and
Batch for large, regularly scheduled interfaces.
Overriding the XAI Options using Adhoc Parameters

By default, the XAI Servlet and MPL read the XAI Options parameters from the database at
startup time. This means that the values must be configured using the online system for each
environment. It is possible to override these XAI Options using a Adhoc Parameters in the
XAIParameterInfo.xml and MPLParameterInfo.xml files for the XAI Servlet and
MPL respectively.
To use this facility the XAIParameterInfo.xml and MPLParameterInfo.xml files
must be manually altered (or custom templates for XAIParameterInfo.xml.template
and MPLParameterInfo.xml.template must be created) to add a new section. With
the following format:
99
<Option name="<Code of XAI Option>" value="<desired

value>" />
Where
<Code of XAI Option>
XAI_OPTION_FLG value from the query:

SELECT x.xai_option_flg,
l.descr
FROM ci_xai_option x,
ci_lookup_val_l l
WHERE l.FIELD_NAME = 'XAI_OPTION_FLG'
AND l.FIELD_VALUE = x.XAI_OPTION_FLG
AND l.LANGUAGE_CD = '<language>';
Where <language> is the desired language code. ENG is

the default. See previous sections for value of
XAI_OPTION_FLG.
<desired value>
Value desired for the parameter.
For example:
<XAIParamaterInfo>
<AdhocParameters>
<Option name="SUSR"
value="fred@oracle.com,wilma@oracle.com" />
</AdhocParameters>
</XAIParamaterInfo>
Note: The example above is for XAIParameter.xml but applies to MPLParameterInfo.xml
as well.
JAAS Based Security
Note: This feature is only available in sites using Oracle Utilities Application Framework version 4.0 and above
.
In Oracle Utilities Application Framework Version 2.2 and below, the XAI servlet used an
adjunct call to the classicxai servlet to ensure web services based calls were authenticated
correctly. Whenever WS-Security headers or security was included in the HTTP Headers were
encountered the xaiserver servlet would pass the credentials in a ping request to verify the
credentials. In most cases this was not a performance hit but in large volume web services
transactions it starts to become noticeable.
To address this an Java Authentication and Authorization Service (JAAS) call has been
introduced to provide a more efficient and standard approach, replacing the adjunct call. The
configuration of this call is automatically provided with the product and no additional
configuration. The JAAS configuration consists of a number of additional settings in the
spl.properties file as shown in the table below:
100
TABLE 52 JAAS CONFIGURATIONSETTINGS

PARAMETER
COMMENT
spl.jaas.subject.className
JAAS implementation class provided by J2EE Web Application Server. By

default the values are as shown below:
Oracle WebLogic: weblogic.security.Security

IBM WebSphere/ND:
com.ibm.websphere.security.auth.WSSubject
spl.jaas.subject.methodName
Method supported by the JAAS classes provided by the J2EE Web

Application Server. Valid Values:
spl.jaas.security.realm
Oracle WebLogic: runAs
IBM WebSphere/ND: doAs
Default realm. Value: jaasRealm
Note: Do not alter these values unless instructed by Oracle Support.

When implemented the JAAS authentication works by providing a security based filter, parsing
the security credentials, as outlined in the flowchart described below:
101
HTTP
Request
Yes
WSDL Based?
No
1
No
Has credentials in
SOAP Header
Yes
2
Yes
No
Authenticated by
server?
JAAS Login
3
Yes
HTTP Authorization
header?
No
4
Return a 401
(Not Authorized)
JAAS Login
Authenticated by
JAAS?
No
Yes
Return a 500
(Internal Server
Error)
Yes
Wrap HTTP
Request to pass
Principal and
remote user
Authenticated by
JAAS?
No
Return a 401
(Not Authorized)
Wrap HTTP
Request to pass
Principal and
remote user
XAI
Servlet
Figure 22 Web Service Authentication Processing Flow
1.
If the request is WSDL based (such as getting WSDL definitions or UDDI calls) then
the JAAS is invoked directly using the provided credentials.
2.
If the request is not WSDL based the presence of SOAP credentials is checked within
the request. The presence of SOAP based credentials implies WS-Security otherwise
HTTP Header Basic Digest Authentication is assumed.
3.
If the request is HTTP Header Basic Digest Authentication is used, then a check is
performed to see if the request has previous been authenticated by the J2EE Web
Application Server. This check is performed to save on processing as past security
102
credentials are cached by the J2EE Web Application Server to provide more efficient
access.
4.
If the HTTP header does not contain authentication information, as it should, then
return the standard HTTP 401 error code. Otherwise if the header does contain
authentication information perform a JAAS call to verify the user internally.
5.
If the JAAS authentication is successful then wrap the request in the verified credentials
and call the XAI Servlet with the verified credentials. If the authentication is
unsuccessful then issue a standard HTTP 401 error code.
6.
If the credentials use SOAP based security (i.e. WS-Security) then use those credentials
in a JAAS call to verify the user internally. If the JAAS authentication is successful then
wrap the request in the verified credentials and call the XAI Servlet with the verified
credentials. If the authentication is unsuccessful then issue a standard HTTP 401 error
code.
This facility replaces the XAI Options to specify the security preferences for the site as the
content of the incoming request dictates what security is used. This allows a site to migrate from
one security flavor to another or use mixed security flavors.
Support of Effective User

Note: This feature is only available in sites using Oracle Utilities Application Framework version 4.0 and above
.
One of the integration options at a site is where the credentials from the calling system are
different from the called system. For example, the site may have a number of systems that share
data with their own security requirements and may not have any overlap in users.
To allow a calling application to identify itself to XAI using alternative credentials the setting of
effectiveUserId and/or effectiveUser when invoking an XAI service is now
supported. This means that the user that the calling application can be used within the header but
an effective userid and/or user can be passed in the header. For example:
The effectiveUser is used for long userids (Login Id) and the effectiverUserId is
used for userid matches (short 8 character userid). Generally either effectiveUser or
103
effectiveUserId is provided not both. If both are provided in the call the
effectiveUser takes precedence over effectiveUserId.
Note: effectiveUser and effectiveUserId can only exist in the SOAP header not the
HTTP Header.
To use this facility the userid passed from the calling system must be defined in the Privileged Users
option on the XAI Options screen. The Privileged User option is a comma delimited list of users
that are authorized to use this facility.
If the user list is extensive, then consider using Adhoc parameters to override the XAI Options
in the XAIParameterInfo.xml and/or MPLParameterInfo.xml files. The example
below illustrates a simple Adhoc parameter used for
<XAIParamaterInfo>
<AdhocParameters>
<Option name="SUSR" value="<list of users>" />
</AdhocParameters>
</XAIParamaterInfo>
Refer to the online documentation for more information about this facility.
104
XAI Best Practices

April 2010
Author: Anthony Shorten, Principal Product
Manager, Tax And Utilities Global Business Unit
Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.
Copyright 2009, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and
the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other
warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or
fitness for a particular purpose. We specifically disclaim any liability with respect to this document and no contractual obligations are
formed either directly or indirectly by this document. This document may not be reproduced or transmitted in any form or by any
means, electronic or mechanical, for any purpose, without our prior written permission.
Worldwide Inquiries:
Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective
Phone: +1.650.506.7000
owners.
Fax: +1.650.506.7200
oracle.com
0109

XAI Best Practices

Uploaded by

Copyright:

Available Formats

XAI Best Practices

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

XAI Best Practices

Uploaded by

Copyright:

Available Formats

An Oracle White Paper

XAI Best Practices

XAI Best Practices Oracle Utilities Application Framework

XAI Best Practices Oracle Utilities Application Framework

Configuring a File based input ..................................................... 33

XAI Best Practices Oracle Utilities Application Framework

JDBC Pooling .............................................................................. 87

XAI Best Practices Oracle Utilities Application Framework

Conventions used in this document

XAI Best Practices Oracle Utilities Application Framework

Figure 1 - Overview of XML Application Integration

The XAI component is made up of a number of parts:

XAI Client An optional Software Development Kit to build XML Schemas

XAI Best Practices Oracle Utilities Application Framework

XAI Best Practices Oracle Utilities Application Framework

Database It is possible to poll an external database table to load data. This

XAI Best Practices Oracle Utilities Application Framework

SMTP Server (Email) It is possible to send emails from the product to an

Web Server (HTTP) It is possible to send data to an existing Web

LDAP Import It is possible to import security information from an LDAP

Oracle Utilities Application Framework

Figure 2 Detailed View of XAI

XAI Best Practices Oracle Utilities Application Framework

Maintenance Objects versus Configuration Objects

XML Standards - Maintenance Objects are XML attribute based, whereas

XAI Best Practices Oracle Utilities Application Framework

Never send a response (i.e. ignore responses).

Send a response if the request was successful

Send a response if the request was unsuccessful due to a system error

Send a response if the request was unsuccessful due to an application error

XAI Best Practices Oracle Utilities Application Framework

This is a short description of the receiver used for documentation purposes.

Reserved for future use

Reserved for future use

XAI Best Practices Oracle Utilities Application Framework

XAI Best Practices Oracle Utilities Application Framework

Configuring XAI Senders

This is a short description of the sender used for documentation purposes.

MPL This sender is managed and executed by the MPL.

JMS Queue/ XAI

XAI Maintenance Object Based Services

XAI Best Practices Oracle Utilities Application Framework

Installing and Configuring the XAI Schema Editor

Generation of Schemas from base services.

Figure 3 - Installing and Configuring the XAI Schema Editor Client

The Database client software for Windows should be installed. It is highly

Install the development version of the product according to the Installation

XAI Best Practices Oracle Utilities Application Framework

Setup an ODBC connection to your nominated development environment. This should

Schema Directory Directory or share where the schemas generated will be

MetaInfo Directory Directory or share where the base product schemas

XAI Servlet URL The URL of the development environment referencing

Default Account Id Default product account id used for testing account

XAI Best Practices Oracle Utilities Application Framework

Language The Language to be used for messages and processing. The

Defining a Maintenance Object Based Schema

XAI Best Practices Oracle Utilities Application Framework

Verify Configuration - Optionally, it is recommended to check your preferences are set

Schema Directory This should be set to the directory or share on the

MetaInfo Directory This should be set to the directory or share on the