How to Create a Custom Action in Action Jail

This guide helps you create a new action from scratch — manually or using AI generation. All wizard fields and their purpose are described.

When to Use

• You need business logic or integration that is not among standard actions.
• You have a logic description but are unsure how to structure the code and parameters.
• You want to use AI for a code, config, or documentation draft.

What to Know

• Check standard actions first — the platform has a library of 98 standard actions. If a standard action fits, do not create a custom one. See Actions Reference.
• System ID cannot be changed after creation — choose the name carefully.
• Parameter keys in the JSON config must match what the code reads via getCurrentNodeParamsJSON().

Before You Start

• You have a role with access to Menu -> Action Library.
• You have checked Actions Reference — no standard action fits.
• You have a logic description: what the action should do, what input data it needs.
• For AI generation: OpenAI token configured for the selected process (bot). See AI generator setup.

Step-by-Step Instructions

Step 1. Open the Wizard

1. Go to Menu -> Action Library.
2. Click Add new action.
3. The wizard opens with five sections (accordions).

Step 2. Action Information

Fields:

Example: Display name — "Language check", system ID — check_language, group — "Validation".

Step 3. Implementation Code

What to write:

• JavaScript function starting with action_ and exported via module.exports.
• Get parameters via this.getCurrentNodeParamsJSON().
• Scenario constants via this.getCurrentConstJSON().

Path 1 — Manual:

async function action_check_language(params) {
  const { language_code } = this.getCurrentNodeParamsJSON();
  // validation logic
  return language_code === 'uk' ? 'success' : 'error';
}
module.exports = action_check_language;

Path 2 — AI generation:

1. Fill in display name and description in the "Information" section.
2. Expand the "Implementation Code" section.
3. Click Quick Generate or Generate Code.
4. Review and edit the generated code.

If the code is long, click Open code in fullscreen in the lower panel header — the editor opens in a larger window and stays in sync with the lower panel.

Important: Keys from getCurrentNodeParamsJSON() (e.g. language_code) must later be added to the JSON config as parameters.

Step 4. JSON Configuration

What to set:

• parameters — array of objects. Each object: key (or name), type, label, required, description, defaultValue, etc.
• ui.groups — field grouping for the form (accordion).
• json_example — example of valid JSON.
• events_schema — possible return values for routing (success, error, etc.).

Path 1 — Manual: Edit the JSON in the editor. Minimal example:

{
  "parameters": [
    {
      "key": "language_code",
      "type": "string",
      "label": "Language code",
      "required": true,
      "description": "Language code to check (uk, en, ru)"
    }
  ],
  "ui": {
    "layout": "accordion",
    "groups": [
      {
        "id": "main",
        "title": "Main parameters",
        "fields": ["language_code"]
      }
    ]
  },
  "json_example": { "language_code": "uk" },
  "events_schema": [
    { "name": "success", "label": "Success", "description": "Language matches" },
    { "name": "error", "label": "Error", "description": "Language does not match" }
  ]
}

Path 2 — AI generation:

1. Fill in the code in the "Implementation Code" section.
2. Expand the "JSON Configuration" section.
3. Click Generate from Code.
4. AI analyzes the code and extracts parameters from getCurrentNodeParamsJSON() into a JSON schema.
5. Review and edit the result.

Step 5. UI Schema

The UI schema is the visual representation of parameters and ui.groups. It is usually synchronized with the JSON config automatically.

• If you edited the JSON — verify that fields in the UI schema display correctly.
• You can add and edit fields in the visual parameter list.

Field types: string, number, boolean, textarea, select, url, Credential, etc. Each type maps to a specific widget in the Scenario Builder form.

Credential-type parameter — integrators pick a record from Scenario secrets instead of typing a token. In action code use server-side helpers (see use scenario secrets in a custom action). Example JSON field:

{
  "key": "api_credential_slug",
  "type": "credential",
  "label": "API secret",
  "required": true,
  "store": "slug"
}

Step 6. Documentation

What to write:

• Markdown: action description, parameters, usage example, return values.

Path 1 — Manual: Write the text in the Markdown editor.

Path 2 — AI generation:

1. Click Generate Documentation.
2. AI creates Markdown from the name, code, and parameters.
3. Edit as needed.

Step 7. Save and Test

1. Click Complete (for new action) or Save (for editing).
2. Open the Testing section (for custom actions).
3. Enter test parameters (JSON or full state) and click Test Action.
4. Check the result, logs, and errors.

What Happens Next

• The action appears in the Action Jail library.
• It can be selected in the Action block in the Scenario Builder.
• Form fields will be built from parameters and ui.groups — see How Action Jail data flows to Scenario Builder.

How to Verify Success

• The action appears in the library and opens without errors.
• System ID is unique.
• The Action block in the scenario shows form fields with correct labels.
• Testing succeeds with test parameters.

Other Options

• Cloning — if there is a similar action, select it → Make a copy → change code and parameters.
• AI generation — for code, config, and documentation drafts; always verify the result manually.

Related Instructions

• How Action Jail data flows to Scenario Builder
• Action editor sections
• AI generator setup
• How to create and manage actions
• Actions Reference
• Use scenario secrets in a custom action