Everything on the jobs and tasks pages describes the north side of the service, the API your back-office application talks to. This page explains what happens on the south side, between OpenGate and the device — because that is what determines how long an operation takes, what progress you can observe, and why an operation can sit in WAITING_FOR_CONNECTION for hours.

Every operation has at least a minimum workflow to be fulfilled. Beyond that minimum, the flow depends on what the device is capable of.

Who starts the conversation

Flow Who initiates When it fits
Platform-driven OpenGate contacts the device The device is reachable and exposes an endpoint
Device-driven The device asks OpenGate for pending operations The device sleeps, sits behind NAT, or has no public address

Device-driven operations are why an operation may report WAITING_FOR_CONNECTION: the work is queued and waiting for the device to show up.

Platform-driven flows

Synchronous

The whole operation is resolved in a single HTTP request and response. The device does the work and answers with the final result:

sequenceDiagram
    participant OG as OpenGate
    participant Dev as Device
    OG->>Dev: Operation request (HTTP POST)
    Note over Dev: executes the operation
    Dev-->>OG: Final response with result and steps (HTTP 201)

Simple and cheap, but it holds the connection for the whole execution — unsuitable for anything slow, such as a firmware download.

Asynchronous with a simple response

The device acknowledges the request immediately and reports the result later, in a request of its own:

sequenceDiagram
    participant OG as OpenGate
    participant Dev as Device
    OG->>Dev: Operation request (HTTP POST)
    Dev-->>OG: ACK (HTTP response)
    Note over Dev: executes the operation
    Dev->>OG: Response notification with result (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)

Asynchronous with multiple responses

The device reports partial progress as it goes, and closes with a final response. This is what makes a long operation observable:

sequenceDiagram
    participant OG as OpenGate
    participant Dev as Device
    OG->>Dev: Operation request (HTTP POST)
    Dev-->>OG: ACK (HTTP response)
    Dev->>OG: Partial response — STEP in progress (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)
    Dev->>OG: Partial response — next STEP (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)
    Dev->>OG: Final response — last STEP and result (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)

Each partial response updates the operation’s steps array, so a north API client polling the job — or receiving callbacks — sees the progress accumulate.

Device-driven flow

The device polls OpenGate for work, executes what it gets, and reports back:

sequenceDiagram
    participant Dev as Device
    participant OG as OpenGate
    Dev->>OG: Ask for pending operations (HTTP GET)
    OG-->>Dev: Pending operation request
    Note over Dev: executes the operation
    Dev->>OG: Response notification with result (HTTP POST)
    OG-->>Dev: ACK (HTTP 200)

Single-step versus multi-step operations

The flow strategy above is about transport. Independently of it, an operation is either atomic or composed of steps:

Structure What the device reports Observability
Simple request/response One result, no intermediate stages Success or failure, nothing in between
Multi-step A declared list of steps, each with its own result and timestamp Progress while the operation runs

A multi-step operation can report all its steps in one response, or spread them across partial responses until the final step is reached. The step list belongs to the operation type definition: it is declared once, and every execution reports against it.

Where to go from here

The diagrams above are summaries. The complete south API — endpoints, ports, request and response schemas, security requirements and the full flow diagrams — lives in the device integration section:

For a real multi-step flow end to end, see the update operation example.