# Status reference

Every value OpenGate can report about an operation, in one place. Use this page when you are reading a
job report, a per-entity result or a [callback](../callbacks/) payload and need to know what a value
means.

Three levels report status independently, and they answer different questions:

```mermaid
flowchart LR
    J["Job status<br>how is the whole execution going?"] --> O["Operation status and result<br>what happened on this entity?"]
    O --> S["Step results<br>which stages ran, and how?"]
```

## Job status

The aggregate state of a job, in `report.summary.status`. See the
[job life cycle](../jobs/#job-life-cycle) for the transitions between them.

| Value | Meaning |
|---|---|
| `IDLE` | The job has been created but not started, because it is not active. |
| `SCHEDULED` | The job is active and waiting for its scheduled start. |
| `IN_PROGRESS` | The job has started. |
| `PAUSED` | The job has been paused by setting `active` to `false` while running. |
| `FINISHED` | All operations in the job have finished. |
| `FINISHED_WITH_ERRORS` | The job finished with errors. Some operations may have succeeded while others failed or were cancelled, or all of them may have failed. `errorCode` and `errorDescription` are present in the summary. |
| `TIMEOUT_CANCELLED` | The job was cancelled because the maximum timeout defined expired. |
| `CANCELLING_BY_USER` | A user cancelled the job, and it is still cancelling its operations. |
| `CANCELLING_BY_ENGINE` | The job's **timeout was reached**, and it is still cancelling its operations. |
| `CANCELLED` | The job and all of its operations have been cancelled. |

{{% notice style="info" title="Cancellation records who caused it" icon="lightbulb" %}}
There is no plain `CANCELLING`: a job in the middle of cancelling always reports which side started it,
`CANCELLING_BY_USER` or `CANCELLING_BY_ENGINE`. The two differ in cause, not in mechanics — a user asked, or
the timeout ran out — and the same distinction appears at operation level in the `finished.cancelled`
counters.
{{% /notice %}}

## Operation status

The state of the operation on **one** entity, in each element of the operations list.

| Value | Meaning |
|---|---|
| `PENDING` | The operation is pending to be started. |
| `QUEUED` | The operation has been launched but has not reached the device yet. |
| `WAITING_FOR_ACK` | The operation is waiting for an acknowledgement from the device to be started. |
| `WAITING_FOR_CONNECTION` | The operation is waiting for the device to connect, when that option is enabled. |
| `IN_PROGRESS` | The operation has started and is waiting for completion. |
| `FINISHED` | The operation has been completed. |
| `FINISHED_OUT_OF_TIME` | The operation finished and its result was collected, but outside the allowed time. |
| `TIMEOUT_CANCELLED` | The operation was cancelled because the maximum timeout defined expired. |
| `NOT_ALLOWED` | The operation cannot be executed over this entity. |
| `CANCELLED` | The operation has been cancelled. |

## Operation result

Why an operation ended the way it did, in the `result` field. A `FINISHED` status with a non-successful
`result` is normal: the execution completed, the outcome was negative.

| Value | Meaning |
|---|---|
| `SUCCESSFUL` | The operation completed with success. |
| `PARTIAL_SUCCESS` | The operation completed with partial success. |
| `OPERATION_PENDING` | The operation is queued to be executed. |
| `ERROR_IN_PARAM` | The operation cannot be executed because of an error in the parameters passed. |
| `NOT_ALLOWED` | The operation execution is not allowed for this entity. |
| `NOT_SUPPORTED` | The operation is not supported by the entity. |
| `ALREADY_IN_PROGRESS` | The operation is already being executed. |
| `ERROR_PROCESSING` | The operation finished with an unknown error. |
| `ERROR_TIMEOUT` | The operation could not be completed because the device response timed out. |
| `TIMEOUT_CANCELLED` | The operation was cancelled because the maximum timeout defined expired. |
| `CANCELLED` | The operation was cancelled by a user or through the API. |
| `CANCELLED_INTERNAL` | The operation was cancelled by the internal engine. Consult your platform administrator. |
| `UNKNOWN_RESULT` | The operation returned a result the platform does not recognize. Consult your platform administrator. |

{{% notice style="info" title="Retry policy" icon="lightbulb" %}}
Any of these results can be listed in the job's `operationParameters.retryResultList` to trigger a
retry. `ERROR_TIMEOUT` is always part of that list, whether you include it or not.
{{% /notice %}}

## Step result

Each element of an operation's `steps` array carries a `name`, a `timestamp`, an optional
`description`, an optional `response`, and one of:

| Value | Meaning |
|---|---|
| `SUCCESSFUL` | The step completed successfully. |
| `ERROR` | The step failed. |
| `SKIPPED` | The step was skipped. |
| `NOT_EXECUTED` | The step did not run. |

Not every declared step appears in every execution: a device only reports the steps it actually goes
through. See [execution flows](../flows/) for how steps are reported.

## Task state

The state of a [task](../tasks/), in its `state` field.

| Value | Meaning |
|---|---|
| `ACTIVE` | The task is launching jobs according to its schedule. |
| `INACTIVE` | The task exists but launches no jobs, because `active` is `false`. |
| `FINISHED` | The task reached its stop condition — its end date or its number of executions. |
| `CANCELLING` | The task has been cancelled and one of its jobs is still finishing. |
| `CANCELLED` | The task has been cancelled. |

## Job summary counters

`report.summary` counts the operations of a job by state. The counters are what tell you whether a
`FINISHED` job actually did what you wanted.

| Counter | Contains |
|---|---|
| `total` | Total operations attempted. |
| `inProgress.total` | Operations not finished yet. |
| `inProgress.scheduled` | Operations scheduled but not launched. |
| `inProgress.pendingExecution` | Operations queued for execution. |
| `inProgress.waitingForConnection` | Operations waiting for the device to appear. |
| `inProgress.started` | Operations already started. |
| `finished.total` | Operations that reached a final state. |
| `finished.successful` | Operations that finished successfully. |
| `finished.error` | Operations that finished with an error. |
| `finished.cancelled.total` | Cancelled operations, broken down by cause below. |
| `finished.cancelled.byUser` | Cancelled by a user or through the API. |
| `finished.cancelled.byEngine` | Cancelled by the platform engine. |
| `finished.cancelled.byTimeout` | Cancelled because the operation timeout expired. |
| `finished.cancelled.byExternalTimeout` | Cancelled because an external system timed out. |
| `finished.cancelled.byExternal` | Cancelled by an external system. |
| `finished.cancelled.byAlreadyInProgress` | Cancelled because the same operation was already running on that entity. |
| `finishedOutOfTime.total` | Operations whose result arrived outside the allowed time. |
| `finishedOutOfTime.successful` | Of those, the ones that succeeded. |
| `finishedOutOfTime.error` | Of those, the ones that failed. |
| `errorCode`, `errorDescription` | Present only when the job status is `FINISHED_WITH_ERRORS`. |

Every counter above is also available as a search filter field, prefixed with
`jobs.report.summary.` — so you can query, for example, all jobs with
`jobs.report.summary.finished.cancelled.byTimeout` greater than zero. See the
[API reference](../api_reference/) for the complete field list.