An integration broker might need to retrieve a business object for which it has a set of attribute values without having the key attribute (or attributes) that uniquely identifies an application entity. Such a retrieve is called "retrieve by non-key values" or "retrieve by content." As an example, if a business object handler receives a Customer business object with the verb RetrieveByContent and with the non-key attributes Name and City set to Smith and San Diego, the RetrieveByContent operation can attempt to retrieve a customer entity that matches the values of the Name and City attributes.
When the business object handler obtains a RetrieveByContent verb from the request business object, it must ensure that an existing application entity, whose type is indicated by the business object definition, is retrieved, as follows:
This section provides the following information to help process a RetrieveByContent verb:
RetrieveByContent functions the same as the Retrieve verb except that it uses a subset of non-key values, instead of key values, to retrieve application data. In its most robust implementation, a top-level business object and its child business objects would independently support the RetrieveByContent verb. However, not all application APIs enable retrieve by non-key values for hierarchical business objects.
A more common implementation is to provide RetrieveByContent support only in the top-level business object. When a top-level business object supports retrieve by non-key values and this retrieve-by-content is successful, the RetrieveByContent operation can retrieve the keys for the entity matching the request business object. The verb operation can then perform a Retrieve operation to retrieve the complete business object.
You might want to specify which attributes are to be used in RetrieveByContent operations. To do this, you can implement attribute application-specific information to specify those attributes that will contain a value that is to be used in the RetrieveByContent operation or receive a value as a result of the operation.
The RetrieveByContent operation should return one of the outcome-status values shown in .