Concept - OCI Punchout (valid from 7.10.17)



1 Introduction

Info

This concept is valid for ICM version 7.10.17 and higher. For previous versions see Concept - OCI Punchout (7.8 - 7.10.16).

With the OCI Punchout feature the Commerce Management application offers an external catalog interface (OCI) for B2B customers. Hereby external systems 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.

oci-punchout-schema

1.1 Glossary

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

1.2 References

The following documentation is related to the OCI Punchout feature:

1.3 Features

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

1.3.1 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.

1.3.2 Administration Features

FeatureDescription
User CreationAccount admins can create an OCI Punchout user.
Edit UserAccount admins may update the OCI Punchout users' e-mail 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.

1.3.3 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 user's 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


2 Functionality

This chapter describes technical insights of the OCI Punchout standard.

2.1 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.

2.2 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).

2.2.1 Login URL

The OCI Punchout URL is publicly 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 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

2.3 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.

2.3.1 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

2.3.2 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 sent back to the caller's 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; Defines 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.

2.3.3 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.

2.3.4 Sourcing

This function is not implemented.

2.4 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.

3 Architecture

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

3.1 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

3.2 Extensions

CustomerBO

Each customer may have his/her own 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 users 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 for getting the basket-related values based on the customer-specific Punchout configuration

ProductBO

Acquire Punchout conform values from a single product.

Extension ID

Interface

Comment

Punchout

com.intershop.component.punchout.capi.configuration.extensions.ProductBOPunchoutExtension

Responsible for getting the product-related values based on the customer-specific Punchout configuration

3.3 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.

3.4 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.

3.4.1 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

3.4.2 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

3.4.3 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

3.4.3.1 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 be applied to the value

3.4.3.2 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.

3.4.3.3 Field Return Values

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

3.4.3.3.1 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 sending the field to the external system.

The placeholders are handled case-insensitive.

3.4.3.3.2 Transform (Handling of Custom Attributes)

A new placeholder has been implemented which now handles custom attributes. This placeholder does not show up 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 which can be accessed. The list of custom attribute names will 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.

The placeholders for custom attributes are case-sensitive.

3.4.3.3.3 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 see Cookbook - OCI Punchout.

3.4.3.3.4 Mapping

Mapping allows to convert the string resolved by a placeholder during the transformation step to another configurable value. The mapping configuration is stored with the customer only and not part of the properties described in section Field Configuration above. The mapping configuration of the map-from value allows a wildcard '*' to match any string. (e.g.: from: 210* - to: 2100000; a text like 21089365 gets mapped to 2100000). The mapping step happens between the transform with placeholders part and the formatter to do an upper case to strings for example. Details on how to configure the mapping is documented in Guide - B2B Storefront Functionality (valid from 7.10.17) | OCI_Punchout_Configuration.

3.4.3.3.5 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:

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}

3.5 Persistent Data Structure

The Punchout configuration of a customer is stored in custom attributes. This allows it to easily 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>

4 REST API

The Punchout configuration feature is implemented and documented as part of the Intershop documentation (Intershop B2B Frontend API | Punchout)

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

5 Limitations

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

  • A field is configured and afterwards the global configuration for this field is changed to NOT configurable: The customer's 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.

Customer Support
Knowledge Base
Product Resources
Support Tickets