DataEntity — public data resource

What it is#

A projection of a dictionary or document outward as an OData resource (/odata/{PublicCollectionName}, $metadata/$filter/$select/CRUD). It is not a web service (POST /api/rest/{Name}), but a full readable/writable collection with its own source-field mapping, hooks, and access rights. There is exactly one primary source: an object of kind Dictionary or Document.

From inside a script, the same contract is called through the data entity manager, not directly through raw data or dictionary managers — only the data entity manager runs the source mapping and RLS.

JSON envelope#

DataEntities/<Name>/<Name>.dataentity.json (object + sources + fields) + Events/<Name>EventHandler.script.json + Events/<Name>EventHandler.cs (event code) — the same pair convention as for a dictionary:

{
  "kind": "DataEntity",
  "object": {
    "caption": { "en": "Customers v2", "ru": "Клиенты v2" },
    "publicCollectionName": "<PublicCollectionName>",
    "primarySourceType": "Dictionary",
    "primarySourceMetaId": "<GUID Dictionary Customer>",
    "requireExplicitRoles": true,
    "isActive": true,
    "metaId": "<GUID DataEntity>", "name": "<Name>", "modelId": "<GUID Model>"
  },
  "fields": [
    {
      "dataEntityMetaId": "<GUID DataEntity>",
      "fieldName": "ID",
      "sourceFieldName": "MetaId",
      "isKey": true,
      "metaId": "<GUID Field>", "name": "ID", "modelId": "<GUID Model>"
    },
    {
      "dataEntityMetaId": "<GUID DataEntity>",
      "fieldName": "Name",
      "sourceFieldName": "Name",
      "isComputed": false,
      "metaId": "<GUID Field>", "name": "Name", "modelId": "<GUID Model>"
    }
  ]
}

A field is either a mapping to a source column (sourceFieldName) or isComputed: true (the value is computed by MapFromSource in code and is not read directly from the table). The key is isKey, usually on the source MetaId. requireExplicitRoles: true means an empty role matrix does not publish the collection outward by default (see zuloone-new-data-entity §4).

C# base#

<Name>EventHandler : TypedDataEntityEventHandler<Name> — the base is declared manually; it overrides MapFromSource/MapToSource (translation between the source line and the projection line in both directions), plus the normal write hooks.

Events / Chain of Command#

The same CoC pattern as for Dictionary: the owner is the handler in the data entity's own model (link 0, does not call next); an extension from another model uses [ExtensionOf] + next in every override. The explicit-role flag applies only to HTTP /odata — a script that calls the data entity manager from inside the platform does not have to have a grant on the entity. The manager does not bypass RLS of the source table for HTTP or for scripts.

Example#

A typical projection of the Customer dictionary has a computed field and explicit roles; a call from another script uses the public collection name, a filter such as ID eq 'C-100', and no typed POCO.