Class: task

Last published : Oct 01, 2026
A longrunning asynchronous task
Related information
XenServer 8.4 Management API

Fields for class: task

Field Type Qualifier Description
allowed_operations task_allowed_operations set RO/runtime list of the operations allowed in this state. This list is advisory only and the server state may have changed by the time this field is read by a client.
backtrace string RO/runtime Function call trace for debugging.
created datetime RO/runtime Time task was created
current_operations (string -> task_allowed_operations) map RO/runtime links each of the running tasks using this object (by reference) to a current_operation enum which describes the nature of the task.
error_info string set RO/runtime if the task has failed, this field contains the set of associated error strings. Undefined otherwise.
finished datetime RO/runtime Time task finished (i.e. succeeded or failed). If task-status is pending, then the value of this field has no meaning
name_description string RO/runtime a notes field containing human-readable description
name_label string RO/runtime a human-readable name
other_config (string -> string) map RO/runtime additional configuration
progress float RO/runtime This field contains the estimated fraction of the task which is complete. This field should not be used to determine whether the task is complete - for this the status field of the task should be used.
resident_on host ref RO/runtime the host on which the task is running
result string RO/runtime if the task has completed successfully, this field contains the result value (either Void or an object reference). Undefined otherwise.
status task_status_type RO/runtime current status of the task
subtask_of task ref RO/runtime Ref pointing to the task this is a substask of.
subtasks task ref set RO/runtime List pointing to all the substasks.
type string RO/runtime if the task has completed successfully, this field contains the type of the encoded result (i.e. name of the class whose reference is in the result field). Undefined otherwise.
uuid string RO/runtime Unique identifier/object reference

RPCs associated with class: task

RPC name: addtootherconfig

Overview:
Add the given keyvalue pair to the otherconfig field of the given task.
Signature:
void add_to_other_config (session ref session_ref, task ref self, string key, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Task object to modify
string key Key to add
string value Value to add
Minimum Role: read-only
Return Type: void

RPC name: cancel

Overview:
Request that a task be cancelled. Note that a task may fail to be cancelled and may complete or fail normally and note that, even when a task does cancel, it might take an arbitrary amount of time.
Signature:
void cancel (session ref session_ref, task ref task)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref task The task
Minimum Role: read-only
Return Type: void
Possible Error Codes: OPERATION_NOT_ALLOWED

RPC name: create

Overview:
Create a new task object which must be manually destroyed.
Signature:
task ref create (session ref session_ref, string label, string description)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string label short label for the new task
string description longer description for the new task
Minimum Role: read-only
Return Type: task ref
The reference of the created task object

RPC name: destroy

Overview:
Destroy the task object
Signature:
void destroy (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
Minimum Role: read-only
Return Type: void

RPC name: getall

Overview:
Return a list of all the tasks known to the system.
Signature:
task ref set get_all (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: task ref set
references to all objects

RPC name: getallrecords

Overview:
Return a map of task references to task records for all tasks known to the system.
Signature:
(task ref -> task record) map get_all_records (session ref session_ref)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
Minimum Role: read-only
Return Type: (task ref -> task record) map
records of all objects

RPC name: getallowedoperations

Overview:
Get the allowedoperations field of the given task.
Signature:
task_allowed_operations set get_allowed_operations (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: task_allowed_operations set
value of the field

RPC name: getbacktrace

Overview:
Get the backtrace field of the given task.
Signature:
string get_backtrace (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getbynamelabel

Overview:
Get all the task instances with the given label.
Signature:
task ref set get_by_name_label (session ref session_ref, string label)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string label label of object to return
Minimum Role: read-only
Return Type: task ref set
references to objects with matching names

RPC name: getbyuuid

Overview:
Get a reference to the task instance with the specified UUID.
Signature:
task ref get_by_uuid (session ref session_ref, string uuid)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
string uuid UUID of object to return
Minimum Role: read-only
Return Type: task ref
reference to the object

RPC name: getcreated

Overview:
Get the created field of the given task.
Signature:
datetime get_created (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: datetime
value of the field

RPC name: getcurrentoperations

Overview:
Get the currentoperations field of the given task.
Signature:
(string -> task_allowed_operations) map get_current_operations (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: (string -> task_allowed_operations) map
value of the field

RPC name: geterrorinfo

Overview:
Get the errorinfo field of the given task.
Signature:
string set get_error_info (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: string set
value of the field

RPC name: getfinished

Overview:
Get the finished field of the given task.
Signature:
datetime get_finished (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: datetime
value of the field

RPC name: getnamedescription

Overview:
Get the name/description field of the given task.
Signature:
string get_name_description (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getnamelabel

Overview:
Get the name/label field of the given task.
Signature:
string get_name_label (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getotherconfig

Overview:
Get the otherconfig field of the given task.
Signature:
(string -> string) map get_other_config (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: (string -> string) map
value of the field

RPC name: getprogress

Overview:
Get the progress field of the given task.
Signature:
float get_progress (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: float
value of the field

RPC name: getrecord

Overview:
Get a record containing the current state of the given task.
Signature:
task record get_record (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: task record
all fields from the object

RPC name: getresidenton

Overview:
Get the residenton field of the given task.
Signature:
host ref get_resident_on (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: host ref
value of the field

RPC name: getresult

Overview:
Get the result field of the given task.
Signature:
string get_result (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getstatus

Overview:
Get the status field of the given task.
Signature:
task_status_type get_status (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: task_status_type
value of the field

RPC name: getsubtaskof

Overview:
Get the subtaskof field of the given task.
Signature:
task ref get_subtask_of (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: task ref
value of the field

RPC name: getsubtasks

Overview:
Get the subtasks field of the given task.
Signature:
task ref set get_subtasks (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: task ref set
value of the field

RPC name: gettype

Overview:
Get the type field of the given task.
Signature:
string get_type (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: getuuid

Overview:
Get the uuid field of the given task.
Signature:
string get_uuid (session ref session_ref, task ref self)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self reference to the object
Minimum Role: read-only
Return Type: string
value of the field

RPC name: removefromotherconfig

Overview:
Remove the given key and its corresponding value from the otherconfig field of the given task. If the key is not in that Map, then do nothing.
Signature:
void remove_from_other_config (session ref session_ref, task ref self, string key)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Task object to modify
string key Key of entry to remove
Minimum Role: read-only
Return Type: void

RPC name: seterrorinfo

Overview:
Set the task error info
Signature:
void set_error_info (session ref session_ref, task ref self, string set value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
string set value Task error info to be set
Minimum Role: read-only
Return Type: void

RPC name: setotherconfig

Overview:
Set the otherconfig field of the given task.
Signature:
void set_other_config (session ref session_ref, task ref self, (string -> string) map value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Task object to modify
(string -> string) map value New value to set
Minimum Role: read-only
Return Type: void

RPC name: setprogress

Overview:
Set the task progress
Signature:
void set_progress (session ref session_ref, task ref self, float value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
float value Task progress value to be set
Minimum Role: read-only
Return Type: void

RPC name: setresult

Overview:
Set the task result
Signature:
void set_result (session ref session_ref, task ref self, string value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
string value Task result to be set
Minimum Role: read-only
Return Type: void

RPC name: setstatus

Overview:
Set the task status
Signature:
void set_status (session ref session_ref, task ref self, task_status_type value)
Arguments:
Type Name Description
session ref session_ref Reference to a valid session
task ref self Reference to the task object
task_status_type value task status value to be set
Minimum Role: read-only
Return Type: void