Professional Documents
Culture Documents
2013 09 17usercommwebinarseries5pdf
2013 09 17usercommwebinarseries5pdf
Contents
Abstract: .................................................................................................................................................... 3
About the author: ..................................................................................................................................... 3
Chapter 1: What is an API and how are they used? ................................................................................. 4
API Definition ........................................................................................................................................ 4
The difference between a 'Public' API and a 'Private' API .................................................................... 4
How are Oracle Public APIs used? ........................................................................................................ 4
Why is it important to use Public APIs? ................................................................................................ 5
Chapter 2: How to identify available APIs................................................................................................. 6
Chapter 3: Working with APIs ................................................................................................................. 11
De-facto Oracle Standards: ................................................................................................................. 11
Less common but often seen in module-specific APIs........................................................................ 12
Chapter 4: What to do when the API call fails? ...................................................................................... 13
Different failure types ......................................................................................................................... 13
Error Messages.................................................................................................................................... 13
Is it hard to debug APIs? ..................................................................................................................... 14
Chapter 5: Performance.......................................................................................................................... 15
Chapter 6: Going beyond what Oracle gives you: Wrappers and Private APIs....................................... 18
Wrappers............................................................................................................................................. 18
Private APIs ......................................................................................................................................... 19
Chapter 6: API Wizard and Oracle APIs................................................................................................... 20
Chapter 7: Conclusion ............................................................................................................................. 21
Abstract:
Recent releases of the E-Business Suite have more than 2500 public APIs available which can be
used to greatly streamline operations and integrate with other applications, yet there is much
ambiguity about whats available and how to best leverage them. This presentation will help
you understand whats available, the best sources for documentation and examples, standards
common across public APIs, peculiarities in specific modules, and advanced topics like API
performance tuning and extensions.
One nice aspect of the integration repository is that it is intended to be updated whenever new APIs or
integration points are added, so if a recently applied patchset includes 20 new public APIs, they should
be documented here.
The integration repository is only available in R12. If you are still running R11, you must use one of the
other options to find API information.
irep.oracle.com
irep.oracle.com is Oracle's hosted integration repository. As of the writing of this document,
irep.oracle.com has been down for a number of months and Oracle has not said anything more than
what is contained in the following screenshot:
If and when iRep is available again, it can be a useful resource. Organizations running R11 can use this
to search for an API and then query their R11 system to see if that API existed as part of R11 (more than
50% will). Organizations on R12 can use it to determine if there are useful APIs in a later patchset than
the one they're currently on.
Of course, to be useful at all it needs to be online. If we all let Oracle know this is a useful resource,
perhaps they will put a little more effort into getting it back up
Oracle Documentation
You can find documentation on most versions of the Oracle EBS at:
http:// docs.oracle.com
API information can sometimes be found in the module-specific documentation. This information might
be provided in a technical/integration manual for the module or in the module user or reference guide.
Due to a lack of consistency, it takes some sleuthing to find API information in the Oracle documentation
but it can be worth it if it exists (which is not always the case) because the documentation has the most
precise explanation of the API rules and behavior, often with some sample code to help the reader
understand how to make a call using that API.
Web Search
Whether you use Google, Bing, etc., a web search is a very useful way to find API information. There is a
plethora of forums where questions about Oracle public APIs are asked and answered as well as many
useful blogs by developers who have successfully mastered one or more public APIs. The blogs are
particularly useful because they often contain sample code which you can use as a test case in your
environment with some tweaking.
API Wizard
API Wizard provides a free service at www.api-wizard.com/FindAPI.html where you can request info on
a particular business process and the API Wizard team will try to point you in the right direction.
SELECT
FROM
WHERE
AND
AND
AND
In 12.1.3 the above query returns over 500 matches. In a sense, this is great there is a lot of item APIs
that you can use but for the purposes of finding the right API, the field is still too large. A nice way to
parse this list down further is to think about one of the parameters that you would expect to enter or
update when working with this API. For item processing, you might search on ITEM_NUMBER (which
seems a little counter-intuitive since there really isn't an item_number field in the item tables, it's a key
flexfield but it turns out some public APIs to use this as a parameter name) or for INVENTORY_ITEM_ID
which you would definitely expect an item API to have as a parameter. However, if you just add the
parameter name 'INVENTORY_ITEM_ID' it actually doesn't restrict the resultset they all use that
parameter! OK, so it helps to pick something that is more specific for what you want to do. If you want
to update inventory items, look at mtl_system_items and try a field name from that table, like
'LEAD_TIME_LOT_SIZE'. Add that to your query as follows:
SELECT
FROM
WHERE
AND
AND
AND
We can review these APIs if needed to identify the correct one. It turns out that the one we want is
ego_item_pub.process_items!
In summary, querying dba_objects and sys.argument$ can be an effective way to find API information by
querying against the database.
10
11
A frequently asked question with respect to APIs and environment initialization is whether or
not APIs support multi-org security. The answer is that some do and some don't. Some APIs will
let you manipulate data in any org even if you've properly initialized a specific org. If this is the
case, you must handle the multi-org security in the calling program.
5. Flexfields
Nearly every public API allows you to import or update flexfield data.
p_record_version_number
No status parameter
No messages parameters
Special messages parameters
12
Error Messages
In general, the public APIs have one or more output parameters to which error messages are written.
The most typical parameters for this purpose are p_msg_data or x_msg_data. Some APIs have other
error output parameters, some write messages to error tables, others just put error messages in the
FND message buffer.
For those APIs that use p_msg_data or x_msg_data, you generally need to check the number of
messages being returned in another parameter, typically p_msg_cnt or x_msg_cnt, to determine if there
is one message or more than one message. When public APIs return a single message, they typically
pass that value to the p_msg_data or x_msg_data parameters. However, when public APIs return
multiple messages, they typically bypass the p or x_msg_data parameters and post their messages to
the fnd message buffer.
In the case where there are multiple messages for an API using p or x_msg_data or for those APIs
without those parameters and not using an error table, then you need to grab the messages from the
13
fnd message buffer using the public API fnd_msg_pub.get. Typically you would use the message count
from the API and run the fnd_msg_pub.get routine in a loop to grab all of the messages for a given API.
Example of getting API messages using fnd_msg_pub with output parameters p_msg_count and
p_msg_data:
IF nvl(p_msg_count,1) = 1
THEN
dbms_output.put_line(p_msg_data);
ELSE
FOR i in 1 .. p_msg_count
LOOP
dbms_output.put_line
(fnd_msg_pub.get
(fnd_msg_pub.g_next, fnd_api.g_false) || i);
END LOOP;
END IF;
END;
Sometimes the output will include characters that you will want to remove before presenting. For
instance, if you want to remove ASCII character CHR(0), you could do the following (assuming output is
in variable v_output_message).
v_output_message := replace(v_output_message, chr(0), ' ');
It's always more difficult to debug someone else's code than your own and it takes a methodical and
patient approach. Having said that, debugging an API isn't that hard. There is often a fair amount of
information available online and you can enter an SR with Oracle if the API is not working properly.
As discussed above, the APIs generate messages that can be very useful in debugging. Additionally, all
of the public API code is unencrypted, so it is easily viewable in user_source. This allows you to use all of
the same debugging techniques that you would with any other code, including things like tracing
which can greatly simplify the debugging process. Additionally, you can make a copy of the API and add
your own debug messages as a way to streamline the debugging process.
Software debugging is an art in and of itself; for this document, the salient point is that it is no harder to
debug a public API than any other software program that someone else has written.
14
Chapter 5: Performance
While the API code itself can't be changed, there are steps that can be taken to improve performance:
1. Trace and Indexes
Sometimes the right index can have a huge impact on performance. By running a trace on the
API, bottlenecks can be identified. To the extent that these bottlenecks are due to SQL queries
(which are used extensively during API validation), it's a fairly simple matter to identify and
create indexes to improve their performance. This is a process that can be performed iteratively
until all sql-based bottlenecks are resolved.
2. Parallel Execution
When a large number of records need to be processed, performance is often improved by
running the API in multiple, parallel executions. This will often result in greatly reducing the
overall runtime. Depending on the process and the data being updated, parallel execution can
potentially cause contention, so it's critical to test and assess the overall impact of this
approach.
3. Coordinating activity
Other system activity can affect performance of APIs and APIs can affect other system activity.
When processing a large number of records, it's a good idea to understand what else is running
in the system at the same time. Consider running the API at a time of low system utilization to
maximize performance.
4. Data preparation:
The Oracle database caches recent queries. This means that it leaves in memory information
that is recently requested (as well as information that is repeatedly requested). If it is possible
to order API executions so that data which is logically related is executed in a cluster, there is an
increased likelihood that validation queries will be resolved from cache rather than needing to
retrieve the information from the physical hard-drives, which can be a big time saver.
An example would be using an API to load customer invoices. Validations on invoices would
likely include verifying the party, the customer, the bill-to and ship-to locations, the payment
terms, whether the customer has a credit-hold, etc. If there are multiple invoices to load for the
same customer and these are processed one right after the other, there is a very good chance
that after the first execution, a great deal of the validation information will be in memory, which
will greatly improve performance.
Working Effectively with Oracle's Public APIs
15
5. Commit frequency
It's a general database issue but commit frequency can have an impact on API performance.
Committing represents making pending changes permanent. Pending changes are stored in a
special area of the database. While changes are pending, the database must do extra work to
keep track of those changes so that the person requesting the change can decide to commit
(save) or rollback (cancel) and to also provide other users with an unaltered view of the data.
When commits are too infrequent, this overhead can cause performance degradation as well as
potential contention, which can include unpleasant things like table and row locks. Frequent
commits can also have a performance impact, as commits have some overhead associated with.
It's beyond the scope of this paper to dive into this issue in more detail but it is worth noting
that finding the correct commit frequency can help improve performance.
6. Using Internal IDs
Some public APIs provide the option to pass either internal identifiers (e.g. party_id) or the more
common identifiers recognized by users (e.g. party_name or party_number). When the internal
identifiers are not passed, then the API will need to do a lookup at some point to derive those
values. Passing the internal identifiers directly to the API saves that step and can improve
performance.
7. Pre-validate
When duration is a concern, it can be helpful to pre-validate data before the actual API
execution. Pre-validation can help identify errors or other issues that will impact the actual API
run. By identifying and addressing potential issues ahead of time, when timing is not as critical,
the actual production run will be more streamlined. While some APIs have a validate option,
any API can be used in a 'validate' only mode by performing a rollback. This approach can be
used regardless of the size of the dataset to be processed.
8. Pinning
A public API is a pl/sql procedure within a pl/sql package. There may be one or more
procedures within any given package.
When an API is first called, that API along with all other procedures in its package, are loaded
into the databases shared pool (a memory area). For large and complex APIs, this can cause a
noticeable delay to the beginning of processing. This delay has a greater impact for APIs that
are run moderately frequently but with small data volumes, where each time the API is
executed it's already been aged out of the shared pool. For APIs where a lot of data is being run
Working Effectively with Oracle's Public APIs
16
at once, this is less of an issue as the first execution may be slow but subsequent executions will
be able to access the API within the shared pool.
To improve performance, APIs can be 'pinned' or kept permanently in the shared pool so that
they are always readily accessible. While doing this helps the API that has been pinned, the
reserved memory is not available for other processes. If the shared pool is too small, this can
lead to a performance hit somewhere else.
9. Patches
Oracle provides patches for poor performing APIs. If there is already a patch available for a
poorly performing API, then this is a great option. If there isn't already a patch, requesting one
from Oracle is a logical approach. They might also have performance improvement tips for
particular APIs.
17
Chapter 6: Going beyond what Oracle gives you: Wrappers and Private
APIs
The Oracle public APIs are powerful and can help process all types of transactions against Oracle. There
are times when requirements call for something above and beyond what the public APIs deliver. Those
requirements might include applying additional logic before or after a public API call or to interact with
data for which no public API exists.
Wrappers
Within the context of Oracle public APIs, a wrapper is a program which provides a shell for calling
multiple APIs, performing validations, and/or performing output translations. This allows organizations
to utilize the Oracle public APIs in a way that meets their precise processing requirements. Wrappers
are typically simple programs that perform a few specific tasks but can also be incredibly involved and
complex if requirements dictate.
Validations
Public APIs perform all of the validations required to determine whether the data passed creates a valid
Oracle EBS transaction. If it does not, the API returns with an error status. Some organizations have
rules that go beyond the standard Oracle EBS rules, which may be setup as form personalizations,
codified as on-insert or on-update database triggers, or controlled via a business process. Wrappers can
be used to enforce any additional logic or constraints when working with public APIs. For example,
staying with the customer example, if an organization has a rule that specifies the maximum credit limit
for a new customer as $10,000, that rule can be created as a validation in the wrapper which is tested
before calling the API. If data is passed to the wrapper with a credit limit greater than $10,000, then the
wrapper would raise an error and not call the API. Any type of validation can be performed in this
manner.
Message Translations
Many Oracle public APIs use fairly sensible and easy to understand output messages. However, in some
cases messages can be confusing. Wrappers can be used to simplify messages so that they are more
Working Effectively with Oracle's Public APIs
18
meaningful to the person receiving them. In order to use a wrapper in this manner, all of the potential
output messages should be identified and mapped to more readily understood messages.
Private APIs
Up until this point of the white-paper, every suggestion and example has focused on working with
Oracle's public APIs in a manner that is consistent with Oracle's software license and support terms.
There are some business processes for which Oracle has provided neither a public API nor an open
interface and, at times, there is a requirement to programmatically work with these processes neverthe-less. In general, there are two ways to do this: working with private APIs and base-table updates
neither approach is supported by Oracle.
A base-table update refers to directly manipulating data in the Oracle EBS base tables. This is generally
considered a high-risk proposition as underlying Oracle data is stored in a somewhat confusing manner
which is not totally normalized. If done incorrectly, there is a risk of data corruption. Never-the-less,
many companies do perform direct table updates from time to time. Risk is reduced by careful and
thorough analysis and testing,.
Better than performing base-table updates is to work with private APIs. These are similar to the public
APIs but their direct use is not approved by Oracle. However, they are used extensively within the
Oracle EBS: in fact, nearly every transaction in the Oracle EBS called both by user forms and by public
APIs result in private API calls.
While not supported, private APIs typically offer a fairly easy way to create or update Oracle
transactions with less risk than direct table updates. The key is to find the correct private API and the
easiest way to do this is to start with the user forms for the target business process and either open up
their code or perform traces while entering test data. Once the correct private APIs have been
identified, they are about as easy to work with as public APIs with the exception of Oracle not providing
any documentation or help. Private APIs are unencrypted pl/sql procedures which can be readily
reviewed, traced, and tested using the methods outlined in this document.
19
20
Chapter 7: Conclusion
Oracle has invested heavily, over the last several years, in exposing APIs for customer use. This is
evidenced by the significant increase in public APIs between R11 (1,500) to R12 (2,500). Additionally,
the introduction of the Integration Repository was a big step forward in making API information
accessible for customer use.
Public APIs offer a safe and effective way to perform Oracle EBS transactions and provide an excellent
mechanism for creating interfaces between systems, providing flexibility in data conversions, or
streamlining business processing within the API Wizard efficiency platform for Oracle.
While it isn't always easy to find particular APIs, they do exist for nearly every business process. With
some ingenuity and effort, they can be identified, understood, tested, tuned, extended, and utilized.
Public APIs represent the 'right' (i.e. safe and supported) way to work with your Oracle EBS data.
21