The Planning and Scheduling API is a RESTful web service that enables REVEAL customers to integrate 3rd 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 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 Name |
Planning and Scheduling – Work Order Status |
Endpoint |
|
Operation |
GET, POST |
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.
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.
Operation and Path |
GET https://fim.api.eu.fleetmatics.com/pas/v1/workorderstatuses |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
[
{
"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"}}
}
]
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. |
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.
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.
{
"WorkOrderStatusCode": "78",
"WorkOrderStatusDescription": "Changed Description",
"WorkOrderStatusType": "Open"
}
Operation and Path |
POST https://fim.api.eu.fleetmatics.com/pas/v1/workorderstatuses |
HOST |
fim.api.eu.fleetmatics.com |
Accept |
application/json |
Authorization |
Atmosphere atmosphere_app_id=fleetmatics-p-eu-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls. |
Successful JSON Response:
{
"WorkOrderStatusCode": "78",
"WorkOrderStatusDescription": "Changed Description",
"WorkOrderStatusType": "Open"
}
Negative JSON Response:
{"Message": "The Work Order status code specified was not valid."}
· 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
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. |