Tenants

Learn all about Tenants

Multi-tenancy is a common use case for a lot of companies that have multiple organizations that use their applications. In some cases, there is a need to separate the behavior of the notification system depending on the individual tenants.

Currently, Novu supports the following customizations:

• Workflow level customizations
• Integration customizations

Tenant Management

Tenants can be created and modified via the API or Web. Each tenant can have multiple fields on it:

• Identifier - The identifier is a unique value, and can be used later when pointing to this tenant during trigger calls.
• Name - A human-readable name of the tenant.
• Data - A custom data object that can store information about the tenant. This data can be later accessed inside workflows.

To create a tenant on the Novu web platform, follow these steps:

• Click on Tenants on the left sidebar.
• In the Tenants section, click on the Add a tenant button.
• Set a Name and Tenant identifier. The tenant identifier is automatically set once you add a name. However, you can modify it to your needs.
• Set a JSON-format Custom properties (optional).

Workflow Level Customizations

When triggering a workflow, it is possible to pass the tenant information (id or object, in case of an object, novu will upsert the tenant if it’s not existing) like so:

• Node.js
• PHP

  import { Novu } from '@novu/node';

  const novu = new Novu("<NOVU_API_KEY>");

  await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>',
    {
      to: {
        subscriberId: '<UNIQUE_SUBSCRIBER_IDENTIFIER>',
      },
      payload: {
        name: "Hello World",
      },
      actor: "actorId"
      tenant: "tenantIdentifier"
    }
  );

The tenant information can now be used inside the workflow template in the following way:

{{ tenant.data.customProp }}

Workflow Settings Override

Workflow settings can now be updated on the workflow per tenant. This enables each tenant to have unique preferences that doesn’t affect others within the same workflow.

The active and channel preferences fields of a workflow can be updated to be tenant-specific the workflow-overrides API endpoint.

This feature is only available from v0.22.0.

Integration Level Customizations

When creating an integration, you can create a condition where you can specify a delivery provider for a channel when a particular tenant id is matched.

The delivery provider specified will only be used if the trigger is executed with the tenant id.

Add provider instance

Set conditions

Tenant-specific Notification Content

When creating a step, variants could be created for each step including digest and delay. For each variant, conditions set can be applied on when this variant could be used.

Using so different workflow configurations (for example digest duration) could be configured on the individual workflow for a given tenant.

For example, if you want a specific notification content to be sent to a tenant named “JohnDoe”, and another to be sent to others. You can do the following:

• Create an email step in your workflow
• In the email step workflow, click on the “Add variant” icon at the top right to add a new variant.

Add variant

• It opens up the condition page. Set the tenant identifier to equal “JohnDoe”.

Set variant

• Apply Conditions as shown above.
• Check the email step in the workflow, you’ll see the root variant and v1 variant.

See the variants

Once a trigger runs, the Novu engine checks to see if there’s a tenant identifier specified in the trigger code.

An example of the trigger code:

• Node.js
• PHP

  import { Novu } from '@novu/node';

  const novu = new Novu("<NOVU_API_KEY>");

  await novu.trigger('<WORKFLOW_TRIGGER_IDENTIFIER>',
    {
      to: {
        subscriberId: '<UNIQUE_SUBSCRIBER_IDENTIFIER>',
      },
      tenant: "JohnDoe"
    }
  );

• If it exists, a condition check is done to see if there’s a variant that matches the tenant identifier.
• If there’s a match, the specific variant template will be fired.
• If there’s no match, the root variant template will be fired.

It is also possible to use handlebars to have minor tenant adjustments in a single step:

<img src="{{tenant.data.logo}}" />

For self-hosted users, this is only available from version 0.22.0.