Add custom entity type support

Author: ncovercash

docs/Migration.md

@@ -1,9 +1,10 @@
-# Query Migration
+# Migration
 
 Entity types and their fields change over time, be it adding fields, moving them between entity types, or completely rethinking the way some fields are handled. As such, we have a robust migration system to ensure that consuming apps will not break, and their queries will continue to work despite any internal FQM changes.
 
-- [Query versions](#query-versions)
+- [Versions](#versions)
 - [Updating a query](#updating-a-query)
+- [Updating an entity type](#updating-an-entity-type)
 - [Writing migrations](#writing-migrations)
   - [Changes](#changes)
     - [Entity type changes](#entity-type-changes)
@@ -26,8 +27,9 @@ Entity types and their fields change over time, be it adding fields, moving them
     - [State](#state)
     - [Extra magic](#extra-magic)
     - [Advanced migration tips](#advanced-migration-tips)
+- [Custom entity types support](#custom-entity-types-support)
 
-## Query versions
+## Versions
 
 The version of a query is stored inside the FQL string:
 
@@ -38,14 +40,28 @@ The version of a query is stored inside the FQL string:
 }
 ```
 
-These are arbitrary strings, and consuming applications should make no assumptions about them (they are currently integers, but may be changed in the future to commit hashes, module versions, or anything else).
+And versions of custom entity types are stored inside the entity definition:
+
+```json
+{
+  "id": "d41130e9-0302-5ef3-a6b2-70f6ae1678ce",
+  "name": "my_custom_entity",
+  "_version": "3"
+}
+```
+
+These are arbitrary strings, and consuming applications should make no assumptions about them (they are currently semver-adjacent, but may be changed in the future to commit hashes, module versions, or anything else).
 
 Queries from Quesnelia or earlier will have no version associated with them and will be considered version `"0"`.
 
 ## Updating a query
 
 To update a query, send it, the entity type ID, and a list of fields (if desired) to `/fqm/migrate`. See our [API documentation](https://dev.folio.org/reference/api/#mod-fqm-manager) for more information about this endpoint. Our module will return the updated query, entity type ID, and list of fields, all of which should be saved. Additionally, the response may contain [warnings](#warnings), meaning that some parts of the query or field list was unable to be migrated.
 
+## Updating an entity type
+
+Custom entity types will be migrated when the module is installed. No additional action is required; for more information see [custom entity types support](#custom-entity-types-support).
+
 ## Writing migrations
 
 Any change to an entity type that results in a field being removed or renamed should result in a migration script. The easiest way to do this is to do the following:
@@ -108,7 +124,16 @@ public Map<UUID, UUID> getEntityTypeChanges() {
 
 ### Defining source maps
 
-<!-- TODO: describe this (in next PR) -->
+Source maps are used in migrations to define relations between composite and simple entity types. For example, if your migration alters `simple_instance_status`, it's necessary for the migration system to know that `composite_instances`'s `inst_stat` source points to `simple_instance_status`. To define these relationships, override `getEntityTypeSourceMaps` (note that the inner keys are the source aliases used by the composite):
+
+```java
+public Map<UUID, Map<String, UUID>> getEntityTypeSourceMaps() {
+  return Map.of(
+    COMPOSITE_INSTANCES_ID, Map.of("inst_stat", SIMPLE_INSTANCE_STATUS_ID),
+    COMPOSITE_ITEM_DETAILS_ID, Map.of("instance_status", SIMPLE_INSTANCE_STATUS_ID)
+  );
+}
+```
 
 ### Warnings
 

src/main/java/org/folio/fqm/migration/MigratableQueryInformation.java

@@ -16,11 +16,10 @@ public record MigratableQueryInformation(
   @CheckForNull String fqlQuery,
   List<String> fields,
   @Singular List<Warning> warnings,
-  String version,
   boolean hadBreakingChanges
 )
   implements Serializable {
   public MigratableQueryInformation(UUID entityTypeId, String fqlQuery, List<String> fields) {
-    this(entityTypeId, fqlQuery, fields, List.of(), null, false);
+    this(entityTypeId, fqlQuery, fields, List.of(), false);
   }
 }

src/main/java/org/folio/fqm/migration/warnings/RemovedFieldWarning.java

@@ -6,6 +6,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.RequiredArgsConstructor;
 import lombok.ToString;
+import org.folio.fqm.service.LocalizationService;
 import org.folio.spring.i18n.service.TranslationService;
 
 @Builder
@@ -31,7 +32,20 @@ public WarningType getType() {
 
   @Override
   public String getDescription(TranslationService translationService) {
-    return Warning.getDescriptionByAlternativeAndFql(translationService, this.getType(), field, fql, alternative);
+    String translationKey = LocalizationService.MIGRATION_WARNING_TRANSLATION_TEMPLATE.formatted(TYPE.toString());
+
+    if (fql == null) {
+      translationKey += ".field";
+    } else {
+      translationKey += ".query";
+    }
+    if (alternative == null) {
+      translationKey += ".withoutAlternative";
+    } else {
+      translationKey += ".withAlternative";
+    }
+
+    return translationService.format(translationKey, "name", field, "alternative", alternative, "fql", fql);
   }
 
   public static FieldWarningFactory withoutAlternative() {

src/main/java/org/folio/fqm/service/EntityTypeInitializationService.java

@@ -40,6 +40,7 @@ public class EntityTypeInitializationService {
   private final CrossTenantQueryService crossTenantQueryService;
   private final EntityTypeRepository entityTypeRepository;
   private final EntityTypeValidationService entityTypeValidationService;
+  private final MigrationService migrationService;
   private final SourceViewService sourceViewService;
 
   private final FolioExecutionContext folioExecutionContext;
@@ -52,13 +53,15 @@ public EntityTypeInitializationService(
     CrossTenantQueryService crossTenantQueryService,
     EntityTypeRepository entityTypeRepository,
     EntityTypeValidationService entityTypeValidationService,
+    MigrationService migrationService,
     SourceViewService sourceViewService,
     FolioExecutionContext folioExecutionContext,
     ResourcePatternResolver resourceResolver
   ) {
     this.crossTenantQueryService = crossTenantQueryService;
     this.entityTypeRepository = entityTypeRepository;
     this.entityTypeValidationService = entityTypeValidationService;
+    this.migrationService = migrationService;
     this.sourceViewService = sourceViewService;
     this.folioExecutionContext = folioExecutionContext;
     this.resourceResolver = resourceResolver;
@@ -85,6 +88,7 @@ public void initializeEntityTypes(String providedCentralTenantId) throws IOExcep
     );
 
     entityTypeRepository.replaceEntityTypeDefinitions(availableEntityTypes);
+    migrationService.migrateCustomEntityTypes();
   }
 
   protected Pair<String, String> getCentralTenantIdSafely(String centralTenantId) {

src/main/java/org/folio/fqm/service/EntityTypeService.java

@@ -18,6 +18,7 @@
 import org.folio.fqm.client.CrossTenantHttpClient;
 import org.folio.fqm.client.LanguageClient;
 import org.folio.fqm.client.SimpleHttpClient;
+import org.folio.fqm.config.MigrationConfiguration;
 import org.folio.fqm.domain.dto.EntityTypeSummary;
 import org.folio.fqm.exception.EntityTypeInUseException;
 import org.folio.fqm.exception.EntityTypeNotFoundException;
@@ -91,6 +92,7 @@ public class EntityTypeService {
   private final EntityTypeFlatteningService entityTypeFlatteningService;
   private final EntityTypeValidationService entityTypeValidationService;
   private final LocalizationService localizationService;
+  private final MigrationConfiguration migrationConfiguration;
   private final MigrationService migrationService;
   private final QueryProcessorService queryService;
   private final CrossTenantHttpClient crossTenantHttpClient;
@@ -487,8 +489,9 @@ public CustomEntityType createCustomEntityType(CustomEntityType customEntityType
       );
     }
 
-    var updatedCustomEntityType = customEntityType.toBuilder()
+    CustomEntityType updatedCustomEntityType = customEntityType.toBuilder()
       .id(customEntityTypeId.toString())
+      .version(migrationConfiguration.getCurrentVersion())
       .createdAt(now)
       .updatedAt(now)
       .owner(folioExecutionContext.getUserId())
@@ -505,6 +508,7 @@ public CustomEntityType updateCustomEntityType(UUID entityTypeId, CustomEntityTy
     permissionsService.verifyUserCanAccessCustomEntityType(oldET);
 
     CustomEntityType updatedCustomEntityType = customEntityType.toBuilder()
+      .version(migrationConfiguration.getCurrentVersion())
       .createdAt(oldET.getCreatedAt())
       .updatedAt(clockService.now())
       .owner(Objects.requireNonNullElse(customEntityType.getOwner(), oldET.getOwner()))

src/main/java/org/folio/fqm/service/EntityTypeValidationService.java

@@ -4,6 +4,7 @@
 import java.util.UUID;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.log4j.Log4j2;
+import org.folio.fqm.config.MigrationConfiguration;
 import org.folio.fqm.exception.EntityTypeNotFoundException;
 import org.folio.fqm.exception.InvalidEntityTypeDefinitionException;
 import org.folio.fqm.repository.EntityTypeRepository;
@@ -26,9 +27,16 @@ public class EntityTypeValidationService {
 
   private final EntityTypeRepository entityTypeRepository;
   private final FolioExecutionContext folioExecutionContext;
+  private final MigrationConfiguration migrationConfiguration;
 
   public void validateCustomEntityType(UUID entityTypeId, CustomEntityType customEntityType) {
     validateEntityType(entityTypeId, customEntityType, null);
+    if (!migrationConfiguration.getCurrentVersion().equals(customEntityType.getVersion())) {
+      throw new InvalidEntityTypeDefinitionException(
+        "Custom entity type must have _version=%s".formatted(migrationConfiguration.getCurrentVersion()),
+        customEntityType
+      );
+    }
     if (customEntityType.getOwner() == null) {
       throw new InvalidEntityTypeDefinitionException("Custom entity type must have an owner", customEntityType);
     }