For administrators

Designing a workflow

The canvas: states, steps, scope, who is asked, and what happens when time runs out.

The Workflows screen

Workflows (in the sidebar, under Governance, beside Change requests) lists every workflow: its status, the types it governs (with some when it has a scope), its Order, and how many requests are open on it. Anyone may look. Drawing and publishing needs Design workflows (WORKFLOW_DESIGN), which in the starter model comes with Sysadmin and Workflow Developer. A Workflow Developer draws the rules but doesn't decide requests.

To make one:

Press New workflow.
Choose a template: Approval, Certify a new asset, Review a change, Approve a deletion, Tell somebody or Start from nothing.
Give it a name, and under Governs tick one or more types. Leave them all unticked for every type. For templates that ask, choose how many levels and which role decides at each one.
Press Create draft. The canvas opens.
Adjust states and steps on the canvas. For each step, choose Who may take it, and whether to tick Ask for a reason and Not the person who raised it.
Press Save, then Publish.

A draft does nothing until it is published. Publishing a new version of a workflow (one made with Copy to a new draft, so it has the same code) retires the version before it. Other workflows on the same types and starting event sit beside it. For each asset, they are tried in their Order (lower first), and the first whose scope takes the asset in governs it. If none takes it in, a workflow for every type governs it, and if there is none, changes are written directly. If a workflow can never be reached because an earlier one covers the same types and leaves nothing out, publishing says so. Requests already in progress finish under the version they started on. To change a published workflow, press Copy to a new draft, edit the copy, and publish it. Retire stops a workflow starting anything new.

Name, code and UID

The name is the large title at the top of the canvas. Click it, type, and press Enter. You can rename a workflow at any time, including one that is published. Under the title are its Code, Version and UID. These never change: they are how requests, the activity log and other systems know the workflow. A copy made with Copy to a new draft keeps the code and takes the next version number.

Starts on

With nothing selected on the canvas, the panel on the right shows how the workflow starts. Under Starts on, tick the types it covers. What it watches is picked from lists rather than typed: the characteristics, links and responsibilities of those types. The same goes for what a condition can test.

Only for these: a workflow's scope

Under Starts on, Only for these narrows which assets of those types the workflow is for. For example, a workflow for Data Entities that leaves out the ones in the Finance and Customer domains:

Press + add a condition.
Choose In Data Domain, then is not one of, tick Finance and Customer, and press Add condition.
Press + and to add more conditions to the same group, for example Classification is Restricted. Every condition in a group must hold.

A date condition can be compared with today instead of a date you type — and with today + 30 days or today - 7 days. It is worked out when the question is asked, so Next review date is after today still means today tomorrow. 4. Press + or another group for a second way in. An asset is in scope if any one group holds. For example, a second group could take back Customer entities that a Business Term defines.

The conditions are the same ones a list can be filtered by: characteristics, links, who is responsible, dates and domain membership. Domain membership counts assets the domain owns directly and everything inside them. In scope now counts how many assets of each type the scope takes in today. Press × on a condition to take it off.

Order decides which workflow is tried first when several start on the same type and event. An asset this workflow leaves out goes to the next one in order. On the Workflows screen, Order shows each workflow's number, and some beside the types means it has a scope.

The scope is checked when a request starts. A request already running carries on even if the asset later falls out of scope.

Condition boxes

A condition box sends a request down one path or another by itself, without anyone deciding. Select a state and tick Condition box — choose the next step automatically. It is drawn as a diamond. It can be an ordinary state, or the starting state, which decides the moment a request is raised.

Each arrow out of a condition box is a path. Select one to set Goes this way when, adding as many conditions as you need on any characteristic of the types the workflow starts on. Paths are tried in order, and Check this path first moves one to the front. The request takes the first path whose conditions all hold. If none hold, it takes the one path with no conditions, labelled otherwise. A box needs exactly one otherwise path and at least one path with conditions, or it can't be published. A characteristic the asset's type doesn't have never holds.

The request records which path was taken and why, against the workflow.

For example, a change to a restricted Data Entity needs three levels of approval, and any other change needs two:

Make sure Data Entities carry the Classification characteristic. If they don't, add it to the type in the Metamodel.
Create an Approval workflow for Data Entities.
Make the starting state a condition box.
Draw two paths from it: one into a chain of three approval states, the other into a chain of two.
On the first path, add the condition Classification is Restricted. Leave the second path with no conditions.
Save, then publish.

Who is asked, and by when

Select a waiting state (the starting state or an ordinary one, not a condition box) to see Who is asked, and by when.

Who must decide: Any one of them (the first person allowed to take a step moves it), Every one of them — one other answer decides, or Every one of them — wait for every answer. The people asked are whoever may take the steps out of the state: the holders of that role over the asset, fixed when the request arrives. With either every one option, choose The step everyone takes, usually Approve. It needs a role, and the state needs at least one other step, such as Reject.
Email: tick Email the people asked when a request arrives, then edit the Subject and Message. They start from a standard wording. You can use {title}, {asset}, {type}, {state}, {who} (who raised it), {workflow}, {approvers}, {waiting_for}, {due}, {link} (straight to the request), and {field}, {old} and {new} for what is changing. {due} is written for each person in the zone their browser last reported, so the same deadline reaches Mumbai as 21:30 and New York as 12:00 — one moment, spelled where each of them is.
Time allowed: a number of minutes, hours or days. Leave it empty for no limit. Tick Count working days only to skip the days off — the weekend as you have set it, and the dates in your own calendar under Working days below. Everything is counted in the server's time zone.
When time runs out: two choices. Draw an arrow from the state to where a late request should go — an Escalated state a manager's role decides, or Rejected — and choose that arrow here; nobody is offered it as a button, and the workflow takes it when the time is up, recording Time ran out against the workflow. Or draw no such arrow: the request then stays where it is, is marked overdue, and everybody still to answer is told once, by email and on their Change requests screen. Nothing moves without somebody deciding.
Reminders: Every so many hours or days, and/or so long before time runs out. Reminders go only to those who haven't answered yet, by email and on their Change requests screen. They start from a standard wording that you can edit.

A Tell somebody action can also go by email: choose on their screen and by email.

Actions

Select a state to see what happens when a request arrives there. Each action has a Change button. It opens the action as it was set up, and Save change puts it back in its place. × removes it.

Try it before publishing

Under the canvas, Try it walks the workflow against a real asset and writes nothing.

Press Try it against an asset and pick one.
It says whether the asset is in scope — and, for a published workflow, whether this is the one that would take it or whether another with a lower Order gets there first.
It then shows where the request would start, who would be asked (by name, from the roles they hold on that asset), by when, and whether the step emails or reminds.
Press one of the steps under Then somebody takes to follow that route. A condition box decides for itself and says why — its conditions hold, or no path's conditions held, so otherwise.
The last line says how it ends, and what the final state would do: the characteristics it sets, who it tells, what it calls.

Start again clears the route. Nothing about this raises a request, changes an asset or sends an email.

Take a workflow to another repository

A workflow can be exported and imported, so one drawn in a test repository can be moved rather than drawn again.

On the canvas, Export (.json) is the definition, whole: states, steps, tasks, actions, scope and order. It is what you move between environments and what reads sensibly in a pull request.
Export (Excel) is the same thing as a workbook — one sheet each for the workflow, its states, its steps, its actions and its scope — for review by people who will not open a JSON file. It imports back.
On the Workflows screen, Import a workflow takes either file. It reads it and tells you first: how many states, steps and actions, what it governs, and anything it names — a role, a type, a characteristic, a connection — that this repository does not have. Nothing is written until you press Import it as a draft, and while anything is missing it refuses.
If a workflow with the same code is already here, you choose: a new draft of it (its next version, which retires the running one when you publish) or a separate workflow with a new code.
What arrives is always a draft. An import that published itself would change what people are approving, by file.

States are referred to by their code inside the file, never by this repository's internal ids, so nothing collides on the way in.

Working days

Under the list of workflows, Working days says which days a time limit set in working days skips. Tick the days that are your weekend — Saturday and Sunday unless you change it — and add your own days off with Add a day off, giving each a date and a name. Press Save the days off; the whole list saves at once, so a bad date refuses the lot and says which.

Hours are counted the same way: an hour inside a day off does not count. Everything is counted in the server's time zone.