Execute tasks from the Deploy CLI

This topic covers how Deploy manages multiple deployments simultaneously, each referred to as a task. Users can instruct Deploy to start, stop, or cancel a task. Once a task is completed or canceled, it is moved to the task archive, where Deploy stores its task history. You can query the task archive for tasks, examine the tasks steps and logs, or export the task archive to an XML file.

Active tasks are stored in the Deploy task registry which is periodically backed up to a file. If the Deploy Server is stopped abruptly, the tasks in the registry are persisted and can be continued when the server is restarted.

Starting, stopping, and canceling

When you start a deployment or undeployment in Deploy, the command-line interface (CLI) returns a TaskInfo object. This object describes the steps Deploy will take to execute your request, but it does not start execution. Deploy creates a task for the request and returns the task ID as the id field in the TaskInfo object. Using the task ID, you can start, stop, or cancel the task.

There are two ways to start a task in the Deploy CLI:

• startTaskAndWait: Starts the task and waits for it to complete.
• startTask: Starts the task and immediately returns a response.

Note: Both methods can be used to restart a failed task.

To stop a task: use the stopTask method. This attempts to interrupt the currently running task.

To cancel a task: use the cancelTask method. This will abandon execution of the task and move it to the archive.

To archive a task, when it has finished running: use the archive method.

For more information, see Sample CLI scripts and Getting started with the Deploy CLI.

Scheduling tasks

Important: Import the DateTime class from org.joda.time import DateTime.

Note: The above examples will use the users' local time zone.

Note: The server will always return the date and time in UTC.

Schedule a task using the following method: task2.schedule(String taskId, DateTime dateTime).

Create a DateTime object representing the current local time using DateTime(). For example, to prepare the deployment of the KidsStore 1.0.0 application to the TEST01 environment and schedule it for two hours in the future, execute:

# Load package
package = repository.read('Applications/Sample Apps/KidsStore/1.0.0')

# Load environment
environment = repository.read('Environments/Testing/TEST01')

# Start deployment
deploymentRef = deployment.prepareInitial(package.id, environment.id)
depl = deployment.prepareAutoDeployeds(deploymentRef)
task = deployment.createDeployTask(depl)
task = task2.schedule(task.id, DateTime().plusHours(2))

You can also specify a concrete date. For example, 31 December 2014 at 23:34, would be specified as DateTime(2014, 12, 31, 23, 34).

Assigning tasks

Tasks in Deploy are assigned to the user that started them. This means that they will appear in the Deploy GUI when this user logs out and back in again.

Deploy also supports reassigning tasks. If you have the task#assign permission, you are allowed to assign a task that is currently assigned to you to another principal. If you have the admin permission, you can assign any task in the system to another principal.

To assign a task in the CLI:

# Import package
  package = repository.read('Applications/Sample Apps/KidsStore/1.0.0')

# Load environment
  environment = repository.read('Environments/Testing/TEST01')

# Start deployment
  deploymentRef = deployment.prepareInitial(package.id, environment.id)
  depl = deployment.prepareAutoDeployeds(deploymentRef)
  task = deployment.createDeployTask(depl)

  # Reassign deployment task
  deployit.assignTask(task.id, 'john')

Note: Deploy does not validate the principal you enter as the recipient of a task.

Retrieving archived tasks from the repository

The repository object can retrieve an overview of all archived tasks or a number of archived tasks within a specified date range.

To retrieve all archived tasks, execute:

archivedTasks = repository.getArchivedTaskList()

This call returns a list of TaskWithBlock object wrappers. On each object wrapper, retrieve all step blocks from the task using get_step_blocks.

To obtain step blocks from a specific task, execute:

first_step_block = archivedTasks[0].get_step_blocks()[0]

To obtain a certain step from the step block, execute:

first_step = first_step_block.getSteps()[0]

To obtain tasks within a given date range, execute:

Important: Start and end date parameters must be specified in the mm/dd/yyyy format.

repository.getArchivedTasksList('01/01/2010', '01/01/2011')

Exporting archived tasks from the repository to a local XML file

To export the contents of the task repository to a local XML file, use:

repository.exportArchivedTasks('/tmp/task-export.xml')

Note: You can use forward slashes (/) in the path, including Microsoft Windows systems.

To export the tasks within a given date range, use:

repository.exportArchivedTasks('/tmp/task-export.xml', '01/01/2010', '01/01/2011')

Using the stepPath parameter

Using TaskBlockService you can retrieve information about a step in a deployment plan using, the API call GET /tasks/v2/{taskid}/step/{stepPath}. In a CLI script, this can be called using:

task2.step(String taskId, String stepPath)

The stepPath parameter has three parts: the root, the number of the task block, and the number of the step in the block. In Deploy, the root is always 0_0 and the parts of the stepPath are separated by underscores.