Hook-urile de instalare sunt funcții logice speciale care rulează în timpul ciclului de viață al instalării sau actualizării. Acestea folosesc același runtime de handler ca și funcțiile logice obișnuite și primesc unDocumentation Index
Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
Use this file to discover all available pages before exploring further.
InstallPayload, dar sunt declarate cu propriile lor funcții de definire — definePostInstallLogicFunction() și definePreInstallLogicFunction() — și există în afara modelului obișnuit de declanșatori (HTTP, cron, evenimente de bază de date).
Fiecare aplicație poate defini cel mult o funcție de pre-instalare și cel mult o funcție de post-instalare. Construirea manifestului va genera o eroare dacă se detectează mai mult de una din oricare dintre ele.
definePostInstallLogicFunction
Rulează după ce migrarea metadatelor workspace-ului este aplicată
definePostInstallLogicFunction
Rulează după ce migrarea metadatelor workspace-ului este aplicată
O funcție de post-instalare rulează automat după ce aplicația a terminat de instalat într-un spațiu de lucru. Serverul o execută după ce metadatele aplicației au fost sincronizate și clientul SDK a fost generat, astfel încât spațiul de lucru este complet pregătit pentru utilizare, iar noua schemă este disponibilă. Cazuri tipice de utilizare includ popularea cu date implicite, crearea de înregistrări inițiale, configurarea setărilor spațiului de lucru sau provizionarea resurselor în cadrul serviciilor terților.Puteți, de asemenea, să executați manual funcția post-instalare oricând folosind CLI:Puncte cheie:
src/logic-functions/post-install.ts
- Funcțiile de post-instalare folosesc
definePostInstallLogicFunction()— o variantă specializată care omite setările de declanșare (cronTriggerSettings,databaseEventTriggerSettings,httpRouteTriggerSettings,toolTriggerSettings,workflowActionTriggerSettings). - Handlerul primește un
InstallPayloadcu{ previousVersion?: string; newVersion: string }—newVersioneste versiunea care este instalată, iarpreviousVersioneste versiunea instalată anterior (sauundefinedla o instalare nouă). Folosiți aceste valori pentru a distinge instalările noi de actualizări și pentru a rula logică de migrare specifică versiunii. - Când rulează hook-ul: doar la instalări noi, în mod implicit. Transmiteți
shouldRunOnVersionUpgrade: truedacă doriți să ruleze și atunci când aplicația este actualizată de la o versiune anterioară. Când este omis, indicatorul are implicit valoareafalse, iar actualizările sar peste hook. - Model de execuție — implicit asincron, sincron opțional: indicatorul
shouldRunSynchronouslycontrolează modul în care este executat post-install.shouldRunSynchronously: false(implicit) — hook-ul este pus în coadă în message queue curetryLimit: 3și rulează asincron într-un worker. Răspunsul la instalare revine imediat ce jobul este pus în coadă, astfel încât un handler lent sau care eșuează nu blochează apelantul. Workerul va reîncerca de până la trei ori. Folosiți acest mod pentru joburi de lungă durată — popularea unor seturi mari de date, apelarea API-urilor lente ale terților, provizionarea resurselor externe, orice ar putea depăși o fereastră rezonabilă de răspuns HTTP.shouldRunSynchronously: true— hook-ul este executat inline în timpul fluxului de instalare (același executor ca pre-install). Cererea de instalare blochează până când handlerul se termină, iar dacă acesta aruncă o eroare, apelantul instalării primește unPOST_INSTALL_ERROR. Fără reîncercări automate. Folosiți acest mod pentru sarcini rapide, care trebuie să se finalizeze înainte de răspuns — de exemplu, emiterea unei erori de validare către utilizator sau o configurare rapidă de care clientul va depinde imediat după ce apelul de instalare revine. Reține că migrarea metadatelor a fost deja aplicată până când rulează post-install, astfel încât un eșec în modul sincron nu anulează modificările de schemă — doar expune eroarea.
- Asigurați-vă că handlerul dvs. este idempotent. În modul asincron, coada poate reîncerca de până la trei ori; în oricare mod, hook-ul poate rula din nou la actualizări când
shouldRunOnVersionUpgrade: true. - Variabilele de mediu
APPLICATION_ID,APP_ACCESS_TOKENșiAPI_URLsunt disponibile în interiorul handlerului (la fel ca în orice altă funcție logică), astfel încât puteți apela API-ul Twenty cu un token de acces al aplicației limitat la aplicația dvs. - Este permisă o singură funcție de post-instalare per aplicație. Construirea manifestului va genera o eroare dacă este detectată mai mult de una.
universalIdentifier,shouldRunOnVersionUpgradeșishouldRunSynchronouslyale funcției sunt atașate automat la manifestul aplicației în câmpulpostInstallLogicFunctionîn timpul build-ului — nu este nevoie să le referiți îndefineApplication().- Timpul de expirare implicit este setat la 300 de secunde (5 minute) pentru a permite sarcini de configurare mai lungi, cum ar fi popularea datelor.
- Nu se execută în modul dev: când o aplicație este înregistrată local (prin
yarn twenty dev), serverul sare complet peste fluxul de instalare și sincronizează fișierele direct prin watcher-ul CLI — astfel încât post-install nu rulează niciodată în modul dev, indiferent deshouldRunSynchronously. Folosițiyarn twenty exec --postInstallpentru a-l declanșa manual într-un workspace care rulează.
definePreInstallLogicFunction
Rulează înainte ca migrarea metadatelor workspace-ului să fie aplicată
definePreInstallLogicFunction
Rulează înainte ca migrarea metadatelor workspace-ului să fie aplicată
O funcție de pre-instalare rulează automat în timpul instalării, înainte ca migrarea metadatelor workspace-ului să fie aplicată. Are aceeași structură a payload-ului ca post-install (Puteți, de asemenea, să executați manual funcția de pre-instalare oricând folosind CLI:Puncte cheie:
InstallPayload), dar este plasată mai devreme în fluxul de instalare, astfel încât poate pregăti starea de care depinde migrarea iminentă — utilizări tipice includ realizarea unui backup al datelor, validarea compatibilității cu noua schemă sau arhivarea înregistrărilor care urmează să fie restructurate sau eliminate.src/logic-functions/pre-install.ts
- Funcțiile de pre-instalare folosesc
definePreInstallLogicFunction()— aceeași configurare specializată ca pentru post-install, doar că atașată la un alt punct din ciclul de viață. - Atât handlerele de pre-install, cât și cele de post-install primesc același tip
InstallPayload:{ previousVersion?: string; newVersion: string }. Importați-l o singură dată și reutilizați-l pentru ambele hook-uri. - Când rulează hook-ul: poziționat chiar înainte de migrarea metadatelor workspace-ului (
synchronizeFromManifest). Înainte de execuție, serverul rulează un “sync redus”, pur aditiv, care înregistrează funcția de pre-instalare a versiunii noi în metadatele workspace-ului — nimic altceva nu este atins — și apoi o execută. Deoarece acest sync este doar aditiv, obiectele, câmpurile și datele versiunii precedente sunt încă intacte când rulează handlerul dvs.: puteți citi și face backup în siguranță stării pre-migrare. - Model de execuție: pre-install este executat sincron și blochează instalarea. Dacă handlerul aruncă o eroare, instalarea este întreruptă înainte ca orice modificări de schemă să fie aplicate — workspace-ul rămâne la versiunea anterioară într-o stare consistentă. Acest lucru este intenționat: pre-install este ultima dvs. șansă de a refuza o actualizare riscantă.
- La fel ca la post-install, este permisă o singură funcție de pre-instalare per aplicație. Este atașată automat la manifestul aplicației sub
preInstallLogicFunctionîn timpul build-ului. - Nu se execută în modul dev: la fel ca post-install — fluxul de instalare este sărit complet pentru aplicațiile înregistrate local, astfel încât pre-install nu rulează niciodată sub
yarn twenty dev. Folosițiyarn twenty exec --preInstallpentru a-l declanșa manual.
Pre-install vs post-install: când să folosiți fiecare
Alegerea hook-ului de instalare potrivit
Pre-install vs post-install: când să folosiți fiecare
Alegerea hook-ului de instalare potrivit
Ambele hook-uri fac parte din același flux de instalare și primesc același Folosiți Regulă practică:
InstallPayload. Diferența constă în momentul în care rulează în raport cu migrarea metadatelor workspace-ului, iar asta schimbă ce date pot atinge în siguranță.Pre-install este întotdeauna sincron (blochează instalarea și o poate întrerupe). Post-install este implicit asincron — pus în coadă pe un worker cu reîncercări automate — dar poate opta pentru execuție sincronă cu shouldRunSynchronously: true. Consultați acordeonul definePostInstallLogicFunction de mai sus pentru când să folosiți fiecare mod.Folosiți post-install pentru orice are nevoie ca noua schemă să existe. Acesta este cazul obișnuit:- Popularea datelor implicite (crearea înregistrărilor inițiale, a vizualizărilor implicite, a conținutului demo) pentru obiectele și câmpurile adăugate recent.
- Înregistrarea webhook-urilor la servicii terțe, acum că aplicația are acreditările sale.
- Apelarea propriului dvs. API pentru a finaliza configurarea care depinde de metadatele sincronizate.
- Logică idempotentă de tipul “asigurați-vă că acest lucru există” care ar trebui să reconcilieze starea la fiecare actualizare — combină cu
shouldRunOnVersionUpgrade: true.
PostCard implicită după instalare:src/logic-functions/post-install.ts
pre-install atunci când o migrare altfel ar distruge sau ar corupe datele existente. Deoarece pre-install rulează pe schema anterioară și eșecul său anulează actualizarea, acesta este locul potrivit pentru orice este riscant:- Crearea unui backup al datelor care urmează să fie eliminate sau restructurate — de exemplu, eliminați un câmp în v2 și trebuie să-i copiați valorile într-un alt câmp sau să le exportați în stocare înainte de rularea migrării.
- Arhivarea înregistrărilor pe care o nouă constrângere le-ar invalida — de exemplu, un câmp devine
NOT NULLși trebuie mai întâi să ștergeți sau să corectați rândurile cu valori nule. - Validarea compatibilității și refuzarea actualizării dacă datele curente nu pot fi migrate fără probleme — aruncați din handler și instalarea se oprește fără ca modificări să fie aplicate. Aceasta este mai sigur decât să descoperi incompatibilitatea în mijlocul migrării.
- Redenumirea sau schimbarea cheilor datelor înaintea unei modificări de schemă care ar pierde asocierile.
src/logic-functions/pre-install.ts
| Doriți să… | Folosiți |
|---|---|
| Populați date implicite, configurați workspace-ul, înregistrați resurse externe | post-install |
| Rulați populări de durată sau apeluri către terți care nu ar trebui să blocheze răspunsul la instalare | post-install (implicit — shouldRunSynchronously: false, cu reîncercări ale workerului) |
| Rulați o configurare rapidă de care apelantul va depinde imediat după ce apelul de instalare revine | post-install cu shouldRunSynchronously: true |
| Citiți sau faceți backup datelor pe care migrarea iminentă le-ar pierde | pre-install |
| Respingeți o actualizare care ar corupe datele existente | pre-install (aruncați din handler) |
| Rulați o reconciliere la fiecare actualizare | post-install cu shouldRunOnVersionUpgrade: true |
| Faceți o configurare unică doar la prima instalare | post-install cu shouldRunOnVersionUpgrade: false (implicit) |
Dacă aveți dubii, alegeți implicit post-install. Apelați la pre-install doar când migrarea în sine este distructivă și trebuie să interceptați starea anterioară înainte să dispară.