URDAD Modeling Tool: User Manual

The tool is designed to be used concurrently by cross-functional teams across the organization, reusing services sourced from within the organization and from external service providers. All changes made to the model are committed and distributed in real-time

include::./requirementsAsServiceContracts

include::./entitiesDeterminedByBusinessProcessRequirements

What the modelling tool offers, grouped by what it is used for. Each entry links to the section that describes it.

Each integration is reached through one contract per responsibility, with the products named here as adapters behind it (Chapter 9):

The same software runs on the organisation’s own infrastructure, hosted for a single tenant, or as a public playground (Section 7.2): two container images, with all state in one data directory (Section 7.3, Section 7.4, Section 7.10). Each evaluator can be given a complete instance of their own (Section 7.9).

What the execution environment offers, grouped by what it is used for. Each entry links to the section that describes it; Known limitations lists what it does not do yet.

An organisation that runs its processes on a BPMN engine instead exports them to Camunda 8 (Section 4.14).

The search field above the tree filters it to the elements that match what is typed, together with the elements containing them, so a result is always shown in its place in the model. The part of a name that matched is highlighted.

The search covers the mounted element libraries as well as the model — they are trees in the same panel, and an element is as worth finding in a library as in the model. A library in which nothing matches keeps its own row, so it is visibly searched rather than absent.

While the filter is in force the tree is not the model, and it says so in two places. A strip under the search field reads Filtered, gives the number of matching elements — a query that matches nothing says so, rather than leaving the model root on its own without explanation — and offers Show all, which restores the whole tree. The end of the filtered tree is closed by a line counting the elements the filter is holding back, so a tree cut short is not mistaken for a model that ends there.

A word matches an element’s name or its type. Two refinements are available:

Matching is case-insensitive. The search is cleared with Show all, with the × button in the field, or by pressing kbd:[Esc] — either while the field has the focus or while the tree itself does, so it is not necessary to return to the field to leave a filter behind.

While a search is active the matching elements are shown expanded so the results are visible without further clicks. Individual elements can still be collapsed; doing so affects that search only, and the tree returns to the shape it had before the search when the search is cleared.

Whenever an element becomes the current element — whether it was selected in the tree, in a diagram, in the Element Details View, from the verification report, or with the back and forward navigation buttons above the tree — the tree reveals it: every containing element is expanded and the element’s row is scrolled into view. Rows that are already visible are not scrolled.

To go the other way — from an element you can see in a diagram to its row here — use Select in model tree on the diagram element’s context menu; see Section 4.1.2.14.

The tree is a single stop in the tab order. Once it has the focus, the current element is moved with the keyboard:

The keys move through the rows the tree is showing, so a collapsed subtree is skipped, and while a search is active only matching results are traversed.

Text in the tree cannot be selected with the pointer — dragging across a row moves the element rather than highlighting its name. To take a name out of the tool, the row’s context menu offers:

Both are available to anyone who can see the element; neither changes the model. The element’s identifier can likewise be copied by clicking the path badge at the top of the Element Details View.

Before renaming, re-typing, moving or deleting an element it is worth knowing what depends on it. Find references, on any row’s context menu, lists every reference to that element, one row per reference, grouped by what the reference means. Each group is headed by the relationship, read from the side of the element asked about, and the number of references in it — for example Is the type of (2) for a data type two fields are typed by, or, for a responsibility domain, May request for the services published to it, Stakeholder of for the contracts it has a say in, and Receives messages sent by for the sends addressed to it. All three of those are held by service contracts or their steps, which is why they are told apart by meaning rather than by the kind of element holding them. A group can be folded away by its heading. A reference of a kind the tool has no wording for is listed under Other references, with the field that holds it.

Selecting a row makes that element the current element, and the tree reveals and selects it. The dialog stays open beside the work and marks the row, so a group can be worked through one row at a time; Close dismisses it.

The search covers this model and every dependency mounted beside it, which is what makes the question answerable for an element that is not the model’s own. Asking what references a primitive type in the standard library lists the fields in this model that are typed by it, and asking it of an element in one library also finds the references another library holds — a finance library’s AccrualPeriod referencing the standard library’s Date. What is searched, and how many dependencies were included, is stated above the list.

What cannot be shown is a reference held by a model that depends on this one. A model holds the revisions it is pinned to and knows nothing of its consumers, so an empty result means "nothing here references it", not "nothing anywhere does". The dialog says as much rather than leaving it to be assumed.

Find references is available on every row, including the rows of a mounted library, and it is available to anyone who can see the row: it reads the model and never changes it. A reference that points at something no longer in the model is a different matter and is reported — and repaired — by model verification instead.

A service contract states which responsibility domains may request it — its Published to list (Section 4.3.1). Published services…, on the context menu of a responsibility domain or of the model root, lists every service contract of that domain and of every domain within it, with whom each is published to:

Above the table is a row of filters: All, one per role the listed services name, and Not published, each with the number of services it selects. Pressing several shows the services matching any of them; All clears them. A role also selects the services published to the domains within it — a service published to Clients › Corporate is one Clients may request — which is how access is granted once the model is deployed: a caller holding a domain reaches what is published to the domains inside it.

On the model root the listing covers the whole model and every dependency mounted beside it, since a library may publish services as well; on a domain, or on a dependency’s own root, it covers that tree alone.

The same listing answers the question from the other side: what may this role request? On a responsibility domain that some service is published to, the context menu also offers Services published to <domain> (n), which opens the listing over the whole model with that role’s filter already pressed. A model therefore does not need a domain that gathers the services offered to a role in one place — each service can sit in the domain that answers for it and still be found by the role it is offered to.

An element is moved by dragging its row onto the element that is to contain it. Only elements that can host the dragged element accept the drop: a valid target is outlined while the pointer is over it, and every other row shows a "no drop" cursor, so an impossible move cannot be attempted. Dropping onto a responsibility domain the user is not authorised to modify is refused with a notification, and the model is left unchanged.

The same move is available as Cut on the source element followed by Paste on the new parent, from the context menu. Paste is offered only where the move would be accepted.

An element is deleted either by pressing kbd:[Delete] (or kbd:[Backspace]) while the tree has the focus, or with Delete on the row’s context menu. Both ask before anything is removed, and both ask the same question: nothing in the tree is deleted without a confirmation.

The confirmation comes in two lengths, according to what the element holds:

In both cases the deletion also removes the references that pointed at what was deleted, which is the same repair model verification performs; and in both cases it can be undone only by reverting to an earlier revision in the change history. There is no undo.

The confirmation is answered from the keyboard as well as with the pointer: it opens with Cancel focused, so kbd:[Enter] and kbd:[Esc] both leave the model alone, and deleting is kbd:[Tab] then kbd:[Enter]. Whichever answer is given, the focus returns to the tree, so the arrow keys continue from where they were. When the deleted element was the current one, the element that contained it takes its place, and navigation carries on from there.

Some rows cannot be deleted, and pressing kbd:[Delete] on one says why rather than doing nothing:

In each of those cases the Delete item is likewise absent from the row’s context menu.

Hover any widget on any diagram and it tells you which model element it stands for: its type, then its full path through the model.

A diagram draws an element’s bare name, which is all that fits and all that needs to be read at a glance. That name is not unique — two responsibility domains may each offer a service called Validate, and a diagram routinely draws elements belonging to domains other than the one you opened it on. The hover text is where you find out which one you are looking at, without leaving the diagram.

The type is named in the interface language, and the path is the same one the element details view and the search lists use: the owning responsibility domains from the top down, separated by colons. The model’s own name is left off, since every element in the diagram shares it. An element that comes from a mounted element library is prefixed with the library’s name and a double colon, so a library’s Shared::Party is never mistaken for your own.

The start and end of a process are the exception: they stand for the process rather than for an element of their own, so they hover as Process start and Process end.

A name longer than a widget carries is shortened in the drawing and ends in …​, so you can see that there is more of it; the widget is drawn to the size of what it shows. Pre- and post-conditions are where this is met most often, since a condition is usually named as a sentence: the pentagon holds the opening of the name and the hover text gives you all of it.

The Data Structure View and the Entity View are the exception, and shorten nothing. A data type’s name and its attributes are what those two views are of, rather than a caption on something drawn for another reason, so the box grows to hold the whole of them however long they run. The same goes for the role name and multiplicity written at the end of a relationship: the space between a structure and the structures it relates to widens to hold the longest of them, so a long role name never runs over the widget it starts from.

Every diagram exports exactly what it draws, so a name shortened on screen is shortened the same way in a published document.

In a project whose processes will run on the execution environment (Section 6.4.1.3), the Process View marks every step that has to be stated formally before the process can run. The mark is a small page with a folded corner:

The steps that carry a mark are those whose execution reads something you write in URDAD-OCL, or an event you configure:

A step that carries no mark needs nothing stated formally, so an absent mark never means a missing one. A Populate response step is the exception worth knowing: it carries no mark because whether the response is fully populated depends on every path through the process, not on any one step. Verification reports it (Section 4.18.44).

The mark answers exactly the question the execution environment asks when it plans a process, so an outlined mark can also mean that the step is formal but uses something the execution environment does not run yet, such as carried variables on a loop. The hover text says which.

The marks appear only in projects that target execution. They are not drawn in other projects, on main, or in documentation the tool generates. An exported diagram includes them, because it exports what is drawn.

A diagram that can be modified carries a column of tools down its left-hand side, grouped and labelled — the element types you may drag onto the diagram, an activities group in the Process View, and the zoom controls at the bottom. Drag a tool onto the diagram to add the element it stands for. Some tools are collections: click one and a small list opens beside the palette, holding the several kinds of that element you can choose between.

Every tool and group heading is named in the interface language, and a tool that creates an element type is named as that type is named in the model tree, so the palette and the tree use one vocabulary. The exception is a tool standing for something that is already in the model — an activity waiting to be placed, or a service a further request may be made of — which carries that element’s own name: a name is model content, and it reads the same whatever language you work in.

Zooming in past the size of the window gives the drawing area a scrollbar, and the palette has one of its own for the same reason. The Process View’s palette is the long one, and on a short window its lower groups — the zoom controls among them — would otherwise sit below the bottom edge with no way to reach them. The two scroll independently: the palette stays in place while you move around the diagram beside it.

If you scroll the palette while a collection is open, the list closes rather than drifting away from the tool it belongs to. Click the tool again to reopen it.

Specialization is recorded on the specialising structure — it names the structure it specialises as its base — so a structure knows what it is built on but not what has been built on it. The Data Structure View shows both ends:

Only the immediate specialisations appear — the level directly below. A subclass is a structure with a view of its own, and drawing its subclasses too would turn a diagram of one structure into a map of the whole hierarchy. The subclasses of a structure the diagram merely reaches — one at the end of a composition, say — are not drawn either, for the same reason.

A subclass box carries no expand handle, because it shows a name and nothing else by design. Click it to open that structure’s own Data Structure View, where its attributes, its relationships and its own specialisations are shown in full.

A contract’s stakeholders — the responsibility domains with an interest in its functional requirements (see Section 4.3.1) — are drawn in the Functional Requirements View’s middle column, each as a stakeholder widget.

Drag a responsibility domain from the model tree, or the Add actor tool, onto the functional requirements panel to add it as a stakeholder. Dropped on open panel space, or on a domain the Add actor tool creates and you then pick from its dialog, the widget draws gray: a provisional stakeholder, one added to the view without yet requiring anything. It stays gray until a functional requirement names it — drag a drag-line from the stakeholder’s widget to the pre- or post-condition it requires, or drop the domain directly onto an existing requirement instead of onto open panel space, and the requirement’s requiredBy list picks it up there and then, without a provisional step. Nothing in the diagram distinguishes how a stakeholder came to require what it does, only whether it currently requires anything.

This is the panel’s own gesture, distinct from a drop in the header row above it — see the next section — which states a different relationship, Published to, on the contract itself rather than on any of its functional requirements.

A contract’s Published to domains — those that may be its clients (see Section 4.3.1) — are drawn in the Functional Requirements View’s header, alongside the contract itself. Each published domain is drawn as a stakeholder widget — the same widget the middle column uses, since being published to a contract and being one of its stakeholders are different questions a domain can answer either way, both ways, or neither (see Section 4.3.1); an association line, solid with an open arrowhead, runs from each one to the service contract.

The header splits into two side-by-side boxes to make room: the published domains, stacked one above the other, at left; the contract — with its base above it, when it specializes one, exactly as before — at right. A contract publishing to nobody draws exactly as it always did, a single box with no change to its position.

A domain that is both a stakeholder and a published client of the same contract is drawn twice — once in the header, once in the middle column — because the two relationships are independent (see Section 4.3.1) and one widget standing for both would silently conflate them. Where each copy is drawn is what tells them apart, not a different colour.

Drag a responsibility domain from the model tree, or the Add actor tool, onto the service contract’s own widget to publish the service to that domain — the same Published to list the element details panel edits (see Section 4.3.1), written from the diagram instead. Dropping either one elsewhere in the header — on an already-published domain, or on the base contract above the service contract when it specializes one — does nothing: only the contract’s own widget is offered for a new Published to entry. Dropped anywhere in the functional requirements panel below the header, both tools keep their ordinary meaning instead — see Section 4.1.2.5.

A service contract may specialize another. The specializing contract then imposes every functional requirement of the contract it specializes, and adds whatever further post-conditions refine it — a PriorityQuote service is a Quote service that also guarantees a priority, and everything a client of Quote may rely on, a client of PriorityQuote may rely on too.

Pre-conditions are the one thing that does not work that way; see Section 4.1.2.7.1 below. A contract’s function declaration travels down the chain too, and in one direction only — see Section 4.1.2.7.2.

As with data structures, the relationship is recorded on the specializing contract — it names the contract it specializes as its base — so a contract knows what it is built on and nothing lists what has been built on it.

The Functional Requirements View of the specializing contract shows the whole of what it requires:

An inherited requirement is drawn here but declared elsewhere, so it cannot be edited or deleted from this view — right-clicking one offers no requirement actions. Select in model tree takes you to it; opening the base contract’s own Functional Requirements View is where it is changed, and a change there is a change for every contract specializing it.

An activity allocated in the Responsibility Allocation View arrives without a name — allocating says what the process must do, and the tool does not guess what the step should be called — so an unnamed box is the ordinary first state of a step, not an oversight.

An activity of the plain kind carrying a formal specification is therefore labelled with that specification for as long as it has no name. A step whose specification says exactly what it does needs no other name to be read, and the alternative is an empty box, which says neither what the step does nor that anything is missing. Give the activity a name and the name is what it reads as from then on: a name you chose is never displaced.

The label is one line. Whatever indentation and line breaks the specification is written with are collapsed to single spaces, and a specification too long for the box is cut with an ellipsis like any other long label — the whole of it is a hover away in the details view.

Only the plain activity does this, because it is the only kind with nothing else to say. A request draws the service it requests, a send and an await the message they carry, and a raise-exception the exception it raises, whether or not anybody has named the step.

A define variable is the one kind whose own content is drawn in preference to a name you gave it: where it has an initialiser its box reads Def: premium = request.sumInsured * rate, because that binding is the whole of what the step does and a name there would only be a label for it. The binding is drawn even where the variable has no name yet — Def: = request.k + 3 — since that is the state the model is in. See Section 4.5.

The Process View and the Responsibility Allocation View show the same label, so a step reads the same in the view that says what the process does as in the view that says when it does it.

An activity that is in the wrong place is moved rather than re-created: press it, drag to the transition it should sit on, and release. A line follows the pointer while you drag, from the activity to wherever it currently is. The activity leaves the position it held and is inserted where the transition points — after the activity the transition leaves, or at the head of the flow when the transition leaves the thing that starts it.

This is one change to the model, not a deletion and an addition. The activity keeps its name, its description, its annotations and everything referring to it, and the change history records it as a single entry.

A whole control-flow construct — a set of alternate flows, a set of concurrent flows, a for-each, a while, a set of event-triggered flows — is dragged the same way, by its diamond, its fork bar or its frame header, and its flows travel with it. The flows themselves do not move: a conditional flow, an exception handler, a message handler and a loop’s body belong to the construct that owns them and have no meaning anywhere else.

A handler’s lane — of either kind — is started by the request-service box rather than by a diamond, so a transition running from that box into a handler puts what you drop on it at the head of the handler. The same holds for the middle lane, the request’s default path. Dropping Raise Exception on an empty handler’s transition is how a handler says it cannot recover: it passes the refusal on as one of this process’s own exceptions — the palette offers exactly those. Throwing on the exception it caught is reported as an error, because the process would then refuse with an exception its own contract never declared (Section 4.18.50). Nothing else in the construct is affected, because the path on which no exception is raised runs to the merge whatever the handlers do.

Dropping an activity anywhere other than on a transition does nothing, and so does dropping it back where it already was. Two drops are refused, and say why:

The same rules govern an activity dragged onto a transition from the model tree, and the tools dragged off the palette.

The Process View’s Activities to place menu holds what this process may put into the flow and has not. It offers two things, and the difference is what dragging one does.

An activity waiting to be placed is one particular step: every activity allocated to a functional requirement in the Responsibility Allocation View, service calls included. Dragging it onto a transition moves it into the flow, and the entry leaves the menu — it is that step and no other, and the model now says where it runs.

A service this process uses is a kind of step. Dragging it adds a further request of that service, and the entry stays in the menu: it is there for as long as the process uses the service, whether that is because a call of it is already in the flow or because the process declares it as a requirement.

A service is requested more than once in the ordinary case. A recursive process calls its own service; two alternate flows may each call the same service, on either side of a decision. The menu used to drop a service the moment the first call of it was placed, so a second call could only be written from the process’s own details form — the one place a modeller laying out a flow is not looking.

Two consequences worth knowing.

While a call of a service is still waiting to be placed, the menu offers that call and not the service. One commitment is never offered twice: the entry you see is the allocated call, so dragging it discharges the commitment rather than adding a second, unallocated one beside it.

A request made from a service entry addresses no functional requirement. The menu knows that the process uses the service, not why this particular call exists. Say so in the Responsibility Allocation View — drag the request onto the requirement, or draw the line from the requirement to it — if that call is what discharges it. A requirement nothing addresses is reported by Verify process specification, so the omission is not silent.

Activities to place offers what the process has already committed to. The rest of the Activities group offers steps nothing allocates, and dragging one of those makes a new step every time.

Raw activity is work this process does itself, specified in place rather than delegated to a service.

Define variable introduces a value the process names for itself — see Section 4.5. It discharges no functional requirement, so nothing ever puts one in Activities to place; you add it where the value becomes available, and then give it its name, its data type, its multiplicity and its initialiser in the element details view. Naming the step names the variable — the two are one thing — until you type a different name into the variable itself.

It is drawn in the shape of an ordinary step and in the plum a raw activity also takes: those two are the things in a flow that do no work, and reading a process means being able to skip over them to find the steps that do something. What tells the two apart is the caption — a define variable’s is prefixed Def:, where a raw activity’s is not.

Populate response states part of what this process answers with, from whatever is in scope where you drop it — see Section 4.5.5. It is the third step drawn in plum, since it binds rather than performs. Its caption is prefixed Resp:, followed by its name or, while it has none, its first constraint. One minted here addresses nothing. When the step is how a post-condition about the response is met, create it in the Responsibility Allocation View instead, by dropping its tool on that post-condition: it is then allocated, and its first constraint is a copy of the post-condition’s body — a draft to rewrite in terms of the data the process holds where you place the step. The copy is made once; later edits to either do not reach the other, because the two are written over different data. A post-condition the contract meets by itself needs no such step, and the tool declines it.

Raise exception answers a different question again — what this process may do when a pre-condition of the service it realizes is not met. It offers one entry per pre-condition of that contract, and adds a step each time.

Check pre-condition is the usual way to say where a pre-condition is enforced. It is created in the Responsibility Allocation View by dropping its tool on a pre-condition, and arrives under Activities to place. Placed in the flow, it evaluates that pre-condition exactly as the contract states it and, if it does not hold, raises the pre-condition’s own exception; otherwise the process carries on. Nothing is copied: editing the pre-condition changes what is checked, and its form shows the condition and the exception read-only. The step is named after the pre-condition and drawn in the pre-condition’s red, captioned Check:, with a small open arrow pointing up and to the right in its top-right corner — in the same red, and in both views that draw the step, so a check reads as one at a glance even before its caption does — and it is itself what addresses the pre-condition, so it needs no separate allocation. It counts as raising the exception, so the pre-condition is not reported as one whose exception nothing raises.

It checks the pre-condition against the request and the state of the world at that point, never against a value the process computed. Where the check reads entity state that a later step changes, prefer requesting the entity’s own service and handling its exception: the service’s pre-condition is the authoritative check, made at the moment of change.

A pre-condition can instead be discharged by asking a lower-level service. In the Responsibility Allocation View, drop a service contract on the pre-condition, or right-click the pre-condition and choose Assign service. When that service can itself refuse — it has pre-conditions of its own — you are asked one more thing: whether your pre-condition holds when the service is provided or when it refuses.

Either way the process continues after the request, and the request counts as raising your pre-condition’s exception. A service that cannot refuse is simply requested. Where the service is a query, a check pre-condition step whose pre-condition applies the service as a function is usually the clearer statement of "must not be provided".

Right-click an activity and choose Remove to take it out of the process. What happens next depends on whether anything still needs it.

An activity that addresses a functional requirement is not deleted. The allocation is a commitment the process made in the Responsibility Allocation View — this step discharges that requirement — and where the step sits in the flow is a separate decision. So the activity goes back to Activities to place on the toolbar, keeping its name, its description, its annotations, its body if it is a control-flow construct, and the arrow drawn to it in the Responsibility Allocation View. The tool says so when it happens, since an activity that leaves the drawing but stays in the model is not something the drawing can show. Drop it on a transition again to put it back into the flow.

An activity nothing has allocated is deleted, as it always was. Nothing else refers to it, and an activity waiting in Activities to place means "allocated, not yet placed" — an unallocated activity parked there would make that half of the menu say something it does not. A request you made from a service entry and never allocated is therefore deleted when you remove it; the service itself stays in the menu, since the process still uses it.

Removing a control-flow construct removes the construct and its flows. Any activity inside it that addresses a requirement is kept, and moves to Activities to place on its own, for the same reason as above: losing it would quietly leave the requirement addressed by nothing, with no arrow left to notice.

To delete an allocated activity outright, remove its allocation first — from Addresses in its details form, or by right-clicking its arrow in the Responsibility Allocation View and choosing Delete allocation. An unplaced activity is removed along with the last allocation naming it.

Right-clicking anything in a diagram opens a menu of what can be done to it. Three conventions hold across all of them.

The first line names what you clicked — the element’s type and its name, or, on an edge, what the edge says. Diagram widgets sit inside one another: an attribute inside a data structure, a lane inside a request inside a sequence. The menu that opens belongs to the innermost thing under the pointer, which is not always the thing you meant, and most of the items name only a kind of act (Add attribute) rather than their subject. The line at the top is how you check before acting: if it does not name what you meant, dismiss the menu with Esc and click again, a little further out.

Items that delete are set apart and coloured. They sit below a rule, after the items that add or open, and they are the only ones drawn in the warning colour. There is no undo: what recovers a deleted element is the model’s revision history — see the change history and tags in the left-hand panel — so the menu marks the difference rather than asking you to confirm each time. Two of them do ask: deleting a responsibility domain or a service contract that still holds anything opens a dialog naming what would go with it.

A menu with nothing to offer says so, with a greyed No actions for this element. That happens on parts of a diagram the view has no acts for, such as an edge that only records what the model already states elsewhere.

Right-clicking the background of a diagram is not nothing: it offers the acts of the element the view is drawn of. Background in the Scope View adds a responsibility domain or a service contract, in the Data Structure View adds an attribute or a relationship to the structure on show, in the Process View verifies the process specification, and in the Responsibility Allocation View opens the process specification.

Every element drawn in a diagram stands for an element of the model, and its context menu ends with Select in model tree. Choosing it makes that element the current element and shows it in the tree: the model tree tab is brought to the front if another tab was showing, the containing elements are expanded and the element’s row is scrolled into view.

This is offered on every element of every diagram, including those whose context menu has nothing else to offer, and it changes nothing in the model. It is the way across from a diagram — where an element is easy to recognise but hard to locate — to the tree, where it can be renamed, moved, described or deleted.

If a search filter is in force and it is withholding the element’s row, the filter is cleared, since the row could not otherwise be shown. A filter that already shows the row is left alone.

The menu item appears for the elements of a diagram, not for the links between them and not for the diagram’s empty background: a link stands for a relationship rather than for a row in the tree.

Selecting the model itself in the model tree opens a Scope View of the model — the same view a responsibility domain gets, because a model decomposes into top-level responsibility domains in exactly the way a domain decomposes into sub-domains. This is where that first decomposition is made.

The model is drawn on the left in a colour of its own, so it is not mistaken for a domain, with its top-level responsibility domains stacked on the right and a containment link to each. Drag the ResponsibilityDomain tool onto the diagram — or right-click the model and choose Add responsibility domain — to add one.

A model provides no services of its own; it is the domains within it that do. So the model’s Scope View offers no service tool and shows no services, and it is the only view the model root has.

A for-each is drawn as a framed band around its body, with a header that states in one line what the loop does. The header reads as set-builder notation rather than as a sentence, so that it stays one line as the parameters accumulate:

To the left of the caption is a multi-instance marker, the same one BPMN uses: three horizontal bars when the elements are worked through in order, and three vertical bars when they may be processed concurrently. A for-each always has a processing mode, so the marker is always drawn — there is no state in which the diagram is silent about it.

A for-each that declares nothing but its body therefore reads ∀ element with the sequential marker beside it, and everything else appears only as the model comes to say it. See Section 4.1.3.6 for what each parameter means and how it is edited.

A continuation condition is not part of the caption. When one is declared, the for-each gains a compartment along the bottom of its frame reading while and then the condition — a constraint on the loop, set apart from the statement of what the loop ranges over. A for-each with no condition has no compartment at all, so the band’s presence is itself the statement that the loop can stop early.

The condition is drawn in continuation polarity, which is why the word is while rather than until: the loop runs while what follows holds.

The word while follows the interface language, so the compartment reads solange, solank or så længe for a colleague working in German, Afrikaans or Danish. A condition too long for its compartment is cut with an ellipsis rather than being allowed to stretch the whole process diagram; hover the frame to read it in full, or open the for-each in the Element Details View.

A Process View shows one level of granularity: each service request is a box naming the service the process asks for, and how that service is provided is the business of another process. That is what keeps each process small, and what lets it be read, verified and changed on its own. When a reader wants to follow a journey end to end instead, any request whose service a process in the model realizes can be drawn as that process, in place — an expanded service request.

If an expanded process stops realizing the requested service — the model is changed so that it realizes another, or it is deleted — the request is simply drawn collapsed again.

Drop the Concurrent Flows tool onto a transition and the Process View draws a fork bar, a lane below it and a join bar: the process splits at the fork, the lanes run at the same time, and the join waits for them before the process goes on. Right-clicking the element offers three kinds of lane to add.

Add concurrent flow adds an unconditional lane. It always runs, and it always arrives at the join. This is the plain case: two things that must both be done before the process continues.

Add background flow adds a lane that starts at the fork and then goes its own way. It ends in a flow end rather than at the join, so the process does not wait for it, and it may outlive the process that started it — a notification to send, a file to archive.

Add conditional flow adds a lane governed by a condition, the same ConditionalFlow an alternate-flows element uses. It runs only when its condition holds, and when it runs it arrives at the join like any other concurrent lane. Its condition is drawn beside the lane where it leaves the fork. Give the flow the condition as its name, and state it formally in the flow’s Formal specification in the Element Details View.

Conditional lanes are what make this more than a plain fork. Where an alternate-flows element takes exactly one of its flows, a set of concurrent flows takes every lane whose condition holds — none of them, some of them or all of them — and joins whichever ran.

A service refuses when one of its pre-conditions is not met, and it refuses by raising the exception that pre-condition names. It may also send a message while meeting a post-condition, which one of that post-condition’s messages sent declares. A step that requests such a service therefore has more than one way out, and the Process View draws each of them as an arm leaving the request-service box:

A lane’s kind therefore decides its side, and the two kinds never share one. That is what keeps an arm on its way back to the merge from crossing a lane that runs past it, and it leaves the success path in the middle of the construct whatever mix of handlers the step carries — the box, the success path and the merge stand in one column, and the arms fan off it in the direction that says what they are.

The last of those is the one that behaves differently, and the drawing is what says so. An exception arm comes back: whatever went wrong, the process carries on from the merge. A message lane does not — it runs down its own column and ends in a flow end level with the merge, because the request carried on the moment the service answered and nothing after it waits for the message to be processed. That is why a message handler is a background flow rather than a second kind of arm.

The arms are otherwise identical, so each one carries a marker saying what it is, where it leaves the box:

Without these, an arm could only be read by following it — and an exception you have added a handler for but not yet filled in leads to an empty lane, so following it told you nothing at all.

A request arrives with an arm for every exception its service can raise: dropping it onto a transition gives it an empty handler for each one it does not yet handle, because every exception must be handled (Section 4.18.49). An empty arm is drawn as the bare loop back to the merge — a decision still to take, which is why it is drawn. Fill it with what happens — recovery steps, or a Raise exception step passing the refusal on as one of this process’s own exceptions, after which the arm ends there and never reaches the merge — or open the handler and mark it as ignoring the exception.

An arm marked as ignoring its exception has nothing to draw, so it is not drawn: the request’s box names it instead, in a row reading (ignores: …) below the domain, the exceptions listed in the order the handlers are named and cut short when the row grows long — the request’s form lists them all. A request whose every arm is ignored is drawn as a plain box. The handler is still in the model; select it from the request’s form or the model tree.

Message arms are added by hand: open the request service in the Element Details View and use the add buttons beside Message handlers, which offer the messages its post-conditions declare it may send. The same buttons beside Exception handlers offer any exception still without a handler — after the request was re-pointed, say. Both offers also appear on the request’s context menu in this view. The lanes are drawn in the order the handlers are named, so the diagram does not rearrange itself as handlers are added.

Monitored activities (monitored activities) are drawn as a request that may refuse or send is, with a frame in place of the request’s box. The frame is a loop’s — same shape, same colours — around the activities it monitors, and its header names the block beside a double ring, BPMN's sign of an event being watched for. Below it is a row of lanes:

The solid and dashed rings are BPMN’s for an interrupting and a non-interrupting boundary event, so a reader who knows BPMN reads them without a key.

Monitored activities are on the toolbar’s controls group, beside the event-triggered flows. A new block has no monitor; right-click it and choose Add interrupting monitor or Add non-interrupting monitor, then give the monitor its trigger and its activities in the Element Details View. Activities are dropped into the frame, or on a monitor’s lane, as into any other sequence.

A branch fans its lanes out to either side of a central one, and every lane on a side leaves from the same point — the left or right corner of the decision diamond, the left or right face of the request-service box. Two lanes to a side and their captions would be written at the same place.

They are therefore stepped, outwards and upwards together:

So the captions climb away from the branch in the order the lanes do, and each sits over the stretch of arm that is its own. This applies to the conditions on an alternate-flows branch, to the events on an event-triggered branch, and to the exception arms of a request service alike.

The central lane — the default flow, or the success path out of a request service — is never stepped: it leaves downwards on its own and shares its departure point with nothing.

Text fields commit their value when the field loses focus (or when you press Enter in a single-line field) — never on every keystroke. This holds for every field in the view, including a data field’s multiplicity, where the intermediate text you type on the way to 0..* is not a value the model is asked to hold. Long-text fields such as annotation bodies, formal specifications and an exception’s message mark unsaved edits with a coloured left border until they are committed; pressing Enter in these fields inserts a newline. Because every committed change is pushed and committed to the model’s change history automatically, there is no separate save step.

Container elements list their structured children — sub-domains, service contracts, processes, decisions, exceptions, data types — as expandable items. Expanding one shows that child’s own form, so a whole domain can be worked through from where you are, and a child that contains further children expands the same way, down as far as the model goes. The arrow beside an item opens that child as the current element instead, for when you want the diagrams and the action bar to follow; the remove button beside it deletes it. A collapsed item is not rendered at all, so a large model costs only what you have open.

Expanding a child shows the properties that belong to its type. Its annotations and formalization references are not repeated there — those are shown for the element you have open, so open the child itself to reach them.

A newly added element is opened where you added it, and is unnamed: the tool names nothing for you. Type the name into the field waiting at the top of the item you have just been given.

That is deliberate. A name is model content — it is committed to the repository, read by everyone on the branch, and carried into every generated artifact — so a name nobody chose is a statement nobody made. It also could not be neutral: a placeholder would be written in whichever language the person who created the element happened to be working in, so the same model would name its elements two ways depending on who added what.

A handful of elements are the exception, and they are not really named by the tool either: they are named after something in the model. A send, an await and a declared message take the name of the data structure they carry; a request service takes the name of the contract it requests. Each shows a provisional form — Send message, Request service — until you point it at something, and then renames itself to match. The moment you type a name of your own, that tracking stops for good.

A service contract's Request and response section holds the two data structures the contract exists to describe — what the service is given and what it returns. Both expand into a full data-structure form, so their fields, base type and invariance constraints are edited here rather than by locating them in the model tree. Neither can be removed: the contract creates them with itself, and there is no way to put one back.

A process’s Services used section lists the service contracts the process requests, whether the request is already in the flow or still waiting under Activities to place. It is read off the requests rather than edited: a service is used by requesting it, in the Responsibility Allocation View or the Process View, and each entry leads to its contract. Which pre- or post-condition a request discharges is recorded on the request itself, under Addresses. Its Activity sequence holds the activities themselves, and the add buttons in the section heading create one of each kind — request service, raw activity, send message, await message, raise exception, conditional flow, for-each, while. An exception handler, a message handler, a request service’s default path and the body of either loop carry the same section and the same buttons, so a sequence can be built to any depth from the form alone.

Building a process from the form and building it by dragging tools onto a process diagram reach the same model; use whichever suits the step you are on.

A request service names the Service contract it requests, and beneath it three sections: the Default path, which is what the process does when the service answered without raising; the Exception handlers that catch what that service can raise; and the Message handlers that process what it declares it may send.

Steps on the default path are not the same as steps placed after the request. An exception arm that recovers rejoins the flow when its handler is done, so anything after the request runs whether or not an exception was raised and handled; the default path runs only where none was. That is also why the request’s answer can be read only on its default path once it has exception handlers — which, since every exception must be handled, is whenever the contract has a pre-condition. It is usually left empty, which is what an ordinary request means — the service answered and the process carries on. The process diagram draws it as the middle lane of the construct, and a step can be dropped onto its transition there instead.

Provider selector says where the party asked is read from, as a path over the data this step can reach — request.preferredUnderwriter, Quote.nextReinsurer. It is typed rather than picked, and deliberately so: a provider you already know when you are writing the model is the contract the request names, drawn in the Responsibility Allocation View, because you require a contract and never a party. What only the running process knows is which service reference to ask for, and that is a value in the data.

Left empty the field is still saying something: the service is requested of whoever provides that contract. Since a contract may be realized more than once, that is an ordinary thing to mean, and a note under the field says it while the field is empty. State a path and the request becomes directed — which is what you want when a provider that cannot serve a request itself passes the same request on to the next one, since that is otherwise indistinguishable from the process calling itself. The path also says where that next provider came from, which naming a party could not.

The tool follows the path and reports what it finds: a route it cannot follow as a warning (Section 4.18.24), and one arriving at a value that is not a service reference for the contract requested as an error.

The selector is not the domain shown in brackets under the request’s name on the process diagram: that one owns the contract. State a path and the diagram draws it as a further row, → <the path>; leave it empty and no row appears, because "whoever provides the contract" names nobody to draw.

A new request is called Request service, and naming the contract renames the step after it — pick Rate the risk and the step becomes "Rate the risk". The name keeps following the contract you choose until you type one of your own in the Name field, at which point it stops for good and nothing the tool does will overwrite it.

Each section’s heading carries one add button per unhandled item, named after the exception or the message it would handle — the requested contract’s pre-conditions say what can be raised, and its post-conditions' messages sent say what can be sent, so the form offers exactly what that contract states and nothing else. Adding a handler creates the corresponding lane on the process diagram. The difference between the two shows there rather than here: an exception arm rejoins the flow at the merge unless it raises, and a message lane runs on to its own end. See Section 4.1.2.19.

Choosing the Service contract — the first time, or re-pointing the request — also gives the request an empty exception handler for every exception that contract may raise and the request does not yet handle, so the add buttons for exceptions are usually already spent. Re-pointing keeps the handlers the previous contract needed, because one with steps holds recovery work; verification reports them until they are removed (Section 4.18.49).

A request to a service that is not a function also has a Compensation section, saying how the request’s change is undone should the process later raise one of its own pre-condition exceptions (compensations). When the requested contract — or a contract it specializes — has an Undone by, the section names it and offers Override for this step; otherwise it says that nothing does, and offers Add compensation. Either way it offers Needs no compensation, which asks why. A compensation’s form names the Undoing contract and lists the request constraints that build its request. A send message carries the same section, without the inherited case. A service contract that is not a function carries the contract-level counterpart, Undone by. A service contract also says whether Its requesters may cancel it (cancellable); a specialization of a cancellable contract is cancellable too, and the form says which base made it so.

An exception handler’s own form names the exception it Handles and lists its steps. While it has none it also offers Ignore this exception and continue after the request: tick it when carrying on really is what should happen, and the empty handler becomes a decision rather than an omission — the process diagram then names it on the request’s box rather than drawing an empty arm. Unticked and empty, the form says that nothing is decided yet, and verification warns of it. Once the handler has steps the box is gone — the steps are the decision.

Instances says whether the service is requested of one provider or of several. Left on Single instance — the default, and what every request written before this setting existed means — nothing further is asked. Choose Multi-instance and two more fields appear.

Reach for multi-instance when one and the same service is requested of a set of providers: three insurers quoting on a risk, every reinsurer on a panel, each of a set of assessors. This is not the same statement as a for-each around a single request, and the two are not interchangeable — a for-each walks a collection in the process’s own data and binds each element to a variable its body reads, whereas a multi-instance request asks one question of several parties and varies only who answers. See Section 4.1.3.6 for the loop, and the primary model elements chapter for why keeping them apart matters.

Processing mode is either parallel or sequential, and starts parallel. Parallel says the instances are independent of one another and may run concurrently; sequential says they must be worked through one at a time, which is what to choose when a later request depends on what an earlier one returned, or when the providers must be approached in a stated order. The default is the opposite of a for-each’s, and deliberately: a loop body routinely carries state from one iteration to the next, whereas separate providers answering one question do not.

Number of providers says how many are addressed, in the same form a data field’s multiplicity takes — 3, 1.., 2..5. Choosing multi-instance seeds it with 1.., which you can narrow. It may be left empty, and an empty one is a statement rather than an oversight: a modeller who has established that a request goes to several providers but not yet how many should be able to say exactly that. Verification then reports it as a warning — see Section 4.18.23.

Continue while is where you say when the request goes on to the next provider. Add a continuation condition here and the request reads ask each in turn while this holds — which is how a chain of providers is modelled as one request rather than as a loop around one. The condition is stated in continuation polarity, exactly as a for-each’s and a while’s are: it says when the request carries on, never when it stops, so the same wording means the same thing wherever you meet it.

On a sequential request it decides whether the next provider is approached at all; on a parallel one every provider has already been asked, so it says that the outstanding answers are no longer wanted. It is an early exit rather than a bound — Number of providers is the bound — so leaving it empty is a complete statement, meaning every provider is asked, and verification never asks about it.

Name the response binds what the service answered to a name of your own, for the rest of the sequence. You supply the name and nothing else: the panel states beneath the field what the name is bound to — the requested contract’s response structure, at this request’s own multiplicity — because the contract has already said what it answers with. Repoint the request, or make it multi-instance, and that binding follows; a multi-instance request binds a collection of answers.

Most requests need none, which is why the button is an offer rather than a field. A request is named after the contract it asks for, and that name already reaches the answer — Rate the risk.premium. The note beside the button says so. Name the response where that reading is ambiguous, most often when one sequence requests the same service twice. See Section 4.5.

All three fields disappear again if you switch back to single instance, and what you typed is kept, so changing your mind and changing it back loses nothing.

On the process diagram a multi-instance request carries three bars in a strip along the bottom of its box — vertical for parallel, horizontal for sequential — and a stated continuation condition adds a row reading (while …) beneath the providing domain.

A for-each runs its body once per element of a collection. Five things describe it, and only the body is mandatory.

Source collection is the collection worked through, written as an expression such as request.items — a formal specification like any other, added and removed the same way, so what it says can be read rather than only displayed. Element variable names each element while the body runs, such as item, and is a process variable with a type of its own rather than a bare name (see Section 4.5), so the body’s activities have something to refer to and a reader can see what kind of thing it is. Its Name, data type and multiplicity are all edited in the for-each’s own form — the name field at the top of the pane is the loop’s. Leave both empty and the for-each is a plain loop with no declared driver — legitimate early in an analysis, but a reader cannot then tell what it repeats over.

What the loop accumulates is stated as a carried variable — see Section 4.5. It says where the value starts and what each iteration makes of it, so a reader sees not only where the results end up but how they get there, and it keeps its last value after the loop, so a step after the loop can read the result. There is no separate result collection field: naming a destination said less, and said it in a form a While could not use.

Carried variables are listed in the Carried variables section of the loop’s form. Its add button creates one; each then has a Name, a data type and multiplicity, a Starts as expression and a Becomes expression, each added and removed like any other formal specification. A carried variable missing either expression is reported as a warning (Section 4.18.21). Selecting the variable in the model tree shows the same fields.

Processing mode is either sequential or parallel, and starts sequential. This is a statement about the model, not a hint to an implementer: sequential says the elements must be worked through in order, which is what a body carrying state from one element to the next requires; parallel says each element is independent of the others and they may be processed concurrently. Sequential is the default because it is the weaker claim — a modeller who has not considered the question has not established that concurrency is safe.

Continue while is an optional formal specification of an early exit, stated as the condition under which the for-each carries on: it proceeds while the condition holds and stops before every element has been processed once it does not — "while fewer than ten results have been collected", for instance. Without one, the for-each runs to the end of the source collection. It is added and removed like any other formal specification, and it is not the same slot as a formal specification the activity may otherwise carry.

It is read after each iteration, once the carried variables have taken their new values, with the element just processed still in scope; names the body itself bound are not, so anything the condition needs from the body has to reach it through a carried variable. When it does not hold, no further element is taken.

A parallel for-each can neither carry variables nor stop early: its lanes run at the same time, so there is no order to fold over and, once all have started, nothing left to stop. Verification reports either as an error (Section 4.18.22). The fields stay in the form when you switch the mode, so nothing you wrote is discarded — the report tells you what to remove or to switch back.

The polarity is worth reading carefully: the condition says when the loop continues, not when it stops. It is stated that way round so that this field and the guard of a while-loop mean the same thing — two loop constructs in one language whose conditions read in opposite senses is a reliable source of mistakes.

A while repeats its body for as long as a guard holds. It is the other loop, and choosing between the two is a statement about why the repetition ends.

Reach for a for-each when the repetition is driven by a collection: there are twelve claim items, so the body runs twelve times, and the loop ends because the collection ran out. Reach for a while when it is driven by a condition: chase the outstanding documents for as long as any are outstanding, and nobody can say in advance how many times that is. The distinction is worth keeping because a for-each terminates by construction and a while does not — a reader, a verification engine and a phase gate can all tell the two apart from the element alone, without inspecting its fields.

A while is created the same two ways a for-each is: with the While tool in the Process View’s Control Flow group, dragged onto the diagram, or with the Add while button on the activity list of whatever sequence is to hold it. Three fields describe it, and only the body is structurally required.

Continue while is the guard, and it is what bounds the loop. It carries the same meaning and the same polarity as a for-each’s: the loop proceeds while it holds. A while with no guard stated is a loop with nothing to end it, which the model can express but a reader should treat as unfinished.

Test before iterating decides where the guard is evaluated. Left on — the default — the guard is checked before the first iteration, and a body whose guard is already false never runs at all. Turned off, the body runs once and the guard is checked afterwards: a do-until. The setting exists so that a modeller wanting the second shape does not have to place a copy of the body ahead of the loop and then keep two copies in step.

Carried variables are what the loop changes from one iteration to the next, edited exactly as a for-each’s are (see Section 4.1.3.6). They are the only thing a guard can read that is able to change, so a guard that names none of them cannot finish (Section 4.18.20).

Maximum iterations is an optional whole number bounding the loop. It is the one thing that lets anything downstream say something about termination, which is why it is a number rather than an expression: a bound that has to be evaluated cannot be reasoned about. Leave it empty when the loop genuinely cannot be bounded — an omission is an honest statement, an invented number is not.

A while has no processing mode. Each iteration depends on the state the previous one left, so there is nothing for a parallel setting to mean.

If the branch you have checked out does not accept writes — it belongs to a project in a phase that is locked, or you are not a member of that project — the whole form is read-only and says so in a note at the top. Fields cannot be typed into, drop-downs cannot be changed, and no add or remove button is offered. Nothing is hidden: everything the model holds is still there to read, and navigation still works. See Section 6.2.2 for which phases accept changes.

An entity’s form is read-only for a different reason, and says so too: everything it shows is derived from the data structures that feed it, so it is changed by editing those.

Properties with a fixed set of values — an annotation's purpose, language and markup type, a data field’s relationship, a primitive type’s basic type, a formal specification's language — are edited through drop-downs. The options read as ordinary words in the interface language: Informal requirement, Plain text, Date and time, English. The model stores its own identifiers underneath, so the same annotation reads as Kurzbeschreibung to a colleague working in German.

Relationships to other model elements are edited through reference fields. A reference can be set in two ways:

The search list can be used from the keyboard without leaving the field: arrow down and arrow up move a highlight through the matches, wrapping at either end, and Enter picks the highlighted one. Nothing is highlighted until you press an arrow, so Enter on its own never picks a match you did not choose, and typing more clears the highlight because the list has changed. The same keys work in every search list on a diagram’s dialogs: the type in Add attribute, Add composition, Add association, Add aggregation and Add specialization, the entity a structure is fed by, the contract a responsibility allocation assigns, a service contract's base contract, and the entity a post-condition's entity service is created for.

Hovering the field lists the element types it accepts, named as they are in the interface language.

Single-reference fields show an arrow button when a reference is set; clicking it (or clicking a reference row in a multi-reference field) navigates to the referenced element. The remove button next to a reference clears it without affecting the referenced element itself.

Formalized from records which informal requirements an element was written to satisfy. Adding a reference opens a search over every informal-requirement annotation in the model; picking one shows its full text and offers to cite a passage within it — select the passage in the body, and the field below it fills with what you selected. That field cannot be typed into: a citation has to be a passage the requirement actually contains, and selecting it is what makes that so. Selecting again replaces it; the x beside the field removes it, and is shown only while there is a citation to remove. The citation is optional, and leaving it empty says the element formalizes the requirement as a whole.

The dialog can be given the window. Both of the things it asks you to read are somebody else’s prose — the list of every informal requirement in the model, and then the whole of the one you are citing, out of which a passage has to be found and selected — and neither is comfortable in a box sized for a form. The button beside the dialog’s heading maximises it, and the same button restores it. The passage you have selected stays as it is across both, and the dialog opens the way you last left it, so working through several long requirements does not mean maximising once for each.

Each reference then states in the row itself what it cites, so a link can be read without opening anything:

Two warnings can appear beneath a reference, and they say different things.

The informal requirement has changed since formalization means the requirement was edited after this element was written, so what the element formalizes may no longer be what the requirement says. It is a prompt to re-read, not a defect: the edit may have been a corrected typo three paragraphs away.

The cited passage is no longer present in this requirement is the stronger one, and it replaces the first rather than joining it: the exact sentence this element was formalized from has been changed or deleted. The passage is repeated in the warning so you can see which one went.

Clicking a reference navigates to the element that holds the requirement. Removing a reference removes only the link — the requirement itself, and everything else pointing at it, is untouched.

A requirement, a raw activity and a conditional flow may each carry a formal specification, shown and edited in the notation you choose under Settings (Section 4.7). Where there is none, the form offers to add one; where there is, the section can be removed again, which asks first because the body goes with it. An activity’s specification is also what its box is labelled with while the activity has no name.

An element may carry more than one, and they are separate sections with separate names because they are separate claims. A for-each and a while each carry a Continuation condition beside their own specification; a post-condition carries a Condition — see below.

A post-condition says what must hold once the service has been provided, and its form adds two things to an ordinary requirement’s.

Condition says when the post-condition applies — "if the claim is approved, the claimant has been paid". It is a formal specification like any other and is offered, added and removed the same way. It is deliberately not the post-condition’s own Formal specification: that says what must hold, this says when it must, and written as one they cannot be read apart. Leave it empty and the post-condition applies unconditionally.

Messages sent declares the messages the service may dispatch while meeting the post-condition — a payment advice to the claimant, a work item to an assessor. Each names the data structure that is the message, says whether it is a work item or a notification, and may name the party addressed, in the same vocabulary a send message uses. There is no recipient selector here: a path picking one particular instance of a party belongs to a particular send in a particular flow, not to the contract that permits it. Leaving the party unnamed says the message goes to the requester of the service, as it does on a send.

A declaration names itself after its message. A new one is called message sent, and choosing the data structure renames it to <that structure> sent — "Payment advice sent". Change the message and the name follows. Type a name of your own and it stops following, permanently: the tool never overwrites a name you chose, and there is nothing to undo if you change the message afterwards. This is the rule a pre-condition's raised exception already follows, read the other way round.

The name is not translated, deliberately. It is part of the model, committed to git and read by everyone on the branch, so deriving it in the language of whoever happened to create the element would name one thing two ways.

These are not implementation detail put in the contract. A client reads them: a request service offers one message handler per declaration listed here, which is what lets a process say what it does when the message arrives without anyone opening the provider’s process to find out what it sends. See Section 4.1.3.5.

An enumeration’s Options list is edited in place: type a value into the field below it and add it. Removing an option asks for confirmation.

Nothing in this view is deleted without being asked about first. Removing a structural element (a service contract, process, data type, field, condition, activity, and so on) reports how many references elsewhere in the model point at the element, so the blast radius of the deletion is visible before it happens; removing something that is not a model element in its own right — an annotation, an enumeration option, a formal specification — names what will go. References held by deleted content are cleared along with it; remaining incoming references are cleared where the model supports cascading deletion, and any that do dangle are flagged by model verification (see Section 4.18).

An action bar under the header carries the actions that apply to the element as a whole. There are two controls.

AI opens a menu of three:

The first two read the element’s informal-requirement annotations, so on an element that has none they are listed but disabled, saying what to add first. All three need an LLM provider, which an administrator configures for the whole instance — see Section 7.6. You choose which of the configured providers and models to use under Integration → AI Settings; you are never asked for an API key, because the key stays on the server and is never sent to your browser. Where no provider has been configured at all, the actions say so and point you at your administrator.

Confluence republishes this element’s page in the model’s Confluence space. It appears on the element types that have a page of their own; see Section 9.2.3.1.

The status line beside the controls is coloured by outcome (green for success, red for error) and clears itself after a short while.

A pre-condition exception means the service had no net effect. A client receiving one is told that its request was refused, so it may retry, correct the request, or give up, and it may do any of those only if nothing happened. A process that raises one of its own pre-condition exceptions after a step has already changed something — a payment posted, a message sent — would otherwise leave that change behind under an answer saying nothing happened. Check a pre-condition before anything is committed and the question does not arise; where it cannot be checked earlier, the change has to be undone.

A compensation says how. It is one request to the contract that undoes the change — Post transfer undone by Reverse transfer — with request constraints building that request exactly as a request service’s do. A complex undo is then a contract of its own, realized by a process like any other. A compensation can be stated in three places, and the first that applies covers a step:

A function changes nothing, so neither a function contract nor a request to one is offered a compensation. Verification reports a committing step that nothing covers and that runs before one of its process’s own pre-condition exceptions is raised — by a check, by a raise step, or by an exception handler passing on a requested service’s refusal in this service’s terms (Section 4.18.52). An execution environment runs them: on such a raise it undoes what the process committed, newest first, before the exception leaves the process, and refuses at its promotion gate a process with a change nothing undoes (How a refusal undoes what was committed). A workflow generated as source runs none, so the Temporal generator refuses a process containing one, and a Camunda export lists them under Compensations not exported.

The service is the transaction scope. Process languages such as BPMN mark out a transaction as a region drawn inside a process. URDAD has no such construct and needs none: a service’s boundary is its transaction’s. A service either delivers what its contract promises, its post-conditions holding, or refuses with one of its pre-condition exceptions and has no net effect, whatever its process committed on the way. That holds however the refusal arises: from a check, from a raise step, or from a handler passing on the refusal of a service it requested (Section 4.18.49). Part of a process that must succeed, or have no effect, as a whole is therefore made a service of its own. It then has a name, a contract stating its requirements, and clients that handle its refusal like any other, and it can be reused, none of which a region drawn inside a process has. Transactions nest the same way services do: when a process undoes a request whose service was itself realized by a process, the request’s compensation undoes that service as a whole.

Such a transaction is a long-running business transaction, a saga, made good by compensations, not an atomic one. Whether a provider commits its own changes atomically is a matter of how it is realized, which the model, being technology neutral, does not state.

Withdrawing after acceptance: the Undo step. A refusal is decided before a service is provided. Some outcomes arrive after it has been accepted: a customer withdraws an order once the stock is reserved and the payment taken. That is not a refusal — something did happen, a cancellation fee is charged, the order is recorded as withdrawn — so it must not be a pre-condition exception, which would say nothing happened. It is a normal completion: the response says the order was withdrawn, and post-conditions qualified by a condition (PostCondition above) say what holds when it was — "when withdrawn, the cancellation fee has been charged".

What the process does on that path starts with an Undo step, on the Process View’s toolbar beside Raise exception and drawn as a red hooked arrow on the flow. It undoes everything the process has committed so far, exactly as a refusal would: newest first, each step by its own compensation, else by its contract’s Undone by, a step that needs none left as it is. Then the process carries on — charging the fee, populating the response. What it undid is gone: a later refusal, or a second Undo step, undoes only what was committed after it. Its scope is the process, as a refusal’s is: a requested service realized by a process is one step, undone as a whole.

An Undo step addresses no requirement of its own. Undoing is how a process reaches an outcome, never the outcome, so the Responsibility Allocation View refuses to allocate one; the requirement it serves goes to the flow holding it and the steps establishing that outcome. Nor may it stand in concurrent work — a concurrent lane, a background flow, a message handler, a parallel request’s exception handling, a parallel for-each body — where other work may still be committing and "everything so far" means nothing. Verification reports both that and an Undo step with nothing to undo (Section 4.18.52.2). A function changes nothing, so an Undo step in a function’s process breaks its claim to be one.

A composition, an association or an aggregation may target the very structure it is stated on. A Node composed of Node children, a Category with sub-categories, an Employee whose manager is an Employee — the structure appears in its own type list, in the Data Structure View as in the element details form.

Specialization is the exception: a structure may not be its own base, and the picker leaves it out of both Add specialization and Add specialized data structure. A structure that specialised itself would make base name nothing a reader could call a base, and the same rule keeps a longer cycle out of the hierarchy — see Section 4.1.2.4.1.

In the Data Structure View a self-reference is drawn like any other: the target is a second box beside the structure, with the relationship’s own arrow between them. Expanding it redraws the structure collapsed rather than opening it inside itself, the same way two structures that reference each other are drawn.

Several fields may target one structure — an order’s billingAddress and deliveryAddress are both an Address. Each field is then drawn as its own relationship, ending at its own box, so every role name sits on its own arrow. In the Data Structure View and the Entity View alike, the structure is drawn in full at most once; each further field ends at a name-only box of the same structure.

An entity is changed only through a service of the responsibility domain that owns it. There is no process step that writes an entity directly: when a deployment executes the model, that service is where the entity’s pre-conditions and invariants are checked and where two concurrent changes are told apart, and a direct write would bypass all three.

So a post-condition about entity state — "the policy is in force" — is addressed by requesting such a service. In the Responsibility Allocation View, drop the Entity tool on the post-condition and choose the entity, or drag the entity itself from the model tree onto it. A new service is created in the domain that owns the entity, provided you may change that domain: its request structure is a view of the entity, and it carries one post-condition for you to state the change in, using the entity’s extent. A call of it, waiting under Activities to place, addresses your post-condition. Name the service and state its post-condition before placing the call.

A data structure whose Entity feed names an entity is a view of that entity — its full field list is not authored directly, but aggregated across every view that feeds it. Every field of such a view carries a second, optional property, Entity role, that says what the field’s value means toward the entity, alongside Relationship and Multiplicity:

This is a different question from Relationship. Relationship says how this structure holds the value — as its own, as a shared part, or merely associated with it; Entity role says what the value means toward the entity. A field’s direction — whether it is being supplied or reported — is not part of the vocabulary either: that already follows from whether the view is a contract’s request or response structure.

Entity role is meaningful only on a field of a view — the selector appears in the field’s details only once Entity feed is set, and it is ignored everywhere else.

Leaving a field’s role unset is not the same as marking it Transient, and the tool never guesses one from the other. An entity-backed field with no role stated yet is listed as a warning — see Section 4.18.9. Two views declaring the same field name with disagreeing roles are treated exactly as two views disagreeing about the field’s type: both are shown side by side wherever the entity’s field conflicts are listed.

At most one identifying field, and what it may be. A view naming two fields as Identifies would leave nothing to say which is authoritative, so the tool refuses to consider more than one — see Section 4.18.10. A compound key is not an exception to this: model it as a single field composed of its own value-object data structure (a PolicyKey holding series and number, say) and mark that one field Identifies, rather than marking several fields of the view.

The one field marked Identifies must be either a plain attribute — a primitive or an enumeration — or a single field related to another data structure by Composition. Never Aggregation or Association: an identity value belongs to, and means nothing outside, this view’s own designation of the entity, where an aggregated or associated structure implies a life of its own elsewhere.

A field whose Entity role is States may also be marked Unique: no two instances of the entity may hold the same value there. A client’s login is the usual example — two clients signing in under one login would make every condition that compares a login with caller ambiguous. An identifying field needs no mark, since it already names exactly one instance.

Marking a field unique is a requirement on the entity’s population, and it is enforced where that population is kept: an execution environment's entity store refuses a write that would give a second instance a value another already holds, and the request that tried it fails with nothing written. A field left empty never clashes. Unticking Unique clears the mark; it is not recorded as "not unique".

It also matters to an association. A condition may find the instance an association points at by a field of that instance — p.owner.login = request.ownerLogin finds the client who owns a policy by their login — and that only names one instance when the field is unique or identifying. A write whose association is found by any other field is not one an execution environment can make from the post-conditions alone (Section 4.18.33). Across domains, finding an instance by a field other than its identity reads the other domain’s records, and is asked for instead (Section 4.18.13).

The checkbox is offered on a stated field of a view, and on any field already marked. Anywhere else the mark says nothing, and is listed as a warning — see Section 4.18.12. Two views declaring the same field with one marking it unique and the other not are treated as a conflict, as for a disagreeing role.

Making a field unique on an entity an execution environment already holds is checked when the environment is promoted: if stored instances already share a value there, the promotion is refused, naming the field and how many values are shared (see A field becoming unique).

Every field carries a third optional property, Personal data, that says whether its value is personal data a deployed execution environment would hold about a real person, and — if so — under what erasure regime. Unlike Entity role, this is not scoped to a view of an entity: it appears on every field, because whether a value is somebody’s personal data is a fact about what the field holds, not about where it is currently used.

Leaving Personal data unset means not personal data, and — unlike Entity role — this is never listed as a gap. Most fields genuinely are not personal data, so requiring an explicit "not personal data" on every ordinary field would be noise with no protective value.

How long a retention hold lasts, and under which regulation, is not stated here: it is deployment content, set where the execution environment is configured, for the same reason a timing event’s exact override value is deployment content rather than model content. The model states only that a hold applies, which is what a reviewer needs to see.

Marking Personal data on a field whose Entity role is Transient is listed as a warning — see Section 4.18.11. A transient field is never persisted, so there is nothing for erasure or retention machinery to act on; the two properties are then making a combined claim that cannot mean anything.

See Section 5.8 for what this classification is for: what a deployed execution environment does with a field marked this way. The classification here is the same one described there, authored on the field rather than repeated in prose.

An entity's records belong to the domain that contains it, its owning domain. Another domain asks for what it needs through the owner’s query services rather than reading the records (Section 4.18.13), so that the owner stays free to change how it keeps them.

An owner may make an exception. The entity’s Readable by lists domains that may read it directly — its published read model. A domain listed, and every domain nested inside it, may read the entity’s population and follow associations into it, but only to stored fields that a view declares and that are not personal data (Section 4.3.2.5). Personal data is always asked for, never read. The list is empty unless the owner adds to it.

An association from another domain’s entity to this one is an identity link: it holds the instance’s identifying field, and nothing more is read through it without asking. The owner may delete an instance another domain refers to; the reference then names nothing.

From the step that defines it to the end of the sequence containing that step — and into everything nested inside that stretch.

So a variable defined in the main flow is available to a loop body further down; a variable defined inside a loop body, or inside one arm of a branch, is not available after that block ends. That is not a restriction so much as a consequence: the arm may not have run, so after the merge there is nothing the name could mean.

A name bound to a collection is used with →; one bound to a single value with .. Setting the multiplicity wrongly makes every expression that reads the name wrong with it, so it is worth getting right when you declare it rather than discovering it later.

Does this actually build the request, or only constrain it? providerRequest.channel = request.preferredChannel says exactly what the field is; providerRequest.amount > 0 says something that must be true of it without saying what it is. Both are legitimate — the second is often exactly what you mean — but only the first is something a generator can build from. The tool tells you which is which; see Section 4.18.37.

Have you left anything mandatory unsaid? If the requested contract’s request has a field that must be given a value, and no constraint you wrote mentions it, the tool says so; see Section 4.18.38.

Neither blocks you from moving on — both are warnings, not errors — but both are exactly the kind of gap that is invisible until the step actually runs.

The step goes wherever the values are, so each lane of a decision, the success lane of a request and each of its exception handlers can populate the response in its own way. The rule is once, on every path that completes:

Populating inside a loop body, or in a lane that runs on past its join, cannot be "once": accumulate with a loop’s carried variables and populate after the loop.

A post-condition that determines a field outright — response.accepted = request.score < 70 — already says how that field is built, so it counts as populated on every path, and a process does not restate it. Only fields that depend on what the process does need a Populate response step.

Both checks, and whether a step’s constraints determine what they populate (Section 4.18.39), are warnings: neither blocks you from moving on.

Multiplying an exact amount by a rate gives a result with more places than anything is reported to, and which way it rounds is a contractual or regulatory decision rather than an engineering detail. So it is stated, by name, with the scale it rounds to:

All four apply to a Real as well, and that is the only way to reach a Decimal from one.

Adding, subtracting and multiplying two exact decimals is exact. Dividing is not: 10 / 3 has no exact decimal value at all. Rather than round by a rule nobody wrote down, the operator was removed — and balance / 12 is reported, naming what to write instead:

Wherever the tool evaluates a body — trying an example, checking a request or an answer at run time — Decimal arithmetic and all eight operations are computed exactly, and a division is rounded once, straight to its scale: 23.34.divideHalfUp(7, 2) is 3.33, (1.0).roundHalfUp(2).divideHalfEven(8, 2) is 0.12, a tie going to the even digit.

divideCeiling, divideFloor, divideHalfEven and divideHalfUp are the same four modes as binary operations, each taking the divisor and the scale. Every other number keeps /, which yields a Real — so 1.5 / 2 and count / 12 are unaffected.

Decimal carries no number of decimal places. Precision genuinely varies — two places for most currencies, three for a few, four to six for an FX quote, fractional pricing for some bonds — so a field that must hold a particular scale says so as an ordinary invariance on the field, exactly as it would state any other numeric constraint.

A Date or a LocalDateTime moves by a CalendarPeriod through an operation that states what + leaves out:

The three arguments are the CalendarPeriod, StandardLib’s BusinessCalendar and StandardLib’s BusinessDayConvention, and all three are required. BusinessDayConvention::unadjusted says that no adjustment is made, but the calendar is still named, so a reader knows which one was considered and set aside. A wrong number of arguments, or an argument of the wrong type, is reported. A type of your own called BusinessCalendar is not StandardLib’s and does not fit.

The day of the month is kept where the month has it and otherwise becomes the month’s last day: 31 January plus P1M is 28 February, or 29 in a leap year.

A DateTime and a Time have no addPeriod. Moving an instant by a month needs the time zone it is read in, which it does not carry, and a time of day has no date to move. Move the local date or date-time the rule is about.

Subtracting two points of different kinds — a Date from a DateTime — is reported as types with nothing in common. Decide which you mean and model both fields as that.

A difference can come out negative, although the library’s amounts are never negative. That rule is about the values a field holds; an expression on its way to a comparison may pass through a negative number of hours.

Values are read in the formats the standard library’s types state: RFC 3339 for dates and times (2026-01-31, 2026-01-31T10:00:00+02:00) and ISO 8601 for amounts (PT72H, P1M). They are compared by what they denote, never by their text: 10:00+02:00 equals 08:00Z, and PT72H is longer than PT9H. A time or timestamp computed from another keeps its offset.

A date and a local date-time can also be taken apart:

DateTime and Time have none of these, deliberately. They are instants, and which day or hour an instant falls on depends on the time zone it is read in: 2026-01-01T01:00+02:00 and 2025-12-31T23:00Z are the same moment, but one is in 2026 and the other in 2025. A rule such as "received on a weekday" is about a place, so model the local date-time or date it means, as LocalDateTime or Date, rather than asking an instant.

There is no separate notation for a date or a duration. Write it as text — in single quotes, as all text is in URDAD-OCL — in its type’s format, beside the value it is compared or combined with:

The value beside the text decides what it is. Beside a Duration it is a Duration; beside a Date it is a Date. Beside a date or a time, text beginning with P is the amount that moves it, so in request.receivedAt + 'PT2H' it is two hours, not a second point in time. 'P1M' there is a CalendarPeriod, which + cannot move a point by (see above). Beside anything else — a String field, another piece of text — it stays text, so label = 'PT1H' compares two strings.

Text that is not in the type’s format is reported where it stands, with one that is: '240 hours' is not a Duration — write one like 'PT1H'. A duration has no days, because a day is not always 24 hours: 20 days is 'PT480H'.

Double quotes are not part of the language. They are how JSON writes text — including the Try an example box beside every constraint — so they are an easy slip, and the message says so: "PT240H" is reported with the repair, 'PT240H'.

OCL has four kinds of collection, and whether two of them are equal depends on their kind. A Sequence and an OrderedSet have an order; a Set and a Bag do not. An entity’s population, Claim.allInstances(), is a Set; select and reject keep the kind they are given; collect makes a Bag from an unordered collection and a Sequence from an ordered one; sortedBy makes an ordered one. A list in a request or a response is a Sequence.

Two collections are equal element by element, in order, only when both are ordered. Otherwise they are equal when they hold the same elements, each as many times, in any order:

So a post-condition about a list requires an order only when it says one, with sortedBy. any gives one element the body holds of, and invalid when none does.

An iterator may be written without a variable. Each element is then what a bare name in the body is read from:

The element’s field wins. A bare name that is a field of the element means that field, even where the request, the response or a name the process has bound has a field or a value of the same name. A name the element does not have is read from outside, as anywhere else. Where the element is an entity, a name that is nothing else is not reported, because an entity may have a property no view has stated yet.

To read the outer value inside such a body, name it in full, request.amount rather than amount, or declare the variable and the rule does not apply.

An entity is a business object with an identity — a real account, a real claim — and a DataStructure is a view onto one: the shape a particular message carries. Views have no population of their own, so AccountSummary.allInstances() is reported, and the message names the entity to ask instead.

That matters more than it sounds. Two services may each carry a different view of one account; if both had extents there would be two different answers to "how many accounts are there".

Give as much of the path as it takes, innermost part last:

Where the bare name would be ambiguous the tool offers you the qualified one as you type.

An entity’s fields are those of every view onto it, taken together — which is what the Entity View draws. The tool types what it finds there, so a.balance > 'x' inside an extent is reported like any other type mismatch.

But it does not report a name no view declares. An entity’s full field set is deliberately not written down anywhere — that is what makes it an entity rather than a data structure — so a name the model has not projected into any message shape may still be a real property of the thing. The tool would be guessing, and it says nothing instead.

@pre may be written in a post-condition, and in its Condition, and nowhere else. A pre-condition is evaluated in the state before already, so it has nothing to add there; an invariance is not about a service at all; and a process step is a part of how a service is realized, not a claim about its whole effect. Anywhere else it is reported as an error.

State lives in entities (see Section 4.6.12), so that is what @pre marks:

Anything else is reported, because it has no state before the service: the response and its fields (there is no response before), caller, a variable the body bound for itself, an operation such as size@pre(), a function applied, and a field of a structure value. That last one is worth a sentence. In a.address.city@pre, a.address is a copy of the account’s address, and the copy has no history; what is meant is the account’s address before, a.address@pre.city.

An entity is matched with itself before and after by its identifying field — the one a view of it declares as identifying (see Section 4.3.2.3). That is the only identity the model states, so it is the one @pre uses. Two consequences:

Account.allInstances@pre() needs no identity: it is the whole population, whoever is in it.

Try an example takes the population before under extentsBefore, beside extents — see Section 4.18.5.

At run time, the execution environment reads the state before a service as it was when the service started, and enforces @pre. The cases it cannot decide, and so lets through, are listed in Section 8.9.8.

A common pre-condition is that some other service must be able to answer this request — that asking it will not be refused. When that service is a function, say so by comparing its answer with null:

When the condition goes on to read the answer, bind it once and guard it:

Often you do not need the guard. A condition that reads the answer is already not satisfied when there is none — a field of null is not a value — so

already requires that premiumFor answers. Write the guard when answering is the whole of what you mean, or when the condition should say plainly what it requires before it reads.

Two limits are worth knowing.

It cannot name the exception. Every way of not answering — an unmet pre-condition of the function, or any exception it raises — gives the same null. You can require that the function answers; you cannot require that it does not raise one particular exception.

It works only for a function. An ordinary service cannot be asked at all (see above), and a pre-condition saying "that service must not raise" would be a claim about how this service is built rather than about what it needs. State the condition itself instead: take what the lower-level service’s own pre-condition requires, restate it in terms of this request, and give it an exception of its own. The process then either handles the lower-level service’s exception or relies on this pre-condition having already ruled it out.

Select the model itself in the model tree. Its details form has a Time zone field, which holds an IANA time-zone id such as Africa/Johannesburg. Left empty, the zone is UTC.

It is model content like any other change: committed, reviewed and signed off with the model, so changing it is visible in the history and at a phase gate. An execution that is already running keeps the zone it started with, because the zone is fixed into a process when it is deployed, as its expressions are.

An element of an element library is read in its library’s own zone, not in the zone of the model that uses the library.

An id the tool does not know, such as a misspelling or a zone that does not exist, is reported by Verify model on the model itself and blocks a phase transition. Otherwise every today() in the model would rest on a date nobody can work out.

Try it asks the decision a question. It starts with a request in the shape of the contract’s request structure, filled with sample values: replace them. The response appears beneath it, and the rules that matched are named and shaded green in the table. When the decision gives no response, Try it says why. For example, two rules matched under Unique, or a rule could not be worked out from the request. It is the same evaluation the decision is answered with whenever it is asked.

A description says what the element is and when to reach for it. It does not restate the name, and it does not restate a constraint the model already carries.

That last point is the one worth being deliberate about. Where an element has invariances, those hold the constraint — what must be true of a value. The description holds the meaning — what the thing is and what it is for. Say a constraint in both places and the two drift, and nothing in the tool will tell you which one is now wrong.

A short description is plain text — it is one or two sentences, and it is drawn into a diagram widget where formatting buys nothing.

A detailed description is usually Markdown, so it can use emphasis and a list where a list is what the content is. See Section 4.10.3.

Hovering a widget names the element it stands for — its type and its full path through the model — rather than showing either description. See Section 4.1.2.1.

Because the short description is what a diagram draws, keep it short enough to be read at a glance. A paragraph belongs in the detailed description.

Every element the tool ships in StandardLib — the model root, each responsibility domain, each type and each field — carries a short description, and the types that are easily confused with one another carry a detailed one. It is checked when the tool is built, so a definition cannot ship undescribed.

Shipped content is where an undescribed name costs most: a reader cannot open the authoring discussion, cannot ask whoever wrote it, and has only the name to go on. The same is true, a little less sharply, of any library you publish for others to reference.

A short description written in Markdown is rendered as Markdown in the domain’s widget wherever that widget appears — the Scope view and the Dependencies view — and in the same diagram in generated documentation. The two are produced from one description and always agree. The model root’s own short description is rendered the same way, in its widget on the model’s Scope view.

Only Markdown is interpreted there. A short description written as HTML or LaTeX is shown as typed inside the widget, and is rendered in the element details view instead.