Endatix.Modules.Audience 0.8.0

Endatix.Modules.Audience

Audience personalization for Endatix: per-form properties and people, tenant match key, CSV import, and personalised links.

Registration

Gated by Endatix:FeatureFlags:PersonalizationModule (off by default). Runs on PostgreSQL and on SQL Server 2025 or later (or Azure SQL Database). EndatixBuilder.UseDefaults() calls UseModule(AudienceModule.Instance).

The module registers AudiencePostgreSqlDbContext or AudienceSqlServerDbContext for the configured provider; handlers see it only as IAudienceDbContext. On SQL Server, keep READ_COMMITTED_SNAPSHOT on for the database (on in a database Endatix creates and in Azure SQL Database; a database created beforehand may have it off): without it, other tenants' audience reads wait for a running CSV import to commit.

Migrations

Each provider has its own chain in this assembly: Persistence/Migrations/PostgreSql/ and Persistence/Migrations/SqlServer/. Run from the repository root:

# PostgreSQL
ConnectionStrings__DefaultConnection="Host=localhost;Database=endatix;Username=postgres;Password=..." \
dotnet ef migrations add <MigrationName> \
  --startup-project src/Endatix.WebHost \
  --project src/Endatix.Modules.Audience \
  --context AudiencePostgreSqlDbContext \
  --output-dir Persistence/Migrations/PostgreSql

# SQL Server
ConnectionStrings__DefaultConnection="Server=localhost;Database=endatix;User Id=sa;Password=...;TrustServerCertificate=True" \
dotnet ef migrations add <MigrationName> \
  --startup-project src/Endatix.WebHost \
  --project src/Endatix.Modules.Audience \
  --context AudienceSqlServerDbContext \
  --output-dir Persistence/Migrations/SqlServer

A model change needs a migration in both chains.

Schema

Database schema: audience

API (directory)

Permission: Forms.Edit, except PUT audience/settings, which needs Tenant.ManageSettings, and redeem, which is anonymous.

Rules

• Match key. Locked while any person is on any form's audience (isLocked). Saving the current key is a no-op and takes no lock. A change soft-deletes members that are on no form, since they were matched under the old key.
• Values by data type. number: invariant, no surrounding spaces, any finite double (-12.5, 1e3, 1e29). boolean: true or false. date: YYYY-MM-DD. date_time: ISO 8601 (2026-10-05T09:30, optional seconds and offset). single_choice: one key from ChoicesJson. multiple_choice: a JSON array of keys. AllowsOther accepts any key.
• Concurrency. Person creates and imports take a shared tenant lock; a match-key change takes it exclusively. The lock is ITransactionLock (scope AudienceMatchKey, key the tenant id), held until the transaction ends. The unique indexes settle create races (a second pass reuses the member; a duplicate on one form is a 409). The identifier is checked against the key read under the lock. Two updates adding the same cell: the second pass overwrites. Cells are written in property-id order. The people list counts and then reads the page without a transaction, so it takes no locks that wait behind writers; when a person added in between makes the page longer than the count, the total is raised to cover the rows shown.
• Deletes. Removing a person deletes the membership and its cells; the member stays. Deleting a property soft-deletes its cells in one statement. Reads skip cells of deleted properties.
• Form deleted. The form.deleted outbox handler soft-deletes the form's cells, memberships and properties; tenant members stay. Until it runs, the form's people still count toward the match-key lock.
• On behalf. POST forms/{formId}/submissions/onbehalf (Submissions.CreateOnBehalf, not this module's routes) freezes a snapshot when Submitter.ExternalSubjectId matches a member on a form that has properties. Unknown id, no properties, or no submitter leaves the create unchanged. The snapshot is source: on_behalf plus memberId and values[] beside variables. Binding Member.SubmitterId is one update that matches only while it is null.
• Links. The token is stored as a SHA-256 hash. A claimed link resumes without a lock. A first open takes ITransactionLock (scope AudienceLinkOpen, key the link id, 5 s wait, then 503) through LinkOpenLock, on one connection: AppDbContext joins the audience transaction. Under the lock it re-reads the claim, adopts a submission an earlier open left (FormId + AudienceLinkId) or inserts one, issues the token, and claims with one update (SubmissionId still null). All of that commits together. A claim lost to a writer outside the lock rolls back and resumes that writer's submission. A link claimed before tokens were issued this way gets its first token under the lock. See ARCHITECTURE.md → Transaction locks. Disabled forms, a removed person, and sharing one submission with on-behalf are not gated here.