Интеграция с DokuWiki

Подключение внешней DokuWiki, чтобы вести развернутые описания объектов в wiki и просматривать их прямо в интерфейсе инвентаризации.

Развернутые описания объектов удобно вести не в самой инвентаризации (форматирование ограничено Markdown), а во внешней wiki. Для подключения укажите в config/params-local.php:

return [
    'wikiUrl'=>'https://wiki.example.local/',
    'wikiUser'=>'inventory_doku_ro_user',
    'wikiPass'=>'inventory_doku_pass',
];

В самой DokuWiki в настройках в секции “Параметры аутентификации” необходимо

  • включить API в параметре “remote”
  • добавить добавленного выше пользователя в параметр “remoteuser”

Как это работает

  • Если в списке ссылок объекта есть ссылка, начинающаяся с wikiUrl, то содержимое этой wiki-страницы будет загружено и показано прямо в карточке объекта (либо прямо в странице, либо будет добавлена вкладка).
  • Страницы запрашиваются через JSON-RPC API DokuWiki (lib/exe/jsonrpc.php) под указанным пользователем - достаточно прав только на чтение.
  • Тот же механизм используется для рендера полей с wiki-разметкой средствами DokuWiki.

Кэширование и webhook

Загруженные из wiki страницы кэшируются на стороне инвентаризации. Чтобы кэш сбрасывался сразу при редактировании страницы в wiki, можно настроить на стороне DokuWiki (например, webhook-плагином) вызов URL:

https://inventory.example.local/wiki/invalidate-page?pageName=<идентификатор страницы>

Будет инвалидирована как сама страница, так и страницы, включающие ее через директиву {{page>...}}.

Отчет: ссылки инвентаризации в wiki

Страница Настройки → Ссылки в wiki (/wiki/links, требует полномочия admin) показывает, на какие страницы wiki ссылается инвентаризация.

Смысл отчета: встроенный в DokuWiki список «Ссылки сюда» учитывает только ссылки внутри самой wiki и ничего не знает про внешние системы. Инвентаризация же ссылается на страницы wiki из своих данных - и этот отчет показывает такие ссылки со стороны инвентаризации: по каждой странице wiki видно, из каких объектов и полей на нее ссылаются.

Что сканируется и какие ссылки распознаются:

  • поля с разметкой DokuWiki (у которых в textFields включен рендер через dokuwiki):
    • вики-ссылки [[namespace:страница]] (относительные пути разрешаются так же, как в самой wiki);
    • включения плагина include {{page>...}} и {{section>...}} - само включение тоже считается ссылкой на страницу;
    • полные адреса страниц wiki, записанные ссылкой в тексте;
  • поля-списки ссылок (тип urls, обычно «Ссылки») - адреса, ведущие на страницы этой wiki: и doku.php?id=..., и человекочитаемые пути;
  • тексты включенных страниц wiki - они запрашиваются из wiki и разбираются рекурсивно (включение внутри включения), до заданной глубины. Ссылки, написанные внутри таких страниц, по умолчанию в отчет НЕ попадают (см. ?nested=1 ниже): страницу-шаблон могут втягивать сотни объектов, и одна ее ссылка превратилась бы в сотни строк отчета, хотя в самой инвентаризации этой ссылки нет. Когда они включены, каждая такая находка помечается страницей, в тексте которой она найдена, и в отчете сворачивается в одну строку «найдено во включённой странице X - объектов: N».

Интервики-ссылки [[shortcut>страница]] ведут в другие wiki, поэтому вынесены в отдельный список внизу страницы и сгруппированы по shortcut.

Список просканированных полей раскрывается на самой странице. Управляющие параметры (кнопки-переключатели вверху либо параметры адреса):

  • ?includes=0 - не ходить в wiki, сканировать только поля инвентаризации;
  • ?nested=1 - учитывать и ссылки, написанные ВНУТРИ включенных страниц. По умолчанию они не учитываются: это ссылки самой wiki, и одна такая ссылка со страницы-шаблона попала бы в отчет по разу на каждый объект, который эту страницу втягивает. Сам факт включения при этом учитывается всегда;
  • ?depth=N - предельная глубина обхода включений (по умолчанию 3).

Страницы, которые не удалось получить (нет страницы, нет прав, wiki не настроена), перечисляются отдельным предупреждением - ссылки из них в отчет не попали.

Confluence

Помимо DokuWiki поддерживается подключение Confluence (через REST API): по аналогии задаются параметры confluenceUrl, confluenceUser, confluencePass, после чего ссылки на страницы Confluence в списках ссылок объектов также открываются во вкладке карточки объекта.