Planning and Scheduling – Work Order Type

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 available work order types for a REVEAL account.

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.

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

· Planning and Scheduling – Work Order Type 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 Order Types API and work order types 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 Work Order Type 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 Type
Endpoint	https://fim.api.eu.fleetmatics.com/pas/v1
Operation	GET, POST

GET Work Order Type

The integrated user can leverage the work order type field to categorize the job to be done.  The Work Order Type Code is provided by the integrated user to be utilized by the POST Work Order Type Code method.

GET All Work Order Type Codes

The integrated user will be able to use the GET All Work Order Type Codes method in order to retrieve all available work order type codes within their REVEAL account.

Operation and Path	GET https://fim.api.eu.fleetmatics.com/pas/v1/workordertypes
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 Type Codes Sample Response

[

      {

      "Code": "10",

      "Description": "TROUBLE CALL"

       },

      {

      "Code": "13",

      "Description": "FAILED DIGITAL SIK"

       },

      {

      "Code": "19",

      "Description": "AO SEPARATE"

       }

]

GET All Work Order Type Codes Response Field Breakdown

Field	JSON Formatted Sample	Field Notes and Default Values
Code	{       "Code": "10",	Work Order Type Codes are alphanumeric values created using the Planning and Scheduling – Work Order Type API.  All available work order types can be found within REVEAL’s Admin section under the Work Order Map Preferences.  This provided value describes the type of work order that the technician will be working on.  This value must be unique when added to the REVEAL account.
Description	"Description": "Trouble Call"        }	The Work Order Type Descriptions 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 Map Preferences.  The Work Order Type Description is used to provide additional context to the Work Order Type Code (i.e. Description “Trouble Call” Is associated with Work Order Type Code “20.”)

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.

Operation and Path	GET https://fim.api.eu.fleetmatics.com/pas/v1/workordertypes/{code}
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 Type by Code Sample Response

{

   "Code": "10",

   "Description": "TROUBLE CALL"

}

GET Work Order Type by Code Response Field Breakdown

Field	JSON Formatted Sample	Field Notes and Default Values
Code	{    "Code": "10",	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 the Work Order Map Preferences.  This provided value describes the type of work order that the technician will be working on.  This value must be unique when added to the REVEAL account.
Description	"Description": "TROUBLE CALL" }	The Work Order Type Descriptions 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 Map Preferences.  The Work Order Type Description is used to provide additional context to the Work Order Type Code (i.e. Description “Trouble Call” Is associated with Work Order Type Code “20.”)

POST Work Order Type

The POST Work Order Type method allows the integrated user to add related work order type information to their REVEAL account.

POST Work Order Status by Work Order Number

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

POST Work Order Status by Work Order Number Request Body

{

   "Code": "20",

   "Description": "New Work Order Type"

}

POST Work Order Status by Work Order Number Request Header

Operation and Path	POST https://fim.api.eu.fleetmatics.com/pas/v1/workordertypes
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 by Work Order Number Return and Response Field Breakdown

Field	JSON Formatted Sample	Field Notes and Default Values
Code	{    "Code": "20",	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 the Work Order Map Preferences.  This provided value describes the type of work order that the technician will be working on.  This value must be unique when added to the REVEAL account.
Description	"Description": "New Work Order Type" }	The Work Order Type Descriptions 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 Map Preferences.  The Work Order Type Description is used to provide additional context to the Work Order Type Code (i.e. Description “Trouble Call” Is associated with Work Order Type Code “20.”)

POST Work Order Status by Work Order Number Sample Response

JSON Response:

{

   "Code": "20",

   "Description": "New Work Order Type"

}

The response will also return a set of standard HTTP codes:

· Successfully edited vehicles will return a 200 code

· Unfound Vehicle Numbers, 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