This page uses JavaScript and requires a JavaScript enabled browser.Your browser is not JavaScript enabled.

9

Applies to:

Oracle XML Gateway - Version 11.5.9 to 11.5.10.4 [Release 11.5 to 11.5.10]

Information in this document applies to any platform.

Checked for relevance on 18FEB2012

Abstract

XML Gateway Setup Testing and Diagnostics

History

Created January 2007

Details

Â

XML Gateway Setup Testing and Diagnostics

January 2007

This article is written to assist 11.5.9 and 11.5.10 customers in testing XML Gateway and obtaining

diagnostics data. It includes setting up a simple test to send and receive an XML transaction using

the seeded test inbound and outbound maps provided by ECX Development for testing XML

Gateway. The most current version of this document is in Note: 337428.1.

This document contains the following sections:

Setup and Usage Documentation

Setup Testing and Diagnostics

Setup and Usage Documentation:

Note 152775.1 Installing Oracle XML Gateway and Oracle Workflow with Oracle Applications 11i

Note 204162.1 General Oracle XML Gateway FAQ

Oracle XML Gateway User's Guide (zipped)

Setup Testing and Diagnostics:

The Oracle Transport Agent (OTA) uses Oracle Workflows Business Event System to send and

receive of XML documents from Trading Partners. The sending of XML documents through OTA is

simply a type of workflow using the ECX_STANDARD.SEND function activity to send through the

ECX_OUTBOUND queue for OTA to dequeue and send. The receiving of inbound XML documents

do not necessarily have to use OTA; however, it is up to the recipient to accept and process the

XML. OTA is designed to accept inbound XML and enqueue it on the ECX Inbound queue for the

ECX Inbound Agent Listener to process on to the ECX Transaction queue where the ECX

Transaction Agent Listener will complete the processing of the inbound XML.

Setup a Test Case:

Assign yourself the XML Gateway responsibility. You will need this responsibility to define your

XML Gateway transactions to be sent to your trading partners.

XML Gateway > Define Transactions

Setup to use TestingDirectOut and TestingDirectIn XML Gateway message maps.

Setup Trading Partner to use TestDirect transaction type for both sending (OUT) and receiving

(IN). This is using SMTP.

NOTE: Select a Supplier type trading partner. This works on both 11.5.9 and 11.5.10 when doing

the inbound test.

TestingDirectIn (Inbound Map)

TestingDirectOut (Outbound Map)

The email address for Protocol Address is the email address that you are sending the XML

doc. The source trading partner location code is any unique name that identifies the Trading

Partners location as the same trading partner can have multiple divisions.

Use Help > Diagnostics > Examine to get the PARTY_SITE_ID = 41 for this trading partner. This is

one of parameters that you need to supply when launching/raising an event to initiate an XML

Gateway transaction.

Navigate Workflow Administrator Web Applications > Business Event menu and create a Business

Event for testing your outbound transaction.

NOTE: This configuration will only work on 11.5.10 as there is no subscription in 11.5.9 for use. PO

Approval includes the ability to send XML documents to its suppliers so one can set that up as a

test for sending an outbound transaction on 11.5.9.

Create a subscription for sending TestingDirectOut. Set the Phase to 10 so it is not deferred on the

WF_DEFERRED queue but will be enqueued directly on ECX_OUTBOUND.

Find the event which should have the subscription and test it.

Event Key = TESTDIRECTOUT1111 (Any unique value).

There are 3 MANDATORY PARAMETERS FOR SENDING

1. ECX_TRANSACTION_TYPE = TESTDIRECTOUT (Defined when you created the Transaction)

2. ECX_TRANSACTION_SUBTYPE = TESTDIRECTOUTS (Defined when you created the Transaction)

3. ECX_PARTY_SITE_ID = 41 (Help > Diagnostics > Examine party_site_id.)

This parameter is useful in tracking the message.

Additional Parameter Required for Viewing Details in Transaction Monitor on pre-11.5.10CU2

instances:

ECX_DOCUMENT_ID = TESTDIRECTOUT1111 (Any unique name for the message_id)

The Document id is optional. However, in pre-11.5.10CU2 in the transaction monitor summary

page the hyper link for showing more details of the ECX transaction is based on the document

number. Therefore, details cannot be viewed without the ECX_DOCUMENT_ID being included as

one of the event parameters. This has been fixed in 11.5.10.2CU to set the document number to

the outgoing message id if it is null.

Party type is not mandatory with the exception that if one has identical trading partner-

transaction setups differing only in party_type, then you need to specify ECX_PARTY_TYPE.

Go to Workflow Administrator Web Applications > Transaction Monitor and search for the

outbound message you just sent when you raised the event.

NOTE: The outbound message was created using a Supplier party type. This is a generic test MAP

so any type is fine. Party Type are usually based on the Trading Partner i.e. one sends a Purchase

Order (PO) to a Supplier not a Customer.

The document was generated and delivered.

Click in the Document ID to get the details of the transaction and view the XML.

This is the XML contents. One will send this in as the payload when using

http:///OA_HTML/US/ECXOTAInbound.htm or

http:///servlets/oracle.apps.ecx.oxta.ECXOTAInbound. This html page posts the message to

http:///servlets/oracle.apps.ecx.ota.TransportAgentServer. This is the servlet that an outbound

OTA or a non oracle sender should use to post a message.

OTA Inbound Test Values:

MESSAGE_ID = Any unique name

TRANSACTION_TYPE = TESTDIRECTIN (Defined as External Transaction Type when one created the

Trading Partner).

TRANSACTION_SUBTYPE = TESTDIRECTINS (Defined as External Transaction SubType when one

created the Trading Partner).

DOCUMENT_NUMBER= Any unique name

SOURCE_TP_LOCATION_CODE= testdirect (Location specified when one defined the Trading

partner)

USERNAME = Any valid Applications User

PASSWORD = User€™s password

Paste in the XML that one had obtained from the Transaction Monitor using View XML as the

PAYLOAD.

Submit the inbound. One must get a STATUS_CODE = 1000. Any other value indicates a

failure. Please review Note 152775.1 section Understanding the Oracle Transport Agent (OTA)

Protocol for a list of STATUS CODE descriptions.

Login to Oracle Applications Manager and navigate:

Select the Workflow Manager from the "Navigate to" pull-down menu and click the Go button.

Click Service Components and verify that both ECX Inbound Agent Listener and ECX Transaction

Agent Listener are running.

Search for the inbound XML. Make sure the ECX Listeners are running inside OAM. Leave the

party type BLANK.

There may be a slight delay before the transaction shows up in the Transaction monitor because it

happens only after the message is picked from the ECX Inbound queue by the listener. However

from 11.5.10.2CU, the transaction will show up in the transaction monitor as soon as the OTA

receives the message.

Click on the Document ID > View XML to see the XML contents that you had used for the

PAYLOAD.

XML Gateway Diagnostics

Run $ECX_TOP/patch/115/sql/ecxver.sql to see the basic configuration of the XML Gateway. Make

sure to spool the output so one can see if it be reviewed.

Sample Output:

SQL> @ecxver

ECX_UTL_XSLT_DIR Profile : /usr/tmp

ECX_OAG_LOGICALID Profile : /dbfiles/applcsf/log

ECX_SERVER_TIMEZONE Profile: Americas/Los_Angeles

ECX_SYS_ADMIN_EMAIL Profile: ecx_admin.email@oracle.com

ECX_XML_VALIDATE_FLAG Profile: Y

ECX_XML_MAXIMUM_SIZE Profile : 2000000

utl_file_dir : /usr/tmp,

/u02/oracle/visdb/9.2.0/appsutil/outbound/VIS_aoldev-pc

Oracle XML Parser 2.0.2.9.0 Production

Parser Version Ok

ERROR: webMethods Not Running!

--------------------------------------------------------

XML Gateway Status Summary

--------------------------------------------------------

XML Parser Version OK

All ECX Objects Valid? OK

All XML Parser Objects Valid? OK

webMethods Running? No

OTA Running? OK

Total Messages on Outbound Queue 0

OTA Msgs on Outbound Queue 0

webMethods Msgs on Outbound Queue 0

Others Msgs on Outbound Queue 0

Messages on Inbound Queue 0

---------------------------------------------------

End of Summary

---------------------------------------------------

Profile Option Value Required Default

ECX: Log File Path Log File Path where the XML

messages and runtime log are

stored

Yes None

ECX: XSLT File Path XSLT Path where XSLT style

sheets are stored

Yes None

ECX: System

Administrator Email

Address

XML Gateway System

Administrator email address

Yes None

ECX: OAG_LOGICALID Identifier for Senders

Information System

No None

ECX: Server Time Zone The time zone in which the

database server is running

Yes Null

ECX: Maximum XML

Size

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.

No 2MB

ECX: XML Validate Flag Specifies whether an outbound

document should continue to be

No Y

parsed by the engine after the

ECX: Maximum XML Size has

been met.

Use $ECX_TOP/patch/115/sql/ECXTEST.sql to do a health check of the XML Gateway installation.

Run $FND_TOP/sql/wfver.sql to obtain information about the ECX queues and packages.

To enable logging for ECX Gateway 11.5.10

1. Set the following profiles at the Site Level inside the E-Business Suite:

FND: Log Module = ecx%

FND: Log Enabled = Yes

FND: Log Level = Statement

2. After launching your ECX, you need to use Site Map > Monitoring > Logs and queried for

module: ecx

NOTE: Sometimes for it to start providing Statement level data you need to shutdown and restart

your apps tier processes using adstpall.sh. However, typically Middle tier bouncing is not required

for changes in FND profiles to take effect.

3. The output file will be in the Unexpected section of the logs for ecx in OAM.

4. One can obtain detailed ECX diagnostics data by for a transaction from sqlplus.

a. UNIX example using @$ECX_TOP/patch/115/sql/ECXTEST.sql

================Begin Script========================

spool debugint.log;

exec wf_log_pkg.wf_debug_flag := true;

exec fnd_log.g_current_runtime_level := 1;

col module format a15;

col message_text format a40;

commit;

spool off;

=================End Script=============================

b. Windows example using @%ECX_TOP%\patch\115\sql\ECXTEST.sql

================Begin Script========================

spool debugint.log;

exec wf_log_pkg.wf_debug_flag := true;

exec fnd_log.g_current_runtime_level := 1;

col module format a15 ;

col message_text format a40;

commit;

spool off;

================End Script========================

c. Sample output of ECXTEST.sql with Statement level data:

PL/SQL procedure successfully completed.

PL/SQL procedure successfully completed.

Testing Seeded Outbound Map for Oracle XML Gateway

Error Code: 0

Error Messg: ECX_SUCCESSFUL_EXECUTION

FND-Logging AFLOG MODULE Name for Log File: ecx.plsql.out.227.log

FND-Logging AFLOG MODULE Name for XML File :ecx.plsql.out.227.xml

Seeded Outbound Map for Oracle XML Gateway SUCCESSFUL..

-------------------------------------------------------------------------

Testing Seeded Inbound Map for Oracle XML Gateway

Error Code: 0

Error Msg: ECX_DOCUMENT_PROCESSED

FND-Logging AFLOG MODULE Name for Log File: ecx.plsql.in.228.log

Seeded Inbound Map for Oracle XML Gateway SUCCESSFUL...

-----------------------------------------------------------------------------

PL/SQL procedure successfully completed.

Commit complete.

d. You can also obtain Statement level diagnostics for your custom outbound test event. This

example is using the 'oracle.apps.ecx.gary.outbound' custom test event.

NOTE: Please review carefully as Support will not troubleshoot ANY customization failures due to

this test.

================Begin Script========================

spool debugout.log;

exec wf_log_pkg.wf_debug_flag := true;

exec fnd_log.g_current_runtime_level := 1;

declare

l_parameter_list wf_parameter_list_t;

l_party_site_id number;

l_params WF_PARAMETER_LIST_T;

l_document_id varchar2(300);

role_id pls_integer;

begin

l_party_site_id:= 41;

select to_char(WF_ADHOC_ROLE_S.NEXTVAL) into role_id

from SYS.DUAL;

l_document_id:= 'TESTDIRECTOUTSQL'||role_id;

WF_EVENT.AddParameterToList('ECX_TRANSACTION_TYPE', 'TESTDIRECTOUT', l_params);

WF_EVENT.AddParameterToList('ECX_TRANSACTION_SUBTYPE', 'TESTDIRECTOUTS',l_params);

WF_EVENT.AddParameterToList('ECX_PARTY_SITE_ID', to_char(l_party_site_id), l_params);

WF_EVENT.AddParameterToList('ECX_DOCUMENT_ID', l_document_id, l_params);

WF_EVENT.Raise(p_event_name=>'oracle.apps.ecx.gary.outbound',

p_event_key=>l_document_id,

p_parameters=>l_params);

end;

/

commit;

col module format a15;

col message_text format a40;

commit;

spool off;

================End Script========================

e. The diagnostics data will be in the Unexpected section of the logs for ecx in OAM.

5. So long as inbound transaction makes it through OTA and ECX_INBOUND you can use sqlplus to

get Statement Level data on 11.5.10:

a. Shutdown the ECX_TRANSACTION listener.

b. Run this select to see when ECX_INBOUND has enqueued the event on ECX_TRANSACTION after

you submit your inbound:

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. Launch the ECX_TRANSACTION listener from sqlplus logged in as apps. You need to make sure

you ran APPSORA.env before logging in:

================Begin Script========================

spool debugint.log;

exec wf_log_pkg.wf_debug_flag := true;

exec fnd_log.g_current_runtime_level := 1;

begin

wf_event.listen('ECX_TRANSACTION');

end;

/

col module format a15 ;

col message_text format a40;

commit;

spool off;

================End Script========================

d. Review spooled debugint.log for the name of the ECX debug log. This is an example of how it

looks:

Message: Starting inbound processing.

Level: 6 Module: ecx.plsql.OAG.in.GARYPOCUSTEXT.GARYSPOCUSTEXT.292.log Time: 06-SEP-05

18:03:37

>>> Message: ecx Log File

e. The output file in this case ecx.plsql.OAG.in.GARYPOCUSTEXT.GARYSPOCUSTEXT.292.log will be

in the Unexpected section of the logs for ecx in OAM.

NOTE: You will need to know how your XML transaction is launched in order to increase

diagnostics for it from sqlplus. For 'oracle.apps.ecx.gary.outbound' event, I simply raised it from

sqlplus. For POXML, you may need to use $FND_TOP/sql/wfretry.sql POXML .

To enable logging for ECX Gateway 11.5.9

1. To increase the debug level on an XML Gateway transaction in 11.5.9 the workflow must have

an item attribute called 'ECX_DEBUG_LEVEL' assigned to the event you are raising in the workflow

to generate the outbound message. Our seeded XML workflow such as POXML include the

'ECX_DEBUG_LEVEL' attribute so we can increase the debug level temporarily whenever we

require detailed debugging information. The debug level can be increased from sqlplus. You can

use the following queries from sqlplus connected as the APPS user to determine if a particular XML

workflow can have its debug level increased:

Select to find the debug level if the attribute exists:

select text_default, name from wf_item_attributes

where item_type = 'POXML' and name = 'ECX_DEBUG_LEVEL';

This is an example for increasing diagnostics for a Purchase Order XML Document:

1. Increase the debug level if the attribute exists.

update applsys.wf_item_attributes set text_default = '3'

where item_type = 'POXML' and name = 'ECX_DEBUG_LEVEL';

2. Get the proper values for the ITEM_TYPE and the ITEM_KEY. This is for PO but we also can use

the Status Monitor:

For Purchase Order:

col wf_item_key format a20

SELECT org_id,po_header_id,wf_item_type,wf_item_key

FROM po_headers_all

WHERE segment1 = '&PO_NUMBER';

For PO releases

col wf_item_key format a20

SELECT org_id,release_num,wf_item_type,wf_item_key

FROM po_releases_all

WHERE po_header_id IN (SELECT po_header_id

FROM po_headers_all

WHERE segment1 = '&PO_NUMBER');

3. Download from Metalink scripts bde_wf_item.sql from Note 187071.1. Login to sqlplus as the

user APPS, run the script and pass the workflow Item Type and workflow Item Key values obtained

in the output from step 2.

example: SQL>@bde_wf_item.sql

Please enter ITEM_TYPE:

Please enter ITEM_KEY:

Then rename the output from bde_wf_item.lst to bde_wf_item_.lst

4. The output from script bde_wf_item.sql will show you a POXML child workflow for this PO

POAPPRV

|_ POXML

Please run the script bde_wf_item.sql again for this POXML/ workflow. Then rename the output

from bde_wf_item.lst to bde_wf_item_.lst

5. $FND_TOP/sql/wfretry.sql POXML to retry the failed activity with ECX_DEBUG_LEVEL=3.

6. Open the output file from step 4. The above POXML workflow will again show you another

POXML/ workflow.

POAPPRV

|_ POXML

|_POXML

Please run the script bde_wf_item.sql once more for this POXML/ workflow too. Then rename the

output from bde_wf_item.lst to bde_wf_item_.lst

7. Using the value of the last POXML/ workflow run the script bde_ecx_out.sql from Note

167629.1.

8. Under the 'ECX: Log File Path' directory two files should have been generated for the PO

OAGOUTPOPRO.log and OAGOUTPOPRO.xml. Please collect these two files.

NOTE: An increased debug level will generate the XML payload on the filesystem. It can also be

viewed from the Transaction Monitor.

9. Collect all the requested diagnostic and log files for one particular PO, zip them and upload the

compressed file into the TAR for analysis

10. Turn off the debugger:

update applsys.wf_item_attributes set text_default = '0'

where item_type = 'POXML' and name = 'ECX_DEBUG_LEVEL';

Setting for ECX_DEBUG_LEVEL = 3 for inbound transactions:

Make a copy of the ecx_rule.inbound_rule subscription and set ECX_DEBUG_LEVEL = 3 in the

parameters section. Disable the original ecx_rule.inbound_rule subscription and enable the

copy. Do the test case again and look under 'ECX: Log File Path' profile location for the log

containing the diagnostics data.

Troubleshooting Listener Issues 11.5.9:

spool ecx_inbound.log

set serveroutput on size 100000;

begin

wf_log_pkg.wf_debug_flag := TRUE;

wf_event.listen('ECX_INBOUND');

end;

/

commit;

/

Spool off

spool ecx_transaction.log

set serveroutput on size 100000;

begin

wf_log_pkg.wf_debug_flag := TRUE;

wf_event.listen('ECX_TRANSACTION');

end;

/

commit;

/

Spool off

Selects to check messages enqueued on the ECX queues:

set linesize 155;

set pagesize 200;

set verify off;

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

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.state;

set linesize 155;

set pagesize 200;

set verify off;

select substr(ecxin.corrid,1,45) corrid,

decode(ecxin.state,

0, '0 = Ready',

1, '1 = Delayed',

2, '2 = Retained',

3, '3 = Exception',

to_char(substr(ecxin.state,1,12))) State,

count(*) COUNT

from apps.ECX_INQUEUE ecxin

group by ecxin.corrid, ecxin.state;

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;

Generic Issues:

SSL with Oracle Transport Agent (OTA):

a. The ca-bundle.crt is only used on the SENDER. The sending instance (ECX_OUTBOUND) does not

have to be configured for SSL as it is simply performing as a client such as your web browser. The

ca-bundle.crt contains all the recognized trusted CA issuers and that in order to for users who have

configured for SSL to receive HTTPS-OXTA they need a valid CA certificate issued by an official CA

that are listed in the ca-bundle.crt. For self signed certificates each trading partner will have to be

provided with the recipients server.crt so it can be appended to ca-bundle.crt for Intranet

transactions using Self Signed. The server.crt will complete the chain otherwise there will be a SSL

handshake failed: X509CertChainIncompleteErr in the Apache logs on the SENDER. The -

DOASSLCACertFile parameter in the $IAS_ORACLE_HOME/Apache/Jserv/etc/jserv.properties

(11.5.9 default) or $IAS_ORACLE_HOME/Apache/Jserv/etc/xmlsvcs.properties (11.5.10+) should

point to your certificate store such as ca-bundle.crt. The OTA XML Gateway parameters were

migrated to $IAS_ORACLE_HOME/Apache/Jserv/etc/xmlsvcs.properties in later autoconfig,

adclone, and technology template patches so that the OTA will have its own java pool to use.

b. To send to your trading partner who will accept your transaction through OTA use HTTPS-OXTA

as the protocol type. Most protocol types are documented in Note: 152775.1 in the following

section:

Understanding the Oracle Transport Agent (OTA) Protocol

PROTOCOL_TYPE

This is the Application Protocol to use to transmit the document. This also contains an identifier as

to the program to use to transmit the document over the protocol.

PROTOCOL_TYPE Meaning

HTTP Straight HTTP post

HTTPS Straight HTTP post using SSL

HTTP-OXT Use OTA protocol over HTTP

HTTPS-OXT Use OTA protocol over HTTPS

SMTP Send document via SMTP (email)

HTTPATCH Straight HTTP post with an attachment

HTTPSATCH Straight HTTP post using SSL with an attachment

OTAHATCH Use OTA protocol over HTTP with an attachment

OTAHSATCH Use OTA protocol over HTTPS with an attachment

NOTE: Only the OTA related protocols are listed. Please review the Oracle XML Gateway Users

Guide Release 11i for a listing of all protocols.

c. Fixing a self signed for OTA:

1. Access the main web page https://aoldev-pc.us.oracle.com:8443.

2. Double-click on the padlock at the bottom of the page to view the Certificates. If there is no

padlock, then on the top toolbar:

select File->Properties->Certificates

3. Select the Certification Path tab and:

a) click on the first line and then View Certificate.

This will be the certificate for the root Certifying Authority (CA).

b) On Details tab click Copy to File, this will start the export wizard.

c) Click Next to continue.

d) Select Base-64 encoded X.509 (.CER) and click next.

e) Enter ca1 as the name and click ok to export the certificate.

f) Repeat steps a through e for each line on the Certification Path tab.

Incrementing the file name each time by 1, i.e. ca2, ca3.

Note: It is important that you do the lines in order.

One won't be able to view the certificate for the last line.

g) Close the wizard and IE.

h) FTP the files you created back to the server in binary mode.

i) Concatenate the files in reverse order and save as ca-bundle.crt

(cat ca2.cer ca1.cer >> ca-bundle.crt).

Sending a transaction through your proxy using OTA:

Set the following in the $IAS_ORACLE_HOME/Apache/Jserv/etc/jserv.properties or

$IAS_ORACLE_HOME/Apache/Jserv/etc/xmlsvcs.properties for depending on the TXK

template/autoconfig patch one has applied:

wrapper.bin.parameters=-DOXTAOutUseProxy=true

wrapper.bin.parameters=-DOXTAOutProxyHost=

wrapper.bin.parameters=-DOXTAOutProxyPort=

>>

References

NOTE:152775.1 - Installing Oracle XML Gateway and Oracle Workflow with Oracle Applications 11i

NOTE:187071.1 - bde_wf_item.sql - Runtime Data of a Single Workflow Item

NOTE:204162.1 - General Oracle XML Gateway FAQ

NOTE:337428.1 - XML Gateway Setup Testing and Diagnostics

f1 !6m6lpiu8b