ChangeLog Message Types

This document covers the three message types that expose Business Central's Change Log for field-level audit browsing, restoration, and coverage checks.

Overview

Prerequisite: The BC Change Log feature must be configured for the relevant tables and fields (Administration → Change Log Setup → Tables). Without Change Log entries there is no history to browse or restore.

Typical workflow:

1. Call ChangeLog.Field.Enabled to confirm a field is tracked.
2. Call ChangeLog.Field.History to browse modifications and pick the target entryNo.
3. Call ChangeLog.Field.Restore with that entryNo to write the value back.

ChangeLog.Field.History

Direction: Outbound Object IDs: Codeunit 65415 (ChangeLog Field History Impl), Codeunit 65416 (ChangeLog Field History Help)

Purpose

Returns the current live value of a field together with all Change Log Entry records for that field on a specific record, ordered from the most recent to the oldest.

The response always starts with a synthetic Current entry at entryNo = 0 showing the live field value. This makes it easy for callers to compare the current state against the historical entries without a separate lookup.

Request Format

{
  "specversion": "1.0",
  "type": "ChangeLog.Field.History",
  "source": "MyApp v1.0",
  "data": "{\"tableName\":\"Customer\",\"recordSystemId\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"fieldNo\":2}"
}

Input Parameters

*If recordSystemId is missing from the data payload, the CloudEvents subject attribute is used as a GUID fallback.

Response Format

{
  "status": "Success",
  "tableNo": 18,
  "tableName": "Customer",
  "recordSystemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fieldNo": 2,
  "fieldName": "Name",
  "fieldType": "Text",
  "history": [
    {
      "entryNo": 0,
      "dateAndTime": "2026-03-28T14:22:00.000Z",
      "typeOfChange": "Current",
      "oldValue": "",
      "newValue": "Contoso Ltd.",
      "userId": "ADMIN"
    },
    {
      "entryNo": 56789,
      "dateAndTime": "2026-03-10T09:00:00.000Z",
      "typeOfChange": "Modification",
      "oldValue": "Contoso Inc.",
      "newValue": "Contoso Ltd.",
      "userId": "ADMIN"
    },
    {
      "entryNo": 45001,
      "dateAndTime": "2025-11-15T11:30:00.000Z",
      "typeOfChange": "Modification",
      "oldValue": "Contoso",
      "newValue": "Contoso Inc.",
      "userId": "JANE"
    }
  ],
  "totalCount": 3
}

Top-Level Response Fields

History Entry Fields

Error Cases

ChangeLog.Field.Restore

Direction: Inbound (Write) Object IDs: Codeunit 65412 (ChangeLog Field Restore Impl), Codeunit 65413 (ChangeLog Field Restore Help), Codeunit 65414 (ChangeLog Field Restore Process)

Purpose

Writes a previous field value back to the live Business Central record. The value is taken from the Old Value of the chosen Change Log entry. The restore is performed using Validate() + Modify(true) so all field-level business logic triggers fire normally.

Supports two modes:

Mode 1: By Entry Number

{
  "specversion": "1.0",
  "type": "ChangeLog.Field.Restore",
  "source": "MyApp v1.0",
  "data": "{\"entryNo\":56789}"
}

Mode 2: By Point-in-Time

{
  "specversion": "1.0",
  "type": "ChangeLog.Field.Restore",
  "source": "MyApp v1.0",
  "data": "{\"tableName\":\"Customer\",\"recordSystemId\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"fieldNo\":2,\"restoreToDateTime\":\"2026-02-10T09:15:00Z\"}"
}

Response Format

{
  "status": "Success",
  "tableNo": 18,
  "tableName": "Customer",
  "recordSystemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "fieldNo": 2,
  "fieldName": "Name",
  "previousValue": "Contoso Ltd.",
  "restoredValue": "Contoso Inc.",
  "fromEntryNo": 56789,
  "entryDateTime": "2026-02-10T09:15:00.000Z"
}

Safety Guards

The following conditions must all be satisfied or the restore is rejected:

• Entry type must be Modification — Insertion and Deletion entries cannot be restored
• Target record must still exist
• Field must be a writable (Normal class) field — FlowFields and FlowFilters are rejected
• Field must not be write-restricted (Cloud Events Field Access)
• Table must not be restricted from write operations (Cloud Events Setup)
• Field must be allowed by the ChangeLog Write Guard setting in Cloud Events Setup
• Restore value must be convertible to the field data type
• Current field value must differ from the restore value (identical values return an error, no write occurs)

Error Cases

ChangeLog.Field.Enabled

Direction: Outbound Object IDs: Codeunit 65362 (ChangeLog FieldEnabled Impl), Codeunit 65363 (ChangeLog FieldEnabled Help)

Purpose

Checks whether:

1. The BC Change Log feature is globally activated.
2. The ChangeLog Write Guard is in an enforcing mode (Blocked or Via force).
3. The specified field is covered by Change Log Setup for Modification tracking.

Useful before writing via Data.Records.Set when the ChangeLog Write Guard is active, or before calling ChangeLog.Field.Restore to confirm the field has history.

Request Format

{
  "specversion": "1.0",
  "type": "ChangeLog.Field.Enabled",
  "source": "MyApp v1.0",
  "data": "{\"tableName\":\"Customer\",\"fieldNo\":2}"
}

Response Format

{
  "status": "Success",
  "changeLogEnabled": true,
  "changelogWriteGuardEnabled": true,
  "tableNo": 18,
  "tableName": "Customer",
  "fieldNo": 2,
  "fieldName": "Name",
  "fieldCovered": true,
  "fieldWriteGuardBypassed": false
}

Error Cases

ChangeLog.Records.Delta

Direction: Outbound Object IDs: Codeunit 65555 (ChangeLog Records Delta Impl), Codeunit 65556 (ChangeLog Records Delta Help)

Purpose

Returns the distinct SystemIds of records in a single table that were Inserted or Modified within a date/time range. Optionally narrows the search to a set of tracked fields. Use this as the source for an incremental sync: pull the changed ids, then fetch each record's full payload via Data.Records.Get and per-field history via ChangeLog.Field.History.

Deletions are not returned — use Deleted.RecordIds.Get for deleted records.

Request Format

{
  "specversion": "1.0",
  "type": "ChangeLog.Records.Delta",
  "source": "MyApp v1.0",
  "subject": "Customer",
  "data": "{\"tableName\":\"Customer\",\"fieldNumbers\":[2,3],\"startDateTime\":\"2026-03-01T00:00:00Z\",\"endDateTime\":\"2026-03-31T23:59:59Z\"}"
}

Input Parameters

Response Format

{
  "status": "Success",
  "tableNo": 18,
  "tableName": "Customer",
  "fieldNumbers": [2, 3],
  "startDateTime": "2026-03-01T00:00:00.000Z",
  "endDateTime": "2026-03-31T23:59:59.000Z",
  "totalCount": 42,
  "systemIds": [
    "a1b2c3d4-...",
    "e5f6a7b8-..."
  ]
}

Response Fields

Error Cases

Typical Workflow

1. Call ChangeLog.Records.Delta with the table, range and (optionally) the field set to track.
2. For each returned SystemId, call Data.Records.Get to fetch the current row.
3. For deeper audit, call ChangeLog.Field.History per field of interest.

ChangeLog Write Guard

The ChangeLog Write Guard is a field in Cloud Events Setup (field 17) that controls which fields Data.Records.Set may write to. It does not affect read operations.

Enabling the Guard

Changing to Blocked or Via force requires the BC Change Log to be active. The setup validation ensures this and returns an error otherwise.

Using force bypass (Via force mode only)

Include "force": true as a top-level key inside the data JSON alongside the data array:

{
  "specversion": "1.0",
  "type": "Data.Records.Set",
  "source": "MyApp v1.0",
  "subject": "Customer",
  "data": "{\"force\":true,\"data\":[{\"id\":\"...\",\"fields\":{\"Name\":\"Updated Name\"}}]}"
}

The caller must hold the CE Force Access permission set (PermissionSet 65303). Without it, force: true is ignored and the request is rejected in the same way as Blocked.

Checking field coverage before writing

To prevent rejected writes at runtime, call ChangeLog.Field.Enabled first:

{ "type": "ChangeLog.Field.Enabled", "data": "{\"tableName\":\"Customer\",\"fieldNo\":2}" }

If fieldCovered is false and the guard is Blocked or Via force, the write to that field will be rejected unless force: true is used (Via force mode only).

Related Documentation

• Data_Message_Types.md — Data.Records.Set request/response format and field naming
• Setup_Reference.md — Complete Cloud Events Setup field reference including ChangeLog Write Guard
• Field_Access_Restrictions.md — User-level field read/write restrictions

© Origo – Cloud Events Base Extension