Task Manager Create Task

Task Manager Create Task

Creates a new Task, specifying the object with which the Task is associated, the type of task, and whether the task is cancelable.

Use this operation in conjunction with the ExtensionManager.

Required privileges: Task.Create

Request
URI
POST
https://{vcenter-host}/sdk/vim25/{release}/TaskManager/{moId}/CreateTask
COPY
Path Parameters
string
moId
Required

The unique identifier for the managed object to which the method attaches; the serialized managed object reference for a request has the form moType/moId, in this case TaskManager/{moId}.

string
release
Required

The vSphere release schema. The current specification covers vSphere 8.0.2.0 APIs.


Request Body
CreateTaskRequestType of type(s) application/json
Required
{
    "obj": {
        "_typeName": "string",
        "type": "string",
        "value": "string"
    },
    "taskTypeId": "string",
    "initiatedBy": "string",
    "cancelable": false,
    "parentTaskKey": "string",
    "activationId": "string"
}
obj
Required

The ManagedObjectReference data object type is a special-purpose data object. Commonly referred to as simply a "reference", "MoRef", "MOR", or other variations of this theme, instances of managed object references contain data that identifies specific server-side managed objects. Managed object references are typically one of the return types from a method invocation.

Managed object references are client application references to server-side managed objects. The client application uses ManagedObjectReference objects when it invokes operations on a server. A ManagedObjectReference is guaranteed to be unique and persistent during an object's lifetime. The reference persists after an object has moved within the inventory, across sessions, and across server restarts. If you remove an object, for example, a virtual machine, from the inventory, and then put it back, the reference changes.

string
taskTypeId
Required

Extension registered task type identifier for type of task being created

string
initiatedBy
Optional

The name of the user on whose behalf the Extension is creating the task

boolean
cancelable
Required

True if the task should be cancelable, false otherwise

string
parentTaskKey
Optional

Key of the task that is the parent of this task

string
activationId
Optional

Activation Id is a client-provided token to link an API call with a task. When provided, the activationId is added to the TaskInfo

Authentication
This operation uses the following authentication methods.
Responses
200

TaskInfo data object describing the new task

Returns TaskInfo of type(s) application/json
This response body class contains all of the following: DataObject
{
    "_typeName": "string",
    "key": "string",
    "task": {
        "_typeName": "string",
        "type": "string",
        "value": "string"
    },
    "description": {
        "_typeName": "string",
        "key": "string",
        "arg": [
            {
                "_typeName": "string",
                "key": "string",
                "value": {
                    "_typeName": "string"
                }
            }
        ],
        "message": "string"
    },
    "name": "string",
    "descriptionId": "string",
    "entity": {
        "_typeName": "string",
        "type": "string",
        "value": "string"
    },
    "entityName": "string",
    "locked": [
        {
            "_typeName": "string",
            "type": "string",
            "value": "string"
        }
    ],
    "state": "string",
    "cancelled": false,
    "cancelable": false,
    "error": {
        "_typeName": "string",
        "faultCause": "MethodFault Object",
        "faultMessage": [
            {
                "_typeName": "string",
                "key": "string",
                "arg": [
                    {
                        "_typeName": "string",
                        "key": "string",
                        "value": {
                            "_typeName": "string"
                        }
                    }
                ],
                "message": "string"
            }
        ]
    },
    "result": {
        "_typeName": "string"
    },
    "progress": 0,
    "progressDetails": [
        {
            "_typeName": "string",
            "key": "string",
            "value": {
                "_typeName": "string"
            }
        }
    ],
    "reason": {
        "_typeName": "string"
    },
    "queueTime": "string",
    "startTime": "string",
    "completeTime": "string",
    "eventChainId": 0,
    "changeTag": "string",
    "parentTaskKey": "string",
    "rootTaskKey": "string",
    "activationId": "string"
}
string
key
Required

The unique key for the task.

task
Required

Reference to an instance of the Task managed object.

description
Optional

Message data which is intended to be displayed according to the locale of a client.

A LocalizableMessage contains both a formatted, localized version of the text and the data needed to perform localization in conjunction with localization catalogs.

Clients of the VIM API may use vim.SessionManager.setLocale() to cause the server to emit a localized message, or may perform client-side localization based on message catalogs provided by the server.

  • If the substition variable is a string, no further lookup is required.
    • arg = [("address" = "127.0.0.1")]
    • CATALOG(locmsg, key) = "IP address is {address}"
    • ==> message = "IP address is 127.0.0.1"
  • If the substitution variable is an integer, value is a lookup key.
    • arg = [("1" = "button.cancel"), ("2" = "msg.revert")]
    • CATALOG(locmsg, key) = "Select '{1}' to {2}"
    • CATALOG(locmsg, button.cancel) = "Cancel"
    • CATALOG(locmsg, msg.revert) = "revert"
    • ==> message = "Select 'Cancel' to revert"
  • If the variable contains '@', value is a label lookup in another catalog, where {[email protected]} looks up prefix.arg[name].label in CATALOG.
    • arg = [("field" = "queued")]
    • CATALOG(locmsg, key) = "State is {[email protected]}"
    • CATALOG(enum, TaskInfo.State.queued.label) is "Queued"
    • ==> message = "State is Queued"
string
name
Optional

The name of the operation that created the task.

This is not set for internal tasks.

string
descriptionId
Required

An identifier for this operation.

This includes publicly visible internal tasks and is a lookup in the TaskDescription methodInfo data object.

entity
Optional

Reference to an instance of the ManagedEntity managed object.

string
entityName
Optional

The name of the managed entity, locale-specific, retained for the history collector database.

locked
Optional

If the state of the task is "running", then this property is a list of managed entities that the operation has locked, with a shared lock.

state
Required

List of possible states of a task.

Possible values:

  • queued: When there are too many tasks for threads to handle.

  • running: When the busy thread is freed from its current task by finishing the task, it picks a queued task to run.

    Then the queued tasks are marked as running.

  • success: When a running task has completed.

  • error: When a running task has encountered an error.

Possible values are : queued, running, success, error,
boolean
cancelled
Required

Flag to indicate whether or not the client requested cancellation of the task.

boolean
cancelable
Required

Flag to indicate whether or not the cancel task operation is supported.

error
Optional

The base data object type for all the object model faults that an application might handle.

result
Optional

The base of all data types. Not to be used directly on the wire.

integer As int32 As int32
progress
Optional

If the task state is "running", then this property contains a progress measurement, expressed as percentage completed, from 0 to 100.

If this property is not set, then the command does not report progress.

progressDetails
Optional

Since: vSphere API Release 8.0.1.0

reason
Required

Base type for all task reasons.

Task reasons represent the kind of entity responsible for a task's creation.

string As date-time As date-time
queueTime
Required

Time stamp when the task was created.

string As date-time As date-time
startTime
Optional

Time stamp when the task started running.

string As date-time As date-time
completeTime
Optional

Time stamp when the task was completed (whether success or failure).

integer As int32 As int32
eventChainId
Required

Event chain ID that leads to the corresponding events.

string
changeTag
Optional

The user entered tag to identify the operations and their side effects

string
parentTaskKey
Optional

Tasks can be created by another task.

This shows TaskInfo.key of the task spun off this task. This is to track causality between tasks.

string
rootTaskKey
Optional

Tasks can be created by another task and such creation can go on for multiple levels.

This is the TaskInfo.key of the task that started the chain of tasks.

string
activationId
Optional

The activation Id is a client-provided token to link an API call with a task.