Skip to content

The open alternative to Salesforce, designed for AI.

Add doc on standard object u ids (#18519)

martmull6f6a9a55fbf4
diff --git a/packages/twenty-docs/developers/extend/capabilities/apps.mdx b/packages/twenty-docs/developers/extend/capabilities/apps.mdx
index a5a02699b8c..25779d9609d 100644
--- a/packages/twenty-docs/developers/extend/capabilities/apps.mdx
+++ b/packages/twenty-docs/developers/extend/capabilities/apps.mdx
@@ -319,6 +319,71 @@ Key points:
but this is not recommended.
</Note>
+### Defining fields on existing objects
+
+Use `defineField()` to add custom fields to existing objects — both standard objects (like `company`, `person`, `opportunity`) and custom objects defined by other apps. Each field lives in its own file and references the target object by its `universalIdentifier`.
+
+To reference standard objects, import `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` from `twenty-sdk`. This constant provides stable identifiers for all built-in objects and their fields:
+
+```typescript
+// src/fields/apollo-total-funding.field.ts
+import {
+ defineField,
+ FieldType,
+ STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
+} from 'twenty-sdk';
+
+export default defineField({
+ universalIdentifier: 'c90ae72d-4ddf-4f22-882f-eef98c91e40e',
+ objectUniversalIdentifier:
+ STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.universalIdentifier,
+ type: FieldType.CURRENCY,
+ name: 'apolloTotalFunding',
+ label: 'Total Funding',
+ description: 'Total funding raised by the company',
+ icon: 'IconCash',
+});
+```
+
+Key points:
+
+- `objectUniversalIdentifier` tells Twenty which object to attach the field to. Use `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.<objectName>.universalIdentifier` for standard objects.
+- Each field requires its own stable `universalIdentifier`, a `name`, `type`, `label`, and the target `objectUniversalIdentifier`.
+- You can scaffold new fields using `yarn twenty entity:add` and choosing the field option.
+- `STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS` is also exported as `STANDARD_OBJECT` for convenience — both refer to the same constant.
+
+Available standard objects include: `attachment`, `blocklist`, `calendarChannel`, `calendarEvent`, `calendarEventParticipant`, `company`, `connectedAccount`, `dashboard`, `favorite`, `favoriteFolder`, `message`, `messageChannel`, `messageParticipant`, `messageThread`, `note`, `noteTarget`, `opportunity`, `person`, `task`, `taskTarget`, `timelineActivity`, `workflow`, `workflowAutomatedTrigger`, `workflowRun`, `workflowVersion`, and `workspaceMember`.
+
+Each standard object also exposes its field identifiers. For example, to reference a specific field on a standard object in role permissions:
+
+```typescript
+STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.name.universalIdentifier
+```
+
+#### Relation fields on existing objects
+
+You can also define relation fields that link existing objects to your custom objects:
+
+```typescript
+// src/fields/people-on-call-recording.field.ts
+import { defineField, FieldType, RelationType, STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk';
+import { CALL_RECORDING_OBJECT_UNIVERSAL_IDENTIFIER } from 'src/objects/call-recording';
+import { CALL_RECORDING_ON_PERSON_ID } from 'src/fields/call-recording-on-person.field';
+
+export default defineField({
+ universalIdentifier: '4a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d',
+ objectUniversalIdentifier:
+ CALL_RECORDING_OBJECT_UNIVERSAL_IDENTIFIER,
+ type: FieldType.RELATION,
+ name: 'person',
+ label: 'Person',
+ relationTargetObjectMetadataUniversalIdentifier:
+ STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.universalIdentifier,
+ relationTargetFieldMetadataUniversalIdentifier:
+ CALL_RECORDING_ON_PERSON_ID,
+ relationType: RelationType.MANY_TO_ONE,
+});
+```
### Application config (application-config.ts)