Введение в плагины Atlassian Confluence

Если вы знакомы с набором продуктов Atlassian, то знаете, насколько мощным инструментом может быть Confluence для командного взаимодействия и управления знаниями. Однако иногда стандартных функций недостаточно. Здесь на помощь приходят плагины, позволяющие настроить и расширить Confluence в соответствии с вашими потребностями. В этой статье мы погрузимся в мир разработки плагинов для Atlassian Confluence с использованием Java.

Настройка среды разработки

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

Установка SDK плагина Atlassian

SDK плагина Atlassian — ваш лучший друг, когда дело доходит до разработки плагинов. Вот как его можно установить:

# Скачать и установить SDK
wget https://www.atlassian.com/software/sdk/downloads/binary/atlassian-plugin-sdk-8.0.2.tar.gz
tar -xzf atlassian-plugin-sdk-8.0.2.tar.gz
cd atlassian-plugin-sdk-8.0.2

# Настроить SDK
./bin/atlas-setup

# Проверить настройку
./bin/atlas-version

Использование Maven для разработки плагинов

Maven — это важный инструмент для управления зависимостями и сборки вашего плагина. Вот пример того, как настроить файл pom.xml для плагина Confluence:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example.plugins</groupId>
    <artifactId>my-confluence-plugin</artifactId>
    <version>1.0</version>
    <packaging>atlassian-plugin</packaging>

    <dependencies>
        <dependency>
            <groupId>com.atlassian.confluence</groupId>
            <artifactId>confluence</artifactId>
            <version>8.0.0</version>
            <scope>provided</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>com.atlassian.maven.plugins</groupId>
                <artifactId>confluence-maven-plugin</artifactId>
                <version>8.0.2</version>
                <extensions>true</extensions>
                <configuration>
                    <productVersion>8.0.0</productVersion>
                    <productDataVersion>8.0.0</productDataVersion>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>
</project>

Обновление до Java 11

Если вы переходите со старой версии Confluence на Confluence 8 или более позднюю версию, вам потребуется обновить Java до версии 11. Вот совет от сообщества:

# Использовать последнюю версию Maven
mvn --version

# Убедитесь, что ваш pom.xml настроен для Java 11
<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>

Создание вашего первого плагина

Описание плагина

Основой любого плагина Confluence является файл atlassian-plugin.xml, который служит описанием плагина. Вот пример того, как это может выглядеть:

<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
    <plugin-info>
        <description>Это мой первый плагин Confluence.</description>
        <vendor-name>Максим Жирнов</vendor-name>
        <vendor-url>https://example.com</vendor-url>
    </plugin-info>

    <!-- Определите свои модули плагина здесь -->
    <module type="macro" key="my-macro">
        <name>Мой макрос</name>
        <class>com.example.plugins.MyMacro</class>
    </module>
</atlassian-plugin>

Написание простого плагина макроса

Макросы — отличное место для начала, поскольку они обеспечивают немедленную визуальную обратную связь. Вот пример простого макроса:

import com.atlassian.confluence.content.render.xhtml.ConversionContext;
import com.atlassian.confluence.macro.Macro;
import com.atlassian.confluence.macro.MacroExecutionException;
import com.atlassian.confluence.renderer.radeox.macros.MacroUtils;
import com.atlassian.confluence.util.velocity.VelocityUtils;

public class MyMacro implements Macro {
    @Override
    public String execute(Map<String, String> parameters, String body, ConversionContext context) throws MacroExecutionException {
        // Простой макрос, который возвращает приветствие
        return "Привет, мир!";
    }

    @Override
    public BodyType getBodyType() {
        return BodyType.NONE;
    }

    @Override
    public OutputType getOutputType() {
        return OutputType.INLINE;
    }
}

Добавление ресурсов и конфигурации

Добавление ресурсов плагина

Ресурсы — это не-Java файлы, которые могут понадобиться вашему плагину. Вот как вы можете добавить ресурс:

<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
    <!-- ... -->
    <resource type="download" name="my-resource" location="/path/to/my/resource.txt"/>
</atlassian-plugin>

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

Если вашему плагину требуется настройка, вы можете добавить пользовательский интерфейс конфигурации:

<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
    <!-- ... -->
    <module type="web" key="my-config-ui">
        <name>Мой пользовательский интерфейс настройки</name>
        <url>/plugins/servlet/my-config-ui</url>
        <class>com.example.plugins.MyConfigUI</class>
    </module>
</atlassian-plugin>

Расширенная разработка плагинов

Использование стандартных декораторов страниц

Если вы разрабатываете плагин, который должен работать в нескольких продуктах Atlassian, вы можете использовать стандартные декораторы страниц:

<atlassian-plugin key="com.example.plugins.my-confluence-plugin" name="Мой плагин Confluence">
    <!-- ... -->
    <module type="web-panel" key="my-web-panel">
        <name>Моя веб-панель</name>
        <url>/plugins/servlet/my-web-panel</url>
        <class>com.example.plugins.MyWebPanel</class>
        <location>system.header</location>
    </module>
</atlassian-plugin>

Доступ к компонентам Confluence

Чтобы взаимодействовать с компонентами Confluence, вам необходимо следовать соглашениям об именах пакетов Java, чтобы избежать конфликтов:

import com.atlassian.confluence.core.ContentEntityObject;
import com.atlassian.confluence.core.ContentEntityManager;
import com.atlassian.confluence.user.ConfluenceUser;
import com.atlassian.confluence.user.UserAccessor;

public class MyPlugin {
    public void doSomething(ContentEntityManager contentEntityManager, UserAccessor userAccessor) {
        // Доступ к компонентам Confluence здесь
        ConfluenceUser user = userAccessor.getCurrentUser();
        // ...
    }
}

Пример рабочего процесса: создание задачи Jira из Confluence

Вот пример того, как вы можете создать плагин для генерации задач Jira из Confluence, распространённый вариант использования:

Пошаговый процесс

  1. Настройте каркас плагина: Используйте шаблон Maven для создания базового каркаса плагина.

  2. Определите описание плагина: Добавьте необходимые модули в свой atlassian-plugin.xml.

  3. Создайте макрос или веб-элемент: Напишите код Java для вашего макроса или веб-элемента, который будет инициировать создание задачи Jira.

  4. Используйте REST API или веб-хуки: Используйте Jira REST API или веб-хуки для создания задачи.

Пример кода

Вот упрощённый пример использования Jira REST API:

import com