Implementing a Punchout Ordering System with Trading Networks

Introduction

This chapter describes how to configure Ariba Supplier OnRamp Adapter to support your punchout site using Trading Networks. Specifically, this chapter describes the following configuration tasks:

Installing cXML document attributes and document types in Trading Networks.
Creating PunchOutSetupRequest processing rules.
Creating OrderRequest processing rules.
Creating the default ProfileRequest processing rule.
Creating MasterAgreementRequest processing rules.
Configuring the cXML document receive service parameters.
Specifying the InvoiceDetailRequest URL - that is, the URL where the InvoiceDetailRequests are sent from the supplier.
Specifying the service for creating and testing PayloadIDs.
Specifying SharedSecrets.

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

You configure Ariba Supplier OnRamp Adapter using the Integration Server Administrator.

Opening the Ariba Supplier OnRamp Adapter Configuration Screen

About this task

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 Configuration screen appears.

Results

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

Use This Page...	To...
Config	Specify the following: Trading Networks resources, including processing rules, document type, and attribute definitions. Parameters for the document receive service. Services for storing OrderRequest messages. One or more PunchOutOrderMessage mapping services. Event logging services. Customized services to listen to and process events that occur during various stages of punchout ordering.
cXML	Specify or view the following: Specify which 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.

Accessing the Trading Networks Configuration Page

About this task

To access the configuration page for Trading Networks support

Procedure

Start Integration Server Administrator.
Ensure that Trading Networks is installed and enabled on Integration Server.
In the IBM webMethods Adapter for Ariba Supplier OnRamp menu, select Config. The Ariba Supplier OnRamp Adapter Configuration screen appears.
If Trading Networks is installed and enabled on Integration Server, you should see the Use Trading Networks Support check box. Select this option and click the Update button next to it.

The page displays the fields that support Trading Networks, and removes the fields that support the built-in document handling in Ariba Supplier OnRamp Adapter. If you decide later to not use Trading Networks, simply de-select the Use Trading Networks Support option; your handler configuration will be restored.

Adding Default ProfileRequest Processing Rules

About this task

Ariba Supplier OnRamp Adapter for Trading Networks includes a default processing rule and handler service implementation for cXML ProfileRequests.

When a cXML ProfileRequest is received by Trading Networks, the following actions occur:

The default processing rule invokes a built-in handler that determines the buyer (from) and the supplier (to).
The default rule then determines for each of the cXML requests (PunchOutSetupRequest or OrderRequest) if a rule exists that could process the particular request if the message contained the from and the to credentials from the ProfileRequest. If so, the ProfileResponse indicates that the particular cXML request transaction is supported by the supplier.

To add the default ProfileRequest processing rule

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Use Trading Networks Support check box and click the Update button next to it.

The page displays the fields that support Trading Networks.
Click the Create Default button next to theProfileRequest Processing Rule label.

Ariba Supplier OnRamp Adapter will install the default processing rule for ProfileRequests in Trading Networks.

Installing cXML Document Attributes and Document Types in Trading Networks

Trading Networks must contain document attributes that are used to describe parts of the cXML request. Trading Networks must also contain document type definitions describing the cXML requests. You use the Ariba Supplier OnRamp Adapter Configuration screen to add these resources to Trading Networks.

Ariba Supplier OnRamp Adapter will also install cXML document attributes in Trading Networks (fields in the cXML requests that were determined to be important).

Document Types that will be installed by Ariba Supplier OnRamp Adapter include the following:

Document Type	Description
`cXML_OrderRequest_new`	Describes a cXML OrderRequest with operation new.
`cXML_OrderRequest_update`	Describes a cXML OrderRequest with operation update.
`cXML_OrderRequest_delete`	Describes a cXML OrderRequest with operation delete.
`cXML_PunchOutSetupRequest_create`	Describes a cXML PunchOutSetupRequest with operation create.
`cXML_PunchOutSetupRequest_inspect`	Describes a cXML PunchOutSetupRequest with operation inspect.
`cXML_PunchOutSetupRequest_edit`	Describes a cXML PunchOutSetupRequest with operation edit.
`cXML_ProfileRequest`	Describes a cXML ProfileRequest message.
`cXML_InvoiceDetailRequest_new`	Describes a cXML InvoiceDetail Request with operation new.
`cXML_InvoiceDetailRequest_delete`	Describes a cXML InvoiceDetail Request with operation delete.
`cXML_MasterAgreementRequest_new`	Describes a cXML MasterAgreement Request with operation new.
`cXML_MasterAgreementRequest_update`	Describes a cXML MasterAgreement Request with operation update.
`cXML_MasterAgreementRequest_delete`	Describes a cXML MasterAgreement Request with operation delete.

Document Attributes that will be installed by Ariba Supplier OnRamp Adapter include the following:

Document Attribute	Description
`operation`	The cXML Request operation type: For OrderRequest: new, update, or delete. For PunchOutSetupRequest: create, inspect, or edit. For ProfileRequest: unset.
`language`	The language used for the cXML request. This field may be set, depending on whether the cXML request has its xml:lang attribute set.
`cXML_SenderIDDomain`	The cXML Request Header From credential domain.
`cXML_ReceiverIDDomain`	The cXML Request Header To credential domain.
`cXML_RoutingAgentIDDomain`	The cXML Request Header Sender credential domain.
`cXML_RoutingAgentID`	The cXML Request Header Sender identity.
`cXML_MarketplaceSenderIDDomain`	The cXML Request Header From credential domain, for the credential with type marketplace.
`cXML_MarketplaceSenderID`	The cXML Request Header From credential identity, for the credential with type marketplace.
`cXML_OrderDate`	For OrderRequests, the Order Date.
`cXML_OrderCurrency`	For OrderRequests, the currency used in that order.
`cXML_OrderID`	For OrderRequests, the unique identifier for the order.
`cXML_OrderTotal`	The total amount for the order.
`cXML_PunchOut_BrowserFormPostURL`	For PunchOutSetupRequests, the buyer's punchout URL.
`cXML_PunchOut_BuyerCookie`	The buyer's unique shopping session ID.
`cXML_InvoiceID`	A supplier-generated identifier for the Invoice. Identical to the Invoice Number that appears at the top of a physical Invoice.
`cXML_InvoicePurpose`	Purpose of the invoice. standard. (Default) A standard billing statement from the supplier to the buying organization. creditMemo. A credit memo for issuing credit to the buying organization. isHeaderInvoice must be yes. Also, the elementInvoiceDetailSummary/DueAmount must be a negative amount. debitMemo. A debit memo for billing a balance owed by the buying organization. isHeaderInvoice must be yes. Also, the element InvoiceDetailSummary/DueAmount must be a positive amount.
`cXML_InvoiceDate`	Date and time that the Invoice was created (should be earlier than the cXML timestamp).
`cXML_IsInformationOnly`	Indicates whether the buying organization needs to take action. yes. Invoice is for the buying organization's information only (no action needs to be taken by the buying organization). Not specified. (Default) Invoice is functional. The buying organization needs to take action upon receiving this document (submit payment or accept credit).
`cXML_AgreementID`	The procurement system agreement ID for this request.
`cXML_AgreementType`	Whether the agreement refers to a value or quantity.
`cXML_AgreementDate`	The date and time that the agreement request was created. This is different from the effective and expiration date of the agreement.
`cXML_EffectiveDate`	The date that the agreement is available for ordering or releases.
`cXML_ExpirationDate`	The date the agreement is no longer available.

In addition, Ariba Supplier OnRamp Adapter uses the following attributes that are predefined in Trading Networks to represent cXML field values:

Document Attributes	Description
`senderID`	Used to represent the cXML Header From credential identity.
`receiverID`	Used to represent the cXML Header To credential identity.
`documentID`	The cXML payloadID.

Initializing the cXML Document Attributes and Document Types

About this task

To initialize the cXML Document attributes and document types in Trading Networks

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Use Trading Networks Support check box and click the Update button next to it.

The page displays the fields that support Trading Networks.
Click the Initialize button next to the Document Attributes and Type Definitions label in the Trading Networks Configurationsection of the page.

Doing this adds all the cXML document attributes and type definitions into Trading Networks. Ariba Supplier OnRamp Adapter warns you that if you proceed, all cXML attributes and document type definitions that exist in Trading Networks will be overwritten with these default values.
Click OK in response to the warning pop-up.

Note: Clicking OK will overwrite any changes that you have made to any of the predefined attributes and document types.

Creating PunchOutSetupRequest Processing Rules

About this task

You can define a processing rule for each operation (create, edit, or inspect) of a PunchOutSetupRequest, or you create one rule to apply to all operations. The purpose of a processing rule is to invoke custom code when PunchOutSetupRequest operations are executed. To create a processing rule, you:

Use Config to specify the operation and the names of the rule and its associated service and package.
Use Trading Networks to specify conditional processing criteria for the rule.
Use Designer to implement the Integration Server service that the rule invokes.

To create a PunchOutSetupRequest processing rule

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Use Trading Networks Support check box and click the Update button next to it.

The page displays the fields that support Trading Networks.
Click the Create button next to the PunchOutSetupRequest Processing Rule label.

The Create Trading Networks Processing Rule for PunchOutSetupRequest screen appears.

Complete the following fields and click the Submit button:

In this field…	Specify…
Operation	Select create, edit, or inspect. Select any if you want the rule to apply to all operations.
Rule Name	The name of the rule.
Rule Description	Optional. A text description of the rule.
Service Name	The name of the service that will be associated with the rule. Type the name in the following format: `folderName:serviceName`
Package Name	The name of the package in which the service will be located.

View the rule from the Trading Networks Console to confirm that the processing rule was created, and to verify that the rule invokes the service you specified.
Move the processing rule above Default Rule and modify the processing rule to create more restrictive conditions when the rule is executed. For more information, see the IBM webMethods Trading Networks Administrator’s Guide for your release.
Using Designer, display the service stub you specified and implement your PunchOutSetupRequest processing inside the sequence labeled ADD YOUR CODE HERE.

The following fields are available in the pipeline for you to use.

Field	Description
`PunchOutSetupRequest`	A record representing the PunchOutSetupRequest.
`operation`	The PunchOutSetupRequest operation type.
`language`	The language encoding specified in the request.

The following data fields are available for your convenience:

Field	Description
`ReceiverID`	The To credential Identity of the request.
`SenderID`	The From credential Identity of the request.
`cXML_ReceiverIDDomain`	The To credential Identity domain.
`cXML_SenderIDDomain`	The From credential Identity domain.
`cXML_MarketplaceSenderID`	If specified in the cXML Header, the From credential Identity with type marketplace.
`cXML_MarketplaceSenderDomain`	If specified in the cXML Header, the From credential Identity domain with type marketplace.
`cXML_RoutingAgentID`	The Sender credential Identity.
`cXML_RoutingAgentDomain`	The Sender credential Identity domain.
`cXML_PunchOut_BuyerCookie`	The Ariba Buyer's BuyerCookie.
`cXML_PunchOut_BrowserFormPostURL`	The Ariba Buyer's punchout URL.
`bizdoc`	The Trading Networks document envelope. Advanced users can use the Trading Networks API to extract data from the bizdoc envelope that is not already extracted for you.
`sender`	The Trading Networks sender profile. Advanced users can use the Trading Networks API to extract data from the sender profile that is not already extracted for you.
`receiver`	The Trading Networks receiver profile. Advanced users can use the Trading Networks API to extract data from the receiver profile that is not already extracted for you.

In addition, if you customize the processing rule to extract additional fields, those fields will also be available in the pipeline.

Ensure that you have created and implemented a PunchOutSetupRequest handler, as described in Creating PunchOutSetupRequest Handlers.
In your implementation, either you must return the catalogURL in a field called catalogURL or you must create a serviceError record with an error message if there was an error.

The service stub's post processing will create the SetupResponse or ErrorResponse accordingly. The service stub will also perform all logging functions, if enabled. In addition, if you customize the processing rule to extract additional fields, those fields will also be available in the pipeline.

Creating OrderRequest Processing Rules

About this task

You can define a processing rule for each operation (new, update, or delete) of a OrderRequest, or you create one rule to apply to all operations. The purpose of a processing rule is to invoke custom code when OrderRequest operations are executed. To create a processing rule, you:

Use Config to specify the operation and the names of the rule and its associated service and package.
Use Trading Networks to specify conditional processing criteria for the rule.
Use Designer to define the Integration Server service that the rule invokes.

To create an OrderRequest processing rule

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Use Trading Networks Support check box and click the Update button next to it.

The page displays the fields that support Trading Networks.
Click the Create button next to theOrderRequest Processing Rule label.

The Create Trading Networks Processing Rule for OrderRequest screen appears.

Complete the following fields and click the Submit button:

In this field...	Specify...
Operation	Select new, update, or delete. Select any if you want the rule to apply to all operations.
Rule Name	The name of the rule.
Rule Description	Optional. A text description of the rule.
Service Name	The name of the service that will be associated with the rule. Type the name in the following format: `folderName:serviceName`
Package Name	The name of the package in which the service will be located.

View the rule from the Trading Networks Console to confirm that the processing rule was created, and to verify that the rule invokes the service you specified.
Move the processing rule above Default Rule and modify the processing rule to create more restrictive conditions when the rule is executed. For more information, see the IBM webMethods Trading Networks Administrator’s Guide for your release.

Using Designer, display the service stub you specified and implement your OrderRequest processing inside the sequence labeled ADD YOUR CODE HERE.

The following fields are available in the pipeline for you to use:

Field	Description
`OrderRequest`	A record representing the OrderRequest.
`operation`	The OrderRequest operation type.
`language`	The language encoding specified in the request.
`AttachmentWrapperCollection`	If one or more attachments were sent with this OrderRequest, the collection object will be present in the pipeline.

Note: Trading Networks does not do anything special with the attachmentWrapperCollection. It is created by the Ariba Supplier OnRamp Adapter package and inserted into the pipeline before the Trading Networks service is invoked.

The following data fields are available for your convenience:

Field	Description
`ReceiverID`	The To credential Identity of the request.
`SenderID`	The From credential Identity of the request.
`cXML_ReceiverIDDomain`	The To credential Identity domain.
`cXML_SenderIDDomain`	The From credential Identity domain.
`cXML_MarketplaceSenderID`	If specified in the cXML Header, the From credential Identity with type marketplace.
`cXML_MarketplaceSenderDomain`	If specified in the cXML Header, the From credential Identity domain with type marketplace.
`cXML_RoutingAgentID`	The Sender credential Identity.
`cXML_RoutingAgentDomain`	The Sender credential Identity domain.
`cXML_OrderDate`	The Order Date.
`cXML_OrderCurrency`	The currency used in that order.
`cXML_OrderID`	The unique identifier for the order.
`cXML_OrderTotal`	The total amount for the order.
`bizdoc`	The Trading Networks document envelope. Advanced users can use the Trading Networks API to extract data from the bizdoc envelope that is not already extracted for you.
`sender`	The Trading Networks sender profile. Advanced users can use the Trading Networks API to extract data from the sender profile that is not already extracted for you.
`receiver`	The Trading Networks receiver profile. Advanced users can use the Trading Networks API to extract data from the receiver profile that is not already extracted for you.
language	The language used for the cXML request. This field may be set, depending on whether the cXML request has its xml:lang attribute set.
operation	The cXML Request operation type: `new`, `update`, or `delete`.

In addition, if you customize the processing rule to extract additional fields, those fields will also be available in the pipeline.

Ensure that you have created and implemented an OrderRequest handler, as described in Creating PunchOutSetupRequest Handlers.
In your implementation, you must create a serviceError record with a localized error message if there was an error.

The service stub's post processing will create the OrderResponse or ErrorResponse accordingly. The service stub will also perform all logging functions, if enabled.

Creating MasterAgreementRequest Processing Rules

About this task

This section describes how to configure Ariba Supplier OnRamp Adapter to support the MasterAgreementRequest documents in a supplier's site that uses Trading Networks.

Trading Networks must contain document attributes that are used to describe parts of the cXML Master Agreement requests. Trading Networks must also contain document type definitions describing the cXML requests. You use the Config Module of Ariba Supplier OnRamp Adapter to add these resources to Trading Networks.

Ariba Supplier OnRamp Adapter will also install cXML document attributes in Trading Networks (fields in the cXML requests that are determined to be important).

Note: You can modify documents by adding or removing attributes. You also can modify the attributes and related queries to match your document. For instructions, see the IBM webMethods Trading Networks Administrator’s Guide for your release.

You can define a processing rule for each operation of a MasterAgreementRequest document type, or you create one rule to apply to all operations. The purpose of the processing rule is to invoke custom code when MasterAgreement-Request operations are executed. To create a processing rule, you:

Use the Config Module to specify the operation and the names of the rule and its associated service and package.
Use Trading Networks to specify conditional processing criteria for the rule and to move the rule above Default Rule.
Use Designer to define the Integration Server service that the rule invokes.

To create a processing rule

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Use Trading Networks Support check box and click the Update button next to it. The page displays the fields that support Trading Networks.
Click the Create button next to the MasterAgreementRequest Processing Rule label. The Create Trading Networks Processing Rule for the selected document type appears.

Complete the following fields and click the Submit button:

Field	Value
Operation	Select new, update, or delete. Select any if you want the rule to apply to all operations.
Rule Name	The name of the rule.
Rule Description	Optional. A text description of the rule.
Service Name	The name of the service that will be associated with the rule. Type the name in the following format: `folderName:serviceName`
Package Name	The name of the package in which the service will be located.

View the rule from the Trading Networks Console to confirm that the processing rule was created and to verify that the rule invokes the service you specified.
Move the processing rule above Default Rule and modify the processing rule to create more restrictive conditions when the rule is executed. For more information, see the IBM webMethods Trading Networks Administrator’s Guide for your release.
Using Designer, display the service stub you specified and implement your MasterAgreementRequest processing inside the sequence labeled ADD YOUR CODE HERE.

Creating InvoiceDetailRequest Processing Rules

About this task

This section describes how to configure Ariba Supplier OnRamp Adapter to support the InvoiceDetailRequest documents in a supplier's site that uses Trading Networks.

Trading Networks must contain document attributes that are used to describe parts of the cXML Invoice Detail requests. Trading Networks must also contain document type definitions describing the cXML requests. You use the Config Module of Ariba Supplier OnRamp Adapter to add these resources to Trading Networks.

Ariba Supplier OnRamp Adapter will also install cXML document attributes in Trading Networks (fields in the cXML requests that are determined to be important).

Note: You can modify documents by adding or removing attributes. You also can modify the attributes and related queries to match your document. For instructions, see the IBM webMethods Trading Networks Administrator’s Guide for your release.

You can define a processing rule for each operation of an InvoiceDetailRequest document type, or you create one rule to apply to all operations. The purpose of the processing rule is to invoke custom code when InvoiceDetailRequest operations are executed. To create a processing rule, you:

Use the Config Module to specify the operation and the names of the rule and its associated service and package.
Use Trading Networks to specify conditional processing criteria for the rule and to move the rule above Default Rule.
Use Designer to define the Integration Server service that the rule invokes.

To create a processing rule

Procedure

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Use Trading Networks Support check box and click the Update button next to it. The page displays the fields that support Trading Networks.
Click the Create button next to the InvoiceDetailRequest Processing Rule label. The Create Trading Networks Processing Rule for the selected document type appears.

Complete the following fields and click the Submit button:

Field	Value
Operation	Select new, update, or delete. Select any if you want the rule to apply to all operations.
Rule Name	The name of the rule.
Rule Description	Optional. A text description of the rule.
Service Name	The name of the service that will be associated with the rule. Type the name in the following format: `folderName:serviceName`
Package Name	The name of the package in which the service will be located.

View the rule from the Trading Networks Console to confirm that the processing rule was created and to verify that the rule invokes the service you specified.
Move the processing rule above Default Rule and modify the processing rule to create more restrictive conditions when the rule is executed. For more information, see the IBM webMethods Trading Networks Administrator’s Guide for your release.
Using Designer, display the service stub you specified and implement your MasterAgreementRequest or InvoiceDetailRequest processing inside the sequence labeled ADD YOUR CODE HERE.

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 Integration Server 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 the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Create Mapping Service button 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 Trading Networks Administrator’s Guide for your release.

To use the generated mapping service for your shopping cart system integration using the client API, see Using Generated Mapping Services with the HTTP Form Post.

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 Configuration screen, click the Create Mapping Service button next to the PunchOutOrderMessage Mapping label to begin creating a mapping service.

Complete the following fields:

In this field	Specify...
Service Name	The name of the service to be created for the handler. Type the name in the following format: `folderName:serviceName`
Package Name	The package in which to create the service.
Encode PunchOutOrderMessage in	The result format in which you want your mapping service to return the PunchOutOrderMessage to the catalog system (URL encoded, base-64 encoded, or raw string).
Return PunchOutOrderMessage as	The response type that indicates how to return the PunchOutOrderMessage. Select HTTP Response Content.
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 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

In the IBM webMethods Adapter for Ariba Supplier OnRamp Configuration screen, click the Use Trading Networks Support check box and click the Update button next to it.

The page displays the fields that support Trading Networks.

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

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

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 From 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, for example, 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 theIBM 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:createPayloadIDSpec in 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 appears on the screen.