DocxTemplateHandler

Генерация документов на основе шаблона docx

Версия 4.6.0

© 2015-2023, ООО "Процессные технологии"

# Обзор

Обработчик ru.runa.wfe.office.doc.DocxHandler предназначен для генерации документа формата DOCX на основании шаблона.

Обработчик может выполняться как в режиме строгого соответствия (strict-mode=true), что соответствует ошибке при любой ошибке в шаблоне или отсутствии определённых в шаблоне переменных в процессе, так и в режиме сниженного контроля (strict-mode=false), что указывается в конфигурации обработчика.

Замечание: Символы в названиях переменных (двоеточие, последовательность ' as ') могут вызывать ошибки обработки.

# Настройка

См. office.properties в руководстве по настройке. Свойства docx.placeholder.start, docx.placeholder.end определяют синтаксис управляющих инструкций. Далее в этом тексте использованы конструкции '${' и '}'.

# Замена текста

Выражения вида

${Переменная}

присутствующие в шаблоне, в документе будут заменены на значения переменных Переменная в формате, определённом в Среде разработки.

Замечание: Для формирования перевода строки переменная должна содержать последовательность "\r\n".

# Доступ к элементам карт и списков

Доступ к элементам контейнерных типов осуществляется с помощью квадратных скобок [].

В качестве индекса списка может выступать целочисленное значение или переменная.

В качестве ключа карты может выступать строковое значение или переменная.

Примеры:

карта[ключ1]
${список[3]}

# Доступ к полям типов Пользователь, Группа, Исполнитель

Вывод полей осуществляется стандартным способом. Например, для вывода Ф.И.О. из переменной "запустившийПроцесс" формата "Пользователь":

${запустившийПроцесс.fullName}

Замечание: В ранних версиях ^4.0.6- в конфигураторе можно было указать другой формат при замене переменной. Этот функционал будет доступен в режиме обратной совместимости ^4.2.0-, но в этом случае будут не доступны текущие возможности. Обработчик принимает решение перехода в режим обратной совместимости на основании наличия такой конфигурации.

# Доступ к коду ^4.2.2+

Доступ к коду осуществляется с помощью groovy.

Примеры:

${groovy:ru.runa.wfe.commons.CalendarUtil.formatDate(VARIABLE_NAME)}

# Работа с изображениями

Путём стандартной замены можно заменить указатель в шаблоне

${image1}

на значение файловой переменной, хранящей изображение.

Замечание: Если файловая переменная хранит не изображение (или изображение в неизвестном формате) - будет выдана ошибка обработки шаблона.

# Итераторы

При работе с контейнерами используются следующие итераторы:

• indexes для списков итерация по индексам (начиная с 0)
• numbers нумерация для списков (начиная с 1 = {index+1})
• items для списков итерация по значениям
• keys для карт итерация по ключам
• values для карт итерация по значениям.

# Работа с таблицами

Замечание: В ранних версиях ^4.0.6- в конфигураторе настраивались таблицы. Этот функционал будет доступен в режиме обратной совместимости ^4.2.0-, но в этом случае станут не доступны текущие возможности. Обработчик принимает решение перехода в режим обратной совместимости на основании наличия в конфигурации таблиц.

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

${ITERATOR:VARIABLE}
${ITERATOR:VARIABLE as SELECTOR}

, где ITERATOR название типа итератора

VARIABLE название контейнерной переменной (типа Карта или Список)

SELECTOR название поля или атрибута, которое будет взято от переменной, хранящей текущее значение итератора; в случае отстутствия используется значение итератора

Необходимо заполнить первую строку таблицы указанием на контейнеры, чтобы остальные строки заполнились значениями элементов этих контейнеров.

Примеры (каждая строк должна соответствовать одной ячейке первой строки):

${indexes:список}
${items:список}
${numbers:список}
${items:списокПользователей as fullName}
${список}
${keys:карта}
${карта}
${values:карта}
${values:картаСГруппами as name}

В случае отображения карт, связанных по ключу, сортировка осуществляется по ключам. Пример для связных карт карта1 и карта2 с ключами ключи1=ключи2. Первая строка таблицы первая ячейка ${keys:карта1}, вторая ячейка ${values:карта1}, третья ячейка ${values:карта2}. Все остальное заполнится автоматически.

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

Например, есть тип "Фурнитура" с атрибутами "Наименование" и "Количество". Есть список фурнитур, хранящийся в переменной вида Список(Фурнитура). Для отображения этого списка в таблице с колонками "Наименование" и "Количество" используем конструкции:

${items:Список as Наименование} 

и

${items: СписокФурнитура as Количество}

расположенные в соответствующих столбцах таблицы. Пример процесса, использующего данные конструкции: Файл:СписокФурнитурDOCX.par

Замечание^4.1.0-: Синтаксис с указанием названия поля или атрибута имел вид: ${ITERATOR:VARIABLE SELECTOR}.

# Объединение ячеек по вертикали ^4.4.0+

При генерации таблицы значение "-||-" (можно изменить с помощью настройки) трактуется как соединение с соответствующей ячейкой из предыдущей строки.

# Работа с переменными пользовательских типов

При замене используется синтаксис с точкой, являющейся разделением атрибутов переменной пользовательского типа.

Пример:

${car 1.name}

# Дополнительные возможности

# Циклы ^βeta

Цикл определяется 3-мя элементами: начало цикла, блок цикла и окончание цикла.

Начало цикла имеет формат

${ITERATOR:VARIABLE as ITERATOR_VARIABLE}

, где ITERATOR название типа итератора

VARIABLE название контейнерной переменной (типа Карта или Список)

ITERATOR_VARIABLE название переменной, хранящей текущее значение итератора, значение зависит от типа итератора

Блок цикла может содержать только текст. Доступ к переменной, хранящей текущее значение итератора аналогично стандартной замене.

Замечание: Блок цикла не допускает наличие таблиц.

Замечание: Блок цикла не допускает вложенных циклов.

Замечание^4.1.0-: Синтаксис с переменной-значением итератора имел вид: ${ITERATOR:VARIABLE ITERATOR_VARIABLE}.

Окончание цикла имеет формат

${/ITERATOR}

, где ITERATOR название типа итератора, соответствующее началу цикла

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

Примеры:

${items:список as значение}
 ${значение}
${/items}

${indexes:список as индекс}
 значение = ${список[индекс]} для элемента ${индекс}
${/indexes}

${keys:карта as ключ}
 ${ключ} = ${карта[ключ]}
${/keys}

${values:карта as значение}
 ${значение}
${/values}

# Ветвления ^{планируется}

${if (карта.size() == 0)}
 карта пустая
${if (карта.size() > 100)}
 карта достаточно заполнена
${if else}
 введите данные
${/if}

# Проверка шаблона docx ^4.4.1+

В версии RunaWFE 4.4.1 в случае заданного docx шаблона как

• файла в процессе (использование в задаче сценарии) - выполняется автоматическая проверка структур шаблона на соответствие переменным бизнес-процесса
• файла в системе (использование в задаче бота) - выполняется автоматическое определение входных параметров на основе используемых конструкций в docx шаблоне

# Проверка соответствия шаблона docx в сценарии переменным бизнес-процесса

Для создания шаблона в процессе используется ссылка "Создать" (доступна в случае входного параметра "Файл в процессе").

В открывшемся окне редактора docx необходимо задать шаблон используя конструкции, описанные ранее в данном документе.

Пример шаблона

После сохранения БП, автоматически выполняется проверка шаблона docx, в результате чего на вкладку с замечаниями будут выданы несоответствия конструкций переменным БП.

Из рисунка выше видно, что в шаблоне используются конструкции с последовательностями, которые не соответствуют названиям переменных в БП и атрибутов пользовательских типов этих переменных, а именно:

• "Данные документа.Список позиций в документе"

В БП существует переменная "Данные документа" пользовательского типа "Данные документа"

но атрибут "Список позиций в документе" называется иначе - "Список позиций"

• "Заказ.Договор на поставку.Поставщик" с атрибутами "Наименование" и "Телефон"

В БП существует переменная "Заказ" пользовательского типа "Заявка", имеющего атрибут "Договор на поставку". А вот атрибут "Поставщик" в БП имеет иное название "Поставщик деталей"

Применив в шаблоне docx правильные названия переменных, ошибки на вкладке с замечаниями будут очищены и БП будет возможно экспортировать на сервер.

# Определение входных параметров задачи бота на основе используемых конструкций в docx шаблоне

В версии RunaWFE 4.1.1 в задаче бота с обработчиком Word в случае использования шаблона docx в виде файла в системе, входные параметры задачи определяются автоматически на основе используемых в шаблоне конструкций.

Для создания шаблона в задаче бота используйте ссылку "Создать"

В открывшемся окне редактора docx необходимо задать шаблон используя конструкции, описанные ранее в данном документе.

Например,

После сохранения шаблона и задачи бота, необходимо обновить входные параметры

Переменные используемые в шаблоне будут автоматически определены и вынесены в раздел входных параметров.

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

Если список входных параметров будет отличаться от найденных в шаблоне переменных, то будет выдано соответствующее сообщение.