Skip to main content

Module: Approval Preconditions

Preconditions let you define on a workflow stage which details a document must have before an approval may take it out of that stage – for example "the cost center is filled in" or "the payment reference is filled in". Advanced Workflow checks these details when someone approves; it does not maintain them. If something is missing, the approver sees what is missing and can add it or reject the document.

Purpose

  • A stage is only approved once the data the next department needs is there – the cost center for accounting, for example.
  • The approver sees what is still missing as soon as they open the document (FactBox Approval Preconditions), not only when the approval fails.
  • With the severity Warning you can give a hint the approver may consciously override; who did so is recorded in the audit log.

Setup

  1. Open the AWF Workflow Template and select the stage in the Stages section.
  2. Choose the Preconditions action (or the number in the Preconditions column). The Rules page opens with the preconditions of this stage.
  3. Create a rule with New and give it a condition that describes the desired state, for example field Cost Center, operator Is Not Empty.
  4. In the rule's Approval Precondition section, set the Severity and, if you like, a Message of your own.

{add screenshot of Rules (preconditions of a stage) here}

When you open the preconditions for the first time, the app creates a rule group of their own for the stage (code PRE- + stage code), shown in the stage's Precondition Rule Group field. It is separate from the step rules: step rules are evaluated when a stage is entered, and the first match wins; preconditions are checked when the stage is left, all of them.

A precondition is worded positively: when the rule matches, the precondition is met. If a related record the condition needs does not exist, the precondition is not met.

Rule fields

  • Severity – Error blocks the approval. With Warning the approver can confirm and approve anyway; this is recorded in the audit log.
  • Message – what the approver reads when the precondition is not met, as an instruction in your own words (for example: Please enter the cost center, accounting needs it.). Leave it empty and the app generates the message in the approver's language from the condition that failed, for example Fill in "Cost Center". or "Cost Center" must be empty. The field is named as the page shows it.
  • Message Translations – a message of its own per language code. Approvers with that language read it instead of the rule's message.

Header or lines

Whether a precondition concerns the document header or every line follows from its condition: if it checks a field of a line table (for example Purchase Line), each line is checked on its own, and the message names the line. The Record Match Type field is not offered for preconditions.

Checks when the template is activated

The template cannot be activated when

  • the Error stage has preconditions (the action is disabled there): The Error stage … has preconditions, but nothing is approved there.
  • a precondition has no condition: Precondition … of stage … has no condition and would always be met.
  • a stage with approval mode Related Only has a precondition on the header – nobody can change the header or reject a header approval there.

If Allow Record Edit is switched off on the stage, or external approvers approve it, the app points this out when you open the preconditions: the approvers cannot add missing details themselves and can only reject the document so that somebody else completes it.

What is checked when approving

Each approval checks what it stands for – so no line blocks an approver who may not change it:

ApprovalChecked
Header approvalthe document header and the lines that have no approval of their own at this stage
Line approval (related approval)its line
the approval that completes the stageall preconditions of the stage

The "Approval not possible yet" dialog

When you approve and a precondition is not met, the dialog Approval not possible yet - stage … (… open) opens before anything is approved. This applies to Approve on the document and in Requests to Approve, to Approve Line(s) in the document lines and to the Related Approvals FactBox. For each precondition it shows Status (Met, Missing or Warning), Precondition, Message, Line, Field and Current Value.

{add screenshot of Approval not possible yet here}

  • Go to Field – opens the record at the field so you can fill it in. Close it to come back to the dialog. Only when you can change the document at this stage; otherwise the dialog says: You cannot change these details at this stage. Reject the approval so that they are added.
  • Check Again – checks once more. When the preconditions are met now, the approval goes ahead without a further click.
  • Reject... – rejects the approval. The open points are proposed as the reason (the first point and "(+n more)"; the full list is in the audit log). Only when you are processing a single approval.
  • Approve Anyway – only when nothing but warnings is open. Who confirmed which warning is recorded in the audit log.

Where no dialog is possible, the approval ends with the message The approval is not possible yet. Stage … requires: … and the action Show problems, which opens the list of preconditions. There is no way to override a precondition of severity Error – not for administrators either.

Approve All

Approve All skips approvals with an unmet Error precondition and reports them at the end: … approval request(s) were approved. … remain open, … of them because their preconditions are not met: …. Open warnings are confirmed once, up front, for all of them.

The "Approval Preconditions" FactBox

The FactBox appears on the document pages with Advanced Workflow integration, in Requests to Approve and on the AWF Workflow Instance card. It is visible while the workflow is at a stage with preconditions.

  • At the top it says Stage … · n of m met, below it lists each precondition with status, message, field, line and current value. A met precondition says what holds ("Payment Reference" is filled in.); a message of your own is shown only while the precondition is open.
  • The check runs in the background. The result appears without reloading the page; meanwhile it says Checking the preconditions....
  • After a change the FactBox checks again: for a header field once the change is saved, for a line once you leave the line – that is when Business Central saves it. Business Central's own Document Check behaves the same way.
  • Refresh checks again right away, Show All opens the stage's preconditions in a list. Outside the document (in Requests to Approve, for example), choosing the message takes you to the field.
  • When your approval still needs something, the document shows the notification Your approval still needs 2 details. Approving is only possible once they are added. once, with the action Show.
  • While the rejection group reviews a document after a header rejection, the FactBox shows the preconditions of the stage that rejected it.

{add screenshot of Approval Preconditions FactBox here}

Automatic approvals, external approvers and deleted lines

  • Automatic approval by rule: if the preconditions are not met, the automatic approval is suspended and the stage goes to its normal assignment. The audit log records Automatic approval by rule … suspended - the preconditions of stage … are not met: …
  • If a stage would be completed by rules, or after lines were deleted, without its preconditions being met, the workflow moves to the Error stage. Complete the data, then move the workflow back to the stage with Change Stage, or cancel it.
  • External approvers: an approval from outside Business Central does not count while an Error precondition is open. The reason is shown on the external approval entry and in the audit log.
  • Warnings do not hold up paths without a dialog (automatic and external approvals); they are logged.

Copying, exporting, importing

Copy a workflow, Export a template and Import / overwrite a template take the stages' preconditions along – with their conditions and the message translations.

For developers

Add checks of your own through the integration event OnAfterCheckPreconditions of codeunit DXP AWF Precondition Mgmt.. It is raised on every path – dialog, the engine's binding check, external and rule-based approvals. A result marked Partner Check with severity Error that is not met blocks the approval exactly like a precondition rule.

  • Define steps
  • Step rules: how does the workflow move to the next step?
  • Related approvals
  • Module: Rejection Handling
  • Module: Monitoring & Administration