Скрипт DocumentGenerator для генерации документов

Принцип работы генератора

  • Генератор получает список интерактивов, используемых в шаблоне документа

  • Для каждого интерактива находит настройки поля в конфигурации по алиасу поля

  • Получает значение поля, используя указанный для поля модуль

  • Либо получает указанное для поля значение по умолчанию

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

Пример настройки поля:

document:field.{@field}.alias=contract_nds_summ_string
document:field.{@field}.filter.ids=11481
document:field.{@field}.value=process:1182
document:field.{@field}.module=parameter
document:field.{@field}.format.1=amount:string
document:field.{@field}.format.2=text:capitalize

где

  • alias - алиас поля. По этому алиасу происходит сопоставление поля с интерактивом

  • module - название модуля, который получает значение поля

  • filter - фильтр, применяемый к входным данным модуля

  • value - путь к значению поля - данный путь используется внутри модуля при получении значения, синтаксис зависит от конкретного модуля

  • format - применяемые к значению форматтеры

Перед добавлением нового поля в конфигурацию, следует убедиться, что поле с такими же настройками еще не добавлено

к содержанию

Типы значений

Модули возращают неформатированное значение поля типа ru.bgcrm.dyn.ufanet.document.generator.value.FieldValue.

Основные типы значений:

  • StringFieldValue - простое строковое значение

  • DateFieldValue - дата

  • AddressFieldValue - адрес

  • EmailFieldValue - e-mail

  • PhoneFieldValue - номер телефона

  • ListFieldValue - список строковых значений

  • IdTitlesFieldValue - список элементов IdTitle

  • MapFieldValue - мап название поля - строковое значение поля. На данный момент используется в композитных модулях

  • TableValue - мап Map<String, List<String>>

При необходимости, можно добавить новый тип значений, создать новый класс, реализующий FieldValue

к содержанию

Значение по умолчанию

Значение по умолчанию возвращается для поля, если текущее значение пустое. Пример:

document:field.{@field}.alias=customer_email
document:field.{@field}.value=customer:15
document:field.{@field}.module=parameter
document:field.{@field}.defaultValue=_______________@________

На данный момент реализована возможность задать вычисляемые значения по умолчанию:

  • date:lastDayOfYear - возвращает дату - последний день текущего года

  • date:today - возвращает дату - текущую дату

При необходимости, список вычисляемых значений по умолчанию можно расширить в классе ru.bgcrm.dyn.ufanet.document.generator.DefaultFieldValues

к содержанию

Модули

Модули отвечают за получение значения поля на основе входных данных.

Имеются стандартные модули, которых достаточно для получения значений параметров и свойств объектов ЕРП и Биллинга.

Модуль генерации данных на основе параметров объектов

Имя модуля: parameter

Класс реализации: ru.bgcrm.dyn.ufanet.document.generator.modules.ParameterFieldModule

Класс кастомизации: ru.bgcrm.dyn.ufanet.document.generator.modules.ParameterCustomizer

Используется для получения значения параметра объекта (процесса, контрагента, пользователя или единого договора). Нужно указать в настройках поля module=parameter и value=<тип объекта>:<код параметра>

  • value=process:<код параметра> - возвращает параметр процесса

  • value=customer:<код параметра> - возвращает параметр контрагента

  • value=user:<код параметра> - возвращает параметр пользователя

  • value=commonContract:<код параметра> - возвращает параметр единого договора

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

  • string, blob - StringFieldValue

  • date - DateFieldValue

  • list - IdTitlesFieldValue

  • address - AddressFieldValue

  • email - EmailFieldValue

  • phone - PhoneFieldValue

Пример:

document:field.{@field}.alias=customer_full_name
document:field.{@field}.value=customer:428
document:field.{@field}.module=parameter

к содержанию

Модуль генерации данных для единого договора

Имя модуля: commonContract

Класс реализации: ru.bgcrm.dyn.ufanet.document.generator.modules.CommonContractFieldModule

Класс кастомизации: ru.bgcrm.dyn.ufanet.document.generator.modules.CommonContractCustomizer

Используется для получения свойств единого договора. На данный момент доступны следующие поля:

  • value=commonContract:title - наименование

  • value=commonContract:dateFrom - дата создания договора

  • value=commonContract:password - пароль

Пример:

document:field.{@field}.alias=contract_number
document:field.{@field}.value=commonContract:title
document:field.{@field}.module=commonContract

к содержанию

Модуль генерации данных на основе договора Биллинга

Имя модуля: contract

Класс реализации: ru.bgcrm.dyn.ufanet.document.generator.modules.ContractFieldModule

Класс кастомизации: ru.bgcrm.dyn.ufanet.document.generator.modules.ContractCustomizer

Используется для получения свойств договора Биллинга. На данный момент доступны следующие поля:

  • value=contract:list:<код параметра> - значение спискового параметра

  • value=contract:address:<код параметра> - значение адресного параметра

  • value=contract:address - значение адресного параметра по умолчанию

Пример:

document:field.{@field}.alias=rb_contract_address
document:field.{@field}.value=address
document:field.{@field}.module=contract

к содержанию

Модуль генерации данных на основе свойств пользователя

Имя модуля: user

Класс реализации: ru.bgcrm.dyn.ufanet.document.generator.modules.UserFieldModule

Класс кастомизации: ru.bgcrm.dyn.ufanet.document.generator.modules.UserCustomizer

Используется для получения свойств объекта пользователя. Пример:

document:field.{@field}.alias=pic:user_sign
document:field.{@field}.value=user:stamp
document:field.{@field}.module=user

к содержанию

Модуль генерации данных на основе других интерактивов

Имя модуля: compose

Класс реализации: ru.bgcrm.dyn.ufanet.document.generator.modules.ComposeFieldModule

Класс кастомизации: ru.bgcrm.dyn.ufanet.document.generator.modules.ComposeCustomizer

Модуль для получения значения поля на основе значений других полей. В настройках композитного поля нужно в свойствах value задать режим использования и список полей, которые используются в композитном поле. К примеру: value=any:field1,field2,field3 На данный момент имеется два режима использования:

  • any - получает значение первого непустого поля в списке заданных полей. Пример:

document:field.{@field}.alias=contract_date
document:field.{@field}.value=any:process_contract_date,common_contract_start_date
document:field.{@field}.module=compose

  • all - получает значение всех полей списка заданных полей.Пример:

document:field.{@field}.alias=xml:contract_order_type_terms
document:field.{@field}.value=all:contract_order_type_terms,contract_start_date,contract_end_date
document:field.{@field}.module=compose

к содержанию

Добавление нового модуля

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

  • Создать класс модуля, реализующий интерфейс ru.bgcrm.dyn.ufanet.document.generator.modules.DocumentFieldModule

  • Создать класс кастомизации, реализующий интерфейс ru.bgcrm.dyn.ufanet.document.generator.modules.DocumentFieldValueGeneratorCustomizer Данный класс должен подготовить входные данные для модуля на основе информации, переданной в событие генерации документа. Можно применить фильтр к входным данным для модуля с помощью ru.bgcrm.dyn.ufanet.document.generator.ObjectFilter

  • Создать экземпляр класса кастомизации и добавить в ru.bgcrm.dyn.ufanet.document.generator.modules.Customizers.create()

к содержанию

Форматтеры

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

К полю можно применить один или несколько форматтеров.

Основные форматтеры:

Текстовые

Реализованы в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.TextFormatter.

Поддерживаемые типы значений: все.

  • text:uppercase - для отображения значения поля в верхнем регистре

  • text:lowercase - для отображения значения поля в нижнем регистре. Пример:

document:field.{@field}.alias=contract_type_lower_case
document:field.{@field}.value=process:3864
document:field.{@field}.module=parameter
document:field.{@field}.format=text:lowercase
document:field.{@field}.defaultValue=Государственный / Муниципальный (оставить нужное)

  • text:capitalize - для отображения значения поля с заглавной буквы

  • text:format - для подстановки значения поля в заданный шаблон. Пример:

document:field.{@field}.alias=customer_document_given_by
document:field.{@field}.value=any:process_customer_document_given_by,bgcrm_customer_document_given_by
document:field.{@field}.module=compose
document:field.{@field}.format=text:format:, выдан %s

В случае значений полей, возвращаемый в виде мапа название поля - значение поля MapFieldValue, шаблон для подстановки значений возвращается в первом элементе мапа, например:

document:field.{@field}.alias=xml:contract_order_type_terms
document:field.{@field}.value=all:contract_order_type_terms,contract_start_date,contract_end_date
document:field.{@field}.module=compose
document:field.{@field}.format=text:format

в данном примере значение поля contract_order_type_terms содержит интерактивы ${contract_start_date}, ${contract_end_date}, в которые подставляются значения полей contract_start_date, contract_end_date

к содержанию

Падежи

Реализованы в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.PadegFormatter.

Поддерживаемые типы значений: все.

Приводит значение поля в нужный падеж:

  • padeg:im:<submode> - именительный

  • padeg:rod<submode> - родительный

Режимы (submode):

  • appointment - падеж должности

  • office - падеж отдела

  • fio - падеж Фамилии Имени Отчества

  • cut_fio - падеж Фамилии Имени Отчества, сокращенном в виде Фамилия И.О.

Пример:

document:field.{@field}.alias=user_fio_rod
document:field.{@field}.value=user:title
document:field.{@field}.module=user
document:field.{@field}.format=padeg:rod:fio

к содержанию

Даты

Реализован в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.DateFormatter.

Поддерживаемые типы значений: DateFieldValue.

  • date:format - для вывода даты в указанном формате

document:field.{@field}.alias=common_contract_start_date
document:field.{@field}.value=commonContract:dateFrom
document:field.{@field}.module=commonContract
document:field.{@field}.format=date:format:«dd» MMMM yyyy г.
document:field.{@field}.defaultValue=«__» _____ ____ г.

к содержанию

Денежные значения

Реализованы в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.AmountFormatter.

Поддерживаемые типы значений: все.

Для форматирования суммы, денежных значений

  • amount:number - для вывода суммы в цифрах

  • amount:string - для вывода суммы в виде "%s рублей %s копеек"

document:field.{@field}.alias=contract_summ_string
document:field.{@field}.value=process:5055
document:field.{@field}.module=parameter
document:field.{@field}.format.1=amount:string
document:field.{@field}.format.2=text:capitalize

к содержанию

Адресные

Реализованы в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.AddressFormatter.

Поддерживаемые типы значений: AddressFieldValue.

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

  • address:city - для вывода города по значению адреса

Пример:

document:field.{@field}.alias=contract_address_city
document:field.{@field}.value=process:90
document:field.{@field}.module=parameter
document:field.{@field}.format=address:city

к содержанию

Номер телефона

Реализованы в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.PhoneFormatter.

Поддерживаемые типы значений: PhoneFieldValue.

  • phone:number - для вывода номера телефона

  • phone:comment - для вывода комментария к номеру телефона

Пример:

к содержанию

Преобразование с помощью мапа

Реализован в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.MapFormatter.

Поддерживаемые типы значений: все.

Мап для преобразования задается в виде map:key1:value1&key2:value2&key3:value3

где

  • key - входящее значение

  • value - значение на выходе

Если в качестве key указан *, то мап применяется ко всему входящему значению.

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

document:field.{@field}.alias=user_department_rod
document:field.{@field}.value=user:1196
document:field.{@field}.module=parameter
document:field.{@field}.format.1=map:Администрация:
document:field.{@field}.format.2=padeg:rod:office

выводит пустую строку вместо значения "Администрация".

document:field.{@field}.alias=rb_els_edo_sbis
document:field.{@field}.value=list:545
document:field.{@field}.module=contract
document:field.{@field}.filter.type=els
document:field.{@field}.format=map:17:✔&*:

если списковое поле содержит значение 17, то выводится знак "✔", в ином случае значение интератива остается пустым.

к содержанию

JSON

Реализован в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.JsonFormatter.

  • json:array - преобразует строку в формате json в ListFieldValue

к содержанию

Для вывода docx-разметки

Реализованы в классе ru.bgcrm.dyn.ufanet.document.generator.formatters.DocxFormatter.

Для преобразования значения поля в xml с разметкой для docx файла.

  • docx:list - возвращает docx-разметку с абзацами для списка строковых значений ListFieldValue. Один элемент списка - один абзац. Пример:

document:field.{@field}.alias=xml:contract_service_terms
document:field.{@field}.value=terms:common_contract
document:field.{@field}.module=terms
document:field.{@field}.format=docx:list

  • docx:table:<tableName> - возвращает docx-разметку с таблицей для значений DoubleListFieldValue. Каждый элемент мапа отображает в столбце таблицы. По умолчанию, все столбцы таблицы будут одинаковой ширины, но можно задать ширину и заголовок столбца в конфигурации в виде:

document.docx.table.<tableName>.column.<columnIndex>.title=Название столбца
document.docx.table.<tableName>.column.<columnIndex>.width=470

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

document:field.{@field}.alias=xml:internet_devices
document:field.{@field}.filter.type=internet
document:field.{@field}.value=devices
document:field.{@field}.module=devices
document:field.{@field}.format=docx:table:device
При обработке значений полей на стороне DocxDocBuilder реализовано экранирование xml специальных символов. Для вывода docx-разметки без экранирования xml специальных символов, нужно в название интерактива добавить префикс xml:

к содержанию

Добавление нового форматтера

Для добавления нового форматтера нужно:

  • Создать класс, реализующий интерфейс ru.bgcrm.dyn.ufanet.document.generator.formatters.FieldFormatter.

  • Добавить форматтер с список используемых форматтеров в ru.bgcrm.dyn.ufanet.document.generator.modules.Customizers.getFormatters()

к содержанию