Use the hierarchy API to create hierarchies, add first-level nodes and child records, and move records within a hierarchy or across hierarchies. You can retrieve all hierarchies within a hierarchy model and all records in a hierarchy. You can also update the name and description of existing hierarchies, and delete hierarchies from a hierarchy model or records from a hierarchy.
You can also retrieve the exact location of a specific record in a hierarchy by returning all paths from the parent record to the child record. Additionally, you can retrieve a list of hierarchies that a record is part of based on its business ID.
Create Hierarchy
Use the Create Hierarchy API to create a hierarchy based on a hierarchy model and add first-level nodes to the hierarchy. You can add up to 25 first-level nodes to a hierarchy.
The API uses the POST method.
POST request
To create a hierarchy, submit a POST request with the following URI:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>?sourceSystem=<sourceSystem>
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Internal ID of the hierarchy model to which you want to add the hierarchy.
sourceSystem
String
Internal ID of the source system to assign to the hierarchy.
For example, c360.default.system
The following table describes the parameters that you can use in the request body:
Parameter
Type
Description
name
String
Name of the hierarchy.
Note:
You can enter a maximum of 255 characters.
description
String
Optional. A short description to provide context about the purpose of the hierarchy.
Note:
You can enter a maximum of 255 characters.
roots
Array
Optional. An array of records to add as first-level nodes in the hierarchy. Each record is identified by its business ID and the business entity it belongs to. If you don't specify this array, the hierarchy is created without any nodes.
Business ID of the record to add as the first-level node.
roots.businessEntity
String
Internal ID of the business entity the record belongs to.
POST response
The response shows the response code, business ID of the hierarchy that you created, and the first-level nodes that are added to the hierarchy. When you submit a request to create a hierarchy, MDM SaaS verifies your user role permissions and the approval workflow configuration. The response indicates whether the hierarchy that you create requires an approval.
The following table describes the parameters in the response:
Parameter
Type
Description
businessId
String
Business ID of the hierarchy that you created.
approvalRequired
Boolean
Identifies whether the request triggers an approval workflow. If the request requires an approval, the value is true. If the request doesn't require an approval, the value is false.
rootsSummary
Object
Includes the details of the first-level nodes in your request.
rootsSummary.succeeded
Array
An array of first-level nodes in the hierarchy.
rootsSummary.succeeded.relationshipIdentifier
Object
Identifies the relationship details between the first-level node and the hierarchy.
Use the Add Root Nodes to a Hierarchy API to add records as first-level nodes to an existing hierarchy based on a hierarchy model. You can add up to 25 first-level nodes to an existing hierarchy.
The API supports the POST method.
POST request
To add records as first-level nodes to an existing hierarchy, submit a POST request with the following URI:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/<businessId>/roots?sourceSystem=<sourceSystem>
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Internal ID of the hierarchy model that contains the hierarchy.
businessId
String
Business ID of the hierarchy in the hierarchy model.
sourceSystem
String
Internal ID of the source system to which the hierarchy belongs.
The following table describes the parameters that you can use in the request body:
Parameter
Type
Description
businessEntity
String
Internal ID of the business entity the record that you want to add as a first-level node belongs to.
businessId
String
Business ID of the record to add as the first-level node.
POST response
The response shows the response code, details of the hierarchy, and details of the first-level nodes that you added to the hierarchy. When you submit a request to add first-level nodes to a hierarchy, MDM SaaS verifies your existing user role permissions and the approval workflow configuration. The response indicates whether you require approval to add records as first-level nodes to a hierarchy.
The following table describes the parameters in the response:
Parameter
Type
Description
businessId
String
Business ID of the hierarchy in the hierarchy model.
approvalRequired
Boolean
Identifies whether the request triggers an approval workflow. If the request requires an approval, the value is true. If the request doesn't require an approval, the value is false.
rootsSummary
Object
Includes the details of the records that are added as first-level nodes.
rootsSummary.succeeded
Array
An array of first-level nodes in the hierarchy.
rootsSummary.succeeded.relationshipIdentifier
Object
Identifies the relationship between the first-level node and the hierarchy.
Use the Add Child Nodes to a Hierarchy API to add records under the first-level nodes and existing child nodes in an hierarchy. You can add up to 25 child records in a single request.
For example, if you have a first-level node named Amazon, you can use this API to add child records such as Amazon - Chennai and Amazon - Bangalore under the first-level node. After you add the records, you can use the API to add child records under these records by specifiying the parent relationship identifier for Amazon - Chennai and Amazon - Bangalore records in the request.
The API uses the POST method.
POST request
To add records under the first-level nodes and existing child nodes in an hierarchy, submit a POST request with the following URI:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/<businessId>/nodes?sourceSystem=<sourceSystem>
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Internal ID of the hierarchy model to which you want to add the hierarchy.
businessId
String
Business ID of the hierarchy in the hierarchy model.
sourceSystem
String
Internal ID of the source system to which the hierarchy belongs.
The following table describes the parameters that you can use in the request body:
Parameter
Type
Description
parentRelationshipIdentifier
Object
Identifies the parent records to add child records to.
If you want to add records to an existing first-level node in a hierarchy, use the Fetch Root Nodes of a Hierarchy API to retrieve all the first-level nodes of a hierarchy. The response of the API contains the relationship identifier details of all the first-level nodes. You can use the relationship identifier details from the content.relationshipIdentifier parameter of the first-level node to add child records to.
If you want to add records to an existing child node within the first-level node, retrieve the child records from the first-level node using the Fetch Child Nodes API. You can use relationship identifier details from the content.relationshipIdentifier parameter.
parentRelationshipIdentifier.businessId
String
Business ID of the relationship between the parent record and the child record.
If you add records to the first-level nodes, this parameter denotes the ID of the relationship between the first-level node and the hierarchy.
parentRelationshipIdentifier.relationship
String
Internal ID of the relationship between the parent record and the child record.
If you add child records to the first-level nodes, this parameter denotes the internal ID of the relationship between the first-level node and the hierarchy.
relationType
String
Internal ID of the relationship to use to relate the parent record and the input record.
If the parent record can participate in only one relationship, you can skip this parameter. If the parent record can participate in multiple relationships, specify which relationship to use to relate the child record.
You can get the internal ID of the relationship from the hierarchy model in Business 360 Console.
children
Array
An array of child records to add to the parent record.
children.businessEntity
String
Internal ID of the business entity that the child record you want to add belongs to.
children.businessId
String
Business ID of the record to add as the child record.
POST response
The response shows the response code and the details of the child records that are added to the hierarchy. When you submit a request to add child records to multiple parent records in a hierarchy, MDM SaaS verifies your existing user role permissions and the approval workflow configuration. The response indicates whether you require approval to add child record to the parent records in a hierarchy.
The following table describes the parameters in the response:
Name
Type
Description
summary
Object
Contains aggregate counts of the total, succeeded, and failed records in the request.
summary.total
Integer
Total number of child records to add to the hierarchy.
summary.succeeded
Integer
Number of child records added to the hierarchy.
summary.failed
Integer
Number of child records that failed to be added to the parent record because of errors.
approvalRequired
Boolean
Identifies whether the request triggers an approval workflow. The value is true if the request requires approval, or false if it doesn't.
details
Array
Lists the details of the succeeded and failed child records.
details.parentRelationshipIdentifier
Object
Identifies the details of the parent record.
details.parentRelationshipIdentifier.businessId
String
Business ID of the relationship between the parent record and the child record.
If you add child records to the first-level nodes, this parameter denotes the ID of the relationship between the first-level node and the hierarchy.
details.parentRelationshipIdentifier.relationship
String
Internal ID of the relationship between the parent record and the child record.
If you add child records to the first-level node, this parameter denotes the internal ID of the relationship that's created between the first-level node and the hierarchy.
details.succeeded
Array
Lists the child records that are successfully added.
details.succeeded.relationshipIdentifier
Array
Lists the relationship details between the child record that you added and parent record.
Use the Fetch Root Nodes of a Hierarchy API to retrieve the first-level nodes in a hierarchy.
The API uses the POST method.
POST request
To retrieve the first-level nodes in a hierarchy, submit a POST request with the following URI:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/<businessId>/roots/paged?appNamespace=<BusinessApplicationName>
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Name of the hierarchy model that contains the hierarchy.
businessId
String
Business ID of the hierarchy in the hierarchy model.
appNamespace
String
Optional. Identifies the application that the record belongs to, such as c360 for the Customer 360 SaaS business application, s360 for the Supplier 360 SaaS business application, and p360 for the Product 360 SaaS business application. When you provide this parameter, the response includes only the fields defined for the business entities of the application.
The following table describes the parameters that you can use in the request body:
Parameter
Type
Description
pageOffset
Integer
Number of pages to skip.
For example, to skip the first two pages of the search results, set pageOffset to 2. Minimum is 0.
pageSize
Integer
Number of search results to display on each page.
Default is 10.
Maximum is 25.
sortBy
Array
A list of fields based on which the records are sorted. To sort results in ascending order, specify +<Field Name. To sort in descending order, specify -<FieldName>.
POST response
The response shows the response code and the details of the first-level nodes in the hierarchy.
The following table describes the parameters in the response:
Parameter
Type
Description
first
Boolean
Indicates whether the current page is the first page.
last
Boolean
Indicates whether the current page is the last page.
page
Integer
Indicates the current page number.
size
Integer
Indicates the requested page size.
numberOfElements
Integer
Actual number of elements on the current page.
content
Array
Indicates the details of the first-level nodes returned.
content.relationshipIdentifier
Object
Identifies the relationship details between the first-level node and the hierarchy.
content.relationshipIdentifier.businessId
String
Business ID of the relationship between the first-level node and the hierarchy.
content.relationshipIdentifier.relationship
String
Internal ID of the type of relationship created between the first-level node and the hierarchy.
content.leaf
Boolean
Indicates whether the first-level node represents an end position within the hierarchy. If the first-level node is at the end of the hierarchy, the value is true. If there are more first-level nodes, the value is false.
content.entity
Object
Displays the fields and meta details of the first-level node.
content.entity.fields
Array
An array of display fields of the record in the business entity.
content.entity.fields.name
String
Name of the record.
The following table describes the meta parameters in the response:
Parameter
Type
Description
businessId
String
Business ID of the first-level node in the hierarchy model.
businessEntity
String
Business entity associated with the first-level node.
state
String
Indicates the state of the first-level node. For example, ACTIVE indicates whether the first-level node is active.
createdBy
String
Name of the user who created the first-level node.
creationDate
String
Date when the first-level node was created.
updatedBy
String
Name of the user who updated the first-level node.
lastUpdateDate
String
Date when the first-level node was last updated.
POST example
You can use the following request to retrieve first-level nodes in a hierarchy:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/hospital_hierarchy/MDM00000000014/roots/paged?appNamespace=c360 Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Use the Fetch Child Nodes API to retrieve the child records of a parent record in a hierarchy.
The API uses the POST method.
POST request
To retrieve the child records of a parent record in a hierarchy, submit a POST request with the following URI:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/<businessId>/nodes/paged?appNamespace=<BusinessApplicationName>
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Name of the hierarchy model that contains the hierarchy.
businessId
String
Business ID of the hierarchy in the hierarchy model.
appNamespace
String
Optional. Identifies the application that the record belongs to, such as c360 for the Customer 360 SaaS business application, s360 for the Supplier 360 SaaS business application, and p360 for the Product 360 SaaS business application. When you provide this parameter, the response includes only the fields defined for the business entities of the application.
The following table describes the parameters that you can use in the request body:
Parameter
Type
Description
parentNode
Object
Lists the details of the parent record from which you want to retrieve the child records.
parentNode.businessId
String
Business ID of the parent record.
parentNode.relationship
String
Internal ID of the relationship created between the parent record and the child record.
pageOffset
Integer
Number of pages to skip.
For example, to skip the first two pages of the search results, set pageOffset to 2. Minimum is 0.
pageSize
Integer
Number of search results to display on each page.
Default is 10.
Maximum is 25.
sortBy
Array
A list of fields based on which the records are sorted. To sort results in ascending order, specify +<Field Name. To sort in descending order, specify -<FieldName>.
POST response
The response shows the response code and the details of the child records in the hierarchy.
The following table describes the parameters in the response:
Parameter
Type
Description
first
Boolean
Indicates whether the current page is the first page.
last
Boolean
Indicates whether the current page is the last page.
page
Integer
Indicates the current page number.
size
Integer
Indicates the requested page size.
numberOfElements
Integer
Actual number of elements on the current page.
content
Array
Lists the details of the child records returned.
content.relationshipIdentifier
Object
Lists the relationship details between the parent record and the child record.
content.relationshipIdentifier.businessId
String
Business ID of the relationship between the parent record and child record.
content.relationshipIdentifier.relationship
String
Internal ID of the relationship between the parent record and child record.
content.leaf
Boolean
Indicates whether the child record represents an end position within the hierarchy. It returns true if the record has no child records and false if the record has one or more child records.
content.entity
Object
Displays the meta details of the child record.
The following table describes the meta parameters in the response:
Parameter
Type
Description
businessId
String
Business ID of the child record.
businessEntity
String
Business entity associated with the child record.
state
String
Indicates the state of the child record. For example, ACTIVE indicates whether the record is active.
createdBy
String
Name of the user who created the child record.
creationDate
String
Date when the child record was created.
updatedBy
String
Name of the user who updated the child record.
lastUpdateDate
String
Date when the child record was last updated.
POST example
You can use the following request to retrieve child records of a parent record in a hierarchy:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/hospital_hierarchy/MDM0000000001O/nodes/paged?appNamespace=c360 Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Use the Move Nodes Within or Across Hierarchies API to move records within the same hierarchy or to a different hierarchy in a hierarchy model. Additionally, you can move a record as a first-level node to a different hierarchy. You can move only one record in a single request.
The API uses the POST method.
POST request
To move records within the same hierarchy or to a different hierarchy, submit a POST request with the following URI:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/<businessId>/nodes/move?sourceSystem=<sourceSystem>
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Name of the hierarchy model that contains the hierarchy.
businessId
String
Business ID of the hierarchy.
sourceSystem
String
Internal ID of the source system that contains the hierarchy.
The following table describes the parameters that you can use in the request body:
Parameter
Type
Description
relationshipIdentifier
Object
Indicates the relationship details of the record that you want to move within or across a hierarchy.
relationshipIdentifier.businessId
String
Business ID of the relationship between the record that you want to move and the hierarchy.
relationshipIdentifier.relationship
String
Internal ID of the relationship between the record that you want to move and the hierarchy.
destination
Object
Indicates the details of the destination record where you want to move the record.
destination.relationshipIdentifier
Object
Indicates the relationship details of the destination record.
destination.relationshipIdentifier.businessId
String
Business ID of the relationship between the target record and the hierarchy.
destination.relationshipIdentifier.relationship
String
Internal ID of the relationship between the target record and the hierarchy.
destination.hierarchyBusinessId
String
Business ID of the hierarchy.
Note:
You must specify this parameter only when you want to move records to a different hierarchy.
POST response
The response shows the response code and the details of the records that are moved within the same hierarchy or to a different hierarchy.
The following table describes the parameters in the response:
Parameter
Type
Description
approvalRequired
Boolean
Identifies whether the request triggers an approval workflow. If the request requires an approval, the value is true. If the request doesn't require an approval, the value is false.
succeeded
Array
An array of records that are moved successfully.
succeeded.relationshipIdentifier
Object
Indicates the relationship details of the records that are moved.
succeeded.relationshipIdentifier.businessId
String
Business ID of the relationship between the record that's moved and the hierarchy.
succeeded.relationshipIdentifier.relationship
String
Internal ID of the relationship between the record that's moved and the hierarchy.
failed
Array
An array of records that weren't moved because of errors.
POST example to move records within the same hierarchy
You can use the following request to move records within the same hierarchy:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/hospital_hierarchy/MDM0000000000K/nodes?sourceSystem=c360.default.system Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Use the Delete Nodes from a Hierarchy API to delete one or more records from a hierarchy. When you delete records from a hierarchy, the API deletes only the relationship between the record and the hierarchy. You can pass only one record in a single request for deletion. If the record has a subtree, the subtree can contain up to 50 child records for a single delete request.
The API uses the DELETE method.
DELETE request
To delete records from a hierarchy, submit a DELETE request with the following URI:
Use the Filter Hierarchy API to retrieve a list of hierarchies in a hierarchy model.
The API uses the POST method.
POST request
To filter a hierarchy, submit a POST request with the following URI:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/filter
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Name of the hierarchy model that contains the hierarchies.
The following table describes the parameters that you can use in the request body:
Parameter
Type
Description
pageOffset
Integer
Number of pages to skip.
For example, to skip the first two pages of the search results, set pageOffset to 2. Minimum is 0.
pageSize
Integer
Number of search results to display on each page.
Default is 10.
Maximum is 25.
sortBy
Array
A list of fields based on which the records are sorted. To sort results in ascending order, specify +<Field Name. To sort in descending order, specify -<FieldName>.
filters
Object
A list of fields that's used to filter the hierarchies in the hierarchy model.
filters._<operator>
Array
Use this parameter to set the filter condition. You can use filters._or to filter hierarchies that matches one of the conditions. You can use filters._and to filter hierarchies that match all the conditions.
filters.name
String
Name of the field.
filters.meta.businessId
String
Business ID of the record.
When you use meta fields to filter hierarchies in a hierarchy model, ensure that you use the keyword meta before to the meta field name.
For example, meta.businessId.
POST response
The response shows the response code and the list of hierarchies based on the hierarchy model.
The following table describes the parameters in the response:
Parameter
Type
Description
first
Boolean
Indicates whether the current page is the first page.
last
Boolean
Indicates whether the current page is the last page.
page
Integer
Indicates the page number.
size
Integer
Indicates the requested page size.
numberOfElements
Integer
Actual number of elements on the current page.
content
Array
Indicates the details of the hierarchy and the first-level nodes that are returned.
content.name
String
Name of the hierarchy.
content.description
String
Description of the hierarchy.
content.leaf
Boolean
Indicates whether the hierarchy represents an end position within the hierarchy model.
The following table describes the meta parameters in the response:
Parameter
Type
Description
businessId
String
Business ID of the hierarchy in the hierarchy model.
businessEntity
String
Internal ID of the business entity associated with the hierarchy.
state
String
Indicates the state of the hierarchy. For example, ACTIVE indicates whether the hierarchy is active.
validation
String
Indicates the validation status of the hierarchy.
You can view one of the following validation statuses:
- PENDING. Indicates that the hierarchy isn't yet validated.
- PASSED. Indicates that the hierarchy is validated and has no errors.
- FAILED. Indicates that the hierarchy is validated and has validation errors.
consolidation
String
Indicates the match and merge status of the hierarchy.
You can view one of the following match and merge statuses:
- MATCH_DIRTY. Indicates that the hierarchy hasn't undergone the match process.
- MATCH_INDEXED. Indicates that match keys are generated for the hierarchy.
- MATCHED. Indicates that the hierarchy matched other hierarchies based on the match configuration, and is ready for merging.
- CONSOLIDATION PENDING. Indicates that the hierarchy hasn't undergone the match process.
- CONSOLIDATION INDEXED. Indicates that match keys are generated for the hierarchy.
- CONSOLIDATED. Indicates that the hierarchy is merged either manually or automatically.
- NOT READY FOR MATCH. Indicates that you've excluded the hierarchy from participating in the match process.
searchIndex
String
Indicates whether the hierarchy is indexed for search. SEARCH_INDEXED denotes that the hierarchy is searchable.
createdBy
String
Name of the user who created the hierarchy.
creationDate
String
Date when the hierarchy was created.
updatedBy
String
Name of the user who updated the hierarchy.
lastUpdateDate
String
Date when the hierarchy was last updated.
POST example
You can use the following request to filter a hierarchy:
POST <baseApiURL>/shm-service/public/api/v1/hierarchies/hospital_hierarchy/filter Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Use the Update Hierarchy API to update the name and description of a hierarchy in a hierarchy model. You can update only one hierarchy in a single request.
The API uses the PUT method.
PUT request
To update the name and description of a hierarchy, submit a PUT request with the following URI:
PUT <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/<businessId>?sourceSystem=<sourceSystem
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
Hierarchy Model
String
Name of the hierarchy model that contains the hierarchy.
businessId
String
Business ID of the hierarchy that you want to update.
sourceSystem
String
Internal ID of the source system that contains the hierarchy.
The following table describes the parameters that you can use in the request body:
Note:
You can specify the parameter that you want to update in the request body.
Parameter
Type
Description
name
String
Optional. Updated name of the hierarchy.
description
String
Optional. Updated description that explains the purpose of the hierarchy.
PUT response
The response shows the response code and approval workflow. When you submit a REST API request to update a hierarchy, MDM SaaS verifies your existing user role permissions and the approval workflow configuration. The response indicates whether you require an approval to update the hierarchy. The approvalRequired response parameter identifies whether the request triggers an approval workflow. If the request requires an approval, the response returns the value as true. If the request doesn't require an approval, the response returns the value as false.
PUT example
You can use the following request to update a hierarchy:
PUT <baseApiURL>/shm-service/public/api/v1/hierarchies/hospital_hierarchy/MDM0000000000K?sourceSystem=c360.default.system Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
{ "name": "Apollo Hospitals Region-wise Structure", "description": "The hierarchy contains the region-wise location of the Apollo hospital group." }
If no approval workflow is configured, you get the following response:
HTTP/1.1 200 OK Content-Type: application/json
{ "approvalRequired": false }
If the approval workflow is configured, you get the following response:
HTTP/1.1 200 OK Content-Type: application/json
{ "approvalRequired": true }
Delete Hierarchy
Use the Delete Hierarchy API to delete a hierarchy from the hierarchy model. When you delete a hierarchy, the API doesn't delete the records in the hierarchy. It deletes only the relationship between the hierarchy and the records in the hierarchy. You can delete only one hierarchy in a single request.
The API uses the DELETE method.
DELETE request
To delete a hierarchy, submit a DELETE request with the following URI:
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Name of the hierarchy model that contains the hierarchy.
businessId
String
Business ID of the hierarchy in the hierarchy model.
sourceSystem
String
Internal ID of the source system to which the hierarchy belongs.
DELETE response
The response shows the response code and approval workflow. When you submit a REST API request to delete a hierarchy, MDM SaaS verifies your existing user role permissions and the approval workflow configuration. The response indicates whether you require an approval to delete the hierarchy. The approvalRequired response parameter identifies whether the request triggers an approval workflow. If the request requires an approval, the response returns the value as true. If the request doesn't require an approval, the response returns the value as false.
DELETE example
You can use the following request to delete the hierarchy from the hierarchy model:
If no approval workflow is configured, you get the following response:
HTTP/1.1 200 OK Content-Type: application/json
{ "approvalRequired": false }
If the approval workflow is configured, you get the following response:
HTTP/1.1 200 OK Content-Type: application/json
{ "approvalRequired": true }
Find Hierarchies by Business ID of a Record
Use the Find Hierarchies by Business ID of a Record API to find hierarchies that a record is part of based on its business ID.
The API uses the GET method.
GET request
To find hierarchies that a record is part of based on its business ID, submit a GET request with the following URI:
GET <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/nodes/<businessEntity>/<businessId>/instances
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Name of the hierarchy model that contains the hierarchy.
businessEntity
String
Internal ID of the business entity associated with the record for which you want to find hierarchies.
businessId
String
Business ID of the record for which you want to find hierarchies.
The API doesn't contain any parameters in the request body.
GET response
The response shows the response code and hierarchies that the record is part of based on its business ID.
The following table describes the parameters in the response:
Name
Type
Description
record
Object
Details of the record for which you retrieved all hierarchies.
record.businessId
String
Business ID of the record in the hierarchy.
record.businessEntity
String
Internal ID of the business entity that's associated with the record.
instances
Array
List of hierarchies in which the record participates.
instances.name
String
Display name of the hierarchy.
instances.description
String
A short description that provides the context about the purpose of the hierarchy.
instances.leaf
Boolean
Indicates whether the hierarchy represents the end position. The value is true if the hierarchy is the last hierarchy in the branch, or false if it has more hierarchies.
instances.meta
Object
Displays the meta details of the hierarchy.
The following table describes the meta parameters in the response:
Parameter
Type
Description
businessId
String
Business ID of the hierarchy.
createdBy
String
Name of the user who created the hierarchy.
creationDate
String
Date when the hierarchy was created.
updatedBy
String
Name of the user who updated the hierarchy.
lastUpdateDate
String
Date when the hierarchy was last updated.
GET example
You can use the following request to find all hierarchies that a record is part of based on its business ID:
GET <baseApiURL>/shm-service/public/api/v1/hierarchies/hospital_hierarchy/nodes/c360.organization/MDM000000000P0/instances Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX
Use the Location of a Record in a Hierarchy API to retrieve the exact location of a specific record in a hierarchy. It returns the path from the first-level node to the child records. It also retrieves the depth of the child record within the hierarchy. The API returns a maximum hierarchy depth of up to 9 levels. At depth level 3, a record can have up to 100,000 child records.
The API uses the GET method.
GET <baseApiURL>/shm-service/public/api/v1/hierarchies/<HierarchyModel>/<HierarchybusinessId>/nodes/<businessEntity>/<RecordbusinessId>/location
The following table describes the parameters that you can use in the request:
Parameter
Type
Description
HierarchyModel
String
Name of the hierarchy model that contains the hierarchy.
HierarchybusinessId
String
Business ID of the hierarchy in the hierarchy model.
businessEntity
String
Internal ID of the business entity that's associated with the record for which you want to retrieve its location.
Recordbusiness ID
String
Business ID of the record for which you want to retrieve its location.
The API doesn't contain any parameters in the request body.
GET response
The response shows the response code and the details of the record and its path.
The following table describes the parameters in the response:
Name
Type
Description
record
Object
Details of the record for which you retrieved the location.
record.businessId
String
Business ID of the record in the hierarchy.
record.businessEntity
String
Internal ID of the business entity that's associated with the record.
paths
Array
An array of path objects that are linked to the record.
paths.path
Array
The ordered sequence of records traversed from the first-level node to the child record. Each entry includes the business ID, business entity, and the relationship details of the record that connects to the parent record.
paths.path.businessId
String
Business ID of the record in the path.
paths.path.businessEntity
String
Internal ID of the business entity that's associated with the record in the path.
paths.path.relationshipFromParent
String
Specifies the exact relationship that connects the record to its immediate parent in the hierarchy.
The value is null for the first-level node in the path because it has no parent record.
paths.depth
Integer
The depth of the record within the hierarchy. It represents the number of levels between the first-level node and the record.
For example, if the requested record is the direct child of the first-level node, the response returns the value as 1.
GET example
You can use the following request to retrieve the exact location of a specific record in a hierarchy :
GET <baseApiURL>/shm-service/public/api/v1/hierarchies/hospital_hierarchy/MDM00000000014/nodes/c360.organization/MDM000000000NE/location Content-Type: application/json IDS-SESSION-ID: XXXXXXXXXXXXXXXXXXXXXX