You are on page 1of 25

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 partnertransaction 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 = Users 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 ECX: Log File Path

Value Log File Path where the XML messages and runtime log are stored

Required Yes

Default 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 No 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.

2MB

ECX: XML Validate Flag Specifies whether an outbound No document should continue to be

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