Configure tenant business settings for hierarchy

Learn more about the tenant business configuration settings used to define hierarchy types and control which entity types can use them.

Define hierarchy types in tenant business configuration so they are available for use in the tenant. To enable hierarchy for an entity type, add a hierarchyTypes section to the tenant business configuration. Each hierarchy type entry can include a URI, a label, a list of allowed entity types and structural validation rules.

Use allowedEntityTypes to restrict a hierarchy type to specific existing entity types. If allowedEntityTypes is not provided, the hierarchy type can use entities from any entity type.

The hierarchy section endpoint returns the hierarchy types defined for a tenant: GET /{{tenant}}/configuration/hierarchyTypes. This request requires an admin role and a bearer token.

Hierarchy type structure

A hierarchy type includes the following fields:


Field	Description
`uri`	URI of the hierarchy type. This value must use the pattern `configuration/hierarchyTypes/{{HierarchyTypeName}}`.
`label`	Label of the hierarchy type used in the UI. This field is optional.
`allowedEntityTypes`	List of entity type URIs that can use the hierarchy type. This field is optional. If this field is omitted, the hierarchy type can use any entity type.
entityType	[Optional] Maps entity type URIs to structural validation rules. For each entity type, you can specify whether it can be a parent or child and the number of children allowed for specified entity types. If an entity type does not have an entry and does not inherit an entry from another entity type,, no restrictions apply to its parent or child role or to the number of children it can have.

Business configuration example

The following example shows a hierarchyTypes section in tenant business configuration.

"hierarchyTypes": [
  {
    "uri": "configuration/hierarchyTypes/CommonHierarchy",
    "label": "Common Hierarchy",
    "allowedEntityTypes": [
      "configuration/entityTypes/Catalog",
      "configuration/entityTypes/Category",
      "configuration/entityTypes/Product",
      "configuration/entityTypes/SKU"
    ],
    "entityType": {
      "configuration/entityTypes/Catalog": {
        "canBeParent": true,
        "canBeChild": false,
        "cardinalityChildren": {
          "configuration/entityTypes/Catalog": "0",
          "configuration/entityTypes/Category": "1+",
          "configuration/entityTypes/Product": "0",
          "configuration/entityTypes/SKU": "0"
        }
      },
      "configuration/entityTypes/Category": {
        "canBeParent": true,
        "canBeChild": true,
        "cardinalityChildren": {
          "configuration/entityTypes/Catalog": "0",
          "configuration/entityTypes/SKU": "0"
        }
      },
      "configuration/entityTypes/Product": {
        "canBeParent": true,
        "canBeChild": true,
        "cardinalityChildren": {
          "configuration/entityTypes/Catalog": "0",
          "configuration/entityTypes/Category": "0",
          "configuration/entityTypes/Product": "0",
          "configuration/entityTypes/SKU": "1+"
        }
      },
      "configuration/entityTypes/SKU": {
        "canBeParent": false,
        "canBeChild": true
      }
    }
  }
]

Inheritance behavior

When hierarchyTypes entries with the same uri are inherited, the values are resolved as follows:

label from L3 overrides the inherited value.
allowedEntityTypes is merged from L2 and L3.

Structural validation rules

The optional entityType map defines structural rules for entities in this hierarchy type. Each entry maps an entity type URI to its canBeParent, canBeChild, and cardinalityChildren settings for that entity type.

If an entity type is included in allowedEntityTypes but does not have an entityType entry and does not inherit an entry from another entity type, no parent, child, or child-cardinality restrictions apply.

For the messages that hierarchy read APIs return when a hierarchy connection violates these rules., see Structural validation messages for materialized hierarchy.

Parent and child permissions

The following fields control whether an entity type can be a parent or child in a hierarchy connection.


Field	Type	Default	Description
`canBeParent`	Boolean	`true`	Determines whether entities of this type can be parents.
`canBeChild`	Boolean	`true`	Determines whether entities of this type can be children.

Specify these fields only when you want to restrict whether the entity type can be a parent or child.

Child cardinality

The cardinalityChildren map defines the number of children allowed or required for each child entity type. Each key is a child entity type URI. The value is one of the following tokens.


Token	Description
`0`	The parent-child type pairing is not allowed.
`0+`	Any number of children is allowed. This is the implicit default.
`1-`	At most one child is allowed.
`1`	Exactly one child is required.
`1+`	At least one child is required.

If an allowed child entity type isn't included in the parent's cardinalityChildren map, it is treated as 0+.

.The business configuration is rejected if cardinalityChildren contains a value other than these tokens.

Entity-type inheritance

An entityType entry applies to the named entity type and its subtypes unless a subtype has its own entry.

For example, a rule defined for Individual also applies to its HCP and Contact subtypes. If HCP has its own entry, an HCP entity uses that entry instead of the Individual entry.

An entity type uses its own entityType entry if it has one. Otherwise, it uses the entry of the nearest entity type it inherits from.

Configuration validation

The business configuration is rejected if any of the following conditions applies:

An entity type referenced by entityType or cardinalityChildren does not exist.
A referenced entity type is not in allowedEntityTypes and is not a subtype of an allowed entity type. This condition does not apply when allowedEntityTypes is omitted or empty.
An entry with canBeParent: false defines a nonempty cardinalityChildren map.
.A cardinalityChildren map lists an entity type that has canBeChild: false with a value other than 0.
Required cardinality relationships (1 or 1+) form a cycle. For example, For example, an entity type requires itself as a child, or two entity types require each other as children.
An entityType or cardinalityChildren map contains he number of children allowed or required for each child entity type. For the supported values, see Child cardinality.

Unify and manage your data

Configure tenant business settings for hierarchy

Hierarchy type structure

Business configuration example

Inheritance behavior

Structural validation rules

Footer