The change history

Every creation, change and deletion on a journalised table writes entries into the BSPK_HISTORY table. This journal feeds the dev panel's undo/redo, tells content reconciliation "when and who", and lets you find and restore a deleted record. A daily task archives old entries.

What is journalised

The journal is written by the entity classes' ORDA events (save, drop). The component injects these events, between the /*** START BSPKENTITY ***/ and /*** END BSPKENTITY ***/ tags:

into the classes of the BSPK_* tables, always;
into the classes of your tables only if the vo_Param.vb_AddBSPKDataClass parameter is true (see Parameter files).

Never journalised: the BSPK_ERROR and BSPK_TASK_MANAGER tables, and the ID, uuidKey, createdOn, createdBy, modifiedOn, modifiedBy fields.

Taking one of your tables out of the journal: declare in its entity class, after the END BSPKENTITY tag (what precedes it is rewritten at each injection):

Function bspkIsHistorized->$vb : Boolean
	return False

Only the journal is switched off: timestamps and notifications to connected clients go on.

If you declare an event yourself (event validateSave…) in a journalised entity class, the component's one is disabled, and the journal with it. Use the bspkOnXxx extension points.

An entry

Field	Content
`codeAction`	`1CREATE`, `5UPDATE` or `9DELETE`
`recordInfos`	the record's table and primary key
`newValues`, `oldValues`	creation: every filled field; change: one entry per changed field (`fieldName`), old and new value; deletion: the whole record
`createdOn`, `createdBy`, `userUuid`	when, and who (the connected user)
`groupUuid`	every entry of one user action, for undo/redo
`infos.origin`	the origin: exchange import, Claude API, version update…

Looking at the history

In an ATL list, right-click the primary-key column → Search in history. The screen filters by period, table, field and value, with or without related records, and exports to CSV. A double-click on a key opens the record in the ATL.

Restoring: on a deletion row, when the record no longer exists, restoring recreates it from the entry. Related records are not restored, and the creation date and author become those of the restore.

When the period starts before the oldest entry still in the table, the search also reads the archives.

Archiving

The CRON_EXPORT_BSPK_HISTORY scheduled task runs every day at 03:05. It is recreated or repaired at every startup: every database archives. To keep more history, raise the retention; switching the task off would not survive a restart.

Entries older than the retention period are grouped by day.
Each day goes into a zip, <folder>/YYYY-MM-DDT.zip (an existing zip for that day is completed).
The archived entries are deleted from the table.

A prior check is made on content reconciliation's date memory: if it fails, nothing is archived and an alert mail goes out.

Parameter (`vo_Param` in `APP_PARAMETERS`)	Default
`vl_BspkHistoryRetentionDays`	30 days
`vt_BspkHistoryArchiveFolder`	`Logs/Archive` in the data folder

Both keys are added automatically if missing. When a server (or single-user) starts and the archive folder is not set, does not exist or is not writable, a dialog offers a folder next to the installation: Change… / Use this folder / Later ("Later" after 60 seconds). Keeping archives out of the data folder stops them from swelling every backup.

BSPK_HISTORY_ARCHIVE_SET($folder) changes the archive folder by code: it checks it can write there, saves the path and moves the existing archives into it.

BSPK_HISTORY_PURGE deletes without archiving: undo/redo has nothing left to replay. Keep it for a fresh start, for instance after moving from version 20 to version 21.

Good to know