1/19/24, 5:28 PM Document 2308292.

1
Copyright (c) 2024, Oracle. All rights reserved. Oracle Confidential.

Troubleshooting And Debugging Oracle XML Gateway 12.2 (Doc ID 2308292.1)

APPLIES TO:

Oracle E-Business Suite

Oracle XML Gateway - Version 12.2 and later
Information in this document applies to any platform.

PURPOSE

The purpose of this document is to provide debugging and troubleshooting steps for the configuration and operation of the
XML Gateway in EBS version 12.2.x

Contents include:

1. Configuring the Oracle Transport Agent

2. Configuring SSL for outbound

3. Debugging the ECX Listeners

4. Setup for ECX_ADMIN notifications

5. XML Message Designer

6. New Settings for EBS 12.2:

7. Performance and Java Memory Issues

8. Helpful scripts:

TROUBLESHOOTING STEPS

1. Configuring the Oracle Transport Agent

In Release 12.2, OTA runs in the OAFM managed server and the system properties are read from the oafm_wls.properties
file of the OAFM managed server which is $INST_TOP/appl/admin/oafm_wls.properties.

See: OTA Overview for 12.2

A) The autoconfig $CONTEXT_FILE parameter s_load_oxta_servlet is used to control loading of the Oracle Transport
Agent servlets (both inbound and outbound) when managed server starts up.

This parameter is defaulted to '1' which will load both OTA inbound servlet (TransportAgentServer) and outbound
servlet (TransportAgentMain) when managed server starts up.

If this parameter s_load_oxta_servlet is set to '-2', then both OTA inbound and outbound servlets will not be loaded
by default when managed server starts up.

In this case, OTA inbound servlet will be loaded and started automatically when it receives the first request, whereas
the outbound servlet will never get loaded as it is not supposed to receive any requests (it only sends). To start
outbound servlet, this parameter should be exclusively set to '1'.

B) To see if the OTA is running, the following SQL can be run:

SQL> select machine,action, decode(count(*),0,'Error: OTA is Not Running','OTA is Running')

from gv$session
where action like '%OXTA%'
group by machine, action;

C) The OTA is designed to run on a single internal node.

https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctrl-state=17ihglp5g2_348&id=2308292.1 1/7
1/19/24, 5:28 PM Document 2308292.1
Read: Oracle E-Business Suite R12 Configuration in a DMZ (Doc ID 380490.1)
Appendix A : List of External Facing Oracle E-Business Suite Release 12 Products

2. Configuring the OTA for Authentication

- Main Note: Enabling TLS in Oracle E-Business Suite Release 12.2 (Doc ID 1367293.1)

- In Release 12.2, OTA now runs under the Weblogic server. The system properties are read from the
oafm_wls.properties file of the oafm managed server, which is $INST_TOP/appl/admin/oafm_wls.properties.

Also, In Release 12.2, the OTA is client authentication enabled by default. The default wallet used by the Weblogic
server already has a user certificate. The same certificate will automatically be used for client authentication during
the handshake, if client authentication is required by the server OTA is connecting to.

If there is a chain of certificates issues by CA(s), the CA certificates should be added as trusted certificates in the
same wallet. The default location for the wallet is {s_web_ssl_directory}/Apache. Refer to the Application Context file
for the exact location of the {s_web_ssl_directory} variable.

- Https client services such as XML gateway, iProcurement punchout and notification mailer can use either a
designated jdk keystore or they can use the default web server keystore. Given the current limitations of the wallets
and wallet management tools it is advised that customers needing to utilize SHA2 and TLS utilize the configuration
option to setup a java based keystore.

1) Create a Java keystore to hold the certificate as a trusted certificate.

Navigate to the <s_fmw_jdktop>/jre/lib/security directory. Refer to the Application context file for the exact
location of the <s_fmw_jdktop> variable.
Back up the existing cacerts file.

Import the trading partner certificates into the Java keystore :

example command:
keytool -import -trustcacerts -alias digicert -file digicert_ca.crt -keystore <s_fmw_jdktop>/jre/lib/security/cacerts
-storepass changeit

(use the actual path to the keystore and the actual crt file names, etc when you import these)

2) modify the autoconfig variables $CONTEXT_FILE to point to new jks keystore:

New Values:
s_ssl_truststore = <s_fmw_jdktop>/jre/lib/security/cacerts
... the expectation is that you will confirm the path to the cacerts file on FMW and will insert the correct path
here.

s_ssl_truststoretype = JKS

3)
12.2: update $INST_TOP/appl/admin/oafm_wls.properties with the following new values:

javax.net.ssl.trustStoreType=JKS
javax.net.ssl.trustStore=$AF_JRE_TOP/jre/lib/security/cacerts
... the expectation is that you will confirm the path to the cacerts file on FMW and will insert the correct path
here.
... this will be the same path that you used in step 1 and 2
javax.net.ssl.trustStorePassword=changeit

4) Run Autoconfig.
5) restart the middle tier server(s)

- To test that the wallet is properly set up and accessible:

SQL>select utl_http.request('<url to access>', '<proxy address>', 'file:<full path to wallet directory>', null) from
dual;

3. Debugging the ECX Listeners

Log into Oracle Application Manager (OAM) and go to SiteMap/Workflow/Home.

This is the workflow manager console page.
https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctrl-state=17ihglp5g2_348&id=2308292.1 2/7
1/19/24, 5:28 PM Document 2308292.1
Click on the green check mark or red X next to "Agent Listeners" or "Service Components"
and select the component titled "ECX Inbound Agent Listener' or 'ECX Outbound Agent Listener.
Use the Edit button and click next to proceed to Page 2 of 4
Use the pull down arrow on the Log Level parameter and change it to STATEMENT and click finish.

Go back to the SiteMap/Workflow/Home and again click on the green check mark or
red X next to "Agent Listeners" or "Service Components" then select "ECX TRANSACTION AGENT LISTENER".
Use the Edit button again proceed to page 2. Change the log Level to STATEMENT, click finish until you have exited
the edit wizard.

From the OAM / Workflow manager Console, go again to the Service Components page where you will see a list of
the Workflow and ECX service components. The ECX Inbound/ Outbound Listener will have a corresponding Container
called the 'Workflow Agent Listener Service'. Click the link for that container and this will take you the Service
Instances for the Generic Service Component Container page. You will need to Stop and then

restart the Workflow Agent Listener Service. When you do this, wait until the container is completely stopped or
terminated before you attempt to

restart it. Once you restart it, wait until the Actual and Target Processes are symmetrical again (1 and 1) then
recreate the issue (wait until

the ECX listener goes into error or System Deactivated state again). Once the listener is again deactivated by error
then gather the FNDCPG logs.

The FND logs are found at $APPLCSF/$APPLLOG and can be listed by date using:
ls -lrt FNDCPG*.txt

4. Setup for ECX_ADMIN notifications

- There is a profile option called "ECX: system administrator email address" which should send an email in case any
ECX_ERROR type event is spawned.

- ECX_SA is an adhoc role. To find ECXERROR notifications sent to this role, do the following:

. Logon as SYSADMIN user and go to responsibility Workflow Administrator, Web Applications

. Then navigate to Administrator Workflow / Administration on the menu.
. On the blue navigation bar under the 'Administration' tab, select 'Notification Search' to bring up the advanced
search box for notifications.
. In the box next to 'Owner' select Adhoc Roles and then click the search icon next to the Owner box.
. in the Search box, search for %ecx% and select the role for ECX System Administrator. (use the quick select
icon)
. back in the Notifications search page, check that your Owner box has 'Adhoc Roles' and 'ECX System
Administrator' populated and then click the GO button at the bottom.

(optional) Next, in the Notification Search screen specify internal name ECXERROR.

If an ecxerror is not spawned, then an email will not be sent to the ECX_SA role.

5. XML Message Designer

- Useful Links:

Step by Step Guide to Creating an Inbound XML Gateway Transaction for E-Business Suite (Doc ID 329903.1)

How To Obtain The .xgd File For A Seeded Oracle xml Gateway Map (Doc ID 1989643.1)

How To Download and Install the Latest Oracle Workflow Builder (Client Tool) and XML Gateway Message
Designer for E-Business Suite (Doc ID 261028.1)

XML Gateway Message Designer Cannot Connect To The Database (Doc ID 1263533.1)

6. New Settings for EBS 12.2:

https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctrl-state=17ihglp5g2_348&id=2308292.1 3/7
1/19/24, 5:28 PM Document 2308292.1
- Oracle XML Gateway has enhanced its inbound processing by allowing the Oracle XML Gateway execution engine to
process inbound messages either in Java or in PL/SQL, based on the value specified in the
ECX_IN_JAVA_PROCESSING profile option. Previously, all inbound messages were processed in PL/SQL only.

- Oracle XML Gateway web services are enabled through Oracle E-Business Suite Integrated SOA Gateway Service
Provider and can be viewed from the Integration Repository. Therefore, XML Gateway web service feature has
product dependency on Oracle E-Business Suite Integrated SOA Gateway, which depends on Oracle SOA Suite 11g
(11.1.1.6.0) and Oracle Applications Adapter (also called Oracle E-Business Suite Adapter) 11g (11.1.1.6.0), or Oracle
SOA Suite 11g (11.1.1.7.0) and Oracle Applications Adapter 11g (11.1.1.7.0).

If your system is upgraded from an earlier Oracle E-Business Suite release and you have been leveraging XML
Gateway services or Oracle E-Business Suite Integrated SOA Gateway feature, then install Oracle SOA Suite 11g first,
before the upgrade to Release 12.2.2.

After the upgrade, the deployed WSDL URL information has already been changed. Therefore, you may have to
replace it with the new WSDL URL and service location or address accordingly in Web service clients while invoking
the deployed Oracle E-Business Suite service. For information about the installation of Oracle E-Business Suite
Integrated SOA Gateway, see My Oracle Support Knowledge Document 1311068.1 , Installing Oracle E-Business Suite
Integrated SOA Gateway, Release 12.2.

For troubleshooting information about potential problem symptoms and corresponding solutions for Oracle E-Business
Suite Integrated SOA Gateway, see "Oracle E-Business Suite Integrated SOA Gateway Troubleshooting Guidelines,
Release 12.2", My Oracle Support Knowledge Document 1317697.1.

- To provide more diagnostic capability and troubleshoot potential issues, Oracle XML Gateway diagnostics are
enhanced to include the ‘XML Gateway Health Check’, which lets you check and validate the health of Oracle XML
Gateway, and ‘Get Document Details’, which lets you display document details and perform root cause analysis on
potential issues.

This enhancement also includes modified parameters for existing diagnostics, including ‘Basic OTA Diagnostic Test’,
‘Ping Destination Server’, and ‘Message Monitor’.

7. Performance and Java Memory Issues:

These issues appear as connection timeout errors or Java OutOfMemoryError exceptions. There are several profile
options available to manage large files and high volumes:

A) In the $CONTEXT_FILE:

- s_oxtainpoolsize: default value of 1. Controls the jdbc connections to database for inbound requests.

- s_outbound_threads: default value of 1. Controls the jdbc connections to database for outbound requests.

B) OTA Parameters Not Set in the $CONTEXT_FILE:

- the following parameters are not configured in the $CONTEXT_FILE but are directly inserted into the
oafm_wls.properties file:

OXTAOutBaseTimeout (default 30) and OXTAOutLinearTimeout

C) Profile options:

- ECX: Maximum XML:Specifies the maximum size of an outbound XML document (in characters) beyond which
parsing is performed based on the value of ECX: XML
Validate Flag. If the size is not set, the document will be parsed by default." This means that if the Maximum
XML is set to 2000 then the parsing of the xml
documents that are bigger than 2000 bytes will be performed if the ECX: XML Validate Flag is set to YES.
Otherwise like in your case the parsing of those documents wont be performed if the document size is higher
that 2000 bytes. Default value is 2mb

- ECX: XML Validate Flag: This profile option specifies whether an outbound document should continue to be
parsed by the engine after the
maximum size defined in the 'ECX: Maximum XML Size' profile option has been reached. This profile option
works together with
the 'ECX: Maximum XML Size' profile option. Default value Y

https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctrl-state=17ihglp5g2_348&id=2308292.1 4/7
1/19/24, 5:28 PM Document 2308292.1
- ECX: Java Memory Limit
This profile option allows you to increase the maximum memory (in megabytes) available for the database
session running the Java portion of the XML
transformation at the site level. Note: With the increase of maximum memory while processing XML messages, it
not only helps avoid Java
out of memory errors (Java heap space exception), but also helps smooth XSLT transformation and XML
message processing. Default value 1024 MB
Note: It can range from 256 MB up to all the available database server memory.

If the document is greater than the maximum size and the 'ECX: XML Validate Flag' profile value is also set to
'Y', then the parsing will be
continued. For example, while parsing the outbound document, if an outbound XML document has size greater
than the maximum 2MB, then the
'ECX: XML Validate Flag' profile value will be checked. If the validate flag is also set to 'Y', then the document
will continue to be parsed.
However, if the document reaches the maximum size, but the validate flag is set to 'N', then the parsing will not
be continued.

Disabling XML Parsing and Validation: Because the 'ECX: XML Validate Flag' profile option works together with
the 'ECX: Maximum
XML Size' profile option, to disable XML parsing and validation for outbound messages, you not only need to set
the 'ECX: XML Validate
Flag' profile value to 'N', but also need to set the 'ECX: Maximum XML Size' profile to a value that is low enough
so that your outbound
document size can easily surpass it. This way, when the document size is greater than the maximum size you
defined, and you have the 'ECX:
XML Validate Flag' profile set to 'N', then the parsing and validation will be disabled. The XML engine will not
parse the document and
perform the XSL transformation.

Setting the 'ECX: XML Validate Flag' profile value to anything other than 'Y' will turn off parser validation for a
document once the
maximum size has been parsed. Turning off the validation avoids Out of Memory errors for large documents. If
validation is turned off, the
XSLT Transformation action cannot be performed.

- Use the following to view the profile option values:

SELECT FND_PROFILE.VALUE('ECX_MAX_JAVA_MEMORY') FROM DUAL

SELECT FND_PROFILE.VALUE('ECX_SERVER_TIMEZONE') FROM DUAL
SELECT FND_PROFILE.VALUE('ECX_XML_MAXIMUM_SIZE') FROM DUAL
SELECT FND_PROFILE.VALUE('ECX_XML_VALIDATE_FLAG') FROM DUAL

D) Http 413 request entity too large or resource does not allow method post (Inbound):

- see: Errors When Submitting Large XML File (Doc ID 2202350.1)

8. Helpful scripts:

A. Diagnostics:

- XML Gateway Data Collection Script for Outbound ECX Transactions (Doc ID 742618.1). This script requires a
document number to run. Output is ECX_OUTBOUND.html

- XML Gateway Data Collection Script for Inbound ECX Transactions (Doc ID 742588.1) Output is ECX_INBOUND.html

B. Gather data from the inbound queue table:

Stop the inbound listeners then transmit your data inbound (recreating the inbound message flow) before running
this script.
This queries the data when ECX_INBOUND has enqueued the event on ECX_TRANSACTION after one submits the
inbound:

https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctrl-state=17ihglp5g2_348&id=2308292.1 5/7
1/19/24, 5:28 PM Document 2308292.1
set linesize 155;
set pagesize 200;
set verify off;
select substr(ecxtran.corrid,1,45) corrid, decode(ecxtran.state,
0, '0 = Ready',
1, '1 = Delayed',
2, '2 = Retained',
3, '3 = Exception',
to_char(substr(ecxtran.state,1,12))) State,
count(*) COUNT
from apps.ECX_IN_OAG_Q_TABLE ecxtran
group by ecxtran.corrid, ecxtran.state;

C. More inbound data gathering, with time stamps from the log tables:

select il.MSGID, il.status, il.error_id, il.logfile, il.time_stamp, er.message,dl.transaction_type, dl.transaction_subtype,

dl.document_number, dl.party_site_id,dl.payload, dl.status
from ECX_INBOUND_LOGS il,
ECX_ERROR_MSGS er,
ECX_DOCLOGS dl
where il.error_id = er.error_id(+)
and il.MSGID = dl.msgid(+)
and il.time_stamp >=
to_date('09-MAR-2012 09:00', 'DD-MON-YYYY HH24:MI') and il.time_stamp <
to_date('09-MAR-2012 09:10', 'DD-MON-YYYY HH24:MI')
--and to_date('21-FEB-2010 00:00', 'DD-MON-YYYY HH24:MI')
order by il.time_stamp asc;

D. This will check the length of the document that is causing the problem (replacing MSGID as needed)

SELECT ed.MSGID, LENGTH(ed.payload)FROM ecx_doclogs ed

WHERE msgid in ('049DEC1D5D44A034E0430AC29C64A034',
'049DEC7CE18B10CAE0430AC29C6410CA', '049EE7A03C147008E0430AC29C647008',
'049EE6F86D0B6072E0430AC29C646072', '049F5EAD1C3A801CE0430AC29C64801C',
'049F5E751EE35044E0430AC29C645044')

E. Check for any successful document of this size has been processed:

SELECT MSGID, LENGTH(payload)FROM ecx_doclogs

WHERE msgid is not in ('049DEC1D5D44A034E0430AC29C64A034',
'049DEC7CE18B10CAE0430AC29C6410CA', '049EE7A03C147008E0430AC29C647008',
'049EE6F86D0B6072E0430AC29C646072', '049F5EAD1C3A801CE0430AC29C64801C',
'049F5E751EE35044E0430AC29C645044')
and LENGTH(payload) > (SELECT MIN(LENGTH(ed.payload))
FROM ecx_doclogs ed)

F. Validate trading partner

select
TPH.PARTY_ID,
TPH.PARTY_SITE_ID,
STD.STANDARD_CODE,
TPD.SOURCE_TP_LOCATION_CODE,
MAP.MAP_CODE,
EXT.DIRECTION,
TRN.TRANSACTION_TYPE,
TRN.TRANSACTION_SUBTYPE
TPD.PROTOCOL_ADDRESS,
TPD.PROTOCOL_TYPE,
TPD.USERNAME,
TPD,PASSWORD
FROM ECX_TP_DETAILS TPD
,ECX_TP_HEADERS TPH
,ECX_DOCLOGS DL
,ECX_MAPPINGS MAP
,ECX_EXT_PROCESSES EXT
https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctrl-state=17ihglp5g2_348&id=2308292.1 6/7
1/19/24, 5:28 PM Document 2308292.1
,ECX_TRANSACTIONS TRN
,ECX_STANDARDS STD
WHERE MAP.MAP_ID = TPD.MAP_ID
and TPD.EXT_PROCESS_ID=EXT.EXT_PROCESS_ID
and EXT.TRANSACTION_ID = TRN.TRANSACTION_ID
and TPD.TP_HEADER_ID = TPH.TP_HEADER_ID
and TPD.SOURCE_TP_LOCATION_CODE=DL.PARTY_SITE_ID
--and TRN.TRANSACTION_TYPE=DL.TRANSACTION_TYPE
--and TRN.TRANSACTION_SUBTYPE=DL.TRANSACTION_SUBTYPE
and EXT.STANDARD_ID=STD.STANDARD_ID
and DL.DOCUMENT_NUMBER='41800000263:0:405';

G. Check the outbound queue with time stamp information:

select substr(ecxout.corrid,1,20) corrid,

to_char(delay, 'YYYY/MM/DD HH24:MI:SS') delay,
to_char(enq_time, 'YYYY/MM/DD HH24:MI:SS') enq_time,
to_char(enq_time, 'YYYY/MM/DD HH24:MI:SS') deq_time,
to_char(sysdate, 'YYYY/MM/DD HH24:MI:SS') sys_date,
retry_count,
substr (ecxout.user_data.PROTOCOL_TYPE,1,14) PROTOCOL_TYPE,
substr (ecxout.user_data.PROTOCOL_ADDRESS,1,50) PROTOCOL_ADDRESS,
substr (ecxout.user_data.PARTYID,1,8) PARTYID,
decode(ecxout.state,
0, '0 = Ready',
1, '1 = Delayed',
2, '2 = Retained',
3, '3 = Exception',
to_char(substr(ecxout.state,1,12)) ) State,
count(*) COUNT
from apps.ECX_OUTQUEUE ecxout
group by ecxout.corrid, ecxout.enq_time,ecxout.deq_time, sysdate, delay, ecxout.
retry_count,
ecxout.user_data.PROTOCOL_TYPE, ecxout.user_data.PROTOCOL_ADDRESS, ecxout.
user_data.PARTYID, ecxout.state;

H. Show map in system, with the business event name:

select * from ecx_mappings map, ecx_objects obj

where obj.object_id = 2
and obj.object_type = 'DB'
and obj.map_id = map.map_id
and map.map_id in( select distinct map.map_id from
ecx_mappings map, ecx_objects obj, ecx_dtds dtd
where map.map_code like 'WSH_SSNI_OAG721_IN'
and map.map_id = obj.map_id and dtd.root_element = obj.root_element
and obj.runtime_location = dtd.version
and obj.fullpath = dtd.filename)

The description field on this query shows the business event name that processes this into the interface tables.

REFERENCES
NOTE:1988982.1 - Oracle XML Gateway Sizing and Performance Guidelines
NOTE:1367293.1 - Enabling TLS in Oracle E-Business Suite Release 12.2
NOTE:601736.1 - E-Business Suite Applications Technology Stack Utility / Script To Check The Techstack Component
Versions (Forms, Http Server, JDK, Framework, Database, etc)
NOTE:1354616.1 - How Calculate OXTAOutLinearTimeout Settings For OTA
NOTE:2127982.1 - How To Debug Oracle HTTP Server (OHS) And SSL (NZ) In FMW 11G (11.1.1.X) And FMW 12C (12.1.X
AND 12.2.X)
Didn't find what you are looking for?

https://support.oracle.com/epmos/faces/DocumentDisplay?_adf.ctrl-state=17ihglp5g2_348&id=2308292.1 7/7