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

Импорт из облачной версии Confluence

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

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

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

  • архив со скриптами импорта
  • URL сервера TeamStorm
  • токен аутентификации пользователя TeamStorm
  • ключ существующего пространства TeamStorm, в который будет выполнен импорт
  • URL сервера Confluence
  • Логин (E-mail) пользователя 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. --user - логин (E-mail) пользователя Confluence

        --user "your@email.com"

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

        --spaces "Team Space" "Dev Space"

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

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

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

  • --pages запустит только этап копирования содержимого страниц и их структуры.

  • --links запустит только этап исправления ссылок. Возможно только после копирования содержимого страниц и их структуры.

  • --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 \
                        --user <login> --spaces [""]

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

        python3 conf_migration.py --all "http://teamstorm.ru" \
                "EzLCJzaWQiOiJh...vwmAVsK0ewQ" \
                "DEV" \
                "http://your-domain.atlassian.net" \
                "EzLCJzaWQiOiJh...fiPnFBcj+f3T" \
                --type cloud \
                --user "your@email.com" \
                --spaces "Team Space" "Dev Space"

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

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

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

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

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