> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opigno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hierarchy Level API Playground Guide
# Exploring the Hierarchy Level API: A Complete Playground Journey
This guide provides a comprehensive walkthrough of the Hierarchy Level API using the GraphQL playground. Follow the structured approach to understand authentication, data querying, and operational procedures.
## Getting Started
### Prerequisites
* Access to an Opigno Enterprise instance
* Valid API credentials (Client ID and Client Secret)
* GraphQL playground access (typically at `/graphql` endpoint)
### Initial Setup
Before proceeding, you need to authenticate and understand the basic structure. The playground provides an interactive environment for testing queries and mutations in real-time.
## Step 1: Authentication
Authentication requires an access token. Configure the following headers in the playground:
```json theme={null}
{
"authorization": "Bearer YOUR_ACCESS_TOKEN",
"opigno-client-uuid": "YOUR_CLIENT_UUID"
}
```
Replace `YOUR_ACCESS_TOKEN` with the token obtained from your OAuth2 flow, and `YOUR_CLIENT_UUID` with your client identifier.
## Step 2: Exploring the Data Structure
### Understanding Hierarchy Levels
Begin by exploring existing hierarchy levels in your system. This query provides an overview:
```graphql theme={null}
query exploreHierarchyLevels {
hierarchyLevels {
id
label
depth
parent {
id
label
}
children {
id
label
}
}
}
```
This query returns all accessible hierarchy levels with their relationships, providing a complete view of your organizational structure.
### Querying Specific Levels
Once you understand the structure, you can query specific levels:
```graphql theme={null}
query getSpecificLevel {
hierarchyLevels(hierarchyLevelId: 1) {
id
label
depth
parent {
id
label
}
children {
id
label
}
}
}
```
## Step 3: Creating New Hierarchy Levels
### Creating a Top-Level Structure
Create a new top-level hierarchy level:
```graphql theme={null}
mutation createTopLevel {
createHierarchyLevel(hierarchyLevel: {
label: "New Department"
}) {
errors
response {
id
label
parent {
id
label
}
}
}
}
```
Top-level hierarchy levels do not require `parentId` specification. The system automatically sets this value to 0.
### Creating Sub-Levels
Create a sub-level under an existing hierarchy:
```graphql theme={null}
mutation createSubLevel {
createHierarchyLevel(hierarchyLevel: {
label: "Sub-Department A",
parentId: "1"
}) {
errors
response {
id
label
parent {
id
label
}
}
}
}
```
## Step 4: Modifying Existing Levels
### Updating Labels
Modify the name of an existing hierarchy level:
```graphql theme={null}
mutation updateLevel {
updateHierarchyLevel(
id: 1,
hierarchyLevel: {
label: "Updated Department Name"
}
) {
errors
response {
id
label
parent {
id
label
}
}
}
}
```
The update mutation implements partial update semantics. Only specified fields are updated; unspecified fields retain their current values.
## Step 5: Managing Relationships
### Assigning Users to Levels
Establish connections between user contexts and specific hierarchy levels:
```graphql theme={null}
mutation assignUser {
assignUserContextToLevel(
userContextUuid: "5acfc440-88e0-4286-b089-c0f03575ed9a"
hierarchyLevelId: 1
) {
errors
response
}
}
```
### Assigning Trainings
Make trainings available to specific hierarchy levels:
```graphql theme={null}
mutation assignTraining {
assignTrainingToLevel(
trainingId: 4
hierarchyLevelId: 1
) {
errors
response
}
}
```
### Assigning Taxonomy Terms
Apply taxonomy terms to hierarchy levels for categorization:
```graphql theme={null}
mutation assignTaxonomy {
assignTaxonomyTermToLevel(
taxonomyTermId: 9
hierarchyLevelId: 1
) {
errors
response
}
}
```
## Step 6: Cleaning Up
### Removing Assignments
Remove existing relationships when necessary:
```graphql theme={null}
mutation unassignTraining {
unassignTrainingFromLevel(
trainingId: 4
hierarchyLevelId: 1
) {
errors
response
}
}
```
```graphql theme={null}
mutation unassignTaxonomy {
unassignTaxonomyTermFromLevel(
taxonomyTermId: 9
hierarchyLevelId: 1
) {
errors
response
}
}
```
### Deleting Hierarchy Levels
**Important:** This operation permanently removes the hierarchy level and all associated data. Verify the target hierarchy level before proceeding.
```graphql theme={null}
mutation deleteLevel {
deleteHierarchyLevel(id: 5) {
errors
response
}
}
```
## Step 7: Advanced Operations
### Complex Queries
Execute multiple operations in a single request:
```graphql theme={null}
query comprehensiveView {
# Get all hierarchy levels
allLevels: hierarchyLevels {
id
label
depth
}
# Get specific level with details
specificLevel: hierarchyLevels(hierarchyLevelId: 1) {
id
label
depth
parent {
id
label
}
children {
id
label
}
}
# Get user context
userContext: getUserContext {
uuid
}
}
```
### Batch Operations
Execute multiple mutations sequentially:
```graphql theme={null}
mutation batchOperations {
# Create multiple levels
level1: createHierarchyLevel(hierarchyLevel: {
label: "Level 1"
}) {
errors
response {
id
label
}
}
level2: createHierarchyLevel(hierarchyLevel: {
label: "Level 2"
}) {
errors
response {
id
label
}
}
}
```
## Best Practices
### Error Handling
Always check the `errors` field in mutation responses before proceeding with dependent operations. The API returns detailed error messages to help troubleshoot issues.
### Query Optimization
Request only the fields you need. GraphQL allows you to specify exactly which fields to return, reducing payload size and improving performance.
### Testing Approach
Use the playground to test queries with sample data before implementing them in your application. This helps identify potential issues early in the development cycle.
## Next Steps
Now that you're familiar with the Hierarchy Level API, you can:
* Integrate these operations into your application
* Explore additional fields available in the schema
* Review the API reference documentation for complete field descriptions
* Learn about advanced filtering and pagination options