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

Work Order Management Methods

GET Methods

The following GET method will be used in order to return work order details.

·        GET Work Order By Work Order Number

·        GET All Work Order Statuses

·        GET All Work Order Type Codes

·        GET Work Order Type by Code

·        GET Work Order Status by Work Order Number

GET Work Order by Work Order Number

The integrated user will be able to return a work order object’s details using this GET method.  The method will only return a work order if the work order has been previously created and sent to the REVEAL account.

The following information will be returned with the GET Work Order by Work Order Number method:

·        Actual Date UTC

·        Actual Duration

·        Address Line 1

·        Address Line 2

·        Administrative Area – state, province, etc.

·        Driver Number

·        Work Order Number

·        Country

·        Description

·        Driver ID

·        Latitude

·        Longitude

·        Locality – city, town, etc.

·        Radius in KM

·        Postal Code

·        Scheduled Date UTC

·        Scheduled Duration

·        Status Change Date UTC

·        Work Order Status Code

·        Work Order Status Description

·        Work Order Status Type

·        Work Order Type Code

GET All Work Order Statuses

The integrated user will be able to use this GET method to collect a list of all the available work order status codes configured within a REVEAL account.  Accurate Work Order Status Code values are important to track the lifecycle of a work order and will be used to calculate work order durations and metrics within REVEAL.

Work Order Status Codes are unique values configured by the integrated user for the account and can be created using the POST Work Order Status method.

Work Order Status Code

Created by the integration user for a REVEAL account – this is a mandatory field to create a work order

Work Order Status Description

Created by the integrated user and is an optional field

Work Order Status Type ID

Created by REVEAL as an enumerator value and will be used to calculate work order durations within REVEAL

Description of Enumerator

Not a value within REVEAL, but is the interpretations of the Work Order Status Type ID enumerator

 

 

0

NONE

 

 

1

OPEN

 

 

2

IN PROCESS

 

 

4

COMPLETE

 

 

8

CLOSED

 

 

16

CANCELED

 

 

32

SUSPENDED
GET All Work Order Type Codes

The integrated user will be able to manage work orders using values created to describe the type of work associated with the work order.  The Work Order Type Code is provided by the integrated user using the POST Work Order Type Code method.

The following information will be returned when invoking this method:

·        Work Order Type Code

·        Work Order Type Description

·        Date and Timestamp when the Work Order Type Code was created by the integrated user

GET Work Order Type by Code

The integrated user will be able to use this GET method to retrieve a particular Work Order Type by providing the unique Work Order Type Code value.  This will allow users to confirm when/if a particular Work Order Type was previously created.  This method will also show the Work Order Type Code Description if one was previously provided when creating the code.

GET Current Status by Work Order Number

The integrated user will be able to use this GET method to retrieve the current status of a specific work order.

The integrated user must present a valid work order number.  If the work order number cannot be verified within the REVEAL account the user will receive an ERROR.

The following information related to a work order will be returned when invoking this method:

·        Current Work Order Status

·        Work Order Status change date and timestamp

·        Work Order Status Code

·        Work Order Status Description

·        Work Order Status Type ID

POST Methods

·        POST Work Order

·        POST Work Order Status Code

·        POST Work Order Status by Work Order Number

·        POST Work Order Type Code

POST Work Order

The integrated user will be able to use this method to create (POST) work orders to their REVEAL account.  Each work order will need to have a set of respective attributes provided within the create method in order to be used properly within REVEAL.

The following information will be available to update the work order record:

·        Actual Date UTC

·        Actual Duration

·        Address Line 1

·        Address Line 2

·        Administrative Area – state, province, etc.

·        Client Customer ID – should be NULL

·        Country

·        Description

·        Driver Number

·        Latitude

·        Longitude

·        Locality – city, town, etc.

·        On Site Duration

·        Postal Code

·        Radius in KM

·        Scheduled Date UTC

·        Scheduled Duration

·        Status Change Date UTC

·        Work Order Number – this is a mandatory field to create a work order and then perform any subsequent work order calls

·        Work Order Status Code

·        Work Order Status Type 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 Work Order Status Code

The integrated user will be able to provide REVEAL with Work Order Status Codes to clarify the state of a work order.  REVEAL interprets all statuses as enumerators that will be used to review a work order’s lifecycle and to calculate specific durations related to a work order.  Therefore, it is important for our integrated users to ensure that the Work Order Status Code is properly aligned to the enumerators that REVEAL will use for these calculations within Work Order metrics and reporting.

Work Order Status Codes must be unique within an REVEAL account.  The value can be alphanumeric and has a maximum character value of 64.  However, integrated users may create multiple work order status codes to be aligned with 1 enumerator value.  The Work Order Status Code is a mandatory field for a work order.

 

Work Order Status Code

Created by the integration user for a REVEAL account – this is a mandatory field to create a work order

Work Order Status Description

Created by the integrated user and is an optional field

Work Order Status Type ID

Created by REVEAL as an enumerator value and will be used to calculate work order durations within REVEAL

Description of Enumerator

Not a value within REVEAL, but is the interpretations of the Work Order Status Type ID enumerator

 

 

0

NONE

 

 

1

OPEN

 

 

2

IN PROCESS

 

 

4

COMPLETE

 

 

8

CLOSED

 

 

16

CANCELED

 

 

32

SUSPENDED

 

POST Work Order Status by Work Order Number

The integrated user will be able to update a work order’s status using this POST method.  This method should ONLY be used for updating an existing work order’s status and will not allow for work order attributes to be modified using this method.  If the work order attributes need to be modified, please refer to the POST Work Order by Work Order Number method.

The following fields will be available to be updated using this PUT method:

·        Work Order Status Change Date

·        Work Order Status Code

If the integrated user provides a Work Order Status Code that has not been previously created within the REVEAL account, a 404 ERROR will be returned.  To create a new Work Order Status Code within an account, see the POST Work Order Status Code method.

POST Work Order Type Code

The integrated user will be able to provide REVEAL with Work Order Type Code to clarify the type of work that should be associated with the work order.  The Work Order Type Code is a mandatory field for a work order.

The user will be able to provide the following details when creating a new Work Order Type Code for a REVEAL account:

·        Work Order Type Code – must be unique

·        Work Order Type Description – optional

The Date and Timestamp will be stored upon creation. 

PUT Methods

·        PUT Work Order by Work Order Number

PUT Work Order by Work Order Number

The integrated user will be able to edit an existing work order by using this PUT method and providing a valid work order number.

This method will not be able to perform the following changes to a work order:

1.      Cannot delete a work order

2.      Cannot update a work order’s status

Please note the unique identifier to call this PUT method is the Work Order Number.  If a valid Work Order Number is not provided an ERROR will be returned.  A valid Work Order Number is defined as REVEAL already having received the work order object previously with a unique Work Order Number.

The following information work order fields will be available to be updated using this method:

·        Actual Date UTC

·        Address Line 1

·        Address Line 2

·        Administrative Area – state, province, etc.

·        Client Customer ID – should be NULL

·        Country

·        Description

·        Driver Number

·        Latitude

·        Longitude

·        Locality – city, town, etc.

·        On-Site Duration

·        Postal Code

·        Radius in KM

·        Scheduled Date UTC

·        Scheduled Duration UTC

·        Work Order Type 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.