SAP Commerce and Punchout – Part 2

Category: Uncategorized Author: Rob Bull 14 October 2024 No comments

This article is brought by Robert Bull, Lead Solution Architect

Introduction

Punchout is an electronic procurement process in B2B scenarios. The typical process involves a purchaser’s system accessing a suppliers product catalog to allow the purchaser to build up a list of products to be purchased (the list exists in the supplier’s system) and then the session is completed with the list being transferred back to the purchaser’s system. The purchaser can then makes a purchase through the use of their own procurement process

In Part 1 of this article, I focused on the background and specifications of the two Punchout protocols OCI and cXML with examples of typical catalog and procurement processes. In this Part 2, I shall be demonstrating the OCI and cXML Punchout standards as implemented for Hybris / SAP Commerce.

Punchout Capability in SAP Commerce /Hybris

We need to go back to earlier Hybris days to see initial inclusion of punchout extensions:

an OCI extension was included in hybris 4.2.2 (2011), supporting OCI versions 4.0, 3.0 and 2.0; and this extension was de-released in hybris 6.7 in the year 2019, but looks to still be included up to and including release 1808.
cXML punchout for the cart transfer service has been included in hybris / SAP Commerce from version 5.3 (year 2014), with variations in the names/number of extensions, partially due to the changes in omnichannel connect web services, and supporting multiple variations of the cXML protocol, for example:
- Hybris 5.3 supported cXML version 1.2.024
- Hybris 6.3 supported cXML version 1.2.029
- SAP Commerce 2211.25 supports cXML version 1.2.051.

At the time of writing, the latest spec of cXML is 1.2.063

So – time to have a play, looking at the following:

For cXML:

The Punchout capabilities in the extensions to add to the B2B accelerator;
The punchout capabilities effective through Spartacus.

For OCI:

I will see if I can get the old OCI extension working in SAP Commerce.

cXML Punchout Capabilities added to the B2B Accelerator

SAP provide a number of extensions to add to the B2B accelerator:

b2bpunchout Extension – it implements the cXML protocol to process cXML requests and produce response objects
b2bpunchoutaddon AddOn – is responsible for PunchOut-related HTTP requests from the procurement system as well as PunchOut-specific changes to the relevant B2B pages and their functionality
b2bpunchoutbackoffice Extension – provides Backoffice configuration capability for the PunchOut module
b2bpunchoutocc Extension – it exposes functionality of the B2B PunchOut module in the form of the standardized OCC (Omnichannel Commerce) APIs

A test extension b2bpunchoutocctests provides tests for the b2bpunchoutocc extension.

I’m not proposing to give full details on building these, as it is well documented by SAP here.

Follow the usual build process, add the extensions to localextensions.xml, add the addon command with ant:

ant addoninstall -Daddonnames="b2bpunchoutaddon" -DaddonStorefront.yb2bacceleratorstorefront="yb2bacceleratorstorefront"

and there are a number of elements you should add to the local.properties file. Compile and run SAP Commerce, and perform a system update. There are then a number of documented necessary properties and impex imports, comprising:

security factors;
OAuth authorization for web services;
A cron job to remove expired punchout sessions;
Configuring automatic verification for punchout orders.

Further to this, it is necessary to ensure that the B2B customer account being used for any tests is “enabled”, and that the account password is set because by default is probably disabled and has no password.

In addition, you need to impex some punchout credentials:

those From, To and Sender elements – these are impexed into PunchOutCredential type; and,
the mapping of the credentials to B2B Customers, in B2BCustomerPunchOutCredentialMapping type.

The PunchOutCredential type is a bit confusing, because each one of these aligns to either a From, or the To or the Sender in hybris type elements , here is the mapping:

cXML Snippet

SAP Commerce Element

<From>

</Credential>

</From>

Punchout Credential data type:

Element Code = <whatever you call this credential>
Element Domain = NetworkId
Element Identity = AN01000002779-T

<To>

</Credential>

</To>

Punchout Credential:

Element Code = <whatever you call this credential>
Element Domain = DUNS
Element Identity = 123456789

<SharedSecret>VerySecret1234$</SharedSecret>

</Credential>

<UserAgent>Procurement System 2.0</UserAgent>

</Sender>

Punchout Credential:

Element Code = <whatever you call this credential>
Element Domain = NetworkID
Element Identity = AN01000002779-T

punchout.customer@punchoutorg.com </Extrinsic>

…

B2C Customer Credential:

Element SharedSecret = B2C Customer password
Element Extrinsic = B2C Customer email address

Multiple PunchOut credentials can be assigned to a B2B Customer and when the authentication is checked, all credentials assigned to a B2B Customer are compared to what was sent by the procurement system. If any one domain/identity pair matches, authentication is successful.

I setup the following test scenario:

SAP Commerce 2211with the punchout extensions added as described above
Postman utility to initiate web services to SAP Commerce OCC
Chrome browser to run the punchout session
A mini http server to see the punchout response

cXML Testing with SAP Commerce B2B Accelerator

The test steps were as follows, as per the steps 1 – 5 in the diagram above:

Postman used to request an OAuth token and then submit a Punchout Request
The punchout request contains the URL of the mini http server as its “return URL”
The Punchout response contains a Start Page URL which is entered in Chrome browser – the powertools store
Punchout session used in Chrome, products added to the cart
Cart Checkout button to return to the procurer, sends the browser to the mini http server address with the punchout response.

Here are some screenshots of the results:

Postman request for an OAuth token:

Submit the punchout request, and copy the Start Page URL:

Paste the Start Page URL in Chrome, see the welcome message to the Punchout customer::

Add some items to the cart, and go to the cart, you can see the new button added “Return to Requisition”:

Click on the Return to Requisition, and the mini http server receives the punchout cart cXML:

cXML Punchout Session Returning the List of products

Therefore, the basic punchout capability is working out of the box.

Looking at the XML response, two specific parameters are of interest:

<UnitOfMeasure>C62</UnitOfMeasure>
<Classification domain="UNSPSC">23291500</Classification>

The Unit of measure parameter is a representation from the United nations Unit of Measure codes, and value C62 represents a single one piece.

All of these can be found here.

Then, for the classification, the UNSPC codes are required, these are here: https://www.unspsc.org/

And code 23291500 is specified as Industrial drilling tools

For implementations adding punchout to their systems, these codes may not yet exist in the product data and therefore will require some development and product information management activity to include.

Punchout Capabilities Through Spartacus

Punchout in Spartacus is one area that has not yet been developed by SAP and the current SAP Road Map plan is showing this as being provided in Q2 2025 although this has been delayed from an earlier Road Map plan that had this scheduled for Q3 2024.

Further to this though, is an article in the SAP Community blogs web site where a contributor has published an article how to implement cXML punchout Level 1 in Spartacus

Although written for Spartacus 5, the approach is equally applicable to subsequent versions.

The technical session flow is the same as the diagram above Level 1 Punchout Scenario, but with the following differences:

when the session request is initiated the URL provided from the OCC service response needs to be a Spartacus URL and not the JSP accelerator storefront URL: – this is changed in the properties file;
the user session information in Spartacus needs to reflect the punchout user and that user’s session, with an OCC service call applied in Spartacus to endpoint {baseSiteId}/punchout/sessions/{sid}
there are a few CMS changes to be defined which are analogous to those changes applied for the JSP accelerator storefront.

The architecture now includes a regular setup of Spartacus, but note that the initial URL (step 3) containing the session Id has code added to Spartacus that detects the URL pattern and in turn invokes the OCC service to the OCC endpoint {baseSiteId}/punchout/sessions/{sid} to retrieve the user data and then performs a redirect to the regular Spartacus URL and displays the home page with the Punchout CMS changes applied.

However, with the regular features of search, PLP, PDP all working, I hit an issue when adding items to then cart – I get an error saying that the item is already in the cart. Looking at the OCC calls, there is an error in one of the cart calls, seemingly associated to the user Id. Oh well, nearly there and time for a debug session when I get some spare time.

However, with the regular features of search, PLP, PDP all working, I hit an issue when adding items to then cart – I get an error saying that the item is already in the cart. Looking at the OCC calls, it appears that the OCC call to add items to the cart, it calls the OCC service with pattern like: /{baseSiteId}/users/{userId}/carts and it substitutes “current” for the {userId}. However, in the list of patterns in the punchoutocc extension (in file b2bpunchoutocc-web-spring-xml) there is no equivalent pattern and therefore in java file PunchOutRequestMatchingFilter.java the method matchAllowedList() is returning true and the conditional test in that file:

if (auth != null && containsRole(auth, PUNCHOUT_OAUTH_ROLE) && excludesFromAllowList(request))

is failing and returning NotFoundException.

Some code fixes in the punchout extension or in Spartacus are needed, but even after then Checkout however would not work as the SAP article author did say that he would publish a follow-on article for dealing with the checkout and return to the procurement system but it was never written or published as far as I can tell.

The Old OCI Extension

The old OCI extension is quite interesting, and very helpful from a test and development perspective. It includes:

a jsp page that explains what the OCI extension is provided with and how it is to be tested;
a jsp page containing a form table where you can enter the OCI form field data and submit it, thus creating an OCI session request (although you could do this via Postman if you want);
a mini lightweight storefront on a specified product catalog comprising a mini search page, a mini PLP page and a mini PDP page and a mini cart page;
to trigger the session completion to revert back to the procurement system and display the OCI results in another jsp page.

Therefore, this extension not only gives the storefront catalog but an entire test scenario representing the procurement system as well. I guess that the Postman utility did not exist when this OCI capability was first created so someone had the insight to create a procurement system emulation.

In any realistic production system, this extension would have needed substantial customization, and the example code style is somewhat deprecated now also.

In order to look at functionality that the OCI extension provided, I needed to build it, and I decided to see if it still works in a current environment, so I added the extension to an OOTB build of SAP Commerce 2211.25 built to the B2C/B2B recipe. My alternative would have been to build version 6.7, but that meant changing java version etc.; so I retrieved the OCI extension from hybris 6.7 and added it to my 2211.25 build – quite straight forward by putting the extension in a “custom” folder, adding the extension to localextensions.xml and running ant – it built with no errors 😊

I ran the system, and from the hybris admin console you can see the OCI extension included, as you can see, it is the extension from hybris 6.7 (and is deprecated):

At the same time, you can also see the latest cXML punchout extensions:

Running the Old OCI Extension

The old extension actually compiles quite well in 2211.25, but from a perspective of it running there are several code issues in the jsp pages to resolve because of changes over the years to classes and methods. You need to reference the catalog version service and set the required catalog version as by default these are not set and without the changes any search on a product from the OCI protocol request fails.

Something like this fixes it, added to various jsp files that deliver the mini sample OCI storefront.

SessionContext ctx = JaloSession.getCurrentSession().getSessionContext();
CatalogVersionService catalogVersionService = (CatalogVersionService) Registry.getApplicationContext().getBean("catalogVersionService");
CatalogVersionModel catalogVersion=catalogVersionService.getCatalogVersion("powertoolsProductCatalog", "Online");
catalogVersionService.setSessionCatalogVersions(Collections.singleton(catalogVersion));

I’ll start by showing the OCI extension information page; which gives a useful introduction to what the extension is about:

We can then start the OCI session by clicking on the sap.jsp link, which brings up a form page that contains the various OCI parameters with explanations of each:

From a functionality perspective, recall that in normal punchout operations these form fields would be created by the user’s procurement system and submitted to the SAP Commerce system. All that is needed as a minimum is to add the username and password of a B2B user in SAP Commerce. Note also that the HOOK_URL field is the address that the SAP Commerce cart will return the cart contents to at the end of the punchout session – that default value sap-data-interpretation.jsp is another page in the OCI extension for purposes of demonstrating the punchout process response. Entering the shop then submits the form as follows to page entrypoint.jsp which redirects to page shop-start.jsp and displays the shop search page:

OCI Punchout Extension – Form Data for Initiating a Session

OK, we’ll search for a sander:

… and we get a small PLP page.

And we can add to the cart:

OCI Punchout Extension –Cart Page

That button “SAP OCI Buyer” is where the user will close the punchout session and the data is sent back to that HOOK-URL we saw above in the OCI form. The cart information is formulated to the OCI XML format, is then Base-64 encoded and sent back on a form over a POST submission.

OCI Punchout Extension –Cart List Data Sent Back to Procurement

(If you want to decode it yourself, first extract just the data, change all occurrences of %2B to a +(plus) character and then Base-64 decode it). The OCI extension however does that for you in page sap-data-interpretation.jsp and displays in both a table and the formatted XML.

Therefore, the OCI extension is providing a fully demonstrable and working OCI punchout capability. In practice though, an implementation would probably adapt the standard B2B storefront, in a way similar to the cXML example above, and likewise there is nothing available for the OCI protocol in a Spartacus storefront, but given the similarities of the process between cXML and OCI, that would be feasible, something analogous to the Spartacus example above.

Conclusion

On face value, it may seem that punchout is a bit dated and doesn’t seem to be the focus of development in SAP Commerce and the protocols have not been converted to more modern data formats such as JSON. Likewise, SAP has dropped OCI in the SAP Commerce platform, although as above, it is not complex to undertake and develop for.

It is worth remembering that a key aspect with these protocols is the targeted specific B2B business capability with interoperability between purchasers and suppliers within the systems that they use. Many of the systems that support punchout are themselves large scale backoffice ERP systems and these tend to remain fairly static and do not change much. However, the interoperability involves a lot of detail to get right and is a critical key to success. Building this interoperability into a SAP Commerce system could involve a lot of data transformation work which itself needs a lot of potential maintenance as products are added etc. Thankfully, the punchout protocols themselves do not change much, otherwise it could justify a question whether the effort is really worth the return value.

Of the 2 standards OCI and cXML, I have only focused on the punchout service where a procurer is identifying products they wish to purchase from a supplier. The punchout capability removes the need for otherwise manual work in building up purchase orders, it provides accuracy of products and is a fairly self-contained capability. The other services I see are less frequently supported or used.

But these protocols serve their business communities well and are likely to be around for many years yet.

Good luck in your implementations !