Tutorial - Creating a project template
This tutorial applies to JIRA 6.0.7 and later.
Note that project template plugins were originally supported in JIRA 6.0 with the project-template module. However, JIRA 6.0.7 introduces the
Level of experience:
This is an intermediate tutorial. You should have completed at least one beginner tutorial before working through this tutorial. See the list of developer tutorials.
It should take you approximately an hour to complete this tutorial.
On this page:
Overview of the Tutorial
JIRA project templates allow administrators to quickly create JIRA projects with a predefined set of project configuration settings and properties. JIRA comes with several built-in project templates, but you can create your own as JIRA plugins using the
project-blueprint plugin module.
Besides hooking into the JIRA project creation process, a project template plugin can define issue-type schemes (with a set of custom issue types) and workflow schemes that link the issue types to JIRA workflows.
This tutorial shows you how to build a project template plugin. Our project template will define a custom issue type scheme with three issue types and a workflow scheme with two imported workflows. The completed JIRA plugin will consist of the following components:
- Java classes encapsulating the plugin logic.
- Resources for display of the plugin user interface (UI).
- A plugin descriptor (XML file) to enable the plugin module in the Atlassian application.
- A configuration file (JSON file) for your Project Template.
- A couple JIRA workflow bundles for importing the workflows in your project template.
When you have finished, all these components will be packaged in a single JAR file.
To complete this tutorial, you need to know the following:
- The basics of Java development: classes, interfaces, methods, how to use the compiler, and so on.
- How to create an Atlassian plugin project using the Atlassian Plugin SDK.
- How to use and administer JIRA, particularly how to configure JIRA projects.
We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, you can find the plugin source code on Atlassian Bitbucket. Bitbucket serves a public Git repository containing the tutorial's code. To clone the repository, issue the following command:
Alternatively, you can download the source as a ZIP archive by choosing download here: https://bitbucket.org/atlassian_tutorial/jira-project-templates-tutorial
Step 1. Create the plugin project
In this step, you'll use the
atlas SDK to generate stub code for your plugin. The
atlas commands are part of the Atlassian Plugin SDK, and automate much of the work of plugin development for you.
- If you have not already set up the Atlassian Plugin SDK, do that now: Set up the Atlassian Plugin SDK and Build a Project.
- Open a terminal and navigate to the directory where you want to create the project.
Enter the following command to create a plugin skeleton:
- Choose 1 for JIRA 5 when asked which version of JIRA you want to create the plugin for.
As prompted, enter the following information to identify your plugin:
- Confirm your entries when prompted.
The SDK generates the project home directory with project files, such as the POM (Project Object Model definition file), stub source code, and plugin resources.
Step 2. Tweak the POM
It's a good idea to familiarise yourself with the project configuration file, known as the POM (Project Object Model definition file). Among other functions, the POM declares project dependencies and controls build settings. It also contains descriptive information for your plugin.
Tweak the metadata and add a dependency as follows:
Open the POM (
pom.xml) for editing. You can find it in the root folder of your project.
Add your company or organization name and website URL to the
Update the project
descriptionelement to add a meaningful description, such as:
descriptionvalues you enter are propagated to the plugin descriptor file,
atlassian.plugin.xml. From there, JIRA uses them in the administration console display for your plugin.
Add a dependency to the Project Templates API artifact under the
dependencieselement in the POM:
Save the file.
If working in an IDE, you need to refresh the dependencies in your project now.
Step 3. Add the plugin module to the plugin descriptor
Now you will add plugin modules to your plugin descriptor. The plugin descriptor is an XML file that identifies the plugin to JIRA and defines the functionality that the plugin requires. We need to add two plugin modules, one for our project template and another for a web resource.
Project templates have their own module type, named
project-blueprint, which takes care of the necessary configuration. Add it to your descriptor as follows:
Open the plugin descriptor at
Add the following as a child of the
At a minimum, you would only need to add the
project-blueprintelement, but since we're also adding an optional information page to the wizard, we need to define a
web-resourceelement as well. Our
web-resourceelement identifies the Soy template file that presents our text page in the wizard.
- Save the file.
Let's take a closer look at the attributes and child elements of the
project-blueprint plugin that we defined here.
The identifier of the plugin module. The key should be unique in the context of your plugin.
Determines the order in which the project templates appear.
|projectTypeKey||(JIRA 7.0+) All the project templates must provide the key for the type of the projects created with the template. Valid values for the project type key are "
Make sure that the Soy Template is also declared as a web-resource in both
Default: No information page.
Default: default icon.
Default: default background image.
|add-project||Holds the custom configuration instructions for the project that will be created.|
*key, label, projectTypeKey, description are required.
add-project element also holds a number of configuration parameters that are specific for the actual project creation.
Step 4. Generate your Workflow Bundles
Project templates can incorporate one or more JIRA workflows as part of their project configuration. To incorporate a workflow in your project template, you first need to define the workflow in an existing JIRA project and then use the workflow sharing feature to export the workflow from there.
Exporting a workflow results in a JIRA Workflow Bundle (
.jwb) file, one for each exported workflow. You can then use the
.jwb file in your project template plugin. Keep in mind that an exported JIRA workflow doesn't include custom fields, post functions, validators and conditions. If you want your workflow to have this functionality when using a project template, you can use the
AddProjectHook to create it, as we do in this example.
To get a workflow bundle file for the plugin, you can either:
- Create a workflow export bundle of the workflow you want to use in your project by following the instructions for exporting a workflow, or
- Get the workflow bundles we've built for you. The bundles are in the
src/main/resources/wfb/directory of the Bitbucket repository for this tutorial.
Once you generate or get the JIRA workflow bundle file, put it in a new directory under your project home,
Step 5. Set up the JSON configuration file
The JSON configuration file allows you to declare a number of configuration options for your project template:
- Issue types
- Issue type scheme
- Workflow type scheme
- The mapping of issue types to workflows
The JSON configuration file for a project template is optional, and needed only if the
hook element is declared in the
add-project element of a
project-blueprint plugin module. We'll add one to ours:
- Create a new JSON file named
Add the following code to the file:
Let's take a closer look at the meaning of the configuration options here:
- The values of the
workflow-schemerefer to i18n keys.
keyattribute of an issue type only serves as an internal identifier within the project templates infrastructure.
iconattribute of an issue type refers to an icon location in the
src/main/resourcesdirectory of your plugin.
sub-taskattribute of an issue type lets you declare whether the issue type is a normal issue type (default) or a sub-task.
- If the issue types that are declared in the
issue-type-schemedon't exist in the JIRA instance, they will be created using the declared configuration.
keyattribute of a workflow can be used to map issue types to workflows, or to declare the
default-workflowattribute of a
workflow-schemelets you define which workflow to use if an issue type is used without an explicit workflow mapping. The value refers to the
keyattribute of a workflow.
workflow-bundleof a workflow refers to a JIRA workflow bundle location in the
src/main/resourcesdirectory of your plugin.
Step 6. Write your Java class
Now write the Java class. This example simply creates a basic project which checks whether the project key is not "TEST". When the project is successfully created, it redirects the user from the create project dialog to the issues browser.
- Create a new class named
Add the following code to the class:
Notice that the new class implements the
AddProjectHook interface. The interface defines two methods:
validate()allows your plugin to validate the parameters to be used for creating the project. It takes the parameters as an argument, and can return errors in the
ValidateResponseobject. The errors, if any, are merged with any other errors resulting from JIRA's project validation and returned to the client.
configure()performs setup actions for the project post-creation. It takes the new
ConfigureDataas an argument, which holds all the created entities (project, workflow scheme, workflows, issue type scheme, issue types). Its return values specifies the redirect page target. If no redirect is set, the default redirect (browse project) is used.
configure()function can be used for a wide variety of configuration options. For example, you can use this to create Workflow Post Functions, Resolutions, and more.
Step 7. Add the i18n keys
In a couple of places we referenced i18n keys. We need to provide values for those i18n keys in the i18n properties file:
- Open the
Add the following lines:
To ensure this file is used for translations, make sure the following line is in your
Step 8. Build, install and run the plugin
Now you're ready to try out the new project plugin:
- Open a terminal and change to the project root directory (where the
pom.xmlfile is located).
Enter the following SDK command:
- When JIRA finishes starting up, open the JIRA home page in a browser. JIRA prints the URL to use in the console output.
- Log in with the default user and password combination, admin/admin.
- Create a new project based on the
My Project Templatetemplate. This is the template you created.
- Check that the information page is shown.
Enter a project name and key, as usual.
Click Submit. Confirm that you are redirected to the issue browser page.