Справочник функций и операторов, которые можно использовать в формулах вычислений. Правила записи формул (кавычки, экранирование, скобки, типы значений) — в статье Синтаксис формул; проверка формул на портале — Отладка формул.
Обозначения
Необязательные параметры указаны в квадратных скобках [ ]. Необязательный первый параметр [context] — элемент, для которого выполняется функция: элемент, значение подстановки или GUID. Если он не указан, используется текущий элемент вычисления. Имена функций чувствительны к регистру и начинаются с заглавной буквы. Исключения — встроенные if и in: это операторы движка формул, они пишутся с маленькой буквы.
Указатель
| Группа | Функции и операторы |
|---|---|
| Операторы | if, ? :, &&, ||, + - * /, + (строки) |
| Структура хранения данных | This, Field, Parent, Lookup, Path, Copy, Null |
| Атрибуты элемента | Id, Author |
| Связи | Ref, Refs |
| Работа со списками | GetList, Select, Merge, Count, Contains, Exists, All, Any, First, Last, GetFieldList |
| Логические функции и проверки | IsNull, IsNotNull, Nvl, Switch, IsNew, IsStartsWith, IsEndWith, IsUserAdmin |
| Строковые функции | Format, Join, Replace, Substring, IndexOf, Split, Shrink, TrimEnd, Str, Hash, Translit, FileExt |
| Дата и время | Date, DateTime, Time, AddDay, AddMonth, AddYear, AddWorkingTime, DateTimeInterval |
| Математические функции | Sum, Min, Max, Inc, Pow, Sqrt |
| Преобразование типов | ParseBool, ParseDateTime, ParseFloat |
| Организационно-штатная структура | User, SubordinateUserList, SubstitutedUserList |
| Конфигурация | Cfg |
| Встроенные математические функции движка | Abs, Round, Floor, Ceiling, Truncate, Sign, Exp, Log, Log10, in |
По алфавиту: AddDay · AddMonth · AddWorkingTime · AddYear · All · Any · Author · Cfg · Contains · Copy · Count · Date · DateTime · DateTimeInterval · Exists · Field · FileExt · First · Format · GetFieldList · GetList · Hash · Id · if · Inc · IndexOf · IsEndWith · IsNew · IsNotNull · IsNull · IsStartsWith · IsUserAdmin · Join · Last · Lookup · Max · Merge · Min · Null · Nvl · Parent · ParseBool · ParseDateTime · ParseFloat · Path · Pow · Ref · Refs · Replace · Select · Shrink · Split · Sqrt · Str · SubordinateUserList · SubstitutedUserList · Substring · Sum · Switch · This · Time · Translit · TrimEnd · User
Операторы
Операторы вычисляются движком формул. Полный перечень операторов и правила их записи — в статье Синтаксис формул.
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| if(statement, 'value is true', 'value is false') | Проверяет результат заданного логического выражения и в зависимости от него возвращает одно из двух значений | statement type: bool value is true type: объект value is false type: объект | объект | if(IsNotNull(This('Шифр')), This('Шифр'), This('Статус документа.Название')) | возвращает значение атрибута "Шифр", если он заполнен, в противном случае, будет возвращено название статуса документа текущего элемента вычисления |
statement ? value1 : value2 НОВОЕ | Тернарный условный оператор — краткая форма if: если условие statement истинно, возвращает value1, иначе value2. Вычисляется только выбранная ветка. Удобен для цепочек условий: | statement type: bool value1 type: объект value2 type: объект | объект |
| то же, что пример для if выше роль текущего пользователя по отношению к элементу. Развёрнутый пример — Пример: фильтрация статусов задачи по участнику |
| statement_1 && statement_2 | Логическое "И" - проверит значение обоих выражений и вернет True, если оба из них являются верными и False, если хотя-бы одно неверно. Если statement_1 == False, то результат тоже будет False и второе выражение вычисляться не будет | statement_1 type: bool statement_2 type: bool | bool | This('Статус.id') == Id(Lookup('Статусы задач.На доработку')) && IsNull(This('Вопрос проектировщику')) | Вернет True, если значение атрибута "Статус" текущего элемента - "На доработку" и атрибут "Вопрос проектировщику" не заполнен и False, в противном случае |
| statement_1 || statement_2 | Логическое "ИЛИ" - проверит значение обоих выражений и вернет True, если хотя-бы одно из них является верным. | statement_1 type: bool statement_2 type: bool | bool | Field(Ref('Вложение процесса'), 'Статус документа.Название') == 'Размещено' || Field(Ref('Вложение процесса'), 'Статус документа.Название') == 'На корректировке' | Вернет True, если значением атрибута "Статус документа" вложения процесса является "Размещено" или "На корректировке" и False, если нет |
математические операторы: + | Применяем математический оператор к операндам | value1 type: число value2 type: число | число/число в плавающей точкой | (This('Поле A') + This('Поле B') + This('Поле С')) * Field(Parent('Комплект'), 'Множитель') / 3 | результат сложения значений атрибутов "Поле A", "Поле В" и "Поле С" текущего элемента, умноженный на значение атрибута "Множитель" родительского элемента с типом элемента "Комплект" и поделенного на 3 |
| value1 + value2 + ... + valueN | Возвращает результат конкатенации N строк | value1,value2,...,valueN type: строка | строка | Field(Parent('Проект'), 'Шифр') + '-' + Field(Parent(), 'Марка') | возвращает разделенные дефисом значение атрибута "Шифр" у первого родительского элемента с типом элемента "Проект", и значение атрибута "Шифр" родительского элемента |
Структура хранения данных
Получение значений атрибутов текущего элемента и элементов структуры хранения, поиск родителей, справочников, копирование.
Коды специальных свойств элемента (id, site, list, parentid, contenttype, author/insertuser, created/insertdate, editor/updateuser, modified/updatedate, deleteuser, deletedate) приведены в описании функции Field.
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| This([fieldName], [expandGroup]) | Возвращает текущий элемент вычисления, если функция вызывается без параметров или значение атрибута [fieldName]. Флаг [expandGroup] используется для раскрытия подразделений и функциональных групп из списка "Пользователи" (вместо группы в атрибуте [fieldName] будут возвращены участники этой группы) | fieldName type: строка expandGroup type: bool | элемент/значение атрибута | This() This('Утверждающие', false) | текущий элемент вычисления значение атрибута "Утверждающие" с раскрытием групп и заменой их на участников этих групп. Если в поле указан пользователь, то он попадает в результат, как есть |
Field([context], fieldName, [checkParent], [includeCurrent], Коды специальных свойств элемента, которые не относятся к атрибутам, но также могут использовать в вычислениях: | Возвращает значение атрибута fieldName из [context], текущего элемента вычисления или проектной структуры. Флаг [checkParent] определяет надо ли искать атрибут fieldName по всей проектной структуре. Флаг [includeCurrent] используется только если [checkParent] выставлен в true. Определяет надо ли учитывать элемент из [context], или текущий элемента вычисления при поиске атрибута fieldName в проектной структуре. Флаг [expandGroup] используется для раскрытия подразделений и функциональных групп из списка "Пользователи" (вместо группы в атрибуте fieldName будут возвращены участники этой группы). | context type: элемент fieldName type: строка checkParent: type: bool includeCurrent: type: bool expandGroup type: bool | значение атрибута | Field(Parent('В процессе'), 'Название') Field('Согласующие', true, false, true) Field(Parent('Проект'), 'Название') | значение атрибута "Название" родительской папки с типом элемента или названием "В процессе" значение поля "Согласующие" из проектной структуры текущего элемента вычисления, без учета самого элемента и с раскрытием групп пользователей значение атрибута "Название" родительской папки с типом элемента или названием "Проект" |
| Parent([context], [typeName], [fieldName], [includeCurrent]) | Возвращает родительский элемент, с типом элемента [typeName] или значение атрибута [fieldName] указанного типа. При этом, если значение типа не указано, то поиск атрибута выполняется по всей проектной структуре снизу-вверх. Флаг [includeCurrent] определяет надо ли учитывать элемент из [context] или текущий элемент вычисления | context type: элемент typeName type: строка fieldName type:строка includeCurrent type: bool | элемент/значение атрибута | Parent() Parent('В процессе') Parent(Ref('Связь с замечанием'), 'Проект') Parent('Утверждающие', true) | непосредственный родительский элемент текущего элемента вычисления родительский элемент с названием или типом элемента "В процессе" родительский элемента с типом элемента "Проект" для элемента, связанного с текущим замечанием значение атрибута "Утверждающие" из проектной структуры. При этом, поиск атрибута будет выполняться с учетом текущего элемента вычисления |
| Lookup(listName.name) | Возвращает по значению атрибута "Название" name элемент из справочника listName | listName type: строка name type: строка | элемент | Lookup('Статусы документов.Размещено') Lookup('Пользователи.ОТДЕЛ ВЫПУСКА') | элемент с названием "Размещено" из списка "Статусы документов" элемент из списка "Пользователи" с наименованием "ОТДЕЛ ВЫПУСКА" (Пользователь, Функциональная группа, Роль или Подразделение) |
| Path([context], [relativePath], [addSubStructure]) | Функция получает путь элемента из [context] или текущего элемента вычисления с учетом относительного пути [relativePath]. Если [context] не равен текущему элементу вычисления и выставлен флаг [addSubStructure], то к итоговому пути прибавляется остаток пути до текущего элемента вычисления (это остаток пути ("хвост"): "путь текущего элемента вычисления" - "путь context") | context type: элемент relativePath type: строка addSubStructure type: bool | строка | Path() Path(Parent('В процессе'), '../Согласовано', true) Path(Parent('В процессе'), '../../03_РД/Входящие', true) | путь для текущего элемента вычисления Пример: "/ЖК Витро Парк/02_ПД/В процессе/АР-09.24/ИЗМ-1/Test 014.pdf" находит папку с именем "В процессе" в структуре текущего элемента вычисления, заменяет ее в пути на папку "Согласовано" (путь относительный папки "В процессе") и добавляет остаток пути исходного элемента вычисления, который идет после папки "В процессе" Пример: "/ЖК Витро Парк/02_ПД/Согласовано/АР-09.24/ИЗМ-1" Пример аналогичен примеру выше: "/ЖК Витро Парк/02_ПД/В процессе/АР-09.24/ИЗМ-1/Test 014.pdf" находит папку с именем "В процессе" в структуре текущего элемента вычисления, поднимается на 2 уровня выше (путь относительно папки "В процессе") и добавляем остаток пути исходного элемента вычисления, который идет после папки "В процессе" Результат: "/ЖК Витро Парк/03_РД/Входящие/АР-09.24/ИЗМ-1" |
Copy(path, [site], [list], [referenceGuid]) | Копирует текущий элемент вычисления в другое размещение по пути path (см. функцию Path). Параметр [site] - пространство, в которое надо скопировать элемент, если не указано, то копирование будет выполняться в рамках текущего пространства. [list] - проектная библиотека, куда копируется элемент, если параметр не указан, то копирование будет выполняться в рамках текущей библиотеки. Например, если указан параметр [site] и не указан параметр [list], то копирование выполняется в другое пространство, но в библиотеку с тем же именем, как у текущего элемента вычисления. [referenceGuid] - guid связи, которая будет создана между исходным элементов и его копией. | path type: строка site type: элемент list type: строка referenceGuid type: guid/строка | элемент | Copy(Path(Parent('В процессе'), '../Согласовано', true), Lookup('Пространства.Выпуск'), 'Файлы', 'a8bcd156-ffe3-4a96-9fea-d5ba9a557006') | копирует текущий элемент вычисления в библиотеку "Файлы" пространства с именем "Выпуск" по пути (см. описание функции Path) и устанавливает связь с типом "Связь с исходным документом" между исходным элементом и его новой копией |
| Null() | Возвращает значение Null (отсутствие значения). Используется, чтобы сбросить значение определенного атрибута | null | Null() |
Дополнительные примеры: копирование документов (функция Copy)
| Сценарий | Формула |
|---|---|
| Копирование в зеркальную структуру другого пространства (полное повторение структуры хранения) | Copy(Path(Parent()), Lookup('Пространства.Выпуск'), 'Файлы', 'a8bcd156-ffe3-4a96-9fea-d5ba9a557006') |
| Копирование в папку «Согласовано» с воспроизведением структуры папок | Copy(Path(Parent("В процессе"), "../Согласовано", true), Lookup("Пространства.Выпуск"), "Файлы", "a8bcd156-ffe3-4a96-9fea-d5ba9a557006") |
| То же без воспроизведения структуры папок | Copy(Path(Parent("В процессе"), "../Согласовано"), Lookup("Пространства.Выпуск"), "Файлы", "a8bcd156-ffe3-4a96-9fea-d5ba9a557006") |
| Копирование по абсолютному пути | Copy("/ЖК Витро Парк/02_ПД/Согласовано/АР-09.24/Основной_09.24", Lookup("Пространства.Выпуск"), "Файлы", "a8bcd156-ffe3-4a96-9fea-d5ba9a557006") |
Параметры: Lookup('Пространства.Выпуск') — пространство, куда копируется элемент; «Файлы» — библиотека назначения (можно не указывать, если называется так же); GUID a8bcd156-ffe3-4a96-9fea-d5ba9a557006 — тип связи «Связь с исходным документом» между оригиналом и копией (связь видна на вкладке «Связи» обоих документов), его менять не нужно. Для работы примеров требуется версия Vitro MP не ниже 24.1.39.1.
Copy выполняет реальное копирование при каждом вычислении формулы, в том числе при проверке формулы через API (см. Отладка формул).
Атрибуты элемента
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| Id([context]) | Возвращает guid (уникальный идентификатор в системе) элемента [context] или текущего элемента вычисления | context type: элемент | guid | Id() Id(This('Статус процесса')) | guid (уникальный идентификатор в системе) элемента, для которого выполняется вычисление guid значения атрибута "Статус процесса" текущего элемента |
| Author([context]) | Возвращает автора (атрибут "Создал") элемента [context] или текущего элемента вычисления | context type: элемент | элемент из списка "Пользователи" | Author() Field(Author(), 'Почта') | элемент из справочника "Пользователи" автора (атрибут "Создал") элемента, для которого выполняется вычисление адрес почты автора (атрибут "Создал") элемента, для которого выполняется вычисление |
Связи
Связи — элементы специального типа «связь»: в поле source указан текущий элемент, в поле destination (Назначение) — связанный. Тип связи указывается по названию.
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| Ref([context], referenceType) | Возвращает элемент из атрибута "Назначение" первой связи с типом referenceType для элемента [context] или текущего элемента вычисления | context type: элемент referenceType type: строка | элемент | Ref('Связь с замечанием') | связанный элемент по связи с типом 'Связь с замечанием' для текущего элемента вычисления (замечания) |
| Refs([context], referenceType) | Возвращает элемент из атрибута "Назначение" для каждой связи с типом referenceType для элемента [context] или текущего элемента вычисления | context type: элемент referenceType type: строка | список<элемент> | Exists(Refs('Вложение процесса'), 'FileExt() == \'.pdf\'') | существует ли среди вложений текущего процесса, хотя бы одно вложение с расширением 'pdf' |
Работа со списками
В функциях Select, Exists, All, Any второй параметр — строка с формулой, которая вычисляется для каждого элемента списка (в ней This() — элемент списка). Кавычки внутри такой строки экранируются, см. Кавычки и экранирование. В GetList условие отбора — строка-лямбда вида i => ....
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
GetList([context], [expression], [resursive]) по синтаксису запросов в [expression], см. Поиск элементов по структуре | Отбирает дочерние элементы [context]. | context type: элемент expression type: строка resursive type: bool | список<элемент> | Count(GetList(This('list'), Format('i => i.GetValueAsString(\"email\") == \"{0}\" && i.Id != Guid(\"{1}\")', This('Почта'), Id()), true)) > 0 GetList(This(), Format('i => i.ContentTypeId == Guid(\"{0}\") && (new Guid[] {{Guid(\"84124eed-7049-46a8-bac9-a179ff00efe3\"), Guid(\"132fd34b-b757-459e-8191-4a264c91a5b3\")}} ).Contains(i.GetLookupId(\"document_status\"))', '6065b2ae-63e3-44aa-a92d-2d414c30f808'), true) | вернет True, если в списке "Пользователи" уже есть другой пользователь с адресом почты, как у текущего пользователя. Эта функция используется в валидаторе при добавлении новых пользователей, чтобы обеспечить уникальность по полю "Почта" вернет все документы в статусах "Согласовано" и "Согласовано с замечаниями" для текущей папки рекурсивно (на всех уровнях вложенности) |
| Select(list, expression) | Применяет к каждому элементу из списка list, выражение из expression и возвращает полученные результаты в виде списка значений | list type: список объектов с типом элемент/объект с типом "ссылка на элемент списка"/guid expression type: строка | список<объект> | Select(This('Исполнитель', true), 'Field(\'Почта\')') | возвращает список адресов эл. почты исполнителей по текущей задаче рабочего процесса, с учетом раскрытия подразделений\групп (см параметр expandGroup функции This) |
| Merge(value1,value2,...,valueN) | Объединяет значения из value в единый список значений. value может содержать единичное значение, так и быть списком значений | value1,value2,...,valueN type: список<элемент>/объект | список<объект> | Merge(This('Согласующие', true), This('Утверждающие', true)) | возвращает объединенный список согласующих и утверждающих текущего рабочего процесса, с учетом раскрытия подразделений\групп (см параметр expandGroup функции This) |
| Count(list) | Возвращает количество элементов в коллекции list. Если в list содержится какой-либо объект, не коллекция, то функция вернет 1, в противном случае - 0 | list type: список<элемент>/объект | число | Count(Refs('Вложение рабочего процесса')) Count(Parent('Стадия', 'Утверждающие', true)) | количество вложений в рабочем процессе количество утверждающих на стадии текущего элемента вычисления, включая участников функциональных групп/подразделений |
| Contains(list, element) | Если list - строка и element - строка, то проверяет, что подстрока element входит в строку list. list также может быть массивом строк. Если list - список элементов или объектов с типом "ссылка на элемент списка" и element - элемент, объект с типом "ссылка на элемент списка" или guid, то проверяет, что значение в element входит в список list | list type: строка/список<элемент>/список<объект с типом "ссылка на элемент списка"> element type: строка/элемент/объект с типом "ссылка на элемент списка"/guid | bool | Contains(Field(Ref('Вложение процесса'), 'Разрешен запуск процесса согласования', true, false, true), This('Инициатор')) | True, атрибут 'Разрешен запуск процесса согласования' родительской папки вложения процесса содержит инициатора процесса (непосредственно или через группу/подразделение), и False, если не содержит |
| Exists(list, expression) | Применяет к каждому элементу из списка list, выражение из expression, которое должно возвращать булево значение True/False. Если результат вычисления выражения, хотя бы для одного элемента, вернет True, то результат всей функции тоже True | list type: список<элемент>
expression type: строка | bool | Exists(Refs('Вложение процесса'), 'FileExt() == \'.pdf\'') | вернет True, если среди вложений текущего рабочего процесса, есть хотя бы один документ с расширение ".pdf", иначе - False |
| All(list, expression, lookupList) | Возвращает истину (True), если, для КАЖДОГО элемента, из просматриваемого списка list , результат выражения expression, содержится в просматриваемом списке lookupList | list type: список<элемент> expression type: строка lookupList type: список объектов | bool | All(Refs('Вложение процесса'), 'Field(\'Статус документа.Название\')', Field(Ref('Вложение процесса'), 'Статус документа.Название')) || All(Refs('Вложение процесса'), 'Field(\'Статус документа.Название\')', 'Размещено', 'На корректировке') | True, если все вложения текущего процесса имеют одинаковый статус (берем статус первого вложения и сравниваем с ним) или все вложения находятся в статусе "Размещено", либо "На корректировке" |
| Any(list, expression, lookupList) | Возвращает истину (True), если, ХОТЯ БЫ ДЛЯ ОДНОГО элемента, из просматриваемого списка list , результат выражения expression, содержится в просматриваемом списке lookupList | list type: список<элемент> expression type: строка lookupList type: список<объект> | bool | Any(Refs('Вложение процесса'), 'FileExt()', '.dwg','.rvt') | True, если среди вложений текущего процесса есть, хотя бы один, файл с расширением ".dwg" или ".rvt" |
First(list, [defaultValue]) НОВОЕ | Возвращает первый элемент списка list. Если список пуст — значение [defaultValue] (по умолчанию — пустое значение). | list type: список | объект |
| адрес почты первого согласующего (с раскрытием групп) |
Last(list, [defaultValue]) НОВОЕ | Возвращает последний элемент списка list. Если список пуст — значение [defaultValue]. | list type: список | объект |
| последняя часть шифра после разделителя «-» |
GetFieldList([context]) НОВОЕ | Возвращает список атрибутов (элементов системного списка атрибутов), входящих во все типы элементов списка [context]. Контекст должен указывать на список. | context type: список / guid списка | список<элемент> |
| названия всех атрибутов типов элементов списка, в котором находится текущий элемент |
Дополнительный пример: фильтр по значению из структуры
Формирование строки-фильтра для выбора марки раздела в зависимости от стадии проектирования (пустая строка, если стадия не указана):
if(IsNull(Parent("Стадия", "Стадия проектирования.id")), "", Format("i => i.GetLookupId(\"prj_stg_lookup\") == Guid(\"{0}\")", Parent("Стадия", "Стадия проектирования.id")))
Логические функции и проверки
Оператор if и логические операторы описаны в разделе Операторы.
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| IsNull([value]) | Функция возвращает true, если атрибут [value] - null, пустая строка или пустая коллекция (список) элементов, и false, если [value] содержит значение | value type: объект | bool | IsNull(Field(Parent(), 'Ответственный')) | true, если атрибут "Ответственный" родительской папки текущего элемента не заполнен или отсутствует и false, в противном случае |
| IsNotNull([value]) | Функция возвращает true, если атрибут [value] содержит значение, и false, если [value] - null, пустая строка или пустая коллекция (список) элементов | value type: объект | bool | IsNotNull(Field(Parent(), 'Ответственный')) IsNotNull(Parent(Ref('Вложение процесса'), '62_Согласование РД')) | true, если атрибут "Ответственный" родительской папки текущего элемента заполнен и false, если атрибут не заполнен или отсутствует true, если файл/папка, приложенные к процессу, находятся в папке 62_Согласование РД |
| Nvl(value, defaultValue) | Возвращает defaultValue, если значение атрибута value равно null, пустой строке или пустой коллекции (списку) элементов (см. функцию IsNull), иначе возвращает само значение value | value type: объект defaultValue type: объект | объект | Nvl(This('% выполнения'), 0) | Вернет значение атрибута "% выполнения" текущего элемента, если значение указано, в противном случае вернет 0 |
| Switch(checkValue, key1, value1, key2, value2, ..., keyN, valueN) | Проверяет совпадение заданного значения value с одним из ключей key из списка пар "key - value" и вернет соответствующее этому ключу значение value | checkValue type: объект <key, value> type: Dictionary<объект, объект> | объект (того же типа, что и checkValue) | Switch(Field(Ref('Вложение процесса'), 'Статус документа.Название'), 'Размещено', Lookup('Статус процесса.Входной контроль'), 'Проверено', Lookup('Статус процесса.Согласующие'), 'Согласовано', Lookup('Статус процесса.Утверждающие')) | По статусу документа первого вложения возвращаем тот или иной статус процесса, например, чтобы по статусу вложения начать процесс с определенного этапа в автоматизации. 'Размещено', Lookup('Статус процесса.Входной контроль') - первая пара <ключ, значение> 'Проверено', Lookup('Статус процесса.Согласующие') - вторая пара "ключ, значение" 'Согласовано', Lookup('Статус процесса.Утверждающие') - третья пара "ключ, значение" |
| IsNew([context]) | Функция возвращает true в момент создания нового элемента, т.е. до первого сохранения элемента в базу данных, при повторных изменениях функция всегда вернет false | context type: элемент default: текущий элемент вычисления | bool | IsNew() | true, при создании нового элемента и до первого сохранения и false, в противном случае |
| IsStartsWith(str, subStr) | Проверяет, начинается ли указанная строка str с подстроки subStr и возвращает true/false | str type: строка subStr type: строка | bool | IsStartsWith(This('name'), 'Согласование') | true, если в This('name') возвращаемая строка начинается с 'Согласование' |
| IsEndWith(str, subStr) | Проверяет, заканчивается ли указанная строка str заданной подстрокой subStr и возвращает true/false | str type: строка subStr type: строка | bool | IsEndWith(This('Название'), '.docx') | true, если в This('Название') возвращаемая строка заканчивается на '.docx' |
| IsUserAdmin() | Функция возвращает true, если текущий пользователь является администратором, Системной учетной записью или входит в группу "Администраторы системы" | bool | IsUserAdmin() | true, если текущий пользователь является системным администратором, входит в группу "Администраторы системы" или системная учетная запись |
Строковые функции
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| Format(formatString, [value1,value2,...,valueN]) | Возвращает строку formatString, с добавлением параметров [value1, value2,...,valueN] в места подстановки {N} внутри строки formatString, где N - порядковый значения из второго параметра функции. Примечание: функцию Format использовать предпочтительней, чем символ конкатенации строк +. | formatString type: строка value1,value2,...,valueN type: объект | строка | Format('Замечание_{0}_{1}', Field(Ref('Связь с замечанием'), 'Название'), This('ИД')) Format('{0:0000}', 12) | Добавление имени связанного документа и атрибута ИД замечания в места подстановки {0} и {1} строки форматирования Вернет строку '0012' Полный набор форматов соответствует работе функции String.Format() https://msdn.microsoft.com/ru-ru/library/0c899ak8(v=vs.110).aspx |
| Join(separator, values) | Возвращает строку, состоящую из элементов списка значений values, разделенных строкой-разделителем separator | separator type: строка values type: список значений | строка | Join(', ', Select(Parent('Согласующие'), 'Field(\'Название\')')) | объединение в одну строку названий значений из поля "Согласующие" (мультилукап) СХД текущего элемент вычисления, разделенные строкой ", " Пример: "Функциональная группа 1, Администраторы домена" |
| Replace(str, oldValue, newValue) | Заменяет в строке str, все вхождения строки oldValue на строку из newValue | str type: строка value type: строка newValue type: строка | строка | Replace('&status=3', '&', '%26') | заменит символ &, во входной строке, на его код, для использования в url адресах, например |
| Substring(str, [startIndex], [lengthSubstring]) | Возвращает подстроку из исходной строки str, начиная с позиции [startIndex], если указано или от начала строки, если параметр отсутствует и длиной [lengthSubstring], если указано или до конца исходной строки, если параметр отсутствует | str type: строка startIndex type: число substrLength type: число | строка | Substring('Анкор-МПРТ.03', 0, 5) Substring('Анкор-МПРТ.03', 6, 4) | Вернет строку 'Анкор' Вернет строку 'МПРТ' |
| IndexOf(str, value, [occurrence]) | Возвращает индекс (позицию) подстроки value в строке str, начиная с порядкового номера вхождения [occurrence] этой подстроки. Если подстрока не найдена, то функция вернет -1 | str type: строка value type: строка occurrence type: число | число | Format('{0} {1}.{2}.', Substring(This('Название'), 0, IndexOf(Field('Название'), ' ')), Substring(Field('Название'), IndexOf(Field('Название'), ' ', 0) + 1, 1), Substring(Field('Название'), IndexOf(Field('Название'), ' ', 1) + 1, 1)) | ФИО текущего пользователя в сокращенном варианте (Сидоров А.С.) |
| Split(str, separator) | Возвращает список подстрок, разбивая входную строку str строкой-разделителем separator | str type: строка separator type: строка | список<строка> | Split('Архитектор, Главный инженер проекта, Инженер', ', ') | [ |
| Shrink(str, startPartLength, endPartLength, separator) | Сокращает строку str, оставляет из строки указанное количество символов в начале startPartLength и в конце endPartLength, между вставляет указанный разделитель separator | str type: строка startPartLength type: число endPartLength type: число separator type: строка | строка | Shrink(This('Название'), 5, 3, '-') | сократит входную строку Пример: "ЖК Изумрудное -> ЖК Из-ное" |
| TrimEnd(str, subStr) | Функция обрезает строку str с конца, начиная с указанной подстроки subStr и возвращает полученный результат. Можно указать несколько вариантов подстрок в subStr, разделив их символом # | str type: строка subStr type: строка | строка | TrimEnd('тест_РД_ver01','_ver#_rev') TrimEnd(This('Название'), FileExt()) | вернет строку "тест_РД" убирает расширение у текущего элемента |
| Str([value]) | Функция выполняет приведение значения в [value] к строке | value type: объект | строка | Str(Parent('Трудозатраты этап 1')) | Значение атрибута 'Трудозатраты этап 1' (с типом 'Целое число') в СХД текущего элемента в виде строки |
| Hash(str, postfixSymbolCount) | Функция вычисляет хэш от заданной строки str и возвращает указанное количество символов postfixSymbolCount с конца полученного хэша | str type: строка postfixSymbolCount type: число | строка | Hash('4_Управление проектом', 3) | вернет строку '3af' |
| Translit(str) * таблица | Функция выполняет транслитерацию строки str (заменяет символы кириллицы на символы/комбинацию символов латинского алфавита). Цифры и пробелы попадают в выходную строку, как есть. Все другие символы заменяются на знак нижнего подчеркивания "_". Таблицу соответствия см. внизу статьи | str type: строка | строка | Translit('В12345/555Д') Translit('Плита перекрытия') | строка "V12345_555D" строка "Plita perekrytiia" |
| FileExt([context]) | Возвращает расширение из атрибута "Название" элемента [context] или текущего элемента вычисления. Если расширения не найдено, то функция вернет пустую строку. | context type: элемент | строка | FileExt() FileExt(Ref('Связь с замечанием')) | расширение текущего элемента вычисления расширение элемента, к которому оставлено замечание |
Дата и время
Даты хранятся и возвращаются в UTC. При указании параметра формата значение преобразуется в строку (с пересчётом в часовой пояс сервера). Форматы — стандартные строки формата .NET: dd.MM.yyyy, HH:mm, MMMM и т.д.
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| Date([date], [format]) | Возвращает дату-время [date] в заданном формате [format], но без учета времени. Если не задано значение даты-времени, будет возвращено текущее значение. Примечание: При указании формата [format], значение даты/времени будет пересчитано из UTC в часовой пояс сервера. | date type: дата-время/строка format type: строка. default: "" | дата-время/строка | Date() | значение в формате дата-время (UTC), но без учета значения времени (часы/минуты/секунды) текущих суток. Пример: "2025-01-31T00:00:00Z" - строковое представление типа дата-время (только дата) |
| DateTime([date], [format]) | Возвращает дату-время [date] в заданном формате [format]. Если не задано значение даты-времени, будет возвращено текущее значение | date type: дата-время/строка format type: строка | дата-время/строка | DateTime(Field(Parent(), 'Время начала'), 'dd.MM.yyyy') | значение атрибута "Время начала" родительской папки элемента в указанном формате |
| Time([date], [format]) | Возвращает дату-время [date] в заданном формате [format], но без учета даты. Если не задано значение даты-времени, будет возвращено текущее значение | date type: дата-время/строка format type: строка. default: "" | дата-время/строка | Time() | значение в формате дата-время (UTC), но без учета значения даты (дни/месяцы/годы) текущих суток. Пример: "07:26:17.6569781" - строковое представление типа дата-время (только время) |
| AddDay([date], [incStepValue], [format]) | Возвращает дату [date], увеличенную на заданное количество дней [incStepValue]. Если указан параметр [format], то возвращает дату в виде строки | date type: дата-время/строка incStepValue type: число format type: строка. default: "" | дата-время/строка | AddDay(This('Created'), 1, 'dd.MM.yyyy') AddDay(-10, 'dd.MM.yyyy') | дата создания данного элемента, увеличенная на один день, в формате dd.MM.yyyy текущая дата-время минус 10 дней, в формате dd.MM.yyyy |
| AddMonth([date], [incStepValue], [format]) | Возвращает дату [date], увеличенную на заданное количество месяцев [incStepValue]. Если указан параметр [format], то возвращает дату в виде строки | date type: дата-время/строка incStepValue type: число format type: строка. default: "" | дата-время/строка | AddMonth(Field(Parent('Раздел'),'Created'), 3) AddMonth(3, 'MMMM') | дата создания родительского элемента с типом контента 'Раздел', увеличенная на 3 месяца название месяца через 3 месяца от текущей даты |
| AddYear([date], [incStepValue], [format]) | Возвращает дату [date], увеличенную на заданное количество лет [incStepValue]. Если указан параметр [format], то возвращает дату в виде строки | date type: дата-время/строка incStepValue type: число format type: строка. default: "" | дата-время/строка | AddYear(Field(Parent(), 'Created'), 2, 'yyyy') | дата создания родительской папки, увеличенная на 2 года, в формате год |
| AddWorkingTime([date], offset, [inWorkingHours], [workInterval]) | Прибавляет к [date] рабочее время offset, рассчитанное в рабочих днях [inWorkingHours] - false, или часах [inWorkingHours] - true, с учетом интервалов рабочих часов в сутках [workInterval]. Параметр [workInterval] имеет значение по умолчанию '9,13,14,18' - строка, которая содержит массив из 4-х чисел, разделенных запятой или точкой с запятой. Первая пара чисел рабочее время до обеденного перерыва, вторая - рабочее время после перерыва. Значение параметра offset прибавляется к указанной дате с учетом производственного календаря (список "Производственный календарь" в ЦА), в котором можно указать даты праздничных дней и рабочих дней, выпадающих на выходной. Обычные выходные дни (суббота и воскресенье) в календаре указывать на надо. Если рабочий день попадает на выходной, то у записи календарь надо выставить флаг "Рабочий день". Примечание: Все расчеты дат в этой функции выполняются в формате UTC. | date type: дата-время/строка offset type: число inWorkingHours type: bool workInterval type: строка | дата-время | AddWorkingTime(This('start_date_fact'), 5, true, '6,10,11,15') | прибавляет к значению атрибута "Дата начала (Факт)" 5 рабочих часов. Интервал рабочих часов в сутках с 6 до 10 часов и с 11 до 15 часов |
DateTimeInterval(mode, [offset], [unit]) НОВОЕ | Возвращает интервал дат (объект с границами | mode type: число — режим: | интервал (From, To) в UTC |
| с понедельника текущей недели до понедельника следующей от сегодняшнего дня до конца седьмого дня от сегодня |
Математические функции
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| Sum(value1,value2,...,valueN) | Возвращает арифметическую сумму параметров | value1,value2,...,valueN type: число | число | Sum(1, 2.6, 5) Sum(Select(GetList('966e62c5-a803-49a0-a1be-e680d130c481', 'i => i.ContentTypeId == Guid(\"540ff572-4a29-4d8e-8dfb-8eda093c583a\")'), 'This(\"complete_percent\")')) | 8.6 Вернет сумму значений атрибута "% выполнения" у папок с типом "Проект" в корне библиотеки |
| Min(value1,value2,...,valueN) | Возвращает минимальное значение из набора параметров | value1,value2,...,valueN type: число | число | Min(1, 2.6, 5) | 1 |
| Max(value1,value2,...,valueN) | Возвращает максимальное значение из набора параметров | value1,value2,...,valueN type: число | число | Max(1, 2.6, 5) Min(Select(GetList(Id(), 'i => i.ContentTypeId == Guid(\"64a15f4c-083e-420b-b54e-fc75d44f31b7\")'), 'This(\"percent_complete\")')) | 5 Вернет минимальное из значений атрибута "% выполнения" у папок с типом "Стадия" в папке проекта |
| Inc(listName.fieldName.id, step) | Получает значение атрибута fieldName строки с номером id (атрибут "ИД") из списка счётчиков listName (в типовой конфигурации это справочник "Счётчики") и инкрементирует (увеличивает) это значение на step. Полученное значение также сохраняется в fieldName | listName type: строка fieldName type: строка id type: число step type: число | число | Inc('Счётчики.Счётчик.2', 1) | Возвращает значение атрибута "Счётчик" элемента с ИД=2 из списка "Счётчики" увеличенного на 1. Данная функция служит для реализации Счётчика, например, для автоматической нумерации каждого добавляемого в папку документа. |
| Pow(base, factor) | Возводит в заданное base число степень factor | base type: число factor type: число | число | Pow(2, 3) | 23 = 8. |
| Sqrt(value) | Возвращает корень квадратный из заданного числа | value type: число | число | Sqrt(16) | 4 |
Встроенные математические функции движка
Помимо функций системы, в формулах доступны встроенные функции движка NCalc (имена также чувствительны к регистру):
| Функция | Назначение | Пример |
|---|---|---|
Abs(x) | модуль числа | Abs(-5) → 5 |
Round(x, digits) | округление до digits знаков. По умолчанию используется «банковское» округление: половина округляется к ближайшему чётному (Round(2.5, 0) → 2). Проверяйте граничные значения | Round(3.14159, 2) → 3.14 |
Floor(x) / Ceiling(x) | округление вниз / вверх до целого | Ceiling(2.1) → 3 |
Truncate(x) | отбрасывание дробной части | Truncate(-2.7) → -2 |
Sign(x) | знак числа: -1, 0 или 1 | Sign(-3) → -1 |
Pow(x, y) / Sqrt(x) | степень / квадратный корень (описаны выше) | Pow(2, 3) → 8 |
Exp(x), Log(x, base), Log10(x) | экспонента и логарифмы | Log10(1000) → 3 |
in(value, v1, v2, ...) | true, если value совпадает с одним из перечисленных значений | in(This('Статус документа.Название'), 'Согласовано', 'Отклонено') |
Преобразование типов
Преобразование в строку — функция Str.
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| ParseBool(value) | Преобразует строки 'true'/'false' (регистр не важен), '0'/'1', числа 0/1 в булево значение True/False | value type: строка/число | bool | ParseBool('true') ParseBool('False') ParseBool('0') ParseBool(1) | True False False True |
| ParseDateTime(value) | Преобразует строку value с указанием даты и времени в формат DateTime. Если указать только дату без времени, то значение времени будет установлено в 00:00:00. Если указать только время, без даты, то будет установлена текущая дата | value type: строка | дата-время | ParseDateTime('20.05.2024 10:50') ParseDateTime('20/06/2024') | "2024-05-20T10:50:00" в формате DateTime "2024-06-20T00:00:00" в формате DateTime |
| ParseFloat(value) | Преобразует строку value в число с плавающей запятой. Целя и дробная части в строке должны быть разделены символом точки или запятой | value type: строка | число с плавающей точкой | ParseFloat('12,05') | 12.05 |
Организационно-штатная структура
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| User() | Возвращает значение элемента из списка "Пользователи" для текущего пользователя, под контекстом которого выполняется вычисление | элемент из списка "Пользователи" | Field(User(), 'Почта') | адрес почты текущего пользователя в системе, под контекстом которого выполняется вычисление | |
SubordinateUserList() НОВОЕ | Возвращает список пользователей из подразделений, руководителем которых является текущий пользователь (включая вложенные подразделения), без повторов. | — | список<элемент> с типом элемента «Пользователь» |
| true, если исполнитель — подчинённый текущего пользователя |
SubstitutedUserList([includeSelf], [mode]) НОВОЕ | Возвращает пользователей, которых замещает текущий пользователь. Флаг [includeSelf] добавляет в результат самого пользователя. В режиме [mode] = | includeSelf type: bool, default: false | список<элемент> с типом элемента «Пользователь» (в режиме Department — элементы-подразделения) |
| true, если исполнитель — текущий пользователь или пользователь, которого он замещает |
Конфигурация
| Функция | Описание | Входные параметры | Результат (тип) | Пример | Результат примера |
|---|---|---|---|---|---|
| Cfg(key) | Возвращает значение элемента из списка "Конфигурация" по ключу key (значение атрибута "Системное имя") | key type: строка | возвращаемое значение соответствует типу элемента, найденного по ключу (строка, число, флаг, картинка) | Cfg('Site.PortalUrl') | значение элемента конфигурации по пути: "Общие настройки" → "Адрес портала" |
Таблица транслитерации (функция Translit)
| а | б | в | г | д | е | ё | ж | з | и | й | к | л | м | н | о | п | р | с | т | у | ф | х | ц | ч | ш | щ | ъ | ы | ь | э | ю | я |
| a | b | v | g | d | e | e | zh | z | i | i | k | l | m | n | o | p | r | s | t | u | f | kh | tc | ch | sh | shch | _ | y | _ | e | iu | ia |