> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled tasks

> See what runs automatically, when it last ran, and what it did — plus how to pause, run now, or cancel a job.

**Operations → Scheduled Tasks → `/schedules`**

Much of what the platform does happens without anyone clicking anything: recurring invoices are
generated, payments are allocated, meters are polled, penalties are assessed, collections cases are
swept, statements are produced. **Scheduled Tasks** is where you see all of it.

## What a schedule record holds

| Section       | Fields                                                            |
| ------------- | ----------------------------------------------------------------- |
| **Identity**  | Name, job name, job type                                          |
| **Basics**    | Recurrence rule, anchor, next run, priority                       |
| **Approval**  | Approval status, approval request, approved by, approved at       |
| **Execution** | Execution ID, last status, started/ended, duration, result, error |
| **Metadata**  | Raw configuration                                                 |

**Recurrence rule** and **anchor** together define when the job runs — the anchor is the reference
point the recurrence counts from, which is why two jobs with the same cadence can run at different
times.

## Actions

| Action                   | Effect                                                                |
| ------------------------ | --------------------------------------------------------------------- |
| **Execute schedule now** | Runs the job immediately, outside its cadence. Asks for confirmation. |
| **Pause**                | Stops future runs without deleting the schedule.                      |
| **Cancel job**           | Cancels a job. Asks for confirmation.                                 |

<Warning>
  **Execute now** on a money-touching job — invoice generation, allocation, penalties — does real
  work immediately. Confirm the branch and the period before you run it, and check whether the job
  has already run for that period.
</Warning>

## Execution history

Each schedule keeps its execution history: when it ran, how long it took, whether it succeeded, and
the result or error. This is the first place to look when something that should have happened
did not.

<Steps>
  <Step title="Check the last status">
    Success, failure, or never run.
  </Step>

  <Step title="Check the next run">
    A next-run date in the past means the schedule is paused or the scheduler is off.
  </Step>

  <Step title="Read the error">
    Failures record the reason, not just the fact.
  </Step>

  <Step title="Check duration trends">
    A job whose duration is growing steadily will eventually not finish inside its window.
  </Step>
</Steps>

## How jobs are enabled

Scheduled work sits behind two switches:

1. A **master scheduler switch** for the environment. It defaults to **off** outside production, so
   a non-production environment cannot write real invoices or payments against live data.
2. A **per-job switch**. New jobs are individually gated and default to off, so a module can ship
   fully built and stay dormant until an organisation is ready for it.

Both must be on for a job to run. If a job appears configured but nothing happens, check both
before investigating the job itself.

<Note>
  Engines that touch money or reach residents also run in **shadow mode** first — computing and
  staging actions for a human to confirm. Enabling the job is not the same as authorising it to act
  alone. See [Collections overview](/guides/collections/overview).
</Note>

## Fairness across organisations

Jobs that sweep large populations work **organisation by organisation in rotation**, with
per-branch limits, rather than taking a single global batch. Without this, one large branch can
consume an entire run and every other branch is starved — a failure mode that looks exactly like
"the job did nothing".

If a job reports work done but a particular branch never seems to be processed, this is the first
thing to check.

## Jobs worth knowing

| Job                              | What it does                                                              |
| -------------------------------- | ------------------------------------------------------------------------- |
| **Recurring invoice generation** | Bills the cycle's standing charges.                                       |
| **Allocation**                   | Matches unallocated payments to outstanding invoices.                     |
| **Penalties**                    | Assesses late fees against overdue invoices.                              |
| **Collections sweep**            | Opens, refreshes, scores and closes arrears cases; stages ladder actions. |
| **IoT polling and billing**      | Collects readings and produces utility invoices.                          |
| **Owner statement generation**   | Produces statements on the contract's cadence.                            |
| **Communication dispatch**       | Sends queued messages.                                                    |
| **Integration submission**       | Drains the eTIMS submission queue.                                        |

## Approval on schedules

Some schedules carry an approval state, so a job with material effect can require sign-off before
it becomes active. The approval request, approver and approval time are recorded on the schedule.

## Common problems

| Symptom                      | Cause                                                               |
| ---------------------------- | ------------------------------------------------------------------- |
| Nothing ran at all           | Master scheduler switch off.                                        |
| One job never runs           | Its own job switch is off, or the schedule is paused.               |
| Job runs but changes nothing | Shadow mode, or nothing in scope met the criteria. Read the result. |
| One branch never processed   | Fairness rotation — check whether the run reached it.               |
| Job ran twice                | Check for a manual **execute now** alongside the scheduled run.     |