Introduction to writing Tasks

In this tutorial we explain the basic elements of the Bamboo Task API, including logging and setting an applicable result state

Create a new plugin

1. First download the copy of the latest Plugin SDK and install it on your machine.

2. Run atlas-create-bamboo-plugin from the command line.

3. When asked for the groupId, artifactId and package just enter "myfirstplugin" and leave the other options as the defaults.

Writing your first Task

Create a new class called "MyFirstTask" in the "myfirstplugin" (myfirstplugin/src/main/java/myfirstplugin) package and implement the interface TaskType on the MyFirstTask class. Change your class so it looks like the one below.

1
2
package myfirstplugin;

import com.atlassian.bamboo.build.logger.BuildLogger;
import com.atlassian.bamboo.task.TaskContext;
import com.atlassian.bamboo.task.TaskException;
import com.atlassian.bamboo.task.TaskResult;
import com.atlassian.bamboo.task.TaskResultBuilder;
import com.atlassian.bamboo.task.TaskType;

public class MyFirstTask implements TaskType
{
    @Override
    public TaskResult execute(final TaskContext taskContext) throws TaskException
    {
        final BuildLogger buildLogger = taskContext.getBuildLogger();

        buildLogger.addBuildLogEntry("Hello, World!");

        return TaskResultBuilder.newBuilder(taskContext).success().build();
    }
}

What am I looking at?

TaskType

A TaskType is the minimal requirement for implementing a Task. This is where all your plugins heavy lifting happens and all Tasks must be capable of running on a Remote Agent.

In our example we are getting the provided BuildLogger from the TaskContext and writing the string "Hello, World!" to the log. Of course, Tasks that you can develop can be a lot more complex than this one.

TaskContext

A TaskContext gives contextual information about where and how the Task is being executed. From this object it is possible to obtain a reference to the configuration, build log, working directory and information about the Job executing from the BuildContext.

TaskResult and TaskResultBuilder

To let Bamboo know if your Task has completed successfully or otherwise, you need to pass back a TaskResult instance. To facilitate the creation of a TaskResult we have provided the TaskResultBuilder. The TaskResultBuilder uses the Builder Pattern to create and maintain the TaskResult.

For example if the local variable condition is true the TaskResult calculated when build() is called will be Successful even though we initially set it to Failed.

1
2
public TaskResult execute(final TaskContext taskContext) throws TaskException
{
    final TaskResultBuilder builder = TaskResultBuilder.create(taskContext).failed(); //Initially set to Failed.

    ...

    if (condition)
    {
        builder.success();
    }

    final TaskResult result = builder.build();

    return result;
}

Registering your Task with the plugin system

In the atlassian-plugin.xml between the atlassian-plugin elements, simply add the following:

1
2
<taskType key="myFirstTask" name="My First Task" class="myfirstplugin.MyFirstTask">
  <description>A task that prints 'Hello, World!'</description>
</taskType>

This lets the Plugin system know what the name of the Task, its description, key and class in order for it to be used in side of Bamboo. For more information about the Task descriptor see The Task Type Module Definition.

Running the 'MyFirstTask' Plugin

From inside your project execute on the command line atlas-run. This command will compile your plugin, run its tests and start Bamboo with your plugin installed. You can tell when Bamboo has finished loading when you see the following in the logs:

1
2
[INFO] [talledLocalContainer] Jun 18, 2024 10:25:23 AM org.apache.catalina.startup.Catalina start
[INFO] [talledLocalContainer] INFO: Server startup in 62551 ms
[INFO] [talledLocalContainer] Tomcat 8.x started on port [6990]
[INFO] bamboo started successfully in 81s at http://localhost:6990/bamboo
[INFO] Type Ctrl-C to shutdown gracefully

Checking that your plugin has loaded correctly

Browse to http://localhost:6990/bamboo then go to Administration->System->Plugins and you should see your plugin in the list of User Installed plugins

Run your Task

Create a new plan, select your task "My First Task" from the list of Tasks and add it to the default Job and run the plan.

In the Job logs you should see the Task output "Hello, World!"