Конфигурация приложения

​

Обзор

• Идентификация — универсальный идентификатор, отображаемое имя, описание.
• Разрешения — от имени какой роли выполняются его логические функции и фронтенд-компоненты.
• Возможности доступа к медиа (необязательно): доступ к микрофону или камере, запрашиваемый фронтенд-компонентами, утверждается отдельно от ролевых разрешений.
• Переменные (необязательно) — пары ключ–значение, доступные вашему коду как переменные окружения.
• Хуки предустановки / постустановки / удаления (необязательно) — см. Логические функции.
• Платёжные данные (необязательно) — billing.recurring для автоматически взимаемых платформой платежей за подписку, billing.operations для операций, за которые ваше приложение списывает кредиты, и billing.description для маркетплейса; см. Списание кредитов.

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

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'My Twenty App',
  description: 'My first Twenty app',
  applicationVariables: {
    DEFAULT_RECIPIENT_NAME: {
      universalIdentifier: '19e94e59-d4fe-4251-8981-b96d0a9f74de',
      label: 'Default recipient name',
      description: 'Default recipient name for postcards',
      value: 'Jane Doe',
      isSecret: false,
    },
    API_KEY: {
      universalIdentifier: '6b1f5a02-7c4d-4a19-9e63-2f0c8a5d1b47',
      label: 'API key',
      description: 'Key used to reach the postcard provider',
      isSecret: true,
      isRequired: true,
    },
  },
});

• Поля universalIdentifier — это UUID, которые вы создаёте один раз и которыми владеете. Сохраняйте их неизменными при синхронизации. Собственный universalIdentifier приложения должен быть допустимым UUID: сервер отклоняет манифест, идентификатор которого не является UUID. Он уникален в пределах всего экземпляра и привязан к рабочему пространству, которому принадлежит его регистрация, поэтому синхронизировать приложение может только это рабочее пространство — см. Владение регистрацией.
• applicationVariables принимает необязательный параметр label — понятное пользователю имя, отображаемое на странице настроек приложения вместо исходного ключа переменной.
• applicationVariables становятся переменными окружения для ваших функций и фронтенд-компонентов. В логических функциях (на стороне сервера) они доступны как process.env.VARIABLE_NAME. Во фронтенд-компонентах используйте getApplicationVariable('VARIABLE_NAME') из twenty-sdk/front-component. Переменные, помеченные как isSecret: true, внедряются только в логические функции. Фронтенд-компоненты получают только несекретные переменные. Переменная с scope: 'USER' хранит значение участника, для которого выполняется код: см. Переменные рабочей области и пользователя.
• Ваше приложение также может считывать и обновлять значения собственных переменных во время выполнения. Именно так пользовательский компонент настроек сохраняет введённые пользователем данные: см. Чтение и обновление переменных во время выполнения. Приложение имеет доступ только к собственным переменным в собственном рабочем пространстве.
• Роль по умолчанию автоматически определяется из файла роли, помеченного с помощью defineApplicationRole() — вам не нужно ссылаться на неё из defineApplication().
• Функции предустановки, постустановки и удаления, а также проверки работоспособности, обнаруживаются автоматически во время сборки манифеста — вам не нужно указывать их в defineApplication().
• Явная передача defaultRoleUniversalIdentifier по-прежнему поддерживается для обратной совместимости, но считается устаревшей и вместо неё рекомендуется использовать defineApplicationRole().
• serverVariables — это параметры конфигурации и секреты в области экземпляра (например, ключи API). В отличие от applicationVariables, значения для них не указываются в манифесте — оператор рабочего пространства заполняет их в настройках приложения, и они внедряются в логические функции только после того, как будут заданы.
• Приложение может сообщать о собственном состоянии конфигурации с помощью defineHealthCheck() для того, о чём может знать только само приложение, — например, ключ присутствует, но отозван, или сторонняя учётная запись использует неподходящий тарифный план. isRequired охватывает то, что Twenty может увидеть самостоятельно; проверка работоспособности охватывает остальное. Установите runOnUserPreferences: true, чтобы проверять собственные настройки каждого участника на странице настроек Apps вместо настроек приложений рабочего пространства. Если не указывать этот параметр или установить для него значение false, будет сохранена существующая проверка рабочего пространства.
• Оба типа переменных принимают isRequired: true. Обязательная переменная, которую рабочая область ещё не заполнила, оставляет приложение ненастроенным: на странице его настроек отображается баннер с указанием отсутствующих переменных и кнопкой для перехода на вкладку, где они задаются. Отмечайте как обязательное только то, без чего приложение действительно не может работать — необязательная переменная с разумным значением по умолчанию должна оставаться необязательной.
• Оба типа переменных принимают isDeprecated: true. Используйте это, чтобы вывести переменную из обращения вместо её удаления: сохранение объявленного ключа сохраняет хранимое значение (удаление уничтожает значение, введённое пользователем), а переменная по-прежнему внедряется, поэтому код сможет обратиться к ней — process.env.NEW_API_KEY ?? process.env.API_KEY. Устаревшая переменная исчезает из настроек приложения, как только у неё больше нет значения, и никогда не учитывается при проверке конфигурации приложения, поэтому isDeprecated имеет приоритет над isRequired.
• Twenty задает эти имена для каждого запуска функции логики, поэтому они зарезервированы: TWENTY_API_URL, TWENTY_APP_ACCESS_TOKEN, TWENTY_APP_APPLICATION_ACCESS_TOKEN, TWENTY_API_KEY, TWENTY_FUNCTIONS_URL, TWENTY_SERVER_ROUTES_URL и APPLICATION_ID. Все остальные имена, начинающиеся с TWENTY_, также зарезервированы для переменных, которые Twenty добавит позже. Манифест, объявляющий зарезервированное имя в качестве переменной приложения или сервера, отклоняется при синхронизации или публикации приложения.
• Чтобы добавить собственные элементы в меню настроек приложения (вместо созданной страницы Variables), объявите фронтенд-компонент и укажите его в defineSettingsMenuItem() в отдельном файле. Объявите столько элементов, сколько необходимо, и упорядочьте их с помощью position; scope размещает элемент в настройках рабочего пространства или в настройках каждого участника. Системный элемент Общие (автообновление, URL приложения, подключения) всегда отображается первым, а URL приложения показывается только если в приложении есть функции, запускаемые по HTTP.

​

Запрашиваемые возможности доступа к медиа

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

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'Media recorder',
  description: 'Record audio and video in your workspace',
  requestedCapabilities: ['microphone', 'camera'],
});

​

Типы переменных

import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    MAX_POSTCARDS: {
      universalIdentifier: '5f4497e4-9030-4085-85eb-2c48b8d53713',
      description: 'Maximum postcards per batch',
      type: FieldType.NUMBER,
      value: 10,
    },
    DEFAULT_REGION: {
      universalIdentifier: '76c5c321-b6b6-46eb-b4fc-f9f04bb04227',
      description: 'Default shipping region',
      type: FieldType.SELECT,
      options: [
        { label: 'Europe', value: 'eu' },
        { label: 'United States', value: 'us' },
      ],
      value: 'eu',
    },
  },
});

const maxCards = Number(process.env.MAX_POSTCARDS); // "10" -> 10
const enabled = process.env.ENABLE_TRACKING === 'true'; // "true" -> true
const channels = JSON.parse(process.env.ENABLED_CHANNELS ?? '[]'); // '["email"]' -> ["email"]
const config = JSON.parse(process.env.PROVIDER_CONFIG ?? '{}'); // '{"retries":3}' -> { retries: 3 }

​

Переменные рабочей области и пользователя

• WORKSPACE (по умолчанию): одно значение для всей рабочей области, заданное участником, который может управлять приложениями.
• USER: каждый участник хранит собственное значение.

import { defineApplication, FieldType } from 'twenty-sdk/define';

export default defineApplication({
  // ...identity, role...
  applicationVariables: {
    RECORD_MY_MEETINGS: {
      universalIdentifier: '0b6f3c1e-8a2d-4f57-9c1b-7e4d2a9f6c30',
      label: 'Record my meetings',
      type: FieldType.BOOLEAN,
      value: true,
      scope: 'USER',
    },
  },
});

• В логической функции process.env содержит значения участника, который инициировал запуск, то есть того же участника, от имени которого действует TWENTY_APP_ACCESS_TOKEN. Запуск, за которым никто не стоит, например задание cron или хук установки, вообще не получает пользовательских переменных.
• Во фронтальном компоненте getApplicationVariable возвращает значения участника, который его просматривает. Секретные пользовательские переменные исключаются, как и секретные переменные рабочей области.

import { MetadataApiClient } from 'twenty-client-sdk/metadata';

// In a logic function, for example a cron job
const client = new MetadataApiClient({ runAs: 'application' });

const { myUserApplicationVariables } = await client.query({
  myUserApplicationVariables: {
    workspaceMemberId: true,
    variables: { key: true, value: true },
  },
});

​

Роль функции по умолчанию

• Токены времени выполнения, подставляемые в ваши функции логики, формируются из этой роли. Вызов, выполняемый от имени пользователя, дополнительно ограничен тем, что может делать этот пользователь, поэтому он никогда не может превышать ни один из них. См. Чей доступ использует вызов.
• Типизированный клиент API ограничен правами, предоставленными этой роли.
• Следуйте принципу наименьших привилегий: объявляйте только те разрешения, которые действительно нужны вашим функциям.

​

Метаданные маркетплейса