Document Properties
Kbid
276T84
Last Modified
07-Jul-2023
Added to KB
20-Jul-2016
Public Access
Everyone
Status
Online
Doc Type
Concepts
Product
ICM 7.10
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

TermDescription
OCIOpen 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:

Features

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

Storefront Features

FeatureDescription
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 DetailsLogin to the storefront as OCI Punchout user and display product details in the OCI Punchout format for a given PRODUCTID.
Validate ProductLogin 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 SearchLogin to the storefront as OCI Punchout user and have all products displayed in the OCI Punchout format that match a given SEARCHSTRING.

Administration Features

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

REST Features

FeatureDescription
List Punchout UsersShows all customer and Punchout specific users
User CreationAccount admins can create Punchout users.
Edit UserAccount admins may update a Punchout users email or password and set them active/inactive.
Punchout ConfigurationAccount admins are able to configure given fields of the Punchout format by defining their content (transform) and optionally providing a formatting.
Delete UserAccount admins can delete a Punchout user.
OCI Punchout DataRetrieve 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:

ParameterDescription
USERNAMELogin name of a storefront user with the role OCI Punchout user
PASSWORDPassword of the OCI Punchout user
HOOK_URLTransfer 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.

ParameterDescription
FUNCTIONThis parameter must be set to DETAIL.
PRODUCTIDA 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.

ParameterDescription
FUNCTIONThis parameter must be set to VALIDATE.
PRODUCTIDA 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.
AUTOSUBMIToptional, 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.

ParameterDescription
FUNCTIONBACKGROUND_SEARCH must be set
SEARCHSTRINGProvide 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:

CartridgeDescription
bc_punchoutInterfaces for Punchout related extensions, services and providers

bc_punchout_orm

Extensions and factories
app_sf_responsive_b2bOCI Punchout related functionality in the My Account section
app_sf_rest_b2bPunchout WebShop REST API
init_b2bRoles and permissions
demo_responsiveInitialize 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:

FieldDefault
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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.