Entities (Сутності) #

Загальна інформація #

Сутність (Entity) - базова одиниця доступу до даних платформи UnityBase. Сутність визначає як спосіб зберігання даних, так і поведінку (методи). Метадані сутності можуть бути використані клієнтськими додатками для побудови користувацького інтерфейсу.

У клієнт-серверній архітектурі найближча аналогія сутності - view у базі даних із тригерами на вставку/оновлення/видалення записів. В OOP - клас, що реалізує ORM.

З точки зору розробника сутність - це:

  • файл у форматі JSON з розширенням .meta (метафайл), що описує сутність та її атрибути
  • опціонально, файл із таким самим іменем, але розширенням .js, що описує додатково поведінку (методи) сутності мовою JavaScript

Використовуючи метафайл, UnityBase може:

  • згенерувати скрипт на створення таблиці в цільовій БД для зберігання даних сутності (якщо таблиця вже є - скрипт на модифікацію)
  • згенерувати інструкції SQL для вибірки/вставки/видалення/додавання даних
  • згенерувати базовий користувацький інтерфейс довідника (гріда) і форми редагування запису
  • згенерувати документацію у форматі HTML
  • відобразити сутність у графічному вигляді на ER diagram

Приклад метафайлу film_film.meta:

{
    "caption" : "Кінофільм",
    "description" : "Кінифільми",
    "documentation": "Зберігає всі зареєстровані кінофільми",
    "descriptionAttribute" : "title",	
    "attributes" : {
        "IMDB": {
            "dataType": "String",
            "size": 12,
            "caption": "IMDB",
            "description" : "Ідентифікатор IMDB",
            "documentation": "Internet Movie Database (IMDb) ідентифікатор може бути використаний для отримання додаткової інформації про фільм через API www.omdbapi.com"
            "allowNull" : false,
            "isUnique": true    
        },
        "title": {
            "dataType" : "String",
            "size" : 100,
            "caption" : "Назва",
            "description" : "Назва кінофільму",
            "allowNull" : false
        }
    },
    "mixins" : {
        "mStorage" : {
            "simpleAudit": true,
            "safeDelete": true 
        }
    }
}

У цьому метафайлі ми описали сутність кінофільм із кодом film_film, у якої є два атрибути: «Ідентифікатор IMDB» і “Назва”.

Повна специфікація метафайлу описується наступною JSON schema:

Mixins (Миксины) #

Самі по собі сутності не мають поведінки, вона описується методами сутності. UnityBase містить низку готових методів, що розв'язують найпоширеніші завдання. Реалізація методів міститься в Міксинах. Розробник може додати свої методи до сутності або перекрити методи, додані міксинами.

У прикладі вище для сутності film_film ми додали міксин mStorage. Власне він додав для нашої сутності методи для CRUID операцій.

mStorage - Implements CRUID operations with entities (ORM) #

Добавляет методы:

  • addNew
  • select
  • insert
  • update
  • delete

Implements "Optimistic locking" and "Soft deletion" - check out mStorage mixin guide for additional reading.

audit - Аудит рівня запису #

Забезпечує запис усіх низькорівневих операцій insert/update/delete у сутність аудиту ubs_audit. Для операцій update записуються як значення ДО оновлення, так і нові. За замовчуванням увімкнено для всіх сутностей системи.

rls - Row Level Security (Безпека рівня записів) #

RLS is a security feature which allows developers to give access to a sub-set of data in their entity to others. Traditional permission systems don't distinguish between individual rows in a table, so access is all-or-nothing. Grant to select method on an entity will allow a user to access all rows of that entity.

RLS supplements these with an additional layer of access controls on a per-row basis, so requirements such as "a manager can only view sensitive employee information for those employees who report to them" can be specified and enforced by the ORM.

Check out Row Level Security Mixin for additional reading.

aclRls - Access Control List Row Level Security #

Access Control List Row Level Security is a commonly used implementation of Row Level Security conception, so we implement it as a mixin and add a client-side features for edit ACL.

Unlike acl mixin, what allows set "static" rule for selecting rows, aclRls mixin allows end user or program to specify grants for each row.

Consider we have doc_document entity and wants to allow supervisor sets specific grants for every document. And we need to give grant either to user, or to role or to group or to organization unit.

For this we add aclRls mixin into mixins section of doc_document metadata and specify onEntities to be

  • uba_dubject: for users, groups and roles, since this entity is a unity for all administration subjects
  • org_unit: for organization units

doc_document.meta example:

{
  "caption": "Documents",
  "attributes": [
    // document attributes ...
  ],
  "mixins": {
    "mStorage": {
    },
    "aclRls": {
      "onEntities": [
        "org_unit",
        "uba_subject"
      ]
    }
  }
}

After execution of ubcli migrate command doc_document_acl table will be added into database. Entity doc_document_acl will be automatically generated by (inside @unitybase/ub model metadata hook). Here is a result:

classDiagram direction RL doc_document "1" --> "*" doc_document_acl : valueID uba_subject "1" --> "*" doc_document_acl : subjID org_unit "1" --> "*" doc_document_acl : ounitID class doc_document { ID : Int64 ... other attrs aclRls(onEntities: ["uba_subject", "org_unit"]) } class uba_subject { ID : Int64 ... other attrs } class org_unit { ID : Int64 ... other attrs } class doc_document_acl { ID : Int64 instanceID: doc_document valueID: Int64 subjID: uba_subject ounitID: org_unit }

After this for each doc_document.select call aclRls mixin will add

  and exists (select 1 from doc_document_acl where instanceID = doc_couemtn.ID and valueID in :admSubjIDs)

condition.

The admSubjIDs parameter value is returned by function, specified in the aclRls.subjectIDsFn mixin parameter. If the mixin parameter is not provided, the default RLS.getDefaultAclRlsSubjects implementation will be used.

The default RLS.getDefaultAclRlsSubjects is applicable for cases, when onEntities contains uba_subject or/and org_unit only. In other cases, it is required to specify subjectIDsFn and develop a custom implementation.

Filtering condition can be changed from Exist to In by specifying aclRls.selectionRule: "In", but this is not recommended, because some DBMS generate more efficient query plan with Exists method.

It is possible to disable adding an aclRls filter by specifying function name in aclRls.skipIfFn. If function returns true - filtering condition is not added. By default, skipIfFn is set to RLS.isSuperUserOrInAdminGroup, which skip aclRls in case current user is admin or root or Admin group member.

Parameters skipIfFn, subjectIDsFn and selectionRule can be specified for every entity or defined globally in the application ubConfig.json:

{
  "application": {
    "domain": {
      //...
    },
    "mixinsDefaults": {
      "aclRls": {
        "skipIfFn": "RLS.isSuperUserOrInAdminGroup",
        "subjectIDsFn": "RLS.getDefaultAclRlsSubjects",
        "selectionRule": "Exists"
      }
    }
  }
}

For individual call aclRls can be disabled by adding misc({__skipAclRls: true}) into repository

UB.Repository('doc_document').attrs(['ID'])
  .misc({skipAclRls: true}).limit(1).selectSingle()

! skipAclRls works ONLY for server repository

For other aclRls options see description in entity schema

Before UB@5.22.10 instead of skipIfFn and subjectIDsFn exprMethod method is used. This method is OBSOLETE

"sameAs" ALC configuration #

For master-detail relations (for example we have a detail doc_doumentitems belong to doc_document) master entity ACL usually should be used. In this case detail entity aclRlc can be configured as such

doc_doumentitems.meta example:

{
  "caption": "Document items",
  "attributes": [
    {
      "name": "docID",
      "dataType": "Entity",
      "associatedEntity": "doc_document",
      "cascadeDelete": true,
      "caption": "Document",
      "allowNull": false,
      "defaultView": false
    },
    // other attributes ...
  ],
  "mixins": {
    "mStorage": {
    },
    "aclRls": {
      "sameAs": "doc_document",
      "entityConnectAttr": "docID"
    },
  }
}

For entities with aclRls configured using sameAs the same ACL RLS storage is used (doc_document_acl in example above). ACL editing UI is disabled for such entities.

als - Attribute Level Security #

Методи міксину:

  • getallroles - Отримати список усіх ролей, включно з динамічними ролями сутності
  • getallstates - Отримати список усіх станів, включно з динамічними станами сутності
  • beforeselect - Підготовка службових даних для укладача запитів, включно з поточним станом і поточними ролями запису сутності
  • afterselect - Формування ALS-інформації для клієнта
  • beforeupdate - Підготовка службових даних для укладача запитів, включно з поточним станом і поточними ролями запису сутності

Властивості міксину:

  • stateAttrName - ім'я атрибута, який містить у собі інформацію про поточний стан запису сутності.
    Якщо значення цієї властивості задано, то міксин виконає запит до БД, щоб отримати його, інакше міксин викличе у сутності метод getRecordCurrState. Метод getRecordCurrState під час свого виконання повинен записати значення поточного стану у властивість _currRecordState (рядковий тип).

    Ця властивість використовується в методах beforeselect і beforeupdate.

    Приклад реалізації getRecordCurrState:

    /**
 * Сформувати і повернути поточний стан для запису сутності
 * @param {ubMethodParams} runparams
 * @return {Boolean}
 */
me.getRecordCurrState = function(runparams) {
    var
        /** @type {TubDataStore} */
        iDoc,
        rp = runparams.mParams;

    iDoc = UB.Repository('doc_incdoc').attrs(['mi_wfState'])
        .where('[ID]', '=', rp.ID)
        .select();
    if (!iDoc.eof) {
        rp._currRecordState = iDoc.get('mi_wfState');
    }else{
        rp._currRecordState = '';
    }
    return true;
};

  • stateEnumGroup - назва групи нумерованого списку із сутності ubm_enum.
    Якщо значення цієї властивості задано, то міксин спочатку виконає запит до сутності ubm_enum і з отриманих даних заповнить два масиви станів: масив значень і масив описів.
    Якщо значення не задано, то цей крок пропускається.
    Після цього міксин викличе у поточної сутності метод addAllDynStates, від якої також чекає масив значень і масив описів.
    Ці два масиви під час виконання addAllDynStates мають бути записані у властивості _dynStateValues і _dynStateNames відповідно.

    Ця властивість використовується в методі getallstates.

    Приклад реалізації addAllDynStates:

    /**
 * Сформувати і повернути масив усіх динамічних станів сутності
 * @param {ubMethodParams} runparams
 * @return {Boolean}
 */
me.addAllDynStates= function(runparams) {
    var rp = runparams.mParams,
        arrValues = [],
        arrNames = [];

    arrValues.push('new');
    arrNames.push('Новий запис');
    arrValues.push('closed');
    arrNames.push('Закритий запис');

    rp._dynStateValues = arrValues;
    rp._dynStateNames = arrNames;
    return true;
};

    Ещё один пример реализации addAllDynStates:

    /**
 * Сформувати і повернути масив усіх динамічних ролей сутності
 * @param {ubMethodParams} runparams
 * @return {Boolean}
 */
me.addAllDynRoles = function(runparams) {
    var rp = runparams.mParams,
        arrValues = [],
        arrNames = [];

    arrValues.push('recordOwner');
    arrNames.push('Создатель записи');
    arrValues.push('worldOwner');
    arrNames.push('Создатель мира');

    rp._dynRoleValues = arrValues;
    rp._dynRoleNames = arrNames;
    return true;
};

  • optimistic - булевое значение позволяющее узнать является ли администрирование оптимистичным(true) или пессимистичным(false).
    Значение этого свойства используется только в одном случае - когда на сущности нет НИ ОДНОГО администрирования ALS. В таком случае при оптимистичном администрировании все атрибуты будут иметь ВСЕ права, при пессимистичном администрировании у атрибутов НЕТ прав.

Условия для администрирования атрибутов с помощью миксина ALS #

Для администрирования атрибутов сущности с помощью миксина ALS необходимо выполнение следующих условий:

  • Миксин должен быть прописан в meta-файле сущности:
    ...
"mStorage": {
    "simpleAudit": true,
    "safeDelete": true
},
"als": {
    "stateAttrName": "mi_wfState",
    "stateEnumGroup": "",
    "optimistic": true
},
...
  • В Post-параметрах от клиента на верхнем уровне должен быть параметр с именем ID
    (Это связанно с тем что на текущий момент миксин администрирует пока только ОДНУ запись сущности)
  • В Post-параметрах от клиента на верхнем уровне должен быть параметр alsNeed: true

Алгоритм работы миксина ALS #

Миксин ALS работает следующим образом:

  1. Если клиентом был вызван метод select, то в Post-параметрах происходит поиск ID и alsNeed: true.
    Если клиентом был вызван метод update, то в Post-параметрах происходит поиск ID и execParams.
    Если все нужные параметры найдены, то переход к п.2. Иначе миксин не делает никаких действий.

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

  3. Происходит получение роли текущей записи сущности (с идентификатором ID).
    (Это роли пользовательской сессии, под которой выполняется миксин плюс динамические роли сущности из метода getRecordCurrDynRoles)

    Пример реализации метода getRecordCurrDynRoles:

    /**
 * Сформировать и вернуть массив динамических ролей для записи сущности
 * @param {ubMethodParams} runparams
 * @return {Boolean}
 */
me.getRecordCurrDynRoles = function(runparams) {
    var
        /** @type {TubDataStore} */
        iDoc,
        arrValues = [],
        rp = runparams.mParams;

    iDoc = UB.Repository('doc_incdoc').attrs(['mi_owner'])
        .where('[ID]', '=', rp.ID)
        .select();

    if (!iDoc.eof) {
        if (iDoc.get('mi_owner') === Session.userID){
            arrValues.push('recordOwner');
        }
    }

    arrValues.push('worldOwner');
    rp._currDynRoleValues = arrValues;
    return true;
};

  4. Миксин формирует служебную информацию составителю запросов, и при построении запроса для каждого атрибута определяет права для текущего состояния и текущих ролей.

  5. Если клиентом был вызван метод select, то миксин в методе afterselect сформирует для клиента следующую структуру:

    ...
"fieldList": ["ID", "outNumber", "outDate"],
"resultAls": {
    "ID": "SUM",
    "outNumber": "UM",
    "outDate": "S"
},
...

  6. Если клиентом был вызван метод update и у него нет прав на изменение данных, то миксин не даст ему изменить атрибут.

    Текст ошибки будет таким: ALS: Update deny. Cannot update attribute "outDate" in entity "myWork" for state "NEW".

Символьные значения прав:

  • Select - право пользователя видеть значение атрибута
    • Символ: S
    • Значение: 0b001
  • Update - право пользователя изменять значение атрибута
    • Символ: U
    • Значение: 0b010
  • Mandatory - является ли значение атрибута обязательным
    • Символ: M
    • Значение: 0b100

Значение можно комбинировать получая различные битовые маски доступа:
1 - можно выбирать
2 - можно апдейтить
4 - обязательное 3 - это можно выбирать и апдейтить
7 - выбирать апдейтить и обязательное
5 - обязательное и выбирать
и т.д.

dataHistory - Историчность записей #

unity #

tree - древовидные структуры с построением хранимого пути #

fts - полнотекстовое индексирование данных сущности #

softLock - Пессимистические блокировки (Pessimistic locks) #

See detailed pessimistic locking guide

clobTruncate - Обрезает большие текстовые поля #