Driver->GetViolationEvents
GetViolationEvents (Driver Function)
GetViolationEvents is intended to be a real-time (pseudo) notification of drivers going into violation. Historic, after the fact, analysis of the data returned from this web service may not always show the driver in violation. There are numerous reasons for this and they are enumerated on The following page. So the ultimate check for historical violations (e.g. once significant time has passed or for previous days) is to use the DriverViolations Web Service method. This one re-calculates historical violations taking into account any log edits, or late messages that may have arrived once a driver is back in coverage.
This function returns the warning and violation events for all the drivers for a company. Each invocation returns a maximum of 1000 events and if there are more events the <NextEventId> tag in the result set will have the Id to be passed in with the next invocation. For the first invocation of this web service set the <EventId> to 0 and provide a valid <StartTime>. All the events happened on/after that time is returned. For subsequent invocations provide the <NextEventId> as the <EventId> and the <StartTime> is ignored.
Note that this method returns ONLY the most negative clock for each driver when returning warnings and violations. The GetViolationEvents is meant to be a near real-time notification of drivers going into violation - hence we only care about the most negative clock. It is not intended to give a full picture of all clocks.
Also: Omnitracs does not recommend calling DriverViolations for all drivers in the fleet individually. Use the GetViolationEvents to give the list of drivers that have at least one violation on a given day. Then use this driver list to call DriverViolations.
XML Request
The GetViolationEvents takes two parameters
| Parameter | Type | Description |
|---|---|---|
| EventId | Long | Id of the next event from where the events need to be fetched. For first call, set EventId to 0, telling the function to use the StartTime for retrieving events. |
| StartTime | DateTime | Start time (in UTC) of the first event to be returned in the list. Only required for first call, if not provided it will default back to 24 hours from now. |
XML Response
The GetViolationEvents returns the following values
| Parameter | Type | Description |
|---|---|---|
| DriverId | string | The driver's ID |
| DepotId | string | The ID of the depot for the driver. |
| EventType | Int | Values representing the following THIRTY_MINUTE_WARNING(1), SIXTY_MINUTE_WARNING(2), VIOLATION(3) |
| Clock | Int | The clock that cause the event to be generated, values are Driving(1), OnDuty(2), CumulativeOnDuty(3), Shift(4), DayOff(5), RestBreak(6), WorkLeft(7) |
| EventTime | TimeDate | The time that the driver crossed the threshold causing the event. The time is truncated to the minute. |
| CalculationTime | TimeDate | The time that QHOS calculated that the driver crossed the threshold. Due to way that QHOS calculates, this could be up to 29 minutes after the threshold was crossed. The time is truncated to the minute. |
| MinutesLeftToDrive | Int | The number of minutes that the driver can driver as of the CalculationTime before going into violation |
| NextEventId | Long | The EventId that the caller should pass to this call to get events following the last event in this result set |