What are Custom Fields?

What are Custom Fields?

Custom Fields let you keep one shared dataset for all your customers, while giving each customer the extra fields that only they need.

Many software companies that embed Luzmo start with one copy of a dataset per customer. It works, until you need to rename a field, fix a formula, or change a format: the change has to be repeated on every copy, and over time the copies drift apart.

With Custom Fields, you manage a single dataset. Fields that everyone uses stay shared. Fields that only one customer (or a few customers) need are scoped to those tenants, so only they see them. Fix a shared calculation once, and every customer gets the fix.

A Custom Field can be:

• a derived column or an aggregation formula that you create for specific customers
• an existing source column of your dataset
• an extra column that exists only in a tenant's own data source (see Tenant data sources)

In this article

• Key concepts
• A worked example
• When should you use Custom Fields?
• How to set up Custom Fields
• Access and permissions
• Fields created by your customers
• Tenant data sources
• Limitations
• Best practices checklist
• FAQ

Key concepts

Tenants

A tenant represents one of your end customers. You create tenants through the API, and you link an embed token to a tenant when your customer's users open a dashboard or the embedded dashboard editor.

If you already use suborganizations in your embed tokens, the tenant defaults to the suborganization value, so every customer is mapped to a tenant in the same way.

Shared fields and tenant fields

Every field in a dataset is either shared or scoped to one or more tenants.

A few rules to keep in mind:

• A field without any tenant assignment is shared. Your existing datasets keep working exactly as before.
• The first assignment limits a field to the assigned tenants. Assignments add up: a field can be visible to tenant A and C, but not B.
• Removing the last assignment makes the field shared again.
• Users of your own organization always see every field.

A worked example

Imagine an Opportunities dataset that you share with three customers.

When a user of Customer A opens the embedded dashboard editor, the field list shows the shared fields plus Customer A's own fields, such as Customer tier. A user of Customer B sees the shared fields plus Region and Lead source. Customer C only sees the shared fields. Nobody sees the fields of another customer, and none of them can tell those fields exist.

If you improve the Win rate formula, all three customers get the new version immediately.

When should you use Custom Fields?

Custom Fields are a good fit when:

• your customers share a core data model, but each needs a few fields of their own
• you maintain many copies of the same dataset and want to reduce them to one
• your customers build their own derived columns or formulas in the embedded dashboard editor, and those should stay private to them

Custom Fields are less suited when:

• all customers use exactly the same fields: a regular shared dataset is enough
• customers have completely different data models: separate datasets remain simpler
• customer-specific attributes are stored as JSON inside a single column: expose them as regular columns first

Which kind of Custom Field to use depends on where the data lives:

How to set up Custom Fields

Setup is done through the Luzmo API today. Your end users don't need to do anything: tenant fields simply appear in the field list of the dashboard editor and the embedded dashboard editor.

1. Create a tenant

Create one tenant per end customer, with a unique identifier and a display name.

POST https://api.luzmo.com/0.1.0/tenant
{
  "action": "create",
  "version": "0.1.0",
  "key": "<your API key>",
  "token": "<your API token>",
  "properties": {
    "identifier": "customer-a",
    "name": { "en": "Customer A" }
  }
}

2. Link your embed tokens to the tenant

When you create an embed authorization for a customer's user, pass the tenant property. If you also pass suborganization, both values must be equal. The token must still give access to the dataset: see Access and permissions.

"properties": {
  "type": "embed",
  "username": "user-123",
  "suborganization": "customer-a",
  "tenant": "customer-a",
  "access": { "datasets": [{ "id": "<dataset id>", "rights": "use" }] },
  ...
}

3. Assign fields to tenants

You assign a field to a tenant by associating it with that tenant. The field itself doesn't change: it simply becomes visible to the assigned tenants only.

A derived column or formula. Create it as usual on the dataset (in the dataset editor, or through the API), then associate it with the tenant.

An existing source column. The column is already in your dataset after the metadata sync. Associate it directly: there is no need to delete or recreate it.

POST https://api.luzmo.com/0.1.0/column
{
  "action": "associate",
  "version": "0.1.0",
  "key": "<your API key>",
  "token": "<your API token>",
  "id": "<column id>",
  "resource": { "role": "Tenants", "id": "<tenant id>" }
}

Use /0.1.0/formula to assign a formula, and dissociate to remove an assignment. With the SDKs, this is the regular associate call, for example client.associate('column', columnId, { role: 'Tenants', id: tenantId }).

Assigning many fields at once. For onboarding, you can send several assignments in a single HTTP request on the tenant resource. The request is all-or-nothing: if one assignment fails, none are applied. This request shape isn't available as an SDK method: send it as a plain HTTP request.

POST https://api.luzmo.com/0.1.0/tenant
{
  "action": "associate",
  "version": "0.1.0",
  "key": "<your API key>",
  "token": "<your API token>",
  "assignments": [
    { "tenant_id": "<tenant A id>", "resource": { "role": "Columns", "id": "<column id>" } },
    { "tenant_id": "<tenant A id>", "resource": { "role": "Formulas", "id": "<formula id>" } }
  ]
}

4. Add the fields to your dashboards

Tenant fields are not added to dashboards automatically.

• A dashboard built on shared fields works for every tenant: each customer sees their own data.
• A dashboard that uses a tenant's own fields is specific to that tenant. In practice, you keep one template on shared fields, and create a variant of it for each customer with custom fields, for example a copy with an extra filter on that customer's fields. You can generate these variants through the API from the template and the customer's list of fields.

Access and permissions

Tenant fields follow dataset access

Tenant scoping is an extra filter on top of the access you give in the embed token. It never grants access on its own: a tenant user only sees the tenant fields of datasets their token gives access to.

What tenant users can do

Who manages tenants and assignments

Creating tenants, assigning fields and managing tenant data sources is reserved to users of your main organization:

• tenant assignments require Modify rights on the dataset
• tenant data sources also require Use rights on the connection

Fields created by your customers

When a customer's user creates a derived column or a formula in the embedded dashboard editor with a tenant-scoped embed token, the new field is automatically scoped to that tenant. Other customers never see it, and you don't need an extra API call.

Fields created by users of your own organization stay shared, unless you assign them.

A tenant can only build on fields it can see. If a derived column or formula references a field that is hidden for the tenant, creation fails with the same error as for a field that doesn't exist. This keeps other customers' fields private.

Tenant data sources

Some customers store their data in their own database or schema, with a few extra columns on top of your standard model. With a tenant data source, one logical dataset reads each tenant's data from that tenant's own table, or from a SQL query.

• Columns that match the shared fields of the dataset are used as shared fields.
• Extra columns in the tenant's source are discovered automatically and appear as tenant fields for that tenant only.
• If two tenants each have a column with the same name, for example Region, each tenant gets its own separate field.
• When a column is added to or removed from the tenant's source, the field list follows automatically.

Create a tenant data source with the tenantdatasetsource resource. It links a tenant and a dataset to a connection, plus exactly one of source_sheet (a table) or source_query (a SQL query).

POST https://api.luzmo.com/0.1.0/tenantdatasetsource
{
  "action": "create",
  "version": "0.1.0",
  "key": "<your API key>",
  "token": "<your API token>",
  "properties": {
    "tenant_id": "<tenant id>",
    "securable_id": "<dataset id>",
    "account_id": "<connection id>",
    "source_query": "SELECT reference, customer, amount, status, created_date, region, lead_source FROM customer_b.opportunities"
  }
}

Limitations

• API-only setup. There is no Luzmo editor screen to manage tenant assignments yet.
• No automatic filters. Tenant scoping controls which fields are visible, not which rows. Keep using your usual row-level security, such as embed token filters or parameters, to limit data.
• No automatic migration. Existing per-customer dataset copies are not merged into a shared dataset automatically.
• No "edit as customer" preview. In the Luzmo editor, your organization sees every field. You can't preview the field list of a specific tenant there.
• Tenant data sources: Warp acceleration is not supported.

Best practices checklist

• Start by moving the fields that every customer uses into one shared dataset.
• Only scope a field when it really belongs to specific customers. Shared is the default for a reason.
• Use a consistent tenant identifier, ideally the same value you already use as suborganization.
• Give tenant users use rights on shared datasets.
• Build your standard dashboards on shared fields only, so one template serves every tenant, and generate customer variants from it.
• Assign fields one by one with the SDK, or use the bulk HTTP request when you onboard a customer with many fields.
• Keep tenant data sources aligned with your shared model: same provider, same shared column names and types.

FAQ

Do I need to enable Custom Fields?

No. Custom Fields are available without a feature flag. Fields without a tenant assignment remain shared, so existing datasets are unaffected.

Are Custom Fields a security feature?

They control which fields a tenant can see and query: a hidden field is removed from the field list and can't be queried. They don't restrict rows. Use embed token filters, parameters or separate connections for row-level access.

Can a field be visible to several tenants?

Yes. Assign the same column or formula to each tenant that needs it.

Can my customers create their own fields?

Yes. Derived columns and formulas created in the embedded dashboard editor with a tenant-scoped token are automatically scoped to that tenant, and they can manage them with use rights.

Can one dashboard show each customer's custom fields?

Not on its own: a filter or chart always points to one specific field, and a tenant's field doesn't exist for other tenants. Keep one template on shared fields, and create a variant per customer that has custom fields.

What happens when I delete a tenant?

The fields that tenant created are cleaned up together with the tenant.

What's the difference with suborganizations?

A suborganization groups the users of one customer for things like access and ownership. A tenant defines which dataset fields that customer sees. In most setups they use the same value.

Related articles

• Using derived columns to enhance your data
• Aggregation formulas
• Cheatsheet: Commonly Used Derived Columns
• Data Ready-for-production Checklist