Kurulum Kancaları

definePostInstallLogicFunction

Çalışma alanı üstveri (metadata) geçişi uygulanıp tamamlandıktan sonra çalışır

Kurulum sonrası işlev, uygulamanız bir çalışma alanına kurulmasını tamamladıktan sonra otomatik olarak çalışır. Sunucu, uygulamanın meta verileri senkronize edildikten ve SDK istemcisi oluşturulduktan sonra bunu yürütür; böylece çalışma alanı tamamen kullanıma hazırdır ve yeni şema kullanıma alınmıştır. Tipik kullanım örnekleri arasında varsayılan verilerin tohumlanması, başlangıç kayıtlarının oluşturulması, çalışma alanı ayarlarının yapılandırılması veya üçüncü taraf hizmetlerde kaynak sağlanması yer alır.

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

Ayrıca kurulum sonrası işlevi istediğiniz zaman CLI kullanarak manuel olarak çalıştırabilirsiniz:

yarn twenty exec --postInstall

Önemli noktalar:

Kurulum sonrası işlevler definePostInstallLogicFunction() kullanır — tetikleyici ayarlarını atlayan (cronTriggerSettings, databaseEventTriggerSettings, httpRouteTriggerSettings, toolTriggerSettings, workflowActionTriggerSettings) özel bir varyanttır.
İşleyici, { previousVersion?: string; newVersion: string } içeren bir InstallPayload alır — newVersion, yüklenen sürümdür; previousVersion ise daha önce yüklü olan sürümdür (veya ilk kurulumda undefined). Bu değerleri ilk kurulumları yükseltmelerden ayırt etmek ve sürüme özgü geçiş (migration) mantığını çalıştırmak için kullanın.
Kanca ne zaman çalışır: varsayılan olarak yalnızca ilk kurulumlarda. Uygulama önceki bir sürümden yükseltildiğinde de çalışmasını istiyorsanız shouldRunOnVersionUpgrade: true geçin. Belirtilmediğinde, bayrak varsayılan olarak false olur ve yükseltmeler kancayı atlar.
Yürütme modeli — varsayılan olarak eşzamansız, isteğe bağlı senkron: shouldRunSynchronously bayrağı kurulum sonrası işlemin nasıl yürütüldüğünü kontrol eder.
- shouldRunSynchronously: false (varsayılan) — kanca, retryLimit: 3 ile mesaj kuyruğuna alınır ve bir worker içinde eşzamansız çalışır. İş kuyruğa alınır alınmaz kurulum yanıtı döner; dolayısıyla yavaşlayan veya hata veren bir işleyici çağıranı engellemez. Worker en fazla üç kez yeniden deneyecektir. Bunu uzun süre çalışan işler için kullanın — büyük veri kümelerini tohumlama, yavaş üçüncü taraf API’lerini çağırma, harici kaynakları sağlama; makul bir HTTP yanıt süresini aşabilecek her şey.
- shouldRunSynchronously: true — kanca kurulum akışı sırasında satır içi olarak yürütülür (kurulum öncesi ile aynı yürütücü). İşleyici bitene kadar kurulum isteği engellenir; hata fırlatırsa, kurulum çağıranı bir POST_INSTALL_ERROR alır. Otomatik yeniden deneme yok. Bunu, yanıt dönmeden mutlaka tamamlanması gereken hızlı işler için kullanın — örneğin, kullanıcıya bir doğrulama hatası iletmek veya kurulum çağrısı döner dönmez istemcinin ihtiyaç duyacağı hızlı bir kurulum yapmak. Kurulum sonrası çalıştığında, üstveri (metadata) geçişinin zaten uygulanmış olduğunu unutmayın; bu nedenle, senkron moddaki bir hata şema değişikliklerini geri almaz — yalnızca hatayı görünür kılar.
İşleyicinizin idempotent olduğundan emin olun. Eşzamansız modda kuyruk en fazla üç kez yeniden deneyebilir; her iki modda da shouldRunOnVersionUpgrade: true iken yükseltmelerde kanca tekrar çalışabilir.
Ortam değişkenleri APPLICATION_ID, APP_ACCESS_TOKEN ve API_URL işleyici içinde kullanılabilir (diğer mantık işlevlerinde olduğu gibi), böylece uygulamanıza özel kapsamda bir uygulama erişim belirteciyle Twenty API’sini çağırabilirsiniz.
Uygulama başına yalnızca bir kurulum sonrası işlevine izin verilir. Birden fazla tespit edilirse manifest oluşturma hataya düşer.
İşlevin universalIdentifier, shouldRunOnVersionUpgrade ve shouldRunSynchronously değerleri, derleme sırasında uygulama manifestine postInstallLogicFunction alanı altında otomatik olarak eklenir — bunlara defineApplication() içinde atıfta bulunmanıza gerek yoktur.
Varsayılan zaman aşımı, veri tohumlama gibi daha uzun kurulum görevlerine izin vermek için 300 saniye (5 dakika) olarak ayarlanmıştır.
Geliştirme modunda çalıştırılmaz: bir uygulama yerel olarak kaydedildiğinde (yarn twenty dev aracılığıyla), sunucu kurulum akışını tamamen atlar ve dosyaları doğrudan CLI watcher üzerinden eşitler — bu nedenle, shouldRunSynchronously ne olursa olsun, kurulum sonrası geliştirme modunda hiç çalışmaz. Çalışan bir çalışma alanında bunu elle tetiklemek için yarn twenty exec --postInstall kullanın.

definePreInstallLogicFunction

Çalışma alanı üstveri (metadata) geçişi uygulanmadan önce çalışır

Kurulum öncesi işlev, kurulum sırasında otomatik olarak çalışır ve çalışma alanı üstveri (metadata) geçişi uygulanmadan önce yürütülür. Kurulum sonrası ile (InstallPayload) aynı yük (payload) biçimini paylaşır, ancak kurulum akışında daha erken konumlandığından yaklaşan geçişin bağlı olduğu durumu hazırlayabilir — tipik kullanımlar arasında verileri yedeklemek, yeni şemayla uyumluluğu doğrulamak veya yeniden yapılandırılacak ya da kaldırılacak kayıtları arşivlemek yer alır.

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

Ayrıca kurulum öncesi işlevi istediğiniz zaman CLI kullanarak manuel olarak çalıştırabilirsiniz:

yarn twenty exec --preInstall

Önemli noktalar:

Kurulum öncesi işlevler definePreInstallLogicFunction() kullanır — kurulum sonrasıyla aynı özel yapılandırma, sadece yaşam döngüsünde farklı bir yuvaya eklenir.
Hem kurulum öncesi hem de kurulum sonrası işleyiciler aynı InstallPayload türünü alır: { previousVersion?: string; newVersion: string }. Bunu bir kez içe aktarın ve her iki kanca için yeniden kullanın.
Kanca ne zaman çalışır: çalışma alanı üstveri (metadata) geçişinden hemen önce konumlandırılır (synchronizeFromManifest). Çalıştırmadan önce, sunucu yalnızca ekleyici bir “indirgenmiş eşitleme” yürütür; bu, çalışma alanı üstverisinde yeni sürümün kurulum öncesi işlevini kaydeder — başka hiçbir şeye dokunulmaz — ve ardından bunu yürütür. Bu eşitleme yalnızca ekleyici olduğundan, işleyiciniz çalıştığında önceki sürümün nesneleri, alanları ve verileri hâlâ sağlamdır: geçiş öncesi durumu güvenle okuyabilir ve yedekleyebilirsiniz.
Yürütme modeli: kurulum öncesi senkron olarak yürütülür ve kurulumu bloklar. İşleyici bir hata fırlatırsa, herhangi bir şema değişikliği uygulanmadan önce kurulum iptal edilir — çalışma alanı, tutarlı bir durumda önceki sürümde kalır. Bu kasıtlıdır: kurulum öncesi, riskli bir yükseltmeyi reddetmek için son şansınızdır.
Kurulum sonrası ile aynı şekilde, uygulama başına yalnızca bir kurulum öncesi işlevine izin verilir. Derleme sırasında uygulama manifestine preInstallLogicFunction altında otomatik olarak eklenir.
Geliştirme modunda çalıştırılmaz: kurulum sonrasında olduğu gibi — yerel olarak kaydedilen uygulamalarda kurulum akışı tamamen atlanır, bu nedenle yarn twenty dev altında kurulum öncesi hiç çalışmaz. Bunu elle tetiklemek için yarn twenty exec --preInstall kullanın.

Kurulum öncesi vs kurulum sonrası: hangisini ne zaman kullanmalı

Doğru kurulum kancasını seçme

Her iki kanca da aynı kurulum akışının parçasıdır ve aynı InstallPayload’ı alır. Fark, çalışma alanı üstveri (metadata) geçişine göre ne zaman çalıştıklarıdır ve bu, güvenle erişebilecekleri verileri değiştirir.Kurulum öncesi her zaman senkrondur (kurulumu bloke eder ve iptal edebilir). Kurulum sonrası varsayılan olarak asenkrondur — otomatik yeniden denemelerle bir worker üzerinde kuyruğa alınır — ancak shouldRunSynchronously: true ile senkron yürütmeye geçebilir. Her modun ne zaman kullanılacağı için yukarıdaki definePostInstallLogicFunction akordeonuna bakın.Yeni şemanın mevcut olmasını gerektiren her şey için post-install kullanın. Bu yaygın durumdur:

Yeni eklenen nesne ve alanlara karşı varsayılan verileri tohumlama (ilk kayıtları, varsayılan görünümleri, demo içeriği oluşturma).
Uygulamanın kimlik bilgileri artık mevcut olduğuna göre, üçüncü taraf hizmetlerle webhook’ları kaydetmek.
Eşitlenmiş üstveriye (metadata) bağlı kurulumu tamamlamak için kendi API’nizi çağırmak.
Her yükseltmede durumu uzlaştırması gereken idempotent “bu mevcut olsun” mantığı — shouldRunOnVersionUpgrade: true ile birleştirin.

Örnek — kurulumdan sonra varsayılan bir PostCard kaydı tohumlama:

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

Bir geçiş mevcut verileri aksi takdirde silecek veya bozacaksa pre-install kullanın. Kurulum öncesi önceki şemaya karşı çalıştığı ve hatalandığında yükseltmeyi geri aldığı için, riskli olan her şey için doğru yerdir:

Kaldırılmak veya yeniden yapılandırılmak üzere olan verileri yedekleme — örn. v2’de bir alanı kaldırıyorsunuz ve geçiş çalışmadan önce değerlerini başka bir alana kopyalamanız veya depolamaya aktarmanız gerekiyor.
Yeni bir kısıtın geçersiz kılacağı kayıtları arşivleme — örn. bir alan NOT NULL oluyor ve önce null değerli satırları silmeniz veya düzeltmeniz gerekiyor.
Uyumluluğu doğrulama ve mevcut veriler temiz bir şekilde geçirilemiyorsa yükseltmeyi reddetme — işleyiciden hata fırlatın ve kurulum, herhangi bir değişiklik uygulanmadan iptal edilir. Bu, uyumsuzluğu geçişin ortasında keşfetmekten daha güvenlidir.
İlişkilendirmeyi kaybettirecek bir şema değişikliğinden önce verileri yeniden adlandırma veya yeniden anahtarlama.

Örnek — yıkıcı bir geçişten önce kayıtları arşivleme:

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

Kural olarak:

Şunu yapmak istiyorsunuz…	Kullan
Varsayılan verileri tohumlamak, çalışma alanını yapılandırmak, harici kaynakları kaydetmek	`post-install`
Kurulum yanıtını engellememesi gereken uzun süreli tohumlama veya üçüncü taraf çağrılarını çalıştırmak	`post-install` (varsayılan — `shouldRunSynchronously: false`, worker yeniden denemeleriyle)
Kurulum çağrısı döner dönmez çağıranın güveneceği hızlı kurulumu çalıştırmak	`post-install` ile `shouldRunSynchronously: true`
Yaklaşan geçişin kaybedeceği verileri okumak veya yedeklemek	`pre-install`
Mevcut verileri bozacak bir yükseltmeyi reddetmek	`pre-install` (işleyiciden hata fırlatmak)
Her yükseltmede uzlaştırma çalıştırmak	`post-install` ile `shouldRunOnVersionUpgrade: true`
Yalnızca ilk kurulumda tek seferlik kurulum yapmak	`post-install` ile `shouldRunOnVersionUpgrade: false` (varsayılan)

Emin değilseniz, varsayılan olarak kurulum sonrasını tercih edin. Yalnızca geçişin kendisi yıkıcıysa ve önceki durum yok olmadan önce onu yakalamanız gerekiyorsa kurulum öncesine başvurun.

Genel Bakış

Uygulamalar

API

Kendi Kendine Barındırma

Katkıda Bulunun

Genel Bakış

Uygulamalar

API

Kendi Kendine Barındırma

Katkıda Bulunun

Documentation Index