OUAF Integration Guidelines

An Oracle White Paper
July 2013
Integration Guidelines
Oracle Utilities Application Framework
Oracle Utilities Application Framework - Integration Guidelines
Introduction ......................................................................................... 2
Conventions used in this whitepaper .............................................. 2
Integration Techniques ........................................................................ 3
Summary of techniques available ................................................... 3
Important Integration Considerations .................................................. 5
Degree of Coupling of Integration ................................................... 5
Volume Considerations ................................................................... 7
Initiation of Integration ..................................................................... 7
Client Interfacing ................................................................................. 8
Screen Population (a.k.a. Screen Pop) ........................................... 8
Client User Exit ............................................................................. 13
URL Characteristic ........................................................................ 18
Navigation Key .............................................................................. 20
Web Application Server Interfacing ................................................... 25
XML Application Integration (XAI) ................................................. 26
Business Application Server Interfacing ............................................ 32
Multi-purpose Listener/SOA Suite ................................................. 33
Message Driven Beans (MDB)
........................................... 37
Algorithms ..................................................................................... 37
Batch Staging Upload ................................................................... 41
Batch Staging Download ............................................................... 44
Server Side User Exit .................................................................... 46
Database Server Interfacing ............................................................. 48
Structure Query Language ............................................................ 48
Stored Procedures ........................................................................ 50
Triggers ......................................................................................... 52
Introduction
Note: This document only covers products that utilize the Oracle Utilities application framework. Implementation of the
techniques discussed may vary from product to product. Refer to the documentation provided with the product for specific
advice.
One of the key activities in any implementation is the ability to define interface or integration between
the product you are implementing and other products or applications used within a site's portfolio.
Therefore, understanding what integration points exist within the application framework is critical for
getting data in and out of products using application framework.
This whitepaper will outline the techniques that are available with the application framework and offer advice to which
techniques are appropriate in which situations.
Note: The case studies discussed in this document are not exhaustive examples of the potential of the interface technique,
but an attempt to illustrate the techniques possibilities.
Note: This document does not cover technology integrations to a large extent. Other whitepapers exist or are planned for
specific technology integration guidelines.
Note: For publishing purposes, the word "product" will be used to be denote all Oracle Utilities application framework
based products.
Conventions used in this whitepaper

The advice in this document applies to any 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.
Framework V4.2 based products and above. Service Packs are indicated by
,
etc
Integration Techniques
When integrating using the application framework, there are a number of techniques that can be used
for extracting and placing data in a product that uses the application framework. The application
framework is flexible in the number of techniques that are available but the key to success is to pick the
most appropriate integration technique best suited for your design.
This document will attempt to outline the common techniques available and their attributes for
integration. It is hoped that armed with this information, architects and designers will be able to choose
the appropriate integration method for the integration challenge put before them.
Summary of techniques available

The application framework, used by a number of products, exposes a number of integration points that
are designed to be flexible, open and retain upgradeability across versions of the product. These
integration points were designed to provide a number of supported avenues where implementation
teams can safely integrate third party applications (or components) without the need for changes to the
base package.
The diagram below illustrates all the techniques available for the application framework to interface in
and out of the framework:
Interface In
Interface Out
Screen Populate
Client User Exit
Client
URL Characteristic
Navigation Key
XAI
Web Application
Server
Algorithm
SOA Suite/MPL
Business
Application
Server
SOA Suite/MPL
Server User Exit
Batch Staging Upload
Batch Staging Download
SQL
Stored Procedure
Database
Server
Triggers
Figure 1 Overview of the integration techniques available.
Screen Populate The ability to pop open a screen from an external application.
Client User Exit The ability to alter the Browser User Interface (BUI) enough to call an
external application or component and have data returned to data fields on a screen.
URL Characteristic The ability to store a URL in a characteristic have the BUI launch a
viewer application to view the information referenced by the URL.
Navigation Key The ability to add a reference to an external web based application from a
menu and jump point.
XML Application Integration (XAI) The ability to send and receive data from any object
using an XML request.
Algorithm The ability to call an external application (using various methods) from a
predetermined component in a business process.
Multi-Purpose Listener (Or Oracle SOA Suite) The ability to send and receive
information asynchronously from various sources and destinations using the service bus.
Note: The Multi-Purpose Listener is only available for specific products. Refer to your product documentation
for clarification.
Batch Staging Upload The ability to load files of data into a staging area for regular
processing and input into the main tables of the system.
Batch Staging Download The ability to extract data from the system, driven by staging
tables, for interfacing to file based systems.
Server Side User Exit The ability to add code at strategic points in the product, not
covered by algorithms, to interface to another application or component.
SQL The ability to execute SQL against the database directly to query and extract
information.
Stored Procedure (or similar) The ability to use a stored procedure to interface to the
complex table structure for reporting or security authorization model.
Triggers (or similar) The ability to use a trigger to initiate an interface.
The subsequent sections will outline the various techniques and their merits for particular integration
scenarios.
Important Integration Considerations

Before discussing the techniques available, there are some important design considerations that must
be factored into any integration design.
One of the major design decisions that have to be made is whether the external application is coupled
as part of the call and what to do when the external application is not there.
Degree of Coupling of Integration

Note: This section is not an in-depth debate on the merits of point to point or middleware based solutions. It is up to the
site standards and practices in deciding which strategy should be used.
One of the major debates in integration is the degree applications should be coupled. This argument has
many names point to point versus middleware oriented integration or real time versus near real time.
This issue is complicated with performance and availability concerns at their core.
A tightly coupled set of applications (a.k.a. point to point) is optimal in terms of performance with real
time integration. This was seen as the traditional method of integration. The issue is when the called
application is NOT responding or is not there at all. At worst, the end user gets an error message,
which indicates that the interface is not available. If the information is not critical to the business
process then the probably the business process can proceed, but if the information is critical to the
business process, it is unclear the next steps. The figure below illustrates point to point integration.
Calling
Called
Application A
Application B
Figure 2 Point to point integration example.
Many people address availability by either introducing high availability and in some cases middleware.
In Middleware Oriented Integration, the applications are loosely coupled and the middleware takes the
responsibility of delivery of the request to the called application when it is available. In some cases it
will queue the information waiting for the called application. When the called application is available the
middleware will deliver the request in as near real time as possible with the technology. Middleware
oriented integration is perceived to be lesser in performance to point to point (as there are extra layers to
traverse) but higher in availability. When the called application is not available it will notify the calling
application and either queue the request for future processing or produce an error. The diagram below
illustrates middleware oriented integration:
Calling
Middleware
Application A
Called
Application B
Figure 3 Middleware orientated integration example.
The key fact that must be considered in any integration design is:
In your designs, if you are using a point to point integration technique then you must consider
the impact to the business process if the external application or component is not available.
The design will have to include what to do in this fact.
In your designs, if you are using a middleware oriented integration technique, you still must also
decide what to do with if the external application or component is not there AND you must
also decide what to do if the request is delayed and the response comes back later.
For the application framework, each technique a coupling mode is used that represents the default
integration typically used within implementations. With the exception of the MPL, Batch Upload
Staging and Batch Download Staging all the techniques use point to point as their default behavior. It
is possible to convert the technique to use middleware depending on the technology used for the
integration (for example, java can use most middleware solutions) and if the external application
supports the middleware.
Volume Considerations
One of the important considerations when designing integration is the volume of the integration.
While all the integration techniques can handle volumes of transaction some are more sensitive than
others.
When designing with volume in mind consider the following when designing:
When using point to point solutions, the key to high volume transaction management is
having enough resource allocated to satisfy the volume. Typically this means connection pools
(client and database), the number of JVM's and memory have to be sufficient to handle the
load. Refer to the Technical Best Practices for guidelines on JVM and memory usage.
If the product is using the Multi-Purpose Listener (MPL), then the provided file scan receivers
are not designed to be replacing the Batch Upload Staging technique for extremely high
volume transactions. While it is possible to recreate the staging technique using the MPL the
high volumes can cause high contention. Refer to the techniques for individual advice. Using
Batch Staging or Oracle SOA Suite as a replacement for the MPL will address this situation.
Note: Oracle Utilities Application Framework V4.2.0.1.0

and above, supplies a set of Oracle Service
Bus adapters for Outbound Messages and Notification/Workflow to replace the MPL functionality. Refer to Oracle
Service Bus Integration Oracle Utilities Application Framework (Doc Id: 1558279.1).
Initiation of Integration
When designing for integration one of the key indicators of which techniques to use is the layer it is
going to be initiated from and the degree of interaction with end users.
If the integration is based upon human initiation rather than system initiation then there will be certain
integration techniques that are more applicable than others (i.e. client interfacing techniques). For
example, the integration where the end users need to initiate will probably negate most of the back end
server integration options. Where the integration needs to be hidden or requires no direct human
interaction, then the back office integration is more appropriate (i.e. Web Application Server, Business
Application Server and Database Integration).
Client Interfacing
When considering integration, some implementations look at integration from user interface to user
interface. This is typically used where the end users need to interact with the other applications or get
the other applications interface to integrate with products utilizing the application framework.
The key to the integration is the ability for both the application framework to call external applications
using a supported method and being able to open (a.k.a. pop) a screen in the product displaying the
necessary data.
The figure below illustrates the various techniques for an external application to interface into the
application framework as well as the various techniques the application framework offers to call an
external application from the user interface:
Interface In
IVR
Interface Out
Screen Populate
Client User Exit
Client
URL Characteristic
Navigation Key
Web
Application
Web
Application
Figure 4 Client integrations.
Each of the techniques illustrated in the diagram will be discussed in subsequent subsections.
Screen Population (a.k.a. Screen Pop)

One of the key integration techniques used in an implementation is the ability to start a product screen,
passing some data to pre-populate the screen. For example, call centers typically use a Computer
Telephony Integration (CTI) application to screen, route calls and accept calls. There may be a
requirement as part of the call initiation to automatically open a screen from the product as the cell
center agent is accepting the call.
To perform this integration the following is assumed:
The calling application can build and open a Universal Resource Locator (URL) (in the form
required by the application framework) for the browser to display.
The calling application can pass security credentials if required to prevent additional logon
requests.
The calling application has the necessary context key values from the product. For example, to
open the Account Page the account number needs to be provided to get the data to display
the page. Typically CTI software gets information using responses from an Interactive Voice
Response (IVR) or Caller Line Identification (CLI) component.
This technique is used where there is end user interaction (from the calling application) and is not
volume related (as it is typically included in traffic volume calculations).
What needs to be done?
To open a screen housed with the framework the following process needs to be done:
The URL of the screen needs to be built by the calling application using available
configuration data.
The URL is in the format:
http://<host>:<port>/<server>/cis.jsp?location=<navoption>&<key>=<val>
&portal=true
Where:
<host>
Hostname (or IP Address) of the Web Application server (or load

balancer) where product is deployed.
<port>
Port Number allocated to Web Application Server (or load balancer)

where the desired environment for the product is deployed.
<server>
Web Server Context
<navoption>
Navigation Option assigned to screen to open at startup
<key>
Context Key name used to delimit key fields
<val>
Value of Context Key field you wish to display. Text values must be
enclosed with double quotes.
&portal=true
Used for calling ConfigTools based style portals, zones and UI Maps
Note: For screens where there are multiple context keys then separate <key>=<val> clauses are added to
the end of the URL delimited with &.
For example the following URL will display Account 10596870 on the Account Page.
http://localhost:1000/testing/cis.jsp?location=accountMaint&ACCT_ID=10596870
The calling application will have to open this URL (i.e. the supported browser). Additionally
the application needs to pass the security credentials. There are two methods of performing
this action:
The calling application must provide a HTTP 1.1 header containing basic digest
authentication (default method) in the HTTP header authorization fields. Refer to
http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html for information on this
standard.
The implementation may use a single sign-on solution, which can be delegated to
provide the credentials. Refer to the documentation provided by your single sign-on
vendor.
If the credentials are not provided, then an additional logon to the application
framework, imposed by the Web Application Server software, may be experienced.
If the URL is correct and the security is provided, if required, then the appropriate screen within the
product should be displayed.
Considerations when using this technique
While this technique is relatively straightforward, there are a number of considerations that must be
taken into account when designing for this technique:
The interface is one way As the BUI is browser based, this technique only allows an
external application to start a screen, passing appropriate context. The browser does not
automatically pass control or data back to the CTI client software. This is deemed the
responsibility of the CTI client software.
There is no detection of the end of the call The integration does not automatically
provide information to detect when the transaction is complete, as the customer service
representative may perform many tasks during the duration of the call. Typically the customer
service representative, using the facilities provided by the CTI client software, does this type
of processing manually.
There is limited possibility of populating screen information While technically

possible; there is a limitation to passing additional information apart from the context fields
indicated. If additional fields need to be populated then investigating using custom navigation
options may be need to be considered.
New or old style screens If the target screen is using ConfigTools based portals, zones or
UI Maps then the portal=true option must be added to the calling URL.
Note: If you are unsure of whether the screen called is using ConfigTools or not, it is recommended to try the
test the call with and without the portal=true option to see which option is applicable.
Finding the location and context fields
10
The values for the location and context keys components of the URL are stored in metadata managed
by the application framework. To find the values use the following process:
Open a browser to a copy of the product.
From the Admin Menu, select N Navigation Option
Search for the screen by screen name:
Figure 5 Example navigation key search dialog.
The location can be determined from the Navigation Option and the context keys from
the Field name in the Context Fields section as shown in the example illustrated below:
Figure 6 Example navigation key.
In the above example, the location is f1Request and the context field is REQ_ID.
Note: As the record is owned by Framework it cannot be altered according to the rules governing record
ownership.
Case Study: CTI Integration
11
A common implementation of this technique is in the integration of Computer Telephony Integration

(CTI) between the site's telephone infrastructure and the relevant product.
The common process is as following:
A customer calls the call center and based upon some rules is identified. This identification
can vary from using the phone number used or getting the customer to enter their Account
Number on the phone.
Once the customer has been accepted by the phone system then if required the customer is
identified within the system. Typically this type of call is performed using the XAI component
(refer to the XML Application Integration section of this document for more information).
There are a number of specific XAI services available to use for a customer to be identified
(see CTI/IVR Integration documentation provided with the product for details of the calls
available). At this point the customer's account number should be available.
Typically, based upon rules within the telephony infrastructure the call is routed to the
appropriate available call center representative. Typically the call center personnel have a piece
of software, provided by the CIT vendor, which interfaces to the telephony infrastructure.
Typically this is known as a CTI client.
The customer service representative accepts the call using the facilities provided by the CTI
client.
The CTI client will compose the appropriate URL and initiate a call to the browser to open
the appropriate product screen. This call can be as simple as a URL call (for more recent CTI
clients) to also using an ActiveX client (for legacy CTI clients). There is a set of infrastructure
available with the CTI integration that can be used and is documented in the CTI/IVR
Integration documentation provided with the product.
If the URL is correct and the appropriate security credentials are provided then the
appropriate screen will be popped up for the customer service representative to work from.
At the end of the transaction the customer service representative either shuts down the
browser that has been started and/or completes the call in the CTI client.
The following figure summarizes the processing discussed above:
12
Product
(Application Server)
Product
XAI
URL
IVR/CTI
CTI ActiveX
CTI Client
Customer
Calls
Determine
Account
Call
Routing
Call
Acceptance
Pop into
screen
Figure 7 Example CTI Integration
Client User Exit

One of the facilities of the Oracle Utilities Software Development Kit (SDK) is the ability to build
client user exits. These are pieces of Java Server Page (JSP) code that alters the behavior of the Browser
User Interface (BUI). At runtime the JSP based client side user exit is included in the screen definition,
which can alter the look and behavior of the base screens. The figure below illustrates an example:
13
Original
New
Client Side
User Exit
Figure 8 Example Client User exit example (from a customer) modifying the product premise screen.
This facility allows developers to alter the look and feel of individual pages to hide fields, move fields
around and add new fields to screens to suit site standards. This also allows the developer to call
external applications and return data to fields.
This technique is useful where user interaction is required from the Browser User Interface, typically
initiated by the end users or the result needs to be verified by end users. It should not be used if the
call needs to be made on each update, as this will become inefficient.
From an integration point of view, the client side user exit JSP can contain valid interface code and
take data from the existing screen and pass it to other application and return the results back to the
screen elements. The JSP must have the following elements:
14
Code to recognize that the interface needs to be initiated, such as an additional button (for
user initiation) or a reaction to a change event, such as altering a field value (for automatic
initiation).
Code to determine the location of the external application. There is a developer standard,
within the product that no hard coding exists in the code. To adhere to this principal it is
recommended that the location of an interface be recorded in the product using Feature
Configuration. For more information see Defining Feature Configurations under General
Options within the online help.
Code to initiate the interface using the protocols supported by the external application.
Commonly HTTP POST is used.
Code to take the output back from the external application into the screen fields.
Details of JSP client side user exits are contained in the Oracle Utilities SDK documentation under
Development Process and Cookbook. Numerous examples are also outlined the documentation and in
the cm_templates directory of the product.
To use this technique the following process needs to be performed:
The name of the user exit filename needs to be determined. Typically the name is of the
format ext_<screenname>.jsp where <screenname> is the name of the screen
from the metadata that is generated by the application framework. Refer to Finding the name
of the User Exit include file name for a screen for details.
The JSP client side user exit has to be coded according to the standards outlined in the Oracle
Utilities SDK.
Note: Remember to use Feature Configuration to record the location of the external system to avoid hard coding
values.
The JSP client side user exit needs to be deployed in the cm directory of the product as
outlined in the packaging standards outlined in the Oracle Utilities SDK.
While this technique is flexible the following considerations need to be factored into any design using
this technique:
You are limited to the JSP language - While the language is comprehensive, there may be
some code constructs that you cannot model in JSP required by the external application. Refer
to the external application documentation for details.
You are limited to the screen real estate available - To ensure maximum usability, you
should be aware that you are restricted in what you can alter due to screen real estate.
15
Do not introduce any unacceptable code - While the JSP is powerful, misuse can cause
performance bottlenecks and security violations (i.e. areas where security exploits can be
introduced). If the external application requires an Active X control for example, this may
introduce additional maintenance overhead.
You are constrained to the application framework model to access and display data The application framework is flexible but you are constrained by the calls available from the
JSP to screen objects. Refer to the Oracle Utilities SDK for details of any limitations.
Ensure that you make any screen changes in the same style as the Browser UI is using
- Introducing any changes in the screens through client side user exits should conform the
usability standards outlined in the Oracle Utilities SDK to maximize use and avoid confusion.
Any screen manipulations should look natural.
Finding the name of the User Exit include file name for a screen
To code the JSP client side user exit, the name of the JSP file for the particular page needs to be
determined. This information can be determined by displaying the screen you wish to enter and using
the View Source/View Page Source right click menu option as shown below:
Internet Explorer
Mozilla Firefox
Figure 9 Browser View Source option
In the code that is displayed you will see the name of the required client side user exit by searching for
the text ext_. The text "/cm/ext not found" may appear which indicates the filename for the
user exit file.
Note: The text display is a note only. It is not an error message. It only indicates that there is current client user exit file
available for this screen.
Note: If the user exit already exists, then the message not found will not be displayed.
The following is an example of the message:
16
Figure 10 Example View Source for User Maintenance Page
Once the client user exit is coded and deployed it will be included in the screen definition when loaded.
Case Study: Address Formatting and Validation
One of the interesting uses of this technique is the ability to integrate an address validation server into
the Browser User Interface. In some countries the post office will offer a service or data that contains
valid addresses for efficient delivery of mail. Additionally some post offices offer additional
information such as bar codes to make mail sorting more efficient.
In the case study, the customer purchased some address validation software from a third party supplier
authorized to supply validated addresses for the country. The software was web based and could be
called via a URL, that would also pass back the validated address and bar code that can be registered
for any correspondence.
Note: The bar code was provided as a number NOT a barcode image. This number can be used to generate the
appropriate barcode with the relevant supported font.
The client user exit was coded to perform the following:
The fields on the screen were re-arranged according to the site standards.
A button to initiate the call was added to the screen. It was decided that it was more efficient
that the call would be performed at user request rather than overloading the server if the call
was performed at every update.
17
When the button was pressed, the URL for the validation server, determined at run time, was
called. This would open a browser popup window that was provided by the address validation
software.
The user would use the address validation software to find the address and once satisfied the
information selected would be passed back to the product screen. The popup screen is closed
as part of this process.
Note: This popup screen was provided as part of the address validation server.
The values from the call would be populated into the relevant fields on the screen.
The customer service representative saves the information.
The figure below illustrates this process:

Address
Validation
Server
Product
URL
Java
Client Side User Exit
CSR Initiates
Address
Check
Client
User Exit
Initiates Call
Client Side User Exit
Validate
Address
Pass Data
Back to
screen
Figure 11 Case Study for Client Side User Exit to call Address Validation Server
Note: In the above case study a number of user exits where introduced as addresses appear in more than one place in the
product. To minimize maintenance there was a common set of code referred to by each user exit.
URL Characteristic
One of the easiest point-to-point integration techniques is to store a link to an external object within a
characteristic on an object. This technique involves storing a URL to the location of the object in a
URL in a characteristic of type File Location Value. The user can then click the icon to view the
resource referred to in the URL.
This technique is valid for any valid URL provided that the following is adhered to:
18
The URL must refer to a server or location available to all users from their desktop. For
example, the resource cannot be on the local machine as that resource is not available
universally.
The URL must be stored in the format supported by the browser. Refer to
http://www.w3.org/Addressing/ and the browser vendor's site for more information.
The viewer for the resourced by the URL must be installed on the local machine. For example,
if the URL refers to a PDF file then a PDF viewer needs to be available on the machine to
view the document. Failure to have a viewer for the resource will result in a request to the user
to download the resource to their machine, which may not be desirable.
To use this technique the following needs to be done:
A characteristic type needs to be created of type File Location Type using the Administration
menu, C Characteristic Type menu item.
The characteristic type needs to be attached to the relevant entities.
The URL characteristic need to be entered against the relevant records using some of the
techniques outlined in this document or manually by users.
Refer to the relevant online documentation for more information.

While this technique is flexible the following considerations need to be factored into any design using
this technique:
Static URL - The technique is basically the launching of a URL that is stored in the database
and associated with an object. The URL is basic and static. Anything beyond that may require
additional integration work. If the URL is dynamic or requires additional authentication, then
this technique must be combined with a client side user exit to code the additional effort to
launch the URL correctly.
URL must be in correct format and must be accessible - There are no limitations with the
technique itself, as the URL loading is recognized as a standard across the industries.
Therefore the advice is to ensure the URL is correct, points to accessible resource and the
viewer for the target is available to the end user.
Case Study: Document Repository
One of the scenarios for this technique is the integration with a document repository. For example, the
site might want to attach copies of contracts and correspondence to objects for perusal.
19
For this scenario to work, it is assumed that the required documents are stored on a shared accessible
resource somewhere (e.g. a file server) and that the information has been loaded using some interface
already (such as a staging upload or as part of another technique in this document).
Once the URLs are populated the end users simply click on the icon next to the URL to launch the
document viewer (in this case study's case, it was Microsoft Word or Adobe PDF Viewer). The figure
below illustrates the case study:
URL
CSR Initiates
View
Document
Retrieved
from Server
Document
Displayed in
Pop window
Figure 12 Case Study for URL Characteristic
Navigation Key
One of the lesser-used techniques is the ability to call an external application from a menu, go-to or
context menu. This allows a URL to be defined as a menu item or on a particular context menu (as
shown the example below) to allow the user to transfer control to another application momentarily.
Figure 13 Example context menu
To use this technique the first step is to decide whether the call is going to be a menu, go-to or a
context menu. What's the difference?
A menu item is displayed in the menu (the Main or Admin menu) on the left of the screen. A
example is shown below:
20
Figure 14 Example menu and menu item
A context menu is attached to a particular data item on the screen and passes the id of that
field as part of the invocation. This is useful for targeting particular items. For example, this is
the maintenance context menu, which is available from anywhere a maintenance object is
displayed:
Figure 15 Example context menu item
A go-to is a context menu with one item. Basically, clicking on the go-to button will navigate
to the appropriate URL without displaying a menu. For example, this is a go-to from the User
Group Maintenance transaction to the Service transaction.
Figure 16 Example Go To menu item
21
Once the decision has been made then the URL needs to be defined to the configuration to enable the
menu item using the following process:
A navigation key containing the URL must be defined. This is done using the Administration
menu, N Navigation Key menu item. Refer to the online Framework Help on the various
options that are applicable to your URL. An example of a definition is shown below:
Figure 17 Example sample Navigation Key
Note: For security, an Application Server must be defined to attach to user groups. If this is omitted, then all
users will have access to the menu item.
Note: By specifying an External the application framework will open a separate window. This is desirable
behavior for this technique.
A navigation option needs to be added. This is done using the Administration menu, N
Navigation Option menu item. Refer to the online Framework Help on the various options that
are applicable to your integration. You will link the navigation key created in the previous step
as the Target Transaction. The Usage section outlines whether the item is a menu and/or
context menu. An example is shown below:
Figure 18 Example sample Navigation Option
22
To decide which menu or submenu you must add a menu entry with the appropriate type.
This is done using the Administration menu, M Menu option. Refer to the online Framework
Help on the various options that are applicable to your integration. The Navigation Option
created in the last step is attached to the menu item. An example is shown below:
Figure 19 Example sample Menu
The menu items need to be flushed to reflect the change. The new menu item should then
appear:
Figure 20 Example Menu shown
Whilst this technique is simple and can allow other applications to be called from the menu there are a
few considerations to be aware of:
Context on Navigation cannot be used for external calls - At the present release there is
no simple way of passing context to the URL. There are context fields within the Navigation
Option but they currently only apply to internal calls. To pass context, this technique would
have to be combined with a JSP based Client Side User Exit.
New browser window opened - The URL call will open a new window (unless the URL has
additional parameters to control the window behavior). This may not be desirable behavior.
Case Study: Changing Passwords
Note: Typically it is not the responsibility for Oracle Utilities Application Framework based products to manage users
passwords. It is the responsibility of the security repository configured at the Web Application Server to maintain
passwords. This example is provided for illustrative purposes only.
23
One of the most common requests involving this technique is the ability for the site to ad a password
change dialog to the product. The idea is that an end user can maintain their password to the product
from within the product.
This technique is used as the end point of the integration but a custom JSP must be written to allow
the user to specify their current password and a new password (at least twice). The custom JSP then
needs to call a native API provide by the security vendor used t hold the information or provide by the
Web Application Server vendor to implement the password change.
Typically each site that implements the product has a different authentication configuration.
Exclusively the Web Application Server software itself, not the product, handles authentication. Each
Web Application Server or Security vendor provides an API (usually a JMX or java class) that allows a
third party application to manipulate security information safely. Refer to your vendor's site for details
of any sample password change dialogs with JMX or java classes.
To implement the password change JSP the following is performed:
The password change JSP has to be placed in the cm directory of the Application using the
utilities provide with the Oracle Utilities SDK.
A navigation key specifying the URL of the jsp must be created.
A navigation option, referring to the navigation key, must be created.
A menu, context menu or go-to must be altered or added to place the password functionality
in an accessible place.
This example is shown below:
URL
CSR Initiates
Menu Item
Custom JSP
Is Displayed
Figure 21 Example Change Password example
Refer to the Technical Best Practices document for more advice around implementing change
password functionality in the product.
24
Web Application Server Interfacing

The integration that is fast being the most popular between the application framework and externally
applications and components is interfacing with the Web Application Server directly using Web
Services. The prospect of being able to access any of the supplied maintenance objects 1 in an interface
is one of the compelling reasons to integrate at this level. Much of the new integration technologies,
such as Web Services are making integration easier and more functionally rich.
This layer of integration is not restricted to traditional point to point synchronous integration but also
supporting asynchronous methods, which adds to the shift towards this layer of technology. The
flexibility of being able to deliver integration on a number of technologies depending on the frequency
of the integration and the technology available means that architects are not really burdened on
specifics technical solutions and can offer a range of options.
Integration at the Web Application Server comes at a price though:
Traffic generated by any integration must be included in any sizing calculations, as it will
compete for resources from online users. Some sites separate the traffic from the integration
from call center traffic, using separate servers, to minimize impacts.
Security must be propagated from the calling application to ensure authentication rules are
adhered to.
Constraints built into the maintenance objects can seem limiting but can be cater for in careful
designing.
external application from the Web Application Server:
1 The term maintenance objects generically refers to any service based objects used for maintenance, lists and
searching.
25
Web
Application
Interface In
XAI
Web Application
Server
Mobile
Application
Figure 22 Example Change Password example
XML Application Integration (XAI)

One of the newer technologies, percolating throughout the industry and commercial applications is the
ability to support XML. The format has permeated various industries and slowly, is becoming a
standard mechanism of communication between applications.
As an integration mechanism there are lots of advantages to using XML:
It is a standard way of sharing structured data.
It is cross platform and vendor neutral standard.
It is a web oriented universal syntax.
It separates the contents from the presentation.
It contains self-describing information.
In response to the fact that XML is fast becoming a preferred method of communication, the XML
Application Integration (XAI) component was introduced into the application framework. This
component consists of three parts:
XAI Server A J2EE application collocated with products that processes XML requests from
HTTP sources and responds with XML.
Multi-Purpose Listener An Enterprise Service Bus that listens to a number of predefined

sources of information and sends that information to the XAI Server for processing. This part
26
is outlined in another section of this document. This is covered in the Business Application
Server Integration section of this document.
Note: Not all products can use the MPL. For products not using the MPL should substitute components of
the Oracle SOA Suite in place of the MPL.
XAI Client A developers tools for defining request and response schemas for relevant
incoming services.
From integration point of view the application (or technology) interfaces to the product through XAI
by:
Sending an XML Request document to the XAI Server directly using a HTTP Post. The
request document format is defined in a schema that is generated by the XAI client and is
registered within the XAI Registry. The XAI Registry is a set of tables within the application
framework database.
The XAI Server calls the necessary maintenance objects directly, as defined in the XAI
Registry for that transaction.
The maintenance object returns the data to XAI, which is then formatted into the necessary
XML Response. The response document format is defined in a schema that is generated by
the XAI client and is registered within the XAI Registry.
The biggest advantage of XAI is that an application can have access to all base services (all
maintenance, lists and searches) as well as any custom services that are defined for the implementation.
The diagram below summarizes the basic processing used with XAI:
Request XML
XML
Compliant
Application
XML
HTTP
XAI
Product
XML
Response XML
Figure 23 Summary of XAI
Advanced Configuration Environment objects
In past versions of the product, the concept of Business Objects, Business Services and Service Scripts
were introduced, along with other new object types, as part of the Advanced Configuration
27
Environment tools. Whilst these are built on Maintenance Objects or Data Objects they are views on
these object types with a defined schema and inbuilt translation.
These object types can be exposed as a XAI Incoming Web Service by simply defining them using the
Business Adaptor. Business Objects, Business Services and Service Scripts with the defined schema used
as the API by the service.
To use XAI for integration the following needs to be performed:
The services that need to be used for the interface need to be determined. There are a number
of techniques available to do this but basically they hinge on the need to identify the screens
within the product that have the required functionality and determining the underlying object
that is used.
If the service is Maintenance object based the following additional steps are required:
A request schema needs to be built, based on the relevant underlying service, using
the XAI Client. This becomes the specification for the data to be input into the call
from the external application. The schema can be altered to rename tags, remove
fields not required etc. Additionally the request schema can be exposed as Web
Service via WSDL for consumption in SOA infrastructure.
A response schema needs to be built, based on the relevant underlying service, using
the XAI Client. This becomes the specification for the data to be output to the
external application from the product. The schema can be altered to rename tags,
remove fields not required etc. If a response schema is not used then the relevant
parts of the request schema are reused. Additionally the response schema can be
exposed as Web Service via WSDL for consumption in SOA infrastructure.
If the format of the Response and request is in a different XML format than available
or in a non-XML format then some translation may be required. Using an
appropriate third party tool, an XSL script will have to be generated or written to
perform the translation.
An Incoming XAI service is defined to the XAI Registry using the Browser User interface to
register the service name. If the service is Maintenance object based then the request schema,
response schema and any XSL files used to translate the schemas for the transaction. If the
service is Advanced Configuration Environment based, then register the relevant Business
Object, Business Service or Service Script.
After the registration of the service the XAI Registry is cleared from the runtime cache to
reload the new definitions.
28
XAI is extremely powerful and flexible but there are a few considerations you need to be aware of
when designing any interface using the technique:
HTTP/HTTPS support - You are limited to the HTTP or HTTPS protocol for real time
integration. This may not be possible from the external application.
Security in HTTP header - The security credentials must be passed in the HTTP header
(a.k.a. HTTP Basic/Digest Access Authentication and WS-Security) propagated from the
external application or hard coded by the external application in the interface. Failure to pass
the security will cause a HTTP standard 401 error (i.e. Unauthorized). This security is used for
authentication and authorization so the user needs to be defined to both the security store
configured on the Web Application Server and within the authorization tables.
SOAP Support - The XML request used for the call must be wrapped in a SOAP 1.1
compliant envelope. SOAP is used by XAI to determine service naming.
Error Message format - Any error messages returned from XAI are in SOAP Fault format
and use the message categories, message numbers and error text from the application
framework. It is the responsibility of the external application to translate error messages into
appropriate values understandable by the external application.
Case Study: A generic Web Self Service
One of the common implementation used of XAI is to implement a Web Self Service portal for the
site. The site requires a presence on their external. Web site to all
The Web Self Service is an example of an external application using XAI to interface to the product
services. The interface was built using the following integration effort:
The functionality that was commonly expected of a Web Self Service application for a utility
were determined and the relevant product services identified to provide the functionality.
Request and Response schemas were generated for the identified product services and
registered within the product for use.
The schemas were used to determine the screen elements that were built to a generic browser
user interface. Additionally any framework code was included.
The schemas, user interface and framework were bundled into the Web Self Service
Application.
At runtime the end customer, uses the utilities web site to use Web Self Service. When they use Web
Self Service, the User Interface uses the Web Self Service framework to translate the request into the
format of the Request Schema for the relevant XAI Incoming Service for that transaction. This is
transported to the backend product XAI Server instance where it is processed and the response sent
back, through the relevant levels, to Web Self Service, to display to the end customer. The diagram
below illustrates this processing:
29
With the advent of SOA, XAI can be used to provide the Web Services interface to SOA Suite
products.
Case Study: Integrating to BPEL
Note: Please refer to the Oracle SOA Suite Integration whitepaper for details of integration with Oracle BPEL and
other Oracle SOA Suite components.
One of the new integration areas is Service Oriented Architecture (SOA) integration. One of the
common components of the SOA is the Business Process Execution Language Server (BPEL Server).
BPEL is a standard XML format for representing a business process, which is made up of a number of
constructs including calling external applications as part of a business process.
Implementing Business Processes within BPEL allows cross product business processes to be
implemented and controlled outside the individual applications participating in a process. Individual
applications can initiate the business process using the Web Services interface. Application framework
based applications can use the integration technique outlined in Algorithms.
XAI can fit into a BPEL solution easily using the Web Services extension to XAI. As part of the
schema generation the schema is usually stored as a W3C format schema. Additionally it can be further
processed to produce a Web Services Definition Language (WSDL) definition. WSDL is the building
block of Web Services.
When an XAI service is generated as a WSDL definition, it then can be imported into a BPEL
development tool, such as JDeveloper, to be included as a component in any Business Process. This
means that any of the product services can be used in any BPEL process once the WSDL is available.
The process to integrate is as follows:
The Services required from the product are to be built and defined as XAI Inbound Services.
This will yield a library of services available for use in any BPEL process.
The WSDL for any XAI Inbound Service can be generated using the URL:
http://<host>:<port>/<server>/XAIApp/xaiserver/<servicename>?WSDL
Where <servicename> is the name of the registered XAI Inbound Service.
Optionally, it is possible to extract the registry (discover) to a UDDI server using the URL
from the UDDI server:
http://<host>:<port>/<server>/XAIApp/xaiserver?WSDL
The following diagram illustrates this concept:
30
XAI
XAI
OUAF product
Discovery
UDDI Server
Web Services IDE
Register
Discover
Use
Figure 24 Web Services Integration
The BPEL Designer is used to build a business process using the XAI WSDL as components
on their own or with other components from other applications.
The BPEL process is deployed to a BPEL Server (or SOA Suite) for initiation.
Note: The WSDL standard, hard codes the end point for the service. You may want to override the address at
deployment time using dynamic end point assignment (refer to the Oracle SOA Suite documentation for a
discussion of this concept).
The diagram below illustrates the process of integration with BPEL:
31
JDeveloper
UDDI Server
WSDL
WSDL
BPEL Process
Server
XML
XML
Application
Initiates
BPEL Process
BPEL Server
Initiates
Process
XAI
OUAF product
XAI Calls
Business
Objects
Figure 25 XAI Integration with BPEL server
Business Application Server Interfacing

In the architecture of the application framework the Business Application Server is a logical
component that is attached to the Web Application Server (for online and XAI) and a standalone
version of the application framework (for Batch). Even though the layer is logical it has a role to play
in a number of integration scenarios.
From an integration point of view typically integration at this level is in three scenarios:
Load data from external sources into Staging areas for processing using a background process.
Calling an internal module to perform a custom calculation or business logic.
Extract data from the product to an external target using Staging areas as guidance via a
background process.
Adding interface logic to a business object in a place NOT covered by an algorithm.
32
Application
Interface Out
Interface In
Process X

MDB
MPL/SOA Suite
JMS/AQ
File
Server User Exit
Business
Application
Server
Database
Batch Staging Dwnload
Process X
Algorithm
MPL/SOA Suite
JMS/AQ
File
Web Server
Email
Server
Figure 26 Business Application Server Integration
Multi-purpose Listener/SOA Suite

Note: The Multi-purpose Listener is only available for Oracle Utilities Customer Care And Billing and Oracle
Enterprise Taxation and Process Management customers. Oracle SOA Suite is recommended for all products as an
alternative to the Multi-Purpose Listener.
While XAI can be used for real time integration, there may be a need for asynchronous integration.
The site can use the Multi-Purpose Listener (MPL), if provided, or Oracle SOA Suite to provide
integration. The table below illustrates the channels available for Oracle SOA Suite 2 and the MPL:
TABLE 1 TYPICAL CHANNELS
CHANNEL
ORACLE SOA SUITE
ADF-BC
Business Activity Monitor
Database Input
MPL
COMMENTS
Inbound and Outbound
Oracle SOA Suite includes updates
The Adapters listed for Oracle SOA Suite are the ones provided with base Oracle SOA Suite. Additional
adapters are available from Oracle or third party providers. Refer to Oracle Integration Adapters for a full
list.
2
33
CHANNEL
ORACLE SOA SUITE
MPL
COMMENTS
Database Output
Direct Binding
EJB Service
Email
Output only
File
FTP
HTTP
Oracle SOA Suite via Socket Adapter
JMS
Inbound and Outbound. Also supports any JMS
Oracle SOA Suite includes updates
compliant provider such as Oracle AQ,

WebLogic JMS, IBM WebSphere MQ etc.
LDAP
Oracle Identity Management Suite is used

instead of Oracle SOA Suite. MPL is import
only, replaced by batch job in Oracle Utilities
Application Framework 4.1 and above.
Oracle Applications
Oracle B2B
Web Service
For a discussion of the MPL, please refer to the MPL Best Practices whitepaper. For the rest of this
section, the Oracle SOA Suite integration will be discussed.
Note: In Oracle Utilities Application Framework V4.1 real time JMS outbound integration was introduced which can
be used as an alternative to both the MPL and Oracle SOA Suite JMS integration, if desired. Refer to the Oracle
WebLogic JMS Integration whitepaper for more details.
Note: The Oracle SOA Suite Integration whitepaper outlines the techniques discussed in this section along with
additional advice. Please refer to this whitepaper for more details.
To use this technique the following must be performed:
The XAI Inbound Services needed for the interface must be registered prior to their use. To
enable the services you must either refresh the registry or restart the product.
Import the XAI Inbound Services using the Oracle SOA Suite Web Services Adapter within
Oracle JDeveloper or Oracle Enterprise Pack for Eclipse.
Incorporate the Web Service into an appropriate BPEL orchestration.
Assign the appropriate data to the invocation of the service.
Deploy the BPEL orchestration to an Oracle SOA Suite instance.
The figure below illustrates a simple Oracle BPEL flow:
34
Product User
Maintenance
XAI Inbound Service
Figure 27 Example integration with Oracle BPEL
Considerations of using this technique
When using Oracle SOA Suite to integrate to the Oracle Utilities Application Framework the following
considerations apply:
When processing data from sources where more than one record at a time, limit the flow to
processing a record at a time. This reduces the complexity of the processing. These are known
as Flow Filters.
When defining an Oracle Utilities Application Framework based web service to Oracle SOA
Suite, the credentials for the web service call to use must be specified somehow. The
credentials may be attached as a WS Policy (recommended) or propagated from the calling
application. Ensure the credentials used match the authentication within the desired security
store and authorization setup within the product.
35
The XAI Inbound Service schema includes a transactionType attribute that denotes
the type of transaction the call is attempting to make. This value can be defaulted from the
XAI Inbound Service definition or overridden at runtime. Refer to the XAI Best Practices
whitepaper for more details of the valid values for this attribute.
Case Study: Rebilling wrongly billed customers
One of the interesting case studies involving the SOA Suite was a customer who wanted to rebill part
of their billing window. A customer reported that approximately 1,000 of the 10,000 they billed each
night were billed incorrectly due to an incorrectly configured rate.
To rebill the customers there was a number of options:
Reverse out the whole billing run, correct the rate and rerun billing. This was an extreme
option and given that 10% of the customers were only affected it was not a good option to
consider.
Manually rebill the customers using Customer Service Representatives (CSR). This would
involve taking CSR's off the active call center to perform this task. This is not an ideal option
as it may reduce the operational efficiency of the call center overall.
Use the SOA Suite (BPEL)/XAI to rebill the customers. This is the option chosen.
To accomplish this solution the following process was used:
The service to rebill was determined including the data required for the service. This service
was built using a Business Object and registered as a XAI Inbound Service. This will be
imported into BPEL using the Web Service Adapter.
The accounts to be rebilled were identified and placed in a CSV file (using Excel).
A BPEL process was created to load the CSV file and call the service. The following was in
the BPEL process:
The File Adapter was used to read the file one record at a time. The CSV file was
used a sample to build an input schema.
For each record on the CSV file, the input record elements were assigned to the
input the Web Service to perform the rebill.
The output of the Web Service is monitored to see if any failures occur.
The identified accounts were rebilled with any billing failures identified within the BPEL logs.
The following diagram illustrates the scenario:
36
WSDL
BPEL
CSV
Identification
of customers
to rebill
Transfer file
to location
XAI
Initiate file
processing
OUAF
Product
XAI Calls
Business
Objects
Figure 28 Rebill case study
Message Driven Beans (MDB)

Note: This technique can be used instead of Oracle SOA Suite JMS integration if desired.
In Oracle Utilities Application Framework V4.1, message driven beans (MDB) were introduced to
provide a native JMS inbound transaction capability. These message driven beans are configured to
listen to JMS queues to process inbound transactions. For more information about this technique refer
to the Oracle WebLogic JMS Integration whitepaper that outlines the configuration steps necessary to
use this technique.
Note: This technique is also available for Oracle Utilities Application Framework V2.2 customers by installing the
patches outlined in the Oracle WebLogic JMS Integration whitepaper. This can replace the MPL JMS integration.
Algorithms
One of the most common customizations in products that use the application framework is the
implementation of Algorithms (a.k.a. plugins). Algorithms are code that is called within specific objects
that are commonly modified by implementations. For example, when the system performs a deposit
calculation, it calls a provided algorithm to perform the calculation. If the site wants to perform a
different calculation they can either alter the parameters sent to the base algorithm or write a new
algorithm. The latter would involve some coding and configuration to tell the application framework to
use the new code.
37
Algorithms are flexible and allow the implementation to influence the behavior of the product at
common points in the processing. Typically as part of an implementation the team will decide what
base algorithms will be used and what additional algorithms are required for the site.
Algorithms can be written in a variety of technologies such as COBOL, Java and Service Side scripting.
From an integration point of view, it is possible in those languages to call an external component or
external application to include data in an object or as part of a calculation.
To use an algorithm for use as an integration technique the following must be performed:
The Algorithm must be coded and deployed according the guidelines and tools outlined in the
ORACLE Utilities SDK documentation. It can be coded in Java or using Server Side
Scripting. The last two are preferential for algorithm longevity. The algorithm code must
include the code to integrate to the external component or application using the facilities
provide by the external entity and the constraints of the language used.
An algorithm type must be added into the meta-data to define the code component of the
algorithm (program type and name) and which algorithm entity it is associated with (i.e. where
in the object it will be called). To enter an algorithm type you must use the Administration menu
A Algorithm Type menu entry. An example is shown below:
Figure 29 Example Algorithm Type
An algorithm entry must be added to the meta-data, which defines the instance of the
algorithm type the algorithm entity will actually use. This defines the values of the parameters
to be passed to the algorithm and may vary. This promotes reuse as you can have a number of
algorithm entries defined that can be used for specific situations. To enter an algorithm you
must use the Administration menu A Algorithm menu entry. An example is shown below:
38
Figure 30 Example Algorithm
You then must enable the algorithm within the configuration component associated with the
algorithm entity. This effectively tells the system that the algorithm is ready for use. The dialog
used will vary from algorithm entity to algorithm entity. Refer to the configuration
documentation for the application framework and the Product for details.
Whilst this technique is powerful there are a few considerations to be aware of:
Work within the language If the external application supports the call from the language
you choose to write your algorithm in, then it should be possible to call that external
application/component from the algorithm. For example, if you use Java as the language of
choice, then as long as the external application/component supports being called by Java,
then it should be possible to get the call to complete successfully.
Consider third party components/tools If the technology used by the external

application/component cannot be called directly then you may need to consider adding
additional third party integration. For example, you cannot call a Web Service directly from
Java easily, you need to have some classes to make interface easier to implement. This
example is expanded in the case study.
Universal - Once configured an algorithm can be called from ALL modes of access to
maintenance objects. This means the browser users, background processes and the XML
Application Integration component can use the algorithm.
Case Study: Calling a Web Service
Note: Refer to the Oracle SOA Suite Integration for alternative methods for calling Web Services
39
There are lots of examples of algorithms that are used within the product. The products that use the
application framework are supplied with a number of standard algorithms per algorithm type that can
be used or adapted for use. From integration point of view an example of using an algorithm is to call
an external Web Service.
Typically Web Services are housed in some Service Orientated Architecture (SOA) infrastructure that
makes the Web Service available to external parties and executes it when requested. From that
infrastructure it is possible to extract the interface to the Web Service in the form of a Web Services
Definition Language (WSDL) file. This contains the inputs and outputs to the service as well as some
location information to the service as a minimum.
Optionally, your site may maintain a repository of available Web Services in an UDDI server. Universal
Description, Discovery and Integration (UDDI) is a platform-independent, XML-based registry for
Web Services to list themselves to be discovered by interested parties wishing to use the services. It is a
method of an enterprise defining all the services it offers to all its applications to integrate with.
The following process was used to use an algorithm to call a Web Service:
Initially, to call a Web Service from Java, a definition of the Web Service must be provided to
the developer. Typically this is in the form of a WSDL file, which may be obtained directly
from the external application/component or via UDDI.
Once the WSDL is obtained the Java code can be written using a number of Java techniques
and tools such as WSIF (Web Services Invocation Framework), JAX-RPC/JAX-WS and
AXIS2. Check with your Service Orientated Architecture vendor or your site enterprise
architects for the site's preferred method. For publishing purposes, the case study will use
AXIS2.
Note: Whichever method is chosen, additional Java jar files may need to be added to the CLASSPATH for
the application framework to invoke the infrastructure correctly.
The AXIS component was used to generate the Java stub code within the ORACLE Utilities
SDK using the provided WSDL as the input. The necessary code was added to complete the
functionality required for the algorithm. For example, to pass relevant context values to the
Web Service and store the result values in object fields or characteristic values.
The algorithm was compiled and deployed on the application framework with associated
meta-data (e.g. Algorithm Type, Algorithm and Algorithm Entity configuration).
The AXIS2 runtime libraries were added to the CLASSPATH used for the application
framework Web Application Server for runtime consistency.
The Web Application Server was restarted to ensure the CLASSPATH was loaded correctly.
The algorithm was invoked using the relevant processing (online, XAI or background
processing). This would invoke the interface.
The diagram below summarizes the case study:
40
Oracle
Utilities
SDK
WSDL
AXIS 2
Deploy
OAUF
product
Algorithm
UDDI
Server
Provide
WSDL
Web Service
Application
AXIS 2
Algorithm is
invoked
Application
executes
Web Service
Figure 31 Web Service Call example

Typically the products focused on an industry have a number of key interfaces that must load data into
the system for processing. These interfaces provide the raw data from external sources to complete
some business processes. For example, loading payments from external parties (banks, post offices
etc).
Traditionally, interfaces loading data into products were custom built and loaded data into base table
for direct processing. The issue with that is after validating the input records that any records in error
would be located with the records that were successful. This has integrity and performance impacts in
the long term.
In the application framework there are a number of key incoming interfaces that have staging tables.
The Staging table is used to house ALL records loaded from the external system and using application
framework processes it is validated and any valid data passed to the relevant base tables. The loading of
the data into the staging tables is the responsibility of the implementation and can use ANY technology
that is favored by the site (e.g. database loading utilities, programs, scripts etc). This is universally
known as Process X. Typically, some Process X samples are supplied with the Oracle Utilities SDK for
templates.
41
To use this technique you must perform the following:
The external system must provide an extracted file for loading. Typically the format of this file
is also provided. If you have control over the format then consider a format as close to the
layout of the relevant staging table as possible (to save Process X coding time).
The Process X needs to be coded in an appropriate language (such as COBOL or Java) or use
an external loading tool (such as a Database Loader). Documentation in the Oracle Utilities
SDK may be useful in this respect.
The Process X is deployed in the appropriate locations with the application framework.
A Batch Control record may be created for the Process X if the background process is to be
managed using the batch control process. This is performed using the browser user interface,
using the Administration menu B Batch Control. An example is shown below:
Figure 32 Example Batch Control
The background process can be scheduled according to the scheduler that is used at the site.
When considering this technique for integration the following considerations need to be factored into a
design using this technique:
Traditional This is a traditional back office integration technique where background

processing extracts are loaded into a database. In this technique it is specifically loaded into a
set of predetermined staging tables.
Volume Independent This technique can take large volumes as well as small volumes run
more frequently.
42
File formats can be flexible The file format can be straightforward (simple load) or
complex (with control records for reconciliation). For externally managed files, this is
important, as the site may have limited scope in changing file formats (e.g. payment formats
from banks).
Cleanup queries Any data that is unsuccessful due to validation errors is marked
accordingly and can be manually reprocessed using a provided query.
Note: Refer to the Business Process documentation on the various Batch Staging Upload processes provided with the
product.
Case Study: Loading Payments from an agency
The most common example of an interface using this technique for implementation is the loading of
payment files into the system.
Sites receive remittance files from internal and/or external payment agencies. The formats of the files
sent by those agencies may vary from agency to agency as well as vary by type of payment (e.g. cash
versus credit). Typically the site will have little or no control over the format of the file.
Typically each payment agency will work with the site and outline the payment file format that is to be
used. The Process X is coded to load that payment file format into the staging table
(CI_PAY_TNDR_ST). You may need to write a number of Process X programs to load the different
payment file formats you typically experience from the various agencies.
To process payments the following process is performed:
The end customer makes payments for bills or assessments, which are accumulated in a
payment file to be transmitted to the site.
The payment files are delivered by the agency according to site standards.
Process X is executed to load the data into the staging tables.
The PUPL process is executed to process the payment staging records. Any unsuccessful
records are marked in Error.
Note: It is recommended that the staging tables be cleared of processed records on a regular basis.
The following figure illustrates the case study:
43
Internet
Payment
Payment
Staging
Upload
Intranet
Process X
Xfer
Payment File
Payment
Agency takes
payment
Payment File
transferred
To Site
PUPL
OUAF
product
Payment
Upload File
Data Loaded
Into Staging
PUPL
Job validates
and transfers
Figure 33 Example Payment Loading
Batch Staging Download

While the Batch Staging Upload, imports data from external sources into the product, typically there is
also a need to extract data from the product to provide to external sources. This is the role of the
Batch Staging Download technique.
As with the Upload process, a Process X needs to be written to provide the interface. In this case, the
Process X will read the Download Staging records and extract the appropriate information from other
maintenance objects using the data indicated in the staging records. The responsibility for populating
the download staging tables is the base product process, either natively or using one of the techniques
outlined in this document.
A number of provided extracts, included with the base product, are provided that can use as-is or
modified to suit your sites needs.
The Process X needs to be coded in an appropriate language (such as Java) or use an external
loading tool (such as a Database Loader) against the Staging Download Table as a driver.
Documentation in the Oracle Utilities SDK may be useful in this respect.
The Process X is deployed in the appropriate locations with the application framework.
Additionally, a Batch Control record may be created for the Process X if the background
process is to be managed using the batch control process. This is performed using the
browser user interface, using the Administration menu B Batch Control menu item.
44
The background process can be scheduled according to the scheduler that is used at the site.
Considerations when this technique
Traditional This is a traditional back office integration technique where background

processing extracts are provided to be loaded into external applications. In this technique the
staging table drives the extraction process.
Volume Independent This technique can support large volumes as well as small volumes
run more frequently.
File formats can be flexible The file format can be as complicated or simple as required
by the external system loading the data.
Cleanup queries Any data that is unsuccessful due to validation errors is marked
accordingly and can be manually reprocessed using a provided query.
Note: Refer to the Business Process documentation on the various Batch Staging Download processes provided with the
product.
Case Study: Extracting Meter Reads for read.
The most common example of an interface using this technique for implementation is extracting meter
reads into handheld devices.
Typically the product, in a utility site, may need to send meter read information files to meter read
devices. The formats of the files needed by the meter read software may vary from vendor to vendor.
Typically the vendor will supply an expected file format for the version of the software required.
The Process X is coded to extract the meter read file in the format using the staging table
(CI_MR_STAGE_DWN). You may need to write a number of Process X programs if you have multiple
meter read vendors with differing file formats.
To process meter reads the following process is performed:
The MSR/MDS processes are executed to identify the meter information to extract.
Process X (MDL is provided as a sample) is executed to extract the data from the staging
tables. Any records that are unable to be extracted, through some violation of a business rule
or validation, are marked for manual correction.
Note: It is recommended that the staging tables be cleared of processed records on a regular basis.
The file is transferred to the meter read group or external agency according to site standards.
The Meter read information file is loaded into the meter read application for transfer to the
meter reader's hand held devices.
45
The following diagram illustrates the case study:

OUAF
product
MDL
Intranet
Internet
Meter
Extract
Meter
Extract
Meter Read
Download
Staging
Process X
Xfer
Meter Read
Application
Meter Reader
MDL
Identifies and
Writes Staging
Data Is
Extracted in
Required Form
Meter Data
File transferred
To Site
Meter Data
Loaded into
MR Application
Figure 34 Example Meter Read Extract
Server Side User Exit

As mentioned in the Web Application Server integration section, a valid technique to use is algorithms.
The restriction with algorithms is that they only apply to specific strategic points in a business object or
business process. If there is an integration that cannot be housed in an algorithm within a business
object then you need to use a Server Side user exit.
A Server Side user exit is a piece of code that is configured to be placed in a specific part of a business
object to provide additional functionality. From an integration point of view, the code may integrate to
an external application/component to provide additional data. A Server Side user exit can be coded in
COBOL or Java.
The Server Side User Exit must be coded and deployed as outlined in the Oracle Utilities
SDK.
The metadata to enable the user exit must be entered as outlined in the Oracle Utilities SDK.
Hooking into foreign technology The application framework supports a hybrid

COBOL/Java approach for backward compatibility therefore you may have a hybrid Server
46
Side User exit (typically Java being inserted into a COBOL based object). Processes and
guidelines for this are documented in the Oracle Utilities SDK.
Java is better for user exits As Java supports multiple protocols and allows extensibility of
the base classes there is a lot more scope for extending behavior of maintenance objects.
Case Study: Calling a callable library
A generic case study that is applicable to Server Side user exits is a generic call to a component to be
included in a business object. For example, there may be a call to an external component that performs
a common calculation that is used across applications (e.g. Credit Rating).
It is assumed that the callable module resides on a resource accessible (from both a network and
security perspective) and can be called by a method supported by the technology used. In the case
study, it is assumed that the Server Side User Exit can use a WSDL (via AXIS2/JAX-RPC/JAXWS/WSIF), RMI or a raw Call to call the module.
A Server Side User Exit is written with the necessary call to pass data to and accept data from the
callable module. This call can be directly or via supported middleware layers as appropriate for your
site standards. It would be coded as outlined in the Oracle Utilities SDK and deployed using the
relevant utilities to the target environment.
At the exit point the module would be called to perform the necessary actions and the data returned to
the object for processing. The diagram below illustrates this case study:
Other
Application or
Library
OUAF
product
WSDL
Business Object
Server Side
Exit
Batch Program
Server Exit
Initiates
Call
RMI
Call
Callable
Module
Library or module
Processes and
Passes response
Figure 35 Example Module Call
47
Database Server Interfacing

One of the more traditional means of integration is at the database level. This level of integration is not
as popular as other integration methods as it is seen as the last resort and does not offer the security
and business process integration as offered by other methods. For some external applications and
some technologies in the market this is the only method that they can be called and they call other
applications.
Reporting
Server
Interface In
SQL
Interface Out
Database
Server
Stored Procedure
Trigger
Extracts
Application
Application
Business
Intelligence
Figure 36 Database integration scenarios
Structure Query Language

Note: Issuing SQL data manipulation language (DML) statements other then SELECT statements
directly against base tables can cause data integrity to be compromised and can invalidate your product
warranty. All data update access should be through maintenance objects that ensure data integrity is
maintained.
One of the most traditional methods of obtaining data from a product is to query its database directly.
This has been a valid technique, which has been used for a long time in the industry.
48
The idea is to issue valid SQL, usually SELECT statements, against a database directly to extract
information that is needed for another application. The calling application either directly embeds the
SQL in their application programs or issues it from a tool (such as SQL*Plus, SQL Developer, TOAD
etc).
To integrate at the database level using SQL the following has to be done:
The tables and views required for the interface need to be agreed.
The application has to be issued a valid database logon with appropriate access to the tables
and views. The basic installation of the application framework usually contains template users
and/or roles that can be used a basis for this user.
Optional, additional setup for the user may need to be required if the database access is
remote.
Whilst this technique is straightforward there are a few considerations to be aware of:
Security Typically this type of access requires access to all the contents of a table or view.
This does not take into account the security rules and filters implemented in the authorization
model. While some of the rules can be implemented by using views, where clauses and stored
procedures typically not all rules can be represented for complex configurations. If any
security rules are implemented in code (e.g. algorithms, user exits etc) these will not be
available from the database level.
Performance Implications Typically, SQL access is not used as integration technique as it

can adversely impact performance of all transactions if not managed correctly. Some sites
have implemented strict usage rules, custom views, materialized views and resource profiles to
minimize this.
Note: Using inappropriate SQL DML statements may result in data corruption outside the control of the product.
Case Study: Ad-hoc query tools/Reporting Tools
One of the most common uses for this technique is the integration between the product and Ad-hoc
query tools or reporting tools.
Typically, selected power users will be given limited direct access to some of the tables/views directly
to compose and execute ad-hoc queries against. Typically this is to query data in such a way not
provided natively by the product on an ad-hoc basis.
The power users (or the reporting tool) are issued with a userid and password to the database. That
user is granted SELECT access to a subset of tables or a series of custom views, which limit the data
49
accessible for security reasons. Additionally, a resource profile could be used to limit their resource
footprint.
The power user composes the SQL necessary for their query in the relevant tool and issues the SQL
against the database.
The figure below illustrates this case study:
OUAF
product
Database
Server
SQL
SQL is
composed
in tool
Database is
directly queried
Figure 37 Example SQL Access
Stored Procedures
Database vendors have allowed code to be created, stored and executed at the database level. This has
allowed powerful and flexible code to be able to be called and executed at the database level. The code
constructs vary from database vendor to database vendor.
From an integration point of view, the stored procedure can integrate to an external database or
external system (stored procedure language permitting) to get information. Stored procedures are also a
handy method of recreating some business logic so that interfacing systems can reuse business rules.
To use Stored Procedures they need to be coded and embedded in appropriate technology.
50
To implement stored procedures for interfacing:
Ascertain the programming constructs that can be used as documented by the relevant
database vendor.
Code the stored procedure in the tool instructed by the database vendor or that is the
preferred tool for your site.
Deploy the stored procedure in the database using the standards and commands provided by
the database vendor and/or tools.
Work within the limitations of the language The language used by the stored procedures
vary from vendor to vendor and may have limitations in terms of integration (for example
calling Web Services or reading files).
Profile Performance As with any programming language, bad performing code can cause
problems. During development, take advantage of the performance profiling tools that are
provided for the stored procedure language.
Case Study: Reporting Interface
As part of the product integration with reporting tools a number of stored procedures are provided so
that reporting tools can utilize some of business object code for validation. For example, the
authorization model checks are implemented in the stored procedures to take into account security
settings of the user running the report.
The reporting interface uses a number of the integration techniques:
An algorithm is provided that provides the interface to initiate a report from the product
browser user interface. This allows a user to specify the report they wish to run and the
parameters to run the report with. The algorithm uses configuration and security information
to determine if the report can be executed and where to execute it.
The report is initiated in the server of the reporting software. The reporting tool will take the
input provided in the algorithm call and schedule a report immediately or as scheduling rules
dictate.
The reporting server calls the report definition from its own repository and initiates the
report. Inside that report definition is the necessary calls to the store procedures to either
return the data for the report or validate that the user running the report can report the data
currently under validation.
51
The report is executed and is displayed to the user immediately by passing control back to the
algorithm to display the results or calling a facility within the reporting server to display the
report.
The figure below illustrates the case study:
Algorithm
URL
Reporting
Server
OUAF
product
Stored Procedure
User Submits
Report
Algorithm
Interfaces to
Reporting Server
Reporting Server
Uses Stored
Procedures
Figure 38 Example Reporting Tool Access
Triggers
One of the integration scenarios that can occur at implementations is the initiation of an interface on a
business event. For example, an interface might be only initiated if certain data is entered or changed.
Typically this can be incorporated into other techniques discussed in this document but if the change
to be tracked is at the database level, then triggers are used.
A Trigger is a database object that tells the database to execute some stored procedure or SQL when
an INSERT, UPDATE or DELETE command is executed against a specific table. The code in a trigger
can be any valid SQL statement (in some DBMS's you can also reference stored procedures).
A Trigger can be set to run BEFORE or AFTER the action has taken place. This allows flexibility in
processing the table values.
52
To use a trigger for integration purposes:
Ascertain the tables that are the trigger is to be attached to.
Code the trigger in the tool instructed by the database vendor or that is the preferred tool for
your site.
Deploy the trigger in the database using the standards and commands provided by the
database vendor and/or tools.
Performance considerations - Triggers are viewed by many DBA's as dangerous as they are
seen as hidden performance hogs. Basically a piece of poorly written trigger code may
drastically slow a perfectly performing piece of code. Consider testing the code before and
after the trigger is implemented to assess the overhead the trigger adds to the transaction
times. Remember a trigger must complete processing before control is returned to the
database or application for further processing.
Always On Triggers are always called where configured and are not conditional. Some
customers have built conditionality into the code but that only partially minimizes
performance impacts.
Case Study: Business Intelligence Extracts
One of the key case studies for triggers is in the interface between Oracle Utilities application
framework products. A great example of this is the Oracle Business Intelligence product, which takes
extracts from other Oracle Utilities products to populate its star schema.
For efficiency, the extracts only extract data that has been changed since the last extract. This is done
through triggers on the interface tables. The following processing is completed to transfer the data:
Triggers track changes on key tables and accumulate the information in the CI_CHG_LOG
table when changes occur.
At a scheduled time, to be determined during the implementation, a set of extraction

background processes are executed to extract the required data driven by the CI_CHG_LOG
table. The table is reset for the next extract.
The data extracted is passed through the transformation and load components of the Oracle
Utilities Business Intelligence product and loaded into the target database for analysis.
The diagram below illustrates this case study.
53
Oracle Business
Intelligence
OUAF
product
Database
Server
Database
Server
CI_CHG_LOG
Trigger
Trigger Writes
To Log Tables
Extracts
Extract based
Upon log tables
Transform
Load
Data is
transformed and
loaded
Figure 39 Example Trigger scenario
54
Integration Guidelines
Copyright 2007-2013, Oracle and/or its affiliates. All rights reserved. This document is provided for information purposes only and
July 2013
the contents hereof are subject to change without notice. This document is not warranted to be error-free, nor subject to any other
Author: Anthony Shorten, Principal Product
warranties or conditions, whether expressed orally or implied in law, including implied warranties and conditions of merchantability or
Manager
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
Oracle Corporation
means, electronic or mechanical, for any purpose, without our prior written permission.
World Headquarters
500 Oracle Parkway
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Redwood Shores, CA 94065

U.S.A.
Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
oracle.com
AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license
and are trademarks or registered trademarks of SPARC International, Inc. UNIX is a registered trademark licensed through X/Open
Company, Ltd. 1010

OUAF Integration Guidelines

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

OUAF Integration Guidelines

Uploaded by

Copyright:

Available Formats

An Oracle White Paper

Oracle Utilities Application Framework - Integration Guidelines

Oracle Utilities Application Framework - Integration Guidelines

Conventions used in this whitepaper

Oracle Utilities Application Framework - Integration Guidelines

Summary of techniques available

Oracle Utilities Application Framework - Integration Guidelines

Client User Exit

Batch Staging Upload

Batch Staging Download

Figure 1 Overview of the integration techniques available.

Oracle Utilities Application Framework - Integration Guidelines

Triggers (or similar) The ability to use a trigger to initiate an interface.

Important Integration Considerations

Degree of Coupling of Integration

Oracle Utilities Application Framework - Integration Guidelines

Figure 2 Point to point integration example.

Figure 3 Middleware orientated integration example.

Oracle Utilities Application Framework - Integration Guidelines

Note: Oracle Utilities Application Framework V4.2.0.1.0

Oracle Utilities Application Framework - Integration Guidelines

Client User Exit

Screen Population (a.k.a. Screen Pop)

Oracle Utilities Application Framework - Integration Guidelines

Hostname (or IP Address) of the Web Application server (or load

Port Number allocated to Web Application Server (or load balancer)

Web Server Context

Navigation Option assigned to screen to open at startup

Context Key name used to delimit key fields

Oracle Utilities Application Framework - Integration Guidelines

There is limited possibility of populating screen information While technically

Finding the location and context fields

Oracle Utilities Application Framework - Integration Guidelines

Open a browser to a copy of the product.

From the Admin Menu, select N Navigation Option

Search for the screen by screen name:

Figure 5 Example navigation key search dialog.

Figure 6 Example navigation key.

Oracle Utilities Application Framework - Integration Guidelines

A common implementation of this technique is in the integration of Computer Telephony Integration

The following figure summarizes the processing discussed above:

Oracle Utilities Application Framework - Integration Guidelines

Figure 7 Example CTI Integration

Client User Exit

Oracle Utilities Application Framework - Integration Guidelines

Oracle Utilities Application Framework - Integration Guidelines

To use this technique the following process needs to be performed:

Considerations when using this technique

Oracle Utilities Application Framework - Integration Guidelines

Figure 9 Browser View Source option

Oracle Utilities Application Framework - Integration Guidelines

Figure 10 Example View Source for User Maintenance Page

Oracle Utilities Application Framework - Integration Guidelines

The customer service representative saves the information.

The figure below illustrates this process:

Client Side User Exit

Client Side User Exit

Oracle Utilities Application Framework - Integration Guidelines

What needs to be done?

To use this technique the following needs to be done:

The characteristic type needs to be attached to the relevant entities.

Refer to the relevant online documentation for more information.

Case Study: Document Repository

Oracle Utilities Application Framework - Integration Guidelines