Planning and Scheduling Ė Work Orders

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.

The Planning and Scheduling (PAS) API is broken into multiple segments based on the object management within REVEAL.The following documentation will focus on the management of work order objects within REVEAL.

In order to apply a Status and/or Type for a work order, the Planning and Scheduling Ė Status and Planning and Scheduling Ė Type APIs will need to be reviewed.In order to create a Work Order, a Status and Type are required fields.If your account does not want to dynamically manage status and types, there are various ways to manage these required fields which will be noted more fully within the Status and Type documentation.

Key concepts for the Planning and Scheduling Ė Work Order API

        Planning and Scheduling Ė Work Order API is offered as a RESTful web service

        Standard REST verbs are applied: GET, POST, and PUT

o   There are no DELETE methods for the Planning and Scheduling Ė Work Orders API and work orders cannot be deleted within the REVEAL UI

        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 Integration Guidelines

Work order management software handles the automation of scheduling, assigning, and tracking jobs for the mobile workforce industry.

The definition of a work order when integrated with REVEAL, includes the following:

Ł  The technician/driver is assigned to a single vehicle within REVEAL

Ł  A single work order is only assigned to one technician/driver

Ł  Multiple work orders can be assigned to one technician/driver

Ł  Scheduled at a defined Start Date and Time within a single day

Vehicle location and work order statusing are used to identify where and when the activity happened and if the stop was a match to the work order.REVEAL displays location and work order information together for customers to review and improve efficiencies within their businesses.

Unassigned Work Orders

In some instances, work orders will be created before a driver assignment is made.For this scenario, the following guidelines will apply:

        If no driver is provided, the POST Work Order API method will accept the request.

        Within REVEAL, on the Live Map you can search for the work order by work order number.

        You can also choose to plot UNASSIGNED work orders on the map.

        Please note, if you choose to plot UNASSSIGNED work orders, you will only see Unassigned Work Orders plotting for the selected day.

REVEAL Work Order Features

Available Work Order Reports include:

        Daily Report with Work Orders

        Work Order Summary

        Work Order Variance Report

REVEAL work order reporting logic assumes that the integration will provide details related to a work orderís status or that the Field App will be used in order to track a work orderís lifecycle.If there is no intention to provide work order status updates, REVEAL reporting logic can be switched to use the Scheduled Date information to compare with vehicle location information for matching.Using the Scheduled Date logic is not as accurate as Status comparison.By default, the work order linkage logic is set to Status, Customer Support can switch this setting for a REVEAL account by request.

Available Work Order Dashboards include:

        On Time Arrivals

        Vehicle Activity (Hours Worked)

        Work Order On Site Time

Additional Work Order features include:

        Work Orders on Live Map

        Timeline View with Work Orders

        Replay with Work Orders

API Summary Details

API Name

Planning and Scheduling Ė Work Orders

Endpoint

https://fim.api.eu.fleetmatics.com/pas/v1

Operation

GET, POST, PUT

GET Methods

GET Work Order

The GET Work Order by Work Order Number method enables integration users to retrieve all the data that REVEAL has been sent related to a specific work order.

GET Work Order by Work Order Number Sample Request

Operation and Path

GET https://fim.api.eu.fleetmatics.com/pas/v1/workorders/<work order number> HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<Fleetmatics Integration Manager App ID>, Bearer <token>
 
NOTE: the Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET Work Order Sample Response

{

††† "WorkOrder": {

††††††† "ActualDateUtc": "2017-01-18T13:15:48.983",

††††††† "ActualDurationSeconds": 0,

††††††† "Address": {

††††††††††† "AddressLine1": "11241 Miromar Square Blvd",

††††††††††† "AddressLine2": "",

††††††††††† "Locality": "Estero",

††††††††††† "AdministrativeArea": "FL",

††††††††††† "PostalCode": "33928†††† ",

††††††††††† "Country": "USA"

††††††† },

††††††† "AddressResolved": true,

††††††† "ClientCustomerId": null,

††††††† "CreatedDateUtc": "2017-01-18T17:00:05.263",

††††††† "Description": "TECH MUST CLOCK IN",

††††††† "DriverNumber": "777",

††††††† "Latitude": 26.425671,

††††††† "Longitude": -81.801965,

††††††† "ModifiedDateUtc": "2017-01-18T16:58:55.4",

††††††† "OnSiteDurationSeconds": 0,

††††††† "RadiusInKm": 0.322,

††††††† "ScheduledDateUtc": "2017-01-18T16:59:50",

††††††† "ScheduledDurationSeconds": 0,

††††††† "StatusChangeDateUtc": "2017-01-18T13:16:47",

††††††† "WorkOrderNumber": "595067-03CARA-374",

††††††† "WorkOrderStatusCode": "Open",

††††††† "WorkOrderTypeCode": "INT LMSW"

††† },

††† "_links": {

††††††† "Self": {

††††††††††† "Href": "http://api.eu.fleetmatics.com/PAS/v1/workorders/595067-03CARA-374"

††††††† }

††† }

}

 

 

GET Current Work Order Status

The GET Current Work Order Status by Work Order Number enables the integration user to retrieve the current Work Order Status applied to the work order.Users may invoke this method to track the work orderís lifecycle within REVEAL.

In order to apply a work order status to a work order in REVEAL the status type must first be created to be recognized using the Planning and Scheduling Ė Work Order Status API.Available work order statuses can be reviewed within REVEALís Admin section under Work Order Preferences.

GET Current Work Order Status Sample Request

Operation and Path

GET https://fim.api.eu.fleetmatics.com/pas/v1/workorders/ <work order number>/status HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<Fleetmatics Integration Manager App ID>, Bearer <token>
 
NOTE: the Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

GET Current Work Order Status Sample Response

{

††† "StatusChangeDateUtc": "2017-01-18T13:16:47",

††† "WorkOrderStatusCode": "InProcess",

††† "WorkOrderStatusDescription": "InProcess Work Order.",

††† "WorkOrderStatusType": "InProcess"

}

POST Methods

POST Work Order†††††††††

The POST Work Order method enables integration users to create work orders within the REVEAL account.

POST Work Order Sample Request

The request body must have the following information completed for the work order:

{

††††††††††††††††† "ActualDateUtc": "",

††††††††††††††††† "ActualDurationSeconds": null,

††††††††††††††††† "Address": {

††††††††††††††††††† "AddressLine1": "4444 East Ridgewood Drive",

††††††††††††††††††† "AddressLine2": null,

††††††††††††††††††† "Locality": "Seven Hills",

††††††††††††††††††† "AdministrativeArea": "Ohio",

††††††††††††††††††† "PostalCode": "44131",

†††††††† †††††††††††"Country": "USA"

††††††††††††††††† },

††††††††††††††††† "ClientCustomerId": null,

††††††††††††††††† "Description": null,

††††††††††††††††† "DriverNumber": "777",

††††††††††††††††† "Latitude": 0.0,

††††††††††††††††† "Longitude": 0.0,

††††††††††† ††††††"OnSiteDurationSeconds": 0,

††††††††††††††††† "RadiusInKm": ".322",

††††††††††††††††† "ScheduledDateUtc": "2017-01-13Z18:00:00",

††††††††††††††††† "ScheduledDurationSeconds": null,

††††††††††††††††† "StatusChangeDateUtc": null,

††††††††††††††††† "WorkOrderNumber": "WO-2518-2029",

††††††††††††††††† "WorkOrderStatusCode": "InProcess",

††††††††††††††††† "WorkOrderTypeCode": "ALM"

††††††††††††††† }

 

Operation and Path

POST https://fim.api.eu.fleetmatics.com/pas/v1/workorders HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<Fleetmatics Integration Manager App ID>, Bearer <token>
 
NOTE: the Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

POST Work Order Sample Response

When the POST Work Order is invoked successfully the response will include the work order objectís details within the response.

{

††† "ActualDateUtc": null,

††† "ActualDurationSeconds": null,

††† "Address": {

††††††† "AddressLine1": "4444 East Ridgewood Drive",

††††††† "AddressLine2": null,

††††††† "Locality": "Seven Hills",

††††††† "AdministrativeArea": "Ohio",

††††††† "PostalCode": "44131",

††††††† "Country": "USA"

††† },

††† "AddressResolved": false,

††† "ClientCustomerId": null,

††† "CreatedDateUtc": "2017-01-18T21:38:28.78",

††† "Description": null,

††† "DriverNumber": "777",

††† "Latitude": 0,

††† "Longitude": 0,

††† "ModifiedDateUtc": "2017-01-18T21:38:28.78",

††† "OnSiteDurationSeconds": 0,

††† "RadiusInKm": 0.322,

††† "ScheduledDateUtc": "2017-01-13T18:00:00",

††† "ScheduledDurationSeconds": null,

††† "StatusChangeDateUtc": null,

††† "WorkOrderNumber": "WO-2518-2029",

††† "WorkOrderStatusCode": "InProcess",

††† "WorkOrderTypeCode": "ALM"

}

 

POST Work Order Status

The POST Work Order Status method enables integration users to update a work orderís status to track the lifecycle of the work order.Work orders need to minimally have IN PROCESS and COMPLETED statuses for REVEAL to calculate reporting metrics and match the work order to vehicle location information.

If your account is not planning to status a work order, there is an option for your work order reporting to use Schedule Date UTC to match against vehicle location information.The match rate is not as accurate, but a Customer Support representative can adjust the logic referenced on request.

POST Work Order Status Sample Request

The request body must have the following information completed to update a work order status:

{

†††††† †††††"WorkOrderStatusCode": "Complete",

††††††††††† "WorkOrderStatusDescription": "Complete",

††††††††††† "WorkOrderStatusType": "Complete"

††††††††† }

 

Operation and Path

POST https://fim.api.eu.fleetmatics.com/pas/v1/workorders/<work order number>/status HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<Fleetmatics Integration Manager App ID>, Bearer <token>
 
NOTE: the Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

 

POST Work Order Sample Response

Similar to a PUT method, the POST Work Order response will not return an object review.The response will be limited to a set of standard HTTP codes:

        Successfully edited work order will return a 200 code

        Unfound Place IDs, or the unique identifier used for the call, will return a 404 error

        Bad requests, typically due to an error in the callís content, will return a 400 error

        Invalid tokens or an Authorization problem will return a 401 error

        If the service is unavailable at the time the call was made a 500 error will return

PUT Methods

PUT Work Order

The PUT Work Order by Work Order Number method enables integration users to update an existing work orderís meta data within REVEAL.

The PUT method cannot be used to update a work orderís status.To update a work order status, the POST Work Order Status method will need to be invoked.

PUT Work Order Sample Request

The request body must have the following information completed for the work order:

{

††††††††††††††††† "ActualDateUtc": "",

††††††††††††††††† "Address": {

††††††††††††††††††† "AddressLine1": "3000 East Ridgewood Drive",

††††††††††††††††††† "AddressLine2": null,

††††††††††††††††††† "Locality": "Seven Hills",

††††††††††††††††††† "AdministrativeArea": "Ohio",

††††††††††††††††††† "PostalCode": "44131",

††††††††††††††††††† "Country": "USA"

††††††††††††††††† },

††††††††††††††††† "ClientCustomerId": null,

††††††††††††††††† "Description": null,

††††††††††††††††† "DriverNumber": "777",

††††††††††††††††† "Latitude": 0.0,

††††††††††††††††† "Longitude": 0.0,

††††††††††††††††† "OnSiteDurationSeconds": 0,

††††††††††††††††† "RadiusInKm": ".322",

††††††††††††††††† "ScheduledDateUtc": "2017-01-13Z18:00:00",

††††††††††††††††† "ScheduledDurationSeconds": null,

††††††††††††††††† "WorkOrderNumber": "WO-2518-2029",

††††††††††††††††† "WorkOrderTypeCode": "ALM"

††††††††††††††† }

 

Operation and Path

PUT https://fim.api.eu.fleetmatics.com:443/pas/v1/workorders/<work order number> HTTP/1.1

HOST

fim.api.eu.fleetmatics.com

Accept

application/json

Authorization

Atmosphere realm=http://atmosphere,atmosphere_app_id=<Fleetmatics Integration Manager App ID>, Bearer <token>
 
NOTE: the Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

PUT Work Order Sample Response

PUT methods will not return an object review.The response will be limited to a set of standard HTTP codes:

        Successfully edited work order will return a 200 code

        Unfound Place IDs, or the unique identifier used for the call, will return a 404 error

        Bad requests, typically due to an error in the callís content, will return a 400 error

        Invalid tokens or an Authorization problem will return a 401 error

        If the service is unavailable at the time the call was made a 500 error will return

Work Order Field Breakdown

The following list provides all the possible fields that may be requested or retrieved when working with the Planning and Scheduling Ė Work Order API.The RAML file or the method documentation above describes the object requirements for request and response fields to be used per call.This list should only be used for reference for field definition.

Field

JSON Formatted Sample

Field Notes and Default Values

ActualDate Utc

{

††† "ActualDateUtc": null,

The Actual Date field is used when a PUT is invoked to change the Scheduled Date for a work order.

ActualDurationSeconds

††† "ActualDurationSeconds": null,

REVEAL will calculate the actual duration value based on the status information provided.If no status information is provided this value may be provided by the work order provider.

Address

††† "Address": {

††††††† "AddressLine1": "4444 East Ridgewood Drive",

††††† ††"AddressLine2": null,

††††††† "Locality": "Seven Hills",

††††††† "AdministrativeArea": "Ohio",

††††††† "PostalCode": "44131",

††††††† "Country": "USA"

††† },

Address contains the global standards for address components:

 

        Address Line 1 Ė location specific identification such as a house number

        Address Line 2 Ė additional information to identify location such as an apartment number

        Locality Ė city, town, etc.

        Administrative Area Ė state, province, etc.

        Postal Code

        Country

Address components are not required if the coordinates are provided for the work order.If address components and coordinates are both provided, the work order will be created referencing the coordinates.

AddressResolved

††† "AddressResolved": false,

Boolean field.When retrieving a work orderís details if the work order location was successfully geocoded by Google the flag will be set to true.

ClientCustomerId

††† "ClientCustomerId": null,

Boolean field for deprecated service parameter, defaults to Null

CreatedDateUtc

††† "CreatedDateUtc": "2017-01-18T21:38:28.78",

The date and time stamp in UTC that the work order object was created within REVEAL.The default value will be the current date and time stamp when the work order was invoked.

Description

††† "Description": null,

This is not a required field.A string may be provided in order to display instructions or notes about the work order to the technician/driver.

DriverNumber

††† "DriverNumber": "777",

The Driver Number is the unique identifier that will be used to reference the driver within the API.The Driver Number is not a mandatory field within the REVEAL account, but is required for the API.

Latitude

††† "Latitude": 0,

Either the Address components or the coordinates must be provided to create a work order.If both the address and coordinate fields are supplied, the coordinates will be used for reference to geocode the work orderís location.

Longitude

††† "Longitude": 0,

Either the Address components or the coordinates must be provided to create a work order.If both the address and coordinate fields are supplied, the coordinates will be used for reference to geocode the work orderís location.

ModifiedDateUTC

††† "ModifiedDateUtc": "2017-01-18T21:38:28.78",

If the work order object is modified after the creation date, the last modified date will be presented within the response.

OnSiteDurationSeconds

††† "OnSiteDurationSeconds": 0,

This is not a required field.If there is an estimate for the time that the technician should be on site at the work order the value may be provided in seconds.Following the work orderís completion if status details were provided, this value will be overwritten with the status calculation to determine the on-site duration.

RadiusInKm

††† "RadiusInKm": ".322",

The designated radius in kilometers used to create the radius around the work order.

ScheduledDateUtc

††† "ScheduledDateUtc": "2017-01-13Z18:00:00",

The Scheduled Date and Time for the work to be started or the technicianís scheduled time to be on site.

ScheduledDuration Seconds

††† "ScheduledDurationSeconds": null,

The Scheduled Duration in Seconds that the work order job is estimated to take.This value will not be overwritten by REVEALís calculation and will be used for reporting variances.

StatusChangeDateUtc

††† "StatusChangeDateUtc": null,

The date and time when the work orderís status was applied.

WorkOrderNumber

††† "WorkOrderNumber": "WO-2518-2021",

Work Order Number is a required field for a work order to be created within REVEAL and must be unique within an account.

WorkOrderStatusCode

††† "WorkOrderStatusCode": "InProcess",

Work Order Status Codes are created using the Planning and Scheduling Ė Work Order Status API.All available work order status codes can be found within REVEALís Admin section under Work Order Preferences.A work order status is used to update a work orderís lifecycle for tracking purposes.

WorkOrderStatus Description

††† "WorkOrderStatusDescription": "InProcess Work Order.",

 

When creating work order statuses within a REVEAL account there is an optional field for a Description to be provided.If the status was created with a Description the GET method for a work orderís current status will return the description field.

WorkOrderStatusType

††† "WorkOrderStatusType": "InProcess"

}

 

 

WorkOrderTypeCode

††† "WorkOrderTypeCode": "ALM"

}

Work Order Type Codes are created using the Planning and Scheduling Ė Work Order Type API.All available work order types can be found within REVEALís Admin section under Work Order Preferences.A work order code is used to describe or categorize the type of work scheduled, i.e. ďTrouble Call.Ē