Error handling

shi…
ehm…
stuff happens

everyone

When communicating with such a complex system as MS Exchange, errors are bound to happen. Whether you did something wrong (which, to be honest, will be the most frequent source of grievance), something bungled the communication or MS introduced a new ‘feature’, You will need to handle errors.

Thus we have a 2-prong approach to error handling:

Item level error reporting

First and foremost, every ItemObject will contain as much error information on the last operation as we could gather:

This is the resulting object from a call to EWS_MoveFolder where an invalid DestinationFolderId has been passed, the error being that it was not passed in lowercase (aka your fault).

{
    "FolderId": "AAMkAGQzMzYyZjQzLTZmMzktNDc5MS04ZGQ3LTA1ZjgyNzAzZTg5MwAuAAAAAADmMJ/daf6PToBs1TzRFnPJAQAkNQEJKoHgSaTyc/uQcD3zAABYGEVkAAA=",
    "DestinationFolderId": "Inbox",
    "SOAP_Action": "MoveFolder",
    "SOAP_Envelope": "<?xml....Envelope>\r",
    "SOAP_Response": "HTTP/1.1....HTTP/1.1 500 Internal Server....Envelope>",
    "GetFolderResponse": "
    <?xml version="1.0" encoding="utf-8"?>
    <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
        <s:Body>
            <s:Fault>
                <faultcode xmlns:a="http://schemas.microsoft.com/exchange/services/2006/types">a:ErrorSchemaValidation</faultcode>
                <faultstring xml:lang="de-DE">The request failed schema validation: The 'Id' attribute is invalid - The value 'Inbox' is invalid according to its datatype 'http://schemas.microsoft.com/exchange/services/2006/types:DistinguishedFolderIdNameType' - The Enumeration constraint failed.</faultstring>
                <detail>
                    <e:ResponseCode xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">ErrorSchemaValidation</e:ResponseCode>
                    <e:Message xmlns:e="http://schemas.microsoft.com/exchange/services/2006/errors">The request failed schema validation.</e:Message>
                    <t:MessageXml xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
                        <t:LineNumber>11</t:LineNumber>
                        <t:LinePosition>34</t:LinePosition>
                        <t:Violation>The 'Id' attribute is invalid - The value 'Inbox' is invalid according to its datatype 'http://schemas.microsoft.com/exchange/services/2006/types:DistinguishedFolderIdNameType' - The Enumeration constraint failed.</t:Violation>
                    </t:MessageXml>
                </detail>
            </s:Fault>
        </s:Body>
    </s:Envelope>
    ",
    "XmlRef_Response": "04DFAD2005D33458",
    "ERROR": "True",
    "ERROR_Number": 73710101,
    "ERROR_Type": "Request Error",
    "ERROR_Method": "EWS__ErrorParse",
    "ERROR_Text": "soap response contains FAULT",
    "ERROR SOAP faultstring": "The request failed schema validation: The 'Id' attribute is invalid - 
    The value 'Inbox' is invalid according to its datatype 'http://schemas.microsoft.com/exchange/services/2006/types:DistinguishedFolderIdNameType' - 
    The Enumeration constraint failed.",
    "ERROR SOAP ResponseCode": "ErrorSchemaValidation",
    "ERROR SOAP Message": "The request failed schema validation.",
    "ERROR SOAP Line": "",
    "ERROR SOAP Position": ""
}

Please note, that the contained XML has been unfolded for easier reading

As you can see all relevant information is gathered in the object elements prefixed with ERROR.
You should find all information here you need to solve this problem, MS Exchange is usually quite verbose when flipping you off.

Other errors, like communication errors from cUrl will be more brief, in order to debug those you can switch on full communication logging, how to do this, please see the appropriate section in EWS_InitParameters.

Errors caught by the 4D-Exchange component will also be tracked here, a full description of these errors and how to fix can be found in the appropriate appendix.

Application wide error tracking

Well now, errors can happen in a row, and the ItemObject will only have data on the last error to occur.

In order to facilitate debugging, you can switch on global or local debugging with the appropriate parameters in EWS_InitParamaters. This will create a local (process) or global (application) collection that will fill up with objects that describe all errors for the appropriate scope.

Theses error objects contain all we can gather on a specific error and are always prepended to the collection, thus the latest error is always on top.

If you wish so, these errors can also be written to a log file, either consecutively appending to the file or as individual files for each error. Required settings are explained in the EWS_InitParameters chapter.