# Подстановка переменных в документ

> [HTML Version](antifraud-fill-in-variables.html)

**(antifraud-fill-in-variables-1.png)**Графический элемент становится доступен в дизайнере бизнес-процессов после подключения [Модуля антифрод](antifraud-solution.md). Он позволяет с помощью модели искусственного интеллекта внести новые значения переменных в [сгенерированный по шаблону](360026936731.md) и отредактированный документ. Подстановка осуществляется на основе подготовленной [маски документа](antifraud-solution.md#templates-and-masks).

````
начало внимание

````
Действие доступно только для документов в формате **.docx**.

````
конец внимание

````
Новые значения подставляются в файл, сформированный на основе данных из элемента приложения. Допустим, сотрудник вносит первоначальные сведения в приложение **Договоры**. В ходе бизнес-процесса по шаблону формируется файл договора, затем сотрудник вручную добавляет в него перечень услуг и отправляет на согласование. Позже может выясниться, что данные договора нужно уточнить, например, со стороны контрагента изменился подписант. Чтобы не пришлось снова генерировать договор и повторно вносить дополнения вручную, в процессе можно предусмотреть изменение данных с помощью блока **Подстановка переменных в документ**. В этом случае сотрудник может просто исправить информацию в карточке договора. С помощью ИИ новое значение переменной подставится в сформированный файл вместо предыдущего.

Для корректной работы** **перед настройкой блока нужно:

- [создать входные и выходные переменные](#add-varialbes), которые указываются в настройках блока;

- [использовать в процессе другие графические элементы](#place-activities), чтобы подготовить данные для выполнения подстановки на сервере ИИ и учесть обработку ошибок.

## Добавить входные и выходные переменные

Для настройки блока нужно заранее создать определённый набор свойств. Они указываются в настройках блока в полях, которые подразделяются на:

- **входные атрибуты** — в них передаются свойства, содержащие данные для выполнения подстановки;

- **выходные атрибуты** — сопоставляются со свойствами, в которых сохраняется результат работы блока.

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

1. **Добавление входных переменных.**

Добавьте в [контекст бизнес-процесса](process_context.md) переменные:

- **Маска **(тип [Файлы](360009707032.md#file_type)) — файл маски, соответствующей шаблону, по которому сгенерирован документ. Используется на сервере ИИ для уточнения позиций переменных в документе, а также поиска в тексте функций, циклов и т. п.;

- **Переменные** (тип [Строка](360009707032.md#string)) — текущие данные из карточки документа, сериализованные в JSON. Свойство используется на сервере ИИ, чтобы подставить изменившиеся значения в файл. Создание строки в ходе процесса описано в разделе [«Сформировать JSON-строку для подстановки новых значений»](#json);

- **Исходный документ **(тип **Файлы**) — сгенерированный по шаблону документ, в который подставлены новые значения переменных. Файл используется на сервере ИИ для уточнения позиций переменных в документе, а также поиска в тексте функций, циклов и т. п. Подробнее о его формировании читайте в разделе [«Сформировать по шаблону файл с новыми значениями»](#genarate-new-doc);

- **Отредактированный документ **(тип **Файлы**) — сгенерированный по шаблону и отредактированный пользователем документ в формате **.docx**, в который подставляются новые значения переменных;

- **Переменные на предыдущем шаге** (тип **Строка**) — старые данные из карточки документа, сериализованные в JSON. Свойство используется на сервере ИИ для определения изменений в значениях переменных;

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

Обратите внимание, входные переменные нужно заполнить данными до того, как ход процесса дойдёт до шага **Подстановка переменных в документ**. Это делается с помощью других графических элементов. Например, файл маски можно записать из карточки документа с помощью блока [Присваивание](360020300571.md).  

2. **Добавление выходных переменных.**

Свойства для сопоставления с выходными атрибутами добавляются:

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

- в [контекст приложения](360028941112.md) — если данные нужно сразу записать в карточку документа. Чтобы свойства нужного приложения были доступны при сопоставлении атрибутов, в настройки процесса добавляется переменная типа **Приложение**, ссылающаяся на него.

Создайте следующие переменные, в которые запишется информация:

- **Ответ сервера AI **(тип **Строка**) — текст ответа, полученного с сервера ИИ. Его может использовать администратор для анализа ошибок, возникших при обработке документа на сервере. Например, чтобы узнать, какая проблема возникла при распознавании значений в JSON-строке с данными документа;

- **Статус запроса на сервер **(тип [Число](360009707032.md#number)) — код состояния HTTP, полученный с сервера ИИ. Переменную можно использовать для определения следующего шага процесса в зависимости от успешности подстановки. Подробнее читайте в разделе [«Настроить обработку ошибок»](#error-handling). Также на основе кода администратор может анализировать возникшие ошибки;

- **Документ с подставленными переменными** (тип **Файлы**) — файл обработанного документа, в который подставлены новые значения переменных.

## Настроить обязательные шаги в процессе

Разместите блок **Подстановка переменных в документ** в том месте на схеме процесса, где нужно внести в документ обновлённые значения.

Чтобы блок работал корректно, в ходе процесса нужно:

1. [Подготовить JSON-строки для сравнения старых и новых данных документа](#json). Они используются на сервере ИИ для добавления новых значений в файл.

2. [Задать проверку на изменения в значениях документа](#check-variables), чтобы не применять подстановку переменных без необходимости.

3. [Перед блоком подстановки сформировать версию документа с новыми значениями](#genarate-new-doc). Она используется на сервере ИИ для уточнения позиций переменных в файле.

4. [Учесть в процессе ошибок](#error-handling).

Рассмотрим, какие графические элементы для этого применяются.

**(antifraud-fill-in-variables-2.png)**

### Сформировать JSON-строки для подстановки новых значений

При подстановке новых значений в документ на сервере ИИ сопоставляются его старые и новые данные. Для этого используются JSON‑строки, в которые записаны свойства из карточки документа и их значения. Строки со старыми и новыми данными нужно передать во входных переменных блока **Подстановка переменных в документ**, поэтому их нужно создать до шага подстановки: перед редактированием документа и после него.

Для формирования строк используется графический элемент [Скрипт](360027203731.md). Представьте свойства приложения и их значения в виде объекта \[OBJECT\], затем переведите их в JSON и запишите результат в переменные.

Пример скрипта для преобразования переменных приложения в JSON-строку

````
async function mapVariables(): Promise<void> \{  
    // Получение свойств приложения, записанного в переменную процесса с кодом \`application\`  
    const applicationData = (await Context.data.application\!.fetch()).data;  
  
    // Создание объекта \`Map\` из всех свойств приложения, кроме системных, так как их не нужно проверять  
    // Системные свойства фильтруются по '\_\_' в начале названия  
    let variables = new Map(  
        Object.keys(applicationData)  
        .filter(key => \!key.startsWith('\_\_'))  
        .map(key => \[key, applicationData\[key\]\])  
    );  
  
    // Удаление ненужных свойств — маски и типа документа  
    variables.delete('mask');  
    variables.delete('contractType');  
  
    // Преобразование в строки тех значений переменных,  
    // для которых нужна особая логика,  
    // например, форматирование значений даты начала и окончания договора  
    variables.set('StartDate', applicationData.StartDate?.format('DD.MM.YYYY'));  
    variables.set('EndDate', applicationData.EndDate?.format('DD.MM.YYYY'));  
  
    // Преобразование объекта \`Map\` в объект со строковыми значениями  
    const variablesObject: \{ \[key: string\]: string \} = \{\};  
    \[...variables\].sort((a, b) => a\[0\].localeCompare(b\[0\]))  
    .forEach(variable => \{  
        variablesObject\[variable\[0\]\] = variable\[1\]?.toString();  
    \});  
      
    // Преобразование объекта в JSON и запись строки в переменную \`variables\` из контекста процесса  
    Context.data.variables = JSON.stringify(variablesObject);  
\}
````

### ````
Настроить проверку на изменение значений

Чтобы процесс направлялся по ветке с подстановкой переменных, только если пользователь изменил данные, задайте проверку с помощью [шлюза](360012495911.md). 

**(antifraud-fill-in-variables-3.png)**

В настройках шлюза установите для перехода к блоку подстановки условие, в котором сравниваются сформированные ранее JSON-строки со старыми и новыми значениями. Если они не совпадают, необходима подстановка новых данных в файл.

**(antifraud-fill-in-variables-4.png)**

Другой переход отметьте как вариант по умолчанию.

### Сформировать по шаблону файл с новыми значениями

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

Для этого после шага изменения данных в карточке используйте блок  [Генерация по шаблону](360026720792.md) или [Генерация по файлу](generate-from-file.md). Запишите получившийся файл в переменную, чтобы передать её во входных атрибутах при настройке блока подстановки.

### Настроить обработку ошибок

1. **Ошибки в работе блока**. Во время работы блока могут возникать критические ошибки, к примеру, если **Модуль антифрод** оказывается отключён. Такие случаи обрабатываются с помощью дополнительного исходящего перехода из блока **Подстановка переменных в документ**. Например, при его активации процесс может завершаться. Добавьте переход на схему, чтобы при настройке блока указать его на вкладке **Обработка ошибок**.

2. **Ошибки на сервере ИИ**. Во время подстановки значений также могут возникать ошибки на стороне сервера. Нужно предусмотреть действия, которые будут выполняться при неуспешной обработке документа. Например, добавить задачу, в которой пользователь может запустить подстановку данных повторно.

Чтобы задать точку, в которой процесс может продолжиться по разным веткам, используется [шлюз](360012495911.md).

**(antifraud-fill-in-variables-5.png)**

В настройках шлюза в качестве варианта по умолчанию укажите переход для обработки ошибок сервера. Для другого перехода задайте условие. Чтобы определить успешность обработки документа, можно использовать код статуса HTTP, который при работе блока **Подстановка переменных в документ** записывается в специальную переменную. Если статус ответа с сервера равен **200**, продолжится основной ход процесса.

**(antifraud-fill-in-variables-6.png)**

## Настройка блока

После выполнения предварительных действий дважды нажмите на блок **Подстановка переменных в документ** на схеме процесса и задайте настройки на трёх вкладках: **Основное**, **Входные и выходные атрибуты**, **Обработка ошибок**.

### Вкладка «Основное»

Заполните основные настройки:

**(antifraud-fill-in-variables-7.png)**

- **Название** — введите название блока, которое будет отображаться на схеме процесса;

- **Название задачи **— блок **Подстановка переменных в документ** выполняется автоматически без назначения задачи на пользователя. Поэтому настраивать формирование названия задачи не требуется, и поле можно оставить пустым;

- **Присвоить выходные атрибуты в **— укажите, куда будет записываться результат исполнения блока:

	- **контекст процесса **— отметьте эту опцию, если вы создали переменные, в которые запишется результат работы блока, в контексте процесса;

	- **приложение **— выберите опцию, а затем в поле **Переменная\*** укажите приложение, добавленное в контекст процесса, в поля которого будет записан результат работы блока.

### Вкладка «Входные и выходные атрибуты»

На этой вкладке заранее созданные свойства связываются с настройками блока, которые делятся на:

- **входные атрибуты** — в них передаются свойства, хранящие данные для выполнения подстановки. Их нужно заполнить значениями до того, как процесс дойдёт до блока **Подстановка переменных в документ**;

- **выходные атрибуты** — сопоставляются со свойствами, в которые записывается результат работы блока.

Описание свойств и их типы приведены в разделе [«Добавить входные и выходные переменные»](#add-varialbes).

Сопоставление может выглядеть так:

**(antifraud-fill-in-variables-8.png)**

### Вкладка «Обработка ошибок»

Определите, по какой ветке направится ход бизнес-процесса при возникновении ошибки в работе блока, например, если модуль отключён. Также вы можете настроить оповещение пользователей об ошибке.

**(antifraud-fill-in-variables-9.png)**

- **Оповещение** — включите опцию и укажите пользователей, которым будет отправляться оповещение об ошибке в процессе. Вы можете выбрать пользователя, [группу](360007146071.md) пользователей, [элемент оргструктуры](360003861992.md), а также указать [контекстную переменную](process_context.md), например, инициатора процесса;

- **Прервать** — для корректной работы блока необходимо включить опцию, а затем в поле **Переход** указать, по какой ветке направится процесс в случае ошибки. Указанный в этих настройках переход будет отмечен на схеме процесса значком **(error-connector-icon.png).**

После завершения настройки нажмите кнопку **Сохранить**.