Skip to content

17. Task Service

17.1 Overview

The Redfish Task Service provides a standardized mechanism for monitoring the execution of long-running operations on the ERMI module management controller. Certain commands—such as power control, or system resets—may take several seconds to complete. Instead of blocking the request, the ERMI module returns HTTP 202 Accepted along with a reference to a Task resource. Clients can then poll the Task to observe its progress, completion, or failure.

This session describes the Task Service behavior, API endpoints, error handling, and an example workflow demonstrating how clients can retrieve and monitor tasks using Redfish-compliant interfaces.

17.2 API Endpoints

Method Endpoint Description
GET /redfish/v1/TaskService Retrieve Task Service information.
PATCH /redfish/v1/TaskService Modify Task Service settings.
GET /redfish/v1/TaskService/Tasks List all tasks.
GET /redfish/v1/TaskService/Tasks/{TaskId} Retrieve a specific task information.
DELETE /redfish/v1/TaskService/Tasks/{TaskId} Delete the specific task information..
GET /redfish/v1/TaskService/Tasks/{TaskId}/Monitor Retrieve a specific task status.
HEAD /redfish/v1/TaskService/Tasks/{TaskId}/Monitor Check Task monitor state without body.

Get TaskService Resource

Retrieve the TaskService resource and its current configuration.

URI: /redfish/v1/TaskService

Method: GET

Response:

HTTP Status Code: 200 OK

The response body as below: 

{
  "@odata.id": "/redfish/v1/TaskService",
  "@odata.type": "#TaskService.v1_7_0.TaskService",
  "Id": "TaskService",
  "Name": "Task Service",
  "ServiceEnabled": true,
  "DateTime": "2025-10-29T02:55:12+00:00",
  "CompletedTaskOverWritePolicy": "Oldest",
  "LifeCycleEventOnTaskStateChange": false,
  "Tasks": [
    {
      "@odata.id": "/redfish/v1/TaskService/Tasks"
    }
  ]
}

Response Properties:

Property Type Description
ServiceEnabled boolean Indicates whether event delivery from this service is enabled.
CompletedTaskOverWritePolicy string Defines how the Task Service handles completed tasks when the maximum number of stored tasks is reached. Only support the Oldest that automatically removes the oldest completed task.
LifeCycleEventOnTaskStateChange boolean Indicates whether the Task Service sends a Redfish lifecycle event whenever a task changes its state.
true: An event is emitted for each task state transition.
false: No events are generated; clients must poll the task instead.

Modify the TaskService Resource

Modify writable properties of the TaskService.

URI: /redfish/v1/TaskService

Method: PATCH

Request Example Body

{
    "ServiceEnabled": false,
    "LifeCycleEventOnTaskStateChange": true
}

Response:

HTTP Status Code: 204 No Content

If the operation is successful, a status code 204 No Content will be returned.

HTTP Status Code: 400 Bad Request

If the paramter of the request body is invalid, a status code 400 Bad Request will be returned.

Get TaskService Collection

Retrieve a list of current tasks.

URI: /redfish/v1/TaskService/Tasks

Method: GET

Response:

HTTP Status Code: 200 OK

The response body as below: 

{
  "@odata.id": "/redfish/v1/TaskService/Tasks",
  "@odata.type": "#TaskCollection.TaskCollection",
  "Members@odata.count": 1,
  "Name": "Task Collection",
  "Members": [
    {
      "@odata.id": "/redfish/v1/TaskService/Tasks/Task_1"
    }
  ]
}

Get a Specified Task

Retrieve details for a specific task.

URI: /redfish/v1/TaskService/Tasks/{TaskId}

Method: GET

Response:

HTTP Status Code: 200 OK

The response body as below: 

{
  "@odata.id": "/redfish/v1/TaskService/Tasks/Task_001",
  "@odata.type": "#Task.v1_7_0.Task",
  "Id": "Task_001",
  "Name": "TaskName",
  "TaskState": "New",
  "TaskStatus": "OK",
  "StartTime": "2025-01-01T00:12:58Z",
  "EndTime": "",
  "TaskMonitor": "/redfish/v1/TaskService/Tasks/Task_001/Monitor",
  "Messages": [
    {
      "Message": "Test123"
    }
  ]
}

Response Properties:

Property Type Description
Id string The unique identifier of the task.
Name string A human-readable name for the task.
TaskState string The current execution state of the task (e.g., New, Running, Completed, Killed).
TaskStatus string The health or status of the task (e.g., OK, Warning, Failed).
StartTime string The timestamp when the task was created or began execution, in ISO8601 format.
EndTime string The timestamp when the task completed. Empty if the task is still running or pending.
TaskMonitor string A URI that clients can poll to track task progress. This endpoint typically returns the task status or HTTP status codes reflecting its completion state.
Messages array An array of messages that provide additional details about the task outcome or intermediate state (e.g., informational or error messages).
HTTP Status Code: 404 Not Found

The specified task information could not be found, the service will respond with HTTP status code 404 Not Found.

Delete the Specified Task

Delete a subscription.

URI: /redfish/v1/TaskService/Tasks/{TaskId}

Method: DELETE

Response:

HTTP Status Code: 204 No Content

If the operation is successful, a status code 204 No Content will be returned.

HTTP Status Code: 404 Not Found

The specified task could not be found, the service will respond with HTTP status code 404 Not Found.

Retrieve the Specified Task Status

Retrieve the specified task status.

URI: /redfish/v1/TaskService/Tasks/{TaskId}/Monitor

Method: GET

Response:

HTTP Status Code: 200 OK

The response body as below: 

{
  "@odata.id": "/redfish/v1/TaskService/Tasks/Task_001",
  "@odata.type": "#Task.v1_7_0.Task",
  "Id": "Task_001",
  "Name": "TaskName",
  "TaskState": "New",
  "TaskStatus": "OK",
  "StartTime": "2025-01-01T00:12:58Z",
  "EndTime": "",
  "TaskMonitor": "/redfish/v1/TaskService/Tasks/Task_001/Monitor",
  "Messages": [
    {
      "Message": "Test123"
    }
  ]
}

Response Properties:

Property Type Description
Id string The unique identifier of the task.
Name string A human-readable name for the task.
TaskState string The current execution state of the task (e.g., New, Running, Completed, Killed).
TaskStatus string The health or status of the task (e.g., OK, Warning, Failed).
StartTime string The timestamp when the task was created or began execution, in ISO8601 format.
EndTime string The timestamp when the task completed. Empty if the task is still running or pending.
TaskMonitor string A URI that clients can poll to track task progress. This endpoint typically returns the task status or HTTP status codes reflecting its completion state.
Messages array An array of messages that provide additional details about the task outcome or intermediate state (e.g., informational or error messages).
HTTP Status Code: 404 Not Found

The specified task could not be found, the service will respond with HTTP status code 404 Not Found.

Retrieve the Specified Task Status Without Body

Retrieve the specified task status without body.

URI: /redfish/v1/TaskService/Tasks/{TaskId}/Monitor

Method: HEAD

Response:

HTTP Status Code: 200 OK

The specified task is completed, the service will respond with HTTP status code 200 OK.

HTTP Status Code: 202 Accepted

The specified task is running, the service will respond with HTTP status code 202 Accepted.

HTTP Status Code: 404 Not Found

The specified task could not be found, the service will respond with HTTP status code 404 Not Found.

HTTP Status Code: 500 Internal Server Error

If an internal server error occurs while retrieving task state or the task encounters some error, the service will respond with HTTP status code 500 Internal Server Error.

17.3 Step-by-Step: Monitoring a Task

This example demonstrates the complete workflow of issuing a long-running command and polling the Task status.

Step 1 — Client Sends a Command (e.g., Power On)

POST /redfish/v1/Systems/{id}/Actions/ComputerSystem.Reset

The request body as below: 

{
    "ResetType": "On"
}

Step 2 — ERMI Returns a Task Reference

If the Power On command is successful, the ERMI will return 202 Accepted status code, and the response body as below: 

{
  "@odata.id": "/redfish/v1/TaskService/Tasks/PowerOn_001",
  "@odata.type": "#Task.v1_7_0.Task",
  "Id": "PowerOn_001",
  "Name": "PowerOn",
  "TaskState": "New",
  "TaskStatus": "OK",
  "StartTime": "2025-01-01T00:12:58Z",
  "EndTime": "",
  "TaskMonitor": "/redfish/v1/TaskService/Tasks/PowerOn_001/Monitor",
  "Messages": []
}

Step 3 — Poll the Task Using GET

GET /redfish/v1/TaskService/Tasks/PowerOn_001

The response body as below: 

{
  "@odata.id": "/redfish/v1/TaskService/Tasks/PowerOn_001",
  "@odata.type": "#Task.v1_7_0.Task",
  "Id": "PowerOn_001",
  "Name": "PowerOn",
  "TaskState": "Running",
  "TaskStatus": "OK",
  "StartTime": "2025-01-01T00:12:58Z",
  "EndTime": "",
  "TaskMonitor": "/redfish/v1/TaskService/Tasks/PowerOn_001/Monitor",
  "Messages": []
}

Step 4 — Optionally Use HEAD for Lightweight Polling

HEAD /redfish/v1/TaskService/Tasks/PowerOn_001

Possible results:

  • 200 OK: Task completed.
  • 202 Accepted: Task is still running.
  • 404 Not Found: The specified task could not be found.
  • 500 Internal Server Error: The task encounters some error.

Step 5 — The Task Completes

GET /redfish/v1/TaskService/Tasks/PowerOn_001

The response body as below: 

{
  "@odata.id": "/redfish/v1/TaskService/Tasks/PowerOn_001",
  "@odata.type": "#Task.v1_7_0.Task",
  "Id": "PowerOn_001",
  "Name": "PowerOn",
  "TaskState": "Completed",
  "TaskStatus": "OK",
  "StartTime": "2025-01-01T00:12:58Z",
  "EndTime": "2025-01-01T00:13:58Z",
  "TaskMonitor": "/redfish/v1/TaskService/Tasks/PowerOn_001/Monitor",
  "Messages": []
}

Step 6 — Client Deletes the Task (Optional)

DELETE /redfish/v1/TaskService/Tasks/PowerOn_001

Next section