DocxTemplateHandler: различия между версиями

Материал из RunaWFE
Перейти к навигации Перейти к поиску
 
(не показано 10 промежуточных версий этого же участника)
Строка 1: Строка 1:
{{PageHeading|Генерация документов на основе шаблона docx}}
{{PageHeading|Генерация документов на основе шаблона DOCX}}


{{Licensing}}
{{Licensing}}
Строка 137: Строка 137:
  ${ITERATOR:VARIABLE as ITERATOR_VARIABLE}
  ${ITERATOR:VARIABLE as ITERATOR_VARIABLE}
где  
где  
* ''ITERATOR'' название [[DocxTemplateHandler#Iterators|типа итератора]]
* ''ITERATOR'' - название [[DocxTemplateHandler#Iterators|типа итератора]]


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


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




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


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


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




Строка 156: Строка 156:
  ${/ITERATOR}
  ${/ITERATOR}
где  
где  
''ITERATOR'' название типа итератора, соответствующее началу цикла
* ''ITERATOR'' - название типа итератора, соответствующее началу цикла.


'''Замечание:''' Для корректной работы необходимо, чтобы управляющие конструкции начала и окончания цикла находились на разных строках и не содержали другого текста.
'''Замечание:''' Для корректной работы необходимо, чтобы управляющие конструкции начала и окончания цикла находились на разных строках и не содержали другого текста.
Строка 187: Строка 187:
  ${/if}
  ${/if}


= {{Title|ParseDocx|Проверка шаблона docx}} {{Since|4.4.1}} =
= {{Title|ParseDocx|Проверка шаблона DOCX}} {{Since|4.4.1}} =


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


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


== {{Title|ParseScriptDocx|Проверка соответствия шаблона docx в сценарии переменным бизнес-процесса}} ==
== {{Title|ParseScriptDocx|Проверка соответствия шаблона DOCX в сценарии переменным бизнес-процесса}} ==


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




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


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


[[Image:script_docx_t_2.png]]
[[Image:script_docx_t_2.png]]




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


[[Image:script_docx_t_3.png]]
[[Image:script_docx_t_3.png]]
Строка 216: Строка 216:


* "Данные документа.Список позиций в документе"  
* "Данные документа.Список позиций в документе"  
* "Заказ.Договор на поставку.Поставщик" с атрибутами "Наименование" и "Телефон".


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


[[Image:script_docx_t_4.png]]
[[Image:script_docx_t_4.png]]


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


[[Image:script_docx_t_5.png]]
[[Image:script_docx_t_5.png]]




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


[[Image:script_docx_t_6.png]]
[[Image:script_docx_t_6.png]]


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


== {{Title|ParseDocx|Определение входных параметров задачи бота на основе используемых конструкций в docx шаблоне}} ==
== {{Title|ParseDocx|Определение входных параметров задачи бота на основе используемых конструкций в DOCX шаблоне}} ==


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


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


[[Image:bot_task_docx_t_1.png]]
[[Image:bot_task_docx_t_1.png]]




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


Например,
Например:


[[Image:bot_task_docx_t_2.png]]
[[Image:bot_task_docx_t_2.png]]




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


[[Image:bot_task_docx_t_3.png]]
[[Image:bot_task_docx_t_3.png]]
Строка 262: Строка 261:
Процесс обновления параметров необходимо повторять после каждого изменения шаблона.
Процесс обновления параметров необходимо повторять после каждого изменения шаблона.


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


[[Image:bot_task_docx_t_5.png]]
[[Image:bot_task_docx_t_5.png]]

Текущая версия на 07:10, 31 октября 2024

Генерация документов на основе шаблона 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}

где

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

где

  • 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 в сценарии переменным бизнес-процесса

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

Script docx t 1.png


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

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

Script docx t 2.png


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

Script docx t 3.png


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

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

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

Script docx t 4.png

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

Script docx t 5.png


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

Script docx t 6.png

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

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

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

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

Bot task docx t 1.png


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

Например:

Bot task docx t 2.png


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

Bot task docx t 3.png


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

Bot task docx t 4.png


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

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

Bot task docx t 5.png

Bot task docx t 6.png