Response document structure

Search response

After a search request, the XML result set that travels through the pipeline in the application layer has a structure that matches that of the business object executing the request. Each subset is represented as a child element to its parent and the attributes of the subset are represented as attributes in the XML document. A typical response document is formatted like this:

<?xml version="1.0" encoding="UTF-8"?>
<idealXML version="2.0">
	<header message="200"/>
	<commands>
		<command message="200" id="UniqueID">
			<response>
				<status>
					<message code="200">OK</message>
				</status>
				<resultset>
					<entity name="Product">
						<attribute name="ProductID">268ATX</attribute>
						.
						.
						.
						<subset name="Category">
							<attribute name="CategoryID">11</attribute>
							<attribute name="CategoryInternalName">Cabinets</attribute>
						</subset>
						<subset name="Price">
							<attribute name="CurrencyID">EUR</attribute>
							<attribute name="Price">25.0000</attribute>
							<attribute name="PriceGroupID">list</attribute>
							<attribute name="PriceGroupName">list</attribute>
							<attribute name="PriceID">19</attribute>
						</subset>
						.
						.
						.
					</entity>
				</resultset>
			</response>
		</command>
	</commands>
</idealXML>

The <command> element will include an id attribute if one was specified in the request document. This enables the recipient to match the response to the original request.

Update, delete, insert, and commit response

Update, delete, insert and commit requests produce a response similar to search requests. However, the response documents to these types of commands are somewhat simpler. As with a search response, the result set includes one or more <entity> elements, each of which specifies the name of a business object affected by the request. Within this element is an <attribute> element, which identifies the key-field value of the specific record affected. There will exist an <entity> element for each successful operation. Unlike a search response, no other attributes are returned and subsets are not reported; if a subset was affected, the response still reports only the main set key value.

<?xml version="1.0" encoding="UTF-8"?> 
<idealXML version="2.0" id="UniqueID1"> 
	<header status="200"/> 
	<commands> 
		<command status="200" id="UniqueID2"> 
			<response> 
				<status> 
					<message code="200">OK</message> 
				</status> 
				<resultset> 
					<entity name="Product"> 
						<attribute name="ProductID">2PAR</attribute>
					</entity> 
					<entity name="Product"> 
						<attribute name="ProductID">3FLEX</ttribute>
					</entity>
					.
					.
					.
				</resultset> 
			</response> 
		</command> 
	</commands> 
</idealXML>

If the request was handled correctly, but none of the requested changes were made, then the response may indicate a successful request (code=200) but will include no <entity> tags. In other cases, only some of the requested changes may have been implemented, thereby resulting in fewer <entity> tags than expected. To identify this type of error, the response must be compared to the request document. By supplying a unique id attribute for the <command> or <idealXML> elements in the request, the sending system can pair requests to their response and make the appropriate comparison.

Status and message elements

The <status> element returns information about the overall status of the request; it contains no attributes.

Nested with in the <status> element will be a <message> element, which has a single attribute called code. The code attribute will be set to one of the values listed in the tables under Gateway error messages. The value of the <message> element will be a short message that matches the specified code.