Scripts
Your catalog of saved scripts. A saved script is a script kept under a name of its own, so any number of Script steps can reference it instead of each carrying a copy—and a fix made here reaches every step that references it on its next run. This page is where saved scripts are created, found, edited, archived, and, when you keep one in a git repository or a gist, pulled and pushed. For how a step uses one, see the Script action.
The table
Scripts are listed one per row, alphabetically by name, a page at a time; the bar under the table pages through them and sets how many a page holds.
| Column | What it shows |
|---|---|
| Name | The script's name. It links to the script's form. An archived script carries an Archived badge, and appears only when Show Archived is on. |
| Language | The language the script is written in. |
| Description | The script's description, if it has one. |
| Used by | How many automations reference the script, revisions and archived automations included. A dash means none. |
| Updated | When the script was last saved. |
Finding a script
| Control | What it does |
|---|---|
| Search scripts | Full-text search over the whole script: its name, its description, and the code itself, so a script is found by a function it calls as readily as by what it was named. Results come most relevant first, with a hit on the name weighted above one on the description, and one only in the code last. |
| Show Archived | Includes archived scripts in the table. Off by default. |
Archived scripts are hidden from the table by default and are never offered to a step's picker, which makes this page the only place to find one again—that is what Show Archived is for. A step that already references an archived script keeps running it; archiving stops offering a script, it does not break the steps that use it. Archive and restore are actions on the script's own form.
Creating a script
+ New Script at the top right opens an empty form. You can also create a script from a Script step's own editor with Save to Scripts…, which opens this form with the step's code already in place—see Moving code between a step and the catalog.
The form
| Field | What it does |
|---|---|
| Name | How the script is listed and picked. Names are unique within the workspace; the form refuses a name another script already has. |
| Description | One line shown beside the name in the table and in a step's picker, where it is what tells two similarly named scripts apart. |
| Language | The language the script is written in. Choosing JavaScript reveals its Script field, holding the source, with the same syntax check and sandbox note a step's own editor has. |
| Kept in | Optional. Where this script is also kept outside Esca: a Repository file or a Gist / Snippet. See Keeping a script in a repository or a gist. |
Above the form, once the script has been saved, a note lists the automations that use it, each linking to its editor. Check it before an edit: a saved script is referenced live, so the change reaches every one of them on their next run.
A script that at least one automation references cannot be deleted; the form says which ones. Archive it instead, or change those automations first.
Keeping a script in a repository or a gist
A saved script can be kept in step with a file elsewhere: a path on a branch of a git repository, or a file in a GitHub gist. Set Kept in on the form, save, and the form gains a panel naming the file with three actions.
| Action | What it does |
|---|---|
| Pull | Replaces this script's code with the file's, and records the sync. If the code here has changed since the last sync, the panel asks first. |
| Push | Writes this script's code to the file as one commit—with the Message you type, or Update <name> when you leave it empty—and records the sync. For a gist that does not exist yet, Push creates it and records its id; the message becomes the gist's description. |
| Check remote | Asks whether the file has changed since the last sync, without changing anything. |
The panel's status line says where the script stands: never pulled or pushed, in step as of a moment, or changed here since the last sync. Nothing here runs at run time; a step always runs whatever the catalog holds, and pulling is how you bring a change in.
A push is refused when the file has changed on the host since the last pull, and when the file already exists but has never been pulled—in both cases nothing is known about what would be overwritten. Pull first, then push.
Repository file
| Field | What it does |
|---|---|
| Connection | A connection to a service that hosts git repositories—a GitHub connection, with either kind of authentication. |
| Repository | The repository, in the host's own naming: owner/name on GitHub. |
| Branch | The branch to read from and write to. Leave empty for the repository's default branch. |
| Path | The file's path within the repository, such as scripts/slugify.js. |
Gist / Snippet
| Field | What it does |
|---|---|
| Connection | A connection to a service that hosts snippets and whose credential can reach them. A GitHub connection qualifies when it authenticates with a personal access token; an App Installation cannot reach gists and is not offered. Pushing needs the token to be allowed to write gists: for a fine-grained token, the Gists permission under Account permissions set to Read and write; for a classic token, the gist scope. Reading needs neither, so a pull can succeed where a push is refused. |
| Gist / Snippet ID | The gist's id. Leave it empty and the first Push creates the gist and fills this in. |
| File Name | The file within the gist, such as slugify.js. |
| Public | Whether a gist created by the first push is public. An existing gist keeps its visibility. |
A gist has no way to refuse a write over a file that has moved, so Esca checks the file just before writing. A change that lands in the moment between the check and the write is overwritten.
Moving code between a step and the catalog
A Script step whose source is Inline offers two links under its editor:
- Insert from Scripts… opens a picker over the catalog. Choosing a script copies its code into the step's editor, replacing what was there after asking. It is a copy: the step does not follow later edits to the saved script. To follow them, switch the step's source to Saved and pick the script instead.
- Save to Scripts… opens the new-script form with the step's code already in the editor. Name it and save; the step is unchanged, and the script is now in the catalog for any step to reference.
Scripts kept elsewhere
Object storage and other places Esca has no connection to are not part of this catalog, by design. Fetch the file with whatever step can reach it—an HTTP Request, a GitHub Get File Contents action, an AWS action—and give the Script step a Runtime source bound to that output. See Where the script comes from.