Я использую Confluence чуть более двух лет, и, хотя у него есть недостатки, он неплохо помогает мне в организации контента. Он также предоставляет хороший API, который позволяет мне делать то, что программное обеспечение не может делать изначально.

Одна из вещей, которыми я занимаюсь, - это создание множества похожего контента. Я часто использую свойства страницы, и у меня есть таблица свойств страницы для отслеживания различных атрибутов документа.

Для создания и обновления этих страниц я использую почтальон. Почтальон - это отсутствующий инструмент в традиционном пакете офисных приложений. Если вы можете создать электронную таблицу в таблицах Google, вы можете использовать почтальон.

По мере того, как я продолжаю создавать нашу программу безопасности, я хочу сопоставить элементы управления с конкретными фреймворками. В этой статье основное внимание уделяется загрузке в Confluence страниц, которые представляют собой элементы управления согласно Приложению A ISO27001. Я использовал электронную таблицу здесь для создания страниц Confluence.

Настроить Atlassian

Получить токен API для Confluence довольно просто. Выполните следующие действия, чтобы создать токен.

  1. Перейдите сюда
  2. Нажмите «Создать токен API».
  3. Назовите токен (я обычно называю его датой создания)
  4. Скопируйте токен в безопасное место.

Я использую Lastpass для хранения токена для последующего извлечения. Когда у вас есть токен, вам нужно настроить почтальон.

Настройка почтальона

Если у вас не установлен Почтальон, начните с посещения сайта Почтальон и скачайте последнюю версию. После того, как у вас установлен почтальон, рекомендую создать среду.

Я назвал свою среду Jira, но имя произвольное. Кроме того, я выбрал имена jira_user и jira_token, но они тоже произвольны. Jira_token - это токен, полученный вами на предыдущих шагах. Наконец, я рекомендую вам создать jira_host, который представляет ваш экземпляр Confluence. Confluence API использует базовую аутентификацию, поэтому настройте ее в Postman ниже. После того, как вы создали среду, вам нужно проверить свои учетные данные.

Учетные данные для тестирования

Теперь, когда у вас есть учетные данные в среде, вы можете протестировать доступ к API, запросив список ваших пространств.

Почтальон использует двойные угловые скобки для замены значений переменными среды. Таким образом, здесь можно использовать значения, определенные на предыдущем шаге. Вы можете видеть, что в поле с надписью 1 выше я ввел {{jira_user}} и в поле 2 выше я ввел {{jira_token}}. Я также заменил имя хоста в используемом мной тестовом URL на {{jira_host}}. Я выбрал для тестирования космическую конечную точку, но вы можете выбрать любую конечную точку Confluence, которая вам нравится. Обратите внимание, что в качестве типа аутентификации я выбрал Обычная аутентификация. После того, как вы ввели URL-адрес, имя пользователя и токен, нажмите Отправить, и вы должны увидеть статус 200, как в поле 4 выше, и некоторые выходные данные, показанные стрелкой 5.

Распространенными ошибками являются ваши учетные данные, неверное имя пользователя или пароль. Убедитесь, что в вашем токене нет начального или конечного пробела.

Создание страницы-шаблона

Для создания массовых страниц в Confluence я использую стандартную страницу Confluence в качестве шаблона. Хотя я хотел бы использовать шаблон слияния, на момент написания этой статьи не существовало метода api для создания страницы из шаблона. Я потратил время на создание рабочей страницы с данными, которые будут частью страницы, и остановился на следующем макете.

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

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

  • Запрос JQL для ссылки на элемент управления внизу страницы перекрывает таблицу цитат. Я хотел убедиться, что правильно помечаю элементы управления, поскольку они были задокументированы и реализованы. Моя цель - пометить элементы управления соответствующими элементами управления ISO и показать их на этой странице, чтобы понять охват и пробелы.
  • Таблица цитат, вероятно, будет включать больше, чем просто элементы управления, поскольку процессы и процедуры могут также ссылаться на этот элемент управления.
  • Имя страницы представляет собой объединение ссылки на элемент управления и имени элемента управления.
  • Единственные данные, которые будут меняться на каждой странице, - это данные в таблице свойств страницы, запрос JQL и метки страниц.

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

Получите шаблон с помощью почтальона

Теперь, когда у нас есть страница, мы можем увидеть, как она выглядит в формате JSON.

Это конечная точка контента, в частности, мы запрашиваем / wiki / rest / api / content / search со следующими параметрами запроса

  • expand = body.storage, metadata.properties, history.nextVersion, version, metadata.labels, space
  • cql = title = "A.8.1.3 Допустимое использование активов" и пробел = SEC и type = page

Используйте ту же аутентификацию и имя экземпляра, что и в нашем тесте выше. Этот запрос важен, потому что мы будем использовать фактическое содержание для создания страницы позже с помощью Postman. Вы можете найти фактический контент, если прокрутите вниз в разделе ответов, пока не увидите следующее

посмотрев на атрибут «тело» в разделе «хранилище», а затем «значение», вы можете увидеть фактическое содержимое на этой странице. Это одна полная строчка в ответе. Я скопировал это ниже. Вы можете увидеть, где размещен текст в шаблоне и в различных разделах страницы.

"<ac:layout><ac:layout-section ac:type=\"two_equal\"><ac:layout-cell><h2>Definition</h2><p><br /></p><ac:structured-macro ac:name=\"details\" ac:schema-version=\"1\" ac:macro-id=\"ad531b4d-a4a1-4000-b69e-0e097244798b\"><ac:rich-text-body><p><br /></p><table data-layout=\"default\"><colgroup><col /><col /></colgroup><tbody><tr><th><p><strong>Domain</strong></p></th><td><p>Asset management</p></td></tr><tr><th><p><strong>Sub Domain</strong></p></th><td><p>Responsibility for assets</p></td></tr><tr><th><p><strong>Control Name</strong></p></th><td><p>Acceptable use of assets</p></td></tr><tr><th><p><strong>Control Reference</strong></p></th><td><p>A.8.1.3</p></td></tr><tr><th><p><strong>Control Description</strong></p></th><td><p>Rules for the acceptable use of information and of assets associated with information and information processing facilities shall be identified, documented and implemented.</p></td></tr></tbody></table><p class=\"auto-cursor-target\"><br /></p></ac:rich-text-body></ac:structured-macro><p class=\"auto-cursor-target\"><br /></p></ac:layout-cell><ac:layout-cell><p class=\"auto-cursor-target\"><br /></p><ac:structured-macro ac:name=\"note\" ac:schema-version=\"1\" ac:macro-id=\"19b3a146-341a-472e-bdaa-45febcbd438b\"><ac:rich-text-body><p>This page is auto generated. Changes may be overwritten.</p></ac:rich-text-body></ac:structured-macro><ac:structured-macro ac:name=\"toc\" ac:schema-version=\"1\" ac:macro-id=\"5afbd337-9992-439b-8028-051f4b94eeb0\" /><ac:structured-macro ac:name=\"qc-doc-citation-macro\" ac:schema-version=\"1\" ac:macro-id=\"d6d39a49-f9fa-47f0-b0c5-c01ee4d5ae1f\" /></ac:layout-cell></ac:layout-section><ac:layout-section ac:type=\"single\"><ac:layout-cell><h2>Controls</h2><ac:structured-macro ac:name=\"detailssummary\" ac:schema-version=\"3\" ac:macro-id=\"ffcbafc6-5f99-4374-adca-de476bff6fd1\"><ac:parameter ac:name=\"headings\">Control Requirements, Control Response, Updated</ac:parameter><ac:parameter ac:name=\"cql\">label = &quot;tsc&quot; and label = &quot;A_8_1_3&quot; and space = currentSpace ( )</ac:parameter></ac:structured-macro></ac:layout-cell></ac:layout-section></ac:layout>"

Алгоритм

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

Коллекция почтальона

Я создал коллекцию почтальонов, которая фиксирует этот поток здесь. Большая часть логики заключена в первом поисковом запросе. Вы можете скачать эту коллекцию и импортировать ее в Почтальон.

Первый запрос ищет страницу из итерации почтальона-бегуна. Если он находит страницу с таким именем, он обновляет ее, в противном случае он создает новую страницу.

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

После определения тестовой функции ответ извлекается из поиска. Переменная «html» - это контент из нашего поиска по шаблону в начале. Следующий раздел проходит по клавишам текущего объекта. Данные итерации - это таблица, приведенная выше. Если вы посмотрите на названия столбцов на этом листе, вы обнаружите, что они соответствуют названиям свойств таблицы. Я использую заголовок таблицы, чтобы найти аналогичное значение в исходном html, если я его найду, я заменяю значение свойств страницы значением из итерации. В противном случае значение игнорируется. Вся цель этого кода - заполнить таблицу в документе Confluence данными из таблицы Google.

В следующем разделе кода обновляется метка в запросе CQL, а затем определяется, нужно ли создать страницу или обновить страницу.

Confluence не допускает точек в ярлыках, поэтому мне пришлось заменить их подчеркиванием. Как только это будет сделано, я заменяю известный ярлык CQL ярлыком страницы. Наконец, я определяю, нужно ли мне создать или обновить страницу. Если я обновляю страницу, мне нужно увеличить ее номер версии и установить идентификатор страницы, которую я собираюсь обновить. Я также установил «setNextRequest» на имя функции обновления в моей коллекции «страница слияния обновлений». В противном случае я «setNextRequest», чтобы «создать страницу слияния». И update, и create требуют тела из html, который мы сгенерировали в начале тестовой функции.

Обе функции POST и PUT довольно просты: они просто создают / обновляют страницу и не обрабатывают ответ.

Почтальон Бегущий

Последний шаг в процессе - создание страниц с помощью Postman Runner. Бегун почтальона в основном позволяет вам перебирать коллекцию. Хотя цель runner - перебрать коллекцию с тестовыми данными для тестирования API, мы будем использовать его для загрузки данных.

Чтобы запустить раннер, нажмите кнопку бегуна в верхнем левом углу окна почтальона. После запуска Collection Runner или Runner найдите коллекцию «Добавить элементы управления ISO». Это изменит отображение и предоставит некоторые дополнительные параметры.

Выберите среду, которую мы установили в начале, загрузите CSV-файл элементов управления в файле googlesheets, затем нажмите «Run Add ISO Cont…».

Это создаст 114 страниц (количество итераций).

Смотреть вперед

Я использовал этот шаблон проектирования в нескольких случаях, когда мне нужно было импортировать или массово создавать страницы в Confluence. Я обнаружил, что API может быть очень требовательным к входным данным, а некоторые ошибки API могут быть очень загадочными. Пара основных наблюдений:

  • У почтальона возникла проблема с цитатами в тексте. Не удалось бы отправить данные с правильно экранированными кавычками для текста CSV. Я не могу вспомнить, остается ли это проблемой, но имейте в виду, что данные, которые вы импортируете, могут потребовать некоторой дезинфекции. Сначала сделайте это в таблице Google.
  • новые строки, возврат каретки, непечатаемые символы. Все это может вызвать проблемы с импортом. Если у вас возникли проблемы с созданием страниц, проверьте наличие непечатаемых символов.
  • Я всегда тестировал с несколькими образцами, прежде чем создавать большое количество страниц. Думаю, что для этого поста я тестировал одну страницу несколько раз, удаляя страницу после каждого теста, затем тестируя 5 страниц, затем еще 5 и т. Д. Страницы легко воссоздать, но удаление 114 страниц может занять много времени. Тестируйте небольшими партиями.
  • В более позднем варианте использования я обнаружил, что мое регулярное выражение оказалось не таким точным, как я надеялся. Я опубликую еще одну статью о более качественном регулярном выражении для обновления таблицы свойств страницы.
  • Я мог бы лучше справляться с ошибками. Я в основном игнорирую ошибки в коде. Было бы несложно добавить код, останавливающий выполнение в случае сбоя.
  • Я использовал похожий шаблон для Jira. Я найду время написать, как это сделать и для Jira.