Page History

...

All DateTime values are in UTC / GMT - both consumed and provided by the service (see XSD Date Time)
Many common types are re-used throughout all services to enable developers to apply both DRY, and to a greater extent, SOLID principals:
1. DriverBase - provides only enough detail required to identify a specific Driver or Operator
2. TruckPCBase - provides only enough detail required to identify a specific Device or ELD
3. Position - provides enough detail to pinpoint a location
4. FormMessage - provides detail of the content for a particular instance of a Macro or Form

Detailed Exception Reporting is provided via Soap Faults. VENDORS MUST, at a minimum, recognize catch and handle ClientFaults vs ServerFaults appropriately:

Server Faults - Should be retried after a limited number of escalating periods of time

Expand

title	Click here to expand Server Fault Example...

Code Block

language	xml
title	Server Fault Example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
   <soap:Fault>
    <faultcode>soap:Server</faultcode>
    <faultstring>Server Unable to Handle Request. SupportCode:d08bdaad-179c-4194-bd7b-6f5fd669ab93</faultstring>
    <faultactor>http://fwapi.drivertech.com/Data/2_1/DataService.asmx</faultactor>
    <detail>
     <fault>
      <Errors xmlns="http://fwapi.DriverTech.com/CommonTypes/2009/04">
       <Error ErrorCategoryId="100" ErrorCodeId="100">
        <ErrorCode>Server</ErrorCode>
        <ErrorCategory>Server</ErrorCategory>
        <ErrorDescription/>
       </Error>
      </Errors>
     </fault>
    </detail>
   </soap:Fault>
  </soap:Body>
</soap:Envelope>

Client Faults - Shall not be retried as any additional attempt will invoke the same failed response UNLESS/UNTIL some external action is taken

Expand

title	Click here to expand Client Fault Examples...

Code Block

language	xml
title	Client Fault - Schema Validation

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
   <soap:Fault>
    <faultcode>soap:Client</faultcode>
    <faultstring>XmlSchemaValidationException: The 'http://fwapi.DriverTech.com/CommonTypes/2009/04:CompanyCode' element is invalid - The value '?' is invalid according to its datatype 'String' - The actual length is less than the MinLength value.</faultstring>
    <faultactor>http://fwapi.drivertech.com/Data/2_1/DataService.asmx</faultactor>
    <detail>
     <fault>
      <Errors xmlns="http://fwapi.DriverTech.com/CommonTypes/2009/04">
       <Error ErrorCategoryId="1000" ErrorCodeId="1109">
        <ErrorCode>XmlSchemaValidationFailed</ErrorCode>
        <ErrorCategory>Client</ErrorCategory>
        <ErrorDescription/>
       </Error>
      </Errors>
     </fault>
    </detail>
   </soap:Fault>
  </soap:Body>
</soap:Envelope>

Code Block

language	xml
title	Client Fault - Incomplete Request

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
   <soap:Header>
      <ResponseHeader xmlns="http://fwapi.DriverTech.com/CommonTypes/2009/04">
         <DriverTechAPIVersion>2.1.40.27252</DriverTechAPIVersion>
         <RequestId>11111</RequestId>
         <ExecutionMilliseconds>0</ExecutionMilliseconds>
      </ResponseHeader>
   </soap:Header>
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Client</faultcode>
         <faultstring>Client: Must provide at least 1 OutboundMessageRequest Item SupportCode:12403e07-83f2-4e85-9fe5-9dc2b2c18aa2</faultstring>
         <faultactor>http://fwapi.drivertech.com/Data/2_1/DataService.asmx</faultactor>
         <detail>
            <fault>
               <Errors xmlns="http://fwapi.DriverTech.com/CommonTypes/2009/04">
                  <Error ErrorCategoryId="1000" ErrorCodeId="1000">
                     <ErrorCode>Client</ErrorCode>
                     <ErrorCategory>Client</ErrorCategory>
                     <ErrorDescription>Must provide at least 1 OutboundMessageRequest Item</ErrorDescription>
                  </Error>
               </Errors>
            </fault>
         </detail>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

Fault Detail

Expand

title	Click here to expand Fault Enumerations...

Code Block

language	c#
title	Enumeration of ErrorCategory and ErrorCode

    /// <summary>
    /// Parent Category of an ErrorCode
    /// </summary>
    [Serializable]
    [XmlType(TypeName = "ErrorCategory", AnonymousType = true)]
    public enum DTErrorCategory
    {
        /// <summary> 
        /// Generic Server Error
        /// </summary>
        [EnumTextValue(@"Generic Server Error")]
        Server = 100,
        /// <summary> 
        /// Generic Client Error
        /// </summary>
        [EnumTextValue(@"Generic Client Error")]
        Client = 1000,
        /// <summary> 
        /// Client schema error
        /// </summary>
        [EnumTextValue(@"Client schema error")]
        InvalidSchema = 1050,
        /// <summary> 
        /// Client versioning error
        /// </summary>
        [EnumTextValue(@"Client versioning error")]
        VersionMismatch = 1051,
        /// <summary> 
        /// Error authenticating to access webservices
        /// </summary>
        [EnumTextValue(@"Error authenticating to access webservices")]
        Authentication = 1500,
        /// <summary> 
        /// Invalid data found in Request
        /// </summary>
        [EnumTextValue(@"Invalid data found in Request")]
        InvalidRequestData = 2000,
    }
    /// <summary>
    /// Specific code of an encountered Error.
    /// </summary>
    [Serializable]
    [XmlType(TypeName = "ErrorCode", AnonymousType = true)]
    public enum DTErrorCode
    {
        /// <summary> 
        /// Default Error Code
        /// </summary>
        [EnumTextValue(@"Default Error Code")]
        Unavailable = 1,
        /// <summary> 
        /// Generic Server Error
        /// </summary>
        [EnumTextValue(@"Generic Server Error")]
        Server = 100,
        /// <summary> 
        /// Generic Client Error
        /// </summary>
        [EnumTextValue(@"Generic Client Error")]
        Client = 1000,
        /// <summary> 
        /// Sql Injection Attempt
        /// </summary>
        [EnumTextValue(@"Sql Injection Attempt")]
        SqlInjectionAttempt = 1106,
        /// <summary> 
        /// Invalid Character Provided
        /// </summary>
        [EnumTextValue(@"Invalid Character")]
        InvalidCharacter = 1107,
        /// <summary> 
        /// Invalid XML Provided
        /// </summary>
        [EnumTextValue(@"Invalid XML")]
        InvalidXML = 1108,
        /// <summary> 
        /// XmlSchemaException
        /// </summary>
        [EnumTextValue(@"XML Schmea Validation Failed")]
        XMLSchemaValidationFailed = 1109,
        /// <summary> 
        /// Invalid data type in client request
        /// </summary>
        [EnumTextValue(@"Invalid data type in client request")]
        InvalidDataType = 1110,
        /// <summary> 
        /// Invalid value in SOAP message body
        /// </summary>
        [EnumTextValue(@"Invalid value in SOAP message body")]
        InvalidValue = 1111,
        /// <summary> 
        /// Invalid element in SOAP message body
        /// </summary>
        [EnumTextValue(@"Invalid element in SOAP message body")]
        InvalidElement = 1112,
        /// <summary> 
        /// Invaild characters in client request 
        /// </summary>
        [EnumTextValue(@"Invalid characters in client request ")]
        ProhibitedCharacters = 1115,
        /// <summary> 
        /// Error authenticating client request
        /// </summary>
        [EnumTextValue(@"Error authenticating client request")]
        AuthenticationFailed = 1500,
        /// <summary> 
        /// Error decrypting client request
        /// </summary>
        [EnumTextValue(@"Error decrypting client request")]
        AuthenticationEncryptionInvalid = 1505,
        /// <summary> 
        /// Not authorized to complete client request
        /// </summary>
        [EnumTextValue(@"Not authorized to complete client request")]
        AuthorizationDenied = 1551,
        /// <summary> 
        /// Invalid customerName in client request
        /// </summary>
        [EnumTextValue(@"Invalid customerName in client request")]
        InvalidCustomerName = 2000,
        /// <summary> 
        /// Invalid customerID in client request
        /// </summary>
        [EnumTextValue(@"Invalid customerID in client request")]
        InvalidCustomerID = 2001,
        /// <summary> 
        /// Invalid DriverID in client request
        /// </summary>
        [EnumTextValue(@"Invalid DriverID in client request")]
        InvalidDriverID = 2010,
        /// <summary> 
        /// Invalid DriverName in client request
        /// </summary>
        [EnumTextValue(@"Invalid DriverLogon in client request")]
        InvalidDriverLogon = 2011,
        /// <summary> 
        /// Invalid DriverName in client request
        /// </summary>
        [EnumTextValue(@"Invalid Driver EmployeeID in client request")]
        InvalidEmployeeId = 2012,
        /// <summary> 
        /// Invalid TruckID in client request 
        /// </summary>
        [EnumTextValue(@"Invalid TruckID in client request ")]
        InvalidTruckPCID = 2020,
        /// <summary> 
        /// Invalid Truck in client request
        /// </summary>
        [EnumTextValue(@"Invalid Truck in client request")]
        InvalidTruckName = 2021,
        /// <summary> 
        /// Invalid Truck in client request
        /// </summary>
        [EnumTextValue(@"Invalid TruckPCSerialNr in client request")]
        InvalidTruckPCSerialNr = 2022,
        /// <summary> 
        /// File data not provided in client request to send file
        /// </summary>
        [EnumTextValue(@"File data not provided in client request to send file")]
        FileDataNotProvided = 2550,
        /// <summary> 
        /// File data invalid in client request to send file
        /// </summary>
        [EnumTextValue(@"File data invalid in client request to send file")]
        FileDataInvalid = 2551,
        /// <summary> 
        /// No file name provided in client request to send file
        /// </summary>
        [EnumTextValue(@"No file name provided in client request to send file")]
        FileNameNotProvided = 2552,
        /// <summary> 
        /// No file mime type provided in client request to send file
        /// </summary>
        [EnumTextValue(@"No file mime type provided in client request to send file")]
        FileMimeTypeNotProvided = 2553,
        /// <summary> 
        /// No recipient list provided in client request
        /// </summary>
        [EnumTextValue(@"No recipient list provided in client request")]
        RecipientsNotProvided = 3000,
        /// <summary> 
        /// Cannot send to recipient driver in client request
        /// </summary>
        [EnumTextValue(@"Cannot send to recipient driver in client request")]
        RecipientDriversNotAllowed = 3001,
        /// <summary> 
        /// Cannot send to recipient truck in client request
        /// </summary>
        [EnumTextValue(@"Cannot send to recipient truck in client request")]
        RecipientTrucksNotAllowed = 3002,
        /// <summary> 
        /// Invalid file id 
        /// </summary>
        [EnumTextValue(@"Invalid file id ")]
        FileIDInvalid = 3500,
        /// <summary>
        /// Invalid Date range
        /// </summary>
        [EnumTextValue(@"Invalid date range ")]
        InvalidDateRange = 4000,
        /// <summary>
        /// Arguement null or missing
        /// </summary>
        [EnumTextValue(@"Argument null or missing")]
        ArgumentNullOrMissing = 1011,
        /// <summary>
        /// Invalid form id in client request
        /// </summary>
        [EnumTextValue(@"Invalid form id in client request")]
        InvalidFormId = 4500,
        /// <summary>
        /// Invalid form field specified
        /// </summary>
        [EnumTextValue(@"Invalid form field specified")]
        InvalidFormField = 4501,
        /// <summary>
        /// Invalid form definition number in client request
        /// </summary>
        [EnumTextValue(@"Invalid form definition number specified")]
        InvalidFormDefinitionNumber = 4502,
        /// <summary>
        /// Invalid form definition
        /// </summary>
        [EnumTextValue(@"Invalid form definition")]
        InvalidFormDefinition = 4503,
    }

...

Versions Compared

Old Version 85

New Version 86

Key