Отчеты#

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

Типы шаблонов печатных форм#

Определяют формат, в котором задаются шаблоны печатных форм.

  • jasper
    Шаблон представляет из себя zip архив содержащий набор xml файлов, сформированных в jasper studio. Jasper studio это специализированное средство построения печатных форм.

  • xlsx
    Шаблон представляет из себя файл в формате xls со спец тэгами

  • docx
    Шаблон представляет из себя файл в формате docx со спец тэгами

Печатная форма#

Печатная форма (cокр. ПФ) определяет правила построения отчета, а также доступность этого отчета для приложения, типа объекта и пользователя. При выполнении печатной формы формируется отчет в виде файла с заданным форматов.
Печатную форму можно подключить к выборке на проекте без внесения изменений в программный код.

Версии печатной формы#

Версия печатной формы позволяет:

  • Безопасно вернутся к предыдущей реализации

  • Запускать реализацию в зависимости от периода

Версия печатной формы содержит:

  • Тип шаблона печатной формы

  • Бинарный файл для построителя отчетов

  • Дату версии

  • Описание

Доступные форматы#

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

Подписи для печатных бланков#

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

with signs as(select * from jsonb_array_elements( $P{SIGNDATA_DZ}::jsonb ->'data'))
select t.*
, (select s.value ->>'sFIO' from signs s WHERE  s.value->>'idBlankSignTypeMC' = 'matching1') as sMatching1
, (select s.value ->>'sPosition' from signs s WHERE  s.value->>'idBlankSignTypeMC' = 'matching1') as sMatching1Pos

На печатный бланк необходимо вывести блок с подписями.

Блок с подписями формируется перед печатью и передается в отчет в формате json, в параметр SIGNDATA_DZ пример:

{
	"data": [
		{
			"idBlankSignTypeMC": "HeadOfDepartment",
			"bReadOnly": 0,
			"idBlankSignTypeHL": "Руководитель подразделения",
			"nOrder": 1, 
			"dDate": "10.12.2020",
			"idBlankSignType": 95401,
			"sPosition": "Начальник отдела",
			"sFIO": "Дьяченко Евгений Владимирович"
		}
	]
}

Где:

  • idBlankSignType
    идентификатор тип подписи

  • idBlankSignTypeMC
    код типа подписи

  • nOrder
    порядковый номер подписи

  • sPosition
    Должность

  • sFIO
    ФИО

  • dDate \ дата

Блок формируется на основе настроек данной закладки.
Настройки могут быть переопределены\уточнены на конкретном объекте в закладке Подписи (Bs_OBjectSign)

Аудит построения отчета#

Содержит информацию о построении отчетов пользователями.

Параметры отчета#

Параметры отчета передаются в запрос, формирующий данные отчета.

Пользовательские параметры#

Настраиваются на печатной форме. Перед выполнением отчета пользователь может ввести данные в эти параметры.

Служебные параметры#

Формируются автоматически

  • SIGNDATA_DZ - Блок подписи

  • IDUSER - Пользователь

  • IDSRCOBJECT - Объект источник
    Идентификатор объекта от которого выполняется печатная форма.

  • IDSRCCLASS - Класс источник
    Идентификатор класса объекта от которого выполняется печатная форма

Вызов печатных форм#

Печатные формы могут вызываться:

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

Для вызова отчета из операции выборки используйте функцию ru.bitec.app.gtk.gl.Reports#createReportEx:

  /**
    * Выполняет построение отчёта по системному имени отчёта.
    *
    * @param reportName        Имя отчёта
    * @param reportVersionDate Дата
    * @param postBuildAction   Действие, которое необходимо произвести после заполнения отчёта
    * @param propertyMap       Карта входящих параметров
    */
  @throws[ApplicationException]
  def createReportEx(reportName: String, reportVersionDate: Date, postBuildAction: PostBuildAction, propertyMap: Map[String, Any]): Unit

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

Пример:

reports.createReportEx("Mct_OrderSheetMaterials2", null, PostBuildAction.print,
        Map[String, Any]("IDSRCOBJECT" -> getVar("id").asNLong,
          "GIDSRCOBJECT" -> getVar("gid").asNString,
          "SDESIGNATION" -> getVar("sCode").asNString)
      )

Формирования файла с отчетом#

Для формирования файла с отчетом используйте функцию ru.bitec.app.rpt.Rpt_Pkg#getReportStreamEx:

  /**
    * Выполняет построение отчёта по системному имени отчёта.
    * Если для версии отчета указано несколько доступных для печати форматов,
    * то будет выдана ошибка построения.
    * Требуется явно указать формат построения, указав параметр [[Rpt_Pkg.ParamFormatType]]
    *
    * @param reportName        Имя отчёта
    * @param reportVersionDate Дата
    * @param propertyMap       Карта входящих параметров
    * @return InputStream, содержащий результат построения отчёта. ByteArrayInputStream не требует закрытия.
    */
  def getReportStreamEx(reportName: String, reportVersionDate: Date, propertyMap: Map[String, Any]): Option[InputStream]

Данная функция может быть вызвана в контексте автономной логики(rest сервиса)

Внимание

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

При формировании файла с отчётом в потоке переменные выборки не доступны.

Вызов печатной формы от произвольного объекта#

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

Для добавления печатной формы к списку печати для типа объекта:

  1. Откройте приложение Настройка системы

  2. Откройте типы объектов
    Выполните пункт меню Сущности > Типы объектов > Типы объектов

  3. Перейдите на вкладку Печатные формы

  4. Добавьте необходимые печатные формы

Вызов печатной формы в свободных отчетах#

Свободные отчеты позволяют настроить для пользователя и приложения перечень отчетов, которые можно построить без привязки к каким-либо типам объектов.

Для вызова интерфейса построения свободных отчетов:

  1. Откройте приложение, в котором есть пункт меню Отчеты

  2. Откройте свободные отчеты
    Выполните пункт меню Отчеты > Свободные отчеты

  3. Выберите нужный отчет

  4. Заполните параметры

  5. Напечатайте отчет
    Для этого выполните операцию Печать

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

  1. Откройте приложение Настройки системы

  2. Откройте печатные формы
    Пункт меню Отчеты > Печатные формы

  3. Выберете требуемую печатную форму

  4. Включите признак Свободный отчет

  5. Настройте параметры отчета

  6. Укажите приложение для печати

  7. Укажите требуемые роли

    Примечание

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

Создание печатной формы#

  1. Откройте приложение Настройки системы

  2. Откройте печатные формы
    Пункт меню Отчеты > Печатные формы

  3. Выполните операцию Создать

  4. Заполните Системное имя, Наименование, Модуль

  5. Создайте версию печатной формы

  6. Выберете тип шаблона

  7. Загрузите файл шаблона выбранного типа
    Для этого выполните операцию Загрузить файл в базу

Настройки вставки изображений в печатную форму типа docx и xls#

Данная настройка производится в коллекции к печатной форме. Все поля данной коллекции обязательны для заполнения.

  • Активность
    Данное поле отвечает будет ли вставленные изображения в печатную форму

  • Шаблон(Тег)
    Определяет тег по которому будет вставлено изображение. Тег должен содержаться в печатной форме иначе изображение не будет вставлено. Существует два вида тегов:

    • Общий
      Общий тег не имеет динамической части и изображение будет вставлено при нахождении данного тега в документе.

      • Пример:

        • В поле: SomeTag

        • В документе: [SomeTag]

    • Подпись
      Тег для подписи состоит из двух частей: общая часть для всех тегов, которые задаётся в данном поле, и имя пользователя подпись которого необходимо вставить в данный документ

      • Пример:

        • В поле: SomeSignTag

        • В документе(с динамической частью): [SomeSignTagAdmin]

  • Печатная форма изображения
    В поле указывается печатная форма с типом jasper и форматом png. В зависимости от типа изображения данный печатной форме будут переданы следующие аргументы:

    • Подпись

      • «PSDATE» - дата подписания документа

      • «PSSERNUMBER» - № сертификата подписи

      • «PSDBEGIN» - дата начала действия подписи

      • «PSDENG» - дата окончания действия подписи

      • «PSFIO» - ФИО сотрудника подписавшего документ

      • «IDDOC» - id документа

      • «IDDOCVER» - id версии документа(если документ версионный то подписывается именно версия а не сам документ)

      • «JOBJ» - json объект подписи документа

    • Общий

      • «IDDOC» - id документа

      • «IDDOCVER» - id версии документа(если документ версионный то подписывается именно версия а не сам документ)

  • Масштаб и Разрешение
    Размер изображения высчитывается по формуле: Масштаб *= Measures.DOTS_PER_INCH / Разрешение

  • Тип
    В поле указывается тип изображения:

    • Общий
      Изображение вставляется при печати в любом случае

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

Вставка изображений в печатную форму docx и xls#

Для вставки изображений в печатную форму типа docx должны быть выполнены следующие условия:

  1. Печатная форма должна содержать теги вида [SomeTag]

  2. Тип шаблона печатной формы - docx или xls

  3. Формат печатной формы - pdf

  4. В коллекции к печатной форме(Настройки вставки изображений в печатную форму) настроены необходимые изображения для вставки

Если все требования выполнены корректно, то при печати такой печатной формы будет получен pdf-файл (для docx) или xls с изображениями на месте тегов.

Примечание

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

Отчет с селекционным экраном#

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

Выборка, которая будет открыта в качестве селекционного экрана, указывается с помощью характеристик Имя выборки, Имя отображения в Настройка отчетных форм > Объектные характеристики.

Выборка для селекционного экрана#

Создание выборки#

Выборку для селекционного экрана нужно унаследовать от базовой выборки ru.bitec.app.rpt.Rpt_ScreenCardAbsAvi.BaseSelectionScreenCard. Эта выборка по умолчанию содержит фильтр с отчетами отчетной формы, который определяет, какая печатная форма будет напечатана. Если этого фильтра нет или он не заполнен будет напечатана печатная форма по умолчанию.

Валидация введенных значений#

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

Параметры выборки#

Для передачи параметров в селекционный экран используется параметр jParams#, который содержит JSON следующего вида:

{
  "attribute_1_name": "attribute_1_value",
  "attribute_2_name": "attribute_2_value"
}

Карта параметров отчета#

Для указания логики получения карты параметров отчета переопределите метод getPropertyMap. По умолчанию получает значения всех фильтров StdLink и стандартных фильтров. Для редактирования полученной карты параметров можно переопределить метод preparePropertyMap.

Интерактивные отчёты#

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

Основные возможности#

  • Редактирование параметров отчёта через интерактивную форму

    • Расширение логики сеттеров с помощью jexl-скриптов

  • Пользовательские Jexl-операции для интерактивных отчётов

    • Указание условий доступности операций

    • Использование данных отчёта в операциях

  • Настройка пользовательской выборки для переопределения бизнес-логики

Объявление отчёта интерактивным#

Отчёт определяется как интерактивный с помощью атрибута bInteractive, который отображается в детализации Печатные формы отчёта в разделе Отчёты > Настройка отчётных форм для отчётов с селекционным экраном и в карточке объектных характеристик для произвольных отчётов

Примечание

Построение интерактивных отчётов в фоновом режиме невозможно

Изменение параметров интерактивного отчёта#

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

  • [#{gid}#{тип_редактора}#{имя}#{значение}/#]
    (вводится в одно из полей в JasperSoft Studio)

Если указан gid-объекта и имя не начинается с P_, то при изменении значения параметра в выборке будет вызван стандартный сеттер ru.bitec.app.btk.class_.attr.AttrApi#setAttrValue.

Чтобы получить введённые пользователем параметры В Jasper Reports, нужно добавить новый параметр отчёта в списке Parameters или получить его из REPORT_PARAMETERS_MAP типа java.util.Map, при чём имя в поле должно совпадать с именем в списке параметров.

Примечание

  • Если имя атрибута начинается с P_, карта параметров обновляется, минуя сеттер по gid

  • Заметьте, что в JasperSoft Studio все параметры указываются в верхнем регистре

Для примера, нескольких параметров:

  • IDSRCOBJ
    вызывающий сеттер по гиду параметр

    • $P{IDSRCOBJ}
      получение значения изменённого пользователем параметра

    • "[#" + $P{GIDOBJ} + "#textArea#IDSRCOBJEDITED#"+ $P{IDSCROBJ} +"/#]"
      содержание редактируемого поля в JasperSoft Studio

      • GIDOBJ - параметр отчёта, содержащий gid объекта с параметром IDSRCOBJ, в который будет устанавливаться его значение при изменении поля интерактивного отчёта

      • IDSCROBJ - параметр отчёта, содержащий изначальное значение изменяемого поля интерактивного отчёта

      • IDSRCOBJEDITED - имя, по которому можно обратиться к изменённому пользователем в интерактивном отчёте параметру

  • $P{P_NTOTAL} - не вызывающий сеттер параметр

  • (java.util.Date) $P{REPORT_PARAMETERS_MAP}.get("P_DDATE")
    получение параметра P_DDATE и приведение его к нужному типу java.util.Date

Функция парсинга изменяемых полей

Изменяемые поля из полученной от Jasper Reports Html-разметки парсятся в функции ru.bitec.app.rpt.interactive.Rpt_HtmlReportHelper#replaceTags.

Типы редакторов#

  • ref - ссылка на объект

  • textArea - текст

  • checkBox - чекбокс (флажок)

  • date - дата

  • dateTime - дата и время

Расширение сеттеров#

Можно задать кастомную логику для сеттера параметра отчёта setByTagId с помощью JEXL-скриптов. Скрипты выполняются до вызова сеттера setByTagId

В контексте JEXL-скрипта доступны параметры атрибута:

  • gid - глобальный идентификатор объекта

  • sAttrName - имя атрибута

Пользовательские JEXL-операции#

Операции могут быть добавлены на тулбар формы интерактивного отчёта через детализацию Процедуры интерактивного отчёта в Отчёты > Настройка отчётных форм. Это происходит с помощью клонируемой операции userDefinedProcedures. Настройка привязывается к Rpt_EntityReport и содержит:

  • № п/п (порядок отображения).

  • Иконка (номер иконки).

  • Наименование.

  • Признак «Выводить текст операции на панели».

  • Ссылка на Bts_Procedure, в которой указан JEXL-скрипт (исполняется в контексте выборки)

Контекст операций#

В настраиваемых операциях интерактивных отчётов доступны:

  • Значения изменяемых полей
    по имени параметра в селекционном экране \ параметра произвольного отчёта

  • Значения неизменяемых полей Jasper-отчёта
    для полей, отмеченных специальными тегами

  • Список всех имён доступных параметров
    по алиасу PARAMS

  • Методы выборки и сессии
    dialogs, commit(), flush() и др.

Получение неизменяемых параметров#

Чтобы получить неизменяемые параметры из Jasper-отчёта и использовать их в пользовательских операциях, необходимо задать следующие свойства для поля в Jasper Reports:

  • net.sf.jasperreports.export.html.class = parse
    обозначает, что поле будет доступно в jexl-операциях

  • net.sf.jasperreports.export.html.id = {имя атрибута}
    имя, по которому можно будет получить значение поля

Условия отображения#

Условия доступности операций задаются в детализации Условие доступности процедуры, находящейся в форме Настройка отчётных форм, в детализации Процедуры интерактивного отчёта

Условия указываются как JEXL-скрипт, который должен возвращать:

  • true - операция активна

  • false - операция недоступна

Скрипт может использовать JSON с параметрами из селекционного экрана или свободного отчёта.

Переопределение выборки интерактивного отчёта#

Для интерактивных отчётов предусмотрена возможность указания пользовательской выборки для переопределения бизнес-логики

Примечание

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

  • Отчёт с селекционным экраном:
    InteractiveSelReportHtml

  • Произвольный отчёт:
    InteractiveFreeReportHtml

  1. Указание кастомной выборки:

    • В классе Rpt_EntityHtmlReportPkg реализован метод hasCustomInteractiveSelection, который проверяет наличие кастомной выборки для интерактивного отчёта.

    • Если кастомная выборка указана, она открывается с переданными параметрами.

  2. Пример использования:

    • Для задания кастомной выборки необходимо указать её имя и представление в объектных характеристиках sSelectionInteractive и sRepresentationInteractive класса Rpt_EntityReport.

    • При вызове метода enterInteractiveMode кастомная выборка будет автоматически открыта, если она указана.

  • Параметры в выборку передаются через selection.form.params и сохраняются в JSON.

Параметры для передачи в отображение интерактивного отчёта#

Отчёт с селекционным экраном#

Обязательные:

  • IDENTITY# - идентификатор отчёта

  • IDREPORT# - идентификатор печатной формы

  • BWITHDOC# - флаг: сохранение в документообороте/истории печати

  • DREPORTVERSION# - дата версии печатной формы

Параметры для построения и печати отчёта:

  • JPARAMETERS - параметры отчёта для истории (наименования как в селекционном экране)

  • LOGJPARAMS# - параметры отчёта для печати (наименования как в Jaspersoft Studio)

Произвольный отчёт#

Обязательные:

  • IDENTITY# — идентификатор отчёта

  • IDREPORT# — идентификатор печатной формы

Параметры для построения и печати отчёта:

  • JPARAMETERS# — параметры отчёта для печати (наименования как в Jaspersoft Studio)

Процедура получения дополнительных параметров печати для ПФ#

В печатной форме Rpt_Report есть возможность указать процедуру (Bts_Procedure) для получения дополнительных параметров печати (поле "Процедура получения дополнительных параметров"). Процедура получает на вход 3 параметра:

  • reportName - имя отчета;

  • reportVersionDate - дата версии отчета;

  • propertyMap - изменяемая карта параметров, которые будут переданы в отчет.

Процедура не возвращает никаких значений. Ее предназначение - редактирование карты параметров propertyMap. Процедура может вызывать как функцию из прикладного кода, так и выполнять Jexl-функцию. Таким образом можно добавлять дополнительные параметры без изменения прикладного кода.

Пример функции, вызываемой из прикладного кода:

  def getAddReportParamTest(reportName: NString, reportVersionDate: NDate, propertyMap: mutable.HashMap[String, Any]): Unit = {
    propertyMap.addOne("additionalParam", "И если я ношу кандибобер на голове, это не значит, что я женщина или балерина")
  }

Пример jexl-функции:

  //создаем карту дополнительных параметров
  var addParamsMap = {"additionalParam": "И если я ношу кандибобер на голове, это не значит, что я женщина или балерина"};
  //к переданной карте propertyMap добавляем карту доп.параметров, приведенную к scala типу 
  propertyMap.addAll(asScala(addParamsMap));