Hierarchy overview

The hierarchy is a tree structure. For example:

  • An item on the hierarchy is called a node.

  • The root node is at the top of the hierarchy and has no parent node.

Hierarchy Structure Rules

  • A node can have many children.

  • A node can only have a single parent or none if it is the root node.

  • There can only be one root node in the hierarchy.

  • The structure of the hierarchy cannot have circular reference where the nodes form a loop.

The Relationship between an Employee and the Hierarchy Node

The relationship is Employee > Job > Hierarchy Node.

You can get from an Employee by getting the Employees Id, for example:

Copy 
GET https://api.iris.co.uk/hr/v2/employees

 

Copy 
GET https://api.iris.co.uk/hr/v2/employees?$filter=DisplayId eq '123'

 

Copy 
{     
"Id": "14c01da5-6e48-4938-be5d-f755fb135666",     ...     "FirstName": "Fred",     "LastName": "Bloggs",     ... 
}
        

Using the EmployeeId you get the active Job from the jobs service:

Copy 
GET https://api.iris.co.uk/hr/v2/jobs?$filter=EmployeeId eq '<id>' and Active eq true

 

Copy 
{
"Id": "055e11e9-f620-410f-9365-63123cfa17f2",     ...     "StartDate": "2012-04-01T00:00:00Z",     "EndDate": null,     "WorkingCalendar": "Office Calendar",     "LineManagerId": "afa26d1a-2aaa-41e4-a5bb-b62021d56a94",     "HierarchyNodeId": "02c14ff0-860d-40ac-b27c-42f699aede10",     "Active": true,     ... 
}

Using the HierarchyNodeId you can retrieve the details of the Hierarchy Node:

Copy 
GET https://api.iris.co.uk/hr/v2/hierarchy/02c14ff0-860d-40ac-b27c-42f699aede10

Getting the path from a Node ID

The path is the description of the hierarchy node, for example:

Company > Division > Location > Department > Team

where the "Team" is the node.

You can assemble this by calling the api to get the parent ID from the node ID on the Employee's Job record, for example:

Copy 
GET https://api.iris.co.uk/hr/v2/hierarchy/8cff89f5-25c0-48f8-b38f-d0157d199b52

 

Copy 
{
"Id": "8cff89f5-25c0-48f8-b38f-d0157d199b52",     ...     "ParentId": "14c01da5-6e48-4938-be5d-f755fb135666",     "Level": 3,     "Title": "Head Office",     "Disabled": false 
}

The level is 3 in this example so there are 2 nodes above this with the root node at level 1.

Using the Parent ID from this response you can make a request to get this parent node:

Copy 
GET https://api.iris.co.uk/hr/v2/hierarchy/14c01da5-6e48-4938-be5d-f755fb135666

 

Copy 
{
"Id": "14c01da5-6e48-4938-be5d-f755fb135666",     ...     "ParentId": "e920b9e8-7550-4723-bbfd-e67423b92791",     "Level": 2,     "Title": "Domino Electric Ltd",     "Disabled": false 
}

And then getting the root using the level 2 node Parent ID:

Copy 
GET https://api.iris.co.uk/hr/v2/hierarchy/e920b9e8-7550-4723-bbfd-e67423b92791

 

Copy 
{
"Id": "e920b9e8-7550-4723-bbfd-e67423b92791",     ...     "ParentId": null,     "Level": 1,     "Title": "Company",     "Disabled": false 
}

This final node has no parent ID and has a level of 1 indicating it is the root node.

To generate the path, the title should be captured at each request and can then be formatted. The path is assembled backwards, working towards the root node.

Copy 
{Level 1 Title} -> {Level 2 Title} -> {Level 3 Title}

Getting a hierarchy node's child nodes

You can retrieve the hierarchy child nodes as an array using an OData filter.

Copy 
GET https://api.iris.co.uk/hr/v2/hierarchy?$filter=ParentId eq '14c01da5-6e48-4938-be5d-f755fb135666

 

Copy 
{     "value": [         {             "Id": "8cff89f5-25c0-48f8-b38f-d0157d199b52",             ...             "ParentId": "14c01da5-6e48-4938-be5d-f755fb135666",             "Level": 3,             "Title": "Warehouse",             "Disabled": false         },         ...         {             "Id": "0a22e5ac-bdee-4528-bf08-5e264fea5aa3",             ...             "ParentId": "14c01da5-6e48-4938-be5d-f755fb135666",             "Level": 3,             "Title": "Sales",             "Disabled": false         }     ] }

Getting all Hierarchy Nodes on the same Level

Usually, a hierarchy level represents a logical part of a business, such as office or team. You can retrieve all hierarchy nodes on the same level using an OData filter.

Copy 
GET https://api.iris.co.uk/hr/v2/hierarchy?$filter=Level eq 3

 

Copy 
           {     "value": [         {             "Id": "8cff89f5-25c0-48f8-b38f-d0157d199b52",             ...             "ParentId": "14c01da5-6e48-4938-be5d-f755fb135666",             "Level": 3,             "Title": "Warehouse",             "Disabled": false         },         {             "Id": "e3d3e16c-a11f-4a86-81a1-feb57ba8d665",             ...             "ParentId": "14c01da5-6e48-4938-be5d-f755fb135666",             "Level": 3,             "Title": "Production",             "Disabled": false         },         {             "Id": "0a22e5ac-bdee-4528-bf08-5e264fea5aa3",             ...             "ParentId": "14c01da5-6e48-4938-be5d-f755fb135666",             "Level": 3,             "Title": "Sales",             "Disabled": false         }     ] }