> ## Documentation Index
> Fetch the complete documentation index at: https://docs.insight.nobly.dk/llms.txt
> Use this file to discover all available pages before exploring further.

# Script Engine

> Choose a script extension point, grant administration access, and understand how saved versions become live behavior.

The Script Engine runs Python logic that you attach to indexing, Caseflow forms, document events, or workflows. You manage scripts in **Admin settings → Script Engine → Scripts**. A script is reusable logic; a **binding** or a reference from a form or workflow determines where it runs.

## Prerequisites and access

The Script Engine must be available in your environment. The client currently also requires the Caseflow area to be enabled to expose these settings. If the section is missing despite the permissions below, ask your environment administrator to check availability.

Grant application permissions to the appropriate user groups in [Managing permissions](/permissions/managing-permissions):

| Permission             | Allows                                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| `script-engine.view`   | Inspect scripts, saved versions, bindings, and execution logs                                    |
| `script-engine.manage` | View access plus create and edit scripts, save versions, publish, roll back, and manage bindings |
| `script-engine.admin`  | All Script Engine permissions, including secret administration                                   |

These permissions govern administration. They do not replace the permissions needed to access documents or objects when a script calls Insight.

## Choose the extension point

| Script type in the Scripts screen | Use it for                                             | Result                                                     |
| --------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------- |
| `external_autofill`               | Look up related keyword values from an external source | Matching rows keyed by keyword type ID, plus a total count |
| `caseflow_autofill`               | Populate Caseflow attributes when a field changes      | A `values` map keyed by attribute name                     |
| `caseflow_action`                 | A Caseflow button or action-chain operation            | Success, an optional message, and optional data            |
| `workflow_action`                 | Logic invoked by a workflow's Script.Run action        | A JSON object that subsequent workflow steps can use       |
| `event_hook`                      | Background processing after a document event           | An acknowledgement and optional message                    |

The engine also supports dataset and workflow-selector contracts. These are not currently offered by the client's Scripts type selector; do not look for them in that dropdown.

## Choose a first exercise

| Your starting point                           | Follow                                                                          |
| --------------------------------------------- | ------------------------------------------------------------------------------- |
| A form field needs normalization              | [Caseflow reference example](/scripts/examples#normalize-a-caseflow-reference)  |
| A workflow needs a calculated decision        | [Workflow action example](/scripts/examples#return-a-workflow-decision)         |
| You need to confirm an event reaches a script | [Event acknowledgement example](/scripts/examples#acknowledge-a-document-event) |

Begin with an input-only example before adding external API calls. That lets you distinguish a caller or binding problem from a connection or credential problem.

## The lifecycle

1. **Create** the script record and choose its type.
2. **Push Version** to save source code and run validation. This does not make the code live.
3. Exercise the behavior in a test environment through its intended form, indexing operation, event, or workflow.
4. **Publish** a validated saved version, then connect it to the intended extension point.
5. Inspect execution logs and the resulting business data. Publish a corrected version or roll back when necessary.

A new saved version does not replace the published version. Production execution by binding or script slug resolves the script's published version.

```mermaid theme={null}
flowchart LR
  A[Choose caller and contract] --> B[Edit source]
  B --> C[Push version]
  C --> D[Check syntax and contract]
  D --> E[Publish saved version]
  E --> F[Verify consuming operation]
  F --> G[Inspect execution log]
```

## Where to read next

<Card title="Authoring and publishing scripts" icon="code" href="/scripts/authoring-and-publishing" horizontal>
  Create a script, save and validate its source, publish a version, and restore an earlier version.
</Card>