Definizione dei tipi di gerarchia in IBMMatch 360 as a Service

Definire i tipi di gerarchia che possono essere utilizzati nell'istanza dei dati master per tracciare le relazioni gerarchiche tra le entità.

Le gerarchie possono essere utilizzate per definire diversi tipi di relazioni, tra cui gerarchie legali, gerarchie di proprietà, gerarchie della catena di relazioni, alberi genealogici, gerarchie di prodotti e altro ancora.

All'interno di IBMMatch 360 as a Service, è possibile modellare gerarchie all'interno di un singolo tipo di entità o su più tipi di entità. Per iniziare a usare le gerarchie, un data engineer deve definire almeno un tipo di gerarchia.

Dopo aver definito un tipo di gerarchia, i data steward possono creare istanze della gerarchia, aggiungere o rimuovere membri e definire relazioni gerarchiche. Per ulteriori informazioni sul lavoro con le gerarchie, vedere Esplorazione delle gerarchie.

Definizione di un tipo di gerarchia

Per consentire ai data steward di lavorare con le gerarchie, è necessario definire almeno un tipo di gerarchia nel modello di dati.

Autorizzazioni richieste
Per configurare un'istanza di dati master, è necessario essere membri del gruppo DataEngineer di utenti per il IBMMatch 360 servizio as a Service.

Per definire un nuovo tipo di gerarchia:

  1. Dal menu di navigazione Dati anagrafici, fare clic su Tipi di dati icona dei tipi di dati per aprire la pagina dei tipi di dati.

  2. Selezionare Tipi di gerarchia e fare clic su Nuovo tipo di gerarchia.

  3. Specificare i dettagli del nuovo tipo di gerarchia:

    a) Fornire un nome di visualizzazione e una descrizione per questo tipo di gerarchia.

    b) Selezionare i tipi di dati consentiti in questo tipo di gerarchia. Ad esempio, se questa gerarchia è un organigramma aziendale, si potrebbe scegliere di consentire solo i record che hanno il tipo di record Dipendente.

    c) Fare clic su Crea.

  4. Aggiungere facoltativamente attributi e campi alla gerarchia. per ulteriori informazioni. vedere Aggiunta di attributi e campi a un tipo di gerarchia.

  5. Al termine dell'aggiunta del nuovo tipo di gerarchia, fare clic su Pubblica tipo di dati nella barra delle azioni della schermata.

    Importante: una volta pubblicato, un tipo di gerarchia non può essere eliminato. È possibile eliminare i tipi di gerarchia solo prima della loro pubblicazione.

    Per eliminare un tipo di gerarchia non pubblicato:

    a) Fare clic su Tipi di dati nel percorso di navigazione per tornare alla schermata Tipi di gerarchia.

    b) Rivedere l'elenco dei tipi di gerarchia. Nella colonna Stato del modello di dati, verificare che il valore sia Non pubblicato.

    c) Fare clic sul menu delle azioni per la gerarchia e scegliere Elimina tipo di gerarchia.

Aggiunta di attributi e campi a un tipo di gerarchia

Dopo aver creato un tipo di gerarchia, è possibile aggiungere attributi e campi. Si possono aggiungere attributi gerarchici o attributi membri.

  • Gli attributi della gerarchia sono attributi che descrivono l'oggetto gerarchico.
  • Gli attributi dei membri sono attributi che vengono applicati a ogni nodo membro della gerarchia.

All'interno degli attributi della gerarchia, c'è un attributo preimpostato chiamato Nome della gerarchia. Questo valore di attributo viene solitamente utilizzato come etichetta per visualizzare il nome della gerarchia all'interno di IBMMatch 360 come servizio.

Per aggiungere un nuovo attributo o campo a un tipo di gerarchia:

  1. Dal menu di navigazione Dati anagrafici, fare clic su Tipi di dati icona dei tipi di dati per aprire la pagina dei tipi di dati.

  2. Fare clic su Tipi di gerarchia e selezionare il tipo di gerarchia da aggiornare.

  3. Fare clic sulla scheda Attributi e campi. In questa pagina sono presenti due sezioni: Attributi della gerarchia e Attributi dei membri.

  4. Fare clic su Nuovo attributo per aggiungere attributi gerarchici o membri. Specificare i dettagli dell'attributo:

    a) Selezionare il tipo di attributo di base. Queste opzioni si basano su altri attributi definiti nel modello di dati.

    b) Definire la cardinalità di questo attributo. Scegliere Singolo se non è necessario fornire più valori per questo attributo.

    d) Digitare il nome visualizzato e, facoltativamente, fornire una descrizione dell'attributo.

    e) Fare clic su Crea.

    Ripetere questa procedura per aggiungere tutti gli attributi necessari.

  5. Definisce il nome di visualizzazione per le gerarchie di questo tipo:

    a) Selezionare un attributo.

    b) Trascinare o fare clic su + per aggiungere un campo.

  6. Al termine dell'aggiunta del nuovo tipo di gerarchia, fare clic su Pubblica tipo di dati nella barra delle azioni della schermata.

    Importante: una volta pubblicato, un tipo di gerarchia non può essere eliminato. È possibile eliminare i tipi di gerarchia solo prima della loro pubblicazione.

    Per eliminare un tipo di gerarchia non pubblicato: a) Fare clic su Tipi di dati nel percorso di navigazione per tornare alla schermata Tipi di gerarchia.

    b) Rivedere l'elenco dei tipi di gerarchia. Nella colonna Stato del modello di dati, verificare che il valore sia Non pubblicato.

    c) Fare clic sul menu delle azioni per la gerarchia e scegliere Elimina tipo di gerarchia.

Per informazioni sulla creazione e la gestione delle istanze di gerarchia, vedere Esplorare e lavorare con le gerarchie.

Lavorare con le gerarchie utilizzando l'API

Poiché molte azioni sulle gerarchie sono fornite come anteprime tecnologiche, è possibile lavorare con le gerarchie anche utilizzando l'API.

Definizione di un tipo di gerarchia tramite l'API

Per creare un nuovo tipo di gerarchia chiamato DnB Hierarchy utilizzando l'API:

  1. Ottenere il modello di dati esistente.

    GET /v1/config_data_model

  2. Modificare il modello di dati per aggiungere il nuovo tipo di gerarchia. Gli esempi di questa procedura creano un nuovo tipo di gerarchia chiamato DnB Hierarchy.

  3. Definire i nuovi tipi di relazione gerarchica per questo tipo di gerarchia. Aggiungere gli oggetti JSON dnb_hierarchy_node_association_relationship e dnb_hierarchy_node_relationship nella sezione 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"
	}
}

  4. Definire i nuovi tipi di nodi gerarchici (tipi di membri) per questo tipo di gerarchia. Aggiungere l'oggetto JSON node-types nel modello dei dati allo stesso livello di 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"
	}
}

  5. Definire i dettagli del nuovo tipo di gerarchia. Aggiungere l'oggetto JSON hierarchy_types nel modello dei dati allo stesso livello di 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": []
		}
	}
}

  6. Cancella il valore del parametro is_model_published . Se il campo non esiste nel modello, aggiungerlo come segue:

    "is_model_published": "",

    Suggerimento: Verificare che il JSON sia formattato correttamente. Ad esempio, assicurarsi che non ci siano virgole mancanti tra gli oggetti in cui sono stati aggiunti i nuovi oggetti della gerarchia.

  7. Caricare il modello di dati aggiornato inviando il JSON di configurazione del modello di dati completo e modificato come payload del comando API PUT /v1/config_data_model .

    PUT /v1/config_data_model

  8. Pubblicare il modello di dati.

    POST /v1/configuration_metadata/processes

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

    Attendere la pubblicazione del modello di dati.

  9. Confermare che il modello di dati è stato aggiornato correttamente ottenendo la versione più recente.

    API GET /v1/config_data_model

    Controllare il payload della risposta per verificare che le modifiche alla gerarchia siano presenti.

Creare un'istanza di gerarchia utilizzando l'API

Dopo aver definito uno o più tipi di gerarchia, è possibile eseguire i comandi API per creare un'istanza di gerarchia.

Per creare una nuova istanza di gerarchia chiamata ABC DnB utilizzando l'API, eseguire il comando API POST /v1/hierarchies con un payload che definisce gli attributi della nuova gerarchia, tra cui il tipo di gerarchia su cui si basa e dettagli come l'origine della gerarchia, il nome e la descrizione.

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

La risposta a questa richiesta API dovrebbe essere simile al seguente esempio:

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

Mantenere le gerarchie utilizzando l'API

È possibile mantenere l'appartenenza e le relazioni all'interno di ogni gerarchia utilizzando il comando API PATCH /v1/hierarchies/{id}. Con questo comando è possibile:

  • Aggiornare gli attributi dell'istanza gerarchica
  • Aggiungere nuovi membri della gerarchia
  • Aggiornare i membri della gerarchia
  • Aggiungere relazioni tra i membri della gerarchia
  • Aggiungere relazioni di associazione tra i membri della gerarchia
  • Eliminare i membri dalla gerarchia
  • Eliminare le relazioni tra i membri della gerarchia
  • Eliminare le relazioni di assegnazione tra i membri della gerarchia

Per aggiornare gli hiearchies utilizzando l'API, è necessario fornire i seguenti dettagli nel payload dell'API:

  • Numeri di registro dei membri della gerarchia con cui si vuole lavorare
  • Dettagli della gerarchia:
    • Nome del tipo di gerarchia
    • ID gerarchia
    • Nomi dei tipi di nodo della gerarchia
    • Nomi dei tipi di relazione gerarchica

Mantenimento delle gerarchie esempio 1: aggiunta di membri e relazioni

Il seguente esempio di comando e payload API apporta le seguenti modifiche a una gerarchia esistente:

  • Aggiorna il nome della gerarchia
  • Aggiunge tre nuovi membri della gerarchia
  • Aggiunge tre relazioni tra i nodi della gerarchia
  • Aggiunge tre relazioni di associazione tra nodi della gerarchia
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"
			}
		}
   ]
	}
}

Esempio di mantenimento delle gerarchie 2: Eliminazione dei membri della gerarchia

Il seguente esempio di comando API e di payload elimina un membro con l'ID 181658077838260226 dalla gerarchia.

API PATCH /v1/hierarchies/{id} 

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

Ottenere i dettagli della gerarchia utilizzando l'API

È possibile ottenere i dettagli dei membri e delle relazioni di una gerarchia utilizzando il comando API GET /v1/hierarchies/{id} e fornendo l'ID della gerarchia.

Ecco un esempio di risposta del comando GET hierarchies, che fornisce gli attributi delle gerarchie e le relazioni (coppie sorgente-target).

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

Ulteriori informazioni