Entity System

CityScreen Deals ships with fixed product features — deals, proposals, inventory, pricing — that work the same way in every organization. Everything else — document kinds, counterparty types, custom fields, catalog directories, task definitions, report structures — is defined by each organization’s administrator using the entity system.

The entity system is the mechanism that makes this possible. It lets an administrator create new kinds of business records, give them fields, and put them to work in the product — all without a code release.

How it works

The entity system has three levels:

Entity type

A schema that defines a kind of record. An administrator creates an entity type by giving it a name, a machine name, and a set of fields organized into groups.

Each entity type belongs to exactly one super type (see The eight super types below). The super type determines where records of that type appear in the interface, what product behavior applies to them, and what other features can reference them.

Data type (field)

A field on an entity type. Each field has a name, a machine name, a value type (string, number, date, link, set, collection, map, or expression), and behavior flags (required, unique).

The interface calls a field a "data type." The REST API calls it a variable. This documentation uses "data type" when referring to what the interface shows and "field" as the general term.

Record

One instance of an entity type, with values for each of its fields. When a user creates a new document, a new counterparty, or a new directory entry, they are creating a record of the corresponding entity type.

This three-level structure — type, field, record — repeats across every configurable area of the product.

The eight super types

Every entity type belongs to one of eight super types. The super type is chosen when the entity type is created and cannot be changed afterward.

Super type	What it drives
Document	Business documents — invoices, contracts, booking orders, credit notes, or any other document kind the organization needs. Document types support custom fields, nested entities, templates, and business processes.
Counterparty	Business partner records beyond the built-in customer. Agencies, media owners, subcontractors, or any other party the organization works with. Counterparty types support custom fields and nested entities.
Directory	General-purpose reference and lookup lists. A directory type can represent anything the organization needs to track as structured data — catalog items, regions, service categories, equipment registers. Directory types support custom fields and nested entities.
Task	Task definitions used by the process automation engine. When a business process reaches a user-task step, the engine creates a task whose fields are defined by the corresponding task entity type. Task types support custom fields and nested entities.
Proposal	Proposal type definitions. Each proposal type configures how a proposal is priced and what inventory it sells against. Proposal types support custom fields and nested entities but cannot be transferred through schema import/export.
Price List	Price list type definitions. Price list types configure which sale rules are available for pricing. Price list types do not support custom fields or nested entities.
Report	Report type definitions. A report type points at a source entity type and a template file; the system generates one document per record from that combination. Report types do not support custom fields or nested entities.
Employee Group	Employee group type definitions. Employee group types support custom fields but cannot be transferred through schema import/export.

Super type

What it drives

Document

Business documents — invoices, contracts, booking orders, credit notes, or any other document kind the organization needs. Document types support custom fields, nested entities, templates, and business processes.

Counterparty

Business partner records beyond the built-in customer. Agencies, media owners, subcontractors, or any other party the organization works with. Counterparty types support custom fields and nested entities.

What you can do with entity types

Create a new entity type with a display name, a machine name, and fields organized into groups.
Edit an existing entity type — rename it, add or remove fields, reorder groups and fields.
Archive an entity type to hide it from creation pickers without deleting existing records. Archived types no longer appear as targets for new link fields, but records already created under the type remain accessible.
Delete an entity type permanently. Built-in system types cannot be deleted.

Each of these operations is covered in entity types.

Where entity types appear in the product

Entity types are not an isolated administration feature. They surface throughout CityScreen Deals wherever the product needs a configurable record:

Document records — every document kind is an entity type belonging to the Document super type.
Counterparties — every counterparty kind is an entity type belonging to the Counterparty super type.
Proposals — every proposal type is an entity type belonging to the Proposal super type.
User tasks — every task definition is an entity type belonging to the Task super type.
Dashboards, batch reports, and criteria all interact with entity types as data sources or classification targets.

When a page in this documentation describes a feature whose visible shape depends on what the administrator has configured, it links back here.

Pages in this section

Entity types: Creating, editing, archiving, and deleting entity types — including field groups, ordering, and the implications of deleting a field.
Data types: The nine data types available for fields, with their options.
Nested entities: Repeating-row structures inside an entity type — line items, sub-records, and tabular data.
Expressions: Computed fields that derive their value from other fields — dot-path references, JavaScript expressions, and auto-fill on link selection.
Field permissions: Per-field access control with Own, Group, and Any scopes, and how field permissions compose with role permissions.
Columns and filters: Controlling which fields appear as list columns, building filters, and working with system variables.
Transferring a schema: Exporting and importing entity type definitions across organizations or environments.