# 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:
```javascript
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

| Action Jail field | Where it appears in Scenario Builder | Note |
|-------------------|--------------------------------------|------|
| **Display name** | Action selection when adding block, selected action name in block | User sees this name |
| **Group** | "Select action group" filter in Action block sidebar | Helps find the action quickly |
| **Description** | Hints, reference guides | Not shown directly in the form |
| **parameters[].key** | Key in `values` read by code via `getCurrentNodeParamsJSON()` | Must match what the code expects |
| **parameters[].label** | Field label in form | |
| **parameters[].placeholder** | Input placeholder | |
| **parameters[].type** | Widget type (input, number, switch, select) | |
| **ui.groups** | Accordion sections in parameter form | Field grouping |
| **json_example** | Default values on first open | |
| **events_schema** | Possible values for routing (e.g. success → next block) | |

---

## 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](/en/settings/how-to/configure-timers.md).

---

## Related Documents

- [Action editor sections](/en/actionjail/explanation/action-editor-sections.md) — what to fill in each section
- [Handing the chat to a live operator](/en/scenariobuilder/explanation/connect-to-operator-node.md) — what happens to the scenario after the handoff to an operator
- [How to create a custom action](/en/actionjail/how-to/create-custom-action.md) — step-by-step guide
- [Actions Reference](/en/actionjail/reference/actions-reference.md) — standard actions reference