Як використати збережені секрети в кастомній дії Action Jail?

Кастомні дії з Бібліотеки дій можуть брати API-ключі, токени та паролі з Секретів для сценаріїв (Налаштування). У сценарії зберігається лише посилання на запис; розшифрування відбувається на сервері під час виконання дії.

Коли знадобиться

• Custom action викликає зовнішній API і потрібен Bearer, Basic, API key або кілька секретів одночасно.
• Один і той самий секрет використовують кілька сценаріїв — після Ротації секрету не треба змінювати код дії.
• У коді дії або в параметрах ноди досі лежить «голий» токен — треба перенести його в Секрети для сценаріїв.

Що важливо знати

• Можливість увімкнена адміністратором інстансу (перемикачі функцій у Налаштування інстансу). Без цього параметр типу Credential і посилання на секрети недоступні.
• У записі секрету в Дозволені споживачі має бути дозволена ваша custom action або Усі дії (action:*) — якщо політика інстансу це дозволяє.
• У JSON-конфігу дії додайте параметр з типом Credential — у Scenario Builder інтегратор обере запис зі списку, без вводу секрету вручну.
• У коді дії не зберігайте токени в рядках. Під час виконання використовуйте серверні helpers (фрагменти коду є в Налаштування → Секрети для сценаріїв після Сканувати застарілі секрети).
• Для HTTP-запитів у custom JS посилання на секрет у полях запиту ({{credentials.slug.field}}) потрібно явно обробити перед відправкою — на відміну від ноди Send Request, де це робиться автоматично.
• OAuth2 з обміном токена (client credentials flow) у v1 не налаштовується одним кліком — його реалізують у коді custom action; inline можна підставити лише client_id / client_secret.

Перед початком

• Адміністратор увімкнув Секрети для сценаріїв і створив потрібний запис (див. керування секретами).
• У Дозволені споживачі запису дозволена ваша custom action.
• У вас є доступ до Бібліотеки дій для редагування коду та JSON-конфігу.
• Custom action уже створена або ви готові додати нову (див. створити custom action).

Покрокова інструкція

1. Створити або оновити секрет для custom action

1. Відкрийте Налаштування → Секрети для сценаріїв.
2. Натисніть Додати секрет або відредагуйте існуючий запис.
3. У Дозволені споживачі додайте назву вашої custom action зі списку або залиште Усі дії (action:*), якщо політика інстансу це дозволяє.
4. Збережіть запис і запам’ятайте slug (наприклад, crm-api-prod).

2. Додати параметр типу Credential у JSON-конфіг

1. Відкрийте custom action у Бібліотеці дій.
2. У секції JSON конфігурація додайте параметр з "type": "credential":

{
  "parameters": [
    {
      "key": "crm_credential_slug",
      "type": "credential",
      "label": "CRM API секрет",
      "required": true,
      "description": "Bearer-токен для CRM API",
      "store": "slug"
    }
  ]
}

3. У списку параметрів (UI схема) для поля типу Credential задайте:
   • Зберігання (slug/id) — зазвичай slug, щоб сценарій не залежав від внутрішнього id запису;
   • поле Consumer — поточна custom action (за замовчуванням підставляється автоматично).
4. Збережіть дію.

3. Отримати секрет у коді дії

1. У Код реалізації читайте параметри через this.getCurrentNodeParamsJSON().
2. Для HTTP-автентифікації (Bearer, Basic, API key у заголовку) використовуйте helper для готових заголовків — приклад з’являється в Секрети для сценаріїв після сканування legacy або в підказках міграції:

async function action_my_integration() {
  const params = this.getCurrentNodeParamsJSON();
  const headers = await this.getInstanceCredentialHeaders(params.crm_credential_slug);
  // далі — HTTP-запит з headers
  return 'success';
}
module.exports = action_my_integration;

3. Для одного поля (токен бота, client_secret тощо) — helper для окремого поля з тим самим slug.
4. Для SMTP або кількох полів одразу — helper для повного payload (використовуйте лише коли справді потрібно кілька полів).

Точні назви helpers і приклади для вашого типу секрету скопіюйте з Налаштування → Секрети для сценаріїв → Сканувати застарілі секрети (вкладка Кастомні дії (Action Jail)) — там slug підставляється без розкриття значення.

4. Inline-посилання в параметрах HTTP (за потреби)

Якщо параметри дії містять URL, заголовки або body з маркерами посилання на секрет (як у Send Request):

1. У Scenario Builder або в Тестуванні дії вставте Вставити посилання на секрет у потрібне поле параметра.
2. У коді перед відправкою HTTP викличте helper для обробки таких маркерів у вашому об’єкті запиту (наприклад, body або headers), потім відправте запит.

Без цього кроку маркери залишаться текстом і запит не автентифікується.

5. Підключити дію в сценарії

1. У Scenario Builder додайте ноду Action з вашою custom action.
2. У полі CRM API секрет (або іншій назві параметра типу Credential) оберіть запис зі списку.
3. Збережіть сценарій і протестуйте (див. підключити дію до сценарію).

6. Протестувати в Action Jail

1. Відкрийте розділ Тестування у редакторі дії.
2. Для параметра типу Credential оберіть запис або вставте посилання на поле секрету.
3. Натисніть Test Action — у виводі секрети замасковані; перевірте статус успіху та логи.

Сканування та міграція з inline-секретів

1. У Секрети для сценаріїв натисніть Сканувати застарілі секрети.
2. Відкрийте вкладку Кастомні дії (Action Jail) — там замасковані зразки і готові фрагменти коду для заміни inline-токенів.
3. Створіть запис секрету потрібного типу, оновіть код дії, збережіть і повторіть тест.

Пов’язані статті

• Керувати секретами для сценаріїв
• Що таке секрети для сценаріїв
• Використати секрет у Send Request
• Створити custom action
• Підключити дію до сценарію