5. Пользовательские отчеты¶

Пользовательские отчеты предоставляют разработчику возможность формировать и загружать произвольные отчеты на основе данных, содержащихся в БД системы или получаемых с помощью API.

Сформированный шаблон отчета можно загрузить в приложение Synergy IDE и и предоставить пользователям права на его использование.

Для разработки шаблона отчета используется TIBCO Jaspersoft Studio.

Примечание

Работа с Jaspersoft Studio рассматривается на примере версии 6.6.0.

Подсказка

В этом разделе будут рассмотрены лишь некоторые возможности Jaspersoft Studio. При работе с отчетами мы рекомендуем обращаться к официальному руководству TIBCO.

5.1. Системные требования¶

Конфигурация, необходимая для работы JaspersoftStudio:

не менее 500 МБ пространства на жестком диске
минимум 1 ГБ оперативной памяти, рекомендуемый размер - 2 ГБ
поддерживаемые ОС:
- Windows 7/8: x86 и x64
- Linux: x86 и x64
- MacOS X: x64

5.2. Установка и первоначальная настройка¶

Дистрибутив Jaspersoft можно скачать по ссылке.

Для работы с Synergy необходимо добавить проект, содержащий необходимые библиотеки и поддерживаемые шрифты:

Скачайте приложенный архив с проектом, добавьте его в папку jasperSoftStudio

2. Запустите JasperStudio, в меню выберите пункт File - Open Projects from File System, далее нажмите на кнопку Archive и выберите скачанный архив.

Импортированный проект отображается во вкладке Project Explorer:

5.3. Создание отчета¶

JasperStudio позволяет получать данные посредством SQL-запроса, из данных json или xml. Источник данных указывается в адаптере данных, соответствующем отчету.

В целом для создания пользовательского отчета нужно проделать такие шаги:

Создать адаптер данных
Настроить поля отчета
Настроить внешний вид отчета
Добавить новый пользовательский отчет, используя полученный шаблон отчета

Адаптер данных - это объект, регулирующий источник данных, их структуру и способ получения. Адаптер хранится в виде файла XML и доступен всем шаблонам отчетов текущего проекта.

5.3.1. Отчет с использованием SQL-запроса¶

Использование SQL в запросе позволяет строить отчет на основнии данных, расположенных непосредственно в БД Synergy. Описание структуры БД приводится в документации.

Рассмотрим простой отчет, который будет содержать список пользователей Synergy.

5.3.1.1. Создание адаптера данных¶

На панели инструментов нажмите на кнопку New data Adapter . Откроется мастер создания нового соединения:

Шаг 1: выбор расположения и имени для нового адаптера

На первом шаге необходимо указать имя и расположение нового адаптера.

Следующим шагом создания адаптера является выбор типа соединения:

Шаг 1: выбор типа соединения

Для работы с SQL необходимо указать тип соединения Database JDBC Connection.

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

Datasource JDBC connection

Введены следующие параметры соединения:

Данные SQL-адаптера¶
Name	Synergy connection
JDBC Driver	`MySQL (com.mysql.jdbc.Driver)`
JDBC URL	`jdbc:mysql://<hostname>:<mysql_port>/synergy`

Здесь <hostname>:<mysql_port> - адрес и порт сервера, на котором расположен MySQL, или, как в случае с пробросом соединения через SSH (пример ниже), локальный хост и порт, куда был выполнен проброс.

Далее указываются логин и пароль пользователя, имеющего доступ к БД.

Для проверки соединения можно нажать на кнопку Test. Если соединение с указанными параметрами удалось установить, то будет отображено сообщение «Successful»

Если же соединение установить не удалось, то будет отображено сообщение с текстом ошибки.

Сохраните новый адаптер, нажав на кнопку Finish.

5.3.1.1.1. Проброс соединения через SSH¶

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

ssh -L 3307:localhost:3306 user@remote-host.com

Здесь 3307 - локальный порт, с которым будет устанавливать соединение JasperSoft, localhost - локальный хост, 3306 - удаленный порт (например, порт mysql, запущенного на удаленном сервере), user@remote-host.com - пользователь@удаленный хост.

Примечание

Примечания:

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

5.3.1.2. Создание шаблона отчета¶

Для создания нового шаблона отчета нужно вызвать контекстное меню элемента дерева (например, корневого элемента SynergyReports) и выбрать пункт New - Jasper Report. Откроется мастер создания нового шаблона.

Шаг 1. Выбор разметки для шаблона отчета

Первым шагом этого мастера является выбор разметки для шаблона. Выберем здесь простой лист формата А4 - Blank A4.

Шаг 2. Место расположения и имя шаблона

На втором шаге нужно указать имя шаблона и выбрать место расположения файла шаблона в проекте.

Далее выполняется настройка запроса для отчета:

Шаг 3. Выбор адаптера данных и настройка запроса для отчета

На шаге 3 нужно выбрать ранее созданный адаптер данных и ввести запрос. Здесь мы используем адаптер Synergy connection и вводим текст запроса:

select firstname, lastname from users

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

Шаг 4. Настройка полей отчета

Для того, чтобы использовать полученное в запросе поле в качестве поля отчета, перенесите это поле в правую часть диалога. Кнопка >> добавит в правую часть все доступные поля:

Настройка полей отчета

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

После завершения создания нового шаблона вкладка с ним откроется в рабочей области:

Окно составления отчета

Слева во вкладке Outline располагается дерево элементов отчета, где в качестве корня выступает сам отчет. В правой части во вкладке Properties будут отображаться свойства элемента, выбранного в дереве элементов. Вкладка Palette позволяет добавить в шаблон отчета новые компоненты.

Посередине окна располагается рабочая область отчета. По умолчанию открыта вкладка Design - в ней отображена структура отчета, и именно в ней настраивается внешний вид отчета.

Вкладка Source содержит полученный отчет в формате XML.

Вкладка Preview предназначена для предварительного просмотра итогового отчета.

5.3.1.2.1. Дизайн шаблона отчета¶

Рабочая область шаблона отчета состоит из следующих основных секций:

Title: заголовок отчета. Секция будет напечатана один раз на первой странице отчета.
Page Header: заголовок страницы. Секция будет напечана в начале каждой страницы отчета. Обычно здесь размещается название отчета либо номер текущей страницы.
Column Header: название колонок отчета.
Detail 1: тело отчета. Секция отличается от остальных тем, что она повторяется в отчете ровно столько раз, сколько строк будет в полученном отчете.
Column Footer: нижняя подпись колонок.
Page Footer: нижний колонтитул страницы. Секция будет напечатана в конце каждой страницы отчета. Аналогично с заголовком страницы, здесь могут быть размещены название отчета или номер текущей страницы.
Summary: нижняя подпись отчета. Секция будет напечатана один раз в конце отчета.

Если какая-либо секция в отчете не нужна, то достаточно просто уменьшить ее размер до 0 и не помещать в нее компонентов. Если необходимо, чтобы область начиналась на следующей странице, следует вставить в конец предыдущей области компонент разрыва (Break).

При необходимости изменить запрос для отчета можно, выбрав в контекстном меню элемента отчета (во вкладке Outline) пункт Dataset and Query:

Запрос и поля отчета

В этом же диалоге можно, например, просмотреть превью данных полей:

Превью данных отчета

Поля, настроенные в запросе, отображаются в дереве компонентов отчета, в ноде Fields. Для того, чтобы добавить их в рабочую область отчета, перетащим мышкой поле lastname в область данных Detail 1. В результате в этой области появилось отображение поля с лейблом $F{lastname}, а в области заголовков столбцов Column Header автоматически был добавлен заголовок lastname:

Добавление поля отчета

Изменить текст заголовка можно, дважды кликнув по лейблу заголовка. Укажем там значениие «Фамилия»:

Повторим эти действия, чтобы добавить в шаблон отчета поле firstname:

Уменьшим высоту неиспользуемых блоков Title и Page Header до минимума, а блоков Column Header и Detail 1 - до 30px. Следать это можно как мышкой, так и с помощью вкладки Properties:

Для лейблов заголовков полей включим специальное свойство net.sf.jasperreports.style.isBold. Для того, чтобы найти это свойство, нужно открыть все свойства компонента и отфильтровать их список, используя текст isBold:

Теперь можно сохранить полученный шаблон и проверить, как будет выглядеть отчет (вкладка Preview):

5.3.1.3. Параметры отчета¶

Часто возникает необходимость формировать отчет с использованием данных, которые должен вводить пользователь. Например, пользователь должен указать условие поиска сотрудников. Для того, чтобы это сделать, в отчете необходимо использовать параметры.

Параметры настраиваются во вкладке Parameters окна редактирования запроса:

По умолчанию здесь отображены встроенные параметры JasperReports. Новый параметр добавляется кнопкой Add, редактируется - в диалоге:

Новый параметр param1 имеет строковый тип. При генерации отчета из Synergy в качестве отображаемого имени параметра будет использовано значение поля Description.

Добавленный параметр будет отображен вместе со встроенными параметрами, что может быть неудобно. Для того, чтобы увидеть только параметры текущего отчета, нужно нажать на кнопку hide :

Для использования параметров нужно добавить их в запрос. Обращение к параметру в запросе производится в формате $P{<имя_параметра>}:

SELECT firstname, lastname
FROM users
WHERE lastname LIKE CONCAT($P{param1}, '%')

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

Сохраним изменения, нажав на кнопку OK, и проверим работу параметра:

Запрос параметра, введено значение adm

Результат - один подходящий пользователь

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

5.3.1.3.1. Специальные параметры¶

При соединении JasperReports с Synergy предусмотрены некоторые специальные параметры.

Если название параметра (Parameter name) содержит комбинацию символов как в коде переменной, то для данной переменной применяется специальный редактор:

users_names: Для параметра с данным кодом в названии будет предоставляться возможность выбора нескольких пользователей. В значение параметра будут записаны имена пользователей, перечисленные через запятую, в формате Фамилия Имя О.
users_id: Для параметра с данным кодом в названии будет предоставляться возможность выбора нескольких пользователей. В значение параметра будут записаны ID пользователей, перечисленные через запятую, в одинарных кавычках.
Примечание

Этот параметр предназначен только для выполнения запросов. Пример:
```
SELECT lastname, firstname FROM users WHERE userid in ($P!{param})
```
Обратите внимание, что параметр в запросе должен быть записан с !
user_name: Имя выбранного пользователя
user_id: ID выбранного пользователя
departments_names: Названия выбранных подразделений, перечисленные через запятую
departments_id: Идентификаторы выбранных подразделений, перечисленные через запятую
department_name: Название выбранного подразделения
department_id: Идентификатор выбранного подразделения
currentuser_id: Идентификатор пользователя, который формирует отчет. Данный параметр не отображается при заполнении отчета. Название используемого параметра быть точно равно коду
currentuser_name: Полное имя пользователя, который формирует отчет. Данный параметр не отображается при заполнении отчета. Название используемого параметра должно быть точно равно коду
currentdate: Дата формирования отчета. Данный параметр не отображается при заполнении отчета
action: Идентификатор выбранного проекта
actions: Идентификаторы выбранных проектов, перечисленные через запятую
_dictionary: В параметре необходимо указать код справочника и коды полей, которые должны быть использованы в качестве значения параметра (value) и его подписи, отображаемой в отчете (title), в формате: <dictionary_code>.<value_code>.<title_code>_dictionary. Например: send_items.item_number.item_name_dictionary.

Если справочник содержит поля с кодами title и value, то значение и подпись элементов справочника будут выделены автоматически, и в названии параметра достаточно указать только код справочника в формате <dictionary_code>_dictionary

5.3.1.3.2. Опциональные параметры¶

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

Открыть диалог свойств параметра:
Открыть список свойств параметра (кнопка … в поле Properties):

3. Нажать на кнопку + и добавить новое свойство kz.arta.synergy.reports.parameters.optional с любым значением:

Нажмите на кнопку Finish, чтобы применить новое свойство.

Чтобы проверить значение опционального параметра в отчете, используется условие вида:

IF($P{param}='', true, t=$P{param})

То есть если параметр param не задан, его значение не учитывается (результат сравнения true). Если параметр задан, то он сравнивается с переменной t.

Если же параметр - это мультивыбор значения справочника, то условие имеет вид:

IF('$P!{param_dictionary}' <> '[]', $X{IN, t, param_dictionary}, true)

То есть если список значений param_dictionary не имеет элементов, то условие считается верным, иначе - выполняется проверка, содержится ли (ключевое слово IN) значение поля t в значениях param_dictionary. Если необходимо проверить, что значение поля не содержится в списке значений параметра, можно использовать ключевое слово NOTIN.

5.3.1.4. Экспорт шаблона и создание пользовательского отчета¶

Когда дизайн шаблона закончен, необходимо добавить его в Synergy, чтобы отчет могли формировать конечные пользователи. Для этого нужно:

Экспортировать файл шаблона отчета jrxml:

Во вкладке Project Explorer в контекстном меню элемента users.jrxml выберите пункт Export Files to…. Откроется диалог экспорта шаблона, в котором нужно выделить экспортируемый файл и целевую папку:

В диалоге выбран файл users.jrxml и указана папка, в которую нужно экспортировать этот файл
В приложении Synergy IDE создать новый пользовательский отчет:

Выделите папку, в которой должен располагаться новый отчет, и выберите в меню пункт Объект - Добавить - Пользовательский отчет. Откроется вкладка создания нового отчета:
Заполнить сведения об отчете и приложить экспортированный файл шаблона отчета jrxml:

Итоговый формат отчета регурируется маской имени файла. В данном случае отчет будет формироваться в формате pdf.

Поскольку отчет работает на основе SQL-запроса, то в поле «Тип источника данных» выбран вариант «SQL соединение».

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

5.3.2. Отчет с использованием JSON¶

Synergy поддерживает использование большого количества методов API, и JasperReport позволяет использовать данные JSON, возвращаемые этими методами, в качестве источника данных для отчетов.

Рассмотрим работу с JSON на примере отчета, содержащего список подписей документа.

5.3.2.1. Создание адаптера данных¶

В первую очередь создадим адаптер данных для нового отчета. Для этого в мастере создания нового адаптера выберем тип JSON File:

На следующем шаге нужно указать источник данных:

Укажем имя адаптера signlist, в качестве источника укажем запрос rest/api/docflow/doc/sign_list. Этот метод по UUID документа возвращает список подписей для него. Описание метода приведено в справочнике API.

В поле File/URL указан полный URL метода и значение параметра documentID в формате:

http://<host>:<port>/Synergy/rest/api/docflow/doc/sign_list?documentID=<doc_UUID>

Примечание

Обратите внимание, что в URL адаптера данных указываются фиксированные значения входных параметров метода. Эти значения будут использоваться только для дизайна и предпросмотра шаблона отчета. При настройке пользовательского отчета в Synergy IDE параметры будут настроены дополнительно.

Подсказка

Получить значение UUID документа можно из его URL в Synergy:

Необходимо включить опцию Use the report JSON expression when filling the report.

Далее нужно перейти к дополнительным настройкам соединения (кнопка Options):

Здесь указываются логин и пароль пользователя, от имени которого выполняется метод. На вкладке HTTP Headers нужно добавить параметр способа авторизации Authorization со значением Basic MTox.

После завершения настройки адаптера нажмите Finish. Вкладка с созданным адаптером открылась в рабочей области, и в ней можно вывполнить проверку соединения кнопкой Test Connection:

5.3.2.2. Создание шаблона отчета¶

Шаблон отчета, использующего данные JSON, создается точно так же, как и для работы с SQL. На панели инструментов нажмите на кнопку new-report New JasperReport:

На первом шаге мастера создания нового шаблона снова выберем вариант Blank A4.

Второй шаг мастера позволяет указать расположение и имя файла шаблона отчета.

На третьем шаге необходимо выбрать адаптер данных.

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

Примечание

Данные, возвращаемые методами API, имеют древовидную структуру. Запрос для JSON пишется через точку. Например, если нужно получить все ноды <node_name>, то в запросе нужно писать просто <node_name>. Если же у <node_name> есть вложенное поле info, и нужно получить именно его, то в запросе нужно указать <node_name>.info.

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

Созданный шаблон отчета откроется во вкладке рабочей области:

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

Настроим набор полей отчета. Для этого нужно в контекстном меню корневой ноды шаблона (вкладка Outline) выбрать пункт Dataset and Query:

Механика добавления полей в отчет из данных JSON несколько отличается от работы с SQL. Для того, чтобы использовать ноды JSON как поля отчета, нужно выделить их правой кнопкой мыши и выбрать пункт Add node as field:

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

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

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

Результат дизайна шаблона. В качестве заголовка отчета используется элемент Static Text, который можно выбрать из вкладки Palette.

Посмотрим, что получилось, переключившись на вкладку Preview:

Результат дизайна шаблона. Отображены данные, соответствующие документу, чей UUID указан в адаптере данных

На этом дизайн шаблона отчета закончен.

5.3.2.3. Параметры отчета для JSON¶

В URL метода или в теле запроса можно использовать подстановки вида {parameter_name}. При соединении JasperReports с Synergy предусмотрены некоторые автоматические параметры, в частности:

elementid — идентификатор текущего выбранного объекта. К примеру, если отчет формируется для карточки документа, то значением параметра является UUID этого документа, если для реестра - UUID реестра, и так далее.
userid — идентификатор текущего пользователя
actorid — идентификатор текущего пользователя

В нашем примере со списком подписей документа будем использовать параметр elementid для получения идентификатора выбранного документа. Для этого достаточно добавить в отчет параметр с таким именем:

В диалоге настройки запроса отчета Dataset and Query, вкладка Parameters, добавляется новый параметр с именем elementid. Дополнительной настройки параметра не требуется - совпадения имени параметра со специальным параметром Synergy достаточно для корректного его использования.

5.3.2.4. Экспорт шаблона и создание пользовательского отчета¶

Как и в предыдущем случае, сначала нужно выполнить экспорт шаблона отчета. Для этого во вкладке Project Explorer в контекстном меню элемента отчета doc_singlist.jrxml выберите пункт Export Files to…. В открывшемся диалоге нужно выделить экспортируемый файл и целевую папку:

Дальше в приложении Synergy IDE нужно создать новый пользовательский отчет:

Рассмотрим подробнее заполнение сведедений об отчете:

в качестве модуля нужно указать значение «Карточка документа». Это означает, что отчет будет доступен для карточки открытого документа
формат, в котором будет формироваться отчет, регулируется с помощью маски отчета; в нашем случае используется формат PDF
приложен экспортированный файл отчета doc_singlist.jrxml
тип источника данных: JSON
URL источника данных: выбран тип метода GET, а URL метода введен в формате:

http://<host>:<port>/Synergy/rest/api/docflow/doc/sign_list?documentID={elementid}

Примечание

Здесь специальный параметр {elementid} используется для получения идентификатора того документа, карточка которого открыта в момент вызова отчета.
в поле «Авторизация» указаны логин и пароль пользователя, от имени которого будет выполняться метод, используемый в отчете.

Сохраним пользовательский отчет и проверим, как он работает, из клиентской части Synergy:

В Synergy создан документ, который подписывали разные сотрудники

Переключимся на карточку документа и в списке отчетов выберем созданный отчет «Список подписей»

Отчет скачивается в виде файла PDF, содержимое этого файла совпадает с настроенным при дизайне отчета

Примечание

Если в результате скачивается пустой файл, убедитесь, что в шаблоне отчета для лейблов используется один из подрреживаемых шрифтов, например, Arial (свойство компонента net.sf.jasperreports.style.fontName):

Поддерживаемые шрифты перечислены в импортированном проекте SynergyReports. Вот их список:

Arial

Times New Roman

Courier New

DejaVu Sans

DejaVu Serif

DejaVu Sans Mono

SansSerif

Serif

Monospaced