Introduction

Oracle E-Business Suite Integrated SOA Gateway provides interface for communicating between your custom applications and Oracle EBS. This component is already included in the Oracle E-Business installation but requires configuration to be enabled. This post is an attempt to share my experience enabling ISG and to provide clear step by step instructions.

References

1311068.1 – Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2
1317697.1 – Oracle E-Business Suite Integrated SOA Gateway Troubleshooting Guide, Release 12.2

Check prerequisite patches

Perform the required patches analysis as per the Doc 1311068.1.

ISG consolidated patch

To check if an ISG consolidated patch is already applied in your EBS, please run the following query as APPS:

  set linesize 250;
  set pagesize 300;
  col "ISG Patch" format a70;
  select
  decode(ab.bug_number,
  '31764501','31764501: ISG Consolidated Patch for 12.2 (20_3_5)',
  '33168402','33168402: ISG Consolidated Patch for 12.2 (21_4_3)',
  '34766982','34766982: ISG Consolidated Patch for 12.2 (23_1_1)',
  '35629149','35629149: ISG Consolidated Patch for 12.2 (23_4_5)',
  '36828728','36828728: ISG Consolidated Patch for 12.2 (24_3_5)'
  ) "ISG Patch"
  from ad_bugs ab
  where
  ab.bug_number in
  ('31764501','33168402','34766982','35629149','36828728') and
  ab.language='US';

EBS release version

select fpg.release_name from fnd_product_groups fpg;

AD and TXK patchsets

select ate.abbreviation, ate.name, ate.codelevel, ate.baseline
from ad_trackable_entities ate
where 
ate.abbreviation in ('ad','txk')
order by ate.abbreviation;

XDK patch

su - applmgr
$FMW_HOME/oracle_common/OPatch/opatch lsinventory -oh $FMW_HOME/oracle_common|grep 17428617

Weblogic patch

su - applmgr
cd $FMW_HOME/utils/bsu
$FMW_HOME/utils/bsu/bsu.sh -prod_dir=$FMW_HOME/wlserver_10.3 -status=applied -verbose -view|grep ENUU

Apply required patches

Here is the patch analysis example for my EBS 12.2.12:

[-]34766982: ISG Consolidated Patch for 12.2 (23_1_1)
	[+]12.2.3
	[+]26834480 R12.AD.C.delta.11
	[+]28840822 R12.TXK.C.delta.11
	[-]17428617 - XDK patch (Opatch applicable for FMW versions 11.1.1.9.0 & 11.1.1.7.0)
	[-]34856303 - Weblogic Smart update patch [ENUU]

Start the new patching cycle

 . ~/EBSapps.env run
adop phase=prepare workers=8

Upgrade AD and TXK

In case you need to upgrade AD and TXK please refer to the following MOS Doc:
Applying the Latest AD and TXK Release Update Packs to Oracle E-Business Suite Release 12.2 (Doc ID 1617461.1)

Apply patch 17428617

Download and unzip the patch 17428617 for FMW 11.1.1.9.0 or 11.1.1.7.0 depending on your FMW version.

 . ~/EBSapps.env patch
export ORACLE_HOME=$FMW_HOME/oracle_common
export PATH=$ORACLE_HOME/OPatch:$PATH
cd /stage/17428617
opatch apply

Patching WLS BSU

If you need to apply weblogic patches and BSU utility runs slowly, follow the steps in the following MOS Doc to resolve this issue:
Enhancement for WLS BSU (Smart Update): Resolves Very Long Time to Apply Patches – Especially When Checking for Patch Conflicts (Doc ID 2271366.1)

Ensure that bsu is version 3.3.0

. ~/EBSapps.env patch
cd $FMW_HOME/utils/bsu/
./bsu.sh -version
Oracle Smart Update. Version: 3.3.0.0

Download patch 31136426: SMART UPDATE TOOL ENHANCEMENT V4.
Copy content of this zip file to $FMW_HOME/utils/bsu/

unzip p31136426_1036_Generic.zip -d $FMW_HOME/utils/bsu

Run the update script (with two dots):

cd $FMW_HOME/utils/bsu
. ./bsu_update.sh install

Applying the latest WLS PSU

If the current WLS PSU level is too old patch 34856303 (ENUU) may not be avaiable for it.
In such case, download the latest WebLogic PSU 10.3.6.0.231017 patch: 35710802.
Apply the patch as follows:

unzip p35710802_R12_GENERIC.zip
unzip p35586779_1036_Generic.zip
 
cp -v patch-catalog_27994.xml E7HI.jar $FMW_HOME/utils/bsu/cache_dir/
cd $FMW_HOME/utils/bsu
$FMW_HOME/utils/bsu/bsu.sh -install -patchlist=E7HI -prod_dir=$FMW_HOME/wlserver_10.3

If you face any conflicts, remove using this command:

$FMW_HOME/utils/bsu/bsu.sh -remove -patchlist=XXXX -prod_dir=$FMW_HOME/wlserver_10.3

Patching Oracle WebLogic Server (WLS)

For Patch 34856303 the instructions to be followed :

Download the latest Fusion Middleware consolidated zip file patch mentioned in

Document 2877607.1 : Oracle E-Business Suite Release 12.2: Consolidated List of Oracle Fusion Middleware Patches and Bug Fixes.

“Section 3: Application Tier Patching Guidance”

Example: 35710787: EBS RELEASE 12.2 CONSOLIDATED FMW FIXES FOR OCT 2023

Obtain this WebLogic Smart Update Patch 34856303 from the downloaded consolidated zip file through the following path:

etcc-bundle/[platform]/wls/10.3.6.0.*****/p34856303_1036_Generic.zip

Per the following doc: Oracle E-Business Suite Release 12.2: Consolidated List of Oracle Fusion Middleware Patches and Bug Fixes (Doc ID 2877607.1)

If Patch 25333306 (SUY4) or Patch 17495356 (CIH8) or Patch 26795917 (DN1F) or Patch 33560682 (9UNH) is installed it must be manually rolled back before applying Patch 34856303 (ENUU).

Change memory allocation to prevent bsu fail

vi $FMW_HOME/utils/bsu/bsu.sh

Change from

MEM_ARGS="-Xms512m -Xmx1024m -XX:+UseParallelGC"

to

MEM_ARGS="-Xms1024m -Xmx4096m -XX:+UseParallelGC"
. ~/EBSapps.env patch
 
cp -v ENUU.jar patch-catalog_27940.xml $FMW_HOME/utils/bsu/cache_dir/
cd $FMW_HOME/utils/bsu
$FMW_HOME/utils/bsu/bsu.sh -install -patchlist=ENUU -prod_dir=$FMW_HOME/wlserver_10.3

If you face any conflicts, remove using this command:

$FMW_HOME/utils/bsu/bsu.sh -remove -patchlist=XXXX -prod_dir=$FMW_HOME/wlserver_10.3

Apply the EBS ISG consolidated patch

Download and unzip the patch 34766982.

 . ~/EBSapps.env run
adop phase=apply patches=34766982 patchtop=/backup_bx10/patches/ISG_12.2
adop phase=finalize workers=4
adop phase=cutover
adop phase=cleanup workers=4

Create GLOBAL user

Create the GLOBAL user per MOS Doc 2287614.1 via the Security > User > Define form.

Description: User for Integrated SOA Gateway configuration

Check whether the GLOBAL user exists in Security > User > Define form.
If the user is not present, create the GLOBAL user via the Security > User > Define form.
It is not required to assign any responsibility to the user.

ISG GLOBAL user configuration

Run the ‘Workflow Directory Services User/Role Validation’ concurrent request to propagate the changes. Specify the parameters as shown on the below screenshot:

ISG run wf dir user validation

Change Signon% profile options values (conditional)

This step applies only if the Signon% profile options values are set.
Upon execution ISGRestSetup.pl generates a new ISGADMIN password. This password contains 9 characters and there may be repeating characters. It may not work with password policies defined by the Signon% profile options. So before running ISGRestSetup.pl it is advised to temporarily change the following profile options:

Login to EBS as SYSADMIN. Go to System Administrator>Profile>System. Query the profile options starting with ‘Signon Password%’.

  • Change the profile option ‘Signon Password Hard To Guess’ to ‘No’ at the ISGADMIN user level.
  • Change the profile option ‘Signon Password Length’ to 8 at the ISGADMIN user level.
  • Change the profile option ‘Signon Password Custom’ to an empty value at the Site level.

Run the REST configuration script

Run the script on the primary EBS node where the Weblogic Admin server is running (ps -ef | grep -i Admin).
There is no need to rerun the script on the other nodes in a multi-node installation.
The script does not run autoconfig but restarts the applications.
The script restarts the application services on all the apps nodes.
You may want to stop the concurrent managers before running ISGRestSetup.pl to make the services restart quicker.
But the Weblogic servers have to be up and running.

. ~/EBSapps.env run
cd $ADMIN_SCRIPTS_HOME
./adcmctl.sh stop apps/****

Please wait until all concurrent managers processes are stopped.

cd /tmp
perl $FND_TOP/patch/115/bin/ISGRestSetup.pl

Review the script log file txkScript.log and make sure that no errors occurred.

Then please run the following command:

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dfile=$JAVA_TOP/oracle/apps/fnd/isg/ant/isg_service.xml -Dverbose=OFF

And then the command:

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions="postclone" -Dverbose=ON -DserviceType=REST

Review the script results file and ensure that all the webservices got redeployed successfully:

$NE_BASE/inst/$CONTEXT_NAME/soa/RESTPostCloneResults.txt

Change Signon% profile options values back

After running ISGRestSetup.pl change the Signon% profile options values back. It is recommended to leave them on the ISGADMIN user level though. As it will be required to run ISGRestSetup.pl in the future in the cloned instances.

Verify that REST login service works

Set the profile option ‘FND: Authn Service Token Scope’ to ‘Header and Body’ at the site level per the Doc ID 2938671.1

Then access the following URL:

http://ebshost.ebsdomain:port/webservices/rest/login

E.g:

https://r122.localdomain:4443/webservices/rest/login

When prompted, provide Oracle E-Business Suite System Administration user credentials. You should see a response, similar to the following in the browser:

ISG verify REST login status

Configure token authentication

To make sure that token authentication works perform the following checks:

Check the value of the profile option “Applications Database ID” at the site level:

sqlplus apps/****
select fnd_profile.value('APPS_DATABASE_ID') from dual;

This profile option inherits its value from the context file parameter s_dbc_file_name. So you may also check the value of that parameter as applmgr:

[applmgr@master ~]$ grep s_dbc_file_name $CONTEXT_FILE

Then execute the following query:

select ip.session_cookie_name from icx_parameters ip;

This should return a NULL. If it does not return NULL, run the following update per Doc ID 1159313.1:

update icx_parameters ip set ip.session_cookie_name=null;
commit;

Then execute the following query and make sure the cookie name matches the APPS_DATABASE_ID profile value above.

sqlplus apps/****
select icx_sec.getsessioncookiename cookie_name from dual;

Open the following configuration file:

$INST_TOP/soa/isgagent.properties

Make sure that ISG_AGENT_JNDI_NAMES is set to the same value as the APPS_DATABASE_ID profile option. Example:

ISG_AGENT_JNDI_NAMES=EBSDB

Note: If you change the parameter value, it is also required to change the prefix of the following parameters:

EBSDB.ISG_RUNTIME_CONTEXT
EBSDB.ISG_TEMP_DIRECTORY_LOCATION
EBSDB.ISG_EBS_EXTERNAL_URL
EBSDB.ISG_EBS_INTERNAL_URL
EBSDB.ISG_EBS_ADMIN_SERVER_URL

If you performed any changes, restart the oafm managed server.

[applmgr@demo ~]$ cd $ADMIN_SCRIPTS_HOME
[applmgr@demo scripts]$ ./admanagedsrvctl.sh stop oafm_server1
[applmgr@demo scripts]$ ./admanagedsrvctl.sh start oafm_server1

Configure ISG for TLS

If your EBS instance is TLS enabled check if the required ISG TLS configuration steps are performed.

Increase OAFM servers Java Heap Size

How To Increase The Java Heap Size For EBS Applications Release 12.2.10 and above ? (Doc ID 2990462.1)

Increasing Java Heap Size may be required to increase the OAFM servers performance. If the Integrated SOA Gateway services are accessed by a large number of users in your EBS instance the default heap size may not be enough. Please perform the following steps:

1) Login into Weblogic admin server and click on servers and then click on “Lock & Edit” button.

2) Click on oafm_server1.

3) Click on server start.

It is recommended that you configure oafm to be between 2G and 4G. You could start with 2 G and increase as necessary.

For example: To change –Xms and –Xmx parameter values to 4096m use:

-Xms4096m -Xmx4096m

Click on Save button.

4) If you have more oafm servers, redo the steps to change the heap size for each server.

5) Click on “Activate Changes” button.

6) Restart oafm manages servers.

Resolving possible issue accessing the weblogic admin console

While trying to login to the weblogic admin console to set the oafm heap size you may face the following error in the browser:

The Server is not able to service this request: [Socket:000445]Connection rejected, filter blocked Socket, weblogic.security.net.FilterException: [Security:090220]rule 2

To solve this issue you need to update s_wls_admin_console_access_nodes variable in the apps context file as per Doc ID 2542826.1. But it may not be easily possible.
To work this issue around you may use the SSH port forwarding.
Open your SSH client, e.g. KiTTY or PuTTY. Provide the Weblogic Admin server Host Name, but do not login yet. Go to Connection>SSH>Tunnels
Fill the following fields:
Source port – the port on your laptop that you will access in your browser, e.g. 12345
Destination – the EBS admin server host name and port.
Click on the Add button.
Then start the session by clicking on Open or Start buttons.

SSH port forwarding to access the weblogic admin console
SSH port forwarding to access the weblogic admin console

Now open your browser and access the following url:

http://localhost:12345/console

While the SSH session is running it will forward your workstation port 12345 to the Weblogic server admin port 7051.

SSH port forwarding to access the weblogic admin console

Sync the run and patch filesystems

It is required to run the adop fs_clone phase to make sure that the ISG configuration persists a cutover.

adop phase=fs_clone workers=4

Configuring ISG in cloned instances

Change the Signon% profile option values

This step applies only if the Signon% profile options values are set.
Upon execution ISGRestSetup.pl generates a new ISGADMIN password. This password contains 9 characters and there may be repeating characters. It may not work with password policies defined by the Signon% profile options. So before running ISGRestSetup.pl it is advised to temporarily change the following profile options:

Login to EBS as SYSADMIN. Go to System Administrator>Profile>System. Query the profile options starting with ‘Signon Password%’.

  • Change the profile option ‘Signon Password Hard To Guess’ to ‘No’ at the ISGADMIN user level.
  • Change the profile option ‘Signon Password Length’ to 8 at the ISGADMIN user level.
  • Change the profile option ‘Signon Password Custom’ to an empty value at the Site level.

Run the ISG postclone steps

Please refer to the document:

Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2 (Doc ID 1311068.1)

Section 7: Configuring Oracle E-Business Suite Integrated SOA Gateway on Release 12.2.x Cloned From an Existing 12.2.x Environment

Run the script on the primary EBS node where the Weblogic Admin server is running.
There is no need to rerun the script on the other nodes in a multi-node installation.
The script does not run autoconfig but restarts the applications.
You may want to stop the concurrent managers before running ISGRestSetup.pl to make the services restart quicker.
But the Weblogic servers have to be up and running.

. ~/EBSapps.env run
cd $ADMIN_SCRIPTS_HOME
./adcmctl.sh stop apps/****
cd /tmp
perl $FND_TOP/patch/115/bin/ISGRestSetup.pl

Review the script log file txkScript.log and make sure that no errors occurred.
Then please run the following command:

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dfile=$JAVA_TOP/oracle/apps/fnd/isg/ant/isg_service.xml -Dverbose=OFF

Then please run the following mandatory command to redeploy the webservices in the cloned instance:

ant -f $JAVA_TOP/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions="postclone" -Dverbose=ON -DserviceType=REST

Review the script results file and ensure that all the webservices got redeployed successfully:

$NE_BASE/inst/$CONTEXT_NAME/soa/RESTPostCloneResults.txt

Blitz Report post clone instructions

If Blitz Report is installed in your instance, please run the following commands to redeploy the custom webservice.

ant -f $COMMON_TOP/java/classes/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions="undeploy" -DirepNames="XXEN_WEBSERVICES" -DserviceType=REST -Dverbose=ON
ant -f $COMMON_TOP/java/classes/oracle/apps/fnd/isg/ant/isgDesigner.xml -Dactions="deploy" -DirepNames="XXEN_WEBSERVICES" -Dalias="xxen_webservices" -DserviceType=REST -Dverbose=ON -DauthType=BOTH

For multi node EBS instances run the following script in all the oafm server nodes:

blitz_report_r12_v******/etc/generate_webservice_artifacts.sh

The above script is not required for single node EBS instances.

Sync the run and patch filesystems

Run fs_clone to copy the ISG configuration to the patch fs. It is required to ensure that it persists a patching and a cutover.

adop phase=fs_clone

Change the Signon% profile option values back

After running ISGRestSetup.pl change the Signon% profile options values back. It is recommended to leave them on the ISGADMIN user level though. As it will be required to run ISGRestSetup.pl in the future in the cloned instances.

Increase the weblogic timeout (WLIOTimeoutSecs)

Some ISG requests may take a long time to be processed. To make sure that they are not interrupted please edit or add the following setting to at least 900 seconds:

WLIOTimeoutSecs 900

In the configuration files returned by the following command

ls -l $FMW_HOME/webtier/instances/EBS_web_*OHS*/config/OHS/EBS_web*/mod_wl_ohs.conf

The setting should be added for the Location /webservices
This configuration file is not overwritten by autoconfig.
If this setting is performed in the production it will be transferred to the cloned instances.
The example of the modified configuration file is presented on the below screenshot:

Weblogic ISG timeout configuration

Known issues

${patchContextFile} doesn’t exist

The following errors may occurr when running ISGRestSetup.pl

BUILD FAILED
/u01/install/APPS/fs1/EBSapps/comn/java/classes/oracle/apps/fnd/txk/util/txkISGConfigurator.xml:1892: ${patchContextFile} doesn't exist !

The following query returns only one row for the run file system:

source EBSapps.env run
 
sqlplus apps/*****
 
set linesize 250
col name format a20
col path format a100
col status format a5
select
focf.name,
focf.path,
focf.status
from
fnd_oam_context_files focf
where
focf.ctx_type='A' and
focf.name not in ('TEMPLATE','METADATA') and
(focf.status is null or focf.status!='H');

Solution

Please follow the action plan from the following document to run autoconfig on the patch filesystem:

txkISGConfigurator.xml Fails with Error PatchContextFile Doesn’t Exist (Doc ID 2227168.1)

1) Disable the ebs_login trigger. Connect to the ebs_system user. If your EBS patch level is too low and ebs_system user does not exist yet, connect to the system user.

sqlplus ebs_system/******
alter trigger ebs_logon disable;

2) Apply the patch env file

source EBSapps.env patch

3) Run autoconfig for the patch fs

cd $ADMIN_SCRIPTS_HOME
./adautocfg.sh

4) Enable ebs_login trigger

source EBSapps.env run
sqlplus ebs_system/******
alter trigger ebs_logon enable;

5) Run autoconfig for the run fs

cd $ADMIN_SCRIPTS_HOME
./adautocfg.sh

6) Execute the following query and make sure two rows are returned

sqlplus apps/*****
 
set linesize 250
col name format a20
col path format a100
col status format a5
select
focf.name,
focf.path,
focf.status
from
fnd_oam_context_files focf
where
focf.ctx_type='A' and
focf.name not in ('TEMPLATE','METADATA') and
(focf.status is null or focf.status!='H');

Workaround

Some users have only one filesystem in their test EBS environments, so it is not possible to use the above solution.
The following workaround may be used:

Take a backup of $JAVA_TOP/oracle/apps/fnd/txk/util/txkISGConfigurator.xml

cp $JAVA_TOP/oracle/apps/fnd/txk/util/txkISGConfigurator.xml $JAVA_TOP/oracle/apps/fnd/txk/util/backup_txkISGConfigurator.xml

Open $JAVA_TOP/oracle/apps/fnd/txk/util/txkISGConfigurator.xml

vi $JAVA_TOP/oracle/apps/fnd/txk/util/txkISGConfigurator.xml

Remove the following functions: getPatchFileSystemCtxFile, copyEBSJars:

Before:

target name="ebsSetup" depends="setrestsetuptype,addASADMINToFNDVault,getEBSSetupParameters,copyEBSJars,stopEBSServers,startAdminServerWindows,startAdminServerUnix,createEBSDataSource,deployEBSDataSource,updateEBSSecurityRealms,restartEBSServers"
target name="getEBSSetupParameters" depends="findOS,getweblogicServerDetails,getWLSAdminPasswordWindows,getWLSAdminPasswordUnix,getHostEnvDetails,getappsDBDetails,getEBSRequiredParams,getPatchFileSystemCtxFile"

After:

target name="ebsSetup" depends="setrestsetuptype,addASADMINToFNDVault,getEBSSetupParameters,stopEBSServers,startAdminServerWindows,startAdminServerUnix,createEBSDataSource,deployEBSDataSource,updateEBSSecurityRealms,restartEBSServers"
target name="getEBSSetupParameters" depends="findOS,getweblogicServerDetails,getWLSAdminPasswordWindows,getWLSAdminPasswordUnix,getHostEnvDetails,getappsDBDetails,getEBSRequiredParams"

Rerun ISGRestSetup.pl

ISG Integration Repository Page Does Not Open

This issue is described in the following MOS doc:
Unable to Open the Page after Clicking on Integration Repository “504 Gateway Time-out” or “Failure of Web Server bridge” (Doc ID 1937511.1)

Solution

Gather statistics on the following tables:

exec fnd_stats.gather_table_stats('APPLSYS','AD_PM_PRODUCT_INFO');
exec fnd_stats.gather_table_stats('APPLSYS','AD_PM_PROD_FAMILY_MAP');
exec fnd_stats.gather_table_stats('APPLSYS','FND_LOOKUP_ASSIGNMENTS');
exec fnd_stats.gather_table_stats('APPLSYS','FND_IREP_CLASSES');
exec fnd_stats.gather_table_stats('APPLSYS','FND_OBJECTS');

Additional password prompt when cloning EBS

After configuring Integrated SOA Gateway when cloning production and running adcfgclone.pl script a new password prompt appears:

Enter the password for DataSource ISGDatasource :

Solution

The issue is described in the following Doc:

After REST configuration, when running adcfgclone.sh script is asking to provide password for DataSouce ISGDatasource (Doc ID 2794581.1)

Please run the following query to get the ISGADMIN password and provide it:

select fnd_vault.get('ISG','ISGADMIN') from dual;