Methods for working with tasks

The tasks are used for processing requests that are time consuming and run asynchronously. Task statuses allow you to monitor the progress of actions specified in the request.

A task may have one of the following states:

• Created – task is created but not started.
• Starting – the task is in the process of starting.
• Running – the task is running. For a task in this state, the execution progress is displayed as a percent value.
• Completed – the task has been successfully completed. For a task in this state, the task execution result is displayed. The result contains task-specific data, for example, the identifier of a new tenant after the CreateTenant task completes.
• Stopping – the task is being prepared for completion. If you stopped a task, it may be in this state before switching to the Canceled state.
• Failed – the task failed. For a task in this state, detailed error information is indicated.
• Canceled – the task is terminated by the user or the system. For a task in this state, detailed error information is indicated.
• Queued – the task has been queued and is waiting for execution to start.

By means of the Integration Server REST API, you can perform the following tasks:

• Get a list of tasks
• Get information about a specified task
• Cancel execution of a specified task

Getting task information

Allows you to get information about the task by its identifier.

Method:

GET /api/2.0/virtualization/tasks/{ID}

where:

{ID} – task identifier (required parameter).

In case of successful completion of the request, the REST API returns the following information about the task:

<task id="{ID}" created="{date and time}" stateChanged="{date and time}" changed="{date and time}">

<state>{state}</state>

<type>{type}</type>

<stage>{stage}</stage>

<progress>{execution progress}</progress>

<result>{result}</result>

<!-- If the task execution fails, an error message is displayed instead of the result.

<error>{error message}</error>

</task>

where:

• {ID} – task ID.
• created="{date and time}" – task creation time in YYYY-MM-DDThh:mm:ss format.
• stateChanged="{date and time}" – time of the task state change in YYYY-MM-DDThh:mm:ss format.
• changed="{date and time}" – task change time in YYYY-MM-DDThh:mm:ss format.
• {state} – task state.
• {type} – task type. For example:
  • CreateTenant – a task that is used in the tenant creation procedure.
  • ChangeTenantActivation – a task that is used in tenant activation and deactivation procedures.
  • DeleteTenant – a task that is used in the tenant deletion procedure.
  • CreateTenantReport – a task that is used in the procedure for generating a tenant protection report.
• {name} – task name.
• {stage} – task execution stage.
• {execution progress} – the progress of task execution indicated as a percentage.
• {result} – result of executing the task, for example, information about a created tenant or a report identifier.
• {error message} – if an error occurs during task execution, an error message is displayed.

Return codes:

• 200 (OK) – request completed successfully.
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) – task with the specified identifier is not found in the Integration Server database.

Getting a list of tasks

Allows you to get a list of all existing tasks and information about each task in the list.

Method:

GET /api/2.0/virtualization/tasks?createdFrom={date and time}&state={status}&type={type}

where:

• createdFrom={date and time} – date and time in YYYY-MM-DDThh:mm:ss format (optional parameter). If the parameter is specified, the list displays the tasks that were created not earlier than the specified date and time.
• state={state} – task state (optional parameter). If the parameter is specified, the list displays only the tasks with the specified state.
• type={type} – task type (optional parameter). If the parameter is specified, the list displays only the tasks of the specified type.

Return codes:

• 200 (OK) – request completed successfully. The response returns a list of tasks.
• 403 (Forbidden) – access to the resource is denied.

Canceling a task

Allows you to stop running tasks. Some tasks cannot be completed immediately. In this case, the 202 (Accepted) code is returned and the task state changes to Stopping.

Method:

POST /api/2.0/virtualization/tasks/{ID}/cancel

where:

{ID} – task identifier (required parameter).

Return codes:

• 200 (OK) – request completed successfully (the task was canceled).
• 202 (Accepted) – request is accepted for execution (the task state changes to Stopping).
• 403 (Forbidden) – access to the resource is denied.
• 404 (Not Found) – task with the specified identifier is not found.
• 405 (Method Not Allowed) – for child tasks: you can cancel a child task only if you cancel the parent task.
• 409 (Conflict) – the task is already in one of the following states: Cancelled, Failed, Stopped.