Multi-Tenancy

A single VARIO Cloud App instance serves multiple tenants (customers). Each tenant has its own data, credentials, and configuration. Multi-tenancy is built into the framework, but you need to be aware of its implications.

How Multi-Tenancy Works

When your app receives a request (API call or webhook), the framework provides context about which tenant the request belongs to:

const { getTenant, getAccessToken } = require('@vario-software/vario-app-framework-backend/utils/context');

app.apiServer.get('/some-endpoint', async (req, res) =>
{
  const tenant = getTenant();           // e.g., "customer-a"
  const token = getAccessToken();       // Contains tenant info

  // All ErpApi calls automatically use the correct tenant
  const data = await ErpApi.vql('SELECT id FROM article.queryArticles LIMIT 1');

  res.json(data);
});

The tenant is extracted from the access token, which is validated by the framework's authentication middleware. You don't need to pass the tenant explicitly — it's automatically available through the context.

Per-Tenant Token Storage

During installation, each tenant receives its own offline token. The framework stores these per tenant:

const { getApp, getTenant } = require('@vario-software/vario-app-framework-backend/utils/context');

// During installation
const app = getApp();
const tenant = getTenant();
await app.offlineToken.set(tenant, offlineToken);

// When making API calls
const token = await app.offlineToken.get(tenant);

The ErpApi class handles this automatically — it retrieves the correct offline token for the current tenant from context.

Data Isolation

Every piece of data in your app must be scoped to the correct tenant:

EAV Data

EAV groups are tenant-scoped by default. When you read or write EAV data, the framework uses the current tenant context:

// This automatically operates on the current tenant's data
const group = await ErpApi.eav.getGroup('my-shop-config');

Local Data

If you store data locally (database, files), include the tenant identifier:

// Scope local storage by tenant
const tenantDbPath = `data/${tenant}/settings.json`;

// Or use tenant as a key prefix
const cacheKey = `${tenant}:lastImportTimestamp`;

Queue Data

If your queue is shared across tenants, include the tenant ID in queue items:

await addToQueue({
  topic: 'article.sync',
  entityId: articleId,
  tenant: getTenant(),        // Include tenant
  salesChannelId: channelId
});

When processing queue items, use runInContext to set the correct tenant context:

const { runInContext } = require('@vario-software/vario-app-framework-backend/utils/context');

async function processQueueItem(item)
{
  await runInContext({ tenant: item.tenant }, async () =>
  {
    // ErpApi calls now use the correct tenant
    await syncArticleToPlatform(item.entityId);
  });
}

Common Pitfalls

Shared State

Avoid global variables that store tenant-specific data. Use the context system instead:

// WRONG — shared across tenants
let currentSalesChannel = null;

app.apiServer.get('/products', async (req, res) =>
{
  currentSalesChannel = req.headers['x-sales-channel'];
  // Another tenant's request could overwrite this!
});

// CORRECT — use request context
app.apiServer.get('/products', async (req, res) =>
{
  const salesChannel = req.headers['x-sales-channel'];
  // Scoped to this request
});

In-Memory Caches

If you use in-memory caches, include the tenant in the cache key:

// WRONG — tenant data could leak
cache.set('lastImport', timestamp);

// CORRECT — tenant-scoped
cache.set(`${getTenant()}:lastImport`, timestamp);

Background Processing

When processing items outside of a request context (e.g., timer-based queue processing), make sure to establish the correct tenant context before making ERP API calls.

Testing Multi-Tenancy

To verify tenant isolation:

1. Install the app on two different test tenants

2. Configure different settings on each tenant

3. Trigger syncs on both tenants

4. Verify that each tenant's data remains separate

5. Check that credentials and tokens don't cross-contaminate