Правила валидации атрибутов

Правила валидации атрибутов#

Общие сведения#

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

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

Для валидации атрибутов доступны два типа правил:

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

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

Общий порядок настройки

Настройка выполняется в следующем порядке:

  1. Откройте Настройки системы > Настройка и сервисы > Правила проверки атрибутов.

  2. Создайте новое правило или откройте существующее.

  3. В карточке правила выберите тип правила, задайте основные свойства и укажите JEXL-код.

  4. Перейдите в интерфейс настройки атрибута и назначьте на него правило.

Правила назначаются на атрибуты в тех интерфейсах, где эти атрибуты создаются или настраиваются. Подробнее см. в разделе Где настраиваются правила.

Примечание

В системе существуют два механизма контроля данных: правила валидации атрибутов и конструктор проверок и изменений (BTS Check).

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

BTS Check используется для проверки объекта, его частей и связанных данных перед выполнением действия, операции или смены состояния.

Если нужно проверить конкретное поле — используйте валидацию атрибутов.
Если нужно проверить объект или бизнес-сценарий целиком — используйте BTS Check.

Карточка правила#

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

При открытии карточки правила становятся доступны его свойства, параметры проверки и JEXL-код:

  • код правила;

  • наименование правила;

  • поле Тип объекта, которое определяет вариант использования правила:

    • Проверка значений атрибутов;

    • Ограничение выбора атрибутов;

  • вкладка Параметры проверки;

  • вкладка Свойства.

JEXL-код правила задается в правой части карточки.

Параметры проверки#

На вкладке Параметры проверки задаются параметры, которые используются в логике правила.

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

Логика работы следующая:

  • в карточке правила задается JEXL-код правила, который описывает общую логику проверки;

  • на вкладке Параметры проверки объявляются параметры, которые используются в этом коде;

  • при назначении правила на атрибут значения параметров задаются в том же окне, где это правило навешивается на атрибут;

  • если для параметра установлен признак Jexl-скрипт, его значение не задается вручную, а вычисляется с помощью отдельного JEXL-скрипта перед выполнением правила;

  • при выполнении правила JEXL-код правила работает уже с учетом значений этих параметров.

Для каждого параметра указывается:

  • мнемокод, который используется в JEXL-коде правила;

  • тип данных и тип атрибута;

  • при необходимости — ссылочный класс;

  • признак Jexl-скрипт.

Параметр может быть:

  • задан напрямую значением;

  • задан ссылкой;

  • вычисляемым, если установлен признак Jexl-скрипт.

Пример использования параметров проверки#

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

Для этого создается правило типа Проверка значений атрибутов с JEXL-кодом:

value >= nMin && value <= nMax

Далее на вкладке Параметры проверки создаются параметры:

  • nMin — минимальное значение;

  • nMax — максимальное значение.

После этого правило назначается на атрибут. Значения параметров задаются в том же окне, где правило навешивается на этот атрибут.

Например:

  • для одного атрибута: nMin = 0, nMax = 100;

  • для другого: nMin = 10, nMax = 1000.

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

Свойства#

На вкладке Свойства задаются:

  • Текст ошибки
    отображается пользователю при нарушении правила. В тексте можно использовать параметры проверки в виде $мнемокод_параметра.

  • Событие выполнения
    определяет, в какой момент выполняется правило.

  • Флаг Не используется
    отключает правило на всех атрибутах и объектах.

  • Дата окончания использования проверки
    ограничивает срок действия правила.

Событие выполнения может принимать следующие значения:

  • На установку значения характеристики
    Проверка выполняется после завершения редактирования.

  • На завершение редактирования объекта
    Проверка выполняется на событии afterEdit, после сохранения.

Скрипты правила и параметров#

JEXL-код самого правила задается в правой части карточки правила.

Если для параметра установлен признак Jexl-скрипт, его значение вычисляется с помощью отдельного JEXL-скрипта перед выполнением правила.

Совет

  • В скрипте правила алиас таблицы можно заменять символом &. Например, вместо t.idObjectType лучше писать &idObjectType.

  • В контексте JEXL-скриптов правил всех типов и их параметров доступна ропа объекта, которому принадлежит атрибут, под алиасом rop.

Типы проверок#

Проверка значений атрибутов#

Для проверки значения задается условие в виде JEXL-скрипта. Система выполняет этот скрипт для выбранного атрибута.

  • Если скрипт возвращает true, проверка считается пройденной.

  • Если скрипт возвращает false, система выводит сообщение об ошибке и останавливает выполнение действия.

Сообщение об ошибке задается в самом правиле. В тексте сообщения можно использовать параметры проверки.

Ограничение выбора атрибутов#

Ограничивает список доступных значений для ссылочных атрибутов.

Для ограничения выбора задается JEXL-скрипт, который возвращает SQL-условие. Это условие применяется при формировании списка значений ссылочного атрибута.

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

Примечание

В контексте JEXL-скрипта доступен объект, которому принадлежит атрибут, по алиасу rop.

Внутренняя логика работы ограничения значений

JEXL-скрипт должен возвращать SQL-условие в виде строки. Это условие вставляется в WHERE финального запроса к таблице ссылочного класса.

Пример скрипта:

if (nNum < 5) { "upper(&sname) like '%БОЛТ%'" } else { "upper(&sname) like '%ВИНТ%'" }

При nNum = 7 результат: "upper(&sname) like '%ВИНТ%'".

Это условие будет использовано в SQL: SELECT * FROM (SELECT * FROM Bs_Goods) t WHERE upper(t.sname) like '%ВИНТ%'

Важно:

  • символ & заменяется на алиас таблицы (t.sName, g.sCaption и т.п.);

  • возвращенная строка становится частью условия WHERE;

  • правила не работают с выборками, сформированными объектным запросом — такие источники не поддерживают дополнительные SQL-условия.

Ограничивающие атрибуты#

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

Это атрибуты, от значения которых зависит список доступных значений в других атрибутах. Если значение такого атрибута изменяется, система повторно проверяет зависимые атрибуты.

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

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

Ограничивающим атрибутом может быть:

  • атрибут самого объекта;

  • атрибут его родителя, если зависимый атрибут находится в коллекции.

Типы настройки:

  • на типе объекта;

  • на группе;

  • на шаблоне атрибутов типа объекта.

Примечание

Обнуление происходит через стандартные сеттеры:

  • Для атрибутов БД — сеттеры в Api класса.

  • Для JSON-характеристик — JObjectAttrApi.setObjAttrValue(rop: AnyRop, idpAttr: NLong, pValue: Any).

Где настраиваются правила#

Правила можно назначать на атрибуты на уровне типа объекта, группы, шаблона, универсальной характеристики и параметра отчета.

На типе объекта
Путь: Сущности > Типы объектов или Сущности > Классы

Правила можно задавать:

  • на детализации Объектные характеристики типа объекта (УХ, ОХ, Базовые) — Btk_ObjectAttrByObjectType;

  • на детализации Управление атрибутами (ОХ, Базовые) — Btk_ObjectTypeAttrRules.

Примечание

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

Замещенные таким образом правила отмечены желтой стрелкой. В подсказке при наведении на нее указано, каким правилом было замещено данное.

Примечание

Для атрибутов класса правила назначаются не на вкладке Атрибуты, а через механизмы настройки атрибутов на уровне типов объектов.

На атрибуте группы
Путь: [редактирование группы] > Атрибуты в группе

Примечание

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

На атрибуте шаблона
Путь: Настройка и сервисы > Шаблоны характеристик > Атрибуты шаблона

На универсальной характеристике
Путь: Сущности > Универсальные характеристики

На параметре отчета
Только для правил ограничения значений.
Путь: Отчеты > Настройка отчетных форм > Параметры отчета

Примеры#

Пример проверки значения#

Общая логика проверки:

  1. Задается условие.

  2. Система выполняет проверку.

  3. При нарушении выводится ошибка.

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

value >= 0

Пример ограничения выбора по региону#

В классе SupplyRequest (Заявка на поставку) есть атрибут idWarehouse, ссылающийся на склад. Необходимо ограничить выбор складов по региону, но информация о регионе в разных объектах хранится по-разному:

  1. в атрибуте idRegion самого объекта;

  2. в связанном объекте контрагента (Bs_Contras), у которого есть свой idRegion.

Чтобы наложить такое ограничение, выполните следующие действия:

  • Создайте одно универсальное правило, которое будет использоваться для всех объектов.

JEXL-скрипт правила:

"&idRegion = " + regionId

  • Добавьте к нему параметр Регион и задайте ему мнемокод regionId.

  • Наложите правило на нужные атрибуты объектов.

  • Установите для каждого объекта соответствующий JEXL-скрипт параметра правила.

Если регион хранится в текущем объекте Заявка на поставку (SupplyRequest), значение можно получить из ропы объекта:

rop.idRegion;

Если регион определяется через контрагента Bs_Contras:

val ropContras = Bs_ContrasApi().load(rop.idContras);
ropContras.idRegion;

Пример ограничения выбора по значению атрибута#

Цель: для атрибута idGoods (класс RplTst_AllDbTypes) показывать только болты или винты в зависимости от значения nNum.

JEXL-скрипт правила:

if (nNum < 5) {
  "upper(&sname) like '%БОЛТ%'"
} else {
  "upper(&sname) like '%ВИНТ%'"
}

JEXL-скрипт параметра nNum:

RplTst_AllDbTypesApi.getAttrValue(rop, "nNumber");

Особенности работы#

Коллизии правил#

Коллизии правил

Одно и то же правило может быть задано на нескольких уровнях: тип, группа, шаблон и т.д. Если на сущности есть хотя бы одно правило на Btk_ObjectTypeAttrRules, остальные игнорируются.

Приоритет:

  1. Btk_ObjectTypeAttrRules (Управление атрибутами);

  2. остальные уровни.

Правило более высокого уровня заменяет правило нижнего уровня. Правила выполняются в порядке очередности.

Кэширование правил#

Кэширование правил

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

Сервис > Управление решением > Очистить все кэши

Содержание