The dispatcher is a by-design 1-minute sweeper: each pass claims due routines and does bounded work, so the engine's high-frequency cron warning doesn't apply.
Resolves (or lazily creates) the routine's dedicated conversation. Public so the integration suite can exercise the creation/reuse contract without an LLM call.
The conversation is owned by the routine's owner and created with
ApplicationScope='Application' + the "${ROUTINES_APPLICATION_NAME}" Application's ID,
which keeps it OUT of the default chat list (the same hide mechanism meeting-room and
Form Builder cockpit conversations use) while remaining fully reachable from the
routine's UI. It is also Linked to the routine record (LinkedEntityID/LinkedRecordID)
and pins the routine's agent as DefaultAgentID.
Best-effort by design: any resolution/creation failure logs and returns null so the run proceeds standalone — a missing Routines app must never break a scheduled run.
Execute the scheduled job
This is the main entry point for job execution. The plugin should:
The Details object will be serialized to JSON and stored in ScheduledJobRun.Details
Execution context including schedule, run record, and user
Promise resolving to execution result
Format notification content for job completion
Called by the engine when notifications are enabled and should be sent. The plugin can customize the notification based on the job type and execution result.
Execution context
The execution result
Notification content
ProtectedgetProtectedGet the job type entity for this plugin
The schedule
User context
Optionalprovider: IMetadataProviderPromise resolving to the job type entity
ProtectedlogProtectedLog execution progress
Log message
Whether to only log in verbose mode
ProtectedlogProtectedLog execution error
Error message
Optionalerror: anyOptional error object
ProtectedparseProtectedParse and validate the Configuration JSON field
Helper method for plugins to parse their configuration with type safety. Throws if configuration is invalid.
The configuration type
The schedule containing the configuration
Parsed configuration
ProtectedresolveResolve the routine owner's UserInfo from UserCache so target execution runs under
the routine owner's RBAC/RLS/FLS identity rather than the scheduler's system user.
Fails closed when UserCache is populated and the owner is missing or inactive.
Run one routine now, on request, without touching its schedule.
The sweep claims a routine before running it, which advances NextRunAt or, for a one-shot,
clears it, and a cleared one-shot is Disabled after the run. A "Wake Now" implemented as
"set NextRunAt to now" therefore SPENDS a one-shot: the reminder wanted tomorrow fires today
and never fires again. This path skips the claim, so after the run NextRunAt still holds
the scheduled time and the roll-up leaves the routine Active. It also skips the wake gate:
the person asked for the run, so "nothing changed since last time" is not a reason to skip.
contextUser is the bookkeeping identity (run row, routine roll-up), normally the scheduler's
system user; the target still executes as the routine's owner, exactly as on the sweep.
Ownership of the routine is the caller's check (see the Run User Routine Now action).
Validate job-specific configuration
Called when creating or updating a scheduled job to ensure the Configuration JSON is valid for this job type.
The schedule being validated
Validation result with any errors or warnings
Driver for the User Routine Dispatcher scheduled job.
Configuration schema (stored in ScheduledJob.Configuration):
{ MaxConcurrentRoutines?: number }Execution result details (stored in ScheduledJobRun.Details):
{ RoutinesEvaluated, RoutinesSeeded, RoutinesRun, Succeeded, Failed, Notified }