OCI – Open Catalog Interface (4.0)
References
- Note:1287412 – Prerequisites for OCI integration in SRM 7.0
- Open Catalog Interface 5.0, OCI5, Specification: https://scn.sap.com/docs/DOC-35441 by Michael Judd (including the link where to find it on SAP Service Market Place) – OCI 5.0 is not an evolution, but more a revolution from OCI 4.0, they can co-exist though.
- Forum post: Is it possible to change/delete the hidden parameter sap-client of the OCI-Call?
General
This document is related to Punchout Catalogs, also known as OCI 4.0. I referenced the OCI 5.0 document as it is more up to date with the latest additions to the OCI 4.0 specification.
For a better view of the possibilities of OCI 5.0 the above mentioned document will be of further help.
The information is mainly aimed at SRM consultants seeking a better understanding of OCI 4.0, debugging the interface itself and at suppliers wanting to make their catalog OCI 4.0 enabled. SRM 7.0 EhP1 using the inbuilt HTML-NWBC is the SRM server version that is used as reference.
I won’t get into any detail regarding the return parameters as they are documented enough in the OCI 5.0 document.
The OCI interface is a simple protocol that launches a supplier catalog using a simple HTTP get or post command, also the return from the catalog is a simple post back to SRM.
OCI call
SRM customizing
The call to the external catalog is maintained in SPRO customizing, from SRM 7.0 onwards you should always use the standard call structure option. You can find it under:
SPRO -> SAP Supplier Relationship Management -> SRM Server -> Master Data -> Content Management -> Define External Web Service
In the call structure you define which parameters should be send to the external catalog, the above example (a call to Ariba Procurement Catalog) is one with a lot of variables. The simplest variant that works (but might not be completely up to the standard ;)) is a simple:
Outbound handler
The outbound handler is a new addition in SRM7, what it does is that it doesn’t call the external catalog directly, but opens it in a window using an iframe and a back link and adds some processing that wasn’t done anymore due to the change of using WebDynpro technology from the older ITS:
You can disable it in the call structure in the customizing using the parameter “BYPASS_OUTB_HANDLER” and set the value to X so that the old logic is used.
For the inbound handler the same procedure can be used but then the parameter is called “BYPASS_INB_HANDLER”.
Call sequence
Before the actual call to the external catalog is made SRM goes through a few more routines, getting some more variables using the BBP_CAT_CALL_ENRICH badi, creating the iframe and finally calling the catalog.
In the above screenshot the POST entries are the most interesting. The first 3 are calls to the SRM system itself (or portal).
To find the classes that handle these posts you will have to check transaction SICF and find the corresponding handlers of the called URL.
- The first POST is an internal call to the shopping cart webdynpro when pressing on the link to open the external catalog.
- The 2nd POST is handled in class CL_NWBC_HTTP (remember this document was created with the HTML-NWBC client).
- The 3rd POST is handled in class /SAPSRM/CL_CH_WD_OUTBOUND_HDLR, if you want to see how the HTML data is created this is the class that you want to check out. See for some more information the thread on the forum which is mentioned in the references at the top.
- And finally the last POST which is the actual call to the external catalog, the data that is used here is actually the same that was used in the 3rd POST.
For debugging purposes you can place external breakpoints in each of those classes, another good spot to put a breakpoint is function module /SAPSRM/CLL_WSI_CALL (or WSI_CALL in SRM5.0).
If we take the most basic catalog call structure the final HTML form contains the following parameters:
As you can see, SRM makes the call OCI 4.0 compliant itself!
BBP_CAT_CALL_ENRICH
If you need to dynamically enrich the catalog call you can implement the BBP_CAT_CALL_ENRICH badi, for example if you want to add an attribute that is maintained in the organizational model for the user that calls the external catalog for instance. In SRM a standard implementation is available (BBP_BUSINESSCARDS), to take a look at this go to SE18, in the Badi name fill in the BBP_CAT_CALL_ENRICH and click on Enhancement implementation -> Overview in the menu.
Below a small example of the main thing to do from the example badi:
" Tel-No READ TABLE it_data_tel INDEX 1 INTO wa_data_tel. wa_post_values-fieldname = 'Telephone'. "#EC NOTEXT wa_post_values-fieldcont = wa_data_tel-tel_no. APPEND wa_post_values TO ct_post_values.
OCI return
The OCI return is again a simple HTML form, containing all the item data that the user selected during his stay in the external catalog. The main thing to keep in mind here is that when you receive the HOOK_URL parameter that you have to save it in a session/cookie or database as-is. Whatever you do with it – don’t change it! You will need the exact string again when the shopper wants to return SRM.
Example taken from note 1287412:
b. Target
Specifies the frame to which a catalog is to return data in a frame-based environment.
Catalog providers must ensure that they post to a specific target which is defined and supplied by SRM. This can be verified in the “form tag” in the HTML that is sent by the catalog:
Complete example:
BBP_CATALOG_TRANSFER
The BBP_CATALOG_TRANSFER badi is called after coming back from the external catalog. The most common usage for this badi is to do a mapping from a general product category classification like UNSPSC to a company specific category classification. Other uses are the transfer of the CUST_FIELD1-5 fields to specific shopping cart item (customer) fields.
It is possible that you want to start debugging in case of problems before the badi is called. In that case take a look at the /SAPSRM/CL_CH_WD_INBOUND_HDLR class (if enabled) or in function module WSI_IMPORT_DATA.
Extensibility
It is possible to extend the OCI interface beyond the 5 customer fields that SAP provides, to enable this you have to create an append for structure CI_OCI_CUSTOMER_EXTENSION. The field that you maintain here for example ZEXTRA_FIELD can then be transferred with the extra hidden field NEW_ITEM[n]-ZEXTRA_FIELD. This is more useful if you have also control of the “external” catalog as most suppliers will want to have one single OCI form to work with (although it would be great if suppliers could add fields when the customer asks for it). Things that typically are asked for:
- Indicator if the item should be handled as a free-text item
- Tax code
- …
In the OCI documentation a reference is made to include CI_BBP_SC_ITEM, I have never used this include and have always taken the more common INCL_EEW_PD_ITEM_CSF(_SC) to add customer fields to the shopping cart item data and fill those fields in the transfer badi.
Restrictions
The newly added hierarchy fields can only be used in a sourcing process using RFQ (wouldn’t it be great if you could add a hierarchy into a shopping cart to group certain items together!).
New NetWeaver Information at SAP.com
Very Helpfull