ID Remapping

Why ID Remapping is Necessary

In BizFirstGO, artifact IDs like proc-1001 or form-2005 are tenant-scoped. If the target tenant already has a proc-1001 (a different workflow), installing the package's proc-1001 without remapping would overwrite it — a silent data loss error.

ID remapping generates fresh, unique IDs for all artifacts in the target tenant and updates every reference within the artifact definitions to use the new IDs. The result is that the installed artifacts are completely independent from any existing artifacts, even if they share names.

Remapping Process

// Source package IDs:
proc-1001  →  proc-7823   (new ID in target tenant)
form-2005  →  form-9104   (new ID in target tenant)
rule-305   →  rule-6612   (new ID in target tenant)
ent-44     →  ent-2291    (new ID in target tenant)

// Cross-reference update in proc-7823.json:
// BEFORE remapping:
"config": { "formId": "form-2005" }

// AFTER remapping:
"config": { "formId": "form-9104" }

// The mapping table is stored in ImportContext and
// applied to every artifact JSON after deserialization

Conflict Cases

Remapping creates new IDs, but conflicts can still arise when an artifact in the package has the same name and type as an existing artifact in the target tenant. For example, both the package and the target tenant have an AtlasForm named EmployeeForm.

In this case, the import engine proceeds to the Conflict Resolution stage (see Installation and Guide 5).

The ID Remap Table

The complete remap table is stored in the ImportContext and is available in the import result for audit purposes:

{
  "importId":    "imp-f9a2c1e8-...",
  "idRemapTable": {
    "proc-1001": "proc-7823",
    "form-2005": "form-9104",
    "rule-305":  "rule-6612",
    "ent-44":    "ent-2291"
  }
}

IDRemappingService

public interface IIDRemappingService
{
    /// <summary>
    /// Generates new target-tenant IDs for all artifacts in the manifest.
    /// Returns the complete remap table.
    /// </summary>
    Task<IDRemapTable> GenerateRemapTableAsync(
        PackageManifest manifest,
        string          targetTenantId,
        CancellationToken ct = default);

    /// <summary>
    /// Applies the remap table to all artifact JSON definitions,
    /// replacing source IDs with target IDs throughout.
    /// </summary>
    IReadOnlyList<RemappedArtifact> ApplyRemap(
        IReadOnlyList<SerializedArtifact> artifacts,
        IDRemapTable                       remapTable);
}

Cross-Reference Fields

The remapper knows which JSON fields contain artifact ID references for each artifact type: