Workflow Interface

Define a workflow

import { workflow } from "@novu/framework";

workflow("my-workflow", async ({ step, payload, subscriber }) => {
  await step.inApp("send-in-app", async () => {
    return {
      body: "Hello there",
    };
  });
}, {
  payloadSchema: z.object({
    body: z.string(),
  }),
  name: "My Workflow",
  description: "This is a workflow",
  tags: ["business", "critical"],
  preferences: {
    channels: {
      inApp: { enabled: true }
    },
  },
});

import { workflow } from '@novu/framework';

workflow(
  workflowId: string,
  handler: WorkflowHandler,
  options?: WorkflowOptions
): WorkflowInstance;

workflowId · number · required

This id should be unique within your organization.

handler · (context: WorkflowContext) => Promise<void> · required

The definition function of the workflow.

options · WorkflowOptions

An optional options object for workflow level configurations

Hide properties

payloadSchema · JsonSchema | ZodSchema

The schema to validate the event payload against, can be used to provide default values.

name · string

The name of the workflow. This is used to display a human-friendly name for the workflow in the Dashboard and <Inbox /> component. If no value is specified, the workflowId will be used as the name.

description · string

The description of the workflow. This is used to provide a brief overview of the workflow in the Dashboard.

tags · string[]

The tags assigned to the workflow. Tags can be used to filter workflows in the dashboard, and can be used by channels such as Inbox to sort Notifications into different categories for a better user experience.

preferences · WorkflowPreferences

The preferences for the workflow. Read more about Workflow Channel Preferences.

Show properties

all · WorkflowPreference

Show properties

enabled · boolean · default: "true"

A flag specifying if notification delivery is enabled for the workflow. If true, notification delivery is enabled by default for all channels. This setting can be overridden by the channel preferences.

readOnly · boolean · default: "false"

A flag specifying if the preferences are read-only. If true, the preferences cannot be changed by the subscriber.

channels · ChannelPreferences

The preferences for the workflow. Read more about Workflow Channel Preferences.

Show properties

inApp · ChannelPreference

Show properties

enabled · boolean · default: "true"

A flag specifying if notification delivery is enabled for the in-app channel. If true, notification delivery is enabled by default.

email · ChannelPreference

Show properties

enabled · boolean · default: "true"

A flag specifying if notification delivery is enabled for the email channel. If true, notification delivery is enabled by default.

sms · ChannelPreference

Show properties

enabled · boolean · default: "true"

A flag specifying if notification delivery is enabled for the SMS channel. If true, notification delivery is enabled by default.

chat · ChannelPreference

Show properties

enabled · boolean · default: "true"

A flag specifying if notification delivery is enabled for the chat channel. If true, notification delivery is enabled by default.

push · ChannelPreference

Show properties

enabled · boolean · default: "true"

A flag specifying if notification delivery is enabled for the push channel. If true, notification delivery is enabled by default.

Workflow Context

This context is passed by the workflow engine to provide contextual information about current workflow execution.

subscriber · Subscriber

Show properties

subscriberId · string · required

The id of the subscriber, as passed during /events/trigger request.

firstName · string

Nullable, the first name of the subscriber.

lastName · string

Nullable, the last name of the subscriber.

payload · InferProperties<payloadSchema>

The payload of the event that triggered the workflow, will be validated against the payloadSchema if provided.

step · object

The object that contains all the step functions, read more at Step Functions.

Workflow Channel Preferences

With Workflow channel preferences, you can control the default delivery preference for a channel and whether a subscriber can change it. Novu will show the subscriber preferences in <Inbox/> component. Subscribers can enable and disable any active channel in the workflow.

In the all object, you can specify default preferences for all channels. The enabled field on the all object is used as fallback value if a channel is not specified explicitly in channels.

The readOnly field controls whether subscribers can change the delivery preference for a channel. Critical workflows are defined with { readOnly: true }.

In the channels object, you can specify In-App, SMS, Email, Chat, and Push channel preferences. Each channel takes an object with an optional enabled flag that controls whether a notification delivery channel is enabled or disabled by default for subscribers.

Default values

By default, enabled is true for all channels. The readOnly flag is false.

These preferences can also be controlled from the Novu Dashboard per workflow. To do so, click on the cog icon at the top right of your screen, and then select the “Preferences” tab.

Default

const newWorkflow = workflow(
  'default-preferences',
  async ({ step }) => {
    await step.inApp('send-in-app', () => ({
      body: 'Hello there',
    }));
  },
  {
    preferences: {
      {
        all: { enabled: true, readOnly: false },
        channels: {
          inApp: { enabled: true },
          email: { enabled: true },
          sms: { enabled: true },
          chat: { enabled: true },
          push: { enabled: true },
        },
      }
    },
  }
);

const newWorkflow = workflow(
  'default-preferences',
  async ({ step }) => {
    await step.inApp('send-in-app', () => ({
      body: 'Hello there',
    }));
  },
  {
    preferences: {
      {
        all: { enabled: true, readOnly: false },
        channels: {
          inApp: { enabled: true },
          email: { enabled: true },
          sms: { enabled: true },
          chat: { enabled: true },
          push: { enabled: true },
        },
      }
    },
  }
);

const newWorkflow = workflow(
  'only-in-app-channel',
  async ({ step }) => {
    await step.inApp('send-in-app', () => ({
      body: 'Hello there',
    }));
  },
  {
    preferences: {
      {
        all: { enabled: false },
        channels: {
          inApp: { enabled: true },
        },
      }
    },
  }
);

const newWorkflow = workflow(
  'all-enabled-editable',
  async ({ step }) => {
    await step.inApp('send-in-app', () => ({
      body: 'Hello there',
    }));
  },
  {
    preferences: {
      {
        all: { enabled: true },
      }
    },
  }
);

const newWorkflow = workflow(
  'all-enabled-read-only',
  async ({ step }) => {
    await step.inApp('send-in-app', () => ({
      body: 'Hello there',
    }));
  },
  {
    preferences: {
      {
        all: { enabled: true, readOnly: true },
      }
    },
  }
);

const newWorkflow = workflow(
  'all-disabled-editable',
  async ({ step }) => {
    await step.inApp('send-in-app', () => ({
      body: 'Hello there',
    }));
  },
  {
    preferences: {
      {
        all: { enabled: false, readOnly: false },
      }
    },
  }
);

const newWorkflow = workflow(
  'in-app-disabled-editable',
  async ({ step }) => {
    await step.inApp('send-in-app', () => ({
      body: 'Hello there',
    }));
  },
  {
    preferences: {
      {
        channels: {
          inApp: { enabled: false },
        },
      }
    },
  }
);