Handlers¶
A script's handlers are what start it, besides someone running it (#2441,
2434, #2435). There are three kinds, and three more an administrator binds to¶
a connection so the script runs for other people's calls on it: a policy
decides whether a call runs, a transform changes what it returns, and a
watch runs the script after it (Tool-call handlers, #2436,
2634, #2635). A seventh, integration, is the script an administrator¶
chooses for an operation in Admin > Settings > Integrations (Integrations, #2659): it is listed among the script's handlers and held to its function by the save gate, and it is chosen, changed and cleared on the settings page, not with the handler commands:
| Kind | Starts the script | The script defines | Settings | Who adds one |
|---|---|---|---|---|
endpoint |
Each request to /endpoints/<endpoint>/... (Endpoints) |
handle(req), or form_spec(req) and form_submit(req, values) on a form |
endpoint, methods, path, auth_mode and the rest of the endpoint settings; a form adds connection and decrypt_personas |
An administrator; a form's owner on their own form |
schedule |
Each fire of a cadence (Running one on a schedule) | main() |
cron, timezone, args |
The script's owner or an administrator |
webhook |
Each event a webhook source stores (Running one for each event) | main(), reading run.event |
event_source |
The script's owner or an administrator; anyone but an administrator only for the source of a form whose script they own |
A form is not a kind of its own. An endpoint whose script defines form_spec
and form_submit is a form, and every list reports its type as form rather
than endpoint.
flowchart LR
R["request to /endpoints/name"] --> E["endpoint handler"]
C["cron fire"] --> S["schedule handler"]
V["event a webhook source stores"] --> W["webhook handler"]
E --> X["the script's latest saved version"]
S --> X
W --> X
A script may hold several handlers of each kind, at most 20 of a kind
(internal/platform/scripthandler, MaxPerKind): two schedules fire on two
cadences, two endpoint handlers answer on two names, and one script may run for
several webhook sources while several scripts run for one. Every handler starts
the script's latest saved version (in a released application, the version the
release pins; a public form serves a caller with no session its approved
version) under the roles its author held at the save; a handler carries no
authority of its own.
Each kind keeps its own table: script_endpoints, script_schedules and
script_webhook_handlers. Migration 000247 dropped the one-per-script
constraint on the first two, moved each script's scripts.event_source into a
webhook handler and dropped the column, and added the read-only view
script_handlers every handler list reads.
The commands¶
manage_script command |
Does |
|---|---|
handler_set |
Adds a handler of kind with that kind's settings, or changes the one handler names |
handler_list |
One script's handlers (name), each described as handler_get describes it; with no name, the handlers of the caller's scripts (every script's for an administrator); kind narrows to one kind |
handler_get |
One handler, by its id (handler) |
handler_enable, handler_disable |
Turns one handler on or off, by its id; a disabled endpoint answers 404 and a disabled schedule or webhook handler starts nothing |
handler_delete |
Removes one handler, by its id |
form_preview |
Opens a preview of the script's form (Publishing a form) |
{"command": "handler_set", "name": "daily-sales", "kind": "schedule",
"cron": "0 7 * * 1-5", "timezone": "America/Los_Angeles", "args": {"report_date": "${fire_date}"}}
handler_set answers with the handler it set, its id in handler. What it
does with no handler depends on the kind:
- endpoint: it changes the script's endpoint handler with the name sent in
endpoint, or the script's only one when no name is sent, and otherwise adds one. A script with several endpoint handlers and no name sent is refused, naming them. A name another script holds is refused, naming the handler that holds it and its script. - schedule: it adds a schedule. A schedule with the same cron, timezone and
args as one the script already holds is refused, naming that one, since a
repeated call would otherwise double the runs. With
handler, it replaces that schedule's cadence in place, and the runs it produced keep pointing at it. - webhook: it runs the script for the source. Adding a source the script
already runs for keeps its handler and turns it on. With
handler, nothing changes: a handler's source does not change, and saving a handler that is off leaves it off (handler_enableturns it on). To move a script to another source, add a handler for the new source and delete the old one.
handler_list with kind=endpoint includes forms. Its rows without name
carry each handler's id, kind, type, script_id, script_name,
owner_email, target (an endpoint's name, a schedule's cron and timezone, a
webhook handler's source), enabled, created_by and created_at, with
count and total.
handler_delete removes an endpoint handler with its failed and refused
requests; /endpoints/<name> answers nothing from then on, and a form's webhook
source and the submissions in it stay. A webhook handler's deletion leaves the
runs its events started. A schedule that produced runs is not deleted, because
its runs name it: the refusal says to disable it with handler_disable.
Who may add or change a handler is the kind's rule in the table above, on every
surface. The handler commands and routes act on a script's handlers for its
owner and administrators only; anyone else reads a script's schedules and
endpoints where the listing and its contract show them. A script run may read
handlers (handler_list, handler_get) and is
refused handler_set, handler_enable, handler_disable and
handler_delete, as it is refused every command that writes a script.
The commands they replaced¶
endpoint_set, endpoint_list, endpoint_enable, endpoint_disable,
schedule_set, schedule_list, schedule_enable and schedule_disable were
removed with no alias. A call to one is refused, naming its replacement:
manage_script update with event_source is refused the same way, naming
handler_set kind=webhook event_source=<source>. A kind's settings keep the
parameter names the old commands took.
What a save checks¶
A save is refused when the new version could not serve a handler the script
holds, naming the handler: an endpoint handler needs handle(req), and a form
needs form_spec(req) and form_submit(req, values). A form script stays a
form while it holds an endpoint handler; to make it something else, delete the
handler first. The check runs on every save, from manage_script and from the
portal's editor alike.
In the portal¶
A script's page has a Handlers section in place of the separate endpoint, schedule and events sections it had before. Each handler is a row with its type badge (Endpoint, Form, Schedule, Webhook, Policy, Transform or Watch), what it answers to (an endpoint's path, a schedule in words, "Each event of" a webhook handler's source, a tool-call handler's connection and operations) and On or Off. Opening a row shows that kind's controls: an endpoint's settings, the schedule builder with Pause and Resume, a webhook handler's switch with how its event runs stand, and Delete. Add handler offers each kind, and shows the reason beside a kind the viewer may not add. Adding an endpoint to a form offers Preview form and Request public access first.
The Automations list shows each script's type badges beside its name and narrows by Filter by type: Endpoint, Form, Schedule, Webhook, Policy, Transform, Watch, or None for a script with no handler. A script with a form and a schedule shows both badges and is listed under both. The schedule and endpoint columns show a script's first one and say how many more it has.
Admin > Automations > Handlers (/portal/admin/automations/handlers) lists
every handler of every script, filtered by type, a search over the script's name
and the target, owner, and state (On or Off); a row opens its script.
Routes¶
| Route | Does |
|---|---|
GET /api/v1/portal/scripts/{id}/handlers |
The script's handlers, each as its kind describes it with type; add, each kind with whether the caller may add one and why not; endpoint, where a page would answer and a form's connections; sources, the webhook sources the caller may name; max_per_kind |
POST /api/v1/portal/scripts/{id}/handlers |
Adds a handler: kind and that kind's settings, named as manage_script names them (201) |
GET, PUT, DELETE /api/v1/portal/handlers/{id} |
Reads, changes or deletes one handler |
POST /api/v1/portal/handlers/{id}/enable, .../disable |
Turns one handler on or off |
GET /api/v1/admin/handlers |
Every handler, administrators only; type (repeatable), search, owner, enabled, limit (default and most 500) and offset; answers data and total |
The portal routes are the script's owner's and an administrator's. A refusal by a kind's rule answers 403, a handler or script that does not exist 404, and a request that names something wrongly 400.
GET /api/v1/portal/scripts takes type, repeatable: the scripts holding a
handler of any of the types named (endpoint, form, schedule, webhook,
policy, transform, watch),
and none for the scripts holding none. Each row carries handler_types,
schedules and endpoints, each [] when empty. endpoint= was removed and
is answered 400. A script's contract (what fetch on its reference returns)
lists its cadences under schedules.
These routes were removed, and the handler routes above replace them: GET and PUT
/api/v1/portal/scripts/{id}/endpoint and .../endpoint/enable|disable, GET
and PUT /api/v1/portal/scripts/{id}/schedule and .../schedule/enable|disable,
PUT /api/v1/portal/scripts/{id}/event-source, GET
/api/v1/admin/scripts/schedules, and GET and PUT
/api/v1/admin/scripts/{id}/schedule and .../schedule/enable|disable.
In an application bundle¶
An application bundle at format_version 2 lists each script's handlers under
handlers: endpoints, schedules and webhooks (each source by name, mapped
on import like every other name). Import reads versions 1 and 2; a version 1
bundle's one endpoint, one schedule and one event_source per script become one
handler each. An import gives each script its handlers as handler_set does,
with the importing administrator's authority: a handler the script already holds
(an endpoint by name, a schedule by cadence and args, a webhook handler by
source) is changed in place, one it holds that the bundle does not name is left,
and each is turned on or off as the bundle holds it. See
Applications.