Permissions, Authority & Scheduling

Permissions, Authority & Scheduling

This page is for the person who is accountable for the system acting without a human in the room. It covers who may build, publish and promote an automation, whose authority an unattended run borrows, who the approvals are attributed to, how the schedule actually fires, and what is written down afterwards.

The ten permissions

The module owns its RBAC keys in modules/Automations/config/permissions.php; nothing is hardcoded in core. They appear in the Roles editor only while module_automations is enabled, and they disappear again when it is switched off — which is the whole reason a module declares its own permissions rather than adding rows to core.

Attendance automations reuse attendance permissions

Deciding attendance is HumanResource's business, so an attendance automation reuses the existing attendance_approval and attendance_update keys rather than forking parallel ones. The module must never invent a second way of being allowed to approve attendance — if it did, revoking someone's approval rights in HR would not revoke them here.

Why "publish" and "go live" are two grants

Scheduling a rule that only reports is a genuinely different decision from letting it act, and most operators should have the first without the second. Splitting them means an automation can be built, published and left running in Observe by the team that understands the process, while the decision to let it change payroll inputs stays with whoever is accountable for payroll.

Promotion is refused unless all four of these hold. The checks live in one private method (Automations::_live_refusal()) shared by publish() and set_run_mode(), precisely so the two paths cannot drift apart:

Demotion is deliberately asymmetric: dropping Live → Observe needs only automations_update, and it takes effect immediately — including for runs already queued. Stopping is always easier than starting.

Publisher authority

An automation is not an account and holds no permissions of its own. It acts with the authority of the person who promoted it, recorded as published_by. That answers the question every auditor asks first — on whose authority did the system do this? — with a name rather than a service account.

Because people leave, change roles and lose permissions, that authority is revalidated on every tick before a live run is allowed to touch anything. It is not a promotion-time snapshot.

The check fails closed: anything it cannot resolve is a denial. The alternative — "cannot tell, so proceed" — means a deleted user's automation keeps changing records, which is the exact failure this guards against. On denial the automation moves to needs review and the run is recorded as failed with error code PUBLISHER_UNAUTHORIZED; nothing is mutated.

// modules/Automations/libraries/Automation_executor.php
private function publisher_denial($automation)
{
    $publisher_id = (int) $automation->published_by;

    if ($publisher_id < 1) {
        return 'This automation has no recorded publisher, so no authority backs a live run.';
    }

    $this->CI->load->model('Users_model');
    $publisher = $this->CI->Users_model->get_one($publisher_id);

    if (!$publisher || !isset($publisher->id) || !$publisher->id) {
        return "The publisher (user #$publisher_id) no longer exists.";
    }

    if (!empty($publisher->deleted)) {
        return "The publisher (user #$publisher_id) has been deleted.";
    }

    if (isset($publisher->status) && $publisher->status !== 'active') {
        return "The publisher (user #$publisher_id) is no longer active.";
    }

    // user_can() reads the stored permissions for an ARBITRARY user. The similarly
    // named user_has_permit() ignores its $userid argument and evaluates the
    // logged-in user instead — which in a cron process is nobody.
    $this->CI->load->helper('permission');
    if (!function_exists('user_can')) {
        return 'Publisher authority could not be evaluated on this installation.';
    }

    if (!user_can($publisher_id, 'automations_go_live')) {
        return "The publisher (user #$publisher_id) no longer holds permission to run automations live.";
    }

    return null;
}

Observe runs are deliberately not gated

Publisher revalidation applies to Live runs only. An Observe run changes nothing — it reads, decides, and writes its decision to the run log — so there is no authority to borrow. Stopping a report because its author left the company would remove visibility at the precise moment you most need it, and would leave you with an automation you can no longer see the behaviour of. That is a deliberate compromise, and it belongs to whoever owns this module's security posture; do not "harden" it by extending the gate to Observe without replacing the visibility it removes.

The System actor

An unattended approval still has to be attributed to somebody. Attributing it to the publisher would be a lie — they authorised the rule, they did not review the record — and leaving the approver blank breaks the audit trail. So headless writers resolve a dedicated System user, and the trail reads "System Automation".

Resolved by

erpat_system_actor_id() in application/helpers/user_helper.php

Seeded by

application/migrations/20260903232432_seed_system_actor_user.php — a core migration, because the actor is a platform fact, not a module one

The row

user_type='system', status='inactive', disable_login=1, no password — invisible to every staff-scoped query and impossible to log into

Caching

Memoised per database. The id differs per tenant and one cron tick walks several tenants inside a single process, so a bare static would leak the previous tenant's id

When absent

Returns 0 — and 0 must be treated as a refusal, never as a usable actor

If you see that failure, the fix is to run the core migrations on that database — the actor is seeded by 20260903232432_seed_system_actor_user. It is worth checking on any tenant that was provisioned from an older install dump before you promote anything to Live there.

How scheduling actually works

The Automation Center ships no scheduler of its own. ERPat's Advanced Cron runtime already owns the catch-up watermark, the per-tenant fan-out, the per-job lock with stale-steal, the cron_runs log, the timeout sweeper and the health endpoint. The module contributes exactly one job that supplies the two phases that are genuinely its own.

Each tick runs two phases. Phase A claims every automation whose pointer has been reached, opens exactly one run per occurrence, and advances the pointer. Phase B hands open runs to the executor, oldest first, until the budget is spent. A run that does not finish keeps its cursor and resumes next tick — unfinished is not failed.

The job self-gates twice before doing anything: it exits if module_automations is not '1' (the cron registry discovers jobs regardless of module state), and it exits quietly if the automations table is absent, which is what happens on the primary-database pass of an install that only migrated the module into tenants.

The 366-day next-occurrence horizon

Next occurrences are computed with App\Cron\Core\CronExpression — the very same parser the runtime's own Scheduler uses, so an automation and a cron job can never disagree about what an expression means. The search steps a cursor minute by minute and stops after 366 days of minutes.

Every expression that can ever match does so within a year. One that cannot — 30 February is the canonical example — is a configuration error, so past the horizon the search returns nothing and the dispatcher clears the pointer and moves the automation to needs review. The same happens to an expression that fails to parse at all. It surfaces as a visible state an operator can act on, instead of an automation that silently never fires again.

The module toggle, and switching a contributing module off

module_automations is seeded off ('0'). The Automation Center is opt-in per tenant: enabling it is a decision somebody makes, not a default that arrives with an upgrade.

Turning it off hides the page, drops the permissions from the Roles editor, and stops the dispatcher on that tenant. It does not delete automations or run history — turn it back on and everything is where you left it, though schedules that came due while it was off were never claimed.

The more interesting case is switching off a module that contributes a type — HumanResource, for the only type registered today:

A malformed type definition is treated differently again: the registry is fail-safe, not fail-closed. A broken sidecar is logged and skipped, never fatal, matching the core config collector that runs on every request. One module's mistake must not take down the Automation Center for the tenant.

Settings tab — engine diagnostics

Gated on automations_settings. It is a read-out, not a control panel — there is nothing here you can misconfigure, which is why it is the right first stop when something is not firing.

Audit — what gets written down

Seven events are registered in modules/Automations/config/system_logs.php. They are ungated by module state, so historical entries still resolve their labels and filter dropdowns after the module is switched off.

One row per run, never one per record

A 263-record run leaves one audit row, not 263. The aggregate entry carries the automation title and UUID, the type key, the run id, the run mode, the status, the number of records evaluated and the reason-code counts. It is written with an explicit user_id => 0, which renders as "System" — cron has no logged-in user, and an implicit fallback would attribute the run to whoever happened to be around.

The detail lives in two other places, on purpose. The per-record decision trail is automation_run_items, one row per subject with its outcome and reason code. The authoritative business audit stays with the module that owns the data: an attendance approval writes its own attendance log entry through the shared transition service, exactly as the Approve button does. Flooding the system activity log with one row per approved record would drown the trail it is supposed to be.

Before you allow Live on a tenant

Next: Integration Contract covers what a module declares to contribute an automation type, and Run Lifecycle & Execution follows a single run from claim to completion.