Transferring a Schema

Schema transfer lets you export entity type definitions from one organization and import them into another. This moves the structure — entity types, field groups, fields, and nested entity types — without moving the record data.

Schema transfer is useful when:

Setting up a new organization that should start with the same entity types as an existing one.
Promoting a configuration from a test environment to production.
Sharing a standard set of entity types across organizations.

What is transferred

A schema export includes:

Entity type definitions — name, machine name, description, super type.
Field groups — name, machine name, display order.
Fields — name, machine name, data type, required flag, unique flag, description, type-specific configuration (date precision, link target, expression text, generic settings).
Nested entity types and their field groups and fields.

A schema export does not include:

Record data (the actual documents, directory entries, or counterparty records).
Permissions (field-level or entity-type-level grants).
Templates attached to document or report types.
Business process definitions.

Super type coverage

Schema transfer covers six of the eight super types:

Document
Counterparty
Directory
Task
Report
Price List

Proposal types and Employee Group types cannot be transferred through schema import/export. These two super types must be recreated manually on the target organization.

Exporting entity definitions

To export, open the Entities section and choose Export definitions. Select the entity types you want to include and choose the file format:

XLSX: An Excel workbook with one sheet per entity type. Entity type names longer than 31 characters are truncated in sheet names (an Excel limitation).
JSON: A JSON file containing the full definition structure.

The export includes only custom entity types. Built-in system types are excluded.

Importing entity definitions

To import, open the Entities section and choose Import definitions. Upload the export file (XLSX or JSON, up to 10 MB), then choose an import mode.

Import modes

Mode	Behavior
Create only (default)	Creates entity types and fields that do not yet exist on the target organization. Skips any entity type whose machine name already exists — no changes are made to existing types.
Merge	Creates entity types and fields that do not yet exist. For entity types that already exist, adds new fields and updates existing fields (by machine name match), but never deletes fields that are present on the target but absent from the import file.
Overwrite	Fully replaces existing entity types with the imported definitions. Fields and nested entity types that are present on the target but absent from the import file are deleted. New fields are added, and existing fields are updated.

Mode

Behavior

Create only (default)

Creates entity types and fields that do not yet exist on the target organization. Skips any entity type whose machine name already exists — no changes are made to existing types.

Merge

Creates entity types and fields that do not yet exist. For entity types that already exist, adds new fields and updates existing fields (by machine name match), but never deletes fields that are present on the target but absent from the import file.

Overwrite

Fully replaces existing entity types with the imported definitions. Fields and nested entity types that are present on the target but absent from the import file are deleted. New fields are added, and existing fields are updated.

The Overwrite mode deletes fields and nested entity types that are not in the import file. If the export file is outdated or incomplete, this can remove fields that are in active use on the target. Always review the dry-run results before confirming an overwrite import.

Dry-run validation

Before applying changes, the import runs a dry-run validation. The dry run parses the uploaded file, validates every entity type and field machine name, and returns a detailed diff showing what will happen for each entity type and each field:

Created — a new entity type or field will be added.
Updated — an existing field will be modified.
Deleted — a field or nested entity type will be removed (Overwrite mode only).
Unchanged — the definition matches what already exists.
Skipped — the entity type already exists (Create only mode).

The dry run also reports validation errors — invalid machine names, unsupported super types, malformed files, or files exceeding the size limit.

Review the dry-run results carefully. Once you confirm the import, the system applies the changes using the same logic as the dry run.

Machine name validation on import

Imported machine names are validated against the same rules as manually created ones:

Must start with a letter and contain only letters, digits, and underscores.
Must not collide with existing machine names on the target organization (unless the import mode is Merge or Overwrite and the collision is an intentional match).
Must not use a reserved system name.

Schema transfer versus data import

Schema transfer and data import are separate features:

Aspect	Schema transfer	Data import
What it moves	Entity type definitions (structure)	Record data (rows)
Scope	Six of eight super types	Counterparties, digital displays, printed displays only
Dry-run	Yes — detailed per-field diff	No
Format	XLSX or JSON	XLSX template

Aspect

Schema transfer

Data import

What it moves

Entity type definitions (structure)

Record data (rows)

Scope

Six of eight super types

Counterparties, digital displays, printed displays only

Dry-run

Yes — detailed per-field diff

Format

XLSX or JSON

XLSX template

See importing data for the record-level import feature.