BGCRM 3.0
Дерево страниц
Перейти к концу метаданных
Переход к началу метаданных

О плагине

Плагин предназначен для генерации и учёта печатных форм документов. Понятие "документ" здесь трактуется достаточно широко: так это может быть и HTML отчёт, генерируемый из очереди процессов.

Механизм работы

Схематично принцип работы плагина изображён ниже. Синим цветом выделены блоки с использованием устаревшей XSLT технологии. Она поддержана в режиме обратной совместимости.

Однако все XSLT шаблоны рекомендуется в ближайшем будущем заменить на JSP.

Причины, по которой технология шаблонов была заменена:

  • унификация, JSP уже массово используется в системе;
  • производительность и ресурсоёмкость у JSP шаблонов существенно ниже;
  • затруднённый доступ к Java API из XSLT, фактически необходимость создания каждый раз XML оболочек для существующих Java методов.

Пояснения по схеме выше. Изначально на вход шаблонизатора подаётся одно либо набор событий с идентификаторами объектов, для которых следует сгенерироват документ и требуемом шаблоне. Идентификатор объекта - это код контрагента, процесса и т.п. Одно событие - генерация документа непосредственно для объекта, блок событий - генерация, например, из очереди процессов.

Есть некоторая разница в генерации событий в зависимости от результирующего формата. При генерации HTML документа из многих объектов генерируется одно событие, т.к. HTML подразумевает единый корень документа. При генерации PDF генерируются несколько событий и результаты склеиваются. Генерация ODT/DOCX и прочих форматов для нескольких объектов невозможна.

При использовании устаревшей XSLT (type=xsltHtml) генерации HTML фрагменты с результатами для отдельных объектов также склеиваются. В результате получить целостное HTML дерево с его помощью невозможно. Однако, большинство современных браузеров всё-таки отображают такой результат корректно.

С системой поставляется набор примеров генерации различных видов документов. Примеры JSP файлов с инструкциями по их настройке в комментариях расположены в каталоге webapps/WEB-INF/jspf/user/plugin/document/template/example.

Дополнительные примеры могут быть найдены в WiKi.

Конфигурация

Для добавления генератора документа в конфигурации указывается запись вида:

document:pattern.<id>.title=<title>
document:pattern.<id>.scope=<scope>
# заменой этого класса своим возможно полностью переопределить логику генерации документов
document:pattern.<id>.script=ru.bgcrm.plugin.document.docgen.CommonDocumentGenerator
document:pattern.<id>.type=<type>
document:pattern.<id>.jsp=<jsp>
#
# необязательные параметры общие
document:pattern.<id>.result=<result>
# 
# если результат не stream только - то имя сохраняемого документа
document:pattern.<id>.documentTitle=<doc_title>
document:pattern.<id>.titleRegexp=<title_pattern>
document:pattern.<id>.additionalParametersJsp=<additional_params_jsp>
#
# необязательный параметры для type=pdfForm/docxForm/odtForm
document:pattern.<id>.file=<file>
document:pattern.<id>.flattening=<flattening>
#
# устаревший параметр
document:pattern.<id>.xslt=<xslt>

Где:

  • <id> - уникальный числовой идентификатор типа документа;
  • <title> - отображаемое наименование шаблона, необходимо только для шаблонов, которые можно выбрать;
  • <scope> - тип сущности, для которой генерируется документ, см. далее;
  • <type> - тип генерируемого документа, описание типом см. далее;
  • <jsp> - путь к JSP шаблону, генерирующему HTML, либо подготавливающему данные для шаблонов;
  • <result> - допустимые значения через запятую: stream - не сохранять сгенерированный документ и сразу выдать его клиенту, save - сохранить документ;
  • <doc_title> - имя создаваемого документа;
  • <file> - имя файла со шаблоном документа (PDF форма либо иной исходный документ для подстановки параметров) рекомендуется располагать в каталоге BGCRM/docpattern;
  • <title_pattern> - REGEXP шаблон имени сущности, для которой будет предлагаться к генерации данный тип документа;
  • <additional_params_jsp> - JSP файл с дополнительными параметрами для генерации документа;
  • <file> - исходный документ, заполняемый данными;
  • <flattening> - 1, для типа pdfForm, если сгенерированный PDF документ следует сделать нередактируемым.

Возможные значения параметра <scope>, для генерации документов объектов ядра:

document:processShowDocuments=1
document:processCreateDocumentsAllowedTemplates=<коды шаблонов документов, доступных для генерации через запятую>

Также интеграцию с Document поддерживают следующие плагины, для них возможны свои значения параметра <scope>:

Поддерживаемые типы (параметр <type>):

  • pdfForm - PDF форма, исходная форма получается из параметра <file>, поля формы заполняются из XML документа с параметрами, подготовленного с помощью JSP шаблона <jsp>;
  • docxForm либо odtForm - .docx либо .odt файл с макросами вида ${macros}, значения которых заменяются значениями из XML документа с параметрами, подготовленного с помощью JSP шаблона <jsp>;
  • jspHtml - преобразование исходных данных в HTML с помощью JSP шаблона <jsp>;
  • xsltHtml - (устарело) преобразование исходных XML данных в HTML документ с помощью XSLT шаблона <xslt>.

PDF формы можно подготовить с помощью Adobe Acrobat, Master PDF Editor или аналогичной программы.

При использовании типов docxForm либо odtForm производится замена в текстовых файлах word/document.xml и content.xml макросов на значения.

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

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

<text:span text:style-name="T2">${cardNumber</text:span><text:span text:style-name="T3">}</text:span>

В этом случае макрос следует забить повторно и пересохранить документ, добившись примерно такого варианта:

<text:span text:style-name="T2">${cardNumber}</text:span>

Пример настройки генерации HTML документа из карточки процесса (взят из примеров webapps/WEB-INF/jspf/user/plugin/document/template/example).

document:pattern.101.title=Пример процесс HTML
document:pattern.101.scope=process
document:pattern.101.script=ru.bgcrm.plugin.document.docgen.CommonDocumentGenerator
document:pattern.101.type=jspHtml
document:pattern.101.jsp=/WEB-INF/jspf/user/plugin/document/template/example/process_html.jsp
document:pattern.101.documentTitle=document.html
document:pattern.101.result=stream,save

При использовании не HTML результирующего формата вывод JSP шаблона используется только в режиме отладки (см. далее). Для заполнения полей в JSP шаблон передаётся объект field, методом set которого можно установить значения именованных параметров.

Установленные промежуточные данные возможно просмотреть в режиме отладки. Режим отладки запускается при генерации документа с зажатой клавишей Alt в режиме без сохранения на диск. Отладка выводится в отдельном окне.

Режим отладки имеет смысл для типов шаблонов, где результирующим документом выступает не HTML. Он предоставляет возможность изучить вывод JSP шаблона с отладочной информацией  и подготовленные им поля. Для шаблонов, генерирующих HTML отладка возможна сразу в результирующий документ.

Плагин документов может быть использован для генерации отчётов в очереди процессов. Для запуска режима отладки в этом случае клавиша Alt должна быть зажата в момент выбора пункта обработчика в меню Ещё.

Интерфейс пользователя

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

В выпадающем списке выводятся настроенные для данного типа сущности шаблоны документов. Далее кнопки генерации документа с сохранением и без (настраиваются с помощью result параметра в конфигурации шаблона). Кнопка +? позволяет загружать произвольные файлы.

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

Примеры и документация к устаревшей XSLT технологии

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

Пример 1. Шаблон документа бланка заказа единого договора.

document:pattern.3.title=Уфа заказ
document:pattern.3.scope=bgbilling-commonContract
document:pattern.3.script=ru.bgcrm.plugin.document.docgen.CommonDocumentGenerator
document:pattern.3.titleRegexp=^72\d{6}
document:pattern.3.file=docpattern/ufa_zakaz.pdf
document:pattern.3.xslt=docpattern/ufa_zakaz.xsl
document:pattern.3.type=pdfForm
document:pattern.3.documentTitle=Уфа заказ.pdf

Пример 2. Шаблон для генерации печатной формы в очереди процессов.

document:pattern.37.title=BLANK
document:pattern.37.scope=processQueue
document:pattern.37.script=ru.bgcrm.plugin.document.docgen.CommonDocumentGenerator
document:pattern.37.xslt=docpattern/ktv_blank.xsl
document:pattern.37.type=xsltHtml
document:pattern.37.documentTitle=blank.html

Пример 3. Шаблон для генерации печатной формы акта в договоре BGBilling, используются доп. параметры и отличный от CommonDocumentGenerator обработчик-генератор документа.

document:pattern.34.title=Акт выполненных работ
document:pattern.34.scope=bgbilling-contract
document:pattern.34.titleRegexp=[a-яА-Яa-zA-Z0-9]*-[0-9]{2}
document:pattern.34.script=ru.bgcrm.dyn.ufanet.ArmDocumentGenerator
document:pattern.34.additionalParametersJsp=/WEB-INF/jspf/user/plugin/document/custom/execute_work_act_parameters.jsp
document:pattern.34.file=docpattern/execute_work_act.pdf
document:pattern.34.xslt=docpattern/execute_work_act.xsl
document:pattern.34.type=pdfForm
document:pattern.34.documentTitle=Акт выполненных работ <active_date>.pdf
document:pattern.34.flattening=1

Исходные данные преобразуются с помощью XSLT преобразования. На вход XSLT генератора подаётся XML документ следующего содержания.

<event objectId="<objectId>" objectType="<objectType>">
 <request>
  <param name="<paramName1>" value="<value1>"/>
  <param name="<paramName2>" value="<value2>"/>
  ....
  <param name="<paramNameX>" value="<valueX>"/>
 </request>
</event>

Где:

  • <objectId> - код объекта для которого генерируется документ;
  • <objectType> - тип объекта;
  • <paramNameX> и <valueX> - параметры HTTP запроса, переданные на генерацию документа, благодаря этим данным возможен параметризированный вызов генерации документа из внешних систем.

Для просмотра хода генерации включите вывод в лог отладочной информации. Работу можно начать с подобного шаблона, который просто выводит в результирующий документ (а следовательно и в лог) исходный XML.

<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 xmlns:bgcrm="http://bgcrm.ru/saxon-extension"
 xmlns:bgcrm-math="http://bgcrm.ru/saxon-extension-math"
 xmlns:t="http://bgcrm.ru/template" 
 exclude-result-prefixes="bgcrm bgcrm-math t"
 version="2.0">

 <xsl:template match="/event">
  <data>
     <!-- отладочный исходной XML -->
    <xsl:copy-of select="/event"/>
  </data>
 </xsl:template>
</xsl:transform>

Получение дополнительной информации осуществляется с помощью функций-расширений. Результат вызова функции-расширения можно вывести в отладку с помощью инструкции <xsl:copy-of>.

При генерации для типа xsltHtml исходный документ преобразуется сразу в HTML.

Для типов *Form в результате преобразования для генерации шаблона подготавливается документ XML следующего вида со значениями параметров.

08-07/19:03:49 DEBUG [http-bio-9089-exec-6] CommonDocumentGenerator - Transformation debug: <?xml version="1.0" encoding="UTF-8"?>
<data xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <field name="contract_number">72000784</field>
  <field name="contract_day">11</field>
  <field name="contract_month">апреля</field>
...

Далее параметры подставляются в поля PDF формы либо заменяют макросы документа, указанного в параметре file.

В составе ядра представлены перечисленные далее пространства имён и функции в них. Список может дополняться в плагинах.

Примеры XSLT шаблонов для генерации документов доступны в WiKi.

Расширения пространства имён "http://bgcrm.ru/saxon-extension-math"

isbitset( <value>, <bitNumber> ) - возвращает результат проверки установленности в значении <value> бита <bitNumber>, нумерация с 0 от конца двоичного представления числа.

Пример:

<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 xmlns:bgcrm-math="http://bgcrm.ru/saxon-extension-math"
 exclude-result-prefixes="bgcrm-math"
 version="2.0">

...
<xsl:when test="bgcrm-math:isbitset( $contractCard/data/contract/@gr, 43 )">
   <field name="contract_ctv_erkc">On</field>
</xsl:when>
...

Расширения пространства имён "http://bgcrm.ru/saxon-extension"

customer( <id> ) - получение XML документа с данными контрагента с кодом <id>.

Пример:

<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 xmlns:bgcrm="http://bgcrm.ru/saxon-extension"
 exclude-result-prefixes="bgcrm"
 version="2.0">
...
<xsl:variable name="customer" select="bgcrm:customer($customerId)" />
...
<field name="fio_full">
  <xsl:value-of select="$customer/data/customer/@title" />
</field>
...

process( <id> ) - получение XML документа с данными о процесе с кодом <id>.

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

<data>
     <process close_user_id="0" create_dt="2014-03-27 01:36:30.0" create_user_id="0" description="ФИО: Тестов Тест Тестович&#xA;Телефон: 33333 3333&#xA;Остаток: -970.00----------&#xA;" 
        executors="" groups="3" id="5408" priority="0" status_dt="2014-03-27 01:36:30.0" status_id="2" status_user_id="0" title="" type_id="4"/>
     <parameters><parameter id="1" title="Адрес" value="Магадан, Ленина, д. 5, кв. 77777"/><parameter id="2" title="Дата повторного обзвона" value=""/></parameters>
     <links><process_link config="" object_id="108035" object_title="TEST" object_type="contract:sofit" process_id="5408"/></links>
     <status><process_status comment="Процесс создан" dt="2014-03-27 01:36:30.0" last="1" process_id="5408" status_id="2" user_id="0"/></status>
</data>

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

<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 xmlns:bgcrm="http://bgcrm.ru/saxon-extension"
 exclude-result-prefixes="bgcrm"
 version="2.0">
...
<xsl:variable name="process" select="bgcrm:process($processId)" />
...
<field name="description">
  <xsl:value-of select="$customer/data/process/@description" />
</field>
...

user( <id> ) - получение XML документа с данными о пользователе с кодом <id>.

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

<xsl:transform xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 xmlns:xs="http://www.w3.org/2001/XMLSchema" 
 xmlns:bgcrm="http://bgcrm.ru/saxon-extension"
 exclude-result-prefixes="bgcrm"
 version="2.0">
...
<xsl:variable name="user" select="bgcrm:user($userId)" />
..

param( <objectId>, <paramId> ) - получение XML документа с данными о параметре <paramId> объекта с кодом <objectId>.

 

  • Нет меток
Документация BGCRM 3.0