Implementing a Punchout Ordering System without Trading Networks

Introduction

This chapter describes how to configure Ariba Supplier OnRamp Adapterto support a punchout site that does not use Trading Networks. Specifically, this chapter describes the following configuration tasks:

Specifying the cXML document receive service-that is, the service that receives cXML documents from Ariba Buyer.
Specifying the InvoiceDetailRequest URL - that is, the URL where the InvoiceDetailRequests are sent from the supplier.
Specifying the following cXML document handlers:
- OrderRequest
- PunchOutSetupRequest
- ProfileRequest.
- MasterAgreementRequest
Defining PunchOutOrderMessage mapping.
Specifying the service for creating and testing PayloadIDs.
Specifying SharedSecrets.
Specifying Digital Signatures.

Other configuration tasks that are common to all punchout systems (with or without Trading Networks) are described in other chapters, as follows:

For information about this task	See...
Enabling the storage of OrderRequest messages.	Storing OrderRequest Messages
Enabling the logging of events	Enabling Logging
Specifying customized services to listen to and process events that occur during various stages of punchout ordering.	Listening to and Processing Punchout Process Events

Opening the Ariba Supplier OnRamp Adapter Configuration Screen

About this task

You configure Ariba Supplier OnRamp Adapter using the Ariba Supplier OnRamp Adapter Configuration screen, which is accessed from Integration Server Administrator.

To open the Ariba Supplier OnRamp Adapter Configuration screen

Procedure

Start Integration Server Administrator.
Click IBM webMethods Adapter for Ariba Supplier OnRamp under Adapters.

In the IBM webMethods Adapter for Ariba Supplier OnRamp menu, select Config. The Ariba Supplier OnRamp Adapter Configuration screen appears.

The following table describes the pages of this user interface, and how you should use them to define a punchout site.

Use This Page…	To…
Config	Specify the following: Parameters for the document receive service. Document handlers. One or more PunchOutOrderMessage mapping services. Event logging services. Services for storing OrderRequest messages. Customized services to listen to and process events that occur during various stages of punchout ordering. If you decide to use Trading Networks with Ariba Supplier OnRamp Adapter, this page also enables you create Trading Networks resources, including processing rules, document type, and attribute definitions. For more information, see Using the Logging Facility.
cXML	Specify or view the following: Specify the service to use to create PayloadIDs and to test the creation of PayloadID. Specify your SharedSecret. All incoming cXML requests are validated against this SharedSecret. Specify your Digital Signature, Signature Type and Signature Encoding. All incoming cXML requests are validated against these. View the version of cXML that you are using. View the name of the Document Type Definition (DTD) file that you are using.
Logs	View log entries of cXML messages sent and received. For more information, see Using the Logging Facility.
Test	Send test messages (ProfileRequest, PunchOutSetupRequest, and OrderRequest) to Ariba Supplier OnRamp Adapter to test the punchout implementation. For more information, see Using the Test Module.
About	View the version, release notes, and build number of your installed Ariba Supplier OnRamp Adapter.

Configuring cXML Document Receive Service Parameters

About this task

For the defaultProfileRequest handler to correctly include the URL to which supported cXML request transaction should be posted, and to enable the Test Module to function properly, you must configure the receive service parameters.

Using Config, you must specify the host and port to which cXML requests will be posted, as well as the protocol to use.

To set the document receive service parameters

Procedure

Start Integration Server Administrator.
Click IBM webMethods Adapter for Ariba Supplier OnRamp under Adapters.
In the IBM webMethods Adapter for Ariba Supplier OnRamp menu, select Config. The Ariba Supplier OnRamp Adapter Configuration screen appears.

Complete the following fields in the cXML Document Receive Service section of the page and click the Update button:

In this field…	Specify…
Protocol	`http` or `https`.
Hostname	The name of the host.
Port	The port number of the host.

Configuring cXML InvoiceDetailRequest Parameters

About this task

For the InvoiceDetailRequest to correctly include the URL to which supported cXML request transaction should be posted, and to enable the Test Module to function properly, you must configure the InvoiceDetailRequest parameters.

Using Config, you must specify the host, port, and service to which cXML InvoiceDetailRequests will be posted, as well as the protocol to use.

To configure the cXML InvoiceDetailRequest parameters

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, complete the following fields in the Invoice Detail Request Configsection of the page and click the Update button:

In this field…	Specify…
Protocol	`http` or `https`.
Hostname	The name of the host.
Port	The port number of the host.
Service	Remaining part of the URL.

Creating PunchOutSetupRequest Handlers

A PunchOutSetupRequest handler is a service that you create and implement to set up all of the supplier's resources needed to conduct a punchout buying session. The cXML processing mechanism of Ariba Supplier OnRamp Adapter, built into receiveCXML invokes this handler when buyers send PunchOutSetupRequest messages.

To create and implement a PunchOutSetupRequest handler, you perform the following tasks:

Create an appropriate service for the handler, using Config.
Implement the handler's functionality using Ariba Supplier OnRamp Adapter API services.

Creating PunchOutSetupRequest Handler Services

About this task

A PunchOutSetupRequest handler service is invoked with a PunchOutSetupRequest record argument that represents the actual received message. The PunchOutSetupRequest handler is also invoked with an operation argument that represents the PunchOutSetupRequest operation that is being requested (create, inspect, or edit). Depending on the operation being requested, the PunchOutSetupRequest handler must return a catalogURL that represents one of the following:

For the create operation: a URL to the supplier's catalog, where the buyer can begin shopping for the first time.
For the inspect operation: a URL to the supplier's catalog, where the buyer can view his or her existing shopping selections.
For the edit operation: a URL to the supplier's catalog, where the buyer can edit his or her shopping selections.
Note: You may choose not to implement inspect and edit operations. The document receive service receiveCXML reports unimplemented operations to the buyer's Ariba Buyer with an error status in the PunchOutSetupResponse.

The detailed implementation of a PunchOutSetupRequest handler depends on the supplier's systems and resources. Each supplier may have different shopping cart systems, application servers, web servers, and ordering systems. The handler must set up resources for a shopping session and return a URL for a buyer to shop online.

To create a PunchOutSetupRequest handler service, you specify a service name for the handler and the operation for which the handler is used. Ariba Supplier OnRamp Adapter automatically generates a service template for you, with the specification specified in wm.b2b.cxml.guidelines:PunchOutSetupRqstHdlr. In addition,Ariba Supplier OnRamp Adapter registers the service internally so that when receiveCXML receives a PunchOutSetupRequest with the specified operation type, the handler service will be invoked.

To create a PunchOutSetupRequest handler service

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Add Handler button in the cXML Request Document Handlingsection of the page. The Handler Configurationscreen appears.

Complete the following fields and click the Submit button:

In this field…	Specify…
cXML Document Type	Select PunchOutSetupRequest.
Operation / Sub Type	Select create, edit, or inspect. Select any if you want the handler to apply to all operations. If you select the operation type any, the handler behaves like a default handler. That is, the handler is invoked only if a PunchOutSetupRequest arrives with an operation type for which no handler is registered. If a handler is registered for a specific operation type, that handler is invoked instead of the default handler.
Service Name	The name of the service to be created for the handler. Type the name in the following format: `folderName:serviceName` If the service name already exists, the existing service will not be overwritten. Ariba Supplier OnRamp Adapter will register the existing service internally to handle the selected operation type.
Package Name	The name of the package in which the service is created.

Implementing PunchOutSetupRequest Handler Services

About this task

Once the PunchOutSetupRequest handler service is created, you must implement its functionality.

To implement a PunchOutSetupRequest handler service

Procedure

If the supplier requires the buyer to be authenticated, ensure that the SharedSecret validation option is enabled in cXML. For more information, see Configuring Shared Secret Validation.
If the supplier requires the buyer to be authenticated using Digital Signature, ensure that the Digital Signature, Signature Type, and Signature Encoding options are enabled in cXML. For more information, see Configuring Digital Signature Validation.
Get the buyer information from the cXML message header and verify that the sender is a valid buyer. To do this, perform the following steps:
1. Use the helper service wm.b2b.cxml.utils.protocol:getFrom in the WmcXML12 package to obtain the From and Sender fields from the cXML message header, or obtain those fields by manually mapping them from the cXML message.
2. The credentials are represented as record list elements in the from and sender fields. Use the helper service wm.b2b.cxml.utils.protocol:getCredential in the WmcXML12 package to extract the credential record with the desired type by mapping the Credential record list field in the from record returned by getFrom to the Credentials record list input field for the getCredential service.
  
  Note: In cXML 1.2, one or more credentials may be sent in a cXML request to represent the buyer. A buyer may belong to a particular Ariba Marketplace and have an additional credential for that marketplace. The credential would have a type set to marketplace. When a buyer is represented by multiple credentials, you typically use the credential without the type field set to determine who the buyer is. For a detailed discussion of credentials, see the cXML User's Guide Version 1.2.
3. Get the sender's identity and domain and make sure it is a valid buyer. You may have a resource file which contains a list of buyers to look up.
Initialize resources of the shopping cart engine for the buyer session.

For the buyer session, initialize any resources that the shopping cart system needs. If the shopping cart system requires a unique ID to identify a buyer session it is initializing, use the server sessionID. If authentication fails, set the serviceError output record with a meaningful message using the error reporting utility in this package, and exit from the PunchOutSetupRequest handler successfully. Do not terminate by throwing exceptions or by Exiting with failure.
Get and store the cXML-specific buyer session data.

Use the helper services getBuyerCookie, getFrom, and getPunchOutURL in the wm.b2b.cxml.utils.protocol folder to obtain the BuyerCookie field, the From field, and the PunchOutURL of the cXML message header. These fields are needed to complete the punchout process later. The BuyerCookie and From fields are needed in the PunchOutOrderMessage. The PunchOutURL is the URL of the Ariba Buyer to which the PunchOutOrderMessage is form posted when the buyer checks out.

To store the cXML specific buyer session data, use any of the following methods:
- If your shopping cart system can store buyer session metadata, store the BuyerCookie, the PunchOutURL, and the From field data in the shopping cart system for later retrieval.
- If your shopping cart system cannot store buyer session metadata, you can store the buyer session metadata using the session object of Integration Server. You can use the helper services in wm.b2b.cxml.shared.session to do this. For more information, see Using the Persistence Utility and wm.b2b.cxml.shared.session.
  In addition, you can use the persistence utility in the wm.b2b.cxml.utils.persistence.session folder in the WmAribaSupplier package, which is provided with Ariba Supplier OnRamp Adapter.
  
  Alternatively, if you want to store the session data in an external data store, you must implement services to create, read, and delete the buyer session metadata into the persistent store. These services should implement the service specifications of saveBuyerSessionDataSpec, getBuyerSessionDataSpec, and removeBuyerSessionDataSpec described in wm.b2b.cxml.utils.persistence.spec. For more information, see Using the Persistence Utility.
- You may pass these fields as GET input fields in all the catalog pages returned to the buyer, or as hidden form fields embedded in all the catalog pages returned to the buyer. However, keep in mind that these fields need to be passed in every catalog page until the buyer checks out.
Create the catalog URL for the buyer session and return the URL in the catalogURL output parameter. The format of the catalog URL can be anything meaningful to distinguish buying sessions. Typically, this is a URL with a sessionID GET input field.

Note: If the URL contains special characters such as space characters, the URL should be HTML encoded before it is returned by the handler service.

Creating OrderRequest Handlers

An OrderRequest handler is a service that you create and implement to receive and process order requests, order updates, and deletions (cancellations). The OrderRequest handler is responsible for mapping the cXML OrderRequest to order requests/ cancellations for the underlying purchasing system. The cXML processing mechanism built into receiveCXML in Ariba Supplier OnRamp Adapter invokes this handler when buyers send OrderRequest messages.

To create and implement an OrderRequest handler, you perform the following tasks:

Create an appropriate service for the handler, using Config.
Implement the handler's functionality using the API services of Ariba Supplier OnRamp Adapter.

Creating OrderRequest Handler Services

About this task

An OrderRequest handler is invoked with an OrderRequest record argument that represents the actual received message. The OrderRequest handler may also have as an input parameter an attachmentWrapperCollection object, which contains one or more attachment documents that were sent with the OrderRequest. The OrderRequest handler is also invoked with an operation argument that represents the OrderRequest operation that is being requested (new, update, delete).

The OrderRequest must return a status in its serviceError output parameter: If an error was encountered while processing the OrderRequest, the serviceError must be set to indicate the error. If no error was set, the Ariba Supplier OnRamp Adapter core returns a successful OrderResponse. However, the OrderResponse does not indicate an order fulfillment. It only indicates that the OrderRequest was successfully received, and that the request is being processed. This is a limitation of the cXML 1.2 framework, not a limitation of Ariba Supplier OnRamp Adapter.

Note: You may choose not to implement the update or delete operations. The cXML document receive service receiveCXML will report unimplemented operations to the buyer's Ariba Buyer with an error status in the OrderResponse.

To create an OrderRequest handler service, you specify a service name for the handler and the operation for which the handler is used. Ariba Supplier OnRamp Adapter automatically generates a service template for you, with the specification specified in wm.b2b.cxml.guidelines:OrderRequestHdlr. In addition, it registers the service internally so that when receiveCXML receives an OrderRequest with the specified operation type, the handler service will be invoked.

To create an OrderRequest handler service

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen., click the Add Handler button in the cXML Request Document Handling section of the page. The Handler Configuration screen appears.

Complete the following fields and click the Submit button:

In this field…	Specify…
cXML Document Type	Select OrderRequest.
Operation / Sub Type	Select new, update, or inspect. Select any if you want the handler to apply to all operations. If you select the operation type any, the handler behaves like a default handler. That is, the handler is invoked only if an OrderRequest arrives with an operation type for which no handler is registered. If a handler is registered for a specific operation type, that handler is invoked instead of the default handler.
Service Name	The name of the service to be created for the handler. Type the name in the following format: `folderName:serviceName` If the service name already exists, the existing service will not be overwritten. Ariba Supplier OnRamp Adapter will register the existing service internally to handle the selected operation type.
Package Name	The name of the package in which the service is created.

Implementing OrderRequest Handler Services

About this task

Once the OrderRequest handler service is created, you must implement its functionality.

To define an OrderRequest handler service

Procedure

If the supplier requires the buyer to be authenticated, ensure that the SharedSecret validation option is enabled in cXML. For more information, see Configuring Shared Secret Validation.
If the supplier requires the buyer to be authenticated using Digital Signature, ensure that the Digital Signature, Signature Type, and Signature Encoding options are enabled in cXML. For more information, see Configuring Digital Signature Validation.
Get the buyer information from the cXML message header and verify that the sender is a valid buyer. To do this, perform the following steps:
1. Use the helper service wm.b2b.cxml.utils.Protocol:getFrom to obtain the From and Sender fields from the cXML message header, or obtain those fields by manually mapping them from the cXML message.
2. The credentials are represented as record list elements in the from and sender fields. Use the helper service wm.b2b.cxml.utils.protocol:getCredential to extract the credential record with the desired type by mapping the Credential record list field in the from record returned by getFrom to the Credentials record list input field for the getCredential service.
  
  Note: In cXML 1.2.011, one or more credentials may be sent in a cXML request to represent the buyer. A buyer may belong to a particular Ariba Marketplace and have an additional credential for that marketplace. The credential would have a type set to marketplace. When a buyer is represented by multiple credentials, you typically use the credential without the type field set to determine who the buyer is. For a detailed discussion of credentials, see the cXML User's Guide Version 1.2.
3. Get the sender's identity and domain and make sure it is a valid buyer. You may have a resource file which contains a list of buyers to look up.
Write Java code or flow code to map the OrderRequest to the ordering system's format and submit the order to the order system.

This is implementation dependent. If you encounter a problem while processing the OrderRequest, set the serviceError output record with a meaningful message using the reporting utility of Ariba Supplier OnRamp Adapter error and exit from the OrderRequest handler successfully. Do not terminate by throwing exceptions or by Exiting with failure.
Check if the attachmentWrapperCollection object to see if it is present. If so, extract the attachment documents and process them accordingly, using the attachmentWrapper API. For more information, see Using the Attachment Utility.

This is implementation dependent. If you encounter a problem while processing the OrderRequest, set the serviceError output record with a meaningful message using the error reporting utility of Ariba Supplier OnRamp Adapter and exit from the OrderRequest handler successfully. Do not terminate by throwing exceptions or by Exiting with failure.
Clear the shopping cart and remove the buyer session.

Creating MasterAgreementRequest Handlers

About this task

A MasterAgreementRequest handler is a service that you create and implement to receive and process new MasterAgreementRequests, updates, and deletions (cancellations). The MasterAgreementRequest handler is responsible for mapping the cXML Master Agreement to MasterAgreementRequests/cancellations for the underlying system. The cXML processing mechanism of Ariba Supplier OnRamp Adapter, built into the wm.b2b.cxml:receiveCXML service, invokes the handler when buyers send MasterAgreementRequest messages.

This section describes how to configure Ariba Supplier OnRamp Adapter to support the MasterAgreementRequest document types in a supplier's site that does not use Trading Networks.

To create and implement a MasterAgreementRequest handler

Procedure

Create an appropriate service for the handler, from the Ariba Supplier OnRamp Adapter Configuration screen.
Implement the handler's functionality using the Ariba Supplier OnRamp Adapter API services.

Creating MasterAgreementRequest Handler Services

About this task

A MasterAgreeementRequest handler is invoked with a Master Agreement record argument that represents the actual received message. The MasterAgreeementRequest handler is also invoked with an operation argument that represents the Master Agreement operation that is being requested (new, update, delete).

The Master Agreement must return a status in its serviceError output parameter. If an error was encountered while processing the MasterAgreeementRequest, the serviceError must be set to indicate the error. If no error was set, Ariba Supplier OnRamp Adapter returns a response with the status code of 200 that indicates that the MasterAgreementRequest was successfully received, and that the request is being processed.

To create a MasterAgreementRequest handler service

Procedure

Start Integration Server Administrator.
In the IBM webMethods Adapter for Ariba Supplier OnRamp menu, select Config. The IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen appears.
Click the Add Handler button in the cXML Request Document Handlingsection of the page. The Handler Configuration screen is displayed.

Complete the following fields and click the Submit button:

In this field…	Specify…
cXML Document Type	Select MasterAgreementRequest.
Operation / Sub Type	Select new, update, or delete. Select any if you want the handler to apply to all operations.
Service Name	The name of the service to be created for the handler. Type the name in the following format: `folderName:serviceName` If the service name already exists, the existing service will not be overwritten. Ariba Supplier OnRamp Adapter will register the existing service internally to handle the selected operation type.
Package Name	The name of the package in which the service is created.

Implementing MasterAgreementRequest Handler Services

About this task

Once the MasterAgreementRequest handler service is created, you must implement its functionality.

To define a MasterAgreementRequest handler service

Procedure

If the supplier requires the buyer to be authenticated, ensure that the SharedSecret validation option is enabled in cXML. For more information, Configuring Shared Secret Validation.
If the supplier requires the buyer to be authenticated using Digital Signature, ensure that the Digital Signature, Signature Type, and Signature Encoding options are enabled in cXML. For more information, see Configuring Digital Signature Validation.
Get the buyer information from the cXML message header and verify that the sender is a valid buyer. To do this, perform the following steps:
1. Use the helper service wm.b2b.cxml.utils.Protocol:getFrom to obtain the From and Sender fields from the cXML message header, or obtain those fields by manually mapping them from the cXML message.
2. The credentials are represented as record list elements in the from and sender fields. Use the helper service wm.b2b.cxml.utils.protocol:getCredential to extract the credential record with the desired type by mapping the Credential record list field in the from record returned by getFrom to the Credentials record list input field for the getCredential service.
  
  Note: In cXML 1.2.011, one or more credentials may be sent in a cXML request to represent the buyer. A buyer may belong to a particular Ariba Marketplace and have an additional credential for that marketplace. The credential would have a type set to marketplace. When a buyer is represented by multiple credentials, you typically use the credential without the type field set to determine who the buyer is. For a detailed discussion of credentials, see the cXML User's Guide Version 1.2.
3. Get the sender's identity and domain and make sure it is a valid buyer. You may have a resource file which contains a list of buyers to look up.
Write Java code or flow code to map the MasterAgreementRequest to the format of the MasterAgreement system and submit the MasterAgreement to the MasterAgreement system. This is implementation dependent. If you encounter a problem while processing the MasterAgreementRequest, set the serviceError output record with a meaningful message using the reporting utility of Ariba Supplier OnRamp Adapter error and exit from the MasterAgreementRequest handler successfully. Do not terminate by throwing exceptions or by Exiting with failure.
Clear the shopping cart and remove the buyer session.

Setting the Default ProfileRequest Handler

About this task

A ProfileRequest is a document that a buyer sends to a supplier to find out what kind of cXML request transactions that the supplier accepts. Upon receiving a ProfileRequest, the supplier must return a ProfileResponse indicating which cXML transactions he supports.

The Ariba Supplier OnRamp Adapter package includes a default ProfileRequest handler that dynamically queries the Configuration Module for the list of handlers currently registered, and returns a list of transactions current supported. For more information, see pub.ariba.supplier.handlerImpl:defaultProfileRequestHandler.

To set the default ProfileRequest handler

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Add Handler button in thecXML Request Document Handling section of the page. The Handler Configuration screen appears.
Click the Set To Default Handler button.

The default ProfileRequest handler is set to pub.ariba.supplier.handlerImpl:defaultProfileRequestHandler.

Note: Make sure that you have the Document Receive Service parameters set in Config, as described in "Configuring cXML OrderRouting on Ariba SN. The defaultProfileRequestHandler uses these parameters to construct a URL to which the handled cXML request should be HTTP posted.

Mapping PunchOutOrderMessages

When a buyer has finished shopping at a supplier's web site and performs a checkout, the contents of the shopping cart must be sent back to the Ariba Buyer using a PunchOutOrderMessage. The PunchOutOrderMessage must be encoded and sent to the buyer's web browser according to the following Ariba specifications:

The PunchOutOrderMessage must be embedded in the checkout page in HTML format, either as a URL encoded input value named cXML-urlencoded or as a base64-encoded input value named cXML-base64.
The target of the checkout page form must be the punchout URL sent by the buyer's procurement application in the PunchOutSetupRequest.

Ariba Supplier OnRamp Adapter provides a utility on cXML to assist you in mapping the shopping cart data into a PunchOutOrderMessage, encoding the PunchOutOrderMessage and returning a checkout web page. Using this utility, you can define a service that your shopping cart system can invoke to help create the PunchOutOrderMessage.

This utility enables you to:

Create a mapping service to map shopping cart data to the PunchOutOrderMessage.
Specify how to format the PunchOutOrderMessage as URL encoded or base64-encoded.
How to embed an encoded PunchOutOrderMessage into an HTML web page (optional).

The following subsections describe how to use this utility.

Methods of Mapping PunchOutOrderMessages

Before using the mapping utility, you must determine how you want to pass shopping cart data from the shopping cart engine to the flow or Java service, and how that service will return the PunchOutOrderMessage to the shopping cart engine. Choose one of the following methods of doing this:

Using the Client API
Using a client API to integrate a catalog system, you can create a record representing the shopping cart. Then, using the client API, you can invoke a PunchOutOrderMessage service that you define using the Configuration Module to map data between the shopping cart record and the PunchOutOrderMessage. The PunchOutOrderMessage will then be available in the pipeline as a string field (PunchOutOrderMessageString) formatted the way you specified. For the procedure to do this, see Passing Shopping Cart Data Using the Client API.
Using HTTP Form Posting
Alternatively, you can use HTTP form posting to pass shopping cart data from the shopping cart system to a PunchOutOrderMapping service that you define using the Configuration Module. Using HTTP form posting, your shopping cart creates an XML string containing the shopping cart. The shopping cart system posts the XML string as a name=value form parameter to the PunchOutOrderMapping service. The PunchOutOrderMessage, formatted the way you specified, is returned in the HTTP response body. For the procedure to do this, see Passing Shopping Cart Data Using HTTP Form Posting.

Passing Shopping Cart Data Using the Client API

To pass shopping cart data using the client API, you perform the following tasks:

Create a PunchOutOrderMessage mapping service that maps the shopping cart to a record that you create to represent the shopping cart.
Use the generated mapping service for your shopping cart system integration using the client API.

Creating PunchOutOrderMessage Mapping Services

About this task

To create a PunchOutOrderMessage mapping service for use with the client API

Procedure

Using Designer, create a simple record to represent the shopping cart on the shopping cart system.
In IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Create Mapping Servicebutton next to the PunchOutOrderMessage Mapping label to begin creating a mapping service.

Complete the following fields:

In this field…	Specify…
Mapping Service Name	The name of the service to be created for the handler. Type the name in the following format: `folderName:serviceName`
Package	The package in which to create the service.
resultFormat	The format in which you want your mapping service to return the PunchOutOrderMessage to the catalog system (URL encoded, base-64 encoded, or raw string).
responseType	How to return the PunchOutOrderMessage. Select webMethods Pipeline.
ShoppingCart Record Name	The name of the record you created to represent the shopping cart. Type the name in the following format: `folderName:serviceName`

Ariba Supplier OnRamp Adapter generates a mapping service stub that will contain the shopping cart record you specified and some code to format a PunchOutOrderMessage record into a string, based on the resultFormat you specified.

Using Designer, implement the handler service stub to map the shopping cart record's data to the PunchOutOrderMessage record.
Generate the client code using Designer. For more information, see the IBM webMethods Service Development Help for your release.

To use the generated mapping service for your shopping cart system integration using the client API, see Using Generated PunchOutOrderMessage Handler Services with the Client API, below.

Using Generated PunchOutOrderMessage Handler Services with the Client API

After you generate a mapping service for your PunchOutOrderMessage handler, you use this service for your shopping cart system integration using the client API.

Using the client API, create a record called ShoppingCart to correspond to the shopping cart record you defined in your PunchOutOrderMessage mapping service. For example, if you defined a simple record representing shopping cart items and totals such as the following:

In your client code you would create a record with this structure and populate its fields.

The generated client API code will invoke the PunchOutOrderMessage mapping service you created. The mapping service will return the PunchOutOrderMessage string in an output variable named PunchOutOrderMessageString. Using the client API, you extract the PunchOutOrderMessage.

Passing in an HTML Template

Using the client API, you can also pass in a string representing an HTML checkout page template that you want the mapping service to embed the PunchOutOrderMessage into. If you pass an HTML template into your mapping service, the mapping service will replace all occurrences of the string "%value PunchOutOrderMessageString" with the encoded PunchOutOrderMessage. You can use this feature to embed a URL encoded or base64 encoded hidden form field in an HTML form.

To use this feature, simply pass in the HTML template as a string input parameter template into the mapping service. The HTML template will be returned in the PunchOutOrderMessageString output parameter.

Passing Shopping Cart Data Using HTTP Form Posting

About this task

To use HTTP form posting to map PunchOutOrderMessages

Procedure

Using Designer, create a simple record to represent the shopping cart.

The record must be a BoundNode representing the XML document that the shopping cart system will send to this service representing the shopping selection. That is, a BoundNode is a record containing only one field, which is a record. The name of the sub-record field is the name of the root element that the XML document represents.
In the IBM webMethods Adapter for Ariba Supplier OnRamp menu, select Config. The IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen appears.
Click the Create Mapping Service button next to the PunchOutOrderMessage Mappinglabel to begin creating a mapping service.

Complete the following fields:

In this field…	Specify…
Mapping Service Name	The name of the service to be created for the handler. Type the name in the following format: `folderName:serviceName`
Package	The package in which to create the service.
ResultFormat	The format in which you want your mapping service to return the PunchOutOrderMessage to the catalog system (URL encoded, base-64 encoded, or raw string).
ResponseType	How to return the PunchOutOrderMessage. Select HTTP Response.
ShoppingCart Record Name	The name of the record you created to represent the Shopping Cart. Type the name in the following format: `folderName:serviceName` Ariba Supplier OnRamp Adapter generates a mapping service stub. The mapping service stub will contain the shopping cart record you specified. The generated stub will also contain some code to convert an XML string representing the shopping cart into the record you specified. In addition, the generated stub will format a PunchOutOrderMessage record into a string, based on the resultFormat you specified

Using Designer, implement the handler service stub as follows:
1. Map the shopping cart record's data to the PunchOutOrderMessage record.
2. In the shopping cart system, extract the PunchOutOrderMessage from the HTTP response body returned by the mapping service.

Using Generated Mapping Services with the HTTP Form Post

About this task

Using HTTP form post, a catalog system can use the PunchOutOrderMessage mapping service that you define. To use the mapping service for your shopping cart system integration, using HTTP form post, perform the following steps:

To use a generated mapping service with HTTP form posting

Procedure

Ensure that the shopping cart system is capable of creating a shopping cart XML string representing the shopping cart.
From the shopping cart system, perform an HTML form post to the following URL:
```
http(s)://<servername>:<port>/invoke/<name of your mapping service>
```
As part of the HTML form, specify the name=value pair ShoppingCartXML, containing the ShoppingCart XML.

Results

The mapping service will return the formatted PunchOutOrderMessage in the body of an HTTP response. The shopping cart system must be capable of extracting the raw contents from the HTTP response.

Passing in an HTML Template

You can also pass in a string representing an HTML checkout page template that you want the mapping service to embed the PunchOutOrderMessage into.

If you pass in an HTML template into your mapping service, the mapping service will replace all occurrences of the string "%value PunchOutOrderMessageString" with the encoded PunchOutOrderMessage. You can use this feature to embed a URL encoded or a base64-encoded hidden form field in an HTML form.

To use this feature, simply pass in the HTML template as a string input parameter template in your HTML form post. The HTML template will be returned as the HTTP response content.

Correlating OrderRequests with PunchOutOrderMessages

After the buyer sends an OrderRequest to the supplier, and the order in the PunchOutOrderMessage is approved, the OrderRequest has to be correlated to the shopping session. Currently, the PunchOutOrderMessage does not have explicit fields to pass supplier session IDs back to the Ariba Buyer. Consequently, the OrderRequest does not include any supplier session ID. Ariba suggests that this information (sessionIDs) be sent from the supplier to the buyer in the SupplierAuxilaryPartID in ItemOut element(s) in the PunchOutOrderMessage. The ItemOut element(s) must be returned from the buyer to the supplier in the OrderRequest message.

Configuring cXML Message Parameters

Ariba Supplier OnRamp Adapter uses the following fields when it validates incoming requests for proper credentials and when it creates and sends responses:

PayloadID
The cXML field PayloadID appears in all cXML messages; it uniquely identifies the cXML message. When Ariba Supplier OnRamp Adapter returns cXML responses, it generates a unique PayloadID for the response messages. To generate a PayloadID, you can use the built-in PayloadID service or you can implement a custom service to generate it for you.
SharedSecret
When Ariba SN forwards cXML requests from Ariba Buyers, it inserts a SharedSecret in the request's Header (in the Sender Credential). The SharedSecret is a password that the supplier chooses and configures on Ariba SN. As a supplier, you should verify that all incoming requests contain this SharedSecret. If not, the cXML request should not be processed. Ariba Supplier OnRamp Adapter provides a built-in mechanism for verifying the SharedSecret of all incoming cXML requests. You can optionally disable this feature if you want to perform tests without it. For more information on SharedSecret, see Configuring Shared Secret Validation.
DigitalSignature
When Ariba SN forwards cXML requests from Ariba Buyers, it inserts a Digital Signature (optional) in the request (in the Sender Credential). As a supplier, you should verify that all incoming requests contain this Digital Signature. If not, the cXML request should not be processed. Ariba Supplier OnRamp Adapter provides a built-in mechanism for verifying the Digital Signature of all incoming cXML requests. You can optionally disable this feature if you want to perform tests without it. For more information on DigitalSignature, see Configuring Digital Signature Validation.

To perform these tasks, you use cXML. In addition, this enables you to:

View the version of cXML that you are using.
View the name of the Document Type Definition (DTD) file that you are using. A DTD file is a text file that describes the syntax and order of cXML documents.

Specifying Services for Generating PayloadIDs

About this task

To generate a PayloadID, you can use the built-in payloadID service or you can implement a custom service to generate it for you.

To specify the PayloadID service

Procedure

Start Integration Server Administrator.
In the IBM webMethods Adapter for Ariba Supplier OnRamp menu, select cXML. The cXML Message Fields page appears, showing the cXML version and the DTD file you are using.
Specify whether to use the default service for generating your payloadID (ns.pub.ariba.supplier.cxml.spec:createPayloadIDSpecin the package WmAribaSupplier) or a custom service that you provide, and click the Update button.
To view a PayloadID that the service creates, click the Test button. The PayloadID is displayed on the screen.