# 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](/en/actionjail/reference/actions-reference.md).
- **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](/en/actionjail/reference/actions-reference.md) — 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](/en/actionjail/how-to/admin-ai-generator-setup.md).

---

## 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:**

| Field | What to enter | Where it appears in scenario |
|-------|---------------|-----------------------------|
| **Display name** | Name users see when selecting the action | Action list, selected action name in block |
| **System ID** | Unique identifier, Latin letters, digits, underscores only. Prefix `action_` is added automatically | Used in scenarios, cannot be changed |
| **Description** | Short explanation of the action's purpose | Hints, reference guides |
| **Group** | Category for grouping. You can create a new one via "Add group" | "Select action group" filter in Action block sidebar |

**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:**
```javascript
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:
```json
{
  "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](/en/actionjail/how-to/use-saved-credential-in-custom-action.md)). Example JSON field:

```json
{
  "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](/en/actionjail/explanation/action-to-scenario-flow.md).

---

## 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](/en/actionjail/explanation/action-to-scenario-flow.md)
- [Action editor sections](/en/actionjail/explanation/action-editor-sections.md)
- [AI generator setup](/en/actionjail/how-to/admin-ai-generator-setup.md)
- [How to create and manage actions](/en/actionjail/how-to/admin-manage-actions.md)
- [Actions Reference](/en/actionjail/reference/actions-reference.md)
- [Use scenario secrets in a custom action](/en/actionjail/how-to/use-saved-credential-in-custom-action.md)