Плагин 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/43386544/documents_type_directory.png

images/download/attachments/43386544/documents_journal_directory.png

images/download/attachments/43386544/documents_status_directory.png

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

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

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

images/download/attachments/43386544/documents_contract_editor.png

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

images/download/attachments/43386544/documents_contract_editor_files.png

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

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

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

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

images/download/attachments/43386544/documents_mails.png

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

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

images/download/attachments/43386544/documents_pattern_clone.png

На данной вкладке отображается список существующих шаблонов документов. В контекстном меню каждого шаблона доступен пункт Создать копию шаблона, которая создает полную копию указанного шаблона, изменяя название.

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

images/download/attachments/43386544/documents_pattern_editor.png

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

images/download/attachments/43386544/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/43386544/add.png , Редактировать images/download/attachments/43386544/edit.png и Удалить images/download/attachments/43386544/delete.png .

images/download/attachments/43386544/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 будет производиться подстановка ТОЛЬКО переменных в таблице на всех листах книги.

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

Массовое добавление файлов в договоры

Для массового добавления файла (ов) к договору (ам) предназначена соответствующая групповая операция. Выберите пункт меню Сервис->Администрирование->Групповые операции, активируйте пункт Документооборот: Добавление файлов к договорам.

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

images/download/attachments/43386544/documents_group_operation.png

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

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

images/download/attachments/43386544/x_167.gif

images/download/attachments/43386544/x_169.gif