Planning and Scheduling – Work Order Status

The Planning and Scheduling API is a RESTful web service that enables REVEAL customers to integrate 3^rd party back-office systems 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 status 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 API documentation.

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

· Planning and Scheduling – Work Order Status API is offered as a RESTful web service

· Standard REST verbs are applied: GET, POST

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

o 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.

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

Note: The returned response will be restricted to the Reveal account's data plan. If the information being queried is outside of the data plan, a "400 Bad Request error "response will be returned.

For more details on your account's data plan please reach out to Verizon Connect Customer Support

API Summary Details

API Name	Planning and Scheduling – Work Order Status
Endpoint	https://fim.api.eu.fleetmatics.com/pas/v1
Operation	GET, POST

GET Work Order Status

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 All Work Order Statuses

The integrated user will be able to use the GET All Work Order Statuses method to retrieve all of the work order statuses that exist within the REVEAL account.

GET ALL Work Order Statuses Request Header

Operation and Path	GET https://fim.api.eu.fleetmatics.com/pas/v1/workorderstatuses
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 All Work Order Statuses Response

[

{

"WorkOrderStatus": {

"CreatedDateUtc": "2015-02-19T14:36:26.097",

"WorkOrderStatusCode": "Open",

"WorkOrderStatusDescription": "Open",

"WorkOrderStatusType": "Open"

"_links": {"Self": {"Href": "https://fim-stage.api.us.fleetmatics.com/pas/v1/workorderstatuses/Open"}}

{

"WorkOrderStatus": {

"CreatedDateUtc": "2015-02-19T14:36:27.633",

"WorkOrderStatusCode": "InProcess",

"WorkOrderStatusDescription": "In process",

"WorkOrderStatusType": "None"

"_links": {"Self": {"Href": "https://fim-stage.api.us.fleetmatics.com/pas/v1/workorderstatuses/InProcess"}}

}

]

GET Response Field Breakdown

Field	JSON Formatted Sample	Field Notes and Default Values
Created Date UTC	"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.
Work Order Status Code	"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.
Work Order Status 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.
Work Order Status Type	"WorkOrderStatusType": "InProcess" }	Work Order Status Types provide additional context to the associated Work Order Status Type Code used to calculate work order durations within REVEAL.

POST Work Order Status

The integrated user will be able to use this method to create (POST) new work order statuses to be available within the REVEAL account for future work order management. For an integrated user to apply a work order status to a particular work order, the Work Order API must be invoked.

POST Work Order Status Code

The POST Work Order Status Code method allows integration users to create new work order statuses that can be further added to existing work orders.

POST Work Order Status Code Request Body

{

"WorkOrderStatusCode": "78",

"WorkOrderStatusDescription": "Changed Description",

"WorkOrderStatusType": "Open"

}

POST Work Order Status Code Request Header

Operation and Path	POST https://fim.api.eu.fleetmatics.com/pas/v1/workorderstatuses
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 Status Code Sample Response

Successful JSON Response:

{

"WorkOrderStatusCode": "78",

"WorkOrderStatusDescription": "Changed Description",

"WorkOrderStatusType": "Open"

}

Negative JSON Response:

{"Message": "The Work Order status code specified was not valid."}

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

POST Work Order Status Code Response Field Breakdown

Field	JSON Formatted Sample	Field Notes and Default Values
Work Order Status Code	{ "WorkOrderStatusCode": "78",	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. When POSTing a new work order status, a new WorkOrderStatusCode must be provided. If a status code is provided that currently exists within the REVEAL account, a negative response will be returned and the status will not be created.
Work Order Status Description	"WorkOrderStatusDescription": "Changed Description",	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.
Work Order Status Type	"WorkOrderStatusType": "Open" }	Work Order Status Types provide additional context to the associated Work Order Status Type Code used to calculate work order durations within REVEAL.