Skip to main content

Instance Lifecycle

When an instance is created or deleted, lifecycle functions execute to manage resources and perform setup or cleanup tasks. This is useful for configuring third-party resources (like webhooks or cloud storage folders) that are created or deleted alongside the instance.

An instance's lifecycle​

Once a user completes a config wizard and an instance is deployed, the following lifecycle functions are executed in order:

  1. If any flows start with a trigger that contains an onInstanceDeploy function, those functions are executed sequentially, synchronously. Once one onInstanceDeploy function completes, the next one starts. Order of execution is not guaranteed to be the same as the order in which the flows are defined.
  2. After all onInstanceDeploy functions have completed, any flows that start with an Instance Deployed management trigger are run in parallel, asynchronously. The flows run as normal flow executions and do not wait for each other to complete.
  3. After any "Instance Deploy" flows have started (but likely before they complete), if any flows start with a trigger that contains a webhookLifecycleHandlers.create function, those functions are executed sequentially, synchronously. Once one webhook create function completes, the next one starts. Order of execution is not guaranteed to be the same as the order in which the flows are defined.

Example lifecycle execution order​

For example, suppose our integration has 4 flows:

  1. Flow 1's trigger has an onInstanceDeploy function and a webhookLifecycleHandlers.create function.
  2. Flow 2's trigger has only an onInstanceDeploy function.
  3. Flow 3's trigger is an "Instance Deployed" management trigger.
  4. Flow 4's trigger is also an "Instance Deployed" management trigger.

In this case,

  • Flows 1 and 2's onInstanceDeploy functions would run first, one after the other.
  • After those functions complete, flows 3 and 4 would start running in parallel.
  • Not waiting for flows 3 and 4 to complete, flow 1's webhookLifecycleHandlers.create function would run.
lifecycle functions run each time an instance is deployed

Remember, lifecycle functions run each time an instance is deployed. This includes both the initial deployment of the instance and any subsequent re-deployments (for example, when a user updates the instance configuration). It is important that lifecycle functions are idempotent and can handle being run multiple times for the same instance.

onInstanceDeploy trigger functions​

If a trigger includes an onInstanceDeploy function, that function will be executed each time an instance is deployed. This includes both the initial deployment of the instance and any subsequent re-deployments (for example, when a user updates the instance configuration).

These functions are useful for setting up resources in third-party applications that your integration interacts with - things like folders in cloud storage services or custom record types in CRMs.

An onInstanceDeploy function is defined similar to a trigger's perform function and can access the same context and input information.

const acmeFolderWatcher = trigger({
  display: {
    label: "Acme Folder Watcher",
    description: "This trigger watches for changes in a specific folder",
  },
  scheduleSupport: "valid",
  synchronousResponseSupport: "invalid",
  inputs: {
    connection: input({
      label: "Acme Connection",
      type: "connection",
      required: true,
    }),
    folder: input({
      type: "string",
      label: "Folder",
      comments: "The folder where the Acme webhook will send events",
    }),
  },
  /** This function runs each time the flow is invoked (by webhook or schedule) */
  perform: async (_context, payload, _params) => {
    return Promise.resolve({ payload });
  },
  /** This function runs on instance deploy */
  onInstanceDeploy: async (context, params) => {
    context.logger.info(
      `Creating folder ${params.folder} in Acme for instance ${context.instance.id}`,
    );
    await createFolder({
      connection: params.connection,
      folderName: params.folder,
    });
  },
});

Note that these functions run synchronously, one after the other. An instance deployment mutation must complete within 30 seconds, so it's important that onInstanceDeploy functions complete quickly.

onInstanceDelete trigger functions​

onInstanceDelete functions work similarly to onInstanceDeploy functions, but they are executed when an instance is deleted. This allows you to clean up any resources that were created when the instance was deployed.

Management triggers​

Flows that start with an Instance Deployed management trigger are executed after all onInstanceDeploy functions have completed. These flows run in parallel, asynchronously, and do not block the instance deployment process. They are useful for performing longer-running tasks that don't need to complete before the instance is considered deployed (like initial data syncs).

webhookLifecycleHandlers.create trigger functions​

webhookLifecycleHandlers.create functions are executed after any "Instance Deployed" management trigger flows have started (but likely before they complete). These functions are useful for creating webhooks in third-party applications that your integration interacts with.

Additionally, these functions are run outside of the instance deployment process if you enter listening mode in the integration designer. When entering listening mode, this function is run to temporarily create a webhook for testing purposes.

For an example of how to use webhookLifecycleHandlers.create and webhookLifecycleHandlers.delete functions in a trigger, see the Custom Triggers. For an additional real-world example, see our implementation of Asana event triggers in GitHub.

webhookLifecycleHandlers.delete trigger functions​

webhookLifecycleHandlers.delete functions are executed when an instance is deleted and when you exit listening mode in the integration designer. This allows you to clean up any webhooks that were created when the instance was deployed or when entering listening mode.

FAQ​

When should I use onInstanceDeploy vs. webhookLifecycleHandlers.create?​

These functions serve different purposes:

  • Use onInstanceDeploy functions to set up resources in third-party applications that your integration interacts with (like creating folders or custom record types).
  • Use webhookLifecycleHandlers.create functions specifically for creating webhooks in third-party applications.

While both functions run during the instance deployment process, webhookLifecycleHandlers.create functions are also run outside of the instance deployment process if you enter listening mode in the integration designer.

When should I use a trigger function vs. a management trigger?​

An instance deployment must complete within 30 seconds. So, onInstanceDeploy and webhookLifecycleHandlers.create functions should complete quickly. If you have longer-running tasks that need to occur when an instance is deployed (like initial data syncs), use an Instance Deployed management trigger instead. Management triggers generate full executions that can run for up to 15 minutes.