Merge pull request #1604 from bbc/rjmunro/error-message-customisation

feat: Status message customisation

Author: rjmunro

meteor/__mocks__/helpers/database.ts

@@ -127,6 +127,7 @@ export async function setupMockPeripheralDevice(
 		created: 1234,
 		status: {
 			statusCode: StatusCode.GOOD,
+			statusDetails: [],
 		},
 		lastSeen: 1234,
 		lastConnected: 1234,

meteor/server/__tests__/cronjobs.test.ts

@@ -510,6 +510,7 @@ describe('cronjobs', () => {
 				name: props.deviceName,
 				status: {
 					statusCode: StatusCode.GOOD,
+					statusDetails: [],
 				},
 				token: '',
 				...props,

meteor/server/api/__tests__/peripheralDevice.test.ts

@@ -203,7 +203,7 @@ describe('test peripheralDevice general API methods', () => {
 		})
 		await MeteorCall.peripheralDevice.setStatus(device._id, device.token, {
 			statusCode: StatusCode.WARNING_MINOR,
-			messages: ["Something's not right"],
+			statusDetails: [{ message: "Something's not right" }],
 		})
 		expect(((await PeripheralDevices.findOneAsync(device._id)) as PeripheralDevice).status).toMatchObject({
 			statusCode: StatusCode.WARNING_MINOR,
@@ -650,6 +650,7 @@ describe('test peripheralDevice general API methods', () => {
 				lastSeen: 0,
 				status: {
 					statusCode: StatusCode.GOOD,
+					statusDetails: [],
 				},
 				subType: '_process',
 				token: 'MockToken',

meteor/server/api/peripheralDevice.ts

@@ -2,7 +2,14 @@ import { Meteor } from 'meteor/meteor'
 import { check, Match } from '../lib/check'
 import _ from 'underscore'
 import { PeripheralDeviceType, PeripheralDevice } from '@sofie-automation/corelib/dist/dataModel/PeripheralDevice'
-import { PeripheralDeviceCommands, PeripheralDevices, Rundowns, Studios, UserActionsLog } from '../collections'
+import {
+	PeripheralDeviceCommands,
+	PeripheralDevices,
+	Rundowns,
+	Studios,
+	UserActionsLog,
+	Blueprints,
+} from '../collections'
 import { stringifyObjects, literal } from '@sofie-automation/corelib/dist/lib'
 import { protectString, unprotectString } from '@sofie-automation/corelib/dist/protectedString'
 import { getCurrentTime } from '../lib/lib'
@@ -37,6 +44,7 @@ import {
 	PeripheralDeviceInitOptions,
 	PeripheralDeviceStatusObject,
 	TimelineTriggerTimeResult,
+	DeviceStatusDetail,
 } from '@sofie-automation/shared-lib/dist/peripheralDevice/peripheralDeviceAPI'
 import { checkStudioExists } from '../optimizations'
 import {
@@ -65,8 +73,121 @@ import bodyParser from 'koa-bodyparser'
 import { assertConnectionHasOneOfPermissions } from '../security/auth'
 import { DBStudio } from '@sofie-automation/corelib/dist/dataModel/Studio'
 import { getRootSubpath } from '../lib'
+import { evalBlueprint } from './blueprints/cache'
+import { StudioBlueprintManifest } from '@sofie-automation/blueprints-integration'
+import { StatusMessageResolver } from '@sofie-automation/corelib'
+import { interpollateTranslation } from '@sofie-automation/corelib/dist/TranslatableMessage'
+import { Blueprint } from '@sofie-automation/corelib/dist/dataModel/Blueprint'
+import { StudioId } from '@sofie-automation/corelib/dist/dataModel/Ids'
 
 const apmNamespace = 'peripheralDevice'
+
+/**
+ * Resolve device status details using the Studio blueprint's deviceStatusMessages.
+ * This allows blueprints to customize status messages shown to operators.
+ *
+ * @param studioId - The studio ID to look up the blueprint
+ * @param deviceName - The peripheral device name (shorter than TSR's internal name)
+ * @param deviceId - The peripheral device ID
+ * @param statusDetails - Structured status details from TSR
+ * @param defaultMessages - The original messages from TSR (used as fallback)
+ */
+async function resolveDeviceStatusDetails(
+	studioId: StudioId,
+	deviceName: string,
+	deviceId: PeripheralDeviceId,
+	statusDetails: DeviceStatusDetail[],
+	defaultMessages: string[]
+): Promise<string[]> {
+	try {
+		// Get the studio and its blueprint
+		const studio = (await Studios.findOneAsync(studioId, {
+			projection: { blueprintId: 1 },
+		})) as Pick<DBStudio, 'blueprintId'> | undefined
+
+		if (!studio?.blueprintId) {
+			// No blueprint, return empty (caller will use original messages)
+			return []
+		}
+
+		// Get the blueprint code
+		const blueprint = (await Blueprints.findOneAsync(studio.blueprintId, {
+			projection: { _id: 1, name: 1, code: 1 },
+		})) as Pick<Blueprint, '_id' | 'name' | 'code'> | undefined
+
+		if (!blueprint) {
+			return []
+		}
+
+		// Evaluate the blueprint to get the manifest with deviceStatusMessages
+		const blueprintManifest = evalBlueprint(blueprint) as StudioBlueprintManifest
+
+		logger.debug(
+			`Blueprint ${blueprint._id} deviceStatusMessages keys: ${Object.keys(blueprintManifest.deviceStatusMessages ?? {}).join(', ')}`
+		)
+
+		if (!blueprintManifest.deviceStatusMessages) {
+			// Blueprint doesn't define any custom status messages
+			logger.debug(`Blueprint ${blueprint._id} has no deviceStatusMessages`)
+			return []
+		}
+
+		// Create resolver with the blueprint's status messages
+		const resolver = new StatusMessageResolver(
+			blueprint._id,
+			blueprintManifest.deviceStatusMessages,
+			undefined // No system error messages
+		)
+
+		// Resolve each status detail
+		const resolvedMessages: string[] = []
+		for (let i = 0; i < statusDetails.length; i++) {
+			const statusDetail = statusDetails[i]
+			// statusDetail.message is always pre-rendered by TSR; use it as fallback if no defaultMessages entry
+			const defaultMessage = defaultMessages[i] ?? statusDetail.message
+
+			if (!statusDetail.code) {
+				// No structured code - use the pre-rendered TSR message directly
+				resolvedMessages.push(defaultMessage)
+				continue
+			}
+
+			logger.debug(
+				`Resolving status code: ${statusDetail.code}, context: ${JSON.stringify(statusDetail.context)}`
+			)
+			const message = resolver.getDeviceStatusMessage(
+				statusDetail.code,
+				{
+					...statusDetail.context,
+					// Override with peripheral device info (TSR might have longer names)
+					deviceName,
+					deviceId: unprotectString(deviceId),
+				},
+				defaultMessage
+			)
+
+			if (message) {
+				// Interpolate the message template with context values
+				const interpolated = interpollateTranslation(message.key, message.args)
+				logger.debug(`Resolved message for ${statusDetail.code}: ${interpolated}`)
+				resolvedMessages.push(interpolated)
+				// Also mutate statusDetail.message so the UI can read from statusDetails[].message directly
+				statusDetail.message = interpolated
+			} else {
+				// Message suppressed by blueprint - clear the message so the UI doesn't show the raw TSR message
+				statusDetail.message = ''
+				logger.debug(`Message suppressed for ${statusDetail.code}`)
+			}
+		}
+
+		return resolvedMessages
+	} catch (e) {
+		// Log error but don't fail - fall back to original messages
+		logger.error(`Error resolving device status messages: ${e}`)
+		return []
+	}
+}
+
 export namespace ServerPeripheralDeviceAPI {
 	export async function initialize(
 		context: MethodContext,
@@ -141,6 +262,7 @@ export namespace ServerPeripheralDeviceAPI {
 				created: getCurrentTime(),
 				status: {
 					statusCode: StatusCode.UNKNOWN,
+					statusDetails: [],
 				},
 				connected: true,
 				connectionId: options.connectionId,
@@ -203,6 +325,37 @@ export namespace ServerPeripheralDeviceAPI {
 			throw new Meteor.Error(400, 'device status code is not known')
 		}
 
+		// Resolve status messages using Studio blueprint if structured status details are present
+		// Child devices (like casparcg0) don't have studioAndConfigId directly - get it from parent
+		let studioId = peripheralDevice.studioAndConfigId?.studioId
+		if (!studioId && peripheralDevice.parentDeviceId) {
+			const parentDevice = await PeripheralDevices.findOneAsync(peripheralDevice.parentDeviceId, {
+				projection: { studioAndConfigId: 1 },
+			})
+			studioId = parentDevice?.studioAndConfigId?.studioId
+		}
+
+		logger.info(
+			`Device ${deviceId} setStatus: statusDetails=${status.statusDetails?.length ?? 'undefined'}, messages=${status.messages?.length ?? 'undefined'}, studioId=${studioId ?? 'none'}`
+		)
+		if (status.statusDetails && status.statusDetails.length > 0) {
+			if (studioId) {
+				const resolvedMessages = await resolveDeviceStatusDetails(
+					studioId,
+					peripheralDevice.name,
+					peripheralDevice._id,
+					status.statusDetails,
+					status.messages ?? []
+				)
+				// Use blueprint-resolved messages if available, otherwise fall back to statusDetails messages
+				status.messages =
+					resolvedMessages.length > 0 ? resolvedMessages : status.statusDetails.map((d) => d.message)
+			} else {
+				// No studio context, derive messages directly from statusDetails
+				status.messages = status.statusDetails.map((d) => d.message)
+			}
+		}
+
 		// check if we have to update something:
 		if (!_.isEqual(status, peripheralDevice.status)) {
 			logger.info(

meteor/server/systemStatus/__tests__/systemStatus.test.ts

@@ -90,6 +90,7 @@ describe('systemStatus', () => {
 			$set: {
 				status: literal<PeripheralDeviceStatusObject>({
 					statusCode: StatusCode.WARNING_MAJOR,
+					statusDetails: [],
 					messages: [],
 				}),
 			},
@@ -116,6 +117,7 @@ describe('systemStatus', () => {
 			$set: {
 				status: literal<PeripheralDeviceStatusObject>({
 					statusCode: StatusCode.GOOD,
+					statusDetails: [],
 					messages: [],
 				}),
 			},

meteor/yarn.lock

@@ -2421,7 +2421,7 @@ __metadata:
   dependencies:
     "@mos-connection/model": "npm:^5.0.0-alpha.0"
     kairos-lib: "npm:^1.0.0"
-    timeline-state-resolver-types: "npm:10.0.0-nightly-main-20260429-110933-d01800ef9.0"
+    timeline-state-resolver-types: "npm:10.0.0-nightly-main-20260514-152958-5f6033589.0"
     tslib: "npm:^2.8.1"
     type-fest: "npm:^4.41.0"
   languageName: node
@@ -12415,13 +12415,13 @@ __metadata:
   languageName: node
   linkType: hard
 
-"timeline-state-resolver-types@npm:10.0.0-nightly-main-20260429-110933-d01800ef9.0":
-  version: 10.0.0-nightly-main-20260429-110933-d01800ef9.0
-  resolution: "timeline-state-resolver-types@npm:10.0.0-nightly-main-20260429-110933-d01800ef9.0"
+"timeline-state-resolver-types@npm:10.0.0-nightly-main-20260514-152958-5f6033589.0":
+  version: 10.0.0-nightly-main-20260514-152958-5f6033589.0
+  resolution: "timeline-state-resolver-types@npm:10.0.0-nightly-main-20260514-152958-5f6033589.0"
   dependencies:
     kairos-lib: "npm:1.0.0"
     tslib: "npm:^2.8.1"
-  checksum: 10/cbd39136ce786cdcde9faa72242e256bb3dbbf27b28088399924544f2f7a655cfc39f77b035ee0b46b4dfed86ee379869104d7ee64b75b04519adb51d367a853
+  checksum: 10/debb3faa9eda1f4ab2a85165c052cfc5b8698367d5a84be8b4095dbdaf6a40175e4c5ec80f09199e7650b53280e8c730f85bbd30685e08d3ea382ca08ee84e8b
   languageName: node
   linkType: hard
 

packages/blueprints-integration/src/api/studio.ts

@@ -41,6 +41,26 @@ import type { MosGatewayConfig } from '@sofie-automation/shared-lib/dist/generat
 import type { PlayoutGatewayConfig } from '@sofie-automation/shared-lib/dist/generated/PlayoutGatewayConfigTypes'
 import type { LiveStatusGatewayConfig } from '@sofie-automation/shared-lib/dist/generated/LiveStatusGatewayOptionsTypes'
 
+/**
+ * Context provided to device status message functions.
+ * Contains the device name, device ID, and any additional context from the TSR status detail.
+ */
+export interface DeviceStatusContext {
+	/** Human-readable name of the device */
+	deviceName: string
+	/** Internal device ID */
+	deviceId?: string
+	/** Additional context values from the TSR error (e.g., host, port, channel, etc.) */
+	[key: string]: unknown
+}
+
+/**
+ * A function that receives device status context and returns a custom status message.
+ * Return `undefined` to fall back to the default TSR message.
+ * Return an empty string `''` to suppress the message entirely.
+ */
+export type DeviceStatusMessageFunction = (context: DeviceStatusContext) => string | undefined
+
 export interface StudioBlueprintManifest<
 	TRawConfig = IBlueprintConfig,
 	TProcessedConfig = unknown,
@@ -56,6 +76,39 @@ export interface StudioBlueprintManifest<
 	/** Translations connected to the studio (as stringified JSON) */
 	translations?: string
 
+	/**
+	 * Alternate device status messages, to override the default messages from TSR devices.
+	 * Keys are status code strings from TSR devices (e.g., 'DEVICE_ATEM_DISCONNECTED').
+	 *
+	 * Import status codes from 'timeline-state-resolver-types' for type safety.
+	 * Values can be:
+	 * - String templates using {{variable}} syntax for interpolation with context values
+	 * - Functions that receive DeviceStatusContext and return a custom message string
+	 * - Empty string to suppress the status message entirely
+	 *
+	 * @example
+	 * ```typescript
+	 * import { AtemStatusCode, CasparCGStatusCode } from 'timeline-state-resolver-types'
+	 *
+	 * deviceStatusMessages: {
+	 *   // String template with placeholders
+	 *   [AtemStatusCode.DISCONNECTED]: 'Vision mixer offline - check network to {{host}}',
+	 *   [AtemStatusCode.PSU_FAULT]: 'PSU {{psuNumber}} needs attention',
+	 *
+	 *   // Function for complex conditional logic
+	 *   [CasparCGStatusCode.CHANNEL_ERROR]: (context) => {
+	 *     const channel = context.channel as number
+	 *     if (channel === 1) return 'Primary graphics output failed!'
+	 *     return `Graphics channel ${channel} error on ${context.deviceName}`
+	 *   },
+	 *
+	 *   // Suppress a noisy message
+	 *   [SomeStatusCode.NOISY_STATUS]: '',
+	 * }
+	 * ```
+	 */
+	deviceStatusMessages?: Record<string, string | DeviceStatusMessageFunction>
+
 	/** Returns the items used to build the baseline (default state) of a studio, this is the baseline used when there's no active rundown */
 	getBaseline: (context: IStudioBaselineContext) => BlueprintResultStudioBaseline
 

packages/blueprints-integration/src/api/system.ts

@@ -2,13 +2,35 @@ import type { IBlueprintTriggeredActions } from '../triggers.js'
 import type { BlueprintManifestBase, BlueprintManifestType } from './base.js'
 import type { ICoreSystemApplyConfigContext } from '../context/systemApplyConfigContext.js'
 import type { ICoreSystemSettings } from '@sofie-automation/shared-lib/dist/core/model/CoreSystemSettings'
+import type { SystemErrorCode } from '@sofie-automation/shared-lib/dist/systemErrorMessages'
+
+// Re-export so blueprints can import from blueprints-integration
+export { SystemErrorCode } from '@sofie-automation/shared-lib/dist/systemErrorMessages'
 
 export interface SystemBlueprintManifest extends BlueprintManifestBase {
 	blueprintType: BlueprintManifestType.SYSTEM
 
 	/** Translations connected to the studio (as stringified JSON) */
 	translations?: string
 
+	/**
+	 * Alternate system error messages, to override the builtin ones produced by Sofie.
+	 * Keys are SystemErrorCode values (e.g., 'DATABASE_CONNECTION_LOST').
+	 *
+	 * Templates use {{variable}} syntax for interpolation with context values.
+	 *
+	 * @example
+	 * ```typescript
+	 * import { SystemErrorCode } from '@sofie-automation/blueprints-integration'
+	 *
+	 * systemErrorMessages: {
+	 *   [SystemErrorCode.DATABASE_CONNECTION_LOST]: 'Database offline - contact IT support',
+	 *   [SystemErrorCode.SERVICE_UNAVAILABLE]: 'Service {{serviceName}} is not responding',
+	 * }
+	 * ```
+	 */
+	systemErrorMessages?: Partial<Record<SystemErrorCode | string, string | undefined>>
+
 	/**
 	 * Apply the config by generating the data to be saved into the db.
 	 * This should be written to give a predictable and stable result, it can be called with the same config multiple times