Advance a Task Run to its next phase

POST

https://nico-rest-api.nico.svc.cluster.local/v2/org/:org/nico/task/run/:id/advance

POST

/v2/org/:org/nico/task/run/:id/advance

$ curl -X POST https://nico-rest-api.nico.svc.cluster.local/v2/org/org/nico/task/run/id/advance \
>      -H "Authorization: Bearer <token>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "siteId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
> }'

1 {
2   "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
3   "name": "Firmware Upgrade Phase 2",
4   "operationType": "FirmwareControl",
5   "status": "Paused",
6   "statusReason": "PhaseGate",
7   "totalPhases": 3,
8   "created": "2024-01-15T09:30:00Z",
9   "updated": "2024-01-15T10:15:00Z",
10   "description": "Advancing to the next phase of the firmware upgrade task run.",
11   "operationCode": "upgrade",
12   "statusMessage": "Task run is paused at phase gate awaiting advance.",
13   "started": "2024-01-15T09:45:00Z",
14   "finished": "null",
15   "stats": {
16     "currentPhase": {
17       "phaseIndex": 1,
18       "selectedTargets": 25,
19       "outcomeCounts": {
20         "completed": 20,
21         "failed": 2,
22         "terminated": 1,
23         "skipped": 2
24       }
25     },
26     "cumulativePhase": {
27       "phaseIndex": 1,
28       "selectedTargets": 50,
29       "outcomeCounts": {
30         "completed": 45,
31         "failed": 3,
32         "terminated": 1,
33         "skipped": 1
34       }
35     }
36   }
37 }

Open the next phase of a Task Run that is paused at a phase gate. Optionally guard the transition with expectedPhaseIndex: when set, the phase that would be opened must match, otherwise Flow rejects the advance so a stale client cannot open the wrong phase.

Task Runs are site-scoped; siteId must be the Site that owns the Task Run. Org must have an Infrastructure Provider entity. User must have authorization role with PROVIDER_ADMIN suffix.

Open the next phase of a Task Run that is paused at a phase gate. Optionally guard the transition with `expectedPhaseIndex`: when set, the phase that would be opened must match, otherwise Flow rejects the advance so a stale client cannot open the wrong phase. Task Runs are site-scoped; `siteId` must be the Site that owns the Task Run. Org must have an Infrastructure Provider entity. User must have authorization role with `PROVIDER_ADMIN` suffix.

Authentication

AuthorizationBearer

export JWT_BEARER_TOKEN="<jwt-bearer-token>"
# Example org name: "acme-inc
export ORG_NAME=<org-name>
# Use the JWT bearer token in your API request auth header:
curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current

``` export JWT_BEARER_TOKEN="<jwt-bearer-token>" # Example org name: "acme-inc export ORG_NAME=<org-name> # Use the JWT bearer token in your API request auth header: curl -v -X GET -H "Content-Type: application/json" -H "Authorization: Bearer $JWT_BEARER_TOKEN" https://nico-rest-api.nico.svc.cluster.local/v2/org/$ORG_NAME/nico/user/current ```

Path parameters

orgstringRequired

Name of the Org

idstringRequiredformat: "uuid"

UUID of the Task Run

Request

This endpoint expects an object.

siteIdstringRequiredformat: "uuid"

ID of the Site that owns the Task Run.

expectedPhaseIndexintegerOptional

Optional guard: when set, the phase that would be opened must match this zero-based index, otherwise the advance is rejected.

Response

Accepted. The advance request was accepted and the Task Run's last known state is returned.

idstringformat: "uuid"

Unique identifier of the Task Run.

namestring

Human-readable name of the Task Run.

operationTypeenum

Type of operation this Task Run executes. Currently always FirmwareControl.

statusenum

Current lifecycle state of the Task Run.

statusReasonenum

Why the Task Run is paused or terminal (e.g. PhaseGate, SafetyGate). None when there is no qualifying reason.

totalPhasesinteger

Total number of phases the selected targets were divided into.

createddatetime

Timestamp when the Task Run was created.

updateddatetime

Timestamp when the Task Run was last updated.

descriptionstring

Optional free-form description.

operationCodestring

Operation code within the operation type (e.g. upgrade).

statusMessagestring

Optional human-readable detail for the current status.

starteddatetime or null

Timestamp when the Task Run started execution. Null before it starts.

finisheddatetime or null

Timestamp when the Task Run reached a terminal state. Null while active.

statsobject

Derived per-phase outcome stats. Present only on the single-Task-Run GET when includeStats=true; omitted otherwise.

Errors

400

Bad Request Error

403

Forbidden Error

404

Not Found Error