WebSphere Commerce services error information

When an exception occurs during the processing of a message, the OAGIS convention is to return a well-formed response message, with the error data embedded. The ChangeStatus element is used to store exception data; if the request was completed successfully, this area is not populated. Because only one action per message is supported, there can be only one error per message. For this reason the limitation of one ChangeStatus area per message is reasonable.

Within the response criteria, the ResponseExpression indicates the actionCode of the request and the ChangeStatus element contains exception information if the request fails. The following is a mapping of exception and the ChangeStatus.

Code

Always ERROR to indicate this is an error response to the action expression

Description

Locale-specific exception detail text

EffectiveDateTime

Time when processing failed

ReasonCode

A unique key that represents the error. It typically corresponds to the message key of a WebSphere Commerce exception that uniquely identifies the problem. However, there are cases where the message key is not sufficient to uniquely identify the error and there is an error code which further classifies the error. For these cases, the reason code is the message key + error code to uniquely identify the error.

Reason

Additional information that can be used to understand the conditions that caused the error. There can be multiple reasons and typically corresponds to the message parameters used to populate the message detail text, where the ordering of the reason correspond with the ordering of message parameters.

The following example shows a Respond error message:

<?xml version="1.0" encoding="UTF-8"?>
<_mbr:AcknowledgePerson releaseID="9.0"
	xmlns:_mbr="http://www.ibm.com/xmlns/prod/commerce/9/member"
	xmlns:_wcf="http://www.ibm.com/xmlns/prod/commerce/9/foundation"
	xmlns:oa="http://www.openapplications.org/oagis/9" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<oa:ApplicationArea xsi:type="_wcf:ApplicationAreaType">
		<oa:CreationDateTime>2009-07-20T15:28:12.968Z
		</oa:CreationDateTime>
		<oa:BODID>efcd3260-7541-11de-a99e-83c74a648a93
		</oa:BODID>
	</oa:ApplicationArea>
	<_mbr:DataArea>
		<oa:Acknowledge>
			<oa:OriginalApplicationArea>
				<oa:CreationDateTime>2009-07-20Z</oa:CreationDateTime>
				<oa:BODID>ef9188f0-7541-11de-a590-83c74a648cf4
				</oa:BODID>
			</oa:OriginalApplicationArea>
			<oa:ResponseCriteria>
				<oa:ChangeStatus>
					<oa:Code>ERROR</oa:Code>
					<oa:Description>The Logon ID user123 already exists. Specify a
						different Logon ID and try again.</oa:Description>
					<oa:ReasonCode>_ERR_LOGONID_ALREDY_EXIST+2030
					</oa:ReasonCode>
					<oa:Reason>user123</oa:Reason>
				</oa:ChangeStatus>
			</oa:ResponseCriteria>
		</oa:Acknowledge>
	</_mbr:DataArea>
</_mbr:AcknowledgePerson>

The ChangeStatus area is used only for error reporting. If this area is not present in the BOD, then you know that processing has been completed successfully.

If the request fails with an error, the Noun in the DataArea should be not be present (null). The rationale is that a defined noun might have required fields, and the exception handling code might not have sufficient information to populate these fields properly. It therefore makes more sense to pass back the response with an empty Noun.

The error handling that is part of the foundation of processing business object documents will take care of populating the change status of the response.

Related concepts
Message mappers
Service Data Objects (SDO)
Design pattern for Get service implementation (SOI)
Design patterns

Related tasks
Creating the component facade

Related reference
Client library exceptions