Build a viewpoint entity

Publish a viewpoint Business Entity: a calculated, read-only business perspective over synchronized record tables. When you finish, Role Assistants and MCP can call governed read capabilities that return measures, dimensions, and grain you defined — not raw multi-entity lists from records search.

Business story: Viewpoints and joined business context.

Prerequisites

• Connected System with at least one synchronized recordStorage entity (storageType omitted or table) already validated and loaded
• Concept understood: Viewpoints and joined business context
• Logged in (aifabrix auth status) and able to validate / upload the system
• Clear business contract: which questions, measures, dimensions, and row grain the Connected System owner will certify

Where it lives

One Business Entity JSON file under the integration package, listed in the application package alongside other datasources. Same Connected System systemKey as the source record entities.

Root markers that distinguish a viewpoint from a synced table entity:

source: record is local table I/O on a synced storageType: table (or omitted) entity. Do not use record on a viewpoint, and do not describe a viewpoint as local table persist.

A viewpoint is not a permanent database VIEW object and not a second synced copy of reporting data. Results are calculated when each read capability runs.

How to set

1. Design the business contract first — name the perspective (for example revenue by customer, actual cost by cost centre). Decide measures, grouping dimensions, and primary identity of each result row. The Connected System owner owns and certifies that meaning.

2. Add a new datasource file on the same Connected System. Set identity and storage:

{
  "key": "example-crm-analytics",
  "displayName": "CRM analytics",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "storageType": "view",
  "resourceType": "record",
  "syncBridge": "disabled",
  "authority": false,
  "primaryKey": ["externalId"],
  "labelKey": ["customerName"]
}

Do not add inbound sync, webhooks, or create/update/delete CIP operations on a viewpoint.

3. Declare metadataSchema and fieldMappings for the result shape only (measures and grain fields the capability returns). Do not copy every source-entity column into the viewpoint schema.

4. Declare accessControl.abac honestly — either keep applicability on this perspective with a clear rationale, or mark notApplicable when policy remains on the underlying synchronized entities and document why. Prefer the same business-dimension keys the source entities use when the viewpoint must respect regional or cost-centre scope.

5. Add CIP operations — one operation per business cut. Each enabled operation uses a read-only SELECT (or WITH … SELECT):

{
  "execution": {
    "engine": "cip",
    "cip": {
      "version": "1.0",
      "inputType": "void",
      "outputType": "records",
      "operations": {
        "revenueByCustomer": {
          "enabled": true,
          "description": "Deal revenue and count per company",
          "output": {
            "type": "object",
            "properties": {
              "customerId": { "type": "string" },
              "customerName": { "type": "string" },
              "dealCount": { "type": "number" },
              "revenue": { "type": "number" }
            }
          },
          "steps": [
            {
              "fetch": {
                "source": "viewpoint",
                "query": "SELECT c.\"id\" AS \"customerId\", c.\"name\" AS \"customerName\", COUNT(d.\"id\") AS \"dealCount\", COALESCE(SUM(CAST(NULLIF(d.\"amount\", '') AS NUMERIC)), 0) AS \"revenue\" FROM records_example_crm_companies c LEFT JOIN records_example_crm_deals d ON d.\"primaryAssociatedCompanyId\" = c.\"id\" GROUP BY c.\"id\", c.\"name\""
              }
            },
            {
              "map": {
                "useFieldMappings": false,
                "inputPath": "$.items[*]"
              }
            },
            { "output": { "mode": "records" } }
          ]
        }
      }
    }
  }
}

SQL rules at save time:

• Exactly one statement
• Read-only SELECT (or WITH … SELECT) — no insert/update/delete/DDL
• Query physical synchronized record tables for source datasources (naming follows the platform records table for each source key)
• Prefer quoted identifiers matching published attribute / column names on those tables

6. Mirror each CIP operation in capabilities[] with business-language description, riskLevel, and approvalRequired as for other read capabilities. Keep OpenAPI disabled unless your package pattern requires otherwise.

7. Register the file in the application package datasource list, then repair and validate:

aifabrix repair <systemKey> --dry-run
aifabrix repair <systemKey> --expose --rbac
aifabrix datasource validate <viewpointDatasourceKey>
aifabrix validate <systemKey>

8. Upload and certify with the Connected System ladder. Re-run governance and trust pillars when the viewpoint contract or source entities change.

Defaults and examples

Validate

1. aifabrix datasource validate <viewpointDatasourceKey> — must admit viewpoint SQL and reject mutations / sync-shaped ops.
2. aifabrix validate <systemKey> then upload with probe as for other entities.
3. Invoke each capability as a scoped subject — confirm measures and grain match the certified contract.
4. Confirm Role Assistants / MCP expose the business capability names, not SQL text.
5. Confirm records search is still used for entity lists; do not expect multi-datasource search to replace these cuts.

Common mistakes

Limits

Physical records table names, which authorization predicates the platform injects into viewpoint SQL, and bind-parameter support evolve with the platform release. Confirm behavior in your environment after validate/upload. Always keep the Connected System owner’s certified measures and grain as the business contract — the platform does not invent finance-approved KPI definitions for you.