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

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

Формирование отчетов осуществляется при помощи библиотеки 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 сервиса проверки прав доступа Платформы.