Создание шаблона проекта

Приложения шаблона проекта изначально поддерживались в Jira 6.0 с помощью модуля project-template. Однако Jira 6.0.7 представляет модуль плагина  project-blueprint, который предоставляет дополнительные возможности и предназначен для замены модуля project-template. Мы настоятельно рекомендуем использовать модуль project-blueprint для разработки приложений шаблонов проектов, как описано в этом уроке.

Обзор учебника

Шаблоны проектов Jira позволяют администраторам быстро создавать проекты Jira с предопределенным набором параметров и свойств конфигурации проекта. Jira поставляется с несколькими встроенными шаблонами проектов, но вы можете создавать свои собственные приложения Jira с помощью модуля плагина project-blueprint.

Помимо подключения к процессу создания проекта Jira, приложение шаблона проекта может определять схемы типов задач (с набором пользовательских типов задач) и схемы рабочего процесса, которые связывают типы задач с рабочими процессами Jira.

В этом учебном пособии показано, как создать приложение шаблона проекта. Наш шаблон проекта будет определять схему пользовательского типа задач с тремя типами задач и схему рабочего процесса с двумя импортированными рабочими процессами.

Завершенное приложение Jira будет состоять из следующих компонентов:

1. Java-классы, инкапсулирующие логику приложения.
2. Ресурсы для отображения пользовательского интерфейса приложения.
3. Дескриптор приложения (файл XML), чтобы включить модуль плагина в приложении Atlassian.
4. Файл конфигурации JSON для вашего шаблона проекта.
5. Пару пакетов рабочих процессов Jira для импорта рабочих процессов в шаблон проекта.

Когда вы закончите, все эти компоненты будут упакованы в один JAR-файл.

Об этих инструкциях

Вы можете использовать любую поддерживаемую комбинацию ОС и IDE для создания этого приложения. Эти инструкции были написаны с использованием IntelliJ IDEA 2017.3 на macOS Sierra. Если вы используете другую комбинацию ОС или IDE, вы должны использовать эквивалентные операции для своей конкретной среды.

Этот учебник был последний раз проверен с помощью Jira 7.7.1.

Прежде чем вы начнете

Чтобы завершить этот учебник, вам необходимо знать следующее:

1. Основы разработки Java: классы, интерфейсы, методы, использование компилятора и т. д.
2. Как создать проект плагина Atlassian  с помощью Atlassian Plugin SDK.
3. Как использовать и администрировать Jira, в частности, как настроить проекты Jira.

Источник приложения

Мы рекомендуем вам проработать этот учебник. Если вы хотите пропустить или проверить свою работу, когда закончите, вы можете найти исходный код приложения на Atlassian Bitbucket.

Чтобы клонировать репозиторий, выполните следующую команду:

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

tutorial.git

Кроме того, вы можете скачать исходный код в виде ZIP-архива:

 

Шаг 1. Создайте проект приложения

На этом шаге вы будете использовать atlas  SDK для создания кода- заглушки для вашего приложения.

Команды atlas  являются частью SDK Atlassian Plugin и автоматизируют большую часть разработки приложений для вас.

1. Настройте SDK Atlassian Plugin и создайте проект, если вы еще этого не сделали.
2. Откройте терминал и перейдите в каталог, в котором вы хотите создать проект.
3. Чтобы создать скелет приложения, выполните следующую команду:

atlas-create-jira-plugin

4. Чтобы определить ваше приложение, введите следующую информацию.

 

5. Подтвердите свои записи.

 

SDK создает домашнюю директорию проекта с файлами проекта, такими как POM (файл определения объектной модели проекта), исходный код заглушки и ресурсами приложения.

6. Удалите тестовые каталоги.

Настройка тестирования для вашего приложения не входит в этот учебник. Чтобы удалить сгенерированный тестовый скелет, выполните следующие команды:

rm -rf src/test/resources
rm -rf src/test/java

7. Удалите ненужные файлы классов Java.

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

8. Импортируйте проект в свою избранную среду IDE.

Шаг 2. Тонкая настройка POM

Это хорошая идея, чтобы ознакомиться с файлом конфигурации проекта, известным как POM. Среди других функций POM объявляет зависимости проекта и контролирует настройки сборки. Он также содержит описательную информацию для вашего приложения.

Измените метаданные и добавьте зависимость следующим образом:

1. Перейдите в корневую папку вашего проекта и откройте файл pom.xml.
2. Добавьте название компании или организации и URL веб-сайта в элемент organization:

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

3. Чтобы добавить осмысленное описание, отредактируйте элемент description описания проекта. Например:

<description> Это учебник для плагина шаблона проекта для Atlassian 

Jira. </ description>

Вводимые вами данные organization и  description распространяются на файл дескриптора приложения atlassian.plugin.xml. Оттуда Jira использует их на дисплее консоли администратора для вашего приложения.

 

4. Под элементом зависимостей dependencies добавьте зависимость от артефакта API шаблонов проектов:

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

5. Сохраните файл.

Если вы работаете в среде IDE, вам нужно обновить зависимости в своем проекте.

 

Шаг 3. Добавьте модуль плагина в дескриптор приложения

Теперь вы добавите модули плагина в свой дескриптор приложения. Дескриптор приложения представляет собой XML-файл, который идентифицирует приложение для Jira и определяет функциональные возможности приложения. Нам нужно добавить два модуля плагина: один для нашего шаблона проекта и другой для веб- ресурса.

Шаблоны проектов имеют собственный тип модуля, называемый чертежом проекта project-blueprint, который заботится о необходимой конфигурации. Добавьте его в свой дескриптор следующим образом:

1. Перейдите в src / main / resources и создайте новую папку soy.
2. Создайте новый шаблон Soy MyProjectTemplate.soy со следующим содержимым:

  {namespace JIRA.Templates.ProjectTemplates.Tutorial}
 
    /**
     * Отображает страницу с информацией о шаблоне My 

Project.
     */
    {template .renderMyProjectTemplateExplanation}
        <p>{getText

('my.project.template.info.page.description')}</p>
    {/template}

Мы будем использовать этот шаблон для страницы с информацией о проекте.

3. Откройте файл atlassian-plugin.xml и добавьте в качестве дочернего элемента элемента atlassian-plugin следующее:

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

Как минимум, вам нужно будет добавить элемент project-blueprint , но поскольку мы также добавляем дополнительную страницу к мастеру, нам также необходимо определить элемент веб-ресурса web-resource. Наш элемент web- resource идентифицирует файл шаблона Soy, который представляет нашу текстовую страницу в мастере.

Давайте подробнее рассмотрим атрибуты и дочерние элементы приложения project-blueprint, которые мы здесь определили.

* key, label, projectTypeKey, description не требуются.

Элемент add-project также содержит ряд параметров конфигурации, которые являются специфическими для фактического создания проекта

 

Шаг 4. Создание пакетов рабочих процессов

Шаблоны проектов могут включать один или несколько рабочих процессов Jira в рамках их конфигурации проекта. Чтобы включить рабочий процесс в ваш  шаблон проекта, сначала необходимо определить рабочий процесс в существующем проекте Jira, а затем использовать функцию совместного доступа к рабочему процессу для экспорта рабочего процесса оттуда.

Экспорт результатов  рабочего процесса в связку рабочих процессов Jira (.jwb), по одному для каждого экспортированного рабочего процесса. Затем вы можете использовать файл .jwb в приложении шаблона проекта. Имейте в виду, что экспортированный рабочий процесс Jira не включает пользовательские поля, функции post, валидаторы и условия. Если вы хотите, чтобы ваш рабочий процесс имел эту функциональность при использовании шаблона проекта, вы можете использовать AddProjectHook для его создания.

Чтобы получить файл пакета рабочего процесса для приложения, выполните одно из следующих действий:

1. Создайте пакет экспорта рабочего процесса рабочего процесса, который вы хотите использовать в своем проекте, следуя инструкциям по экспорту рабочего процесса.
2. Получите пакеты рабочих процессов, которые мы создали для вас. Пакеты находятся в каталоге src / main / resources / wfb / директории репозитория Bitbucket для этого учебника.
3. В новом каталоге под вашим src / main / resources / wfb сохраните файл пакета рабочего процесса.

Шаг 5. Настройте конфигурационный файл JSON

Файл конфигурации JSON позволяет объявить ряд параметров конфигурации для вашего шаблона проекта:

• Типы задач
• Схема типа задачи
• Рабочие процессы
• Схема типа рабочего процесса
• Сопоставление типов задач для рабочих процессов

Файл конфигурации JSON для шаблона проекта является необязательным и необходим, только если элемент hook объявлен в элементе add-project модуля модуля плагина project-blueprint. На этом этапе мы добавляем один.

1. Перейдите в src / main / resources / config и создайте новый файл JSON с именем my-project-template-config.json.
2. Добавьте в файл следующий код:

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

В my-project-template-config.json и atlassian-plugin.xml мы определили несколько значков. Загрузите их из Bitbucket и поместите в src / main / resources / images.

Давайте подробнее рассмотрим значение параметров конфигурации здесь:

• Значения атрибутов name и description issue-type-scheme и схемы workflow-scheme относятся к ключам i18n.
• Атрибут key типа задачи является только внутренний идентификатор в инфраструктуре шаблонов проектов.
• Атрибут icon типа задачи относится к расположению значков в каталоге src / main / resources вашего приложения.
• Атрибут sub-task типа задачи позволяет объявить, является ли тип задачи обычным типом задачи (по умолчанию) или подзадачей(sub-task).
• Если типы задач, объявленные в issue-type-scheme, не существуют в экземпляре Jira, они создаются с использованием объявленной конфигурации.
• Атрибут key рабочего процесса может использоваться для сопоставления типов задач с рабочими потоками или для объявления default- workflow для workflow-scheme.
• Атрибут default-workflow для workflow-scheme позволяет определить, какой рабочий процесс использовать, если тип задачи используется без явного сопоставления рабочего процесса. Значение относится к атрибуту key  рабочего процесса.
• workflow-bundle рабочего процесса относится к местоположению пакета рабочего процесса Jira в каталоге src / main / resources вашего приложения.

Шаг 6. Запишите класс Java            &n bsp; 

На этом этапе вы пишете класс Java. В этом примере просто создается базовый проект, который проверяет, не является ли ключ проекта «ТЕСТ». Когда проект успешно создан, он перенаправляет пользователя из диалогового окна «Создать проект» в «Браузер задач».

 

1. Перейдите в src / main / java / com / example / plugins / tutorial и создайте новый класс с именем MyAddProjectHook.
2. Добавьте следующий код в класс:

MyAddProjectHook

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();
    }
}

Обратите внимание, что новый класс реализует интерфейс AddProjectHook. Интерфейс определяет два метода:

 

• validate () позволяет вашему приложению проверять параметры, которые будут использоваться для создания проекта. Он принимает параметры как аргумент и может возвращать ошибки в объекте ValidateResponse. Ошибки, если они есть, сливаются с любыми другими ошибками, связанными с проверкой проекта Jira и возвращаются клиенту.
• configure () выполняет действия по настройке для пост-создания проекта. В качестве аргумента требуется новая конфигурация ConfigureData, в которой хранятся все созданные сущности (проект, схема рабочего процесса, рабочие процессы, схема типа задачи и типы задач).

Функция configure () может использоваться для самых разных параметров конфигурации. Например, вы можете использовать это для создания функций Workflow Post Functions, Resolutions и других.

Шаг 7. Добавьте ключи i18n

В нескольких местах мы ссылались на ключи i18n. Нам нужно предоставить значения для этих ключей i18n в файле свойств i18n.

1. Перейдите в src / main / resources и откройте файл my- project-template.properties.
2. Добавьте следующие строки:

#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. Чтобы гарантировать, что этот файл используется для переходов, убедитесь, что следующая строка находится в вашем atlassian-plugin.xml:

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

Шаг 8. Создание, установка и запуск приложения.

Теперь вы готовы попробовать новое приложение проекта:

1. Откройте терминал и перейдите в корневой каталог проекта.
2. Запустите следующую команду SDK:

atlas-run

Это создает код приложения, запускает экземпляр Jira и устанавливает ваше приложение. Это может занять несколько минут.

3. Найдите URL-адрес домашней страницы Jira на выходе терминала и откройте ее в своем браузере.
4. Войдите в систему с помощью admin / admin по умолчанию.
5. Создайте новый проект на основе шаблона My Project Template (Мой шаблон проекта). Это шаблон, который вы создали.

РИСУНОК

6. Убедитесь, что отображается информационная страница.

РИСУНОК

7. Введите имя проекта и ключ, как обычно.

РИСУНОК

8. Нажмите «Отправить». Убедитесь, что вы перенаправлены на страницу браузера задач.

 

Поздравляю, вот и все!

Имейте удовольствие!

Следующие шаги

Чтобы узнать больше о настройке проектов в Jira, перейдите к этим учебникам:

• Добавление пунктов меню в JIRA.
• Добавление содержимого на страницу «Просмотр задач Jira».
• Добавление JQL-функции в Jira.

По материалам Atlassian JIRA  Server Developer Creating a project template