# Validation Checks and Assistance Reasons

This page describes when Workist completes a document without assistance, which checks send a document to assistance, and which reasons Analytics shows for it. You switch the selectable checks on in the channel under [Document → Validation](/en/docs/channel-configuration/document-processing/document.md#step-6--validation).

## When is a document automated?

Workist only completes a document automatically and hands it to your target system if **all** of the following conditions are met. If one of them is not met, the document goes to assistance.

1. **Automation enabled** is switched on in the *Automation* block of the [Document](/en/docs/channel-configuration/document-processing/document.md#step-2--automation) page.
2. **Every header field** reaches the **Header data confidence threshold (%)**, and **every line item field in every line item** reaches the **Position lines confidence threshold (%)**. Workist checks each field on its own (confidence ≥ threshold); there is no average.
   - **Required** fields must be filled and reach the threshold.
   - **Optional** fields may be empty. If they contain a value, that value must reach the threshold too.
   - For fields with **Field should not block automation when below threshold**, Workist does not check the confidence. A required field must still be filled.
3. The document has at least one line item if at least one line item field is required.
4. **No validation check has failed**, neither a blocking nor a non-blocking one.
5. With order or offer matching active, no compared field deviates from the master data (see [Matching](/en/docs/channel-configuration/document-processing/matching.md)).
6. The document contains no sub-items. Sub-items only come from structural line item operations of [agentic line item extraction](/en/docs/channel-configuration/document-processing/agentic-extraction.md#specifics-of-line-item-extraction).

:::note Thresholds without a saved value
If no threshold is saved for a channel, **100 %** applies. Then a document is only automated if every checked field is fully certain. There is no threshold per field.
:::

### Blocking and non-blocking

Every failed check prevents automation, including a non-blocking one. The difference only shows in assistance:

- **Non-blocking:** the check is a hint. Users can complete the document without changing anything.
- **Blocking:** the document can only be completed once the affected value is corrected.

### What is needed to complete a document in assistance

In assistance, confidence no longer matters. A document can be completed as soon as

- all required fields are filled and valid,
- no blocking check fails any more,
- every deviating field from order or offer matching is corrected or confirmed with **Accept deviation**.

Some checks run again when users change an affected field (e.g. min quantity, article status, unit price, document number). The hint then disappears as soon as the value fits.

## Checks

The checks fall into three groups:

- **Selectable checks** are switched on or off under *Document → Validation → Validation checks*. Which ones are offered depends on the channel's document type.
- **Always-on checks** run for every document of the respective type. You control their behaviour through field options or keywords.
- **Automatic checks** come from field options, master data or other features of the channel.

The column *Shown at* tells you where the Workbench shows the hint in assistance.

### Selectable checks

<!-- generated by .claude/tasks/docs-audit/scripts/validation_checks_table.py (en) -->
| Check | Document types | Fails when … | Shown at | Blocking |
| --- | --- | --- | --- | --- |
| **Total amount** | Order, Invoice, Order confirmation, Delivery note | The net total differs by more than 0.10 from the sum of the line totals. If the total or all line totals are missing, nothing is checked. | Total amount (net) | No |
| **Line item sum** | Order, Order confirmation, Delivery note | Quantity × unit price differs from the line total (tolerance 1 cent or 0.25 %). Discounts are not taken into account. The quantity's confidence drops to 0. | Quantity of the line item | No |
| **Position number** | Order, Order confirmation, Delivery note | The range of position numbers does not match the number of recognized line items (e.g. positions 1–5 but only 4 recognized). Steps such as 10, 20, 30 are recognized. | Document | No |
| **Forgotten line items** | all | A page has more than two line-item-like values (article number, quantity, price …) outside the recognized line items. On by default for new channels. | Document | No |
| **Incomplete line items** | all | Article number, quantity or position number is present on only some of the line items. With a single line item: such values appear on the page outside that line item. | Document | No |
| **Max quantity** | Order, RFQ | A quantity is above the **Max value** of the line item field *Quantity* (default 999). The quantity's confidence drops to 30 %. | Quantity | No |
| **Min quantity** | Order, RFQ | A quantity is below the minimum or not a multiple of the pack size stored in the article's extra data. See [Min quantity rules](#min-quantity-rules). | Quantity or converted quantity | Per rule (default: yes) |
| **Remove bulk order summary** | Order | Workist removes the last line items if they are a summary (for every article, the last quantity is the sum of the previous ones). If Workist finds no such summary, the check fails, also on ordinary orders. | Document | No |
| **Repeated positions (e.g. appended summary or order confirmation)** | Order, RFQ | The last line items repeat earlier ones (same article number, article number 2 and quantity), e.g. from an appended summary or order confirmation. | Article number of the repeated line items | No |
| **Customer internal note** | all | The recognized customer or supplier has an internal note (`internal_note`) in the master data. The document text is not evaluated. | Document | No |
| **ERP Lock** | Order | The order is already marked as locked for downstream processing during processing. Only a customer-specific customization sets this mark. | Document | No |
| **Multiple sales organizations** | Order | The article of a line item has more than one sales organisation in the master data. A user picks the right one. | Sales organisation of the line item | No |
| **Thousand separator in quantities** | all | Quantity and prices use different separators, and quantity × 1,000 or quantity ÷ 1,000 matches total price ÷ unit price. A notation such as `1.000` on its own does not trigger the check. On by default for new channels. | Quantity | No |
| **Matching article descriptions (experimental)** | Order, RFQ | A language model rates whether the article description from the document and the one from the master data mean the same article. Below 50 % likelihood the check fails. | Article description | No |
| **Article status** | Order, RFQ | The matched article has a status in the master data (`article_status`) that is listed in an article status rule. See [Article status rules](#article-status-rules). | Article number | Per rule (default: yes) |
| **Offer matching** | Order | The order references a quote number, and values deviate from the quote, the quote number is unknown, or the order has fewer line items than the quote. See [Matching](/en/docs/channel-configuration/document-processing/matching.md). | Deviating fields | Until corrected or accepted |
| **Open Offer Check (only if Offer matching is enabled)** | Order | The order contains no quote number, but the customer has quotes in the [quote master data](/en/docs/master-data/quotes.md). | Quote number | No |
| **Unique document number** | all | The same channel has a document from the last 30 days with the same document number and the same customer or supplier number. Discarded, rejected and deleted documents do not count. If either number is missing, nothing is checked. | Document number | No |
| **Unit price / gross price mismatch check** | Order | The unit price of a line item is not exactly the article's price from the master data (`gross_price`), or the article has no price there. | Unit price | Yes |
| **Order matching** | Invoice, Order confirmation | Values deviate from the order in the order data, or the order number is unknown there. See [Matching](/en/docs/channel-configuration/document-processing/matching.md). | Deviating fields | Until corrected or accepted |
| **Order matching: Partial confirmations** | Order confirmation | Not a check of its own: allows order confirmations with fewer line items than the order. Without this option, order matching fails in that case. | – | – |

:::warning Remove bulk order summary
This check fails for every order that does **not** end with a summary. Only switch it on for channels whose orders always contain such a summary.
:::

:::tip Taking the unit price from the catalog
If the option **Allow overriding unit price with catalog price (via button)** is active on the line item field *Unit price*, users take over the price from the master data with the **Use catalog price** button when the *Unit price / gross price mismatch check* fails.
:::

### Always-on checks

| Check | Document types | Fails when … | Shown at | Blocking |
| --- | --- | --- | --- | --- |
| **Keywords to assistance** | all | A term from **Keywords to assistance** appears in the document or in the email body. | Document | No |
| Field length | all | A value is longer than the field's **Max field length**. If **Block automation when max field length is exceeded** is off, Workist shortens the value; the hint remains. | Affected field | Per field |
| **Order date** | Order | A delivery date (header or line item) is before the order date. Only if the order date and a delivery date field are configured; switched off by **Allow past delivery date** on the header field delivery date. | Delivery date | No |
| Customer from quote | Order | Only with offer matching: the quote belongs to a different customer than the recognized one. Workist took the customer from the quote; a user confirms which one is right. | Customer | No |

Workist compares keywords word by word, ignoring case and punctuation. Terms made of several words must appear consecutively in that order.

### Automatic checks

| Check | Document types | Fails when … | Shown at | Blocking |
| --- | --- | --- | --- | --- |
| **Assigned user not found** | all | [User assignment](/en/docs/channel-configuration/document-processing/document.md#step-3--user-assignment) is on, but the responsible person from the master data (or the default email) is not an active Workbench user. | Document | No |
| Decimal quantity | all | A quantity has decimals although **Allow decimal quantities** is off on the line item field *Quantity*. | Quantity | Yes |
| Zero quantity | all | A quantity is 0 although **Allow zero quantities** is off on the line item field *Quantity* (default: on; not available for RFQs), or unit conversion rounded a positive quantity to 0 (always). | Quantity | Yes |
| VAT ID | Order, RFQ | Only if the header field VAT ID is configured and the customer is from an EU country other than Germany: there is no VAT ID on the document or in the customer master data, the format is invalid, or the online check does not confirm number, name and address. The field's confidence drops to 0. | VAT ID | No |
| Number in matching data | Order, Invoice, Order confirmation | Only with order or offer matching: the number is not in the matching data. | Order or quote number | No |
| Line item count (quote) | Order | Only with offer matching: the order has fewer line items than the quote. | Document | No |
| Line item count (order) | Invoice, Order confirmation | Only with order matching: the number of line items differs from the order (rules in [Matching](/en/docs/channel-configuration/document-processing/matching.md#number-of-line-items)). | Document | No |
| Ambiguous line items | Order confirmation | Only with order matching: two or more line items are identical in all matched fields and cannot be assigned to an order line unambiguously. | Document | No |
| Agentic extraction failed | all | An [agentic configuration](/en/docs/channel-configuration/document-processing/agentic-extraction.md) could not run for technical reasons. The values of the standard extraction stay; their confidence drops to 0. The hint alone does not prevent automation. | Document | No |
| Knowledge file too large | all | A knowledge file of an agentic configuration is too large (over 200,000 tokens); the configuration does not run. Same effect as above. | Document | No |

### Min quantity rules

If the **Min quantity** check is on, the rule editor **Min quantity rules** appears in the *Validation* block. Each rule compares the quantity of every line item with a value from the extra data (`extra_data`) of the matched article in the [article master data](/en/docs/master-data/articles.md).

| Setting | Meaning |
| --- | --- |
| **Extra data field** | Required. Name of the field in the article's extra data that holds the value, e.g. `min_quantity`. |
| **Check type** | **Minimum**: the quantity must be at least the value. **Multiple**: the quantity must be a whole multiple of the value (e.g. a pack size); the value is then also the minimum. |
| **Quantity to check** | **Quantity** (quantity from the document) or **Converted quantity** (quantity after unit conversion). |
| **Number format in master data** | How the value is written in the master data: **English (1,000.5)** (default; `10.500` is 10.5) or **German (1.000,5)** (`10.500` is 10,500). |
| **Blocking** | Default: on. A quantity below the value must be corrected before completing. Off: only a hint. |
| **Article list (lookup definition ID)** | Optional. Reads the value from this article list instead of the matched article. A customer-specific entry takes precedence over the general one. |

Workist checks all rules. If a line item violates several rules, the Workbench shows the first one in the editor's order. Articles without a value in the configured field, with the value 0 or with an unreadable value are not checked. The hint appears at the *Quantity* field, e.g. “Quantity 5 is below the minimum order quantity 10 for article 4711.”

### Article status rules

If the **Article status** check is on, the rule editor **Article status rules** appears in the *Validation* block. It is based on the `article_status` column of the [article master data](/en/docs/master-data/articles.md), e.g. “blocked”, “discontinued” or “dangerous goods”.

| Setting | Meaning |
| --- | --- |
| **Article statuses** | Required. One or more statuses, press Tab or Enter after each. Case does not matter. |
| **Blocking** | Default: on. The article must be replaced before completing. Off: only a hint. |

Workist evaluates the rules in order; the first rule that contains the article's status applies. This way you can, for example, make “blocked” blocking and “phase-out” a hint only. Articles without a status, or with a status no rule lists, are not checked. The hint appears at the article number of the line item.

## Assistance reasons in Analytics

For every document that goes to assistance, Workist stores the reasons. [Analytics](/en/docs/administration/analytics.md) shows the most frequent ones under **Top 5 Assistance Reasons**. A document can have several reasons.

| Reason in Analytics | Meaning |
| --- | --- |
| “Invalid field …” | A required field (or subfield) is empty, or a blocking check on this field failed. |
| “Unconfident field …” | The field's confidence is below the threshold, for a required field or for an optional field that has a value. |
| “Validation check … failed” | A validation check failed, blocking or not. The name of the check is shown. |
| “No line items” | No line item was recognized although at least one line item field is required. |
| “… deviates from the order” | A matched field deviates from the order or quote data (see [Matching](/en/docs/channel-configuration/document-processing/matching.md)). |
| Sub-items present | The document contains sub-items. They only come from structural line item operations of agentic line item extraction. Such documents are never completed automatically. |

:::tip Tuning with the reasons
- Many **unconfident fields** of the same kind: check whether the field really is required, whether the master data contains the value, or whether **Field should not block automation when below threshold** fits.
- Many **failed validation checks** with the same name: check whether the channel needs that check. Non-blocking checks also prevent automation.
:::

## Frequently Asked Questions

**All fields were certain, but the document still went to assistance. Why?**
Usually a non-blocking check failed, e.g. *Forgotten line items* or *Unique document number*. The hint is shown at the top of the document or at the affected field. A filled optional field with low confidence also prevents automation.

**Can I use a check as a hint only, without stopping automation?**
No. Every failed check sends the document to assistance. “Non-blocking” only means that users can complete the document without changes.

**Is there a confidence threshold per field?**
No. There is one threshold for all header fields and one for all line item fields. Per field, you can only switch the confidence check off entirely (**Field should not block automation when below threshold**).