Flow references
Give every process flow a unique reference, generated from a format, typed in at the start, or handed over by another system, and see what happens when the same number is sent again.
A process flow can carry one reference, such as TV-2026-0042 or EL-24-118734. It sits under the flow's name in the title bar, in the first column of the flows list, and at the start of every notification title and email subject the flow sends ([TV-2026-0042] Your permit). The flows list search finds a flow by its reference as well as its name.
A reference is unique within a workspace environment, and each environment counts on its own: development and production may use the same numbers, and production is never influenced by a sandbox.
Setting it up
The reference is set up once for the whole organization, by an organization admin, on the extension's sheet in Platform › Settings › Extensions. The sheet's Setup tab has a Check the reference step, and the Includes tab shows one line per process flow with its reference. Until someone changes it, the setup is what the extension suggests (see Suggesting a reference in your extension).
| Where the reference comes from | What happens |
|---|---|
| Generated | Each flow gets the next number from a format. {YYYY}, {YY} and {MM} are the start date; the zeros in {0000} are the counter, which starts again every year, every month, or never. {WS} is the workspace's code (RB): with it every workspace counts on its own, without it the whole organization counts together. |
| Typed in at the start | The person starting the flow types it in the Start dialog. An example is shown in the empty field. The admin chooses whether a flow may start without one. |
| From another system | The system that starts the flow sends its own number in a start value. The admin picks the systems a workspace may use, with one default: a connection, or a system that is only a name so far. A link with {reference} in it makes the flow's Details link to that system's page. |
| Not needed | Flows are known by their name only. |
The admin also chooses what workspaces may change: for a number from another system, which of the allowed systems it comes from, and whether a number is required. The format and the counter are never a workspace's to change.
Workspace admins see the setup on the Extensions page: the ⋯ menu on a process flow that is turned on says View reference… when nothing may be changed, or Manage reference… when something may. A changed field is marked and can go back to the organization's setting.
Changing a format only affects flows that start afterwards; flows that already have a number keep it.
A generated number is never given out twice, so deleting a flow leaves a gap in the count. The organization's Reference sheet lists each deleted production number under Deleted numbers, with who deleted it, when, and in which workspace. A number typed in at the start or sent by another system is listed too.
Workspace codes
Every shared workspace has a code, which a format with {WS} fills in: 2 to 5 capital letters or digits, unique in the organization. Create workspace always asks for one, filled in from the name, whether or not a format uses {WS} yet; a workspace created without one (through the API, or the workspace a new organization starts with) gets the first free code its name suggests. The organization's Workspaces table always shows each code, with a suggested code to accept for older workspaces. A workspace without a code is never stopped: its flows number with an empty code until one is set. An organization admin accepts or changes a code on the Workspaces table, and an organization admin or the workspace's owner change it on the Settings tab of the workspace's Manage page, which always shows the code. A change there says what it does before you save; once numbers carry a code, the table shows it as locked, and a change keeps those numbers as they are, so only new flows get the new code. Creating a workspace from the workspace menu in the side menu asks for the code the same way.
Suggesting a reference in your extension
An extension suggests a starting point in template.reference. It is optional: an extension without it asks the organization admin to set one up, and every flow still starts.
template: {
// …
reference: { kind: "format", format: "SEC-{WS}-{YYYY}-{0000}", restart: "yearly" },
// or: { kind: "external", startValueKey: "zaaknummer", allowWithout: false }
// or: { kind: "not-needed" }
},kind | Fields |
|---|---|
format | format (needs a counter such as {0000}), restart: never, yearly (default) or monthly |
external | startValueKey, a start value the template declares in attributes; allowWithout (default false) |
not-needed | none |
The suggestion becomes the organization's setup when the extension's process flow is installed. A newer version of the extension updates it until the organization admin saves their own; from then on the admin's choice stays.
Starting a flow
The Start dialog shows a Reference field under Template:
- a generated reference shows the number the flow will most likely get, read-only;
- a typed reference is a text field;
- a number from another system is named after it ("e-loket number"), and its start value is not asked for a second time.
A number another flow in the environment already has is refused, naming that flow. If a generated number cannot be made right now (Scrydon could not read the environment or the workspace code), the flow does not start and the dialog says to try again.
If the connection drops after Create, the dialog sends the start once more. Scrydon recognises it as the same start and answers with the flow the first attempt made: no second flow is started, and a typed reference is not refused as already used by that flow. The same holds if you reload the page and start it again with the same values in the same browser tab. Change anything in the dialog and it is a new start. When the flow was already there from an earlier Create, the dialog says the flow had already been started instead of calling it created; if no answer comes back at all, it asks you to try again, which is safe for the same reason.
A client that starts flows through the API (POST /api/process-flows) gets the same protection by sending an Idempotency-Key header (16 to 128 letters, digits, - or _, such as a random UUID) and resending with the same key. The repeat answers 200 with the flow's id and deduped: true instead of 201. A key belongs to the person who sent it and holds until the flow ends. The same key for another template is refused (409, idempotency_key_template_mismatch), and a malformed key with 400 (invalid_idempotency_key).
A key names exactly one request. Only the template is checked on a repeat, so resending the same key with another name or other inputs answers with the first flow, unchanged, and starts nothing. Make a new key whenever anything in the request changes, and reuse a key only to resend the identical request.
Details
Details, first in the title bar's ⋯ menu, shows the flow's name, reference, template, and who started it and when. Anyone who may edit the flow can rename it there, correct a typed reference, or add a missing one by hand once. A generated number and a number from another system cannot be changed. Every change is written to the flow's Activity.
The same number sent again
When a workflow starts a flow with an outside number that a flow of the same kind already has, no second flow is started:
- The existing flow keeps the new request under How it started, marked Sent again, listing only the start values that changed. The first request stays folded underneath.
- Its start values are never overwritten: steps that already ran keep what they used.
- The flow's case owner is notified (Sent again in their notifications). Until templates name a case owner, that is whoever owns the flow's first owned step.
- A flow that has already ended stays closed. A note above How it started offers Start a new flow from it, which opens the Start dialog with the request's values filled in, for people who may start flows of that kind.