Domain/tenant mapping feature

Available in ≥ 3.5.x-funcrel

Overview

As described in Working with domains, domains are a method of grouping applications together. Out of the box, domain groupings can be used in conjunction with user access requirements, however, they can also support additional scenarios:

Functional or technical application grouping – particularly when App to App dependencies must not cross functional or technical boundaries
Database size management – controlling where imaging-viewer results are stored.

These use cases are enabled through the domain/tenant mapping feature described below.

Default configuration: single database mode

By default, CAST Imaging operates in “single database” mode, where all imaging-viewer application results are stored in a single Neo4j database (otherwise known as a “tenant”). In this configuration, data from multiple applications resides in one shared database (“tenant”) named “default” - a setup that works well for most installations and use cases while remaining transparent to end-users:

Domain/tenant mapping: multi-database mode

When you enable domain mapping, each domain is mapped to its own dedicated Neo4j database (“tenant”) for storing imaging-viewer results. Applications assigned to a domain store their results in that domain’s database, while unassigned applications continue using the “default” database:

This configuration provides two key benefits:

Enhanced data isolation: The App to App Dependencies respects domain boundaries - interactions between applications are restricted to those within the same domain, preventing unauthorized cross-domain data access. Without domain/tenant mapping, App to App Dependencies are generated across all applications regardless of domain assignment.
Improved database scalability: Database size can be managed more effectively, particularly in environments with many large applications. Without domain/tenant mapping, the single database can grow unwieldy as all application data accumulates in one location.

At what moment can I enable this feature?

The domain/tenant mapping feature can be enabled at any moment, however there are important considerations that should be understood before doing so:

Enabling in fresh installations of CAST Imaging

CAST highly recommends that the feature is enabled as part of the process of installing a fresh instance of CAST Imaging, i.e. in the following scenarios:

Fresh installations of CAST Imaging 3.5.0-funcrel or later
Migrations to 3.5.0-funcrel or later (where a fresh instance of CAST Imaging is installed) from CAST Imaging v2 where the equivalent feature was already enabled

Enabling in existing installations of CAST Imaging

While technically possible to enable this feature in existing installations of CAST Imaging 3.5.0-funcrel or later, doing so has important data loss consequences:

When you enable domain/tenant mapping in an instance where domains have already been created and existing applications have been assigned to them, the next analysis and view generation process will create results in a new dedicated Neo4j database. This means all previous customizations made in the application will be lost, including:

Tags
Post-it notes
Saved views
Custom objects
History/Compare data

These customizations cannot be retrieved because they remain in the original “default” database and will no longer be accessible. This must be taken into account if you decide to enable the feature:

in an existing installation of 3.5.0-funcrel or later
when you update to 3.5.0-funcrel or later from a previous 3.x release
when you migrate to 3.5.0-funcrel or later release (where a fresh instance of CAST Imaging is installed) from CAST Imaging v2 where the equivalent feature was disabled

How do I enable this feature?

Enabling the domain/tenant mapping feature is achieved as follows:

Microsoft Windows: requires a system level environment variable to be in place on the machine on which the imaging-services component is installed
Linux via Docker: enabled via an option in the installation configuration file / .env file

Microsoft Windows

Create a system environment variable on the machine on which the imaging-services component is to be installed or is already installed, as follows:
- variable name = IMAGING_SYNCHRO_DOMAIN_ENABLED
- variable value = true
Then depending on the scenario:
- perform the installation as normal
- or reboot the imaging-services component to ensure the setting is taken into account

Linux via Docker

Fresh installation

Locate the configuration.conf file at the root of the unzipped installation media files and open it in a text editor such as nano or vi.
Update the IMAGING_DOMAIN_SYNCHRO_ENABLED option to true.
Perform the installation as normal.

Existing installation

Edit the following file located on the machine where the imaging-services component is running with a text editor such as nano or vi:

/opt/cast/installation/imaging-services/.env

Locate the following line and update the variable to true, e.g.:

IMAGING_DOMAIN_SYNCHRO_ENABLED=true

Restart the following components and containers via docker compose to ensure the change is taken into account:

$ cd /opt/cast/installation/imaging-services/ # imaging-services component
$ sudo docker compose down
$ sudo docker compose up -d
$ cd /opt/cast/installation/imaging-viewer/ # imaging-viewer component
$ sudo docker compose down
$ sudo docker compose up -d
$ cd /opt/cast/installation/imaging-node/ # analysis-node component
$ sudo docker compose down
$ sudo docker compose up -d

It is not necessary to restart the dashboards service/containers.
If you have multiple analysis-node components in a distributed deployment, ensure you restart them all.

When enabled, how does the feature work?

If an application belongs to a domain (DOMAIN1), the application will be uploaded to a Neo4j database (“tenant”) with the same name (DOMAIN1) when the generate views analysis option is run. If the equivalent database (DOMAIN1) does not already exist, it will be created.

If an application belongs to a domain (DOMAIN1) and a database (“tenant”) with the same name (DOMAIN1) already exists, the application will be uploaded to that same database (DOMAIN1) when the generate views analysis option is run.
If an application does not belong to a domain, the application will be uploaded to the “default” database (“tenant”).

Note that in the current release where the domain mapping feature is enabled: when an application has been assigned to a domain and the generate views analysis option has been run, it is not currently possible to re-assign the application to a different domain. In other words the application cannot be “moved” to a different domain/tenant - instead it will need to be deleted and recreated in the appropriate domain.

What about domain names

When the domain/tenant mapping feature is enabled, naming constraints are applied to domain names as follows:

a minimum of three characters
contain only alphanumeric characters or an underscore
not one of the following reserved names:
- “default”
- “neo4j”
- “imaging”
- “packageReference”
- “system”

Therefore:

any new domain created after the domain/tenant mapping is enabled must conform to these constraints - the UI will prevent the creation of the domain name where it does not conform.
any existing domain created before the domain/tenant mapping is enabled and which do not conform to these constraints will continue to exist but all applications will be stored in the “default” Neo4j database (“tenant”) as was the case before the feature was enabled.

What about user permissions?

There is no change to the way in which user permissions function when the domain/tenant mapping feature is enabled: roles are assigned to profiles and profiles are assigned to users and groups of users as normal. Application and domain access can also be assigned to profiles and these are then propagated to their associated Neo4j databases (“tenants”).

What about license keys?

There is no change to the way in which license keys function: one product license or dedicated named application licenses are required as normal, whatever the number of domains.

Are there any impacts on the CAST Imaging UI when the feature is enabled?

Users with the Administrator role

For users with the Administrator role, there are some visible impacts within the administration part of the UI:

All imaging-viewer related administration options will now include a “domain” selector drop down: this is to allow these settings to be applied on a domain basis:

This is valid for:

App to App Dependencies - results are generated per domain therefore no inter-application links will be generated between applications in different domains
AI Settings - AI provider settings are specific to the domain
Search configuration - advanced search configuration settings are specific to the domain

Users without the Administrator role

For users without the Administrator role - i.e. those consulting results and piloting analyses there are very few visible impacts to the CAST Imaging UI: they will mostly not be aware that domain/tenant mapping has been enabled, except in the following situations:

App to App Dependencies - a domain selector will be displayed when attempting to access the App to App Dependencies feature and the user has been assigned permission to access two or more domains:

Custom aggregation - custom aggregations created for a specific domain will not be available for applications in other domains

Onboarding/importing applications

When onboarding new applications or importing existing application results:

an existing domain can be selected (the application results will be stored in the corresponding and existing Neo4j database (“tenant”))
a new domain can be created (a new corresponding Neo4j database (“tenant”) will be created and used to store the application results)
no domain can be selected (the application results will be stored in the default Neo4j database (“tenant”))