Get Request and the Show Response

Get requests are requests for data, and use the Get verb, and return a Show response. The Get verb will indicate the search criteria used to retrieve the business objects along with paging options for paged requests. The Show response will include the business objects that match the search criteria .

 

Search expressions for Get service request

Following the OAGIS model for read requests, the best practice is for every read request to be represented as a Get Noun document where Get is the action to perform and the Noun is the business object or objects to return. As a response to the Get request, the Show document will be returned with the requested data.

The search expressions will be XPath expressions which represent a query against the respective noun to indicate the data to be returned. As part of the extension to the XPath syntax, there is a way to pass control information to indicate the amount of data to return, ordering and other search result control information.

Read requests will use XPath expressions to define the response data to be returned.

 

Access profile

An access profile can be used to scope the response data. For example, to return a specific view of the data (for example a search view of a catalog entry), or to return the data in all languages for authoring purposes. As an extension to the XPath syntax, the access profile name-value pair should be prepended to the XPath expression in curly brackets ({}). You must always specify the access profile. See WebSphere Commerce extended XPath notation for more information.

{ibmwcf.ap=$accessProfile$}/CatalogGroup[Name='MyCatalogGroupName']

 

Result paging

There are cases when the results need to be paged so the service request will only return a subset of the data that matches the criteria. To control the amount of records to return, the GET verb has paging attributes which will be used to indicate the number of records to return and where to start from on the list of information to return. The maxItems attribute is used to indicate the number of data elements returned from the query and recordSetStartNumber is the starting index of the record set to start returning information.

For search expressions where the number of returned results does not equal the number of possible results of the query, the responding Show message will populate the recordSetReferenceId attribute. This attribute can be used by the client as a key to uniquely identify the query in order to avoid performing the entire search again. The recordSetReferenceId is a unique key associated with the search that will only be valid for a timeout period which is dependent on the component facade implementation. The service consumer can use this identifier as an indicator to the component facade implementation that it should retrieve cached results instead of re-running the expression just to return a different page of the same results.

Get Attribute	Meaning
Show Attribute	Meaning
recordSetReferenceId	If this is a follow-up to an existing query, pass in the reference ID so that the resultset can be retrieved from cache.
recordSetStartNumber	The starting index from which to retrieve results from the resultset.
maxItems	The maximum number of items to return.
recordSetReferenceId	The internal identifier for the resultset, so that it can be resolved on a subsequent request.
recordSetCompleteIndicator	Indicates whether or not you have reached the end of the result set.
recordSetTotal	The total number of results in the resultset.
recordSetCount	The number of records from the resultset that are being returned in this message.
recordSetStartNumber	The starting index for the results that are being returned in this message.

Below is an example of the Show verb response and the next Get verb to retrieve the next 10 elements of the query. As a result of the Show response, the recordSetReferenceId is populated along with the number of records the query returned and the number of records included within the current response message. The preceding GET request can use the recordSetReferenceId to retrieve the next page of records to avoid the server to re-execute the query.

<oa:Get maxItems="10" recordSetStartNumber="10"
  recordSetReferenceId="ABCD-1234-WXYZ">
  <oa:Expression expressionLanguage="wc:XPath">
   
{ibmwcf.ap=$accessProfile$}/CatalogGroup[Name='MyCatalogGroupName]
  </oa:Expression>
</oa:Get>

<oa:Show
  recordSetCompleteIndicator="true"
recordSetReferenceId="ABCD-1234-WXYZ"
  recordSetTotal="101" recordSetCount="10"
recordSetStartNumber="10">

Pagination for complex nouns

OAGIS only supports pagination at the noun level. However, there are nouns within nouns, known as sub nouns, that also need to be paginated (for example, OrderItem, within the Order noun). In order to paginate at the sub noun level, the recommendation is to add the sub noun at the end of the XPath for the request to indicate pagination at the sub noun level. The following example shows a search of the OrderItems in all Pending orders:

/Order[OrderStatus[(Status='P')]]/OrderItem

When paging on the sub noun, you cannot page on the noun. IBM recommends that the Show response will only return one noun when paging on the sub noun.

Related concepts

WebSphere Commerce use of Open Applications Group (OAGIS) messaging

Verbs

Process request and the acknowledge response

Change Request / Respond Response

Sync request and the ConfirmBOD response