feat: allow returning error from adlib actions in blueprints (Sofie-Automation#1638)

Co-authored-by: Ivan Maretić <i.maretic@evs.com>
Co-authored-by: Julian Waller <git@julusian.co.uk>

Author: 3 people

meteor/server/api/rest/v1/playlists.ts

@@ -989,7 +989,9 @@ export function registerRoutes(registerRoute: APIRegisterHook<PlaylistsRestAPI>)
 		'post',
 		'/playlists/:playlistId/execute-adlib',
 		new Map([
+			[400, []],
 			[404, [UserErrorMessage.RundownPlaylistNotFound]],
+			[409, [UserErrorMessage.ValidationFailed]],
 			[412, [UserErrorMessage.InactiveRundown, UserErrorMessage.NoCurrentPart, UserErrorMessage.AdlibNotFound]],
 		]),
 		playlistsAPIFactory,
@@ -1025,7 +1027,9 @@ export function registerRoutes(registerRoute: APIRegisterHook<PlaylistsRestAPI>)
 		'post',
 		'/playlists/:playlistId/execute-bucket-adlib',
 		new Map([
+			[400, []],
 			[404, [UserErrorMessage.RundownPlaylistNotFound]],
+			[409, [UserErrorMessage.ValidationFailed]],
 			[
 				412,
 				[

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

@@ -41,7 +41,7 @@ import type { IBlueprintShowStyleVariant, IOutputLayer, ISourceLayer } from '../
 import type { SourceLayerType } from '../content.js'
 import type { TSR, OnGenerateTimelineObj, TimelineObjectCoreExt } from '../timeline.js'
 import type { IBlueprintConfig } from '../common.js'
-import type { ReadonlyDeep } from 'type-fest'
+import type { JsonValue, ReadonlyDeep } from 'type-fest'
 import type { JSONSchema } from '@sofie-automation/shared-lib/dist/lib/JSONSchemaTypes'
 import type { JSONBlob } from '@sofie-automation/shared-lib/dist/lib/JSONBlob'
 import type { BlueprintConfigCoreConfig, BlueprintManifestBase, BlueprintManifestType, IConfigMessage } from './base.js'
@@ -51,6 +51,7 @@ import type { ABResolverConfiguration } from '../abPlayback.js'
 import type { SofieIngestSegment } from '../ingest-types.js'
 import { PackageStatusMessage } from '@sofie-automation/shared-lib/dist/packageStatusMessages'
 import { BlueprintPlayoutPersistentStore } from '../context/playoutStore.js'
+import type { ITranslatableMessage } from '../translations.js'
 
 export { PackageStatusMessage }
 
@@ -141,12 +142,7 @@ export interface ShowStyleBlueprintManifest<
 		privateData: unknown | undefined,
 		publicData: unknown | undefined,
 		actionOptions: { [key: string]: any } | undefined
-	) => Promise<{
-		/**
-		 * To be set if the payload sent by the user is invalid. When set, a 409 `ValidationFailed` message will be displayed to the User.
-		 */
-		validationErrors: any
-	} | void>
+	) => Promise<BlueprintExecuteActionResult | void>
 
 	/** Generate adlib piece from ingest data */
 	getAdlibItem?: (
@@ -381,3 +377,20 @@ export interface IShowStyleVariantConfigPreset<TConfig = IBlueprintConfig> {
 
 	config: Partial<TConfig>
 }
+
+export interface BlueprintExecuteActionResult {
+	/**
+	 * User friendly error message to return to the caller if the action was rejected.
+	 */
+	message: ITranslatableMessage
+
+	/**
+	 * HTTP error code for the action. If set, must be in the range 400-499
+	 */
+	errorCode?: number
+
+	/**
+	 * Additional details payload to provide to the caller
+	 */
+	details?: JsonValue
+}

packages/corelib/src/__tests__/lib.spec.ts

@@ -146,7 +146,7 @@ describe('Lib', () => {
 			errorCode: 42,
 			key: UserErrorMessage.ValidationFailed,
 			userMessage: {
-				key: 'Validation failed!',
+				key: 'Validation failed! {{message}}',
 				args: {},
 			},
 			rawError: {

packages/corelib/src/error.ts

@@ -116,7 +116,7 @@ const UserErrorMessagesTranslations: { [key in UserErrorMessage]: string } = {
 	[UserErrorMessage.DeviceAlreadyAttachedToStudio]: t(`Device is already attached to another studio.`),
 	[UserErrorMessage.ShowStyleBaseNotFound]: t(`ShowStyleBase not found!`),
 	[UserErrorMessage.NoMigrationsToApply]: t(`No migrations to apply`),
-	[UserErrorMessage.ValidationFailed]: t('Validation failed!'),
+	[UserErrorMessage.ValidationFailed]: t('Validation failed! {{message}}'),
 	[UserErrorMessage.AdlibTestingNotAllowed]: t(`Rehearsal mode is not allowed`),
 	[UserErrorMessage.AdlibTestingAlreadyActive]: t(`Rehearsal mode is already active`),
 	[UserErrorMessage.BucketNotFound]: t(`Bucket not found!`),

packages/corelib/src/worker/studio.ts

@@ -322,11 +322,6 @@ export interface ExecuteBucketAdLibOrActionProps extends RundownPlayoutPropsBase
 	externalId: string
 	triggerMode?: string
 }
-export interface ExecuteBucketAdLibOrActionProps extends RundownPlayoutPropsBase {
-	bucketId: BucketId
-	externalId: string
-	triggerMode?: string
-}
 export interface ExecuteActionResult {
 	queuedPartInstanceId?: PartInstanceId
 	taken?: boolean

packages/job-worker/src/playout/adlibAction.ts

@@ -14,7 +14,7 @@ import { PlayoutModel, PlayoutModelPreInit } from './model/PlayoutModel.js'
 import { runJobWithPlaylistLock } from './lock.js'
 import { updateTimeline } from './timeline/generate.js'
 import { performTakeToNextedPart } from './take.js'
-import { ActionUserData } from '@sofie-automation/blueprints-integration'
+import { ActionUserData, BlueprintExecuteActionResult } from '@sofie-automation/blueprints-integration'
 import {
 	DBRundownPlaylist,
 	SelectedPartInstance,
@@ -38,6 +38,7 @@ import type { INoteBase } from '@sofie-automation/corelib/dist/dataModel/Notes'
 import { NotificationsModelHelper } from '../notifications/NotificationsModelHelper.js'
 import type { INotificationsModel } from '../notifications/NotificationsModel.js'
 import { PersistentPlayoutStateStore } from '../blueprints/context/services/PersistantStateStore.js'
+import { interpollateTranslation } from '@sofie-automation/corelib/dist/TranslatableMessage'
 
 /**
  * Execute an AdLib Action
@@ -249,7 +250,7 @@ export async function executeActionInner(
 		)} (${actionParameters.triggerMode})`
 	)
 
-	let result: ExecuteActionResult | void
+	let result: BlueprintExecuteActionResult | void
 
 	try {
 		const blueprintPersistentState = new PersistentPlayoutStateStore(
@@ -274,15 +275,21 @@ export async function executeActionInner(
 		throw UserError.fromUnknown(err)
 	}
 
-	if (result && result.validationErrors) {
+	// If the blueprint returned an error, abort the action and throw the error
+	if (result && typeof result === 'object' && result.message) {
+		const messageStr = interpollateTranslation(result.message.key, result.message.args)
+		const statusCode = Number.isFinite(result.errorCode)
+			? Math.max(Math.min(Math.round(result.errorCode as number), 499), 400)
+			: 409
 		throw UserError.from(
-			new Error(
-				`AdLib Action "${actionParameters.actionId}" validation failed: ${JSON.stringify(result.validationErrors)}`
-			),
+			new Error(messageStr),
 			UserErrorMessage.ValidationFailed,
-			undefined,
-			409
+			{ message: messageStr, rawMessage: result.message, details: result.details },
+			statusCode
 		)
+	} else if (result !== undefined) {
+		// Unexpected return value — does not match the BlueprintExecuteActionResult shape; treat as success but warn so it can be investigated
+		logger.warn(`executeAction returned an unexpected value: ${JSON.stringify(result)}`)
 	}
 
 	// Store any notes generated by the action