Skip to content

Формат шаблона отчетов

В качестве администратора Apiary вы можете загружать собственные шаблоны отчетов в систему.

Как создать свой шаблон отчета?

  1. Определите, какие данные хотите включить в будущий отчет.
  2. Выберите шаблон-основу для отчета.
  3. Выберите поля и подберите фильтры, чтобы добавить выбранные данные в отчет.
  4. Выберите стиль оформления отчета.
  5. Загрузите свой шаблон в Apiary и используйте его для генерации уникальных отчетов.

Подробнее о каждом этапе смотрите далее.

Отбор данных для отчета

  • Выберите, какие данные нужно включить в отчет. Исходя из этого, вы определите, какие поля и фильтры понадобятся. Можно включить следующее:

    • Любой текст, который будет просто скопирован в выходной файл.
    • Оформление: оглавление, верхние и нижние колонтитулы, титульный лист и т.д.
    • Информация по ишам в проекте: данные из схемы иши по умолчанию либо из всех доступных схем.
    • Изображения в форматах, поддерживаемых DOCX (например, PNG и JPEG).

    Примечание: файлы в других форматах, прикрепленные к ишам, в отчет не попадут.

Report sample Apiary

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

  • Узнайте технические названия полей схем ишей (такие как generalDescription, myString и т.д.). Для этого воспользуйтесь фильтром json с переменной this.

    Создайте шаблон со следующим содержимым: 

    {this | json}

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

Выбор шаблона-основы

  1. Войдите в Apiary в качестве администратора.

  2. В левом меню выберите Админ > Шаблоны отчетов.

  3. Выберите шаблон, нажав на его название:

    • template.docx — набор полей для той схемы иш, которая выбрана в проекте по умолчанию. Для этого шаблона проще добавлять поля вручную. Данный шаблон можно оставить без особых изменений, если нужен краткий отчет.
    • universal-template.docx — максимум полей с техническими названиями. Это универсальный шаблон для всех доступных схем ишей. Выбирайте этот шаблон, если вам недостаточно данных, собранных из схемы ишей по умолчанию.

Использование фильтров в шаблоне отчётов

Используйте специальные фильтры в шаблоне, чтобы форматировать поля отчета, а также извлекать и преобразовывать нужные данные.
Выберите подходящие фильтры из списка ниже. С полным списком доступных фильтров можно ознакомиться на официальной странице Docxtemplater. Docxtemplater используется как основа для генератора отчётов (шаблонизатора) в Apiary.

Инструкции для шаблонизатора нужно записывать в {}.

Общие правила фильтрации:

  • Фильтр без параметров: {myExpression | filter}
  • Фильтр с одним параметром: {myExpression | filter:"argument1"}
  • Фильтр с несколькими параметрами: {myExpression | filter:variable:variable2}

Список базовых фильтров

  • lower

Конвертирует строку в нижний регистр.

{issue.name|lower}
  • upper

Конвертирует строку в верхний регистр.

{issue.name | upper}
  • length

Определяет длину коллекции (списка или строки).

{issues | length}
{issues | where:'totalScore >= 2' | length}
  • prop

Возвращает произвольное свойство объекта.

{issues | prop:'length'}

  • where
    Фильтрует список элементов.

    • Общий показатель риска больше или равен двум (например, 2 — средний или 3 — высокий уровень риска):
    {#issues | where:'totalScore >= 2'} {name} {/}
    • Общий показатель риска равен одному (где 1 — низкий уровень риска):
    {#issues | where:'totalScore === 1'} {name} {/}
    • Вероятность меньше трех (например, 1 — низкий или 2 — средний уровень вероятности):
    {#issues | where:'probabilityScore < 3'} {name} {/}
    • Общий показатель риска равен трем, и критичность больше или равна двум (возможные значения: && И || ИЛИ):
    {#issues | where:'totalScore === 3 && criticalityScore >= 2'} {name} {/}
    • Фильтр по любому настраиваемому полю с числовым значением:
    {#issues | where:'myCustomFieldEstimatedLosses > 9000'} {name} {/}

  • find

Поиск по элементам.

{(issues | find:'id === 42').name}
  • sortBy, sortByAsc

Сортировка списка по возрастанию. Вы можете добавить несколько параметров:

{#issues | sortBy:'totalScore'} {name} {/}
{#issues | sortBy:'totalScore':'name'} {name} {/}
  • sortByDesc

Сортировка списка по убыванию. Вы можете добавить несколько параметров:

{#issues | sortByDesc:'totalScore'} {name} {/}
{#issues | sortByDesc:'totalScore':'name'} {name} {/}
  • sumBy

Сумма значения поля объектов из списка.

{issues | sumBy:'myCustomFieldBusinessExpenses'}
  • toFixed

Приводит число к строковому представлению с фиксированным количеством знаков после точки.

{myNumber | toFixed:2}
  • json

Выводит значение переменной в json, что полезно для отладки при написании шаблона. Рекомендуется использовать с переменной this — это отобразит текущую область видимости и все доступные переменные.

{myVariable | json}
{this | json}
  • replaceText

Замена одной подстроки на другую в тексте.

{name | replaceText:’Web’:’Веб’}
  • replaceByRegex

Замена регулярного выражения (Regex) на строку. Фильтр осталяет текст только до разделителя (в данном случае — пробела), а остальное убирает. Рекомендуется использовать совместно с фильтром replaceText, когда строки с содержимым по типу CHECK.32.1-4 Проверка работы веб-приложения требуется оформить в разные столбцы таблицы.

{name | replaceByRegex: ‘^([^ ]+).*’ : ‘$1’ }

Пример вывода:

CHECK.32.1-4
  • displayValue

Отображение значения полей с перечислениями (например, score, select, radio). Вызывается с системным значением поля (например, 1 для score). Принимает описание поля из справочника presetFieldsMap.

Пример для поля Score:

{#issues}
{totalScore | displayValue:presetFieldsMap.totalScore}
{/issues}

Пример для кастомных полей:

  • одиночный выбор или радиокнопки (radio button):
{#issues}
{myCustomField | displayValue:presetFieldsMap.myCustomField} 
{/issues}
  • множественный выбор (multiple choice):
{#issues}
{#myCustomListField}
{this | displayValue:presetFieldsMap.myCustomListField}
{/myCustomListField}
{/issues}

Выбор стилей для полей отчета

Вы можете редактировать параметры стилей и создавать собственные фильтры полей в DOCX-шаблонах.
Для всех полей будет сохранено форматирование, которое используется в шаблоне отчета.

Для поля ишей в шаблонах отчетов также можно использовать Markdown.

Report styles

Пример изменений в шаблоне отчета:

  1. Обновление параметров стилей и создание новых стилей;
  2. Добавление текста;
  3. Вставка изображений, не привязанных к ишам.

Стили полей Markdown

Внимание! Не меняйте идентификаторы (ID) и названия стилей в шаблонах template.docx и universal-template.docx.
В настоящее время генератор отчетов поддерживает только предустановленные названия стилей.

Используйте названия и идентификаторы стилей, перечисленные ниже. Параметры стилей можно изменить в самом DOCX-шаблоне.

Данные стили применяются только для полей Markdown (General description, Risk description, Technical description и Recommendations).

ID стиля Название стиля Применение Комментарий
H1 H1 Параграф Заголовок уровня 1
H2 H2 Параграф Заголовок уровня 2
H3 H3 Параграф Заголовок уровня 3
H4 H4 Параграф Заголовок уровня 4
H5 H5 Параграф Заголовок уровня 5
BodyExpRep Body (Exp_Rep) Параграф Все стандартные параметры body
BodyExpRepChar Body (Exp_Rep) Char Символ Символы внутри стандартного параметра body
Code Code Параграф Блочные строки кода
CodeChar Code Char Символ Строка кода
InternetLink Internet Link Символ Ссылки на внешние ресурсы
Emphasis Emphasis Символ Курсив (Italic)
StrongChar Strong Char Символ Жирное выделение (Bold)
PictureCaption Picture Caption Параграф Название рисунков и таблиц
Table style 1 Table style 1 Таблица Стиль таблиц

Стили для значений риска

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

ID стиля Название стиля Применение Комментарий
vulnrate vulnrate Параграф Абзац для уровня риска иши
styleRatingLow styleRatingLow Символ Символ для низкого уровня риска иши (зеленый)
styleRatingMedium styleRatingMedium Символ Символ для среднего уровня риска иши (желтый)
styleRatingHigh styleRatingHigh Символ Символ для высокого уровня риска иши (красный)

Загрузка собственного шаблона в Apiary

Чтобы добавить новый шаблон для отчета:

  1. Войдите Apiary в качестве администратора.

  2. В левом меню выберите Админ > Шаблоны отчетов.

  3. Измените название шаблона, прежде чем загружать его в Apiary.

  4. Нажмите Загрузить шаблон (Upload template) и загрузите файл с вашего компьютера.

    При загрузке шаблонов с существующим названием Apiary автоматически изменит имя файла, добавив дату и время — например, [2022-01-06T15: 49: 23.895Z] template.docx.

  5. Новый шаблон появится в списке шаблонов.

upload_report

Теперь вы можете использовать собственные шаблоны при создании отчетов по ишам.

Для этого перейдите в нужный проект, в левом меню нажмите Иши и выберите иши. Нажмите Собрать отчет (Generate report) в правом нижнем углу и выберите свой шаблон.

Примечание: для корректного отображения оглавления и нумерации отчета нажмите Ctrl + A после F9, затем выберите Обновить все.