Concepts

cXML, or commerce eXtensible Markup Language, is an open XML-based standard protocol created by Ariba, Inc., and is designed specifically for e-commerce. cXML is defined by a set of Document Type Definitions (DTDs), which are text files that describe the syntax and order of cXML documents.

Using cXML, you can create the following kinds of e-commerce documents:

• Catalogs. Static files that describe the products and services that you offer. A buyers' procurement application stores your catalogs in its database, making them available to its users.
• Punchout catalogs. Interactive catalogs running on your web site. By running your catalogs on your web site, you eliminate the need to send your catalogs to buyers. Users access a punchout web site by sending a cXML PunchOutSetupRequest document to a network e-commerce hub such as Ariba SN. The hub accepts the request, verifies the buyer, and passes the request to your punchout site. The punchout site responds with the location of the catalog.
• Purchase orders. Requests from buyers that are routed through Ariba SN to a supplier to fulfill a contract. Users send purchase order requests using a cXML OrderRequest document through Ariba SN. When you configure your account on an e-commerce network hub, you specify a URL to which all cXML purchase orders will be sent. Upon receiving a purchase order, you send it to your internal order management system and fulfill it. Your web site must then return an OrderResponse acknowledgement to the e-commerce network hub.
• Profile requests. Documents sent to suppliers to query for the cXML transactions the suppliers support.

Ariba Supplier OnRamp Adapter provides a basic mechanism to process each XML request type received by Ariba SN. The basic framework receives and decodes cXML requests from Ariba SN and executes "handlers" that you create for each of the cXML document types to implement the punchout process or order processing.

The document receiver service wm.b2b.cxml:receiveCXML in the WmAribaSupplier package is the entry point for all cXML request messages sent to the supplier from the buyer's procurement system (shown as (2) in the figure).

The receiveCXML service performs the following tasks:

• Parses the received request messages (cXML documents or Multipart MIME messages) and creates node objects to represent them, so they can be easily manipulated by flow or Java services on Integration Server.
• Initiates processing of the request message.

The wm.b2b.cxml.messages folder in the WmAribaSupplier package contains services to create and send cXML messages related to the punchout process. The Message Module contains utilities for creating or sending the following kinds of cXML messages in HTTP format:

• OrderResponse. A response to an OrderRequest sent by an Ariba Buyer. This response should indicate that an OrderRequest was successfully received, and that the request is being processed.
• PunchOutSetupResponse. A response to a PunchOutSetupRequest sent by an Ariba Buyer. This response should contain a URL that tells the buyer's Ariba Buyer where to go to initiate a browsing session on your supplier web site.
• ErrorResponse. An error message that you send to an Ariba Buyer.
• ProfileResponse. A response to a ProfileRequest. A ProfileRequest is a buyer's query to a supplier for a list of cXML request transactions that the supplier is capable of processing. The response contains a list of supported cXML transactions and the locations where to the send the cXML transaction request documents.
• MasterAgreementResponse. A response acknowledging the MasterAgreementRequest sent by the Ariba Buyer.

Ariba Supplier OnRamp Adapter uses the Message Module to return cXML responses to the Ariba Buyer, based on output parameters you return in your implementation. The Message Module is used with both the basic document processing mechanism and with the Trading Networks processing mechanism. For punchout implementations, you do not need to use these services, because the responses are automatically returned by Ariba Supplier OnRamp Adapter.

The Configuration Module in Ariba Supplier OnRamp Adapter stores all of the configuration data related to the supplier specific implementation. The Configuration Module also provides tools to create stages of the punchout process. You access the Configuration Module from the Integration Server Administrator, selecting Ariba On Ramp > Config. The Ariba Supplier OnRamp Adapter Configuration screen appears.

From the Configuration screen you specify how to process cXML messages:

• For processing without Trading Networks, you use Ariba Supplier OnRamp Adapter Config to specify the name of the message handler services that will be processing the cXML messages received from Ariba Buyer. The Document Receiver uses this part of the module to find and invoke the appropriate handlers when it receives a cXML message.
• For processing with Trading Networks, you use Ariba Supplier OnRamp Adapter Config to create cXML routing rules and services to process cXML messages.

  With the Configuration Module you can also:

  • Define PunchOutOrderMessage mapping services to convert buyer selections from a shopping cart system to a PunchOutOrderMessage,
  • Format the PunchOutOrderMessage in a way that can be understood by the shopping cart system.
  • Store configuration data related to logging, event services, and cXML message parameters.

The Logging/Document Store Module logs status messages during the punchout process. You can view log entries from the Integration Server Administrator.

In addition, this module can manage the storing of cXML OrderRequests received. If Trading Networks is used, this module uses Trading Networks to store log entries and OrderRequests. If Trading Networks is not used, this module stores log entries and OrderRequests in the server's file system.

You can configure this module to store log entries and OrderRequests in a custom storage facility, by implementing a set of services and registering them from the Ariba Supplier OnRamp Adapter Configuration screen. For more information, see Using the Logging Facility.

When Ariba Supplier OnRamp Adapter sends or receives cXML messages, it reports the status of the message transaction to the Event Module. The following kinds of events are reported:

Using the Ariba Supplier OnRamp Adapter Configuration screen, you can set services that are automatically invoked when these events occur. For example, you can invoke a service to email an administrator when an OrderRequest fails. For more information, see Listening to and Processing Punchout Process Events.

The Error Module reports errors or propagates errors throughout Ariba Supplier OnRamp Adapter. It consists of the services in wm.b2b.cxml.utils.errors folder in the WmAribaSupplier package. For more information, see Development Utilities.

Ariba Supplier OnRamp Adapter provides a test facility that enables you to send cXML request messages to the Document Receiver receiveCXML, as if the messages were sent by Ariba SN. The Test Module is accessible from the Integration Server Administrator.

Ariba Supplier OnRamp Adapter processes a PunchOutSetupRequest message received by the supplier as follows:

• If logging is enabled, the document receiver service receiveCXML logs an entry indicating that the PunchOutSetupRequest was received. For a description of logging, see Using the Logging Facility.
• receiveCXML then checks the cXML request envelope and verifies that the message contains the correct Supplier Shared Secret. The shared secret is a password that the supplier configures on Ariba SN. All requests sent by Ariba SN to this supplier will contain the shared secret in the SharedSecret field in the requests' Sender credential. If you specify the shared secret in Ariba Supplier OnRamp Adapter, its default processing mechanism will check all incoming cXML requests for a matching shared secret. If the shared secret is checked and does not match, the document is not processed. In addition, Ariba Supplier OnRamp Adapter logs the failure.
• receiveCXML queries the Configuration Module if an event handler service is registered for the SetupRequestReceived event. If so, that service is invoked. For more information, see Listening to and Processing Punchout Process Events.
• receiveCXML obtains the operation type (create, inspect, or edit) of the PunchOutSetupRequest.
• receiveCXML searches for the developer-defined PunchOutSetupRequest handler for the particular operation type. receiveCXML queries the Configuration Module for the handler service name by calling wm.ariba.supplier.handlers:getHandler. For more information, see The PunchOutSetupRequest Handler.
• receiveCXML invokes the handler. If an error occurs when the handler is invoked, receiveCXML returns an ErrorResponse to the buyer's Ariba Buyer. Any errors that occur while the handler executes are returned in a serviceError record (assuming that you designed the handler with the appropriate specifications). In addition, if logging is enabled, a log entry is entered to indicate that an error occurred. Furthermore, if an event service is registered for the SetupRequestFailure event, that service is invoked.
• If the handler successfully processes the PunchOutSetupRequest, the handler should return a catalogURL that indicates where the Ariba Buyer should redirect the buyer. If the handler does not return a catalogURL, the receiveCXML service sends an ErrorResponse to the buyer's Ariba Buyer. In addition, if logging is enabled, a log entry is entered indicate an error occurred. Furthermore, if an event service is registered for the SetupRequestFailure event, that service is invoked.
• The supplier returns a PunchOutSetupResponse, which is a cXML message that is returned in an HTTP response to the buyer's Ariba Buyer.
• If logging is enabled, receiveCXML adds a log entry indicating that a PunchOutSetupResponse was sent.
• If an event service is registered for the SetupResponseSent event, receiveCXML calls the service.

Ariba Supplier OnRamp Adapter processes an OrderRequest message received by the supplier as follows:

• If logging is enabled, the document receiver service receiveCXML logs an entry indicating that the OrderRequest was received. For a description of logging, see Using the Logging Facility.
• The receiveCXML service queries the Configuration Module to determine if a developer-defined event handler service is registered for the OrderRequestReceived event. If so, that service is invoked. For more information, see Listening to and Processing Punchout Process Events.
• receiveCXML obtains the operation type (new, update, or delete) of the OrderRequest.
• receiveCXML searches for the developer-defined OrderRequest handler for the particular operation type. receiveCXML queries the Configuration Module for the handler service name by calling wm.ariba.supplier.handlers:getHandler. For more information, see The OrderRequest Handler.
• receiveCXML invokes the appropriate handler. If an error occurs when the handler is invoked, receiveCXML returns an ErrorResponse to the Ariba Buyer. Any errors that occur while the handler executes are returned in a serviceError record (assuming that you designed the handler with the appropriate specifications). In addition, if logging is enabled, a log entry is entered to indicate that an error occurred. Furthermore, if an event service is registered for the OrderRequestFailure event, that service is invoked.
• receiveCXML checks the serviceError record to see if an error occurred. If so, receiveCXML returns an ErrorResponse to the Ariba Buyer. In addition, if logging is enabled, a log entry is entered to indicate that an error occurred. Furthermore, if an event service is registered for the OrderRequestFailure event, that service is invoked.
• If an error did not occur, receiveCXML calls the service and returns an OrderResponse to the Ariba Buyer.
• If logging is enabled, receiveCXML adds a log entry indicating that an OrderResponse was sent.
• If an event service is registered for the OrderResponseSent event, receiveCXML calls the service.

A ProfileRequest is a buyer's query to a supplier for a list of cXML request transactions that the supplier is capable of processing. Ariba Supplier OnRamp Adapter processes a ProfileRequest message as follows:

• receiveCXML searches for the developer-defined ProfileRequest handler. receiveCXML queries the Configuration Module for the handler service name by calling wm.ariba.supplier.handlers:getHandler. For more information, see The ProfileRequest Handler.
• receiveCXML invokes the handler.

  If an error occurs when the handler is invoked, receiveCXML returns an ErrorResponse to the Ariba Buyer. Any errors that occur while the handler executes are returned in a serviceError record (assuming that you designed the handler with the appropriate specifications).

• If an error did not occur, receiveCXML extracts the handledRequests string array output parameter and returns a ProfileResponse to the Ariba Buyer, based on the result.

Master Agreements enable buyers to establish a commitment for goods and services with suppliers. They represent a common mechanism for managing supplier and budget commitments, and they enable buyers to negotiate better discounts by basing the discounts on future purchases, while enabling suppliers to more accurately forecast demand.

The MasterAgreementRequest document defines the Master Agreement created by the buying organization. It specifies beginning and end dates, and the committed maximum and minimum values of the agreement. It also lists maximum and minimum values and quantities for individual items. The MasterAgreementRequest document consists of MasterAgreementRequestHeader and AgreementItemOut. The MasterAgreement-RequestHeader contains the Master Agreement common to all contained items. The AgreementItemOut specifies the requirements of a particular line item that is part of the Master Agreement contract.

Ariba Supplier OnRamp Adapter provides sample services to create a MasterAgreement-Request test message and submit it to the configured URL. To test this transaction, see Using the Test Module.

Ariba Supplier OnRamp Adapter processes a MasterAgreementRequest message received by the supplier as follows:

• If logging is enabled, the document receiver service receiveCXML logs an entry indicating that the MasterAgreementRequest was received. For a description of logging, see Using the Logging Facility.
• The receiveCXML service queries the Configuration module to determine if a developer-defined event handler service is registered for the MasterAgreementRequestReceived event. If the handler service is registered, that service is invoked. For more information, see Listening to and Processing Punchout Process Events.
• The receiveCXML service obtains the operation type (new, update, or delete) of the MasterAgreementRequest.
• The receiveCXML service searches for the user-defined MasterAgreementRequest handler for the particular operation type. receiveCXML queries the Configuration Module for the handler service name by calling wm.ariba.supplier.handlers:getHandler service
• The receiveCXML service invokes the appropriate handler. If an error occurs when the handler is invoked, receiveCXML returns an ErrorResponse to the Ariba buyer. Any errors that occur while the handler executes are returned in a serviceError record (assuming that you designed the handler with the appropriate specifications). In addition, if logging is enabled, a log entry is entered to indicate that an error occurred. Furthermore, if an event service is registered for the MasterAgreementRequestFailure event, that service is invoked. receiveCXML checks the serviceError record to see if an error occurred and will return an ErrorResponse to the Ariba buyer.
• If an error did not occur, receiveCXML calls the service and returns a MasterAgreementResponse to the Ariba Buyer.
• If logging is enabled, receiveCXML adds a log entry indicating that a MasterAgreementResponse was sent.
• If an event service is registered for the MasterAgreementResponseSent event, receiveCXML calls the service.

The cXML InvoiceDetail transaction enables suppliers to send invoices to buying organizations or marketplaces. This transaction supports invoice details for a wide variety of business scenarios, including standard invoices, credit memos, debit memos, and receipts. Suppliers use cXML invoices to bill buying organizations or marketplaces for provided products or services.

The supplier sends a cXML document of type, InvoiceDetailRequest, to let the buyer know about the list of products that are being delivered against an order placed by the buyer. The document is routed to the buyer through Ariba SN. Ariba Supplier OnRamp Adapter allows the supplier to create InvoiceDetailRequest and posts it to the specified URL in Ariba SN to be routed to the buyer. The supplier can make use of Trading Networks to post the document to Ariba SN. Trading Networks can be used in the case of InvoiceDetail to make use of its logging and event mechanism. Ariba SN, after receiving the InvoiceDetailRequest, responds with a generic response indicating whether the request is genuine/authenticated.

Ariba Supplier OnRamp Adapter provides sample services to send a request of type InvoiceDetailRequest to the configured URL. The sample services are:

• wm.ariba.supplier.test:sendCXMLInvoiceDetailRequest. Sends the InvoiceDetailRequest document to the configured URL and writes logging information. This service should be used for transactions without Trading Networks.
• wm.ariba.supplier.test:sendCXMLInvoiceTN. Invoked from the processing rule created by Ariba Supplier OnRamp Adapter. Ariba Supplier OnRamp Adapter sends the InvoiceDetailRequest document to Trading Networks where the processing rule is executed. When the processing rule is executed, the InvoiceDetailRequest document is sent to the configured URL and the corresponding information is logged. This service should be used for transactions with Trading Networks. To test this transaction, see Using the Test Module.