ERP Plugin Developer Docs

Appearance

Add a compliance-sweep job ​

What you're doing ​

"Find rows that break a policy and flag them — or raise an escalation." More expressive than a reminder job: the condition is a boolean expression over the row's fields (plus now and an optional related_count), not just one date column. No Java. One entity_compliance_config row, run by engine-entity.compliance-sweep, shipped as seed data.

Use this instead of a reminder job whenever the condition is more than "one date vs now".

Two outcomes ​

OutcomeSet
FLAG — set a field on the offending rowset_field, set_value
ESCALATION — raise a row in a separate entity, deduped by source idescalation_entity, escalation_dedupe_field, field_map_json, escalation_template_json

The complete example — flag un-acknowledged checkouts ​

spk-assembly/metadata/seed-data/office-equipment-compliance-configs.json (standalone example, real file):

json
{
  "entity": "entity_compliance_config",
  "keyFields": ["compliance_code"],
  "source": "office-equipment",
  "rows": [
    {
      "compliance_code": "checkout-acknowledgement-compliance",
      "source_entity": "oeq_checkout",
      "when_status_in": "CHECKED_OUT,DUE_SOON,OVERDUE",
      "condition_expr": "custody_acknowledged != true && daysBetween(checkout_date, now()) > 7",
      "set_field": "compliance_flag",
      "set_value": "NON_COMPLIANT",
      "seeded_by": "office-equipment",
      "active": true
    }
  ]
}

Line by line ​

  • compliance_code — unique id; natural key.
  • source_entity — table to evaluate.
  • when_status_in — optional status pre-filter.
  • condition_expr — a boolean expression in the platform ExpressionEvaluator language. In scope: the row's own fields, now, and (if configured) related_count. Whitelisted functions only — daysBetween, now, coalesce, arithmetic, &&, ||, !, comparisons. No ternary, no in, no ^. A row where the expression is true is non-compliant.
  • set_field / set_value — FLAG outcome. Idempotent: a row already equal to set_value is skipped.
json
"related_count_entity": "oeq_license_assignment",
"related_count_key_field": "license_id",
"related_count_status_in": "ACTIVE",
"condition_expr": "related_count > entitlement_quantity"

→ counts ACTIVE assignments whose license_id equals the source row's id, binds it as related_count, and flags over-allocated licences.

Escalation variant ​

Replace set_field/set_value with:

json
"escalation_entity": "oeq_compliance_case",
"escalation_dedupe_field": "checkout_id",
"field_map_json": { "checkout_id": "id", "employee_id": "employee_id" },
"escalation_template_json": { "status": "OPEN", "severity": "HIGH" }

→ one oeq_compliance_case per offending checkout, deduped on checkout_id.

The register rule ​

spk-assembly/metadata/rules/ensure_compliance_sweep_job_registered.json:

json
{
  "entityType": "entity_compliance_config",
  "name": "ensure_compliance_sweep_job_registered",
  "triggerEvent": "AFTER_CREATE",
  "conditions": null,
  "actions": "[{\"type\": \"EXECUTE_SERVICE\", \"service\": \"ensureEntityComplianceSweepJobRegistered\"}]",
  "priority": 10,
  "active": true
}

Ground yourself first ​

bash
erp schema pull entity-compliance-config
erp examples patterns --kind jobs     # "condition-based-compliance-flagging"

How to verify it worked ​

bash
erp api get "/api/v1/jobs/engine-entity.compliance-sweep"
# → { "status": "ENABLED", ... }

erp api post "/api/v1/jobs/engine-entity.compliance-sweep/execute" --body "{}"
erp api get "/api/v1/entities/oeq_checkout/records/query?size=10"

Rows that break the policy now carry "compliance_flag": "NON_COMPLIANT".

Common mistakes ​

SymptomCauseFix
expression parse errorused ternary / in / ^rewrite with whitelisted operators
nothing flaggedcondition_expr logic inverted (true = compliant)true must mean non-compliant
related_count is always 0related_count_key_field isn't the FK back to the source idfix the FK column name
escalations duplicateescalation_dedupe_field not the source-id columnmust be a numeric column holding the source id