Writing a Task with a User Interface
Bamboo 3.1 and later
Create a new plugin
- First download the copy of the latest Plugin SDK and install it on your machine.
atlas-create-bamboo-pluginfrom the command line.
- When asked for the groupId, artifactId and package just enter "helloworld" and leave the other options as the defaults.
What is the Hello World plugin?
The "Hello World" plugin is the example plugin from the SDK that demonstrates how to build a Task plugin with a User Interface, validation and internationalisation. The plugin is very simple. It allows a user in Bamboo to configure the Task so that it prints a user configured value to the log and returns a successful TaskResult.
Try it out
To try the default Hello World plugin out run the
atlas-run command from the root of the project you generated when you started the tutorial. Once Bamboo is up, create a new Plan with a "None" repository type and configure the Job to contain the "Hello World" Task.
Try removing the default value in the "Say" field and saving. You should see a validation error like the one below:
Thats the validation we have defined in the Configurator. We will show you how to add your own validation in a moment. Change the "Say" field value to be "Hello, World!" then save the task then run your plan. Once the plan has completed running you should see the plugin executing and printing "Hello, World!" in the default Jobs logs
Breakdown of the plugin
We will now break down the plugin into its components and explain how its put together.
We covered what a TaskType is and how it works in the Introduction to Tasks tutorial. This Task takes the a value out of the configuration map using the key "say" and adds a new entry with its value to the build log and returns a successful TaskResult.
Lets have a look at the Hello World plugins templates. Bamboo uses the WebWork web framework and the Freemarker templating language to render its user interface. There are numerous tags available from WebWork that can be used from within freemarker to map values in the Configurator to elements in the user interface (we will talk more about the Configurator in a moment).
This template provides the configuration form for the Task. We use a
textField here to provide input. The
helloworld.say maps to a property defined in the
english.properties file that provides the translation and the
name specifies what the value of the
textField should be in the Configurator. In this case we always want the user to specify a value for the field so we mark it with the
required attribute with the value set to
So whats a TaskConfigurator? A TaskConfigurator is a class that controls what objects and values are available when rendering the User Interface, how input is persisted and validated.
Saving configuration inputs
To save your configuration you need to override or implement the
generateTaskConfigMap method on your TaskConfigurator.
The ActionParametersMap contains all the form parameter keys and values from the input fields of the
editExampleTask.ftl. The TaskDefinition is the saved state of the Task within Bamboo. It contains its user description and its map of configuration key/values. One thing to note is that if the Task is being created the TaskDefinition instance here is null but if it is being edited it contains the previous state of the Task before the user changes it.
Remember the field named "say" in the
editExampleTask.ftl? Well the value set by the user for this field is available in the ActionParametersMap. In order to persist the value in a new TaskDefinition we must return a new map that contains this value. For simplicity sake we use the same key for this value as was used as the name of the field.
Validating configuration inputs
generateTaskConfigMap is called the
ActionParametersMap is validated to ensure it contains the correct values needed to create the new
generateTaskConfigMap. Validation is simple. If the field does not pass your Tasks validation rules you simply call addError on the ErrorCollection with the name of the field that did not pass validation and a message about why it failed.
Populate for Create and Edit
In this method you can set the default configuration of your Task when it is being created by populating the given
context map with the key of the field and the value you want it to contain.
Once your Task has been created the
populateContextForEdit can be used to show the configured values of the Task. Simply populate the given
context map with the values stored in the map on the
TaskDefinition (These are the values you set to a new map from the
ActionParametersMap in the
generateTaskConfigMap method). Like
populateContextForCreate, the keys of the
context map should match the field names in your templates.
Registering a Configurator and associated Templates with the Plugin system
Internationalisation and TextProvider
In our example we use the injected TextProvider in
ExampleTaskConfiguratior.java to load the
helloworld.say.error string from the
english.properties internationalisation file when validation fails.
To register the
english.properties with the plugin system add a line to the
atlassian-plugin.xml like so: