This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Hierarchical Business Units

Usage

Hierarchical business units can be used to restrict read- and write-access for specified entity models in a hierarchical business unit structure. How the read/write access is restricted is defined by the chosen strategy. There are two different strategies available. hierarchical and self. It is possible to choose different strategies for the read access and the write access for any entity model.

hierarchical - With the hierarchical strategy the read/write access is restricted to entities in the current business unit and all child business units.

self - With the self strategy the read/write access is restricted to the current business unit.

Warning

These strategies (hierarchical, self) only can be applied to entities which are not business unit dependent. Entity models which are defined with business-unit=”single” can’t be used for these strategies.

Example

In the following picture a simple business unit structure with three levels is shown.

Example 1: Users should only have write access on users in the same business unit and on users in child business units.

This means a user in the business unit Switzerland should have write access on all users while a user in the business unit Zurich should have write access on users in the business units Zurich, Zurich 1 and Zurich 2.

Solution: use the hierarchical strategy for the write access for the entity model User.

Example 2: User should only have read access on users in the same business unit and on users in child business units but write access only on users in the same business unit.

This means a user in the business unit Switzerland should have read access on all users but only has write access on users in the business unit Switzerland. A user in the business unit Zurich should have read access on users in the business units Zurich, Zurich 1 and Zurich 2 but only has write access on users in Zurich.

Solution: use the hierarchical strategy for the read access and the self strategy for the write access for the entity model User.

How to add Hierarchical Structures

To add a hierarchical business unit handling the following steps need to be done

1. Configure a hierarchical business unit structure

2. Add relations from the desired entity model to the business unit

3. Add a contribution in the @Configuration class of the module

Assume we want to apply the hierarchical business unit handling to the entity model Address.

Configure a hierarchical business unit structure

Hierarchical business unit structures can easily be configured by setting the relation relParent and relChildren correctly on the business unit entities.

Add relation relHierarchy_business_unit

It is necessary to add a relation to the business unit for each entity model which should be applied to the hierarchical business unit handling. It is important to name the relation something different than relBusiness_unit. Otherwise the counter fragment creates a counter for each business unit for that entity model which is not desired.

Address_relBusiness_unit.xml:

<?xml version="1.0" encoding="UTF-8"?>
<relation xmlns="http://nice2.tocco.ch/schema/relation.xsd">
  <source entity-model="User" name="relBusiness_unit_hierarchy"> <!-- a different name is needed because of counters -->
    <delete cascade="no"/>
    <display show="false"/>
  </source>
  <target entity-model="Business_unit" name="relBusiness_unit_hierarchy_user">
    <display show="false"/>
  </target>
  <cardinality>n:n</cardinality>
  <default type="query">unique_id == :currentBu</default>
</relation>

Hint

For most customers it probably makes sense to set the default to the current business unit.

Hint

Maybe it makes sense to set the relation mandatory.

Add contribution

Make a contribution to the configuration-point with the id nice2.businessunit.HierarchySpecification. The hierarchySpecification element has the following attributes:

Name	Required	Description
entityModel	✔	The entity model on which the strategy should be applied to
businessUnitRelation	✔	The name of the relation to the business unit
readAccess	✘	The strategy for the read access (self or hierarchical)
writeAccess	✘	The strategy for the write access (self or hierarchical)

Example 1: use hierarchical strategy for write access on the entity model Address

@Bean
public HierarchySpecificationContribution addressHierarchySpecificationContribution() {
  HierarchySpecificationContribution contribution = new HierarchySpecificationContribution();
  contribution.setEntityModel("Address");
  contribution.setWriteAccess("hierarchical");
  contribution.setBusinessUnitRelation("relBusiness_unit_hierarchy");
  return contribution;
}

Example 2: use hierarchical strategy for read access and self strategy for write access on the entity model Address

@Bean
public HierarchySpecificationContribution addressHierarchySpecificationContribution() {
   HierarchySpecificationContribution contribution = new HierarchySpecificationContribution();
   contribution.setEntityModel("Address");
   contribution.setReadAccess("hierarchical");
   contribution.setWriteAccess("self");
   contribution.setBusinessUnitRelation("relBusiness_unit_hierarchy");
   return contribution;
}

Example 3: use hierarchical strategy for write access on the entity model User and Address and only make Membership writable if either relCompany (Address) or relSingle_user (User) is writable.

@Bean
public HierarchySpecificationContribution userHierarchySpecificationContribution() {
   HierarchySpecificationContribution contribution = new HierarchySpecificationContribution();
   contribution.setEntityModel("User");
   contribution.setWriteAccess("hierarchical");
   contribution.setBusinessUnitRelation("relBusiness_unit_hierarchy");
   return contribution;
}

@Bean
public HierarchySpecificationContribution addressHierarchySpecificationContribution() {
   HierarchySpecificationContribution contribution = new HierarchySpecificationContribution();
   contribution.setEntityModel("Address");
   contribution.setWriteAccess("hierarchical");
   contribution.setBusinessUnitRelation("relBusiness_unit_hierarchy");
   return contribution;
}

@Bean
public HierarchySpecificationContribution singleMembershipHierarchySpecificationContribution() {
   HierarchySpecificationContribution contribution = new HierarchySpecificationContribution();
   contribution.setEntityModel("Membership");
   contribution.setWriteAccess("hierarchical");
   contribution.setBusinessUnitRelation("relSingle_user.relBusiness_unit_hierarchy");
   return contribution;
}

@Bean
public HierarchySpecificationContribution companyMembershipHierarchySpecificationContribution() {
   HierarchySpecificationContribution contribution = new HierarchySpecificationContribution();
   contribution.setEntityModel("Membership");
   contribution.setWriteAccess("hierarchical");
   contribution.setBusinessUnitRelation("relCompany.relBusiness_unit_hierarchy");
   return contribution;
}

Technical implementation

Hierachical business units actually do not have anything to do with the with business unit handling itself. It is more something built on top of the business unit.

The read and write permissions are handled by the GenericHierarchyPolicyProcessor. This policy processor adds rules (Rule) depending on the contributed HierarchySpecification during the login phase.

The rules are actually created by the handlers for the different strategies (self, hierarchical) which are provided by the HierarchyStrategyProvider.

Miscellaneous

• If no business unit is set, the read and write access is not restricted at all.