Scheduled commands
Scheduled commands send saved commands to devices automatically, following a calendar: pick a calendar and the saved commands to send when each of its windows starts and when it ends, for example to stop and resume a vehicle engine. Every run is recorded so it can be reviewed afterwards.
The Scheduled Command Model
Scheme
- Name
id- Type
- integer
- Description
- Unique identifier for the scheduled command
- Name
name- Type
- string required
- Description
- Human-readable name
- Name
description- Type
- object
- Description
- Free text describing what the schedule does
- Name
calendarId- Type
- integer required
- Description
- Calendar whose windows drive the schedule. A window is the time between an event's start and end; touching or overlapping events count as one window
- Name
active- Type
- boolean
- Description
- When false the schedule never fires on its own (Run now still works). Re-activating does not fire retroactively
- Name
onStart- Type
- array of object
- Description
- Commands sent, in order, when a calendar window starts
- Name
onEnd- Type
- array of object
- Description
- Commands sent, in order, when a calendar window ends
- Name
attributes- Type
- object
- Description
- Additional custom attributes
- Name
deviceIds- Type
- array of integer
- Description
- Devices linked directly. Managed with `POST`/`DELETE /permissions/bulk`, not in this body
- Name
groupIds- Type
- array of integer
- Description
- Groups linked; every device in them (child groups included) is a target, resolved when the schedule fires
- Name
lastRun- Type
- object
- Description
- Time of the latest run, if any
The Scheduled Command Step Model
Scheme
- Name
commandId- Type
- integer required
- Description
- Saved command to send
- Name
delaySeconds- Type
- integer
- Description
- Seconds to wait after the previous step was sent. Ignored for the first step of a list
The Scheduled Command Run Model
Scheme
- Name
id- Type
- integer
- Description
- Name
scheduledCommandId- Type
- integer
- Description
- Name
phase- Type
- string
- Description
- Name
deviceId- Type
- integer
- Description
- Name
commandId- Type
- integer
- Description
- The saved command of the step
- Name
time- Type
- string <date-time>
- Description
- When the step was sent, queued or skipped (the due time while it is still pending)
- Name
status- Type
- string
- Description
- `pending` is a delayed step waiting for its time. `sent` means it was handed to an online device's connection (the device's acknowledgement is not tracked). `queued` waits in the command queue for an offline device and becomes `delivered` once the device takes it. `skipped` was not sent, see `reason`. `failed` is an unexpected error while sending
- Name
reason- Type
- object
- Description
- Why a step was skipped: `offline`, `queue_expired`, `superseded` (the opposite phase fired for the same device), `schedule_inactive`, `missed` (more than 5 minutes past its time, for example after a restart), `no_permission`, `device_not_found`, `command_not_found` or `not_sent` (the saved-command send path declined the command)
GET/scheduledcommands
Fetch a list of Scheduled commands
Without params, it returns the Scheduled commands the user has access to. Each item includes the devices and groups it is linked to (deviceIds, groupIds) and the time of its latest run (lastRun).
Authorizations
BasicAuth or ApiKey
- Name
BasicAuth- Type
- scheme
- Description
- HTTP Authorization Scheme: basic
- Name
ApiKey- Type
- scheme
- Description
- HTTP Authorization Scheme: bearer
Query Parameters
- Name
all- Type
- boolean
- Description
- Can only be used by admins or managers to fetch all entities
- Name
userId- Type
- integer
- Description
- Standard users can use this only with their own _userId_
Response schema
- Name
application/json- Type
- schema
- Description
Responses
- Name
200- Type
- success
- Description
- ScheduledCommand
- Name
401- Type
- error
- Description
- Unauthorized
Request
GET
/scheduledcommandscurl --location 'https://gw.onemap8.com/api/scheduledcommands?all=<boolean>&userId=<integer>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'
Response
[
{
"id": 0,
"name": "<string>",
"description": "<string>",
"calendarId": 0,
"active": true,
"onStart": [
{
"commandId": 0,
"delaySeconds": 0
}
],
"onEnd": [
{}
],
"attributes": {
"queueMaxMinutes": 0
},
"deviceIds": [
0
],
"groupIds": [
0
],
"lastRun": "<date-time>"
}
]
POST/scheduledcommands
Create a Scheduled command
deviceIds, groupIds and lastRun are read-only and ignored here. Link devices and groups afterwards with POST /permissions/bulk, using { deviceId, scheduledCommandId } and { groupId, scheduledCommandId } bodies (owner first, in separate requests). A schedule with no links simply has nothing to send. Requires a calendar and at least one command in onStart or onEnd, each a saved command the user can access.
Authorizations
BasicAuth or ApiKey
- Name
BasicAuth- Type
- scheme
- Description
- HTTP Authorization Scheme: basic
- Name
ApiKey- Type
- scheme
- Description
- HTTP Authorization Scheme: bearer
Request body schema
- Name
application/json- Type
- schema
- Description
Body schema
- Name
id- Type
- integer
- Description
- Unique identifier for the scheduled command
- Name
name- Type
- string required
- Description
- Human-readable name
- Name
description- Type
- object
- Description
- Free text describing what the schedule does
- Name
calendarId- Type
- integer required
- Description
- Calendar whose windows drive the schedule. A window is the time between an event's start and end; touching or overlapping events count as one window
- Name
active- Type
- boolean
- Description
- When false the schedule never fires on its own (Run now still works). Re-activating does not fire retroactively
- Name
onStart- Type
- array of object
- Description
- Commands sent, in order, when a calendar window starts
- Name
onEnd- Type
- array of object
- Description
- Commands sent, in order, when a calendar window ends
- Name
attributes- Type
- object
- Description
- Additional custom attributes
- Name
deviceIds- Type
- array of integer
- Description
- Devices linked directly. Managed with `POST`/`DELETE /permissions/bulk`, not in this body
- Name
groupIds- Type
- array of integer
- Description
- Groups linked; every device in them (child groups included) is a target, resolved when the schedule fires
- Name
lastRun- Type
- object
- Description
- Time of the latest run, if any
Response schema
- Name
application/json- Type
- schema
- Description
Responses
- Name
200- Type
- success
- Description
- ScheduledCommand
- Name
400- Type
- error
- Description
- Bad request: a validation error, or no access to the calendar or a saved command, or a restricted user (`readonly`, `limitCommands`)
- Name
401- Type
- error
- Description
- Unauthorized
Request
POST
/scheduledcommandscurl --location --request POST 'https://gw.onemap8.com/api/scheduledcommands' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": 0,
"name": "<string>",
"description": "<string>",
"calendarId": 0,
"active": true,
"onStart": [
{
"commandId": 0,
"delaySeconds": 0
}
],
"onEnd": [
{}
],
"attributes": {
"queueMaxMinutes": 0
}
}'
Response
{
"id": 0,
"name": "<string>",
"description": "<string>",
"calendarId": 0,
"active": true,
"onStart": [
{
"commandId": 0,
"delaySeconds": 0
}
],
"onEnd": [
{}
],
"attributes": {
"queueMaxMinutes": 0
},
"deviceIds": [
0
],
"groupIds": [
0
],
"lastRun": "<date-time>"
}
GET/scheduledcommands/{id}
Fetch a Scheduled command
Authorizations
BasicAuth or ApiKey
- Name
BasicAuth- Type
- scheme
- Description
- HTTP Authorization Scheme: basic
- Name
ApiKey- Type
- scheme
- Description
- HTTP Authorization Scheme: bearer
Path parameters
- Name
id- Type
- integer required
- Description
Response schema
- Name
application/json- Type
- schema
- Description
Responses
- Name
200- Type
- success
- Description
- ScheduledCommand
- Name
400- Type
- error
- Description
- No access to this Scheduled command
- Name
401- Type
- error
- Description
- Unauthorized
- Name
404- Type
- error
- Description
- Not found
Request
GET
/scheduledcommands/{id}curl --location 'https://gw.onemap8.com/api/scheduledcommands/<integer>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'
Response
{
"id": 0,
"name": "<string>",
"description": "<string>",
"calendarId": 0,
"active": true,
"onStart": [
{
"commandId": 0,
"delaySeconds": 0
}
],
"onEnd": [
{}
],
"attributes": {
"queueMaxMinutes": 0
},
"deviceIds": [
0
],
"groupIds": [
0
],
"lastRun": "<date-time>"
}
PUT/scheduledcommands/{id}
Update a Scheduled command
Replaces the editable fields. Changing the calendar or re-activating a schedule makes it start watching its calendar from scratch, so it never fires retroactively for a window that is already open. Deactivating cancels its pending and queued commands.
Authorizations
BasicAuth or ApiKey
- Name
BasicAuth- Type
- scheme
- Description
- HTTP Authorization Scheme: basic
- Name
ApiKey- Type
- scheme
- Description
- HTTP Authorization Scheme: bearer
Path parameters
- Name
id- Type
- integer required
- Description
Request body schema
- Name
application/json- Type
- schema
- Description
Body schema
- Name
id- Type
- integer
- Description
- Unique identifier for the scheduled command
- Name
name- Type
- string required
- Description
- Human-readable name
- Name
description- Type
- object
- Description
- Free text describing what the schedule does
- Name
calendarId- Type
- integer required
- Description
- Calendar whose windows drive the schedule. A window is the time between an event's start and end; touching or overlapping events count as one window
- Name
active- Type
- boolean
- Description
- When false the schedule never fires on its own (Run now still works). Re-activating does not fire retroactively
- Name
onStart- Type
- array of object
- Description
- Commands sent, in order, when a calendar window starts
- Name
onEnd- Type
- array of object
- Description
- Commands sent, in order, when a calendar window ends
- Name
attributes- Type
- object
- Description
- Additional custom attributes
- Name
deviceIds- Type
- array of integer
- Description
- Devices linked directly. Managed with `POST`/`DELETE /permissions/bulk`, not in this body
- Name
groupIds- Type
- array of integer
- Description
- Groups linked; every device in them (child groups included) is a target, resolved when the schedule fires
- Name
lastRun- Type
- object
- Description
- Time of the latest run, if any
Response schema
- Name
application/json- Type
- schema
- Description
Responses
- Name
200- Type
- success
- Description
- ScheduledCommand
- Name
400- Type
- error
- Description
- Bad request
- Name
401- Type
- error
- Description
- Unauthorized
- Name
404- Type
- error
- Description
- Not found
Request
PUT
/scheduledcommands/{id}curl --location --request PUT 'https://gw.onemap8.com/api/scheduledcommands/<integer>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": 0,
"name": "<string>",
"description": "<string>",
"calendarId": 0,
"active": true,
"onStart": [
{
"commandId": 0,
"delaySeconds": 0
}
],
"onEnd": [
{}
],
"attributes": {
"queueMaxMinutes": 0
}
}'
Response
{
"id": 0,
"name": "<string>",
"description": "<string>",
"calendarId": 0,
"active": true,
"onStart": [
{
"commandId": 0,
"delaySeconds": 0
}
],
"onEnd": [
{}
],
"attributes": {
"queueMaxMinutes": 0
},
"deviceIds": [
0
],
"groupIds": [
0
],
"lastRun": "<date-time>"
}
DELETE/scheduledcommands/{id}
Delete a Scheduled command
Cancels its pending and queued commands. Its run history is kept until it ages out but can no longer be listed.
Authorizations
BasicAuth or ApiKey
- Name
BasicAuth- Type
- scheme
- Description
- HTTP Authorization Scheme: basic
- Name
ApiKey- Type
- scheme
- Description
- HTTP Authorization Scheme: bearer
Path parameters
- Name
id- Type
- integer required
- Description
Responses
- Name
204- Type
- success
- Description
- No Content
- Name
400- Type
- error
- Description
- Bad request
- Name
401- Type
- error
- Description
- Unauthorized
Request
DELETE
/scheduledcommands/{id}curl --location --request DELETE 'https://gw.onemap8.com/api/scheduledcommands/<integer>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'
Response
No Content
GET/scheduledcommands/{id}/runs
Fetch the run history of a Scheduled command
One entry per device and step sent or skipped, newest first. Delayed steps still waiting for their time are not listed.
Authorizations
BasicAuth or ApiKey
- Name
BasicAuth- Type
- scheme
- Description
- HTTP Authorization Scheme: basic
- Name
ApiKey- Type
- scheme
- Description
- HTTP Authorization Scheme: bearer
Path parameters
- Name
id- Type
- integer required
- Description
Query Parameters
- Name
from- Type
- string <date-time>
- Description
- in ISO 8601 format. eg. `1963-11-22T18:30:00Z`
- Name
to- Type
- string <date-time>
- Description
- in ISO 8601 format. eg. `1963-11-22T18:30:00Z`
- Name
deviceId- Type
- integer
- Description
- Name
limit- Type
- integer
- Description
- Defaults to 200, at most 1000
Response schema
- Name
application/json- Type
- schema
- Description
Responses
- Name
200- Type
- success
- Description
- ScheduledCommandRun
- Name
400- Type
- error
- Description
- No access to this Scheduled command
- Name
401- Type
- error
- Description
- Unauthorized
Request
GET
/scheduledcommands/{id}/runscurl --location 'https://gw.onemap8.com/api/scheduledcommands/<integer>/runs?from=<date-time>&to=<date-time>&deviceId=<integer>&limit=<integer>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'
Response
[
{
"id": 0,
"scheduledCommandId": 0,
"phase": "start",
"deviceId": 0,
"commandId": 0,
"time": "<date-time>",
"status": "pending",
"reason": "<string>"
}
]
POST/scheduledcommands/{id}/run
Run a Scheduled command now
Sends the onStart or onEnd commands immediately to the schedule's current devices, ignoring the calendar. Works even when the schedule is inactive. Steps with a delay stay pending and are sent later; the permissions of the requesting user apply. Returns the runs created.
Authorizations
BasicAuth or ApiKey
- Name
BasicAuth- Type
- scheme
- Description
- HTTP Authorization Scheme: basic
- Name
ApiKey- Type
- scheme
- Description
- HTTP Authorization Scheme: bearer
Path parameters
- Name
id- Type
- integer required
- Description
Query Parameters
- Name
phase- Type
- string required
- Description
Response schema
- Name
application/json- Type
- schema
- Description
Responses
- Name
200- Type
- success
- Description
- ScheduledCommandRun
- Name
400- Type
- error
- Description
- Bad request: invalid `phase`, no access, or a restricted user (`readonly`, `limitCommands`)
- Name
401- Type
- error
- Description
- Unauthorized
Request
POST
/scheduledcommands/{id}/runcurl --location --request POST 'https://gw.onemap8.com/api/scheduledcommands/<integer>/run?phase=<string>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'
Response
[
{
"id": 0,
"scheduledCommandId": 0,
"phase": "start",
"deviceId": 0,
"commandId": 0,
"time": "<date-time>",
"status": "pending",
"reason": "<string>"
}
]