Tutorial - Creating a project template

Transcription

1 Tutorial - Creating a project template Applicable: This tutorial applies to JIRA and later. Note that project template plugins were originally supported in JIRA 6.0 with the project-templa te module. However, JIRA introduces the project-blueprint plugin module, which provides additional capabilities and is meant to supersede the project-template module. We strongly encourage you to use the project-blueprint module for project template plugin development, as described in this tutorial. Level of experience: Time estimate: 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 Step 1. Create the plugin project Step 2. Tweak the POM Step 3. Add the plugin module to the plugin descriptor Step 4. Generate your Workflow Bundles Step 5. Set up the JSON configuration file Step 6. Write your Java class Step 7. Add the i18n keys Step 8. Build, install and run the plugin 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. About these Instructions You can use any supported combination of OS and IDE to create this plugin. These instructions were written using IntelliJ IDEA on Mac OS. If you are using another OS or IDE combination, you should use the equivalent operations for your specific environment. This tutorial was last tested with JIRA Required Knowledge To complete this tutorial, you need to know the following:

2 2 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. Plugin source 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: git clone git@bitbucket.org:atlassian_tutorial/jira-project-templates-tutorial.git Alternatively, you can download the source as a ZIP archive by choosing download here: lassian_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: atlas-create-jira-plugin 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: group-id artifact-id version package com.atlassian.plugins.tutorial my-project-template 1.0-SNAPSHOT com.example.plugins.tutorial 6. 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 organization element:

3 3 <organization> <name>example Company</name> <url> </organization> 3. Update the project description element to add a meaningful description, such as: <description>this is the Project Template plugin tutorial for Atlassian JIRA.</description> 4. The organization and description values you enter are propagated to the plugin descriptor file, at lassian.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 dependencies element in the POM: <dependency> <groupid>com.atlassian.jira.plugins</groupid> <artifactid>project-templates-api</artifactid> <version>2.18</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 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 src/main/resources/atlassian-plugin.xml Add the following as a child of the atlassian-plugin element:

4 4 <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> <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.rendermyproj ecttemplateexplanation" /> <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> 3. At a minimum, you would only need to add the project-blueprint element, but since we're also adding an optional information page to the wizard, we need to define a web-resource element as well. Our web-resource element 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

5 5 here. Name* key weight Description 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. Default: 100 label The key attribute defines the localisation key for the human-readable name of the plugin module. This name is used to identify the project template in the Project Templates dialog. 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 "business", "softwar e", and "service_desk". description The key attribute defines the localisation key for the human-readable short description of the plugin module. This description is used on the first page of the project templates dialog where all the available project templates are listed. longdescription The key attribute defines the localisation key for the human-readable long description of the plugin module. The long description is used on the right side of the Create Project form of the Project Templates dialog wizard. If no longdescription is specified, the short des cription will be used. Default: description. infopage The soy-template attribute refers to a Soy Template that renders a page in the Project Templates dialog. Typically, you would use this page to explain the characteristics of the Project Template to the JIRA administrator. Make sure that the Soy Template is also declared as a web-resource in both atl.genera l and atl.admin contexts. The information page will be shown after the administrator selects your Project Template from the initial Project Templates selection dialog. If you do not define an infopage element, the Project Templates wizard skips that step and goes directly to the Create Project form of the wizard. Default: No information page. icon The location attribute defines an icon to be used when listing the available project templates in the selection screen of the Project Templates dialog. Default: default icon. backgroundicon The location attribute defines the background image to use on the Create Project form of the wizard. Default: default background image. add-project Holds the custom configuration instructions for the project that will be created. *key, label, projecttypekey, description are required. The add-project element also holds a number of configuration parameters that are specific for the actual project creation. Name Description hook The class attribute refers to the Java class which implements the AddProjectHook interface. This allows project templates to hook into the validation and configuration of JIRA projects. descriptor The file attribute refers to a JSON file which defines parts of the configuration for the project.

6 6 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 instructio ns for exporting a workflow, or Get the workflow bundles we've built for you. The bundles are in the src/main/resources/wfb/ direct ory 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, src/ main/resources/wfb. 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 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: 1. Create a new JSON file named my-project-template-config.json in the src/main/resources /config directory 2. Add the following code to the file: my-project-template-config.json

7 7 "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" ]

8 8 Let's take a closer look at the meaning of the configuration options here: The values of the name and description attributes of issue-type-scheme and workflow-scheme refer to i18n keys. The key attribute of an issue type only serves as an internal identifier within the project templates infrastructure. The icon attribute of an issue type refers to an icon location in the src/main/resources directory of your plugin. The sub-task attribute 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-scheme don't exist in the JIRA instance, they will be created using the declared configuration. The key attribute of a workflow can be used to map issue types to workflows, or to declare the defaultfor a workflow-scheme. The default-workflow attribute of a workflow-scheme lets you define which workflow to use if an workflow issue type is used without an explicit workflow mapping. The value refers to the key attribute of a workflow. The workflow-bundle of a workflow refers to a JIRA workflow bundle location in the src/main/reso urces directory 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. 1. Create a new class named MyAddProjectHook in the src/main/java/com/example/plugins/tu torial director. 2. Add the following code to the class:

9 9 MyAddProjectHook package com.example.plugins.tutorial; import com.atlassian.jira.blueprint.api.addprojecthook; import com.atlassian.jira.blueprint.api.configuredata; import com.atlassian.jira.blueprint.api.configureresponse; import com.atlassian.jira.blueprint.api.validatedata; import com.atlassian.jira.blueprint.api.validateresponse; public class MyAddProjectHook implements public ValidateResponse validate(final ValidateData validatedata) ValidateResponse validateresponse = ValidateResponse.create(); if (validatedata.projectkey().equals("test")) validateresponse.adderrormessage("invalid Project Key"); return public ConfigureResponse configure(final ConfigureData configuredata) ConfigureResponse configureresponse = ConfigureResponse.create().setRedirect("/issues/"); return configureresponse; 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 ValidateResponse object. 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 ConfigureData as 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. The 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:

10 Open the src/main/resources/my-project-template.properties file. Add the following lines: #put any key/value pairs here my.project.template.name=my Project Template my.project.template.description=this is my custom Project Template my.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 Scheme my.project.template.issuetype.scheme.description=this is my Issue Type Scheme my.project.template.workflow.scheme.name=my Project Template Workflow Scheme my.project.template.workflow.scheme.description=my Project Template Workflow Scheme my.project.template.workflow.wf1.name=my Workflow 1 my.project.template.workflow.wf2.name=my Workflow 2 3. To ensure this file is used for translations, make sure the following line is in your ml: atlassian-plugin.x <resource type="i18n" name="i18n" location="my-project-template"/> 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.xml file is located). Enter the following SDK command: atlas-run 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 Template template. This is the template you created.

11 11 6. Check that the information page is shown. 7. Enter a project name and key, as usual. 8. Click Submit. Confirm that you are redirected to the issue browser page. Success!