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 payload and need to know what a value means.

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

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 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.
Cancellation records who caused it

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.

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.
Retry policy

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.

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 for how steps are reported.

Task state

The state of a task, 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 for the complete field list.