.. _system_attributes:

Системные атрибуты
===================

**Системные атрибуты** — зарезервированные атрибуты платформы Citeck, доступные для любой сущности вне зависимости от её типа. Они начинаются с символа ``_`` и предоставляют служебную информацию: метаданные сущности, права доступа, статус, мета-информацию об атрибутах, а также управляют поведением операций чтения и записи.

Системные атрибуты используются в тех же контекстах, что и обычные атрибуты: в Records API, в конфигурации журналов, форм, вычислениях и бизнес-процессах.

.. list-table::
   :widths: 10 30
   :align: center
   :class: tight-table
   :header-rows: 1

   * - Атрибут
     - Описание
   * - **_null**
     - всегда возвращает ``null``
   * - **_type**
     - возвращает тип сущности
   * - **_notExists**
     - возвращает ``true``, если сущность не существует
   * - **_has**
     - | проверить наличие чего-то в значении. Например:

           .. code-block:: text

                  permissions._has.Write?bool

       | проверить наличие прав на изменение сущности
   * - **_edge**
     - | получить мета-информацию об атрибуте (имя, заголовок, возможность просматривать, возможность редактировать и т.д.):

           .. code-block:: text

                  _edge.title.protected?bool

       | например, для того чтобы узнать, что атрибут защищён от редактирования
   * - **_alias**
     - | алиас сущности при сабмите. Используется, когда нужно создать несколько связанных сущностей.
       | Т.к. ID новых сущностей станет известен только после того, как непосредственно они будут созданы, то необходим «фиктивный ID», чтобы на него ссылаться в атрибутах.
       | Например, хотим создать 2 сущности:

           .. code-block:: json

                 [
                   {"id": "emodel/some-type@", "attributes": {"link": "alias-value-0"}},
                   {"id": "emodel/some-type@", "attributes": {"_alias": "alias-value-0"}}
                 ]

       | Движок создаёт сущности с конца. Т.е. сначала создаст:

           .. code-block:: json

                 {"id": "emodel/some-type@", "attributes": {"_alias": "alias-value-0"}}

       | получит идентификатор новой сущности **emodel/some-type@123-123-123-123**, пробежится по сущностям,
       | которые будут созданы далее и подменит все ``alias-value-0`` на реальный ID ``emodel/some-type@123-123-123-123``.
       | Т.е. вторая сущность отправится на создание уже в виде:

           .. code-block:: json

                 {"id": "emodel/some-type@", "attributes": {"link": "emodel/some-type@123-123-123-123"}}
   * - **_parent**
     - ассоциация на родителя
   * - **_parentAtt**
     - родительский атрибут, по которому создаётся ссылка родитель → дочерняя сущность
   * - **_formKey**
     - | ключ формы (в множественном варианте), которые можно использовать для редактирования сущности в порядке приоритета от большего к меньшему.
       | Позволяет связывать сущности без ECOS типа с формами (старые задачи, например).
   * - **_modified**
     - дата изменения сущности
   * - **_modifier**
     - изменивший сущность
   * - **_statusModified**
     - дата последнего изменения статуса у записи
   * - **_created**
     - дата создания сущности
   * - **_creator**
     - создавший сущность
   * - **_content**
     - содержимое сущности
   * - **_actions**
     - действия
   * - **_docNum**
     - номер документа, который генерируется по шаблону нумерации в типе
   * - **_status**
     - текущий статус
   * - **_stage**
     - этап
   * - **_status?str**
     - id текущего статуса
   * - **_name**
     - | атрибут, который возвращает отображаемое имя сущности.
       | Может быть вычислен следующим образом:
       | 1. Если в конфиге типа есть **dispNameTemplate**, то имя будет вычислено на его основе
       | 2. Если в типе есть атрибут с **id=name** и в сущности это поле не пустое, то его значение будет значением ``_name``
       | 3. Берётся name типа
       | 4. Берётся id типа
       | Вычисленное значение **_name** всегда сохраняется в БД и по нему можно искать
   * - **_self**
     - | атрибут, который представляет само значение.
       | Т.е. ``_self._self._self._self._self`` — то же самое что и ``_self._self``.
       | Используется:
       | 1. Там, где значение — примитив (строка, число), но его нужно отредактировать на форме (форма может редактировать только атрибуты). В этом случае можно добавить на форме атрибут **_self**.
       | 2. Там, где нужно сделать мутацию, передав на форме файл (или JSON-объект), который по сути является сборником атрибутов сущности (например, форма с загрузкой конфигурации артефактов). Т.е. при отправке:

           .. code-block:: json

                 {"id": "abc", "attributes": {"_self": {"first": "second", "third": "fourth"}}}

       | движок воспринимает это так же, как:

           .. code-block:: json

                 {"id": "abc", "attributes": {"first": "second", "third": "fourth"}}

   * - **_isDraft?bool**
     - Получить значение системного флага «Черновик». Для записей в черновике отключена проверка обязательности полей и не запускается бизнес-процесс.
   * - **_as**
     - | получить значение как другой тип. Список вариантов зависит от типа значения.
       | Для строки доступно:
       | **_as.ref** — получить строку как ссылку на сущность
       | **_as.mltext** — получить строку как multi language text
   * - | **_localId**
       | **_disp**
       | **_str**
     - | :ref:`скаляры<scalars>`, которые можно получить как значения обычных атрибутов.
       | Т.е. в API доступ к скалярам идёт через вопросительный знак (например, **?str** и **?bin**), но заменив **«?»** на **«_»** мы получим те же данные в неконечном виде (т.е. можно запрашивать вложенные атрибуты).
       | Как вариант использования — берём свойство, в котором в виде строки записана ссылка на что-то другое. Пишем:

           .. code-block:: text

                 someField._str._as.ref.fieldFromRef

   * - | **_roles.isCurrentUserMemberOf.initiator?bool**
     - | Является ли текущий пользователь представителем роли «инициатор». Вместо ``initiator`` можно подставлять любой идентификатор роли
   * - | **_roles.assigneesOf.initiator[]?str**
     - | Загрузить представителей роли «инициатор». Вместо ``initiator`` можно подставлять любой идентификатор роли
   * - | **_pathByAssoc.someAssoc[]{?id,?disp}**
     - | Загрузить путь до текущей записи через ассоциацию с id ``someAssoc``
   * - | **_pathByParent[]{?id,?disp}**
     - | Загрузить путь до текущей записи через ассоциацию с id ``_parent``