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.


| Tab | What you set |
|---|---|
| General | Label, description, and whether it is a web service outside systems call (POST /svc/v1/<name>) |
| Input | What 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 |
| Identity | Who 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 |
| Triggers | What 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) |
| Reaches | The 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 |
| Script | The script. It is checked as you type, including calls to things it will not have |
| Try it | Calls the published version |
| Activity | Its calls and triggers, and each request it sent. A failed trigger can be sent again |
| Stewards | Who answers for it |


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 })orctx.mail({ to, layout, object, id })→{ to, subject }: a message of the service's own, where mail is ticked under Reaches.tois an address, a person's sign-in id (their email, People & departments),department:<id>orgroup:<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.attemptsays 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.
Several instances as one: peers and links
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.
3. A link. On a service's Link tab, Link to a peer: pick the peer and what runs there, then where each of its inputs comes from: a field of the record that sets it off, an input of the transaction whose run sets it off (and a field of a record that input names), or a fixed value. The checks hold it to what the peer published: an input it does not take, one it requires that you left out. A link has no script. Set it off on the Triggers tab: a record event, a transaction's run (after the run commits, with what was entered), a schedule, or a caller (a web service here that hands its input on). Sent once per sends once per event unless you give a value (the lot's number) to send once per value.
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 inctx.output(read back next time asctx.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.