Introduction

With the OCI Punchout feature, the Commerce Management application offers an external catalog interface (OCI) for B2B customers. This allows external systems to access product data from an Intershop server or a selection of products. It uses the official OCI transfer format. The Punchout format can be configured at the application level or individually at runtime with customer-specific settings.

Glossary

References

The following documentation is related to the OCI Punchout feature:

• Concept - OCI Punchout (valid from 7.10.17) - Basic concepts, OCI Punchout functionality (this document)

• Guide - B2B Storefront Functionality (valid from 7.10.17) - See chapters "OCI Punchout" and "OCI Punchout Configuration"

• Intershop documentation (Intershop B2B Frontend API | Punchout) - Documentation of the Punchout REST API

• Cookbook - OCI Punchout - Recipes on frequently asked questions

• Overview - Configuration Framework - Reference when customizing placeholders or formatters

Features

To understand the OCI Punchout, a list of features for storefront and account administration is given below.

Storefront Features

Administration Features

REST Features

Functionality

This chapter describes technical insights of the OCI Punchout standard.

OCI Transfer Format

The OCI data is transferred using hidden input fields of an HTML form with a defined field name including an index starting with 1.

<form name="form" method="post" action="123" data-testing-id="oci-basket">
    <input type="hidden" name="NEW_ITEM-DESCRIPTION[1]" value="Sony VPL-SW225">
    <input type="hidden" name="NEW_ITEM-MATNR[1]" value="">
    <input type="hidden" name="NEW_ITEM-QUANTITY[1]" value="1">
    <input type="hidden" name="NEW_ITEM-UNIT[1]" value="">
    <input type="hidden" name="NEW_ITEM-PRICE[1]" value="988.01">
    <input type="hidden" name="NEW_ITEM-CURRENCY[1]" value="USD">
    <input type="hidden" name="NEW_ITEM-PRICEUNIT[1]" value="">
    <input type="hidden" name="NEW_ITEM-LONGTEXT_1:132[]" value="Sony VPL-SW225, 2600 ANSI lumens, 3LCD, WXGA (1280x800), 6000h, 210W, UHP">
    <input type="hidden" name="NEW_ITEM-VENDOR[1]" value="IQ">
    <input type="hidden" name="NEW_ITEM-VENDORMAT[1]" value="">
    <input type="hidden" name="NEW_ITEM-MANUFACTCODE[1]" value="Sony">
    <input type="hidden" name="NEW_ITEM-MANUFACTMAT[1]" value="VPL-SW225+TM-ST2">
    <input type="hidden" name="NEW_ITEM-EXT_PRODUCT_ID[1]" value="0027242869158">
</form>

Technically, we reuse the product, basket product line item, and/or customer information to display one or more products.

OCI Punchout Catalog Browsing

Intershop Commerce Management allows to log on to a storefront as OCI Punchout user. A reduced storefront (e.g. no footer, reduced header, no checkout process) is then available. An OCI Punchout user can still search or add products to a shopping cart that can be transferred back to a referenced (procurement) system (see HOOK_URL).

Login URL

The OCI Punchout URL is publicly available and can be accessed by any OCI Punchout user with valid credentials. The URL pattern is described below:

https://<HOST>/INTERSHOP/web/WFS/inSPIRED-inTRONICS_Business-Site/en_US/-/USD/ViewOCICatalog-Start?USERNAME=<USERNAME>&PASSWORD=<PASSWORD>&HOOK_URL=<HOOK_URL>

The following parameters are required for the default OCI Punchout storefront browsing:

Example:

https://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS_Business-Site/en_US/-/USD/ViewOCICatalog-Start?USERNAME=ociuser@test.intershop.de&PASSWORD=!InterShop00!&HOOK_URL=www.my-procurements-provider.com

Additional Functions

Besides the OCI Punchout catalog browsing on the storefront, several other specialized OCI Punchout functions are available. Each function has its own parameters.

Product Details

Log on to the storefront as OCI Punchout user and display product details in the OCI Punchout format for a given PRODUCTID.

Besides USERNAME, PASSWORD and HOOK_URL, the following parameters must be provided:

Example:

https://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS_Business-Site/en_US/-/USD/ViewOCICatalog-Start?USERNAME=ociuser@test.intershop.de&PASSWORD=!InterShop00!&HOOK_URL=www.my-procurements-provider.com&FUNCTION=DETAIL&PRODUCTID=0027242869158

Validation of Products

The validate function allows to retrieve up-to-date information for a specific product with a given quantity from Intershop Commerce Management. A possible use-case is the update of product data in external systems. Intershop Commerce Management returns a single (or no) product record in the OCI format which is automatically sent back to the caller's HOOK_URL.

Besides USERNAME, PASSWORD, and HOOK_URL, the following parameters must be provided.

Example:

https://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS_Business-Site/en_US/-/USD/ViewOCICatalog-Start?USERNAME=ociuser@test.intershop.de&PASSWORD=!InterShop00!&HOOK_URL=www.my-procurements-provider.com&FUNCTION=VALIDATE&PRODUCTID=0027242869158&QUANTITY=3

Internally, the OCI Punchout validate utilizes the cart (basket) functionality. This allows you to have the correct price for a given quantity.

Background Search

The Background Search functionality can be used for cross-catalog searches of the procurement system. The search results are returned in an OCI-compliant format that is not automatically sent (as required by the standard).

Besides USERNAME, PASSWORD, and HOOK_URL, the following parameters must be provided.

Example:

https://www.example.com/INTERSHOP/web/WFS/inSPIRED-inTRONICS_Business-Site/en_US/-/USD/ViewOCICatalog-Start?USERNAME=ociuser@test.intershop.de&PASSWORD=!InterShop00!&HOOK_URL=www.my-procurements-provider.com&FUNCTION=BACKGROUND_SEARCH&SEARCHSTRING=Sony

Internally, the OCI Punchout Background Search reuses the standard product search that returns ProductBOs. Each product comes with a quantity of one. Unlike the other functionalities, no cart (basket) functionality is used. The values of the response are retrieved from the ProductBOs of the search result.

Sourcing

This function is not implemented.

Outbound Connection

A new basket is created for each outbound connection from the external system to the Intershop system. The lifetime of the basket is limited to the session. Therefore, each OCI Punchout connection, even with the same user, creates a new session with an empty basket. Typically, only a single OCI Punchout user is configured per customer, which is then used for multiple employees in the connected external system. A customer account administrator can configure a single OCI Punchout user. Using the REST API, more than one OCI Punchout user can be configured.

Architecture

The following artifacts are of interest when developing in the area of Punchout.

Cartridges

The following cartridges contain code artifacts:

Extensions

CustomerBO

Each customer can have their own Punchout users and Punchout field configuration.

BasketPLIBO

Retrieve punchout conform values from a basket (cart) for a given product line item (PLI).

ProductBO

Acquire Punchout conform values from a single product.

Roles and Permissions

For OCI Punchout, new roles and new permissions have been introduced.

The Punchout user may have Punchout-standard-specific roles. Currently in the punchoutconfiguration.properties there is APP_B2B_OCI_USER set for the OCI Punchout.

The OCI user has limited access to storefront functionality like quotes. Therefore the storefront user's role is checked.

Configuration

A Punchout standard can be configured in the punchoutconfiguration.properties (see bc_punchout). The Punchout user roles and also individual fields can be specified per Punchout standard here.

Punchout Standard

Currently Intershop Commerce System comes with the OCI Punchout standard. Each standard has a set of fields and user roles defined.

# e.g., punchout.configuration.standards=oci,<punchout-type>
punchout.configuration.standard=oci

Punchout-Specific User Roles

For the existing OCI Punchout standard, the role APP_B2B_OCI_USER is set by default in the Intershop Commerce System for specific Punchout users.

# Define the users related to a given punchout type
# e.g., <punchout-standard>.users.roles=<my-custom-role>,<another-custom-role>
oci.users.roles=APP_B2B_OCI_USER

Punchout-Specific Fields

By default, the following fields are returned for the OCI Punchout standard. Additional fields can be added, but will require your custom field configuration.

oci.ver5.punchout.configuration.fields=NEW_ITEM-PRICE, NEW_ITEM-UNIT, NEW_ITEM-MATNR, NEW_ITEM-DESCRIPTION, NEW_ITEM-QUANTITY, NEW_ITEM-CURRENCY, NEW_ITEM-PRICEUNIT, NEW_ITEM-LEADTIME, NEW_ITEM-LONGTEXT, 
NEW_ITEM-VENDOR, NEW_ITEM-VENDORMAT, NEW_ITEM-MANUFACTCODE, NEW_ITEM-MANUFACTMAT, NEW_ITEM-MATGROUP, NEW_ITEM-CONTRACT, NEW_ITEM-CONTRACT_ITEM, NEW_ITEM-CUST_FIELD1, NEW_ITEM-CUST_FIELD2, NEW_ITEM-CUST_FIELD3, 
NEW_ITEM-CUST_FIELD4, NEW_ITEM-CUST_FIELD5, NEW_ITEM-EXT_PRODUCT_ID

Field Configuration

The following set of properties has to be defined per Punchout standard (see <punchout-standard>) and per field (see <fieldId>).

Custom Attributes Configuration

A new placeholder for product custom attributes has been created. The placeholder name for the transform configuration is simply the case-sensitive name of the custom attribute (e.g.: {MyColor}). To control the access to the custom attributes of the product, the following property key has been introduced: <punchout-standard>.ver5.punchout.configuration.custom.attributes.with.access=MyColor,MySize. Only custom attributes with access will be resolved. All others are ignored.

The punchoutconfiguration.properties file is loaded by the configuration framework. This allows to overwrite the default Punchout configuration, e.g., in a custom cartridge.

Field Return Values

The return value of a Punchout field is determined by the transform value and the following formatter.

Transform

The transformation may contain constants and/or placeholders (e.g., "EN_{sku}"). Each placeholder is surrounded by curly brackets and returns a specific value. The return value of a placeholder is defined by a backing PunchoutPlaceholder implementation. The following standard placeholders are available:

• Currency

• Description

• Discarded

• ManufacturerName

• ManufacturerSku

• Price

• ProductName

• Quantity

• Sku

• SupplierName

• SupplierSku

Using the placeholder Discarded prevents the field from being sent to the external system.

Transform (Handling of Custom Attributes)

A new placeholder has been implemented that now handles custom attributes. This placeholder does not appear in the list of available placeholders because it is used implicitly if no explicit placeholder name matches the list above.

There is now a new property key for custom attributes. This key contains a list of custom attribute names that can be accessed. The list of custom attribute names is automatically appended to the list of available placeholders in the UI. See Guide - B2B Storefront Functionality (valid from 7.10.17) | OCI_Punchout_Configuration for details and see the custom attributes configuration above for the required property configuration.

Formatter

To apply a custom formatting to the by transform generated value, use formatters. The available formatters can be extended. The following standard formatters are available:

• LowerCase

• Trim

• UpperCase

Mapping

Mapping allows the string resolved by a placeholder during the transformation step to be converted to another configurable value. The mapping configuration is only stored with the customer and is not part of the properties described in section Field Configuration above. The mapping configuration of the map-from value allows a wildcard '*' at the end to match any string. (e.g.: from: 210* - to: 2100000; a text like 21089365 will be mapped to 2100000).

The mapping step occurs between the placeholder transformation part and the formatter that converts strings to uppercase, for example. Details on how to configure the mapping is documented in Guide - B2B Storefront Functionality (valid from 7.10.17) | OCI_Punchout_Configuration.

Default Return Values

The following fields have a default return value specified by the property <punchout-standard>.ver5.punchout.configuration.<fieldId>.transform in punchoutconfiguration.properties:

Persistent Data Structure

The Punchout configuration of a customer is stored in custom attributes. This makes it easy to import and export the configuration (see below).

<?xml version="1.0" encoding="UTF-8"?>
<enfinity xmlns="http://www.intershop.com/xml/ns/intershop/customer/impex/7.3" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns:dt="http://www.intershop.com/xml/ns/enfinity/6.5/core/impex-dt" 
    xsi:schemaLocation="http://www.intershop.com/xml/ns/intershop/customer/impex/7.3 b2b_customer.xsd http://www.intershop.com/xml/ns/enfinity/6.5/core/impex-dt dt.xsd" 
    major="6" minor="1" family="enfinity" branch="enterprise" build="build">
	<customer id="OilCorp">
		<customer-type>SMB</customer-type>
		<company-name>Oil Corp</company-name>
		<description>Oil Corp is one of the world&amp;apos;s leading oil companies.</description>
		<taxation-id>89548681508155</taxation-id>
		<enabled>1</enabled>
		<custom-attributes>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UN2IT.formatter" dt:dt="string"></custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROUP.transform" dt:dt="string">{ManufacturerName}</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UNIT.formatter" dt:dt="string">uppercase</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROU2P.formatter" dt:dt="string">UpperCase</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UN2IT.transform" dt:dt="string">box</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROUP.formatter" dt:dt="string">uppercase</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-UNIT.transform" dt:dt="string">{box}</custom-attribute>
			<custom-attribute name="oci.ver5.punchout.configuration.NEW_ITEM-MATGROU2P.transform" dt:dt="string">{ManufacturerName}</custom-attribute>
		</custom-attributes>
        ...
    </customer>
</enfinity>

REST API

Depending on your ICM version, the Punchout REST API is documented, for example, in Reference - Punchout REST API 2.3.0. Refer Overview - Intershop Commerce Management REST API to find the correct REST API reference for your ICM version. 

The following use-cases are supported:

• Show list of Punchout standards
• Show/create/delete Punchout users
• Set Punchout user e-mail and password
• Activate/deactivate single Punchout users
• Set configurable fields for a Punchout standard
• Retrieve available formatters/placeholders via OPTIONS call
• Retrieve basket line item or product data using the customer-specific Punchout configuration

Storefront Integration

Depending on the storefront you are using, PWA or Responsive Starter Store, the Punchout URL and the underlying process of the Punchout functions will be different.
The following sections explain the different integrations that are available and include some sequence diagrams of how they work. The diagrams do not show the entire process, but only include key elements to better illustrate the differences in the overall processes.

Responsive Starter Store

PWA

Limitations

With the current implementation you should be aware of the following limitations:

• According to the OCI standard, the BACKGROUND SEARCH returns unlimited results. This might lead to huge results, even though it is internally limited to 99.999 items.