A task represents an operation that takes more time than a user typically wants to wait and is carried out asynchronously.
An example of a task is resetting an aggregate of servers. Resetting all the servers in a group is a time-consuming operation; the user waiting for the result would be blocked from performing other operations. Resource Aggregator for ODIM creates Redfish tasks for such long-duration operations and exposes Redfish TaskService
APIs and Task monitor
API. Use these APIs to manage and monitor the tasks until their completion, while performing other operations.
Supported endpoints
API URI | Operation Applicable | Required privileges |
---|---|---|
/redfish/v1/TaskService | GET | Login |
/redfish/v1/TaskService/Tasks | GET | Login |
/redfish/v1/TaskService/Tasks/{taskId} | GET, DELETE | Login , ConfigureManager |
/redfish/v1/ TaskService/Tasks/{taskId}/SubTasks |
GET | Login |
/redfish/v1/ TaskService/Tasks/{taskId}/SubTasks/ {subTaskId} |
GET | Login |
/taskmon/{taskId} | GET | Login |
NOTE: To view the tasks and the task monitor, ensure that the user has
Login
privilege at the minimum. If you access these endpoints without necessary privileges, you will receive an HTTP403 Forbidden
error.
Config file of ODIMRA is located at: odimra/lib-utilities/config/odimra_config.json
Refer to the section Modifying Configurations in the README.md file to change the configurations of an odimra service.
Specific configurations for Tasks Service are:
/var/log/ODIMRA/task.log
Method | GET |
URI | /redfish/v1/TaskService |
Description | This endpoint retrieves JSON schema for the Redfish TaskService root. |
Returns |
|
Response code | 200 OK |
Authentication | Yes |
curl command
curl -i GET \
-H "X-Auth-Token:{X-Auth-Token}" \
'https://{odimra_host}:{port}/redfish/v1/TaskService'
Sample response header
Allow:GET
Cache-Control:no-cache
Connection:keep-alive
Content-Type:application/json; charset=utf-8
Date:Sun,17 May 2020 15:11:12 GMT+5m 13s
Link:</redfish/v1/SchemaStore/en/TaskService.json>; rel=describedby
Odata-Version:4.0
X-Frame-Options:sameorigin
Transfer-Encoding":chunked
Sample response body
{
"@odata.type":"#TaskService.v1_1_4.TaskService",
"@odata.id":"/redfish/v1/TaskService",
"@odata.context":"/redfish/v1/$metadata#TaskService.TaskService",
"Description":"TaskService",
"Id":"TaskService",
"Name":"TaskService",
"CompletedTaskOverWritePolicy":"Oldest",
"DateTime":"2020-04-17T09:42:04.547136227Z",
"LifeCycleEventOnTaskStateChange":true,
"ServiceEnabled":true,
"Status":{
"Health":"OK",
"HealthRollup":"OK",
"Oem":{
},
"State":"Enabled"
},
"Tasks":{
"@odata.id":"/redfish/v1/TaskService/Tasks"
}
}
Method | GET |
URI | /redfish/v1/TaskService/Tasks |
Description | This endpoint retrieves a list of tasks scheduled by or being executed by Redfish TaskService .NOTE: Only an admin or a user with ConfigureUsers privilege can view all the running and scheduled tasks in Resource Aggregator for ODIM at any given time. Other users can view tasks created only for their operations with Login privilege. |
Returns | A list of task endpoints with task Ids. |
Response code | 200 OK |
Authentication | Yes |
curl command
curl -i GET \
-H "X-Auth-Token:{X-Auth-Token}" \
'https://{odimra_host}:{port}/redfish/v1/TaskService/Tasks'
Sample response body
{
"@odata.type":"#TaskCollection.TaskCollection",
"@odata.id":"/redfish/v1/TaskService/Tasks",
"@odata.context":"/redfish/v1/$metadata#TaskCollection.TaskCollection",
"Name":"Task Collection",
"Members@odata.count":3,
"Members":[
{
"@odata.id":"/redfish/v1/TaskService/Tasks/taskc8cf2e2e-6cb2-4e24-8512-247fa5d606b0"
},
{
"@odata.id":"/redfish/v1/TaskService/Tasks/taskc15aca5a-30a6-4618-adca-c25c889dc409"
},
{
"@odata.id":"/redfish/v1/TaskService/Tasks/task38d6df20-989f-4c05-ad0e-5939774bab7c"
}
]
}
Method | GET |
URI | /redfish/v1/TaskService/Tasks/{TaskID} |
Description | This endpoint retrieves information about a specific task scheduled by or being executed by Redfish TaskService . |
Returns | JSON schema having the details of this task - task Id, name, state of the task, start time and end time of this task, completion percentage, URI of the task monitor associated with this task, subtasks if any. The sample response body given in this section is a JSON response for a task which adds a server. |
Response code | 200 OK |
Authentication | Yes |
curl command
curl -i GET \
-H "X-Auth-Token:{X-Auth-Token}" \
'https://{odimra_host}:{port}/redfish/v1/TaskService/Tasks/{TaskID}'
Sample response body
{
"@odata.type":"#Task.v1_5_1.Task",
"@odata.id":"/redfish/v1/TaskService/Tasks/task2e4b6684-5c6b-4872-bb64-72cf27f3a78f",
"@odata.context":"/redfish/v1/$metadata#Task.Task",
"Id":"task2e4b6684-5c6b-4872-bb64-72cf27f3a78f",
"Name":"Task task2e4b6684-5c6b-4872-bb64-72cf27f3a78f",
"TaskState":"Completed",
"StartTime":"2021-01-21T07:09:03.366954469Z",
"EndTime":"2021-01-21T07:10:30.311241695Z",
"TaskStatus":"OK",
"SubTasks":"",
"TaskMonitor":"/taskmon/task2e4b6684-5c6b-4872-bb64-72cf27f3a78f",
"PercentComplete":100,
"Payload":{
"HttpHeaders":[
"Transfer-Encoding: chunked",
"Cache-Control: no-cache",
"Connection: keep-alive",
"Content-type: application/json; charset=utf-8",
"Link: </redfish/v1/AggregationService/AggregationSources/7b08ecbd-d23e-4dd5-ad99-58ac2be7576d:1/>; rel=describedby",
"Location: /redfish/v1/AggregationService/AggregationSources/7b08ecbd-d23e-4dd5-ad99-58ac2be7576d:1",
"OData-Version: 4.0"
],
"HttpOperation":"POST",
"JsonBody":"{\"HostName\":\"10.24.0.4\",\"Links\":{\"ConnectionMethod\":{\"@odata.id\":\"/redfish/v1/AggregationService/ConnectionMethods/c31a079c-4b69-4b78-b7d5-41d64bed8ea8\"}},\"Password\":\"HP1nvent\",\"UserName\":\"admin\"}",
"TargetUri":"/redfish/v1/AggregationService/AggregationSources"
},
"Messages":[
]
}
Method | GET |
URI | /taskmon/{TaskID} |
Description | This endpoint retrieves the task monitor associated with a specific task. A task monitor allows for polling a specific task for its completion. Perform GET on a task monitor URI to view the progress of a specific task (until it is complete). |
Returns |
|
Response code |
|
Authentication | Yes |
curl command
curl -i GET \
-H "X-Auth-Token:{X-Auth-Token}" \
-H "Content-Type:application/json" \
'https://{odimra_host}:{port}/taskmon/{TaskID}'
Sample response header
Connection:keep-alive
Content-Type:application/json; charset=utf-8
Location:/taskmon/taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70
Odata-Version:4.0
X-Frame-Options:sameorigin
Date:Sun,17 May 2020 14:35:32 GMT+5m 13s
Content-Length:491 bytes
Sample response body (ongoing task)
{
"@odata.type":"#Task.v1_5_1.Task",
"@odata.id":"/redfish/v1/TaskService/Tasks/taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70",
"@odata.context":"/redfish/v1/$metadata#Task.Task",
"Id":"taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70",
"Name":"Task taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70",
"Message":"The task with id taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70 has started.",
"MessageId":"TaskEvent.1.0.3.TaskStarted",
"MessageArgs":[
"taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70"
],
"NumberOfArgs":1,
"Severity":"OK",
"TaskState":"Running",
"StartTime":"2020-04-17T09:39:22.713860589Z",
"EndTime":"0001-01-01T00:00:00Z",
"TaskStatus":"OK",
"SubTasks":"/redfish/v1/Tasks/taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70/SubTasks",
"TaskMonitor":"/taskmon/taskfbd5cdb0-5d33-4ad4-8682-cab90534ba70",
"PercentComplete":8,
"Payload":{
"HttpHeaders":null,
"HttpOperation":"",
"JsonBody":null,
"TargetUri":""
},
"Messages":[
]
}
Sample response body (completed task)
{
"code": "Base.1.11.0.Success",
"message": "Request completed successfully."
}
Sample error response
{
"error":{
"code":"Base.1.11.0.GeneralError",
"message":"one or more of the reset actions failed, check sub tasks for more info."
}
Method | DELETE |
URI | /redfish/v1/TaskService/Tasks/{TaskID} |
Description | This operation deletes a specific task. Deleting a running task aborts the operation being carried out. NOTE: Only a user having ConfigureComponents privilege is authorized to delete a task. If you do not have the necessary privileges, you will receive an HTTP 403 Forbidden error. |
Returns | JSON schema representing the deleted task. |
Response code | 204 No Content |
Authentication | Yes |
curl command
curl -i DELETE \
-H "X-Auth-Token:{X-Auth-Token}" \
'https://{odimra_host}:{port}/redfish/v1/TaskService/Tasks/{TaskID}'