Development Utilities

Using the Error Utility

The wm.b2b.cxml.utils.errors folder of the WmAribaSupplier package provides a set of APIs for reporting errors in Ariba Supplier OnRamp Adapter. The core of this package relies on a serviceError structure in the pipeline to detect and process errors. When developing services, make sure that you return a serviceError structure containing an error message if you want to report errors to the Ariba Supplier OnRamp Adapter core.

To create a serviceError record, invoke wm.b2b.cxml.utils.errors:setError with the following arguments:

  • error. The error message.
  • errorStatusCode. Optional. This argument corresponds to the numeric status code in the cXML ErrorResponse returned to Ariba Supplier Network. If not specified, the ErrorResponse statusCode is set to 500. Otherwise, the value you specify here is used. For a description of ErrorResponse status codes, see the cXML User's Guide Version 1.2.

Using the Persistence Utility

If your shopping cart system cannot store the buyer session metadata that is needed for the punchout ordering process, you can save the buyer session data by passing the data 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.

Storing Data in the webMethods Server Session Object

If you need to store the shopping cart data, you can use the services in the wm.b2b.cxml.utils.persistence folder of the WmAribaSupplier package. The wm.b2b.cxml.utils.persistence.session folder uses the session object of Integration Server to store the session data persistently in Integration Server.

Storing Data in External Data Stores

About this task

To store the buyer session metadata persistently in an external data store, you must implement services to create, read, and delete the buyer session metadata into the external persistent store. These services should implement the service specifications of saveBuyerSessionDataSpec, getBuyerSessionDataSpec, and removeBuyerSessionDataSpec described in wm.b2b.cxml.utils.persistence.spec.

Note: The services in wm.b2b.cxml.utils.persistence.memory folder implement a memory-based store for buyer session data. These services usable since Ariba Supplier OnRamp Adapter 1.0 are now deprecated and may be removed. They should not be used because they will not scale to a clustered server environment. The services are provided in this release to preserve backward compatibility; use of these services is not recommended for new implementations.

To store metadata in the Integration Server session object

Procedure

  1. Map the relevant buyer session metadata fields to the record object wm.b2b.cxml.utils.persistence:BuyerSession.
  2. Invoke the service wm.b2b.cxml.utils.persistence.session:saveBuyerSessionData with the following input arguments:
    Field Name Value
    buyerSessionID Leave this field blank if you are storing the buyer data for the first time. If buyerSessionID is blank, this service will store the buyer data in the session object and return to you the session object's ID in the buyerSessionID output field.

    If you have already stored the buyer data in a session object using this service, you may update the buyer data in that session object by calling this service with buyerSessionID set to the ID of that session object.

    Typically, you would embed the buyerSessionID returned by this service in the catalogURL or as a hidden field in web page forms. When the buyer is finished shopping, the shopping cart system retrieves the buyer data by calling the retrieveBuyerSessionData service with this ID.

    BuyerSession A record of the form wm.b2b.cxml.utils.persistence:BuyerSession. Contains the punchout buyer session data.

    This service stores the BuyerSession record in a session object in a record called sessionData. (The BuyerSession record exists in the session object as sessionData/BuyerSession.)

    newSessionTimeoutMS Optional. If you are storing the buyer data for the first time, you can specify how long (in milliseconds) the session object should be maintained before it is de-allocated.
  3. To retrieve the buyer session metadata, invoke the service wm.b2b.cxml.utils.persistence.memory:getBuyerSessionData. Set the buyerSessionID input parameter to the ID of the session object you want to retrieve.
  4. To remove the buyer metadata from the session object, invoke the service wm.b2b.cxml.utils.persistence.memory:removeBuyerSessionData. This service will remove the BuyerSession record from the session object.
    Note: Make sure you remove buyer session metadata when the session is no longer used (that is, after the session expires or the order request has be fulfilled).

Using the Attachment Utility

Ariba SN is capable of sending cXML OrderRequest and attachment documents in a MIME/Multipart message. Ariba Supplier OnRamp Adapter is capable of receiving MIME/Multipart messages containing OrderRequests and attachments. It extracts the attachments and for each attachment and creates an attachmentWrapper data object to represent the attachment.

Each attachmentWrapper contains metadata describing the attachment document and the contents of the attachments in bytes.

The set of attachments are collected in an attachmentWrapperCollection object which allows you to:

  • Loop through the set of attachmentWrappers.
  • Retrieve an attachmentWrapper by index.
  • Retrieve an attachmentWrapper by the attachment's unique identifier. Each attachment sent by Ariba SN has a unique ID and is set in the cXML OrderRequest. They are located in the element cXML/Request/OrderRequest/OrderRequestHeader/Comment.

Working with the attachmentWrapperCollection Object

The attachmentWrapperCollection object will appear in your OrderRequest handler service pipeline. You use the services in the pub.ariba.supplier.attachment.collection folder to manipulate the attachmentWrapperCollection. For a detailed description of these services, see pub.ariba.supplier.attachment.collection.

To Get the Number of Attachments in the Collection

Use the service pub.ariba.supplier.attachment.collection:getCollectionSize.

To Get a Specific attachmentWrapper from the Collection

If you want to retrieve the attachmentWrapper at a particular index, set the index input field to the index of the item you want to retrieve (the first attachmentWrapper is at index=0).

To Retrieve the attachmentWrapper from the Collection by ID

You can also retrieve the attachmentWrapper by ID. Each attachment has a unique identifier. All attachments sent by Ariba SN have a unique ID and are set in the cXML OrderRequest. They are located in the element cXML/Request/OrderRequest/OrderRequestHeader/Comments/Attachment/URL as the string "cid: < unique attachment id >".

Use the service pub.ariba.supplier.attachment:getIDFromComment to extract the attachment ID from the Comments/Attachment record entry corresponding to the attachment you are interested in.

Invoke pub.ariba.supplier.attachment.collection:getWrapperFromCollection with the id field set to the extracted value.

To Loop Through the attachmentWrapperCollection

You can either loop through all the attachmentWrappers in a collection in either of the following ways:

  • Use the pub.ariba.supplier.attachment.collection:getWrapperList service.

    This service will return a list of attachmentWrapper objects. You can use the flow loop construct to loop through each element. This service is resource intensive. It should only be used for small number of attachments.

    Set the sortOrder input parameter to forward to sort the list of attachmentWrappers first to last, or set it to backward to sort them last to first.

  • Use the attachmentWrapperCollectionIteratorservice to iterate through the attachmentWrapper elements.

    Using the iterator is much more efficient than using the getWrapperList. To use the collection iterator, invoke the service pub.ariba.supplier.attachment.collection.iterator:getIterator to get an iterator object for the collection.

    Set the direction input parameter to forward to iterate through the list of attachmentWrappers first to last, or set it to reverse to sort them last to first.

    Once you have the collectionIterator object, use the getIterator and iteratorHasMoreWrappers services in a repeat flow statement as follows. 

    INVOKE pub.ariba.supplier.attachment.collection.iterator:getIterator  
REPEAT (repeat-on SUCCESS)  
INVOKE 
pub.ariba.supplier.attachment.collection.iterator:iteratorHasMoreWrappers  
BRANCH on hasMoreWrappers  
SEQUENCE true  
INVOKE 
pub.ariba.supplier.attachment.collection.iterator:getNextWrapperFromIterator  
<do something with the attachment wrapper>  
SEQUENCE false  
EXIT $loop

Working with the attachmentWrapper Object

Once you have an attachmentWrapper, you can get the attachment's metadata as described in the record pub.ariba.supplier.attachment:AttachmentInfo, or you can get the attachment's contents in bytes.

  • To get the attachment metadata information, invoke the service pub.ariba.supplier.attachment:getInfoFromWrapper.
  • To get the attachment's contents, invoke the service pub.ariba.supplier.attachment:getContentFromWrapper.

Set the format input parameter to bytes if you want the contents in bytes, or set it to string if you want the contents in string format.