@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/tutorial/06-checkout-approval-workflow.md

@@ -0,0 +1,139 @@
+---
+title: "6. The checkout approval workflow"
+audience: tenant
+---
+
+# 6. The checkout approval workflow
+
+## What we're adding
+
+When a user clicks **Submit for approval** on a checkout, its status becomes
+`PENDING_APPROVAL`. That should start an approval process; when the Office
+Equipment Manager approves, the status becomes `APPROVED`; if rejected,
+`REJECTED`. No approval code — a workflow definition, an entity rule, and the
+platform's generic callback.
+
+## 1. The workflow
+
+`spk-assembly/metadata/workflow/office-equipment.checkout-approval.json`
+([real file](./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 }
+  ]
+}
+```
+
+- `stagesJson`, `tasksJson`, `transitionsJson` are **JSON-encoded strings**, not
+  objects.
+- One stage `["manager"]`, one human approval task, no transitions (reaching the
+  only stage's decision ends the instance).
+- `approvalPermissions` is a real array; `roleCode` references the role by its
+  stable `code` (the one we prefixed in chapter 1).
+
+## 2. The rule
+
+`spk-assembly/metadata/rules/oeq_checkout_submit_workflow.json`
+([real file](./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 callback flips status to APPROVED/REJECTED.",
+  "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
+}
+```
+
+- The `all` condition fires exactly on the transition *into*
+  `PENDING_APPROVAL` — `status__previous` is the value before the update.
+  Without that guard the rule would re-fire on every later save.
+- `config.fields` maps the workflow decision back onto the row:
+  approved → `status = APPROVED`, rejected → `status = REJECTED`.
+- `callbackUrl` — the generic entity workflow-callback endpoint. Its base
+  (`http://localhost:8080`) is environment-specific; use your ERP's base URL.
+- `priority: 20` leaves room below for validation rules.
+
+## 3. The Submit button
+
+On the checkout detail dialog (chapter 5), the button `PUT`s the status:
+
+```json
+"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": "setValue", "config": { "field": "page.gridRefreshTick", "value": "${!page.gridRefreshTick}" } },
+  { "id": "a4", "order": 4, "type": "showToast", "config": { "message": "Submitted for approval." } }
+] } }
+```
+
+## Verify
+
+```bash
+erp workflow validate spk-assembly/metadata/workflow/office-equipment.checkout-approval.json
+erp schema validate spk-assembly/metadata/rules/oeq_checkout_submit_workflow.json --schema entity-rule-definition
+```
+
+Both `OK`. After publish, the rule is installed:
+
+```bash
+$ erp api get "/api/v1/entity-rules?entityType=oeq_checkout"
+[ { "id": 388, "entityType": "oeq_checkout", "name": "oeq_checkout_submit_workflow",
+    "triggerEvent": "AFTER_UPDATE", "active": true } ]
+```
+
+Submit a checkout and confirm it transitions and then *stays* pending until a
+human decides it:
+
+```bash
+$ erp api put "/api/v1/entities/oeq_checkout/records/3" --body '{"status":"PENDING_APPROVAL"}'
+{ "id": 3, "checkout_number": "CO-200", "status": "PENDING_APPROVAL" }
+```
+
+`PENDING_APPROVAL` — correct. Confirm a real workflow instance started and find
+its pending task:
+
+```bash
+$ erp workflow list --definition oeq_checkout_submit_workflow --record 3
+[ { "id": 5012, "status": "RUNNING", "currentStage": "manager-approval", "correlationId": "3" } ]
+1 instance(s) for record 3 of "oeq_checkout_submit_workflow".
+
+$ erp workflow tasks 5012
+[ { "id": 88, "stage": "manager-approval", "status": "PENDING", "candidateApprovers": ["MANAGER"] } ]
+```
+
+(`erp workflow list/instance/tasks/history` reach the workflow engine through a
+read-proxy on `engine-api`'s own base URL, so they work even though the workflow
+engine runs as a separate service here.)
+
+The Office Equipment Manager now sees the task in the ERP's **approval inbox**;
+approving it triggers the generic callback, which sets `status = APPROVED` with
+zero code from you.
+
+## Common mistakes
+
+- `stagesJson`/`tasksJson` authored as objects → install fails. They're strings.
+- No `status__previous` guard → workflow starts on every save.
+- `approvalPermissions` with a role *name* instead of `roleCode` → nobody can
+  approve.
+
+**Next:** [7. The return-due reminder job](./07-return-due-reminder-job.md)

package/bundle/docs/tutorial/07-return-due-reminder-job.md

@@ -0,0 +1,129 @@
+---
+title: "7. The return-due reminder job"
+audience: tenant
+---
+
+# 7. The return-due reminder job
+
+## What we're adding
+
+A checkout that is `CHECKED_OUT` and:
+
+- within **3 days** of its `due_date` → status `DUE_SOON`
+- past its `due_date` → status `OVERDUE`
+
+Zero Java. The platform's generic `engine-entity.status-date-sweep` job runs
+daily and applies config rows we seed.
+
+## 1. Ship the shared config entity
+
+So a fresh environment that predates the shared table still gets it.
+`spk-assembly/metadata/entities/entity_status_date_sweep_config.json`
+([real file](./example-plugin/spk-assembly/metadata/entities/entity_status_date_sweep_config.json)) —
+ships only the additive columns (`day_offset`, `seeded_by`); the installer is
+idempotent-additive, so an existing table just gains anything missing.
+
+## 2. Seed the config rows
+
+`spk-assembly/metadata/seed-data/office-equipment-sweep-configs.json`
+([real file](./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"
+    }
+  ]
+}
+```
+
+- Row 1: `day_offset: 3` + `compare_op: lte` → "fires when `due_date` is within
+  3 days" — the "N days before" reminder.
+- Row 2: `day_offset: 0` + `compare_op: lt` → "fires once `due_date` has
+  passed". `when_status_in` includes `DUE_SOON` so a warned checkout still
+  escalates to overdue.
+- Neither sets `set_field`, so they write `status_field` (`status`) itself.
+- `keyFields` includes `day_offset` so the two rows for the same date column are
+  distinct on re-install.
+
+### Status value vs. boolean flag
+
+This module flips a `status` enum because that reads well on the checkout grid.
+A boolean flag works too: since 2026-09-10 the generic job coerces
+`set_status_to: "true"` / `"false"` to a real boolean (and numeric strings to
+numbers) before the write, so a config targeting a `boolean`/`integer`/`numeric`
+`set_field` is fully supported. An earlier draft of this tutorial hit a SQL type
+error doing exactly that — that platform bug is fixed.
+
+## 3. The job registers itself
+
+The platform ships an `AFTER_CREATE` rule on `entity_status_date_sweep_config`
+that calls `ensureEntityStatusDateSweepJobRegistered`. So the first row you seed
+auto-registers the job for your tenant — **you ship no register rule for this
+job** (unlike the aggregation/cadence/compliance jobs).
+
+## Verify
+
+```bash
+erp schema validate spk-assembly/metadata/seed-data/office-equipment-sweep-configs.json --schema plugin-seed-data
+```
+
+`OK`. After publish, the job is enabled:
+
+```bash
+$ erp api get "/api/v1/jobs/engine-entity.status-date-sweep"
+{ "jobCode": "engine-entity.status-date-sweep", "status": "ENABLED",
+  "cronExpression": "0 5 0 * * *", "concurrencyPolicy": "PER_TENANT" }
+```
+
+**This exact sequence was run against the tutorial module:**
+
+```bash
+# a CHECKED_OUT checkout whose due_date is 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"}'
+{ "id": 2, "checkout_number": "CO-100", "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`. `"failed": 0`. Verified end to end.
+
+## Common mistakes
+
+- `set_field` a boolean/numeric column with an *unparseable* `set_status_to`
+  (e.g. `"yes"` into a boolean) → that row counts `failed`. Use `"true"`/`"false"`.
+- `when_status_in` casing not matching the enum → nothing sweeps.
+- Forgot `day_offset` → the "3 days before" rule fires only on the exact day.
+
+**Next:** [8. Menus, i18n, validate, publish](./08-menus-i18n-publish.md)

package/bundle/docs/tutorial/08-menus-i18n-publish.md

@@ -0,0 +1,123 @@
+---
+title: "8. Menus, i18n, validate, publish"
+audience: tenant
+---
+
+# 8. Menus, i18n, validate, publish
+
+## The menu
+
+`spk-assembly/metadata/menu/office-equipment-menu.json`
+([real file](./example-plugin/spk-assembly/metadata/menu/office-equipment-menu.json)) —
+one group node `Office Equipment` with three children pointing at the three
+pages' `route.pattern` values, `modules: ["office-equipment"]`.
+
+Because this is a **standalone** plugin (it ships its own application, chapter
+1), there is no master menu scaffold to keep in sync — one menu file is enough.
+
+## The translations
+
+`spk-assembly/metadata/i18n/en.json`
+([real file](./example-plugin/spk-assembly/metadata/i18n/en.json)) — a flat map
+of every i18n key the three pages, the menu, the app and the module reference
+(~70 keys):
+
+```json
+{
+  "office-equipment.application.title": "Office Equipment",
+  "office-equipment.module.title": "Equipment",
+  "office-equipment.equipment-register.title": "Equipment Register",
+  "office-equipment.equipment-register.newBtn": "New",
+  "office-equipment.equipment-register.column.asset_tag": "Asset Tag",
+  "office-equipment.equipment-checkout.status.OVERDUE": "Overdue",
+  "office-equipment.equipment-checkout.status.DUE_SOON": "Due Soon"
+}
+```
+
+A missing key is caught by `erp plugin test` as `I18N-001`.
+
+## Validate everything
+
+```bash
+erp plugin validate example-plugin/spk-assembly
+erp plugin test     example-plugin/spk-assembly
+```
+
+```
+validated 3 page(s) — clean
+
+Plugin Tests
+────────────────────────────────────────
+✓ page:equipment-catalog.json
+✓ page:equipment-checkout.json
+✓ page:equipment-register.json
+✓ plugin.json:valid-json
+4 passed, 0 failed, 0 semantic warning(s), 3 skipped
+```
+
+And the docs example runner, which also schema-validates every artifact:
+
+```bash
+node developer-docs/examples/test-examples.mjs
+# ... All examples valid.
+```
+
+## Build
+
+```bash
+erp plugin build example-plugin/spk-assembly -o example-plugin/office-equipment-1.0.0.spk
+```
+
+```
+validated 3 page(s) — clean
+packaged 33 files -> example-plugin/office-equipment-1.0.0.spk (231986 bytes)
+sha256: ...
+```
+
+## Publish
+
+```bash
+erp plugin publish example-plugin/office-equipment-1.0.0.spk --tenant 2
+```
+
+```
+installed:
+{"pluginId":"office-equipment","version":"1.0.0","state":"installed","pf4jState":"STARTED", ...}
+```
+
+## Confirm it's all live
+
+```bash
+# pages
+$ erp api get "/api/v1/authoring/pages?module=office-equipment"
+[ {"name":"equipment-catalog", "route":{"pattern":"/office-equipment/equipment-catalog"}, ...},
+  {"name":"equipment-checkout", ...}, {"name":"equipment-register", ...} ]
+
+# seeded reference data
+$ erp api get "/api/v1/entities/oeq_category/records/query?size=10"
+{"rows":[{"category_code":"LAPTOP", ...}, ... ],"total":4}
+
+# the reminder job
+$ erp api get "/api/v1/jobs/engine-entity.status-date-sweep"
+{"status":"ENABLED", ...}
+
+# the approval rule
+$ erp api get "/api/v1/entity-rules?entityType=oeq_checkout"
+[{"name":"oeq_checkout_submit_workflow","active":true, ...}]
+```
+
+Open `/app/office-equipment/equipment/office-equipment/equipment-register` in
+your ERP. The module is complete: three working pages, seeded categories, an
+approval workflow, and a nightly reminder sweep — and you wrote one line of Java.
+
+## Iterating from here
+
+To change anything: edit the file, **bump `plugin.json` `version`**, rebuild,
+re-publish. Don't uninstall to iterate — see
+[Publish and upgrade](../guides/publish-and-upgrade.md) for why.
+
+## Where to go next
+
+- [Guides](../guides/index.md) — every task as its own page
+- [Recipes](../recipes/index.md) — copy-paste solutions
+- [Reference](../reference/index.md) — every schema

package/bundle/docs/tutorial/index.md

@@ -0,0 +1,72 @@
+---
+title: "Tutorial: build the Office Equipment module"
+audience: tenant
+---
+
+# Tutorial: build the Office Equipment module
+
+By the end of this tutorial you will have built, from an empty folder, a small
+real module and published it to your ERP. Every step is something you run, and
+every result shown here was produced by actually running it against a live ERP
+(tenant 2).
+
+## What you're building
+
+**Office Equipment** — a 3-page module for tracking company laptops, monitors and
+phones, and who has them.
+
+| Page | Backed by | Demonstrates |
+| --- | --- | --- |
+| **Equipment Catalog** | `oeq_category` entity, **seeded** with 4 categories on install | an entity + install-time reference data |
+| **Equipment Register** | `oeq_equipment` entity | a full list page: header, KPI row, search/filter, grid, create dialog, a category **lookup** field |
+| **Equipment Checkout** | `oeq_checkout` entity | a **reference-flagged** employee field (auto `_label`), a create dialog, a detail dialog with a **"Submit for approval"** action |
+
+Plus, with no Java:
+
+- a **workflow** — a submitted checkout needs manager approval before it's
+  `APPROVED`;
+- a **scheduled reminder job** — a `CHECKED_OUT` checkout past its due date is
+  swept to `OVERDUE`, and one within 3 days to `DUE_SOON`;
+- **install seeding** — the 4 categories and the 2 sweep configs travel with the
+  `.spk`;
+- **menus** and **i18n**.
+
+## What it looks like at the end
+
+```
+$ erp plugin publish office-equipment-1.0.2.spk --tenant 2
+installed:
+{"pluginId":"office-equipment","version":"1.0.2","state":"installed","pf4jState":"STARTED", ...}
+
+$ erp api get "/api/v1/authoring/pages?module=office-equipment"
+[ {"name":"equipment-catalog", ...}, {"name":"equipment-checkout", ...}, {"name":"equipment-register", ...} ]
+
+$ erp api get "/api/v1/entities/oeq_category/records/query?size=10"
+{"rows":[{"category_code":"LAPTOP","category_name":"Laptops", ...}, ... ],"total":4}
+```
+
+Open `/app/office-equipment/equipment/office-equipment/equipment-register` in the
+ERP and the module is there.
+
+## The finished source
+
+The whole module lives at
+[`example-plugin/`](./example-plugin/) in this docs tree — read any file as you
+go, or diff yours against it. It is the same module the guides reference.
+
+## Chapters
+
+1. [Create the plugin](./01-create-the-plugin.md) — the scaffold, the manifest, the one Java class, the application/module
+2. [The equipment category entity + seeded data](./02-category-entity-and-seed.md)
+3. [The equipment register entity](./03-equipment-entity.md)
+4. [The equipment register page](./04-equipment-register-page.md) — header, KPIs, filter, grid, create dialog
+5. [The checkout entity, page, and lookups](./05-checkout-entity-and-page.md)
+6. [The checkout approval workflow](./06-checkout-approval-workflow.md)
+7. [The return-due reminder job](./07-return-due-reminder-job.md)
+8. [Menus, i18n, validate, publish](./08-menus-i18n-publish.md)
+
+## Before you start
+
+Work through [Set up the SDK](../guides/set-up-the-sdk.md) first — you need
+`erp whoami` returning `"valid": true`. This tutorial assumes the `erp` command
+is on your path (or aliased to `node .../tools/erp-cli/erp.mjs`).

package/bundle/examples/backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-aggregation-configs.json

@@ -0,0 +1,18 @@
+{
+ "entity": "entity_aggregation_config",
+ "keyFields": ["sweep_code"],
+ "source": "hcm-assets",
+ "rows": [
+  {"sweep_code": "asset-inventory-reconciliation", "source_entity": "hcm_asset", "aggregation": "count", "group_by_field": "status", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "asset_status:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "asset-allocation-reconciliation", "source_entity": "hcm_asset_allocation", "aggregation": "count", "group_by_field": "status", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "allocation_status:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "asset-return-reconciliation", "source_entity": "hcm_asset_return", "aggregation": "count", "group_by_field": "status", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "return_status:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "asset-audit-reconciliation", "source_entity": "hcm_asset_audit", "aggregation": "count", "group_by_field": "status", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "audit_status:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "maintenance-history-aggregation", "source_entity": "hcm_asset_maintenance", "aggregation": "count", "group_by_field": "asset_id", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "maint_events_asset:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "maintenance-cost-sync", "source_entity": "hcm_asset_maintenance_cost", "aggregation": "sum", "agg_field": "total_cost", "group_by_field": "maintenance_id", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "maint_cost:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "software-license-usage-sync", "source_entity": "hcm_software_license_assignment", "aggregation": "count", "when_status_in": "ASSIGNED,ACTIVE", "status_field": "status", "group_by_field": "license_id", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "license_seats_used:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "software-license-cost-sync", "source_entity": "hcm_software_license", "aggregation": "sum", "agg_field": "cost_amount", "group_by_field": "status", "target_entity": "hcm_asset_reconciliation", "target_key_field": "metric_key", "target_key_prefix": "license_cost_status:", "target_value_field": "metric_value", "target_timestamp_field": "last_reconciled_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "maintenance-cost-rollup", "source_entity": "hcm_asset_maintenance_cost", "aggregation": "sum", "agg_field": "total_cost", "group_by_field": "maintenance_id", "target_entity": "hcm_asset_maintenance", "target_key_field": "id", "target_value_field": "synced_cost", "target_timestamp_field": "cost_synced_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "predictive-maintenance-event-count", "source_entity": "hcm_asset_maintenance", "aggregation": "count", "date_field": "scheduled_start", "date_compare_op": "gte", "day_offset": -180, "group_by_field": "asset_id", "target_entity": "hcm_asset", "target_key_field": "id", "target_value_field": "recent_maintenance_count", "target_timestamp_field": "maintenance_risk_scored_at", "seeded_by": "hcm-assets", "active": true},
+  {"sweep_code": "predictive-open-maintenance-count", "source_entity": "hcm_asset_maintenance", "aggregation": "count", "when_status_in": "REQUESTED,PENDING_APPROVAL,APPROVED,SCHEDULED,IN_PROGRESS,WAITING_FOR_PARTS", "group_by_field": "asset_id", "target_entity": "hcm_asset", "target_key_field": "id", "target_value_field": "open_maintenance_count", "seeded_by": "hcm-assets", "active": true}
+ ]
+}

package/bundle/examples/backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-cadence-configs.json

@@ -0,0 +1,9 @@
+{
+ "entity": "entity_cadence_config",
+ "keyFields": ["cadence_code"],
+ "source": "hcm-assets",
+ "rows": [
+  {"cadence_code": "asset-audit-schedule", "target_entity": "hcm_asset_audit", "interval_days": 90, "dedupe_target_field": "cadence_marker", "template_json": {"audit_number": "AUDIT-${date}-${ts}", "audit_name": "Scheduled Quarterly Asset Audit ${date}", "audit_type": "QUARTERLY", "status": "DRAFT"}, "seeded_by": "hcm-assets", "active": true},
+  {"cadence_code": "preventive-maintenance-generation", "target_entity": "hcm_asset_maintenance", "interval_days": 1, "source_entity": "hcm_asset", "source_status_field": "status", "source_status_in": "AVAILABLE,ASSIGNED,IN_USE", "source_date_field": "next_pm_date", "due_within_days": 7, "dedupe_target_field": "pm_source_asset_id", "field_map_json": {"asset_id": "id", "asset_number": "asset_number", "pm_source_asset_id": "id"}, "template_json": {"work_order_number": "PM-${sourceId}-${ts}", "maintenance_type": "PREVENTIVE", "priority": "MEDIUM", "problem_title": "Scheduled preventive maintenance", "status": "REQUESTED"}, "seeded_by": "hcm-assets", "active": true}
+ ]
+}

package/bundle/examples/backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-compliance-configs.json

@@ -0,0 +1,74 @@
+{
+ "entity": "entity_compliance_config",
+ "keyFields": ["compliance_code"],
+ "source": "hcm-assets",
+ "rows": [
+  {
+   "compliance_code": "asset-assignment-compliance",
+   "source_entity": "hcm_asset",
+   "when_status_in": "ASSIGNED,IN_USE",
+   "condition_expr": "custody_acknowledged != true",
+   "set_field": "compliance_flag",
+   "set_value": "NON_COMPLIANT",
+   "seeded_by": "hcm-assets",
+   "active": true
+  },
+  {
+   "compliance_code": "asset-allocation-policy-compliance",
+   "source_entity": "hcm_asset_allocation",
+   "when_status_in": "ALLOCATED,ACKNOWLEDGED,IN_USE",
+   "condition_expr": "allocation_type == \"PERMANENT\" && agreement_file_ref_id == null",
+   "set_field": "compliance_flag",
+   "set_value": "POLICY_VIOLATION",
+   "seeded_by": "hcm-assets",
+   "active": true
+  },
+  {
+   "compliance_code": "software-license-compliance",
+   "source_entity": "hcm_software_license",
+   "when_status_in": "ACTIVE,EXPIRING",
+   "related_count_entity": "hcm_software_license_assignment",
+   "related_count_key_field": "license_id",
+   "related_count_status_field": "status",
+   "related_count_status_in": "ASSIGNED,ACTIVE",
+   "condition_expr": "related_count > entitlement_quantity",
+   "set_field": "compliance_flag",
+   "set_value": "OVER_ALLOCATED",
+   "seeded_by": "hcm-assets",
+   "active": true
+  },
+  {
+   "compliance_code": "software-license-unused-detection",
+   "source_entity": "hcm_software_license_assignment",
+   "when_status_in": "ASSIGNED,ACTIVE",
+   "condition_expr": "(last_used_date == null && daysBetween(start_date, now()) > 90) || (last_used_date != null && daysBetween(last_used_date, now()) > 90)",
+   "set_field": "usage_flag",
+   "set_value": "UNUSED",
+   "seeded_by": "hcm-assets",
+   "active": true
+  },
+  {
+   "compliance_code": "asset-audit-exception-escalation",
+   "source_entity": "hcm_asset_return_exception",
+   "when_status_in": "OPEN,IN_PROGRESS",
+   "condition_expr": "resolution_due_date != null && daysBetween(resolution_due_date, now()) > 0",
+   "escalation_entity": "hcm_asset_compliance_escalation",
+   "escalation_dedupe_field": "source_record_id",
+   "escalation_timestamp_field": "raised_at",
+   "field_map_json": {"severity": "severity", "details": "description"},
+   "escalation_template_json": {"source_entity": "hcm_asset_return_exception", "escalation_type": "RESOLUTION_OVERDUE", "status": "OPEN"},
+   "seeded_by": "hcm-assets",
+   "active": true
+  },
+  {
+   "compliance_code": "predictive-maintenance-risk",
+   "source_entity": "hcm_asset",
+   "when_status_in": "AVAILABLE,ASSIGNED,IN_USE",
+   "condition_expr": "coalesce(recent_maintenance_count, 0) >= 3 || coalesce(open_maintenance_count, 0) >= 2",
+   "set_field": "maintenance_risk",
+   "set_value": "HIGH",
+   "seeded_by": "hcm-assets",
+   "active": true
+  }
+ ]
+}

package/bundle/examples/backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-cross-plugin-configs.json

@@ -0,0 +1,9 @@
+{
+ "entity": "entity_cross_plugin_action_config",
+ "keyFields": ["action_code"],
+ "source": "hcm-assets",
+ "rows": [
+  {"action_code": "asset-separation-return", "trigger_entity": "employee", "trigger_status_field": "employment_status", "trigger_status_in": "TERMINATED,SEPARATED", "trigger_key_field": "id", "related_entity": "hcm_asset_allocation", "related_match_field": "employee_id", "related_status_field": "status", "related_status_in": "ALLOCATED,ACKNOWLEDGED,IN_USE", "create_entity": "hcm_asset_return", "create_dedupe_field": "allocation_id", "create_template_json": {"return_number": "ASR-${relatedId}-${ts}", "status": "REQUESTED", "reason": "EMPLOYEE_SEPARATION"}, "create_field_map_json": {"asset_id": "asset_id", "employee_id": "employee_id"}, "related_set_field": "status", "related_set_value": "RETURN_PENDING", "seeded_by": "hcm-assets", "active": true},
+  {"action_code": "software-license-reclamation", "trigger_entity": "employee", "trigger_status_field": "employment_status", "trigger_status_in": "TERMINATED,SEPARATED", "trigger_key_field": "id", "related_entity": "hcm_software_license_assignment", "related_match_field": "employee_id", "related_status_field": "status", "related_status_in": "ASSIGNED,ACTIVE", "related_set_field": "status", "related_set_value": "RECLAMATION_PENDING", "seeded_by": "hcm-assets", "active": true}
+ ]
+}

package/bundle/examples/backend/modules/hcm-assets/spk-assembly/metadata/seed-data/hcm-assets-document-configs.json

@@ -0,0 +1,9 @@
+{
+ "entity": "entity_document_generator_config",
+ "keyFields": ["document_code"],
+ "source": "hcm-assets",
+ "rows": [
+  {"document_code": "asset-audit-report", "source_entity": "hcm_asset_audit", "status_field": "status", "when_status_in": "COMPLETED", "target_file_field": "report_file_ref_id", "format": "json", "cabinet_name": "HCM Assets Documents", "file_name_template": "asset-audit-report-${id}-${date}.json", "child_entity": "hcm_asset_audit_item", "child_match_field": "audit_id", "seeded_by": "hcm-assets", "active": true},
+  {"document_code": "asset-audit-certificate", "source_entity": "hcm_asset_audit", "status_field": "status", "when_status_in": "COMPLETED", "target_file_field": "certificate_file_ref_id", "format": "json", "cabinet_name": "HCM Assets Documents", "file_name_template": "asset-audit-certificate-${id}-${date}.json", "include_fields": "id,audit_number,audit_name,status,start_date,end_date,scope,location", "seeded_by": "hcm-assets", "active": true}
+ ]
+}