ERP Plugin Developer Docs

Appearance

"My scheduled job never runs" ​

You seeded a job config row but nothing happens. Work through this in order.

1. Is the job registered for your tenant? ​

bash
erp api get "/api/v1/jobs/engine-entity.status-date-sweep"
  • { "status": "ENABLED", ... } → registered. Go to step 2.
  • 404 → not registered. The job registers on the first config row via an AFTER_CREATE register rule. Either:
    • your plugin seeded no config row (check the install log for PluginDataSeedInstaller: ... -> entity entity_<x>_config), or
    • for the aggregation / cadence / compliance / cross-plugin / document jobs you must ship the register rule yourself — metadata/rules/ensure_<job>_registered.json with an unconditional AFTER_CREATE EXECUTE_SERVICE. Only the status-date-sweep job's register rule ships with the platform.

2. Run it on demand and read the result ​

bash
erp api post "/api/v1/jobs/engine-entity.status-date-sweep/execute" --body "{}"
# → { "executionId": 534 }

erp api get "/api/v1/jobs/engine-entity.status-date-sweep/executions?size=1"

The latest execution's resultJson:

json
{ "swept": 0, "failed": 0, "rowsScanned": 92, "configsScanned": 28 }
  • configsScanned: 0 → the job sees no config rows. Your seed didn't land, or active is false on the rows.
  • configsScanned > 0 but swept: 0 → configs are seen but no record matched. Go to step 3.
  • failed > 0 → a matching record's update threw. Go to step 4.

3. swept: 0 — why does no record match? ​

For each config row, a record is swept only if all of:

  • its status_field value is exactly one of when_status_in (case matters — match the enum);
  • its date_field satisfies compare_op against now (± day_offset days);
  • (aggregation/compliance) it passes any when_status_in filter.

Common causes:

  • when_status_in: "checked_out" but the enum value is CHECKED_OUT.
  • day_offset omitted, so "within 3 days" is really "on the exact day".
  • date_field is null on the records (a null date never satisfies a comparison).

Set up a record that should obviously match and re-run.

4. failed > 0 — the update threw ​

bash
erp logs tail --lines 200 --grep "status/date sweep: failed to update"
Entity status/date sweep: failed to update oeq_checkout #1 (tenantId=2):
  PreparedStatementCallback; bad SQL grammar [update oeq_checkout set return_due_soon = ? ...]

The most common cause: the config's set_field is a boolean column and the job writes the value as a string. Fix: flip a status enum value (DUE_SOON, OVERDUE) instead of a boolean flag.

5. It works on demand but not on schedule ​

The cron is 0 5 0 * * * (00:05 daily, per tenant). It won't fire mid-day. Test with /execute; trust the schedule once /execute is clean.

See also ​