Installing REST services in Oracle R12.2.4 EBS
This week I have been playing around with getting REST services up and available to use for our developers. We are soon going to be refreshing our development environment, so I figured this may be the perfect time to give them a week or so to go out and play around with REST services and see if they can work as business solution.
I will start by giving the some pertinent information to this install:
We are currently on or using:
R12.2.4 E-Business Suite
AD/TXK Delta 11
wlserver_10.3
NOTE: To install REST, I was following the Oracle note ID: 1311068.1 , Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2
Now, a couple things here before I walk you though what I did to get it working. I want to be clear that I was following the portion of the above mentioned note to implement REST services only, as per our business requirements. The REST solution has minimal requirements as opposed to implementing SOAP services, as they require a whole new architecture to get it to work, REST does not. This document is lengthy, do not let it discourage you! The REST portion is minimal here.
With that said, on with what we did!
There are quite a few requirements to figure out what all you will need to have in place before you can implement REST services. Please read the note in its entirety, but the information below is what I believe to be the most important.
The two MAIN requirements are to have EBS patch 22328483:R12.OWF.C, and Oracle Fusion Middleware patch 17495356 for Weblogic Server.
You can check for these patches in your environment by doing the following in your desired destination instance:
For the regular EBS patch that would be applied with ADOP method:
select * from apps.ad_bugs where bug_number in '22328483';
--or
select * from apps.ad_applied_patches where patch_name ='22328483';
We did not have this patch, and needed to install it.
For the FMW Weblogic patch, it is a bit more complicated:
On your application server go to your $FMW_HOME/utils/bsu/
./bsu.sh -prod_dir=$FMW_Home/wlserver_10.3 -status=applied -verbose -view > applied_patches.txt
This will create an output file you can search in for patch number 17495356. For us, we already had this patch applied.
Alternatively you can also search for this patch in your AdminServer.log file located here:
$FMW_Home/user_projects/domains/EBS_domain_XXXX/servers/AdminServer/logs/AdminServer.log
Each time the server starts it will display a list of patches that it uses, and the patch in question was also in here for us.
Example line in AdminServer.log file:
WebLogic Server Temporary Patch for BUG17495356 Tue Sep 24 00:23:38 CDT 2013
You must apply the patches first if you do not have them. This next section will take us to the actual steps performed after the patches were applied.
1. Enable the ASADMIN user and give it the Integration Administrator role.
This is pretty straight forward in the note, but this is what I did:
a. Login as SYSADMIN user
b. Go to User Management responsibility, drill into Users, and then User Maintenance
c. Pull up ASADMIN user, click Update, remove the "Active To" date field if there is one
d. Reset the password, in the same screen, go to Assign Roles.
e. Select search by "Code" in the drop down and use "UMX|FND_IREP_ADMIN" and select.
f. Apply it and now sysadmin has the role assigned.
2. Create a Temporary folder on your EBS that has write permissions. We created a folder here called "soa"
We created it here on the application node $NE_BASE/inst/SID/soa
You'll need to update some files with this new location here $INST_TOP/soa.
Update the isgagent.properties file, specifically the ISG_TEMP_LOCATION parameter with the folder you created above. NOTE: Make a backup of these files, and then modify on each application node you have, if you have more than one
3. The next step to run the actual txkISGConfigurator.xml utility that is supposed to stop and restart the weblogic servers:
ant -f $JAVA_TOP/oracle/apps/fnd/txk/util/txkISGConfigurator.xml ebsSetup -DforceStop=yes
Now, I could not for the life of me get this script to run, it would fail every time it tried to force stop weblogic, so I ended up stopping all my weblogic servers and AdminServer and removing the -DforceStop=yes, and this still did not work correctly.
Hmm, I couldn't figure out what was going on here initially. After some searching I found an oracle community thread somewhere that mentioned for me to re-source the EBSapps.env file - located under /appl_top/%inst%/, AND to source your setDomainEnv.sh file located: $FMW_HOME/user_projects/domains/EBS_domain_$TWO_TASK/bin/setDomainEnv.sh
Make sure you use ". ./setDomainEnv.sh" since this is cosidered an environment file.
This got us past our Weblogic issue we were having, although I still left off the -DforceStop from my command as I wanted to make sure that wasn't the issue.
Something else interesting to note - In the documentation Oracle provides in this note, they say you should get prompted for APPS user/pw, ASADMIN user/pw. I got prompted for APPS and WEBLOGIC, but the install went in fine! We'll come back to this part later.
After your script finishes, you should get something similar to:
[echo] Mandatory Step : Restart all the Weblogic Servers NOW !!!
ebsSetup:
BUILD SUCCESSFUL
Total time: 3 minutes 7 seconds
As you can see it does not take very long to complete.
First Verfication
Restart your Weblogic servers if you've left them down as I did.
Go into your Weblogic console and under your Domain Structure, expand your Environment and go into your Clusters.
After your clusters show up, go into oafm_cluster1, and go to the Services tab at the top. You should now see your OAEADatasource.
Second Verification: (Deploy an actual REST Web Service)
a. Log into SYSADMIN, navigate to Integrated SOA Gateway responsibility, and drill down into Integration Repository, and hit Search on the Right Pane
b. Click the link "Show More Search Options"
c. Fill in Category with Interface Subtype, and Category Value with Java Bean Services, click Go
d. Click Rest Service Locator
e. If you wish you can click Grants tab to change some grants around to the service you are about to create, but it is just a test, so you can go directly to the REST Web Services tab if you want.
f. Fill our the mandatory Service Alias field with whatever you want to name it, I named it Test_Rest, and click Deploy at the bottom.
You are supposed to get a message that your service deployed fine, and I wish I could say that mine did, but it did not. I ended up getting the message:
oracle.apps.fnd.framework.OAException: Password for user:ASADMIN is not configured.
DOH! I was almost there. I went back and tried changing the password once again but that did not help. I searched online and found very little, but did find some people having the exact same issue I did. I saved opening an SR for last, as no one really wants to do that. I bit the bullet, and opened an SR under the product Oracle E-Business Suite Integrated SOA Gateway.
I basically told them I followed the documentation to the T and what my issue I was having was. Oracle came back and told me that if I had properly followed all documentation, then I could try using the below command to add ASADMIN to the FNDVault:
****************************************
ant -f $JAVA_TOP/oracle/apps/fnd/txk/util/txkSoaConfigUtility.xml addASADMINToFNDVault
****************************************
This utility will ask for the APPS password, and the ASADMIN user/password. I ran it and entered the password as I had set it.
I went back to the second validation section (steps a-f just above), and was able to successfully deploy my first REST Web Service! You can Undeploy the service just as easy. After it is deployed you can select it and hit the Undeploy button.
I suggest that you run txkSoaConfigUtility.xml utility if you :
1. Run the txkISGConfigurator.xml, and if it does not ask you for the ASADMIN credentials, run it after the setup.
2. You could wait until you try to deploy the service and get the same message as I did, or
3. You could run the utility directly after enabling and setting up the ASADMIN user to make sure the password gets accepted into the vault (make sure you login as ASADMIN first and change the password if you have it setup where it forces you to change your password upon logging into the EBS!)
As a side note, oracle did come back on the SR after some conversation and say that this document is configured with the latest AD/TXK Delta, which is update 7, while we are on Delta 6.
I will start by giving the some pertinent information to this install:
We are currently on or using:
R12.2.4 E-Business Suite
AD/TXK Delta 11
wlserver_10.3
NOTE: To install REST, I was following the Oracle note ID: 1311068.1 , Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2
Now, a couple things here before I walk you though what I did to get it working. I want to be clear that I was following the portion of the above mentioned note to implement REST services only, as per our business requirements. The REST solution has minimal requirements as opposed to implementing SOAP services, as they require a whole new architecture to get it to work, REST does not. This document is lengthy, do not let it discourage you! The REST portion is minimal here.
With that said, on with what we did!
STEPS:
There are quite a few requirements to figure out what all you will need to have in place before you can implement REST services. Please read the note in its entirety, but the information below is what I believe to be the most important.
The two MAIN requirements are to have EBS patch 22328483:R12.OWF.C, and Oracle Fusion Middleware patch 17495356 for Weblogic Server.
You can check for these patches in your environment by doing the following in your desired destination instance:
For the regular EBS patch that would be applied with ADOP method:
select * from apps.ad_bugs where bug_number in '22328483';
--or
select * from apps.ad_applied_patches where patch_name ='22328483';
We did not have this patch, and needed to install it.
For the FMW Weblogic patch, it is a bit more complicated:
On your application server go to your $FMW_HOME/utils/bsu/
./bsu.sh -prod_dir=$FMW_Home/wlserver_10.3 -status=applied -verbose -view > applied_patches.txt
This will create an output file you can search in for patch number 17495356. For us, we already had this patch applied.
Alternatively you can also search for this patch in your AdminServer.log file located here:
$FMW_Home/user_projects/domains/EBS_domain_XXXX/servers/AdminServer/logs/AdminServer.log
Each time the server starts it will display a list of patches that it uses, and the patch in question was also in here for us.
Example line in AdminServer.log file:
You must apply the patches first if you do not have them. This next section will take us to the actual steps performed after the patches were applied.
INSTALL / SETUPS:
1. Enable the ASADMIN user and give it the Integration Administrator role.
This is pretty straight forward in the note, but this is what I did:
a. Login as SYSADMIN user
b. Go to User Management responsibility, drill into Users, and then User Maintenance
c. Pull up ASADMIN user, click Update, remove the "Active To" date field if there is one
d. Reset the password, in the same screen, go to Assign Roles.
e. Select search by "Code" in the drop down and use "UMX|FND_IREP_ADMIN" and select.
f. Apply it and now sysadmin has the role assigned.
2. Create a Temporary folder on your EBS that has write permissions. We created a folder here called "soa"
We created it here on the application node $NE_BASE/inst/SID/soa
You'll need to update some files with this new location here $INST_TOP/soa.
Update the isgagent.properties file, specifically the ISG_TEMP_LOCATION parameter with the folder you created above. NOTE: Make a backup of these files, and then modify on each application node you have, if you have more than one
3. The next step to run the actual txkISGConfigurator.xml utility that is supposed to stop and restart the weblogic servers:
ant -f $JAVA_TOP/oracle/apps/fnd/txk/util/txkISGConfigurator.xml ebsSetup -DforceStop=yes
Now, I could not for the life of me get this script to run, it would fail every time it tried to force stop weblogic, so I ended up stopping all my weblogic servers and AdminServer and removing the -DforceStop=yes, and this still did not work correctly.
Hmm, I couldn't figure out what was going on here initially. After some searching I found an oracle community thread somewhere that mentioned for me to re-source the EBSapps.env file - located under /appl_top/%inst%/, AND to source your setDomainEnv.sh file located: $FMW_HOME/user_projects/domains/EBS_domain_$TWO_TASK/bin/setDomainEnv.sh
Make sure you use ". ./setDomainEnv.sh" since this is cosidered an environment file.
This got us past our Weblogic issue we were having, although I still left off the -DforceStop from my command as I wanted to make sure that wasn't the issue.
Something else interesting to note - In the documentation Oracle provides in this note, they say you should get prompted for APPS user/pw, ASADMIN user/pw. I got prompted for APPS and WEBLOGIC, but the install went in fine! We'll come back to this part later.
After your script finishes, you should get something similar to:
[echo] Mandatory Step : Restart all the Weblogic Servers NOW !!!
ebsSetup:
BUILD SUCCESSFUL
Total time: 3 minutes 7 seconds
As you can see it does not take very long to complete.
VERIFICATION and Troubleshooting:
Restart your Weblogic servers if you've left them down as I did.
Go into your Weblogic console and under your Domain Structure, expand your Environment and go into your Clusters.
After your clusters show up, go into oafm_cluster1, and go to the Services tab at the top. You should now see your OAEADatasource.
Second Verification: (Deploy an actual REST Web Service)
a. Log into SYSADMIN, navigate to Integrated SOA Gateway responsibility, and drill down into Integration Repository, and hit Search on the Right Pane
b. Click the link "Show More Search Options"
c. Fill in Category with Interface Subtype, and Category Value with Java Bean Services, click Go
d. Click Rest Service Locator
e. If you wish you can click Grants tab to change some grants around to the service you are about to create, but it is just a test, so you can go directly to the REST Web Services tab if you want.
f. Fill our the mandatory Service Alias field with whatever you want to name it, I named it Test_Rest, and click Deploy at the bottom.
You are supposed to get a message that your service deployed fine, and I wish I could say that mine did, but it did not. I ended up getting the message:
oracle.apps.fnd.framework.OAException: Password for user:ASADMIN is not configured.
DOH! I was almost there. I went back and tried changing the password once again but that did not help. I searched online and found very little, but did find some people having the exact same issue I did. I saved opening an SR for last, as no one really wants to do that. I bit the bullet, and opened an SR under the product Oracle E-Business Suite Integrated SOA Gateway.
I basically told them I followed the documentation to the T and what my issue I was having was. Oracle came back and told me that if I had properly followed all documentation, then I could try using the below command to add ASADMIN to the FNDVault:
****************************************
ant -f $JAVA_TOP/oracle/apps/fnd/txk/util/txkSoaConfigUtility.xml addASADMINToFNDVault
****************************************
This utility will ask for the APPS password, and the ASADMIN user/password. I ran it and entered the password as I had set it.
I went back to the second validation section (steps a-f just above), and was able to successfully deploy my first REST Web Service! You can Undeploy the service just as easy. After it is deployed you can select it and hit the Undeploy button.
I suggest that you run txkSoaConfigUtility.xml utility if you :
1. Run the txkISGConfigurator.xml, and if it does not ask you for the ASADMIN credentials, run it after the setup.
2. You could wait until you try to deploy the service and get the same message as I did, or
3. You could run the utility directly after enabling and setting up the ASADMIN user to make sure the password gets accepted into the vault (make sure you login as ASADMIN first and change the password if you have it setup where it forces you to change your password upon logging into the EBS!)
As a side note, oracle did come back on the SR after some conversation and say that this document is configured with the latest AD/TXK Delta, which is update 7, while we are on Delta 6.
