Running the Example Punchout Site

Overview

An example punchout site is included in the package named WmcXMLExample. This site represents a fictional supplier named Snowboard Supplier, which sells snowboards. This appendix describes how to run this site and how we have configured it. To install this example package, see Installing Ariba Supplier OnRamp Adapter.

This example is intended only to demonstrate the functionality of Ariba Supplier OnRamp Adapter. The components of this example site can be modularly duplicated and modified. For example, you can replace the site's session-based shopping cart with a database-driven shopping cart.

You can run the Snowboard Supplier site using either of the following methods:

Use a simulated order management system, in which the buyer's order management system is simulated by services in Integration Server.
Use the Test Ariba Buyer of Ariba SN running in supplier.ariba.com.

Simulated Behaviors

Because Snowboard Supplier is a fictional company, we simulated its shopping cart system and web pages. Although these simulations oversimplify the order system, it illustrates how to use Ariba Supplier OnRamp Adapter.

The Simulated Shopping Cart System

Snowboard Supplier's shopping cart is located in wm.b2b.cxml.example.snowboardSupplier.shoppingcart.

This shopping cart is session based, which means that all data is stored in Integration Server session objects. In a clustered server environment, session objects are persisted in the database. In a single-server environment, however, the data is volatile.

Snowboard Supplier's shopping cart item record is located in wm.b2b.cxml.example.snowboardSupplier.shoppingcart. The shopping cart items are record instances based on the ItemIn element from the cXML protocol. To convert shopping cart items to items in the cXML messages, you simply map the shopping cart items to the ItemIn records in the cXML messages.

In addition, items can be added, but not removed. If more than one of the same item is added, the cart increments the quantity instead of adding duplicate entries.

The services defined to manipulate shopping cart items are described below.

wm.b2b.cxml.example.snowboardSupplier.messageHandlers: shoppingCartToCXMLItemList

WmcXMLExample. Converts a list of shopping cart items to the cXML ItemIn list.

Input Parameters

ShoppingCartList

The contents of the current user's shopping cart.

Output Parameters

ItemList

A list of cXML ItemIn records.

wm.b2b.cxml.example.snowboardSupplier.shoppingcart:additem

WmcXMLExample. Adds the item to the buyer's shopping cart.

Input Parameters

`itemID`	The unique product ID.
`name`	The common name of the product.
`quantity`	The quantity to add to the shopping cart.
`price`	The price of a single item.
`sessionID`	The unique ID that identifies the buyer's shopping session.

Output Parameters

`newitem`	A record containing the new item, used on the web page as a confirmation.
`shoppingcart`	A record list containing the entire shopping cart; used on the web page for displaying the contents of the entire shopping cart.
`Cost`	The total cost of all items in the shopping cart.

wm.b2b.cxml.example.snowboardSupplier.shoppingcart: clearShoppingCart

WmcXMLExample. Clears the contents of the shopping cart.

Input Parameters

sessionID

The unique ID that identifies the buyer's shopping session.

Output Parameters

None.

wm.b2b.cxml.example.snowboardSupplier.shoppingcart: computeCartTotalCost

WmcXMLExample. Computes the cost of a buyer's shopping cart.

Input Parameters

shoppingcart

The contents of the current user's shopping cart.

Output Parameters

cost

The total cost of the shopping cart.

wm.b2b.cxml.example.snowboardSupplier.shoppingcart: computeCartTotalTax

WmcXMLExample. Computes the tax of a buyer's shopping cart.

Input Parameters

shoppingcart

The contents of the current user's shopping cart.

Output Parameters

Tax

The total tax of the shopping cart.

wm.b2b.cxml.example.snowboardSupplier.shoppingcart: getPunchOutOrderMessageFromCart

WmcXMLExample. This service performs an HTTP post to the PunchOutOrderMessage mapping service that was generated, passing in an XML document representing the shopping cart as a string in the form field ShoppingCartXML.

The service reads the HTTP response content from the mapping service as a URL encoded PunchOutOrderMessage and embeds the URL encoded PunchOutOrderMessage in the checkout page returned to the buyer.

This service represents the folder from the shopping cart system to the PunchOutOrderMessage mapping service that you define to map shopping cart data to the PunchOutOrderMessage.

When you define a PunchOutOrderMessage mapping service, your shopping cart system sends it the shopping cart data. The mapping service uses the The Simulated Web Pages service to convert the shopping cart data into a PunchOutOrderMessage. The mapping service also formats the PunchOutOrderMessage in a format that can be understood by the shopping cart system.

Input Parameters

None.

Output Parameters

PunchOutOrderMessageString

The URL encoded PunchOutOrderMessage returned by the mapping service. This string is embedded in the HTML checkout page returned to the buyer.

wm.b2b.cxml.example.snowboardSupplier.shoppingcart: getShoppingCart

WmcXMLExample. Gets the contents of a shopping cart for a specific buyer session.

Input Parameters

sessionID

The unique ID that identifies the buyer's shopping session.

Output Parameters

shoppingcart

The contents of the current user's shopping cart.

The Simulated Web Pages

Services are used to simulate Snowboard Supplier's web pages.

wm.b2b.cxml.example.snowboardSupplier:checkout

WmcXMLExample. The supplier checkout page.

This service returns the HTML checkout page that contains the embedded PunchOutOrderMessage. This service represents a shopping cart system that dynamically generates a checkout page. It sends the shopping cart data to a PunchOutOrderMessage mapping service that was created, and expects the PunchOutOrderMessage to be returned in a specific format. The shopping system then embeds the data in a dynamic HTML page.

Input Parameters

sessionID

The unique ID that identifies the user's shopping session.

Output Parameters

None.

wm.b2b.cxml.example.snowboardSupplier:startpage

WmcXMLExample. Returns the supplier's home page where the buyer begins to shop.

The PunchOutSetupRequestHandler service returns a URL to invoke this service to the buyer in a PunchOutSetupResponse. The service displays buyer-specific data in the start page by retrieving the BuyerSession data stored by the PunchOutSetupRequestHandler.

Input Parameters

sessionID

The unique ID that identifies the user's shopping session.

Output Parameters

`sessionID`	The unique ID that identifies the user's shopping session.
`buyerIdentity`	The name of the buyer, as set in the cXML PunchOutSetupRequest `From` Credential Identity.
`buyerDomain`	The domain of the identifier (DUNS, NetworkID, etc.).

wm.b2b.cxml.example.snowboardSupplier.catalog:listItems

WmcXMLExample. This service returns an HTML page representing a web-based catalog of items to buy.

This page also displays your current shopping selections and the total cost of the items you selected. This service interacts with the "simulated shopping cart system" to obtain the shopping cart and build the web page.

Input Parameters

sessionID

The unique ID that identifies the user's shopping session.

Output Parameters

`shoppingcart`	A record list of items representing the cart.
`cost`	The total cost of the cart.
`sessionID`	The unique ID that identifies the user's shopping session.

The Configuration of the Example Punchout Site

This section describes how we have configured the example punchout site, which is located in the wm.b2b.cxml.example.snowboardSupplier folder.

The PunchOutSetupRequest Handler

The service for this handler (wm.b2b.cxml.example.snowboardSupplier.messageHandlers:newShoppingSession) was created using the handler specification guidelines described in wm.b2b.cxml.guidelines:PunchOutSetupRqstHdlr. This service handles only the create operation of the PunchOutSetupRequest service.

The newShoppingSession service initializes storage for a buyer's session in the shopping cart system by calling wm.b2b.cxml.example.snowboardSupplier.buyerUtils:initBuyerPersistentStore, which sets up the shopping cart session on the shopping cart system. The shopping cart system returns a unique ID (sessionID) that identifies this shopping cart session.

The initBuyerPersistentStore service represents the code that you would write to initialize the shopping cart system for a new buying session. In our simulated shopping cart system, we are using the server's session object to persist shopping cart data.

Note: The storage of the shopping cart items in the session object was done only to simplify the implementation of the simulated shopping cart system; it should not be considered part of a "real" PunchOut implementation. In a real implementation, the shopping cart system would manage storage of the selected cart items.

This service was created to illustrate that you need to write some code to setup a new buying session on the shopping cart system when you receive a PunchOutSetupRequest.

In the example, the BuyerSession data (the PunchOutSetupRequest fields that need to be saved) is stored on Integration Server using the services in wm.b2b.cxml.utils.persistence.session.

Note: The use of the services in wm.b2b.cxml.utils.persistence.sessionto store the BuyerSessionData (the punchoutURL, BuyerCookie, and from credential fields) should be considered part of the punchout implementation. In a real punchout implementation, you could use the services in wm.b2b.cxml.utils.persistence.session to store the punchout-specific BuyerData, if the shopping cart system cannot be used.

It is important to distinguish between these two different uses of the session object in the demonstration package.

wm.b2b.cxml.example.snowboardSupplier.buyerUtils:saveBuyerInfo gets the punchout URL, the buyer cookie, and the From/Senderheader fields from the PunchOutSetupRequest. In addition, saveBuyerInfo creates a BuyerSession object. For more information, see wm.b2b.cxml.utils.persistence:BuyerSession.

The BuyerSession object is stored by the utility wm.b2b.cxml.utils.persistence.session:saveBuyerSessionData. The newShoppingSession service then generates a catalog URL to enable the buyer to start shopping, using the service wm.b2b.cxml.example.snowboardSupplier.buyerUtils:getStartpageURL. This service simply appends a sessionID to a fixed URL for the catalog. The URL is set in the catalogURL output field.

The catalogURL is of the following form:

http://serverhostname:port/invoke/wm.b2b.cxml.example.snowboardSupplier/startpag 
e?sessionID=ID

where, ID is the unique identifier of the shopping session.

The Registration of the PunchOutSetupRequest Handler

The demonstration package will register the newShoppingSession service as a PunchOutSetupRequest handler for the create operation in the Configuration Module. When you start the example package, you will be prompted to allow the demonstration package to register this handler service.

Note: The demonstration package will overwrite the current configuration for the PunchOutSetupRequest handler for the create operation.

The OrderRequest Handler

The service for this handler (wm.b2b.cxml.example.snowboardSupplier.messageHandlers:processNewOrder) was created using the handler specification guidelines described in wm.b2b.cxml.guidelines:OrderRequestHdlr. This service handles only the OrderRequest newoperation. This service accepts the order and clears the shopping cart corresponding to that buyer's session.

The Registration of the OrderRequest Handler

The demonstration package will register the processNewOrder service as the OrderRequest handler for the new operation in the Configuration Module. When you start the example package, you will be prompted to allow the demonstration package to register this handler service.

Note: The demonstration package will overwrite the current configuration for the OrderRequest handler for the new operation.

The PunchOutOrderMessage Mapping Service

In this demonstration package, the Configuration Module of Ariba Supplier OnRamp Adapter was used to generate a PunchOutOrderMessage mapping service to map the shopping cart data record to a PunchOutOrderMessage. Following are characteristics of this service:

The mapping service is defined in wm.b2b.cxml.example.snowboardSupplier.messageHandlers:createPunchOutOrderMessage.
The mapping service was configured to accept the shopping cart data as an XML document from the shopping cart system.
The implementation of the service maps the shopping cart data passed from the shopping system into the PunchOutOrderMessage. The mapping service invokes the service wm.b2b.cxml.example.snowboardSupplier.messageHandlers:shoppingCartToCXMLItemListto convert the shopping cart data into the PunchOutOrderMessage.The mapping service also sets the PunchOutOrderMessageenvelope fields using the wm.b2b.cxml.messages:createCXMLEnvelope service.
The mapping service was configured to return the PunchOutOrderMessage as a URL encoded string.

The simulated catalog system uses HTTP post to send an XML document describing the shopping cart system. This is simulated using the service wm.b2b.cxml.example.snowboardSupplier.shoppingcart:getPunchOutOrderMessageFromCart.

The format of the XML shopping cart document is represented by the record wm.b2b.cxml.example.snowboardSupplier.shoppingcart:ShoppingCart_BoundNode. The record contains the sub-record corresponding to the root of the XML document sent to the mapping service.

Running the Example Site Using the Simulated Order Management System

About this task

To run the Snowboard Supplier site with a simulated order management system, in which the buyer's order management system is simulated by services in Integration Server, perform the following steps.

CAUTION:

If you plan to install and run this example package, and your Integration Server version is 4.0 or later, assign an Integration Server Access Control List (ACL) to an appropriate access group for the wm.b2b.cxml.example and wm.b2b.cxml.formsfolders and for the service wm.b2bi.cxml:receivecXML. For more information about ACLs, see the IBM webMethods Integration Server Administrator’s Guide for your release.

To run the Snowboard Supplier site using the simulated order management system

Procedure

In Integration Server Administrator, verify that Ariba Supplier OnRamp Adapter is enabled.
In your web browser, type the following URL:
```
http(s)//<local hostname>:<port>/WmcXMLExample
```
The logon page of the demonstration appears.
Click the Continue with Demonstration button to begin configuring your Ariba Supplier OnRamp Adapter.

Note: Clicking this button will overwrite the current handler configuration for the PunchOutSetupRequest handler for the create operation and the OrderRequest handler for the new operation.
Click OK when you are prompted to overwrite the existing configuration.
Click the Continue with Demonstration button again.
Click the log in button to log into Ariba Supplier. (The user name and password are supplied.)
Select the Snowboard Supplier link from the list of suppliers.

The cXML PunchOutSetupRequest page appears.
Click the Send PunchOutSetupRequest button to request a cXML-enabled buyer session with the Snowboard Supplier site.

Snowboard Supplier responds by displaying its back-end page cXML PunchOutSetupResponse. This page displays the cXML PunchOutSetupResponse message that sent the response.

Note: The cXML PunchOutSetupRequest message that performs this task appears at the bottom of the page. This request is sent using an http post to the published Snowboard Supplier URL.
Click the Shop at Supplier's Store button on the Snowboard Supplier back-end screen.

The Snowboard Supplier start page appears.
Click the Browse the Catalog icon.

The catalog items are displayed.
Add one or more items to your shopping cart.
Click the Proceed to Checkout icon.

Your shopping cart appears. The cXML-URL encoded PunchoutOutOrderMessage is also embedded in this page.
Click the Submit Order button.
This page's HTML form, along with the cXML-URL encoded message, is posted to the buyer's Ariba Buyer at the following URL:
```
http://<local host>:<port>/invoke/wm.b2b.cxml.orms/approveOrder
```
Snowboard Supplier responds by displaying its back-end page cXML PunchOutOrderMessage. This page displays the cXML PunchOutOrderMessage message that will return the contents of the buyer's shopping cart to the buyer.
Click the Send back to ORMS button.

The verification page of Ariba Buyer appears.
Click the Create OrderRequest button to submit the order to Snowboard Supplier.

The OrderRequest page of Ariba Buyer appears.
Click the Send OrderRequest button.

The cXML OrderRequest message that will be sent to Snowboard Supplier appears at the bottom of the page.

Snowboard Supplier responds by displaying the OrderResponse page.
Click the Return to the Logon Screen button.

The OrderResponse message that will respond to the OrderRequest is displayed.

The log on screen is redisplayed.

Running the Example Site Using a Test Ariba Buyer

About this task

To run the Snowboard Supplier site using the Test Ariba Buyer of Ariba SN, perform the following steps.

To run the Snowboard Supplier site using a Test Ariba Buyer

Procedure

Ensure that you are connected to the Internet.
Ensure that you have a valid supplier.ariba.com user name and password.
Ensure that your Integration Server is accessible from outside your company's firewall.
In Integration Server Administrator, verify that IBM webMethods Adapter for Ariba Supplier OnRamp is enabled.
In your web browser, type the following URL:
```
http(s)//<local hostname>:<port>/WmcXMLExample
```
The log on page of the demonstration appears.
Click the Continue with Demonstration button to begin configuring your Ariba Supplier OnRamp Adapter.

Note: Clicking this button will overwrite the current handler configuration for the PunchOutSetupRequest handler for the create operation and the OrderRequest handler for the new operation.
Click OK when you are prompted to overwrite the existing configuration.
Log into Ariba Supplier's website by accessing the following web site:

http://supplier.ariba.com
At the Ariba Supplier site, underAriba Supplier Network Log In, type your Ariba user name and password, and click Log In.
On the Main page, under Account Activity, click Configuration.
Click OrderRequest.
Select cXML for thePreferred Method of Order Routing.
Select1.2 as the cXML version.
In the space provided, enter the punchout URL
```
http://servername:port/invoke/wm.b2b.cxml/receiveCXML
```
where servername is the name of your server and port is its port specification.
Click Save to save the changes.
On the Main page, under Account Activity, click Catalogs.
On the Catalogs page, click Create Links to Internet Catalogs.

Under Create a New Catalog for PunchOut, type the following sample supplier information and click Create:

In this field…	Specify…
Catalog Name	`Snowboard Supplier`
PunchOut URL	`http://servername:port/invoke/wm.b2b.cxml/receive` where `servername` is the name of your server and `port` is its port specification.
UN/SPSC code	`49151505`
Commodities	`Musical Instruments, Recreational Equipment, Supplies and Accessories`
Brief Description	`This is a demonstration.`

The Currently Uploaded Catalogs page appears, with an entry for the Snowboard Supplier catalog.

In the Snowboard Supplier entry row in the Actions column, click Test. A new page appears, showing all matches for that catalog.
In the single entry row of the Snowboard Supplier catalog, click Shop. If a Security Information dialog box appears with the message "Do you want to display the nonsecure items?", click Yes. This message appears because the Ariba site is a secure site, but the Snowboard Supplier site is not. The Snowboard Supplier site now appears.
On the Snowboard Supplier home page, click Browse the Catalog.
On the catalog page, select the items you wish to purchase and click Add to Cart. Continue shopping until you have selected all of the items you wish to add to your shopping cart.
When you are finished shopping, click Proceed to Checkout. A confirmation page appears, showing what you have selected. The confirmation page contains a PunchOutOrderMessage URL encoded inside the web page. The page asks you to confirm you order selection.
Click Confirm to continue. The encoded PunchOutOrderMessage is sent back to the test Order Management System on Ariba SN. If no errors occurred, you see a web page from Ariba SN containing an Order Contents section. The Order Contents section shows you the items you selected.
Click Order. An OrderRequest is sent to Snowboard Supplier. Integration Server of Snowboard will respond with an OrderResponse to acknowledge the order. You will not be able to see the Order Response on Ariba SN. But the OrderResponse status will be shown in the OrderRequest entry in your Ariba SN inbox.
On the Main page, click Inbox. The status of your order request should be acknowledged, indicating that the OrderRequest was successfully processed by Snowboard Supplier. If there is a problem processing the OrderRequest, the status is failed. To see details of the failure, click the link for the OrderRequest.