Workflow Set-up

1Overview #

One step of the route: who is asked, when they are asked, how many of them have to answer, and what their answer does to the document. OK keeps the step on the form ; nothing reaches the database until the workflow itself is saved (F5).

2What this screen is for #

• A workflow written here is dormant until a voucher type points at it. That is done in Masters > Voucher Manager : turn on Enable Workflow and choose this route.
• One voucher type can carry several workflows. Which of them a particular document enters is decided by each workflow's activation condition .
• When a document is submitted the engine creates one instance per step and one assignment per responsible person. Those are what the approval inbox and the bell show.
• Everything the engine decides — and the reason for it — is recorded, and the voucher's Workflow panel reads it back.

3Writing a route, step by step #

1. Add (F3) and give it a name that says what it approves.
2. Leave the activation condition empty while you find your feet — every document then enters the route — and narrow it later.
3. Under Document creation options set the posting status to Unposted if the document must stay out of the books until it is approved.
4. Add step. Name it, give it order 1 , and set it to Start immediately on work flow submit — the first step must, or nothing would ever begin.
5. Name the people, or a user group. Choose how the step completes: All of them, Any one, Atleast N, a Percentage , or a Majority .
6. Say what a completion does to the document — the status, and the posting status — and what a rejection does, and where a rejection sends it.
7. Add the later steps with order 2, 3 … set to Start when previous step was completed .
8. Save (F5) , then attach it to a voucher type in Voucher Manager and try it on a real document.
9. Closing the step dialog keeps the step on the form only — nothing reaches the database until you save the workflow . Until then the step's own Who that comes out as says so, and names what the database still holds.

4Drawing the route (the Diagram) #

Step details shows the route drawn by default; Table shows the grid. In View mode the drawing is read-only: click a step to pick it, double-click to read it. After Add (F3) or Modify (F4) it is the designer, and every change it makes is the same change the step window would make.

• An arrow is a starting rule. From Start: the step opens when the document is submitted. From the step just before it (by order): it waits for that step. From any other step: it waits for all its parents , and the arrow's source is one of them. Dashed from Start: it is started by hand ( No Criteria ).
• Draw an arrow by dragging from the blue dot under a step — or under Start — onto the step that should wait. Or, without aiming at the dot: click the step (or Start), press Connect , then click the step that should wait; press Connect again to stop. Drawing a second arrow into a step adds a link — a step that waited for the one before it keeps waiting for it too.
• Remove an arrow : click it and press Delete, or Remove . The step it pointed at loses that parent; with none left it becomes started by hand, and the message says so — draw a new arrow into it.
• Add step opens the step window; double-click a step to edit it; select a step and press Delete to take it off the route (a step documents have been through is kept, as in the grid).
• The number in each box is the execution order . It is set in the step window; the drawing places a step below everything it waits for.

5The step window #

Every field of a step is explained in the step window itself: open a step with Add step or Edit step and press the Help strip on its right edge. It covers a first step worked through, each section of the window field by field, why a list can be empty, what OK checks, the keys, and every message the window can show.

6The five policies, exactly #

• All — every person assigned to the step has to answer that way.
• Any — one answer is enough.
• Atleast — the number beside it. Four people, Atleast 2: the second answer settles the step.
• Percentage — meant as that percentage of the people assigned, but today it behaves like All : the engine divides whole numbers, as the desktop always has, so 2 approvals of 3 count as 0% and only everybody counts as 100%. Use Atleast or Majority for "some of them".
• Majority — more than half.

Completion and rejection are judged separately, so a step can complete on All and be rejected by Any — one refusal stops it while every approval is needed to pass it. That is the usual setting.

7Where a rejection sends the document #

• Revert to Previous Step — the step before this one opens again, and its people are asked afresh.
• Revert to Creator — the whole route goes back to the person who raised the document, to correct and submit again.
• Abort Workflow — the route ends rejected; the document does not go round again.
• Allow the document to be edited on rejection lets the raiser change it before re-submitting. Without it they may only re-submit what was refused.

8When a step is overdue #

• A step counts as overdue once Escalate after has passed since it opened — or, if that is empty, Expiry in days .
• Nothing happens unless the step also names somebody under Escalate to . With nobody named an overdue step simply keeps waiting, and the Workflow Manager shows it in orange.
• The sweep is a background job inside the API , not something this screen or the inbox does. It looks every half hour; the delay is not exact to the minute.
• What becomes of the people who already had the step is this workflow's own Escalation set-up, above. Off hands the step over — theirs close as escalated. On keeps them and adds the new names beside them.
• Either way a step escalates once : an assignment made by an escalation is never escalated again, so nothing travels down a chain.

9Conditions #

A condition is one true-or-false test, read against the saved document. Three sections are available: the document , its item lines and its ledger lines .

• Builder writes it for you: pick a field, pick an operator that fits what the field holds, give the value. Rule adds another; Group adds a bracket, which may be ALL (AND) or ANY (OR) and may be turned round with NOT.
• Expression is the same condition as text, with the field and operator pickers beside it. Anything the builder cannot show — a function, arithmetic, a sub-query — is written here, and the screen keeps it as text rather than losing it.
• Check asks SQL Server to read the test without running it on anything. Test it on a document runs it on one real voucher, says whether it holds, and lists what that document has in every field the condition names — which is how a condition that looked right but never fires is argued with.
• MasterSection.VchAmount > 100000 — only large documents enter the route.
• MasterSection.LedgerName = 'ABC Traders' — only that party's.
• LineItemSection.Qty > 500 — true if any line has more than 500, because the lines are joined to the document.

The same kind of test on a step decides whether that step is created at all — which is how one route can ask a second approver only of the larger documents.

There are no totals. The picker offers the columns the engine can actually read, and the document row does not carry line totals — so a test on "the whole quantity of the order" is not available. Test the figures on the document ( MasterSection.VchAmount ), or a line ( LineItemSection.Qty ), which is true if any line matches. The desktop offered a longer list including TotalLineItemQty and the like; those names fail when the engine reads them, and a workflow with one in its condition simply never starts.

A condition may not carry a semicolon, a comment marker or a word like delete : it is a test, not a command, and the screen refuses those rather than letting the engine run them.

10Who is e-mailed, and when #

A notification rule says: on this event, send this template to these people. There are two sets, kept in the same tables the desktop uses:

• Document notifications , on the form — the document is created, changed or deleted, or its workflow is submitted, finished or aborted. When the workflow finishes is the one that tells the raiser their document went through.
• A step's own rules , in the step's window under Who is e-mailed, and when — somebody is asked, the step opens, is approved, refused, escalated, paused, stopped or cancelled.
• Add rule. Choose When it is sent and the Message template — the mail is built from it, with the document's values filled in. A rule without a template is never sent, so it is required.
• Choose Who from the route : nobody, everybody on the route, or — on a step — the step's own people, or the people it was escalated to. These are worked out on each document.
• Add people or user groups by name, and switch on The person who created the document if the raiser should hear.
• Who that comes out as shows what is picked: named people and the groups' members by name, the route's people and the creator described, because they are only known on a real document.
• Save (F5) the workflow. The rules are written with it; nothing reaches the database before.
• Nothing is sent unless Enable notification and E-mail are on and an E-mail account is chosen in Notification options. The rules say so above themselves when one of those is missing.
• Only a person whose user account has an e-mail address can be sent anything. The rest are skipped silently.
• Two rules on one event are not two separate mailings. The database gathers the people of every rule on the event into one list and sends each rule's template to all of them.
• The template list here holds every template, as the desktop's rule window does — not only those marked Workflow Notification. An inactive one is listed, marked, so a rule that uses it reads true.

11Changing a route that is already in use #

• The engine reads the definition each time it decides , so a change reaches documents that are already waiting. For a materially different route, Duplicate and change the copy.
• A step documents have been through is kept even if you take it off the list, because their history points at it. The screen says so when it happens.
• A workflow that documents have used cannot be deleted. Mark it Inactive : no new document picks it up, and the old ones stay readable.
• A workflow a voucher type still points at cannot be deleted either — clear it in Voucher Manager first.

12Rights #

• The route itself: the Masters object Work Flow - Settings Master (Find / Create / Alter / Delete).
• Step names are a master of their own: Work Flow Steps . Without Create on it you can use the existing names but not add one.
• The database checks the same rights again when the row is written, so a screen that offers a button is not the last word.

13Step window: what it is for #

• A step is one stop on the route, such as PO Review or CFO Approval . When a document is submitted, every step whose condition holds is created for it, in execution order, and each step asks its people when it opens.
• It is opened from Step details on the workflow form: Add step for a new one, Edit step or a double-click for an existing one. The workflow has to be in Add (F3) or Modify (F4).
• It does not approve anything and does not touch any document. Approving happens on the voucher, in My Approvals and in the Workflow Manager.
• OK (F5) keeps the step in the list on the form. Save (F5) on the workflow writes it. Closing the browser in between loses it.
• A change to a step reaches documents that are already waiting on it, because the engine reads the step each time it decides. The people already asked on those documents are not changed.

14Step window: your first step, step by step #

A purchase-order review that two reviewers must both pass, and that sends the order back to whoever raised it if either refuses.

1. On the workflow form press Add step . The window opens with the cursor in Step name , execution order already 1 and starting criteria Start immediately on work flow submit .
2. Type PO in Step name and pick PO Review . If it is not in the list, open the list and press + Create new step at its foot, name it, save, and it is picked for you.
3. In Description type Purchase order review for and press Pick a field , then choose mVoucherNo . The text becomes {MasterSection.mVoucherNo} , which turns into the order's own number on each document.
4. Set On start document status to Under Review . Leave Step creation condition empty, so every purchase order gets this step.
5. In Responsible users pick the two reviewers, or pick the PO Review Group in Responsible user groups . Who that comes out as names every person the step will ask.
6. Completion policy All , on completion status Approved , posting status Posted if this is the last step.
7. Rejection policy Any , on rejection status Rejected , Where a rejection sends the document Revert to Creator , and switch on Editable after rejection so the raiser can correct the order.
8. In User instructions write what the reviewers check, for example Check the rates against the last purchase and the quantities against the indent.
9. Press OK (F5) . The step appears in the grid as row 1. Press Save (F5) on the workflow and confirm.
10. A second step, CFO Approval , would take order 2, Start when previous step was completed , and a creation condition such as {MasterSection.VchAmount} > 500000 , so only large orders ever reach the CFO.

To change it later: pick the row and press Edit step . To remove it: pick it and press Remove step , then save; a step documents have already been through is kept, and the save says so.

15Step window: The step #

• Step name is required. It is what approvers see in their queue and on the voucher. The names are a master of their own, Workflow Steps , shared by every workflow; that is also where a step's standing instructions, attached documents and parent steps are kept. + Create new step at the foot of the list opens that master without leaving this window.
• Execution order is required, 1 or more, and must differ from every other step of the workflow. It decides the order steps are created and which step is "the previous one". Gaps are allowed: 10, 20, 30 leaves room to insert a step later.
• Description is optional. It is copied onto each document's copy of the step when the document is submitted, with every {Section.Field} replaced by that document's value, so it can say Review of PO 42 for ABC Traders .
• Pick a field opens the list of fields the engine can read - the document, its item lines and its ledger lines - with what each one holds. Clicking one writes it into the text in braces at the end.

16Step window: When it starts #

• Starting type is Automatic : the engine opens the step on its own when its starting criteria are met. It is the only type the engine implements.
• Starting criteria is required. Start immediately on work flow submit opens the step the moment the document is submitted - the first step must use it, and two steps may both use it to run side by side. Start when previous step was completed opens it when the step before it (by execution order) completes or is cancelled. Start when all parent step was completed waits for every parent named on the step name in Workflow Steps, for a route that branches and joins. No Criteria is never opened by the engine - not on submit and not when another step finishes - so it is only for a step somebody means to start by hand.
• On start document status is optional. The document takes this status while the step waits, for example Under Review or CFO Approval Stage . (Not Applicable) leaves the status as it is.
• Step creation condition is optional. Empty, the step is created for every document. Filled, it is created only for documents the condition is true of, tested once when the document is submitted; a document it is false for simply has one step fewer. This is how a second approver is asked only of the larger orders.
• The condition has two faces. Builder : pick a field, an operator that suits what the field holds, and the value; Rule adds another line, Group a bracket, which may be ALL (AND) or ANY (OR) and turned round with NOT . Expression : the same test as text, for anything the builder cannot draw - a function, arithmetic, a sub-query.
• Check asks SQL Server whether the condition can be read, without running it on a document. Test it on a document runs it on one real voucher by its Voucher #ID, says whether this step would be created for it, and lists what the document holds in every field the condition names.
• A test on an item-line or ledger-line field is true if any line matches. There are no totals of the lines: test the document's own amount, {MasterSection.VchAmount} .

17Step window: Who is responsible #

• Responsible users are the people asked to answer this step. Type to search. A disabled user is listed and marked as such; they cannot sign in to answer, so a step that relies on them waits.
• Responsible user groups add every member of each group. The database works out the members when the workflow is saved and again on every later save, so somebody who joins the group afterwards is asked on the next document.
• At least one user or one group is required - a step with nobody on it would wait for ever.
• Who that comes out as lists everybody the step will ask, as picked: the users first, then each group's members, nobody twice. Until the workflow is saved it also says what the database still holds for this step.
• A document already waiting keeps the people it was given when it was submitted. To add somebody to one document, use Add under PEOPLE in the Workflow Manager.

18Step window: If nobody answers #

• Escalate to is optional. Empty, an overdue step keeps waiting and the Workflow Manager shows it in orange. Named, the overdue step goes to these people. Whether the people who already had it keep it or lose it is the workflow's own Escalation setting on the form: off hands the step over, on adds the new names beside the old.
• Escalate after is the wait before the step counts as overdue, counted from the moment it opened. Empty uses Expiry in days further down; both empty, the step is never overdue.
• Counted in is Days or Hours .
• The check runs in the background about every half hour, so a step escalates within half an hour of falling due, not to the minute. A step escalates once: somebody it was escalated to is never escalated again.
• If the section shows Automatic escalation is not installed on this company yet , these fields are hidden until an administrator runs the escalation script. Approvers can still escalate by hand from My Approvals.

19Step window: Completion policy #

• Completion policy is required and decides how many approvals pass the step. All : every person on the step. Any : one approval. Atleast : the number in Completion value . Majority : more than half - 2 of 3, 3 of 4. Percentage : see the note below.
• Completion value is read only by Atleast (a number of people, above zero) and Percentage (1 to 100). The others ignore it.
• Percentage behaves like All today. The engine divides whole numbers, as the desktop always has, so 2 approvals out of 3 count as 0% and only everybody counts as 100%. A step set to 50% therefore waits for everybody. Use Atleast or Majority for "some of them".
• When everybody has answered and neither policy is met - three people, All to complete and All to reject, two for and one against - the step closes anyway rather than wait for ever, and the Workflow Manager marks it a tie.
• On completion document status is the status the document takes when the step passes: Under Review mid-route, Approved on the last step. (Not Applicable) leaves it unchanged.
• Posting status on completion : Posted puts the document into the books as the step passes - usually only on the last step; Unposted keeps it out; (Not Applicable) leaves it as it is.

20Step window: Rejection policy #

• Rejection policy is required and decides how many refusals stop the step, with the same five choices counted in refusals. Any is usual: one refusal is enough. Completion and rejection are judged separately.
• Rejection value is read only by Atleast and Percentage , as above - and Percentage behaves like All here too.
• On rejection document status : normally Rejected , or Altered when the raiser is meant to correct it and submit again.
• Posting status on rejection : Unposted takes a document that had reached the books back out of them.
• Where a rejection sends the document is required. Revert to Previous Step opens the step before this one again and asks its people afresh. Revert to Creator puts every step back to waiting and the workflow back to not submitted: the raiser corrects the document and submits it again, and the whole route runs from the start. Abort Workflow ends the route as aborted; the document does not go round again.
• Editable after rejection : on, the raiser may change the document before submitting it again; off, they may only re-submit it as it is. The lock returns as soon as a step opens again.

21Step window: What the approver is told #

• User instructions are shown to the approvers with the step: say what they are checking and what should make them refuse. Like the description, they are copied onto each document's step with every {Section.Field} filled in. Pick a field inserts one.
• Expiry in days is how long the step may wait before it counts as overdue, used only when Escalate after is empty.
• Message template , Subject and Message are kept with the step, as the desktop keeps them. Nothing in the database sends mail from them today: the e-mails a step sends come from its notification rules, in the next section, each with its own template. Leave them empty unless the desktop still reads them for you.

22Step window: Who is e-mailed, and when #

• Each rule says: when this happens to the step, send this template to these people. The events are: somebody is asked, the step opens, it is approved, refused, escalated, cancelled, stopped because the workflow was aborted, or paused.
• Add rule opens the rule's own window: When it is sent and Message template are required; Who from the route can add everybody on the route, this step's own people, or the people it was escalated to; people and groups can be named; and The person who created the document adds the raiser. A rule has to reach somebody.
• Read rule opens a rule without changing it; Edit rule and Remove rule change the list. Rules are saved with the workflow.
• Nothing is sent unless the workflow's Enable notification and E-mail are on and an e-mail account is chosen; a warning above the rules says which is missing. Only users with an e-mail address on their account receive anything.
• Two rules on the same event send each template to everybody either rule names, because the database gathers them into one list.

23Step window: why is a pick-list empty? #

• Step name lists the names in Workflow Steps that are not inactive, plus the one this step already uses. + Create new step needs the Create right on Work Flow Steps.
• Starting type and Starting criteria are fixed lists and are never empty.
• The four document status lists come from the Status Master (Settings > Status Master); a status appears there once it is created.
• The two posting status lists are Posted and Unposted , plus (Not Applicable) .
• Responsible users and Escalate to list every user of this company except template users.
• Responsible user groups lists the user groups that are not inactive (Admin > User Groups).
• Message template lists active templates whose module type is Workflow Notification (Settings > Email Templates). A notification rule's template list is not filtered and holds every template.
• Pick a field lists the columns of the document, its item lines and its ledger lines that the engine can read; it is generated from the database, so it is never empty on a working company.

24Step window: rules the save checks #

• OK refuses the step, listing everything at once, when it has no step name, an execution order below 1, no starting criteria, no completion or rejection policy, no rejection path, an Atleast or Percentage policy with no value above zero, or nobody responsible.
• Saving the workflow checks the whole route again: execution orders unique, percentages no higher than 100, expiry not negative, every condition readable, every notification rule complete, and the first step starting on submit.
• The database checks the Alter right on Work Flow - Settings Master when the step is written, whatever the screen offered.
• A step documents have already been through cannot be deleted, only taken off the list; it stays in the database so their history keeps its shape.

25Step window: shortcut keys #

• F5 is OK: the step is checked and kept on the form.
• Esc is Cancel: the window closes and the step is as it was before it was opened. In an open drop-down list Esc closes the list first.
• Tab and Shift+Tab move between fields; in a list, type to search and press Enter to pick.
• While a window opened from here is on top - a notification rule, Pick a field , + Create new step - its own F5 and Esc apply to it, not to this window.

26If something does not work #