Flows
A flow automates work across ConnectCloud: a graph of nodes started by a trigger. Triggers are module events
(a desk item was created), schedules (cron), manual starts and inbound webhooks; nodes call module actions, branch
(if, switch), set values, wait, ask people (human_task), run in parallel or in loops, call sub-flows, send mail
and use AI. A flow is stored as YAML – the portal's graphical builder edits the same document – so you can keep
flows in your own repository and deploy them through the API.
All routes live under /api/flows/v1 (reference).
Permissions and ownership
| Permission | Grants |
|---|---|
tenant:flows:read |
see tenant flows, their versions, triggers and runs; the catalogue and validation |
tenant:flows:write |
create, edit, test, publish and start your own personal flows |
tenant:flows:admin |
everything for tenant flows; live test runs; see the metadata and YAML of everyone's personal flows |
tenant:flows:tasks |
the task inbox: approvals and forms flows assign to you |
- A personal flow (
owner: personal) belongs to the person who created it and acts with their permissions. Only they edit, publish, start and cancel it; its runs are theirs alone (others, admins included, get404). Service-account keys own no personal flows: creating one answers403 person_required. Use a personal API key. - A tenant flow (
owner: tenant,serviceAccountIdrequired) needstenant:flows:adminand acts as the service account it names. A service-account key withtenant:flows:admincan manage tenant flows. - A scoped flow belongs to a desk space or a forge project: create it with
owner: tenant, aserviceAccountIdandscope(desk:space:<id>orforge:project:<id>, the id as a lower-case UUID). It acts as its service account like every tenant flow, but who sees and manages it is decided by the module that owns the scope, live at every request – not bytenant:flows:admin: people who see the space or project (and hold a flows permission) read the flow and its runs; whoever the module lets manage it (a desk space: desk admins and the space's maintainers; a forge project: forge admins and the project's maintainers and admins while the project is active) creates, changes, publishes, starts and cancels it withtenant:flows:writeortenant:flows:admin–tenant:flows:adminalone is not enough. A live test run still needstenant:flows:admin. Anyone else gets404; someone who sees but may not manage it403. When the owning module cannot answer, the routes of a scoped flow answer503 scope_unavailable(retry later). Scoped flows are listed withGET /flows?scope=…, never in the plain list; their runs withflowId. They are hidden from service-account keys (no person the module could look up). - Whoever may change a flow may also start and cancel its runs.
The definition
schemaVersion: 1
key: monitoring-incident # lower case, digits, dashes; fixed after creation
name: Monitoring alert as incident
triggers:
- { id: alarm, kind: webhook, auth: hmac, filter: "trigger.data.status == 'down'" }
nodes:
incident:
kind: action
action: desk.item.create
params:
spaceId: SUP
title: "Monitoring: {{ trigger.data.host }} unreachable"
dedupeKey: "monitoring:{{ trigger.data.host }}"
edges:
- alarm -> incident
triggers(event|schedule|manual|webhook),nodes(id → node) andedges(from -> to, orfrom.port -> tofor a node with several exits, e.g.check.true -> notify) form the graph; optional aredescription,inputs(a JSON schema of the start data of manual starts and sub-flows),settings,varsandlayout(positions of the graphical builder, ignored when the flow runs).- Parsing is strict: unknown and duplicate keys are errors with line and column.
- Fields such as
condition,filteroritemsare expressions; every other string is a template, plain text unless it contains{{ … }}. Expressions read the namespacestrigger,nodes(outputs of upstream nodes),vars,run,error, and in loopsitemandloop. A failing expression fails the node – never a silentfalse. - What you can use – every module's actions (
action: <module>.<noun>.<verb>) with their parameter and answer schemas, the events with their payload schemas, the node kinds with their ports, the namespaces and the functions of the expression language – comes from the catalogueGET /catalog. It lists what the platform offers; whether a flow may use an action is decided by its owner's permissions when you publish.
From draft to live
- Create –
POST /flowswithname,owner(personalortenant) and optionallykeyand a firstyaml, or thetemplatekey of a ready-made flow fromGET /templates(not together withyaml;available: falsemeans a module the template uses is not offered, so its draft would have errors); without either the draft is a skeleton with a manual trigger. A template lists itsparams– recipients, a priority, a time – with type, label and default: send their values asparams(a parameter left out takes its default; a wrong value is400 invalidwith the fieldparams.<key>).POST /templates/{key}/renderreturns the definition a template gives for your values without creating anything. Templates with ascopeare made for a desk space or forge project and need ascopeof that kind; templates withprofile: inlineare immediate automations of their module and are created there, not as flows. The answer is the flow and the validation of its draft. - Save the draft –
PUT /flows/{id}/draftwithyamland the draft'sversionfromGET /flows/{id}/draft(409 version_conflictwhen someone saved in between). Invalid drafts are saved too; the answer lists theirdiagnostics. - Validate –
POST /validatechecks any YAML without storing it. Each diagnostic has aseverity(errors block publishing, warnings never), a stablecode, a dottedpath(nodes.incident.params.title) andline/col.permissionslists the any-of permission groups the flow needs. - Test –
POST /flows/{id}/test-runsruns the current draft without publishing or enabling it (triggerpicks the trigger to act as,inputis itstrigger.data, e.g. a sample webhook body). Like a publish, it needs a valid draft (422 invalid_definition) and the owner's permissions (422 permission_missing). Tests are dry by default: write actions are not sent (their output is a sample of the answer, their input saysdryRun), mail is resolved but not sent and human tasks ask only you; reads and AI nodes run for real. Dry tests are not billed.live: trueacts like a real run and needstenant:flows:admin(403 live_test_forbidden). The answer is202 {runId}; follow it like any run. - Publish –
POST /flows/{id}/publishwith the draftversionyou reviewed and an optionalnote. The draft must be valid (422 invalid_definition,details.diagnostics) and differ from the live version (409 no_changes). HR then checks that the owner holds a permission of every group the flow needs (422 permission_missing,details.groups); for a tenant flow you must hold every permission of its service account (403 forbidden_grant). The confirmed permissions are stored with the version and are exactly what its runs act with. Publishing enables the flow and arms its triggers.
Versions are immutable: GET /flows/{id}/versions, one with its YAML
GET /flows/{id}/versions/{number}, and
POST …/versions/{number}/restore copies one back into the draft.
PATCH /flows/{id} enables or disables a flow (with the flow's version);
DELETE /flows/{id}?version=… archives it. A flow can stop by itself –
pausedReason says why (owner_inactive, permission_lost, tripped); enable it again once the cause is fixed.
Generate a draft from a description
POST /flows/generate with a description in your own words (at most 4000
characters) and an optional name lets the AI write the YAML, using only actions and events you hold a permission
of, and corrects it with the validator (at most three attempts). It creates a new personal flow with that draft –
also when it is still invalid, so check validation – and never publishes it. 6 calls per minute; 503 ai_unavailable / ai_failed when the AI is not available. Service-account keys get 403 person_required.
A mail node sends a message with its own subject (at most 200 characters) and text (at most 4000) through
comms. There are no message templates to reference: the text is part of the flow.
nodes:
info:
kind: mail
to: ["manager:{{ trigger.data.employeeId }}", "group:5b0d6c0e-2f0a-4d0b-9b1c-0e8f6a7d3c21", "channel:9a1f4c2e-6b7d-4e8f-a0b1-c2d3e4f5a6b7"]
subject: "Absence requested: {{ trigger.data.employeeName ?? '' }}"
text: "{{ trigger.data.startDate }} – {{ trigger.data.endDate }}"
Entry in to |
Reaches |
|---|---|
person:<e-mail> or a bare address |
that address |
employee:<id> |
an employee by HR id |
group:<id>, role:<id> |
the members of a group, the holders of a role – as they are when the node runs |
manager:<e-mail or employee id> |
the direct manager of that person |
channel:<id> |
a comms channel (Microsoft Teams or webhook): one message per channel, see Webhooks |
{{ … }} |
whatever the expression yields: one of the above or a list of them |
- Who: groups, roles, employees and managers are resolved in HR for the flow's tenant only; an id that names
nobody (someone who left, an empty group) is listed in the node's output
missing, the others get the mail. In a tenant flow – with or without scope – an address that is no active employee's is mailed anyway and listed inexternal(at most 20 per node). In a personal flow nothing leaves the company: such an address ismissing. - How many: at most 50 entries in
to, as written and after the expressions are rendered (a group or role counts once); the people they resolve to are sent in messages of 50, and more than 500 people fail the node. Errors:too_many_recipients,no_recipient(nobody is left),invalid_recipient(an entry that is no reference). - Output:
recipients(people mailed),to(employees),external,channels,missing. mandatory: true(people cannot switch the message off, digest it or pause it during an absence) andmailChannel: <id>(the comms e-mail channel to send through instead of the tenant's default) are reserved for tenant flows without scope, managed withtenant:flows:admin. A personal or scoped flow that sets one gets the diagnosticmail_option_not_allowedon its draft and cannot be published or test-run (422 invalid_definition). Withoutmandatorythe recipients' personal notification settings apply.- A
human_task'sassignTotakes the same references exceptchannel:; assignees are employees in every flow (an address that is no active employee's ismissing). - In a dry test run mail is resolved but not sent.
Immediate automations in desk and forge
Desk and forge run automations written in the same YAML inside the change that triggers them – the answer of the request already shows the ticket or item as its automations left it. They are stored by the module, not by flows:
| Desk | Forge | |
|---|---|---|
| Routes | /api/desk/v1/automations?scope=… |
/api/forge/v1/projects/{key}/automations |
| Scope | tenant (every space) or space:<space id> |
the project |
| Read | everyone with desk access; a space's: whoever sees the space | tenant:forge:read and a project the caller sees |
| Change | tenant: desk:admin; a space: desk:admin or a maintainer of the space |
tenant:forge:admin, or tenant:forge:write and project role maintainer or admin |
| Triggers | desk's events and manual (the ticket's actions) |
forge's events |
Both modules serve the same set of operations (the links are desk's; forge has the same with Forge in the name):
list (listDeskAutomations, each with its newest execution lastRun), create
(createDeskAutomation: {name} for a skeleton or {yaml, enabled, blocking}), read, change (patchDeskAutomation with version), delete
(?version=), reorderDeskAutomations (ids: the order they run in),
the catalogue of what a definition may use (getDeskAutomationCatalog),
a check without storing (validateDeskAutomation) and the last 50
executions (listDeskAutomationRuns).
- What a definition may use: triggers
event(the module's own events;trigger.datais the event's payload) and, in desk,manual; the nodesif,switch,set,end,mailand the module's actions marked for immediate use in the catalogue – at most 25 nodes. Everything else (wait,human_task, loops,parallel,ai, schedules, webhooks, other modules' actions and events,group:/role:/manager:/employee:recipients,mandatory,mailChannel) is the diagnosticneeds_durable: create it as a flow scoped to the space or project instead (POST /flowswithscope). An automation has no versions and no publish step: what is stored andenabledruns; a definition with errors is stored withvalid: falseand cannot be enabled (422 invalid_definition). - Scope rule: an automation acts only inside its scope – a forge automation on items of its own project, a desk
space's automation on tickets of that space; anything else fails the action with
out_of_scope. Desk'stenantautomations act on every ticket and run before the space's. - Failure: a failing automation is rolled back as a whole and logged (
…/{id}/runs: outcome, failing node, error code); the triggering change is kept. Withblocking: truethe change is refused instead with422 automation_blocked(details.automation,details.reason) – only for requests on the API; changes that arrive by mail, feeds, timers, the customer portal or from GitHub are never refused. - Loops: a trigger ignores changes made by automations (flows included) unless it says
includeAutomated: true; then automations start each other at most 4 levels deep, each once per ticket or item per change, at most 20 per event. - By hand (desk):
listItemActionslists the enabled automations with amanualtrigger that fit a ticket (the trigger'sfilterdecides), andrunItemActionstarts one (422 not_applicable;422 automation_failedwhen it failed – then nothing was changed). Forge starts no automation by hand. - Ready-made automations are flow templates with
profile: inline: render one withPOST /templates/{key}/renderand post the returnedyamlto the module's create route. - Ticket
version: an automation or flow may update a desk ticket or change its status withoutversion(it then acts on the ticket as it is); everyone else must send it – see Idempotency and concurrency.
Desk also evaluates expressions of the same language in two settings: the match of an SLA policy (over the
ticket's event payload) and the condition of a mail source's route (over the mail's from, fromDomain, to,
subject, body, hasAttachments, mailbox); getConditionCatalog lists
the fields. An SLA policy's escalation levels carry no actions: reaching one writes the event desk.sla.escalated,
which automations and flows react to.
Start by hand
A flow with a manual trigger is started with POST /flows/{id}/runs:
curl -X POST 'https://api.mbcom.cloud/api/flows/v1/flows/7d0c…/runs' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 6c1f0a52-0d0e-4a43-9c55-8f6e1f2a0b7d' \
--data '{"input": {"title": "Two monitors", "amount": 640}}'
input becomes trigger.data; trigger picks a manual trigger (default: the first). The answer is 202 {runId, created}. Repeating a start with the same Idempotency-Key answers the run it started first with created: false –
send one on every start you might retry. The flow must be published (422 not_published) and enabled
(409 flow_disabled); a trigger that is not manual answers 422 no_manual_trigger.
Runs
GET /runslists runs newest first (flowId,statusrunning | succeeded | failed | cancelled; keyset paging withlimitandcursor, see Pagination). Test runs carrytestMode(dryorlive).GET /runs/{id}is the run with the YAML of the version it ran and its node history: per node its input, output, port, attempts and error (status skippedwhen no path reached it).POST /runs/{id}/cancelcancels a running run (409 run_finishedwhen it has ended); a node that is calling a module finishes its call, nothing follows it.
A run is pinned to the version it started on; publishing again does not change running runs.
Webhooks
A webhook trigger gives the flow its own address that external systems call without any ConnectCloud token:
triggers:
- { id: alarm, kind: webhook, auth: hmac } # auth: token (default) or hmac
-
Credentials: the publish that arms the trigger answers its
path(/api/flows/v1/hooks/{token}), thetokenand, forauth: hmac, a signingsecretinwebhooks. They are shown only once – store them in your secret store.GET /flows/{id}/triggersnever shows them again. The token is kept across later versions. -
Call:
POST /api/flows/v1/hooks/{token}with a JSON body (Content-Type: application/json, at most 1 MiB); the body becomestrigger.data. The answer is202 {runId, created};runIdisnullwhen the trigger'sfilterwas false. -
Signature (
auth: hmac): sendX-Flows-Signature: sha256=<hex>, the lower-case hex HMAC-SHA256 of the exact raw body, keyed with the secret as you received it (its characters as bytes – do not hex-decode it). A missing or wrong signature answers401 invalid_signature.BODY='{"host":"db-01","status":"down"}' SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$FLOWS_WEBHOOK_SECRET" -hex | sed 's/^.*= //') curl -X POST "https://api.mbcom.cloud/api/flows/v1/hooks/$FLOWS_WEBHOOK_TOKEN" \ -H 'Content-Type: application/json' \ -H "X-Flows-Signature: sha256=$SIG" \ -H 'Idempotency-Key: alert-8812' \ --data "$BODY" -
Retries: with an
Idempotency-Keyheader a repeated call answers the same run (created: false). -
Rotate:
POST /flows/{id}/triggers/{trigger}/rotateissues a new token (and secret); the old ones stop at once. -
Limits: calls are rate-limited per client IP (
429). A flow started more than 60 times in a minute by events or webhooks pauses (409 flow_tripped,pausedReason: tripped) until someone enables it again. An unknown token, or a flow that is archived or not published, answers404; a disabled flow409 flow_disabled.
The token in the path is the credential: treat it like an API key and rotate it when it may have leaked.
Tasks
human_task nodes ask people for an approval or a form and wait. The inbox needs tenant:flows:tasks and a
person: sign-in sessions and personal API keys work, service-account keys get 403 person_required, and a flow
can never answer a task.
GET /tasks(statusopen | done, keyset paging) andGET /tasks/countlist your tasks;GET /tasks/{id}shows one (canAnswerwhen you are an assignee of the open task).POST /tasks/{id}/answer: an approval needsoutcomeapprovedorrejected, a form its requiredvalues(checked against the form,400 invalidwithfieldvalues.<key>);commentis optional. The run continues on the outcome's port. Someone who is no assignee gets404, a task that is answered, timed out or cancelled409 task_closed.