Skip to main content
Omnitracs Knowledge Base

Driver->DriverLogQueue

DriverLogQueue (DriverFunction) 

Driver web service and is intended for real-time or historical accumulation of driver log data based on a specified depot. Parameters are provided for consumers to request log data over a period of time and are also available for requesting only new and changed data. The function is limited to returning 1,000 records per call, but the function can be called over and over again until no more data can be found. Note that a driver's current duty status can be returned through this call, but once the status has been ended and a new one begun, this record can be returned again with an updated duration and possibly an updated distance driven value.

XML Request

The function takes four possible parameters, none of which are mandatory parameters. The request XML looks like this:

  
<soap:Body>  
    <DriverLogQueue xmlns="http://www.qualcomm.com">  
        <request>  
            <Depot>int</Depot>  
            <Start>dateTime</Start>  
            <End>dateTime</End>  
            <LogId>int</LogId>  
            <TimeResolutionInSeconds>boolean</TimeResolutionInSeconds>  
        </request>  
    </DriverLogQueue>  
</soap:Body>  

The Depot parameter is used to specify the company's depot. This is a numerical field that can be found on the HOS Depot Administration page. By default, if the parameter is not provided, the function will assume a DepotId of 0. Every customer has a default depot set to that value.

The Start parameter is used to specify the starting date and time and is useful for the very first time this function is called. Afterwards, this parameter is not needed. On the initial call if the parameter is not provided, the function will default to the current day starting at the depot's Start of Day, which is typically midnight on the depot's time zone. When provided, the date ad time are assumed to be in GMT. SOAP date/time stamps are in the format: yyyy-mm-ddThh:mm:ss.

The End parameter is optional and can be useful when retrieving historical records. The main purpose of the function is for real time processing of current duty logs as they happen, but the function can also be used for retrieving past records. The End parameter, when provided, allows for a stopping point for the function, even if additional records are available. If this parameter is not provided, the function will continue returning records until the 1,000 maximum records limit is reached or no additional records are available to return. If duty logs are current, no additional records would be available. This parameter uses the same date/time format as the Start parameter and is also in GMT time.

The LogId parameter is the most important parameter for retrieving real time information. The first call to this function is used to set a starting point, so a Start parameter is useful for setting that time frame. If the call has additional records to return beyond the 1,000 maximum, a LogId value is provided called NextLogId that can be used here in this parameter for the next call, giving the web service function a reference point for what additional records to return. For the first call, set LogId to 0 telling the function to use the Start point for retrieving records. On subsequent calls, a non-zero value in LogId will override any Start parameter. Note that if no additional records are to be found, the LogId entered as an input parameter is returned in NextLogId. The customer can continue to call this web service function on a periodic basis using that same NextLogId until additional data is available.

The TimeResolutionInSeconds parameter specifies whether certain values in the response are returned in seconds or minutes. If true, values are returned in seconds; otherwise in minutes. This parameter is optional. If the parameter is omitted, then values in the response are returned in minutes. See the response description for the effected fields.

The Odometer value in in 10ths of a mile. If not available, this value will be -1.

 

XML Response

The XML returned by this function looks like the following:

  
<soap:Body>  
    <DriverLogQueueResponse xmlns="http://www.qualcomm.com">  
        <DriverLogQueueResult>  
            <Depot>int</Depot>  
            <RecordsReturned>int</RecordsReturned>  
            <Logs>  
                <DriverLogQueueData>  
                    <DriverId>string</DriverId>  
                    <TractorId>string</TractorId>  
                    <Activity>Unknown or OffDuty or Sleeper or Driving or OnDuty or OffDutyDriving or PersonalConveyance or YardMove</Activity>  
                    <StartTime>dateTime</StartTime>  
                    <Duration>int</Duration>  
                    <Edit>None or Original or Correction</Edit>  
                    <State>string</State>  
                    <Odometer>int</Odometer>  
                    <DistanceDriven>int</DistanceDriven>  
                </DriverLogQueueData>  
                <DriverLogQueueData>  
                    <DriverId>string</DriverId>  
                    <TractorId>string</TractorId>  
                    <Activity>Unknown or OffDuty or Sleeper or Driving or OnDuty or OffDutyDriving or PersonalConveyance or YardMove</Activity>  
                    <StartTime>dateTime</StartTime>  
                    <Duration>int</Duration>  
                    <Edit>None or Original or Correction</Edit>  
                    <State>string</State>  
                    <Odometer>int</Odometer>  
                    <DistanceDriven>int</DistanceDriven>  
                </DriverLogQueueData>  
            </Logs>  
            <NextLogId>int</NextLogId>  
        </DriverLogQueueResult>  
    </DriverLogQueueResponse>  
</soap:Body>  

In the results, the following values are returned:
Depot: This is the same value as the input parameter.

RecordsReturned: This is a number reflecting the total count of records returned in the call. This number cannot exceed 1,000.

Logs: This is a structure that repeats once for each driver log record returned. The data structure returned for each log entry is called DriverLogQueueData.

NextLogId: This value is useful for the next iterative call to this function. It is used by the web service function to know where the last call left off and where the next record can be found. The value itself is not meaningful beyond the web service call. If no records are left to be returned, a LogId representing the next future log entry is returned here. Or, if no data is returned at all, the same input LogId will be returned in NextLogId for use with the next call. That same value can be used in the next call. A zero or negative value will never be returned.

Activity: Duty status (Unknown, OffDuty, Sleeper, Driving, OnDuty, OffDutyDriving, PersonalConveyance, YardMove) . PC and YM are returned only if TimeResolutionInSeconds is True.

StartTime: Starting time of duty record, in UTC time zone (if TimeResolutionInSeconds is false or omitted in the request, then StartTime will be truncated to the minute)

Duration: Amount of time this duty lasted (if TimeResolutionInSeconds is true in the request, then returned in seconds; otherwise minutes)

Odometer: Value is in 10ths of a mile.

Distance: How far the tractor was driven, in tenths of miles, during the duty status.

  • Was this article helpful?