Configurația aplicației

​

Prezentare generală

• Identitate — identificator universal, nume de afișare, descriere.
• Permisiuni — sub ce rol rulează funcțiile logice și componentele front-end ale acesteia.
• Capabilități media (opțional): acces la microfon sau cameră solicitat de componentele front-end, aprobat separat de permisiunile de rol.
• Variabile (opțional) — perechi cheie–valoare expuse codului dvs. ca variabile de mediu.
• Hook-uri de pre-instalare / post-instalare / dezinstalare (opțional) — vedeți Funcții logice.
• Facturare (opțional) — billing.recurring pentru taxele de abonament pe care platforma le percepe automat, billing.operations pentru operațiunile pentru care aplicația dvs. percepe credite și billing.description pentru marketplace; consultați Perceperea creditelor.

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

• Câmpurile universalIdentifier sunt UUID-uri pe care le generați o singură dată și pe care le dețineți. Mențineți-le stabile între sincronizări. Propriul universalIdentifier al aplicației trebuie să fie un UUID valid: serverul respinge un manifest al cărui identificator nu este un UUID valid. Este unic în întreaga instanță și este asociat spațiului de lucru care deține înregistrarea sa, astfel încât numai acel spațiu de lucru poate sincroniza aplicația — consultați Proprietatea înregistrării.
• applicationVariables acceptă un label opțional — un nume ușor de înțeles pentru utilizator, afișat în pagina de setări a aplicației în locul cheii brute a variabilei.
• applicationVariables devin variabile de mediu pentru funcțiile și componentele front-end. În funcțiile de logică (server-side), acestea sunt disponibile ca process.env.VARIABLE_NAME. În componentele front-end, folosește getApplicationVariable('VARIABLE_NAME') din twenty-sdk/front-component. Variabilele marcate cu isSecret: true sunt injectate doar în funcțiile de logică. Componentele front-end primesc doar variabile non-secrete. O variabilă cu scope: 'USER' păstrează valoarea membrului pentru care rulează codul: consultați Variabilele spațiului de lucru și ale utilizatorului.
• Aplicația ta poate, de asemenea, să citească și să actualizeze propriile valori ale variabilelor în timpul rulării, astfel salvează o componentă personalizată de setări ceea ce a introdus utilizatorul: consultă Citirea și actualizarea variabilelor în timpul rulării. O aplicație accesează doar propriile variabile, în propriul spațiu de lucru.
• Rolul implicit este detectat automat din fișierul de rol marcat cu defineApplicationRole() — nu este necesar să faci referire la el în defineApplication().
• Funcțiile de pre-instalare, post-instalare și dezinstalare, precum și verificările de stare, sunt detectate automat în timpul construirii manifestului — nu este nevoie să faceți referire la ele în defineApplication().
• Transmiterea explicită a defaultRoleUniversalIdentifier este în continuare acceptată pentru compatibilitate retroactivă, dar este considerată învechită în favoarea defineApplicationRole().
• serverVariables sunt configurări și secrete la nivel de instanță (de ex. chei API). Spre deosebire de applicationVariables, ele nu declară nicio valoare în manifest — operatorul spațiului de lucru le completează din setările aplicației și sunt injectate în funcțiile de logică doar după ce au fost setate.
• O aplicație își poate raporta propria stare de configurare cu defineHealthCheck(), pentru aspecte pe care numai aplicația le poate cunoaște — o cheie prezentă, dar revocată, un cont terț cu planul greșit. isRequired acoperă ceea ce Twenty poate vedea singur; verificarea stării de sănătate acoperă restul. Setați runOnUserPreferences: true pentru a verifica configurația proprie a fiecărui membru în pagina sa de preferințe pentru aplicații, în locul setărilor aplicației pentru spațiul de lucru. Omiterea opțiunii sau setarea acesteia la false păstrează verificarea existentă pentru spațiul de lucru.
• Ambele tipuri de variabile acceptă isRequired: true. O variabilă obligatorie pe care spațiul de lucru nu a completat-o încă lasă aplicația neconfigurată: pagina sa de setări afișează un banner care indică variabilele lipsă, cu un buton care duce la fila în care acestea sunt configurate. Marcați ca obligatoriu doar ceea ce aplicația chiar nu poate rula fără — o variabilă opțională cu o valoare implicită rezonabilă ar trebui să rămână opțională.
• Ambele tipuri de variabile acceptă isDeprecated: true. Folosește-l pentru a retrage o variabilă în loc să o ștergi: păstrarea cheii declarate conservă valoarea stocată (ștergerea ei distruge valoarea introdusă de operator), iar variabila este în continuare injectată, astfel încât codul tău poate reveni la ea — process.env.NEW_API_KEY ?? process.env.API_KEY. O variabilă învechită dispare din setările aplicației odată ce nu mai are nicio valoare și nu este niciodată luată în calcul la verificarea configurației aplicației, astfel încât isDeprecated are prioritate față de isRequired.
• Twenty setează aceste nume pentru fiecare rulare a funcției logice, așadar sunt rezervate: TWENTY_API_URL, TWENTY_APP_ACCESS_TOKEN, TWENTY_APP_APPLICATION_ACCESS_TOKEN, TWENTY_API_KEY, TWENTY_FUNCTIONS_URL, TWENTY_SERVER_ROUTES_URL și APPLICATION_ID. Toate celelalte nume care încep cu TWENTY_ sunt, de asemenea, rezervate, pentru variabilele pe care Twenty le adaugă ulterior. Un manifest care declară un nume rezervat ca variabilă de aplicație sau de server este respins atunci când aplicația este sincronizată sau publicată.
• Pentru a adăuga propriile intrări în meniul de setări al aplicației (în locul paginii generate Variables), declară o componentă front și direcționează un defineSettingsMenuItem() către aceasta, într-un fișier separat. Declară oricâte ai nevoie și ordonează-le cu position; scope plasează un element în setările spațiului de lucru sau în setările proprii ale fiecărui membru. Elementul General gestionat de sistem (actualizare automată, URL-ul aplicației, conexiuni) este întotdeauna primul, iar URL-ul aplicației se afișează numai când aplicația are funcții declanșate prin HTTP.

​

Capabilități media solicitate

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

​

Acces la conținut media pentru site-uri web încorporate

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

​

Tipuri de variabile

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 }

​

Variabilele spațiului de lucru și ale utilizatorului

• WORKSPACE (implicit): o valoare pentru întregul spațiu de lucru, setată de un membru care poate gestiona aplicații.
• USER: fiecare membru își păstrează propria valoare.

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

• Într-o funcție logică, process.env păstrează valorile membrului care a declanșat rularea, același membru ca cel pentru care acționează TWENTY_APP_ACCESS_TOKEN. O rulare fără nicio persoană în spatele ei, cum ar fi o sarcină cron sau un hook de instalare, nu primește deloc variabile de utilizator.
• Într-o componentă front-end, getApplicationVariable returnează valorile membrului care o vizualizează. Variabilele secrete ale utilizatorului sunt omise, la fel ca variabilele secrete ale spațiului de lucru.

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 implicit pentru funcții

• Tokenurile de runtime injectate în funcțiile dvs. de logică sunt derivate din acest rol. Un apel care acționează ca o persoană este restrâns suplimentar la ceea ce poate face acea persoană, astfel încât nu poate depăși niciodată niciuna dintre cele două limite. Consultați Ce acces utilizează un apel.
• Clientul API tipizat este restricționat la permisiunile acordate acelui rol.
• Respectați principiul celui mai mic privilegiu: declarați doar permisiunile de care au nevoie funcțiile.

​

Metadate pentru marketplace