Punchout White Paper - Release 12 (Doc ID 1177725.1) To Bottom

Modified:05-Aug-2013 Type:WHITE PAPER

In this Document

Abstract

History

Details

Punchout Overview

Punchout Models

Technical Requirements

Punchout Setup

Troubleshooting Punchout

References and Useful Notes

Known Patches

Related Documents

References

APPLIES TO:

Oracle Exchange Marketplace - Version 6.2.3 to 6.2.5 [Release 6] Oracle iProcurement - Version 12 to 12.2.1 [Release 12 to 12.2] Information in this document applies to any platform.

ABSTRACT

This white paper provides information on the Punchout feature from iProcurement, including basic setup, and some overview of the integration with other modules. It also contains key technical information and troubleshooting techniques.

HISTORY

Author: Clarina Allen Create Date 16/Aug/2010 Update Date 03/01/2012

DETAILS

Punchout Overview

Punchout is a feature from iProcurement and Oracle Exchange which allows to access the external catalog and bring the items to iProcurement in order to create requisitions. The external catalog can be hosted by Oracle Exchange, a third party organization or by the supplier. Following a schematic sample of the Punchout process in iProcurement:

1. Requester/preparer clicks the Punchout link. 2. Login request is sent to the supplier server. 3. Supplier authenticates the access and sends the login response. 4. iProcurement redirects the browser to the supplier catalog site. 5. Requester/preparer searches the items and returns to iProcurement. 6. Shopping cart is processed by iProcurement. Once the requisition is created and converted to a Purchase Order, the PO document can be sent to the supplier directly or through OSN (Oracle Supplier Network). This feature is not part of Punchout, however it is mentioned to give an idea of the indirect integration and cycle on the procurement process. The start is to find the punchout model to be used or being used in the process. The Punchout models and messages are documented in the following manuals: Oracle Procurement Buyer's Guide to Punchout and Transparent Punchout Oracle Procurement Supplier's Guide to Punchout and Transparent Punchout The documentation is the same for 11.5.10.2+ and release 12. There is no specific manual for release 12.

Punchout Models

Punchout can be executed from iProcurement or Oracle Exchange.

The Punchout Models available are:

From Type Model

iProcurement XML Model 1: Punchout from Oracle iProcurement to Oracle Exchange

iProcurement XML Model 2a: Punchout from Oracle iProcurement Directly to Supplier-

Hosted Catalog

iProcurement cXML Model 2b: Punchout from Oracle iProcurement Directly to Supplier-

Hosted Catalog

Exchange XML Model 3a : Punchout from Oracle Exchange to Supplier-Hosted Catalog

Exchange cXML Model 3b: Punchout from Oracle Exchange to Supplier-Hosted Catalog

iProcurement XML Model 4: Punchout from Oracle iProcurement to Supplier-Hosted Catalog

via Oracle Exchange

iPprocurement cXML Model 5: Punchout from Oracle iProcurement to Supplier-Hosted Catalog

via Oracle Exchange

Model 5: In this model, the supplier hosts a cXML catalog at its own site or Web store, which the requester in Oracle iProcurement accesses (invisibly) via Oracle Exchange. The supplier must set up a punchout from Oracle Exchange to its Web store. The Oracle iProcurement administrator, using the eContent Manager in Oracle iProcurement, must download the supplier's punchout definition from Oracle Exchange.

Transparent Punchout is used when users do not see the supplier site. The system will search the supplier sites and bring the item in iProcurement search results page along with local items. It is for iProcurement only. The URL is like: http://[exchangeURL]/dsearch/DistributedSearchLogin.jsp or http://[supplierURL]/dsearch/DistributedSearchLogin.jsp The Transparent Punchout Models available are: . Model 1: Transparent Punchout from Oracle iProcurement to Oracle Exchange (XML) . Model 2: Transparent Punchout from Oracle iProcurement to Supplier-Hosted Catalog (XML) Re-punchout allows to view later the item on the supplier site from the created requisition line. To use this feature, supplier provides the Supplier Config ID in the xml message which becomes a hidden number in the requisition and purchase order. The Supplier Config ID cannot be edited in Oracle iProcurement and Oracle Purchasing. Also, the applications do not check whether the Supplier Config ID is still valid during purchase order creation, but assume that it is. Only standard purchase orders support

the Supplier Config ID field. In re-punchout, the supplier part auxiliary id is not stored in the requisition lines table. Only the supplier part id is in the requisition line table. The configuration number for re-punchout is supported by the following models only: . Model 2a: Punchout from Oracle iProcurement Directly to Supplier-Hosted Catalog (XML) . Model 2b: Punchout from Oracle iProcurement Directly to Supplier-Hosted Catalog (cXML) . Model 4: Punchout from Oracle iProcurement to Supplier-Hosted Catalog via Oracle Exchange (XML) . Model 5: Punchout from Oracle iProcurement to Supplier-Hosted Catalog via Oracle Exchange (cXML)

Technical Requirements

In release 12 the technology stack is more compatible than in 11.5.10. Punchout is based on the Java (JDK) installed with Oracle Applications, the libraries from rdbms 10.1.2 and proper certificate if SSL installed in Oracle Applications, supplier site, or third catalog site.

Punchout Setup

1. In iProcurment Punchout is configured by following steps 1.1. Go to iProcurement Catalog Administration responsibility > Stores > Content Zones 1.2. In the dropdown list choose Create Punchout Content Zone or Create Transparent Punchout Content Zone. 1.3. Click GO 1.4. Enter the Punchout information 1.5. Click Apply 1.6. Now go to Stores > Stores 1.7. Create a new store or choose an existing one 1.8. Add the Punchout definition created above in the Content Zone. In release 12 the realms were replaced by Content Zone which is used to restrict access by category, suppliers, operating units, and/or responsibilities.

2. Download from Exchange If you are executing Punchout to/or through Oracle Exchange, choose the option Exchange in the Source. The Punchout URL for exchange is: https://exchange.oracle.com/orders/LinkinLogin.jsp or https://testexchange.oracle.com/orders/LinkinLogin.jsp.

Once the Punchout is defined, a Download Punchout icon will show up in the Manage Content Zones page where the content zones are listed. This will take to Oracle Exchange where the suppliers are listed. Click the link to Synchronize Suppliers. If the supplier is not listed, go to Oracle Exchange > Purchases > Control Punchout Access and choose the supplier. If supplier is not listed it is more likely they haven't published the Punchout definition in Exchange. If there is a connectivity error, check Troubleshooting Punchout section below. 3. Profiles There are three main profiles in Punchout: 3.1.POR :CA Certificate File Name If you are punching out to a secure site (including punching out via a secure site), enter the absolute file path of the certificates file that stores the certificates' names that your company will accept. The file should be readable and accessible from the middle tier. The certificate file is located at tech_st directory structure: /.../apps/tech_st/10.1.2/sysman/config/b64InternetCertificate.txt The path is a full explicit path where the file resides. 3.2. POR :Proxy Server Name Enter the proxy server (web server) name if your iProcurement implementation has a proxy setup.The proxy server name is typically the same as the proxy server that is set up in people's browsers in your company's for example, www-proxy.company.com. 3.3.POR :Proxy Server Port Enter the proxy server port for the server defined in profile POR :Proxy Server Name. If profiles above are not set properly, errors like Connection refused, SSL handshake errors could occur. Note: If profiles are changed bounce the entire application for the change to take effect. 4. Certificates The certificate is required if one of the involved sites are secured (SSL enabled). Profile POR :CA Certificate File Name will be used to execute the handshake and verify the valid certificates. If any site involved in the Punchout process is using certificate which is not included

in the b64InternetCertificate.txt (or the file from profile POR :CA Certificate File Name), append it in the file:

4.1. Navigate to the supplier site 4.2. Double click on the padlock icon at the bottom of the browser window or at the top at the end of the URL of the page depending on the browser version. 4.3. Select the Details tab. 4.4. Click the Copy To File button 4.5. Export the (Chain) Certificates from IE in Base 64 encoding. 4.6. Open the exported file using a text editor (such as Notepad) 4.7. Update the b64InternetCertificate.txt (or the file from profile POR :CA Certificate File Name) by copying the details of the exported certificate 4.8. If there is a chain of certificates, add all in the correct order. 4.9. Bounce OC4J / middle tier after the change in the certificate bundle file.

5. Credentials and Access The credentials are defined and used for validation by the supplier (optional), besides the proxy username and password defined in the Punchout definition page. The validation of the access to the supplier or third party site is not standard and it is defined by the third party or supplier according to their system. If using Punchout to or through Oracle Exchange, supplier Punchout needs to be published in Oracle Exchange. Also buying organization needs to get access from Control Punchout Access from Oracle Exchange.

In case the DUNS number is used by the supplier, it is mapped from <supplierDUNS> or <supplierTradingPartnerCode> in the xml/cxml message to EDI location field in core purchasing (Purchasing responsibility > Supply Base > Suppliers) in the Supplier Site belonging to the Operating Unit tied to iProcurement responsibility.

Troubleshooting Punchout

1. From the buyer side 1.1. If changing a punchout definition with a different URL or model, it is recommended to create a new Punchout definition instead of re-using an existing one. 1.2. Check DNS setups on the applications host so that it can find the supplier punchout host by name as well as by IP address. 1.3. Check NetCache Fire Rules to allow HTTPS tunneling. 2. From the supplier side 2.1. Check if the supplier is receiving the correct credentials to access their site. 2.2. Verify if supplier is passing the message in the correct format as shown in the manual listed in this note. 2.3. Contact supplier if the issue is not from the buyer side.

3. Checking the libraries and java path The libraries being used in the Punchout process are: /.../apps/tech_st/10.1.3/jlib/jssl-1_1.jar /.../apps/tech_st/10.1.3/jlib/javax-ssl-1_1.jar /.../apps/tech_st/10.1.3/lib/libnjssl10.so /.../apps/tech_st/10.1.3/lib32/libnjssl10.so Check if the path to those libraries are set in ORA_CONFIG_HOME/10.1.3/opmn/conf/opmn.xml in variable $LD_LIBRARY_PATH. Also, check the CLASSPATH (library path) from $ORA_CONFIG_HOME/10.1.3/j2ee/oacore/application-deployments/oacore/orion-application.xml to see if the standard $JAVA_TOP is the first entry in the library path. The file permissions need to be set for applmgr (applications system user) access. 4. Testing with standalone code There is a standalone code TestPunchout.class in $JAVA_TOP/oracle/apps/icx/punchout/util directory to test the connectivity to the Punchout site. However, as we are not passing the credentials it will not establish the connection. It only checks if the site can be reached. To run the test execute the steps: 4.1. Set the CLASSPATH variable to include the current directory as well as the javax-ssl-1_1.jar and jssl-1_1.jar. These two files reside under /.../apps/tech_st/10.1.3/ You may need to run a command similar to the one given below to set the CLASSPATH env variable: $ CLASSPATH=$CLASSPATH:/db/oracle/VIS/apps/tech_st/10.1.3/jlib/jssl-1_1.jar:/db/oracle/VIS/apps/tech_st/10.1.3/jlib/javax-ssl-1_1.jar $ export CLASSPATH 4.2. Set the shared library path LD_LIBRARY_PATH to include the directory where the shared SSL library used by iProcurement resides. The libraries are the ones from directory /.../apps/tech_st/10.1.2. Usually they are set already in $LD_LIBRARY_PATH is using iProcurement. 4.3. Run the following command: $ java oracle.apps.icx.punchout.util.TestPunchout <Supplier url> <cacert> <isCXML> <proxyHost> <proxyPort> OR $ java oracle.apps.icx.punchout.util.TestPunchout <Supplier url> <cacert> <isCXML> if not using proxy

Replace: <cacert> with the value of profile "POR : CA Certificate File Name" <isCXL> to be replaced with either 'Y' or 'N'. If you are using cxml provide the value as 'Y' <proxyHost> and <proxyPort> replace with the value of profile POR :Proxy Server Name and POR: Proxy Server Port <Supplier url> is the supplier URL. After running the script check the log generated in TestPunchout.log. Sample of the output: ========================== HttpsURL ========================== HttpsURL() ----url=https://ABC.com/login.do init() ----proxyHost=null ----proxyPort=80 ----CACertFile=/global/oracle/visprc05/apps/tech_st/10.1.2/sysman/config/b64InternetCertificate.txt readCACerts() ----CACertFile=/global/oracle/visprc05/apps/tech_st/10.1.2/sysman/config/b64InternetCertificate.txt ----CACerts.size()=51 openConnection() setContentType() ----contentType=text/xml getOutputStream() connect() createConnection() ----hostName=www.ABC.com ----portNum=9999 ----secure=true ========================== HttpsURL ========================== Response from external site: null ---> means no connection to the supplier site ##### END TestPunchout ##### [Mon Aug 12 08:50:15 EST 2010]

5. How to get the detailed error message When the punchout fails usually it shows message like: Error ABC (direct): The connection to the supplier website cannot be established. Show technical details of this error Click the link or the plus signal to see the detailed error message. 6. Finding the XML/cXML document from Punchout transaction iProcurement as well Exchange does not store the XML/cXML messages being passed or returned to/from supplier sites. To capture the message execute the debug.log following the steps from Note 290614.1:How To Get Log Files In iProcurement. Look for entries like for example (the entry will depend on the Punchout model): PUNCHOUTDEBUG: -xmlDoc=<?xml version = '1.0' encoding = 'UTF-8'?> <response> <header version="1.0"> <return returnCode="S"/> </header> <body> <loginURL> <![CDATA[https://ABC.com]> </loginURL> </body> </response> PUNCHOUTDEBUG: -shopping cart=<?xml version = '1.0' encoding = 'UTF-8'?> <response> <header version="1.0"> <return returnCode="S"/> </header> <body> <OrderLinesDataElements> <catalogTradingPartner> <![CDATA[OracleExchange]]> </catalogTradingPartner> <orderLine> <contract> <catalogType> <![CDATA[CONTRACTED]]> </catalogType> </contract> <item lineType="GOODS" quantity="10.0"> <itemNumber>

<supplierItemNumber> <supplierReferenceNumber> <![CDATA[]]> </supplierReferenceNumber> <itemID> <![CDATA[XYZ]]> </itemID> </supplierItemNumber> </itemNumber> <itemDescription> <![CDATA[XYZ description]]> </itemDescription> <unitOfMeasure> <supplierUnitOfMeasure> <supplierUOMType> <![CDATA[EA]]> </supplierUOMType> <supplierUOMQuantity> <![CDATA[]]> </supplierUOMQuantity> </supplierUnitOfMeasure> </unitOfMeasure> </item> <category> <categoryCode categoryCodeIdentifier="SPSC"> <![CDATA[999999]]> </categoryCode> </category> <price> <currency> <![CDATA[USD]]> </currency> <unitPrice> <![CDATA[9.99]]> </unitPrice> </price> <supplier> <supplierDUNS> <![CDATA[123456789]]> </supplierDUNS> </supplier> </orderLine> </OrderLinesDataElements> </body>

</response> If the entries are not generated in the debug.log, requesting the XML/cXML message to the supplier will help to see if the message format is compliant with the DTD's listed in the Punchout manuals.

References and Useful Notes

The useful notes are added as reference in this note.

Known Patches

Recommendation is to keep the instance updated with the latest release available from 12.0 (Procurement RUP patch) or 12.1 latest release.

Related Documents

The manuals available are the same from release 11.5.10:

Oracle Procurement Buyer's Guide to Punchout and Transparent Punchout Oracle Procurement Supplier's Guide to Punchout and Transparent Punchout

Located at:

http://www.oracle.com/technetwork/indexes/documentation/index.html > Applications Releases 11i and 12 > Oracle Applications 11.5.10.2+ Online Documentation Library > Documentation tab.

OR http://www.oracle.com/technology/documentation/applications.html> Oracle Applications 11.5.10.2+ Online Documentation Library > Documentation tab

The direct links are: http://docs.oracle.com/cd/B25516_18/current/acrobat/icx115punchbuy.pdf

http://docs.oracle.com/cd/B25516_18/current/acrobat/icx115punchsup.pdf

REFERENCES

NOTE:1354129.1 - What Version Of cXML Does Oracle Support For Punchout ? NOTE:1358993.1 - iProcurement Punchout to Non-Oracle Exchange Site Results in 700 Authentication Failure - Language Not Supported NOTE:137145.1 - How to configure Oracle Portal with SSL and Global Server Certificates in Portal 3.0.9 NOTE:206646.1 - Punchout FAQ NOTE:252907.1 - Unable To Do Direct cXML Punchout To Supplier; Connection To Supplier Website Cannot Be Established NOTE:281613.1 - Error Code: 700 Authentication Failure Executing Punchout NOTE:377320.1 - How to Diagnose a Punchout Issue NOTE:1569752.1 - Punchout Connection Fails With SSL Handshake Failed: SSLIOClosedOverrideGoodbyeKiss NOTE:317606.1 - Error Code: 201 Unable To Reach Supplier Site: UnknownHostException NOTE:760866.1 - How To Add The Certificate To The Apache Certificate File For Punchout Suppliers Using HTTPS? NOTE:356128.1 - How to Run the Punchout TEST Delivered With Oracle Applications? NOTE:359557.1 - Punchout Fails To Connect Via Proxy Server NOTE:382890.1 - Supplier and Supplier Site Not Populated On The Requisition From Punchout NOTE:428729.1 - After Setup A New SSL Certificate Bundle Punchout Still Fails With X509CertChainInvalidErr NOTE:456335.1 - FAQs For Punchout In Release 12 NOTE:290614.1 - How To Get Log Files In iProcurement NOTE:1537727.1 - How to Make the Quantity Field Editable After Returning from a Punchout Session?

Related

Products

Oracle E-Business Suite > Procurement > Exchange > Oracle Exchange Marketplace > Punchout Issues > Punch In to Exchange from iP

Oracle E-Business Suite > Procurement > Procurement > Oracle iProcurement > Punchout to Supplier or hub > Punchout Config, Setup & Maintenance

Keywords

CERTIFICATE; CONNECTION REFUSED; CREATE REQUISITIONS; CREDENTIALS; HANDSHAKE; HANDSHAKE ISSUE;MODEL; PUNCH OUT; PUNCHOUT; PUNCHOUT MODEL; SHOPPING CART; TRANSPARENT PUNCHOUT

Back to Top