Reference 360 > Reference 360 REST API > hierarchies
  

hierarchies

Use this resource to retrieve hierarchies, hierarchy details, and hierarchy model relationships.

Get hierarchies

Retrieves a list of all hierarchies.

GET request

To retrieve a list of all hierarchies, submit a GET request with the following URI:
/rdm-service/external/v1/hierarchies

GET response

The response contains information about each hierarchy.
The following table describes the attributes in the response:
Field
Type
Definition
id
String
ID of the asset. Assets include reference data sets, code lists, crosswalks, and hierarchies. For more information, see Asset IDs.
name
String
Name of the asset.
description
String
Optional. Description of asset.
version
String
Optional. Version of the code list.
domain
String
Optional. Domain of the asset.
confidentiality
String
Optional. Confidentiality of the asset.
priority
String
Optional. Priority of the asset.
application
String
Optional. Application that uses the code list.
priority
String
Optional. Priority of the asset.
status
String
Optional. Status of the asset.
effectiveDate
String
Optional. Date the asset became effective.
approvedById
String
Optional. ID of the approver of the asset.
approvedByName
String
Optional. Username of the user who approved the asset.
approvedOn
String
Optional. Date the asset was approved.

GET example

To retrieve the list of all hierarchies, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/hierarchies 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

[
{
"id":"6e7dd28fc13b417c5c19d1fb",
"name":"Cost centers",
"description":"Cost center hierarchy",
"version":"v1",
"domain":"International standards",
"confidentiality":"private",
"priority":"Prio1",
"status":"Draft",
"effectiveDate":"2017-04-01",
"approvedOn":"2017-03-01"
},
{
"id":"e3e57e39ea8623f258013c43",
"name":"Profit centers",
"description":"Profit center hierarchy",
"version":"v1"
}
]

Get hierarchy details

Retrieves the details of a hierarchy, such as the properties and status.

GET request

To retrieve the details of a hierarchy, submit a GET request with the following URI:
/rdm-service/external/v1/hierarchies/<hierarchy ID>

GET response

The response contains the details of the hierarchy.
The following table describes the attributes in the response:
Field
Type
Definition
id
String
ID of the asset. Assets include reference data sets, code lists, crosswalks, and hierarchies. For more information, see Asset IDs.
name
String
Name of the asset.
description
String
Optional. Description of asset.
version
String
Optional. Version of the code list.
domain
String
Optional. Domain of the asset.
confidentiality
String
Optional. Confidentiality of the asset.
priority
String
Optional. Priority of the asset.
application
String
Optional. Application that uses the code list.
priority
String
Optional. Priority of the asset.
status
String
Optional. Status of the asset.
effectiveDate
String
Optional. Date the asset became effective.
approvedById
String
Optional. ID of the approver of the asset.
approvedByName
String
Optional. Username of the user who approved the asset.
approvedOn
String
Optional. Date the asset was approved.

GET example

To retrieve the hierarchy details, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/hierarchies/6e7dd28fc13b417c5c19d1fb 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: 334

{
"id":"6e7dd28fc13b417c5c19d1fb",
"name":"Cost centers",
"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

Retrieves the relationships in a hierarchy model.

GET request

To retrieve the relationships in a hierarchy model, submit a GET request with the following URI:
/rdm-service/external/v1/hierarchies/<hierarchy ID>/relations

GET response

The response contains the relationships and the code lists in each relationship. The child.codeListId attribute contains the top-level node relationship.
The following table describes the attributes in the response:
Field
Type
Definition
relations
-
Lists the code list in the relationship.
child
-
Contains information about the child code list.
parent
-
Contains information about the parent code list.
codeListId
String
ID of the code list.
codeListName
String
Name of the code list.
termId
String
ID of the reference data set to which the code list is associated.
termName
String
Name of the reference data set.

GET example

To retrieve the relationships in a hierarchy model, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/hierarchies/6e7dd28fc13b417c5c19d1fb/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":{
"codeListId":"8bc955e614df2040968e9d85",
"codeListName":"Parent Codelist",
"termId":"28a1320fe7f63cd25b58bef4",
"termName":"Reference Data Set"
}
},
{
"parent":{
"codeListId":"8bc955e614df2040968e9d85",
"codeListName":"Parent Codelist",
"termId":"28a1320fe7f63cd25b58bef4",
"termName":"Reference Data Set"
},
"child":{
"codeListId":"81a714a66863f954a9b60045",
"codeListName":"First Level Codelist",
"termId":"28a1320fe7f63cd25b58bef4",
"termName":"Reference Data Set"
}
}
]
}
The child.codeListId 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

Retrieves all the change events of a hierarchy for a specific time range.

GET request

To retrieve all the change events of a hierarchy for a specific time range, submit a GET request with the following URI:
/rdm-service/external/v1/hierarchies/<hierarchy ID>/summary/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
from
Start date and time of a time range. The start date and time is inclusive. Set the time range in the ISO-8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'. For example, you can set 2023-01-01T00:00:00Z.
to
End date and time of a time range. The end date and time is exclusive. Set the time range in the ISO-8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'. For example, you can set 2024-01-01T00:00:00Z.
page
Optional. Page number to display. Default is 0.
pageSize
Optional. The number of records to display in each page. Default is 100. Maximum 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:
Attribute
Type
Description
pageSize
Number
The number of records displayed on each page.
page
Number
Page number displayed.
numberOfElements
Number
The number of events.
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 hierarchy.
modificationType
String
The type of change made to the hierarchy.
fieldChanges
Object
Displays the previous and new values of the fields with changes.
attributeChanges
Object
Displays the previous and new values of the attributes with changes.
eventTime
String
The date and time the hierarchy was last updated.
userName
String
The 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, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/hierarchies/a5bfc1f71d31ae1149dae8ef/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",
"assetType":"HIERARCHY"
},
"modificationType":"UPDATE",
"eventTime":"2023-03-07T10:53:29Z",
"userName":"mdm-rdm-service"
},
{
"asset":{
"id":"640717485b243e32c4b048f9",
"name":"Country ISO 3166-1",
"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",
"assetType":"HIERARCHY"
},
"modificationType":"UPDATE",
"eventTime":"2023-03-07T10:52:15Z",
"userName":"mdm-rdm-service"
},
{
"asset":{
"id":"640717485b243e32c4b048f9",
"name":"Country ISO 3166-1",
"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

Retrieves all the change events of hierarchy relationships for a specific time range.

GET request

To retrieve all the change events of hierarchy relationships for a specific time range, submit a GET request with the following URI:
/rdm-service/external/v1/hierarchies/<hierarchy ID>/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
from
Start date and time of a time range. The start date and time is inclusive. Set the time range in the ISO-8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'. For example, you can set 2023-01-01T00:00:00Z.
to
End date and time of a time range. The end date and time is exclusive. Set the time range in the ISO-8601 format: yyyy-MM-dd'T'HH:mm:ss'Z'. For example, you can set 2024-01-01T00:00:00Z.
page
Optional. Page number to display. Default is 0.
pageSize
Optional. The number of records to display on each page. Default is 100. Maximum is 10000.
modificationType
Optional. Type of modification. Value can be CREATE 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:
Attribute
Type
Description
pageSize
Number
The number of records displayed on each page.
page
Number
Page number displayed.
numberOfElements
Number
The number of events.
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 hierarchy.
modificationType
String
The type of change made to the hierarchy.
from
Object
Displays 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
The date and time the hierarchy was last updated.
userName
String
The 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, you might use the following request:
GET https://use4-mdm.dm-us.informaticacloud.com/rdm-service/external/v1/hierarchies/a34cf6171f8db153e41977d0/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",
"assetType":"HIERARCHY"
},
"modificationType":"CREATE",
"from":{
"newValue":"Antarctica"
},
"to":{
"newValue":"Antarctica"
},
"eventTime":"2023-03-07T10:53:00Z",
"userName":"integration-test-admin"
},
{
"asset":{
"id":"640717485b243e32c4b048f9",
"assetType":"HIERARCHY"
},
"modificationType":"CREATE",
"from":{
"newValue":"Albania"
},
"to":{
"newValue":"Albania"
},
"eventTime":"2023-03-07T10:52:52Z",
"userName":"integration-test-admin"
},
{
"asset":{
"id":"640717485b243e32c4b048f9",
"assetType":"HIERARCHY"
},
"modificationType":"CREATE",
"from":{
"newValue":"Afghanistan"
},
"to":{
"newValue":"Afghanistan"
},
"eventTime":"2023-03-07T10:52:44Z",
"userName":"integration-test-admin"
},
{
"asset":{
"id":"640717485b243e32c4b048f9",
"assetType":"HIERARCHY"
},
"modificationType":"CREATE",
"from":{
"newValue":"Antarctica"
},
"eventTime":"2023-03-07T10:52:35Z",
"userName":"integration-test-admin"
},
{
"asset":{
"id":"640717485b243e32c4b048f9",
"assetType":"HIERARCHY"
},
"modificationType":"CREATE",
"from":{
"newValue":"Albania"
},
"eventTime":"2023-03-07T10:52:34Z",
"userName":"integration-test-admin"
},
{
"asset":{
"id":"640717485b243e32c4b048f9",
"assetType":"HIERARCHY"
},
"modificationType":"CREATE",
"from":{
"newValue":"Afghanistan"
},
"eventTime":"2023-03-07T10:52:34Z",
"userName":"integration-test-admin"
}
]
}