API Objects

When writing InSight Alert Scripts, you typically start with the Context object (of type ApiContext) to get the information you need to determine if an Alert condition is met. The following tables describe all of the objects that you can use in your scripts. Note that all properties are read-only.

Note that you also have access to the global variables and methods.

ApiContext

The ApiContext object provides information about the Unit or Driver that is the target of the alert. It is the top level object for accessing information from the message that you are checking to see if your condition has been met. It has the following properties:

Property

Type

Description

Example

Time

DateTime

The time when the message about a unit or driver was generated (localized to the user's time zone)

Weekend Use

UserTimeZone

string

The time zone of the user - this is the time zone that the Time property is expressed in.

 

TimeUtc

DateTime

The time when the message was generated in UTC.

Idle Time Thresholds

Unit

ApiUnit

The vehicle (unit) that this alert concerns (when Target Type of the alert is Unit).

Custom Radius

Driver

ApiDriver

The driver who this alert concerns (when Target Type of the alert is Driver).

Last Job

MessageIsCurrent

bool

True when the message is actually a report from the unit or false when the message is an automatically generated message (for example, when the This script does not require message from vehicles check box is selected).

 

HasPayload

bool

True if the message has a JSON payload attached.

 

PayloadName

string

The specified JSON payload name, or an empty string if there is no payload attached.

 

Payload

object

The specified JSON payload as a JsObject, or an empty JsObject if there is no payload attached.

 

Job

ApiJob

The job this alert relates to (when the TargetType of the alert is Job).

 

The ApiContext object has the following methods:

Method

Parameters

Return type

Description

Example

UtcTimeToUserTime

DateTime time

DateTime

Returns the UTC DateTime time value so that it is expressed using the time zone of the user.

 

LatLon

double lat, double lon

LatLon

Returns a new LatLon object from the provided latitude and longitude coordinates.

 

ApiUnit

The ApiUnit object describes a vehicle and the unit installed in that vehicle. It has the following properties:

Property

Type

Description

Example

Id

integer

A unique identifier for the vehicle (unit).

 

Name

string

The name of the vehicle as it appears in the user interface.

 

IsAtCustomer

bool

True if the vehicle is currently at a marker in the Customer category, false otherwise.

 

IsAtHq

bool

True if the vehicle is currently at a marker in the HQ category, false otherwise.

 

IsAtProhibited

bool

True if the vehicle is currently at a marker in the Prohibited category, false otherwise.

 

HasCurrentMarker

bool

True if the vehicle is at a known marker, false otherwise.

Return in half an hour

CurrentMarker

ApiMarker

When HasCurrentMarker is true, this returns the marker where the vehicle is located.

Return in half an hour

HasCurrentDriver

bool

True if the vehicle has an assigned driver, false otherwise.

 

CurrentDriver

ApiDriver

When HasCurrentDriver is true, this returns the assigned driver.

 

HasCurrentStreetAddress

bool

True if the street address for the vehicle is known, false otherwise.

Idle Time Thresholds

CurrentStreetAddress

ApiStreetAddress

The street address where the vehicle is located, if known.

Idle Time Thresholds

Ignition

bool

True if the vehicle's ignition is on, false otherwise.

 

HasIgnition

bool

True if the unit has an input that senses if the ignition is on, false otherwise.

 

SerialNumber

string

The serial number that identifies the unit installed in the vehicle.

 

Tags

string[]

A collection of tags assigned to the vehicle.

Tags

HasOdometer

bool

True if the reports from the vehicle provide odometer information (either through running odometer values in status reports or using an odometer diagnostic input).

 

OdometerMeters

double

When HasOdometer is true, this returns the current odometer reading (or estimate thereof), in meters.

 

HasEngineHours

bool

True if the reports from the vehicle provide information about engine hours (either through status reports or using a diagnostic input).

 

EngineHours

double

When HasEngineHours is true, this returns the number of hours the engine has been running.

 

EngineOn

bool

When HasEngineOn is true, this returns if the vehicle's engine is currently on.

 

HasDiagnostics

bool

True if the unit reports the values of diagnostic inputs, false otherwise.

 

HasLocation

bool

True if the unit has reported its current location.

 

Location

LatLon

When HasLocation is true, this returns the current latitude and longitude of the vehicle's location.

 

HasSpeed

bool

True if the unit has reported its speed.

Speeding with weather

SpeedKph

int

When HasSpeed is true, this returns the vehicle's speed in kilometers per hour.

Speeding with weather

HasHeading

bool

True if the unit has reported its current heading (direction of travel).

 

Heading

int

When HasHeading is true, this is the direction of travel, in degrees clockwise from north (where north is 0).

 

VIN

string

The VIN of the vehicle.

 

Registration

string

The registration number of the vehicle.

 

Model

string

The model of the vehicle

 

Year

string

The year of the vehicle.

 

Status

int

The current status of the vehicle, one of the following values:
 

0 - Stopped.

1 - Idle.

2 - Moving.

3 - Working.

Idle Time Thresholds

NeedsService

bool

True if the vehicle is currently due for scheduled maintenance, false otherwise.

 

ExternalId

string

A foreign key value that uniquely identifies the vehicle for this customer account.

 

Color

string

The color of the vehicle.

 

EngineSerialNumber

string

The engine serial number on the vehicle.

 

Type

string

The type of unit installed in the vehicle, one of the following values:
 

0 - vCore unit, model G3

1 - vCore unit, model TC

2 - vCore unit, model TG

3 - Quanta unit

4 - Magneti unit

5 - GenX unit

6 - Pointer unit

7 - Web-based unit

 

VehicleTimeZone

string

The time zone that the unit is in.

 

LastKnownLocation

LatLon

The last known location of the unit.

 

CustomField

object

Returns the custom fields set on the Unit via Verizon Connect Data Exchange (anything inside the "custom" property on ot2.unit) as a JsObject, or an empty JsObject if no custom fields have been set.

Unit.CustomFields.Location

GpsQuality

string

When HasLocation is true, GpsQuality returns one of the following values, corresponding to the GPS quality of the unit message:

 

Off

NoFix

Unreliable

Excellent

 
When HasLocation is false, NoGps is returned.

 

The ApiUnit object has the following methods:

Method

Parameters

Return type

Description

Example

IsAtMarkerInCategory

ApiCategory category

bool

Returns true if the vehicle is currently within the boundaries of a marker in the category passed in as a parameter.

Weekend Use

HasDiagnosticValue

int tid

bool

Returns true if the vehicle has a diagnostic input that reports values for the type of information specified by the parameter. The parameter is a TID (a device-independent code that uniquely identifies a diagnostic parameter type)

Checking Diagnostics

GetDiagnosticValue

int tid

double

Returns the current value of a diagnostic input for which HasDiagnosticValue returns true.

Checking Diagnostics

HasDtc

int tid

string code

bool

Returns true if the given DTC code is present for the specified TID (a device-independent code that uniquely identifies a diagnostic parameter type)

 

HasAnyDtc

int tid

bool

Returns true if there are any DTC codes present for the specified TID (a device-independent code that uniquely identifies a diagnostic parameter type)

Checking DTCs

GetAllDtcCodes

int tid

string

Returns a comma-separated string of DTC codes that are present for the specified  TID(a device-independent code that uniquely identifies a diagnostic parameter type).

Checking DTCs

GmtToUnitTime

DateTime time

DateTime

Returns the specified DateTime value so that it is expressed using the time zone of the unit.

 

ApiDriver

The ApiDriver object describes a driver and provides access to information associated with the driver such as the route the driver is currently servicing. It has the following properties:

Property

Type

Description

Example

Id

integer

A unique identifier for the driver.

 

Name

string

The nickname of the driver as it appears in the user interface.

 

UserName

string

For drivers who are also users of the account, this is the login name that the driver uses for authentication.

 

Tags

string[]

A collection of tags assigned to the driver.

Tags

Unit

ApiUnit

The vehicle to which the driver is currently assigned (if any).

Tags

BaseMarker

ApiMarker

The marker where the driver is based.

 

CurrentRoute

ApiRoute

The route that the driver is currently servicing. This property is only used if the account has Verizon Connect® Response™.

Last Job

RouteCategory

ApiCategory

The category of marker associated with the routes this driver services.

 

ExternalId

string

A foreign key value that uniquely identifies the driver for this customer account.

 

FirstName

string

The driver's given name.

 

MiddleName

string

The driver's middle name.

 

LastName

string

The driver's family name.

 

Address1

string

The first line of the driver's home address.

 

Address2

string

The second line of the driver's home address.

 

Address3

string

The third line of the driver's home address.

 

City

string

The city where the driver lives.

 

PostCode

string

The zip code or postal code of the driver's home address.

 

Country

string

The country where the driver lives.

 

PhoneNumber1

string

The driver's primary phone number.

 

PhoneNumber2

string

The driver's secondary phone number.

 

MobileNumber

string

The driver's mobile phone number.

 

EmailAddress

string

The driver's email address

 

SSN

string

The driver's social security number.

 

EmployeeNumber

string

The driver's employee number.

 

HireDate

DateTime

The date when the driver was hired.

 

LeaveDate

DateTime

The date when the driver's contract ends.

 

JobTitle

string

The driver's job title.

 

SupervisorId

string

The ID of the driver's supervisor.

 

LicenseNumber

string

The driver's license number.

 

LicenseClass

string

The class of the driver's license.

License class

LicenseExpires

DateTime

The expiration date of the driver's license.

 

BirthDate

DateTime

The date of the driver's birth.

 

Height

string

The driver's height

 

EyeColor

string

The color of the driver's eyes.

 

Gender

string

The driver's gender.

 

Restriction

string

Any restrictions placed on the driver.

 

InsuranceExpires

DateTime

The date when the driver's insurance coverage expires.

 

InsuranceCarrier

string

The carrier for the driver's insurance policy.

 

InsuranceNumber

string

The number of the driver's insurance policy.

 

Notes

string

Free-form notes about the driver.

 

PinNumber

string

The 6-digit PIN that identifies the driver to Verizon Connect® WorkPlan™.

 

CustomFields

object

Returns the custom fields set on the Driver via TDE Data Exchange (anything inside the "custom" property on ot2.unit) as a JsObject, or an empty JsObject if no custom fields have been set.

Driver.CustomFields.Location

ApiMarker

The ApiMarker object describes one of your markers (locations). It has the following properties:

Property

Type

Description

Example

Id

integer

A unique identifier for the marker.

Return in half an hour

Name

string

The name of the marker as it appears in the user interface.

 

RadiusFeet

int

The radius of the marker, in feet (circle markers only).

 

IsGlobal

bool

True if the marker is visible to all users with permission to see public markers, false if it is private.

 

IsDepotRelated

bool

True if the marker acts as a depot, false otherwise.

 

IsZone

bool

True if the marker is a zone marker, false otherwise. Zone markers can have speed limits, and vehicle locations in zone markers are reported as the actual location, rather than as the marker location.

 

SpeedLimitKnots

double

When IsZone is true, the speed limit for vehicles within the boundaries of the marker (if any).

 

StreetAddress

ApiStreetAddress

The address of the marker.

 

AssignedDriver

ApiDriver

The driver associated with this marker (for example, the driver with a job assigned at this marker).

 

PrimaryCategory

ApiCategory

The primary category of the marker.

 

CustomFields

object

Returns the custom fields set on the Driver via TDE Data Exchange (anything inside the "custom" property on ot2.unit) as a JsObject, or an empty JsObject if no custom fields have been set.

Marker.CustomFields.Location

The ApiMarker object has the following methods:

Method

Parameters

Return type

Description

Example

ContainsLatLon

LatLon latlon

bool

Returns true if the specified location is within the boundaries of the marker, false otherwise.

 

ContainsLatLonCustomRadius

LatLon latlon

int customRadius

bool

Returns true if the specified location is within the specified radius (measured in feet) of the center of the marker.

Custom Radius

DistanceTo

LatLon latlon

int distanceUnit

double

Returns the distance from the specified location to the marker, expressed in the specified distance units. DistanceUnit is one of the following values:
 

1 - Feet

2 - Yards

4 - Miles

8 - Meters

16 - Kilometers

32 - Nautical Miles

64 - Radians

128 - Degrees

256 - Centimeters

512 - Inches

 

 

DistanceToInRadians

LatLon latlon

double

Returns the distance, in radians, from the specified location to the marker. This is the same as calling DistanceTo(latlon, 64).

 

ApiRoute

The ApiRoute object describes a route (sequence of jobs) that has been assigned to a driver. This object is only used if the account has Verizon Connect® Response™. It has the following properties:

Property

Type

Description

Example

Id

string

A unique ID for the route.

 

Name

string

The name of the route.

 

StartTime

DateTime

The date and time when the route is scheduled to start (when the driver should leave the depot).

 

EndTime

DateTime

The date and time when the route is scheduled to end.

 

Territory

string

The name of the territory to which the route belongs.

 

Unit

ApiUnit

The vehicle that is assigned to the driver of this route.

 

Driver

ApiDriver

The driver who is assigned to this route.

 

StartDepot

ApiJob

The depot where the route starts.

 

FirstJob

ApiJob

The first job scheduled on the route.

 

CurrentJob

ApiJob

The first incomplete job in this route.

 

LastJob

ApiJob

The last job scheduled on the route.

Last Job

EndDepot

ApiJob

The depot where the route ends.

 

Jobs

IList<ApiJob>

A list of all the jobs on this route, in order.

 

Status

integer

The status of this route. Possible values are:
 

0 - Not Started.

1 - In Progress.

2 - Complete.

3 - Not Complete.

 

ApiJob

The ApiJob object describes a scheduled stop in a route. This object is only used if the account has Verizon Connect® Response™. It has the following properties:

Property

Type

Description

Example

Id

string

A unique identifier for the job

 

Tag

string

The name of the job

 

Status

ApiJobStatus

A status object giving information about the job based on the known behavior of the driver and vehicle.

Last Job

ExpectedArrivalTime

DateTime

The time when the driver is scheduled to arrive at the job site.

 

ExpectedDepartureTime

DateTime

The time when the driver is scheduled to leave the job site.

 

ExpectedTravelDistance

double

The distance, in radians, that the driver is scheduled to drive from the previous job to this job.

 

EarliestArrival

TimeSpan

The amount of time before the ExpectedArrivalTime that the driver can still arrive at the job.

 

LatestArrival

TimeSpan

The amount of time after the ExpectedArrivalTime that the driver can still arrive at the job.

 

TimeToExpiry

TimeSpan

The amount of time remaining before this job expires.

 

Description

string

A brief description of the job.

 

Notes

string

Notes that have been appended to the job.

 

Priority

integer

The priority of this job. Possible values are:
 

10 - Lowest

-5 - Below Normal

0 - Normal

5 - Above Normal

10 - Highest

 

ApiJobStatus

The ApiJobStatus object describes information about a job that is based on known behavior of a vehicle and driver. This object is only used if the account has Verizon Connect® Response™. It  has the following properties:

Property

Type

Description

Example

ActualArrivalTime

DateTime

The date and time when the vehicle actually arrived at the job site (if known).

 

ActualDepartureTime

DateTime

The date and time when the vehicle actually left after completing the job (if known).

 

ActualTravelDistance

double

The distance, in radians, that the vehicle covered traveling from the previous job to this job (if known).

 

Status

integer

The status of the job. Possible values are:
 

0 - Assigned - the job has been assigned to the driver but the route has not begun.

2 - EnRoute - the driver is currently driving from the previous job to this one.

3 - OnSite - the driver has arrived at the job site and has not yet left.

4 - Completed - the driver has completed the job and left for another job or to end the route.

7 - Unassigned - the job is not assigned to any driver.

Last Job

StatusFlag

integer

Additional status information, concerning possible problems. Possible values are:
 

0 - Ok - There are no problems detected about the job.

1 - OffRoute - the vehicle is not following the expected route to this job.

2 - Late - the vehicle has not arrived at the job by the scheduled time.

3 - WrongOrder - the driver has stopped at a job later in the route before arriving at this one.

4 - OverlapAdjusted - the job's monitor has made adjustments for time on site because of another job scheduled at roughly the same location.

5 - IdledAtJob - the vehicle idled while at the job site rather than turning off the engine.

 

IsCurrent

bool

True if this is the first incomplete job in its route, false otherwise.

Last Job

IsFinished

bool

True if the vehicle has departed the job site after completing this job, false otherwise.

 

IsOnSite

bool

True if the vehicle has arrived at this job site but not yet left.

 

ApiCategory

The ApiCategory object describes the category of a marker. It has the following properties:

Property

Type

Description

Example

IsAll

bool

True if this ApiCategory represents all markers, false otherwise.

 

IsGlobal

bool

True if this category is visible to all users who can see public categories, false if it is private.

 

IsShared

bool

True if this category is shared with multiple users, false otherwise.

 

IsReadOnly

bool

True if this category cannot be edited, false otherwise.

 

Count

int

The number of markers in this category.

 

CategoryType

int

The type of category. The following categories are defined:
 

0 - none

1 - all

2 - HQ

3 - Customer

4 - Prohibited

100 - Showups

101 - Substations

102 - Private

 

The ApiCategory object has the following methods:

Method

Parameters

Return type

Description

Example

GetMember

int id

ApiMarker

Returns the marker in this category with the specified id.

 

IsMember

int id

bool

Returns true if the marker with the specified id is a member of this category.

 

IsMember

ApiMarker member

bool

Returns the if the specified marker is a member of this category.

 

GetEnumerator

 

Enumerator

Lists the markers in this category.

 

ApiFleet

The ApiFleet object describes a fleet (collection of vehicles). It has the following properties:

Property

Type

Description

Example

IsAll

bool

True if this ApiFleet represents all vehicles, false otherwise.

 

IsGlobal

bool

True if this fleet is visible to all users who can see public fleets, false if it is private.

 

IsShared

bool

True if this fleet is shared with multiple users, false otherwise.

 

IsReadOnly

bool

True if this fleet cannot be edited, false otherwise.

 

IsInHierarchy

bool

True if this fleet is implicitly defined by the hierarchy, false otherwise.

 

Count

int

The number of vehicles in this fleet.

 

The ApiFleet object has the following methods:

Method

Parameters

Return type

Description

Example

GetMember

int id

ApiUnit

Returns the vehicle in this fleet with the specified id.

 

IsMember

int id

bool

Returns true if the vehicle with the specified id is a member of this fleet.

 

IsMember

ApiUnit member

bool

Returns true if the specified vehicle is a member of this fleet.

License class

GetEnumerator

 

Enumerator

Lists the vehicles in this fleet.

 

ApiTeam

The ApiTeam object describes a team (collection of drivers). It has the following properties:

Property

Type

Description

Example

IsAll

bool

True if this ApiTeam represents all drivers, false otherwise.

 

IsGlobal

bool

True if this team is visible to all users who can see public teams, false if it is private.

 

IsShared

bool

True if this team is shared with multiple users, false otherwise.

 

IsReadOnly

bool

True if this team cannot be edited, false otherwise.

 

IsInHierarchy

bool

True if this team is implicitly defined by the hierarchy, false otherwise.

 

Count

int

The number of drivers in this team.

 

The ApiTeam object has the following methods:

Method

Parameters

Return Type

Description

Example

GetMember

int id

ApiDriver

Returns the driver in this team with the specified id.

 

IsMember

int id

bool

Returns true if the driver with the specified id is a member of this team.

 

IsMember

ApiDriver member

bool

Returns true if the specified driver is a member of this team.

 

GetEnumerator

 

Enumerator

Lists the drivers in this team.

 

ApiStreetAddress

The ApiStreetAddress object provides information about a location, such as its address and speed limit. It has the following properties:

Property

Type

Description

Example

Country

string

The country where the address is located.

 

PostCode

string

The zip code or postal code of the address.

 

Region

string

The state, province, or region of the address.

Idle Time Thresholds

County

string

The county of the address.

 

City

string

The city of the address.

 

Building

string

The name of the building, if any.

 

Name

string

The name part of the street.

 

Number

string

The number on the street (for example, 22B or 413 apt 2).

 

SpeedLimit

int

The speed limit at the location, in either miles per hour or kilometers per hour (the returned unit determined by the default speed units of the user account). This is the posted speed limit, if known. Otherwise, if the location is within the boundaries of a zone marker that has a speed limit, this is the speed limit of the zone marker.

Speeding with weather

LatLon

The LatLon object gives the latitude and longitude of a location. It has the following properties:

Property

Type

Description

Latitude

double

The latitude of the location, in degrees.

Longitude

double

The longitude of the location, in degrees.