Systemmetadaten ansprechen

Lösen Sie die deterministischen universellen Bezeichner der Metadaten auf, die Twenty für jedes Objekt automatisch bereitstellt, damit Ihre App ohne Hardcoding darauf verweisen kann.

Jedes Objekt in Twenty verfügt über Systemmetadaten, die Sie selbst nie deklarieren, wie etwa eine Reihe von Feldern und eine Hauptlistenansicht mit ihren Spalten. Der Server erstellt all dies, wenn das Objekt bereitgestellt wird, und der Umfang wächst mit Twenty.

Da Sie sie nicht deklarieren, gibt es keine universalIdentifier-Konstante, die Sie importieren könnten. Stattdessen leitet der Server jeden Bezeichner deterministisch ab, und twenty-sdk stellt dieselbe Ableitung zur Verfügung, sodass Ihr Manifest den genauen Wert auflösen kann, den der Server verwendet.

​

Systemfelder

Die skalaren Felder, die bei jedem Objekt vorhanden sind und die Sie nicht mit defineField() deklarieren:

id, createdAt, updatedAt, deletedAt, createdBy, updatedBy, position, searchVector

Wie referenzieren Sie also createdAt als Spalte in einer Ansicht?

​

Das Problem

Seit Twenty 2.19 wird die universelle Kennung eines Systemfelds deterministisch abgeleitet vom Server aus drei Eingaben: der universellen Kennung der Applikation, der universellen Kennung des Objekts und dem Feldnamen. Sich eine ID auszudenken und sie hart zu codieren, funktioniert nicht: Sie stimmt mit nichts auf dem Server überein, und die Synchronisierung lehnt die lose Referenz ab:

Dev sync failed: viewField: INVALID_VIEW_DATA: Field metadata not found

​

Die Lösung

getFieldUniversalIdentifier ist ab twenty-sdk 2.21 verfügbar.

Verwenden Sie getFieldUniversalIdentifier, um genau denselben Wert aufzulösen, den der Server verwendet. Die Funktion nimmt die drei Eingaben entgegen und gibt die universelle Kennung des Feldes zurück:

import { getFieldUniversalIdentifier } from 'twenty-sdk/define';

const createdAtFieldId = getFieldUniversalIdentifier({
  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
  name: 'createdAt',
});

• applicationUniversalIdentifier ist die Kennung Ihrer App, diejenige, die Sie an defineApplication() übergeben.
• objectUniversalIdentifier ist die Kennung des Objekts, zu dem das Feld gehört.
• name ist der Name des Systemfelds, einer der oben aufgeführten Werte.

​

Beispiel: eine createdAt-Spalte in einer Ansicht

Der typische Anwendungsfall ist das Hinzufügen einer createdAt-Spalte zu einer Ansicht eines Ihrer benutzerdefinierten Objekte. Lösen Sie die Feld-ID auf und referenzieren Sie sie wie jeden anderen fieldMetadataUniversalIdentifier:

src/views/example-view.ts

import {
  defineView,
  getFieldUniversalIdentifier,
} from 'twenty-sdk/define';

const APPLICATION_UNIVERSAL_IDENTIFIER =
  '0b04e15c-27b2-4741-9046-b32e07469072';
const MY_OBJECT_UNIVERSAL_IDENTIFIER =
  'c782b61c-70fd-4c88-9cd6-4e61ab8d7591';

export default defineView({
  universalIdentifier: '70f10d44-144a-4da8-8c6f-3ec2422138c0',
  name: 'All records',
  objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
  icon: 'IconList',
  position: 0,
  fields: [
    {
      universalIdentifier: '75a90bc4-d901-4df4-85e0-af29db5e0104',
      fieldMetadataUniversalIdentifier: getFieldUniversalIdentifier({
        applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
        objectUniversalIdentifier: MY_OBJECT_UNIVERSAL_IDENTIFIER,
        name: 'createdAt',
      }),
      position: 0,
      isVisible: true,
      size: 200,
    },
  ],
});

Dieselbe aufgelöste ID funktioniert überall dort, wo ein fieldMetadataUniversalIdentifier erwartet wird: Ansichtsfelder, Filter, Sortierungen, Gruppierungen und Page-Layout-Widgets.

Lösen Sie die ID auf, statt sie hart zu codieren. Da der Server den Wert aus der Applikations-ID, der Objekt-ID und dem Feldnamen ableitet, hält ein Aufruf von getFieldUniversalIdentifier Ihre Referenz korrekt, selbst wenn sich diese Eingaben ändern, und verhindert Abweichungen, falls sich die Ableitung jemals weiterentwickelt.

​

System-Relationsfelder

getSystemRelationFieldUniversalIdentifier ist ab Version 2.23 von twenty-sdk verfügbar und erfordert einen Twenty-Server in Version 2.23 oder höher.

Zusätzlich zu den oben genannten skalaren Systemfeldern stellt der Server für jedes Objekt vier System-Relationsfelder bereit: timelineActivities, attachments, noteTargets und taskTargets, die jeweils auf das passende Standard-Relationsobjekt verweisen.

Diese Felder werden nicht mit getFieldUniversalIdentifier aufgelöst: Ihre Kennung wird namenunabhängig abgeleitet, aus dem Objekt, das das Feld enthält, und dem Objekt, auf das das Feld verweist. Auf diese Weise ändert das Umbenennen eines Objekts niemals die Kennungen seiner Relationsfelder.

Verwende getSystemRelationFieldUniversalIdentifier, um sie aufzulösen:

import {
  getSystemRelationFieldUniversalIdentifier,
  STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS,
} from 'twenty-sdk/define';

// rocket.attachments — the relation field hosted on your custom object
const rocketAttachmentsFieldId = getSystemRelationFieldUniversalIdentifier({
  applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  relationTargetObjectUniversalIdentifier:
    STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
});

• objectUniversalIdentifier ist das Objekt, das das Feld enthält.
• relationTargetObjectUniversalIdentifier ist das Objekt, auf das das Feld zeigt.

Die Richtung wird durch die Reihenfolge der Argumente codiert. Um die umgekehrte Seite aufzulösen (z. B. attachment.targetRocket, das Morph-Feld, das der Server auf dem Standard-Relationsobjekt erstellt), vertausche die beiden:

// attachment.targetRocket — the reverse morph field on Attachment
const attachmentTargetRocketFieldId =
  getSystemRelationFieldUniversalIdentifier({
    applicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
    objectUniversalIdentifier:
      STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.attachment.universalIdentifier,
    relationTargetObjectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  });

Wie bei skalaren Systemfeldern funktioniert die aufgelöste ID überall dort, wo ein fieldMetadataUniversalIdentifier erwartet wird.

​

Systemansichten

getSystemViewUniversalIdentifier und getSystemViewFieldUniversalIdentifier sind ab Version 2.26 von twenty-sdk verfügbar und erfordern einen Twenty-Server in Version 2.26 oder höher.

Der Server stellt außerdem für jedes Objekt eine Systemansicht bereit: die Hauptlistenansicht (All {objectLabelPlural}, mit dem Schlüssel ViewKey.INDEX), mit einer Spalte pro anzeigbarem Feld. Wie bei Systembeziehungsfeldern werden ihre Bezeichner namensfrei abgeleitet, sodass das Umbenennen eines Objekts oder eines Feldes sie nie ändert.

Verwenden Sie getSystemViewUniversalIdentifier, um die Ansicht aufzulösen:

import { getSystemViewUniversalIdentifier, ViewKey } from 'twenty-sdk/define';

const rocketIndexViewId = getSystemViewUniversalIdentifier({
  objectMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  objectUniversalIdentifier: ROCKET_OBJECT_UNIVERSAL_IDENTIFIER,
  viewKey: ViewKey.INDEX,
});

• objectMetadataApplicationUniversalIdentifier ist die Anwendung, der das Objekt gehört; sie bestimmt den Namensraum der Ansicht.
• objectUniversalIdentifier ist das Objekt, das die Ansicht auflistet.
• viewKey ist der Systemansichtsschlüssel, aktuell ViewKey.INDEX.

Die aufgelöste ID funktioniert überall dort, wo ein viewUniversalIdentifier erwartet wird, etwa bei einem NavigationMenuItemType.VIEW-Eintrag in der Seitenleiste. Um einfach die Hauptliste eines Objekts zu öffnen, sollten Sie NavigationMenuItemType.OBJECT mit targetObjectUniversalIdentifier bevorzugen: Es benötigt keine Ableitung.

getSystemViewFieldUniversalIdentifier löst eine einzelne Spalte in einer Systemansicht auf, basierend auf der Ansicht und dem Feld, das sie anzeigt:

import { getSystemViewFieldUniversalIdentifier } from 'twenty-sdk/define';

const rocketNameColumnId = getSystemViewFieldUniversalIdentifier({
  fieldMetadataApplicationUniversalIdentifier: APPLICATION_UNIVERSAL_IDENTIFIER,
  viewUniversalIdentifier: rocketIndexViewId,
  fieldMetadataUniversalIdentifier: ROCKET_NAME_FIELD_UNIVERSAL_IDENTIFIER,
});

Beachten Sie das erste Argument: Eine Spalte ist dem Namensraum der Anwendung zugeordnet, die das Feld, das sie anzeigt, besitzt – nicht der Anwendung, der die Ansicht gehört. Ein Feld, das Ihre App zu einem Standardobjekt hinzufügt, erhält seine Spalte im Namensraum Ihrer Anwendung – auf einer Ansicht, die Twenty gehört.

Systemansichten und ihre Spalten sind im Besitz des Servers: Lösen Sie ihre Bezeichner auf, um auf sie zu verweisen, niemals, um sie zu deklarieren. key in defineView() ist veraltet und wird ignoriert, sodass eine Manifestansicht niemals den INDEX-Schlüssel beanspruchen kann, und der Server stellt bereits eine Spalte für jedes Feld bereit, das Sie hinzufügen, sodass das Deklarieren eines eigenen defineViewField() für dasselbe Feld in einer Systemansicht damit in Konflikt steht.

​

Standardobjekte von Twenty

Für ein Standard-Twenty-Objekt (Person, Company, Opportunity, …) müssen Sie nichts ableiten: Die Bezeichner für Felder und Ansichten sind vorab berechnete Konstanten, die Sie direkt importieren können.

import { STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS } from 'twenty-sdk/define';

// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.company.fields.createdAt.universalIdentifier
// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.fields.updatedAt.universalIdentifier
// STANDARD_OBJECT_UNIVERSAL_IDENTIFIERS.person.views.allPeople.universalIdentifier

Greifen Sie auf die obigen Helfer zurück, wenn es sich um ein Objekt handelt, das Ihre App mit defineObject() definiert und für das es keine solche Konstante gibt.

name ist ein Standard-Feld, kein Systemfeld. Es behält seine eigene hart codierte universelle Kennung und wird nicht über getFieldUniversalIdentifier aufgelöst. Für Objekte, die Sie definieren, referenzieren Sie das name-Feld über die Kennung, die Sie ihm in defineObject() gegeben haben.