A task is a schedule that creates jobs. Where a job runs an operation once, a task runs it again and again — every night, every Monday, the first day of every month — creating one job per execution.

POST /v80/operation/tasks

A task wraps a complete job request in its job.request field, so everything you know about jobs applies: the operation name, its parameters, the target, the per-operation timeouts and the callback. What the task adds on top is when and how often.

flowchart LR
    T["Task<br>schedule + job template"] --> J1["Job<br>run 1"]
    T --> J2["Job<br>run 2"]
    T --> JN["Job<br>run N"]
    J1 --> O1["operations<br>per entity"]
    J2 --> O2["operations<br>per entity"]
    JN --> ON["operations<br>per entity"]

The task schedule

Field Purpose
schedule.start First execution. Defaults to now when omitted.
schedule.stop When to stop: a date, a number of executions, or nothing at all — which means forever.
schedule.repeating.period Repeat every n time units.
schedule.repeating.pattern Repeat on a calendar pattern: weekly, monthly or yearly.
active When false, no jobs are launched.
state Current task state: ACTIVE, INACTIVE, FINISHED, CANCELLING, CANCELLED.

Repeating by period

period repeats on a fixed interval — each time units of unit, where unit is one of SECONDS, MINUTES, HOURS or DAYS.

Repeating by calendar pattern

pattern targets specific calendar positions, optionally pinned to a time of day in hh:mm:ssTZD format:

Pattern Fields Values
weekly days MON, TUE, WED, THU, FRI, SAT, SUN — at least one
monthly day, months Day 1–31; months JAN … DEC
yearly day, months Day 1–31; months JAN … DEC

Example: a reboot every Monday and Wednesday at 10:30 UTC, stopping after 10 executions.

{
  "task": {
    "id": "task_1",
    "name": "task_1_name",
    "description": "example task request",
    "active": true,
    "schedule": {
      "start": { "date": "2010-12-11T10:10:00Z" },
      "stop": { "executions": 10 },
      "repeating": {
        "period": { "each": 7, "unit": "DAYS" },
        "pattern": {
          "time": "10:30:00Z",
          "weekly": { "days": ["MON", "WED"] }
        }
      }
    },
    "job": {
      "request": {
        "name": "REBOOT_EQUIPMENT",
        "parameters": { "TYPE": "HARDWARE" },
        "schedule": { "stop": { "delayed": 300000 } },
        "notify": true,
        "operationParameters": {
          "ackTimeout": 5000,
          "timeout": 60000
        },
        "target": { "append": { "entities": ["device_1", "device_2"] } }
      }
    }
  }
}
Scheduling the job of a task

Inside job.request.schedule, the only valid form of start and stop is delayed — an exact date cannot be used, because the task itself decides when each job starts.

If id is omitted at creation, OpenGate generates a UUID. If provided, it must be unique.

Selecting the target

Target selection works exactly as in jobs, inside job.request.target: an explicit list of entities, a tag, or an inlined filter — never a combination of them. The same 300 KByte request size limit applies, and large target lists can be built up with successive PUT requests.

The optional resourceType query string parameter restricts a filter to a single entity type (entity.device, entity.asset, entity.commsModule, entity.subscription, entity.subscriber).

See selecting the target for the full description of the three modes and their limits.

Modifying a task

PUT /v80/operation/tasks/{taskId}

Changes apply to the next executions of the task, never to the job that is already running. This includes appending or removing target entities.

Listing the jobs created by a task

GET /v80/operation/tasks/{taskId}/jobs
GET /v80/tasks/{taskId}/entities

The first endpoint returns the jobs the task has produced, which is how you audit a recurring operation over time. Each of those jobs is read exactly like a standalone job.

Cancelling a task

DELETE /v80/operation/tasks/{taskId}

The task is marked CANCELLED. If the cancellation arrives while one of its jobs is running, the task stays in CANCELLING until that job finishes cancelling all of its operations.

Cancellation does not roll back

As with jobs, cancelling a task does not undo steps already executed on the devices.

Searching tasks

POST /v80/search/tasks

Tasks are searchable with the platform’s standard filter, sort and select clauses. Every field of the task object is available as a filter field, prefixed with tasks. — for example tasks.schedule.repeating.period.unit or tasks.job.request.name. See the API reference for the complete list.