Table of Contents

Interface IIdentityMapStore

Namespace
Excalibur.Data.IdentityMap
Assembly
Excalibur.Data.IdentityMap.dll

Provides identity resolution between external system identifiers and internal aggregate IDs.

public interface IIdentityMapStore
Extension Methods

Remarks

Used during CDC ingestion, API anti-corruption layers, and import pipelines to maintain stable mappings between foreign keys and domain aggregate identifiers.

All identifiers are stored as strings at the persistence layer, following the framework convention where aggregate roots normalize typed keys to strings. Use the typed extension methods in IdentityMapStoreExtensions for compile-time safety.

Methods

BindAsync(string, string, string, string, CancellationToken)

Creates or updates a mapping between an external identifier and an aggregate ID.

ValueTask BindAsync(string externalSystem, string externalId, string aggregateType, string aggregateId, CancellationToken cancellationToken)

Parameters

externalSystem string

The external system name.

externalId string

The external identifier value.

aggregateType string

The aggregate type name.

aggregateId string

The internal aggregate ID to map to.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask

ResolveAsync(string, string, string, CancellationToken)

Resolves an external identifier to its mapped aggregate ID.

ValueTask<string?> ResolveAsync(string externalSystem, string externalId, string aggregateType, CancellationToken cancellationToken)

Parameters

externalSystem string

The external system name (e.g., "LegacyCore", "SAP").

externalId string

The external identifier value.

aggregateType string

The target aggregate type name (e.g., "Order", "Account").

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<string>

The mapped aggregate ID, or null if no mapping exists.

ResolveBatchAsync(string, IReadOnlyList<string>, string, CancellationToken)

Resolves a batch of external identifiers to their mapped aggregate IDs.

ValueTask<IReadOnlyDictionary<string, string>> ResolveBatchAsync(string externalSystem, IReadOnlyList<string> externalIds, string aggregateType, CancellationToken cancellationToken)

Parameters

externalSystem string

The external system name (shared by all IDs in the batch).

externalIds IReadOnlyList<string>

The external identifier values to resolve.

aggregateType string

The target aggregate type name.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IReadOnlyDictionary<string, string>>

A dictionary mapping external IDs to aggregate IDs for entries that exist.

Remarks

The default implementation falls back to sequential per-item ResolveAsync(string, string, string, CancellationToken) calls. Override in stores that support efficient batch lookups (e.g., SQL WHERE IN clause).

TryBindAsync(string, string, string, string, CancellationToken)

Creates a mapping only if no mapping exists for the external identifier. Returns the existing aggregate ID if one is already bound.

ValueTask<IdentityBindResult> TryBindAsync(string externalSystem, string externalId, string aggregateType, string aggregateId, CancellationToken cancellationToken)

Parameters

externalSystem string

The external system name.

externalId string

The external identifier value.

aggregateType string

The aggregate type name.

aggregateId string

The aggregate ID to bind if no mapping exists.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<IdentityBindResult>

A result containing the aggregate ID (either newly bound or existing) and whether the binding was newly created.

UnbindAsync(string, string, string, CancellationToken)

Removes a mapping for an external identifier.

ValueTask<bool> UnbindAsync(string externalSystem, string externalId, string aggregateType, CancellationToken cancellationToken)

Parameters

externalSystem string

The external system name.

externalId string

The external identifier value.

aggregateType string

The aggregate type name.

cancellationToken CancellationToken

Cancellation token.

Returns

ValueTask<bool>

true if a mapping was removed; false if no mapping existed.