Record audit and errors

Every attempt to write a record — successful or not — produces a record audit entry. This is how Grunddata tells you what happened, and it is the same mechanism behind the error messages you see in the web app, the Excel plugin and the Google Sheets add-on.

What an audit entry contains

Field	Description
Status	success or error
Message	A human-readable explanation
Operation	insert, update or delete
Table	Which table the attempt was against
source_id / version	Which record and which revision
Code / Name	So you can identify the row without decoding a UUID
Data	The values that were attempted
Attempted by / at	Who tried, and when

Rejected attempts are recorded too

An attempt that fails validation is not written as a record, but it is recorded as an audit entry. You can see that someone tried to enter an invalid value, what they tried, and why it was refused.

What happens on failure

A rejected record is never partially saved

Grunddata does not truncate an over-long string, coerce a bad number, or drop an unresolvable reference. The whole record is refused with a message.

Per surface:

• Web app — the record dialog stays open and shows the message inline. Fix and save again.
• Excel plugin / Google Sheets — the upload reports back which rows failed and why. Your valid rows in the same upload are still processed; the failed ones are not.
• API — the response contains a record_audits array with an entry per record.

Common errors and how to fix them

“Required” / missing value

An attribute marked required had no value.

Tip

Remember that required only applies going forward. If old rows have blanks, they were created before the rule existed — they will only be rejected once you edit them. Clean them up in one deliberate pass rather than being surprised row by row.

Value not found in domain table

The value in a domain attribute could not be resolved to a record in the target table.

Usual causes:

1. The lookup value does not exist yet. Add it to the domain table first.
2. A typo, or trailing whitespace in a spreadsheet cell.
3. The value was typed by hand instead of chosen from the picker.
4. The domain table record was deleted.

Load lookups before the data that references them

When bootstrapping a new domain, always populate the domain tables first. A reference can only resolve if the target record already exists.

Uniqueness violation

Another record already holds this value on an attribute marked unique.

Caution

Check whether the existing record is soft-deleted. A value that “looks free” may still be occupied by history.

Max length exceeded

The string is longer than the attribute’s max length. Either shorten the value or increase the max length on the attribute.

Validation rule failed

A validation rejected the value — a pattern, a range, a list membership, or a table-level comparison between two attributes.

The message names the rule that failed. If the message is cryptic, the rule probably needs a clearer description on the attribute.

Wrong datatype

Text in a numeric column, or a date in a format that could not be parsed.

Excel date formatting is the usual culprit

If dates fail to upload, check the cell format in the sheet. Grunddata expects yyyy-MM-dd for date and yyyy-MM-dd HH:mm for datetime. Formatting the column as text in the expected format is the most reliable fix.

Validating a whole table at once

Rather than discovering problems one upload at a time, you can run the current validation rules against every record in a table. The result reports:

• The total number of records checked.
• How many are valid.
• How many are invalid.
• A sample of failures, each with the record’s Code, Name and the specific messages.

Run this after tightening a rule

Adding or changing a validation is exactly when existing data goes out of compliance. Run the check straight afterwards so you find the 40 bad rows before your users do.

A workflow for fixing bad data in bulk

1. Run the table validation check and note the failing records.

2. Download the table into Excel or Google Sheets.

3. Correct the failing rows. Leave the hidden identifier columns untouched so the rows are recognised as updates, not new records.

4. Upload with a commit message that says what you fixed and why, for example Correct 40 accounts failing the new account_number pattern.

5. Re-run the validation check to confirm you are clean.