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 Jail.
• 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 Jail.
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.

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/edit fields via the visual list (ParametersList).

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

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