Validation error highlighting

When an RPA flow processes a document, the flow can detect data quality issues such as mismatched totals or missing required fields. The flow identifies the affected fields and assigns validation errors to those fields.

The Review Center user interface highlights the fields that contain validation errors. This highlighting enables reviewers to quickly identify fields that require attention, without reviewing all document values.

Validation processing is performed entirely within the RPA flow. The application does not evaluate or enforce business rules. The RPA flow executes validation logic and submits validation results to the Review Center through the Document Management APIs.

Validation errors are informational and do not block document processing. Reviewers can modify and submit documents even when validation errors are present.

How validation works

The validation process runs within the RPA flow and involves these steps:

The RPA flow processes a document. This processing can include OCR extraction, ERP validation, or business rule evaluation.
The RPA flow detects rule violations. For example:
- The Total field does not equal the sum of Subtotal and Tax
- The product of quantity and unit price does not match the line amount.
The RPA flow invokes the Document Management API using the POST, PUT, or PATCH method. The request payload can include an optional validation_errors array.
The application stores the validation errors with the document data.
The application highlights the affected fields when a reviewer opens the document in the Review Center user interface. The interface displays error (red) or warning (amber) indicators along with the associated message.
The reviewer corrects the data and submits the document. After resubmission and reprocessing, the application clears the validation errors.

Types of validation errors

You can define three types of validation errors based on the location of the issue in the document:

Header-level field error
Highlights a specific document field in the header. Use this error type when a top-level field value is incorrect or inconsistent. Specify the entity_key to identify the affected field.
Table column error
Highlights an entire column in a table. Use this error type when all values in a column require review. Specify the table_name and column_key to identify the affected column.
Table cell error
Highlights a specific cell in a table. Use this error type when a single row in a column contains an issue. Specify the table_name, column_key, and row_index (zero-based) to identify the affected cell.

Severity levels

Each validation error can include a severity level that determines how the error is displayed in the user interface:

Error (default)
Displayed with a red highlight. This severity indicates a confirmed issue that must be corrected before submitting the document to the ERP application.
Warning
Displayed with an amber highlight. This severity indicates a potential issue that requires review but is not necessarily incorrect.
Default behavior
The application assigns the severity as error if the request payload does not specify a severity level.

Validation errors schema

The validation_errors array is an optional field in the Document Management API request payload. Each entry in the array represents a single validation error.

You can include the validation_errors array in POST, PUT, and PATCH requests to the Document APIs. Sending an empty array clears all existing validation errors associated with the document.

Each validation error entry supports these properties:

entity_key (String, conditional)
Specifies the key of the document entity field for header-level errors. This property is required when flagging a header field.
table_name (String, conditional)
Specifies the name of the table for table-level errors. This property must be used together with column_key when flagging a table column or table cell
column_key (String, conditional)
Specifies the column key within the table. This property must be used together with table_name.
row_index (Integer, optional)
Specifies the zero-based row index for cell-level errors. When this property is provided, the application highlights only the specified cell. When this property is not provided, the application highlights the entire column.
message (String, required)
Specifies the error message displayed to the reviewer near the highlighted field. The message must provide a clear and human-readable description of the issue.
severity (String, optional)
Specifies the severity level of the validation error. Supported values are error (red, default) and warning (amber).

POST /api/v1/rpa/exception/usecasetypes: Creates a new RPA use case type configuration.

Note: Each validation error entry must include either the entity_key or the combination of table_name and column_key. Do not specify entity_key and table_name in the same validation error entry.

Example: Document payload with validation errors

This example illustrates a document submitted to the Review Center with three validation errors. The validation errors include a header-level error, a table column error, and a table cell error.

POST /api/v1/rpa/exception/usecasetypes/{id}/documents

Content-Type: application/json

{

"document_name": "Invoice_12345",

"category_key": "NEEDSVERIFICATION",

"document_entities": [

{ "key": "SUBTOTAL", "value": "100.00" },

{ "key": "TAX", "value": "10.00" },

{ "key": "TOTAL", "value": "120.00" }

],

"table_data": [

{

"name": "valid_lines",

"rows": [

{

"row": [

{ "key": "ITEMCODE", "value": "12345" },

{ "key": "QUANTITY", "value": "10" },

{ "key": "UNITPRICE", "value": "5.00" },

{ "key": "AMOUNT", "value": "60.00" }

]

}

]

}

],

"validation_errors": [

{

"entity_key": "TOTAL",

"message": "Total (120.00) does not equal Subtotal + Tax (110.00)",

"severity": "error"

},

{

"table_name": "valid_lines",

"column_key": "AMOUNT",

"message": "Line amounts do not match Qty x Unit Price",

"severity": "warning"

},

{

"table_name": "valid_lines",

"column_key": "AMOUNT",

"row_index": 0,

"message": "Row 1: Amount (60.00) does not match 10 x 5.00 = 50.00",

"severity": "error"

}

]

}

In this example:

The application highlights the TOTAL header field in red. The value does not match the sum of the SUBTOTAL and TAX fields.
The application highlights the entire AMOUNT column in the valid_lines table with an amber indicator. The column values require review.
The application highlights the first row of the AMOUNT column in red. The value in that row does not match the expected calculation.

Important considerations

Review these considerations to understand the behavior and usage of the validation_errors field in the Review Center workflow:

Optional validation_errors field
The validation_errors array is optional. If not included in the API request, no validation highlights are displayed, and the existing application behavior remains unchanged.
Clearing validation errors
Sending an empty array ("validation_errors": []) removes all previously stored validation errors from the document.
Persistence of validation errors
Validation errors continues to be associated with the document until the document is resubmitted and reprocessed by the RPA flow.Modifying a field in the Review Center UI does not automatically remove the corresponding validation error.
Responsibility for validation logic
The RPA flow is responsible for validating document data. The Review Center does not execute or enforce business rules. However, only validation results returned by the RPA flow are displayed.
Error message guidelines
Error messages must be written in clear, human-readable language as the error messages are displayed directly in the Review Center UI. Use the Translations API to provide localized versions of error messages, if required.
Retrieving validation errors
The validation_errors field is included in the response of the GET Document API. This allows RPA flows to retrieve and evaluate the current validation errors associated with a document.