Object Builder

Object Builder — це універсальний блок для формування, зміни та структурування даних у флоу. Він використовується для підготовки JSON-тіла перед HTTP Request, трансформації API-відповідей, обʼєднання результатів кількох блоків або динамічного створення масивів та вкладених обʼєктів. Object Builder дозволяє привести дані до формату, який очікує API або наступний блок, без написання коду.

Навігація:

1. Налаштування блоку
2. Методи роботи з об'єктом
3. Дії (Actions) для формування структури
   3.1. Робота з властивостями (Objects)
   3.2. Робота з масивами (Arrays)
   3.3. Видалення даних
4. Режими поля TXT та EXP
5. Швидкий старт
6. FAQ

Налаштування блоку

─────────────────────────────────────────────────────────────-

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

Тут можна обрати що треба буде зробити з об'єктом, яку дію можна застосувати для формування структури запиту та в якій змінній буде збережений результат.

1 -> Start from (метод): початковий метод роботи з об'єктом: новий об'єкт, копія або редагування існуючого.

2 -> Operations (дії): список дій для зміни структури (додати ключ, видалити поле тощо).

3 -> Save Result To: Визначає, куди зберегти результат для передачі даних.

• Механізм: Дані записуються в глобальне сховище VARS і стають доступними для всього потоку.
• Синтаксис: {{VARS}}['key_name'], де key_name — назва вашого ключа.
• Важливо: Не прописуйте {{VARS}} вручну — обов’язково оберіть її зі списку змінних Globals -> VARS.

Методи роботи з об'єктом

─────────────────────────────────────────────────────────────-

Цей параметр визначає вихідну точку: чи почнеться побудова структури «з нуля», чи використовуватимуться дані з попередніх кроків.

New Empty Object

Створення об’єкта «з чистого аркуша». Усі властивості, які ви задаєте (через дії Set Property, Add Value at End тощо), будуть додані до цього нового об’єкта.
Коли використовувати: Якщо потрібно зібрати абсолютно нову структуру, незалежну від попередніх даних. Результат доступний як Result для наступних блоків.

Copy Object From

Створення незалежної копії існуючого об’єкта.
Коли використовувати: Для безпечної модифікації даних без зміни оригіналу.
У полі Value оберіть об'єкт, який хочете скопіювати. Це ідеально підходить для трансформації відповідей від API.

Edit Existing Object

Пряме редагування оригіналу. 
Коли використовувати: Якщо потрібно внести зміни безпосередньо в існуючу змінну чи об’єкт.
У полі Value вкажіть об'єкт для редагування. Всі зміни одразу перезапишуть початкові дані.  

Дії (Actions) для формування структури

─────────────────────────────────────────────────────────────-

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

1 -> Action: Тип операції (Set, Add, Remove).

2 -> Key: Назва поля (ключа), яке ми створюємо або змінюємо (ключ може бути навіть у вкладених об'єктах).

3 -> Value: Значення (текст, число або змінна), яке записуємо в ключ.

4 -> Перемикач режиму поля:  Якщо TXT, то все обробляється як текст, якщо EXP - як вираз (наприклад, «/» у режимі TXT - це роздільник, а в режимі EXP - ділення).

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

Робота з властивостями (Objects)


Set property - Створює або змінює властивість (Key-Value) в об’єкті. Якщо ключ існує — перезаписує його значення.

Дозволяє сформувати об'єкт із властивостями і отримати такий тип даних:

object

{ "full_name": "Piter Simonson", "email": "[email protected]" }


Set property if - Створює або змінює властивість (Key-Value) в об’єкті тільки якщо виконується певна умова (наприклад, поле не пусте або дорівнює певному значенню).

Дозволяє сформувати об'єкт із властивостями якщо умова виконана і отримати такий тип даних:

object

{ "full_name": "Piter Simonson", "email": "[email protected]" }


Set property Object - Додає до поточного об’єкта інший об’єкт як значення властивості. Використовується для вкладених структур.

Дозволяє сформувати об'єкт як значення властивості іншого об'єкта і отримати такий тип даних:

object

{"customProperties":{"key":"field_string","value":"test100"}}


Set property Object From Json - Створює властивість, значення якої — об’єкт, розпарсений із JSON-рядка. Незамінно, коли API повертає дані одним текстовим блоком, який потрібно розбити на окремі змінні.

Встановлює властивість, розпарсивши JSON-рядок у JSON-об’єкт, можна отримати такий тип даних:

object

В поле Key вказуємо ключ, в який буде записано об'єкт після парсингу JSON-рядка.
В полі Value обираємо JSON-рядок, який потрібно перетворити в об’єкт.  

Робота з масивами (Arrays)


Add Value from start - Додає значення на початок масиву в поточному об’єкті. Якщо масиву не було - створює новий масив. Використовується для формування списків у зворотному порядку (наприклад, щоб нові дані завжди були першими)

Формує масив зі значень, отримуємо такий тип:

array

["https://resend.com/docs","https://resend.com/docs/integrations"]


Add Object from start -  Додає об’єкт на початок масиву в поточному об’єкті.

Формує масив всередині якого знаходяться об'єкти, отримуємо такий тип даних:

array

[{"full_name":"Piter Simonson","email":"[email protected]","phone":"15749999999"}]


Add Value at end - Додає значення в кінець масиву. Якщо масиву не було - створює новий масив. Стандартний метод для послідовного збору даних у список.

Формує масив зі значень, отримуємо такий тип:

array

["https://resend.com/docs","https://resend.com/docs/integrations"]


Add Value at end if - Додає значення в кінець масиву лише якщо умова виконується (наприклад, поле не пусте або дорівнює певному значенню).

Дозволяє сформувати масив зі значень якщо умова виконана і отримати такий тип даних:

array

["https://resend.com/docs","https://resend.com/docs/integrations"]


Add Object at end - Додає об’єкт у кінець масиву в поточному об’єкті. Використовується для збору структурованих записів у єдиний список

Формує масив всередині якого знаходять об'єкти, отримуємо такий тип даних:

array

[{"full_name":"Piter Simonson","email":"[email protected]","phone":"15749999999"}]

Видалення даних  


Remove Key - Видаляє властивість з об’єкта за його ключем. Допомагає "очистити" дані перед відправкою, щоб не передавати зайві технічні поля.


Remove Key if - Видаляє властивість з об'єкта за його ключем, якщо виконується певна умова (наприклад, поле не пусте або дорівнює певному значенню). 


Remove First / Remove Last - Видаляє перший або останній елемент масиву. Зручно для керування довжиною черги або видалення зайвих елементів.

Режими поля TXT та EXP

─────────────────────────────────────────────────────────────-

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

1. TXT (Text Mode) — Текстовий режим

Використовується для звичайних рядків, назв або URL.

• Особливість: Будь-яке значення (навіть формула або число) передається як String (текст).
• Ризик: Якщо написати функцію TO_NUMBER(123) у режимі TXT, API отримає не число, а просто набір символів "TO_NUMBER(123)".

2. EXP (Expression Mode) — Режим виразів

Перетворює поле на функціональний редактор, де працюють оператори та функції.

• Навіщо це в інтеграціях: API часто вимагають суворих типів даних (наприклад, сума замовлення має бути числом, а не текстом у лапках). Режим EXP дозволяє конвертувати типи та обробляти дані «на льоту».

Можливості EXP:

• Математика та Логіка: Обчислення значень та порівняння (>, <, ==, &&).
• Трансформація даних: Зміна регістру, пошук/заміна тексту, форматування дат.
• Робота з типами: Конвертація у числа (TO_NUMBER), булеві значення (TO_BOOL) або масиви.
• Умови: Перевірка на порожнечу (EMPTY()) або існування ключа (ISSET()).

1 -> Режим поля TXT: значення або змінні будуть оброблені як текст.

2 -> Режим поля EXP: вміст поля буде оброблено як вираз із застосуванням функцій, операторів, модифікаторів.

3 ->  Змінні: динамічні значення, які можна підставляти у вирази та передавати як аргументи функціям або як звичайні значення для полів.

4 -> Виклик зовнішньої функції: функція, що приймає аргументи та застосовується до переданих даних (наприклад, для обробки, перетворення або форматування).

5 -> Зовнішні функції та оператори: стають доступними коли режим поля EXP.

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

Швидкий старт

─────────────────────────────────────────────────────────────-

Як швидко зібрати об'єкт для HTTP Request?

1. Додайте Object Builder, оберіть New Empty Object.
2. Через Set Property додайте потрібні поля.
3. У Save Result To вкажіть {{VARS}}['my_variable'].
4. В HTTP Request (Body -> Raw JSON data) оберіть цю змінну.
5. Важливо: Застосуйте до змінної модифікатор-функцію Encode object as JSON (f:1), щоб перетворити об'єкт у формат, який зрозуміє API.

FAQ

─────────────────────────────────────────────────────────────-

1. Як використовувати результат Object Builder далі?
Результат доступний у глобальній змінній, яку ви вказали у полі Save Result To, або як результат виконання блока в цілому через Result.

2. Що обрати: Copy Object From чи Edit Existing Object?
Обирайте Copy, щоб змінити дані, зберігши оригінал незмінним. Edit використовується для прямого перезапису існуючої змінної.

3. Чому API повертає помилку структури?
API очікує JSON-рядок, а не об'єкт. У блоці HTTP Request застосуйте до вашої змінної функцію-модифікатор Encode object as JSON (f:1).

4. Як додати дані в масив без вказання індексу?
Використовуйте дії Add at end. Система автоматично знайде кінець масиву або створить новий, якщо його ще не існує.

5. Чому не працює функція (наприклад, TO_NUMBER)?
Перевірте режим поля. Функції та логіка виконуються лише в режимі EXP, тоді як у TXT вони передаються як звичайний текст.

6. Коли варто використовувати дії з умовою (Add / Remove … if)?
Умовні дії використовуються для динамічної побудови структури залежно від даних. Вони дозволяють додавати або видаляти поля лише за виконання певної умови, що особливо корисно при підготовці запитів до API з необовʼязковими параметрами.

7. Як Object Builder працює разом з Loop?
Object Builder часто використовується всередині Loop для накопичення даних. На кожній ітерації можна додавати значення або обʼєкти в масив, формуючи фінальну структуру з динамічного набору даних.