Defining hierarchy types in IBM Match 360

Last updated: May 30, 2025

Define hierarchy types that can be used in your master data instance to track hierarchical relationships between entities.

Hierarchies can be used to define many different types of relationships, including legal hierarchies, ownership hierarchies, reporting chain hierarchies, family trees, product hierarchies, and more.

Within IBM Match 360, you can model hierarchies within a single entity type or across multiple entity types. To get started with hierarchies, a data engineer must define at least one hierarchy type.

After a hierarchy type has been defined, data stewards can create hierarchy instances, add or remove members, and define hierarchy relationships. For more information about working with hierarchies, see Exploring hierarchies.

The graphical interfaces for defining and working with hierarchies are provided as a technology preview.

Defining a hierarchy type

To enable data stewards to work with hierarchies, you must define at least one hierarchy type in your data model.

Required permissions: To configure a master data instance, you must be a member of the DataEngineer user group for the IBM Match 360 service.

To define a new hierarchy type:

From the Master data navigation menu, click Data types to open the data types page.
Select Hierarchy types and then click New hierarchy type.
Specify the details of your new hierarchy type: a) Provide a display name and description for this hierarchy type. b) Select the allowed data types in this hierarchy type. For example, if this hierarchy is a company organizational chart, you might choose to only allow records that have the Employee record type. c) Click Create.
Optionally, add attributes and fields to the hierarchy. For more information. see Adding attributes and fields to a hierarchy type.
When you are done adding the new hierarchy type, click Publish data type in the action bar of the screen.

Important: After a hierarchy type is published, it cannot be deleted. You can only delete hierarchy types before they are published.

To delete an unpublished hierarchy type: a) Click Data types in the navigation path to go back to the Hierarchy types screen. b) Review the list of hierarchy types. In the Data model status column, check to ensure that the value is Not published. c) Click the action menu for the hierarchy and choose Delete hierarchy type.

Adding attributes and fields to a hierarchy type

After you have created a hierarchy type, you can add attributes and fields. You can add either hierarchy attributes or member attributes.

Hierarchy attributes are attributes that describe the hierarchy object.
Member attributes are attributes that get applied to each member node in the hierarchy.

Within the hierarchy attributes, there is a preset attribute called Hierarchy name. This attribute value is typically used as a label to display the hierarchy name within IBM Match 360.

To add a new attribute or field to a hierarchy type:

From the Master data navigation menu, click Data types to open the data types page.
Click the Attributes and fields tab. There are two sections on this page: Hierarchy attributes and Member attributes.
Click New attribute to add hierarchy or and member attributes. Specify the attribute details: a) Select the base attribute type. These options are based on other attributes defined in your data model. b) Define the cardinality of this attribute. Choose Single if you do not need provide multiple values for this attribute. d) Type the display name and, optionally, provide a description of the attribute. e) Click Create.

Repeat this process to add as many attributes as you need.
Define the display name for hierarchies of this type: a) Select an attribute. b) Drag or click + to add a field.
When you are done adding the new hierarchy type, click Publish data type in the action bar of the screen.

Important: After a hierarchy type is published, it cannot be deleted. You can only delete hierarchy types before they are published.

To delete an unpublished hierarchy type: a) Click Data types in the navigation path to go back to the Hierarchy types screen. b) Review the list of hierarchy types. In the Data model status column, check to ensure that the value is Not published. c) Click the action menu for the hierarchy and choose Delete hierarchy type.

Working with hierarchies by using the API

Since many hierarchy actions are provided as technology previews, you can also work with hierarchies by using the API.

Defining a hierarchy type by using the API

To create a new hierarchy type called DnB Hierarchy by using the API:

Get the existing data model.

GET /v1/config_data_model

Modify the data model to add the new hierarchy type. The examples in this procedure create a new hierarchy type called DnB Hierarchy.

Define the new hierarchy relationship types for this hierarchy type. Add the JSON objects dnb_hierarchy_node_association_relationship and dnb_hierarchy_node_relationship into the relationship_types section.

"relationship_types": {
	"dnb_hierarchy_node_association_relationship": {
		"internal": true,
		"label_from_source": "dnb_hierarchy_source_HYui4x",
		"label_from_target": "dnb_hierarchy_target_EKhbfJ",
		"directional": true,
		"description": "Link a hierarchy node with a record or an entity or other data types",
		"rules": [
			{
				"source": {
					"node_types": [
						"dnb_hierarchy_node"
					]
				},
				"target": {
					"hierarchy_types": [],
					"entity_types": [
						"person_entity",
						"organization_entity"
					],
					"record_types": [
						"person",
						"organization"
					]
				}
			}
		],
		"label": "DnB Hierarchy node association relationship",
		"classification": "hierarchy_node_association_relationship",
		"cardinality": "ONE2ONE"
	},
	"dnb_hierarchy_node_relationship": {
		"internal": true,
		"label_from_source": "dnb_hierarchy_source_0QbKqr",
		"label_from_target": "dnb_hierarchy_target_LCwveN",
		"directional": true,
		"description": "DnB Hierarchy node to node relationship",
		"rules": [
			{
				"source": {
					"hierarchy_types": [
						"dnb_hierarchy"
					],
					"node_types": [
						"dnb_hierarchy_node"
					]
				},
				"target": {
					"node_types": [
						"dnb_hierarchy_node"
					]
				}
			}
		],
		"label": "DnB Hierarchy node relationship",
		"classification": "hierarchy_node_relationship"
	}
}

Define the new hierarchy node types (member types) for this hierarchy type. Add the JSON object node-types into the data model at same level as record_types.

"node_types": {
	"dnb_hierarchy_node": {
		"attributes": {
			"role": {
				"indexed": true,
				"description": "",
				"attribute_type": "string",
				"label": "role",
				"cardinality": "LIST"
			},
			"level": {
				"indexed": false,
				"description": "",
				"attribute_type": "string",
				"label": "level",
				"cardinality": "SINGLE"
			},
			"description": {
				"indexed": false,
				"description": "",
				"attribute_type": "string",
				"label": "description",
				"cardinality": "SINGLE"
			},
			"designation": {
				"indexed": true,
				"description": "",
				"attribute_type": "string",
				"label": "designation",
				"cardinality": "LIST"
			}
		},
		"label": "DnB Hierarchy",
		"classification": "hierarchy_node"
	}
}

Define the new hierarchy type details. Add the JSON object hierarchy_types into the data model at the same level as record_types.

"hierarchy_types": {
	"dnb_hierarchy": {
		"node_type": "dnb_hierarchy_node",
		"node_relationship_type": "dnb_hierarchy_node_relationship",
		"attributes": {
			"hierarchy_name": {
				"indexed": true,
				"description": "",
				"attribute_type": "string",
				"label": "Hierarchy name",
				"cardinality": "SINGLE"
			},
			"hierarchy_value": {
				"indexed": false,
				"description": "",
				"attribute_type": "string",
				"label": "hierarchy value",
				"cardinality": "SINGLE"
			},
			"description": {
				"indexed": false,
				"description": "",
				"attribute_type": "string",
				"label": "Description",
				"cardinality": "SINGLE"
			}
		},
		"label": "DnB Hierarchy",
		"node_associations": {
			"dnb_hierarchy_node_association_relationship": []
		}
	}
}

Clear the value of the is_model_published parameter. If the field does not exist in the model, add it as follows:

"is_model_published": "",

Tip: Check your JSON to ensure that it is formatted correctly. For example, ensure that there are no missing commas between objects where you added the new hierarchy objects.

Upload the updated data model by submitting the full, modified data model configuration JSON as the payload of the API PUT /v1/config_data_model command.
```
PUT /v1/config_data_model
```

Publish the data model.

POST /v1/configuration_metadata/processes

   {
	   "process_name": "publish_model",
     "initiator": "admin"
    }

Wait for the data model to be published.

Confirm that that data model was successfully updated by getting the latest version.
```
API GET /v1/config_data_model
```
Check the response payload to ensure that your hierarchy changes are present.

Creating a hierarchy instance by using the API

After defining one or more hierarchy types, you can run API commands to create a hierarchy instance.

To create a new hierarchy instance called ABC DnB hierarchy by using the API, run the API command POST /v1/hierarchies with a payload that defines the new hierarchy attributes, including the hierarchy type that it is based on and details such as the hierarchy source, name, and description.

POST /v1/hierarchies

{
  "type": "hierarchy",
  "type_name": "dnb_hierarchy",
  "attributes": {
  	"hierarchy_source": "MDM",
	"hierarchy_name": {"value": "ABC DnB hierarchy"},
	"description": {"value": "ABC DnB hierarchy description"}
  }
}

The response to this API request should be similar to the following example:

{
	"hierarchy": {
		"attributes": {
			"description": {
				"value": "ABC DnB hierarchy description"
			},
			"hierarchy_name": {
				"value": "ABC DnB hierarchy"
			}
		},
		"id": "181655782266320896",
		"system_attributes": {
			"created_date": 1744394453974,
			"created_user": "cpadmin",
			"hierarchy_number": 181655782266320900,
			"hierarchy_source": "MDM",
			"last_updated_date": 1744394453974,
			"last_updated_user": "cpadmin"
		},
		"type": "hierarchy",
		"type_name": "dnb_hierarchy"
	},
	"metadata": {
		"href": "https://cpd-cpd-instance.apps.test.cp.fyre.ibm.com/1744083874892597/mdm/v1/hierarchies?crn=1",
		"id": "181655782266320896",
		"updated_at": "2025-04-11T18:00:53.974Z"
	}
}

Maintaining hierarchies by using the API

You can maintain the membership and relationships within each hierarchy by using the API command PATCH /v1/hierarchies/{id}. By using this command, you can:

Update hierarchy instance attributes
Add new hierarchy members
Update hierarchy members
Add relationships between hierarchy members
Add association relationships between hierarchy members
Delete members from the hierarchy
Delete relationships between hierarchy members
Delete assocation relationships between hierarchy members

To update hiearchies by using the API, you must provide the following details in the API payload:

Record numbers of the hierarchy members you want to work with
Hierarchy details:
- Hierarchy type name
- Hierarchy ID
- Hierarchy node type names
- Hierarchy relationship type names

Maintaining hierarchies example 1: Adding members and relationships

The following example API command and payload makes the following changes to an existing hierarchy:

Updates the hierarchy name
Adds three new hierarchy members
Adds three hierarchy node relationships
Adds three hierarchy node association relationships

API PATCH /v1/hierarchies/{id}

{
	"upserts": {
		"type": "hierarchy",
		"type_name": "dnb_hierarchy",
		"id": "181655782266320896",
		"attributes": {
			"hierarchy_name": {"value": "ABC legal entity hierarchy"}
		},
		"nodes":[
			{
				"type": "node",
				"type_name": "dnb_hierarchy_node",
				"reference_id": "11",
				"attributes": {
					"designation": {"value": "GLOBLE PARENT"}
				}
			},
			{
				"type": "node",
				"type_name": "dnb_hierarchy_node",
				"reference_id": "12",
				"attributes": {
					"designation": {"value": "LOCAL PARENT"}
				}
			},
			{
				"type": "node",
				"type_name": "dnb_hierarchy_node",
				"reference_id": "13",
				"attributes": {
					"designation": {"value": "LOCAL PARENT"}
				}
			}		
		],
		"relationships": [
			{
				"type": "relationship",
				"type_name": "dnb_hierarchy_node_relationship",
				"source": {
					"id": "181655782266320896",
					"type": "hierarchy",
					"type_name": "dnb_hierarchy"
				},
				"target": {
					"id": "11",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				}
			},
			{
				"type": "relationship",
				"type_name": "dnb_hierarchy_node_relationship",
				"source": {
					"id": "11",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				},
				"target": {
					"id": "12",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				}
			},
			{
				"type": "relationship",
				"type_name": "dnb_hierarchy_node_relationship",
				"source": {
					"id": "11",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				},
				"target": {
					"id": "13",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				}
			},
		{
			"type": "relationship",
			"type_name": "dnb_hierarchy_node_association_relationship",
			"source": {
				"id": "11",
				"type": "node",
				"type_name": "dnb_hierarchy_node"
			},
			"target": {
				"id": "2430371744395911724",
				"type": "record",
				"type_name": "organization"
			}
		},
		{
			"type": "relationship",
			"type_name": "dnb_hierarchy_node_association_relationship",
			"source": {
				"id": "12",
				"type": "node",
				"type_name": "dnb_hierarchy_node"
			},
			"target": {
				"id": "1575571744395917308",
				"type": "record",
				"type_name": "organization"
			}
		},
		{
			"type": "relationship",
			"type_name": "dnb_hierarchy_node_association_relationship",
			"source": {
				"id": "13",
				"type": "node",
				"type_name": "dnb_hierarchy_node"
			},
			"target": {
				"id": "4602671744395921139",
				"type": "record",
				"type_name": "organization"
			}
		}
   ]
	}
}

Maintaining hierarchies example 2: Deleting hierarchy members

The following example API command and payload deletes a member with the ID 181658077838260226 from the hierarchy.

API PATCH /v1/hierarchies/{id}

{
	"deletions": {
		"nodes": [
      {
			  "type": "node",
			  "type_name": "dnb_hierarchy_node",
			  "id": "181658077838260226"
		  }
		]
  }
}

Getting hierarchy details by using the API

You can get details of a hierarchy's members and relationships by using the API command GET /v1/hierarchies/{id} and providing the hierarchy ID.

Here is a sample response from the GET hierarchies command, which provides hierarchy attributes and relationships (source-target pairs).

{
	"hierarchy": {
		"attributes": {
			"description": {
				"value": "ABC DnB hierarchy description"
			},
			"hierarchy_name": {
				"value": "ABC legal entity hierarchy"
			},
			"hierarchy_type": "dnb_hierarchy"
		},
		"id": "181655782266320896",
		"system_attributes": {
			"created_date": 1744394453974,
			"created_user": "cpadmin",
			"hierarchy_number": 181655782266320900,
			"hierarchy_source": "MDM",
			"last_updated_date": 1744396643229,
			"last_updated_user": "cpadmin"
		},
		"nodes": [
			{
				"attributes": {
					"designation": {
						"value": "GLOBLE PARENT"
					}
				},
				"id": "181658077838260224",
				"system_attributes": {
					"context_id": 181655782266320900,
					"created_date": 1744396643202,
					"created_user": "cpadmin",
					"last_updated_date": 1744396643231,
					"last_updated_user": "cpadmin",
					"node_number": 181658077838260220
				},
				"type": "node",
				"type_name": "dnb_hierarchy_node"
			},
			{
				"attributes": {
					"designation": {
						"value": "LOCAL PARENT"
					}
				},
				"id": "181658077838260225",
				"system_attributes": {
					"context_id": 181655782266320900,
					"created_date": 1744396643202,
					"created_user": "cpadmin",
					"last_updated_date": 1744396643232,
					"last_updated_user": "cpadmin",
					"node_number": 181658077838260220
				},
				"type": "node",
				"type_name": "dnb_hierarchy_node"
			}
		],
		"relationships": [
			{
				"id": "181658077839308800",
				"source": {
					"id": "181655782266320896",
					"type": "hierarchy",
					"type_name": "dnb_hierarchy"
				},
				"target": {
					"id": "181658077838260224",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				},
				"type": "relationship",
				"type_name": "dnb_hierarchy_node_relationship"
			},
			{
				"id": "181658077839308801",
				"source": {
					"id": "181658077838260224",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				},
				"target": {
					"id": "181658077838260225",
					"type": "node",
					"type_name": "dnb_hierarchy_node"
				},
				"type": "relationship",
				"type_name": "dnb_hierarchy_node_relationship"
			}
		],
		"type": "hierarchy",
		"type_name": "dnb_hierarchy"
	},
	"metadata": {
		"href": "https://cpd-cpd-instance.apps.test.cp.fyre.ibm.com/1744083874892597/mdm/v1/hierarchies/181655782266320896?crn=1&from_level=0&to_level=10&hierarchy_type=dnb_hierarchy",
		"id": "181655782266320896",
		"updated_at": "2025-04-11T18:37:23.229Z"
	}
}