Docs / Phone system

Tenants (companies)

A tenant is one company on the phone system. Every extension, phone, phone number, menu, recording and call record belongs to exactly one tenant, and tenants never see each other. A server for a single business has one tenant; a reseller or a hosted service runs many on the same server. This chapter covers creating, switching off and deleting tenants, what a tenant owns, its administrators and the settings that are kept per tenant.

What a tenant owns

Each tenant has its own:

• number plan: extensions, ring groups, call queues, conference rooms, auto attendants, business hours and paging groups (Extensions and users);
• phones and other devices, including desk phones it has been given and DECT handsets;
• phone numbers (DIDs) and outbound routes (Phone numbers and routes);
• trunks it added for itself (trunks can also be shared by all tenants, see Trunks (carriers));
• prompts and hold music, contacts and directory sources;
• voicemail, call recordings, call history and change history;
• sign-in accounts for its administrators and phone users;
• call limits, recording retention, rate plan and fees.

Extension numbers are per tenant: Acme Dental and another company can both have extension 101. Outside phone numbers are different: a number can be routed only once on the server (per trunk), because the carrier delivers it to the server, not to a company.

Some things belong to the whole server and are managed by system administrators only: trunks marked Shared by all tenants, Server settings, Security, the Server pages, and the list of tenants itself.

Creating a tenant

Only system administrators see the Tenants page.

1. Open Tenants and click New tenant.
2. Fill in Name, Short code, Time zone and Main number (see the table below).
3. Click Create tenant.

The console switches to the new tenant and opens Extensions & numbers with the form for the first extension, because a tenant without extensions cannot make or take calls. Continue with Creating an extension.

If you answered yes when the setup wizard asked about the first tenant, it already exists and appears in the list.

The short code

The short code is 2 to 16 characters: lowercase letters and digits, starting with a letter. Dashes, spaces and underscores are not allowed, so acme, acmedental and acme2 work but acme-dental does not. The code appears in every SIP username of the tenant (acme_101), in the names the engine uses for its objects and in the folder names of its files, which is why it can never change. Pick something short that you will recognise in logs.

Time zone

The tenant's time zone decides when business hours are open, the date and time read out with voicemail messages, and what the speaking clock (*60) says. Use the zone where the company works, not where the server stands. A wrong zone shows up as menus that switch to "closed" an hour or more too early or late.

Main number

The main number is the caller ID for outside calls from any extension that has no outbound caller ID of its own, and for outside callers whose calls are forwarded out again (for example to a ring group member's mobile). It must be 3 to 15 digits with an optional leading +. Without a main number and without an outbound caller ID on the extension, outside calls carry only the extension number, which most carriers refuse. See Caller ID.

Working on one tenant

Most pages of the console show one tenant at a time. A system administrator chooses it in the tenant picker at the top of the console (it shows Acme Dental (acme)), or clicks Manage next to the tenant on the Tenants page, which selects it and opens Extensions & numbers. The choice is remembered while the browser tab stays open.

Tenant administrators have no picker: they always work on their own tenant.

The Tenants page lists every tenant with its main number, the number of extensions (and of all numbers in its plan), its phone numbers (DIDs), time zone and status (Active or Switched off).

Changing a tenant's name, time zone or main number

The console has no form for this yet. Use the command line on the server:

onyx tenant set acme --name "Acme Dental Group" --tz America/Denver --main-number +16125550100

An empty --main-number "" removes the main number. Changes reach the engine within a second. The tenant's hold music is chosen on Prompts & hold music (see Hold music).

Switching a tenant off

To suspend a company without losing anything, for example for an unpaid bill:

1. Open Tenants.
2. Click Switch off next to the tenant.

While a tenant is switched off:

• its phones can no longer register, so they show as unregistered and cannot call;
• calls to its phone numbers are refused as an unallocated number, without being answered;
• no outside calls leave on its behalf, and trunks that belong only to it are not used;
• its tenant administrators and phone users can no longer use the console or the portal.

Everything is kept: extensions, voicemail, recordings, call history and settings. Click Switch on to bring it all back. Only system administrators can switch a tenant on or off. The same from the command line: onyx tenant set acme --enabled off.

Deleting a tenant

Deleting a tenant cannot be undone. Make a backup first if there is any chance you need its data again.

1. Open Tenants.
2. Click Delete next to the tenant. The button changes to Deletes everything: click again.
3. Click it again within four seconds.

This removes the tenant's number plan, devices, phone numbers, outbound routes, its own trunks, prompts and hold music entries, contacts, desk phone assignments, call limits and all its sign-in accounts. Its call records and change history entries stay in the database, no longer linked to a tenant, so the console's pages for a tenant no longer show them.

The tenant's voicemail messages, recordings and audio files stay on the server's disk (under /var/spool/onyx-voice and /var/lib/onyx-voice, in folders named after the tenant code); Onyx Voice does not remove them. If you later create a tenant with the same short code, its mailboxes would find the old messages, so remove those folders first or use a different code.

From the command line, onyx tenant delete acme --yes does the same; without --yes it refuses.

Tenant administrators

A tenant administrator manages one company and nothing else. To give someone that role:

1. Pick the tenant at the top of the console.
2. Open Sign-in accounts and click New account.
3. Enter the Name and E-mail address, choose Tenant administrator under Role and the company under Tenant.
4. Keep the suggested password or click Suggest for another, then click Create account.
5. Click Copy sign-in details and pass them on. The password is not shown again.

A tenant administrator sees only their own tenant: its numbers, phones, routes, prompts, contacts, call history, recordings and reports. They can add trunks for their own tenant, but cannot change shared trunks, switch their tenant off, or open Tenants, Security, Call limits, Server settings or the Server pages. More about accounts, roles and two-factor sign-in is in The web console and sign-in accounts.

Settings kept per tenant

These settings belong to one tenant. Pick the tenant first, then open the page.

Call parking uses number 700 and slots 701 to 720 in every tenant, and a parked call waits 120 seconds; these cannot be changed from the console or the command line. See Call parking.

From the command line

onyx tenant list
onyx tenant add acme --name "Acme Dental" --tz America/Chicago
onyx tenant set acme [--name ..] [--main-number <number>] [--tz <zone>] [--enabled on|off] [--moh <class>|default]
onyx tenant delete acme --yes

onyx tenant add without --tz uses America/Chicago. Its --domain option stores a SIP domain for the tenant, which Onyx Voice does not use yet. Every command is described in Command line (onyx).