SOA (Service Orientated Architecture) is a term that has been emerging in the IT industry since I was at university (10 years ago). I have always been conscious of it’s presence but until late their has been no really mature products out there that would enable businesses to implement a SOA without having a highly technical and expensive support and development team behind them and not to mention an endless pit of money for R&D in middleware.

I have recently had cause to potentially look at how SOA could be realistically applied to one of my clients existing IT Infrastructure. This was not through a request from my client but driven by my desire to present a better IT solution to my customer that addressed a lot of the floors I have observed in their existing architecture.

I want to use this article to go back to basics and address what SOA really is now that it has been packaged and sold by many large IT vendors and how it could realistically be implemented in a large modern and distributed IT infrastructure.

As the evolution of the web surged forward a now well known markup language emerged which we all know and love as XML, XML (Extensible Markup Language) was the answer to making disparate systems talk to each other in the same language. But XML was nothing more that a structured data format which could be output and read by what ever system we want but how does any one system or program publish and consume this new XML data to and from other systems, up steps web services the next evolutional product on the road to SOA.

Web services is both a technology and a standard but put simply it allows system A to provide a service such as “Postcode Lookup” to system B using XML and the HTTP protocol (The same one as we use for the Internet). System B has no idea how system A provides it with street names based on it’s postcode input that system B provides and it doesn’t care.

So now we have a method of publishing and consuming our XML data in a controlled manner using a universal language and communication protocol that every system in the world can use, the web.

Based on XML and web services the term SOA emerged which consisted on a design principle of packaging system functionality as services and de-coupling systems that traditionally had been intertwined and reliant on each other using point to point interfaces.

SOA is all about systems talking to each other, this can either be internally within a business or externally to provide public services I.e. payment processing services.

So SOA is all about integration of systems, but why is this needed? A good question and one that I hope to explore further.

Let’s be honest with traditional point to point systems that use files and various persistent software communication protocols to talk to each other every time we add or change some part of the system we re-invent the wheel. Maybe it is a batch interface or near real time processing program each time we retrieve information from our database or present the data back to our users it is purpose built from scratch or we copy it and duplicate code. This is mainly because there is no culture of Software Re-use or if there is there is no means of cataloging and controlling the code that is already available in the system which would easily allow us to identify reuse opportunities. Here lies the first intangible benefit of SOA. SOA provides us with a structured development methodology and means to easily catalogue and identify opportunities for code re-use.

From discussing some of the benefits of SOA with traditional interface and point to point developers it has become clear to me that changing the mind set of technical, functional and business users is some what of a challenge. It is often very much the case that two sets of system implementers will get together and agree a set of rules with which they can enable their systems to talk to each other. The problem here is that the rules become dependent on each other, so how do we highlight the benefits of decoupling systems and making code on each side of the void more generic and thus reusable when the effort to do so is more complicated, more time consuming and potentially a waste of time.

My thoughts on this area are that the fundamental business design process needs to change, start there and implementers and developers will follow suite, don’t design an interface on system a to send a specific type of workflow notification to system b, design an interface to send any notification to any system that is interested, don’t tightly couple the systems by designing the content of your XML to fit system b, consider what systems c, d and e may want in the future (within reason) and make it extensible. In my opinion it’s only with this flexible and generic thought process that the concept of code reuse will truly be realised in large SOA implementations.

Until this time comes it is likely that SOA implementations will continue to be tactical solutions for a specific purpose rather than strategic roll outs at en enterprise level, thus SOA becomes an evolutionary product within an organisation, this needs to be understood centrally within an organisation such as an IS group and governed as it evolves to maximise the benefits and the chance that it will one day be the heart of the businesses technical infrastructure.

Please comment on this article, I would love to hear your thoughts.

I have recently had the need to look in detail at how workflow synchronises role information with Oracle HRMS in an R12 instance and wanted to publish my findings as there is not too much information out there about how this works in one place, please leave me a comment if you find any inaccuracies in this article and I will review the content. This article assumes you have some background knowledge regarding workflow notifications and the concept of a workflow role.

From R12 onwards incremental role synchronisation is a standard feature in Oracle HRMS, two views are provided called FND_USR_ROLES and PER_ROLE_ROLES_V which can be used to see what information workflow uses to populate the WF_LOCAL_ROLES table.

What is Incremental and Bulk Synchronisation?

Bulk synchronisation is the process of updating roles in the workflow table using a concurrent program called “Synchronize WF LOCAL Tables”, this program will take information from views delivered by different EBS modules and populate the WF_LOCAL_ROLES table using this information. This job can be run for individual or all modules and for the context of this article the process would be run for the HRMS module or FND module which would synchronise information from the user form or Person form.

Incremental Synchronisation is a term used to describe the process of an Oracle module updating the workflow roles in real-time as the information is changed in that module, for example if I create a new user record the information for that record will be automatically populated in WF_LOCAL_ROLES without the need to run Bulk Synchronization. Incremental Syncing is enabled as default in R12 for Oracle HRMS and the Bulk Sync concurrent program is provided for backwards compatibility and should not need to be run.

Incremental Syncing is standard in R12 however it is also available in R11 via relevant patches, see metalink note 171703.1

Where are role details taken from when a person record is linked to a user record?

Two roles can exist in workflow for a user/employee in EBS.

Internal Employee Role

At the point that the person record is created an additional person role will be created in wf_local_roles. The role name will be along the lines “PER_ROLE:771703” (where 771703 indicates the person id from per_all_people_f) with all details such as e-mail address, display name, description being populated from the person record and in addition user preferences are now used to populate Notification Preference, Language and territory from FND_USER_PREFERENCES. The incremental synchronisation role that is used to populate WF_LOCAL_ROLES is PER_ROLE_ROLES_V.

A person record with a valid internal role can be identified with the following SQL:

SELECT * FROM wf_local_roles WHERE name =’PER_ROLE:’||:person_id and orig_system = ‘PER_ROLE’

N.B A PER_ROLE role is created regardless of if a user account is linked to the employee.

User Role with/without person record linked

This is one role that is maintained at a user level and dependant on if you have an employee linked to the user record or not the role will source its email, description and preferences information differently. The role name will be the user name held in the FND_USER table.

The view FND_USR_ROLES is used to populate role information to the user/employee role in the event that your user is linked to a person record or not. If the record is not linked to a person record the view simply takes the information including the e-mail address from the FND_USER table. In this situation certain information such as Notification Preferences, Language and Territory are defaulted in this instance to “MAILHTML’, ‘AMERICAN’ and ‘AMERICA’ respectively. This results in the role being automatically eligible to receive e-mail based notifications for processes such as the email reset function where an email can be sent to a user account based role with a link to reset their password. A user only based role can be identified in the workflow tables using the following SQL:

SELECT * FROM wf_local_roles where name = :fnd_user_name and orig_system = ‘FND_USR’

In the event that a user record is linked to a person record using the user form the following happens:

1. The email address is blanked out from the user form

2. The FND_USR role is updated with the information from the existing PER_ROLE role that belongs to the linked employee and already exists in the wf_local_roles table (See Internal Employee Role above).

3. The orig_system partition in WF_LOCAL_ROLES is updated to PER

From this point the PER role and the PER_ROLE role are synchronised and any workflow notifications sent to the role associated with the user account i.e. user from FND_USER will use the details copied from the PER_ROLE role which are originally captured from the person record such as email address and the user record in FND_USER will no longer be referenced, it could be argued that since a new person role is created (PER_ROLE) which already sources its details from the person form why does the standard FND user account role (FND_USR) also have to be switched to a (PER) role and source its details from the same location, it would make sense to have one user level role and one person level roll? This is an annoyance to some customers of Oracle who very often have to migrate their email details over from the user form to the person form when implementing HRMS.

A user with associated employee record can be identified in the workflow tables using the following SQL:

SELECT * FROM wf_local_roles WHERE name =:fnd_user_name and orig_system = ‘PER’

Workflow Notification Behaviour with standard and ADHOC Roles

Workflow notifications can be sent to standard or adhoc roles. Standard roles are roles that are maintained in embedded workflow out of the box using incremental or batch synchronisation. Standard roles are maintained for a variety of modules but for the context of this article roles are created and maintained for users, linked users (User linked to a HRMS record) and HRMS people (See previous section). The 3 types can be referenced as FND, PER and PER_ROLE. The FND role becomes a PER role at the point the user records are linked. This partition can be found in the WF_LOCAL_ROLES table in the “ORIG_SYSTEM” column.

Adhoc roles are roles that have been created using the workflow API’s at run time by a program or process. An adhoc role will have an ORIG_SYSTEM of “WF_LOCAL_ROLES”. The actual role name can vary dependant on the process.

To demonstrate how standard and adhoc roles are used by a workflow process we will look at the “Password Reset” process that is accessible in R12 from the login screen link “Login Assistance”, we will examine how the associated workflow process selects the correct role to send the notification to and how the roles have been populated based on the setup.

By default the reset password workflow will try to send the notification to the actual user role, that is the role with the same name as the user requesting the reset.

Scenario 1 – User account exists but no person record has been linked.

In the event that no email address exists on the user account then an error will be displayed when the user tries to request a reminder email:

“Your email address is either invalid or an account matching the entered email address could not be found. Please contact the System Administrator for further assistance.”

If the email address is populated the password reset workflow will select the role based on the user account so it will identify the role name as “TURLEYK” (My username in “FND_USER”), the email and description will be taken from the FND_USER table and populated to WF_LOCAL_ROLES with “FND_USR” in the ORIG_SYSTEM column. By default the email preference is set to HTML.

Scenario 2 – User account has been linked but no email address has been entered on the person record.

In the event that no email address exists on the user account as well as the person record then an error will be displayed when the user tries to request a reminder email:

“Your email address is either invalid or an account matching the entered email address could not be found. Please contact the System Administrator for further assistance.”

If an e-mail address does exist on the user account record (PER role due to the fact that it is linked to a person record) but not on the person record then something unusual happens here. As mentioned previously once a user account is linked to a person account the email address is sourced from the person record, but in this instance the person record email is not populated so workflow does not have a standard role with an email address on despite the fact that the user record has a valid email address populated.

In this situation the email reset workflow process is intelligent enough to know that an email address exists on the FND_USER table for the user name but no standard role exists with the email address synced. The result is that the workflow will build an adhoc role called FNDPWD__ and store it in wf_local_roles using the orig_system of “WF_LOCAL_ROLES”. This role will be populated with the e-mail address from fnd_user and the notification will be sent to this adhoc role.

Scenario 3 – User account has been linked and email address has been entered on the person record.

In this instance the password reset workflow will select the role based on the user account so it will identify the role name as “TURLEYK” (My username in “FND_USER”), the email and description on this role will be taken from the PER_ALL_PEOPLE_F table via the PER_ROLE_ROLES_V view and populated to WF_LOCAL_ROLES with “PER_ROLE” in the ORIG_SYSTEM column by incremental synchronization.

The above examples should give you an idea of how workflow processes can use roles to send notifications and how those roles are maintained. The behaviour will vary between workflow processes but this article should give you the knowledge to recognise how roles are used and thus how to implement them in your workflow processes.

All OAF Pages use a number of ”View Objects” to execute SQL queries against the E-Business Suite Database. These View Objects are actually XML files on the application server that contain an SQL query, this XML file is used in conjunction with a Java Utility called the JPX Importer to load a pointer to the content of the XML file into a number of Database tables that EBS uses to identify which SQL queries it should be executing when a page loads. These tables are collectively known as the MDS (Meta Data System) Repository. The MDS holds a lot more than just SQL query definitions but for the scope of this article we need not cover the other content. 

For this article we are going to use the Oracle Projects Search screen as our OAF web page on an R12 instance. We are going to modify the SQL that is used to query back a list of projects so that the SQL only returns projects that are within their current start date and end date as opposed to returning all projects.

Analysis

First of all we need to identify which “View Object” we will be working with, to do this we will need to activate OAF diagnostics. To do so locate the profile option “FND: Diagnostics” and set it to “Yes”. Now take a look at the page we are going to be extending…

Fig 1

 By turning on the “FND: Diagnostics” profile option you will now be able to see two new links on the page. The “Diagnostics” link which will appear in the header and the footer of the page and the “About This Page” link which will appear in the footer only. In order to identify the VO that is being used by the page we will first examine the “About This Page Link”. 

When you click on the “About This Page” link you will see an array of tabs all of which do various tasks which we can use as OAF developers however for the purposes of this article we will be looking at the default “Page” tab which you see when the page opens. 

All OAF pages are made up of a number of BC4J (Business Components for Java) and Web elements known as the MDS content or “Web Beans”. The BC4J content exists as compiled java code and XML under JAVA_TOP on the application server and the web content exists as meta data in the MDS Repository. The web content is organised into a tree structure i.e. you have a page which contains a table which contains fields etc… When the page loads this “Bean Hierarchy” is rendered according to its structure and this structure is what we can see in the “Page Definition” section of the Page tab. Click the “Expand All” Link. 

If you are familiar with OAF development this screen will be very apparent to you as representing the page structure layout that you are used to seeing in JDeveloper when building a page and navigating it will be simple. If you are not used to OAF page development and you are simply trying to identify the SQL behind this page then examine the View Object Column until you see populated content, you should then be able to determine that the “Name” column holds content such as “messageStyledText: Project Manager” and that this is describing the “Project Manager” column that we see on the OAF page. We can also see that there is a collection of columns indented below the “Bean” “table: My Projects Result Container” which refers to the result table that we see on the page.   

Fig 2

Implementation

Now that we have identified the VO we need to extend, oracle.apps.pa.project.server.ProjectListGenVO, we need to setup our JDeveloper environment so that we can create a new View Object that contains our extended code. If you have not already got your JDeveloper environment setup then do so now, you can read how to at the Apps Tech Blog post “OAF – Downloading and Configuring JDeveloper”. 

Start JDeveloper and follow the instructions below. Please note that this article only covers the procedure for JDeveloper 10g. The process although similar is slightly different in 9i. 

In the Applications Navigator right click the Applications Node and select “New OA Workspace” 

In the file name box enter a suitable file name, if you are often working with different clients then it may be an idea to call this XXCLIENT.jws, if you are working for your own company you may want to call it XXCUST.jws, the workspace name is however completely personal preference and up to you as a developer how you organise your workspaces and projects within JDeveloper. Leave the directory path as your default myprojects folder in your JDev Home, ensure that the “Add a New OA Project” check box is selected. 

Fig 3

Select “OK”. 

The new project wizard will now be launched, select “Next”. 

In the project name enter a meaningfull name, I recommend that the project name be pertinent to the piece of work you are doing i.e. XXCUST_projects_list, leave the default directory as your myprojects folder in the JDev Home. For a VO substitution the default package name will need to represent the VO file path on JAVA_TOP with the exception that it must be prefixed with your custom application shortname, the prefix can actually be anything you like however it is recommended that the custom application shortname is used, in this example we would specify the default package as  xxcust.oracle.apps.pa.project.server 

Fig 4

Click “Next” 

Ensure that the “Use repository for design time” box is not selected and click “Next”. 

Select your DBC file, enter your applications username and password, enter ICX as the responsibility application shortname and responsibility key. For more information regarding this setup step including obtaining your DBC file and setting up your user account please refer to the Apps Tech Blog post “OAF – Downloading and Configuring JDeveloper”. 

Fig 5

Click “Next” 

Click “Finish” 

Next we need to copy the existing VO component from the apps server and import it into our local file system. In order to do this we must setup a file structure on our local machine in our project folder so we can copy the VO into it. Log onto the applications server and navigate to $JAVA_TOP, change into the oracle/apps/pa/ directory (Or which ever product top you are working with) 

Fig 6

Zip the project application directory and save it to a directory that you can ftp from. i.e. zip -r $HOME/pa.zip pa 

FTP the pa.zip file in binary mode back to your local machine and extract it to your user JDev Home under myprojects/oracle/apps/ (You will have to create the directory structure manually if it does not exist), you should also extract the contents to your myclasses folder in the same way i.e. myclasses/oracle/apps/ 

You should now have the following file structure in your local file system under the oracle.apps directory in myprojects and myclasses 

Fig 7

Click the “Refresh” button on the Applications Navigator tab of JDeveloper, you should notice that a new business components package under oracle.apps.pa has now appeared. 

Fig 8

 Now that we have the existing projects business components in our environment we need to create our new VO object that will be used in place of the existing one. Remember we do not customise existing components in OA Framework we extend the existing ones which means creating a new object that extends the original and we notify the framework that we want to use the new object rather than the seeded one. 

We now need to test that the VO we want to substitute does not contain any java errors following the download. Navigate to the VO in the applications navigator window i.e. Application Sources > oracle.apps.pa > project > server > ProjectListGenVO, right click the VO and click edit (If you have not already done so you will now need to configure your database connection, for more details on how to do this see the apps tech blog article “OAF – Downloading and Configuring JDeveloper”). If the VO opens without error then we are ready to move onto the next step. If you get an error message saying that java errors exist in either the voNameImpl.java file or the voNameRowImpl.java file then you will need to obtain the original source files for the files listed as being in error and add them to your myprojects folder in the relevant directory and recompile the project, unfortunately Oracle do not allow you to obtain the source files and you may need to employee the services of an Oracle consultant who would have access to the files. 

Before closing the base VO window take a look at the “Java” settings and make a note of the boxes that are checked/unchecked, we will need this for later. 

If you havn’t already done so Close the Edit VO window. 

Right click on the project node and select “New”. Select “View Object” under Business Tier > ADF Business Components and click “OK” 

The View Object Wizard has been launched, click “Next”. 

Specify the package as xxcust.oracle.apps.pa.project.server (This component package will hold our extended object so we need the custom application prefix). Specify the VO name as the name of the custom application concatenated with the orginal VO name i.e. XxcustProjectListGenVO. Select the original VO in the “extends” box using the browse button and select the original VO i.e. oracle.apps.pa.project.ProjectListGenVO 

Fig 9

Click “Next” 

On step 2 of the VO wizard you can see the SQL statement that we first saw when we were analysing the page. For this example we are simply going to wrap the SQL as follows and add an additional where clause statement: 

SELECT * FROM (ORIGINAL_QUERY) WHERE trunc(sysdate) between project_start_date and nvl(project_end_date,sysdate) 

Click the “Test” button to validate that your modified SQL is valid. 

Click “Next” until you reach the end of the wizard, If you encounter the following error at step 4 “Each row in the query results column msut be mapped to a unique query attribute in the mapped entity columns” then their is something wrong with the base VO, in this example I did experience this error and found that the original VO SQL had 3 missing aliases that the view object attributes were referencing, In order to correct the error you must make the change to the base VO by editing the SQL, I successfully added the missing aliases and then re-ran the create new VO instructions above and it worked correctly. 

Once we have clicked through to the end of the wizard the final step is to create the relevant java files. When a VO is implemented we always generate a voNameImpl.java file but we dont always have a voNameRowImpl.java file, the best way to tell which files to implement is to look at the java screen for the seeded VO and ensure that our new VO has the same settings. 

In this case we need both so our final wizard screen would look like this 

Fig 10

Now click “Finish” and the new business components package will be created containing our new extended VO. 

Fig 11

Right click on the custom business components package and select “Make”, this will compile the Impl and RowImpl java files. 

Now that we have our newly extended VO we need to create a substitution file. This substitution file will be an xml based file that will contain a mapping from the old VO to the new VO, we will use this file to tell Oracle Application to use our newly extended VO rather than the old one by uploading it to the MDS repository using the JPX Import tool. 

Right click on your project node (XXCUST_projects_list) and select “Project Properties”, click “Substitutions” under the “Business Components” menu. In the “Available” pane select the original VO i.e. oracle.apps.pa.project.server.ProjectListGenVO, and in the right hand “Substitute” pane select the new VO i.e. xxcust.oracle.apps.pa.project.server.XxcustProjectListGenVO. Once you have done this click the “Add” button and select “OK”. 

Fig 12

In your JDev home in the myprojects folder you will see a file called projectName.jpx in my case it would be called XXCUST_projects_list.jpx, this is your substitution file and we will use this later when we deploy the substitution.

Deployment

 

In order to deploy our solution to the actual ebusiness suite instance we need to copy the relevant java and xml files to java top and also upload our substituion file to the MDS repository. You can do this just by simply transfering the files using an FTP tool however I find it is best to create an archive file that will retain the folder hierarchy and allow you to issue a single transfer and unpack command. For a large OAF project we may have files that have to be transfered to different locations and because of this I tend to create 3 types of jar files called BC4J, MDS and SRC. These three files will contain the BC4J files like class files and VO’s, the MDS files such as pages and regions and the java source files. 

Following the transfer we can issue a java call from the command line on the apps server to perform the MDS upload. 

For this example a VO substitution only involves BC4J objects and java source files, the solution does not require that we package up our source code so for the sake of simplicity I will just create one archive file called BC4J.jar 

Right click on the project node and select “New”, select “Jar File” under the General > Deployment Profiles menu. Name the profile as something meaningful, in this example I will stick to convention and call it  ”XXCUST_PROJECTS_LIST_BC4J” . Leave the directory set as the default myprojects folder and click “OK”. 

In the deployment profile properties deselect the “Include Manifest File” option. On the filters menu deselect the root folder and navigate to the xxcust.oracle.apps.pa.project.server directory, select all the files in this directory and click “OK” 

Fig 13

You will see in JDeveloper that you now have a deployment profile listed under you application sources node, right click the .deploy file and select “Deploy to JAR file”, You will see a deploy tab appear next to the compile log and this will confirm that the deployment was successfull. If you experience issues with compilation i.e. there are issues with some of the files in your project that are not connected to your custom files then simply remove them from the project by selecting the top level component package i.e. oracle.app.pa and click the “Exclude Project Content” button (Little file symbol with a red cross on it) and re-try the deployment. 

Fig 14

Inspect your myprojects folder and you will see you now have a “Deploy” directory, in this directory will be your jar file ready for deployment to the apps server. 

Now that we have both our BC4J objects for java_top and our substituion file for the MDS we need to transfer them both to the apps server, FTP both the files (remember to send the jar file in binary format and the jpx file in ascii) to a convienient directory on the apps server. 

Now extract the jar file to java_top i.e.

cp home/kturley/*.jar $JAVA_TOP 

jar -xvf /$JAVA_TOP/XXCUST_PROJECTS_LIST_BC4J.jar 

Now upload the substitution file to the  MDS using the following command: 

java oracle.jrad.tools.xml.importer.JPXImporter $HOME/kturley/XXCUST_projects_list.jpx -username apps -password xxxx -dbconnection “(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=hostname.oracle.co.uk)(PORT=1551))(CONNECT_DATA=(SID=XXXXX)))” 

Make sure you specify the correct values for 

1. Path of you jpx file 

2. apps password 

3. host name 

4. port 

5. database SID 

Finally restart the webserver so that you can see your changes in the application 

For R11: 

$COMMON_TOP/admin/scripts/$TWO_TASK*/adapcctl.sh stop
$COMMON_TOP/admin/scripts/$TWO_TASK*/adapcctl.sh start 

For R12: 

$INST_TOP/admin/scripts/adoacorectl.sh stop
$INST_TOP/admin/scripts/adoacorectl.sh start  

This article will describe the process for downloading & installing the correct version of JDeveloper for development on your instance of E-Business Suite. It will discuss how to identify the correct version of JDeveloper to use and how to configure your OAF environment on your local machine.

Oracle JDeveloper (JDev) is the development tool we use to develop Oracle Applications Framework components, due to variations in the framework different versions of Oracle Applications require development to be performed on different versions of JDeveloper or at least the OAF flavour of JDeveloper. JDeveloper can be downloaded from metalink however prior to visiting meta link you will need to establish which version and patch set you are running as regards Oracle Apps.

To identify the correct version of Oracle Applications Framework we need to activate diagnostics. You can do this by ensuring the profile option “FND: Diagnostics” is set to “Yes”. Close your browser session and restart Oracle Applications, Log in and click the “About this Page” Link which can be found in the page footer.

Fig 1

When the “About Page” loads click the “Technology Components” Tab. You will be able to identify the version of Oracle Applications from the OA Framework version.

Fig 2

Fig 3

JDeveloper comes as a zip file and does not require any installation as such. We do however need to follow a few setup instructions to get up and running particularly if you are a developer that works on various versions of E-Business suite and thus will be using different versions of JDeveloper.

First unzip the JDeveloper zip file to a convenient directory. I recommend that you create a separate directory such as C:\JDeveloper\JDEV_R12_RUP4 . This will allow you to create further directories in the event that you download more versions and they will not conflict with each other. Once unzipped you will have three directories:

JDEVBIN: This is the JDeveloper software directory and contains the executables for the IDE.

JDEVDOC: This contains all help documentation including the OAF Developer Guide which will become invaluable to you as an OAF developer

JDEVHOME: This is where by default all of your project files and code will be created, sort of a my documents folder for JDeveloper.

Once installed we will need to create some shortcut links for your desktop so that you can launch JDeveloper and access the Developer Guide. Locate and create shortcuts for the following files for your desktop:

C:\yourInstallDirectory\jdevbin\jdev\bin\jdevW.exe for windows and jdev.exe for any other operating system.

 C:\yourInstallDirectory\devdoc\index.htm

The jdevW.exe/jdev.exe links will launch JDeveloper and the index.htm will open the help documentation which contains a link to the OAF Dev Guide.

Before we launch JDeveloper we will complete one more configuration task and re-point the JDEVHOME directory to a central location i.e. My Documents or another partition where you keep all your files. This process is very helpful when it comes to running multiple versions of JDeveloper. Right Click on the “My Computer” icon and select the “Properties” option. Click the “Advanced” tab and then “Environment Variables”. Create a new user variable by clicking on the “New” button and enter JDEV_USER_HOME as the environment variable name and the path to your central directory as the value i.e. d:\my_files\jdev_home.

Fig 4

Click OK and close the “My Computer” windows.

When JDeveloper is launched it will now automatically save your files and settings to the central user home rather than the default home in the installation directory. Always ensure that you back up your central user home to prevent the loss of critical project files.

 Now we have our JDeveloper environment ready we need to get some environment specific setup completed so that you can interact with your E-Business Suite instance. In order to enable us access to apps we will need to obtain the DBC file and copy it to our local machine. The best way of doing this is to log into the application server using a tool like putty and obtain the file from $FND_SECURE by ftp using a tool like winscp, failing this you could obtain it from your DBA. Once you have your DBC file create a folder in your JDEVHOME directory called dbc_files\secure\ (Remember the JDEVHOME is the location that we assigned to the JDEV_USER_HOME environment variable in the previous steps) and copy the DBC file to it.

Fig 5

 

Now that we have our DBC file we can open JDeveloper and configure the database connection. Launch your JDeveloper download by clicking the jdevW.exe link that we created earlier.

Fig 6

Click on the Connections tab and right click the “Database” folder and select “New Database Connection”.

Fig 7

If you are using JDeveloper 9i then the Database folder can be found in the “System – Navigator” pane under the connections node, you will not have the Connections Tab.

Fig 8

 

You will be presented with the Database Connection Wizard. Click “Next”

 

When prompted enter a name to represent your connection, this can be anything you like however I have just used the database SID for simplicity

 

Fig 9

Click “Next” and enter the database username and password, this will need to be the apps account and password, leave the role field blank.

 

Fig 10

Click “Next” and enter the database hostname, port and SID

 

Fig 11

 Click “Next” and click “Test Connection”, you should receive a successful connection message.

 

Fig 12

 OK, now that we have the database connection configured we need to make sure that we can connect to our E-Business suite instance from within JDeveloper. We can use the toolbox tutorial files to do this which get shipped with the JDeveloper build.

Click File > Open and navigate to JDEV_USER_HOME/myprojects and select the file toolbox.jws If you are running JDeveloper 10g you will automatically be in your JDev User Home with 9i you may have to navigate there manually due to a bug in the IDE.

If you are running JDeveloper 9i select the “Show Categories” icon, this will help us identify the test jsp page to run later.

Fig 13

If you are running JDeveloper 10g select the “Applications Navigator” tab to see the opened workspace. 

 

Now that we have the toolbox workspace open we need to modify the project settings in Tutorial.jpr, navigate to the project node under the toolbox node and right click on the “Tutorial” node and select “Project Properties” in 10g and “Project Settings” in 9i.

 

You will be presented with a properties screen with several options in the left hand pane, expand the “Oracle Applications” node and select the “Run Time” sub menu item. Your screen will look similar to this.

 

Fig 14

Configure the credentials as above. Select your DBC file that we downloaded earlier, enter YOUR username and password for Oracle Applications and ensure that you have the responsibility “Framework Toolbox Tutorial” assigned to that logon. To check that your logon is configured correctly run the SQL:

select fnd_web_sec.validate_login('<UserName>','<Password>') from dual;

This should return ‘Y’ as the result indicating that your account is setup correctly.

Repeat the above test for the Guest account specified in your DBC file (Usually GUEST/ORACLE).

Enter ICX as the application short name and FWK_TBX_TUTORIAL as the responsibility, these parameters define which responsibility we will be running the project under.

Select OK when you have finished.

We are now ready to run the test project:

In JDeveloper 9i navigate to the file test_fwktutorial under Workspaces > toolbox.jws > Tutorial.jpr > HTML Sources > test_fwktutorial.jsp

In JDeveloper 10g navigate to the file test_fwktutorial under Applications > toolbox > tutorial > Web Content > test_fwktutorial.jsp

Right click the test_fwktutorial.jsp node and select “Run” in 10g and “Run test_fwktutorial.jsp” in 9i

Fig 15

 

If you are running on a remotely hosted environment prepare for this process to be slow (anywhere from 2 – 10 minutes dependant on your network) you are now effectively running an embedded server from your local machine and a lot of information will be pinging to and from your machine and the application server on the environment, normally these two components would be hosted on the same server and thus the performance will be seriously degraded.

 

Once complete you should see the below screen.

 

Fig 16

 

Congratulations! You have successfully configured JDeveloper.

 

If you experience problems configuring your JDeveloper version then refer to meta link note 330236.1 for guidelines on raising a service request.

 

This is one of several “Oracle Applications Basics” articles that are aimed at oracle applications program developers and cover a number of commonly used development elements when interacting with the E-Business Suite.

This article covers how to establish an Oracle Applications Context within your SQL session ( i.e. Toad/SQL Developer) when developing outside of the application or when a requirement exists to interact with Oracle Applications from an external source.

When logging into Oracle Applications a number of “Session” variables are assigned that are used during the time you spend logged on, these variables and application profile options are referred to collectively as the Apps Context. Some of these variables are used to restrict access to data through the use of secured views. You may find that certain views within Oracle Applications do not return data when you know that they should do, this is probably because you have not set your “Apps Context”.

A custom program being developed within the application should not need to establish its own context, that is established when the user logs in via the standard Apps login screen. You may find that certain products such as workflow will want you to establish a session manually within your code in certain scenarios, for details on this you will need to consult the product documentation however as a general rule you should not need to establish a context yourself if you are developing your code to run within Oracle Apps and you are doing so with the correct responsibilities and users with correct security access.

To set a global context session you can use the following code:

The values for user_id, resp_id and resp_appl_id can be obtained by running the following query:

Substitute <USER_NAME> for the oracle applications user name for the account you wish to use. This query will then return a list of the assigned responsibilities for that user.

Once executed you will have established a context within your database session and will be able to see profile option values at user/responsibility/site level aswell as retrieve data from organisation secured views.

R12 Considerations

With the introduction of R12 Oracle introduced the concept of “Multi Organization Access Control” which allowed a user to operate across different organizations using a single responsibility. The introduction of this feature meant that the fnd_global.apps_initialize function was no longer sufficient to establish the context session and an additional API was introduced called MO_GLOBAL.

Within R12 after calling the apps_intialize API you must then call MO_GLOBAL.INIT(‘<PRODUCT_SHORT_NAME>’) where PRODUCT_SHORT_NAME is the product you are coding for i.e. ONT, PER, AMS etc…

To read more about Multi Organization Access Control and how it can impact your code see Meta Link note 420787.1 “White Paper: Oracle Applications Multiple Organizations Access Control for Custom Code”.

Download This Code From The Download Folder

This is one of several “Oracle Applications Basics” articles that are aimed at oracle applications program developers and cover a number of commonly used development elements when interacting with the E-Business Suite.

This article covers the use of application messages and focuses on the use of the pl/sql package FND_MESSAGE as well as the use of the generic loader to download and upload messages between your environments.

During the development of custom programs it is common to use customised messages in our code to implement error messages, confirmation messages, log entries etc…

These messages will be seen and interpreted by your end users and it is important to ensure that these messages can easily be changed in the event that your customer wishes to do so. The reason for changing them maybe simple such as a spelling mistake or more complex like assigning a generic error code to all error messages used by the system to aid in support activities.

The Oracle E-Business suite provides a message library that allows us to implement our messages and at the same time provides the facility to easily change these messages via the E-Business suite standard user interface.

This article will cover the creation of messages via the E-Business suite user interface and the implementation of message retrieval via the pl/sql API package provided with Oracle Applications.

Creating an Oracle E-Business Suite Message

To create a message in the E-Business suite message library you will need the “Application Developer” responsibility. Once logged in navigate to Application Developer > Application > Messages. This will launch a form and it will look like figure 1:

Enter a unique name for your message, for custom messages this is often in the form XX_NN_MM where

XX is the custom schema prefix you are using (Usually just XX)

NN is the module code or short name for the extension that the message belongs

MM the message description

I would advise that you always use a unique NN portion to the message name to make it easy for you to identify your messages i.e. you can query back all messages for XX_MYMOD%, this will help you later when you are compiling your messages for your installation scripts.

Select the language that your message is written in and the application that the message belongs, this will usually be the custom application setup by your development team lead. If you don’t yet have a custom application and you are developing custom application modules then you will need one.

Enter the message text in the “Current Message Text” box.

Click the save icon.

For message naming conventions you should always consult your build standards documentation for the customer you are implementing for to ensure you have observed any standard development approach that may have been implemented at your site.

Example:

Figure 2

Retrieving a message using PL/SQL

Once we have saved the message in E-Business suite via the standard message form we need to interact with the message library via our custom code to enable us to implement the message in the way it was intended to be used.

In order to retrieve the message from the database we need to use a few different standard foundation API’s in the FND_MESSAGE package. An E-Business suite message should be retrieved as follows:

1. Clear the current session of any message variables that may already be set

2. Tell E-Business suite which message you wish to retrieve

3. Retrieve the actual message string

4. Clear the session (Not required but good practice)

This process will look like this in your PL/SQL

For more details regarding fnd_global.apps_initialise see my other blog entry “Oracle Apps Basics – Session Context”

set serveroutput on 

DECLARE  

 my_message VARCHAR2(100); 

BEGIN  

 --Initialise Apps Session

 fnd_global.apps_initialize( user_id      => 1290

                          ,  resp_id      => 50257

                          ,  resp_appl_id => 10003

                           );

 --Clear the existing session  

 FND_MESSAGE.CLEAR;

 --Tell ebusiness suite which message you want (custom application short name/message name)   

 FND_MESSAGE.SET_NAME('XX','XX_MYMOD_MESSAGE1');

 --Retrieve the message  

 my_message := FND_MESSAGE.GET;    

 --Output the message  

 DBMS_OUTPUT.PUT_LINE(my_message); 

END; 

anonymous block completed 

Test Message 1

Using Tokens

The Oracle E-Business suite allows the substitution of tokens within a message string to enable the programmer to add dynamic content to the message at run time. This is useful for adding things like timestamps and user names to the existing message.

We will expand the example used in the previous section to demonstrate the use of tokens in our messages.

Open the E-Business Suite message creation form and query back your previous message.

In order to insert a token into a message it is necessary to prefix the token with a ampersand e.g. modify your message text from “Test Message 1″ to “Test Message Retrieved at &TIMESTAMP by user &USERNAME”

Tokens can be called what ever you want but they must be prefixed with an ampersand and they must be in uppercase.

To demonstrate the use of our new tokens we will add an additional 2 API calls to our previous code which will set the tokens to the desired values and then resolve the message using the substituted values, our code will now look like this:

 
set serveroutput on
 
DECLARE
 my_message VARCHAR2(100);
BEGIN
 --Initialise Apps Session
 fnd_global.apps_initialize( user_id      => 1290
                          ,  resp_id      => 50257
                          ,  resp_appl_id => 10003
                           );
 
 --Clear the existing session
 FND_MESSAGE.CLEAR;
 
 --Tell ebusiness suite which message you want (custom application short name/message name)
 FND_MESSAGE.SET_NAME('XXC','XX_MYMOD_MESSAGE1');
 
 --Set the timestamp message token with the current database timestamp 
 FND_MESSAGE.SET_TOKEN('TIMESTAMP',to_char(SYSDATE,'DD-MM-YYYY HH:MI:SS'));
 
 --Set the username message token with the current applications user
 FND_MESSAGE.SET_TOKEN('USERNAME',FND_GLOBAL.USER_NAME);
 
 --Retrieve the message
 my_message := FND_MESSAGE.GET;
 
 --Output the message
 DBMS_OUTPUT.PUT_LINE(my_message);
END;
 
anonymous block completed
Test Message Retrieved at 02-04-2009 03:16:59 by user TURLEYK
 




 

Downloading and Uploading Messages using the Generic Loader

The generic loader can be used to download/upload existing E-Business Suite messages.

To download our example message we would use the following command at the Unix prompt on the mid-tier:

 
FNDLOAD apps/apps 0 Y DOWNLOAD $FND_TOP/patch/115/import/afmdmsg.lct MSG_XX_MYMOD_MESSAGE1.ldt 
FND_NEW_MESSAGES APPLICATION_SHORT_NAME='XX' MESSAGE_NAME="XX_MYMOD_MESSAGE1"
 

To Upload our example message we would use the following command at the Unix prompt on the mid-tier:

FNDLOAD apps/apps 0 Y UPLOAD $FND_TOP/patch/115/import/afmdmsg.lct MSG_XX_MYMOD_MESSAGE1.ldt

Download This Code From The Download Folder

I wasn’t sure what to write about on my first blog entry so I waited for inspiration and it came to me in the form of Function Result Caching in Oracle 11g.

I have recently had cause to use this feature in one of my recent customer engagements to assist with SQL performance. Im sure that anyone in the Business Intelligence arena or anyone who has had to write complex performant SQL queries will appreciate the difficulties that come with using functions in your SQL. Traditionally we work around these performance problems by removing the function calls from our queries and replacing them with other joins and complex SQL logic to achieve something that more often than not is very simple.

The use of functions in SQL simplifies the main query making it more readable and more importantly maintainable. The Oracle 11g database now comes with a new caching feature that will help you overcome some of these difficulties in the right circumstances. Say you had a function that is referenced several times in the same SQL query (maybe you want to include it in your select and where clause or maybe in a decode function and it must be used twice). Each time the function would probably be receiving the same parameters, why does it have to be executed multiple times? Maybe you are interrogating a bunch of records with a date column and you want to work out what financial period that date is in according to your business calendar, maybe these records all have similar dates, say 1 million records all with dates in January. Obviously there will be a fair amount of repetition and you may only be passing 31 distinct values to the function throughout the SQL query execution, Why do we need to execute the function 1 million times?

With the introduction of function result caching in Oracle 11g we no longer have to worry about wasted effort executing functions. By simply adding a declaration of RESULT_CACHE to your functions you can tell Oracle to only execute the code in your function once for every unique set of parameters that are supplied to that function. In the event that a duplicate call is made to that function then Oracle will simply return the same value that it did last time by recalling it from the cache which it updated the first time the function was called with that set of parameters.

The best thing with this new feature is that the cache operates from the shared pool (Global System Memory) rather than the PGA which only operates at a session level. Meaning that all of your users will benefit from the cached values. An additional feature can be used with function caching which enables you to specify that the cache should be refreshed following a DML operation on a specified table. By adding the RELIES_ON(TABLE_NAME) clause to the end of the RESULT_CACHE declaration you can clear the cached values for the function which will force the function body to execute the next time it is called regardless of the fact that it may have been called before the table update with the same parameters. This allows you to take advantage of the fact that your function may use underlying tables to calculate it’s return value and following an update the data it is returning from the cache maybe stale.

This new Oracle database feature will undoubtedly be a massive help to any of you out there writing big complex SQL queries that use functions or PL/SQL batch processes. I know I will be using it a lot. I have included an example below of the code in action, please note the fact that when specifying a dependant table you do not do so in the package specification (If you are using packages) it must only be added as an option in the package body, failure to do this will result in the following error from the compiler:

• Error(3,12): PLS-00999: implementation restriction (may be temporary) RELIES_ON clause is disallowed on function declaration

Further reading and examples:

http://www.oracle-developer.net/display.php?id=504

http://www.oracle.com/technology/oramag/oracle/07-sep/o57plsql.html

Example:

--Create a temporary table
CREATE TABLE FUNCTION_CACHING_TEST (COLUMN1 VARCHAR2(10));

--Create the package spec
CREATE OR REPLACE PACKAGE FUNCTION_CACHING_TEST_PKG AS
  FUNCTION DBMS_OUTPUT_TEST(p_test_number VARCHAR2) RETURN VARCHAR2 RESULT_CACHE;
END FUNCTION_CACHING_TEST_PKG;

--Create the package body
CREATE OR REPLACE PACKAGE BODY FUNCTION_CACHING_TEST_PKG AS
  FUNCTION DBMS_OUTPUT_TEST(p_test_number VARCHAR2) RETURN VARCHAR2 RESULT_CACHE RELIES_ON(FUNCTION_CACHING_TEST)
  IS
  BEGIN
    DBMS_OUTPUT.PUT_LINE('DBMS_OUTPUT_TEST Function body executed');
    RETURN 'SUCCESS';
  END DBMS_OUTPUT_TEST;
END FUNCTION_CACHING_TEST_PKG;

--Call the function with value of Test 1
DECLARE
  result VARCHAR2(100);
BEGIN
  result:= FUNCTION_CACHING_TEST_PKG.DBMS_OUTPUT_TEST('Test 1');
END;
--DBMS OUTPUT
--anonymous block completed
--DBMS_OUTPUT_TEST Function body executed

Note that the DBMS_OUTPUT_TEST message has been printed indicating that the function body was executed

--Call the function with value of Test 1 again
DECLARE
  result VARCHAR2(100);
BEGIN
  result:= FUNCTION_CACHING_TEST_PKG.DBMS_OUTPUT_TEST('Test 1');
END;
--DBMS OUTPUT
--anonymous block completed

Note that the DBMS_OUTPUT_TEST message has not been printed, the function body was not executed

--Call the function with a new value
DECLARE
  result VARCHAR2(100);
BEGIN
  result:= FUNCTION_CACHING_TEST_PKG.DBMS_OUTPUT_TEST('Test 2');
END;
--DBMS OUTPUT
--anonymous block completed
--DBMS_OUTPUT_TEST Function body executed

A new value was used that is not recorded in the cache so the function was executed

--Update the relies on table
INSERT INTO FUNCTION_CACHING_TEST VALUES ('DML Update');

--Pass a previously cached value
DECLARE
  result VARCHAR2(100);
BEGIN
  result:= FUNCTION_CACHING_TEST_PKG.DBMS_OUTPUT_TEST('Test 1');
END;
--DBMS OUTPUT
--anonymous block completed
--DBMS_OUTPUT_TEST Function body executed

Despite the fact that the value “Test 1″ has already been passed and was logged in the cache the DML update on the table specified in the RELIES_ON clause has forced a cache refresh.

Download This Code From The Download Folder