Add a possibility to re-add deleted elements with preserved ids

change/@itwin-imodel-transformer-635c5a66-27ec-4eae-9501-ca020a3b90aa.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "add more cases to support preserveElementIdsForFiltering options",
+  "packageName": "@itwin/imodel-transformer",
+  "email": "Daniel.Erbynn@bentley.com",
+  "dependentChangeType": "patch"
+}

packages/transformer/src/IModelImporter.ts

@@ -63,6 +63,11 @@ export interface IModelImportOptions {
    * @see [IModelImporter Options]($docs/learning/transformer/index.md#IModelImporter)
    */
   autoExtendProjectExtents?: boolean | { excludeOutliers: boolean };
+  /**
+   * Indicates whether the importer is used in a transformation process.
+   * If `true`, the importer was passed into the transformer, or the transformer constructed this instance of the importer
+   */
+  fromTransformation?: boolean;
   /** See [IModelTransformOptions]($transformer) */
   preserveElementIdsForFiltering?: boolean;
   /** If `true`, simplify the element geometry for visualization purposes. For example, convert b-reps into meshes.
@@ -103,6 +108,20 @@ export class IModelImporter {
    */
   private _duplicateCodeValueMap: Map<Id64String, string>;
 
+  /**
+   * A set of elementIds that the transformer adds to while exporting elements to indicate that the element already exists in the target.
+   * Defaults to an empty set.
+   * @note
+   *
+   * This is used as an optimization when `preserveElementIdsForFiltering` is set to `true`
+   * In normal cases where this option set to `false`,
+   * the importer determines whether to insert or update based off of whether the ID is defined on the `elementProps` passed to `importElement`.
+   * However, with `preserveElementIdsForFiltering` set to `true`, IDs are always set, so we can't determine insert/update like the normal case.
+   * The transformer already knows if an element exists or not by the time `importElement` is called and pushes to this set with `markElementAsUpdate`.
+   * @note This set should stay small, as right after the transformer pushes to it, the importer will remove from the set.
+   */
+  private _elementsToUpdate = new Set<Id64String>([]);
+
   /** The set of elements that should not be updated by this IModelImporter.
    * Defaults to an empty set.
    * @note Adding an element to this set is typically necessary when remapping a source element to one that already exists in the target and already has the desired properties.
@@ -133,6 +152,7 @@ export class IModelImporter {
     this.targetDb = targetDb;
     this.options = {
       autoExtendProjectExtents: options?.autoExtendProjectExtents ?? true,
+      fromTransformation: options?.fromTransformation ?? false,
       preserveElementIdsForFiltering:
         options?.preserveElementIdsForFiltering ?? false,
       simplifyElementGeometry: options?.simplifyElementGeometry ?? false,
@@ -155,6 +175,16 @@ export class IModelImporter {
     return false;
   }
 
+  /**
+   * Marks an element so that it can be updated during import when [[IModelImportOptions.preserveElementIdsForFiltering]] is set to true
+   */
+  public markElementAsUpdate(elementId: Id64String) {
+    if (this._rootElementIds.has(elementId)) {
+      return;
+    }
+    this._elementsToUpdate.add(elementId);
+  }
+
   /** Import the specified ModelProps (either as an insert or an update) into the target iModel. */
   public importModel(modelProps: ModelProps): void {
     if (undefined === modelProps.id || !Id64.isValidId64(modelProps.id))
@@ -229,6 +259,25 @@ export class IModelImporter {
 
   /** Import the specified ElementProps (either as an insert or an update) into the target iModel. */
   public importElement(elementProps: ElementProps): Id64String {
+    const tryUpdateElement = (elemProps: ElementProps): void => {
+      try {
+        this.onUpdateElement(elemProps);
+      } catch (err) {
+        if ((err as IModelError).errorNumber === IModelStatus.DuplicateCode) {
+          assert(
+            elemProps.code.value !== undefined,
+            "NULL code values are always considered unique and cannot clash"
+          );
+          this._duplicateCodeValueMap.set(elemProps.id!, elemProps.code.value);
+          // Using NULL code values as an alternative is not valid because definition elements cannot have NULL code values.
+          elemProps.code.value = Guid.createValue();
+          this.onUpdateElement(elemProps);
+        } else {
+          throw err;
+        }
+      }
+    };
+
     if (
       undefined !== elementProps.id &&
       this.doNotUpdateElement(elementProps.id)
@@ -246,6 +295,7 @@ export class IModelImporter {
           "elementProps.id must be defined during a preserveIds operation"
         );
       }
+
       // Categories are the only element that onInserted will immediately insert a new element (their default subcategory)
       // since default subcategories always exist and always will be inserted after their categories, we treat them as an update
       // to prevent duplicate inserts.
@@ -257,29 +307,23 @@ export class IModelImporter {
       ) {
         this.onUpdateElement(elementProps);
       } else {
-        this.onInsertElement(elementProps);
+        // if [[IModelImportOptions.fromTransformation]] is false, try and get the element (update if it exists)
+        const shouldUpdateElement =
+          !this.options.fromTransformation &&
+          this.targetDb.elements.tryGetElement(elementProps.id);
+        if (
+          this._elementsToUpdate.has(elementProps.id) ||
+          shouldUpdateElement
+        ) {
+          tryUpdateElement(elementProps);
+          this._elementsToUpdate.delete(elementProps.id);
+        } else {
+          this.onInsertElement(elementProps);
+        }
       }
     } else {
       if (undefined !== elementProps.id) {
-        try {
-          this.onUpdateElement(elementProps);
-        } catch (err) {
-          if ((err as IModelError).errorNumber === IModelStatus.DuplicateCode) {
-            assert(
-              elementProps.code.value !== undefined,
-              "NULL code values are always considered unique and cannot clash"
-            );
-            this._duplicateCodeValueMap.set(
-              elementProps.id,
-              elementProps.code.value
-            );
-            // Using NULL code values as an alternative is not valid because definition elements cannot have NULL code values.
-            elementProps.code.value = Guid.createValue();
-            this.onUpdateElement(elementProps);
-          } else {
-            throw err;
-          }
-        }
+        tryUpdateElement(elementProps);
       } else {
         this.onInsertElement(elementProps); // targetElementProps.id assigned by insertElement
       }

packages/transformer/src/IModelTransformer.ts

@@ -668,6 +668,7 @@ export class IModelTransformer extends IModelExportHandler {
       this.validateSharedOptionsMatch();
     }
     this.targetDb = this.importer.targetDb;
+    this.importer.options.fromTransformation = true;
     // create the IModelCloneContext, it must be initialized later
     this.context = new IModelCloneContext(this.sourceDb, this.targetDb);
 
@@ -1882,10 +1883,7 @@ export class IModelTransformer extends IModelExportHandler {
   public override onExportElement(sourceElement: Element): void {
     let targetElementId: Id64String;
     let targetElementProps: ElementProps;
-    if (this._options.preserveElementIdsForFiltering) {
-      targetElementId = sourceElement.id;
-      targetElementProps = this.onTransformElement(sourceElement);
-    } else if (this._options.wasSourceIModelCopiedToTarget) {
+    if (this._options.wasSourceIModelCopiedToTarget) {
       targetElementId = sourceElement.id;
       targetElementProps =
         this.targetDb.elements.getElementProps(targetElementId);
@@ -1944,6 +1942,34 @@ export class IModelTransformer extends IModelExportHandler {
       ? targetElementId
       : undefined;
 
+    if (this._options.preserveElementIdsForFiltering) {
+      const isInvalid = !Id64.isValid(targetElementId);
+
+      if (!isInvalid && targetElementId !== sourceElement.id) {
+        // Element found with different id
+        throw new Error(
+          `Element id(${sourceElement.id}) cannot be preserved. Found a different mapping(${targetElementId}) from source element`
+        );
+      } else if (!isInvalid && targetElementId === sourceElement.id) {
+        // targetElementId is valid (indicating update)
+        this.importer.markElementAsUpdate(sourceElement.id);
+      } else if (isInvalid) {
+        const sourceInTargetElemProps =
+          this.targetDb.elements.tryGetElementProps(sourceElement.id);
+
+        // if we don't find mapping for source element in target(invalid) but another element with source id exists in target
+        if (sourceInTargetElemProps) {
+          // Element id is already taken by another element
+          throw new Error(
+            `Element id(${sourceElement.id}) cannot be preserved. An unrelated element in the target already uses id: ${sourceElement.id}`
+          );
+        } else {
+          // Element id in target is available to be remapped
+          targetElementProps.id = sourceElement.id;
+        }
+      }
+    }
+
     if (!this._options.wasSourceIModelCopiedToTarget) {
       this.importer.importElement(targetElementProps); // don't need to import if iModel was copied
     }