Jobs

A job is one execution of an operation type over a target set of entities. Creating a job is the normal way to run an operation: you POST a job request, and OpenGate turns it into one operation per target entity.

POST /v80/operation/jobs

Anatomy of a job request

Selecting the target

There are three ways to reference the entities a job acts on, and they are mutually exclusive — a single job cannot mix entity lists, tags and filters.

An explicit list of entities

"target": { "append": { "entities": ["device_1", "device_2"] } }

The same parametrization is applied to every entity in the list. Two limits apply:

• Entities per array: 100 by default.
• Request body size: 300 KBytes by default.

Both are configurable per platform, so check the values with your administrator. To launch an operation over a larger list, create the job with active set to false and use PUT requests to append entities in batches, activating the job in the last call.

A tag

"target": { "append": { "tags": ["fleet_north"] } }

Only one tag name can be passed. OpenGate resolves the tag into the target set and builds the internal structure of the job; when that work finishes the job waits in IDLE if it is not active, or in SCHEDULED if it is.

A filter

"target": { "append": { "filter": { "eq": { "device.model": "MDL-1" } } } }

The filter is evaluated by the platform to resolve the target set. Previously created filters cannot be reused here — the filter must be inlined in the request.

The optional resourceType query string parameter restricts the filter to one entity type:

Scheduling

The schedule block controls when the job runs. start accepts either an exact date or a delayed value in milliseconds; stop sets the deadline after which pending operations are cancelled.

Two optional modes refine how the operations are distributed inside that window.

Window

window restricts execution to given weekdays and a daily time range — useful when field interventions are only acceptable during a maintenance window.

Periods must be whole hours; intermediate periods are rejected:

Scattering

scattering spreads the individual operations across the available time instead of firing them all at once. It exists to protect shared infrastructure — typically a mobile operator cell that would collapse if thousands of devices woke up simultaneously.

Per-operation timeouts and retries

operationParameters applies to each individual operation, not to the job as a whole:

Job life cycle

A job’s status reflects the aggregate progress of all its operations:

stateDiagram-v2
    direction TB
    [*] --> IDLE: active=false
    [*] --> SCHEDULED: active=true<br>start delayed
    [*] --> IN_PROGRESS: active=true<br>start now

    IDLE --> SCHEDULED: active=true<br>start delayed
    IDLE --> IN_PROGRESS: active=true<br>start now
    SCHEDULED --> IDLE: active=false
    SCHEDULED --> IN_PROGRESS: start time<br>reached

    IN_PROGRESS --> PAUSED: active=false
    PAUSED --> IN_PROGRESS: active=true

    IN_PROGRESS --> FINISHED: all ok
    IN_PROGRESS --> FINISHED_WITH_ERRORS: with errors
    IN_PROGRESS --> CANCELLING_BY_USER: cancelled<br>by a user
    IN_PROGRESS --> CANCELLING_BY_ENGINE: timeout<br>reached
    SCHEDULED --> CANCELLING_BY_USER: cancelled<br>by a user
    CANCELLING_BY_USER --> CANCELLED: all operations<br>cancelled
    CANCELLING_BY_ENGINE --> TIMEOUT_CANCELLED: all operations<br>cancelled

    FINISHED --> [*]
    FINISHED_WITH_ERRORS --> [*]
    TIMEOUT_CANCELLED --> [*]
    CANCELLED --> [*]

Both cancelling states are transient: the job stays there until every one of its operations has finished cancelling, which on a job targeting thousands of entities is not instant.

See the status reference for the complete list of job, operation and step values.

Reading the result

An execution involves as many entities as the target references, so one job explodes into many results. The API exposes both levels:

flowchart LR
    JOB["Job"] --> SUM["report.summary<br>one aggregated view<br>counters per state"]
    JOB --> RES["operations<br>one result per entity<br>status, result, steps"]

The per-entity list is paginated with start and size parameters — necessary when a job targets thousands of entities. Each operation object carries its own status, result, description and steps array.

To be notified when the job starts and when it finishes instead of polling these endpoints, configure a callback.

Updating a job

PUT /v80/operation/jobs/{jobId}

A job can only be modified while active is false and it has not started. What you can change:

• Request fields: active, notify, callback, userNotes, schedule.start, schedule.stop.
• The target entity list, by appending or removing entities.

The same JSON size limit as in creation applies. In the last PUT, set active to true to start the execution.

Pause and resume

The same endpoint controls a running job through the active field:

• Pause: set active to false on a job in IN_PROGRESS. The job moves to PAUSED. While paused, the job’s features cannot be modified.
• Resume: set active to true on a paused job. The job returns to IN_PROGRESS.

Cancelling a job

DELETE /v80/operation/jobs/{jobId}

The job moves to CANCELLING_BY_USER first — or to CANCELLING_BY_ENGINE when the platform itself cancels it — and to CANCELLED once all of its operations are cancelled.

Searching jobs and operations

Job and operation searches follow the platform’s standard search pattern, with support for filtering, sorting, field selection and summaries:

POST /v80/search/jobs
POST /v80/search/jobs/summary
POST /v80/search/entities/devices/operations
POST /v80/search/entities/operations/history

Equivalent endpoints exist for subscribers and subscriptions. Results are returned as JSON by default, or as CSV through HTTP header options. The full parameter list is in the API reference.