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/ 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 — the scaffold, the manifest, the one Java class, the application/module
2. The equipment category entity + seeded data
3. The equipment register entity
4. The equipment register page — header, KPIs, filter, grid, create dialog
5. The checkout entity, page, and lookups
6. The checkout approval workflow
7. The return-due reminder job
8. Menus, i18n, validate, publish

Before you start

Work through Set up the SDK 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).