ORACLE EBS 12.

2 ISG
REST WEB SERVICES
T H E U LT I M AT E G U I D E
 TA B L E O F C O N T E N T S

Part One: Overview

Part Two: What is EBS ISG REST Web Services?

Part Three: Becoming familiar with the ISG Integration Repository

Part Four: ISG REST design and deployment considerations

Part Five: Building custom ISG REST web services

Part Six: Building custom ISG PL/SQL REST web services

Part Seven: Building the demo PL/SQL REST web service

Part Eight: Building custom ISG Application Module REST web services

Part Nine: Building the demo Application Module REST web service

Part Ten: Putting ISG REST to work now

About the author

© 2020 togglefox 2
 Overview

Part One

TITLEORACLE EBSCHAPTER
OF THIS 12.2 REST
WEB SERVICES: AN
SHALLOVERVIEW
GO HERE

© 2020 togglefox 3
 ORACLE EBS 12.2 ISG REST WEB
SERVICES: AN OVERVIEW
Here’s what we’ll be covering and why.

REST web services is a hot topic at the moment and for good reason. Being able to securely communicate
packets of structured data endpoint-to-endpoint makes REST ideal for connecting your EBS system both
within your enterprise and externally to B2B systems.

And with Oracle Cloud ERP heavily utilizing REST and SOAP for integration, now is a good time to not just
get familiar with the technology, but to begin utilizing REST to upgrade your E-Business Suite data
processes.

You’ll learn the workings of Oracle E-Business Suite 12.2 Integrated SOA Gateway and how you can begin
using the technology within your organization to deploy REST web services.

Here’s what we’ll be covering:

• What is EBS ISG REST Web Services and why would you use it?
• Becoming familiar with the ISG Integration Repository
• ISG REST design and deployment considerations
• Building custom ISG REST web services
• Building custom ISG PL/SQL REST web services
• Building the demo PL/SQL REST web service
• Building custom ISG Application Module REST web services
• Building the demo Application Module REST web service
• Putting ISG REST to work now

This guide is intended for anyone who wants to learn about SOA within E-Business Suite. We’ll discuss the
workings of SOA, REST, and how this all fits within E-Business Suite.

We’ll be covering how to discover existing interfaces in the Integration Repository that you can service-
enable and expose as web services. Then we’ll move onto all considerations for designing, building and
deploying your very own custom REST web services, including working examples.

This eBook offers a broad summary of utilizing REST web services within E-Business Suite
but there’s still plenty more to talk about. Subscribe to the togglefox newsletter to keep
learning and stay up to date.

© 2020 togglefox 4
What is EBS ISG REST Web
Services?

Part Two

TITLEWHAT IS EBS
OF THIS ISG REST
CHAPTER
WEB SERVICES ( AND WHY
SHALL
WOULDGOYOUHERE
USE IT?)

© 2020 togglefox 5
 W H AT I S E B S 1 2 . 2 I S G R E S T W E B
SERVICES?
And why would you use it?
Now we’ll start getting into the detail of EBS REST web services: how it works, how it’s useful to you
and what Oracle Integrated SOA Gateway (ISG) is all about.

What is Oracle E-Business Suite REST web services?

EBS REST web services is one component of a Service Orientated Architecture (SOA), integrated with
E-Business Suite, and sits on your WebLogic Server listening for requests. It functions in much the
same way as if you were accessing a page on the web – you make an HTTP request and you get a
response. However, what makes REST incredibly versatile is that it uses this request/response model
to not just return data, but to communicate structured data in both directions.

Resources, services and entities

When you issue a call to a web page, the final part of the URL address is the page you’re wanting to
access. This is also known as the resource. REST operates in a similar way; also using a URL address to
point to a resource. Within REST architecture this resource is also known as a service and maps to a
server component such as a PL/SQL package or Java program. Think of the resource or service as an
entity, such as FND Profile Options or the FND_PROFILE PL/SQL package.

The REST service also has program functions that receive and return data. These are known as service
operations and map, for example, to a procedure or function in the PL/SQL package.

Integration interfaces, methods and endpoints

In the context of EBS REST, this service maps to an integration interface. And in the above example, it’s
the PL/SQL package which is the interface.

The service operation maps to a method in the interface, for example, to a procedure or function in the
PL/SQL package.

An example of an FND_PROFILE service operation would be a “get” operation that maps to an

interface method – in this case to a procedure within the PL/SQL package FND_PROFILE. This
procedure has a parameter that receives a profile option name and returns the value associated to that
name. So our “get” service operation receives a profile option name and returns a value.

An endpoint is the full URL that that defines the path to the service operation.

HTTP verbs
So how does the REST service communicate data? There are several considerations here. The first is
HTTP verbs – in the context of REST, also known as REST methods. When you issue a request to a
REST service, your HTTP request is sent using a GET or a POST verb. A GET HTTP request only allows
parameters to be specified within the URL so is limited in terms of data that can be pushed. However,
it does have its advantages and forms a core component of the REST model. A POST HTTP request
submits a body of structured text to the REST service which is then mapped to

© 2020 togglefox 6
parameters within the service operation, and then on to the interface method. So, in general terms, a
GET request is used to query data. And a POST request is used to insert or change data or perform
more complex actions within the interface method.

REST data formats

What does this structured text look like? REST understands XML and JSON (JavaScript Object
Notation). When you send your request to the REST service, you indicate what format you wish to
communicate with, XML or JSON. Your program that consumes the REST service, known as a REST
Client, uses this assumption that data will be received back in the format requested.

EBS REST security

It must be secure, right? Absolutely. When you send your REST request you also send authorization
data (an EBS username and password), encrypted using Base64 encryption. Alternatively, you can
request and use a security token for a username/password combination if you are managing a session
with multiple REST calls.

So now we understand the basics of EBS REST and we’ll build on this foundation as we go. Note that
the EBS implementation of REST only loosely follows the guiding principles of a pure REST model and
this is the context of how I have explained the architecture and workings of REST. The pure REST model
would be using slightly different terminology to EBS REST.

Why would I use E-Business Suite REST web services?

Communicating data between independent systems is complex enough without also needing to worry
about the logistics of exporting, importing and transporting the data. These transportation layers can
be error-prone, may involve user intervention and are generally not instantaneous.

The simplicity of the REST mechanism allows the sender and receiver to consume and process data in
real time from within their respective environments, as a direct endpoint-to-endpoint communication
without the complication of intermediary processes.

S E RVICE - E NABL ING A DATA IM PO RT PRO CE S S

Stepping back to the 1990s

Let’s consider an example. You have a remote Oracle database that collects invoice data. This data
needs to ultimately become EBS Receivables invoices. So you have a PL/SQL program that generates a
flat file using UTL_FILE and deposits the file in an outbound directory. A cron’d linux script periodically
parses the directory and remote copies new files to the EBS database server.

On the EBS database server, another cron’d linux script parses the inbound directory for new files and
when it finds a file it calls a SQL*Loader program to load the records into the AutoInvoice tables. The
concurrent manager periodically runs AutoInvoice and creates the invoices. And for any failures that
occur, well, we have a whole different set of problems.

Yikes. Feels like I’m back in the 1990s. Let’s redevelop this process as a REST web service.

© 2020 togglefox 7
Back to the future
On the EBS side, discover and deploy the REST web service “AR Autoinvoice”. This exposes and service-
enables the integration interface tables and RAXMTR concurrent program submission. Set up the
appropriate security grant for the caller and communicate the WADL (Web Application Description
Language – more on this later) so the caller understands the structure of data for communicating.

On the caller (or REST Client) side, consume the REST web service, review the service URL address and
WADL data structure and then build a PL/SQL program to perform the call. PL/SQL can write and
traverse XML nodes and from 12c Rel2 onwards, the same with JSON objects, so you have all the tools
you need to accomplish this.

See how simple this is? Direct endpoint-to-endpoint communication. And the REST Client could be any
technology, any location, inside or outside the enterprise.

As a side note, rather than just service-enabling Autoinvoice, I’d consider this process as a candidate
for a full redevelopment using PL/SQL package AR_INVOICE_API_PUB to create Receivables invoices
real-time.

Using REST with mobile applications

Say you have an old, clunky client-server application. The client (let’s say it’s a SQL*Forms application)
runs on the user workstation and uses SQL*Net to communicate with the Oracle database. Not very
portable in this day and age.

And now you want to redevelop the application as a modern mobile application. How are you going to
manage all the communication from the mobile device to the Oracle database? Using REST web
services, of course. REST is lightweight and fast and forms part of the perfect architecture for mobile
applications.

Using REST to trigger business events

Instead of pushing data around, let’s say you want to service-enable a business event or transaction.
Use EBS REST to service-enable triggering of Workflow business events or BPEL processes. Or engage
in a transaction by service-enabling a PL/SQL package. Easy.

Do I need to separately install SOA Suite to use REST?

If your intention is only to use REST web services then the answer is no, you’re good to go with your
existing E-Business Suite 12.2 installation.

What about SOAP Web Services?

If you want to use SOAP web services with E-Business Suite, then you need to separately install and
license SOA Suite. SOAP does not support Java-based interfaces such as Application Module Services,
but PL/SQL is supported as both synchronous and asynchronous interactions. SOAP is another
interesting subject and worthy of its own e-book. (Stay tuned.)

Do I need to use EBS REST with Oracle Integration Cloud Service (ICS)?
No, you don’t need to, but there are clear benefits for using ICS. Better connectivity and security and a
very nice remapping of web service data structures if you have a business need to do this. But if EBS
REST standard functionality meets your needs, then you don’t need to install any additional
components.

© 2020 togglefox 8
What is Oracle Integrated SOA Gateway (ISG)?
Oracle Integrated SOA Gateway (ISG) is the component layer that service-enables E-Business Suite
with REST and SOAP-based web services. Oracle bundles ISG with your EBS 12.2 instance and
WebLogic Server installation and provides the functionality for service-enabling the following
technologies and EBS components;

• PL/SQL
• Concurrent Programs
• Workflow Business Events
• BPEL Processes
• Open Interfaces
• Java Bean Services
• Application Module Services
• Java APIs
• XML Gateway
• Business Service Objects

Service types
These technologies and components are called service types. Each service type has functionality in ISG
to perform a mapping of inbound and outbound data, known as payloads. ISG accepts payloads of XML
or JSON data then maps the payload to the service type’s native interface. So for example, a PL/SQL
based web service maps the XML or JSON payload to Oracle data types and object structures. Java web
service payloads map to Java Beans.

ISG execution steps

ISG accomplishes this data mapping by making use of two very clever libraries; Jackson and JAXB.
These two libraries specialize in mapping XML and JSON data to Java objects. This type of mapping of
data is known as serializing-deserializing. Or, my favorite: marshalling-unmarshalling. Once ISG
understands the incoming data and has found the matching interface method, it then performs
security checks to ensure the username/password combination is valid and is authorized to access the
method. If these checks fail, then a security exception message is returned to the Client.

At this stage, a fully Apps-initialized database session is prepared for the authorized user. These
service types also accept context values in the payload to further establish the initialization:

• Responsibility
• Responsibility Application
• Security Group
• NLS Language
• Org Id

The interface method execution then occurs, such as calling your PL/SQL package procedure, followed
by the reversing of the above process to serialize (or marshall) the result back into XML or JSON for
returning to the Client. Most of the above is user-administered using EBS self-service pages in the ISG
Integration Repository. Sounds pretty nice, right?

© 2020 togglefox 9
ISG limitations
But. (There’s always a but). ISG does have its limitations. Take the following three points:

• ISG doesn’t allow nesting of resources, called sub-resources, in the REST path
• There’s also very limited usage of HTTP verbs (REST methods)
• And there’s no control over HTTP response status codes.

This may be a problem for those seeking the elegance of a pure RESTful model. The canonical data
structure coupled with the use of verbs and return codes is what epitomizes the simplicity and
elegance of RESTful-enabled systems.

A pure RESTful model

A true and pure RESTful model would allow the following resource structure:

/invoices
/invoices{invoice id}
/invoices{invoice id}/lines
/invoices{invoice id}/lines{line id}
/invoices{invoice id}/lines{line id}/distributions
/invoices{invoice id}/lines{line id}/distributions{dist id}

Coupled with the use of CRUD (Create/Read/Update/Delete) operations and standardized status
codes as listed below, all general operations of the above resources are covered.

Operation Verb
Create POST
Read GET
Update PATCH
Delete DELETE

Status Code Meaning

200 OK
201 Created
404 Not Found

When you add into the mix being able to return status codes, there’s REST in a nutshell:

Action Verb URL Status Code

Read invoice 101 GET /invoices/101 200
Read lines for invoice 101 GET /invoices/101/lines 200
Read line 123 for invoice 101 GET /invoices/101/lines/123 200
Read all invoices for 01-JAN-20 GET /invoices/?q=trx_date=2020-01-01 200
Update invoice 101 PATCH /invoices (update payload) 204
Delete invoice 101 DELETE /invoices/101 204
Read deleted invoice 101 GET /invoices/101 404

See the elegance and simplicity of the REST model? Pretty ingenious, wouldn’t you say? Now let’s
consider how we’d do the same in EBS REST.

© 2020 togglefox 10
The ISG REST model
ISG doesn’t allow nesting of resources, so we’re only allowed to define the service object. No path. So
all service object endpoints are at the same level.

Verbs are limited to GET and POST - PL/SQL is even more limited with only POST being supported.
However, interface tables such as Autoinvoice tables are allowed GET, POST, PUT and DELETE.

No control over return status codes. Either 200 (OK) is returned for success or 500 (Internal Server
Failure) for an error.

Based upon these limitations, we’ve lost the versatility of the pure RESTful model. We’re still able to
name our service objects as nouns (e.g., invoice). But without nesting (i.e., a path), invoice lines needs
to be a service object named invoiceLines or integrated into the invoice service object.

And without access to the full array of HTTP verbs, it becomes necessary to create service methods
that include the verbs in the name, resulting in names that sound like commands.

Revisiting the previous REST example for invoices, an Application Module service, which supports GET
and POST requests, could manage something like this:

Action Verb URL

Read invoice 101 GET /invoices/getInvoice/101
Read lines for invoice 101 GET /invoices/getInvoiceLines/101
Read line 123 for invoice 101 POST /invoices/getLinesForInvoice (post data)
Read all invoices for 01-JAN-20 GET /invoices/queryInvoice?trxDate=2020-01-01
Update invoice 101 POST /invoices /updateInvoice (post data)
Delete invoice 101 POST /invoices/deleteInvoice (post data)

A PL/SQL service, which may only POST and does not support path parameters (more on that later),
would be even worse:

Action Verb URL

Read invoice 101 POST /invoices/queryInvoice (post data)
Read lines for invoice 101 POST /invoices/getInvoiceLines (post data)
Read line 123 for invoice 101 POST /invoices/getLinesForInvoice (post data)
Read all invoices for 01-JAN-20 POST /invoices/queryInvoice (post data)
Update invoice 101 POST /invoices /updateInvoice (post data)
Delete invoice 101 POST /invoices/deleteInvoice (post data)

As you can see, it becomes awkward. We’ve lost our structure of resources and verbs and now have a
single level of command endpoints. (There are other limitations to ISG and REST, which I’ll blog about
another time.)

Implementing REST in WebLogic Server

Why not just expose your REST web services thru WebLogic Server? After all, WebLogic Server is a
full-buffet, all-you-can-eat J2EE-compliant application server offering full support of the REST data
model and the goodness of JAX-RS annotations.

© 2020 togglefox 11
Sure, this is possible. But it’s not so easy when you consider the EBS functionality that you’re missing
out on.

✗You’ll need to manage security through WebLogic and code your own endpoints.
✗You’ll miss out on the convenience of having a provided JDBC Oracle connection already initialized
for the user, responsibility and org.
✗You’ll need to build your own integrations to all the EBS components that ISG supports.
✗You’ll miss out on being able to integrate with the rich OA Framework ecosystem and BC4J
components and object persistence.
✗If you do require this level of BC4J componentry, then you’ll need to utilize ADF server libraries
✗You’ll need to package the whole thing up for deployment in a complicated ear/war file with all the
required dependencies. And repeat this step every time you make a change.

Yuck.

Introducing ISG’s superpower

So this highlights to us ISG’s superpower. It may not allow for a perfect implementation of REST, but it
makes REST easy.

✓Easy to build
✓Easy to implement
✓Easy to discover
✓Easy to deploy
✓Easy to administer

Consider the following. If you’re reading this, you’re probably not intentionally designing a
discoverable REST model where the REST Client is unfamiliar with the services and needs to machine-
learn the structure from WADLs.

You’re probably building, or looking to build, service-enabled E-Business Suite APIs within your
enterprise or for B2B connectivity. And these types of APIs generally follow the format of commands
with a well-documented API structure, agreed upon between all stakeholders. Think
AR_INVOICE_API_PUB or AP_VENDOR_PUB_PKG or similar API design.

So there we have it. REST Web Services, implemented through ISG, is a pretty nice SOA implementation
for building and managing web service connectors into your E-Business Suite, both from within your
enterprise and external B2B systems.

In Part 3, we’ll talk about the ISG Integration Repository, getting familiar with the self-service pages
and walk through a deployment example.

© 2020 togglefox 12
Becoming familiar with the
ISG Integration Repository

Part Three
BECOMING
TITLE OF THISFAMILIAR
CHAPTERWITH
THE ISG INTEGRATION
SHALLREPOSITORY
GO HERE

© 2020 togglefox 13
 B E C O M I N G FA M I L I A R W I T H T H E
I S G I N T E G R AT I O N R E P O S I T O R Y
Previously, we discussed the workings of E-Business Suite REST web services and how it’s implemented as
part of Integrated SOA Gateway (ISG). Now, we’ll cover the workings of the Oracle Integration Repository:
the data repository and user interface for ISG.

Before we begin, ensure you have ISG configured and ready for use in your 12.2 instance by following the
steps in Oracle technical document: Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2
(Doc ID 1311068.1)

What is the Oracle Integration Repository?

The Oracle Integration Repository is the data repository and user interface for Integrated SOA Gateway
(ISG). It’s in this repository that ISG stores all integration interfaces. You can then utilize this user interface
to discover and service-enable interfaces and deploy as REST and SOAP Web Services.

GET T ING ACCE S S T O T HE INT E GRAT IO N RE PO S IT O RY

Assigning responsibility and role

To gain the necessary access to be able to complete the following steps through the remainder of this blog
series, you’ll need SOA administrator access. There are two steps to this process, requiring assignment of
responsibility and role.

First you’ll need to be assigned Integrated SOA Gateway responsibility. This will be labelled Integration
Repository in your responsibility list.

And second you’ll need user role Integration Administrator role (UMX|FND_IREP_ADMIN) granted to you to
gain full access within the responsibility. Follow the below steps.

Query your user in Users (User Management) responsibility.

© 2020 togglefox 14
Assign role Integration Administrator role (UMX|FND_IREP_ADMIN) to your user if not already
assigned.

If you have just assigned this role, then wait for the workflow background process to complete (you’ll
see a message for this) then clear the Global Cache.

© 2020 togglefox 15
The Integration Repository home page
Open the Integration Repository responsibility to view the home page. Here you have access to all the
installed integration interfaces. You can either drilldown through the hyperlinks on the left to find an
interface or click Search to navigate to a search page.

How many integration interfaces are in the repository?

There are roughly 3,600 interfaces. That’s a lot. So how are they distributed by product and service
type?

Run the below SQL. This shows us the top 20 interfaces by product type.

select display_product_name,count(*)
from (
select nvl(b.product_name,a.product_code) as display_product_name
from fnd_irep_all_interfaces a,
ad_pm_product_info b
where a.product_code = b.product_abbreviation(+)
and a.lifecycle_mode = 'ACTIVE')
group by display_product_name
order by count(*) desc
/

Human Resources 629

Application Object Library 334
Receivables 269
Lease Management 243
Common Application Calendar 223

© 2020 togglefox 16
Projects 154
Student System 130
Advanced Product Catalog 128
iRecruitment 121
Trading Community 113
Bills of Material 100
Inventory Management 90
Learning Management 85
Purchasing 74
Workflow 70
Trade Management 68
Supply Chain Trading Connector 64
Shipping Execution Common 61
CRM Data Model 54
iStore 51

And now run the below SQL. This shows us the number of interfaces by service type.

select display_interface_type,count(*)
from (
select decode(a.open_interface_flag,'Y','Open Interface',b.meaning) as
display_interface_type
from fnd_irep_all_interfaces a,
fnd_lookups b
where b.lookup_code = a.class_type
and b.lookup_type = 'FND_REP_OBJECT_TYPE'
and b.enabled_flag = 'Y'
and a.lifecycle_mode = 'ACTIVE')
group by display_interface_type
order by count(*) desc
/

PL/SQL 1359
Business Event 875
Service Data Object 455
Java 424
Open Interface 189
XML Gateway Map 112
Concurrent Program 91
Interface View 49
Business Service Object 43
EDI 22
© 2020 togglefox 17
Based on the above results we can see that HR utilizes SOA the most, followed by AOL and Receivables.

And by service type, PL/SQL is most common followed by Workflow Business Events, Service Data
Objects (a Java-based object used for integration with BPEL) and then Java-based services.

Expect this list to grow with each new ISG release.

DISCOVERING, DEPLOYING AND TESTING AN ISG REST WEB SERVICE

Now we’ll go through an example of discovering, deploying and testing a REST web service. The
example we’re going to work through is FND_PROFILE PL/SQL API to query and set values. It’s quite
harmless as it will only change values in memory.

Discover the ISG interface

From the Integration Repository home page, click and Search to enter the search page. Enter
FND%PROFILE in the Enter Name, click Go to search then click on Profile Management APIs.

Now we can see the detail of the integration interface. Type tells us the service type for the interface.
The hyperlink for Business Entity shows us other interfaces that reference this entity.

Source File and Source Version show us the name and version of the physical file that was loaded into
the repository. The file needs to contain meaningful annotations for the Integration Repository Loader
and is a special parsed file created by the Integration Repository Parser. More on this later.

Procedures and Functions lists the integration interface methods that may be service-enabled. Click
on method Get Profile.

© 2020 togglefox 18
As you can see, there is a parameter named NAME as in input parameter, returning a parameter named
OUT. This matches the procedure signature in PL/SQL package FND_PROFILE.

Note that VAL, defined as an OUT parameter in the procedure, could just as easily be a function
returning a VARCHAR2. This is all defined in the annotations that we set in the loader file. More on this
in Part 4.

Click on the REST Web Service tab. Service Alias should be empty and Service Options should be
unchecked. If you are not seeing an enterable field in Service Alias, then you’re unable to deploy the
service. Something has gone wrong with assigning you the Integration Administrator role, so you will
need to resolve this first.
© 2020 togglefox 19
Note also that your page probably looks a little different to mine. You’ll have a Service Operations column
labeled Grant. And you are probably constantly being reminded:

Oracle E-Business Suite Integrated SOA Gateway is not configured for SOAP Services. Please refer My Oracle
Support Note 1311068.1 to configure for SOAP Services

I have a fix in place to stop this message which I find kind of annoying. If you’d like to do the same, then
check out this blog post. If you don’t, then no problem. We’re still performing the same actions.

Deploy the FND_PROFILE ISG interface as a REST web service

Now we’re ready to deploy and service-enable the integration interface for use as a REST web service.
We’re going to name the service FndProfile so enter this value in the Service Alias. We’ll also be
exposing all the service operations to REST Clients so check all the checkboxes for Service Operations.
Click Deploy to deploy the service.

© 2020 togglefox 20
If all has gone well, then you should have the below confirmation message:

Successfully deployed Web Service for interface “Profile Management APIs” to Application Server

We now have a deployed REST web service. The final step we need to complete is granting access to
the web service.

Grant access to the REST web service

Click the Grants tab to administer grants for the web service. We’re going to grant access for all the
service operations so check the top box to select all then click the Create Grant button.

© 2020 togglefox 21
Grants can be set for All Users, a Specific User or a Group of Users. Multiple grants can also be
assigned. Note that the page refers to Users but the source is actually WF Roles. This is useful for
setting up web service security for B2B transactions.

Assign the grants you wish to assign to the web service then click Create Grant. If all good, then you
should see the below confirmation message. You can add additional grants or revoke grants using a
combination of the Method checkboxes and the Create Grant or Revoke Grant buttons. However, be
aware that if you make any changes to grants you will need to clear the Global Cache for the change to
take effect.

You can also view grants that are currently assigned to a service operation by clicking the icon in the
Grant column.

So now you have a deployed REST web service with grants assigned that is ready to be consumed by a
REST Client. Any Client that wishes to consume this web service needs to first understand the API.

The ISG REST web service WADL

Click on the REST Web Service tab and then click the View WADL hyperlink. WADL (Web Application
Description Language) is a machine-readable XML description of the deployed service and the
exposed service operations. It also shows us how we communicate with the web service and API.

The WADL is important as it defines a contract that all REST Clients must adhere to. This is called
a contract-first approach.

In the WADL file, the resources base is the URL path to our service. Appending our get operation
name to the resource base gives us the full URL for the get method, known as the endpoint.

http://vis1227.togglefox.com:8000/webservices/rest/FndProfile/get/

The WADL also tells us that the service operation is only accepting POST verbs and request and
response data may be communicated in XML or JSON.
© 2020 togglefox 22
Now copy the full URL for GET_SYNC_TYPEDEF.xsd and paste it into a new browser window.

This is the grammar document for the get service operation. It shows us that the operation accepts a
NAME parameter of type string then maps the value to a VARCHAR2 for passing into the integration
interface method – in this case a PL/SQL package procedure. The interface method then returns a VAL
parameter of type VARCHAR2 and maps it to a string for returning to the Client.

Now we have a deployed REST web service, we’ve granted permissions, we have our service operations
and we’re familiar with the API usage. We’re ready to test the web service.

ACCESSING AND TESTING THE REST WEB SERVICE

Choosing a REST Client

To access and test the REST web service we need a REST Client. We have several options:

• cURL is a command line tool. Works well in Linux

• REST Client plugins are available for both Chrome and Firefox
• Postman API Client is a sophisticated HTTP Client with full support for REST
© 2020 togglefox 23
Install Postman and import the test cases
Postman API Client is commercial software but has a free option which is more than up to the task of
what we need to achieve. I’m a big fan of Postman and I’ll be using Postman as my REST Client for the
rest of this blog series. All of the test cases that we’ll be working through are available on github and
can be imported directly into Postman.

Postman is installed as a standalone program. Install Postman and download the Postman import file
from github here.

Open Postman, click Import and choose file FND Profile.postman_collection.json.

Configure the test cases for your EBS installation

You will now have a collection named FND Profile. Right-click on FND Profile, choose Edit from the
popup menu and then click on the Authorization tab.

See that the Type is set to Basic Auth? This means we will be communicating with ISG using a simple
HTTP authorization of EBS username/password combination, encrypted with Base64 encryption.
We’re also able to do token-based encryption but more on that later.

Change the username and password values to an EBS user who was granted access in the earlier steps
then click Update to save the changes.

© 2020 togglefox 24
Now expand the FND Profile collection to view the requests and click on Get profile option value xml
to open the request. Update the URL to your site’s URL and click Save. Click on the Body tab and you
should see similar to the below.

© 2020 togglefox 25
This shows our FND Profile REST Web Service with our get service operation. We’ll be sending the
request to ISG as a POST verb. The Body contains our payload that we’ll be sending. If you go back to
reference the WADL for this method, you will recognize InputParameters and NAME.

Click Send to send the REST request to your ISG Server. You should see similar to the below. Scroll
down in the window to see the response output.

The server has returned a 200 OK Status Code, so we know the operation was successful.

The Body contains our return payload. If you again go back to reference the WADL for this method,
you will recognize OutputParameters and VAL. And contained within VAL is the profile option value
that we requested. If you are seeing an error returned, then you will need to diagnose this and revisit
the previous steps.

So you have now successfully executed your first E-Business Suite REST web service. Nice! This was
all accomplished in XML. How did ISG know we wanted to communicate using XML? Click on the
Headers tab (next to the Body Tab) and you will see:

Content-Type: application/xml

In the header of our HTTP message we state that we wish to communicate using XML. So what if we
want to use JSON instead? Let’s run this same request using JSON.

Click on request Get profile option value json under FND Profile to open the JSON request. Change
the URL as you did with the XML request. Click on the Headers tab. Now you’ll see:

Content-Type: application/json
© 2020 togglefox 26
Now we’re instructing ISG that we wish to communicate using JSON. Click on the Body tab and you
should see the same as the below.

This is exactly the same message as our XML request, but communicated in JSON instead. Click Send
and you should see the same result as your XML response, but this time in JSON.

© 2020 togglefox 27
Now we’ve tested both XML and JSON REST web services. Great! What else can this thing do? Honestly,
we’ve only just scratched the surface. I’d suggest discovering and deploying some more REST web
services and then try testing the web services using Postman, working from what you’ve learned so
far.

Next, we’ll be laying the groundwork for building your own web services.

© 2020 togglefox 28
 ISG REST design and
deployment considerations

Part Four

TITLE ISG
OF REST
THISDESIGN AND
CHAPTER
DEPLOYMENT
SHALL GO HERE
CONSIDERATIONS

© 2020 togglefox 29
 D E S I G N A N D D E P LO Y M E N T
C O N S I D E R AT I O N S
For the remainder of this book, we’ll be discussing how you can build your own custom integration
interfaces for loading into the Integration Repository. We’ll be focusing on two service types,
discussing their benefits and disadvantages and we’ll work through an example of each:

• PL/SQL
• Application Module Services

Before starting our build, we have a series of technical design considerations centered around the
following points:

• ISG REST web services work structurally different to a pure REST model, so we have design
decisions based around these differences.
• Each of the service types we’ll be covering also has their own design and implementation
considerations.
• You’re most likely building enterprise or B2B web services so there’s business and organization
considerations.
• We want to follow general practices and standards for good REST API design, so there’s
considerations here too.

Always consider standard functionality first

This is an across-the-board design paradigm with E-Business Suite development but especially fitting
to ISG. There are currently approximately 3,600 integration interfaces available in the Integration
Repository for discovery and deploying. Consider first if an existing interface meets your needs
before making the decision to take the customization route.

Reach agreement on API structure

Involve all relevant stakeholders in the design of the API, methods and parameters.

Apply mindful API design principles

Remember that what is registered first in the Integration Repository is not a web service but an
interface. Understanding who and what processes will be using the API and what they wish to achieve
will result in robust, reliable and intuitive APIs. Remember also that once the interface has been
deployed and is in use by Clients, changing API signatures becomes more difficult than simply
changing a piece of internal code.

Practice thoughtful ISG REST API design

Interfaces for ISG REST web services have different naming considerations than a pure REST model.
Identify actions that need to take place and group these into entities. The entity becomes the web
service and the actions become the service operations.

© 2020 togglefox 30
Consider establishing design guidelines and naming standards before starting the SOA design process.

Understand expectations of web service performance

Clear expectations and metrics of web service performance need to be agreed upon very early on. This
in part will dictate design. ISG only supports synchronous REST communication – asynchronous
communication is currently only supported for SOAP PL/SQL-based service operations. The REST
Client will need to wait for a response so the wait times need to fit within the parameters of the Client’s
scenario. Is the REST Client part of a UI where a user is waiting for the response? Or is the REST Client
a background process that has no resulting system impact if the response is slower?

One simple solution to a performance expectation disparity is to wrap the interface functionality in a
service-enabled concurrent program. This of course involves a trade-off. You are sacrificing the
availability of real-time results to achieve a performance gain.

Performance can also be enhanced by leveraging the GET verb for implicit caching.

When establishing performance expectations and metrics, you need to also consider other
intermediary entities along the transportation layer that may impact performance or cause
bottlenecks: rerouting, proxies, firewalls and integration layers.

Consider other components of your SOA ecosystem

Will your REST web services be integrated with Oracle Integration Cloud Service (ICS) or other
integration components? Do the stakeholders in these components have requirements that you need to
consider in your design?

Consider security layers

There may be a number of enterprise security layers that the web service needs to navigate through,
both before and after processing in ISG. These all need to be considered with appropriate approvals
and configurations in place.

Security requirements for the REST Client need to be established and put in place for the web service.
Is security limited to one person, party or group? Grants to the web service are based on WF Roles, so
the role may be a person or a party – suitable for internal EBS users or external B2B entities.

Security authentication is based on HTTP Basic Authentication and requires an EBS username and
password, encrypted using Base64 encryption. Alternatively, the Client may switch to Token-Based
Authentication after first requesting a security token from the Login Service. This is useful if the Client
is part of a process that is managing a session with multiple REST calls, such as a UI session.

Who will be responsible for transaction failures?

Considering transaction failures, points of failure, and follow-up process is key to your design. Take, for
example, service-enabling the creation of AR Invoices. Exposing AutoInvoice results in the same
process flow as other means of utilizing AutoInvoice; populate the interface tables and submit
RAXMTR concurrent program. End of responsibility for the Client. Invoice creation errors become
someone else’s problem.

© 2020 togglefox 31
Now consider service-enabling AR_INVOICE_API_PUB instead. This results in invoices being created in
real time, possibly a critical assumption for the Client. But the flip side results in invoice creation
errors being returned to the Client.

As a side note, in this particular case the entire interface process may be a good candidate for building
a custom interface, web service and business process.

Understanding consequences of the commit unit

A major downside with service-enabling an API is you no longer over control over the commit unit. A
regular PL/SQL API is generally called from within a database session. You can monitor the API, either
by wrapping it in an exception block and catching a raised exception or by checking for a failure return
code. If a problem is encountered you can then take appropriate action, probably involving a rollback.

A service-enabled API will commit upon success or rollback upon failure. Simple as that.

Take, for example, a program that creates a vendor and then creates an invoice for the new vendor.
First you call AP_VENDORS_PKG (along with other APIs) to create the vendor. If this succeeds, you then
call AP_IMPORT_INVOICES_PKG to create the invoice. If there’s an issue along the way, no problem, you
just issue a rollback and the logical unit of work disappears as if it never happened. (OK, it’s a problem
for someone that it failed but we’ll leave that out of the equation)

Say you wanted to reproduce this in a service-enabled scenario. You service-enable AP_VENDORS_PKG
by deploying Suppliers Package. (There isn’t a service option for AP_IMPORT_INVOICES_PKG, so you’d
need to do this yourself.)

Now you have both APIs service-enabled. And say you have a business rule in place that one can’t exist
without the other. OK, so you call the Suppliers Package Service. Success. All good. Now you call the
Import Invoice Service. And it fails. Hmm. What now? You can’t just rollback as the supplier has already
been committed. This is the dilemma with web services – operating in their own independent commit
units.

There is one way to address this. Consider wrapping the interfaces for PL/SQL Web Services into one
service-enabled umbrella interface that brings them all together into the same commit unit and deploy
this interface.

Considerations and constraints around naming of method parameters

Service operation parameter names map directly to their corresponding native properties. This works
great with Java Beans but not so great with PL/SQL interface types. PL/SQL objects, arrays and
procedure parameters will appear in your WADL in uppercase. If you follow the EBS naming standard
of naming IN parameters as P_% and OUT parameters as X_%, then these names will also reflect in
your WADL. And PL/SQL object array elements are appended with %-ITEM. Not great. We’ll talk more
about these constraints in Part 5.

Designing for exceptions

Java-based interfaces allow you to throw an ISG-based exception that you can populate with
meaningful data. This exception is returned as the response payload along with a 500 service error.
PL/SQL-based interfaces offer no control for returning exceptions. If your PL/SQL program raises an
exception, then the service will return a generic service error message and a 500 service error. It’s not
possible to return anything meaningful to the Client. Details of the exception are logged in the
WebLogic Server EBS Domain server log, but this is of no use to the Client.
© 2020 togglefox 32
Versioning APIs
If your API is likely to evolve and change its signature, then there are considerations around this.
Exposing a new version of your web service without coordinating the change with REST Client
stakeholders will in all probability break the Client. There are two scenarios here.

The first (and best) scenario is where the API and Clients are contained within an organization with
good communication and cooperation between all invested parties. API changes and deployment times
can be agreed upon, ensuring the API and Clients remain in sync with the expected web service
signatures and data.

The second scenario is where agreement of changes and/or deployment timelines cannot be
coordinated between all parties. If it’s critical that both versions of the API be exposed, then utilizing
API versioning is the established, if not ideal, solution.

API versioning ensures the contract between the API and the Client remains binding and involves
implementing multiple copies of the API, differentiated by a version number.

The usual methods of REST API versioning in a pure REST model would involve URL, header or media
type versioning. None of these are possible in ISG so instead we’ll discuss how you can accomplish this
with ISG web services.

1. Create another native interface that meets your new signature requirements.
2. Where possible, share functionality with the previous version(s) of the interface to minimize code
duplication and maintenance overhead.
3. Load the interface into the Integration Repository and deploy the interface as a REST web service
with a name that includes the version. For example, if the original service name is FndProfile, name
this service FndProfileV2.

To begin using the new version, Clients will need to consume the new web service endpoint and
method signatures. Reach agreement with all parties as to when older versions of the web service can
be decommissioned and undeployed. The fewer versions hanging around the better.

Caution: Approach versioning with caution and only use it if you need to. It introduces logistical
complications of multiple APIs in use and support headaches of needing to maintain multiple versions
of code.

One other caution: Resist the desire to introduce a “version number” property into your request
payload. You will be introducing a dynamic interface and this is very much discouraged as it breaks the
contract.

Logging and auditing REST web services

ISG has service monitor logging and auditing for both design time and runtime. However, this auditing
and logging is only available for SOAP web services.

ISG performs fairly detailed console logging, and this output is routed to log file
$EBS_DOMAIN_HOME/servers/oafm_server1/logs/oafm_server1.out. This log file is extremely useful
for monitoring and diagnosing REST web service activity. I would also suggest integrating your own
logging into your native interface code.

© 2020 togglefox 33
E-Business Suite context parameters
Context parameters can optionally be passed in the header block of the request payload and contribute
to the further initializing of APPS_INITIALIZE. These parameters are wrapped in a RESTHeader
element and include the following:

• Responsibility
• RespApplication
• SecurityGroup
• NLSLanguage
• Org_Id

These parameters are processed by ISG and not passed through to the interface. Consider if you are
planning to use context parameters. If so, then program your code based on the assumption that
language and/or org are appropriately set or perform a test in your code for the presence of these
values in FND_GLOBAL.

Caching of response data

Caching of REST web service response data reduces Client wait times, improves performance and
reduces server load. Response caching can occur at multiple places along the request-response
transportation path.

Caching is generally only available for GET verbs. Caching behavior is defined according to directives
set in the request and response headers. ISG by default does not exclude responses from being cached
and this is one area that can be leveraged for performance gains.

PL/SQL web services cannot be cached due to the inability to send GET requests. Java-based services
can be cached when the request is sent as a GET. On this basis, I recommend using the GET verb where
possible for all retrieval of data. Note that it’s possible to include a header directive in your request
stating that caching should not be used.

Test your interfaces before loading into ISG

ISG service-enables native interfaces into web services. Before interfaces become web services, the
interfaces are first native interface types such as PL/SQL, Java and EBS components. These interfaces
are built as a standalone APIs and as such, should be fully tested in a native controlled environment
before loading into the Integration Repository. Diagnosing and fixing bugs in this earlier stage will be
easier than once the interface has been loaded and deployed as a web service.

Use simple data types

ISG will translate your native interface data types into XSD (XML Schema Definition) compliant data
types. Sticking to simple types such as number, VARCHAR2/String and date will ensure an accurate
mapping to clear XSD data types such as:
• xsd:int
• xsd:string
• xsd:decimal
• xsd:dateTime

Deviating from this rule may involve mapping to catch-all XSD data types such as:
• xsd:anySimpleType
• xsd:anyType
© 2020 togglefox 34
The WADL needs to be a clear document explaining precisely how the API can and should be used.
Ambiguous data types such as these require supplementary documentation to explain to the Client
consuming the service as to how to use the related elements. Using ambiguous data types also
potentially breaks the contract.

There are also runtime implications. Your first level of request document validation is performed
by ISG. If ISG understands what data types to expect then it can take care of validating robustness of
the request data and report back inconsistencies to the Client with a meaningful error message.

If ISG then attempts to map the data to your interface’s native data structure and this fails then the
error message will be less helpful.

As a general rule of thumb, after deploying your web service, scan the generated WADL looking for
any occurrences of these generic XSD data types. If any occurrences are not intentional then revisit
your API signatures and revise as need be.

Pagination of results
ISG supports pagination of results using URL parameters offset and limit. Pagination is not
supported for PL/SQL service types.

Payload data format

ISG can receive and send payloads in either XML or JSON data formats, as long as you indicate in
your request header which format you wish to communicate with. My experience with building ISG
Clients has been positive with XML but less positive with JSON. I much prefer JSON but, right up to
12.2.7, I’ve found JSON unreliable. Context values with PL/SQL web services need to be XML as ISG
will not set a JSON Org_Id. And using JSON with Application Module services seems particularly
unreliable, so for the time being I’ll be sticking to XML with Application Module services.

Filtering of results
REST web service filtering is the ability to include a query expression as an HTTP parameter when
performing a GET. The query expression is applied as a filter to the response, ultimately returning a
subset payload.

Oracle Cloud ERP REST web services has sophisticated query abilities as part of the standard REST
API. However, there is no standard or requirement for REST frameworks to provide filtering. ISG
does not perform any filtering of results.

Automating REST web service deployment

All stages of ISG service deployment happens at the application server operating system level.
Automated deployment is entirely possible and is quite feasible to integrate ISG service
deployments into deployment automation software.

Now that we’ve covered ISG design considerations, we’ll move onto building and deploying actual
working examples of REST web services.

© 2020 togglefox 35
Building custom ISG REST
web services

Part Five

TITLE BUILDING
OF THISCUSTOM
CHAPTERISG
REST WEB SERVICES
SHALL GO HERE

© 2020 togglefox 36
 BUILDING CUSTOM ISG REST
WEB SERVICES
In Part 4, we discussed design considerations. Now we’re beginning the process of building,
loading and deploying actual REST web services.

BU IL DING AND LO ADING A CU S T O M IS G INT E GRAT IO N INT E RFACE

Build your custom integration interface

The first step in this process is to build your integration interface using one of the
supported ISG integration type technologies. All of the points from the previous post<link>
should be considered when designing your interfaces.

Annotate the custom integration interface

Loading ISG interfaces into the Integration Repository requires a physical file for loading.
The interface file needs to be annotated with ISG-specific Javadoc-style annotations for
loading into the repository. The annotations give the upload process and the repository the
ability to understand the API structure and how this fits into the context of ISG, interfaces
and web services.

A good place to understand annotations for each interface type is Appendix A - Integration
Repository Annotation Standards in the Integrated SOA Gateway Developer's Guide Release
12.2 document.

Load the interface file onto the Application Server

The next step requires loading the interface file or files onto your Application Server
operating system for parsing by the Integration Repository Parser.

Parse the interface file using the IREP Parser

The Integration Repository Parser (IREP Parser) is a Perl-based parser that parses the
interface, validates the annotations and generates an Integration Repository loader (iLDT)
file. The IREP Parser requires a version number for the interface. Note that the interface
will not load into the repository if the version number is not incremented from the previous
load of this interface.

Load the parsed interface into the ISG Integration Repository

The Integration Repository loader file (iLDT) is an FNDLOAD-compatible *.ildt file that
contains the interface specification for loading into the Integration Repository. This file is
loaded into the repository using FNDLOAD and utilizes Integration Repository Loader
Configuration file wfirep.lct.

Tip: If you are loading a new version of the interface into the Integration Repository then the
Global Cache will need to be cleared to reflect the changes in the WADL.

© 2020 togglefox 37
Perform additional Application Module Service steps
Deploying Application Module-based services requires a few more steps involving regenerating the signed
jar file for custom Java code (custom.jar) and restarting the Fusion Middleware Managed Server
(oafm_server1). (This step isn’t required for PL/SQL based services.)

If these previous stages have completed successfully, the interface will now be available for deploying as a
REST web service.

INS TAL L ING T HE DE M O DATABAS E O BJ E CT S

For the remainder of this blog series, we’ll be creating an example interface and deploying as a REST web
service for each of the following service types:

• PL/SQL
• Application Module Services

Both service types will be based on common database schema objects and service operations to
demonstrate how the same business operations can be implemented for each of the service types.

Our scenario is a very simple one, based around maintaining invoices and invoice lines. For the PL/SQL
based demo we’ll use a PL/SQL package to maintain and query the invoices, whereas with the Application
Module demo we’ll accomplish everything in BC4J. Each interface and REST web service will expose
methods to:

• Create a new invoice

• Retrieve a single invoice
• Retrieve multiple invoices using query criteria
• Update an invoice
• Delete an invoice

All of our examples are intended for demonstration purposes and should only be installed in a
development or non-essential EBS instance. Download the required files from github here.

Install the demo tables and PL/SQL package

The PL/SQL package XXTF_REST_INVOICES_PKG references a simple logging system to provide logging
output. Follow this blog post to install the logging package. If you’d prefer not to use the logging, then
simply comment out or remove the logging lines from the PL/SQL package.

From the APPS user, execute install.sql to create:

Object type xxtf_rest_invoice_line_rec

Object array xxtf_rest_invoice_line_tab
Object type xxtf_rest_invoice_rec
Object array xxtf_rest_invoice_tab.sql
Table xxtf_rest_invoice_lines
Table xxtf_rest_invoices
PL/SQL package XXTF_REST_INVOICES_PKG

We’re keeping things simple by creating all the objects in the APPS schema.
© 2020 togglefox 38
Seed sample demo data
The next step is to seed some invoice data. This step is optional and you’re welcome to skip over.

Execute sql get_user_resp_combo.sql and pick a user id, responsibility id and application id
combination. When seeding the data, this combination will populate the user auditing values.

If you’re using the logging functionality then open a separate putty (or equivalent) window, log on as
the applications owner and issue the following commands:

cd /tmp
touch togglefox.log
tail -f togglefox.log

Update seed_data.sql with your user values, execute seed_data.sql and commit.

In your logging window, you should see something like the screenshot below, which shows that both
seeding of the data and the logging is working correctly.

We’re now ready to begin creating our first interface and REST web service. In the next part, we’ll go
through the steps to accomplish this with a PL/SQL interface type.

© 2020 togglefox 39
Building custom ISG PL/SQL
REST web services

Part Six

TITLE BUILDING
OF THISCUSTOM ISG
CHAPTER
PL/SQL REST WEB
SHALL SERVICES
GO HERE

© 2020 togglefox 40
 BUILDING CUSTOM PL/SQL REST
WEB SERVICES
Before we begin creating our first custom web service, we’ll discuss considerations specific to
PL/SQL- based REST web services.

DE S IGN CO NS IDE RAT IO NS

Interface design
An ISG PL/SQL web service is based on a PL/SQL native interface type. The web service maps to a
PL/SQL package and the service operations map to procedures or functions in the PL/SQL package.
The PL/SQL interface is built and installed in the database server as you would generally any PL/SQL
package-based public API.

Interface testing
Building interfaces using PL/SQL is particularly beneficial for testing. By the time you are ready to
load the interface into the Integration Repository the API should already have been thoroughly tested
using isolated use case testing techniques. This significantly reduces the potential failure points for
diagnosing service errors.

Request HTTP methods

PL/SQL services may only send POST requests. GET requests are not supported.

Payload data types

The request payload may be a combination of Oracle data types, object types and tables of objects
(object arrays). These data types map to IN and IN OUT parameters in the interface method PL/SQL
package procedures and functions.

ISG supports multiple complex Oracle data types as input parameters. Complex structures may be
sent as any request payload to PL/SQL Services and will be mapped to Oracle objects for input into
the PL/SQL package procedure/function. All input parameters in the request payload are optional.

The response payload may also be a combination of Oracle data types, object types and tables of
objects (object arrays). These data types map to OUT and IN OUT parameters for the PL/SQL package
procedure, or to a return value for a function.

Payload element names map directly to the parameter names and appear in the WADL as uppercase. A
function return value will be given the procedure name in uppercase as the payload response element
name.

The ability to map any direction of procedure parameters to request and response payloads and to
define parameters as complex Oracle data types makes the whole process of defining payload
structure incredibly versatile.
© 2020 togglefox 41
Since complex Oracle data types may be fairly heavily utilized as the means for passing data in and out
of the service, the developer needs to be familiar with all aspects of traversing and populating Oracle
objects, tables of objects and working with nested objects.

Payload element names

ISG maps PL/SQL data names unchanged to payload element names. Underscores are retained and all
payload element names become uppercase. Elements of tables of objects (object arrays) will be named
the same as the object array element name with “_ITEM” appended to the name.

This means that however you name your procedure parameters, Oracle object type names, arrays and
attributes, these names will appear exactly the same in the WADL as uppercase names with
underscores. And any Clients that consume this web service will need to reference these same names.

This is not ideal. The general standard for naming of REST payload elements is camelCase, not
snake_case. Think customerTrxId, not CUSTOMER_TRX_ID. And there is simply no fix other than
remapping names through an intermediary such as Oracle Integration Cloud Service (ICS). However,
the element naming doesn’t limit the functionality in any way so it’s simply a cosmetic inconvenience.
And ISG has roughly 1,700 standard E-Business Suite interfaces that follow this convention so you’d be
in good company.

GET requests and path key parameters

The PL/SQL service type only supports POST requests. The GET verb is the standard for performing
reads (or queries) of REST resources and has the benefit of being cacheable.

The GET verb also introduces the concept of path key parameters which gives us the ability to include a
key value in the endpoint path, such as:

invoices/getInvoice/{invoice id}

PL/SQL services are unable to utilize either the GET verb or path key parameters.

Pagination
ISG has functionality to manage pagination and is especially useful when a remote application is
performing queries and requires pagination.

ISG implements pagination as parameters on the URL: offset and limit. Unfortunately, PL/SQL service
types are unable to utilize pagination, so there is no way to limit number of returned results. If this is
required, then you would need to build this mechanism manually within the interface.

Dealing with exceptions

ISG does not handle PL/SQL exceptions well. If your REST web service PL/SQL interface raises an
exception, ISG will return a generic service error message and a 500 service error. It’s not possible to
return anything meaningful in the payload. Details of the exception are logged into the WebLogic
Server EBS Domain server log, but this is of no use to the Client.

One possible solution would be to return a status code and message similar to how PL/SQL API
AR_INVOICE_API_PUB manages errors. Catch exceptions at the API procedure block level and
incorporate these values into your response payload.

© 2020 togglefox 42
Payload data format
As of EBS 12.2.7, ISG will not set Org_Id with a JSON payload. If you need to pass context values, then
I’d suggest using XML.

Hot deployment
It is entirely possible to hot-deploy PL/SQL interfaces and REST web services, meaning that the
service can be installed and deployed into a live system without needing to restart any components.
There are some caveats, however.

The deployment needs to avoid the possibility of Oracle error occurring:

ORA-6508 Could not find program unit being called

The safest way to approach this is for the interface to be a standalone package with no dependencies.
If the package has dependencies, then reinstalling can cause timestamp discrepancies resulting in
other areas of the application encountering ORA-6508 errors.

The interface must be a valid PL/SQL package and body that will install or reinstall without
compilation errors.

Immediately after installing, I recommend checking for and recompiling any invalid objects.

Tip: When reinstalling a service, the Global Cache needs to be cleared to trigger the creation of a new
WADL. Updating security, such as granting access to a new method, also requires the Global Cache to be
cleared.

CONCLUSIONS

Custom REST PL/SQL web services are pretty easy to build. As all functionality is encapsulated within
PL/SQL packages and objects, the only skill required to build ISG PL/SQL interfaces is good Oracle
development skills.

PL/SQL-based services can be hot-deployed, minimizing application and service outages. However,
PL/SQL interfaces are also the most limiting. The only available verb is POST. GET requests, key path
parameters and pagination are not allowed.

Payload attribute naming is limited to upper snake_case instead of camelCase, the general standard for
REST payload naming.

ISG has no ability to return details of raised PL/SQL exceptions. This is a disadvantage and needs to be
considered as part of the interface design.

Even after factoring in the above limitations, the ISG PL/SQL interface is still the simplest and easiest
way to deploy custom EBS REST web services. In Part 7, we’ll roll up our sleeves to build, load, deploy
and test a custom PL/SQL REST web service.

© 2020 togglefox 43
Building the demo PL/SQL
REST web service

Part Seven
BUILDING
TITLE OF THE DEMO
THIS CHAPTER
PL/SQL REST WEB
SHALL GO HERE
SERVICE

© 2020 togglefox 44
 BUILDING THE DEMO PL/SQL REST
WEB SERVICE

We’re now finally ready to begin creating a PL/SQL REST web service. To recap, we’re working on a
very simple business use case scenario: creating and querying invoices and invoice lines.

We’ll work through every step of the process, from creating the PL/SQL package to testing the REST
web service, demonstrating all the steps and skills involved.

BUILD THE CUSTOM PL/SQL INTERFACE

CRUD operations
Our demo web service will be a service-enabled PL/SQL package that CRUD-enables two custom
tables. CRUD is a common REST term and stands for Create/Read/Update/Delete, covering the four
basic functions that we need to perform on our resource (i.e., our database table). Note that CRUD-
enabling is simply exposing four service operations to perform these four operations. You can also
create additional service operations to do anything you like. Ensure that you’ve first downloaded and
installed the required files as described in Part 5.

Annotate the package header

ISG requires annotating of all PL/SQL package header procedures and functions that we wish to
expose as service-enabled. Only the annotated procedures and functions will be considered for loading
into the Integration Repository so it’s safe to include other public and private procedures and
functions in this package. First, the package header itself needs to be annotated in the following
format. This is an example from our demo package file XXTF_REST_INVOICES_PKG_S.pls.

/* $Header: $ */
/*#
* APIs to provide CRUD support for tables XXTF_REST_INVOICES and XXTF_REST_INVOICE_LINES.
* @rep:scope public
* @rep:product XXTF
* @rep:displayname XXTF_REST_INVOICE_PKG
* @rep:category BUSINESS_ENTITY XXTF_REST_INVOICES
* @rep:compatibility S
* @rep:lifecycle active
*/

Each procedure or function that you wish to load into the Integration Repository needs to be
annotated. These are the procedures and functions that will have the ability to be

© 2020 togglefox 45
service-enabled. This is another example from our demo package file
XXTF_REST_INVOICES_PKG_S.pls. Have a browse through the package header to get an understanding
of the annotations. Every parameter, whether defined as an IN or OUT (or IN OUT), needs a
corresponding @param annotation. If we are annotating a function, then the return parameter needs
annotating with @return.

/*#
* Creates a new invoice.
* @param invoice Invoice Record
* @return New Invoice Id
* @rep:scope public
* @rep:lifecycle active
* @rep:displayname Create a new invoice
* @rep:compatibility S
*/
function create_invoice(invoice in xxtf_rest_invoice_rec) return number;

LOAD THE CUSTOM PL/SQL INTERFACE INTO THE

INT E GRAT IO N RE PO S IT O RY

Parse the annotated header using the IREP Parser

The next step requires parsing the XXTF_REST_INVOICES_PKG_S.pls package header with the
Integration Repository Parser (IREP Parser). This validates the annotations and generates an
Integration Repository loader (iLDT) file.

The parser resides on the Application Server as a Perl script, so load the interface file onto your
Application Server operating system, owned by the applications user and source the Apps RUN
environment. For example:

. /u01/install/APPS/EBSapps.env RUN

This is the command to IREP parse the package header:

$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -g -v
FND:patch/115/sql:XXTF_REST_INVOICES_PKG_S.pls:1.3=XXTF_REST_INVOICES_PKG_S.pls

There are two things to note here. First, FND:patch/115/sql. FND should really be replaced with your
custom application short name. But with this demo it’s fine to leave as-is.

The second thing to note is the version number, 1.3. This will load just fine as a new install but for any
subsequent installs, the version number must increase otherwise the file will not be loaded.
Subversions such as 1.3.1 are allowed.

Now go ahead and run the IREP Parser command and you should see the below output:

# Interface Repository Annotation Processor, 12.0.0

#
# Generating annotation output.

© 2020 togglefox 46
# Processing file 'XXTF_REST_INVOICE_PKG_S.pls'.
# Using YAPP-based parser.
# Found a package-level annotation for 'XXTF_REST_INVOICE_PKG'.
# Found a detail-level annotation...
# Found a function named 'CREATE_INVOICE'.
# Found a detail-level annotation...
# Found a function named 'GET_INVOICE'.
# Found a detail-level annotation...
# Found a function named 'GET_INVOICES'.
# Found a detail-level annotation...
# Found a procedure named 'UPDATE_INVOICE'.
# Found a detail-level annotation...
# Found a procedure named 'DELETE_INVOICE'.
# Found a detail-level annotation...
# Found a procedure named 'CREATE_INVOICE_ID'.
# Found a detail-level annotation...
# Found a procedure named 'GET_INVOICE2'.
# Found a detail-level annotation...
# Found a procedure named 'GET_INVOICE3'.
# Found a detail-level annotation...
# Found a procedure named 'GET_INVOICE_WITH_STATUS'.
# Done all files.

You now have a newly generated XXTF_REST_INVOICES_PKG_S_pls.ildt file.

If you instead received this error:

Error Can't Locate Class/MethodMaker.pm

Then there’s an additional setup step that needs to be done first. Follow the instructions in this
Support document:

12.2: Script irep_parser.pl Fails With Error Can't Locate Class/MethodMaker.pm When Attempting to
Generate *.ildt File (Doc ID 2007651.1)

If you receive the below error, then your header-level annotation is incorrect and needs fixing.

XXTF_REST_INVOICES_PKG_S.pls:4:The package 'XXTF_REST_INVOICE_PKG' annotation was not found

at the required second line after the declaration. Parsing remaining annotations as orphans.
XXTF_REST_INVOICES_PKG_S.pls:18:Missing target name for orphan annotation
XXTF_REST_INVOICES_PKG_S.pls:20:The tag @rep:product belongs at the master level of the note for
orphan annotation
# Warning: Not generating iLDT for 'XXTF_REST_INVOICES_PKG_S.pls', invalid annotation.

And if you receive this error, then it means the PL/SQL package header file also contains a package
body. The IREP parser parses file with a package header only.

# Package body 'XXTF_REST_INVOICE_PKG' seen, skipping.

# Warning: Not generating iLDT for 'XXTF_REST_INVOICES_PKG.pls', file to be ignored.

© 2020 togglefox 47
If you’ve reached this stage successfully, then we have a newly generated
XXTF_REST_INVOICES_PKG_S_pls.ildt file.

Load the iLDT file into the Integration Repository

We’re now ready to load the iLDT file into the Integration Repository. Run the following command:

$FND_TOP/bin/FNDLOAD apps/password 0 Y UPLOAD $FND_TOP/patch/115/import/wfirep.lct

XXTF_REST_INVOICES_PKG_S_pls.ildt

This loads the interface specification into the Integration Repository and creates a log file. Open the log
file and you should see something like this:

Uploading from the data file XXTF_REST_INVOICE_PKG_S_pls.ildt

Altering database NLS_LANGUAGE environment to AMERICAN
Dump from LCT/LDT files
(/u01/install/APPS/fs1/EBSapps/appl/fnd/12.0.0/patch/115/import/wfirep.lct(120.8.12020000.3),
XXTF_REST_INVOICE_PKG_S_pls.ildt) to stage tables
Dump LCT file
/u01/install/APPS/fs1/EBSapps/appl/fnd/12.0.0/patch/115/import/wfirep.lct(120.8.12020000.3)
into FND_SEED_STAGE_CONFIG
Dump LDT file XXTF_REST_INVOICE_PKG_S_pls.ildt into FND_SEED_STAGE_ENTITY
Dumped the batch (IREP_OBJECT PLSQL:XXTF_REST_INVOICE_PKG C , PARAMS 2 0 ) into
FND_SEED_STAGE_ENTITY
Upload from stage tables

This indicates the integration interface has been successfully loaded into the Integration Repository.

If your EBS version is pre-12.2.7 and you are reloading an interface which is currently deployed as a
web service, then you may have experienced a load failure. If this is the case, then you need to first
undeploy the web service before loading the interface.

From 12.2.7 onwards, if the service is marked as deployed then the loader will automatically undeploy
the web service before loading the interface.

SERVICE-ENABLE AND DEPLOY THE CUSTOM PL/SQL INTERFACE TO A REST

WEB SERVICE

Confirm the interface has been loaded correctly into the Integration Repository
We now need to confirm the interface has been loaded correctly into the Integration Repository,
deploy the interface as a REST web service and assign grants. If you’re unsure of any of the following
steps, then revisit Part 2 to review how to use the Integration Repository.

Search for and open PL/SQL interface XXTF_REST_INVOICE_PKG. The Overview Tab shows our PL/SQL
interface we just loaded.

© 2020 togglefox 48
The product value is sourced from the @rep:product annotation and is not validated – this can
be anything.

Source Information region contains parameter values that were passed to IREP Parser. This is
where FND product code appears and for production deployments should really be your custom
application product code.

Source Version shows the version loaded during the Ihttps://togglefox.com/blog/oracle-ebs-12-

2-isg-rest-web-services-the-ultimate-guide-part-1/REP Parser stage. This needs to be
incremented with subsequent loads. Loading with the same version number will result in your
iLDT file being ignored and not loaded. You’ll also need to clear the Global Cache to trigger the
creation of a new WADL.

Deploy the interface as a REST web service

Click on REST Web Service Tab. Enter TfServicePlsql into the Service Alias, select all methods for
deployment and click the Deploy button.

Your PL/SQL interface should now be deployed as a REST web service.

© 2020 togglefox 49
Assign grants to the service
Click on the Grants Tab. Select all methods, click Create Grant then assign the appropriate grant.
Changes to grants require the Global Cache to be cleared so you’ll need to take care of this.

© 2020 togglefox 50
If you’re seeing grant creation confirmation, then we’ve reached a great milestone. You’ve
accomplished these key steps:

✓Created a PL/SQL interface with full CRUD support

✓Loaded it into the Integration Repository
✓Deployed it as a REST web service
✓Assigned user grants to the service methods

We now have a fully functioning PL/SQL REST web service ready to be tested.

TESTING THE CUSTOM REST WEB SERVICE IN POSTMAN

WIT H RE AD S E RVICE O PE RAT IO NS

We’ll be testing the web service in Postman. If you’re unfamiliar with Postman, then revisit Part 3
where the workings of what we’ll be doing is explained.

Import the Postman test cases and configure for your EBS installation
Import TfInvoicePlsql.postman_collection.json into Postman from the github library. You’ll need to
change the username, password and site URLs as explained in Part 3. All of our request headers are
now using JSON instead of XML. JSON has a more natural, modern feel, is less verbose and easier to
read. If you’re using the logging functionality as described during the install of the demo tables and
PL/SQL package in Part 5, issue the following on your application server from the applications owner:

tail –f /tmp/togglefox.log

Previously, when we seeded our demo data, we created two invoices with Invoice ID 1 and 2.

Test the Get Invoice REST service operation

Click on request Get Invoice, confirm INVOICE_ID is set to 1, and then click Send. Your response should
look like this:

© 2020 togglefox 51
And your logging output like this:

Congratulations, you’ve just successfully tested your first custom REST web service in ISG!

Scroll down in Postman to view the full response payload.

© 2020 togglefox 52
The payload root element, named GET_INVOICE, is not ideal. Relate this service method back to the
function in XXTF_REST_INVOICE_PKG_B.pls. Its definition looks like this:

function get_invoice(invoice_id in number) return xxtf_rest_invoice_rec

It’s a function so the return value doesn’t have a parameter name. And the annotations don’t let us
specify an element name so ISG just defaults it to the procedure name. Not great. But I’ll show you a fix
for this shortly. See the element marked array element? All elements of our LINES array will be named
LINES_ITEM. Also not great.

Test the Get Invoice2 REST service operation

Now execute service Get Invoice2 and relate this back to the procedure:

procedure get_invoice2(
invoice_id in number,
invoice_num out xxtf_rest_invoices.invoice_num%type,
invoice_date out xxtf_rest_invoices.invoice_date%type,
customer_num out xxtf_rest_invoices.customer_num%type,
lines out xxtf_rest_invoice_line_tab) is

See how all of our invoice elements are named the same as our OUT parameters? This is how we can fix
the previous problem of returning a function value with no parameter name. Simply define the
parameter with an OUT direction and give it a suitable name.

So to recap, IN and IN OUT parameters become elements in the request payload. OUT and IN OUT
parameters become elements in the response payload. Function return values are included in the
response payload, but the element name is set to the procedure name.

Testing Get Invoice for a service error

Now change INVOICE_ID to 4 (an invoice that doesn’t exist yet) and execute the service. You should
receive a service error.

© 2020 togglefox 53
And your logging output shows:

060520 22:53:31.3131 got no_data_found exception

If you check the PL/SQL code, we’re accommodating for no_data_found by raising an exception with a
meaningful error message.

exception
when no_data_found then
XXTF_SIMPLE_LOG_PKG.log('got no_data_found exception');
raise_application_error(-20001,'Invalid invoice id: '||v_invoice_id);
when others then
XXTF_SIMPLE_LOG_PKG.log ('got exception sqlerrm='||sqlerrm);
raise;
end;

The error message isn’t in our Service Fault payload, so where is it? It’s recorded in
$EBS_DOMAIN_HOME/servers/oafm_server1/logs/oafm_server1.out;

Caused by: java.sql.SQLException: ORA-20001: Invalid invoice id: 4

ORA-06512: at "APPS.XXTF_REST_INVOICE_PKG", line 136
ORA-06512: at "APPS.XXTF_REST_INVOICE_PKG", line 449
ORA-06512: at line 1

Not very helpful. So what can we do about this? I discussed in Part 6 about catching exceptions at the
interface procedure block level and incorporating exception data into your response payload as a
return code and status. Not ideal but it’s a workaround.

Test the Get invoice with status REST service operation

So click on Get invoice with status and execute the service. There’s two things to see here. First, see
how the invoice details in the response payload are wrapped in an INVOICE element? That’s the third
(and last) way to name your elements in the response payload. Have a look at the procedure; the
invoice object is an OUT named parameter.

procedure get_invoice_with_status(
invoice_id in number,
invoice out xxtf_rest_invoice_rec,
result_status out varchar2,
result_message out varchar2)

Second, we have two new elements in our response payload: RESULT_STATUS AND MESSAGE_STATUS.
These elements match the OUT parameters in the procedure. If you check the code, you’ll see we’ve
introduced a PL/SQL block wrapper to catch and return exceptions:

result_status := 'S';
begin
invoice := get_invoice(invoice_id);
exception when others then
result_status := 'E';
result_message := SQLERRM;
end; © 2020 togglefox 54
Testing for service errors with Get Invoice with status
Let’s test it. In Postman, change the INVOICE_ID in the request payload to 3 and execute the service.

"RESULT_STATUS": "E"
"RESULT_MESSAGE": "ORA-20001: Invalid invoice id: 3"

That’s an improvement. Not great design, but at least we’re now receiving our exception as a status and
message. Now try this. Change the INVOICE_ID to a non-numeric, for example “abc”, then execute the
service. And we’re back to our service execution error.

The log file $EBS_DOMAIN_HOME/servers/oafm_server1/logs/oafm_server1.out shows:

Caused by: oracle.apps.fnd.isg.common.error.ISGException: Adapter error - null : XSD object

conversion error.
An error occurred while parsing XML representing a Java object.
Unable to convert the XSD element INVOICE_ID whose SQL type is NUMBER and JDBC type is
NUMERIC. Cause: java.lang.NumberFormatException
Check to ensure that the XML data describing the object matches the definition of the element in the
XSD. This exception is considered not retriable, likely due to a modelling mistake.

This exception is raised by ISG before execution reaches our PL/SQL code so we can’t catch it. Any
Client that consumes this service and sends bad data won’t be able to receive anything meaningful to
explain the data conversion issue.

Test the Get invoice with ctx params REST service operation
Let’s move on. Click on request Get invoice with ctx params. As you can see, we’ve introduced a new
element, RESTHeader, which contains context parameters. ISG will additionally use these values when
initializing the session. These parameters don’t need to be in our PL/SQL package as ISG takes care of
processing the values for us.

Notice also that we’ve switched back to XML. There seems to be a bug in ISG with RESTHeader Org_id.
In JSON, the Org_id always comes through as 0, whereas it’s being set correctly in XML. I’ve checked
with Oracle Support and can’t get any hits on this bug. So XML it is.

<POST_Input>
<RESTHeader>
<Responsibility>FND_REP_APP</Responsibility>
<RespApplication>FND</RespApplication>
<SecurityGroup>STANDARD</SecurityGroup>
<NLSLanguage>AMERICAN</NLSLanguage>
<Org_Id>202</Org_Id>
</RESTHeader>
<InputParameters>
<INVOICE_ID>1</INVOICE_ID>
</InputParameters>
</POST_Input>

Update any values that won’t work with your instance (probably Org_Id) and execute the service. Check
your togglefox.log output and you’ll see FND_GLOBAL values as per our request payload.

© 2020 togglefox 55
Test the Get invoices REST service operation
Now click on request Get invoices. This service performs the equivalent of a query and returns
multiple invoices. Have a look at the corresponding PL/SQL to see how it works.

Have a play around with submitting query values and note the effect in the response. Currently we
only have two records to query, but soon we’ll be adding more. Revisit this service later when there’s
more invoices and the results will be more meaningful.

We’ve now fully tested the Read component of CRUD. Now let’s test Create, Update and Delete.

T E S T ING T HE WE B S E RVICE WIT H CRE AT E , U PDAT E AND

DE L ET E S E RVICE O PE RAT IO NS

Test the Create Invoice REST service operation

Click on request Create invoice. We have a new invoice all set in the payload for creating. Go ahead
and execute the service.

The response payload has returned INVOICE_ID 3, which is confirmation that a new invoice has been
created using this Invoice Id. The togglefox.log output has logged the creation.

© 2020 togglefox 56
A query of XXTF_REST_INVOICES shows a new row. XXTF_REST_INVOICE_LINES will also show a new
line for the invoice.

Now click on request Get Invoice, change INVOICE_ID to 3 and execute the service. And there’s our
invoice.
© 2020 togglefox 57
Test the Delete Invoice REST service operation
Click on Delete invoice, ensure INVOICE_ID is set to 3, and execute the service to delete the invoice. A
query of XXTF_REST_INVOICES shows we’re back to two records – INVOICE_ID 3 has been deleted.

Execute request Get invoice again and you should receive a service error as the invoice doesn’t exist.

Execute request Get invoice with status using INVOICE_ID 3. The return payload will be a little more
informative:

"RESULT_STATUS": "E",
"RESULT_MESSAGE": "ORA-20001: Invalid invoice id: 3"

Test the Update Invoice REST service operation

Now click on request Update invoice. We’re updating values for INVOICE_ID 1. This update is the verb
equivalent of a PUT, as opposed to a PATCH. A PUT request updates all values of the resource, whereas
a PATCH request only updates values for the supplied elements.

Execute the service. The togglefox.log output shows the parameters received and rows updated.

© 2020 togglefox 58
And a query of XXTF_REST_INVOICES shows INVOICE_ID 1 has been updated with the new values.

Have a play with the various services and see how this impacts the data. Revisit request Get invoices
and try out some query parameters now that you have more invoices. Check out request Create
invoice id and see how the response differs to Create invoice.

We’ve now demonstrated all CRUD operations on our demo invoice and lines, all implemented through
ISG PL/SQL REST web services. What you’ve learned here should be sufficient to use as a foundation
for going on to build your own services.

As you’ve seen, PL/SQL REST web services are pretty good at service enabling PL/SQL-based APIs. But
not great at implementing more of a pure REST model.

In the next chapter, we won’t be bound by any of the limitations of PL/SQL REST web services. We’ll be
building, deploying and testing a custom Application Module based REST web service, taking your ISG
REST web services to a whole different level.

© 2020 togglefox 59
 Building custom ISG
Application Module REST web
services

Part Eight

TITLE BUILDING
OF THISCUSTOM
CHAPTERISG
APPLICATION MODULE
SHALL
REST GO
WEB HERE
SERVICES

© 2020 togglefox 60
 BUILDING CUSTOM ISG
A P P L I C AT I O N M O D U L E R E S T
WEB SERVICES
In the previous two chapters, we completed building, deploying and testing a PL/SQL REST web
service. We covered its capabilities, but we also discussed its limitations. Application Module Services
take the level of functionality available a significant step further.

DE S IGN CO NS IDE RAT IO NS

Interface design
The foundation of Application Module Services is Oracle Applications Framework (OA Framework),
the same architecture that forms the foundation of E-Business Suite self-service pages.

OA Framework is based on the MVC (Model-View-Controller) architecture. And while all three
components are heavily utilized to build self-service pages, ISG only utilizes the Model (also known as
the server) component to build web services. The reason for this is because web services do not
require any visual elements, so the View (the web page itself) and the Controller (the glue that sticks
everything together) are not needed.

The server components of OA Framework are also known as BC4J components (Business Components
for Java). These components are:

• Application Module. The service operation maps to Java methods in the Application Module. The
Application Module also acts as the BC4J controller and is the backbone to managing interactions
with the other BC4J components.
• Entity Object. Performs a Java mapping to your Oracle tables and encapsulates business logic.
• View Object. The core component that application modules interact with to access the Oracle
database objects. View objects can map to an entity object or directly to a database object.
• Entity Associations and View Links. Establishes and manages relationships between BC4J objects.

The Application Module service type is far superior to the PL/SQL service type. The Application
Module opens up the integration interface and web service to all the rich functionality that OA
Framework server and BC4J components have to offer.

OA Framework and BC4J introduce not just convenience business object types for operating with the
Oracle database but a sophisticated layer of functionality and abstraction over the underlying data.
BC4J utilizes optimizations and caching, ultimately resulting in high-performance web services.

© 2020 togglefox 61
Being Java based, Application Module interfaces have the ability to leverage the rich ecosystem of Java
libraries, access to the operating system and, if security policies allow, to additional disparate systems
for the manipulation and collation of data. Pretty impressive.

Interface testing
Development of OA Framework applications takes place in Oracle’s JDeveloper IDE. This is a feature-
rich Java development IDE that integrates an EBS layer to support building OA Framework applications
and self-service pages. JDeveloper also includes a runtime environment that emulates the workings of
EBS; testing of self-service pages and application modules can take place right inside in the IDE.

Using JDeveloper it’s entirely possible to fully test Application Module interfaces before loading into
the Integration Repository.

Request HTTP methods

Both GET and POST requests are supported with Application Module Services.

Payload data types

Application Modules communicate payloads using Java Beans. A Java Bean is very similar to a POJO
(Plain Old Java Bean – who names these things?) but must also be serializable and define getters and
setters for the internal private fields. ISG performs Java Reflection introspection using Jackson and
JAXB to marshall-unmarshall the serialized payload into and out of Java Beans.

Java Beans may reference other Java Beans and build complex payload structures. These references can
be either singular or array, using simple Java arrays or sophisticated lists utilizing Java Collections.

The web service operation maps to a Java method in the Application Module class. All input is received
as method parameters and the response is returned as the method return value. Application Module
Services support both GET and POST verbs. The payload for a POST request is received into the
method as a Java Bean parameter. And the response, being the method’s return value, is returned as a
Java Bean. ISG supports the sending of URL parameters to Application Module Services in both GET
and POST requests. These parameters are also mapped to method parameters.

Payload element names

Java Beans maintain their original names in the WADL for both request and response payloads. Java
Bean and REST naming standards support camelCase (e.g., customerTrxId) and these standardizations
may be maintained in the WADL and service API. Unlike PL/SQL service types, you maintain full
control of all payload element names, including elements of arrays.

GET requests and path key parameters

Application Module types support the GET verb and path key parameters. This is a huge benefit in
terms of simplicity and performance that PL/SQL service types are not able to leverage. GET requests
are cacheable and send a more lightweight request for processing as well as giving us the ability to
include a path key parameter value in the endpoint path, such as:

invoices/getInvoice/{invoice id}

This forms part of the URL, is cacheable and can be stored in browser history and bookmarks.

© 2020 togglefox 62
Pagination
ISG supports pagination, but only for Java-based service types such as Application Module Services.
Pagination is useful when a remote application performs queries and requires paginating the data for
displaying to the user. The benefits include smaller response payloads and less redundant data.
Pagination functionality is managed by the Service instead of the Client.

To implement pagination in your service, it’s as simple as adding parameters offset and limit to your
method and ensuring they are appropriately annotated. ISG takes care of calculating and building the
subset of data when you return your Java Bean array or Collections list.

Dealing with exceptions

Application Module Services have full control of managing exceptions and returning a response to the
Client. Your WADL will show an element named ISGServiceFault as part of the output payload.

To configure your endpoint for handling exceptions, specify that the corresponding service method
throws ISGException. Throw the exception, defining an error code, message, resolution, and optionally,
a Throwable exception. This will return a payload something like:

<ISGServiceFault>
<Code>ISG_SERVICE_CUSTOM_ERROR_INVOICE_ID_NOT_FOUND</Code>
<Message>Invoice id not found: 49</Message>
<Resolution>Correct the invoice id and retry</Resolution>
<ServiceDetails>
<ServiceName>TfInvoiceAM</ServiceName>
<OperationName>getInvoice</OperationName>
<InstanceId>0</InstanceId>
</ServiceDetails>
</ISGServiceFault>

Having the ability to return a meaningful Service Exception is a huge advantage over PL/SQL Services.

Payload data format

Application module Services support both XML and JSON. As of EBS 12.2.7, I’m not having a lot of luck
using JSON in POST payloads, so for the time being I’ll be sticking to XML.

Hot deployment
Application Module Services cannot be hot-deployed. Deploying OA Framework requires building a
new customall.jar signed jar file and restarting the Fusion Middleware Services, oafm_server1,
resulting in a service outage.

CONCLUSIONS

Application Module Services are far superior to PL/SQL Services. Whereas PL/SQL Service
functionality is limited to PL/SQL programs, Application Module Services have a far greater reach: into
the Oracle database using BC4J components and also into the rich ecosystem of Java libraries for
extended functionality and access to the operating system and beyond.

Development is performed using JDeveloper, an intuitive, easy-to-use IDE that uses visual

© 2020 togglefox 63
elements to describe business entities and relationships. Interfaces can be fully tested in JDeveloper
before loading into the Integration Repository.

Payloads are sent and received using Java Beans, a simple-to-use object with getter and setter
convenience methods. Java Bean property names map directly to WADL element names, resulting in an
easy-to-understand interface that follows REST naming standards.

Both GET and POST requests are supported, a big step towards building a more pure REST model. GET
requests also support path key parameters and pagination, and additional URL parameters may be
passed into the service as method parameters.

Upon start-up, Application Module Services are provided with a fully Apps-initialized database
session, along with initialization of context parameters.

The service has full control over service exceptions and the returning of meaningful exception data to
the Client.

Building OA Framework applications requires a different level of expertise than building PL/SQL
services. The developer needs to be proficient with Java, JDBC and packaging and deploying OA
Framework applications onto an EBS 12.2 application server.

Factoring in the above, Application Module web services are the most sophisticated and feature-rich
way to build ISG custom REST web services. This service type is ideally suited for building REST APIs
for remote applications that require both querying and data changes. However, they are also the most
technically challenging to build.

Next, we’ll go through the process of building, deploying and testing a custom Application Module web
service.

© 2020 togglefox 64
 Building the demo
Application Module REST web
service

Part Nine
BUILDING THE DEMO
TITLE OF THIS CHAPTER
APPLICATION MODULE REST
SHALLWEB
GOSERVICE
HERE

© 2020 togglefox 65
 B U I L D I N G T H E D E M O A P P L I C AT I O N
MODULE REST WEB SERVICE
We’re now ready to build, deploy and test a custom Application Module REST web service.

We’ll be implementing the same functionality as we did with the PL/SQL based demo, but in a
different way. We’ll be bypassing the PL/SQL package that provides CRUD support and instead
utilize BC4J for all interactions with our base tables. This will showcase the abilities of BC4J in
the context of building REST web services.

Download the required files from github here.

Annotate the Application Module

As with PL/SQL-based interfaces, ISG also requires us to annotate Application Module interfaces.
This annotation takes place in the Application Module implementation class. The beginning of the
class is annotated in a similar way, describing the interface:

/**
* Application Module Service to provide CRUD support for tables XXTF_REST_INVOICES and
XXTF_REST_INVOICE_LINES.
* @rep:scope public
* @rep:product XXTF
* @rep:displayname XxtfRestDemoAM
* @rep:category BUSINESS_ENTITY XXTF_REST_INVOICES
* @rep:category IREP_CLASS_SUBTYPE AM_SERVICES
*/

The method annotations are also similar but need to express additional functionality available to
this service type. The first paraminfo defines a required key path parameter named invoiceId.
And the second paraminfo defines a class of Java Bean that we’ll be returning in the Response
payload. The httpverb defines whether this method may be exposed for GET and/or POST
service operations.

/**
*
* Get an invoice by key
*
* @param invoiceId Invoice Id
* @rep:paraminfo {@rep:required} {@rep:key_param}
* @return Invoice
* @rep:paraminfo {@rep:innertype xxtf.oracle.apps.xxtf.restdemo.service.beans.Invoice}
* @rep:scope public
* @rep:displayname Get Invoice
* @rep:httpverb get
*/
© 2020 togglefox 66
Have a browse through RestDemoAMImpl.java to see how the annotations apply to methods.

Optionally deploy to JDeveloper

If you are familiar with JDeveloper then deploy the xxtf package structure into your project directory.

Follow the instructions in SOA 12.2 Developers Guide, section 4-19 for prerequisites to EBS REST
development. The two libraries referenced in the guide, fndall.jar and isgagent.zip, can be found on
your EBS application tier at $AF_JLIB.

Let’s deconstruct the Application Module interface to show you the workings.

The Application Module is the interface, the equivalent of the PL/SQL package. It contains the interface
methods and is ultimately mapped to service operations.

The Entity Objects are the mappings to the Oracle tables XXTF_REST_INVOICES and
XXTF_REST_INVOICE_LINES. Entity Objects manage caching and all DML (data manipulation)
operations with the database tables.

The Application Module is the interface, the equivalent of the PL/SQL package. It contains the interface
methods and is ultimately mapped to service operations.

The Entity Objects are the mappings to the Oracle tables XXTF_REST_INVOICES and
XXTF_REST_INVOICE_LINES. Entity Objects manage caching and all DML (data manipulation)
operations with the database tables.

© 2020 togglefox 67
The View Objects are mappings to the Entity Objects and form the encapsulation for interacting with
the Oracle tables. All CRUD operations are performed through the View Objects and BC4J takes care of
the rest.

Note that there is one extra View Object – RestInvoiceQueryVO. The first two View Objects are used for
performing queries by primary key. RestInvoiceQueryVO is a specialized view object that we use to
perform more complex queries on the table columns.

The parent-child connectors define the parent-child relationship between the invoice and lines. These
are convenience business objects that perform subqueries and cascade-deletes, minimizing the
amount of code we need to write to enable these operations.

The Java Beans form the structure of our payloads and define a nested parent-child structure of
invoices and lines.

The service exception is the class we use to raise an exception identified by ISG for returning a service
exception payload to the Client.

The simple logging mechanism logs output to /tmp/togglefox.log on your application server. Have a
browse through the Java source files RestDemoAMImpl.java, Invoice.java, InvoiceLine.java and
DemoServiceException.java to see how incredibly simple it is to implement CRUD support for ISG REST
web services when utilizing BC4J to do the heavy lifting.

LO AD T HE CU S T O M APPL ICAT IO N M O DU L E INT E RFACE INT O T HE

I N T E G R AT I O N R E P O S I T O R Y.

Prepare $OA_JAVA on your Application Server

Copy xxtf.zip onto your Application Server operating system. Logon as the applications owner and
source the Apps RUN environment. For example:

. /u01/install/APPS/EBSapps.env RUN

Build the OA Framework custom application

Unzip xxtf.zip into $OA_JAVA. This will unzip a number of loader files and create an xxtf directory
structure.

At this point, you’ll need to create an xxtf custom application. Follow the directions in this blog post. If
you prefer to instead use your own custom application then all references to xxtf will need to be
changed to your own product short code.

The first stage is to compile the java code. Execute the following:

cd xxtf
find . -name *.java -exec javac {} \;

The subdirectories should now contain a class file for each java file. Next we need to create a
customall.jar file. Execute the following and follow the prompts;

adcgnjar

© 2020 togglefox 68
You should now have a new customall.jar file in $OA_JAVA. This is a signed java archive file that the EBS
Middleware will reference for OA Framework customizations.

Parse the annotated Application Module using the IREP Parser

The next step requires parsing our Application Module implementation class with the Integration
Repository Parser (IREP Parser). This validates the annotations and generates an Integration
Repository loader (iLDT) file in this directory. First, update some environment variables with extra
stuff we need:

export JAVA_HOME=$COMMON_TOP/util/jdk32
export CLASSPATH=$COMMON_TOP/java/lib/isgagent.zip:./ojdbc6.jar:./fndall.jar:$OR
ACLE_HOME/BC4J/lib/bc4jmt.jar:$ORACLE_HOME/BC4J/lib/bc4jdomorcl.jar:$CLASSPATH

Now we’re ready to run the IREP Parser. Change xxtf if you’re using a different custom application.

$IAS_ORACLE_HOME/perl/bin/perl $FND_TOP/bin/irep_parser.pl -g -v xxtf:patch/115/

java:RestDemoAMImpl.java:1.2=$OA_JAVA/xxtf/oracle/apps/xxtf/restdemo/server/R
estDemoAMImpl.java

Tip: If you need to reload at some later point, then make sure you update the version number before
loading.

There should now be a new RestDemoAMImpl_java.ildt file in the current directory. Our annotations
have been parsed and validated and placed into this new file. So far so good.

Load the iLDT file into the Integration Repository

We’re now ready to load this file into the Integration Repository. Run the following command:

$FND_TOP/bin/FNDLOAD APPS/password 0 Y UPLOAD $FND_TOP/patch/115/import/wfirep.lct

RestDemoAMImpl_java.ildt

This loads the interface specification into the Integration Repository and creates a log file. Check that
the log file doesn’t contain any errors.

Restart the Fusion Middleware Services

Final stage is to restart the Fusion Middleware Services, oafm_server1. Either perform a full restart of
WebLogic Server, or just simply restart the Fusion Middleware server, as I do:

$ADMIN_SCRIPTS_HOME/admanagedsrvctl.sh abort oafm_server1 -nopromptmsg

$ADMIN_SCRIPTS_HOME/admanagedsrvctl.sh start oafm_server1 –nopromptmsg

We’re now finished with the operating system tasks. The Application Module interface should now be
in the Integration Repository and ready for deploying. All the hard bits are behind us.
© 2020 togglefox 69
 S E RVICE - E NABL E AND DE PLO Y T HE CU S T O M APPL ICAT IO N M O DU L E
INTERFACE TO A REST WEB SERVICE.

Deploy the interface as a REST web service

In the Integration Repository, query the interface XxtfRestDemoAM and deploy to service alias
TfInvoiceAM. Note that we can now enable individual service methods for both GET and POST
requests. Leave these values as their defaults.

Assign grants to the service and clear the Global cache.

Have a browse through the WADL and you’ll see that the element naming is more REST-compliant with
camelCase names.

Assign grants to the service

Click on the Grants Tab. Select all methods, click Create Grant then assign the appropriate grant as
you’ve done before.

Tip: If you’re changing grants, ensure you clear the Global Cache.

We now have a fully functioning Application Module REST Web Service ready to be tested.

Testing the custom REST Web Service in Postman with CRUD service operations
We’re now ready to begin testing our service. We’ll be doing this in Postman, the same as the PL/SQL
service demo.

© 2020 togglefox 70
Import the Postman test cases and configure for your EBS installation
Import TfInvoiceAM.postman_collection.json into Postman from the github library. You’ll need to
change the username, password and site URLs as explained in Part 2.

Prepare for logging

The Application Module service has very basic logging installed using a custom logger. Output will be
written to /tmp/togglefox.log.

Open a putty session as the applications owner. Issue the following:

cd /tmp
tail –f togglefox.log

If you get the message file not found, touch the file then try the tail –f again. You should now be all set
for logging.

Test the Create Invoice REST service operation

Click on request Create invoice. There is a prebuilt invoice in XML ready to be created. Press Send to
send the POST request.

Check togglefox.log and you should see logging output for the service. Scroll down to see the response
payload in Postman. The created invoice is returned in the payload along with invoiceId. Make a note
of the invoiceId.
© 2020 togglefox 71
Test the Get Invoice REST service operation
Now click on request Get invoice and add the above invoiceId to the URL. Click Send to send the GET
request. You’ll see the invoice that you just created in the response payload.

Testing Get Invoice for a service error

Now change the invoiceId to a larger number (i.e., an invoiceId that won’t exist) and click Send. See
how we now have a meaningful Service Error payload returned? This has been programmed into our
service method.

© 2020 togglefox 72
Create and verify additional invoices
Now go back to request Create invoice, change some of the values and add some more invoices. Check
togglefox.log and the underlying tables XXTF_REST_INVOICES and XXTF_REST_INVOICE_LINES for
inserted invoice data.

Test the Get Invoices REST service operation

Click on request Get invoices and ensure the Params tab is the current tab. This is a GET based search
request that returns multiple records. The parameters are sent as URL parameters.

Try a few searches that will return multiple rows, for example setting invoiceDateFrom to an early date.
Make a note of the number of invoices returned.

Now have a play with limit and offset. Limit is the maximum number of records returned and offset is
the offset position from the start of the original record set. This is how ISG manages pagination.

© 2020 togglefox 73
•At the bottom of the response payload you’ll see ControlBean. This is echoing back your search
parameters. Some Clients would consume this data to manage pagination within their own application.

"ns:ControlBean": {
"ns:filter": null,
"ns:limit": "3",
"ns:offset": "1",
"ns:sort": null
}

Test the Update Invoice REST service operation

Click on request Update invoice. Update invoiceId and invoiceLineId using values from an invoice you
created, and change some invoice data. This request also demonstrates using context parameters in
Application Module services so update these values too. Click Send.

Check the togglefox.log file for your context parameter values and base tables for changes to your
invoice data.

Click Delete invoice to delete an invoiceId you created. Have a play with more requests. Any errors
you encounter along the way will be returned to you as a meaningful Service Error.

You’ve now experienced full Application Module REST web service CRUD operations on our base
tables. Notice how it feels more sophisticated and user friendly than PL/SQL web services? More
machine friendly, too. And generally just a more natural way of interacting with data.

PL/SQL web services feel more like service-enabled PL/SQL APIs, which is basically what they are.
Whereas Application Module web services implement a CRUD experience that’s closer to the natural
workings of a pure REST model.

Next, we’ll perform some comparisons and wrap up.

© 2020 togglefox 74
Putting ISG REST to work now

Part Ten
PUTTING ISG REST TO
TITLE OF THIS CHAPTER
WORK NOW
SHALL GO HERE

© 2020 togglefox 75
 P U T T I N G I S G R E S T T O W O R K T O D AY
If you’ve worked through each of the chapters and made it here, then you’ve developed a good
understanding of the workings of E-Business Suite ISG REST web services. We’ve covered what ISG is,
how it can benefit you and the architecture and workings of ISG.

You’ve also learned how easy it is to build, deploy, test and manage ISG web services, especially
compared to other REST-enabling J2EE technologies such as deploying directly onto WebLogic Server.

You’ve become familiar with the Integration Repository and how to discover and deploy web services.
We also explored the considerations for building your own custom REST services and went through
examples of building and testing both PL/SQL and Application Module REST web services. Phew!

So if you’re looking to build your own custom services, you should now have a fairly good
understanding of which service types and APIs are going to work best for you.

LET’S RECAP THE OPTIONS

PL/SQL Services
If all you need is to service-enable simple PL/SQL APIs as basic POST requests, then PL/SQL Services
may be the way to go. There are a few limitations, as we’ve discussed, but this is the simplest and
easiest way to deploy web services.

All a developer needs is good PL/SQL skills and maybe some understanding of working with Oracle
objects.

Application Module Services

If you’re looking to do something a little more sophisticated, then Application Module Services may
be a better fit. The ability to issue cacheable GET requests with key path parameters and pagination
makes this technology ideal for web applications using REST as a backend into your EBS system.

A WADL and API that follows REST-naming standards is a nice-to-have over the clunky feel of PL/SQL
web services. Being able to receive meaningful error messages as a response to the Client is pretty
nice too.

And as Application Module Services are built using OA Framework, the service has access to all the
goodness of BC4J and the Java ecosystem to perform a variety of integrations and advanced
functionality.

The downside is the breadth of skills required to pull it off: Oracle database, Java, OA Framework,
BC4J.

© 2020 togglefox 76
 One before the author

“
This e-book has provided you with a basic
understanding of ISG, but stay connected
to the togglefox blog, where there’s plenty
more to learn. Cheers and happy RESTing!

Subscribe to the togglefox newsletter

© 2020 togglefox 77
 ABOUT THE AUTHOR
About the author

togglefox founder, Michael Carroll

Michael has been immersed in Oracle database products, OA Framework
and E-Business Suite (EBS) applications, components and technology stack
for his entire career. He brings in-depth, expert-level knowledge and
extensive breadth of technical experience with current and legacy EBS
technologies to every project, client and product.

“For me, the creative challenge is working with my customers to deeply

understand their vision and help them meet—or exceed—it by architecting
well-thought-out, technically advanced solutions that they can rely on.”

Connect with me on LinkedIn.

© 2020 togglefox 78
 NEED HELP?
togglefox is the Oracle E-Business Suite SOA expert.
We can perform full builds of PL/SQL and Application Module web
services and provide expertise and advice on ISG architecture and
design across the full SOA Lifecycle. Get in touch below to discuss
how we can help you unlock your ideas and achieve your REST goals.

Y E S , W E N E E D T O TA L K .

© 2020 togglefox 79