Spark ERP Docs

Appearance

5. The checkout entity, page, and lookups ​

The entity ​

spk-assembly/metadata/entities/oeq_checkout.json (real file):

json
{
  "entity": {
    "name": "oeq_checkout",
    "tableName": "oeq_checkout",
    "label": "{\"en\":\"Equipment Checkout\"}",
    "category": "office-equipment",
    "icon": "assignment_ind",
    "color": "#2563EB",
    "pkStrategy": "identity"
  },
  "fields": [
    { "fieldName": "checkout_number", "label": "\"Checkout Number\"", "dataType": "text", "nullable": false, "required": true, "isUnique": true, "isIndexed": true, "isDisplayField": true, "displayOrder": 1 },
    { "fieldName": "equipment_id", "label": "\"Equipment Id\"", "dataType": "long", "nullable": false, "required": true, "isIndexed": true, "displayOrder": 2 },
    { "fieldName": "equipment_tag", "label": "\"Equipment\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 3 },
    { "fieldName": "employee_id", "label": "\"Employee Id\"", "dataType": "long", "nullable": false, "required": true, "isIndexed": true, "flags": "{\"reference\":{\"entityType\":\"Employee\"}}", "displayOrder": 4 },
    { "fieldName": "checkout_date", "label": "\"Checkout Date\"", "dataType": "date", "nullable": false, "required": true, "displayOrder": 5 },
    { "fieldName": "due_date", "label": "\"Due Date\"", "dataType": "date", "nullable": false, "required": true, "isIndexed": true, "displayOrder": 6 },
    { "fieldName": "purpose", "label": "\"Purpose\"", "dataType": "text", "nullable": true, "required": false, "displayOrder": 9 },
    { "fieldName": "status", "label": "\"Status\"", "dataType": "enum", "nullable": false, "required": true, "isIndexed": true, "defaultValue": "DRAFT", "typeParams": "{\"enumValues\":[\"DRAFT\",\"PENDING_APPROVAL\",\"APPROVED\",\"CHECKED_OUT\",\"DUE_SOON\",\"OVERDUE\",\"RETURNED\",\"REJECTED\"]}", "displayOrder": 10 }
  ]
}

The reference flag ​

json
"flags": "{\"reference\":{\"entityType\":\"Employee\"}}"

on employee_id turns on automatic id → name resolution. Every read of an oeq_checkout row now includes a sibling employee_id_label. Verified live:

bash
$ erp api post "/api/v1/entities/oeq_checkout/records" \
    --body '{"checkout_number":"CO-001","equipment_id":3,"employee_id":1,"checkout_date":"2026-09-10","due_date":"2026-10-10","status":"CHECKED_OUT"}'
{ "id": 1, "checkout_number": "CO-001", "employee_id": 1,
  "employee_id_label": "Aria Chen", "status": "CHECKED_OUT" }

"Employee" is a registered provider (backed by the HCM employee plugin), so the flag works. For equipment — which is your own entity, with no registered provider — we denormalize equipment_tag instead.

The status enum ​

DUE_SOON and OVERDUE are in the enum because the reminder job (chapter 7) flips the status into them.

The lookups ​

The checkout create dialog needs an equipment picker and an employee picker.

  • Equipment — your own entity, so build the pair: oeq-equipment-select-options-view.json (Data View: t.id → value, asset_tag - name → label) and oeq-equipment-search.json (search Data Service over it). The dialog's core.lookup sets optionsSourceKey: "oeq-equipment-search".
  • Employee — a registered reference type. The core.lookup sets optionsSourceKey: "employee-search" (the platform-provided search service) and recordType: "Employee".

The page ​

equipment-checkout.json follows the same 6-section shape as the register page, with two differences:

  1. KPIs are Currently Out / Overdue, from oeq-checkout-kpis (a composite of count services filtered on status = CHECKED_OUT and status = OVERDUE).
  2. A detail dialog. The grid's rowClicked fetches the record into page.detailRecord and opens page.detailDialogOpen. Inside, an overview card shows detailRecord.checkout_number, equipment_tag, employee_id_label, status, and an actions card with a Submit for approval button (chapter 6) and a Close button.

The grid's status column chip map includes the new values:

json
"colorMap": { "DRAFT": "default", "PENDING_APPROVAL": "warning", "APPROVED": "info",
              "CHECKED_OUT": "success", "DUE_SOON": "warning", "OVERDUE": "error",
              "RETURNED": "default", "REJECTED": "error" }

Verify ​

bash
erp plugin test example-plugin/spk-assembly
✓ page:equipment-checkout.json
✓ page:equipment-register.json
✓ page:equipment-catalog.json

After publish, the reference flag and the KPI service:

bash
$ erp api post "/api/v1/data-services/oeq-checkout-kpis/execute" --body "{}"
{ "results": { "open": { "value": 1 }, "overdue": { "value": 0 } } }

Next: 6. The checkout approval workflow