Tasks Overview

Introduction

In 3.1 we have introduced Tasks. Each Job can now have multiple Tasks.

• Tasks have replaced the Builder.
• Tasks are run in order on a single Agent.
• If a task fails following tasks will not be executed (Final Tasks are an exception)
• Final tasks will always be executed regardless of the state of previous tasksso can be used to for e.g. clean up tasks
• Tasks are executed after the Pre Build Plugins and Before the Post Build Plugins.
• What you choose to do in a task is entirely up to you!

Special Considerations When Developing Tasks

• People can add multiple of your TaskType plugin to the one Job.
• People can put your task in the final tasks section so you task needs to be defensive to the situation where previous setup may not exist.
• It must be a plugins 1 plugin because it needs to be capable of running on remote agents

The TaskType Module Definition

We have tried to make writing Task Plugins as simple as possible, so there are core details required plus a lot of optional extension points if you want the plugin to bemore powerful. I have included an example of a fully fledged TaskType Module for you to refer back to.

<taskType key="task.builder.maven" name="Maven 1.x" class="com.atlassian.bamboo.plugins.maven.task.Maven1BuildTask">
        <description>Execute one or more Maven 1 goals as part of your build</description>
        <category name="builder"/>
        <category name="test"/>
        <executable key="maven" nameKey="builder.maven.executableName" pathHelpKey="builder.maven.helpPath"/>
        <capabilityDefaultsHelper class="com.atlassian.bamboo.plugins.maven.task.Maven1CapabilityDefaultsHelper"/>
        <configuration class="com.atlassian.bamboo.plugins.maven.task.configuration.Maven1BuildTaskConfigurator" />
        <resource type="freemarker" name="edit" location="com/atlassian/bamboo/plugins/maven/task/configuration/maven1BuildTaskEdit.ftl"/>
        <resource type="freemarker" name="view" location="com/atlassian/bamboo/plugins/maven/task/configuration/maven1BuildTaskView.ftl"/>
</taskType>

The elements in the following example are the only mandatory elements

<taskType key="task.awesome" name="Awesome Task" class="com.atlassian.bamboo.plugins.MyAwesomeTaskType" />

Selecting the TaskType

When configuring the Job, the user is offered a TaskType picker.

The TaskType module name and description will be visible to assist the user in selecting the desired TaskType. The description is optional however we highly recommend including one.

You can also optionally provide categories to group the TaskType in the picker

Available Categories:

• builder
• test
• deployment

When a user selects a TaskType, if your TaskType requires configuration, they will have the opportunity to configure it and then it will be saved as a TaskDefinition. TaskDefinitions are stored against the BuildDefinition of a Job.

The Data Model.

TaskDefinition objects are what we store in the BuildDefinition and will be used whenever you are configuring a Task. When you are executing the TaskType we have provided lots of other useful information, so you will be dealing instead with the TaskContext. Both the TaskDefinition and TaskContext extend the TaskIdentifier interface which may be used when only the core information is required.

Executing The Task

The minimal requirement for a TaskType Module is a class implementing the TaskType interface.

The TaskType interface has only 1 method.

/**
     * Execute the task
     *
     * @param taskContext representing any context and configuration of the Task
     * @return a {@link TaskResult} representing the status of the task execution
     * @throws TaskException
     */
    @NotNull
    TaskResult execute(@NotNull final TaskContext taskContext) throws TaskException;

Things to consider

• TaskTypes are run on the Agent so must not use stuff your not allowed to use

Executing an external process

ExternalProcess
ProcessService
ExternalProcessBuilder

Reading Logs

LogInterceptor

Parsing Tests

TestCollationService

Helpful Utilities

EnvironmentVariableAccessor

Configuring The Task

If your TaskType requires configuring you can provide a configuration class. The configuration class must implement TaskConfigurator. You will also need to provide freemarker files for both edit and view of the configuration.

Utilities

AbstractTaskConfigurator
This abstract class provides empty implementations of the methods on the TaskConfigurator interface. You can extend this to simplify tasks with more basic configuration requirements

TaskConfiguratorHelper
The TaskConfiguratorHelper can be injected into your TaskConfigurator class. It contains many utility method to handle basice configuration requirements, especially moving configuration from the TaskDefinition to the FreemarkerContext and from the ActionParameters basck to the TaskDefinition. e.g.

private static final List<String> FIELDS_TO_COPY = ImmutableList.of("goal", "environment");

    @NotNull
    @Override
    public Map<String, String> generateTaskConfigMap(@NotNull final ActionParametersMap params, @Nullable final TaskDefinition previousTaskDefinition)
    {
        final HashMap<String,String> config = Maps.newHashMap();
        taskConfiguratorHelper.populateTaskConfigMapWithActionParameters(config, params, FIELDS_TO_COPY);
        return config;
    }

    @Override
    public void populateContextForEdit(@NotNull Map<String, Object> context, @NotNull TaskDefinition taskDefinition)
    {
        taskConfiguratorHelper.populateContextWithConfiguration(context, taskDefinition, FIELDS_TO_COPY);
    }

The TaskConfiguratorHelper also contains utilities to assist some generic fields such as selecting a JDK, and setting the location of where to find Test Results. However these methods rely on specifically named parameters, so if you want to make use of this functionality you should use TaskConfigConstants for your field naming.

Extensions

TaskTestResultsSupport

Requirements And Capabilities

TaskExecutableType – private class, but public functionality
TaskRequirementSupport
CapabilityDefaultsHelper
TaskConfiguratorHelper: add system requirement.

other

TaskManager

TaskModuleDescriptor?? public or not

TaskProcessCommandDecorator

Updating your builder configuration

TaskProcessCommandDecoratorModuleDescriptor ?? public or not