Přejít na hlavní obsah
Instalační hooky jsou speciální logické funkce, které se spouštějí během životního cyklu instalace nebo upgradu. Sdílí stejný runtime handleru jako běžné logické funkce a přijímají InstallPayload, ale deklarují se pomocí vlastních definičních funkcí — definePostInstallLogicFunction() a definePreInstallLogicFunction() — a fungují mimo běžný model triggerů (HTTP, cron, databázové události). Každá aplikace může definovat nanejvýš jednu pre-install a nanejvýš jednu post-install funkci. Sestavení manifestu skončí chybou, pokud je zjištěno více než jedno.
┌─────────────────────────────────────────────────────────────┐
│ install flow                                                │
│                                                             │
│   upload package → [pre-install] → metadata migration →     │
│   generate SDK → [post-install]                             │
│                                                             │
│                  old schema visible    new schema visible   │
└─────────────────────────────────────────────────────────────┘
Postinstalační funkce se spustí automaticky, jakmile je instalace vaší aplikace v pracovním prostoru dokončena. Server ji provede poté, co byla synchronizována metadata aplikace a vygenerován klient SDK, takže je pracovní prostor plně připraven k použití a nové schéma je zavedeno. Mezi typické případy použití patří naplnění výchozími daty, vytvoření počátečních záznamů, konfigurace nastavení pracovního prostoru nebo zřizování prostředků ve službách třetích stran.
src/logic-functions/post-install.ts
import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';

const handler = async (payload: InstallPayload): Promise<void> => {
  console.log('Post install logic function executed successfully!', payload.previousVersion);
};

export default definePostInstallLogicFunction({
  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
  name: 'post-install',
  description: 'Runs after installation to set up the application.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: false,
  shouldRunSynchronously: false,
  handler,
});
Postinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:
yarn twenty dev:function:exec --postInstall
Hlavní body:
  • Postinstalační funkce používají definePostInstallLogicFunction() — specializovanou variantu, která vynechává nastavení spouštěčů (cronTriggerSettings, databaseEventTriggerSettings, httpRouteTriggerSettings, toolTriggerSettings, workflowActionTriggerSettings).
  • Obslužná funkce obdrží InstallPayload s { previousVersion?: string; newVersion: string }newVersion je verze, která se instaluje, a previousVersion je verze, která byla nainstalována dříve (nebo undefined při čisté instalaci). Tyto hodnoty použijte k rozlišení čistých instalací od aktualizací a ke spuštění migrační logiky specifické pro verzi.
  • Kdy se hook spouští: ve výchozím nastavení pouze při čistých instalacích. Předejte shouldRunOnVersionUpgrade: true, pokud chcete, aby se spouštěl i při aktualizaci aplikace z předchozí verze. Pokud je vynechán, příznak má výchozí hodnotu false a při aktualizacích se hook přeskočí.
  • Model provádění — ve výchozím nastavení asynchronní, synchronní volitelně: příznak shouldRunSynchronously určuje jak se spouští post-install.
    • shouldRunSynchronously: false (výchozí) — hook je zařazen do fronty zpráv s retryLimit: 3 a běží asynchronně ve workeru. Odezva instalace se vrátí hned po zařazení úlohy do fronty, takže pomalá nebo chybující obslužná funkce neblokuje volajícího. Worker se pokusí o opakování až třikrát. Použijte pro dlouho běžící úlohy — plnění velkých datových sad, volání pomalých externích API, zřizování externích prostředků, cokoli, co by mohlo přesáhnout rozumné časové okno HTTP odezvy.
    • shouldRunSynchronously: true — hook se provádí inline během instalačního procesu (stejný vykonavatel jako pre-install). Instalační požadavek blokuje, dokud obslužná funkce nedokončí, a pokud vyvolá výjimku, volající instalace obdrží POST_INSTALL_ERROR. Žádné automatické opakování. Použijte pro rychlé úlohy, které se musí dokončit před odpovědí — například vrácení validační chyby uživateli nebo rychlé nastavení, na kterém bude klient záviset ihned po návratu volání instalace. Mějte na paměti, že v době, kdy se spustí post-install, už byla migrace metadat aplikována, takže selhání v synchronním režimu změny schématu nevrací zpět — pouze odhalí chybu.
  • Ujistěte se, že vaše obslužná funkce je idempotentní. V asynchronním režimu se může fronta pokusit až třikrát; v obou režimech se může hook znovu spustit při aktualizacích, pokud je shouldRunOnVersionUpgrade: true.
  • Proměnné prostředí APPLICATION_ID, APP_ACCESS_TOKEN a API_URL jsou dostupné uvnitř obslužné funkce (stejně jako u jakékoli jiné logické funkce), takže můžete volat Twenty API s aplikačním přístupovým tokenem omezeným na vaši aplikaci.
  • Na jednu aplikaci je povolena pouze jedna postinstalační funkce. Sestavení manifestu skončí chybou, pokud je zjištěna více než jedna.
  • Atributy funkce universalIdentifier, shouldRunOnVersionUpgrade a shouldRunSynchronously jsou během buildu automaticky připojeny k manifestu aplikace do pole postInstallLogicFunction — není potřeba je uvádět v defineApplication().
  • Výchozí časový limit je nastaven na 300 sekund (5 minut), aby umožnil delší úlohy nastavení, jako je naplnění daty.
  • Nespouští se v režimu dev: když je aplikace registrována lokálně (pomocí yarn twenty dev), server zcela přeskočí instalační tok a synchronizuje soubory přímo prostřednictvím sledovače CLI — takže se post-install v režimu dev nikdy nespustí bez ohledu na shouldRunSynchronously. Použijte yarn twenty dev:function:exec --postInstall k ručnímu spuštění nad běžícím pracovním prostorem.
Předinstalační funkce se během instalace spouští automaticky, před aplikováním migrace metadat pracovního prostoru. Má stejný tvar payloadu jako post-install (InstallPayload), ale je zařazena dříve v instalačním toku, aby mohla připravit stav, na němž nadcházející migrace závisí — typické použití zahrnuje zálohování dat, ověření kompatibility s novým schématem nebo archivaci záznamů, které se chystají přeuspořádat nebo odstranit.
src/logic-functions/pre-install.ts
import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';

const handler = async (payload: InstallPayload): Promise<void> => {
  console.log('Pre install logic function executed successfully!', payload.previousVersion);
};

export default definePreInstallLogicFunction({
  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  name: 'pre-install',
  description: 'Runs before installation to prepare the application.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: true,
  handler,
});
Předinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:
yarn twenty dev:function:exec --preInstall
Hlavní body:
  • Funkce pre-install používají definePreInstallLogicFunction() — stejné specializované nastavení jako u post-install, pouze připojené k jiné fázi životního cyklu.
  • Obě obslužné funkce pre- i post-install přijímají stejný typ InstallPayload: { previousVersion?: string; newVersion: string }. Importujte jej jednou a znovu použijte pro oba hooky.
  • Kdy se hook spouští: umístěn těsně před migrací metadat pracovního prostoru (synchronizeFromManifest). Před spuštěním server provede čistě aditivní “zjednodušenou synchronizaci”, která v metadatech pracovního prostoru zaregistruje pre-install funkci nové verze — ničeho dalšího se nedotkne — a poté ji spustí. Protože tato synchronizace je pouze aditivní, objekty, pole a data předchozí verze zůstávají při spuštění vaší obslužné funkce zachována: můžete bezpečně číst a zálohovat stav před migrací.
  • Model provádění: pre-install se provádí synchronně a blokuje instalaci. Pokud obslužná funkce vyvolá výjimku, instalace se přeruší ještě před aplikováním jakýchkoli změn schématu — pracovní prostor zůstane na předchozí verzi v konzistentním stavu. Je to záměrné: pre-install je vaše poslední šance odmítnout rizikovou aktualizaci.
  • Stejně jako u post-install je na jednu aplikaci povolena pouze jedna funkce pre-install. Během buildu je automaticky připojena k manifestu aplikace pod preInstallLogicFunction.
  • Nespouští se v režimu dev: stejně jako u post-install — u lokálně registrovaných aplikací je instalační tok zcela přeskočen, takže se pre-install pod yarn twenty dev nikdy nespustí. Použijte yarn twenty dev:function:exec --preInstall k ručnímu spuštění.
Oba hooky jsou součástí téhož instalačního toku a přijímají stejný InstallPayload. Rozdíl je v tom, kdy se spouštějí vzhledem k migraci metadat pracovního prostoru, a to určuje, jakých dat se mohou bezpečně dotýkat.Pre-install je vždy synchronní (blokuje instalaci a může ji přerušit). Post-install je ve výchozím nastavení asynchronní — zařazen do workeru s automatickými pokusy o opakování — ale může přejít na synchronní provádění pomocí shouldRunSynchronously: true. Viz accordion definePostInstallLogicFunction výše, kdy použít jednotlivé režimy.Použijte post-install pro cokoli, co vyžaduje existenci nového schématu. To je běžný případ:
  • Plnění výchozími daty (vytváření počátečních záznamů, výchozích pohledů, demo obsahu) vůči nově přidaným objektům a polím.
  • Registrace webhooků u služeb třetích stran poté, co má aplikace své přihlašovací údaje.
  • Volání vlastního API k dokončení nastavení, které závisí na synchronizovaných metadatech.
  • Idempotentní logika “zajisti, že to existuje”, která má při každé aktualizaci uvést stav do souladu — kombinujte s shouldRunOnVersionUpgrade: true.
Příklad — po instalaci naplňte výchozí záznam PostCard:
src/logic-functions/post-install.ts
import { definePostInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { createClient } from './generated/client';

const handler = async ({ previousVersion }: InstallPayload): Promise<void> => {
  if (previousVersion) return; // fresh installs only

  const client = createClient();
  await client.postCard.create({
    data: { title: 'Welcome to Postcard', content: 'Your first card!' },
  });
};

export default definePostInstallLogicFunction({
  universalIdentifier: 'f7a2b9c1-3d4e-5678-abcd-ef9876543210',
  name: 'post-install',
  description: 'Seeds a welcome post card after install.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: false,
  handler,
});
Použijte pre-install, pokud by migrace jinak zničila nebo poškodila existující data. Protože pre-install běží proti předchozímu schématu a jeho selhání vrací aktualizaci zpět, je to správné místo pro cokoli rizikového:
  • Zálohování dat, která se chystají odstranit nebo přeuspořádat — např. odstraňujete pole ve verzi v2 a potřebujete jeho hodnoty zkopírovat do jiného pole nebo je před spuštěním migrace exportovat do úložiště.
  • Archivace záznamů, které by nové omezení zneplatnilo — např. pole se stává NOT NULL a je třeba nejprve smazat nebo opravit řádky s hodnotami null.
  • Ověření kompatibility a odmítnutí aktualizace, pokud nelze aktuální data čistě migrovat — vyhoďte výjimku z obslužné funkce a instalace se ukončí bez provedených změn. Je to bezpečnější, než zjistit nekompatibilitu uprostřed migrace.
  • Přejmenování nebo změna klíčů dat před změnou schématu, která by ztratila vazby.
Příklad — archivujte záznamy před destruktivní migrací:
src/logic-functions/pre-install.ts
import { definePreInstallLogicFunction, type InstallPayload } from 'twenty-sdk/define';
import { createClient } from './generated/client';

const handler = async ({ previousVersion, newVersion }: InstallPayload): Promise<void> => {
  // Only the 1.x → 2.x upgrade drops the legacy `notes` field.
  if (!previousVersion?.startsWith('1.') || !newVersion.startsWith('2.')) {
    return;
  }

  const client = createClient();
  const legacyRecords = await client.postCard.findMany({
    where: { notes: { isNotNull: true } },
  });

  if (legacyRecords.length === 0) return;

  // Copy legacy `notes` into the new `description` field before the migration
  // drops the `notes` column. If this fails, the upgrade is aborted and the
  // workspace stays on v1 with all data intact.
  await Promise.all(
    legacyRecords.map((record) =>
      client.postCard.update({
        where: { id: record.id },
        data: { description: record.notes },
      }),
    ),
  );
};

export default definePreInstallLogicFunction({
  universalIdentifier: 'a1b2c3d4-5678-90ab-cdef-1234567890ab',
  name: 'pre-install',
  description: 'Backs up legacy notes into description before the v2 migration.',
  timeoutSeconds: 300,
  shouldRunOnVersionUpgrade: true,
  handler,
});
Zlaté pravidlo:
Chcete…Použít
Naplňte výchozí data, nakonfigurujte pracovní prostor, zaregistrujte externí prostředkypost-install
Spusťte dlouho běžící plnění nebo volání třetích stran, která by neměla blokovat odezvu instalacepost-install (výchozí — shouldRunSynchronously: false, s opakovanými pokusy workeru)
Spusťte rychlé nastavení, na které bude volající spoléhat ihned po návratu volání instalacepost-install s shouldRunSynchronously: true
Čtěte nebo zálohujte data, která by nadcházející migrace ztratilapre-install
Odmítněte aktualizaci, která by poškodila existující datapre-install (vyhoďte výjimku z obslužné funkce)
Spouštějte srovnání stavu při každé aktualizacipost-install s shouldRunOnVersionUpgrade: true
Proveďte jednorázové nastavení pouze při první instalacipost-install s shouldRunOnVersionUpgrade: false (výchozí)
Pokud si nejste jisti, výchozí volbou je post-install. Po pre-install sáhněte pouze tehdy, když je samotná migrace destruktivní a potřebujete zachytit předchozí stav, než zmizí.