Personal Library

Concept - OCI Punchout (7.8 - 7.10.16)

Introduction

With the OCI Punchout feature the Commerce Management application offers an external catalog interface (OCI) for B2B customers. Hereby external system can access product data from an Intershop server or a selection of products. Therefore the official OCI transfer format is utilized. The Punchout format can be configured on application level or during runtime individually with customer specific settings.

Glossary

Term	Description
OCI	Open Catalog Interface (OCI) is one of the standard formats used by ERP/Purchasing Systems when connecting to external Punchout catalogs.

References

The following documentation is related to the OCI Punchout feature:

Concept - OCI Punchout (7.8 - 7.10.16) - Basic concepts, OCI Punchout functionality (this document)
Guide - B2B Storefront Functionality (valid to 7.10.16) - See chapter "OCI Punchout"
Reference - WebShop REST API 7.8 - Documentation of the Punchout REST API for product version 7.8
Reference - WebShop REST API 7.9 - Documentation of the Punchout REST API for product version 7.9
Intershop Documentation - Documentation of the latest REST API
Cookbook - OCI Punchout - Recipes on frequently asked questions
Overview - Configuration Framework - Reference when customizing placeholder or formatters

Features

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

Storefront Features

Feature	Description
OCI Checkout	An external (procurement) system can log as OCI Punchout user onto an Intershop Commerce Management storefront, browse the storefront, add products to the cart and transfer a cart back to the caller (initially identified by the HOOK_URL). Certain parts of the storefront (e.g., footer) are hidden to improve the shopping experience coming from an external system (e.g., procurement).
Product Details	Login to the storefront as OCI Punchout user and display product details in the OCI Punchout format for a given PRODUCTID.
Validate Product	Login to the storefront as OCI Punchout user and automatically transfer back product details in the OCI Punchout format for a given PRODUCTID and QUANTITY.
Background Search	Login to the storefront as OCI Punchout user and have all products displayed in the OCI Punchout format that match a given SEARCHSTRING.

Administration Features

Feature	Description
User Creation	Account admins can create an OCI Punchout user.
Edit User	Account admins may update the OCI Punchout users email and password.
Punchout Configuration	Account admins are able to configure given fields of the Punchout format by defining their content (transform) and optionally providing a formatting.

REST Features

Feature	Description
List Punchout Users	Shows all customer and Punchout specific users
User Creation	Account admins can create Punchout users.
Edit User	Account admins may update a Punchout users email or password and set them active/inactive.
Punchout Configuration	Account admins are able to configure given fields of the Punchout format by defining their content (transform) and optionally providing a formatting.
Delete User	Account admins can delete a Punchout user.
OCI Punchout Data	Retrieve basket line item or product data depending on customer specific Punchout configuration

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.

Example Response

<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 re-use the product, basket product line item and/or customer information to display one or more products.

Note

Decision: BasketLineitems which are either gifts or hidden gifts are not part of the OCI Punchout transfer format, since they would get added automatically when it comes to an order.

OCI Punchout Catalog Browsing

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

Login URL

The OCI Punchout URL is public available, which any OCI Punchout user with valid credentials can access. The pattern of the URL 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 for are required for the default OCI Punchout storefront browsing:

Parameter	Description
USERNAME	Login name of a storefront user with the role OCI Punchout user
PASSWORD	Password of the OCI Punchout user
HOOK_URL	Transfer the OCI Punchout data back to this URL. Usually a reference to the external (procurement) system.
<CUSTOM_NAME>	optional; For customization purposes any additional URL parameter is stored in the storefront session and can be accessed later if required.

A short example is given below:

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 there are several other specialized OCI Punchout functions available. Each function comes with their own parameters.

Product Details

Log into 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.

Parameter	Description
FUNCTION	This parameter must be set to `DETAIL`.
PRODUCTID	A unique product identifier as returned by the OCI Punchout transfer format

Example:

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 the Intershop Commerce System. A possible use-case is the update of product data in external systems. The Intershop Commerce System returns a single (or no) product record in the OCI format which is automatically send back to the callers HOOK_URL.

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

Parameter	Description
FUNCTION	This parameter must be set to `VALIDATE`.
PRODUCTID	A unique product identifier as returned by the OCI Punchout transfer format
QUANTITY	optional; Define the requested quantity. This setting may have influence on the returned price.
AUTOSUBMIT	optional, This parameter is not part of the official specification. For testing issues `AUTOSUBMIT` can be set to `false` to suppress the automatic redirect to the provided `HOOK_URL`.

Example:

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 enables to have correct prices for a given quantity.

Background Search

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

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

Parameter	Description
FUNCTION	`BACKGROUND_SEARCH` must be set
SEARCHSTRING	Provide a search term

Example:

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 re-uses the standard product search which returns ProductBOs. Each product comes with a quantity of one. Opposite to 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

For every outbound connection from the external system into the Intershop system a new basket is created. The lifetime of the basket is limited to the session. Therefore every OCI Punchout connection even with the same user creates a new session including an empty basket. Usually only a single OCI Punchout user per customer is configured, which is then used for multiple employees in the connected external system. A customer account administrator can configure a single OCI Punchout user. Utilizing 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:

Cartridge	Description
bc_punchout	Interfaces for Punchout related extensions, services and providers
bc_punchout_orm	Extensions and factories
app_sf_responsive_b2b	OCI Punchout related functionality in the My Account section
app_sf_rest_b2b	Punchout WebShop REST API
init_b2b	Roles and permissions
demo_responsive	Initialize demo content (CMS) for OCI Punchout, and roles and permissions

Extensions

CustomerBO

Each customer may have it's on Punchout users and Punchout field configuration.

Extension ID	Interface	Comment
PunchoutConfiguration	com.intershop.component.punchout.capi.CustomerBOPunchoutConfigurationExtension	Responsible for saving and retrieving the customer specific configuration
Punchout	com.intershop.component.punchout.capiCustomerBOPunchoutExtension	Responsible for handling OCI user of the customer

BasketPLIBO

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

Extension ID	Interface	Comment
Punchout	com.intershop.component.punchout.capi.configuration.extensions.BasketPLIBOPunchoutExtension	Responsible to get the basket related values based on the customer specific Punchout configuration

ProductBO

Aquire Punchout conform values from a single product.

Extension ID	Interface	Comment
Punchout	com.intershop.component.punchout.capi.configuration.extensions.ProductBOPunchoutExtension	Responsible to get the product related values based on the customer specific Punchout configuration

Roles and Permissions

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

Role	Description
APP_B2B_OCI_USER	The B2B OCI user.

Permission	Description
APP_B2B_MANAGE_PUNCHOUT	The permission to manage Punchout settings. This permission is assigned to the role APP_B2B_ACCOUNT_OWNER.
APP_B2B_VIEW_PUNCHOUT	The permission to view Punchout settings. This permission is assigned to the role APP_B2B_ACCOUNT_OWNER.
APP_B2B_SEND_OCI_BASKET	Permission to send the basket to the OCI backend. This permission is assigned to the new role APP_B2B_OCI_USER

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.

Note

Some functionality is disabled on pages which are intended to be cached. To prevent page caching issues a special user group is used. Other B2B user roles still do not own a dedicated user group.

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 the 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 default Intershop Commerce System has the role APP_B2B_OCI_USER set 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

Per default the following fields are returned for the OCI Punchout standard. More fields may be added, but require their 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>).

Property Key	Description
<punchout-standard>.ver5.punchout.configuration.fields	A comma separated list of field IDs to be returned
<punchout-standard>.ver5.punchout.configuration.<fieldId>.fieldname	The name of the field
<punchout-standard>.ver5.punchout.configuration.<fieldId>.length	The length of the value to be returned (-1 for unlimited length of the value to return)
<punchout-standard>.ver5.punchout.configuration.<fieldId>.configurable	True, if the field can be configured by the customer
<punchout-standard>.ver5.punchout.configuration.<fieldId>.transform	The transformation rule for retrieving the values
<punchout-standard>.ver5.punchout.configuration.<fieldId>.formatter	A formatter to applied to the value

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 constant 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 placeholder Discarded prevents sending the field to the external system.

The placeholders are handled case-insensitive.

Formatter

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

LowerCase
Trim
UpperCase

The formatters are handled case-sensitive. For adding new formatters and placeholders check the Cookbook - OCI Punchout.

Default Return Values

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

Field	Default
NEW_ITEM-PRICE	{Price}
NEW_ITEM-DESCRIPTION	{ProductName}
NEW_ITEM-QUANTITY	{Quantity}
NEW_ITEM-CURRENCY	{Currency}
NEW_ITEM-LONGTEXT	{Description}
NEW_ITEM-VENDORMAT	{SupplierSku}
NEW_ITEM-MANUFACTCODE	{ManufacturerName}
NEW_ITEM-MANUFACTMAT	{ManufacturerSku}
NEW_ITEM-EXT_PRODUCT_ID	{Sku}

Persistent Data Structure

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

Customer export XML

<?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

The Punchout configuration feature is implemented and documented as part of the REST API documentation (see Reference - WebShop REST API 7.8, Reference - WebShop REST API 7.9 or Intershop Documentation for the latest version of the REST API).

The following use-cases are supported:

Show list of Punchout standards
Show/create/delete Punchout users
Set Punchout user email 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

Limitations

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

A fields is configured and afterwards the global configuration for this field is changed to NOT configurable: The customers configuration might still work.
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.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Table of Contents

Introduction

Glossary

References

Features

Storefront Features

Administration Features

REST Features

Functionality

OCI Transfer Format

OCI Punchout Catalog Browsing

Login URL

Additional Functions

Product Details

Validation of Products

Background Search

Sourcing

Outbound Connection

Architecture

Cartridges

Extensions

Roles and Permissions

Configuration

Punchout Standard

Punchout-specific User Roles

Punchout-specific Fields

Field Configuration

Field Return Values

Persistent Data Structure

REST API

Limitations