@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/guides/add-a-reminder-job.md

@@ -0,0 +1,181 @@
+---
+title: Add a scheduled reminder job
+audience: tenant
+---
+
+# Add a scheduled reminder job
+
+## What you're doing
+
+"Flip this record's status once a date passes" — or "N days before it passes".
+Overdue checkouts, expiring warranties, upcoming audits. **You write no Java and
+no job class.** The platform ships one generic job,
+`engine-entity.status-date-sweep`, that runs daily and applies every
+`entity_status_date_sweep_config` row. Adding a reminder = adding one config row,
+shipped with your plugin as seed data.
+
+## How the generic job works
+
+Once a day (cron `0 5 0 * * *`, per tenant) the job:
+
+1. reads every active `entity_status_date_sweep_config` row;
+2. for each, lists all rows of that config's `entity_name`;
+3. for every row whose `status_field` is one of `when_status_in` **and** whose
+   `date_field` satisfies `compare_op` against *now* (optionally shifted by
+   `day_offset` days), it sets `set_field` (defaults to `status_field`) to
+   `set_status_to`.
+
+Because a swept row no longer matches `when_status_in`, re-running the job is a
+harmless no-op — it's naturally idempotent.
+
+## The complete example
+
+`spk-assembly/metadata/seed-data/office-equipment-sweep-configs.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/seed-data/office-equipment-sweep-configs.json):
+
+```json
+{
+  "entity": "entity_status_date_sweep_config",
+  "keyFields": ["entity_name", "date_field", "set_status_to", "day_offset"],
+  "source": "office-equipment",
+  "rows": [
+    {
+      "entity_name": "oeq_checkout",
+      "status_field": "status",
+      "when_status_in": "CHECKED_OUT",
+      "date_field": "due_date",
+      "compare_op": "lte",
+      "day_offset": 3,
+      "set_status_to": "DUE_SOON",
+      "active": true,
+      "seeded_by": "office-equipment"
+    },
+    {
+      "entity_name": "oeq_checkout",
+      "status_field": "status",
+      "when_status_in": "CHECKED_OUT,DUE_SOON",
+      "date_field": "due_date",
+      "compare_op": "lt",
+      "day_offset": 0,
+      "set_status_to": "OVERDUE",
+      "active": true,
+      "seeded_by": "office-equipment"
+    }
+  ]
+}
+```
+
+You also need the shared config entity to exist. Ship it (idempotent-additive):
+`spk-assembly/metadata/entities/entity_status_date_sweep_config.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/entities/entity_status_date_sweep_config.json).
+
+## Line by line
+
+### The seed-data wrapper
+
+- **`entity`** — `entity_status_date_sweep_config`, the shared platform config
+  table.
+- **`keyFields`** — the natural key. On re-install, a row matching **all** of
+  these is updated (only if a value changed) rather than duplicated. Include
+  `day_offset` so the 3-day and 0-day rows for the same date column are treated
+  as distinct.
+- **`source`** — your plugin id; stamped into `seeded_by`.
+- **`rows`** — the config rows.
+
+### Each config row
+
+- **`entity_name`** — the entity to sweep.
+- **`status_field`** — which column holds the lifecycle status (default
+  `status`).
+- **`when_status_in`** — comma-separated statuses a row must currently be in to
+  be eligible.
+- **`date_field`** — the date/timestamp column to compare against now.
+- **`compare_op`** — `lte | lt | gte | gt`.
+- **`day_offset`** — `0` = compare against now exactly. `3` = compare against
+  `now + 3 days`, i.e. "fires when `due_date` is within 3 days" — this is the
+  "N days before" reminder. Negative shifts earlier.
+- **`set_field`** — the column to write. **Omit it** to write `status_field`
+  itself.
+- **`set_status_to`** — the new value.
+
+### The two rows together
+
+- Row 1: a `CHECKED_OUT` checkout whose `due_date` is within 3 days → `DUE_SOON`.
+- Row 2: a `CHECKED_OUT` **or** `DUE_SOON` checkout whose `due_date` has passed →
+  `OVERDUE`.
+
+This two-row shape (a "soon" warning then an "it happened" flip) is the exact
+pattern the platform's own `leave_policy` sweep uses.
+
+### Flip a status, not a boolean
+
+Write to an **enum/text status column**, as above. Writing `set_status_to:
+"true"` to a **boolean** `set_field` currently fails inside the generic job with
+a SQL type error — the job passes the value as a string. Model reminders as
+status values (`DUE_SOON`, `OVERDUE`) rather than boolean flags until that is
+fixed. (This was found while building this tutorial.)
+
+## The job registers itself
+
+The platform ships an `AFTER_CREATE` rule on `entity_status_date_sweep_config`
+that calls `ensureEntityStatusDateSweepJobRegistered` — so the **first** config
+row your plugin seeds auto-registers the job for your tenant. You don't ship that
+rule.
+
+## Ground yourself first
+
+```bash
+erp schema pull entity-status-date-sweep-config
+erp schema pull plugin-seed-data
+erp examples patterns --kind jobs
+```
+
+## How to verify it worked
+
+After publishing, the job is registered and enabled:
+
+```bash
+erp api get "/api/v1/jobs/engine-entity.status-date-sweep"
+```
+
+```json
+{ "jobCode": "engine-entity.status-date-sweep", "status": "ENABLED",
+  "cronExpression": "0 5 0 * * *", "concurrencyPolicy": "PER_TENANT" }
+```
+
+Run it on demand and check a record flips. **This exact sequence was run against
+the tutorial module:**
+
+```bash
+# a checkout that is CHECKED_OUT with a due_date in the past
+erp api post "/api/v1/entities/oeq_checkout/records" \
+  --body '{"checkout_number":"CO-100","equipment_id":1,"employee_id":1,"checkout_date":"2026-08-01","due_date":"2026-09-04","status":"CHECKED_OUT"}'
+
+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"
+# → resultJson: {"swept": 4, "failed": 0, "rowsScanned": 102, "configsScanned": 30}
+
+erp api get "/api/v1/entities/oeq_checkout/records/2"
+# → { "checkout_number": "CO-100", "status": "OVERDUE" }
+```
+
+`CHECKED_OUT` → `OVERDUE`. Verified.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| job execution reports `"failed": N` | `set_field` is a boolean column | flip a status value instead |
+| nothing sweeps | `when_status_in` casing doesn't match the enum | match exactly |
+| "N days before" never fires | forgot `day_offset` (defaults to 0) | set `day_offset` to the window |
+| re-install duplicates the config | `keyFields` don't uniquely identify the row | include enough fields (add `day_offset`, `set_field`) |
+| job not registered | plugin seeded no config row, or the config entity wasn't shipped | ship `entity_status_date_sweep_config.json` and at least one seed row |
+
+## What to read next
+
+- [Add a cross-row aggregation job](./add-an-aggregation-job.md)
+- [Add a cadence-generator job](./add-a-cadence-job.md)
+- [Add a compliance-sweep job](./add-a-compliance-job.md)
+- Recipe: [N-days-before reminder job](../recipes/n-days-before-reminder.md)

package/bundle/docs/guides/add-an-aggregation-job.md

@@ -0,0 +1,153 @@
+---
+title: Add a cross-row aggregation job
+audience: tenant
+---
+
+# Add a cross-row aggregation job
+
+## What you're doing
+
+"Count / sum / average many rows and store the result somewhere." A nightly
+inventory reconciliation, a per-asset maintenance-cost rollup, seats-used per
+licence. **No Java.** One `entity_aggregation_config` row, run by the generic
+`engine-entity.aggregation-sweep` job, shipped as seed data.
+
+This is the batch cousin of a [KPI Data Service](./add-a-kpi.md): a KPI is
+computed on demand for a screen; an aggregation job writes a number back into a
+table on a schedule so other rows/pages/rules can use it.
+
+## Two target shapes
+
+| You want | Set |
+| --- | --- |
+| a **summary entity** with one row per bucket (e.g. count of equipment per status) | `target_key_field` = a text key column, `target_key_prefix` to namespace it |
+| a value written **onto the source's own parent row** (e.g. `synced_cost` onto a maintenance record) | `target_key_field: "id"` — the bucket key *is* the parent's primary key |
+
+## The complete example — count per status into a summary entity
+
+`spk-assembly/metadata/seed-data/office-equipment-aggregation-configs.json`
+(standalone example,
+[real file](../examples/standalone-plugin/spk-assembly/metadata/seed-data/office-equipment-aggregation-configs.json)):
+
+```json
+{
+  "entity": "entity_aggregation_config",
+  "keyFields": ["sweep_code"],
+  "source": "office-equipment",
+  "rows": [
+    {
+      "sweep_code": "equipment-status-reconciliation",
+      "source_entity": "oeq_equipment",
+      "aggregation": "count",
+      "group_by_field": "status",
+      "target_entity": "oeq_reconciliation",
+      "target_key_field": "metric_key",
+      "target_key_prefix": "equipment_status:",
+      "target_value_field": "metric_value",
+      "target_timestamp_field": "last_reconciled_at",
+      "seeded_by": "office-equipment",
+      "active": true
+    }
+  ]
+}
+```
+
+You also ship: the `oeq_reconciliation` summary entity (`metric_key` text,
+`metric_value` numeric, `last_reconciled_at` datetime), the shared
+`entity_aggregation_config` entity file (idempotent-additive), and an
+`AFTER_CREATE` register rule (below).
+
+## Line by line
+
+- **`sweep_code`** — unique id for this config; the natural key.
+- **`source_entity`** — the table to fold.
+- **`aggregation`** — `count` | `sum` | `avg` | `min` | `max`. The last four need
+  **`agg_field`** (the numeric column to fold).
+- **`group_by_field`** — the bucket. `count` grouped by `status` → one number per
+  status value.
+- **`when_status_in` / `status_field`** — optional filter: only fold rows in
+  these statuses.
+- **`target_entity`** — where results go.
+- **`target_key_field` + `target_key_prefix`** — for each bucket, the target row
+  is keyed `<prefix><bucket value>` (e.g. `equipment_status:AVAILABLE`). Prefix
+  lets several configs share one summary table.
+- **`target_value_field`** — the column that receives the number.
+- **`target_timestamp_field`** — stamped with the run time.
+
+### The "write onto the parent row" variant
+
+```json
+{
+  "sweep_code": "maintenance-cost-rollup",
+  "source_entity": "oeq_maintenance_cost",
+  "aggregation": "sum",
+  "agg_field": "total_cost",
+  "group_by_field": "maintenance_id",
+  "target_entity": "oeq_maintenance",
+  "target_key_field": "id",
+  "target_value_field": "synced_cost",
+  "target_timestamp_field": "cost_synced_at",
+  "active": true
+}
+```
+
+Here `group_by_field` values **are** `oeq_maintenance` primary keys, so the sum
+is written straight onto each maintenance row. Leave `target_key_prefix` blank.
+
+## The register rule
+
+Ship `spk-assembly/metadata/rules/ensure_aggregation_sweep_job_registered.json`:
+
+```json
+{
+  "entityType": "entity_aggregation_config",
+  "name": "ensure_aggregation_sweep_job_registered",
+  "triggerEvent": "AFTER_CREATE",
+  "conditions": null,
+  "actions": "[{\"type\": \"EXECUTE_SERVICE\", \"service\": \"ensureEntityAggregationSweepJobRegistered\"}]",
+  "priority": 10,
+  "active": true
+}
+```
+
+## Ground yourself first
+
+```bash
+erp schema pull entity-aggregation-config
+erp examples patterns --kind jobs
+```
+
+The `cross-row-aggregation-into-summary-entity` and `target-key-field-id-rollup`
+patterns each point at a real shipped file.
+
+## How to verify it worked
+
+```bash
+erp api get "/api/v1/jobs/engine-entity.aggregation-sweep"
+# → { "status": "ENABLED", ... }
+
+erp api post "/api/v1/jobs/engine-entity.aggregation-sweep/execute" --body "{}"
+erp api get "/api/v1/entities/oeq_reconciliation/records/query?size=10"
+```
+
+```json
+{ "rows": [
+  { "metric_key": "equipment_status:AVAILABLE", "metric_value": 8, "last_reconciled_at": "2026-09-10T..." },
+  { "metric_key": "equipment_status:ASSIGNED",  "metric_value": 4, "last_reconciled_at": "2026-09-10T..." }
+], "total": 2 }
+```
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| job not registered | no `AFTER_CREATE` register rule shipped | ship it |
+| `sum`/`avg` writes null | `agg_field` missing | required for all aggregations except `count` |
+| summary rows collide with another config's | no `target_key_prefix` | namespace each config's keys |
+| rollup creates rows instead of updating | wanted the parent-row shape but set a prefix | use `target_key_field: "id"`, blank prefix |
+
+## What to read next
+
+- [Add a cadence-generator job](./add-a-cadence-job.md)
+- [Add a compliance-sweep job](./add-a-compliance-job.md)
+- Recipe: [cross-row aggregation into a summary entity](../recipes/cross-row-aggregation.md)

package/bundle/docs/guides/add-an-approval-workflow.md

@@ -0,0 +1,222 @@
+---
+title: Add an approval workflow
+audience: tenant
+---
+
+# Add an approval workflow
+
+## What you're doing
+
+Making a record require sign-off before it advances. When a user submits a
+checkout, its status goes to `PENDING_APPROVAL`; a manager approves or rejects;
+the platform flips the status to `APPROVED` or `REJECTED`. You write **no**
+approval code — you declare three things:
+
+1. a **workflow definition** — the stages, the approval task, who may decide
+2. an **entity rule** — "when status enters `PENDING_APPROVAL`, start that
+   workflow"
+3. nothing else — a generic callback controller writes the decision back
+
+## The mental model
+
+```
+user sets status = PENDING_APPROVAL
+        │
+        ▼
+entity rule (AFTER_UPDATE)  ──START_WORKFLOW──▶  workflow instance + a human task
+        │                                              │
+        │                                     manager approves / rejects
+        ▼                                              │
+generic workflow-callback controller  ◀────────────────┘
+        │
+        ▼
+record.status = APPROVED  (or REJECTED)
+```
+
+## The complete example
+
+### 1. The workflow — `spk-assembly/metadata/workflow/office-equipment.checkout-approval.json`
+
+[Real file](../tutorial/example-plugin/spk-assembly/metadata/workflow/office-equipment.checkout-approval.json):
+
+```json
+{
+  "name": "office-equipment.checkout-approval",
+  "description": "Single-stage Office Equipment Manager approval for a checkout submitted for approval.",
+  "stagesJson": "[\"manager\"]",
+  "tasksJson": "[{\"taskKey\":\"manager-approve\",\"stage\":\"manager\",\"taskType\":\"approval\",\"kind\":\"human\",\"payload\":{\"approvalObject\":\"office-equipment.checkout-approval\",\"amount\":0,\"dueInSeconds\":259200}}]",
+  "transitionsJson": "[]",
+  "approversJson": "{}",
+  "slasJson": "[]",
+  "escalationsJson": "[]",
+  "notificationsJson": "[]",
+  "metadataJson": "{}",
+  "approvalPermissions": [
+    { "roleCode": "OFFICE_EQUIPMENT_MANAGER", "approvalObject": "office-equipment.checkout-approval", "maxAmount": null }
+  ]
+}
+```
+
+### 2. The rule — `spk-assembly/metadata/rules/oeq_checkout_submit_workflow.json`
+
+[Real file](../tutorial/example-plugin/spk-assembly/metadata/rules/oeq_checkout_submit_workflow.json):
+
+```json
+{
+  "entityType": "oeq_checkout",
+  "name": "oeq_checkout_submit_workflow",
+  "description": "On transition INTO PENDING_APPROVAL, start office-equipment.checkout-approval; the generic workflow callback controller flips status to APPROVED/REJECTED on the decision.",
+  "triggerEvent": "AFTER_UPDATE",
+  "conditions": "{\"all\":[{\"field\":\"status\",\"op\":\"eq\",\"value\":\"PENDING_APPROVAL\"},{\"field\":\"status__previous\",\"op\":\"neq\",\"value\":\"PENDING_APPROVAL\"}]}",
+  "actions": "[{\"type\":\"START_WORKFLOW\",\"workflowName\":\"office-equipment.checkout-approval\",\"callbackUrl\":\"http://localhost:8080/api/v1/entities/workflow-callback\",\"config\":{\"entityType\":\"oeq_checkout\",\"idField\":\"id\",\"fields\":[{\"name\":\"status\",\"approved\":\"APPROVED\",\"rejected\":\"REJECTED\"}]}}]",
+  "priority": 20,
+  "active": true
+}
+```
+
+### 3. The Submit button on the page
+
+```json
+{
+  "blockType": "core.button",
+  "properties": { "labelKey": { "source": "static", "value": "office-equipment.equipment-checkout.detail.submitBtn" } },
+  "events": { "clicked": { "source": "action-chain", "actions": [
+    { "id": "a0", "order": 0, "type": "callApi",
+      "config": { "connectionRef": "self", "path": "/api/v1/entities/oeq_checkout/records/${page.detailRecord.id}", "httpMethod": "PUT", "params": { "status": "PENDING_APPROVAL" } } },
+    { "id": "a1", "order": 1, "type": "callApi",
+      "config": { "connectionRef": "self", "path": "/api/v1/entities/oeq_checkout/records/${page.detailRecord.id}", "httpMethod": "GET", "params": {} }, "output": "refreshed" },
+    { "id": "a2", "order": 2, "type": "setValue", "config": { "field": "page.detailRecord", "value": "${refreshed}" } },
+    { "id": "a3", "order": 3, "type": "showToast", "config": { "message": "Submitted for approval." } }
+  ] } }
+}
+```
+
+## Line by line
+
+### The workflow
+
+- **`name`** — must be `<pluginId>.<something>`, globally unique. The rule
+  references it by this exact string.
+- **`stagesJson` / `tasksJson` / `transitionsJson`** — **each is a JSON-encoded
+  *string***, not a nested object. `stagesJson: "[\"manager\"]"` is the string
+  `["manager"]`. Same rule as an entity's `label`.
+- **`stagesJson`** — ordered stage codes. One stage = `["manager"]`. A single
+  actor who both requests and decides = `["only"]`.
+- **`tasksJson`** — one approval task per stage. `payload.approvalObject` is the
+  string that `approvalPermissions` and the platform's approval inbox key off.
+  `dueInSeconds: 259200` = 3 days.
+- **`transitionsJson: "[]"`** — no transitions needed for a single stage;
+  reaching the last stage with no matching transition completes the instance.
+  For a linear two-stage flow: `"[{\"fromStage\":\"manager\",\"toStage\":\"hr\",\"condition\":{\"field\":\"decision\",\"op\":\"eq\",\"value\":\"approved\"}}]"`.
+- **`approvalPermissions`** — a **real top-level array** (not a `*Json` string).
+  `roleCode` references a role by its stable `code` — never a display name. List
+  every role that may decide.
+
+### The rule
+
+- **`triggerEvent: "AFTER_UPDATE"`** — fires after any update to an
+  `oeq_checkout` row.
+- **`conditions`** — a JSON string. `status__previous` is the value *before* the
+  update; the `all` clause means "status is now `PENDING_APPROVAL` **and** it
+  wasn't before" — so the workflow starts exactly once, on the transition.
+- **`actions`** — a JSON string containing one `START_WORKFLOW`:
+  - `workflowName` — matches the workflow's `name`.
+  - `callbackUrl` — the generic entity workflow-callback endpoint. On this
+    environment its base is `http://localhost:8080`; on yours use your ERP's base
+    URL. (Platform teams are moving this to a relative path — check
+    `erp platform describe` if `START_WORKFLOW` config changes.)
+  - `config.fields` — "when the workflow approves, set `status` to `APPROVED`;
+    when it rejects, `REJECTED`." This is what makes the decision land back on
+    the row with zero code.
+- **`priority`** — lower runs first when multiple rules match. `20` leaves room
+  for validation rules at `10`.
+
+## Ground yourself first
+
+```bash
+erp schema pull workflow-definition
+erp schema pull entity-rule-definition
+erp workflow validate spk-assembly/metadata/workflow/office-equipment.checkout-approval.json
+erp examples patterns --kind workflow
+```
+
+`erp examples patterns --kind workflow` names three shapes:
+`single-stage-self-decide`, `multi-stage-linear`,
+`multi-stage-conditional-branching`, each pointing at a real shipped file.
+
+## How to verify it worked
+
+After publishing, the rule is installed:
+
+```bash
+erp api get "/api/v1/entity-rules?entityType=oeq_checkout"
+```
+
+```json
+[ { "id": 388, "entityType": "oeq_checkout", "name": "oeq_checkout_submit_workflow",
+    "triggerEvent": "AFTER_UPDATE", "active": true,
+    "actions": "[{\"type\": \"START_WORKFLOW\", ...}]" } ]
+```
+
+Then submit a checkout and confirm the status transitions correctly:
+
+```bash
+erp api put "/api/v1/entities/oeq_checkout/records/3" --body '{"status":"PENDING_APPROVAL"}'
+```
+
+```json
+{ "id": 3, "checkout_number": "CO-200", "status": "PENDING_APPROVAL" }
+```
+
+The record stays `PENDING_APPROVAL` — correct — until a manager decides the task,
+at which point the callback flips it to `APPROVED` / `REJECTED`.
+
+Confirm a real workflow instance was created and see its pending human task —
+`engine-api` re-exposes the workflow engine's read API on its own base URL, so
+this works even when the workflow engine runs as a separate service:
+
+```bash
+erp workflow list --definition oeq_checkout_submit_workflow --record 3
+```
+
+```json
+[ { "id": 5012, "definitionName": "oeq_checkout_submit_workflow",
+    "definitionVersion": 1, "status": "RUNNING", "currentStage": "manager-approval",
+    "correlationId": "3" } ]
+
+1 instance(s) for record 3 of "oeq_checkout_submit_workflow".
+```
+
+```bash
+erp workflow tasks 5012
+```
+
+```json
+[ { "id": 88, "stage": "manager-approval", "status": "PENDING",
+    "approvalObject": "oeq_checkout.approve", "candidateApprovers": ["MANAGER"] } ]
+```
+
+A manager then decides it from the ERP's approval inbox (or, for automation,
+`POST /api/v1/workflow-bridge/human-tasks/{id}/decide`), and the callback lands
+the decision back on the record.
+
+> **Verified in the tutorial:** the rule installs, the submit transition
+> persists without auto-resolving, and `erp workflow list/tasks` returns the
+> real running instance and its pending task.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| workflow never starts | rule condition missing the `status__previous` guard | add it, or the rule re-fires on every later update |
+| workflow starts on every save | same | as above |
+| decision never lands back on the record | `config.fields` missing or wrong status values | `{ "name": "status", "approved": "APPROVED", "rejected": "REJECTED" }` |
+| install rejects the workflow | `stagesJson`/`tasksJson` authored as objects | they are JSON *strings* |
+| nobody can approve | `approvalPermissions` references a role display name | use `roleCode` (the stable `code`) |
+| `!= null` never matches in a rule | action-engine quirk | use `is_not_null` / `is_null` operators |
+
+## What to read next
+
+- [Add business rules and expressions](./add-business-rules.md)
+- Recipe: [entity with an approval workflow + reminder job](../recipes/entity-with-approval-workflow.md)
+- Tutorial chapter 6: [the checkout approval workflow](../tutorial/06-checkout-approval-workflow.md)