Skip to main content

Managing Alternate IDs

This section explains how Alternate IDs fit into SyncHive’s identity model, how to configure them, and the rules that govern creation, editing, removal, and imports.

Alternate IDs are user-defined data properties that serve as identifiers. They bridge systems by matching records on existing business fields (e.g., CustomerAccountNumber, ProductCode, RegionCode).

Roles & Permissions​

  • Admins and Power Users: Can create and remove Alternate IDs.
  • Standard Users: Read-only access;

View Alternate ID​

Schema Viewer: Alternate IDs are indicated with a key icon, visible at both the Entity Schema and Shape Schema levels.

Manage Alternate IDs​

Alternate IDs must be created or removed at the Entity level.

They can be enabled or disabled it for a given property. When doing so, the following rules apply:

1. Property must be empty before flagging it as Alternate ID

You can only mark properties that have no existing data. This prevents introducing duplicates or conflicts. Flagging a property that contains a value will trigger a validation error.

Tip: Mark a property as an Alternate ID only if you can guarantee that its values will be unique. Sending duplicate Alternate ID value may cause identity resolution failures or schema import errors.

2. System-managed properties cannot be flagged

The following fields are not eligible and have the Alternate ID checkbox disabled in the UI:

  • hiveId
  • isDeleted
  • createdOn
  • lastUpdatedOn

Removing Alternate IDs​

If a property no longer needs to function as an Alternate ID, simply uncheck the flag in the property editor. Once removed the key icon disappears from the schema viewer screen.

Modifying Alternate IDs via Imports​

When you import a schema between environments or instances, any Alternate ID updates are applied as defined in the imported schema. SyncHive automatically updates or removes Alternate IDs based on the import. You cannot restore an Alternate ID for a property that already contains data.

Best Practices:

  • Plan carefully: select fields that serve as stable, unique business keys. Consider creating a dedicated property to use as the Alternate ID.
  • Avoid transient/nullable fields: Alternate IDs should be persistent and consistently populated.
  • Ensure uniqueness: Duplicate Alternate IDs can break identity resolution or cause failed schema imports.