ERP Plugin Developer Docs

Appearance

A resolved reference column in a grid ​

When you need this ​

A grid column (or a detail-view field) that should show a person's or record's name, but the entity only stores the id. Don't bind the raw *_id — bind the automatically-resolved *_id_label sibling.

The one line on the entity field ​

json
{
  "fieldName": "employee_id",
  "label": "\"Employee Id\"",
  "dataType": "long",
  "flags": "{\"reference\":{\"entityType\":\"Employee\"}}"
}

That flags string turns on id → display-name resolution platform-wide. From then on, every read of the entity — GET .../records/query (the grid) and GET .../records/{id} (single record) — gains a sibling key employee_id_label, resolved in one batched call per page load, not per row.

Verified live in the tutorial:

bash
$ erp api post "/api/v1/entities/oeq_checkout/records" --body '{"...":"...","employee_id":1,"...":"..."}'
{ "id": 1, "employee_id": 1, "employee_id_label": "Aria Chen", ... }

The grid column ​

json
{ "name": "employee_id_label", "type": "string",
  "headerKey": "office-equipment.equipment-checkout.column.employee" }

Bind employee_id_label, not employee_id.

The rules ​

  • entityType must be a registered provider — one that exposes a batch-names endpoint. "Employee" (backed by the HCM employee plugin) is the only one shipped today. An unregistered entityType simply produces no _label key — no error.
  • For a foreign key to your own entity (no registered provider), denormalize instead: store category_name next to category_id and write both on create. That's what the tutorial's oeq_equipment does.
  • You can add the flag to a field after the fact via PUT /api/v1/entities/{id}/fields/{fieldId} — the _label key appears on the next read.