Сервис генерации отчетов

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

Формирование отчётов осуществляется при помощи библиотеки JasperReports® Library.

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

Чтобы сформировать отчет требуется подготовить шаблон отчета.
Для подготовки шаблонов отчетов сервис предлагает возможность создания или модификации шаблонов отчётов и привязки к ним составляющих их файлов. Чтобы использовать шаблоны перейдите на страницу https://<Platform_instance_URL>/demo/, выберите пункт Отчеты и закладку Шаблоны.

Формирование файлов, входящих в состав шаблона отчёта

Формирование файлов, входящих в состав шаблона отчёта, осуществляется при помощи произвольного текстового редактора (например, Notepad++), позволяющего сохранять файлы в форматах JRXML (XML), R, JSON. В представленной ниже таблице приведено соответствие файла, входящего в состав шаблона отчёта, и формата, в котором он должен быть реализован:

Вид файла	Формат	Примеры файлов
Файл шаблона отчёта библиотеки Jasper Reports	JRXML (XML)	books-jr-template.zip, audit-template.zip, templateAudit.zip
Файл скрипта трансформации данных	R	books-r-script-simple.zip, books-r-script-services-call-and-data-transformation.zip, books-r-script-service-call.zip, audit-script.zip, generalized_script.zip
Файл настроек порядка формирования отчёта	JSON	books-json-settings.zip, audit-settings.zip, settingsAll.zip

подсказка

Файл шаблона отчёта библиотеки Jasper Reports может быть создан с использованием графической среды TIBCO Jaspersoft Studio версии 6.11.0.

Трансформация данных

Файл скрипта трансформации данных предназначен для выборки информации из внешних, по отношению к сервису, источников и преобразовании информации к виду, обрабатываемому библиотекой Jasper Reports.

Выборка и преобразование информации

{
    "parameters": {
        <наименование параметра 1>: <значение параметра 1>,
        ... ... ...
        <наименование параметра m>: <значение параметра m>
    },
    "data": [
        <кортеж данных для построения отчёта 1>,
        ... ... ...
        <кортеж данных для построения отчёта k>
    ]
}

или

{
    "parameters": {
        <наименование параметра 1>: <значение параметра 1>,
        ... ... ...
        <наименование параметра m>: <значение параметра m>
    },
    "data": {
        <наименование перечня кортежей данных для построения отчёта>: [
            <кортеж данных для построения отчёта 1>,
            ... ... ...
            <кортеж данных для построения отчёта k>
        ]
    }
}

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

Наименование	Назначение	Входные параметры	Тип возвращаемого значения (R)	Примечания
get	Выборка данных запросом HTTP GET из внешнего сервиса.	url — URL доступа к сервису; contentType — тип MIME запроса HTTP; pathParameters — карта соответствия наименования переменных секции path URL доступа к сервису и значений, присвоенных этим переменным; queryParameters — карта соответствия наименования переменных секции query URL доступа к сервису и значений, присвоенных этим переменным.	character
post	Выборка данных запросом HTTP POST из внешнего сервиса.	url — URL доступа к сервису; contentType — тип MIME запроса HTTP; pathParameters — карта соответствия наименования переменных секции path URL доступа к сервису и значений, присвоенных этим переменным; queryParameters — карта соответствия наименования переменных секции query URL доступа к сервису и значений, присвоенных этим переменным; body — тело запроса.	character
getPlatform	Выборка данных запросом HTTP GET из сервиса Платформы или продукта, на её основе.	destination — адрес сервиса в формате <наименование сервиса>:<метод сервиса>; contentType — тип MIME запроса HTTP; pathParameters — карта соответствия наименования переменных секции path URL доступа к сервису и значений, присвоенных этим переменным; queryParameters — карта соответствия наименования переменных секции query URL доступа к сервису и значений, присвоенных этим переменным.	character	Для корректного взаимодействия с подсистемой безопасности Платформы необходимо сформировать секцию authentication в файле настроек порядка формирования отчёта.
postPlatform	Выборка данных запросом HTTP POST из сервиса сервиса Платформы или продукта, на её основе.	destination — адрес сервиса в формате <наименование сервиса>:<метод сервиса>; contentType — тип MIME запроса HTTP; pathParameters — карта соответствия наименования переменных секции path URL доступа к сервису и значений, присвоенных этим переменным; queryParameters — карта соответствия наименования переменных секции query URL доступа к сервису и значений, присвоенных этим переменным; body — тело запроса.	character	Для корректного взаимодействия с подсистемой безопасности Платформы необходимо сформировать секцию authentication в файле настроек порядка формирования отчёта.
graphql	Выборка информации из источника данных GrpahQL.	name — наименование источника данных GraphQL (см. раздел Настройка порядка формирования отчёта); operationName — наименование операции выборки данных в запросе информации в формате GraphQL. Необязательный параметр; variables — параметры запроса к серверу GraphQL. Необязательный параметр.	character	Для корректного взаимодействия с подсистемой безопасности Платформы необходимо сформировать секцию authentication элемента раздела graphql источника данных GraphQL в файле настроек порядка формирования отчёта.

Настройка порядка формирования отчёта

Структура файла настроек порядка формирования отчёта должна иметь следующий вид:

Структура файла настроек порядка формирования отчёта

{
    "parameters": [{
        "name": <обязательное уникальное наименование параметра 1>,
        "description": <необязательное описание параметра 1>,
        "type": <необязательный тип параметра 1, по умолчанию имеет тип string>,
        "value": <необязательное значение параметра 1>,
        "default.value": <необязательное значение параметра 1 по умолчанию>
    }, {
        ... ... ...
    }, {
        "name": <обязательное уникальное наименование параметра N>,
        "description": <необязательное описание параметра N>,
        "type": <необязательный тип параметра N, по умолчанию имеет тип string>,
        "value": <необязательное значение параметра N>,
        "default.value": <необязательное значение параметра N по умолчанию>
    }],
    "customView": <необязательное наименование специализированной формы ввода параметров формирования отчёта>,
    "graphql": [{
        "name": <наименование источника данных GraphQL 1>,
        "endpoint": <URL доступа к серверу GraphQL 1 по протоколу HTTP(S)>,
        "query": <запрос данных в формате GraphQL 1>,
        "authentication": {
            "client.id": <обязательный идентификатор клиента OAuth 2.0/OpenID>,
            "grant.type": <обязательный тип доступа>
        }
    }, {
        ... ... ...
    }, {
        "name": <наименование источника данных GraphQL T>,
        "endpoint": <URL доступа к серверу GraphQL T по протоколу HTTP(S)>,
        "query": <запрос данных в формате GraphQL T>,
        "authentication": {
            "client.id": <обязательный идентификатор клиента OAuth 2.0/OpenID>,
            "grant.type": <обязательный тип доступа>
        }
    }],
    "authentication": [{
        "service.name": <обязательное наименование сервиса 1 Платформы, или продукта, построенного на её основе>,
        "client.id": <обязательный идентификатор клиента OAuth 2.0/OpenID>,
        "grant.type": <обязательный тип доступа>
    }, {
        ... ... ...
    }, {
        "service.name": <обязательное наименование сервиса M Платформы, или продукта, построенного на её основе>,
        "client.id": <обязательный идентификатор клиента OAuth 2.0/OpenID>,
        "grant.type": <обязательный тип доступа>
    }]
}

Значение поля type может принимать одно из следующих значений:

Значение поля	Описание
number	число с плавающей точкой
bigint	целое число произвольной длины
string	строка символов
boolean	логическое значение

к сведению

Cекция authentication элемента раздела graphql не является обязательной.

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

Для формирования шаблона отчета следует:

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

Синхронное формирование отчёта

1. сформировать шаблон отчёта;
2. сформировать отчёт (смотри метод синхронного формирования отчёта в разделе Методы API).

Асинхронное формирование отчёта

1. сформировать шаблон отчёта;
2. сформировать отчёт (смотри метод асинхронного формирования отчёта и/или методы взаимодействия с менеджером заданий в разделе Методы API).

Модель данных

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

Параметры настройки

Параметры настройки сервиса генерации отчетов задаются следующими способами:

1. Файл settings.json.
2. Переменная окружения.
3. Глобальная конфигурация nginx Платформы.
4. Конфигурация сервиса Платформы.

Наименование параметра настройки не зависит от способа задания.

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

1. Параметру присваивается значение из файла settings.json.
2. Параметру присваивается значение из переменной окружения.
3. Параметру присваивается значение из Global Parameters nginx. Посмотреть значения можно в Консоли администрирования Платформы в разделе Configuration, нажав на кнопку Global Parameters.
4. Параметру присваивается значение из конфигурации сервиса Платформы.
5. Параметру присваивается значение из переменной окружения.

Например, если параметр задан в файле settings.json, в переменной окружения и в глобальной конфигурации nginx, результирующему параметру конфигурации будет присвоено значение из окружения.

Основные параметры конфигурации сервиса, соответствующие им переменные окружения, задаваемые при запуске контейнера Docker-сервиса, и параметры конфигурации сервиса конфигурации Платформы приведены в таблице.

Наименование	Значение по умолчанию	Примечания
RABBITMQ_URI	amqp://admin:admin@rabbitmq:5672	Параметр осуществления аудита операций сервиса.
discovery:heartbeat.period	10000	Интервал между проверками работоспособности Discovery-сервиса. Значение параметра указывается в миллисекундах.
licenses.module:name	licenses_module	Наименование сервиса.
licenses.module:skills	[ "licenses processing", "Product" ]	Значение параметра представляет собой массив строк.
ConfigServer	{ConfigServer}	Базовый url Платформы. (В случае, если Платформа развёрнута без дополнительных настроек, это путь до nginx)
identityConfiguration__identityServiceUrl	{ConfigServer}/identity	Url функционала identity
spring.datasource.driver-class-name	{Не задано}	Настройки для подключения к базе данных
SPRING_DATASOURCE_URL	{Не задано}	Настройки для подключения к базе данных
SPRING_DATASOURCE_USERNAME	{Не задано}	Настройки для подключения к базе данных
SPRING_DATASOURCE_PASSWORD	{Не задано}	Настройки для подключения к базе данных
http:request:timeout	10	Величина интервала ожидания отклика по протоколу HTTP(S), выраженная в секундах.
logging:LogLevel:Default	debug	Уровень логирования корневого журнала сервиса.
ApiConfiguration__ClientSecrets__0__ClientId	{Не задано}	Логин клиента identity.
ApiConfiguration__ClientSecrets__0__Secret	{Не задано}	Пароль клиента identity.
ApiConfiguration__ClientSecrets__1__ClientId	{Не задано}	Логин клиента identity.
ApiConfiguration__ClientSecrets__1__Secret	{Не задано}	Пароль клиента identity.
ApiConfiguration__ClientSecrets__2__ClientId	{Не задано}	Логин клиента identity.
ApiConfiguration__ClientSecrets__2__Secret	{Не задано}	Пароль клиента identity.
ApiConfiguration__ClientSecrets__3__ClientId	{Не задано}	Логин клиента identity.
ApiConfiguration__ClientSecrets__3__Secret	{Не задано}	Пароль клиента identity.
ApiConfiguration__ClientSecrets__4__ClientId	{Не задано}	Логин клиента identity.
ApiConfiguration__ClientSecrets__4__Secret	{Не задано}	Пароль клиента identity.
ApiConfiguration__ClientSecrets__5__ClientId	{Не задано}	Логин клиента identity.
ApiConfiguration__ClientSecrets__5__Secret	{Не задано}	Пароль клиента identity.
ProductName	{Не задано}	Наименование продукта
ProductVersion	{Не задано}	Версия продукта
PlatformVersion	{Не задано}	Версия Платформы
DiscoveryNodeFileLocation	/usr/src/nodeId.txt	Местоположение файла с сохранённым nodeId Discovery-сервиса
StandName	LocalStand	Название стенда, на котором развёрнут сервис
Kafka__AuditProducerTopic	{stand}-Audit	Топик Kafka для отправления сообщений аудита
audit.kafka.repeats	localhost:9094	Сервер Kafka
TracesEnabled	false	Флаг, определяющий нужно ли отправлять трейсы
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	-	Endpoint для отправки трейсов

Описания параметров сервиса генерации отчетов

Описания параметров сервиса генерации отчетов в подробностях.

Параметры сервиса

Идентификатор задания

Наименование поля	Тип поля	Описание поля
taskID	string	идентификатор задания

Параметры запроса добавления задания

Наименование поля	Тип поля	Описание поля
kind	string	вид задания (допустимые значения: EXPORT_REPORT_TO_FILE_SERVICE, EXPORT_REPORT_TO_SFTPS, MOVE_REPORT_TEMPLATES_FILES_TO_DATABASE)
parameters	string	параметры выполнения задания
locale	string	локализация согласно RFC 5646
sendNotification	boolean	признак необходимости отправки пользователю, инициировавшему задание, уведомления о его завершении (true - отправлять уведомление, false - не отправлять уведомление). Значение по умолчанию: false

Описания ошибок, зафиксированных при работе сервиса бизнес-логики

Наименование поля	Тип поля	Описание поля
code	string	код ошибки в номерации сервиса
exceptionStackTrace	string	трассировка стека исключения
exceptionType	string	тип исключения
extra	string	дополнительная информация об ошибке
id	string	идентификатор сквозной трассировки
isError	boolean	признак обнаружения ошибки при работе сервиса
message	string	описание ошибки в удобном для восприятия человека виде
source	string	источник возникновения ошибки
type	string	тип ошибки

Описания ошибок, зафиксированных при работе сервиса

Наименование поля	Тип поля	Описание поля
code	string	код ошибки в номерации сервиса
extra	string	дополнительная информация об ошибке
id	string	идентификатор сквозной трассировки
isError	boolean	признак обнаружения ошибки при работе сервиса
message	string	описание ошибки в удобном для восприятия человека виде
type	string	тип ошибки

Тип результата при успешном завершении работы сервиса

Наименование поля	Тип поля	Описание поля
name	string	тип результата в случае успешного завершения работы сервиса

Стандартизированный ответ сервиса бизнес-логики Платформы

Наименование поля	Тип поля	Описание поля
error		секция, содержащая описание ошибки, зафиксированной при работе сервиса бизнес-логики
result		результат работы сервиса прикладной области в случае его успешного завершения
typeInfo		секция, содержащая тип результата в случае успешного завершения работы сервиса

Стандартизированный ответ сервиса Платформы

Наименование поля	Тип поля	Описание поля
error		секция, содержащая описание ошибки, зафиксированной при работе сервиса
result		результат работы сервиса в случае его успешного завершения
typeInfo		секция, содержащая тип результата в случае успешного завершения работы сервиса

Параметры сервиса бизнес-логики

Наименование поля	Тип поля	Описание поля
authorizationExplicitScopes	[string]	перечень областей авторизации сервиса бизнес-логики
cmd	string	команда вызова сервиса бизнес-логики
description	string	описание сервиса бизнес-логики
urn	string	секция path вызова сервиса бизнес-логики

Идентификатор шаблона отчёта

Наименование поля	Тип поля	Описание поля
uuid	string($uuid)	идентификатор шаблона отчёта

Номер страницы, количество записей на странице и тип сортировки

Наименование поля	Тип поля	Описание поля
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

Параметры добавления или модификации шаблона отчёта

Наименование поля	Тип поля	Описание поля
alias	string	псевдоним
description	string	описание шаблона отчёта
name	string	наименование шаблона отчёта
namespace	string	пространство имён
uuid	string($uuid)	идентификатор шаблона отчёта

Параметры привязки файлов, входящих в состав шаблона отчёта

Наименование поля	Тип поля	Описание поля
script	string($byte)	файл скрипта трансформации данных
settings	string($byte)	файл настроек порядка формирования отчёта
template	string($byte)	файл шаблона отчёта Jasper Reports
uuid	string($uuid)	идентификатор шаблона отчёта

Псевдоним и пространство имён

Наименование поля	Тип поля	Описание поля
alias	string	псевдоним
namespace	string	пространство имён

Параметры асинхронного построения отчета

Наименование поля	Тип поля	Описание поля
callbackURL	string	URL обратного вызова возврата результата выполнения метода
destination	string	URI выгрузки отчёта в файловое хранилище, соответствующее значению параметра destinationType
destinationType	string	тип места назначения выгрузки файла отчёта (допустимые значения: PLATFORM, FTP, FTPS, SFTP)
externalURL	boolean	признак необходимости разрешения URL обратного вызова результата выполнения метода посредством сервиса Discovery Платформы
parameters	string	параметры объединения и трансформации информации из источников данных
type	string	формат отчёта (допустимые значения: CSV, HTML, JSON, PDF, RTF, TXT, XLS, XLSX, XML)
uuid	string($uuid)	идентификатор шаблона отчёта
locale	string	локализация согласно RFC 5646

Параметры для формирования URL выгрузки заданных файлов из файлового сервиса Платформы

Наименование поля	Тип поля	Описание поля
archiveName	string	наименование архивного файла, выгружаемого по сформированному URL
fileIDs	[string]	перечень идентификаторов файлов файлового сервиса Платформы, для которых формируется URL выгрузки

Параметры построения отчета

Наименование поля	Тип поля	Описание поля
destination	string	URI выгрузки отчёта в файловое хранилище, соответствующее значению параметра destinationType
destinationType	string	тип места назначения выгрузки файла отчёта (допустимые значения: PLATFORM, FTP, FTPS, SFTP)
parameters	string	параметры объединения и трансформации информации из источников данных
type	string	формат отчёта (допустимые значения: CSV, HTML, JSON, PDF, RTF, TXT, XLS, XLSX, XML)
uuid	string($uuid)	идентификатор шаблона отчёта
locale	string	локализация согласно RFC 5646

Идентификатор

Наименование поля	Тип поля	Описание поля
id	integer($int64)	идентификатор

Параметры выборки по дате поступления задания

Наименование поля	Тип поля	Описание поля
assignmentDate	string($date-time)	дата поступления задания
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

Параметры выборки по дате завершения обработки задания

Наименование поля	Тип поля	Описание поля
completionDate	string($date-time)	дата завершения обработки задания
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

Параметры выборки по виду (типу) задания

Наименование поля	Тип поля	Описание поля
kind	string	вид (тип) задания
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

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

Наименование поля	Тип поля	Описание поля
sendNotification	boolean	признак необходимости отправки нотификации пользователю о завершении выполнения задания
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

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

Наименование поля	Тип поля	Описание поля
sendNotification	boolean	признак необходимости отправки нотификации пользователю о завершении выполнения задания
userID	string	идентификатор пользователя
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

Параметры выборки по дате начала обработки задания

Наименование поля	Тип поля	Описание поля
startDate	string($date-time)	дата начала обработки задания
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

Параметры выборки по статусу

Наименование поля	Тип поля	Описание поля
state	string	статус задания
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

Параметры выборки по идентификатору пользователя

Наименование поля	Тип поля	Описание поля
userID	string	идентификатор пользователя
page	integer($int32)	номер страницы (начиная с 0)
size	integer($int32)	максимальное число записей на странице
sort	string	порядок сортировки записей (формат <поле сортировки>:<порядок сортировки>)

Для авторизации доступа к методам сервиса формирования отчётов используется метод API /api/external/access/check сервиса проверки прав доступа Платформы.