Work with Hierarchies

To work with Hierarches in a Hub, you first need to create a new Hierarchy definition and then upload the Node-structure. If you want to use the hierarchy in a Studio report, and you plan to have end users access the report, you can enable NodeAssignments on the hierarchy and in that way control which nodes in the hierarchy each end user has access to. See examples below.

New Hierarchy

Request

POST  https://<host>/v1/hubs/32323/hierarchies HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>
{
    "name": "TestHierarchy",
    "listId": 32, (1)
    "enableNodeAssignments": "true"
}

1	If you plan to use NodeAssignments, you need to specify which end user list to use.

Response

{
    "id": 232, (1)
    "name": "TestHierarchy",
    "defaultLanguageId": 9, (2)
    "languages": [9],
    "endUserListId": 32,
    "nodeAssignmentsEnabled": "true",
    "hierarchyGuid": "67875445-C3B3-4598-94FB-4C31C2B52B49", (3)
    "schemaGuid": "4B1BB596-7048-4499-8C6C-C91899340676", (4)
    "schemaId": 323, (5)
    "schemaName": "TestHierarchy", (6)
    "tableId": 343, (7)
    "tableName": "root", (8)
    "companyId": 33, (9)
    "companyName": "Test Company" (10)
}

1	The unique Id of the hierarchy.
2	The defaultLanguageId property is always set to 9 (English).
3	The unique Guid of the hierarchy.
4	The hierarchy is always connected to a TableSchema in Confirmit. This is the Guid property of the TableSchema.
5	The unique Id of the TableSchema.
6	The name of the TableSchema.
7	The hierarchy is always connected to a DbTable in Confirmit. This is the unique Id of the DbTable.
8	The name of the DbTable.
9	The unique Id of the Confirmit Company the hierarchy belongs to.
10	The name of the Confirmit Company.

Get Hierarchy

Request

GET  https://<host>/v1/hubs/32323/hierarchies/232 HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>

Response

{
    "id": 232,
    "name": "TestHierarchy",
    "defaultLanguageId": 9,
    "languages": [9],
    "endUserListId": 32,
    "nodeAssignmentsEnabled": "true",
    "hierarchyGuid": "67875445-C3B3-4598-94FB-4C31C2B52B49",
    "schemaGuid": "4B1BB596-7048-4499-8C6C-C91899340676",
    "schemaId": 323,
    "schemaName": "TestHierarchy",
    "tableId": 343,
    "tableName": "root",
    "companyId": 33,
    "companyName": "Test Company"
}

Get Hierarchies

The '/v1/hubs/{hubId}/hierarchies' - endpoint includes some QueryParameters alowing you to customize the response:

pageSize - an integer describing the number of records to return for a 'paged' - response. Default is 100.
page - an integer describing which page of size pageSize to return for a 'paged' - response. Default is 1.

Request

GET  https://<host>/v1/hubs/32323/hierarchies?page=2&pageSize=2 HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>

Response

{
    "itemCount": 2,
    "totalCount": 200,
    "items": [
        {"id": 232, "name": "TestHierarchy", "companyId": 23, "companyName": "Test Company", "created": "2025-01-30 20:13:05", "createdBy": "test-user", "lastModified": "test-user2", "lastModifiedBy": "2025-02-10 02:13:05"},
        {"id": 433, "name": "TestHierarchy2", "companyId": 23, "companyName": "Test Company", "created": "2025-01-31 20:13:05", "createdBy": "test-user2", "lastModified": "", "lastModifiedBy": ""}
    ]
}

Hierarchy Content

Adding content to a hierarchy is done asynchronously via an Upload job.

Create Upload job

POST  https://<host>/v1/hubs/32323/hierarchies/232/uploads HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>
{
    "importMode": "UpdateExistingAndAddNew" (1)
}

1	Adding nodes supports two different modes "UpdateExistingAndAddNew" and "Replace". The first will update existing and add new, while the latter will delete all existing nodes before adding the new ones.

Response

{
    "id": 22,
    "status": "queue"
}

Add nodes to a job

POST  https://<host>/v1/hubs/32323/hierarchies/232/uploads/22/data HTTP/1.1
Accept: application/json
Content-Type: text/csv (1)
Authorization: Bearer <access_token>
Id\tLabel\tParentId
root\tRoot\t
l1\tLevel 1\troot
l2\tLevel 2\tl1

1	Note that Content-type is text/csv and the payload is in tab-delimitted format.

Start the job

PATCH  https://<host>/v1/hubs/32323/hierarchies/232/uploads/22 HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>
{
    "status": "execute"
}

Check status for a job

GET  https://<host>/v1/hubs/32323/hierarchies/232/uploads/22 HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>

Response

{
    "id": 22,
    "status": "complete"
}

Get error-results from the upload job (for failed jobs)

GET  https://<host>/v1/hubs/32323/hierarchies/232/uploads/22/results HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>

Response

[
    {
        "type": "hub-hierarchies/validation-result",
        "title": "error",
        "detail": "Row-2,Column-3: Invalid ParentId"
    },
    {
        "type": "hub-hierarchies/validation-result",
        "title": "warning",
        "detail": "Row-4,Column-2: Label is blank"
    }
]

Hierarchy Nodes

When a hierarchy upload job has completed, you can use the nodes-endpoint the get the content/structure of the hierarchy.

Request

GET  https://<host>/v1/hubs/32323/hierarchies/232/nodes HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>

Response

{
    "itemCount": 200,
    "totalCount": 200,
    "items": [
        {"id": "root", "label": "Root"},
        {"id": "l1", "label": "Level 1", "parentId": "root"},
        {"id": "l2", "label": "Level 2", "parentId": "l1"}
    ]
}

Node Assignments

If you have created a hierarchy with nodeAssignmentsEnabled set to "true", you can use the assignments-endpoints to handle which end users are assigned to which nodes. The assignments can be handled on a hierarchy level or on a node level.

End user user-names: ["johns", "miked", "brianj"] Hierarchy node-ids: ["root", "l1", "l2"]

Replace node assignments for the whole hierarchy (this will erase existing assignments)

PUT  https://<host>/v1/hubs/32323/hierarchies/232/node-assignments HTTP/1.1
Accept: application/json
Content-type: application/json
Authorization: Bearer <access_token>
[
    {
        "nodeId": "root",
        "userName": "johns"
    },
    {
        "nodeId": "l1",
        "userName": "brianj"
    },
]

Merge node assignments for the whole hierarchy (this will updating existing assignments and add new)

PUT  https://<host>/v1/hubs/32323/hierarchies/232/node-assignments HTTP/1.1
Accept: application/json
Content-type: application/json
Authorization: Bearer <access_token>
[
    {
        "nodeId": "root",
        "userName": "miked"
    }
]

Get node assignments for the whole hierarchy

GET  https://<host>/v1/hubs/32323/hierarchies/232/node-assignements HTTP/1.1
Accept: application/json
Authorization: Bearer <access_token>

Response

{
    "itemCount": 3,
    "totalCount": 3,
    "items": [
        {"nodeId": "root", "userName": "johns"},
        {"nodeId": "root", "userName": "miked"},
        {"nodeId": "l1", "userName": "brianj"},
    ]
}

Add assignments to a specific node

POST  https://<host>/v1/hubs/32323/hierarchies/232/nodes/root/assignments HTTP/1.1
Accept: application/json
Content-type: application/json
Authorization: Bearer <access_token>
[
    {
        "userName": "brianj"
    }
]

Get assignments for a specific node

GET  https://<host>/v1/hubs/32323/hierarchies/232/nodes/root/assignments HTTP/1.1
Accept: application/json
Content-type: application/json
Authorization: Bearer <access_token>

Response

{
    "itemCount": 3,
    "totalCount": 3,
    "items": [
        {"nodeId": "root", "userName": "johns"},
        {"nodeId": "root", "userName": "miked"},
        {"nodeId": "root", "userName": "brianj"},
    ]
}

Remove assignment from a specific node

DELETE  https://<host>/v1/hubs/32323/hierarchies/232/nodes/root/assignments/brianj HTTP/1.1
Accept: application/json
Content-type: application/json
Authorization: Bearer <access_token>