Osy#betaRun it on Osyrin: osyrin.com

Reference / Workflow

partial workflow (a workflow written in several files)

workflow W { … state S; … } · partial workflow W { state S { … } }

A large workflow can keep its state bodies in their own files. The root `workflow W { … }` declares every state in order and writes `state S;` for a state whose body is elsewhere; a `partial workflow W { state S { … } }` in another file gives that body. The compiler puts each body back in the place of its declaration, so the split workflow is the same revision as its one-file form and a running workflow does not notice the move.

preview2 examples compiled by CIworkflowauthoringfiles

Summary#

A workflow can be written in several files. The root holds the whole contract — the header settings, the events, the workflow-level handlers and slots — and lists every state in order. A state written as state Building; has its body in a part: partial workflow SliceFlow { state Building { … } }. The compiled workflow is exactly the one the same text gives in one file.

Signature#

workflow <Name> {                       // the root: one per workflow
  …settings, events, on/subscribe at workflow scope…
  state <S> { … }                       // a body here
  state <T>;                            // its body is in a part
  terminal success <Done>;              // a terminal, likewise
}

partial workflow <Name> {               // a part: state bodies only
  state <T> { … }
  terminal success <Done> { }
}

Description#

The root declares every state#

The root is the ordinary workflow declaration. It lists every state, in the order the states have, and a state whose body is in another file is declared with ; in place of its body. The list is what keeps the split invisible: a state's place in the order is part of the workflow's revision, and a reader of the root still sees every state.

A part holds state bodies only#

A partial workflow repeats the workflow's name and holds state and terminal bodies — nothing else. Each body repeats its declaration's head exactly (terminal success Done { … } for terminal success Done;). Events, header settings, Start, workflow-level on handlers, workflow-scope subscribe slots and workflow-scope Assigned/Finished stay in the root: they are the contract every state reads. A part file may hold several bodies, under any file name. Under the [[project-layout#layout-check|layout check]] a part file holds one state and is named after it: SliceFlow.Building.osy holds partial workflow SliceFlow with only state Building, as in the example below.

What the merge does#

Before anything resolves, each body is put in the place of its declaration, and the parts are removed. A workflow-scope slot reaches a state whose body is in a part exactly as it reaches one written in the root. So the workflow's revision fingerprint, its states' order and its body names are those of the one-file form: moving a body to a part, with no other change, deploys no new revision. An edit inside a part is an edit to the workflow and mints a revision as any edit does. A diagnostic inside a body names the part file and its line.

A body reads names as the file it is written in sees them: a part's using lines reach the bodies in that part, and the root's reach the root's. A part that names a type from another namespace writes its own using for it.

Where parts may be#

Parts merge inside one app, or inside one package. A part has its workflow's namespace. An app cannot continue a package's workflow: a kit's workflow is extended through the slots and events the kit offers.

The refusals#

MistakeWhat the compiler says
a part with no rootpartial workflow SliceFlow`: no `workflow SliceFlow` in this app. A workflow can be continued in another file only inside the app or package that declares it. — and, when a composed package declares it, SliceFlow is declared by package <Package>; extend a kit's workflow through its slots and events.
a body the root does not declarestate `Building` has a body here, but `SliceFlow` (SliceFlow.osy) declares no `state Building;`. Add it to the root's states, in the order the states should have.
a declaration no part gives a bodystate `Building` is declared without a body, and no `partial workflow SliceFlow` gives it one.
two bodies for one statestate `Building` has two bodies: SliceFlow.Building.osy:3 and SliceFlow.osy:9. A state has one body.
a body with another headthe part must repeat the declaration's head: `terminal success Done`, not `terminal cancel Done`.
a part in another namespacethis part is in namespace `Osyrin.Release`, and `SliceFlow` is in `Osyrin.Planning`. A part has its workflow's namespace.
anything but a state in a parta `partial workflow` holds state bodies only: `event Built` belongs in `workflow SliceFlow` (SliceFlow.osy).
two rootsworkflow `SliceFlow` is declared twice: Again.osy:12 and SliceFlow.osy:9. A workflow has one declaration; write more of it in another file as `partial workflow SliceFlow`.

Examples#

using Osysharp.Workflow;

enum SliceStage { Draft, Building, Done, Dropped }

entity Slice {
  [Required, MaxLength(100)] string Title;
  SliceStage Stage = SliceStage.Draft;
  int Builds;
}

workflow SliceFlow {
  Tracks = Slice.Stage;
  Initial = Draft;

  event Built(string head);
  event Approve();
  event Drop();

  subscribe Drop();                 // in every live state, Building included
  on Drop { goto Dropped; }

  state Draft {
    subscribe Built(string head);
    on Built(string head) { goto Building; }
  }
  state Building;                   // the body is in SliceFlow.Building.osy
  terminal success Done { }
  terminal cancel Dropped { }
}
partial workflow SliceFlow {
  state Building {
    subscribe Approve();
    on Approve {
      this.Item.Builds = this.Item.Builds + 1;
      goto Done;
    }
  }
}

Notes#

  • <Wf>.Graph.SourceFile names the root's file: the workflow is declared there.

See also#

Related

Workflows (the run that outlives the request)

A `workflow` is a run that survives the process it started in — it parks, waits days for a person or a timer, and…

Transitions — where this item may go next

One row per move this instance can make right now, with each arm's guard evaluated against it. A board offers only the…

subscribe

Declares that a workflow state waits on an event, and configures the wait — who may hold it, who may hand it on…

Version — which version of a workflow is running, and which file declares it

`<Wf>.Version` is the number of the app version the code runs in — the same number a migration header names (`migration…

Graph — every state and every transition of a workflow

The whole shape of a workflow — every state (with its label, and whether it starts or ends a run) and every transition…

Extension members

A `partial entity X { … }` in a bridge package or in the app adds OPTIONAL members to an entity another package…