Creating a project template (2024)

Overview of the tutorial

Jira project templates allow administrators to quickly create Jira projects with a predefined set of projectconfiguration settings and properties. Jira comes with several built-in project templates, but you can createyour own as Jira apps using the project-blueprint plugin module.

Besides hooking into the Jira project creation process, a project template app 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 app. Our project template will define a custom issue typescheme with three issue types and a workflow scheme with two imported workflows.

The completed Jira app will consist of the following components:

1. Java classes encapsulating the app logic.
2. Resources for display of the app UI (user interface).
3. An app descriptor (XML file) to enable the plugin module in the Atlassian application.
4. A configuration JSON file for your Project Template.
5. A couple Jira workflow bundles for importing the workflows in your project template.

When you are finished, all these components are packaged in a single JAR file.

Before you begin

To complete this tutorial, you need to know the following:

1. The basics of Java development: classes, interfaces, methods, how to use the compiler, and so on.
2. How to create an Atlassian plugin project using theAtlassian Plugin SDK.
3. How to use and administer Jira, particularly how to configure Jira projects.

App source

We encourage you to work through this tutorial. If you want to skip ahead or check your work when you have finished, youcan find the app source code on Atlassian Bitbucket.

To clone the repository, run the following command:

12
git clone git@bitbucket.org:atlassian_tutorial/jira-project-templates-tutorial.git

Alternatively, you can download the source as a ZIP archive:

Step 1. Create the app project

In this step, you'll use theatlasSDK to generate stub code for your app. Theatlascommands are part of theAtlassian Plugin SDK and automate much of the work of app development for you.

1. Set up the Atlassian Plugin SDK and Build a Projectif you have not done it yet.

2. Open a Terminal and navigate to the directory where you want to create the project.

3. To create an app skeleton, run the following command:

   12
   atlas-create-jira-plugin

4. To identify your app, enter the following information.

   group-id	com.example.plugins.tutorial
   artifact-id	my-project-template
   version	1.0-SNAPSHOT
   package	com.example.plugins.tutorial

5. Confirm your entries.

   The SDK generates the project home directory with project files, such as the POM (Project Object Model definition file),stub source code, and app resources.

6. Delete the test directories.

   See Also

   Is there a limit of number of projects that can be created in an instance?How can I easily tell what kind of Software project is a project in Jira, Kanban vs Scrum vs Basic?Introduction to Jira Projects | AtlassianHow can I create custom project template ?

   Setting up testing for your app isn't part of this tutorial. To delete the generated test skeleton,run the following commands:

   12
   rm -rf src/test/resourcesrm -rf src/test/java

7. Delete the unneeded Java class files.

   12
   rm -rf src/main/java/com/example/plugins/tutorial

8. Import the project to your favorite IDE.

Step 2. Tweak the POM

It's a good idea to familiarize yourself with theproject configuration file, known as the POM.Among other functions, the POM declares project dependencies and controls build settings.It also contains descriptive information for your app.

Tweak the metadata and add a dependency as follows:

1. Navigate to the root folder of your project and open the pom.xml file.

2. Add your company or organization name and website URL to theorganizationelement:

   12
   <organization> <name>Example Company</name> <url>http://www.example.com/</url></organization>

3. To add a meaningful description, edit the projectdescriptionelement. For example:

   12
   <description>This is the Project Template plugin tutorial for Atlassian Jira.</description>

   Theorganizationanddescriptionvalues you enter are propagated to the app descriptor file,atlassian.plugin.xml.From there, Jira uses them in the administration console display for your app.

4. Under the dependencies element, add a dependency to the Project Templates API artifact:

   12
   <dependency> <groupId>com.atlassian.jira.plugins</groupId> <artifactId>project-templates-api</artifactId> <version>6.2.0</version> <scope>provided</scope></dependency>

5. 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 app descriptor

Now you will add plugin modules to your app descriptor. The app descriptor is an XML file that identifies theapp to Jira and defines the functionality that the app requires. We need to add two plugin modules: one for ourproject template and another for a web resource.

Project templates have their own module type called project-blueprint which takes care of the necessary configuration.Add it to your descriptor as follows:

1. Navigate tosrc/main/resources and create a new soy folder.

2. Create new Soy template MyProjectTemplate.soy with the following content:

   12
   {namespace JIRA.Templates.ProjectTemplates.Tutorial}/** * Render the information page for My Project Template. */{template .renderMyProjectTemplateExplanation} <p>{getText('my.project.template.info.page.description')}</p>{/template}
   See Also
   Issue Templates for Jira | Atlassian Marketplace

   We will use this template for project info page.

3. Open the atlassian-plugin.xml file and add the following as a child of the atlassian-plugin element:

   12
   <atlassian-plugin ...> ... <web-resource key="my-project-template-resources" name="my-project-template Web Resources"> <dependency>com.atlassian.auiplugin:ajs</dependency> <transformation extension="soy"> <transformer key="soyTransformer"/> </transformation> <transformation extension="js"> <transformer key="jsI18n"/> </transformation> <resource type="download" name="MyProjectTemplate.soy.js" location="/soy/MyProjectTemplate.soy"/> <resource type="download" name="images/" location="/images"> <param name="content-type" value="image/png; charset=binary"/> </resource> <context>atl.general</context> <context>atl.admin</context> </web-resource> <project-blueprint key="my-project-template" weight="90"> <label key="my.project.template.name"/> <projectTypeKey>business</projectTypeKey> <description key="my.project.template.description"/> <longDescription key="my.project.template.description.long"/> <infoPage soy-template="JIRA.Templates.ProjectTemplates.Tutorial.renderMyProjectTemplateExplanation" /> <icon location="images/my-template-icon.png"/> <backgroundIcon location="images/my-template-background.png"/> <add-project> <hook class="com.example.plugins.tutorial.MyAddProjectHook"/> <descriptor file="/config/my-project-template-config.json"/> </add-project> </project-blueprint> ...</atlassian-plugin>

   At a minimum, you would only need to add the project-blueprintelement, but since we're also adding an optionalinformation page to the wizard, we need to define aweb-resourceelement as well. Our web-resourceelementidentifies the Soy template file that presents our text page in the wizard.

Let's take a closer look at the attributes and child elements of theproject-blueprint app that we defined here.

*key, label, projectTypeKey, description are required.

Theadd-projectelement also holds a number of configuration parameters that are specific for the actual project creation.

Step 4. Generate workflow bundles

Project templates can incorporate one or more Jira workflows as part of their project configuration. To incorporate aworkflow in your project template, you first need to define the workflow in an existing Jira project, and then use theworkflow sharingfeature 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 app. 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 theAddProjectHookto create it.

1. To get a workflow bundle file for the app, do one of the following:

   1. Create a workflow export bundle of the workflow you want to use in your project by following theinstructions for exporting a workflow.
   2. Get the workflow bundles we've built for you. The bundles are in thesrc/main/resources/wfb/ directory of theBitbucket repository for this tutorial.

2. In a new directory under your src/main/resources/wfb, save the workflow bundle file.

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
• Workflows
• Workflow type scheme
• The mapping of issue types to workflows

The JSON configuration file for a project template is optional and is needed only if thehookelement is declared in theadd-projectelement of aproject-blueprintplugin module. In this step, we add one.

1. Navigate to src/main/resources/config and create a new JSON file namedmy-project-template-config.json.

2. Add the following code to the file:

   my-project-template-config.json

   12
   { "issue-type-scheme": { "name": "my.project.template.issuetype.scheme.name", "description": "my.project.template.issuetype.scheme.description", "issue-types": [ { "key": "issueType1", "name": "New Feature", "description": "A new feature of the product, which has yet to be developed.", "icon": "/images/icons/newfeature.png", "workflow": "wf1" }, { "key": "issueType2", "name": "Bug", "description": "A problem which impairs or prevents the functions of the product.", "icon": "/images/icons/bug.png" }, { "key": "issueType3", "name": "Sub-Task", "description": "The sub-task of the issue", "icon": "/images/icons/subtask_alternate.png", "sub-task": true, "workflow": "wf2" } ] }, "workflow-scheme": { "name": "my.project.template.workflow.scheme.name", "description": "my.project.template.workflow.scheme.description", "default-workflow": "wf1", "workflows": [ { "key": "wf1", "name": "my.project.template.workflow.wf1.name", "workflow-bundle": "/wfb/Issue-Tracking-Workflow.jwb" }, { "key": "wf2", "name": "my.project.template.workflow.wf2.name", "workflow-bundle": "/wfb/Software-Development-Workflow.jwb" } ] }}

Let's take a closer look at the meaning of the configuration options here:

• The values ofnameanddescriptionattributes ofissue-type-schemeandworkflow-schemerefer to i18n keys.
• Thekeyattribute of an issue type only serves as an internal identifier within the project templates infrastructure.
• Theiconattribute of an issue type refers to an icon location in thesrc/main/resourcesdirectory of your app.
• Thesub-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 theissue-type-schemedon't exist in the Jira instance, they arecreated using the declared configuration.
• Thekeyattribute of a workflow can be used to map issue types to workflows, or to declare thedefault-workflowfor aworkflow-scheme.
• Thedefault-workflowattribute of aworkflow-schemelets you define which workflow to use if an issue typeis used without an explicit workflow mapping. The value refers to thekeyattribute of a workflow.
• Theworkflow-bundleof a workflow refers to a Jira workflow bundle location in thesrc/main/resourcesdirectory of your app.

Step 6. Write Java class

In this step you write the Java class. This example simply creates a basic project which checks whether the projectkey is not "TEST". When the project is successfully created, it redirects the user from the Create project dialogto the Issues Browser.

1. Navigate to src/main/java/com/example/plugins/tutorial and create a new class namedMyAddProjectHook.

2. Add the following code to the class:

   MyAddProjectHook

   12
   package com.example.plugins.tutorial;import com.atlassian.jira.project.template.hook.AddProjectHook;import com.atlassian.jira.project.template.hook.ConfigureData;import com.atlassian.jira.project.template.hook.ConfigureResponse;import com.atlassian.jira.project.template.hook.ValidateData;import com.atlassian.jira.project.template.hook.ValidateResponse;public class MyAddProjectHook implements AddProjectHook{ @Override public ValidateResponse validate(final ValidateData validateData) { ValidateResponse validateResponse = ValidateResponse.create(); if (validateData.projectKey().equals("TEST")) { validateResponse.addErrorMessage("Invalid Project Key"); } return validateResponse; } @Override public ConfigureResponse configure(final ConfigureData configureData) { return ConfigureResponse.create(); }}

Notice that the new class implements theAddProjectHookinterface. The interface defines two methods:

• validate()allows your app to validate the parameters to be used for creating the project. It takes theparameters as an argument, and can return errors in theValidateResponseobject. The errors, if any, are mergedwith any other errors resulting from Jira's project validation and are returned to the client.
• configure()performs setup actions for the project post-creation. It takes the newConfigureDataas anargument, which holds all the created entities (project, workflow scheme, workflows, issue type scheme, and issue types).
  Theconfigure()function can be used for a wide variety of configuration options. For example, you can usethis 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.

1. Navigate tosrc/main/resources and openthe my-project-template.properties file.

2. Add the following lines:

   12
   #put any key/value pairs heremy.project.template.name=My Project Templatemy.project.template.description=This is my custom Project Templatemy.project.template.description.long=This custom Project Template will create a new Project with customized workflows and issue types.my.project.template.info.page.description=Explain the configurations specifics of your template here.my.project.template.issuetype.scheme.name=My Project Template Issue Type Schememy.project.template.issuetype.scheme.description=This is my Issue Type Schememy.project.template.workflow.scheme.name=My Project Template Workflow Schememy.project.template.workflow.scheme.description=My Project Template Workflow Schememy.project.template.workflow.wf1.name=My Workflow 1my.project.template.workflow.wf2.name=My Workflow 2

3. To ensure that this file is used for translations, makesure the following line is in youratlassian-plugin.xml:

   12
   <resource type="i18n" name="i18n" location="my-project-template"/>

Step 8. Build, install, and run the app

Now you're ready to try out the new project app:

1. Open a Terminal and navigate to the project root directory.

2. Run the following SDK command:

   12
   atlas-run

   This builds your app code, starts a Jira instance, and installs your app. This could take a few minutes.

3. Find the Jira home page URL in the Terminal output and open it in your browser.

4. Log in with the default admin/admin.

5. Create a new project based on theMy Project Templatetemplate. This is the template you created.
   

6. Check that the information page is shown.
   

7. Enter a project name and a key, as usual.
   

8. ClickSubmit. Confirm that you are redirected to the issue browser page.

Next steps

To learn more about the customizing projects in Jira, go to these tutorials:

• Adding menu items to JIRA.
• Adding content to the Jira View Issue page.
• Adding a JQL function to Jira.