Files
twenty/packages/twenty-server/test/integration/rest/utils/view-rest-api.util.ts
T
Paul Rastoin 0c545bcdeb [BREAKING-CHANGE] Centralize system View viewField side effect (#23081)
# Introduction

Closes https://github.com/twentyhq/core-team-issues/issues/2669

Part of the `isSystemSideEffect` engine-ownership effort. Until now, a
custom object's default **INDEX** table view (`All {objectLabelPlural}`)
and its view fields were built imperatively in `ObjectMetadataService`
with random `v4()` identifiers, while `twenty-standard` authored its own
copies with hardcoded literals. The two never converged, an object
rename could drift the view, and nothing marked these rows as
engine-owned.

This PR makes the metadata side-effect engine the **single owner** of
the INDEX view and its view fields, on name-free deterministic
identifiers, for custom and standard objects alike.

## Core design

- **Name-free deterministic identity.** The INDEX view identifier
derives from `object identifier + ViewKey.INDEX`
(`getSystemViewUniversalIdentifier`); each view-field identifier derives
from `view identifier + field identifier`
(`getViewFieldUniversalIdentifier`). An object rename (with a pinned
object identifier) keeps the same view, losslessly.
- **`isSystemSideEffect: true` is provenance.** Every INDEX view / view
field the engine emits is flagged system-owned, so manifest deletion
inference never drops it. The flag follows the view: a view field
inherits its parent view's flag.
- **The engine is the sole owner of the INDEX view.** It always emits
it; a caller providing one with the same derived identifier is a genuine
conflict surfaced by the engine's reserved-identifier collision, not
silently deferred.

## Changes

### Shared (`twenty-shared`)

- `getIndexViewUniversalIdentifier` →
`getSystemViewUniversalIdentifier`, now taking a `viewKey` (generalizes
to any singleton engine-owned view).
- Standard field identifiers extracted into a new
`STANDARD_OBJECT_FIELDS` constant, so both an object's `fields` and its
INDEX view read the same field identifiers.
- `buildStandardObjectIndexView` derives the standard INDEX view +
view-field identifiers from `STANDARD_OBJECT_FIELDS`, replacing the
hardcoded literals in `standard-object.constant.ts`.

### Metadata side-effect engine (custom objects)

- **`objectSystemFieldsAndIndexViewOnCreate`** (replaces
`objectSystemFieldsOnCreate`): on object creation, provisions the 7
reserved system fields **and** the INDEX view with one view field per
displayable system field, all `isSystemSideEffect: true`.
- **`fieldIndexViewFieldOnCreate`** (new): on field creation, provisions
the field's INDEX view field. Object created in the same batch →
visible, positioned before the system view fields; pre-existing object →
hidden, appended (preserving the historical `createOneField` behavior).
Both branches resolve the INDEX view by its derived identifier (single
map access, never a scan).
- **`fieldSystemViewFieldsOnDelete`** (new): on field deletion,
cascade-deletes every engine-owned view field displaying it.
- **`objectSystemSideEffectsOnDelete`** (extended): now also
cascade-deletes the object's engine-owned views and their view fields
(in addition to system fields, indexes, searchFieldMetadata). Every
lookup walks a foreign-key aggregator down from the deleted object, so
the work is proportional to what the object owns, never to workspace
size.
- Object-create and field-create positions are derived from the same
caller-input field list, so the INDEX view layout is contiguous with no
handler-ordering dependency.
- `view` / `viewField` added to the side-effect companion metadata names
for `fieldMetadata` and `objectMetadata`.

### Reserved-identifier invariant

A caller can never define an entity whose identifier collides with one a
system side effect produces: caller inputs are forced
`isSystemSideEffect: false` at every entry point (API and app-manifest
transpilers), and the engine raises
`RESERVED_SYSTEM_UNIVERSAL_IDENTIFIER`, aborting the operation, when a
system emission lands on a caller-claimed identifier. Covered by a new
engine-level test.

### Caller-side provisioning removed

The imperative INDEX view + view-field provisioning is removed from
`ObjectMetadataService.createOneObject`. The record-page `FIELDS_WIDGET`
view is intentionally left caller-side and deferred to the follow-up
(see below).

### `twenty-standard` convergence

Standard INDEX views and their view fields converge on the same
derived-identifier + `isSystemSideEffect: true` scheme as the engine.
`twenty-standard` syncs through the from/to migration path (which never
runs the side-effect engine), so it authors this INDEX surface itself,
matching what the engine produces for custom objects.

## Rollout

Two `2.26.0` workspace commands, running after the `2.25`
messageCampaign commands:

- `upgrade:2-26:reconcile-index-view-universal-identifier` re-owns the
INDEX views of the **twenty-standard and workspace-custom applications**
and all their view fields to the derived identifiers with
`isSystemSideEffect: true`, in a single per-workspace transaction. Each
view field identifier is keyed on the application of the **displayed
field** (an app or user column on a standard INDEX view converges too).
Soft-deleted views and view fields are skipped: one can coexist with an
active successor on the same derivation inputs and both would derive the
same identifier. Children reference the view by primary key, so the
re-own is lossless.
- `upgrade:2-26:demote-and-backfill-application-index-view` handles
**manifest-installed applications**, which never had their INDEX view
auto-provisioned: every caller-authored INDEX view of another
application is demoted to `key: null` (a plain additional view under its
manifest identifier), then every application object gets the
engine-owned INDEX view and its full view-field layout backfilled
through the migration pipeline's legacy path (no side-effect expansion),
views committed before view fields across applications since a view
field belongs to the application owning its field. Idempotent and
retry-safe: engine-owned INDEX views are neither demoted nor
re-backfilled, and view creation and view-field creation are gated
independently, so a retry after a partial failure still backfills the
missing view fields of an already-committed view.

Both support `--dry-run` and invalidate the full flat-maps closure
(parents aggregate the re-owned identifiers, children resolve them as
universal foreign keys, and page-layout widget universal configurations
resolve view PKs at cache-build time).

The `2.25` `upgrade:2-25:add-message-campaign-name-field` command is
adapted to resolve the campaign INDEX view by its INDEX key on the
object instead of by universal identifier: it now runs before the
reconcile, on workspaces still holding legacy identifiers.

## ⚠️ Breaking change

This PR **mutates 187 previously hardcoded universal identifiers** — the
standard objects' INDEX views and their view fields (the literals
removed from `standard-object.constant.ts`), now derived.

- **Handled by the `2.26` commands above** for all existing workspaces.
- **The INDEX key is now engine-reserved.** The flat view validator
rejects caller-created INDEX views (API and manifest inputs are forced
`isSystemSideEffect: false`) and enforces a single non-deleted INDEX
view per object; `view.key` is no longer a comparable/updatable
property, so no writer can promote or demote a view after creation.
`ViewManifest.key` is deprecated and ignored (manifest views are always
additional views, so old apps keep syncing and demoted views are not
promoted back); the REST/GraphQL create path now rejects `key: INDEX`.
In-repo example apps (`hello-world`, `document-generator`) no longer
declare it.
- **12 declared-but-never-seeded standard INDEX view field identifiers
deleted** (the former `preservedViewFields` on `timelineActivity`,
`workflowRun` and `workspaceMember`): after the reconcile, no workspace
row references them.
- **`computeFlatViewFieldsToCreate` now derives view field identifiers**
instead of drawing `v4()` ones, which also changes what the committed
`1-23` record-page backfill produces going forward (deliberate,
documented in-code).
- **Record-page views and view fields are not affected** (identifiers
unchanged).
- **In-repo apps: `twenty-last-contact` updated.** It was the only app
declaring explicit INDEX view fields (10 columns across `allPeople` /
`allCompanies` / `allOpportunities`) through manifest `viewFields`.
Those target identifiers are now engine-owned and derived, so the
manifest inputs no longer resolve and install failed with `View not
found`. The app now declares only its fields; the engine's
`fieldIndexViewFieldOnCreate` provisions the matching INDEX view field
automatically. No other app under `packages/twenty-apps` references any
of the 187 mutated identifiers, and apps that target standard views
point at record-page views (e.g. `real-estate` →
`opportunityRecordPageFields`) or their own objects (`twenty-partners`),
all unchanged.

### Loss of granularity for app maintainers

The engine now owns the INDEX view field of every field a caller adds to
an object, so app maintainers lose direct control over those columns.
Previously an app could target the engine-owned INDEX view with an
explicit manifest `viewField` and set its `position` and `isVisible`.
Now `fieldIndexViewFieldOnCreate` appends a **hidden** view field in
caller-input order on field creation, so:

- Columns an app previously showed at a **dedicated position** and
**visible** (e.g. `twenty-last-contact`'s last-contact columns) become
**hidden** and **appended in input order** after install.
- There is currently **no manifest way to override** the
engine-provisioned INDEX view field's position, visibility, or size.

This is a deliberate regression accepted for the sake of
single-ownership, and app maintainers should expect their INDEX columns
to move/hide after upgrading. A follow-up override API will let
maintainers reclaim per-field control over the engine-provisioned INDEX
view field.

## Testing

- Unit specs for each handler: object create (system fields + INDEX
view/view fields, override, position offset), field create (same-batch
vs existing-object, non-displayable noop, no-INDEX-view noop), field
delete, object delete (fields/indexes/searchFieldMetadata/views/view
fields cascade, reverse-relation view field on another object).
- Engine-level test for the reserved-identifier collision.
- `twenty-standard` guard test that its INDEX views/view fields stay on
the derived scheme and stay system-owned.
- Integration test: full engine provisioning of the INDEX view/view
fields on object creation, same view id preserved across an object
rename, and cascade delete on object deletion.

## Follow-up

The full record-page stack (record-page view, its view fields, view
field groups, page layout / tab / widget) is still built imperatively
and moves into the engine in
https://github.com/twentyhq/core-team-issues/issues/2721.
2026-07-29 13:32:21 +00:00

295 lines
7.9 KiB
TypeScript

import { makeRestAPIRequest } from 'test/integration/rest/utils/make-rest-api-request.util';
import { generateRecordName } from 'test/integration/utils/generate-record-name';
import {
ViewOpenRecordIn,
ViewType,
ViewVisibility,
} from 'twenty-shared/types';
import { type ViewFieldEntity } from 'src/engine/metadata-modules/view-field/entities/view-field.entity';
import { type ViewFilterGroupEntity } from 'src/engine/metadata-modules/view-filter-group/entities/view-filter-group.entity';
import { type ViewFilterEntity } from 'src/engine/metadata-modules/view-filter/entities/view-filter.entity';
import { type ViewGroupEntity } from 'src/engine/metadata-modules/view-group/entities/view-group.entity';
import { type ViewSortEntity } from 'src/engine/metadata-modules/view-sort/entities/view-sort.entity';
import { type ViewEntity } from 'src/engine/metadata-modules/view/entities/view.entity';
export const findViewByIdWithRestApi = async (
viewId: string,
): Promise<ViewEntity | null> => {
const response = await makeRestAPIRequest({
method: 'get',
path: `/metadata/views/${viewId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status === 404) {
return null;
}
return response.body;
};
export const findViewFilterWithRestApi = async (
viewFilterId: string,
): Promise<ViewFilterEntity | null> => {
const response = await makeRestAPIRequest({
method: 'get',
path: `/metadata/viewFilters/${viewFilterId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status === 404) {
return null;
}
return response.body;
};
export const createTestViewWithRestApi = async (
params: {
objectMetadataId: string;
} & Partial<Omit<ViewEntity, 'objectMetadataId'>>,
): Promise<ViewEntity> => {
const { objectMetadataId, name, ...restParams } = params;
const viewData = {
name: name || generateRecordName('Test View'),
objectMetadataId,
icon: 'IconTable',
type: ViewType.TABLE,
key: null,
position: 0,
isCompact: false,
openRecordIn: ViewOpenRecordIn.SIDE_PANEL,
visibility: ViewVisibility.WORKSPACE,
...restParams,
};
const response = await makeRestAPIRequest({
method: 'post',
path: '/metadata/views',
body: viewData,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status !== 201) {
throw new Error(
`Failed to create test view: ${response.status} - ${JSON.stringify(response.body)}`,
);
}
return response.body;
};
export const createTestViewFieldWithRestApi = async (
params: {
viewId: string;
fieldMetadataId: string;
} & Partial<Omit<ViewFieldEntity, 'viewId' | 'fieldMetadataId'>>,
): Promise<ViewFieldEntity> => {
const { viewId, fieldMetadataId, ...restParams } = params;
const viewFieldData = {
viewId,
fieldMetadataId,
position: 0,
isVisible: true,
size: 150,
...restParams,
};
const response = await makeRestAPIRequest({
method: 'post',
path: '/metadata/viewFields',
body: viewFieldData,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status !== 201) {
throw new Error(
`Failed to create test view field: ${response.status} - ${JSON.stringify(response.body)}`,
);
}
return response.body;
};
export const createTestViewFilterWithRestApi = async (
params: {
viewId: string;
fieldMetadataId: string;
} & Partial<Omit<ViewFilterEntity, 'viewId' | 'fieldMetadataId'>>,
): Promise<ViewFilterEntity> => {
const { viewId, fieldMetadataId, operand, value, ...restParams } = params;
const viewFilterData = {
viewId,
fieldMetadataId,
operand: operand || 'Is',
value: value || 'test-value',
...restParams,
};
const response = await makeRestAPIRequest({
method: 'post',
path: '/metadata/viewFilters',
body: viewFilterData,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status !== 201) {
throw new Error(
`Failed to create test view filter: ${response.status} - ${JSON.stringify(response.body)}`,
);
}
return response.body;
};
export const createTestViewSortWithRestApi = async (
params: {
viewId: string;
fieldMetadataId: string;
} & Partial<Omit<ViewSortEntity, 'viewId' | 'fieldMetadataId'>>,
): Promise<ViewSortEntity> => {
const { viewId, fieldMetadataId, direction, ...restParams } = params;
const viewSortData = {
viewId,
fieldMetadataId,
direction: direction || 'ASC',
...restParams,
};
const response = await makeRestAPIRequest({
method: 'post',
path: '/metadata/viewSorts',
body: viewSortData,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status !== 201) {
throw new Error(
`Failed to create test view sort: ${response.status} - ${JSON.stringify(response.body)}`,
);
}
return response.body;
};
export const createTestViewGroupWithRestApi = async (
params: {
viewId: string;
fieldMetadataId: string;
} & Partial<Omit<ViewGroupEntity, 'viewId' | 'fieldMetadataId'>>,
): Promise<ViewGroupEntity> => {
const { viewId, fieldMetadataId, fieldValue, ...restParams } = params;
const viewGroupData = {
viewId,
fieldMetadataId,
isVisible: true,
fieldValue: fieldValue || 'test-group-value',
position: 0,
...restParams,
};
const response = await makeRestAPIRequest({
method: 'post',
path: '/metadata/viewGroups',
body: viewGroupData,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status !== 201) {
throw new Error(
`Failed to create test view group: ${response.status} - ${JSON.stringify(response.body)}`,
);
}
return response.body;
};
export const createTestViewFilterGroupWithRestApi = async (
params: {
viewId: string;
} & Partial<Omit<ViewFilterGroupEntity, 'viewId'>>,
): Promise<ViewFilterGroupEntity> => {
const { viewId, logicalOperator, ...restParams } = params;
const viewFilterGroupData = {
viewId,
logicalOperator: logicalOperator || 'AND',
...restParams,
};
const response = await makeRestAPIRequest({
method: 'post',
path: '/metadata/viewFilterGroups',
body: viewFilterGroupData,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
});
if (response.status !== 201) {
throw new Error(
`Failed to create test view filter group: ${response.status} - ${JSON.stringify(response.body)}`,
);
}
return response.body;
};
export const deleteTestViewWithRestApi = async (
viewId: string,
): Promise<void> => {
await makeRestAPIRequest({
method: 'delete',
path: `/metadata/views/${viewId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
}).catch(() => {});
};
export const deleteTestViewFieldWithRestApi = async (
viewFieldId: string,
): Promise<void> => {
await makeRestAPIRequest({
method: 'delete',
path: `/metadata/viewFields/${viewFieldId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
}).catch(() => {});
};
export const deleteTestViewFilterWithRestApi = async (
viewFilterId: string,
): Promise<void> => {
await makeRestAPIRequest({
method: 'delete',
path: `/metadata/viewFilters/${viewFilterId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
}).catch(() => {});
};
export const deleteTestViewSortWithRestApi = async (
viewSortId: string,
): Promise<void> => {
await makeRestAPIRequest({
method: 'delete',
path: `/metadata/viewSorts/${viewSortId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
}).catch(() => {});
};
export const deleteTestViewGroupWithRestApi = async (
viewGroupId: string,
): Promise<void> => {
await makeRestAPIRequest({
method: 'delete',
path: `/metadata/viewGroups/${viewGroupId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
}).catch(() => {});
};
export const deleteTestViewFilterGroupWithRestApi = async (
viewFilterGroupId: string,
): Promise<void> => {
await makeRestAPIRequest({
method: 'delete',
path: `/metadata/viewFilterGroups/${viewFilterGroupId}`,
bearer: APPLE_JANE_ADMIN_ACCESS_TOKEN,
}).catch(() => {});
};