Skip to content

The open alternative to Salesforce, designed for AI.

Let app manifests declare related record paths (#29328)

Charles Bochetf2fdd27297a5
diff --git a/packages/twenty-agent-skills/references/develop-app/data-model.md b/packages/twenty-agent-skills/references/develop-app/data-model.md
index 6f0c71a4985..544206d1e49 100644
--- a/packages/twenty-agent-skills/references/develop-app/data-model.md
+++ b/packages/twenty-agent-skills/references/develop-app/data-model.md
@@ -122,6 +122,7 @@ When adding permissions:
- Check whether the app introduces side effects through logic functions before granting write access.
- To keep some permissions from being granted on an object, set `disabledObjectPermissionActions` on `defineObject()`, for example `['canDestroyObjectRecords']`. Allowed values are the object permission flags: `'canReadObjectRecords'`, `'canUpdateObjectRecords'`, `'canSoftDeleteObjectRecords'` and `'canDestroyObjectRecords'`. Users, API keys and agents never get these actions on that object, whatever their role grants; the app's own logic functions keep them. List the update, soft-delete and destroy flags to make an object only the app can write.
- To do the same on one field, set `disabledFieldPermissionActions` on the field, with `'canReadFieldValue'` and/or `'canUpdateFieldValue'`. `['canUpdateFieldValue']` makes a field only the app can write, which suits values the app computes or syncs.
+- To extend access from a record to its related records, declare a related record path with `defineRelatedRecordPath()`: an `objectUniversalIdentifier`, then `firstFieldMetadataUniversalIdentifier` and optionally `secondFieldMetadataUniversalIdentifier` and `thirdFieldMetadataUniversalIdentifier`, each a relation field on the object the previous hop reached. Set `isInherent: true` for records that belong to their parent (attachments, timeline activities): those follow whenever the parent is readable. Leave it unset for paths that should apply only when the role grants the starting object directly. Convention: `src/related-record-paths/`. Paths are in preview: they sync, but record permissions don't use them yet, and once enforced they require the Organization plan or above, like row-level security.
## Verification
diff --git a/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap b/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap
index 7006c711ca7..928bc60c26d 100644
--- a/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap
+++ b/packages/twenty-cli/src/app/manifest/__tests__/__snapshots__/manifest-fixtures.spec.ts.snap
@@ -24,6 +24,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"pageLayouts": [],
"permissionFlags": [],
"publicAssets": [],
+ "relatedRecordPaths": [],
"roles": [
"my.role.ts",
],
@@ -88,6 +89,7 @@ The scripts invoke that local build directly, so the SDK binary cannot shadow it
"pageLayouts": [],
"permissionFlags": [],
"publicAssets": [],
+ "relatedRecordPaths": [],
"roles": [
{
"canBeAssignedToAgents": false,
@@ -161,6 +163,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"pageLayouts": [],
"permissionFlags": [],
"publicAssets": [],
+ "relatedRecordPaths": [],
"roles": [
"my.role.ts",
],
@@ -253,6 +256,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"pageLayouts": [],
"permissionFlags": [],
"publicAssets": [],
+ "relatedRecordPaths": [],
"roles": [
{
"canBeAssignedToAgents": false,
@@ -350,6 +354,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"publicAssets": [
"public/favicon.png",
],
+ "relatedRecordPaths": [],
"roles": [
"src/roles/default-function.role.ts",
"src/root.role.ts",
@@ -1167,6 +1172,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"fileType": "png",
},
],
+ "relatedRecordPaths": [],
"roles": [
{
"canBeAssignedToAgents": false,
@@ -1439,6 +1445,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"pageLayouts": [],
"permissionFlags": [],
"publicAssets": [],
+ "relatedRecordPaths": [],
"roles": [
"my.role.ts",
],
@@ -1496,6 +1503,7 @@ exports[`CLI manifest fixtures and worker transport > matches the manifest, file
"pageLayouts": [],
"permissionFlags": [],
"publicAssets": [],
+ "relatedRecordPaths": [],
"roles": [
{
"canBeAssignedToAgents": false,
diff --git a/packages/twenty-cli/src/app/manifest/manifest-build.ts b/packages/twenty-cli/src/app/manifest/manifest-build.ts
index 33778d94cee..c7dad039efe 100644
--- a/packages/twenty-cli/src/app/manifest/manifest-build.ts
+++ b/packages/twenty-cli/src/app/manifest/manifest-build.ts
@@ -41,6 +41,7 @@ import {
type CommandMenuItemManifest,
type ConnectionProviderManifest,
type McpServerManifest,
+ type RelatedRecordPathManifest,
type MessagingProviderManifest,
type FieldManifest,
type FrontComponentManifest,
@@ -117,6 +118,7 @@ export const buildManifest = async (
const connectionProviders: ConnectionProviderManifest[] = [];
const messagingProviders: MessagingProviderManifest[] = [];
const mcpServers: McpServerManifest[] = [];
+ const relatedRecordPaths: RelatedRecordPathManifest[] = [];
const logicFunctions: LogicFunctionManifest[] = [];
const frontComponents: FrontComponentManifest[] = [];
const publicAssets: AssetManifest[] = [];
@@ -151,6 +153,7 @@ export const buildManifest = async (
const connectionProvidersFilePaths: string[] = [];
const messagingProvidersFilePaths: string[] = [];
const mcpServersFilePaths: string[] = [];
+ const relatedRecordPathsFilePaths: string[] = [];
const logicFunctionsFilePaths: string[] = [];
const frontComponentsFilePaths: string[] = [];
const publicAssetsFilePaths: string[] = [];
@@ -315,6 +318,18 @@ export const buildManifest = async (
mcpServersFilePaths.push(relativePath);
break;
}
+ case 'relatedRecordPaths': {
+ const extract =
+ await extractManifestFromFile<RelatedRecordPathManifest>({
+ appPath,
+ filePath,
+ });
+ relatedRecordPaths.push(extract.config);
+ errors.push(...extract.errors);
+ warnings.push(...(extract.warnings ?? []));
+ relatedRecordPathsFilePaths.push(relativePath);
+ break;
+ }
case 'logicFunctions': {
const extract = await extractManifestFromFile<LogicFunctionConfig>({
appPath,
@@ -750,6 +765,7 @@ export const buildManifest = async (
commandMenuItems: commandMenuItems.sort(byId),
timelineActivityTypes: timelineActivityTypes.sort(byId),
settingsMenuItems: settingsMenuItems.sort(byId),
+ relatedRecordPaths: relatedRecordPaths.sort(byId),
};
const entityFilePaths: EntityFilePaths = {
@@ -765,6 +781,7 @@ export const buildManifest = async (
connectionProviders: connectionProvidersFilePaths,
messagingProviders: messagingProvidersFilePaths,
mcpServers: mcpServersFilePaths,
+ relatedRecordPaths: relatedRecordPathsFilePaths,
logicFunctions: logicFunctionsFilePaths,
frontComponents: frontComponentsFilePaths,
publicAssets: publicAssetsFilePaths,
diff --git a/packages/twenty-cli/src/app/pull/__tests__/build-pull-entities.spec.ts b/packages/twenty-cli/src/app/pull/__tests__/build-pull-entities.spec.ts
index d289b3e14fb..637b7ee72ad 100644
--- a/packages/twenty-cli/src/app/pull/__tests__/build-pull-entities.spec.ts
+++ b/packages/twenty-cli/src/app/pull/__tests__/build-pull-entities.spec.ts
@@ -1029,6 +1029,32 @@ describe('buildPullEntities', () => {
expect(pathOf('skill')).toBe('src/skills/grooming-tips.skill.ts');
});
+ it('should write related record paths into src/related-record-paths verbatim, named after their universal identifier', () => {
+ const relatedRecordPath = {
+ universalIdentifier: '81818181-8181-4181-8181-818181818181',
+ objectUniversalIdentifier: '82828282-8282-4282-8282-828282828282',
+ firstFieldMetadataUniversalIdentifier:
+ '83838383-8383-4383-8383-838383838383',
+ isInherent: true,
+ };
+ const { entities, skipped } = buildPullEntities({
+ manifest: buildManifest({ relatedRecordPaths: [relatedRecordPath] }),
+ });
+ const entity = entities.find(
+ (candidate) => candidate.kind === 'relatedRecordPath',
+ );
+
+ expect(skipped).toEqual([]);
+ expect(entity).toMatchObject({
+ definer: 'defineRelatedRecordPath',
+ config: relatedRecordPath,
+ parentName: null,
+ });
+ expect(
+ `${entity?.defaultFolder}/${entity?.fileBaseName}${entity?.fileSuffix}`,
+ ).toBe('src/related-record-paths/81818181.related-record-path.ts');
+ });
+
it('should build a manifest that has no views, view fields, page layouts and page layout tabs properties without producing their entities', () => {
const {
views: _views,
diff --git a/packages/twenty-cli/src/app/pull/build-pull-entities.ts b/packages/twenty-cli/src/app/pull/build-pull-entities.ts
index fe69c4fb2a0..1cb0beb34d2 100644
--- a/packages/twenty-cli/src/app/pull/build-pull-entities.ts
+++ b/packages/twenty-cli/src/app/pull/build-pull-entities.ts
@@ -48,6 +48,7 @@ export const PULL_ENTITY_KINDS = [
'workflow',
'skill',
'agent',
+ 'relatedRecordPath',
] as const;
export type PullEntityKind = (typeof PULL_ENTITY_KINDS)[number];
@@ -412,6 +413,23 @@ export const buildPullEntities = ({
});
}
+ for (const relatedRecordPathManifest of manifest.relatedRecordPaths ?? []) {
+ entities.push({
+ kind: 'relatedRecordPath',
+ universalIdentifier: relatedRecordPathManifest.universalIdentifier,
+ definer: 'defineRelatedRecordPath',
+ config: relatedRecordPathManifest,
+ enumBindings: [],
+ defaultFolder: 'src/related-record-paths',
+ fileSuffix: '.related-record-path.ts',
+ fileBaseName: toFileBaseName({
+ segments: [],
+ universalIdentifier: relatedRecordPathManifest.universalIdentifier,
+ }),
+ parentName: null,
+ });
+ }
+
for (const agentManifest of manifest.agents ?? []) {
entities.push({
kind: 'agent',
diff --git a/packages/twenty-cli/src/app/pull/entity-key-by-kind.constant.ts b/packages/twenty-cli/src/app/pull/entity-key-by-kind.constant.ts
index a7cc073450a..0b8b4198452 100644
--- a/packages/twenty-cli/src/app/pull/entity-key-by-kind.constant.ts
+++ b/packages/twenty-cli/src/app/pull/entity-key-by-kind.constant.ts
@@ -17,4 +17,5 @@ export const ENTITY_KEY_BY_KIND: Record<PullEntityKind, ManifestEntityKey> = {
workflow: 'workflows',
skill: 'skills',
agent: 'agents',
+ relatedRecordPath: 'relatedRecordPaths',
};
diff --git a/packages/twenty-cli/src/app/source/extract-define-entity.ts b/packages/twenty-cli/src/app/source/extract-define-entity.ts
index bc409ff23c8..399bfc3f872 100644
--- a/packages/twenty-cli/src/app/source/extract-define-entity.ts
+++ b/packages/twenty-cli/src/app/source/extract-define-entity.ts
@@ -30,6 +30,7 @@ export const DEFINE_ENTITY_KEYS = {
defineCommandMenuItem: 'commandMenuItems',
defineTimelineActivityType: 'timelineActivityTypes',
defineSettingsMenuItem: 'settingsMenuItems',
+ defineRelatedRecordPath: 'relatedRecordPaths',
} as const;
export type TargetFunction = keyof typeof DEFINE_ENTITY_KEYS;
diff --git a/packages/twenty-docs/developers/extend/apps/data/overview.mdx b/packages/twenty-docs/developers/extend/apps/data/overview.mdx
index 6f30a0f416e..231623d8be3 100644
--- a/packages/twenty-docs/developers/extend/apps/data/overview.mdx
+++ b/packages/twenty-docs/developers/extend/apps/data/overview.mdx
@@ -57,8 +57,9 @@ A Twenty app's **data layer** is the data your app *adds* to a workspace — the
| **Relation** | A bidirectional link between two objects — both sides declared as fields | `defineField()` with `FieldType.RELATION` |
| **Index** | A database index to speed up a recurring query on one of your objects | `defineIndex()` |
| **Timeline activity type** | An automatic audit event or explicit domain event shown in record timelines | `defineTimelineActivityType()` |
+| **Related record path** | A chain of up to three relations along which access to a record extends to its related records | `defineRelatedRecordPath()` |
-The CLI detects these via AST analysis at build time, so file organization is up to you — the convention is `src/objects/`, `src/fields/`, `src/indexes/`, and `src/timeline-activity-types/`. Stable `universalIdentifier` UUIDs tie everything together across deploys.
+The CLI detects these via AST analysis at build time, so file organization is up to you — the convention is `src/objects/`, `src/fields/`, `src/indexes/`, `src/timeline-activity-types/`, and `src/related-record-paths/`. Stable `universalIdentifier` UUIDs tie everything together across deploys.
## Indexes (optional)
@@ -104,6 +105,37 @@ defineIndex({
Order the `fields` array the way Postgres should use it — leftmost column first, like a phone book. Indexes are not free: every write to the table updates them. Add one only when you have a query that needs it.
+## Related record paths (optional)
+
+<Warning>
+ Related record paths are in preview: they sync with your app, but record
+ permissions don't use them yet. Once enforced, they require the
+ **Organization plan or above**, like
+ [row-level security](/developers/extend/apps/config/roles#row-level-security).
+</Warning>
+
+A related record path starts on an object and follows up to three relation fields, each on the object the previous one reached. Record permissions use these paths to extend access from a record to its related records.
+
+- An **inherent** path (`isInherent: true`) applies whenever the starting record is readable, however that access was granted. Use it for records that belong to their parent, such as a post card's attachments.
+- A **regular** path applies only when access to the starting record comes directly from a role, so workspaces choose which ones to rely on.
+
+```ts src/related-record-paths/post-card-attachments.related-record-path.ts
+import { defineRelatedRecordPath } from 'twenty-sdk/define';
+
+import { POST_CARD_UNIVERSAL_IDENTIFIER } from '../objects/post-card.object';
+import { ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER } from '../fields/attachments-on-post-card.field';
+
+export default defineRelatedRecordPath({
+ universalIdentifier: 'c1b8f0d2-7e4a-4b6c-9a1d-3f5e2b7c8d90',
+ objectUniversalIdentifier: POST_CARD_UNIVERSAL_IDENTIFIER,
+ firstFieldMetadataUniversalIdentifier:
+ ATTACHMENTS_ON_POST_CARD_UNIVERSAL_IDENTIFIER,
+ isInherent: true,
+});
+```
+
+Add `secondFieldMetadataUniversalIdentifier` and `thirdFieldMetadataUniversalIdentifier` for longer paths. Each hop must be an active relation on the object reached so far, a path can't visit the same object twice, and two paths can't use the same hops.
+
<Note>
Looking for **Application Config** or **Roles & Permissions**? Those describe the app itself rather than the data it adds — they live under [Config](/developers/extend/apps/config/overview). Looking for **Connections** (Linear, GitHub, Slack OAuth)? Those exist to be called *from* logic functions and live under [Logic](/developers/extend/apps/logic/connections).
</Note>
diff --git a/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts b/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts
index 585cdd25a83..28ad212a4a1 100644
--- a/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts
+++ b/packages/twenty-sdk/src/sdk/define/common/types/define-entity.type.ts
@@ -21,6 +21,7 @@ import {
type McpServerManifest,
type MessagingProviderManifest,
type NavigationMenuItemManifest,
+ type RelatedRecordPathManifest,
type SkillManifest,
type StandalonePageLayoutWidgetManifest,
type StandaloneViewFieldManifest,
@@ -53,6 +54,7 @@ export type DefinableEntity =
| ViewConfig
| StandaloneViewFieldManifest
| NavigationMenuItemManifest
+ | RelatedRecordPathManifest
| PageLayoutConfig
| PageLayoutTabConfig
| StandalonePageLayoutWidgetManifest
diff --git a/packages/twenty-sdk/src/sdk/define/index.ts b/packages/twenty-sdk/src/sdk/define/index.ts
index 96b42f4a9bf..11dff9c6ea9 100644
--- a/packages/twenty-sdk/src/sdk/define/index.ts
+++ b/packages/twenty-sdk/src/sdk/define/index.ts
@@ -192,6 +192,7 @@ export {
} from 'twenty-shared/types';
export { SystemPermissionFlag } from '@/sdk/define/roles/system-permission-flag.constant';
+export { defineRelatedRecordPath } from '@/sdk/define/related-record-paths/define-related-record-path';
export { defineSkill } from '@/sdk/define/skills/define-skill';
export { defineView } from '@/sdk/define/views/define-view';
diff --git a/packages/twenty-sdk/src/sdk/define/related-record-paths/__tests__/define-related-record-path.spec.ts b/packages/twenty-sdk/src/sdk/define/related-record-paths/__tests__/define-related-record-path.spec.ts
new file mode 100644
index 00000000000..897e6bddf12
--- /dev/null
+++ b/packages/twenty-sdk/src/sdk/define/related-record-paths/__tests__/define-related-record-path.spec.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+
+import { defineRelatedRecordPath } from '@/sdk/define';
+
+const baseValidConfig = {
+ universalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a01',
+ objectUniversalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a02',
+ firstFieldMetadataUniversalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a03',
+};
+
+describe('defineRelatedRecordPath', () => {
+ it('returns success for a valid config', () => {
+ const result = defineRelatedRecordPath({
+ ...baseValidConfig,
+ secondFieldMetadataUniversalIdentifier:
+ '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a04',
+ isInherent: true,
+ });
+
+ expect(result.success).toBe(true);
+ expect(result.errors).toEqual([]);
+ });
+
+ it('rejects a path without a first field', () => {
+ const result = defineRelatedRecordPath({
+ ...baseValidConfig,
+ firstFieldMetadataUniversalIdentifier: '',
+ });
+
+ expect(result.success).toBe(false);
+ });
+
+ it('rejects a path that skips its second relation', () => {
+ const result = defineRelatedRecordPath({
+ ...baseValidConfig,
+ thirdFieldMetadataUniversalIdentifier:
+ '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a05',
+ });
+
+ expect(result.success).toBe(false);
+ expect(result.errors).toContain(
+ 'Related record path cannot skip its second relation',
+ );
+ });
+});
diff --git a/packages/twenty-sdk/src/sdk/define/related-record-paths/define-related-record-path.ts b/packages/twenty-sdk/src/sdk/define/related-record-paths/define-related-record-path.ts
new file mode 100644
index 00000000000..f7782075d09
--- /dev/null
+++ b/packages/twenty-sdk/src/sdk/define/related-record-paths/define-related-record-path.ts
@@ -0,0 +1,34 @@
+import { isNonEmptyString } from '@sniptt/guards';
+import { type DefineEntity } from '@/sdk/define/common/types/define-entity.type';
+import { createValidationResult } from '@/sdk/define/common/utils/create-validation-result';
+import { type RelatedRecordPathManifest } from 'twenty-shared/application';
+import { isDefined } from 'twenty-shared/utils';
+
+export const defineRelatedRecordPath: DefineEntity<
+ RelatedRecordPathManifest
+> = (config) => {
+ const errors: string[] = [];
+
+ if (!isNonEmptyString(config.universalIdentifier)) {
+ errors.push('Related record path must have a universalIdentifier');
+ }
+
+ if (!isNonEmptyString(config.objectUniversalIdentifier)) {
+ errors.push('Related record path must have an objectUniversalIdentifier');
+ }
+
+ if (!isNonEmptyString(config.firstFieldMetadataUniversalIdentifier)) {
+ errors.push(
+ 'Related record path must have a firstFieldMetadataUniversalIdentifier',
+ );
+ }
+
+ if (
+ isDefined(config.thirdFieldMetadataUniversalIdentifier) &&
+ !isDefined(config.secondFieldMetadataUniversalIdentifier)
+ ) {
+ errors.push('Related record path cannot skip its second relation');
+ }
+
+ return createValidationResult({ config, errors });
+};
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-flat-related-record-path-to-related-record-path-manifest.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-flat-related-record-path-to-related-record-path-manifest.util.ts
new file mode 100644
index 00000000000..5691261ea75
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-flat-related-record-path-to-related-record-path-manifest.util.ts
@@ -0,0 +1,39 @@
+/* @license Enterprise */
+
+import { type RelatedRecordPathManifest } from 'twenty-shared/application';
+import { isDefined } from 'twenty-shared/utils';
+
+import { type UniversalFlatRelatedRecordPath } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-related-record-path.type';
+
+export const fromFlatRelatedRecordPathToRelatedRecordPathManifest = ({
+ flatRelatedRecordPath,
+}: {
+ flatRelatedRecordPath: Pick<
+ UniversalFlatRelatedRecordPath,
+ | 'universalIdentifier'
+ | 'objectMetadataUniversalIdentifier'
+ | 'firstFieldMetadataUniversalIdentifier'
+ | 'secondFieldMetadataUniversalIdentifier'
+ | 'thirdFieldMetadataUniversalIdentifier'
+ | 'isInherent'
+ >;
+}): RelatedRecordPathManifest => ({
+ universalIdentifier: flatRelatedRecordPath.universalIdentifier,
+ objectUniversalIdentifier:
+ flatRelatedRecordPath.objectMetadataUniversalIdentifier,
+ firstFieldMetadataUniversalIdentifier:
+ flatRelatedRecordPath.firstFieldMetadataUniversalIdentifier,
+ ...(isDefined(flatRelatedRecordPath.secondFieldMetadataUniversalIdentifier)
+ ? {
+ secondFieldMetadataUniversalIdentifier:
+ flatRelatedRecordPath.secondFieldMetadataUniversalIdentifier,
+ }
+ : {}),
+ ...(isDefined(flatRelatedRecordPath.thirdFieldMetadataUniversalIdentifier)
+ ? {
+ thirdFieldMetadataUniversalIdentifier:
+ flatRelatedRecordPath.thirdFieldMetadataUniversalIdentifier,
+ }
+ : {}),
+ isInherent: flatRelatedRecordPath.isInherent,
+});
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-related-record-path-manifest-to-universal-flat-related-record-path.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-related-record-path-manifest-to-universal-flat-related-record-path.util.ts
new file mode 100644
index 00000000000..2555195d9c1
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/converters/from-related-record-path-manifest-to-universal-flat-related-record-path.util.ts
@@ -0,0 +1,29 @@
+/* @license Enterprise */
+
+import { type RelatedRecordPathManifest } from 'twenty-shared/application';
+
+import { type UniversalFlatRelatedRecordPath } from 'src/engine/workspace-manager/workspace-migration/universal-flat-entity/types/universal-flat-related-record-path.type';
+
+export const fromRelatedRecordPathManifestToUniversalFlatRelatedRecordPath = ({
+ relatedRecordPathManifest,
+ applicationUniversalIdentifier,
+ now,
+}: {
+ relatedRecordPathManifest: RelatedRecordPathManifest;
+ applicationUniversalIdentifier: string;
+ now: string;
+}): UniversalFlatRelatedRecordPath => ({
+ universalIdentifier: relatedRecordPathManifest.universalIdentifier,
+ applicationUniversalIdentifier,
+ objectMetadataUniversalIdentifier:
+ relatedRecordPathManifest.objectUniversalIdentifier,
+ firstFieldMetadataUniversalIdentifier:
+ relatedRecordPathManifest.firstFieldMetadataUniversalIdentifier,
+ secondFieldMetadataUniversalIdentifier:
+ relatedRecordPathManifest.secondFieldMetadataUniversalIdentifier ?? null,
+ thirdFieldMetadataUniversalIdentifier:
+ relatedRecordPathManifest.thirdFieldMetadataUniversalIdentifier ?? null,
+ isInherent: relatedRecordPathManifest.isInherent ?? false,
+ createdAt: now,
+ updatedAt: now,
+});
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/application-manifest-export.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/application-manifest-export.service.ts
index a07a749f4f1..a825513461a 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/application-manifest-export.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/application-manifest-export.service.ts
@@ -15,6 +15,7 @@ import { getResolvableReferenceUniversalIdentifiers } from 'src/engine/core-modu
import { reconstructNavigationMenuItemsManifest } from 'src/engine/core-modules/application/application-manifest/utils/reconstruct-navigation-menu-items-manifest.util';
import { reconstructPageLayoutsManifest } from 'src/engine/core-modules/application/application-manifest/utils/reconstruct-page-layouts-manifest.util';
import { reconstructRolesManifest } from 'src/engine/core-modules/application/application-manifest/utils/reconstruct-roles-manifest.util';
+import { reconstructRelatedRecordPathsManifest } from 'src/engine/core-modules/application/application-manifest/utils/reconstruct-related-record-paths-manifest.util';
import { reconstructSkillsManifest } from 'src/engine/core-modules/application/application-manifest/utils/reconstruct-skills-manifest.util';
import { reconstructViewsManifest } from 'src/engine/core-modules/application/application-manifest/utils/reconstruct-views-manifest.util';
import { reconstructWorkflowsManifest } from 'src/engine/core-modules/application/application-manifest/utils/reconstruct-workflows-manifest.util';
@@ -185,6 +186,8 @@ export class ApplicationManifestExportService {
const { skills, coverage: skillsCoverage } = reconstructSkillsManifest({
applicationAllFlatEntityMaps,
});
+ const { relatedRecordPaths, coverage: relatedRecordPathsCoverage } =
+ reconstructRelatedRecordPathsManifest({ applicationAllFlatEntityMaps });
const translations = isDefined(flatApplication.applicationRegistrationId)
? await this.applicationTranslationCacheService.getCatalogsByLocale(
flatApplication.applicationRegistrationId,
@@ -219,6 +222,7 @@ export class ApplicationManifestExportService {
commandMenuItems: [],
timelineActivityTypes: [],
settingsMenuItems: [],
+ relatedRecordPaths,
workflows,
...(isDefined(translations) ? { translations } : {}),
};
@@ -243,6 +247,7 @@ export class ApplicationManifestExportService {
...workflowsCoverage,
...agentsCoverage,
...skillsCoverage,
+ ...relatedRecordPathsCoverage,
],
}),
files: shouldIncludeDependencies
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts
index ba81d6d9b9d..bc92bf5aeac 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/services/compute-application-manifest-all-universal-flat-entity-maps.service.ts
@@ -34,6 +34,7 @@ import { fromPermissionFlagToUniversalFlatRolePermissionFlag } from 'src/engine/
import { fromRoleManifestToUniversalFlatRole } from 'src/engine/core-modules/application/application-manifest/converters/from-role-manifest-to-universal-flat-role.util';
import { fromRowLevelPermissionPredicateGroupManifestToUniversalFlatRowLevelPermissionPredicateGroup } from 'src/engine/core-modules/application/application-manifest/converters/from-row-level-permission-predicate-group-manifest-to-universal-flat-row-level-permission-predicate-group.util';
import { fromRowLevelPermissionPredicateManifestToUniversalFlatRowLevelPermissionPredicate } from 'src/engine/core-modules/application/application-manifest/converters/from-row-level-permission-predicate-manifest-to-universal-flat-row-level-permission-predicate.util';
+import { fromRelatedRecordPathManifestToUniversalFlatRelatedRecordPath } from 'src/engine/core-modules/application/application-manifest/converters/from-related-record-path-manifest-to-universal-flat-related-record-path.util';
import { fromSkillManifestToUniversalFlatSkill } from 'src/engine/core-modules/application/application-manifest/converters/from-skill-manifest-to-universal-flat-skill.util';
import { fromTimelineActivityTypeManifestToUniversalFlatTimelineActivityType } from 'src/engine/core-modules/application/application-manifest/converters/from-timeline-activity-type-manifest-to-universal-flat-timeline-activity-type.util';
import { fromSettingsMenuItemManifestToUniversalFlatSettingsMenuItem } from 'src/engine/core-modules/application/application-manifest/converters/from-settings-menu-item-manifest-to-universal-flat-settings-menu-item.util';
@@ -304,6 +305,19 @@ export class ComputeApplicationManifestAllUniversalFlatEntityMapsService {
});
}
+ for (const relatedRecordPathManifest of manifest.relatedRecordPaths ?? []) {
+ addUniversalFlatEntityToUniversalFlatEntityMapsThroughMutationOrThrow({
+ universalFlatEntity:
+ fromRelatedRecordPathManifestToUniversalFlatRelatedRecordPath({
+ relatedRecordPathManifest,
+ applicationUniversalIdentifier,
+ now,
+ }),
+ universalFlatEntityMapsToMutate:
+ allUniversalFlatEntityMaps.flatRelatedRecordPathMaps,
+ });
+ }
+
for (const permissionFlagManifest of manifest.permissionFlags ?? []) {
addUniversalFlatEntityToUniversalFlatEntityMapsThroughMutationOrThrow({
universalFlatEntity:
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/__tests__/export-covers-compared-properties.spec.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/__tests__/export-covers-compared-properties.spec.ts
index 62ebbad4af5..a0ec4fef45a 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/__tests__/export-covers-compared-properties.spec.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/__tests__/export-covers-compared-properties.spec.ts
@@ -17,6 +17,7 @@ import {
type ViewFilterManifest,
type ViewGroupManifest,
type ViewManifest,
+ type RelatedRecordPathManifest,
type SkillManifest,
type ViewSortManifest,
type WorkflowManifest,
@@ -41,6 +42,8 @@ import {
import { isDefined } from 'twenty-shared/utils';
import { fromFlatAgentToAgentManifest } from 'src/engine/core-modules/application/application-manifest/converters/from-flat-agent-to-agent-manifest.util';
+import { fromFlatRelatedRecordPathToRelatedRecordPathManifest } from 'src/engine/core-modules/application/application-manifest/converters/from-flat-related-record-path-to-related-record-path-manifest.util';
+import { fromRelatedRecordPathManifestToUniversalFlatRelatedRecordPath } from 'src/engine/core-modules/application/application-manifest/converters/from-related-record-path-manifest-to-universal-flat-related-record-path.util';
import { fromFlatSkillToSkillManifest } from 'src/engine/core-modules/application/application-manifest/converters/from-flat-skill-to-skill-manifest.util';
import { fromSkillManifestToUniversalFlatSkill } from 'src/engine/core-modules/application/application-manifest/converters/from-skill-manifest-to-universal-flat-skill.util';
import { fromAgentManifestToUniversalFlatAgent } from 'src/engine/core-modules/application/utils/from-agent-manifest-to-universal-flat-agent.util';
@@ -436,6 +439,15 @@ const SKILL_MANIFEST: SkillManifest = {
content: 'Research the company first.',
};
+const RELATED_RECORD_PATH_MANIFEST: RelatedRecordPathManifest = {
+ universalIdentifier: APP_UID,
+ objectUniversalIdentifier: OBJECT_UID,
+ firstFieldMetadataUniversalIdentifier: FIELD_UID,
+ secondFieldMetadataUniversalIdentifier: FIELD_UID,
+ thirdFieldMetadataUniversalIdentifier: FIELD_UID,
+ isInherent: true,
+};
+
type ExportedKind = {
metadataName: keyof typeof ALL_UNIVERSAL_FLAT_ENTITY_PROPERTIES_TO_COMPARE_AND_STRINGIFY;
emittedProperties: string[];
@@ -903,6 +915,24 @@ const EXPORTED_KINDS: ExportedKind[] = [
'always false for application skills; any other value is reported as unsupported',
},
},
+ {
+ metadataName: 'relatedRecordPath',
+ emittedProperties: Object.keys(
+ fromFlatRelatedRecordPathToRelatedRecordPathManifest({
+ flatRelatedRecordPath:
+ fromRelatedRecordPathManifestToUniversalFlatRelatedRecordPath({
+ relatedRecordPathManifest: RELATED_RECORD_PATH_MANIFEST,
+ applicationUniversalIdentifier: APP_UID,
+ now: NOW,
+ }),
+ }),
+ ),
+ renamedProperties: {
+ objectMetadataUniversalIdentifier: 'objectUniversalIdentifier',
+ },
+ workspaceLocalProperties: [],
+ knownGaps: {},
+ },
];
describe('export coverage of the compared properties', () => {
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts
index 3be40c7d20d..e45850ee4b5 100644
--- a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/find-manifest-entity-descriptor-by-universal-identifier.util.ts
@@ -298,7 +298,8 @@ export const MANIFEST_ENTITY_REGISTRY: Record<
},
relatedRecordPath: {
entityKind: 'related record path',
- getCandidates: () => NO_MANIFEST_CANDIDATES,
+ getCandidates: (manifest) =>
+ toCandidates(manifest.relatedRecordPaths, () => undefined),
},
validationRule: {
entityKind: 'validation rule',
diff --git a/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/reconstruct-related-record-paths-manifest.util.ts b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/reconstruct-related-record-paths-manifest.util.ts
new file mode 100644
index 00000000000..d803f8a1b09
--- /dev/null
+++ b/packages/twenty-server/src/engine/core-modules/application/application-manifest/utils/reconstruct-related-record-paths-manifest.util.ts
@@ -0,0 +1,76 @@
+/* @license Enterprise */
+
+import { type RelatedRecordPathManifest } from 'twenty-shared/application';
+import { isDefined } from 'twenty-shared/utils';
+
+import { fromFlatRelatedRecordPathToRelatedRecordPathManifest } from 'src/engine/core-modules/application/application-manifest/converters/from-flat-related-record-path-to-related-record-path-manifest.util';
+import { fromRelatedRecordPathManifestToUniversalFlatRelatedRecordPath } from 'src/engine/core-modules/application/application-manifest/converters/from-related-record-path-manifest-to-universal-flat-related-record-path.util';
+import { type ApplicationExportCoverageEntry } from 'src/engine/core-modules/application/application-manifest/types/application-export.type';
+import { buildExportedCoverageEntry } from 'src/engine/core-modules/application/application-manifest/utils/build-exported-coverage-entry.util';
+import { getUnreproducedPropertiesReason } from 'src/engine/core-modules/application/application-manifest/utils/get-unreproduced-properties-reason.util';
+import { sortFlatEntitiesByUniversalIdentifier } from 'src/engine/core-modules/application/application-manifest/utils/sort-flat-entities-by-universal-identifier.util';
+import { ApplicationExportCoverageStatus } from 'src/engine/core-modules/application/enums/application-export-coverage-status.enum';
+import { type AllFlatEntityMaps } from 'src/engine/metadata-modules/flat-entity/types/all-flat-entity-maps.type';
+import { type FlatRelatedRecordPath } from 'src/engine/metadata-modules/flat-related-record-path/types/flat-related-record-path.type';
+
+const convertFlatRelatedRecordPath = (
+ flatRelatedRecordPath: FlatRelatedRecordPath,
+): { manifest: RelatedRecordPathManifest } | { reason: string } => {
+ const manifest = fromFlatRelatedRecordPathToRelatedRecordPathManifest({
+ flatRelatedRecordPath,
+ });
+ const reason = getUnreproducedPropertiesReason({
+ metadataName: 'relatedRecordPath',
+ flatEntity: flatRelatedRecordPath,
+ reproducedUniversalFlatEntity:
+ fromRelatedRecordPathManifestToUniversalFlatRelatedRecordPath({
+ relatedRecordPathManifest: manifest,
+ applicationUniversalIdentifier:
+ flatRelatedRecordPath.applicationUniversalIdentifier,
+ now: flatRelatedRecordPath.updatedAt,
+ }),
+ });
+
+ return isDefined(reason) ? { reason } : { manifest };
+};
+
+export const reconstructRelatedRecordPathsManifest = ({
+ applicationAllFlatEntityMaps,
+}: {
+ applicationAllFlatEntityMaps: Pick<
+ AllFlatEntityMaps,
+ 'flatRelatedRecordPathMaps'
+ >;
+}): {
+ relatedRecordPaths: RelatedRecordPathManifest[];
+ coverage: ApplicationExportCoverageEntry[];
+} => {
+ const relatedRecordPaths: RelatedRecordPathManifest[] = [];
+ const coverage: ApplicationExportCoverageEntry[] = [];
+
+ for (const flatRelatedRecordPath of sortFlatEntitiesByUniversalIdentifier(
+ applicationAllFlatEntityMaps.flatRelatedRecordPathMaps,
+ )) {
+ const conversion = convertFlatRelatedRecordPath(flatRelatedRecordPath);
+
+ if ('reason' in conversion) {
+ coverage.push({
+ metadataName: 'relatedRecordPath',
+ universalIdentifier: flatRelatedRecordPath.universalIdentifier,
+ status: ApplicationExportCoverageStatus.UNSUPPORTED,
+ reason: conversion.reason,
+ });
+ continue;
+ }
+
+ coverage.push(
+ buildExportedCoverageEntry({
+ metadataName: 'relatedRecordPath',
+ flatEntity: flatRelatedRecordPath,
+ }),
+ );
+ relatedRecordPaths.push(conversion.manifest);
+ }
+
+ return { relatedRecordPaths, coverage };
+};
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/successful-export-application-data-model.integration-spec.ts.snap b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/successful-export-application-data-model.integration-spec.ts.snap
index e69f02b4749..ffce785b18c 100644
--- a/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/successful-export-application-data-model.integration-spec.ts.snap
+++ b/packages/twenty-server/test/integration/metadata/suites/application/__snapshots__/successful-export-application-data-model.integration-spec.ts.snap
@@ -1114,6 +1114,7 @@ exports[`Application export - data model exports the whole application as a stab
},
],
"publicAssets": [],
+ "relatedRecordPaths": [],
"roles": [
{
"canAccessAllAgentChatChannels": false,
diff --git a/packages/twenty-server/test/integration/metadata/suites/application/successful-manifest-sync-related-record-path.integration-spec.ts b/packages/twenty-server/test/integration/metadata/suites/application/successful-manifest-sync-related-record-path.integration-spec.ts
new file mode 100644
index 00000000000..bbf11cb2e66
--- /dev/null
+++ b/packages/twenty-server/test/integration/metadata/suites/application/successful-manifest-sync-related-record-path.integration-spec.ts
@@ -0,0 +1,111 @@
+/* @license Enterprise */
+
+import { buildBaseManifest } from 'test/integration/metadata/suites/application/utils/build-base-manifest.util';
+import { cleanupApplicationAndAppRegistration } from 'test/integration/metadata/suites/application/utils/cleanup-application-and-app-registration.util';
+import { exportApplication } from 'test/integration/metadata/suites/application/utils/export-application.util';
+import { setupApplicationForSync } from 'test/integration/metadata/suites/application/utils/setup-application-for-sync.util';
+import { syncApplication } from 'test/integration/metadata/suites/application/utils/sync-application.util';
+import { type Manifest } from 'twenty-shared/application';
+import { STANDARD_OBJECTS } from 'twenty-shared/metadata';
+import { v4 as uuidv4 } from 'uuid';
+
+const TEST_APP_ID = uuidv4();
+const TEST_ROLE_ID = uuidv4();
+const TEST_PATH_ID = uuidv4();
+
+const RELATED_RECORD_PATH_MANIFEST = {
+ universalIdentifier: TEST_PATH_ID,
+ objectUniversalIdentifier: STANDARD_OBJECTS.person.universalIdentifier,
+ firstFieldMetadataUniversalIdentifier:
+ STANDARD_OBJECTS.person.fields.messageParticipants.universalIdentifier,
+ isInherent: true,
+};
+
+const buildManifest = (
+ overrides?: Partial<Pick<Manifest, 'relatedRecordPaths'>>,
+) => buildBaseManifest({ appId: TEST_APP_ID, roleId: TEST_ROLE_ID, overrides });
+
+const findRelatedRecordPathRows = async (): Promise<
+ { isInherent: boolean; secondFieldMetadataId: string | null }[]
+> =>
+ globalThis.testDataSource.query(
+ `SELECT "isInherent", "secondFieldMetadataId" FROM "core"."relatedRecordPath"
+ WHERE "universalIdentifier" = $1`,
+ [TEST_PATH_ID],
+ );
+
+describe('Manifest sync - related record paths', () => {
+ beforeEach(async () => {
+ await setupApplicationForSync({
+ applicationUniversalIdentifier: TEST_APP_ID,
+ name: 'Related Record Path Test Application',
+ description: 'App for testing related record path manifest sync',
+ sourcePath: 'related-record-path-manifest-sync',
+ });
+ }, 60000);
+
+ afterEach(async () => {
+ await cleanupApplicationAndAppRegistration({
+ applicationUniversalIdentifier: TEST_APP_ID,
+ });
+ });
+
+ it('creates the declared path and deletes it once removed from the manifest', async () => {
+ await syncApplication({
+ manifest: buildManifest({
+ relatedRecordPaths: [RELATED_RECORD_PATH_MANIFEST],
+ }),
+ expectToFail: false,
+ });
+
+ expect(await findRelatedRecordPathRows()).toEqual([
+ { isInherent: true, secondFieldMetadataId: null },
+ ]);
+
+ await syncApplication({
+ manifest: buildManifest({ relatedRecordPaths: [] }),
+ expectToFail: false,
+ });
+
+ expect(await findRelatedRecordPathRows()).toEqual([]);
+ }, 60000);
+
+ it('exports the declared path back into the manifest', async () => {
+ await syncApplication({
+ manifest: buildManifest({
+ relatedRecordPaths: [RELATED_RECORD_PATH_MANIFEST],
+ }),
+ expectToFail: false,
+ });
+
+ const { data, errors } = await exportApplication({
+ universalIdentifier: TEST_APP_ID,
+ expectToFail: false,
+ });
+
+ expect(errors).toBeUndefined();
+ expect(data.exportApplication.manifest.relatedRecordPaths).toEqual([
+ RELATED_RECORD_PATH_MANIFEST,
+ ]);
+ }, 60000);
+
+ it('rejects a path whose field does not belong to its object', async () => {
+ const response = await syncApplication({
+ manifest: buildManifest({
+ relatedRecordPaths: [
+ {
+ ...RELATED_RECORD_PATH_MANIFEST,
+ objectUniversalIdentifier:
+ STANDARD_OBJECTS.company.universalIdentifier,
+ },
+ ],
+ }),
+ expectToFail: true,
+ });
+
+ expect(JSON.stringify(response.errors)).toContain(
+ 'Each related record path field must belong to the object reached by the previous relation',
+ );
+ expect(await findRelatedRecordPathRows()).toEqual([]);
+ }, 60000);
+});
diff --git a/packages/twenty-shared/src/application/index.ts b/packages/twenty-shared/src/application/index.ts
index 37b3b37095f..6ad8621a2d7 100644
--- a/packages/twenty-shared/src/application/index.ts
+++ b/packages/twenty-shared/src/application/index.ts
@@ -226,6 +226,7 @@ export type {
} from './permissionFlagManifestType';
export type { PostInstallLogicFunctionApplicationManifest } from './postInstallLogicFunctionApplicationType';
export type { PreInstallLogicFunctionApplicationManifest } from './preInstallLogicFunctionApplicationType';
+export type { RelatedRecordPathManifest } from './relatedRecordPathManifestType';
export type { RoleManifestGrant } from './roleManifestGrantType';
export type {
ObjectPermissionManifest,
diff --git a/packages/twenty-shared/src/application/manifestType.ts b/packages/twenty-shared/src/application/manifestType.ts
index cbd72b80bfe..3334434f704 100644
--- a/packages/twenty-shared/src/application/manifestType.ts
+++ b/packages/twenty-shared/src/application/manifestType.ts
@@ -22,6 +22,7 @@ import {
type StandalonePageLayoutWidgetManifest,
} from './pageLayoutManifestType';
import { type PermissionFlagManifest } from './permissionFlagManifestType';
+import { type RelatedRecordPathManifest } from './relatedRecordPathManifestType';
import { type RoleManifest } from './roleManifestType';
import { type SettingsMenuItemManifest } from './settingsMenuItemManifestType';
import { type SkillManifest } from './skillManifestType';
@@ -60,5 +61,6 @@ export type Manifest = {
commandMenuItems: CommandMenuItemManifest[];
timelineActivityTypes: TimelineActivityTypeManifest[];
settingsMenuItems: SettingsMenuItemManifest[];
+ relatedRecordPaths?: RelatedRecordPathManifest[];
translations?: TranslationsManifest;
};
diff --git a/packages/twenty-shared/src/application/relatedRecordPathManifestType.ts b/packages/twenty-shared/src/application/relatedRecordPathManifestType.ts
new file mode 100644
index 00000000000..6d642ebbc35
--- /dev/null
+++ b/packages/twenty-shared/src/application/relatedRecordPathManifestType.ts
@@ -0,0 +1,9 @@
+import { type SyncableEntityOptions } from '@/application/syncableEntityOptionsType';
+
+export type RelatedRecordPathManifest = SyncableEntityOptions & {
+ objectUniversalIdentifier: string;
+ firstFieldMetadataUniversalIdentifier: string;
+ secondFieldMetadataUniversalIdentifier?: string;
+ thirdFieldMetadataUniversalIdentifier?: string;
+ isInherent?: boolean;
+};