OCI Interface Setup: from Call Structure to Testing
A practical guide to connecting a supplier shop to SAP and other procurement systems
The OCI interface connects a procurement system with an external web catalog. This entry describes what to clarify before setup, what the call structure looks like, which fields need to be aligned and where integrations typically fail.
- Checklist before setup
- Call structure with HOOK_URL
- Field mapping for units and material groups
- Test cases and typical errors
What Is an OCI Interface?
The OCI interface is the technical connection between a procurement system and an external web catalog based on SAP's Open Catalog Interface. It consists of a configured catalog call with parameters and a return through which the catalog hands the selected items to the procurement system.
Standard, Catalog and Interface: How They Relate
Three things tend to get mixed up. OCI is the standard, meaning the rules for call and return. The OCI catalog is the supplier's shop that implements those rules. The OCI interface is the specific, configured connection between your procurement system and one such catalog. This entry covers the setup; the flow and field list of the standard are described in the OCI entry.
What to Clarify Before Setup
- Calling system: which application do users jump from, for example SAP SRM, SAP ERP, S/4HANA or an upstream procurement platform?
- Credentials: does the supplier provide one technical user per customer, or are individual users passed? What are the shop's login parameters called?
- Test environment: is there a test shop you can work against from your development or quality assurance system?
- Field scope: which return fields does your system evaluate, and which can the shop fill?
- Master data: which material groups, units of measure and vendor numbers apply in your system?
- Display: does the catalog open in the same window, in a new window or embedded in a frame?
- Network: the shop must be reachable from the users' browsers, and so must the return address of your procurement system. A direct connection between the servers is not required for the standard return.
Configuring the Call Structure
In the procurement system the catalog is stored as an external web service with a call structure. In SAP SRM this is done in Customizing where external web services are defined; SAP ERP and S/4HANA have comparable settings for catalogs in the purchase requisition. Each row of the call structure has a name, a content value and a type.
| Parameter name | Type | Content |
|---|---|---|
| (no name) | URL | Address of the catalog, for example https://shop.supplier.example/oci |
| USERNAME | Fixed value | Technical user the supplier has set up for you |
| PASSWORD | Fixed value | Corresponding password |
| LANGUAGE | SAP field | System field for the logon language, so the shop starts in the right language |
| HOOK_URL | Return URL | Left empty; the system inserts the return address at runtime |
| ~OkCode | Fixed value | ADDI |
| ~target | Fixed value | _top |
| ~caller | Fixed value | CTLG |
The order of the rows determines how the call is assembled. Further parameters, such as a client identifier or a view selector, are agreed individually with the supplier. Where possible, the call should use HTTP POST rather than GET so that credentials do not end up in the address bar and in logs.
Aligning the Field Mapping
The standard prescribes the field names but not the values. The following points cause most of the questions in integration projects.
| Topic | What matters |
|---|---|
| Units of measure | NEW_ITEM-UNIT expects an ISO code. In the procurement system an ISO code must be maintained for every internal unit used, otherwise the item is rejected. |
| Material groups | NEW_ITEM-MATGROUP must contain a material group known in the system. Alternatively the shop supplies a classification in NEW_ITEM-EXT_SCHEMA_TYPE and NEW_ITEM-EXT_CATEGORY_ID, which the procurement system maps to material groups. |
| Vendor | NEW_ITEM-VENDOR contains your vendor number, not the customer number from the supplier's point of view. For single-supplier catalogs the number can also be fixed in the system. |
| Price and price unit | NEW_ITEM-PRICE refers to NEW_ITEM-PRICEUNIT. If the price unit is not taken over, the item value is off by the corresponding factor. |
| Short text | NEW_ITEM-DESCRIPTION is limited to 40 characters. The shop should truncate sensibly and supply the full text as long text. |
| Character set | Shop and procurement system must use the same character encoding, otherwise umlauts and special characters arrive corrupted. |
| Number format | Quantities and prices are passed with a decimal point and without thousands separators. |
If a mismatch cannot be solved in the shop, the remaining option is to adjust values on transfer in the procurement system. SAP SRM provides the BAdI BBP_CATALOG_TRANSFER for this.
Test Cases Before Go-Live
Login
The jump leads straight into the shop, with the right customer, assortment and language.
One item
A single item arrives correctly with short text, quantity, unit, price, currency and supplier part number.
Several items
A cart with many items is transferred completely and in the right order.
Special values
Items with a price unit other than 1, with decimal quantities, with umlauts and with long descriptions.
Cancel and timeout
The user returns without selecting anything or lets the session expire. The procurement system is left in a clean state.
Downstream processing
After account assignment and approval, the transferred items become a purchase requisition and a purchase order the supplier can process.
Typical Errors and Their Causes
| Symptom | Common cause |
|---|---|
| User lands on the shop's login page | Login parameters named incorrectly or not passed; call uses GET instead of POST or vice versa |
| Cart arrives empty | Return is not posted to the HOOK_URL supplied, field names deviate from the standard, or the item index does not start at 1 |
| Item rejected because of the unit of measure | No ISO code passed, or no mapping to the internal unit maintained in the procurement system |
| Error message about the material group | Material group unknown in the system, classification mapping missing |
| Price off by a factor of 10 or 100 | Price unit not passed or not evaluated; decimal comma instead of decimal point |
| Umlauts appear as garbled characters | Different character encoding in shop and procurement system |
| Session is lost on return | Shop runs embedded in a frame and the browser blocks third-party cookies; return target does not match the window structure |
Security and Data Protection
Call and return should run over HTTPS only. Technical users in the shop need no more than the right to fill and transfer a cart; placing an order directly in the shop should be disabled for these accounts. Pass only the user data the shop really needs. One technical login per customer is often enough, without names or email addresses of individual employees.
Related Terms and Matching Ovenca Pages
- OCI (Open Catalog Interface)
The standard itself: flow, return fields with an example, and versions.
- OCI catalog
The connected supplier shop and how it compares with static catalogs.
- cXML punchout
The alternative when your procurement system or the supplier relies on cXML.
- Managing punchout interfaces in the admin area
Maintain OCI parameters and access rights for punchout catalogs centrally.
- Planning the SAP SRM successor
What happens to existing OCI catalogs when SAP SRM is replaced.
- Procurement with SAP S/4HANA
Integration via OCI, cXML or API.
OCI Interface in Four Steps
From alignment with the supplier to go-live
1. Clarify the framework
Calling system, credentials, test shop and field scope are agreed with the supplier before anyone configures anything.
- Technical user per customer
- Test environment on both sides
- List of required fields
2. Create the call structure
Catalog URL, login parameters and the return URL are stored in the procurement system as a web service.
- HOOK_URL as return URL
- Fixed values ~OkCode, ~target, ~caller
- Call via POST over HTTPS
3. Align the fields
Units of measure, material groups, vendor number and price unit have to match the master data of the procurement system.
- ISO codes for units
- Material groups or classification
- Character set and number format
4. Test and release
Test carts cover the normal case, special cases and cancellation. Only then are productive credentials entered.
- Single and multi-item carts
- Special characters and price units
- End-to-end run to the purchase order
Manage Punchout Interfaces Centrally
With Ovenca you maintain punchout connections in one place instead of configuring every supplier shop individually in the ERP.
- OCI parameters in the admin area
- You manage the OCI parameters and interfaces of the connected supplier shops directly in Ovenca's admin area.
- Access control per user
- Permission management determines who may use which punchout catalogs.
- One cart, one approval
- Items from punchout shops and imported catalogs come together in one cart and run through the same multi-level approval process.
- OCI and cXML
- Ovenca supports both punchout protocols, so suppliers can keep the integration they already have.
- Handover to the ERP
- Ovenca hands approved requisitions and orders to your ERP via an interface.
- Operating model of your choice
- On-premise, private cloud or hybrid: you decide where the platform runs.
OCI Interface: Questions and Answers
Related pages
OCI Integrations Without One-Off Projects
We show you how to connect supplier shops centrally and hand the items over to your ERP cleanly.