Configuración de la aplicación

​

Resumen

• Identidad — identificador universal, nombre para mostrar, descripción.
• Permisos — bajo qué rol se ejecutan sus funciones de lógica y componentes de frontend.
• Capacidades multimedia (opcional): acceso al micrófono o a la cámara solicitado por los componentes frontales, aprobado por separado de los permisos de rol.
• Variables (opcionales) — pares clave–valor expuestos a tu código como variables de entorno.
• Hooks de preinstalación / posinstalación / desinstalación (opcionales) — consulta Funciones de lógica.
• Facturación (opcional) — billing.recurring para las tarifas de suscripción que la plataforma cobra automáticamente, billing.operations para aquello por lo que tu aplicación cobra créditos y billing.description para el mercado; consulta Cobro de créditos.

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

• Los campos universalIdentifier son UUID que generas una vez y te pertenecen. Manténlos estables entre sincronizaciones. El universalIdentifier propio de la aplicación debe ser un UUID válido: el servidor rechaza un manifiesto cuyo identificador no es un UUID válido. Es único en toda la instancia y está vinculado al espacio de trabajo propietario de su registro, por lo que solo ese espacio de trabajo puede sincronizar la aplicación; consulta Propiedad del registro.
• applicationVariables acepta una label opcional: un nombre fácil de usar que se muestra en la página de configuración de la aplicación en lugar de la clave de variable sin procesar.
• applicationVariables se convierten en variables de entorno para tus funciones y componentes de frontend. En las funciones lógicas (del lado del servidor), están disponibles como process.env.VARIABLE_NAME. En los componentes de frontend, usa getApplicationVariable('VARIABLE_NAME') de twenty-sdk/front-component. Las variables marcadas con isSecret: true solo se inyectan en las funciones lógicas. Los componentes de frontend solo reciben variables no secretas. Una variable con scope: 'USER' contiene el valor del miembro para el que se ejecuta el código: consulta Variables de espacio de trabajo y de usuario.
• Tu aplicación también puede leer y actualizar los valores de sus propias variables en tiempo de ejecución, que es la forma en que un componente de configuración personalizado guarda lo que escribió el usuario: consulta Lectura y actualización de variables en tiempo de ejecución. Una aplicación solo puede acceder a sus propias variables, en su propio espacio de trabajo.
• El rol predeterminado se detecta automáticamente a partir del archivo de rol marcado con defineApplicationRole(); no necesitas hacer referencia a él desde defineApplication().
• Las funciones de preinstalación, posinstalación y desinstalación, y las comprobaciones de estado, se detectan automáticamente durante la compilación del manifiesto; no necesitas referenciarlas en defineApplication().
• Pasar defaultRoleUniversalIdentifier explícitamente sigue siendo compatible por motivos de retrocompatibilidad, pero está en desuso en favor de defineApplicationRole().
• serverVariables son configuraciones y secretos con ámbito de instancia (por ejemplo, claves de API). A diferencia de applicationVariables, no declaran ningún valor en el manifiesto: el operador del espacio de trabajo los completa desde la configuración de la aplicación, y se inyectan en las funciones lógicas solo una vez que se han establecido.
• Una aplicación puede informar de su propio estado de configuración con defineHealthCheck(), para aquello que solo la aplicación puede saber: una clave que está presente pero revocada, una cuenta de terceros con el plan incorrecto. isRequired cubre lo que Twenty puede ver por sí mismo; la comprobación de estado cubre el resto. Establece runOnUserPreferences: true para comprobar la configuración propia de cada miembro en su página de preferencias de Apps en lugar de en la configuración de la app del espacio de trabajo. Omitir la opción o establecerla en false mantiene la comprobación existente del espacio de trabajo.
• Ambos tipos de variable aceptan isRequired: true. Una variable obligatoria que el espacio de trabajo aún no ha rellenado deja la aplicación sin configurar: su página de configuración muestra un banner que indica las variables que faltan, con un botón que salta a la pestaña donde se configuran. Marca como obligatorio solo lo que la aplicación realmente no puede ejecutar sin ello; una variable opcional con un valor predeterminado razonable debe seguir siendo opcional.
• Ambos tipos de variable aceptan isDeprecated: true. Úsala para retirar una variable en lugar de eliminarla: mantener la clave declarada conserva el valor almacenado (eliminarla destruye el valor que el operador introdujo), y la variable sigue siendo inyectada, por lo que tu código puede recurrir a ella — process.env.NEW_API_KEY ?? process.env.API_KEY. Una variable obsoleta desaparece de la configuración de la app una vez que no tiene ningún valor y nunca cuenta para la verificación de configuración de la app, por lo que isDeprecated tiene prioridad sobre isRequired.
• Twenty establece estos nombres para cada ejecución de función lógica, por lo que están reservados: TWENTY_API_URL, TWENTY_APP_ACCESS_TOKEN, TWENTY_APP_APPLICATION_ACCESS_TOKEN, TWENTY_API_KEY, TWENTY_FUNCTIONS_URL, TWENTY_SERVER_ROUTES_URL y APPLICATION_ID. También se reserva cualquier otro nombre que comience con TWENTY_, para las variables que Twenty agregue más adelante. Un manifiesto que declara un nombre reservado como variable de aplicación o servidor se rechaza cuando la aplicación se sincroniza o publica.
• Para añadir tus propias entradas al menú de configuración de la aplicación (en lugar de la página Variables generada), declara un componente de frontend y apunta un defineSettingsMenuItem() a él, en su propio archivo. Declara tantos como necesites y ordénalos con position; scope coloca un elemento en la configuración del espacio de trabajo o en la configuración propia de cada miembro. El elemento General administrado por el sistema (actualización automática, URL de la app, conexiones) siempre aparece primero, y la URL de la app solo se muestra cuando la app tiene funciones activadas mediante HTTP.

​

Capacidades multimedia solicitadas

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

​

Acceso a medios de sitios web incrustados

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

export default defineApplication({
  universalIdentifier: '39783023-bcac-41e3-b0d2-ff1944d8465d',
  displayName: 'Phone',
  description: 'Call your contacts from Twenty',
  requestedIframeMediaPermissions: [
    { origin: 'https://workspace.aircall.io', microphone: true, camera: false },
  ],
});

​

Tipos de variables

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 }

​

Variables de espacio de trabajo y de usuario

• WORKSPACE (predeterminado): un valor para todo el espacio de trabajo, establecido por un miembro que puede administrar aplicaciones.
• USER: cada miembro conserva su propio valor.

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',
    },
  },
});

• En una función lógica, process.env contiene los valores del miembro que activó la ejecución, el mismo miembro como el que actúa TWENTY_APP_ACCESS_TOKEN. Una ejecución sin nadie detrás, como un trabajo cron o un hook de instalación, no obtiene ninguna variable de usuario.
• En un componente de front-end, getApplicationVariable devuelve los valores del miembro que lo está viendo. Las variables de usuario secretas se omiten, al igual que las variables secretas del espacio de trabajo.

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

​

Rol de función predeterminado

• Los tokens en tiempo de ejecución inyectados en tus funciones de lógica se derivan de este rol. Una llamada que actúa como una persona se limita aún más a lo que esa persona puede hacer, por lo que nunca puede superar ninguno de los dos. Consulta Qué acceso usa una llamada.
• El cliente de API tipado está restringido a los permisos otorgados a ese rol.
• Sigue el principio de mínimo privilegio: declara solo los permisos que necesitan tus funciones.

​

Metadatos del Marketplace