ERP sends work orders to OpenCore MES, and OpenCore MES confirms each released lot to ERP. Four designs in one change request: a connection, a web service, a trigger, their scripts. Then a token for ERP and the secret for the connection.
DV-01Give ERP an identity and a token
Purpose
ERP calls as an integration user; its token says who is calling.
Done by
IT
Before you start
The user erp exists and is active (People & departments). The seed has one.
#
Do this
You should see
Done
1
On the server, with DATABASE_URL set to the plant's database:
node app/mes/db/token.mjs erp "ERP production"
A token mes_…, scope service:call, printed once. Only its hash is kept.
2
Give the token to ERP's administrators through your secrets process.
—
The token only says who calls. Which services that user may call is each service's design (its callers), approved like any change.
// ERP sends a work order; it is created as this service, through the work order's policy and rule pipe.
export default async function erp_work_order_in(ctx) {
const wo = await ctx.records.create("work_order", {
wo_no: ctx.input.wo_no, item: ctx.input.item, qty: ctx.input.qty, line: ctx.input.line,
});
ctx.output = { id: wo.id, wo_no: wo.wo_no, state: wo.state };
return ctx;
}
DV-04Write the trigger that confirms a released lot
Purpose
After a lot's release commits, ERP is told; retried while ERP is down.
Done by
Designer
#
Do this
You should see
Done
1
Add to this change → + service, name erp_lot_released; not a web service.
Run the drafts as they will run, change nothing, and keep the runs as their evidence.
Done by
Designer
#
Do this
You should see
Done
1
Under erp_lot_released's script, Dry run with an event { "kind": "transition:release", "object": "lot", "id": "<a lot id>" } and responses { "POST /confirmations": { "status": 201, "body": { "id": "DRY-1" } } }.
Its output { "confirmation": "DRY-1" }, the lot it read, and the request it would send, with the credential marked “not sent”. Nothing reaches ERP.
2
Again with { "POST /confirmations": { "status": 503 } }.
The error “ERP is unavailable”, marked as asking for a retry.
3
Name each run and press Save as test case.
The script's test cases list them.
4
Under erp_work_order_in, dry-run with { "wo_no": "WO-2001", "item": "PA66", "qty": 0, "line": "L1" }.
Refused by the work order's own rule: “The quantity must be more than zero.” A real create goes through the same pipe.
5
Again with a quantity of 10; save both as test cases.
The work order it would create, and nothing created.
A dry run runs as the service will: its own service role with the draft's roles, its user, or its caller (you, or one of its callers standing in). Acting with anyone's rights but your own is audited (dry-run-as).
DV-06Submit, approve, and set the secret
Purpose
Nothing answers until the change is approved and executed; the outbound call needs its secret.
Done by
Designer; reviewer; department representatives; IT
#
Do this
You should see
Done
1
Before approval, call POST /svc/v1/erp_work_order_in.
404: nothing answers before it is published.
2
Write the reason, run the fitness test, submit; the first submission asks Who executes it?: an executor (People & departments, Roles → Designer).
It passes: the scripts compile and call only what they will have; their test cases pass. Will need approval from: Engineering, Production and Quality: the stewards of the connection, of the services, and of the work order and the lot they reach.
3
Review, then approve for each department.
Approved: nothing answers yet. It waits for its executor (in their inbox, and on Approvals).
4
The executor, when ERP is ready for it, opens the change and presses Execute.
Executed: the services are live at once, on every node. Where the plant executes at the last signature (People & departments → Approvals → Execution cleared), the last approval did this.
5
The executor calls it once, as ERP will, and checks what it did; then It works (sign) on the change, or Report a problem… with a picture of the page that shows it.
Verified, or a request for change with the picture for the designers, and the change offered for rolling back.
6
IT sets the secret on every node that may run the trigger: MES_SECRET_ERP_TOKEN=<ERP's credential>, then restarts the node.
Secret names are lower case letters, digits and _, up to 48; the variable is the name in upper case after MES_SECRET_.