Skip to main content
Last updated: 11 Mar 2025

Tracking when a content block changes

As outlined in how embedding works. When a block is updated, all the pages that use the block are simply represented for publishing, which updates the block’s value without creating a new edition.

This means that we need a way of showing an editor when the change to a content block has happened.

We do this by recording an Event in Publishing API when a change to a content block triggers a republication. This is done in the HostContentUpdateJob class.

There is also an Events endpoint in Publishing API, which allows us to get the events that have occurred for a given content ID. We can also filter by event type, allowing us to get a list of when HostContentUpdateJob events have been created for a given piece of content.

Where this is used

This is currently used in Whitehall and Mainstream Publisher to “weave” HostContentUpdateJob events into the timeline of a document

Whitehall

The timeline of a given document is handled in the Document::PaginatedTimeline class we first fetch events from the database, and weave any HostContentUpdateJob events that have come from the Publishing API into the current page by filtering for a time window between the newest and oldest database-level events.

Mainstream

Because Mainstream’s history is very much tied to editions, we first fetch all the events from the Publishing API, and add a helper method to check if a given event is for an edition.

Each event then has a transformer that duck types an event as an Action, these then get fetched in the Editions controller and sent to the edition_actions helper method where the relevant actions are weaved into the edition’s other actions and presented on the frontend.

Future plans

We know having two places for document / edition history is not ideal, and going forward, it would be better to have a single source of truth for this information (such as the Publishing API), but this is a bigger piece of work and beyond the current scope of the Content Modelling Team’s remit.