Modules Record Management

Record Identity & Granularity

Each module lands in its own table, and each table has its own primary key column, following the pattern scv_<module>_id (e.g. scv_user_contact_preference_id for the Contact Preferences module).

This PK is what Cortex uses to decide whether an incoming row creates a new record or updates an existing one: rows whose PK already exists in the table are upserted (updated in place), while rows with a new PK are inserted as new entries.

Records can be deleted by populating the deleted_at timestamp field (soft delete).

Because of this, before onboarding a module you should evaluate what granularity its PK represents — i.e. what real-world entity one row/one PK is meant to correspond to (a single preference, a single ticket line, a single transaction, etc.). Getting this wrong has direct consequences:

• Too coarse (PK reused across what should be distinct events/records) — new occurrences will silently overwrite prior ones instead of being added as new history.
• Too fine (a new PK generated for what should be the same logical record, e.g. because it's derived from a timestamp) — you'll get duplicate records instead of updates to the same entry.

When preparing files for a module, confirm with Cortex what column(s) compose that module's PK and how it should be sourced from your system, so the upload granularity matches the intended one-row-per-entity semantics.

How to Delete Records

Every module table includes a deleted_at field. Records are soft-deleted — there's no separate delete operation; you delete a record the same way you upload one, by re-submitting its row with deleted_at populated.

To delete a record:

1. Include the row's PK (scv_<module>_id) so it matches the existing record — this is what tells Cortex which row to update rather than insert as new.
2. Populate deleted_at with a timestamp (yyyy-mm-dd hh:mm:ss).
3. Upload the file to the module's folder as usual.

Because deletes are matched by PK, the same granularity considerations apply: a PK that's too coarse can end up soft-deleting more than intended, and a PK that doesn't match any existing row will simply insert a new, already-deleted record rather than deleting anything.