Назначение плагина Documents
Плагин предназначен для хранения документов, привязанных к договору клиента, и предоставления клиенту возможности загрузки документов через страницу Web-статистики. Также с помощью плагина есть возможность генерации документов в формате docx/xlsx/odt по заранее сформированному шаблону.
Установка и настройка плагина Documents
Плагин устанавливается с помощью утилиты bg_installer. После установки плагин должен быть активирован в меню Плагины=>Настройки плагинов и у него должна быть установлена конфигурация.
В конфигурации должно быть определено место на диске, где сервер биллинга будет хранить документы и шаблоны документов. Каталог должен быть доступен для записи пользователю, под которым запускается сервер биллинга. Также имеется возможность открытия файлов напрямую с расшаренной папки без скачивания, в случае необходимости.
# серверный путь, куда складируются файлы (корень) file.storage.root.path=/var/billing_doc # серверный путь, где будут расположены файлы шаблонов file.storage.pattern.path=/var/billing_pattern # путь, из которого могут открываться файлы file.net.share.root.path=/var/billing_files
Также стандартно может задаваться название пункта меню
# наименование пункта меню в Web-интерфейсе web.menuItem1=Документы
Для задания статуса, который будет присваивается сгенерированным документам по умолчанию используется следующая опция:
#статус по умолчанию для сгенерированных документов default.status=<код статуса из справочника статусов>
В случае использования в качестве шаблона документов файла в формате odt, необходимо указать полный путь до исполняемого файла LibreOffice
#путь до исполняемого файла libre.path=
Для различных типов договоров возможно указать папку, которая будет открываться при выгрузке/загрузке файлов документа через клиент биллинга. Папка должна быть доступна с единым именем на всех машинах, где запускается клиент.
contract.type.<type_id>.prefix=<prefix> contract.type.<type_id>.dir=<dir> contract.type.<type_id>.extract.regexp=<regexp1> contract.type.<type_id>.compare.regexp=<regexp2> #автоматическое создание поддиректорий, если они не существуют contract.type.<type_id>.dir.auto.create=<true|false>
Где:
- <type_id> - уникальный числовой идентификатор типа договора в пределах конфигурации;
- <prefix> - префикс номера договора;
- <dir> - доступный с клиентской машины общий каталог с подкаталогами договоров;
- <regexp1> - регулярное выражение для извлечения из номера договора ключевой последовательности;
- <regexp2> - регулярное выражение для определения подкаталога, с ключевым словом <EXTRACT>, заменяемым на извлечённую ключевую последовательность.
Например, файлы договоров x<номер> размещаются в каталогах /tmp/TT<номер>.
contract.type.1.prefix=x contract.type.1.dir=/tmp contract.type.1.extract.regexp=x(\d+) contract.type.1.compare.regexp=TT<EXTRACT>
Использование плагина Documents
После установки и активации плагина в каждом договоре появляется вкладка Документы. В редакторе справочников, доступном через меню Плагины=>Документы, должны быть определены перечни статусов документов, типы документов и журналы документов.
В договоре на вкладке Документы отображаются документы договора. Для добавления нового документа выберите Новый элемент на стандартной панели инструментов.
Далее введите название документа, выберите его тип, журнал и текущий статус. Для статуса можно ввести комментарий. История изменений статуса документа отображается в соответствующей таблице справа.
Нажмите ОК для сохранения документа.
На вкладке Файлы выберите файл, соответствующий текущему статусу документа, и загрузите его на сервер, нажав кнопку 
.
В дальнейшем вы можете загружать новые версии документа и выгрузить любое его состояние, выбрав строку в таблице и нажав на кнопку 
.
Для удаления документа нажмите кнопку 
.
Нажав кнопку 
можно открыть документ в приложении операционной системы, с которым ассоциирован данный тип файлов.
Шаблоны документов плагина Documents
Для автоматизации заполнения типовых форм документов предназначена функция генерации документов по шаблону. Шаблон документа заводится в редакторе шаблонов, доступном через меню Плагины=>Документы=>Шаблоны документов.
Для создания нового шаблона документа щелкните на кнопку Новый элемент на стандартной панели инструментов. В появившемся редакторе заполните необходимые поля, выберите файл шаблона - документ в формате docx (предпочтительный формат), odt (на сервере должен быть установлен пакет LibreOffice), xlsx.
На представленном выше рисунке отображены следующие поля:
Имя шаблона - имя шаблона документа;
Имя выходного документа - название документа, который будет сгенерирован и привязан к договору;
Файл шаблона - загружаемый шаблон документа в формате docx, odt, xlsx;
Комментарий к файлу - комментарий к загружаемому файлу шаблона;
Имя выходного файла - имя сгенерированного файла;
Комментарий к шаблону - комментарий шаблона;
Динамический класс - Java-класс, в котором возможно определить логику получения данных для шаблона;
Видимость шаблона в плагине - флаг того, что шаблон будет отображен на вкладке Документы в договоре;
Переменные - список переменных, содержащихся в файле шаблона документа;
Таблицы - список таблиц, которые требуется сгенерировать в файле шаблона документа.
Файл шаблона представляет собой текстовый документ, содержащий в своем тексте специальные последовательности, на место которых будут подставлены данные. Формат таких последовательностей имеет вид:
{имя_переменной} или {имя_переменной(значение_по_умолчанию)}
где имя_переменной - название этой последовательности; в тексте шаблона данное название должно совпадать с именем переменной в таблице Переменные;
значение_по_умолчанию - то значение, которое будет подставлено вместо последовательности в случае, если по имени перменной возвратится пустое значение (н-р, если в договоре отсутствует какой-либо заполненный параметр, то на его место можно поставить прочерк или какую-нибудь фразу ).
Новая переменная заводится с помощью редактора переменных, который вызывается нажатием на кнопку 
. Кнопками 
и можно отредактировать и удалить переменную соответственно.
В диалоговом окне редактора переменной задается имя переменной, ее тип и значение. Тип переменной выбирается в соответствующем выпадающем списке. Доступны следующие варианты:
Константа - значение переменной данного типа подставится в тело шаблона документа как есть. Данный тип переменной поддерживает макроподстановки, о которых речь пойдет ниже.
Параметр договора - как следует из названия, значение переменной данного типа берется из параметра договора. Для этого необходимо выбрать тип параметра договора и непосредственно сам параметр.
Дата - значение переменной данного типа можно выбрать из календаря (статическая дата, например, дата принятия устава), либо выбрать одно из предустановленных значений получения даты (динамическая дата. Возможные варианты: текущая дата, дата создания договора). Для переменной типа дата возможно ввести формат даты, который отформатирует дату требуемым образом. Подробнее о форматах дат см. SimpleDateFormat.
URL - предполагается, что значение переменной данного типа расположено на каком-то удаленном узле;
SQL - получение значения переменной данного типа осуществляется путем выборки из БД с помощью SQL-запроса.
В переменных типа Константа возможны следующие макроподстановки:
${contract_title} - название договора, для которого генерируется документ;
${contract_comment} - комментарий договора;
${current_user} - имя пользователя, который генерирует документ;
${user_<userId>} - имя пользователя с кодом <userId>. Код пользователя можно посмотреть в редакторе пользователей биллинга (Сервис=>Администрирование=>Пользователи и права), выбрав интересующего пользователя в таблице и нажав комбинацию клавиш Ctrl+i.
В переменных типа SQL возможны следующие макроподстановки:
${cid} - код договора, для которого генерируется документ.
Если в шаблоне документа задан динамический Java-класс, то значения, возвращаемые данным классом, имеют бОльший приоритет и перетирают значения одноименных переменных в списке переменных.
Динамический Java-класс реализует интерфейс ru.bitel.bgbilling.plugins.documents.server.bean.pattern.PatternDataExtractor, содержащий метод extractData( Connection con, int contractId, DocumentPattern pattern, DocumentType type, DocumentJournal journal, Map<String, String> apiMap ), который должен возвращать объект типа Map<String, String> - список переменных в формате "ключ=>значение переменной". Здесь в качестве ключа выступает название переменной, соответствующей переменной в файле шаблона документа.
Простой пример реализации метода extractData(Connection con):
public Map extractData( Connection con, int contractId, DocumentPattern pattern, DocumentType type, DocumentJournal journal, Map<String, String> apiMap ) throws BGException
{
Map<String, String> result = new HashMap<String, String>();
result.put("param1","value1");
result.put("param2","value2");
return result;
}
Если в файле шаблона документа есть таблицы, которые необходимо сгенерировать, то в редакторе шаблонов необходимо добавить соответствие между таблицей в файле шаблона и таблицей в шаблоне, создаваемом в клиенте биллинга. Это осуществляется на вкладке Таблицы редактора шаблонов путем нажатия кнопок Добавить , Редактировать и Удалить .
В представленном редакторе задается символьное имя таблицы, ее уникальный идентификатор в файле документа, метод получения данных и, соответствующее методу получения данных, значение для таблицы. На данный момент поддерживается 2 метода получения данных:
SQL - полученная SQL-запросом таблица как есть попадет в тело сгенерированного документа. В SQL-запросе возможно использование макроподстановки ${cid} - код договора, для которого производится генерация документа;
Динамический класс Java - класс на Java, который возвращает данные для генерируемой таблицы.
Для генерации содержимого таблицы необходимо в файле шаблона создать заголовок таблицы и первую строку-шаблон, содержащую образец форматирования текста и ячеек. В этой строке-шаблоне также необходимо прописать названия столбцов, которые будут выступать в качестве ключей при получении данных (только для метода получения данных - Динамический класс). Если названия столбцов не заданы, то используются названия по умолчанию (col1...colN). В методе получения данных SQL по умолчанию используется нотация col1...colN, следовательно, задавать названия столбцов не обязательно.
Следует отметить, что для поиска таблицы в тексте документ необходимо задать уникальный идентификатор, который должен соответствовать идентификатору, заданному в редакторе таблицы клиента биллинга. Этот идентификатор можно поместить в любую ячейку таблицы, но рекомендуется поместить ее в самую первую ячейку заголовка - потребуется меньше времени для поиска нужной таблицы. Формат идентификатора соответствует формату переменных в шаблоне - {уникальный_идентификатор}. В редакторе таблиц этот уникальный идентификатор должен быть без фигурных скобок.
Динамический класс должен реализовывать интерфейс ru.bitel.bgbilling.plugins.documents.server.bean.pattern.TableDataExtractor и метод extractData( Connection con, int contractId, List<Map<String, String>> apiRowList ), который возвращает List<Map<String, String>>, т.е. список строк и содержимое столбцов в виде "ключ->значение". В качестве ключа выступает название столбца в строке-шаблоне.
Замечения:
Рекомендуется использовать в качества шаблона документа файл Microsoft Office с расширением docx.
При использовании в качества шаблона документа файл с расширением odt необходимо, чтобы на сервере был установлен пакет LibreOffice. Также необходимо учитывать, что при использовании данного формата файла возможно искажение форматирования документа.
При использовании в качестве шаблона документа файл с расширением xlsx будет производиться подстановка ТОЛЬКО переменных в таблице на всех листах книги.
Для генерации документа необходимо открыть договор, для которого требуется сгенерировать документ по шаблону, выбрать вкладку Документы, выбрать Шаблон документа из выпадающего списка, Тип генерируемого документа и Журнал и нажать кнопку Сгенерировать. Сгенерированный документ появится в списке документов договора.