.. _concepts-hierarchy:

Introduction to Hierarchies
----------------------------


Overview 
..........

Configurable hierarchy nodes in VOSS Automate allows you to partition data in a 
multi-tenant system. Together with user roles, data partitioning via hierarchies also provides 
data security. 


Hierarchies Mapped to Business models
........................................

Hierarchies may be used to model the hierarchical nature of various types of businesses via 
hierarchy nodes, hierarchy node types, and hierarchy rules. Hierarchy rules can be 
applied to various models in the system. An example of a hierarchy 
rule is that sites can only be created under a customer. 

Hierarchy nodes and node types may include:

* Provider
* Reseller
* Customers
* Shared buildings
* Sites
* Divisions
* Branches

A hierarchical structure allows you to manage the allocation of infrastructure 
(such as network device lists), users, and other entities.


The diagram illustrates an example of a system that hosts two managed service providers: 
*Varidion* and *VS-OPS*. 

* *VS-OPS* hosts two customers: *VS-Corp* and *GenCorp*
* *VS-CORP* operates from these locations: Boston, Brooklyn, Chicago and New York.


.. image:: /src/images/hierarchy-VS-Corp.png   



Data Partitioning and Hierarchies
..................................

Using hierarchies to partition data means that an administrator user is
only allowed to view and perform operations on entity instances that
are provisioned at the parent hierarchy of the hierarchy where they have access. 

Access
to resources is thus based on the user's parent hierarchy. This restriction is enforced in
API middleware for every requested operation. Partitioning is enforced across the
various system interfaces, for example loaders, API, and the Admin Portal. This means
that an administrator user for customer "VS-Corp" cannot view or act on data at customer
"GenCorp". The "VS-Corp" administrator can only view and act on entities assigned to "VS-Corp" or
its child hierarchy levels (sites).

.. note::

   When an administrator navigates to a particular hierarchy they may have read-only
   access to model instances created at a higher level of the hierarchy. For example,
   a provider administrator's view of the list of menu layouts may show
   instances created *above* the provider's hierarchy. In this case, the administrator
   requires read-only access in order to have the ability to clone a field display
   policy at a lower level of the hierarchy. This administrator will not be able to
   edit the model instance created at the higher level of the hierarchy. However, a
   provider administrator viewing the list of model instances below the provider
   level is able to edit model instances created at the provider hierarchy.

   When the model is designed, the following setting is enabled: **Visible at Lower Hierarchy**

   This setting is available for Data, Domain, and Relation
   definitions.  For Relations, the setting overrides the setting in any
   related models. See the table below.






Hierarchies and User Roles
...........................

VOSS Automate secures access to data with the concepts of data partitioning via hierarchies, and
user roles. You can create administrators with different roles for different types of hierarchy 
nodes for devolved administration. For example: 

* An administrator is responsible for the setup of the overall system.
* Provider administrators own and manage infrastructure and define services
  available to resellers.
* Resellers offer the infrastructure and services to customers or
  enterprises.
* Customers and enterprises are grouped into various groupings.
* Groupings such as divisions or branches belong to customers.
* Physical locations hold users and phones.
* End users consume services and manage their own configurable settings.

A flexible hierarchy allows you to: 

* Define as many levels as you need
* Create hierarchy node instances of different types
* Define the required business rules  



Parent-Child Relationships
............................

All entities in the system reside at a specific hierarchy and the 
data displayed is within the scope of the specified hierarchy.
This means that every entity in the system (including users, device
models and network components) has a parent hierarchy defined.
A user is for example provisioned with a specific hierarchy node in a
parent-child relationship. User names must be unique within a specific
hierarchy.


User Roles, Access Profiles, and Data Security
.................................................

Access profiles define the read and write permissions assigned to user roles. The
access profile defines how the user can interact with specific system entities. Permissions
include details of each entity type in the system, as well as the relevant privileges
related to that entity type. See :ref:`role_based_access`.

* Hierarchy - defines the specific instances of the various entities that the user can
  interact with
* User's role and access profile - determines the permitted operations that can be performed on these instances.


The table describes models with **Visible at Lower Hierarchy** set to *true*:

+----------------------------------+----------------+
| Name                             | Model Type     |
+==================================+================+
| AccessProfile                    | data/DataModel |
+----------------------------------+----------------+
| Adaptation                       | data/DataModel |
+----------------------------------+----------------+
| AdaptationLog                    | data/DataModel |
+----------------------------------+----------------+
| BulkAdminDataRefreshPerHierarchy | data/DataModel |
+----------------------------------+----------------+
| BulkAdminFullDataRefresh         | data/DataModel |
+----------------------------------+----------------+
| BulkAdminScheduleDataRefresh     | data/DataModel |
+----------------------------------+----------------+
| Bundle                           | data/DataModel |
+----------------------------------+----------------+
| Bundle                           | data/Relation  |
+----------------------------------+----------------+
| ConfigurationTemplate            | data/DataModel |
+----------------------------------+----------------+
| Countries                        | data/DataModel |
+----------------------------------+----------------+
| CredentialPolicy                 | data/DataModel |
+----------------------------------+----------------+
| FeatureConfigProfile             | data/DataModel |
+----------------------------------+----------------+
| FieldDisplayPolicy               | data/DataModel |
+----------------------------------+----------------+
| HcsCommandBuilderDAT             | data/DataModel |
+----------------------------------+----------------+
| HcsDeviceGroupDAT                | data/DataModel |
+----------------------------------+----------------+
| HcsDeviceTypeDAT                 | data/DataModel |
+----------------------------------+----------------+
| HcsDpDialPlanSchemaDAT           | data/DataModel |
+----------------------------------+----------------+
| HcsDpDialPlanSchemaGroupDAT      | data/DataModel |
+----------------------------------+----------------+
| HcsLocalizedStringDat            | data/DataModel |
+----------------------------------+----------------+
| HcsMovePhoneCustomizationsDAT    | data/DataModel |
+----------------------------------+----------------+
| HcsMoveSubCustomizationsDAT      | data/DataModel |
+----------------------------------+----------------+
| HcsPrimeCollabREL                | data/Relation  |
+----------------------------------+----------------+
| LandingPage                      | data/DataModel |
+----------------------------------+----------------+
| Macro                            | data/DataModel |
+----------------------------------+----------------+
| MenuLayout                       | data/DataModel |
+----------------------------------+----------------+
| Patch                            | data/DataModel |
+----------------------------------+----------------+
| ProvisioningWorkflow             | data/DataModel |
+----------------------------------+----------------+
| QuickAddGroups                   | data/DataModel |
+----------------------------------+----------------+
| Role                             | data/DataModel |
+----------------------------------+----------------+
| SelfServiceFeatureDisplayPolicy  | data/DataModel |
+----------------------------------+----------------+
| SelfServiceLinks                 | data/DataModel |
+----------------------------------+----------------+
| SelfServiceTranslation           | data/DataModel |
+----------------------------------+----------------+
| Theme                            | data/DataModel |
+----------------------------------+----------------+









.. rubric:: Related Topics

* 
  .. raw:: latex

     Network Device Lists in the Core Feature Guide

  .. raw:: html
  
     <a href="concepts-network-device-list.html">Network Device Lists</a> 

* 
  .. raw:: latex

     VOSS Automate Configuration and Sync in the Core Feature Guide

  .. raw:: html
  
     <a href="concepts-VOSS-Automate-configuration-and-sync-for-microsoft.html">VOSS Automate Configuration and Sync</a>