Record uniqueness and archive

A unique constraint prevents two records from using the same combination of values. In the Entity Definition’s constraints panel, select the fields and choose an archive scope:

• All records keeps values reserved after archiving. Existing constraints retain this setting when the application is upgraded.
• Active records releases values when a record is archived. Restoring that record can fail if another active record has used the same combination.

For example, a constraint on Beneficiary and Phone allows different beneficiaries to share a phone number. It prevents two participating records from sharing both values. This setting does not change phone formatting or letter-case rules.

Active records is available on a record’s primary table. Owned child Tables retain All records. Configuration managed by the application remains subject to its existing editing restrictions. The administrator must choose the scope as a business decision; upgrading does not switch existing constraints.

Change a scope

Edit the existing constraint and save the new scope. Its selected fields stay the same. Changing Active records to All records fails if archived records would introduce a duplicate. The saved setting remains unchanged after a failure. Review the affected test or business records before trying again; the application does not delete or merge them automatically.

If another administrator changed the constraint, reload it before making a new decision. Configuration permissions are required and do not grant access to otherwise hidden business records.

Handle a restore refusal

A duplicate error means the record cannot reclaim its values. The record stays archived. If restoring it also restores dependent records, a conflict in any dependent record cancels the whole restore. Reload to inspect the unchanged state and resolve the business conflict through authorized actions before submitting a new operation. Repeating the same failed request does not make the value available. Hidden records also reserve keys; error messages do not identify those records.

APIs and C# integration

Resolve all /api/workspace/... routes against WORKSPACE_API_BASE_URL, never against moltaro.com. On a supporting installation, create a constraint with POST /api/workspace/admin/entity-definitions/{definitionId}/unique-constraints:

{
  "EntityDefinitionTableId": "primary-table-id",
  "FieldIds": ["beneficiary-field-id", "phone-field-id"],
  "ArchiveScope": 2
}

The numeric values are 1 for AllRecords and 2 for ActiveRecords. Missing, null, zero and unknown scopes are rejected. The response includes ArchiveScope and RowVersion. Change only the scope with PUT to the same route plus the constraint ID, sending {"ArchiveScope": 1, "RowVersion": "current-guid"}. Use the installed Configuration OpenAPI to regenerate configuration clients.

Entity YAML v10 requires ArchiveScope for each unique constraint; its embedded Security document remains v8. Re-export older documents or convert them explicitly after confirming the desired scope. Plan and apply use the same validation as the configuration screen.

Ordinary REST record mutations and the supported C# automation services keep their existing payloads. They use the configured scope. A uniqueness refusal is a business failure, including in a composite save: do not treat it as a transient retry. HTTP mutations use status 400 and moltaro.instances.duplicate, or .duplicate.archived for an AllRecords archived conflict. Consult the installation’s error catalog for the available operations and reaction contract.

Agents must confirm installed-version support and obtain an explicit business decision before changing a customer’s existing constraint. Changing scope does not by itself require rebuilding C# functions whose record contracts are unchanged. A rollback to older application code needs a compatibility and backup plan: archived duplicates may prevent restoring AllRecords.