twenty/packages/twenty-docs/l/ko/developers/extend/apps/data/system-fields.mdx

---
title: 시스템 메타데이터 대상 지정
description: Twenty가 모든 객체에 자동으로 프로비저닝하는 메타데이터의 결정론적 범용 식별자를 해석하여, 앱이 하드코딩 없이 이를 참조할 수 있도록 합니다.
icon: gears
---

Twenty의 모든 객체에는 필드 집합과 열이 포함된 기본 목록 보기처럼, 직접 선언하지 않아도 되는 **시스템 메타데이터**가 함께 제공됩니다. 객체가 프로비저닝될 때 서버가 이러한 모든 요소를 생성하며, Twenty가 확장됨에 따라 해당 집합도 함께 증가합니다.

직접 이를 선언하지 않기 때문에, 가져올 수 있는 `universalIdentifier` 상수가 없습니다. 대신 서버는 각 식별자를 결정론적으로 **도출**하며, `twenty-sdk`는 동일한 도출 방식을 제공하여 매니페스트가 서버가 사용하는 정확한 값을 해석할 수 있게 합니다.

## 시스템 필드

모든 객체에 존재하는 스칼라 필드로, [`defineField()`](/l/ko/developers/extend/apps/data/extending-objects)로 선언하지 않는 필드들입니다:

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

그렇다면 [view](/l/ko/developers/extend/apps/layout/views)에서 `createdAt`을 컬럼으로 어떻게 참조할 수 있을까요?

### 문제

Twenty 2.19부터 시스템 필드의 유니버설 식별자는 애플리케이션 유니버설 식별자, 객체 유니버설 식별자, 필드 이름이라는 세 가지 입력값으로부터 서버에서 결정론적으로 도출됩니다. id를 임의로 만들고 하드코딩해도 동작하지 않습니다. 서버에서 어떤 것과도 일치하지 않으며, 동기화에서 이러한 끊어진 참조를 거부합니다:

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

### 해결책

<Note>
  `getFieldUniversalIdentifier`는 `twenty-sdk` 2.21부터 사용할 수 있습니다.
</Note>

`getFieldUniversalIdentifier`를 사용해 서버가 사용하는 것과 정확히 동일한 값을 해석하세요. 이 함수는 세 가지 입력값을 받아 필드의 유니버설 식별자를 반환합니다:

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

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

* `applicationUniversalIdentifier`는 [`defineApplication()`](/l/ko/developers/extend/apps/config/application)에 전달하는, 앱의 식별자입니다.
* `objectUniversalIdentifier`는 필드가 속한 객체의 식별자입니다.
* `name`은 시스템 필드 이름이며, 위에 나열된 값들 중 하나입니다.

### 예시: 뷰의 createdAt 컬럼

일반적인 사용 사례는 커스텀 객체 중 하나의 뷰에 `createdAt` 컬럼을 추가하는 것입니다. 필드 id를 해석한 다음, 다른 `fieldMetadataUniversalIdentifier`와 동일한 방식으로 참조하세요:

```ts 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,
    },
  ],
});
```

이렇게 해석된 동일한 id는 `fieldMetadataUniversalIdentifier`가 필요한 모든 곳에서 사용할 수 있습니다. 예를 들어 view 필드, 필터, 정렬, 그룹, 페이지 레이아웃 위젯 등입니다.

<Note>
  id를 해석해서 사용하고, 하드코딩하지 마세요. 서버는 애플리케이션 id, 객체 id, 필드 이름으로부터 값을 도출하기 때문에,
  `getFieldUniversalIdentifier`를 호출하면 이 입력값들이 변경되더라도 참조를 올바르게 유지할 수 있고, 도출 방식이 바뀌더라도 드리프트를 방지할 수 있습니다.
</Note>

### 시스템 관계 필드

<Note>
  `getSystemRelationFieldUniversalIdentifier`는 `twenty-sdk`
  2.23부터 사용 가능하며, Twenty 서버 버전 2.23 이상이 필요합니다.
</Note>

위에 언급된 스칼라 시스템 필드 외에도 서버는 모든 객체에 `timelineActivities`, `attachments`, `noteTargets`, `taskTargets`라는 네 개의 **시스템 관계 필드**를 제공하며, 각각은 해당하는 표준 관계 객체를 가리킵니다.

이 필드는 `getFieldUniversalIdentifier`로는 해결되지 않습니다. 이들의 식별자는 필드를 호스팅하는 객체와 필드가 가리키는 객체에서 **이름과 무관하게** 도출됩니다. 이 방식이면 객체의 이름을 변경해도 해당 객체의 관계 필드 식별자는 변경되지 않습니다.

이들을 해결하려면 `getSystemRelationFieldUniversalIdentifier`를 사용하세요:

```ts
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`는 필드를 **호스팅하는** 객체입니다.
* `relationTargetObjectUniversalIdentifier`는 필드가 **가리키는** 객체입니다.

방향은 인수의 순서에 의해 인코딩됩니다. 반대쪽(예: `attachment.targetRocket`, 서버가 표준 관계 객체에 생성하는 morph 필드)을 해결하려면 두 인수의 순서를 바꾸면 됩니다:

```ts
// 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,
  });
```

스칼라 시스템 필드와 마찬가지로, 해결된 ID는 `fieldMetadataUniversalIdentifier`가 필요한 곳이면 어디서든 사용할 수 있습니다.

## 시스템 뷰

<Note>
  `getSystemViewUniversalIdentifier`와 `getSystemViewFieldUniversalIdentifier`는 `twenty-sdk` 2.26부터 사용 가능하며, Twenty 서버 버전 2.26 이상이 필요합니다.
</Note>

서버는 또한 모든 객체에 대해 **시스템 뷰**를 프로비저닝합니다. 즉, 표시 가능한 각 필드마다 하나의 열이 있는 기본 목록 보기(`All {objectLabelPlural}`, `ViewKey.INDEX`를 키로 사용)를 제공합니다. 시스템 관계 필드와 마찬가지로, 이들의 식별자는 **이름에 의존하지 않고** 도출되므로, 객체나 필드의 이름을 변경해도 식별자는 절대 바뀌지 않습니다.

뷰를 해석하려면 `getSystemViewUniversalIdentifier`를 사용하세요:

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

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

* `objectMetadataApplicationUniversalIdentifier`는 **객체**를 소유하는 애플리케이션으로, 뷰의 네임스페이스 기준이 됩니다.
* `objectUniversalIdentifier`는 뷰가 목록으로 표시하는 객체입니다.
* `viewKey`는 시스템 뷰 키이며, 현재는 `ViewKey.INDEX`입니다.

해석된 ID는 [`NavigationMenuItemType.VIEW`](/l/ko/developers/extend/apps/layout/navigation-menu-items) 사이드바 항목처럼, `viewUniversalIdentifier`가 필요한 모든 곳에서 사용할 수 있습니다. 객체의 기본 목록만 단순히 열고 싶다면, 파생 과정이 필요 없는 `targetObjectUniversalIdentifier`와 함께 `NavigationMenuItemType.OBJECT`를 사용하는 것이 좋습니다.

`getSystemViewFieldUniversalIdentifier`는 뷰와 해당 뷰에 표시되는 필드 정보를 기반으로 시스템 뷰의 개별 **열**을 해석합니다:

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

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

첫 번째 인자에 주목하세요. 열은 뷰를 소유한 애플리케이션이 아니라, **표시되는 필드를 소유한** 애플리케이션을 기준으로 네임스페이스가 구분됩니다. 앱이 표준 객체에 추가한 필드는, Twenty가 소유한 뷰 위에 있지만 해당 열은 앱이 소유한 애플리케이션 네임스페이스 하에서 도출됩니다.

<Warning>
  시스템 뷰와 그 열은 **서버 소유**입니다. 이들을 참조하기 위해서만 식별자를 해석해야 하며, 직접 선언하는 용도로는 사용해서는 안 됩니다. [`defineView()`](/l/ko/developers/extend/apps/layout/views)의 `key`는 더 이상 사용되지 않으며 무시되므로, 매니페스트 뷰가 `INDEX` 키를 차지할 수 없습니다. 또한 서버는 앱이 추가하는 모든 필드에 대해 이미 열을 프로비저닝하므로, 시스템 뷰에서 동일한 필드에 대해 별도의 `defineViewField()`를 선언하면 서버가 생성한 열과 충돌합니다.
</Warning>

## 표준 Twenty 객체

**표준** Twenty 객체(Person, Company, Opportunity 등)의 경우 어떤 것도 도출할 필요가 없습니다. 필드와 뷰 모두에 대해, 미리 계산된 상수 식별자를 바로 import하여 사용할 수 있습니다.

```ts
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
```

[`defineObject()`](/l/ko/developers/extend/apps/data/objects)로 **앱에서 직접 정의한** 객체처럼, 그러한 상수가 존재하지 않는 경우에는 위에 소개한 헬퍼들을 사용하세요.

<Note>
  `name`은 시스템 필드가 아니라 **기본(default)** 필드입니다. 이 필드는 자체 하드코딩된 유니버설 식별자를 유지하며,
  `getFieldUniversalIdentifier`를 통해 해석되지 않습니다. 여러분이 정의한 객체에서는 `defineObject()`에서 부여한 식별자를 사용해 `name` 필드를 참조하세요.
</Note>