Data scoping is a fairly common architectural concept when it comes to developing custom software. Basically it refers to the level of granularity that a specific type of data in your application needs to support. You can think of granularity as a way to group similar types of data to provide a logical boundary around it.
In standard applications the concept of data scoping is usually quite simple. You generally store most data at an Application or "global" scope as there is no deeper level of granularity available. You may also scope some of your data at the User level for personalization and security purposes. And depending on the needs of your application, you may also have a few other custom levels of granularity for specific scenarios.
However in a multi-tenant and composable application architecture, there are many levels of granularity which can be utilized and it is very important to understand their characteristics, usage scenarios, and purpose. Oqtane has 7 distinct data scopes and each offer a specific level of granularity. Each level is outlined below...
1. Installation Scope - this represents data which is "global" and is available to the entire application. Usually this type of information is stored in appsettings.json (ie. connection strings) however Oqtane also the concept of a "Master" database which can be used to store information at a global level. Using the Settings API with an EntityType of Host is an example of using installation scope with the master database.
2. Tenant Scope - Oqtane is multi-tenant which means it supports multiple databases within the same installation. Data which is stored at tenant scope is available to all Sites which are part of the same tenant. Using the Settings API with an EntityType of Tenant and EntityId of TenantId is an example of using tenant scope with a specific tenant database.
3. Site Scope - Oqtane supports multiple "sites" within an installation. Sites reside within a specific tenant. However a tenant can contain multiple sites. As a result, a site is the most common level of granularity for data in Oqtane - as it provides the abiility to logically separate the data for different sites (which includes information such as pages, modules, roles, etc...). Using the Settings API with an EntityType of Site and EntityId of SiteId is an example of using site scope with a specific tenant database.
4. Page Scope - each site can have an unlimited number of virtual pages. Pages are essentially a way to organize the content of your site into distinct areas which can be directly accessed with a Url route. Data can be scoped to a specific page using a PageId (available in UI components via PageState.Page.PageId). Page scope is generally used for items such as Themes which may need to store customized display options for a specific page within a site.
5. Module Scope - each site can have an unlimited number of module instances. Module instances are generally organized and exposed through pages. However the same module instance can also exist multiple times on the same page or on multiple pages. Data can be scoped to a specific module using a ModuleId (available in UI components via ModuleState.ModuleId). Module scope is a very common scoping mechanism as it allows a module to function in every possible Oqtane configuration. For this reason, module scoping is included in the implementation of the default module template.
6. Page/Module Scope - as mentioned above, a module instance can exist multiple times on the same page or on multiple pages in a site. For this unique scenario, it may be necessary to store data which is specific to each module instance and page combination. An example might be a blog module which is configured to display all posts on one page and a calendar view on another page... in this scenario you could specify configuration options at a Page/Module scope.
7. User Scope - most applications contain users, and users generally have a security context related to the actions they are able to perform. In Oqtane, users are scoped at a Tenant level which enables a user account to be shared across multiple sites in a tenant. In order to support this capability, a user must be assigned a Registered User role in each site to which they are allowed access. This is a desirable feature in many enterprise environments where they may be multiple unique department sites which a user needs to be able to access using the same account.