OpenCore MES Try the demo

Docs Integration 4

A first integration, step by step

On this page

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
PurposeERP calls as an integration user; its token says who is calling.
Done byIT
Before you start
  • The user erp exists and is active (People & departments). The seed has one.
#Do thisYou should seeDone
1On 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.
2Give 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.
The ERP connection's Allowed requests: POST /confirmations and GET /orders
A connection's Allowed requests: the only calls a service may send that system.
The ERP connection's Allowed requests: POST /confirmations and GET /ordersA connection's Allowed requests: the only calls a service may send that system.
DV-02Describe ERP as a connection
PurposeThe outside system, the only requests services may send it, and its credential by name.
Done byDesigner
#Do thisYou should seeDone
1Designer → Services & connections → New connection, name erp, or Add to this change → + connection in an open change.The connection's tabs: General, Authentication, Allowed requests, Activity, Stewards.
2General: label, base URL https://erp.plant.local/api; timeout 3000 ms.A URL with a user, a password, a query or a fragment is refused: credentials go in a secret.
3Authentication: bearer, secret erp_token.Only the secret's name is in the design.
4Allowed requests: POST /confirmations.Nothing else may be sent to ERP.
5Stewards: Engineering.—
{
  "name": "erp", "label": "ERP",
  "baseUrl": "https://erp.plant.local/api",
  "auth": { "kind": "bearer", "secret": "erp_token" },
  "allow": [{ "method": "POST", "path": "/confirmations" }],
  "timeoutMs": 3000,
  "stewards": ["engineering"]
}
A service's Script tab: erp_confirm_lot posting a lot's confirmation to ERP
A service's script: one function, the context in and out; ctx.http reaches only what its connection allows.
A service's Script tab: erp_confirm_lot posting a lot's confirmation to ERPA service's script: one function, the context in and out; ctx.http reaches only what its connection allows.
DV-03Write the web service ERP calls
PurposeERP sends a work order; it is created through the work order's own policy and rule pipe.
Done byDesigner
Before you start
  • The change from DV-02 is open.
#Do thisYou should seeDone
1Add to this change → + service, name erp_work_order_in.Its tabs: General, Input, Identity, Triggers, Reaches, Script, Try it, Activity, Stewards. A script is made with it.
2General: label, description; tick web service.Its address will be POST /svc/v1/erp_work_order_in.
3Input: wo_no string, item string, qty decimal, line choice of L1, L2, L3, all required.Each input is checked before the script runs; a bad one answers 400 with the field named.
4Identity: its own service role, holding work_order planner; callers: the user erp.It plans work orders, whoever calls it.
5Reaches: work_order: create.—
6Script: as below.Checked as you type: a syntax error on its line; a call it will not have (a typo, fetch) as a warning.
7Stewards: Production.Will need approval from adds the work order's stewards.
{
  "name": "erp_work_order_in", "label": "Work order from ERP",
  "description": "ERP sends a planned work order.",
  "input": {
    "wo_no": { "label": "Work order no.", "type": "string", "required": true },
    "item":  { "type": "string", "required": true },
    "qty":   { "type": "decimal", "required": true },
    "line":  { "type": "enum", "values": ["L1", "L2", "L3"], "required": true }
  },
  "http": { "enabled": true },
  "callers": { "users": ["erp"], "groups": [] },
  "on": [],
  "runAs": "service",
  "roles": { "work_order": ["planner"] },
  "uses": { "connections": [], "objects": { "work_order": ["create"] } },
  "stewards": ["production"]
}
// 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
PurposeAfter a lot's release commits, ERP is told; retried while ERP is down.
Done byDesigner
#Do thisYou should seeDone
1Add to this change → + service, name erp_lot_released; not a web service.—
2Triggers: Add trigger, object lot, event transition:release.The events are create, update, archive, restore, or transition:<action> of the object.
3Identity: the user erp. Reaches: lot: read; connection erp.A trigger has no caller: it cannot run as its caller.
4Script: as below. A 5xx from ERP throws with retry: true; any other refusal throws with words.—
{
  "name": "erp_lot_released", "label": "Lot released → ERP",
  "description": "Confirms a released lot to ERP.",
  "input": {}, "http": { "enabled": false },
  "callers": { "users": [], "groups": [] },
  "on": [{ "object": "lot", "event": "transition:release" }],
  "runAs": "erp",
  "uses": { "connections": ["erp"], "objects": { "lot": ["read"] } },
  "stewards": ["production"]
}
// A released lot is confirmed to ERP.
export default async function erp_lot_released(ctx) {
  const lot = await ctx.records.get("lot", ctx.event.id);
  const res = await ctx.http("erp", {
    method: "POST", path: "/confirmations",
    body: { lot_no: lot.lot_no, item: lot.item, qty: lot.qty, uom: lot.uom, event: ctx.event.id },
  });
  if (res.status >= 500) throw Object.assign(new Error("ERP is unavailable"), { retry: true });
  if (!res.ok) throw new Error(`ERP refused the confirmation (${res.status})`);
  ctx.output = { confirmation: res.body.id };
  return ctx;
}
A service's Try it tab: a lot's number sent, ERP's confirmation answered
Try it: the published service called as you, through its callers and checks; its answer below.
A service's Try it tab: a lot's number sent, ERP's confirmation answeredTry it: the published service called as you, through its callers and checks; its answer below.
DV-05Dry-run the scripts and keep test cases
PurposeRun the drafts as they will run, change nothing, and keep the runs as their evidence.
Done byDesigner
#Do thisYou should seeDone
1Under 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.
2Again with { "POST /confirmations": { "status": 503 } }.The error “ERP is unavailable”, marked as asking for a retry.
3Name each run and press Save as test case.The script's test cases list them.
4Under 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.
5Again 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
PurposeNothing answers until the change is approved and executed; the outbound call needs its secret.
Done byDesigner; reviewer; department representatives; IT
#Do thisYou should seeDone
1Before approval, call POST /svc/v1/erp_work_order_in.404: nothing answers before it is published.
2Write 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.
3Review, then approve for each department.Approved: nothing answers yet. It waits for its executor (in their inbox, and on Approvals).
4The 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.
5The 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.
6IT 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_.
The integration monitor's Run history: runs of the two services, from a screen and from the schedule
The monitor's Run history: every run, how it was set off, its outcome and who set it off.
The integration monitor's Run history: runs of the two services, from a screen and from the scheduleThe monitor's Run history: every run, how it was set off, its outcome and who set it off.
DV-07Call it from ERP, and watch it
PurposeThe inbound call, the outbound confirmation, and where to see both.
Done byERP's developer; designer
#Do thisYou should seeDone
1GET /svc/v1/openapi.json with ERP's token.An OpenAPI 3.1 description of exactly the services this user may call.
2Call it (in a shell where TOKEN holds the token):
curl -X POST https://mes.plant.local/svc/v1/erp_work_order_in -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: order-2001" -d '{"wo_no":"WO-2001","item":"PA66","qty":10,"line":"L1"}'
200 { "output": { "id": "…", "wo_no": "WO-2001", "state": "planned" } }.
3Send the same request again, same Idempotency-Key.The first answer again; no second work order.
4Release a lot (a person, a transaction, anything).Within seconds ERP receives POST /confirmations, with the bearer credential.
5Open Design → Integration monitor, and the services' Activity tabs.The inbound calls, the outbound requests, the trigger's runs. A failed one can be Send again once ERP is back.