Референтний бізнес-процес: управління логічними операторами `AND` та `OR` в рамках однієї таблиці

ЗМІСТ

1. Проблематика
2. Загальний опис
3. Референтні приклади моделювання регламенту
4. Пов’язані сторінки

1. Проблематика

У традиційному підході до формування пошукових запитів, параметри об’єднувалися виключно за допомогою логічного оператора AND. Це створювало обмеження, оскільки не давало можливості використовувати гнучкіші умови об’єднання параметрів, такі як OR. Тепер користувачі можуть обирати між AND та OR, забезпечуючи гнучкість у порядку застосування цих операторів.

2. Загальний опис

Моделювальники регламенту мають змогу деталізувати та оптимізувати пошукові запити завдяки тегу <ext:logicOperator>. Цей тег є ключовим елементом у створенні більш гнучких і ефективних умов пошуку в базах даних.

Особливості та можливості тегу <ext:logicOperator>:

Підтримка різних логічних операторів:
- Наразі <ext:logicOperator> підтримує два основні типи логічних операторів: AND та OR.
- Це розширення дозволяє створювати складніші та точні умови пошуку, адаптуючи запити до конкретних потреб користувачів.
Гнучкість при моделюванні запитів:
- З використанням <ext:logicOperator>, моделювальники можуть визначити, чи мають умови в таблиці об’єднуватися через AND (всі умови повинні бути виконані), або через OR (достатньо виконання будь-якої з умов).
Вкладеність та комбінації умов:
- Тег дозволяє використовувати вкладені структури, комбінуючи AND і OR для створення складніших логічних умов.
- Це значно розширює можливості моделювання запитів, дозволяючи враховувати різноманітні сценарії та бізнес-вимоги.

Більше про моделювання структур даних із тегом <ext:logicOperator> читайте на сторінці Оптимізація пошукових запитів: управління логічними операторами AND та OR в рамках однієї таблиці.

3. Референтні приклади моделювання регламенту

Ми розробили референтні приклади моделювання регламенту, зокрема схеми даних, референтний процес та UI-форми до нього, які наочно продемонструють використання функціональності у реєстрах.

3.1. Моделювання структур даних

Розгляньмо референтний приклад критерію пошуку, який демонструє управління логічними операторами AND та OR у контексті однієї таблиці, використовуючи тег ext:logicOperator.

Використовуйте ChangeSet із регламенту демо-реєстру. Модель буде доступна за шляхом: data-model/reference/search-type-or/main.xml.

Приклад 1. Референтна XML-схема з використанням AND та OR

<changeSet author="registry owner" id="create SC search build types with OR">
	<ext:createSearchCondition name="search_build_type_active_or_id">
		<ext:table name="build_type">
			<ext:logicOperator type="or">
				<ext:logicOperator type="and">
					<ext:column name="name" searchType="startsWith"/>
					<ext:column name="active" searchType="equal"/>
				</ext:logicOperator>
				<ext:column name="build_type_id" searchType="equal"/>
			</ext:logicOperator>
		</ext:table>
	</ext:createSearchCondition>
</changeSet>

Ця XML-схема використовує вкладені теги <ext:logicOperator> для моделювання складних умов пошуку в межах однієї таблиці. У цьому прикладі, OR використовується для створення двох різних умов пошуку: одна з комбінацією AND, що включає поля name та active, та інша для поля build_type_id.

Таблиця 1. Опис таблиці `build_type`
Стовпець	Опис
`name`	Назва типу будівлі, яка використовується для пошуку з оператором `startsWith`.
`active`	Статус активності типу будівлі, який використовується для точного пошуку з оператором `equal`.
`build_type_id`	Унікальний ідентифікатор типу будівлі, який використовується для точного пошуку з оператором `equal`.

У цьому SQL-скрипті ми використовуємо комбінацію логічних операторів AND та OR для створення складних умов пошуку в таблиці build_type. Скрипт виконує пошук за двома різними наборами критеріїв:

Комбінація AND:
- name LIKE 'desired_name%': шукаємо записи, де назва типу будівлі починається з певної фрази (desired_name). Використання оператора LIKE з символом відсотка (%) дозволяє знаходити всі записи, які починаються з цієї фрази.
- AND active = true: Додатково фільтруємо записи, щоб вони відповідали тим, де поле active дорівнює true, тобто тип будівлі є активним.
Оператор OR:
- OR build_type_id = specific_id: окрім вищевказаних умов, цей запит також включає до вибірки записи, де ідентифікатор типу будівлі (build_type_id) точно дорівнює конкретному значенню (specific_id).

Отже, цей запит вибере всі записи, що задовольняють або першій комбінації умов (AND), або другій умові (OR). Це дозволяє отримати більш гнучкі та цілеспрямовані результати пошуку.

Приклад 2. SQL-скрипт (пошуковий запит)

SELECT * FROM build_type
WHERE (name LIKE 'desired_name%' AND active = true)
   OR build_type_id = specific_id

Такий підхід дозволяє здійснити більш точний пошук, наприклад, вибрати всі активні типи будівель із певною назвою або конкретний тип будівлі за його унікальним ідентифікатором.

3.2. Довідник типів будівель

У дата-фабриці, де зберігається довідник Типів будівель, ви маєте п’ять різних типів будівель. З цих п’яти типів, перші чотири позначені як активні. Це означає, що при використанні вашого пошукового запита, ви зможете легко ідентифікувати ці чотири активні типи будівель.

bp and or single table 02

Розглянемо, як це впливає на роботу SQL-скрипта, який ми розглядали вище.

Приклад 3. SQL-скрипт (пошуковий запит)

SELECT * FROM build_type
WHERE (name LIKE 'desired_name%' AND active = true)
   OR build_type_id = specific_id

У цьому запиті:

Умова name LIKE 'desired_name%' AND active = true дозволить вам вибрати всі активні типи будівель (перші чотири з п’яти), які відповідають певному критерію за назвою. Це може бути корисним для знаходження специфічних активних типів будівель.
Умова OR build_type_id = specific_id дає можливість включити в результати пошуку також той тип будівлі, який має відповідний унікальний ідентифікатор (specific_id), незалежно від його активності. Це означає, що якщо п’ятий тип будівлі має цей ідентифікатор, він також буде включений у результати пошуку, навіть якщо він не активний.

Таким чином, ваш пошуковий запит ефективно допомагає управляти та фільтрувати інформацію про типи будівель у вашій дата-фабриці, надаючи гнучкість для отримання даних як про активні, так і про специфічні типи будівель.

3.3. Моделювання бізнес-процесу

Де можна знайти приклад референтного бізнес-процесу?

Адміністратор Платформи може розгорнути для вас демо-реєстр — еталонний реєстр, що містить референтні та інші приклади файлів для створення цифрового регламенту. Він містить різноманітні елементи для розробки моделі даних, бізнес-процесів, UI-форм, аналітичної звітності, витягів, сповіщень, зовнішніх інтеграцій та багато іншого.

Детальну інструкцію щодо розгортання демо-реєстру та отримання референтних прикладів моделювання ви знайдете на сторінці Розгортання демо-реєстру із референтними прикладами.

Приклад BPMN-схеми процесу буде доступний у регламенті демо-реєстру за пошуком по ключовим словам — reference-search-type-or.

Назви форм ви можете знайти всередині відповідних користувацьких задач (User Task) бізнес-процесу у полі Form key:

reference-search-type-or-add-new-info-build.json
reference-search-type-or-sign-act-build.json
reference-search-type-or-sign-act-build-update.json
reference-search-type-update-build-info.json

У Кабінеті користувача процес буде доступний у папці Референтні бізнес-процеси > Пошук даних в дата-фабриці за типом OR.

bp and or single table 01

Зображення 1. Загальний вигляд бізнес-процесу у Кабінеті адміністратора регламентів

3.3.1. Користувацька задача для внесення даних про об’єкт

На першій користувацькій формі налаштуйте можливість введення даних про об’єкт та вибору типу цього об’єкта з довідника Типів будівель. Для цього:

Створіть User Task та застосуйте шаблон делегата User Form.
У полі Name введіть назву задачі.
В полі Form key вкажіть службову назву форми.
У полі Assignee вкажіть ${initiator}, щоб призначити задачу користувачеві, який ініціював виконання цього бізнес-процесу.

bp and or single table 2

3.3.2. Користувацька задача для підписання даних КЕП

Створіть користувацьку задачу для підписання даних за допомогою User Task та шаблону делегата Officer Sign Task.

У полі Name введіть назву задачі.
У полі Form key вкажіть службову назву форми для підписання даних.
У полі Assignee вкажіть ${initiator}, щоб призначити задачу користувачеві, який ініціював виконання цього бізнес-процесу.
У полі Form data pre-population вкажіть змінну ${submission('UserTask_AddDataBuildInfo').formData} для автоматичного заповнення форми даними, що зібрані в попередній користувацькій задачі.

bp and or single table 3

3.3.3. Скрипт підготування даних для запису до БД

Створіть задачу скриптування (Script Task) для підготовки даних до запису у Фабрику даних.

bp and or single table 4

У полі Name введіть назву задачі.
Натисніть кнопку Open script editor та внесіть наступний скрипт:

def formDataForm = submission('UserTask_SignDataBuildInfo').formData

def buildTypeId = formDataForm.prop('buildType').prop("buildTypeId").value()

def data = [:]
data['buildType'] = buildTypeId;
data['buildNumber'] = formDataForm.prop('buildNumber').value()
data['sectionNumber'] = formDataForm.prop('sectionNumber').value()
data['flatNumber'] = formDataForm.prop('flatNumber').value()

def payload = S(data, 'application/json')
set_transient_variable('payload', payload)

Цей скрипт забирає дані з попередньої користувацької задачі, формує вихідні дані у форматі JSON і зберігає їх як тимчасову змінну 'payload'. Використання Groovy дозволяє гнучко маніпулювати даними й підготувати їх для подальшого запису в базу даних.

Розгляньмо скрипт більш детально:

Отримання даних з форми:
```
def formDataForm = submission('UserTask_SignDataBuildInfo').formData`
```
Цей рядок витягує дані з форми, які були підписані користувачем на попередній користувацькій задачі (UserTask_SignDataBuildInfo).
Витягнення конкретних даних:
```
def buildTypeId = formDataForm.prop('buildType').prop("buildTypeId").value()
```
Тут витягується ідентифікатор типу будівлі (buildTypeId) з даних форми.
Формування об’єкта даних:
- Створюється новий об’єкт data типу Map (у Groovy це визначається як [:]).
- Далі до об’єкта data додаються різні властивості, такі як buildType, buildNumber, sectionNumber, flatNumber, кожна з яких отримує своє значення з даних форми.
Формування JSON Payload:
```
def payload = S(data, 'application/json')
```
Цей рядок конвертує об’єкт data в JSON-рядок, готовий для відправлення або обробки як частина запита до Фабрики даних.
Зберігання даних для використання у подальших задачах:
```
set_transient_variable('payload', payload)
```
Останній рядок зберігає JSON-рядок в тимчасову змінну payload, яка може бути використана в подальших задачах або процесах.

3.3.4. Сервісна задача для підписання даних системним ключем

Для забезпечення безпеки та автентичності даних у вашому бізнес-процесі важливо використовувати сервісну задачу для підписання даних системним ключем. Це можна зробити за допомогою наступних кроків:

Створіть сервісну задачу (Service Task) та застосуйте шаблон делегата Digital signature by DSO service.
Налаштуйте параметри задачі:
1. У полі Name задайте назву задачі, яка чітко відображає її мету, наприклад: Підписання даних системним ключем.
2. Застосуйте шаблон делегата Digital signature by DSO service, який забезпечить потрібну функціональність для підписання.
3. У полі Payload вкажіть вхідні дані: ${payload}. Це забезпечує передачу даних, які потребують підписання, у задачу.
4. У полі X-Access-Token source вкажіть токен доступу: ${completer('UserTask_SignDataBuildInfo').accessToken}. Цей токен визначає виконавця останньої користувацької задачі, який має право підписати дані.
5. У полі Result variable задайте змінну, яка буде містити результат підписання: system_signature_key. Це дозволить зберігати ключ підписання для подальшого використання або перевірки.

3.3.5. Сервісна задача для збереження даних до БД

Створення сервісної задачі для збереження даних до бази даних в бізнес-процесі вимагає ретельного планування та налаштування. Ось кроки, які необхідно виконати:

Створіть сервісну задачу (Service Task) та застосуйте шаблон делегата Create entity in data factory.
Налаштування задачі:
1. У полі Name вкажіть назву задачі, що чітко відображає її мету, наприклад, Збереження даних до БД.
2. У полі Resource вкажіть ресурс або назву ендпоінту для таблиці, куди будуть зберігатися дані.
3. В полі Payload введіть дані для створення запису: ${payload}. Це забезпечить передачу необхідних даних у задачу.
4. У полі X-Access-Token вкажіть токен доступу користувача, під яким виконується операція: ${completer('UserTask_SignDataBuildInfo').accessToken}. Це забезпечить авторизацію користувача при збереженні даних.
5. У полі X-Digital-Signature source вкажіть джерело цифрового підпису: ${sign_submission('UserTask_SignDataBuildInfo').signatureDocumentId}. Це ідентифікує документ із цифровим підписом, який був створений на попередніх етапах.
6. В полі X-Digital-Signature-Derived source вкажіть змінну, яка містить ключ цифрового підпису: ${system_signature_key}.
7. В полі Result variable задайте ім’я для змінної, в якій буде зберігатися відповідь від операції збереження, наприклад, response.

3.3.6. Користувацька задача для оновлення даних про будівлю

Для демонстрації можливості відображення усіх активних та неактивних типів будівель у випадку, коли використовуються обидва оператори пошуку – AND та OR, необхідно створити користувацьку задачу. Виконайте наступні кроки:

Створіть користувацьку задачу (User Task) та застосуйте шаблон делегата User Form.
Налаштування задачі:
1. У полі Name введіть назву задачі, наприклад, Оновлення даних про будівлю.
2. У полі Form key вкажіть службову назву форми. Наприклад, building-type-update-form, що відповідатиме формі для оновлення даних.
3. У полі Assignee вкажіть ім’я користувача, який підписав дані на попередній задачі: ${completer('UserTask_SignDataBuildInfo').userName}. Це забезпечить, що задачу буде виконувати той же користувач, який брав участь у попередніх етапах процесу.

3.3.7. Користувацька задача для підписання оновлених даних КЕП

Підписання оновлених даних є важливим етапом у забезпеченні цілісності та автентичності інформації в рамках бізнес-процесу. Виконайте наступні кроки для створення користувацької задачі з використанням форми для підписання даних:

Створіть користувацьку задачу (User Task) та застосуйте шаблон делегата Officer Sign Task.
Налаштування параметрів задачі:
1. У полі Name введіть назву задачі, яка чітко описує її мету. Наприклад, Підписання оновлених даних.
2. У полі Form key вкажіть службову назву форми для підписання даних. Це може бути, наприклад, signature-update-form.
3. У полі Assignee вкажіть користувача, який вніс останні оновлення: ${completer('UserTask_UpdateBuildInfo').userName}. Це забезпечить, що підписання буде виконуватися користувачем, відповідальним за останні зміни.
4. У полі Form data pre-population вкажіть змінну: ${submission('UserTask_UpdateBuildInfo').formData}. Це автоматично заповнить форму підписання необхідними даними.

bp and or single table 8

3.3.8. Скрипт підготування даних для оновлення сутності у БД

Створіть задачу скриптування (Script Task) для підготовки даних до запису у Фабрику даних.

bp and or single table 9

У полі Name введіть назву задачі.
Натисніть кнопку Open script editor та внесіть наступний скрипт:

def formDataForm = submission('UserTask_SignUpdateBuildInfo').formData

def buildTypeId = formDataForm.prop('buildType').prop("buildTypeId").value()

def data = [:]
data['buildType'] = buildTypeId;
data['buildNumber'] = formDataForm.prop('buildNumber').value()
data['sectionNumber'] = formDataForm.prop('sectionNumber').value()
data['flatNumber'] = formDataForm.prop('flatNumber').value()
data['autoGeneratedNumber'] = formDataForm.prop('building').prop('autoGeneratedNumber').value()

def payload = S(data, 'application/json')
set_transient_variable('payload', payload)

Скрипт ефективно підготовлює дані, забезпечуючи їхню відповідність формату, необхідному для оновлення сутностей у базі даних.

Розгляньмо цей скрипт більш детально:

Отримує дані з форми, які були заповнені у попередній користувацькій задачі з ідентифікатором UserTask_SignUpdateBuildInfo.
```
def formDataForm = submission('UserTask_SignUpdateBuildInfo').formData
```
Витягує конкретне значення buildTypeId з отриманих даних форми. buildTypeId може бути, наприклад, унікальним ідентифікатором типу будівлі.
```
def buildTypeId = formDataForm.prop('buildType').prop("buildTypeId").value()
```
Створює об’єкт data, який є словником (або мапою) у Groovy. Ключами словника є назви полів, а значеннями є дані, витягнуті з форми. Цей об’єкт містить всі необхідні дані для оновлення запису в базі даних.
```
def data = [:]
data['buildType'] = buildTypeId;
data['buildNumber'] = formDataForm.prop('buildNumber').value()
data['sectionNumber'] = formDataForm.prop('sectionNumber').value()
data['flatNumber'] = formDataForm.prop('flatNumber').value()
data['autoGeneratedNumber'] = formDataForm.prop('building').prop('autoGeneratedNumber').value()
```
Наступний рядок конвертує об’єкт data у JSON-рядок. S(data, 'application/json') є вбудованою функцією в Groovy, яка виконує серіалізацію об’єкта в JSON.
```
def payload = S(data, 'application/json')
```
Останній рядок зберігає JSON-рядок у тимчасову змінну payload. Ця змінна потім може бути використана в інших частинах бізнес-процесу, наприклад, у сервісних задачах, які відповідають за взаємодію з базою даних.
```
set_transient_variable('payload', payload)
```

3.3.9. Сервісна задача для підписання оновлених даних системним ключем

Сервісна задача для автоматичного підписання оновлених даних системним ключем є важливою частиною забезпечення цілісності та безпеки даних у бізнес-процесі. Щоб налаштувати цю задачу, слід виконати наступні кроки:

Створіть сервісну задачу (Service Task) та застосуйте шаблон делегата Digital signature by DSO service.
Налаштування задачі:
1. У полі Name введіть назву задачі. Назва має чітко відображати мету задачі, наприклад, Підписання даних системним ключем.
2. У полі payload вкажіть змінну ${payload}, що містить дані для підписання. Це вхідні дані, які були підготовлені попередніми задачами скриптування.
3. У полі X-Access-Token source вкажіть токен виконавця останньої користувацької задачі: ${completer('UserTask_SignUpdateBuildInfo').accessToken}. Цей токен забезпечить автентифікацію та авторизацію для підписання даних.
4. У полі Result variable вкажіть ім’я змінної, в якій буде збережено ключ підпису, наприклад, system_signature_key.

bp and or single table 10

3.3.10. Сервісна задача для оновлення сутності у БД

Сервісна задача для оновлення сутності в базі даних відіграє ключову роль у процесі оновлення даних, забезпечуючи їхню актуалізацію та синхронізацію. Щоб налаштувати цю задачу, слід виконати наступні кроки:

Створіть сервісну задачу (Service Task) та застосуйте шаблон делегата Update entity in data factory.
Налаштування параметрів задачі:
1. У полі Name введіть назву задачі, яка відображатиме її функцію, наприклад, Оновлення сутності у БД.
2. У полі Resource вкажіть назву ендпоінту або ресурсу, де буде відбуватися оновлення сутності.
3. У полі Resource id використовуйте ${submission('UserTask_SignUpdateBuildInfo').formData.prop('building').prop('entityId').value()} для визначення ідентифікатора оновлюваної сутності.
4. У полі Payload введіть ${payload}. Це забезпечить передачу даних, які необхідно оновити.
5. У полі X-Access-Token зазначте токен доступу користувача: ${completer('UserTask_SignUpdateBuildInfo').accessToken}.
6. У полях X-Digital-Signature source та X-Digital-Signature-Derived source вкажіть джерела цифрових підписів. Це забезпечить автентичність та відповідність даних стандартам безпеки.
7. У полі Result variable вкажіть назву змінної для збереження результату, наприклад, response. Це дозволить відстежувати результат операції оновлення.

3.4. Моделювання UI форм

3.4.1. Створення першої форми для внесення даних про будівлю

Створення форми для внесення даних про будівлю є першим кроком у реалізації бізнес-процесу в реєстрі. Ця форма дозволяє зібрати інформацію про новий об’єкт, включаючи його тип, номер будинку, корпус/секцію та номер квартири/офісу.

У демо-реєстрі референтна форма буде доступна за назвою reference-search-type-or-add-new-info-build.

Створіть UI-форму.
Налаштування текстових полів:
- Додайте поля Номер будинку, Корпус/Секція та Номер квартири/офісу. Це текстові поля (компонент Text Field), які дозволяють користувачеві ввести відповідну інформацію про будівлю.
  
  Детальніше про компонент Text Field, читайте на сторінці Text Field.
Конфігурація випадного списку для типу будівлі:
1. Додайте поле Тип будівлі за допомогою компонента Select. Це поле дозволить користувачам вибирати тип будівлі з попередньо визначеного переліку.
  
  Детальніше про компонент Select, читайте на сторінці Select.
2. На вкладці Data налаштуйте параметри для випадного списку:
  1. У полі Data Source Type оберіть URL.
  2. У полі Data Source URL вкажіть шлях до критерію пошуку. Наприклад, використовуйте /api/data-factory/search-build-type-active-or-id.
  3. У полі Search Query Name вкажіть параметр name.
  4. У полі Filter Query введіть ?active=true, щоб вибирати лише активні типи будівель.
  5. У полі Item Template введіть {{ item.name }}, щоб відображати імена типів будівель.

Ця форма є важливою частиною процесу збору даних та внесення інформації про нові об’єкти в систему. Вона дозволяє користувачам легко вибирати типи будівель із довідника, забезпечуючи точність та зручність введення даних.

bp and or single table 002

3.4.2. Створення форми для підписання даних КЕП

Створення форми для підписання даних КЕП, внесених на першій формі.

У демо-реєстрі референтна форма буде доступна за назвою reference-search-type-or-sign-act-build.

Форма складається з усіх полів попередньої форми у "Disabled"-вигляді.

Наполегливо рекомендуємо:: При моделюванні UI-форм для підписання даних КЕП, налаштовуйте їх так, щоб користувачі лише переглядали дані, й не могли їх змінювати. Для цього активуйте опцію Disabled (Disable the form input) на вкладці Display для кожного компонента, залученого у моделюванні.

bp and or single table 003

3.4.3. Створення форми для оновлення даних про будівлю

У процесі роботи над реєстром, форма для оновлення даних про будівлю забезпечує важливу функцію — вона дозволяє користувачам оновлювати інформацію про об’єкти, включаючи їх тип, використовуючи складні критерії пошуку. У демо-реєстрі форма доступна під назвою reference-search-type-or-update-build-info.

Створіть UI-форму.
Налаштування випадного списку "Будівля":
1. Додайте поле Будівля з типом за допомогою компонента Select для пошуку даних про будівлю, внесених на попередній формі.
  
  Детальніше про компонент Select, читайте на сторінці Select.
2. Налаштуйте параметри випадного списку на вкладці Data:
  1. У полі Data Source Type оберіть URL.
  2. У полі Data Source URL вкажіть шлях до критерію пошуку, наприклад, /api/data-factory/search-build-acts-with-type.
  3. У полі Limit вкажіть 100.
  4. У полі Item Template введіть Будинок {{ item.buildNumber }}, секція {{ item.sectionNumber }}, квартира/офіс {{ item.flatNumber }}.
Налаштування випадного списку "Тип будівлі" (Select):
1. У полі Тип будівлі вкладки Data:
  1. Для Data Source Type оберіть URL.
  2. У полі Data Source URL вкажіть шлях до критерію пошуку, наприклад, /api/data-factory/search-build-type-active-or-id.
  3. У полі Search Query Name вкажіть name.
  4. У полі Filter Query введіть ?buildTypeId={{data.building?.buildType?.buildTypeId}}&active=false.
  5. У полі Limit вкажіть 100.
  6. У полі Item Template введіть {{ item.name }}.

Ця форма використовує функціональність логічних операторів AND та OR для відображення у полі Тип будівлі типів, що відповідають двом параметрам: АБО id будівлі, створеному після внесення даних на першій формі, АБО статусу будівлі як "неактивний".

Такий підхід дозволяє користувачам виконувати детальніші та гнучкіші пошукові запити, що значно підвищує зручність роботи з реєстром.

Референтний бізнес-процес: управління логічними операторами AND та OR в рамках однієї таблиці

Референтний бізнес-процес: управління логічними операторами `AND` та `OR` в рамках однієї таблиці