Skip to content

The open alternative to Salesforce, designed for AI.

Add fidelity manifest fields for objects, fields and permission flags (#25265)

Weiko648a34155b20
diff --git a/packages/twenty-docs/developers/extend/apps/config/roles.mdx b/packages/twenty-docs/developers/extend/apps/config/roles.mdx
index e8dc437d7c3..39db4c7d0d8 100644
--- a/packages/twenty-docs/developers/extend/apps/config/roles.mdx
+++ b/packages/twenty-docs/developers/extend/apps/config/roles.mdx
@@ -209,4 +209,5 @@ Notes:
- Start from the scaffolded role, then progressively restrict it — the default grants broad read access, which is rarely what you want in production.
- Replace `objectPermissions` and `fieldPermissions` with the exact objects and fields your functions actually need.
- `permissionFlagUniversalIdentifiers` control access to platform-level capabilities. Keep them minimal.
+- A permission flag your app declares with `definePermissionFlag()` carries a `permissionType`: `'tool'` (the default) for a capability an agent or a user can be granted, `'settings'` for a flag that unlocks a settings area.
- See a working example: [`examples/hello-world/src/roles/default-role.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/examples/hello-world/src/roles/default-role.ts).
diff --git a/packages/twenty-docs/developers/extend/apps/data/objects.mdx b/packages/twenty-docs/developers/extend/apps/data/objects.mdx
index eb3aa2f7de9..ea250f6b10d 100644
--- a/packages/twenty-docs/developers/extend/apps/data/objects.mdx
+++ b/packages/twenty-docs/developers/extend/apps/data/objects.mdx
@@ -81,6 +81,9 @@ export default defineObject({
- The `fields` array is optional — you can define objects without custom fields.
- `openRecordIn` sets where records of this object open when clicked: `ObjectOpenRecordIn.USER_CHOICE` (the default, following each workspace member's own preference from Settings → Experience), `ObjectOpenRecordIn.SIDE_PANEL`, or `ObjectOpenRecordIn.RECORD_PAGE`. Pin it to `RECORD_PAGE` for records that need a full page to be usable, the way workflows and dashboards do, or to `SIDE_PANEL` for records that only make sense as a quick panel, the way calendar events do.
- `writability` controls who may write records of the object at all, before role permissions apply: `MetadataWritability.OPEN` (the default — workspace roles decide), `MetadataWritability.APPLICATION` (only your app's own logic functions can create, update, or delete records; use this for configuration-like objects whose records grant behavior, so workspace members with broad record access cannot edit them through the API), or `MetadataWritability.SYSTEM` (reserved for platform-managed data). Reads are unaffected — this is enforced server-side, unlike `isUIEditable`, which only hides UI affordances. It also exists per field, where it can only be stricter than the object's level.
+- `color` sets the accent color of the object in the UI. Omit it and Twenty picks one for the object.
+- `imageIdentifierFieldMetadataUniversalIdentifier` names the field whose value is shown as the record avatar. Omit it to let Twenty pick the default.
+- `isLabelSyncedWithName`, on an object or on a field, keeps the API name in sync with the label when the label is edited in Settings. It defaults to `false`, so a renamed label leaves the name untouched.
- Inline fields defined here do **not** need an `objectUniversalIdentifier` — it's inherited from the parent object. Use [`defineField()`](/developers/extend/apps/data/extending-objects) to add fields to objects you don't own.
- You can scaffold new objects with `yarn twenty dev:add object`, which guides you through naming, fields, and relationships. See [Architecture → Scaffolding entities](/developers/extend/apps/getting-started/scaffolding).
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-field-manifest-to-universal-flat-field-metadata.util.spec.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-field-manifest-to-universal-flat-field-metadata.util.spec.ts
index 60d07edc800..46389978e25 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-field-manifest-to-universal-flat-field-metadata.util.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-field-manifest-to-universal-flat-field-metadata.util.spec.ts
@@ -179,4 +179,26 @@ describe('fromFieldManifestToUniversalFlatFieldMetadata', () => {
expect(result.writability).toBe(MetadataWritability.APPLICATION);
});
});
+
+ describe('label sync', () => {
+ it('should default isLabelSyncedWithName to false', () => {
+ const result = fromFieldManifestToUniversalFlatFieldMetadata({
+ fieldManifest: buildFieldManifest({}),
+ applicationUniversalIdentifier: APP_UID,
+ now: NOW,
+ });
+
+ expect(result.isLabelSyncedWithName).toBe(false);
+ });
+
+ it('should respect an explicit isLabelSyncedWithName', () => {
+ const result = fromFieldManifestToUniversalFlatFieldMetadata({
+ fieldManifest: buildFieldManifest({ isLabelSyncedWithName: true }),
+ applicationUniversalIdentifier: APP_UID,
+ now: NOW,
+ });
+
+ expect(result.isLabelSyncedWithName).toBe(true);
+ });
+ });
});
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-object-manifest-to-universal-flat-object-metadata.util.spec.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-object-manifest-to-universal-flat-object-metadata.util.spec.ts
index e919a5cad38..88dca57d95b 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-object-manifest-to-universal-flat-object-metadata.util.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-object-manifest-to-universal-flat-object-metadata.util.spec.ts
@@ -84,4 +84,37 @@ describe('fromObjectManifestToUniversalFlatObjectMetadata', () => {
expect(result.writability).toBe(MetadataWritability.APPLICATION);
});
});
+
+ describe('fidelity properties', () => {
+ it('should default color, label sync and image identifier', () => {
+ const result = fromObjectManifestToUniversalFlatObjectMetadata({
+ objectManifest: buildObjectManifest({}),
+ applicationUniversalIdentifier: APP_UID,
+ now: NOW,
+ });
+
+ expect(result.color).toBeNull();
+ expect(result.isLabelSyncedWithName).toBe(false);
+ expect(result.imageIdentifierFieldMetadataUniversalIdentifier).toBeNull();
+ });
+
+ it('should respect explicit color, label sync and image identifier', () => {
+ const result = fromObjectManifestToUniversalFlatObjectMetadata({
+ objectManifest: buildObjectManifest({
+ color: 'blue',
+ isLabelSyncedWithName: true,
+ imageIdentifierFieldMetadataUniversalIdentifier:
+ 'image-field-universal-identifier',
+ }),
+ applicationUniversalIdentifier: APP_UID,
+ now: NOW,
+ });
+
+ expect(result.color).toBe('blue');
+ expect(result.isLabelSyncedWithName).toBe(true);
+ expect(result.imageIdentifierFieldMetadataUniversalIdentifier).toBe(
+ 'image-field-universal-identifier',
+ );
+ });
+ });
});
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-permission-flag-manifest-to-universal-flat-permission-flag.util.spec.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-permission-flag-manifest-to-universal-flat-permission-flag.util.spec.ts
new file mode 100644
index 00000000000..187b6725e20
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/__tests__/from-permission-flag-manifest-to-universal-flat-permission-flag.util.spec.ts
@@ -0,0 +1,50 @@
+import { type PermissionFlagManifest } from 'twenty-shared/application';
+
+import { fromPermissionFlagManifestToUniversalFlatPermissionFlag } from 'src/engine/core-modules/application/application-manifest/converters/from-permission-flag-manifest-to-universal-flat-permission-flag.util';
+
+const APP_UID = 'app-universal-identifier';
+const NOW = '2026-09-03T00:00:00.000Z';
+
+const buildPermissionFlagManifest = (
+ overrides: Partial<PermissionFlagManifest> = {},
+): PermissionFlagManifest => ({
+ universalIdentifier: 'permission-flag-universal-identifier',
+ key: 'EXPORT_RECORDS',
+ label: 'Export records',
+ ...overrides,
+});
+
+describe('fromPermissionFlagManifestToUniversalFlatPermissionFlag', () => {
+ it('should convert a minimal permission flag manifest as a tool flag', () => {
+ const result = fromPermissionFlagManifestToUniversalFlatPermissionFlag({
+ permissionFlagManifest: buildPermissionFlagManifest(),
+ applicationUniversalIdentifier: APP_UID,
+ now: NOW,
+ });
+
+ expect(result).toEqual({
+ universalIdentifier: 'permission-flag-universal-identifier',
+ applicationUniversalIdentifier: APP_UID,
+ key: 'EXPORT_RECORDS',
+ label: 'Export records',
+ description: null,
+ icon: null,
+ permissionType: 'tool',
+ rolePermissionFlagUniversalIdentifiers: [],
+ createdAt: NOW,
+ updatedAt: NOW,
+ });
+ });
+
+ it('should respect an explicit permission type', () => {
+ const result = fromPermissionFlagManifestToUniversalFlatPermissionFlag({
+ permissionFlagManifest: buildPermissionFlagManifest({
+ permissionType: 'settings',
+ }),
+ applicationUniversalIdentifier: APP_UID,
+ now: NOW,
+ });
+
+ expect(result.permissionType).toBe('settings');
+ });
+});
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-field-manifest-to-universal-flat-field-metadata.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-field-manifest-to-universal-flat-field-metadata.util.ts
index eea844d90ce..26664de4260 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-field-manifest-to-universal-flat-field-metadata.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-field-manifest-to-universal-flat-field-metadata.util.ts
@@ -96,7 +96,7 @@ export const fromFieldManifestToUniversalFlatFieldMetadata = ({
writability: fieldManifest.writability ?? MetadataWritability.OPEN,
isNullable: fieldManifest.isNullable ?? true,
isUnique: fieldManifest.isUnique ?? false,
- isLabelSyncedWithName: false,
+ isLabelSyncedWithName: fieldManifest.isLabelSyncedWithName ?? false,
morphId:
fieldManifest.type === FieldMetadataType.MORPH_RELATION
? (fieldManifest.morphId ?? null)
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-object-manifest-to-universal-flat-object-metadata.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-object-manifest-to-universal-flat-object-metadata.util.ts
index a204b1c70af..c46cd5384b8 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-object-manifest-to-universal-flat-object-metadata.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-object-manifest-to-universal-flat-object-metadata.util.ts
@@ -19,7 +19,7 @@ export const fromObjectManifestToUniversalFlatObjectMetadata = ({
namePlural: objectManifest.namePlural,
labelSingular: objectManifest.labelSingular,
labelPlural: objectManifest.labelPlural,
- color: null,
+ color: objectManifest.color ?? null,
openRecordIn: objectManifest.openRecordIn ?? ObjectOpenRecordIn.USER_CHOICE,
description: objectManifest.description ?? null,
icon: objectManifest.icon ?? null,
@@ -35,7 +35,7 @@ export const fromObjectManifestToUniversalFlatObjectMetadata = ({
isSearchable: objectManifest.isSearchable ?? true,
duplicateCriteria: null,
shortcut: null,
- isLabelSyncedWithName: false,
+ isLabelSyncedWithName: objectManifest.isLabelSyncedWithName ?? false,
fieldUniversalIdentifiers: [],
indexMetadataUniversalIdentifiers: [],
searchFieldMetadataUniversalIdentifiers: [],
@@ -46,7 +46,8 @@ export const fromObjectManifestToUniversalFlatObjectMetadata = ({
pageLayoutUniversalIdentifiers: [],
labelIdentifierFieldMetadataUniversalIdentifier:
objectManifest.labelIdentifierFieldMetadataUniversalIdentifier,
- imageIdentifierFieldMetadataUniversalIdentifier: null,
+ imageIdentifierFieldMetadataUniversalIdentifier:
+ objectManifest.imageIdentifierFieldMetadataUniversalIdentifier ?? null,
createdAt: now,
updatedAt: now,
};
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-permission-flag-manifest-to-universal-flat-permission-flag.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-permission-flag-manifest-to-universal-flat-permission-flag.util.ts
index e389fb19022..2acefef4688 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-permission-flag-manifest-to-universal-flat-permission-flag.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-permission-flag-manifest-to-universal-flat-permission-flag.util.ts
@@ -18,7 +18,7 @@ export const fromPermissionFlagManifestToUniversalFlatPermissionFlag = ({
label: permissionFlagManifest.label,
description: permissionFlagManifest.description ?? null,
icon: permissionFlagManifest.icon ?? null,
- permissionType: 'tool',
+ permissionType: permissionFlagManifest.permissionType ?? 'tool',
rolePermissionFlagUniversalIdentifiers: [],
createdAt: now,
updatedAt: now,
diff --git a/packages/twenty-shared/src/application/fieldManifestType.ts b/packages/twenty-shared/src/application/fieldManifestType.ts
index 6bf5fb064c3..641fb43265a 100644
--- a/packages/twenty-shared/src/application/fieldManifestType.ts
+++ b/packages/twenty-shared/src/application/fieldManifestType.ts
@@ -24,6 +24,7 @@ type BaseRegularFieldManifest<
isUIEditable?: boolean;
writability?: MetadataWritability;
isUnique?: boolean;
+ isLabelSyncedWithName?: boolean;
objectUniversalIdentifier: string;
};
diff --git a/packages/twenty-shared/src/application/objectManifestType.ts b/packages/twenty-shared/src/application/objectManifestType.ts
index fe31ef94e10..9ad99422d31 100644
--- a/packages/twenty-shared/src/application/objectManifestType.ts
+++ b/packages/twenty-shared/src/application/objectManifestType.ts
@@ -10,6 +10,8 @@ export type ObjectManifest = SyncableEntityOptions & {
labelPlural: string;
description?: string;
icon?: string;
+ color?: string | null;
+ isLabelSyncedWithName?: boolean;
isSearchable?: boolean;
// When false, the generic UI shows no affordance to create records of this object
isUICreatable?: boolean;
@@ -19,4 +21,5 @@ export type ObjectManifest = SyncableEntityOptions & {
openRecordIn?: ObjectOpenRecordIn;
fields: ObjectFieldManifest[];
labelIdentifierFieldMetadataUniversalIdentifier: string;
+ imageIdentifierFieldMetadataUniversalIdentifier?: string | null;
};
diff --git a/packages/twenty-shared/src/application/permissionFlagManifestType.ts b/packages/twenty-shared/src/application/permissionFlagManifestType.ts
index 8651e94a0ed..bf2f98d7b04 100644
--- a/packages/twenty-shared/src/application/permissionFlagManifestType.ts
+++ b/packages/twenty-shared/src/application/permissionFlagManifestType.ts
@@ -7,4 +7,5 @@ export type PermissionFlagManifest = SyncableEntityOptions & {
label: string;
description?: string | null;
icon?: string | null;
+ permissionType?: PermissionFlagPermissionType;
};