Configurazione dell'applicazione

​

Panoramica

• Identità — identificatore universale, nome visualizzato, descrizione.
• Autorizzazioni — il ruolo sotto il quale vengono eseguite le sue funzioni logiche e i componenti front-end.
• Funzionalità multimediali (facoltativo): accesso al microfono o alla fotocamera richiesto dai componenti front, approvato separatamente dalle autorizzazioni del ruolo.
• Variabili (opzionali) — coppie chiave–valore esposte al tuo codice come variabili d’ambiente.
• Hook di pre-installazione / post-installazione / disinstallazione (opzionali) — vedi Funzioni logiche.
• Fatturazione (facoltativa) — billing.recurring per le tariffe di abbonamento che la piattaforma addebita automaticamente, billing.operations per ciò per cui l’app addebita crediti e billing.description per il marketplace; vedi Addebito di crediti.

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

• I campi universalIdentifier sono UUID che generi una sola volta e possiedi. Mantienili stabili tra le sincronizzazioni. Il universalIdentifier dell’applicazione deve essere un UUID valido: il server rifiuta un manifesto il cui identificatore non lo è. È univoco nell’intera istanza ed è associato allo spazio di lavoro proprietario della sua registrazione, quindi solo quello spazio di lavoro può sincronizzare l’app — consulta Proprietà della registrazione.
• applicationVariables accetta un elemento facoltativo label — un nome intuitivo visualizzato nella pagina delle impostazioni dell’app invece della chiave della variabile non elaborata.
• applicationVariables diventano variabili d’ambiente per le tue funzioni e i componenti front-end. Nelle funzioni di logica (lato server), sono disponibili come process.env.VARIABLE_NAME. Nei componenti front-end, usa getApplicationVariable('VARIABLE_NAME') da twenty-sdk/front-component. Le variabili contrassegnate con isSecret: true vengono iniettate solo nelle funzioni di logica. I componenti front-end ricevono solo variabili non segrete. Una variabile con scope: 'USER' contiene il valore del membro per cui viene eseguito il codice: consulta Variabili dell’area di lavoro e dell’utente.
• La tua app può anche leggere e aggiornare i propri valori delle variabili in fase di esecuzione, ed è così che un componente di impostazioni personalizzato salva ciò che l’utente ha digitato: consulta Lettura e aggiornamento delle variabili in fase di esecuzione. Un’applicazione può accedere solo alle proprie variabili, nel proprio spazio di lavoro.
• Il ruolo predefinito viene rilevato automaticamente dal file di ruolo contrassegnato con defineApplicationRole(): non è necessario farvi riferimento da defineApplication().
• Le funzioni di pre-installazione, post-installazione e disinstallazione, nonché i controlli di integrità, vengono rilevate automaticamente durante il build del manifest — non è necessario farvi riferimento in defineApplication().
• Il passaggio esplicito di defaultRoleUniversalIdentifier è ancora supportato per garantire la compatibilità con le versioni precedenti, ma è deprecato a favore di defineApplicationRole().
• serverVariables sono configurazioni e segreti con ambito di istanza (ad esempio chiavi API). A differenza di applicationVariables, non dichiarano alcun valore nel manifest — l’operatore dello spazio di lavoro li compila dalle impostazioni dell’app e vengono iniettati nelle funzioni di logica solo una volta impostati.
• Un’app può segnalare il proprio stato di configurazione con defineHealthCheck(), per ciò che solo l’app può sapere — una chiave presente ma revocata, un account di terze parti con il piano errato. isRequired copre ciò che Twenty può vedere autonomamente; il controllo di integrità copre il resto. Imposta runOnUserPreferences: true per controllare la configurazione di ogni membro nella pagina delle preferenze delle app anziché nelle impostazioni dell’app dello spazio di lavoro. Omettere l’opzione o impostarla su false mantiene il controllo esistente dello spazio di lavoro.
• Entrambi i tipi di variabile accettano isRequired: true. Una variabile obbligatoria che lo spazio di lavoro non ha ancora compilato lascia l’app non configurata: la relativa pagina delle impostazioni mostra un banner che indica le variabili mancanti, con un pulsante che porta alla scheda in cui sono impostate. Contrassegna come obbligatorio solo ciò senza cui l’app non può effettivamente funzionare: una variabile facoltativa con un valore predefinito sensato dovrebbe rimanere facoltativa.
• Entrambi i tipi di variabile accettano isDeprecated: true. Usala per ritirare una variabile invece di eliminarla: mantenere la chiave dichiarata preserva il valore memorizzato (eliminandola si distrugge il valore inserito dall’operatore) e la variabile è ancora iniettata, così il tuo codice può ripiegare su di essa — process.env.NEW_API_KEY ?? process.env.API_KEY. Una variabile deprecata scompare dalle impostazioni dell’app non appena non ha più un valore e non viene mai conteggiata nel controllo di configurazione dell’app, quindi isDeprecated prevale su isRequired.
• Twenty imposta questi nomi per ogni esecuzione di funzioni logiche, pertanto sono riservati: TWENTY_API_URL, TWENTY_APP_ACCESS_TOKEN, TWENTY_APP_APPLICATION_ACCESS_TOKEN, TWENTY_API_KEY, TWENTY_FUNCTIONS_URL, TWENTY_SERVER_ROUTES_URL e APPLICATION_ID. Anche ogni altro nome che inizia con TWENTY_ è riservato, per le variabili che Twenty aggiunge in seguito. Un manifesto che dichiara un nome riservato come variabile dell’applicazione o del server viene rifiutato quando l’app viene sincronizzata o pubblicata.
• Per aggiungere le tue voci al menu delle impostazioni dell’app (al posto della pagina Variables generata), dichiara un front component e configura un defineSettingsMenuItem() affinché punti a esso, in un proprio file. Dichiarane quanti te ne servono e ordinali con position; scope colloca un elemento nelle impostazioni del workspace o nelle impostazioni personali di ciascun membro. L’elemento Generale gestito dal sistema (aggiornamento automatico, URL dell’app, connessioni) è sempre il primo e l’URL dell’app viene visualizzato solo quando l’app dispone di funzioni attivate da HTTP.

​

Funzionalità multimediali richieste

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

​

Accesso ai contenuti multimediali di siti web incorporati

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

​

Tipi di variabili

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 }

​

Variabili dello spazio di lavoro e dell’utente

• WORKSPACE (predefinito): un valore per l’intero spazio di lavoro, impostato da un membro che può gestire le app.
• USER: ogni membro mantiene il proprio valore.

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

• In una funzione logica, process.env contiene i valori del membro che ha attivato l’esecuzione, lo stesso membro di cui agisce TWENTY_APP_ACCESS_TOKEN. Un’esecuzione senza alcun membro associato, come un processo cron o un hook di installazione, non riceve alcuna variabile utente.
• In un componente front-end, getApplicationVariable restituisce i valori del membro che lo visualizza. Le variabili utente segrete vengono omesse, come le variabili segrete dell’area di lavoro.

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

​

Ruolo funzione predefinito

• I token di runtime iniettati nelle funzioni logiche sono derivati da questo ruolo. Una chiamata che agisce come una persona è ulteriormente limitata a ciò che tale persona può fare, quindi non può mai superare nessuno dei due. Vedi L’accesso utilizzato da una chiamata.
• Il client API tipizzato è limitato alle autorizzazioni concesse a quel ruolo.
• Segui il principio del privilegio minimo: dichiara solo le autorizzazioni necessarie alle tue funzioni.

​

Metadati del marketplace