ORACLE-BASE Blog Aggregator » Dimitri Gielis

E-Business Suite and APEX integration using APIs (1)

Dimitri Gielis — Sun, 05 Feb 2012 22:07:00 +0000

I didn't expect to many technical issues using E-Business Suite (EBS) APIs in APEX as it's basically a call to PL/SQL packages.

Next to that the EBS APIs seems to be well documented. I first didn't realise, but for a long time I was using the Oracle Integration Repository for EBS R11 (whereas I'm using R12).

For EBS R12 the Oracle Integration Repository ships as part of the E-Business Suite. To access it, in the Navigator menu, select the Integrated SOA Gateway responsibility, then click on the Integration Repository link.

Using the Oracle Integration Repository I would have found it more useful if I could define the number of results (maybe you can, but I didn't find that setting). At the moment I get only 10 results at a time, which is too low for me.

I also found it not that easy to find the right API to use. I guess it comes by experience. Next to that, the parameters are not always the same, so the API could be more consistent.

For example I want to create and edit a person. In the navigator I went to Human Resources Suite > Human Resource. That was logic for me. Next I looked into the list and saw Employee, so that was a logic choice for me. In there I found the HR_EMPLOYEE_API. That API allows to create an employee. So far so good, but where is the edit? I couldn't really find it, until I asked a friend and he told me to look for person. So when I went to HR Person(1) in the navigator I saw the HR_PERSON_API and in there you find the update and delete of a person.

When you look at the parameters; in HR_EMPLOYEE_API.CREATE_EMPLOYEE you see a parameter p_per_comments, in HR_PERSON_API.UPDATE_PERSON you see a parameter p_comments. It would have been easier if the parameters were consistent.

So once I got familiar with APIs, I started with the integration in my APEX app. Here are the steps to drill-down into a person from the people report (see previous post) and edit his or her email address.

Just as with the views I find it a good practice to not grant execute on the entire libraries of EBS to your own schema. I prefer to create my own packages in the APPS schema e.g. apex_api_pkg and call the correct API calls from there. The advantage is that you can add logging to your own package or do some other extra logic in there. For example APEX passes typically back values as strings, but some API calls need to be passed (next to varchar2) as a date, a number or a boolean. So you could choose to have all input strings in varchar2 in the apex_api_pkg and do the conversion inside the package to the correct one. In the below code I didn't do that, instead I went for an almost 1-on-1 mapping.

create or replace package apex_api_pkg
as

procedure update_person_email (
p_effective_date in date,
p_datetrack_update_mode in varchar2,
p_person_id in number,
p_email_address in varchar2,
p_object_version_number in out number,
p_employee_number out varchar2,
p_effective_start_date out date,
p_effective_end_date out date,
p_full_name out varchar2,
p_comment_id out number,
p_name_combination_warning out boolean,
p_assign_payroll_warning out boolean,
p_orig_hire_warning out boolean
);

end apex_api_pkg;
/

create or replace package body apex_api_pkg
as

procedure update_person_email (
p_effective_date in date,
p_datetrack_update_mode in varchar2,
p_person_id in number,
p_email_address in varchar2,
p_object_version_number in out number,
p_employee_number out varchar2,
p_effective_start_date out date,
p_effective_end_date out date,
p_full_name out varchar2,
p_comment_id out number,
p_name_combination_warning out boolean,
p_assign_payroll_warning out boolean,
p_orig_hire_warning out boolean
)
is
l_object_version_number number;
l_employee_number varchar2(4000);
l_effective_start_date date;
l_effective_end_date date;
l_full_name varchar2(4000);
l_comment_id number;
l_name_combination_warning boolean;
l_assign_payroll_warning boolean;
l_orig_hire_warning boolean;
begin
l_object_version_number := p_object_version_number;

hr_person_api.update_person (
p_effective_date => p_effective_date,
p_datetrack_update_mode => p_datetrack_update_mode,
p_person_id => p_person_id,
p_email_address => p_email_address,
p_object_version_number => l_object_version_number,
p_employee_number => l_employee_number,
p_effective_start_date => l_effective_start_date,
p_effective_end_date => l_effective_end_date,
p_full_name => l_full_name,
p_comment_id => l_comment_id,
p_name_combination_warning => l_name_combination_warning,
p_assign_payroll_warning => l_assign_payroll_warning,
p_orig_hire_warning => l_orig_hire_warning
);
end update_person_email;

end apex_api_pkg;
/

The next thing is to grant execute privileges on this package to your own user which is linked to your APEX workspace:

grant execute on apex_api_pkg to apex_ebs;

In the APEX application we create a new Form based on this procedure. I found that the APEX wizard didn't work in my case (but more on that in another post). I created a new Blank Page, add a region to it and a couple of items.

From my report I created an edit link to this new page and I pass the value of PERSON_ID to this page.

As I want to see the original data in my form (note that I didn't include all fields available in the API) I added a Fetch data process of type PL/SQL anonymous block with this code:

select full_name, email_address, effective_start_date, employee_number, object_version_number
into :P2_FULL_NAME, :P2_EMAIL_ADDRESS, :P2_EFFECTIVE_DATE, :P2_EMPLOYEE_NUMBER, :P2_OBJECT_VERSION_NUMBER
from apex_per_people_vw
where person_id = :P2_PERSON_ID;

When you hit the Apply Changes button I want the email address to update, that is why we have the Update email Process in Page Processing. The PL/SQL code is as follows:

declare
l_object_version_number number;
l_employee_number varchar2(4000);
l_effective_start_date date;
l_effective_end_date date;
l_full_name varchar2(4000);
l_comment_id number;
l_name_combination_warning boolean;
l_assign_payroll_warning boolean;
l_orig_hire_warning boolean;
begin
l_object_version_number := to_number(:P2_OBJECT_VERSION_NUMBER);

apps.apex_api_pkg.update_person_email (
p_effective_date => to_date(:P2_EFFECTIVE_DATE, 'DD-MON-YYYY'),
p_datetrack_update_mode => :P2_UPDATE_MODE,
p_person_id => to_number(:P2_PERSON_ID),
p_email_address => :P2_EMAIL_ADDRESS,
p_object_version_number => l_object_version_number,
p_employee_number => l_employee_number,
p_effective_start_date => l_effective_start_date,
p_effective_end_date => l_effective_end_date,
p_full_name => l_full_name,
p_comment_id => l_comment_id,
p_name_combination_warning => l_name_combination_warning,
p_assign_payroll_warning => l_assign_payroll_warning,
p_orig_hire_warning => l_orig_hire_warning
);
end;

I just do the necessary to update the email, I don't do that much yet with the output parameters, but you could transfer that back to the page if you wanted to. Also note that the package is in the APPS schema, so don't forget to add the owner in front of it. You could create a synonym in your own schema if you preferred. For the view I find it important to have those in my own schema too, for packages only if I wanted to add some extra logic to it.

Running the page shows you the below form.

In EBS there are different ways (UPDATE, CORRECTION, UPDATE_OVERRIDE, UPDATE_CHANGE_INSERT), to update the record, as I wanted to test them out, I added the Update Mode select list to the form. An UPDATE you can only do once per day, CORRECTION is what I used to update the same record multiple times.

Note that we still didn't login into our APEX application as an EBS user, so EBS doesn't know who I'm. As EBS is keeping an audit of the records, I (the logged in APEX user) won't be seen in those audit records, instead it will be a general one (EBS sysadmin I suppose). In the next posts we will authenticate with EBS integrate tighter.

In this post the purpose was to make an EBS API call to update an email address of a person. While playing with the EBS API I came across some challenges and I had to ask for advice to more experienced EBS people. Which will also be shown in the next post; where I will create a person with the API...

Previous related posts:

E-Business Suite and APEX integration using Views

Dimitri Gielis — Fri, 03 Feb 2012 11:36:00 +0000

Integrating APEX and EBS by using views is one of the easiest solutions (at first sight!).

This is the first scenario, where I have an APEX application and I want to integrate with data sitting in EBS.

Pre-requisites:

APEX is installed in the same database as EBS (see previous post).
My APEX application (actually Workspace) is linked to my own (non-EBS) Oracle schema.

If you want to view data coming from EBS in your APEX application, follow these steps:

Identify where the data is in EBS

If you are not familiar with the data model of EBS, it can be hard to find the right information. A good starting point would be the APPS schema, because that has access to the complete Oracle E-Business Suite data model. You can compare it with the SYSTEM schema, which has access to the entire database.

This pictures shows an overview of the APPS schema and base product schemas.

You can read more about the APPS schema in the EBS documentation.

In my example I wanted to find the people that are in my organisation (HR). I started to look for views that would give me that information. My first query was like this:

select object_name
from user_objects
where object_name like '%PEOPLE%'
and object_type = 'VIEW'
order by 1

That query returned 82 rows in my environment. In the results I saw e.g. ADS_PEOPLE_V, HRBG_PEOPLE, PER_ALL_PEOPLE, PER_PEOPLE, PER_PEOPLE_F etc.

I started to look at the definitions of those, but if you are not familiar with EBS it's hard to know which one is the one you need. So my recommendation would definitely be; when you are not that familiar with EBS, talk with somebody who knows more about it. For me that is the case, I only started to look into EBS and actually do something with it, a few weeks ago.

When I talked to somebody more experienced in EBS, he told me I probably wanted to look at PER_ALL_PEOPLE_F. Hmm, that wasn't in the result set of the above query. After investigating a bit more PER_ALL_PEOPLE_F is a synonym for HR.PER_ALL_PEOPLE_F.

I wanted to understand the naming convention in EBS a bit better e.g. for the PER%PEOPLE% objects.

Below I created a table how I interpret the EBS objects:

View /Synonym (^)	count(*)	count(distinct person_id)	Interpretation
per_all_people_f (^)	32295	18518	Synonym to real HR table
per_all_people	0	0	Needs EBS session (record inFND_SESSIONS) so it knows what you can see
per_all_people_d	32295	18518	All records but showstranslated text if user settings are applied
per_people	0	0	Needs EBS session, showseffective records based on user's date
per_people_f	32295	18518	EBS security implemented, youonly see records you are allowed to see
per_people_v	0	0	Needs EBS Session, includes alot of display text and is language dependend
per_people_x	18518	18518	EBS security implemented (sameas per_people_f), but limits to only the effective records (WHERE TRUNC(SYSDATE) BETWEEN EFFECTIVE_START_DATE ANDEFFECTIVE_END_DATE)

So to me PER_PEOPLE_X looks like a good candidate to use in my APEX application. If I'm not logged into the app as an E-Business user I still see all records that are effective at the time I run the query.

Create a view on top of the EBS views and use some naming conventions so it's easy to recognise which objects you created and are not native EBS ones.

create view apex_per_people_vw as select * from per_people_x
Grant access on that view to the schema that is linked to your APEX workspace and application

grant select on apex_per_people_vw to apex_ebs
Create a view in your own schema that selects everything from the view in the apps schema.
We do that so that the views are a one-on-one mapping between schema's, but they show up in the APEX wizards.

create view apex_per_people_vw as select * from apps.apex_per_people_vw
Create an Interactive Report on top of the view

This first examples shows how you can view data from EBS in your own APEX application. We can now create a calendar, charts etc. in APEX based on the data coming from EBS. In the next post I will show how you can edit this data.

Previous related posts:

E-Business Suite and APEX integration (overview)

Dimitri Gielis — Thu, 02 Feb 2012 11:41:00 +0000

For me there are two main use cases to integrate Oracle E-Business Suite (EBS) with Oracle Application Express (APEX):

In my APEX application I want to include/integrate data that exist in EBS
e.g. I want to include my employees that are in EBS HR

The EBS application needs to be customised and I use APEX to do that
e.g. I want to show a calendar with the birthdays of my employees
or I want a chart about the different age categories in my company
or I want to bulk update some information and there is no screen to do that

In both cases you want things to go seamlessly, you shouldn't be aware that you go from one technology to another. APEX and EBS data are in the Oracle database, so accessing data is not a big issue. Updating data in EBS you need to be careful with, as directly updating data through tables is not allowed (supported).

When I was reviewing ways to retrieve data from EBS and create/update/delete data in EBS from APEX I found a couple of methods that are interesting to explore further:

	Retrieve data from EBS	Update data in EBS
1. Views	X
2. APIs	X	X
3. OITs (Open Interface Tables)		X
4. Webservices (incl. BPEL/SOA)	X	X

There are other ways to integrate or interface with EBS e.g. through EDI (Electronic Data Interchange) and EAI (Enterprise Application Integration), but from an APEX perspective the above four seemed to me the most interesting ones to explore further. In my next posts I will dig into integrating APEX and EBS with the above techniques.

References to interesting readings:

Oracle Integration Repository
Oracle Release 12.1 Documentation Library (see Integration)
Oracle Apps Epicenter Blog

Previous related posts:

E-Business Suite and APEX installation
APEX and E-Business Suite integration (OBUG event)

E-Business Suite and APEX installation

Dimitri Gielis — Wed, 25 Jan 2012 15:05:00 +0000

Before doing the integration of Oracle Application Express (APEX) with E-Business Suite (EBs) you need to have both environments installed. The Oracle white paper talks about the installation of APEX, but not about installing E-Business Suite.

The white paper states; the prerequisites for the solution given are:

Oracle E-Business Suite 12.1.3 or above
Oracle E-Business Suite Patch 12316083
Oracle Database 10.2.0.3 or above
Oracle Application Express 3.2 or above

The first thing I needed was an E-Busisness Suite environment. Oracle provides some VM Templates for E-Business Suite 12.1.3. I wanted a complete demo system, like for example the HR schema in the Oracle database or the Sample Application in APEX. The VM Template for E-Business Suite includes the Vision demo.

I never installed EBs before, so I did some research how to do that. Finally I didn't proceed with installing E-Business Suite on our servers, as MCX was happy to provide us with a complete Oracle E-Business Suite 12.1.3 Vision installation on their servers. The version of the underlying Oracle database is 11.2.0.2.0. I also asked them to apply patch 12316083.

APEX needs to be installed on the same Oracle database as the Oracle E- Business suite database server.
We went with installing the latest version of APEX at the moment: APEX 4.1.

Installing APEX is not that hard, basically running some scripts. The only bit you have to be careful with is the choice of web listener. APEX supports three web listeners: mod_plsql, EPG and the APEX Listener.
The mod_plsql gateway is disabled by default by EBs R12, so you shouldn't go with that. The EPG is not recommended either as it will add additional load on the database server, so the best choice would be the APEX Listener. The APEX Listener is the recommended choice in any circumstance anyway, regardless of EBs. (on a related note; I'm giving a presentation about my experiences moving to the APEX Listener at OGh and ODTUG.)

So after installing APEX and using the APEX Listener on an EBs configuration, the architecture looks like this:

So now all the prerequisites are met and we can concentrate on the real integration part in the next post.

Previous related posts:

APEX and E-Business Suite integration

APEX and E-Business Suite integration

Dimitri Gielis — Wed, 18 Jan 2012 10:39:00 +0000

For a couple of years now companies like for example Popay integrate APEX with E-Business Suite.

The learning curve of APEX is not that high, so people with a (technical) E-Business Suite background should be up and running in no time.

In April 2011, Oracle released a whitepaper how to Extending Oracle E-Business Suite Release 12 using Oracle Application Express. Before, although it worked, you were a bit on your own incase you had issues, with the whitepaper things changed, so now you can call Oracle support as well.

In the next days I will share my experiences trying to get up-to-speed with integrating APEX with Oracle E-Business Suite. My background with Oracle E-Business Suite is limited, but I know a lot about APEX and that whitepaper should get me a big step further in integrating with E-Business Suite.

On the 15th of February, the APEX and E-Business Suite SIGs of OBUG (Oracle Benelux User Group) hold a half day (FREE) seminar about this integration too. So if you want to see this integration live or you want to hear from companies who are successful in it, come and join us. You find the agenda below:

SQL: Start day and End day of week

Dimitri Gielis — Wed, 08 Sep 2010 19:49:00 +0000

I just got an interesting question: how do you know for a date, in which week (Monday – Sunday) it falls.

I created a little test script to get 31 days of data:
(date_c is the same as date_d, but in a more readable output. c stands for char, d for date)

select to_char(sysdate + level, 'Day DD-MON-YYYY HH24:MI') as date_c,   (sysdate + level) as date_dfrom dualconnect by level <= 31

Next I used the NEXT_DAY function to get the first Monday after that date, and the same for the Sunday. As it will give you the results of the next week I had to subtract 7 days so I was sure it would fall under the week the date was in.
e.g. if you have a date Wednesday 8 of September, that person wanted to have Monday 6th-Sunday 12th. If I just did NEXT_DAY of 8-SEP I would get 13-SEP, that is why I first had to subtract 7 to go to a previous week and get the next Monday.
For the end date it's similar, but there you only have to subtract 1 day, as only the Sunday might be a problem, as the next Sunday is the next week.

So the final query became:

with t1 as (select to_char(sysdate + level, 'Day DD-MON-YYYY HH24:MI') as date_c,    (sysdate + level) as date_dfrom dualconnect by level <= 31 ) select date_c,        next_day(trunc(date_d)-7,'Monday') as start_day_of_week,        next_day(trunc(date_d)-1,'Sunday') as end_day_of_week  from t1

A more readable screenshot:

Update (after comments of Kees and Alex): the following solution looks even more elegant and is NLS independent:

with t1 as (select to_char(sysdate + level, 'Day DD-MON-YYYY HH24:MI') as date_c,    (sysdate + level) as date_dfrom dualconnect by level <= 31 ) select date_c,        trunc(date_d,'iw') as start_day_of_week,        trunc(date_d+7,'iw')-1 as end_day_of_week  from t1