Results Description Document Schema

This schema is used to return results from operations which perform a single transactional update or a set of transactional updates on one or more topic maps. For operations invoked over SOAP, the results description document will be returned in the body of the SOAP response message. For operations invoked against ASP.NET pages directly, the result document will be contained in the body of the HTTP response.

The structure of the results document is as follows.

<res:results containsError="true|false">
  <res:result ... > 
    ...
  </res:result>
</res:results>
res:results/@containsError

A boolean flag that is set to true if at least one of the transactions failed, and true if and only if every transaction succeeded. This attribute is REQUIRED.

res:results/res:result

Contains the detailed result information for a single transaction. The syntax of this element is as described below.

Each res:result element reports the status of a single transaction performed during the request processing. The optional key attribute on this element allows the result description to be correlated to one of the transactions in the request. Each res:result element has has the following structure:

<res:result isError="true|false">
  <res:error code="CODE" key="KEY"> 
    <res:message> ERROR MESSAGE </res:message>
    <res:action role="ROLE"> ACTION MESSAGE </res:action>
    <res:cause>
      <res:message> EXCEPTION MESSAGE </res:message>
      <res:type> EXCEPTION TYPE </res:type>
      <res:stacktrace> EXCEPTION STACK </res:stacktrace>
    </res:cause>
    ...
  </res:error>
  ...
</res:result>
res:result/@key

Contains a string value that can be used to correlate the result report to part of the operation request. The precise way in which this is achieved is operation-specific and described in the operation definition. This attribute is OPTIONAL, and may be omitted if the result is for a single transaction.

res:result/@isError

Contains a boolean flag that is set to true if the operation is reporting an error. This attribute is OPTIONAL and defaults to false.

res:result/res:error

Wrapper element for reporting detail on an error that occurred in the processing of the operation. This element is OPTIONAL. It SHOULD be present if the isError attribute of the parent res:result element is set to true, it SHOULD NOT be present if the isError attribute of the parent res:result element is set to false.

res:result/res:error/@code

Contains the error code for the error being reported. Error codes are service-specific and defined as part of the service description. The error code is specified in this attribute as a string value. This attribute is REQUIRED.

res:result/res:error/res:message

Contains an error message for the error being reported. This element is OPTIONAL.

res:result/res:error/res:action

The text contained in this element describes the action(s) that can be taken to resolve the reported error.

res:result/res:error/res:action/@role

This attribute identifies which user role can perform the corrective action described in the content of the element. This attribute has two allowed value. If the value is 'user', then the action can be performed by the user who issued the request. If the value is 'admin' then the corrective action requires administrative intervention on the server.

res:result/res:error/res:cause

This OPTIONAL element describes the underlying exception that caused the process to fail. This element provides additional detail which can be helpful in determining the cause of certain errors.

res:result/res:error/res:message

Contains the message reported by the exception that caused the process to fail.

res:result/res:error/res:type

Specifies the type of exception that caused the process to fail.

res:result/res:error/res:stacktrace

Contains the stack trace of the exception that caused the process to fail.

res:result/res:error/{##other}

Any number of elements from any other namespace may appear after the res:message element. This may be used by services to convey additional detailed error information (such as a stack trace or debug output) to the caller.

res:result/{##other}

Any number of elements from any other namespace may appear as the last children of the res:result element. This may be used by services to convey additional detailed response information (such as performance statistics). This extension point SHOULD NOT be used to convey detailed error information - instead the extension point inside the res:error element should be used.