Planning and Scheduling – Work Orders

The Planning and Scheduling API is a RESTful web service that enables Fleetmatics customers to integrate 3^rd 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.”