Driver->DriverLogQueueByGroupEx

XML Requests

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

  
<soap:Body>  
    <DriverLogQueueByGroupEx xmlns="http://www.qualcomm.com">  
        <request>  
            <DriverGroup>string</DriverGroup>  
            <Start>dateTime</Start>  
            <End>dateTime</End>  
            <LocalTime>boolean</LocalTime>  
            <LogId>int</LogId>  
            <TimeResolutionInSeconds>boolean</TimeResolutionInSeconds>  
        </request>  
    </DriverLogQueueByGroupEx>  
</soap:Body>  

The DriverGroup parameter is used to specify a driver group, as defined in the HOS Group Administration page. It is a logical ordering of drivers defined by the customer. Alternatively, the string '- All -' (dash, space, All, space, dash with no quotes) may be used to signify all drivers for a customer. This is a required parameter.

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 midnight Eastern Standard Time. When provided, the date and 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 LocalTime parameter is a boolean true/false statement. If the parameter equals false, then all times are GMT. If the parameter equals true, the depot local time is used.

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. LogId can never be a negative number.

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.

XML Responses

The XML returned by this function looks like the following:

  
<soap:Body>  
    <DriverLogQueueByGroupExResponse xmlns="http://www.qualcomm.com">  
        <DriverLogQueueByGroupExResult>  
            <DriverGroup>string</DriverGroup>  
            <RecordsReturned>int</RecordsReturned>  
            <Logs>  
                <DriverLogQueueDataEx>  
                    <DriverId>string</DriverId>  
                    <TractorId>string</TractorId>  
                    <Activity>Unknown or OffDuty or Sleeper or Driving or OnDuty or OffDutyDriving or PersoanlConveyance or YardMove</Activity>  
                    <WaitingInOilWell>boolean</WaitingInOilWell>  
                    <HazmatOnDutyRest>boolean</HazmatOnDutyRest>  
                    <StartTime>dateTime</StartTime>  
                    <Duration>int</Duration>  
                    <Edit>None or Original or Correction</Edit>  
                    <State>string</State>  
                    <Odometer>int</Odometer>  
                    <DistanceDriven>int</DistanceDriven>  
                    <CoDriverId>string</CoDriverId>  
                    <Location>string</Location>  
                    <Document>string</Document>  
                    <TrailerId>string</TrailerId>  
                    <Confirmed>boolean</Confirmed>  
                    <SensorFailure>boolean</SensorFailure>  
                    <TimeZone>string</TimeZone>  
                    <Remark1>string</Remark1>  
                    <Remark2>string</Remark2>  
                    <EditReason>string</EditReason>  
                    <OriginalLogId>int</OriginalLogId>  
                    <LogId>int</LogId>  
                </DriverLogQueueDataEx>  
                <DriverLogQueueDataEx>  
                    <DriverId>string</DriverId>  
                    <TractorId>string</TractorId>  
                    <Activity>Unknown or OffDuty or Sleeper or Driving or OnDuty or OffDutyDriving or PersonalConveyance or YardMove</Activity>  
                    <WaitingInOilWell>boolean</WaitingInOilWell>  
                    <HazmatOnDutyRest>boolean</HazmatOnDutyRest>  
                    <StartTime>dateTime</StartTime>  
                    <Duration>int</Duration>  
                    <Edit>None or Original or Correction</Edit>  
                    <State>string</State>  
                    <Odometer>int</Odometer>  
                    <DistanceDriven>int</DistanceDriven>  
                    <CoDriverId>string</CoDriverId>  
                    <Location>string</Location>  
                    <Document>string</Document>  
                    <TrailerId>string</TrailerId>  
                    <Confirmed>boolean</Confirmed>  
                    <SensorFailure>boolean</SensorFailure>  
                    <TimeZone>string</TimeZone>  
                    <Remark1>string</Remark1>  
                    <Remark2>string</Remark2>  
                    <EditReason>string</EditReason>  
                    <OriginalLogId>int</OriginalLogId>  
                    <LogId>int</LogId>  
                </DriverLogQueueDataEx>  
          . . .  
          . . .  
          . . .  
            </Logs>  
            <NextLogId>int</NextLogId>  
        </DriverLogQueueByGroupExResult>  
    </DriverLogQueueByGroupExResponse>  
</soap:Body>  

In the results, the following values are returned:

Depot: This is merely 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 DriverLogQueueDataEx. This structure is identical to the one used in the DriverLogQueueEx function.

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) . PersonalConveyance and YardMove are only returned when TimeResolutionInSeconds is True. Otherwise, the web service returns Off Duty and On Duty, respectively.

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)