Configure Content Review

Integrator checklist to wire Content Review (product module at /content-review) for entityType: documentStorage Business Entities — required metadata, foreign keys, processing flags, upload validation, and steward handoff.

Content Review is the governed human step that completes document metadata before search, retrieval, and Role Assistant context. Operators see Needs Review in the queue; integrators declare what must be complete before Approve is enabled.

Assumes a document Business Entity already exists. Start from Build a document storage entity if not.

Prerequisites

• Document storage Business Entity JSON with entityType: documentStorage and working sync
• Target record Business Entities for required links (customer, deal, project) published and syncing
• Steward roles with document read and governed save permissions for Content Review
• Business sign-off on mandatory dimensions and links before AI or search exposure

Where it lives

Manifest bands that drive Content Review eligibility:

• foreignKeys[] — required links to record Business Entities
• dimensions — required governed fields (sensitivity, lifecycle, owner)
• labelKey — display title in the review panel
• metadataSchema — canonical scalar fields stewards edit
• documentStorage.processing — file path, enrichment, validation, notification flags

Runtime review APIs read these declarations; the UI does not hardcode vendor-specific fields.

How to set

The JSON blocks below are illustrative manifest fragments, not complete deployable manifests. Merge them into the appropriate generated Business Entity manifest, then run the validation commands before upload.

1. Declare join identity and display label — stewards need stable keys and a readable title:

{
  "key": "example-documents",
  "entityType": "documentStorage",
  "resourceType": "document",
  "primaryKey": ["externalId"],
  "labelKey": ["name"],
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": { "type": "string", "index": true },
      "name": { "type": "string", "index": true },
      "lifecycleStage": { "type": "string", "index": true },
      "sensitivityLabel": { "type": "string", "index": true },
      "linkedDealId": { "type": "string", "index": true }
    }
  }
}

2. Add required foreign keys — Content Review stays blocked until required links resolve:

{
  "foreignKeys": [
    {
      "name": "linkedDeal",
      "fields": ["linkedDealId"],
      "targetDatasource": "example-deals",
      "required": true,
      "description": "Every document must link to an active deal before approval"
    }
  ]
}

3. Mark required dimensions — map ABAC and approval eligibility to indexed metadata fields:

{
  "dimensions": {
    "sensitivity": {
      "type": "local",
      "field": "sensitivityLabel",
      "enabled": true
    },
    "lifecycleStage": {
      "type": "local",
      "field": "lifecycleStage",
      "enabled": true
    },
    "owner": {
      "type": "local",
      "field": "createdByEmail",
      "actor": "email",
      "enabled": true
    }
  }
}

4. Enable document storage processing — binary path and sync behavior under documentStorage:

{
  "documentStorage": {
    "enabled": true,
    "twoPhaseSync": true,
    "processing": {
      "fileStoragePath": "/data/documents/example"
    }
  }
}

Processing flags control file storage, optional AI validation, enrichment, and steward notifications. Keep enrichment configuration within supported manifest bands only.

5. Materialize governed fields in fieldMappings.attributes — stewards edit canonical metadata JSON; projections must align with metadataSchema and dimensions:

{
  "fieldMappings": {
    "attributes": {
      "lifecycleStage": {
        "expression": "{{raw.listItem.fields.LifecycleStage}}"
      },
      "sensitivityLabel": {
        "expression": "{{raw.listItem.fields.SensitivityLabel}}"
      },
      "linkedDealId": {
        "expression": "{{raw.listItem.fields.DealId}}"
      }
    }
  }
}

6. Repair, validate, and publish:

aifabrix repair <systemKey> --expose
aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>
aifabrix upload <systemKey> --probe

7. Hand off to stewards — share Operate Content Review; confirm /content-review queue visibility and role assignments before E2E approval tests.

Content Review runtime contract

Governed saves use canonical metadata JSON on the per-entity record row. Physical columns are derived projections for search and ABAC — not a second write path.

Sync status needs_validation (shown as Needs Review in Content Review) means human completion is required before the document is embeddable for search paths that honor approval gates.

For document storage, root documentStorage.ingestAfterSync controls the timing of eligible ingestion after binary extraction; it does not bypass required-link, security-review, trust, or access gates. The review header uses an actual source key (or datasource label when unavailable) and shows AI confidence only when AI validation produced a score. Processing status distinguishes disabled enrichment, no extracted text, unchanged trusted content, and a failed stage. Complete trusted metadata can proceed without a per-file click where policy allows; unresolved required links remain in human review. An optional link can be absent, but a supplied reference that names a record and cannot be resolved also needs review. Optional does not mean that a guessed or broken relationship is safe to accept.

Defaults and examples

Example minimal approval gate for a policy library linked to customers:

{
  "foreignKeys": [
    {
      "name": "owningCustomer",
      "fields": ["customerId"],
      "targetDatasource": "example-customers",
      "required": true
    }
  ],
  "dimensions": {
    "sensitivity": { "type": "local", "field": "classification", "enabled": true }
  }
}

A short option list is a presentation preview, not the complete permission
scope. When more values exist, Content Review provides a searchable selector;
search by a recognizable label and retain the current selection while searching.
Save still checks the complete allowed set and rejects out-of-scope values.
An absent preview option does not prove access denial; an empty governed search
also does not authorize entering a hidden value manually.

Validate

aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>
aifabrix upload <systemKey> --probe
aifabrix test-integration <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey> --verbose

Manual proof with a steward account:

• Sync at least one document into Needs Review in Content Review
• Confirm Approve disabled until required FK and dimensions are set
• Test an absent optional link separately from a supplied but unresolved reference; the latter must remain in review
• Search for a permitted dimension value outside the initial preview; confirm it can be selected and saved, while an out-of-scope value is refused
• Save draft, refresh etag, approve, confirm status moves to validated/synced
• Verify entitled search returns document; non-entitled user does not

Common mistakes

Limits

Provider-specific list envelopes and download URL patterns belong in document sync configuration — Content Review rules stay generic.

Bulk metadata update endpoints, when exposed, must follow the same atomic write, etag, FK validation, and audit rules as single-document save — confirm current API surface before building automation.