Reference 360 > Reference 360 REST API > hierarchies v2
  

hierarchies v2

Use this resource to retrieve hierarchies, hierarchy details, and hierarchy model relationships based on internal ID or alias.

Get hierarchy details (v2)

Retrieves the details of a hierarchy based on an internal ID or alias.

GET request

To retrieve the details of a hierarchy based on an internal ID or alias, submit a GET request with the following URI:
/rdm-service/external/v2/hierarchies/{key}

GET request query parameters

The following table describes the parameter in the request:
Parameter
Type
Description
key
String
Internal ID or alias of the hierarchy.

GET response

The response contains the details of the hierarchy.
The following table describes the attributes in the response body:
Field
Type
Description
id
String
ID of the hierarchy. For more information, see Asset IDs.
name
String
Name of the hierarchy.
internalId
String
Unique identifier of the code list.
alias
String
Alternative identifier of the code list.
description
String
Optional. Description of the hierarchy.
version
String
Optional. Version of the hierarchy.
application
String
Optional. Application that uses the hierarchy.
domain
String
Optional. Domain of the hierarchy.
confidentiality
String
Optional. Confidentiality of the hierarchy.
priority
String
Optional. Priority of the hierarchy.
status
String
Optional. Status of the hierarchy.
effectiveDate
String
Optional. Date the hierarchy became effective.
approvedOn
String
Optional. Date the hierarchy was approved.

GET example

To retrieve the details of a hierarchy based on the internal ID or alias, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v2/hierarchies/hierarchy_internal_id HTTP/1.1
Accept: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The following sample response shows the details of the hierarchy:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 334

{
"id": "640717485b243e32c4b048f9",
"name": "Cost centers",
"internalId": "hierarchy_internal_id",
"alias": "hierarchy_alias",
"description": "Cost center hierarchy",
"version": "v1",
"application": "App1",
"domain": "Internal standards",
"confidentiality": "private",
"priority": "Prio1",
"status": "Draft",
"effectiveDate": "2017-04-01",
"approvedOn": "2020-03-01"
}

Get hierarchy model relationships (v2)

Retrieves the relationships in a hierarchy model based on an internal ID or alias.

GET request

To retrieve the relationships in a hierarchy model based on an internal ID or alias, submit a GET request with the following URI:
/rdm-service/external/v2/hierarchies/{key}/relations

GET request query parameters

The following table describes the parameter in the request:
Parameter
Type
Description
key
String
Internal ID or alias of the hierarchy.

GET response

The response contains the relationships and the code lists in each relationship. The child.codeListDetails attribute contains the top-level node relationship.
The following table describes the attributes in the response body:
Field
Type
Definition
relations
Array
Lists the code list in the relationship.
child
Object
Contains information about the child in the hierarchy model.
codeListDetails
Object
Includes details for the child code list.
id
String
ID of the child code list.
internalId
String
Unique identifier of the child code list.
alias
String
Alternative identifier of the child code list.
name
String
Name of the child code list.
rdsDetails
Object
Includes details for the child reference data set.
id
String
ID of the child reference data set. For more information, see Asset IDs.
internalID
String
Unique identifier of the child reference data set.
alias
String
Alternative identifier of the child reference data set.
name
String
Name of the child reference data set.
parent
Object
Contains information about the parent in the hierarchy model.
codeListDetails
Object
Includes details for the parent code list.
id
String
ID of the parent code list.
internalId
String
Unique identifier of the parent code list.
alias
String
Alternative identifier of the parent code list.
name
String
Name of the parent code list.
rdsDetails
Object
Includes details for the parent reference data set.
id
String
ID of the parent reference data set. For more information, see Asset IDs.
internalID
String
Unique identifier of the parent reference data set.
alias
String
Alternative identifier of the parent reference data set.
name
String
Name of the parent reference data set.

GET example

To retrieve the relationships in a hierarchy model based on the internal ID or alias, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v2/hierarchies/parent_codelist/relations HTTP/1.1
Accept: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The following sample response shows hierarchies:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 452
{
"relations": [
{
"child": {
"codeListDetails": {
"id": "b9270cec5293af42eb60fa00",
"internalId": "parent_codelist",
"alias": "parentcodelist",
"name": "Parent Codelist"
},
"rdsDetails": {
"id": "fa9c90dfdd269c354581807f",
"internalId": "parent_rds",
"alias": "parentrds",
"name": "Reference Data Set"
}
}
},
{
"parent": {
"codeListDetails": {
"id": "b9270cec5293af42eb60fa00",
"internalId": "parent_codelist",
"alias": "parentcodelist",
"name": "Parent Codelist"
},
"rdsDetails": {
"id": "fa9c90dfdd269c354581807f",
"internalId": "parent_rds",
"alias": "parentrds",
"name": "Reference Data Set"
}
},
"child": {
"codeListDetails": {
"id": "d1cf0227c95f4668ffcfaeda",
"internalId": "first_level_codelist",
"alias": "firstlevelcodelist",
"name": "First Level Codelist"
},
"rdsDetails": {
"id": "fa9c90dfdd269c354581807f",
"internalId": "parent_rds",
"alias": "parentrds",
"name": "Reference Data Set"
}
}
}
]
}
The child.codeListDetails attribute contains the top-level node relationship. For example, the first relationship in the example is the top-level node relationship.

Get history of a hierarchy by time range (v2)

Retrieves all the change events of a hierarchy for a specific time range based on an internal ID or alias.

GET request

To retrieve all the change events of a hierarchy for a specific time range based on an internal ID or alias, submit a GET request with the following URI:
/rdm-service/external/v2/hierarchies/{assetKey}/summary/audit

GET request query parameters

The following table describes the parameter in the request body:
Parameter
Description
assetKey
Internal ID or alias of the hierarchy.
from
Start date and time of the time range, which is inclusive. Time range must be in the following ISO-8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'. For example, you might use 2019-12-12T14:04:04Z.
to
End date and time of the time range, which is exclusive. Time range must be in the following ISO-8601 format: yyyy-MM-dd’T’HH:mm:ss’Z'. For example, you might use 2019-12-15T14:04:04Z.
page
Optional. Page number to display. Default is 0.
pageSize
Optional. Number of records to display per page. Default value is 100. Maximum value is 10000.
modificationType
Optional. Type of modification. Value can be CREATE, UPDATE, or DELETE.

GET response

The response contains the change events of a hierarchy for a specific time range.
The following table describes the attributes in the response body:
Attribute
Type
Description
pageSize
Number
Number of records displayed per page.
page
Number
Page from which the response was retrieved.
numberOfElements
Number
Number of records returned in the current page.
lastPage
Boolean
Indicates whether the current page is the last page in the total result.
firstPage
Boolean
Indicates whether the current page is the first page in the total result.
content
Array
Includes the list of modification events.
asset
Object
Includes details about the asset.
id
String
ID of the hierarchy. For more information, see Asset IDs.
name
String
Name of the hierarchy.
internalId
String
Unique identifier of the hierarchy.
alias
String
Alternative identifier of the hierarchy.
assetType
String
Type of the asset. The value is hierarchy.
modificationType
String
Type of change made to the hierarchy. Value can be CREATE, UPDATE, or DELETE.
fieldChanges
Object
Includes details of the previous and new values of the fields with changes.
confidentiality
String
Optional. Confidentiality of the hierarchy.
description
String
Optional. Description of the hierarchy.
domain
String
Optional. Domain of the hierarchy.
priority
String
Optional. Priority of the hierarchy.
status
String
Optional. Status of the hierarchy.
version
String
Optional. Version of the hierarchy.
eventTime
String
Date and time when the hierarchy was last updated.
userName
String
User name of the user who initiated the modification.

GET example

To retrieve all the change events of a hierarchy for a specific time range based on the internal ID or alias, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v2/hierarchies/country_iso/summary/audit?from=2023-01-01T00:00:00Z&to=2024-01-01T00:00:00Z HTTP/1.1
Accept: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The following sample response shows the change events of the hierarchy from 2023-01-01T00:00:00Z to 2024-01-01T00:00:00Z:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2552

{
"pageSize": 100,
"page": 0,
"numberOfElements": 6,
"lastPage": true,
"firstPage": true,
"content": [
{
"asset": {
"id": "640717485b243e32c4b048f9",
"name": "Country ISO 3166-1",
"internalId": "country_iso",
"alias": "als_country_iso",
"assetType": "HIERARCHY"
},
"modificationType": "UPDATE",
"eventTime": "2023-03-07T10:53:29Z",
"userName": "mdm-rdm-service"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"name": "Country ISO 3166-1",
"internalId": "country_iso",
"alias": "als_country_iso",
"assetType": "HIERARCHY"
},
"modificationType": "UPDATE",
"fieldChanges": {
"application": {
"newValue": {
"key": "EnterpriseKey",
"label": "Enterprise"
}
},
"confidentiality": {
"newValue": {
"key": "PublicKey",
"label": "Public"
}
},
"description": {
"newValue": "Hierarchy for Country Codes"
},
"domain": {
"newValue": {
"key": "GeographyKey",
"label": "Geography"
}
},
"priority": {
"newValue": {
"key": "Priority4",
"label": "Low"
}
},
"status": {
"newValue": {
"key": "ActiveKey",
"label": "Active"
}
},
"version": {
"newValue": "1"
}
},
"eventTime": "2023-03-07T10:53:28Z",
"userName": "integration-test-admin"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"name": "Country ISO 3166-1",
"internalId": "country_iso",
"alias": "als_country_iso",
"assetType": "HIERARCHY"
},
"modificationType": "UPDATE",
"eventTime": "2023-03-07T10:52:15Z",
"userName": "mdm-rdm-service"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"name": "Country ISO 3166-1",
"internalId": "country_iso",
"alias": "als_country_iso",
"assetType": "HIERARCHY"
},
"modificationType": "UPDATE",
"eventTime": "2023-03-07T10:52:14Z",
"userName": "integration-test-admin"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"name": "Country ISO 3166-1",
"assetType": "HIERARCHY"
},
"modificationType": "UPDATE",
"eventTime": "2023-03-07T10:51:53Z",
"userName": "mdm-rdm-service"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"name": "Country ISO 3166-1",
"assetType": "HIERARCHY"
},
"modificationType": "CREATE",
"fieldChanges": {
"name": {
"newValue": "Country ISO 3166-1"
}
},
"eventTime": "2023-03-07T10:51:52Z",
"userName": "integration-test-admin"
}
]
}

Get history of hierarchy relationships by time range (v2)

Retrieves all the change events of hierarchy relationships for a specific time range based on an internal ID or alias.

GET request

To retrieve all the change events of hierarchy relationships for a specific time range based on an internal ID or alias, submit a GET request with the following URI:
/rdm-service/external/v2/hierarchies/{assetKey}/mappings/audit

GET request query parameters

You can append query parameters to the URI to specify the time range, page number, page size, and modification type.
The following table describes the query parameters:
Parameter
Description
assetKey
Internal ID or alias of the hierarchy.
from
Start date and time of the time range, which is inclusive. Time range must be in the following ISO-8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'. For example, you might use 2019-12-12T14:04:04Z.
to
End date and time of the time range, which is exclusive. Time range must be in the following ISO-8601 format: yyyy-MM-dd’T’HH:mm:ss’Z'. For example, you might use 2019-12-15T14:04:04Z.
page
Optional. Page number to display. Default is 0.
pageSize
Optional. Number of records to display per page. Default value is 100. Maximum value is 10000.
modificationType
Optional. Type of modification. Value can be CREATE, UPDATE, or DELETE.

GET response

The response contains the change events of hierarchy relationships for a specific time range.
The following table describes the attributes in the response body:
Attribute
Type
Description
pageSize
Number
Number of records displayed per page.
page
Number
Page from which the response was retrieved.
numberOfElements
Number
Number of records returned in the current page.
lastPage
Boolean
Indicates whether the current page is the last page in the total result.
content
Array
Includes the list of modification events.
asset
Object
Includes details about the hierarchy.
id
String
ID of the hierarchy. For more information, see Asset IDs.
internalId
String
Unique identifier of the hierarchy.
alias
String
Alternative identifier of the hierarchy.
assetType
String
Type of the asset. The value is hierarchy.
modificationType
String
Type of change made to the hierarchy. Value can be CREATE, UPDATE, or DELETE.
from
Object
Includes details of the previous and new values of the child node in the relationship.
to
Object
Displays the previous and new values of the parent node in the relationship.
eventTime
String
Date and time when the hierarchy was last updated.
userName
String
User name of the user who initiated the modification.

GET example

To retrieve all the change events of a hierarchy for a specific time range based on the internal ID or alias, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v2/hierarchies/hr_hierarchy/mappings/audit?from=2023-01-01T00:00:00Z&to=2024-01-01T00:00:00Z HTTP/1.1
Accept: application/json
IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
The following sample response shows the change events of the hierarchy from 2023-01-01T00:00:00Z to 2024-01-01T00:00:00Z:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1929

{
"pageSize": 100,
"page": 0,
"numberOfElements": 6,
"lastPage": true,
"firstPage": true,
"content": [
{
"asset": {
"id": "640717485b243e32c4b048f9",
"internalId": "hr_hierarchy",
"alias": "als_hr_hierarchy",
"assetType": "HIERARCHY"
},
"modificationType": "CREATE",
"from": {
"newValue": "Antarctica"
},
"to": {
"newValue": "Antarctica"
},
"eventTime": "2023-03-07T10:53:00Z",
"userName": "integration-test-admin"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"internalId": "hr_hierarchy",
"alias": "als_hr_hierarchy",
"assetType": "HIERARCHY"
},
"modificationType": "CREATE",
"from": {
"newValue": "Albania"
},
"to": {
"newValue": "Albania"
},
"eventTime": "2023-03-07T10:52:52Z",
"userName": "integration-test-admin"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"internalId": "hr_hierarchy",
"alias": "als_hr_hierarchy",
"assetType": "HIERARCHY"
},
"modificationType": "CREATE",
"from": {
"newValue": "Afghanistan"
},
"to": {
"newValue": "Afghanistan"
},
"eventTime": "2023-03-07T10:52:44Z",
"userName": "integration-test-admin"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"internalId": "hr_hierarchy",
"alias": "als_hr_hierarchy",
"assetType": "HIERARCHY"
},
"modificationType": "CREATE",
"from": {
"newValue": "Antarctica"
},
"eventTime": "2023-03-07T10:52:35Z",
"userName": "integration-test-admin"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"internalId": "hr_hierarchy",
"alias": "als_hr_hierarchy",
"assetType": "HIERARCHY"
},
"modificationType": "CREATE",
"from": {
"newValue": "Albania"
},
"eventTime": "2023-03-07T10:52:34Z",
"userName": "integration-test-admin"
},
{
"asset": {
"id": "640717485b243e32c4b048f9",
"internalId": "hr_hierarchy",
"alias": "als_hr_hierarchy",
"assetType": "HIERARCHY"
},
"modificationType": "CREATE",
"from": {
"newValue": "Afghanistan"
},
"eventTime": "2023-03-07T10:52:34Z",
"userName": "integration-test-admin"
}
]
}