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

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

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

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

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

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

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

Новая переменная заводится с помощью редактора переменных, который вызывается нажатием на кнопку . Кнопками и можно отредактировать и удалить переменную соответственно.

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

В переменных типа Константа возможны следующие макроподстановки:

В переменных типа SQL возможны следующие макроподстановки:

Если в шаблоне документа задан динамический 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 метода получения данных:

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

Замечения:

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