Planning and Scheduling

The Planning and Scheduling API is a RESTful web service that enables Fleetmatics customers to integrate 3rd party back-office systems with REVEAL to create and manage work orders to review the vehicle’s GPS data alongside the locations that their drivers are expected to visit.

Important concepts to understand prior to utilizing any of the available integration methods:

·        Planning and Scheduling API is offered as a RESTful web service

·        Standard REST verbs are applied: GET, POST, PUT, DELETE

·        The Planning and Scheduling API is broken into two main components: methods available to manage work orders and methods available to manage navigation

·        Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created or deleted.  The unique identifiers used within this API method set include:

o   Work Order Number

o   Driver Number

o   Vehicle Number

o   Work Order Status Code

o   Work Order Type Code

o   Stop ID

Navigation Methods

GET Methods

·        GET Stops by Vehicle Number

GET Stops by Vehicle Number

The integrated user will be able to use this GET method to retrieve a list of stops previously sent to a vehicle’s Garmin navigational device.

A valid Vehicle Number will need to be provided to invoke this method.  If the user provides a Vehicle Number for a vehicle that does not have a Garmin device an ERROR will be returned.

All stops on the vehicle’s Garmin navigational device that are active will be returned.  The following information related to the vehicle’s stops will be returned when invoking this method:

·        Address Line 1

·        Address Line 2

·        Administrative Area – state, province, etc.

·        Country

·        Description

·        Device Index – this value will help to review the full list of stops sent to a vehicle’s Garmin navigational device in order to see the order of the stops

·        Device Stop ID

·        Is High Priority

·        Has Been Completed – Boolean

·        Latitude

·        Longitude

·        Locality – city, town, etc.

·        Postal Code

·        Stops List

·        Vehicle Number

POST Methods

·        POST Stops

·        POST Stops Order

·        POST Stop for Work Order

POST Stops

The integrated user will be able to use this POST method to send stops to a vehicle’s Garmin navigational device in order to help the driver prioritize and navigate to the stops that he/she will make throughout the day.

The following information will be available to send a stop to a vehicle:

·        Address Line 1

·        Address Line 2

·        Administrative Area – state, province, etc.

·        Country

·        Description – optional

·        Latitude

·        Longitude

·        Locality – city, town, etc.

·        Is High Priority – when set to “TRUE” this stop will become critical and will take precedence over any other stop in the vehicle’s stop queue.  This value will default to “FALSE.”

·        Postal Code

If both address fields and latitude/longitude values are provided within the request, the work order will use the latitude/longitude coordinates to designate the location.  If neither the address nor coordinates are provided an ERROR will be returned to the integrated user.

POST Stops Order

The integrated user will be able to use this POST method to re-order stops previously sent to a vehicle’s Garmin navigational device.

The integrated user will need to provide a valid Vehicle Number.

The method request will provide the Ordered Device Stop Id List for the user to place the Stop IDs into the proper order as they should appear on the vehicle’s corresponding Garmin navigational device.

POST Stop for Work Order

The integrated user utilizing both work orders management integration alongside the Garmin navigation integration will be able to convert existing work orders into stops to be managed by the Garmin navigational device within the driver’s vehicle.

Work Orders must already exist within REVEAL with a valid Work Order Number in order to be sent as a stop to a driver’s vehicle.  If the Work Order Number does not exist within REVEAL an ERROR will be returned.

Work Orders with coordinates/locations that cannot be resolved will return an ERROR for an invalid request regarding the location for the work order.

If a Work Order Number does not have a driver assigned to it, an ERROR will be returned noting that unassigned stops cannot be sent.  Furthermore, if the driver assigned to the work order is not assigned to a vehicle within the REVEAL account, an ERROR will be returned specifying that the driver assigned to the work order must be assigned to a vehicle to send a stop.

If the Work Order is sent with a Description included the description provided within the request will be shown on the vehicle’s Garmin navigational device.  If no Description is provided by the user within the request, the Garmin navigational device will display the Work Order Number and Work Order Address.

DELETE Methods

·        DELETE Stops

DELETE Stops

The integrated user will be able to use this DELETE method to remove stops from a vehicle’s Garmin navigational device. 

The integrated user will need to provide a valid Vehicle Number and Stop Id.  If no valid Vehicle Number or Stop Id exist