Scheduler

Overview

The Scheduler is the tenant’s cron table. Each row pairs a background job processor with a cron expression and, optionally, a JSON payload of properties for that job. On every pacemaker tick the platform reads the tenant’s active rows, works out which are due, and puts the matching job on the tenant queue.

It is how recurring work gets scheduled without a deployment: e-invoice submission sweeps, replenishment runs, report generation, notification pushes and the rest. It runs nothing itself and knows nothing about what the jobs do.

Where it fits

Screens and menus

Create has two tabs. Details holds Scheduler Code (read-only — clicking it opens a Select Processor picker over the tenant’s job processors, showing Code, Name, Type and Status), Scheduler Name, and Status (ACTIVE / INACTIVE). Cron Expression embeds the ngx-cron-editor widget in standard flavour, pre-set to 0 0 1/1 * *. CREATE is disabled until code, name and status are filled.

Edit adds a third tab, Json, for the event properties — a JSON editor pre-filled from the selected processor’s own property_json when the row is new, or from the row’s saved event_properties, and able to load a .json file. Edit also shows Created Date and Modified Date, and carries Run and Delete.

The Personalization menu lists a Field Settings item pointing at field-settings, which is not a child route of personalization — selecting it falls through to the applet’s 404 (menu-items.ts vs app.routing.ts, commit 3fd3986).

Screenshots needed

No screenshots exist for this applet. A capture session should take: the Scheduler listing with several rows and their Last Run Date; the Select Processor picker; the Cron Expression tab with the editor open; and the Edit screen’s Json tab with a payload and the Run button. Job processor codes are product-wide, not customer data, so a demo tenant is enough.

Configuration

Before you can use it

Applet settings

Settings are applet-local, and neither screen does anything for this applet.

• Settings → Field Settings is the unbound eight-toggle stub (Unit Discount, SST/VAT/GST, WHT, Blanket Order, Segment, G/L Dimension, Profit Center, Project) — no form binding, SAVE has no handler, and the labels belong to a sales-document screen. No exposed control found (routes and settings components checked at commit 3fd3986).
• Settings → Default Selection and Personalization → Default Selection offer Default Branch and Default Location. Neither key is read anywhere in the applet.

Everything that matters is on the schedule row itself:

Feature visibility / permissions

bl_applet_client_side_perm_dfn holds zero rows for schedulerApplet (checked 2026-09-14), and the applet checks no HIDE_* / SHOW_* keys, so the Feature Visibility screen has nothing to gate.

Server-side, SchedulerCrontabController guards its endpoints with AkaunTenantPermissions.API_TNT_DM_SCH_CRONTAB_READ, _CREATE, _UPDATE and _DELETE (with _OWNER and _ADMIN as the broad grants). Note that Run is guarded by API_TNT_DM_SCH_CRONTAB_CREATE, not by update — anyone who may add a schedule may also fire one immediately.

Fields

Create → Details

Cron Expression tab — the ngx-cron-editor control, standard flavour. Its value is copied onto the row on submit.

Json tab (Edit) — a single event_properties field holding a JSON object, pre-filled and uploadable from a file.

Listing columns — Scheduler Code, Scheduler Name, Status, Last Run Date, Created Date, Updated Date.

Lifecycle and effects

No document type, no signums, no journal, no stock. The applet writes bl_sch_crontab_hdr; the platform writes bl_sch_crontab_event and the queue rows.

What happens on each pacemaker tick (MainTenantProcessor.triggerSchCron):

1. Read every ACTIVE row from the tenant’s cron table. A tenant database that cannot be reached is logged and skipped, not failed.
2. Keep only rows whose code resolves to a JobProcessorClassName enum constant — JobProcessorClassName.valueOf(code) must succeed. A row naming a processor the platform does not have is silently dropped: no error, no event, no change to Last Run Date.
3. Keep only rows that are due. SchedulerCronService.isTimeToTriggerClock parses the expression with the UNIX cron definition, takes last_run_time as the reference (falling back to created_date), asks the parser for the next execution after that point, and fires when now is after it. Because the reference is the last run and not the wall clock, a tenant that was down catches up on exactly one missed occurrence per tick.
4. For each due row, check jobExistsInQueue first — an identical job already queued is logged and not queued again.
5. Queue the job with the row’s event_properties as its properties map and the row’s execution_strategy as its strategy.
6. Only if the queue insert succeeded: set last_run_time to now and write a bl_sch_crontab_event row with the trigger time. A failed insert leaves last_run_time alone so the next tick retries.

What “Run” does instead. POST …/sch/crontabs/scheduler/execute/backoffice-ep/{guid} writes an app_scheduler_queue row (start now, expire in five hours, priority 5) carrying the schedule’s code and event properties, then resolves the processor class and calls processAvailableEvent directly. It returns JOBPROCESSORCLASS_CAST_ERROR when the code does not resolve to a usable processor and EVENT_PROCESSING_ERROR when the processor throws. It does not update last_run_time, so a manual run does not shift the next scheduled occurrence.

What the backend fills in. On create, the data-consistency object supplies a GUID, status = ACTIVE, created_date, updated_date, a revision and execution_strategy = INSERT_TO_QUEUE when they are missing, and it defaults last_run_time to now. That last default is the one to remember: a new schedule’s first firing is computed forward from the moment you created it, never from the past, so creating a daily job at 3 pm does not back-fill this morning’s run.

Validation on create rejects a row with no code, no name, no cron expression, no status, no revision, or an execution strategy that is not one of the queue’s own strategy values.

Related applets

• Developer SysAdmin Applet — where job processors and their subscriptions are registered, and where a failed job is inspected.

Troubleshooting

Related documentation

• Developer documentation