Skip to main content

​
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: 
{
  "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: 
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: 
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: 
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: 
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: 
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: 
mutation assignUser {
  assignUserContextToLevel(
    userContextId: "5acfc440-88e0-4286-b089-c0f03575ed9a"
    hierarchyLevelId: 1
  ) {
    errors
    response
  }
}

​
Assigning Trainings

Make trainings available to specific hierarchy levels: 
mutation assignTraining {
  assignTrainingToLevel(
    trainingId: 4
    hierarchyLevelId: 1
  ) {
    errors
    response
  }
}

​
Assigning Taxonomy Terms

Apply taxonomy terms to hierarchy levels for categorization: 
mutation assignTaxonomy {
  assignTaxonomyTermToLevel(
    taxonomyTermId: 9
    hierarchyLevelId: 1
  ) {
    errors
    response
  }
}

​
Step 6: Cleaning Up

​
Removing Assignments

Remove existing relationships when necessary: 
mutation unassignTraining {
  unassignTrainingFromLevel(
    trainingId: 4
    hierarchyLevelId: 1
  ) {
    errors
    response
  }
}

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.
mutation deleteLevel {
  deleteHierarchyLevel(id: 5) {
    errors
    response
  }
}

​
Step 7: Advanced Operations

​
Complex Queries

Execute multiple operations in a single request: 
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: 
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
⌘I