Правила данных в домене

Этот раздел описывает правила данных в домене.

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

  • ограничивают возможные операции с атрибутами и связями сущностей;

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

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

  • условие, которое должно выполняться;

  • параметр для атрибутов или связей, соответствующих условию.

Ознакомьтесь с правилами нотации в схеме домена. Это позволит присваивать корректные названия создаваемым элементам схемы. Эти названия будут отображаться в интерфейсе системы.

Логика работы правил данных

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

Например, если для атрибута установлено правило kind: required, а его значение не заполнено, проверка данных для атрибута не выполняется.

  • Правила данных могут лишь дополнять и усиливать существующие ограничения и правила атрибутов, но не ослаблять их.

    Например, если для атрибута установлено readonly: true, в правиле данных нельзя сделать этот атрибут редактируемым.

  • В правиле можно использовать все атрибуты сущности, включая системные, а также атрибуты типов Workflow и Enum.

    • Для атрибута типа Array объектом правила может быть как весь массив, так и конкретные элементы массива.

    • Для атрибута типа Table объектом правила может быть как вся таблица, так и конкретные столбцы таблицы.

  • Правила данных поддерживают наследование:

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

    • Если в правиле указана ссылка на сущность Родителя, правило применяется только для объектов Родителя.

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

Структура поля dataRules

Путь в схеме: dataRules[]

Поле dataRules представляет собой массив записей правил данных для атрибутов сущности. Каждый элемент массива имеет следующую структуру:

Поле Обязательность и значение по умолчанию Тип данных Описание

id

да

Data ID

Уникальный идентификатор правила.

name

да

строка

Название правила.

description

нет (по умолчанию — пустая строка)

строка

Описание правила.

target

да

перечисление

Тип объекта правила. Допустимые значения:

  • entity — сущность, ее атрибуты и связи в контексте этой сущности;

  • entityAttribute — элементы массива или атрибуты таблицы;

  • linkage — связь и ее атрибуты.

entity

да (при target: entity или entityAttribute)

Data ID Ref

Ссылка на идентификатор сущности, к которой применяется правило. Объектом может быть сущность, расположенная как в текущем, так и в другом домене.

linkage

да (при target: linkage)

Data ID Ref

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

attribute

да (при target: entityAttribute)

Data ID Ref

Ссылка на идентификатор атрибута. Доступно, если объектом правила определен атрибут с типом Table или Array.

condition

да

логическое или RQL-выражение

Условие, при истинности которого применяется заданное правило:

  • Если эффект применяется всегда, указывается значение true.

  • Если эффект применяется лишь в определенных случаях, указывается RQL-выражение.

Ознакомьтесь с описанием поля condition.

rule

да

объект

Описание действия правила.

Ознакомьтесь с описанием поля rule.

message

нет (по умолчанию — пустая строка)

строка

Сообщение, отображаемое в случае ошибки выполнения правила. Доступно, если значение поля effect отличается от default.

Ознакомьтесь с описанием поля message.

help

нет (по умолчанию — пустая строка)

строка

Сообщение, отображаемое при наведении курсора на иконку справки. Доступно, если значение поля effect отличается от hidden.

Ознакомьтесь с описанием поля help.

Условие правила данных (condition)

Путь в схеме: dataRules[].condition

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

  • Всегда истина (true) — правило применяется безусловно.

  • RQL-выражение — правило применяется, только если выражение возвращает значение true.

В рамках RQL-выражения доступно обращение к следующим данным:

  • данные сущностей из текущего и других доменов:

    • идентификатор сущности;

    • значения атрибутов сущности, в том числе значения элементов массивов и перечислений, атрибутов таблиц, этапов рабочих процессов и метаданных файлов.

  • данные связей при использовании стороны связи с одним объектом (1-1, 1-N):

    • атрибуты связи;

    • идентификатор связанной сущности;

    • атрибуты связанной сущности.

  • данные окружения:

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

    • текущие дата и время, а также их составляющие.

В выражении можно применять операторы сравнения и специальные функции. Подробный перечень доступных операторов, функций и псевдонимов приведен в руководстве по RQL.

Описание действия правила данных (rule)

Путь в схеме: dataRules[].rule

Поле имеет следующую структуру:

Поле Обязательность и значение по умолчанию Тип данных Описание

effect

да

перечисление

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

Ознакомьтесь с доступными значениями.

attributes

да

массив

Определения значений для объектов правила.

Ознакомьтесь с описанием поля attributes.

nested

да (для Table и Array)

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

Ознакомьтесь с описанием поля nested.

объект

linkages

нет

массив

Определения значений для связей. Доступно при target: entity.

Ознакомьтесь с описанием поля linkages.

Действие над атрибутом (effect)

Путь в схеме: dataRules[].rule.effect

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

  • hidden — скрыть указанные атрибуты для отображения в пользовательском интерфейсе и API.

  • readonly — сделать поле существующего объекта недоступным для редактирования.

  • required — сделать поле обязательным для заполнения.

  • default — использовать значение по умолчанию.

  • allowed — проверить значения на допустимость или предоставить для выбора только допустимые значения.

Скрытие (effect: hidden)

Эффект hidden скрывает виджеты атрибутов и связей, указанных в правиле:

  • В таблице списка объектов скрываются значения в столбцах, соответствующих условию правила.

  • В карточке и окнах объекта скрывается объект правила.

    Заголовок группы виджетов остается видимым, даже если согласно правилу скрыты все виджеты в группе.

  • При запросе через API данные об объекте правила не передаются.

Не рекомендуется применять эффект hidden вместе с эффектами readonly, required или default к одному объекту правила. Такая ситуация вызовет циклическую зависимость, которую можно будет исправить только через изменение в базе данных.

Для атрибута типа Array с помощью параметра можно скрыть как весь массив, так и конкретные элементы:

  • Если объект правила — атрибут-массив, скрывается весь атрибут.

  • Если объект правила — элементы массива, и в поле item указано значение '*', скрываются все элементы.

  • Если объект правила — элементы массива, и в поле item указан индекс элемента, скрывается указанный элемент.

Для атрибута типа Table с помощью параметра можно скрыть как всю таблицу, так и конкретный столбец:

  • Если объект правила — таблица, скрывается вся таблица.

  • Если объект правила — столбец таблицы, и для условия используется атрибут сущности, столбец скрывается во всех строках таблицы.

  • Если объект правила — столбец таблицы, и для условия используется другой столбец таблицы, значение столбца скрывается в строках таблицы, соответствующих условию. Сами столбцы при этом не скрываются.

Примеры скрытия значений в атрибуте-таблице
Условие с атрибутом сущности, объект правила — таблица
dataRules:
  - id: hidden_usersTable
    name: Скрытие таблицы.
    target: entity
    entity: Incident
    condition: !rql incidentTime < CAST('10:00', 'Time')
    rule:
    effect: hidden
    # Правило применяется к отдельным атрибутам таблицы.
    attributes:
      - attribute: incidentArtifactsTable

Правило hidden_usersTable применяется для всех строк таблицы. Таким образом, если значение атрибута incidentTime текущего объекта меньше 10.00, его атрибут-таблица incidentArtifactsTable скрывается полностью.

Условие с атрибутом сущности, объект правила — атрибут таблицы
dataRules:
  - id: hidden_usersAttrInTable
    name: Скрытие столбцов с пользовательскими атрибутами в таблице
    target: entityAttribute
    entity: Incident
    attribute: incidentArtifactsTable
    # В условии используется атрибут сущности, а не атрибут атрибута-таблицы.
    condition: !rql incidentTime < CAST('10:00', 'Time')
    rule:
      effect: hidden
      # Правило применяется к отдельным атрибутам таблицы.
      nested:
        type: table
        attributes:
          - attribute: incidentArtifactsResp
          - attribute: incidentArtifactsReport

Правило hidden_usersAttrInTable применяется для всех строк таблицы. Таким образом, если значение атрибута incidentTime текущего объекта меньше 10.00, в таблице полностью скрываются столбцы incidentArtifactsResp и incidentArtifactsReport.

Условие с атрибутом атрибута-таблицы
dataRules:
  - id: required_baseAttrInTableRow
    name: Обязательность атрибутов для конкретной строки таблицы
    target: entityAttribute
    entity: Incident
    attribute: incidentArtifactsTable
    # Условие для конкретной строки должно быть с указанием атрибута таблицы. Обращение к атрибуту таблицы через @row.
    condition: !rql |
      @row.incidentArtifactStatus = 'REGISTERED'
    rule:
      effect: required
      nested:
        type: table
        attributes:
          - attribute: incidentArtifactsResp
          - attribute: incidentArtifactsReport

Правило required_baseAttrInTableRow применяется только к ячейкам строк, для которых выполняется условие. Таким образом, если значение атрибута incidentArtifactStatus в текущей строке таблицы равно "REGISTERED", значения столбцов incidentArtifactsResp и incidentArtifactsReport в ячейках этой строки скрываются. Сами столбцы при этом отображаются в таблице.

Эффект hidden не поддерживается для атрибутов с типом Counter и RQL.
Если нужно скрыть часть значений атрибута типа Enum, используйте эффект default

Запрет редактирования (effect: readonly)

Эффект readonly запрещает редактирование атрибутов и связей, указанных в правиле:

  • Значение заполняется один раз, при создании объекта.

  • Иконки и опции редактирования скрываются в компактном и полноэкранном представлениях, а также в окне редактирования. Если объект правила — атрибут типа Table или Array, в редакторах таблиц и массивов скрываются иконки и опции редактирования.

  • При запросе через API данные об объекте правила не редактируются.

Не рекомендуется применять эффекты readonly и hidden к одному объекту правила. Такая ситуация вызовет циклическую зависимость, которую можно будет исправить только через изменение в базе данных.

Для атрибута типа Array параметр можно применять как ко всему массиву, так и к конкретному элементу:

  • Если объект правила — атрибут-массив, массив становится недоступным для редактирования. Опции добавления, удаления и изменения элементов массива скрываются.

  • Если объект правила — элементы массива, и в поле item указано значение '*', все текущие элементы массива становятся нередактируемыми: опции изменения и удаления элементов скрываются. При этом можно добавлять новые элементы.

  • Если объект правила — элементы массива, и в поле item указан индекс элемента, нередактируемым становится указанный элемент: опции изменения и удаления элементов скрываются.

Примеры нередактируемых значений в массиве
Объект правила — атрибут-массив
dataRules:
  - id: readonly_ArrayIpAddress
    name: Нередактируемость массива
    target: entity
    entity: Incident
    condition: !rql attributesString = 'special'
    message: Значения недоступны для редактирования.
    rule:
      effect: readonly
      attributes:
        - attribute: IpAddress

Правило readonly_ArrayIpAddress применяется для массива в целом. Таким образом, в массиве нельзя изменять существующие элементы и добавлять новые.

Объект правила — все элементы массива
dataRules:
  - id: readonly_itemArrayIpAddress
    name: Нередактируемость всех элементов массива
    target: entityAttribute
    entity: Incident
    attribute: IpAddress
    condition: !rql attributesString = 'special'
    message: Элементы недоступны для редактирования.
    rule:
      effect: readonly
      nested:
        type: array
        items:
          # Применение ко всем элементам массива.
          - item: '*'

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

Объект правила — конкретный элемент массива
dataRules:
  - id: readonly_itemArrayIpAddress_first
    name: Нередактируемость конкретных элементов массива
    target: entityAttribute
    entity: Incident
    attribute: IpAddress
    condition: !rql attributesString = 'special'
    message: Элементы недоступны для редактирования.
    rule:
      effect: readonly
      nested:
        type: array
        items:
          # Применение к конкретному элементу массива -- первому.
          - item: 0
          ...

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

Для атрибута типа Table параметр можно применять как ко всей таблице, так и к конкретному столбцу:

  • Если объект правила — таблица, атрибут таблицы становится недоступными для редактирования.

  • Если объект правила — столбец таблицы, и для условия используется атрибут сущности, столбец становится нередактируемым во всех строках таблицы.

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

Эффект readonly не поддерживается для атрибутов с типами Counter, Identifier, и RQL, а также для системных атрибутов, помимо organizationId.

Обязательность (effect: required)

Эффект required делает обязательным заполнение атрибутов или установление связей, указанных в правиле. При запросе через API необходимо заполнить атрибуты или связи сущности, указанные в правиле.

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

Не рекомендуется применять эффекты required и hidden к одному объекту правила. Если обязательный атрибут будет скрыт и недоступен для заполнения, это приведет к ошибке создания или редактирования объекта.

Для атрибута типа Array параметр можно применять как ко всему массиву, так и к конкретному элементу массива:

  • Если объект правила — массив, необходимо добавить хотя бы один элемент массива.

  • Если объект правила — элементы массива, указанные в правиле элементы становятся обязательными.

Для атрибута типа Table параметр можно применять как ко всей таблице, так и к конкретному столбцу:

  • Если объект правила — таблица, необходимо добавить хотя бы одну строку таблицы.

  • Если объект правила — столбец таблицы, и для условия используется атрибут сущности, столбец обязателен во всех строках таблицы.

  • Если объект правила — столбец таблицы, и для условия используется другой столбец таблицы, столбец обязателен в строках таблицы, соответствующих условию.

Эффект required не поддерживается для атрибутов с типами Counter, Identifier и RQL, а также для системных атрибутов, помимо organizationId.

Значение по умолчанию (effect: default)

Эффект default подставляет в объект правила данных значение по умолчанию, указанное в блоке values, если пользователь не указал иное значение.

Если в условии правила данных используются данные связи, эффект не применяется при редактировании в компактном представлении.

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

Пример правила данных 
dataRules:
  - id: dataR_link
    name: Подстановка значений по умолчанию
    target: entity
    entity: Incident
    condition: !rql |
              select(count(id), from('current', @linkages_users, @links), where(eq(@links.side1, @doc.id))) > 0
    rule:
      effect: default
      attributes:
        - attribute: responsible
          value: 'Ответственный назначен'

Пользователь создает связь linkages_users в компактном представлении объекта. Значение атрибута responsible не заполняется, пока пользователь не откроет форму редактирования объекта.

Блок values содержит массив объектов "объект правила — значение". Объект должен быть уникален в рамках конкретного правила данных.

Значение по умолчанию можно задать следующими способами:

  • Указать статическое значение, соответствующее типу данных атрибута.

  • Задать RQL-выражение, которое возвращает значение, соответствующее типу данных атрибута.

Чтобы сгенерировать значение по умолчанию для атрибута типа Uuid, используйте функцию gen_random_uuid:

expression: !rql SELECT gen_random_uuid()
Эффект default не поддерживается для связей, системных атрибутов и атрибутов с типами Attachment, Counter, Identifier, Reference, RQL Table и Workflow.

Проверка допустимости (effect: allowed)

Эффект allowed проверяет значение на допустимость:

  • Для атрибутов типа Enum и Workflow: отфильтровывает список значений для выбора согласно выражению, заданному в поле expression.

    • При создании объекта значение атрибута типа Workflow всегда будет initial, эффект allowed не применяется.

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

  • Проверяет введенное значение на допустимость согласно ограничению, заданному в поле constraint.

    Если значение не задано пользователем, оно равно NULL. Поэтому проверка на отсутствие значения должна быть задана явно с использованием оператора IS NULL или IS NOT NULL.

Если в отношении одного и того же объекта правила срабатывает несколько правил, фильтры объединяются через логическое "И".

При редактировании атрибута в карточке объекта может сработать проверка допустимости другого атрибута. Поскольку при таком редактировании значения сохраняются для каждого атрибута отдельно, выполнение условия допустимости становится невозможным. В таком случае система предложит пользователю перейти в окно для редактирования объекта.
Эффект allowed не поддерживается для связей и атрибутов типа Array, Counter, Reference, RQL и Table.

Атрибуты, подпадающие под правило (attributes)

Путь в схеме: dataRules[].attributes[]

Каждый элемент массива имеет следующую структуру:

Поле Обязательное поле Описание Тип данных

attribute

да

Ссылка на идентификатор атрибута, подпадающего под действие правила.

Data ID Ref

constraint

да (при effect: allowed, подробности в описании)

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

Если в поле effect установлено значение allowed, должно быть заполнено хотя бы одно из полей: constraint или expression.

RQL-выражение или выражение сравнения

value

да (подробности в описании)

Значение по умолчанию для атрибута при effect: default.

Если в поле effect установлено значение default, обязательно одно из полей — value или expression.

Значение соответствующего типа данных.

expression

да (подробности в описании)

Выражение на языке RQL, которое возвращает вычисленное значение соответствующего типа данных.

Если в поле effect установлено значение default или allowed, обязательно одно из полей:

  • value или expression для default;

  • constraint или expression для allowed.

RQL-выражение

message

нет

Сообщение, отображаемое в случае ошибки выполнения правила. Доступно, если значение в поле effect отличается от default.

Ознакомьтесь с описанием поля message.

строка

help

нет

Сообщение, отображаемое при наведении курсора на иконку справки. Доступно, если значение в поле effect отличается от hidden.

Ознакомьтесь с описанием поля help.

строка

Элементы массива и атрибуты таблицы (nested)

Путь в схеме: dataRules[].nested

Поля items и attributes представляют собой массив записей атрибутов, подпадающих под действие правила, их возможных значений и отображаемых сообщений.

Поле имеет следующую структуру:

Поле Обязательное поле Описание Тип данных

type

да

Тип атрибута. Возможные значения:

  • table;

  • array.

перечисление

attributes

да (для Table)

Массив определения значений для объектов правила.

Запись включает поле attribute со ссылкой на атрибут таблицы, подпадающий под действие правила.

массив

items

да (для Array)

Массив определения значений для объектов правила.

Запись включает поле item с индексом элемента массива, подпадающий под действие правила.

Доступные значения индекса:

  • целое число, не меньше нуля;

  • строка '*' — для обозначения всех элементов массива.

массив

Связи, подпадающие под правило (linkages)

Путь в схеме: dataRules[].linkages[]

Каждый элемент массива имеет следующую структуру:

Поле Обязательность и значение по умолчанию Тип данных Описание

linkage

да

Data ID Ref

Ссылка на идентификатор связи, подпадающей под действие правила.

message

нет

строка

Сообщение, отображаемое в случае ошибки выполнения правила. Доступно, если значение в поле effect отличается от default.

Ознакомьтесь с описанием поля message.

help

нет

строка

Сообщение, отображаемое при наведении курсора на иконку справки. Доступно, если значение в поле effect отличается от hidden.

Ознакомьтесь с описанием поля help.

Сообщение при применении правила (message)

Путь в схеме:

  • dataRules[].message

  • dataRules[].attributes[].message

Поле message содержит текст сообщения, отображаемого при применении правила данных в интерфейсе и ответе API:

  • В поле message внутри элемента блока dataRules содержится единое сообщение для всех атрибутов объекта правила.

  • В поле message внутри записи действия для атрибута содержится сообщение для конкретного атрибута.

Пример заполнения поля message для всех атрибутов
dataRules:
  - id: required_attributes
    ...
    description: атрибуты становятся обязательными, если сработало условие в поле condition
    target: entity
    entity: incident
    condition: !rql incidentStatus = 'Подтвержден'
    message: "Укажите значения атрибутов!"
    rule:
      effect: required
      attributes:
        - attribute: incidentGuid
        - attribute: registrationDate
        - attribute: ipAddress
        ...
Пример заполнения полей message для конкретных атрибутов
dataRules:
  - id: required_attributes
    ...
    description: атрибуты становятся обязательными, если сработало условие в поле condition
    target: entity
    entity: incident
    condition: !rql incidentStatus = 'Подтвержден'
    rule:
      effect: required
      attributes:
        - attribute: incidentGuid
          message: "Укажите GUID!"
        - attribute: registrationDate
          message: "Укажите дату регистрации!"
        - attribute: ipAddress
          message: "Укажите IP-адрес!"
          ...

Сообщение справки (help)

Путь в схеме:

  • dataRules[].help

  • dataRules[].attributes[].help

Поле help содержит текст сообщения, отображаемого при наведении курсора на иконку справки.

  • В поле help внутри блока dataRules содержится единое сообщение для всех атрибутов объекта правила.

  • В поле help внутри записи действия для атрибута содержится сообщение для конкретного атрибута.

Пример заполнения поля help для всех атрибутов
dataRules:
  - id: required_attributes
    ...
    description: атрибуты становятся обязательными, если сработало условие в поле condition
    target: entity
    entity: incident
    condition: !rql incidentStatus = 'Подтвержден'
    help: "Необходимо заполнить все поля."
    rule:
      effect: required
      attributes:
        - attribute: incidentGuid
        - attribute: registrationDate
        - attribute: ipAddress
        ...
Пример заполнения полей help для конкретных атрибутов
dataRules:
  - id: required_attributes
    ...
    description: атрибуты становятся обязательными, если сработало условие в поле condition
    target: entity
    entity: incident
    condition: !rql incidentStatus = 'Подтвержден'
    rule:
      effect: required
      attributes:
        - attribute: incidentGuid
          help: "Необходимо указать GUID."
        - attribute: registrationDate
          help: "Необходимо дату регистрации инцидента."
        - attribute: ipAddress
          help: "Необходимо указать IP-адрес устройства."
          ...

Была ли полезна эта страница?

+7 (499) 755 55 70 sales@rvision.ru

О компании Пользовательское соглашение Политика cookies

Обратная связь