How Action Jail Data Flows to Scenario Builder

When you create an action in Action Jail and add it to a scenario, the data from the action editor is transformed into the parameter form in the Action block. This page explains how this happens, where each field appears, and why the structure is designed this way.

Context and Problem

When a scenario user (analyst, implementation) adds an Action block and selects an action from the library, they need to:

• See clear fields for entering parameters (email, subject, number, choice).
• Avoid writing JSON manually when a form is available.
• Understand how form values are passed to the action code.

The administrator creating the action in Action Jail must configure:

• Implementation code (JavaScript).
• Parameter schema (what the code expects).
• How these parameters are displayed in the form (labels, fields, groups).

Problem: Without understanding the link between Action Jail fields and what the scenario user sees, you may create an action with incorrect configuration — the form will be empty or parameters will not reach the code.

Key Concepts

What is Stored in Action Jail

Each action stores:

• Information — name, system ID, description, group.
• Code — JavaScript function that runs on the backend.
• JSON configuration — parameter schema (parameters), grouping (ui.groups), example (json_example).
• UI schema — visual representation of the same parameters (synchronized with JSON).
• Documentation — Markdown for reference guides.

What is Stored in the Scenario Node

When you add an Action block to a scenario and select an action:

• The node stores only templateId (action name) + parameter values (values).
• The parameter schema (types, fields, groups) is not copied into the node — it is dynamically loaded from Action Jail when the block is opened.

Why: If an administrator changes an action's parameter schema (adds a field, changes type), all scenarios using that action automatically get the updated form. No need to update each scenario separately.

Data Flow: Action Jail → Scenario Builder

┌─────────────────────────────────────────────────────────────────────────────┐
│  Action Jail (action editor)                                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│  Information: displayName, name, description, group_id                       │
│  Code: action_xxx()                                                          │
│  JSON config: parameters, ui.groups, json_example, events_schema             │
│  Documentation: Markdown                                                     │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    │  Stored in action library
                                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Action block in scenario                                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│  node.data:                                                                  │
│    templateId: "action_send_email"   ← reference to action                   │
│    templateConfig.values: { to: "...", subject: "..." }  ← values only      │
│                                                                              │
│  When block is opened:                                                       │
│    → parameters loaded from Action Jail (dynamically)                       │
│    → form built from parameters + ui.groups                                  │
│    → values filled into form fields                                         │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: User Opens the Action Block

The system:

1. Reads templateId from the node (e.g. action_send_email).
2. Loads full action info from Action Jail: parameters, ui, json_example.
3. If parameters exist — shows Form mode (form fields).
4. If parameters are empty — shows JSON mode (Monaco editor).

Step 2: Form Built from parameters + ui.groups

Each item in parameters becomes a form field:

• type: "string" → text input
• type: "number" → number input
• type: "boolean" → switch
• type: "select" → dropdown

Groups from ui.groups are displayed as accordion sections. Fields from parameters are distributed across groups by the key field in the group.

Step 3: User Enters Values

When the user changes a form field:

• The value is saved in templateConfig.values (values only, no schema).
• When the scenario runs, the Engine passes values to the action code via this.getCurrentNodeParamsJSON().

Step 4: Action Code Receives Parameters

In the action code:

const { to, subject } = this.getCurrentNodeParamsJSON();

The keys to, subject are the same key or name from parameters in the JSON config. Values come from templateConfig.values.

Where Each Field Appears

Edit Modes: Form ↔ JSON

The Action block has two modes:

• Form — form fields built from parameters. Convenient for most users.
• JSON — direct JSON input. User sees and edits templateConfig.values (values only).

Both modes are synchronized: changes in the form update JSON, changes in JSON update the form. The parameter schema always comes from Action Jail, not from the node.

Implications for Administrators

When creating an action:

• Ensure keys in parameters match what the code reads via getCurrentNodeParamsJSON().
• If the code has const { email } = this.getCurrentNodeParamsJSON(), then parameters must have a field with key: "email" or name: "email".

When changing the schema:

• Adding a new parameter — all scenarios get the new field in the form.
• Removing a parameter — old values in scenarios are ignored; the code will not receive this key.
• Changing type — the form updates; verify that existing values in scenarios are valid.

When an Action Will Not Run: the Chat Is Already With an Operator

An action in a scenario runs only while the scenario controls the chat. As soon as the chat is handed to the operator panel (connect-to-operator node, handoff to Fast Line, or transfer to a skill group), the engine stops advancing the scenario position for that chat — so the bot does not talk over a live operator.

What this means for the action author:

• An action placed on the canvas after the handoff will not run — neither immediately nor on a timer.
• No error is raised: the scenario simply freezes in place, and the log looks normal.
• This applies both to delayed transitions (interval/timer nodes) and to custom Action Jail actions.

How to check whether your action is in this trap. Trace the path from the start node to your action: if there is a connect-to-operator node or a handoff to Fast Line in between, the action is unreachable.

What to do instead: build logic that has to run after the handoff with operator panel tools — timers, automatic rules, statuses — not as a continuation of the scenario. For auto-closing inactive chats, use operator panel timers.

Related Documents

• Action editor sections — what to fill in each section
• Handing the chat to a live operator — what happens to the scenario after the handoff to an operator
• How to create a custom action — step-by-step guide
• Actions Reference — standard actions reference