Docs Integration 3
How integration works
On this page


3.1 The two elements
| Element | What it is | Holds |
|---|---|---|
| Connection | An outside system | its base URL; its authentication (none, bearer, header, basic) naming a secret; allow, the only requests services may send it; its timeout; its stewards |
| Service | A script, and what may set it off | its input; whether it is a web service; its callers; its triggers (record events, schedules); who it acts as; what it may reach (objects and connections); the node tag its runs keep to; its stewards |
A service is set off four ways, all running the same script the same way: an outside system calls it over HTTP; a person calls it from the designer (Try it); a record event; the clock. Whichever, it runs as the identity its design names, and reaches only what its design declares.


3.2 Data flows
Inbound ERP →
POST /svc/v1/erp_work_order_in (token: user erp) → callers checked → input checked → script → ctx.records.create("work_order", …) as the service's identity → work order's policy, rule pipe, audit → { output }Outbound a lot released (any form, transaction, service or import) → in the same database transaction, an outbox row → after the commit, a node's outbox worker → script →
ctx.http("erp", …): allowed request, secret added on the server → ERP → done, or retried while ERP is downScheduled the clock → the scheduler plans the run once, whatever the number of nodes → outbox → script with
ctx.event.previous.output (its cursor) → its next page at once if it asks for more3.3 Identity: who a service acts as
Its design's Identity tab (runAs) says who it acts as. Whoever it is, every record it touches is checked as that identity, exactly as at a form, and the audit names on whose behalf it acted.
| runAs | Acts as | Use it when |
|---|---|---|
service (the default) | its own identity, service:<name>, holding exactly the object roles its design grants ("roles": { "work_order": ["planner"] }), on behalf of its caller or the event | almost always: a service can do no more than was approved, whoever calls it; granting a role is approved by that object's stewards |
caller | whoever called it, with their own rights | a service people call to do what they could do themselves; never with triggers or schedules (they have no caller) |
a user id (erp) | that integration user, with that user's roles | an outside system whose rights are managed as a person's |


3.4 Governance: deny by default, approved by whoever answers
- Callers. Nobody calls a service until its callers name them (users, groups). A refused caller reads who may call and which stewards decide.
- Reach. A service touches only the objects and operations in
uses.objects(read,create,update,action,archive), only the connections inuses.connections, and runs only the transactions inuses.transactions; it sends a connection only what the connection allows. Anything else is a fault: logged, refused. - Approval. A service answers to its own stewards and to the stewards of what it reaches: every object it may write, reacts to, or holds a role on, and every connection it uses. An ERP confirmation of lot releases is approved by whoever stewards the connection and the lot.
- Audit. Every run, refused or not: who, how (web, UI, trigger, schedule), the input, the output, each request sent (connection, method, path, status, time; never a secret), and any refusal. Every record write inside it is audited as its identity, on behalf of the caller or the event.