Vai al contenuto principale
Gli oggetti personalizzati sono nuovi tipi di record che la tua app aggiunge a uno spazio di lavoro — Cartolina, Fattura, Abbonamento, qualsiasi cosa specifica per il tuo dominio. Ogni oggetto dichiara il proprio schema (campi, relazioni, valori predefiniti) e un identificatore universale stabile che persiste tra le sincronizzazioni e le distribuzioni.
src/objects/post-card.object.ts
import { defineObject, FieldType } from 'twenty-sdk/define';

enum PostCardStatus {
  DRAFT = 'DRAFT',
  SENT = 'SENT',
  DELIVERED = 'DELIVERED',
  RETURNED = 'RETURNED',
}

export default defineObject({
  universalIdentifier: '54b589ca-eeed-4950-a176-358418b85c05',
  nameSingular: 'postCard',
  namePlural: 'postCards',
  labelSingular: 'Post Card',
  labelPlural: 'Post Cards',
  description: 'A post card object',
  icon: 'IconMail',
  fields: [
    {
      universalIdentifier: '58a0a314-d7ea-4865-9850-7fb84e72f30b',
      name: 'content',
      type: FieldType.TEXT,
      label: 'Content',
      description: "Postcard's content",
      icon: 'IconAbc',
    },
    {
      universalIdentifier: 'c6aa31f3-da76-4ac6-889f-475e226009ac',
      name: 'recipientName',
      type: FieldType.FULL_NAME,
      label: 'Recipient name',
      icon: 'IconUser',
    },
    {
      universalIdentifier: '95045777-a0ad-49ec-98f9-22f9fc0c8266',
      name: 'recipientAddress',
      type: FieldType.ADDRESS,
      label: 'Recipient address',
      icon: 'IconHome',
    },
    {
      universalIdentifier: '87b675b8-dd8c-4448-b4ca-20e5a2234a1e',
      name: 'status',
      type: FieldType.SELECT,
      label: 'Status',
      icon: 'IconSend',
      defaultValue: `'${PostCardStatus.DRAFT}'`,
      options: [
        { value: PostCardStatus.DRAFT, label: 'Draft', position: 0, color: 'gray' },
        { value: PostCardStatus.SENT, label: 'Sent', position: 1, color: 'orange' },
        { value: PostCardStatus.DELIVERED, label: 'Delivered', position: 2, color: 'green' },
        { value: PostCardStatus.RETURNED, label: 'Returned', position: 3, color: 'orange' },
      ],
    },
    {
      universalIdentifier: 'e06abe72-5b44-4e7f-93be-afc185a3c433',
      name: 'deliveredAt',
      type: FieldType.DATE_TIME,
      label: 'Delivered at',
      icon: 'IconCheck',
      isNullable: true,
      defaultValue: null,
    },
  ],
});

​
Punti chiave

  • Il universalIdentifier deve essere univoco e stabile tra i deployment.
  • Ogni campo richiede un name, type, label e il proprio universalIdentifier stabile.
  • L’array fields è facoltativo: puoi definire oggetti senza campi personalizzati.
  • I campi inline definiti qui non hanno bisogno di un objectUniversalIdentifier — viene ereditato dall’oggetto padre. Usa defineField() per aggiungere campi a oggetti che non possiedi.
  • Puoi generare nuovi oggetti con yarn twenty dev:add object, che ti guida nella denominazione, nei campi e nelle relazioni. Vedi Architettura → Scaffolding delle entità.
I campi base vengono aggiunti automaticamente. Quando definisci un oggetto personalizzato, Twenty crea per te campi standard come id, name, createdAt, updatedAt, createdBy, updatedBy e deletedAt. Non è necessario dichiararli nel tuo array fields — solo i tuoi campi personalizzati. Puoi sovrascrivere un campo predefinito dichiarandone uno con lo stesso nome, ma è raramente una buona idea.

​
Valori predefiniti

I valori predefiniti letterali devono essere racchiusi tra apici singoli all’interno della stringa — defaultValue: "'Draft'", non defaultValue: "Draft". Ecco perché il campo status sopra utilizza `'${PostCardStatus.DRAFT}'`. Le stringhe senza virgolette sono riservate ai valori predefiniti calcolati, valutati quando viene creato un record:
  • 'uuid' — genera un UUID (per i campi UUID)
  • 'now' — il timestamp corrente (per i campi DATE_TIME)
La stessa convenzione si applica ai sotto-campi stringa dei valori compositi predefiniti (ad es. { source: "'MANUAL'" } su un campo ACTOR) e ai valori SELECT/MULTI_SELECT. Una stringa letterale predefinita lasciata senza virgolette genera un avviso quando la tua app viene compilata.

​
Cosa c’è dopo