Alias Grammar
A schedule may carry an optionalalias — a short, stable name usable anywhere the schedule’s
id is accepted.
The 6-character floor rejects the names most people try first:
main, dev, prod and ci are
all too short and are refused. primary, default, staging, daily_report and
nightly-build all clear it. The alias is optional — a schedule without one simply omits alias
from responses, rather than carrying it as null.
The shape rule catches what the character and length rules let through: a string built entirely
from lowercase hex and hyphens can still satisfy both, if it happens to fall into a generated id’s
exact 36-character pattern. 8f14e45f-cee4-4b0b-8f8a-8e3b1a2c3d4e is 36 characters of a–f hex
and hyphens and would otherwise be a legal alias — it is refused, and so is the all-zeros case
00000000-0000-0000-0000-000000000000, which isn’t even a real id. Aliases and ids share one
namespace, and the platform tells them apart by shape alone, so the two can never be allowed to
overlap.
The grammar is enforced when an alias is set — at create and at rename. Reads normalize case
and surrounding whitespace before resolving, so a lookup does not have to match the stored value
byte-for-byte.
A schedule’s own alias is not the only “alias” in view here. invocation_target.workflow carries its own
definition field — an id or an alias, per The workflow
reference — naming the workflow the schedule invokes when it
fires; create_execution’s own workflow.definition names the same concept elsewhere. When a schedule’s alias and
its invocation_target.workflow.definition appear side by side — as they do on every schedule response — they name
two different things: the schedule itself, and the workflow it invokes. Read alias at the top level of a schedule as
the schedule’s own name; read workflow.definition inside invocation_target as the target it runs.
Workflow sessions support the same optional alias, with the same grammar. Workflow definition aliases share
the same shape restriction too — see Create Definition and
Update Definition. get_session,
update_session, close_session, reopen_session, delete_session, get_schedule,
update_schedule and delete_schedule all accept an id or an alias in their session_id /
schedule_id parameter — every command that addresses the object itself. create_execution takes a session id or
alias too, in target.session, resolved in the route’s revision: the session is where the execution runs.
Everything else is id only, including list_executions, list_session_events, and every
session-object, thread and graph command: these address content inside a session or schedule
rather than the object itself, so a caller resolves the alias once — on the command that returns
the object — and holds the id from there on.
This is the session’s or schedule’s own alias, not to be confused with a session object’s
alias — the path-style name given to individual objects stored inside a session, documented in
Session Objects.
The two grammars are deliberately incompatible: that one allows slashes, dots and uppercase that
this one forbids, so a value valid under one can never be mistaken for the other.
Alias resolution reads a secondary index and is eventually consistent: creating an object with an
alias and immediately addressing it by that alias can fail briefly. Hold the id the create call
returns rather than re-resolving by alias on every call.
Schedule Types
A schedule fires either once or on a recurring cadence. Therepeat field controls which:
one_time— fires once at a specifiedinvocation_time. After firing, the schedule transitions to thecompletedstate.recurring_cron— fires repeatedly based on acron_expression. Staysactiveuntil deleted, or untilend_dateis reached (if provided).
Cron Expressions
Recurring schedules use the AWS EventBridge Scheduler six-field cron format:cron_expression. A few common examples:
Either
day-of-month or day-of-week must be ? (AWS cron does not allow both to be specified).
Timezones
Every schedule requires an IANA timezone string in thetimezone field (for example, America/New_York, Europe/London, or UTC). Both cron expressions and one-time invocation times are evaluated in this timezone.
Date Windowing
Schedules accept optionalstart_date and end_date fields (ISO 8601, UTC) that constrain when the schedule is active:
- Before
start_date, the schedule does not fire. - After
end_date, the schedule does not fire. A recurring schedule automatically transitions to thecompletedstate onceend_dateis passed.
Description
A schedule may carry an optionaldescription of at most 256 characters. It describes the schedule, and every
fire sends it as the new execution’s description on
Create Execution; each run in the
execution history records the description its fire sent. It is not part of the invocation
target.
Invocation Targets
A schedule invokes a target each time it fires. The currently supported target type isworkflow, which
creates a workflow execution on a target blob revision. A target is either pinned to one revision, or
following — it names the target blob’s default revision and resolves it fresh on every fire.
The invocation_target object says where the schedule runs and what it runs:
target has the following fields:
Neither object admits a key it does not list. Every field of
target is a non-blank string of at most 64
characters; a blank, over-length or non-string value is refused with 400 invalid_request_body.
globex’s support-bot blob, following its default revision, and runs acme-corp’s triage
definition from the default revision of procedures.
A pinned target (target.revision is a UUID): target.session is resolved once, at save time, and rewritten
in place to its UUID, so every later fire reuses the exact session resolved then. A following target
(target.revision is default) pins nothing — target.session stays the alias it was sent as, and every fire
re-resolves the target blob’s default revision, then the session alias inside it, then the workflow reference,
from scratch.
Stored as written, resolved at every use. A blob alias is not rewritten to an id at save time — it matches
workflow, which has to be resolved at every fire anyway for default to follow. Only a pinned target’s
target.session is still resolved once, at save time, as described above.
Saving either kind still checks access, that the session resolves in the target revision, and that the workflow
reference resolves in its own source revision — the target’s own revision for a bare definition, the named
organization, blob and revision for a qualified one — so a typo fails at save time rather than at the next fire. A
following target can still fail at fire time, without suppression, if the default revision has since committed,
the session has closed, or the workflow reference no longer resolves — see the fire-time errors below.
This is about the target’s own
org and blob: target.org is required only when target.blob is an alias — a
blob id needs no org, though one given alongside a blob id must name that same blob’s organization. A
target.blob alias with no target.org is refused with 400 invalid_invocation_target. The same rule inside
workflow — a workflow.blob alias without workflow.org — is refused with 400 invalid_workflow_reference
instead.workflow.definition must be named by alias, never by id, whenever the definition it names follows default —
when workflow.revision is default, or when workflow has no revision and target.revision is default. A
branch gives its definitions new ids but keeps their aliases, so an id-named definition there would fail every
fire after the next branch; a definition in a pinned revision never moves, so naming it by id is fine. This is
refused at save time with the same 400 invalid_invocation_target, for the same reason a following target’s
target.session must already be an alias, above.
Authorization
Schedules execute on behalf of the auth entity (user or organization) that created them. At the time of invocation, that auth entity must still have access to the target blob. If access has been revoked, the execution fails withinvocation_error and no workflow is started.
When workflow is qualified, the auth entity must also hold READ on the source blob, under the same rule as
The workflow reference. A source it can
no longer resolve or reach is recorded as invocation_failed, carrying create_execution’s refusal.
Execution History
Every time a schedule fires it creates an execution record. Executions are fire-and-forget: the execution result captures the immediate outcome of creating the workflow execution, not the final outcome of the workflow itself. Each execution has astatus field with one of three values:
Every run is recorded — including a following target that fails to resolve — with no suppression, so a
schedule’s execution history is always the true account of what each fire attempted.
result carries a
stable error name to switch on, alongside message for the two causes that cannot name themselves — the
API’s own rejection text, and an unforeseen exception:
Only
target_not_found and default_revision_committed are following-only — they come from resolving
revision, which a pinned target already carries as a fixed id and so never re-resolves. The session and
{definition}-form workflow checks run unconditionally on every fire, pinned or following alike, so a pinned target can
still reach session_not_found, session_not_open or workflow_not_found — nothing pins a session’s own
lifecycle or a definition’s continued existence, only the target’s own reference to them.
Each run records the invocation_target it fired, in the nested shape the schedule stores, and the description
it sent to create_execution — see List Executions.
Schedule States
A schedule is always in one of two states, stored in itsstate field:
active— the schedule can be updated or deleted. One-time schedules remain active until they fire; recurring schedules remain active indefinitely or until theirend_dateis reached.completed— the schedule is read-only. Completed schedules cannot be updated but can still be deleted.