Deprecated feature

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 ({}). We must always specify the access profile. See WebSphere Commerce extended XPath notation.

{_wcf.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
maxItems	The maximum number of items to return.
recordSetStartNumber	The starting index from which to retrieve results from the result set.
recordSetReferenceId	If this is a follow-up to an existing query, pass in the reference ID so that the result set can be retrieved from cache.

Show Attribute	Meaning
recordSetStartNumber	The starting index for the results that are being returned in this message.
recordSetCount	The number of records from the result set that are being returned in this message.
recordSetTotal	The total number of results in the result set.
recordSetCompleteIndicator	Indicates whether you have reached the end of the result set.
recordSetReferenceId	The internal identifier for the result set, so that it can be resolved on a subsequent request.

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="_wcf:XPath">
   
{_wcf.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. The data service layer and SOI components do not support paging on sub nouns. However, there are nouns within nouns, known as sub nouns, that also need to be paginated (for example, OrderItem, within the Order noun) in the Order component.

Related concepts
Change Request / Respond Response
WebSphere Commerce use of Open Applications Group (OAGIS) messaging
Verbs
Process request and the acknowledge response
Sync request and the ConfirmBOD response