Руководство разработчика | Отчёты

Данное руководство содержит теоретические сведения о расширении возможностей Платформы НЕЙРОСС в части построения отчетов, в частности добавления в Платформу новых шаблонов отчётов.

Пошаговая инструкция по созданию простого набора шаблонов приведена на странице Как создать свой набор шаблонов.

Общие сведения

В составе Платформы НЕЙРОСС присутствует веб-приложение «Отчеты», которое позволяет:

1. загрузить шаблоны отчётов,
2. настроить подключение к источникам данных (SQL),
3. для выбранного источника данных и выбранного шаблона отчётов заполнить форму параметров формирования отчёта,
4. сгенерировать отчёт выбранного формата (PDF, XLS и пр.) по заданному источнику данных и шаблону отчёта.

Шаблон отчёта — совокупность файлов, содержащих необходимое для Платформы НЕЙРОСС описание того, как формировать отчёт.

Шаблоны отчётов загружаются в Платформу в форме наборов. Набор шаблонов — это zip-архив, в котором размещены файлы с определением набора и шаблонов отчётов.

Для добавления в Платформу новых «пользовательских» шаблонов отчётов необходимо создать соответствующий набор с такими шаблонами и загрузить его в программу. Средствами своего набора разработчик может:

1. Добавить в Платформу свои шаблоны отчётов.
2. Произвольным образом формировать отчёты (в рамках своих шаблонов):
   1. формировать произвольные запросы к базе / базам данных,
   2. задавать полностью произвольное визуальное оформление отчёта,
   3. использовать источники данных, отличные от SQL баз данных,
   4. поддержать новые форматы экспорта отчётов в дополнение к XLS, PDF и HTML.
3. Изменять внешний вид форм ввода параметров:
   1. настраивать существующие поля ввода данных,
   2. создавать собственные поля ввода данных — например, список-перечисление для выбора опций, подгружаемых из внешней базы данных,
   3. использовать свои стили оформления для формы ввода входных параметров,
   4. и даже формировать форму ввода параметров произвольным образом.

Основной сценарий формирования отчётов в Платформе — подключение к базе данных (SQL) и формирование отчётов с помощью программных компонентов JasperReports Library. При этом разработка шаблонов отчётов преимущественно осуществляется в визуальном редакторе Jaspersoft Studio.

Краткое руководство на русском языке по созданию отчётов с помощью JasperReports и Jaspersoft Studio доступно по ссылке.

Подробная информация по Jaspersoft Studio на английском языке приведена на официальном сайте jaspersoft.com в разделе Resources.

Структура набора шаблонов

Набор шаблонов — это zip-архив, который должен содержать следующие папки и файлы:

definitions/    // папка с шаблонами
  <папка шаблона 1>/
    ...         // другие файлы шаблона
    report.conf // определение шаблона
  <папка шаблона 2>/
    ...
libs/           // папка дополнительных java-библиотек
  *.jar         // jar-файлы дополнительных библиотек
deployment.conf // определение набора

Файл deployment.conf содержит определение набора, этот файл обязательно должен присутствовать в составе архива. Если файла нет, то Платформа НЕЙРОСС не примет загружаемый zip-архив. Подробное описание данного файла приведено в разделе Определение набора шаблонов.

Для каждого шаблона в наборе должна быть отдельная подпапка в директории definitions. В этой подпапке должен присутствовать файл определения шаблона — reports.conf. Подробное описание поддиректории шаблона отчёта приведено в разделе Шаблон отчёта.

В директории libs могут размещаться jar-файлы, используемые в наборе. При использовании нестандартных компонентов ввода параметров или реализации собственной логики формирования отчёта на языке Scala / Java соответствующий код должен быть собран и в форме jar-файлов помещён в данную директорию. Подробная информация по использованию библиотек приведена в разделе Программные компоненты.

Определение набора шаблонов

Текстовый файл deployment.conf должен состоять из пар ключ=значение, размещённых на отдельных строках. При создании набора необходимо корректно задать в файле значения для следующих ключей:

Пример файла deployment.conf из набора типовых шаблонов СКУД ITRIUM приведён ниже:

deployment.key=ultima.reports.itrium
deployment.title=Типовые формы отчётов к Itrium
deployment.version=0.6.0

Шаблон отчёта

Для каждого шаблона в наборе должна быть отдельная подпапка в директории definitions. В этой подпапке должен присутствовать файл определения шаблона — reports.conf. Текстовый файл report.conf должен состоять из пар ключ=значение, размещённых на отдельных строках. При создании шаблона необходимо корректно задать в файле значения для следующих ключей:

Параметр definition.class является ключевым. В данном параметре необходимо указать имя программного компонента, который будет отвечать за подготовку и формирование отчёта по создаваемому шаблону. Разработчику доступно несколько готовых реализаций / компонентов, которые он может использовать в своём шаблоне. Разработчик может выбрать одно из следующих значений definition.class:

В зависимости от указанного значения definition.class в файле report.conf может потребоваться указать и другие параметры. См. описание конкретной реализации шаблонов.

Пример файла report.conf из модуля типовых шаблонов СКУД ITRIUM приведён ниже:

definition.class=extensions.reports.itrium.ReportDefinition
definition.htmlPaging=false
definition.supportedFormats=["pdf","xls"]

definition.generic.key="ultima.reports.itrium:byAccessPoints"
definition.generic.title="События по точкам доступа"
definition.generic.description="Список событий доступа по одной или нескольким выбранным точкам доступа / пропускам"

definition.jasper.design = {
  main: "O5.jasper",
  html: "O5.jasper"
}

Кроме report.conf в поддиректории шаблона отчёта также могут располагаться и другие файлы, необходимые для подготовки отчёта. Например *.jasper-файлы (в случае использования JasperReports Library). Состав файлов зависит от выбранной реализации шаблона отчёта.

Программные компоненты

При загрузке набора шаблонов Платформа НЕЙРОСС распаковывает zip-архив и загружает все классы из всех jar-файлов (библиотек Java) из директории libs в модуле. Эти классы могут быть использованы:

1. для расширения или создания собственной реализации формирования отчёта;
2. для реализации новых полей ввода параметров;
3. для выборки данных, вычислений или преобразования / форматирования данных по вызову из шаблона JasperReports.

Разработчик может самостоятельно реализовать соответствующие Java-классы, собрать jar-файл (один или несколько) и включить его в состав набора, поместив все необходимые jar-файлы в директорию libs zip-архива набора.

Для пунктов 1 и 2 выше разработчику необходимы определения классов API (программного интерфейса), используемых в Платформе НЕЙРОСС. Такие классы поставляются в артефакте (библиотеке) ultima-reports-api вместе с исходным кодом. Каждая версия Платформы НЕЙРОСС использует свою версию API. Последнюю версию ultima-reports-api можно загрузить по ссылке ниже.

Список версий API для предыдущих версий программ приведён ниже.

Классы базовой реализации шаблона отчёта с JasperReports Library входят в API, поэтому для базовой реализации дополнительных jar-файлов включать в директорию libs не требуется. Но, например, реализация полей ввода, используемых в типовых шаблонах СКУД к ITRIUM, не входит в API. Соответствующие классы реализованы и упакованы в отдельный jar-файл, который при их использовании необходимо поместить в директорию libs в наборе шаблонов.