Синтаксис формул — набор правил, по которым записываются выражения, чтобы система могла их однозначно разобрать и вычислить. Перечень функций — в статье Функции и операторы для формул вычисления.

Из чего состоит формула

Формула (выражение) — инструкция системе выполнить вычисление и вернуть результат. Формула состоит из:

Элемент	Описание	Примеры
Константы (литералы)	Фиксированные значения: числа (дробная часть — через точку), строки, логические значения.	`5`, `3.14`, `-10`, `'Согласовано'`, `true`, `false`
Функции	Имя, круглые скобки и параметры через запятую. Возвращают значение и могут быть вложены друг в друга: результат одной функции — параметр другой.	`Date()`, `Parent('Проект', 'Шифр')`
Операторы	Арифметические, сравнения, логические, конкатенация — см. ниже.	`+`, `==`, `&&`
Скобки	Круглые скобки задают порядок вычисления: выражение в скобках вычисляется первым.	`(A + B) * 2`

Пустое значение получают функцией Null(), даты — функциями Date(), DateTime(), ParseDateTime(). Переменных и присваивания в формулах нет: формула только вычисляет значение, а куда его записать, определяет настройка (например, атрибут вычисляемого поля).

Пример формулы:

if(IsNull(This("Дата начала (План)")), Date(), This("Дата начала (План)"))

Функции

Имя функции начинается с заглавной буквы и чувствительно к регистру: This — верно, this — ошибка.
Скобки обязательны даже у функций без параметров: Date(), User().
Параметры передаются по порядку, через запятую. Необязательные параметры в конце можно опускать.
У многих функций первый параметр [context] необязателен: если первым передан элемент, значение подстановки или GUID, он считается контекстом; иначе используется текущий элемент. Например, Field('Название') — атрибут текущего элемента, Field(Parent(), 'Название') — атрибут родителя.
Некоторые функции принимают произвольное число параметров: Merge, Sum, Format, Switch.

if и in — не функции системы, а встроенные операторы движка формул, они пишутся с маленькой буквы.

if(условие, значение_если_истина, значение_если_ложь) — ветвление. Вычисляется только выбранная ветка — это позволяет, например, увеличивать один из двух счётчиков в зависимости от условия. Та же логика записывается тернарным оператором условие ? a : b.
in(значение, v1, v2, ...) — проверка вхождения: истина, если значение совпадает с одним из перечисленных.

Операторы

Группа	Операторы	Примечание
Арифметические	`+ - * / %`	% — остаток от деления.
Сравнение	`== != > < >= <=`	Равенство можно записать и как `=`, неравенство — как `<>`. Рекомендуется `==` и `!=`.
Логические	`&& \|\| !`	Допустимы также слова `and`, `or`, `not`.
Конкатенация строк	`+`	Если один из операндов — строка, выполняется склеивание. Для сборки строк из нескольких частей удобнее `Format`.
Ветвление	`if(условие, a, b)` `условие ? a : b`	Две равнозначные формы записи. Тернарный оператор удобен для цепочек условий: `усл1 ? a : (усл2 ? b : c)` — пример в статье Пример: фильтрация статусов задачи по участнику.
Проверка вхождения	`in(значение, v1, v2, ...)`	Истина, если значение совпадает с одним из перечисленных.

Приоритет: скобки → ! и унарный минус → * / % → + - → сравнения → && → ||. При сомнениях ставьте скобки.

Кавычки и экранирование

Перед разбором формулы система заменяет все двойные кавычки " на одинарные ', а сочетание \" — на символ двойной кавычки внутри строки. Из этого следуют правила:

Строку можно заключать в одинарные или двойные кавычки — они равнозначны. Рекомендуется для внешнего уровня использовать одинарные.
Двойная кавычка без обратной косой черты не может быть символом внутри строки: 'Field("Почта")' превратится в 'Field('Почта')' и вызовет ошибку.
Чтобы поместить кавычки внутрь строки, экранируйте их обратной косой чертой: \' или \".
В лямбда-условиях GetList строковые значения и GUID записываются в двойных кавычках, поэтому внутри условия всегда используйте \".
При обычном вызове функции (без вложенной строки-формулы) экранирование не требуется.

Задача	Как записать	Пример
Обычная строка	в одинарных `' '` или двойных `" "` кавычках	`This('Название')` или `This("Название")`
Строка внутри строки (формула в Select, Exists, All, Any)	внешняя строка в одинарных кавычках, внутренние кавычки — `\'` или `\"`	`Select(This('Исполнитель', true), 'Field(\'Почта\')')` `Select(This('Наблюдатели', true), 'Field(\"Почта\")')`
Строка в лямбда-условии GetList (сравнение со строкой, Guid)	внутренние кавычки только `\"`	`GetList(Id(), 'i => i.ContentTypeId == Guid(\"84124eed-7049-46a8-bac9-a179ff00efe3\")')`
Символ двойной кавычки в результате (JSON, параметры URL)	`\"`	`'{\"id\":\"' + Str(Id()) + '\"}'`
Фигурная скобка как текст в Format	удвоить: `{{` и `}}`	`Format('{{{0}}}', Id())` → {guid}

Глубокая вложенность

Если уровней вложенности больше двух (например, формула в Select внутри строки параметров URL), используйте замену: запишите внутренние кавычки условным символом (например, #) и замените его функцией Replace(строка, '#', '\"'). Разобранные примеры: Пример: копирование подписей ЭЦП на копию документа (условный символ # вместо кавычек и метки для подстановки идентификаторов) и Пример: добавление в процесс связей на новые файлы папки.

Прочие элементы синтаксиса

Элемент	Назначение	Пример
Запятая `,`	Разделяет параметры функции. Лишняя или пропущенная запятая — ошибка.	`if(IsNull(This('Дата')), Date(), This('Дата'))`
Точка `.` в имени атрибута	Переход к атрибуту связанного объекта (по подстановке): объект → связанный объект → его атрибут.	`This('Инициатор.Название')` `This('Статус процесса.id')`
Точка в Lookup и Inc	Разделяет имя списка, атрибут и значение.	`Lookup('Статусы документов.Размещено')` `Inc('Счётчики.Счётчик.2')`
Лямбда `=>`	Условие отбора в GetList (строка): переменная => условие. Доступны `i.Id`, `i.ContentTypeId`, `i.ParentId`, `i.GetValueAsString("поле")`, `i.GetLookupId("поле")` и др.	`GetList(Id(), 'i => i.ContentTypeId == Guid(\"84124eed-7049-46a8-bac9-a179ff00efe3\")')`
Фигурные скобки `{ }`	Маркеры подстановки в Format (`{0}`, `{1:0000}`); создание массивов в лямбда-условиях (`new Guid[] {Guid(...), Guid(...)}`). Внутри Format литеральные скобки удваиваются.	`Format('{0:0000}', 12)` → 0012
Квадратные скобки `[ ]`	Используются только внутри строк (JSON, параметры API). В документации функций квадратными скобками обозначаются необязательные параметры.	`'[{' + ... + '}]'`

Типы значений

Тип	Откуда получается	Особенности
Элемент	`This()`, `Parent()`, `Lookup()`, `Ref()`	Можно передавать как [context] в другие функции; атрибуты — через `Field(элемент, 'атрибут')`.
Значение подстановки (lookup)	атрибут-ссылка: `This('Статус')`	Для названия используйте `This('Статус.Название')`, для идентификатора — `This('Статус.id')` или `Id(...)`.
Список	`GetList`, `Refs`, `Select`, `Merge`, множественные атрибуты	Обрабатывается функциями Count, Contains, Exists, All, Any, Join, First, Last, Sum, Min, Max.
Дата-время	`Date()`, `DateTime()`, атрибуты-даты	Хранится в UTC. Параметр формата превращает дату в строку.
Число, строка, логическое	константы, функции	Для сравнения чисел из строк используйте `ParseFloat`, для приведения к строке — `Str`.

Обработка ошибок

Синтаксическая ошибка — формула не вычисляется. В вычисляемом поле значение атрибута не изменится, в отладочном запросе вернётся ошибка.
Ошибка внутри функции — функция возвращает пустую строку, формула продолжает вычисляться. Типичные причины: опечатка в названии атрибута, типа элемента или типа связи; элемент не найден; неверный тип параметра.
Сравнение пустого значения со строкой или числом даёт Ложь — поэтому ошибочное условие автоматизации «не срабатывает», а не выдаёт ошибку.

Проверка перед сохранением

Каждой открывающей скобке ( { [ соответствует закрывающая.
Все кавычки закрыты; кавычки внутри строк экранированы (\' или \"), неэкранированных " внутри строк нет.
Нет лишних и пропущенных запятых; число параметров соответствует описанию функции.
Имена функций написаны с заглавной буквы (кроме if и in).
Названия атрибутов, типов элементов, типов связей и справочников совпадают с настройками системы.
Для сравнения используется == или !=; вложенность if корректна.
Формула проверена на тестовом элементе (см. Отладка формул).

Page tree

Синтаксис формул