Company Separation

Introduction

If your data and your users are neatly divided by “company”, the Company Separation feature allows you to restrict each user to only see the data for their company. A “company” can be your customer, client, business unit, division, or any such grouping of users and data.

Assumptions

Before you can use Company Separation, you need to verify that the following assumptions hold true:

• Companies are distinct, they don’t overlap or contain other companies
• Each user belongs to a single company
• Tables that need to be separated by company have a company field, and the name of this company field is always the same (e.g., “company_id”) in the data source. In such tables, each record belongs to exactly one company
• If tables have references (foreign keys), we assume that they don’t cross company boundaries. For example, we assume that an invoice for company A will not have a shipping location or payment terms that belong to company B. Therefore, it’s sufficient to check the company field on the invoice when reporting on invoices
• There’s a company table that has the list of companies with a unique company field (e.g., “company_id”) and a display name (e.g., “company_name”)

A few clarifications are needed:

• You can apply company separation to a single data source
• You can apply company separation to multiple data sources. Each data source can define its own company field name, however the values of the company fields must be consistent across data sources because the user can only be assigned to one company
• In the company table, the company field and the display-name field may be the same field

Using Company Separation

To use company separation, follow these high-level steps. We go into details of each steps in the following sections.

1. In Global Settings, define company separation. Specify the company table and select some options.
2. In the Data Sources list, define the company field for any data source for which you want to apply company separation.
3. In the Active Users list, assign a company to each user. For users who should have access to all companies, grant the “all_companies” role instead of assigning them to a company.

Global Settings - Company Separation

To enable company separation, select “Global settings” from the “Admin” menu. In the dialog, go to the “Company Separation” tab and check the box “Enable data separation by company”. The dialog fields are described below:

Data Source

This is the data source where the company table is located. Normally, this is also the data source that will be company-separated. If the company table is not part of that data source. For example, if you uploaded the company information into a table in the Explore data source, then select the Explore data source.

Company Table

This is the table with the list of companies. Select it by typing part of its name or its label and select from the autocomplete.

Company Field

This is the name of the field in the company table that identifies the company. This also becomes the default company field name for the data source to be company-separated (although we can change the data source company field name).

Display Field

This is the name of the field in the company table that provides a humanly-readable company name. This can be the same as the company field or a separate field.

Restrict sharing and publishing to within the same company

In addition to separating data by company, you can also separate the views that are shared or published based on the company separation. If you check this option, shared and published views will be restricted to users within a company. This option is described in more detailed later on this page.

Apply company separation to the "..." data source

With this option checked, company separation will automatically be enabled on the data source of the company table with the same company field as the company table. This automated the next step of setting company separation for the data source.

If, however, you want to set the company separation on the data source later, then keep this option unchecked.

Enable/Disable Company Separation for a Data Source

Each data source can enforce company separation or not. In the list of data sources, the context menu will show one of two options, either “Add company separation” or “Remove company separation”.

When you select “Add company separation”, the following dialog appears for the selected data source.

Company Field

Company separation will apply to any table in this data source that has the company field. By default, the company field is the same as the company field of the company table, however you can change it if this data source uses a difference field name.

When you click OK, company separation will be enforced for this data source for all users except users with the “tenant_admin” or “all_companies” role. If you want to exempt certain non-admin users from company separation, grant them the all_companies role. For all other non-admin users, company separation will be enforced so they only see data for the company to which they are assigned (see next section). If the user is not assigned to a company, they will see an error message telling them that company separation requires that they will be assigned to a company.

Assign User to a Company

Once company separation is defined, you can assign users a company. From the list of Active Users, the context menu will show the option “Assign company”.

When you select this option, the Assign Company dialog will appear.

Company

When you type part of the company name or company id, you can pick the company from the autocomplete drop-down list.

When you click OK, the user will be assigned to this company (and only to this company). When the user access data that is company-separated, they will automatically filter the data to only show data for the company to which they are assigned.

View Separation – Restricting the sharing and publishing by company

When you defined company separation in Global Settings, if you checked the option “Restrict sharing and publishing to within the same company”, then views will also be separated by company.

When a user who is assigned to a company publishes or shares a view, that view will only be shared with users who are assigned to the same company.

View separation is implemented using roles in the following way:

• When a user is assigned to company “A”, they are automatically granted a role named “Company A”. If another user is assigned to company “B”, they will have the “Company B” role.
• When a user is assigned to company “A” and they publish or share a view, that view will now require the “Company A” role or the “all_companies” role. You can see it if you inspect the view’s “read roles”.
• Users who are admins or have the “all_companies” role and publish or share a view, that view will be visible to users of all companies. Such admin users or users who have the “all_companies” role can see views shared by users of all companies.

You can tailor the sharing of a view by editing its read roles.

Creating Views that Ignore Company Separation

By default, views always respect the company separation rules described in previous sections. If you need a view to show data for all companies, even to users who are assigned to a single company, then follow these steps:

1. You must either be a tenant admin or have the “all_companies” role
2. Create the view to show the data you want. For you it always shows data for all companies because you have the tenant_admin or all_companies role
3. Share or publish the view
4. In the list of share view, or the list of published views select the option to ignore company separation

When a view is set to ignore company separation, the view will show information as if company separation was not enabled. To modify the view to respect company separation, use the same context menu on the list of views and this time select the option to “Set this view to respect company separation”.

Removing Company Separation

If you want to remove company separation. Use Global Settings to uncheck “Enable separation by company” and click OK. This will automatically remove company separation from all the data sources that were previously configured for company separation.

After you remove company separation, users’ assignment to a company will remain but will have no effect. Users will also continue to have the company-specific role if view separation was used.

Views will remain separated. To make shared and published views accessible to all users, you’ll need to clear the read roles from all those views. You can do so by selecting multiple views and editing their read roles.

Limitations

Company separation allows you to restrict data and views by company. Other Explore Analytics objects such as dashboard, tables created by users, trend tables, jobs, Apps, Frozen views (created by a scheduled task), and trend tables (populated by a track-trend job) are not separated by company. Such objects created by a user from one company, could be accessed by users from another company.