Maintenances

A maintenance (maintenance generator) is a preventive maintenance plan: Bob! Desk creates its tickets on a schedule, for each location or equipment it covers. This resource returns the maintenances visible to your account, each with one line per location or equipment: where it applies, how often, and who performs it. Read-only.

Properties

Name
_id
Type
string
Description
Unique identifier of the maintenance.
Name
name
Type
string
Description
Name of the maintenance.
Name
type
Type
string
Description
regulatory (fixed interval, the default) or calendar (periods aligned on the calendar: start of the week, month or year).
Name
description
Type
string
Description
Free-text description, "" when empty.
Name
locations
Type
array
Description
The lines of the maintenance, one per location or equipment (see below). Lines removed from the maintenance or deleted are never returned.

Each line of locations has the following properties:

Name
_id
Type
string
Description
Unique identifier of the line.
Name
type
Type
string
Description
location (the maintenance applies to a location) or equipment (it applies to an equipment).
Name
location
Type
object
Description
The location of the line, or the location of the equipment: { _id, name, parent_id, path }. parent_id is the id of the parent location (null for a root location). path is the readable path from the root location, for example "Centre / Bâtiment A / Salle 1". Use the locations resource for the full location.
Name
equipment
Type
object
Description
{ _id, name } for an equipment line, null for a location line. Use the equipments resource for the full equipment.
Name
periodicity
Type
object
Description
{ type }: how often a ticket is created for this line (see the codes below). When the line has no periodicity of its own, the default periodicity of the maintenance is returned.
Name
intervener
Type
object
Description
{ _id, name } of the contractor or technician assigned to the line, or null. For a contractor account, see Which maintenances are returned.
Name
job
Type
object
Description
{ _id, label } of the job (trade) of the line, or null. label is in the language of the API token's user, then of the account, then in French.

Periodicity codes

`periodicity.type`	Meaning
`businessDay`	Every working day
`calendarDay`	Every day
`week`	Weekly
`2week`	Every 2 weeks
`3week`	Every 3 weeks
`6week`	Every 6 weeks
`month`	Monthly
`2month`	Every 2 months
`trim`	Every 3 months
`qrim`	Every 4 months
`semestre`	Every 6 months
`year`	Yearly
`reduit`	Reduced (yearly)
`complet`	Complete (every 6 months)
`2year`	Every 2 years
`3year`	Every 3 years
`4year`	Every 4 years
`5year`	Every 5 years
`6year`	Every 6 years
`10year`	Every 10 years

Which maintenances are returned

The token only reads the maintenances of its own account, with the same rules as the Bob! Desk app.

Client account: every maintenance shared with the account, with only the lines on its own locations and equipments.
Contractor account: only the lines the contractor is assigned to. On a maintenance the contractor created itself, it also gets the lines without an intervener and the lines assigned to its own technicians, subcontractors or partners. A maintenance with none of these lines is not returned, except one the contractor created. The intervener of another contractor is never named: intervener is null.

GET/api/v3.0/maintenances

Maintenances list

This endpoint returns the maintenances of your account, sorted by _id, with their lines. To paginate, pass the _id of the last item of the current page as the cursor parameter of the next request. When the response returns an empty maintenances array and cursor is null, you have reached the end of the list.

Optional parameters

Name
type
Type
string
Description
regulatory | calendar, filter on the type of the maintenance.
Name
cursor
Type
string
Description
Cursor to paginate the results (_id of the last item of the previous page).
Name
limit
Type
number
Description
Page size, 1..100 (default 20). Each maintenance carries all its lines, so pages are smaller than for other resources.

An invalid parameter returns 400 with { "error": "..." }, for example { "error": "Invalid cursor." }.

Request

GET

/api/v3.0/maintenances

curl -G https://api.bob-desk.com/api/v3.0/maintenances \
  -H "Authorization: Bearer {token}" \
  -d type="regulatory" \
  -d limit="20"

Response

{
  "cursor": "66a1f0c2e4b0a1b2c3d4e5f6",
  "maintenances": [
    {
      "_id": "66a1f0c2e4b0a1b2c3d4e5f6",
      "name": "Entretien des chaudières",
      "type": "regulatory",
      "description": "Contrôle annuel obligatoire",
      "locations": [
        {
          "_id": "66a1f0c2e4b0a1b2c3d4e600",
          "type": "equipment",
          "location": {
            "_id": "5f3c9b7e2a1d4c0017a1b2c3",
            "name": "Salle 1",
            "parent_id": "5f3c9b7e2a1d4c0017a1b2c2",
            "path": "Centre / Bâtiment A / Salle 1"
          },
          "equipment": {
            "_id": "60b1c2d3e4f5a6b7c8d9e0f1",
            "name": "Chaudière gaz"
          },
          "periodicity": { "type": "year" },
          "intervener": {
            "_id": "5d973899ecb060003525ddec",
            "name": "Domo-Elec"
          },
          "job": {
            "_id": "5d9b5b5b9ab7e72a4fb4ae70",
            "label": "Plomberie"
          }
        },
        {
          "_id": "66a1f0c2e4b0a1b2c3d4e601",
          "type": "location",
          "location": {
            "_id": "5f3c9b7e2a1d4c0017a1b2c2",
            "name": "Bâtiment A",
            "parent_id": "5f3c9b7e2a1d4c0017a1b2c1",
            "path": "Centre / Bâtiment A"
          },
          "equipment": null,
          "periodicity": { "type": "trim" },
          "intervener": null,
          "job": null
        }
      ]
    }
  ]
}

GET/api/v3.0/maintenances/:id

Retrieve a maintenance

This endpoint allows you to retrieve a single maintenance, with the same properties and the same lines as in the list. Returns 404 with { "error": "Maintenance not found." } if the id is not a valid id, if the maintenance is deleted, or if it is not visible to your account (for a contractor: no line of the maintenance is assigned to it, and it did not create it).

Route parameters

Name
id
Type
string
Description
Id of the maintenance (_id, 24-char hex).

Request

GET

/api/v3.0/maintenances/:id

curl https://api.bob-desk.com/api/v3.0/maintenances/66a1f0c2e4b0a1b2c3d4e5f6 \
  -H "Authorization: Bearer {token}"

Response

{
  "maintenance": {
    "_id": "66a1f0c2e4b0a1b2c3d4e5f6",
    "name": "Entretien des chaudières",
    "type": "regulatory",
    "description": "Contrôle annuel obligatoire",
    "locations": [
      {
        "_id": "66a1f0c2e4b0a1b2c3d4e601",
        "type": "location",
        "location": {
          "_id": "5f3c9b7e2a1d4c0017a1b2c2",
          "name": "Bâtiment A",
          "parent_id": "5f3c9b7e2a1d4c0017a1b2c1",
          "path": "Centre / Bâtiment A"
        },
        "equipment": null,
        "periodicity": { "type": "trim" },
        "intervener": null,
        "job": null
      }
    ]
  }
}