retry dictionary registration

apps/server/swagger/dictionary-api.yml

@@ -2,9 +2,17 @@
 
 /dictionary/register:
   post:
-    summary: Register new dictionary
+    summary: Register a dictionary to a category. Creates the category if it does not exist, or updates its active dictionary and triggers a data migration to validate and update existing data against the new dictionary.
     tags:
       - Dictionary
+    parameters:
+      - name: force
+        description: Runs dictionary registration and migration again for this category, even if the same dictionary is already registered. Use this only when a previous migration ended unexpectedly and you must rerun both steps.
+        in: query
+        required: false
+        schema:
+          type: boolean
+          default: false
     requestBody:
       content:
         application/json:
@@ -38,8 +46,8 @@
         $ref: '#/components/responses/BadRequest'
       401:
         $ref: '#/components/responses/UnauthorizedError'
-      404:
-        $ref: '#/components/responses/NotFound'
+      409:
+        $ref: '#/components/responses/StatusConflict'
       500:
         $ref: '#/components/responses/ServerError'
       503:

packages/data-provider/docs/dictionary-registration.md

@@ -108,6 +108,8 @@ A Category is uniquely identified by its case-sensitive `categoryName`.
 
 Category groups data that is related and shares the same data structure, for that reason, a category must be associated to a registered dictionary. Over time, if the dictionary requires an update, the category needs to be updates accordingly, See [Dictionary Migration](#dictionary-migration) for more details.
 
+If a category is already using the same dictionary name and version, registration returns `409 Conflict` by default. Set the `force` query parameter to `true` only when you need to override this and rerun registration for the same dictionary. This also triggers migration validation for existing category data, which is mainly useful when a previous registration or migration ended unexpectedly.
+
 ## Centric entity
 
 Some dictionaries define a centric entity, representing the root of the data model hierarchy (used on compound views).

packages/data-provider/src/controllers/dictionaryController.ts

@@ -22,6 +22,7 @@ const controller = (dependencies: BaseDependencies) => {
 				const dictionaryName = req.body.dictionaryName;
 				const dictionaryVersion = req.body.dictionaryVersion;
 				const defaultCentricEntity = req.body.defaultCentricEntity;
+				const forceRegistration = req.query.force?.toLowerCase() === 'true';
 				const user = req.user;
 
 				logger.info(
@@ -35,6 +36,7 @@ const controller = (dependencies: BaseDependencies) => {
 					dictionaryVersion,
 					defaultCentricEntity,
 					username: user?.username,
+					forceRegistration,
 				});
 
 				logger.info(LOG_MODULE, `Register Dictionary completed!`);

packages/data-provider/src/services/dictionaryService.ts

@@ -7,7 +7,7 @@ import { BaseDependencies } from '../config/config.js';
 import lecternClient from '../external/lecternClient.js';
 import categoryRepository from '../repository/categoryRepository.js';
 import dictionaryRepository from '../repository/dictionaryRepository.js';
-import { BadRequest } from '../utils/errors.js';
+import { BadRequest, StatusConflict } from '../utils/errors.js';
 import migrationService from './migrationService.js';
 
 const dictionaryService = (dependencies: BaseDependencies) => {
@@ -99,12 +99,14 @@ const dictionaryService = (dependencies: BaseDependencies) => {
 		dictionaryVersion,
 		defaultCentricEntity,
 		username,
+		forceRegistration = false,
 	}: {
 		categoryName: string;
 		dictionaryName: string;
 		dictionaryVersion: string;
 		defaultCentricEntity?: string;
 		username?: string;
+		forceRegistration?: boolean;
 	}): Promise<{ dictionary: Dictionary; category: Category; migrationId?: number }> => {
 		logger.debug(
 			LOG_MODULE,
@@ -131,11 +133,54 @@ const dictionaryService = (dependencies: BaseDependencies) => {
 		// Check if Category exist
 		const foundCategory = await categoryRepo.getCategoryByName(categoryName);
 
+		const initiateMigrationOrThrow = async ({
+			categoryId,
+			fromDictionaryId,
+			toDictionaryId,
+		}: {
+			categoryId: number;
+			fromDictionaryId: number;
+			toDictionaryId: number;
+		}): Promise<number> => {
+			const resultMigration = await initiateMigration({
+				categoryId,
+				fromDictionaryId,
+				toDictionaryId,
+				userName: username || '',
+			});
+
+			if (!resultMigration.success) {
+				const errorMessage = `Failed to initiate migration for category '${categoryName}' with error: ${resultMigration.data}`;
+				logger.error(LOG_MODULE, errorMessage);
+				throw new Error(errorMessage);
+			}
+
+			return resultMigration.data;
+		};
+
 		if (foundCategory && foundCategory.activeDictionaryId === savedDictionary.id) {
 			// Dictionary and Category already exists
 			logger.info(LOG_MODULE, `Dictionary and Category already exists`);
 
-			return { dictionary: savedDictionary, category: foundCategory };
+			if (forceRegistration) {
+				logger.info(
+					LOG_MODULE,
+					`Force flag is true, initiating migration for Category '${foundCategory.name}' 
+					with Dictionary '${savedDictionary.name}' version '${savedDictionary.version}'`,
+				);
+
+				const migrationId = await initiateMigrationOrThrow({
+					categoryId: foundCategory.id,
+					fromDictionaryId: foundCategory.activeDictionaryId,
+					toDictionaryId: savedDictionary.id,
+				});
+
+				return { dictionary: savedDictionary, category: foundCategory, migrationId };
+			}
+
+			throw new StatusConflict(
+				`Category '${categoryName}' with Dictionary '${savedDictionary.name}' version '${savedDictionary.version}' already exists`,
+			);
 		} else if (foundCategory && foundCategory.activeDictionaryId !== savedDictionary.id) {
 			// Update the dictionary on existing Category
 			const updatedCategory = await categoryRepo.update(foundCategory.id, {
@@ -144,25 +189,18 @@ const dictionaryService = (dependencies: BaseDependencies) => {
 				updatedBy: username,
 			});
 
-			const resultMigration = await initiateMigration({
+			const migrationId = await initiateMigrationOrThrow({
 				categoryId: updatedCategory.id,
 				fromDictionaryId: foundCategory.activeDictionaryId,
 				toDictionaryId: savedDictionary.id,
-				userName: username || '',
 			});
 
-			if (!resultMigration.success) {
-				const errorMessage = `Failed to initiate migration for category '${categoryName}' with error: ${resultMigration.data}`;
-				logger.error(LOG_MODULE, errorMessage);
-				throw new Error(errorMessage);
-			}
-
 			logger.info(
 				LOG_MODULE,
 				`Category '${updatedCategory.name}' updated successfully with Dictionary '${savedDictionary.name}' version '${savedDictionary.version}'`,
 			);
 
-			return { dictionary: savedDictionary, category: updatedCategory, migrationId: resultMigration.data };
+			return { dictionary: savedDictionary, category: updatedCategory, migrationId };
 		} else {
 			// Create a new Category
 			const newCategory: NewCategory = {

packages/data-provider/src/utils/schemas.ts

@@ -234,9 +234,13 @@ export interface DictionaryRegisterBodyParams {
 	defaultCentricEntity?: string;
 }
 
+export interface DictionaryRegisterQueryParams extends ParsedQs {
+	force?: string;
+}
+
 export const dictionaryRegisterRequestSchema: RequestValidation<
 	DictionaryRegisterBodyParams,
-	ParsedQs,
+	DictionaryRegisterQueryParams,
 	ParamsDictionary
 > = {
 	body: z.object({
@@ -245,6 +249,9 @@ export const dictionaryRegisterRequestSchema: RequestValidation<
 		dictionaryVersion: stringNotEmpty,
 		defaultCentricEntity: entityNameSchema.or(z.literal('')).optional(),
 	}),
+	query: z.object({
+		force: booleanSchema.default('false'),
+	}),
 };
 
 // Migration Requests