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.
definePostInstallLogicFunction
Spouští se po aplikování migrace metadat pracovního prostoru
definePostInstallLogicFunction
Spouští se po aplikování migrace metadat pracovního prostoru
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.Postinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:Hlavní body:
src/logic-functions/post-install.ts
- Postinstalační funkce používají
definePostInstallLogicFunction()— specializovanou variantu, která vynechává nastavení spouštěčů (cronTriggerSettings,databaseEventTriggerSettings,httpRouteTriggerSettings,toolTriggerSettings,workflowActionTriggerSettings). - Obslužná funkce obdrží
InstallPayloads{ previousVersion?: string; newVersion: string }—newVersionje verze, která se instaluje, apreviousVersionje verze, která byla nainstalována dříve (neboundefinedpř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í hodnotufalsea při aktualizacích se hook přeskočí. - Model provádění — ve výchozím nastavení asynchronní, synchronní volitelně: příznak
shouldRunSynchronouslyurčuje jak se spouští post-install.shouldRunSynchronously: false(výchozí) — hook je zařazen do fronty zpráv sretryLimit: 3a 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_TOKENaAPI_URLjsou 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,shouldRunOnVersionUpgradeashouldRunSynchronouslyjsou během buildu automaticky připojeny k manifestu aplikace do polepostInstallLogicFunction— není potřeba je uvádět vdefineApplication(). - 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 nashouldRunSynchronously. Použijteyarn twenty dev:function:exec --postInstallk ručnímu spuštění nad běžícím pracovním prostorem.
definePreInstallLogicFunction
Spouští se před aplikováním migrace metadat pracovního prostoru
definePreInstallLogicFunction
Spouští se před aplikováním migrace metadat pracovního prostoru
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 (Předinstalační funkci můžete také kdykoli spustit ručně pomocí CLI:Hlavní body:
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
- 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 devnikdy nespustí. Použijteyarn twenty dev:function:exec --preInstallk ručnímu spuštění.
Pre-install vs post-install: kdy použít který
Výběr správného instalačního hooku
Pre-install vs post-install: kdy použít který
Výběr správného instalačního hooku
Oba hooky jsou součástí téhož instalačního toku a přijímají stejný Použijte Zlaté pravidlo:
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.
PostCard:src/logic-functions/post-install.ts
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 NULLa 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.
src/logic-functions/pre-install.ts
| Chcete… | Použít |
|---|---|
| Naplňte výchozí data, nakonfigurujte pracovní prostor, zaregistrujte externí prostředky | post-install |
| Spusťte dlouho běžící plnění nebo volání třetích stran, která by neměla blokovat odezvu instalace | post-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í instalace | post-install s shouldRunSynchronously: true |
| Čtěte nebo zálohujte data, která by nadcházející migrace ztratila | pre-install |
| Odmítněte aktualizaci, která by poškodila existující data | pre-install (vyhoďte výjimku z obslužné funkce) |
| Spouštějte srovnání stavu při každé aktualizaci | post-install s shouldRunOnVersionUpgrade: true |
| Proveďte jednorázové nastavení pouze při první instalaci | post-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í.