OpenCore MES Try the demo

Docs Designing the system 7

Services: talking to outside systems

On this page

A service is a script plus what may set it off and what it may reach. Create one with New service or + service. A new service can do nothing and be called by nobody until you say so.

A service's Script tab: erp_confirm_lot posting a lot's confirmation to ERP
A service's Script tab: 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 tab: one function, the context in and out; ctx.http reaches only what its connection allows.
TabWhat you set
GeneralLabel, description, and whether it is a web service outside systems call (POST /svc/v1/<name>)
InputWhat a caller sends, typed like fields. Each input is checked before the script runs. A long text holds 2 000 characters unless it says max (up to 4 000 000: a file's text sent whole, such as an inspection tool's KLARF); over 200 000 the service takes a body of up to 24 MB, and the audit trail keeps such a text as its length and hash
IdentityWho it acts as (runAs): its own service role (the default: an identity of its own, holding only the object roles you grant it here), its caller, the person whose change set it off (actor: the person who changed the record or ran the transaction its trigger names, with their rights alone; a change made by a plan, a service or the clock sets it off for no one, and it cannot run on a schedule), or a named user (such as the integration user erp). And its callers: the users and groups allowed to call it
TriggersWhat sets it off besides a call: record events (a lot is created, a lot is released…) and schedules (section 8). And where it runs (runOn)
ReachesThe objects it may read, create, update, act on or archive, the connections it may use, the transactions it may run, and what it may ask of an installed suite (From the … suite). Nothing else is reachable
ScriptThe script. It is checked as you type, including calls to things it will not have
Try itCalls the published version
ActivityIts calls and triggers, and each request it sent. A failed trigger can be sent again
StewardsWho answers for it
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.

The script has the rule-script contract (one function, context in, context out, throw to refuse), with what the service may reach on its context:

// 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, qty: lot.qty } });
  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;
}
  • ctx.input: what the caller sent. ctx.event: the record event ({ kind, object, id, by }) or the schedule (section 8). ctx.user: who it acts as. ctx.output: what the caller gets back.
  • ctx.records.get / list / create / update / action / archive / restore: every record it touches goes through the object's policies and rule pipe, exactly as at a form, and is audited as the service, on behalf of whoever or whatever set it off. A rule that throws refuses the service's write, with the rule's words.
  • ctx.http(connection, { method, path, query, body }) → { status, ok, body }: only what the connection allows.
  • ctx.mail({ to, subject, body }) or ctx.mail({ to, layout, object, id }) → { to, subject }: a message of the service's own, where mail is ticked under Reaches. to is an address, a person's sign-in id (their email, People & departments), department:<id> or group:<id> (its mailbox); a mail layout about a record (section 13, Mail layouts) fills its placeholders from that record. Written to the outbox with the run and sent by the instance that sends mail; a dry run reports it and sends nothing.
  • ctx.transactions.run(name, input, { key }) → { run, changes, records }: runs a transaction ticked under Reaches, exactly as a person running it would, all or nothing: its checks, and each step through the object's policies and rule pipe. Use it when outside systems start things the plant starts with a transaction (ERP starting a lot runs Start a lot, so an obsolete product is refused for ERP as it is on the floor). If the service runs as its own service role, the transaction's Callers tab must tick the service under Services (its stewards approve that, and the checks say when it is missing). A refusal comes back with the transaction's own words and field, and reaches the caller as a 422. key (the lot's number, the event's id) makes a run sent again answer the first, so a retried trigger does not start a lot twice. A transaction someone signs is never run by a service. Dry run shows what the transaction would change (Would run) and writes nothing.
  • Throw with words to refuse (a caller gets 422 and your message). **Throw with { retry: true }** when the other system is down: a trigger is then retried, with a growing wait (2, 4, 8… seconds, at most five minutes apart), ten times over about a quarter of an hour before it is marked dead. Each retry runs the whole script again: ctx.event.attempt says which attempt this is, so call the other system first and write records after, or check what an earlier attempt already wrote.

Called as a web service. The caller sends its token and JSON. With an Idempotency-Key header (one per business message: the order number and its revision), a retry answers the first result instead of running again; a retry sent while the first call is still running is answered 409 (idempotency.running, with Retry-After) and should simply be sent again. A key is its caller's own: two systems may use the same text. A refusal answers the script's or the rule's words; a failure inside the server answers "The request failed." and the details stay in the server's log. Every answer carries API-Version, the version of the contract the platform keeps (docs/contracts/http-apis: its changelog says what each version added).

Changing a web service its callers rely on. What a web service takes is a promise to whoever calls it. A change that would break a caller (an input removed, retyped, made required or losing a value, a new required input, the service no longer a web service, a caller taken off) is refused at the fitness test when someone called it over HTTP in the last 30 days: the Web services' callers check names them and how often they called. Give them notice instead: on the service's General tab, tick Deprecated and give the date it starts, its sunset (the date after which it may change) and its successor (the service to use instead), with a note. Once that change is live, every call is answered with Deprecation, Sunset and Link headers and the service's OpenAPI description says until when; after the sunset, the breaking change goes through (with a warning). Or publish the new shape under a new name, and name it as the successor. A service nobody called in 30 days changes with a warning only.

How a trigger behaves. A record-event trigger runs after the record's change is committed, never for one that was rolled back, and is retried while the other system is down. A service never sets itself off, and a chain of services stops at three. The other system should treat the request as idempotent: it may, rarely, receive it twice.

Dry run executes the draft with everything it may call callable and nothing changed: reads are real, writes go through policy and the rule pipe but are not saved, and requests are checked against the connection and answered from the responses you give ({ "POST /confirmations": { "status": 201, "body": { "id": "X" } } }), never sent. In the fitness test, an object new in the same change has no records yet: the service reads none, and what it would create of it is shown but not checked, since its policies apply once it is live.

A plant may run several OpenCore MES instances: one per site, one hosting a suite of its own (quality on one, the warehouse on another), a supplier's. Each publishes web services, transactions and named queries at /svc/v1. Linked, they work as one system: a lot started at one plant is noted at the next, an order taken by the instance that runs the shop is released on the floor of the one that runs the plant, each change checked by the instance it happens on.

1. On the other instance, its designers publish what you may run or read there (a transaction's Callers tab, The web; a named query's Web tab; a service's General tab) and name an integration user among its callers. Its IT issues that user a token with the scopes service:call, transaction:run and query:run.

2. Here, a peer. New connection, tick Peer on its General tab, give the other instance's address and the name of the secret that will hold the token (IT sets MES_SECRET_<NAME> on this server). A peer lists no allowed requests: what it publishes is all of it you reach. On the Published tab, Discover reads what it publishes to that token: its plant's name, the suites it runs, and each web service, transaction and named query with its inputs. A peer not yet approved may be discovered while you design it, with a secret no other connection uses.

How it is sent. Through the outbox, after what set it off is committed, as the identity on the Identity tab here and as the integration user there, through that instance's own callers, policies and rules. It carries a key (Idempotency-Key), so sent again, the other instance answers the first run and changes nothing twice. The other instance busy or down: tried again with a growing wait, then given up on after ten. A refusal there (the lot is not known there, a check fails): refused here too, in its words, and not tried again by itself.

Logic a mapping cannot say goes in a script, with the peer under Reaches:

  • ctx.peers.run(peer, name, input, { key }): runs a web service or a transaction there (once per key);
  • ctx.peers.preview(peer, transaction, input): what it would change, nothing written;
  • ctx.peers.read(peer, query, params) → { columns, rows, next }: a named query's rows. On a schedule this is a puller: keep where it got to in ctx.output (read back next time as ctx.event.previous.output).

The copilot drafts all three: ask it to link two instances, to pull a peer's rows every hour, or to wrap a peer's transaction in a web service here; it reads what the peer publishes (discover_peer) before it maps anything.

Picking up where each side left off. The monitor's Peers tab (section 13) shows, for each peer, what is left to send (waiting, to be tried again, given up on, refused this week; waiting since when) and where each puller stands (its last good run and what it answered, its next, what it missed). After an outage, Send again sends what was given up on or refused, each with its own key, so nothing runs twice there. A sandbox, the test sandbox and a dry run send nothing to a peer: a dry run shows what it would send.

Trying both sides together. Give the peer's connection Its test sandbox's address, and have IT set MES_SECRET_PEER_TEST_<SECRET> to a test token the peer's test sandbox issued. Put the change on each instance under test: this instance's test sandbox then discovers and sends to the peer's test sandbox, never the live one, and links fire there as they would live. Nothing reaches either live system.

The source goes first. A link may name what the other instance does not publish yet, while the change there that publishes it is still open (type its name under Or one it will publish). Once every department has approved this change, it does not execute: it waits, approved, and its page says for what (Approved: waits for another instance). It executes by itself, within a minute, once the change on the other instance has executed and what it links to is published there (or press Check again). Where changes are executed by hand, it waits for its executor as any approved change does: Execute does nothing until the other instance publishes it, and they are told by mail once it does. If the other change is rejected, send this one back to design.

Not yet. Instances find each other only through the connections you design (no automatic announcing), and a peer's catalogue is read when someone asks (Discover), not kept up to date by itself.

Where scripts run. Every script (rules, services, dry runs) runs in a separate script runner: it holds no passwords or keys, cannot read the server's files, and a script that loops or eats memory is stopped and reported as a fault. Form buttons that call a service are not there yet.