Перейти к содержанию

Импорт из серверной версии Confluence

Документ описывает инструкцию по переносу пространств из серверной версии Confluence в TeamStorm.

Исходные данные

Для переноса пространств из Confluence потребуются следующие данные:

  • архив со скриптами импорта
  • URL сервера TeamStorm
  • токен аутентификации пользователя TeamStorm
  • ключ существующего пространства TeamStorm, в который будет выполнен импорт
  • URL сервера Confluence
  • персональный токен доступа пользователя Confluence
  • названия простанств Confluence, которые необходимо перенести

Подготовка запуска

  1. Установите среду выполнения Python 3.11.

  2. Установите следующие модули:

        pip install \
        Markdown==3.4.4
        requests==2.31.0
        jira2markdown==0.3.4
        dataclasses-json==0.5.7
        future==0.18.2
        pytz==2023.3
        jsonpickle==3.0.2

  3. Распакуйте архив со скриптами миграции

  4. Добавьте пользователей в TeamStorm перед запуском импорта. E-mail или отображаемое имя пользователей TeamStorm должны совпадать с пользователями Confluence для автоматического маппинга.

Получение токена аутентификации TeamStorm

Для аутентификации в API TeamStorm необходимо выбрать учетную запись пользователя, у которого есть системные роли "Администратор Core" и "Пользователь TeamStorm".

  1. Авторизуйтесь в TeamStorm в браузере с выбранной учетной записью.
  2. Откройте веб-инспектор браузера.
  3. Откройте любой запрос TeamStorm.

  4. Скопируйте из заголовка запроса Authorization токен авторизации (символы без "Bearer").

    Получение токена аутентификации TeamStorm

Создание токена Confluence

  1. Авторизуйтесь в Confluence с выбранной учетной записью.
  2. Создайте и сохраните персональный ключ доступа в профиле пользователя согласно документации Atlassian Using Personal Access Tokens

Этапы импорта

Импорт проходит в несколько этапов:

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

    На этом этапе ссылки на другие страницы сохраняют исходный адрес Confluence.

    Для последующего связывания в контент страниц добавляются служебная информация.

  2. Исправление ссылок на другие страницы Confluence. На данном этапе адреса ссылок на другие страницы заменяются ссылками на аналогичные страницы в TeamStorm. Также старые ссылки на пользователей заменяются на блок упоминания пользователей в TeamStorm.

  3. Удаление со страниц служебной информации, необходимой для исправления ссылок и связывания страниц.

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

    1. Выполнить этап 1 последовательно для всех импортируемых пространств. На этом шаге потребуется перенести все необходимые пространства в TeamStorm.
    2. Выполнить этап 2 последовательно для всех пространств. На этом этапе внутренние ссылки в импортированных пространствах будут исправлены.
    3. Выполнить этап 3 последовательно для всех пространств. На этом этапе служебные временные метаданные на страницах будут удалены. Последующее исправление ссылок и связывание страниц будет невозможно.

Параметры скрипта

  1. teamstorm_url URL сервера TeamStorm

        "https://teamstorm.io"

  2. teamstorm_token токен аутентификации пользователя TeamStorm

        "EzLCJzaWQiOiJh...vwmAVsK0ewQ"

  3. teamstorm_space_key ключ существующего пространства TeamStorm, в который будет выполнен импорт

        "DEV"

  4. confluence_url URL сервера Confluence

        "https://confluence.yourdomain.ru"

  5. confluence_token персональный токен доступа пользователя Confluence

        "EzLCJzaWQiOiJh...vwmAVsK0ewQ"

  6. --type - тип установки Confluence

        --type server

  7. --spaces - названия пространств Confluence, которые необходимо перенести

        --spaces "Team Space" "Dev Space"

  8. Указание выполняемых этапов импорта

    Этапы импорта описаны в разделе Этапы импорта

  9. --all запустит этап копирования содеожимого страниц.

  10. --clean запустит этап удаления служебной информации. Возможно только после копирования содержимого страниц их структуры. После удаления служебной информации будет невозможно выполнить исправление ссылок и связывание страниц.

Запуск скрипта

  1. Перейдите в папку со скриптами

  2. Выполните команду c необходимыми параметрами

        python3 conf_migration.py --all|pages|links|clean <teamstorm_url> \
                            <teamstorm_token> \
                            <teamstorm_space_key> \
                            <confluence_url> \
                            <confluence_token> \
                            --type server --spaces [""]

    Пример вызова скрипта:

        python3 conf_migration.py --all "http://teamstorm.ru" \
                "EzLCJzaWQiOiJh...vwmAVsK0ewQ"
                "DEV"
                "http://local-confluence.yourdomain.ru"
                "EzLCJzaWQiOiJh...fPnFBcj+f3T"
                --type server
                --spaces "Team Space" "Dev Space"

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

  4. В случае возникновения ошибок соединения скрипт можно перезапустить c теми же параметрами, импорт продолжит перенос страниц.

Результат переноса

В результате будет выполнен перенос из указанных пространств Confluence в заданное пространство TeamStorm:

  1. Страницы и их структура
  2. Текст, изображения и их форматирование содержимого страниц
  3. Контент, генерируемый макросами Confluence в нередактируемом виде (текст и изображения)
  4. Диаграммы draw.io в редактируемом формате
  5. Ссылки между страницами
  6. Упоминания пользователей на страницах
  7. Вложения страниц