Модификация базового отчета

Дополнительную информацию о разработке отчетов можно подчерпнуть в данной статье.

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

Общая информация

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

• Добавление дополнительных фильтров данных
• Вывод дополнительных данных
• Предварительная обработка данных отчета
• Изменение параметров визуализации

В рамках платформы Эра, задача модификации отчета решается с помощью создания собственного контрола и механизма подмен (shifts).

Общий алгоритм следующий:

1. Найти необходимый контрол базового отчета
2. Создать в своём пакете собственный контрол, скопировав в него все параметры базового
3. Внести необходимые изменения в параметры контрола
4. Заместить базовый контрол новым при помощи подмены*
5. Применить изменения пакета

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

Далее, на примере базового отчета "Звонки по суткам" разберем весь процесс.

Шаг 1. Поиск контрола базового отчета

Отчет "Звонки по суткам"

Самый простой способ найти контрол отчета - это поиск по полному имени в пакете callcenter.

Для этого необходимо взять адрес страницы с отчетом:

https://[ERA_FQDN]/app/callcenter_reports/#/ui/callcenter/reports/seances/ArchiveSeancesByDateReport

Из него необходимо взять строку после /ui/:

Поиск контрола в приложении Builder

callcenter/reports/seances/ArchiveSeancesByDateReport

Далее, в приложении Builder, в разделе Controls необходимо выбрать пакет callcenter (все базовые отчеты хранятся именно в этом пакете) и указать полученное ранее значение в строке поиска.

В текущем примере "Звонки по суткам" выводится два отчета на одну страницу, поэтому сам контрол имеет тип layout, и не будет содержать настроек получения данных. Однако, в нем будут указаны вложенные контролы, которые нам и необходимы:

В коллекции items находятся два контрола - с типом table и с типом chart. Они соответствуют левой и правой области в отчете.

При этом оба этих контрола имеют общие фильтры, которые как раз определены в "родительском" контроле с типом layout.

Если необходимо добавить дополнительный фильтр в отчеты, то нужно скопировать (и при необходимости, подменить) все три контрола - В родительском необходимо добавить сам фильтр, а в дочерних - добавить применение нового фильтра к выборке данных.

Далее, разберем копирование и замещение контрола на примере "дочернего" callcenter/reports/seances/ArchiveSeancesByDateChart, который выводит график в правой части отчета.

Шаг 2. Копирование контрола

Создание копии контрола

В своем пакете необходимо создать новый контрол. Для того, чтобы не путаться, рекомендуется использовать имя контрола-копии идентичное имени базового контрола. Отличаться они будут по имени пакета. Тип контрола (controlKind) так же можно при необходимости переопределить, для того чтобы изменить способ визуализации выводимых данных. В нашем случае, мы оставляем chart. Режим работы контрола необходимо выбрать Custom.

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

Скопированные данные в контроле

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

После того, как все параметры скопированы, контрол необходимо сохранить.

Шаг 3. Модификация параметров контрола

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

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

Настройка визуализации данных

Модифицированный отчет

Параметры модифицированного отчета

Свойства контрола

Свойство	Комментарий
title	Заголовок диаграммы
subtitle	Подзаголовок диаграммы
palette	Палитра цветов
legend	JSON, описывающий работу легенды
hideSeriesLabels	Скрыть значения в столбцах диаграммы

Также на визуализацию отчета влияет настройка JSON в свойстве series. Данные параметры позволяют настроить визуализацию серий в диаграмме.

Настройка логики получения и обработки данных

Получение и обработка данных отчета описывается с помощью JSONа в свойстве data.

Пример базовой настройки (значение в defaultFilter сокращено):

{
  "allowActions": false,
  "allowDelete": false,
  "allowInsert": false,
  "allowModify": false,
  "autoCalcProperties": false,
  "className": "callcenter/seances/ArchiveSeances",
  "defaultAggr": {
    "count": [
      "count",
      "id"
    ]
  },
  "defaultFilter": [
    "and",
    [
      "or",
      [
        "isnull",
        [
          "parameter",
          "direction"
        ]
      ],
      [
        "==",
        [
          "property",
          "direction"
        ],
        [
          "parameter",
          "direction"
        ]
      ]
    ],
    ...
    [filter]
  ],
  "defaultGroupby": {
    "date": [
      "toYYYYMMDD",
      [
        "dateadd",
        [
          "property",
          "timeStart"
        ],
        "$$$TimeZoneSecondsShift$$$"
      ]
    ]
  },
  "defaultInterval": [
    [
      "parameter",
      "timeStartFrom"
    ],
    [
      "parameter",
      "timeStartTo"
    ]
  ],
  "defaultOrder": [
    {
      "date": "asc"
    }
  ],
  "fillEmptyGroups": true
}

В данном примере источником данных является класс callcenter/seances/ArchiveSeances (className), к нему применена группировка по дате с форматом YYYYMMDD (defaultGroupBy), агрегация по количеству (defaultAggr), фильтр по интервалу (defaultInrerval), а так же набор дополнительных фильтров по значению (defaultFilter).

Если в рамках модификации отчета, необходимо добавить новые фильтры, то в родительском layout-контроле описывается необходимый фильтр, а в данном JSON он добавляется в defaultFilter с привязкой к имени параметра:

["parameter", "parameter_name"]

Для построения структуры фильтра рекомендуется использовать инструмент REST Sandbox в приложении Builder. Он позволяет визуально настроить фильтр, после чего скопировать его JSON-описание.

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

Сервис при получении запроса от отчета, будет собирать и обрабатывать данные произвольным образом, и возвращать их в необходимом формате в контрол.

Разработка сервиса для отчета описана в данной статье курса по разработке приложений. Также полезным будет изучить работу с универсальным источником данных.

Шаг 4. Подмена контрола базового отчета

Модифицированный отчет можно использовать тремя способами:

• Добавить контрол в собственное приложение
• Подменить базовый контрол новым модифицированным
• Подменить приложение отчетов и добавить модифицированный контрол как новый отчет

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

Механизм подмен (shifts) позволяет подменить базовый класс/контрол/редактор/приложение/компонент сценария на собственный.

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

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

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

Подмена может быть отключена, если необходимо "откатиться" на старую версию отчета.

Для самой подмены необходимо указать два значения:

• from_FullName - значение свойства fullName базового контрола (например, callcenter/reports/seances/ArchiveSeancesByDateChart)
• to_FullName - значение свойства fullNname модифицированного контрола (например, creomate_tutorial/reports/seances/ArchiveSeancesByDateChart)

На каждый модифицированный контрол необходимо создать собственную подмену.

В случае подмены приложения, необходимо создать полный клон приложения "Отчеты", добавить в него новую вкладку и так же использовать подмену с типом Application.

Шаг 5. Применение изменений в пакете

После проведения всех настроек, необходимо применить изменения в пакете.