On This Page:

Related Pages:

The sp:EmpChangeTravelStatus2Request API method can be used to update the travel status of an operative.

Description

An operative can have a travel status with values:

`Moving`	The vehicle has its engine running and is in a different location between move events.
`Stationary`	The vehicle has its engine running but it isn’t moving, i.e. it’s at the same location for two or more events.
`Stopped`	The vehicle’s engine isn’t running, and it’s location isn’t changing. Additional information in the form of a location type - the type of location that the vehicle is stopped near (e.g. a parts depot) - may also be available.
Cancelled	Returns Job Cancelled status
`Unknown`	The vehicle was expected to send a new event because the sample time has elapsed since the previous move (or stationary) event but one hasn’t been received. (This could be because the vehicle is ‘out of range’.)

The travel status is set by calling the sp:EmpChangeTravelStatus2Request API method.

When the travel status is Stopped, additional information in the form of a location type - the type of location that the vehicle is stopped near (GeoFenceLocType) - can be supplied:

By default, ServiceGPS is configured to send one of the following two character strings for the location type (GeoFenceLocType), but they are configurable:

“HO” Home

“VD” Vehicle Depot

“PL” Parts Location

“TO” Team Office

“CO” Company Office

“CS” Customer Site

“NG” No Go

A location name can also be supplied if one has been defined in ServiceGPS for the location (geofence).

This can used for different purposes, depending the value of the type. Where the location type (GeoFenceLocType, above) is Parts Location, for example, the location name could be the name of the building where the parts are located, e.g. “Stockport Depot”.

#define SP_LatitudeMin -90.0 /* 90°S */

#define SP_LatitudeMax +90.0 /* 90°N */

#define SP_LongitudeMin -180.0 /* 180°W */

#define SP_LongitudeMax +180.0 /* 180°E */

Definition

The definition of this API is:

Click here to expand...

Web Service			Type	Description	Req?	Val?
`<sp:EmpChangeTravelStatus2Request>`
	`<empID>?</empID>`		`EmpID`	The operative’s ID	Yes	Yes
	`<newTravelStatus>?</newTravelStatus>`
	`<timeStamp>?</timeStamp>`
	`<latitude>?</latitude>`			Latitude (see 2.5) of the current position of the operative
	`<longitude>?</longitude>`			Longitude (see 2.5) of the current position of the operative
	`<address>`
		`<address1>?</address1>`
		`<address2>?</address2>`
		`<address3>?</address3>`
		`<address4>?</address4>`
		`<country>?</country>`
		`<postcode>?</postcode>`	`Postcode`			Yes
	`</address>`
	`<geoFence>`
		`<type>?</type>`
		`<name>?</name>`
	`</geoFence>`
	`<disStatus>?</disStatus>`		`DisStatus`	An optional parameter that represents the dispatch status associated with the operative when the travel change request is made.	No	Yes
`</sp:EmpChangeTravelStatus2Request>`

The Timestamp field is the timestamp from the GPS device in the vehicle itself and can be operative-local or UTC, according to the setting of EmpChangeTravelStatus: Time Zone Type (tz_opts ).

Return Structure

The API returns the standard return structure.

Return Codes

In addition to the Standard Return Codes, the possible Return Codes from this API are:

Click here to expand...

SP_OK (0)
SP_EMPID_INVALID (5)
SP_STATUS_NO_CHANGE (86)
SP_EMPID_NOT_SUPPLIED (215)
SP_DATETIME_INVALID (538)
SP_EMP_TRAVEL_STATUS_INVALID (568)
SP_OK_EMP_TRAVEL_STATUS_OFF (569)
SP_LATITUDE_INVALID (608)
SP_LONGITUDE_INVALID (609)
SP_LOCADD1_INVALID (610)
SP_LOCADD2_INVALID (611)
SP_LOCADD3_INVALID (612)
SP_LOCADD4_INVALID (613)
SP_LOCPOSTCODE_INVALID (614)
SP_COUNTRY_INVALID (615)
SP_GEOFENCELOCTYPE_INVALID (616)
SP_GEOFENCELOCTYPE_NOT_SUPPLIED (617)
SP_GEOFENCELOCNAME_INVALID (618)
SP_GEOFENCE_DOES_NOT_EXIST (619)
SP_DATETIME_NOT_SUPPLIED (620)

Browser not supported