Edit confluence with n8n

Редактирование Confluence с помощью n8n: Полное руководство по автоматизации

n8n — это инструмент с открытым исходным кодом для оркестрации рабочих процессов (workflow automation), который позволяет соединять различные приложения и сервисы без необходимости писать код. Confluence — это корпоративная вики-платформа от Atlassian для совместной работы и хранения документации. Интеграция n8n с Confluence предоставляет мощные возможности для автоматического создания, обновления, форматирования и управления страницами, что значительно экономит время и снижает количество ручных ошибок.

Принципы интеграции n8n с Confluence

Взаимодействие между n8n и Confluence осуществляется через официальный REST API Confluence. n8n использует для этого специальные ноды (нода — узел рабочего процесса): Confluence Trigger (для инициирования workflows по событиям) и Confluence (для выполнения операций). Для аутентификации в большинстве случаев используется метод Basic Auth (логин и пароль) или более безопасный API-токен, созданный в учетной записи Atlassian. Рабочий процесс (workflow) в n8n строится путем соединения нод в определенной последовательности, где выходные данные одной ноды становятся входными для следующей.

Настройка учетных данных Confluence в n8n

Перед созданием рабочих процессов необходимо настроить доступ к вашему экземпляру Confluence. Это делается в разделе Credentials.

• Тип аутентификации: Basic Auth или OAuth2 (для облачного Confluence).
• URL: Адрес вашего Confluence (например, https://your-domain.atlassian.net/wiki для Cloud).
• Пользователь: Email вашей учетной записи для Cloud или имя пользователя для Server/Data Center.
• Пароль/API Token: Для облачной версии необходимо использовать API-токен. Для Server/Data Center можно использовать пароль.

Основные ноды для работы с Confluence и их параметры

Нода «Confluence» (для операций)

Эта нода выполняет все основные действия со страницами и пространствами (spaces).

Ресурс (Resource)	Операция (Operation)	Ключевые параметры и описание
Page	Create	Space Key: Ключ пространства, где будет создана страница. Title: Заголовок страницы. Content Type: Обычно «storage» (формат Confluence Storage). Content: Тело страницы в формате HTML или wiki markup (зависит от выбранного content type). Parent Page ID: Опционально. ID родительской страницы для создания иерархии.
	Update	Page ID: Уникальный идентификатор обновляемой страницы. Title: Новый заголовок (можно оставить прежним). Content: Новое содержимое. Важно: по умолчанию API Confluence полностью заменяет контент. Version: Должен быть на 1 больше текущей версии. Обычно это значение вычисляется динамически из данных предыдущей ноды (например, «Get» или «Search»).
	Get	Получение полной информации о странице по ее Page ID, включая текущий контент и номер версии.
	Search	Поиск страниц по запросу (CQL — Confluence Query Language). Возвращает список страниц с их основными данными.
Space	Get All	Получение списка всех пространств, к которым у пользователя есть доступ. Полезно для динамического выбора Space Key в workflow.
Attachment	Upload	Загрузка файла на страницу. Требует указания Page ID и пути к файлу (из предыдущей ноды, например, «Read Binary File»).

Нода «Confluence Trigger»

Эта нода запускает рабочий процесс при наступлении события в Confluence. Она работает по принципу опроса (polling) API с заданным интервалом.

• События (Events): Page Created, Page Updated, Page Trashed.
• Параметры: Можно фильтровать события по Space Key, чтобы workflow реагировал только на изменения в определенных пространствах.

Практические примеры рабочих процессов (Workflows)

Пример 1: Автоматическое создание еженедельного отчета

Workflow запускается по расписанию (нода «Schedule Trigger»), собирает данные из внешних источников (например, Google Sheets, базы данных, API Jira), форматирует их в HTML-таблицу и создает новую страницу в Confluence.

• Шаг 1: Нода «Schedule Trigger» (каждый понедельник в 9:00).
• Шаг 2: Нода «Google Sheets» → получение данных по продажам за неделю.
• Шаг 3: Нода «Code» (или «Template») → преобразование массива данных в HTML-код для Confluence.
• Шаг 4: Нода «Confluence» (Create Page) → создание страницы с заголовком «Отчет по продажам за [Дата]» и сгенерированным HTML-контентом в заданном пространстве.

Пример 2: Обновление страницы-дашборда на основе данных из Jira

Workflow обновляет существующую страницу, чтобы в ней всегда была актуальная статистика.

• Шаг 1: Нода «Schedule Trigger» (каждый час).
• Шаг 2: Нода «Jira» → поиск задач по JQL (например, все открытые задачи в проекте XYZ).
• Шаг 3: Нода «Confluence» (Get Page) → получение текущего контента и версии страницы-дашборда по ее ID.
• Шаг 4: Нода «Code» → извлечение номера версии из данных шага 3 и создание нового контента путем вставки актуальных данных Jira в определенный раздел HTML (требует парсинга).
• Шаг 5: Нода «Confluence» (Update Page) → отправка обновленного контента с версией, увеличенной на 1.

Пример 3: Копирование и реструктуризация контента при срабатывании триггера

При создании новой страницы в пространстве «Заявки» автоматически создается ее структурированная копия в пространстве «Архив».

• Шаг 1: Нода «Confluence Trigger» (Page Created, Space Key = «ЗАЯВКИ»).
• Шаг 2: Нода «Confluence» (Get Page) → получение полного контента новой страницы.
• Шаг 3: Нода «Code» → добавление в начало контента стандартного информационного блока (например, «Перенесено из Заявок [Дата]»).
• Шаг 4: Нода «Confluence» (Create Page) → создание страницы в пространстве «АРХИВ» с модифицированным контентом. В качестве родителя можно указать ID определенной страницы-индекса.

Форматирование контента для Confluence

API Confluence Cloud работает с двумя основными форматами контента, которые указываются в поле Content Type.

Тип контента (Content Type)	Описание	Пример тела контента (значение поля «Content»)
storage (рекомендуется)	Современный формат на основе HTML, который используется редактором Confluence. Поддерживает макросы, сложное форматирование и адаптивен для будущих обновлений.	<ac:structured-macro ac:name="info"><ac:rich-text-body><p>Это пример текста в макросе info.</p></ac:rich-text-body></ac:structured-macro>
wiki (устаревший)	Старый формат Wiki Markup. Может быть полезен для простых задач, но не поддерживает все возможности нового редактора. В будущем может быть удален.	{info}Это пример текста в макросе info.{info}

Для генерации корректного HTML в формате storage можно использовать следующие подходы:

• Создать страницу вручную в Confluence, отформатировать ее как нужно, а затем через ноду «Get» посмотреть, какой HTML был сгенерирован. Этот HTML можно использовать как шаблон.
• Использовать ноду «HTML» в n8n для экранирования или ноду «Template» для подстановки переменных в HTML-шаблон.
• Для создания таблиц, информационных блоков (info, warning), панелей (panel) и других элементов необходимо использовать соответствующие макросы Confluence в формате storage.

Обработка вложений (Attachments)

n8n позволяет автоматизировать загрузку файлов на страницы Confluence. Типичный workflow:

1. Нода «Read Binary File» (или загрузка из внешнего URL/сервиса) получает файл.
2. Нода «Confluence» (Upload Attachment) принимает на вход бинарные данные и загружает их на страницу с указанным Page ID. Можно указать имя файла и комментарий.

Обработка ошибок и отладка

При построении сложных workflows важно предусмотреть обработку ошибок.

• Проверка статус-кодов: Нода Confluence возвращает информацию об успешности операции. Следующая нода может проверять поле status.
• Нода «Error Trigger»: Позволяет создать ветку workflow, которая выполнится только в случае ошибки в предыдущих нодах (например, отправка уведомления в Slack).
• Отладка: Используйте функцию «Execute Node» для пошагового запуска workflow. Внимательно изучайте входные и выходные данные каждой ноды, особенно поля body, version, id.
• Частая ошибка при обновлении: Неверный номер версии (поле version). Он должен быть целым числом и строго на единицу больше текущей версии страницы в Confluence.

Советы по оптимизации и безопасности

• Для часто используемых значений (например, Space Key, ID родительской страницы) создавайте отдельные параметры workflow (Workflow Settings), чтобы легко менять их в одном месте.
• Не храните логины и пароли в открытом виде. Всегда используйте Credentials в n8n. Для облачного Confluence применяйте API-токены, а не пароли учетной записи.
• Настраивайте триггеры (особенно «Schedule Trigger») с разумной частотой, чтобы не создавать излишней нагрузки на API Confluence.
• При массовых операциях (создание/обновление многих страниц) используйте функцию пагинации в нодах поиска и добавляйте задержки между запросами, чтобы не превысить лимиты API (rate limits).

Часто задаваемые вопросы (FAQ)

Как обновить только часть страницы, а не полностью заменять контент?

Стандартный метод Update Page в API Confluence всегда выполняет полную замену. Для частичного обновления необходимо:

1. Сначала получить текущий контент страницы (нода «Get»).
2. В ноде «Code» или «Template» программно отредактировать полученный HTML, найдя и изменив нужный фрагмент (например, с помощью регулярных выражений или парсеров HTML).
3. Отправить измененный полный контент обратно через «Update Page».

Это требует аккуратной работы с HTML-структурой.

Можно ли работать с локальным (on-premise) Confluence Server?

Да. При настройке учетных данных в n8n необходимо указать URL вашего локального сервера Confluence (например, http://your-confluence-server:8090). Метод аутентификации — Basic Auth с логином и паролем пользователя, имеющего необходимые права. Убедитесь, что сервер n8n имеет сетевой доступ к серверу Confluence.

Как создать сложную страницу с макросами, таблицами и картинками?

Самый надежный способ:

1. Вручную создайте в Confluence страницу-образец с желаемым форматированием.
2. С помощью ноды «Confluence» (Get Page) получите HTML-код этой страницы в формате storage.
3. Используйте этот код как шаблон в ноде «Template». Замените динамические части (текст, цифры) на выражения вида {{$json.body.storage.value}} или с помощью ноды «Code».
4. Используйте полученный результат в ноде «Create» или «Update».

Почему операция Update Page возвращает ошибку 409 Conflict?

Ошибка 409 почти всегда указывает на проблему с номером версии (version). Текущая отправляемая версия не на 1 больше актуальной версии страницы в Confluence. Убедитесь, что:

• Вы предварительно получаете страницу через «Get Page» непосредственно перед обновлением.
• Вы извлекаете значение version.number из результата «Get Page».
• В ноде «Update Page» вы устанавливаете поле Version в значение {{$json.version.number + 1}}.

Если страницу мог отредактировать другой пользователь между операциями «Get» и «Update», реализуйте повторную попытку (retry logic) в workflow.

Как искать страницы по сложным критериям?

Используйте операцию «Search» и язык запросов CQL (Confluence Query Language). Примеры:

• space=DEMO and type=page — все страницы в пространстве DEMO.
• title~"Отчет" and creator=currentUser() and created>=startOfMonth() — страницы с «Отчет» в заголовке, созданные текущим пользователем в этом месяце.
• id=123456 — поиск по ID страницы.

Результаты поиска можно использовать для последующего получения полного контента («Get Page») или массового обновления.

Можно ли удалять страницы через n8n?

Прямой операции «Delete» в ноде Confluence на момент написания статьи нет. Однако удаление можно эмулировать:

1. Используя операцию «Update Page» и установив поле status в значение trashed в теле запроса (для Cloud API).
2. Либо выполняя прямой HTTP-запрос к API Confluence через ноду «HTTP Request» с методом DELETE на соответствующий endpoint (/wiki/rest/api/content/{id}).

Перед использованием этих методов внимательно изучите документацию API вашей версии Confluence.