Definindo tipos de hierarquia em IBMMatch 360 como serviço

Defina os tipos de hierarquia que podem ser usados em sua instância de dados mestre para rastrear relacionamentos hierárquicos entre entidades.

As hierarquias podem ser usadas para definir muitos tipos diferentes de relacionamentos, incluindo hierarquias legais, hierarquias de propriedade, hierarquias de cadeia de relatórios, árvores genealógicas, hierarquias de produtos e muito mais.

No IBMMatch 360 como serviço, você pode modelar hierarquias dentro de um único tipo de entidade ou em vários tipos de entidade. Para começar a usar as hierarquias, o engenheiro de dados deve definir pelo menos um tipo de hierarquia.

Depois que um tipo de hierarquia é definido, os administradores de dados podem criar instâncias de hierarquia, adicionar ou remover membros e definir relações de hierarquia. Para obter mais informações sobre como trabalhar com hierarquias, consulte Explorando hierarquias.

Definição de um tipo de hierarquia

Para permitir que os administradores de dados trabalhem com hierarquias, você deve definir pelo menos um tipo de hierarquia em seu modelo de dados.

Permissões necessárias: Para configurar uma instância de dados mestres, você deve ser membro do grupo DataEngineer de usuários do serviço IBMMatch 360 como serviço.

Para definir um novo tipo de hierarquia:

No menu de navegação de dados mestre, clique em Tipos de dados para abrir a página de tipos de dados.
Selecione Tipos de hierarquia e clique em Novo tipo de hierarquia.
Especifique os detalhes de seu novo tipo de hierarquia:

a) Forneça um nome de exibição e uma descrição para esse tipo de hierarquia.

b) Selecione os tipos de dados permitidos nesse tipo de hierarquia. Por exemplo, se essa hierarquia for um organograma de uma empresa, você pode optar por permitir apenas registros que tenham o tipo de registro Employee.

c) Clique em Create (Criar ).
Opcionalmente, adicione atributos e campos à hierarquia. para obter informações adicionais. consulte Adição de atributos e campos a um tipo de hierarquia.
Quando terminar de adicionar o novo tipo de hierarquia, clique em Publicar tipo de dados na barra de ação da tela.

Importante: Depois que um tipo de hierarquia é publicado, ele não pode ser excluído. Só é possível excluir tipos de hierarquia antes de serem publicados.

Para excluir um tipo de hierarquia não publicado:

a) Clique em Data types (Tipos de dados ) no caminho de navegação para voltar à tela Hierarchy types (Tipos de hierarquia ).

b) Revise a lista de tipos de hierarquia. Na coluna Status do modelo de dados, verifique se o valor é Não publicado.

c) Clique no menu de ação da hierarquia e selecione Excluir tipo de hierarquia.

Adição de atributos e campos a um tipo de hierarquia

Depois de criar um tipo de hierarquia, você pode adicionar atributos e campos. Você pode adicionar atributos de hierarquia ou atributos de membro.

Atributos de hierarquia são atributos que descrevem o objeto de hierarquia.
Atributos de membro são atributos que são aplicados a cada nó de membro na hierarquia.

Nos atributos da hierarquia, há um atributo predefinido chamado Nome da hierarquia. Esse valor de atributo é normalmente usado como um rótulo para exibir o nome da hierarquia dentro do IBMMatch 360 como um serviço.

Para adicionar um novo atributo ou campo a um tipo de hierarquia:

No menu de navegação de dados mestre, clique em Tipos de dados para abrir a página de tipos de dados.
Clique em Hierarchy types (Tipos de hierarquia) e selecione o tipo de hierarquia que deseja atualizar.
Clique na guia Atributos e campos. Há duas seções nesta página: Atributos de hierarquia e Atributos de membro.
Clique em Novo atributo para adicionar atributos de hierarquia ou de membros. Especifique os detalhes do atributo:

a) Selecione o tipo de atributo base. Essas opções são baseadas em outros atributos definidos em seu modelo de dados.

b) Defina a cardinalidade desse atributo. Selecione Single se você não precisar fornecer vários valores para esse atributo.

d) Digite o nome de exibição e, opcionalmente, forneça uma descrição do atributo.

e) Clique em Create (Criar ).

Repita esse processo para adicionar quantos atributos forem necessários.
Define o nome de exibição para hierarquias desse tipo:

a) Selecione um atributo.

b) Arraste ou clique em + para adicionar um campo.
Quando terminar de adicionar o novo tipo de hierarquia, clique em Publicar tipo de dados na barra de ação da tela.

Importante: Depois que um tipo de hierarquia é publicado, ele não pode ser excluído. Só é possível excluir tipos de hierarquia antes de serem publicados.

Para excluir um tipo de hierarquia não publicado: a) Clique em Tipos de dados no caminho de navegação para voltar à tela Tipos de hierarquia.

b) Revise a lista de tipos de hierarquia. Na coluna Status do modelo de dados, verifique se o valor é Não publicado.

c) Clique no menu de ação da hierarquia e selecione Excluir tipo de hierarquia.

Para obter informações sobre como criar e gerenciar instâncias de hierarquia, consulte Explorar e trabalhar com hierarquias.

Trabalhar com hierarquias usando a API

Como muitas ações de hierarquia são fornecidas como visualizações de tecnologia, você também pode trabalhar com hierarquias usando a API.

Definição de um tipo de hierarquia usando a API

Para criar um novo tipo de hierarquia chamado DnB Hierarchy usando a API:

Obter o modelo de dados existente.
```
GET /v1/config_data_model  
```
Modifique o modelo de dados para adicionar o novo tipo de hierarquia. Os exemplos deste procedimento criam um novo tipo de hierarquia chamado DnB Hierarchy.

Definir os novos tipos de relação de hierarquia para esse tipo de hierarquia. Adicione os objetos JSON dnb_hierarchy_node_association_relationship e dnb_hierarchy_node_relationship na seção relationship_types .

"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"
	}
}

Definir os novos tipos de nós de hierarquia (tipos de membros) para esse tipo de hierarquia. Adicione o objeto JSON node-types ao modelo de dados no mesmo nível que 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"
	}
}

Defina os detalhes do novo tipo de hierarquia. Adicione o objeto JSON hierarchy_types ao modelo de dados no mesmo nível que 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": []
		}
	}
}

Limpar o valor do parâmetro is_model_published . Se o campo não existir no modelo, adicione-o da seguinte forma:
```
"is_model_published": "",
```
Dica: Verifique seu JSON para garantir que ele esteja formatado corretamente. Por exemplo, verifique se não há vírgulas faltando entre os objetos onde você adicionou os novos objetos de hierarquia.
Faça upload do modelo de dados atualizado enviando o JSON de configuração do modelo de dados completo e modificado como a carga útil do comando API PUT /v1/config_data_model .
```
PUT /v1/config_data_model
```

Publicar o modelo de dados.

POST /v1/configuration_metadata/processes

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

Aguarde até que o modelo de dados seja publicado.

Confirme que o modelo de dados foi atualizado com sucesso obtendo a versão mais recente.
```
API GET /v1/config_data_model
```
Verifique a carga útil da resposta para garantir que suas alterações de hierarquia estejam presentes.

Criação de uma instância de hierarquia usando a API

Depois de definir um ou mais tipos de hierarquia, você pode executar comandos de API para criar uma instância de hierarquia.

Para criar uma nova instância de hierarquia chamada hierarquia ABC DnB usando a API, execute o comando da API POST /v1/hierarchies com um payload que defina os novos atributos da hierarquia, incluindo o tipo de hierarquia no qual ela se baseia e detalhes como a fonte, o nome e a descrição da hierarquia.

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"}
  }
}

A resposta a essa solicitação de API deve ser semelhante ao exemplo a seguir:

{
	"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"
	}
}

Manutenção de hierarquias usando a API

Você pode atualizar a associação e as relações dentro de cada hierarquia usando o comando da API PATCH /v1/hierarchies/{id}. Ao usar esse comando, você pode:

Atualizar atributos de instância de hierarquia
Adicionar novos membros da hierarquia
Atualizar membros da hierarquia
Adicionar relações entre os membros da hierarquia
Adicionar relações de associação entre os membros da hierarquia
Excluir membros da hierarquia
Excluir relações entre membros da hierarquia
Excluir relações de atribuição entre membros da hierarquia

Para atualizar as hierarquias usando a API, você deve fornecer os seguintes detalhes no payload da API:

Números de registro dos membros da hierarquia com os quais deseja trabalhar
Detalhes da hierarquia:
- Nome do tipo de hierarquia
- ID da hierarquia
- Nomes de tipos de nós de hierarquia
- Nomes de tipos de relações hierárquicas

Exemplo 1 de manutenção de hierarquias: adição de membros e relacionamentos

O exemplo de comando e carga útil de API a seguir faz as seguintes alterações em uma hierarquia existente:

Atualiza o nome da hierarquia
Adiciona três novos membros da hierarquia
Adiciona três relações de nós de hierarquia
Adiciona três relações de associação de nós de hierarquia

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"
			}
		}
   ]
	}
}

Exemplo de manutenção de hierarquias 2: Eliminação de membros da hierarquia

O exemplo de comando e carga útil da API a seguir exclui um membro com o ID 181658077838260226 da hierarquia.

API PATCH /v1/hierarchies/{id}

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

Obtenção de detalhes da hierarquia usando a API

Você pode obter detalhes dos membros e relacionamentos de uma hierarquia usando o comando da API GET /v1/hierarchies/{id} e fornecendo o ID da hierarquia.

Aqui está um exemplo de resposta do comando GET hierarchies, que fornece atributos e relações de hierarquia (pares de origem e destino).

{
	"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"
	}
}