Плагин Documents

Назначение плагина 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
# путь, по которому могут открываться файлы шаблонов напрямую с диска.
# Внимание! Указанный путь должен быть доступен для клиента!
file.pattern.net.share.root.path
 
################ Настройки генерации документов #####################
 
# статус по умолчанию для сгенерированных документов
default.status=<код статуса из справочника статусов>
# В случае использования в качестве шаблона документов 
# файла в формате odt, необходимо указать полный путь до 
# исполняемого файла LibreOffice
libre.path=
 
############### Прочие настройки ###################
 
# заголовок отправляемого email-сообщения при отправке
# документа по почте
documents.mail.subject=Файл
# наименование пункта меню в Web-интерфейсе
web.menuItem1=Документы
# Для различных типов договоров возможно указать папку, 
# которая будет открываться при выгрузке/загрузке файлов 
# документа через клиент биллинга. Папка должна быть 
# доступна с единым именем на всех машинах, где запускается клиент.
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>
# Настройки по загружаемым файлам в редакторе документа.
# Формат строки:
# <extA1> | <extA2> | ... | <extAN> - <descriptionA>;<extB1> | <extB2> | ... | <extBN> - <descriptionB>; ...
# где <ext..> расширения в нижнем регистре, перечисленные через вертикальную черту, а через тире описание. Каждая такая группа разделяется точкой с запятой
client.documents.contract.file.upload.extensions=
# Ограничение на максимальный размер загружаемого файла в редакторе документа в байтах.
client.documents.contract.file.max.size=

Где:

  • <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

После установки и активации плагина в каждом договоре появляется вкладка Документы. В редакторе справочников, доступном через меню Плагины=>Документы, должны быть определены перечни статусов документов, типы документов и журналы документов.

images/download/attachments/73598649/documents_type_directory.png

images/download/attachments/73598649/documents_journal_directory.png

images/download/attachments/73598649/documents_status_directory.png

В договоре на вкладке Документы отображаются документы договора. Для добавления нового документа выберите Новый элемент на стандартной панели инструментов.

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

Нажмите ОК для сохранения документа.

images/download/attachments/73598649/documents_contract_editor.png

На вкладке Файлы выберите файл, соответствующий текущему статусу документа, и загрузите его на сервер, нажав кнопку images/download/attachments/73598649/item_up.png .

images/download/attachments/73598649/documents_contract_editor_files.png

В дальнейшем вы можете загружать новые версии документа и выгрузить любое его состояние, выбрав строку в таблице и нажав на кнопку images/download/attachments/73598649/item_down.png .

Для удаления документа нажмите кнопку images/download/attachments/73598649/delete.png .

Нажав кнопку images/download/attachments/73598649/open.png можно открыть документ в приложении операционной системы, с которым ассоциирован данный тип файлов.

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

images/download/attachments/73598649/documents_mails.png

Шаблоны документов плагина Documents

Для автоматизации заполнения типовых форм документов предназначена функция генерации документов по шаблону. Шаблон документа заводится в редакторе шаблонов, доступном через меню Плагины=>Документы=>Шаблоны документов.

Для создания нового шаблона документа щелкните на кнопку Новый элемент на стандартной панели инструментов. В появившемся редакторе заполните необходимые поля, выберите файл шаблона - документ в формате docx (предпочтительный формат), odt (на сервере должен быть установлен пакет LibreOffice), xlsx.

images/download/attachments/73598649/documents_pattern_editor.png

На представленном выше рисунке отображены следующие поля:

  • Имя шаблона - имя шаблона документа;

  • Имя выходного документа - название документа, который будет сгенерирован и привязан к договору;

  • Файл шаблона - загружаемый шаблон документа в формате docx, odt, xlsx;

  • Комментарий к файлу - комментарий к загружаемому файлу шаблона;

  • Имя выходного файла - имя сгенерированного файла;

  • Комментарий к шаблону - комментарий шаблона;

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

  • Видимость шаблона в плагине - флаг того, что шаблон будет отображен на вкладке Документы в договоре;

  • Переменные - список переменных, содержащихся в файле шаблона документа;

  • Таблицы - список таблиц, которые требуется сгенерировать в файле шаблона документа.

Файл шаблона представляет собой текстовый документ, содержащий в своем тексте специальные последовательности, на место которых будут подставлены данные. Формат таких последовательностей имеет вид:

{имя_переменной} или {имя_переменной(значение_по_умолчанию)}

где имя_переменной - название этой последовательности; в тексте шаблона данное название должно совпадать с именем переменной в таблице Переменные;

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

Новая переменная заводится с помощью редактора переменных, который вызывается нажатием на кнопку images/download/attachments/73598649/add.png . Кнопками images/download/attachments/73598649/edit.png и images/download/attachments/73598649/delete.png можно отредактировать и удалить переменную соответственно.

images/download/attachments/73598649/documents_variable_editor.png

В диалоговом окне редактора переменной задается имя переменной, ее тип и значение. Тип переменной выбирается в соответствующем выпадающем списке. Доступны следующие варианты:

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

  • Параметр договора - как следует из названия, значение переменной данного типа берется из параметра договора. Для этого необходимо выбрать тип параметра договора и непосредственно сам параметр.

  • Дата - значение переменной данного типа можно выбрать из календаря (статическая дата, например, дата принятия устава), либо выбрать одно из предустановленных значений получения даты (динамическая дата. Возможные варианты: текущая дата, дата создания договора). Для переменной типа дата возможно ввести формат даты, который отформатирует дату требуемым образом. Подробнее о форматах дат см. 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;
}

Если в файле шаблона документа есть таблицы, которые необходимо сгенерировать, то в редакторе шаблонов необходимо добавить соответствие между таблицей в файле шаблона и таблицей в шаблоне, создаваемом в клиенте биллинга. Это осуществляется на вкладке Таблицы редактора шаблонов путем нажатия кнопок Добавить images/download/attachments/73598649/add.png , Редактировать images/download/attachments/73598649/edit.png и Удалить images/download/attachments/73598649/delete.png .

images/download/attachments/73598649/documents_table_editor.png

В представленном редакторе задается символьное имя таблицы, ее уникальный идентификатор в файле документа, метод получения данных и, соответствующее методу получения данных, значение для таблицы. На данный момент поддерживается 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>>, т.е. список строк и содержимое столбцов в виде "ключ->значение". В качестве ключа выступает название столбца в строке-шаблоне.

Замечения:

  1. Рекомендуется использовать в качества шаблона документа файл Microsoft Office с расширением docx.

  2. При использовании в качества шаблона документа файл с расширением odt необходимо, чтобы на сервере был установлен пакет LibreOffice. Также необходимо учитывать, что при использовании данного формата файла возможно искажение форматирования документа.

  3. При использовании в качестве шаблона документа файл с расширением xlsx будет производиться подстановка ТОЛЬКО переменных в таблице на всех листах книги.

Для генерации документа необходимо открыть договор, для которого требуется сгенерировать документ по шаблону, выбрать вкладку Документы, выбрать Шаблон документа из выпадающего списка, Тип генерируемого документа и Журнал и нажать кнопку Сгенерировать. Сгенерированный документ появится в списке документов договора.

Web-интерфейс плагина Documents

В Web-интерфейсе клиент может посмотреть все связанные с ним документы в меню Документы и загрузить их.

images/download/attachments/73598649/x_167.gif

images/download/attachments/73598649/x_169.gif