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(
    userContextUuid: "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

Getting started

Integration & Concepts

Use cases

Hierarchy Management

Zapier Integration

Mobile application

Hierarchy Level API Playground Guide

Exploring the Hierarchy Level API: A Complete Playground Journey

Getting Started

Prerequisites

Initial Setup

Step 1: Authentication

Step 2: Exploring the Data Structure

Understanding Hierarchy Levels

Querying Specific Levels

Step 3: Creating New Hierarchy Levels

Creating a Top-Level Structure

Creating Sub-Levels

Step 4: Modifying Existing Levels

Updating Labels

Step 5: Managing Relationships

Assigning Users to Levels

Assigning Trainings

Assigning Taxonomy Terms

Step 6: Cleaning Up

Removing Assignments

Deleting Hierarchy Levels

Step 7: Advanced Operations

Complex Queries

Batch Operations

Best Practices

Error Handling

Query Optimization

Testing Approach

Next Steps

​Exploring the Hierarchy Level API: A Complete Playground Journey

​Getting Started

​Prerequisites

​Initial Setup

​Step 1: Authentication

​Step 2: Exploring the Data Structure

​Understanding Hierarchy Levels

​Querying Specific Levels

​Step 3: Creating New Hierarchy Levels

​Creating a Top-Level Structure

​Creating Sub-Levels

​Step 4: Modifying Existing Levels

​Updating Labels

​Step 5: Managing Relationships

​Assigning Users to Levels

​Assigning Trainings

​Assigning Taxonomy Terms

​Step 6: Cleaning Up

​Removing Assignments

​Deleting Hierarchy Levels

​Step 7: Advanced Operations

​Complex Queries

​Batch Operations

​Best Practices

​Error Handling

​Query Optimization

​Testing Approach

​Next Steps

Exploring the Hierarchy Level API: A Complete Playground Journey

Getting Started

Prerequisites

Initial Setup

Step 1: Authentication

Step 2: Exploring the Data Structure

Understanding Hierarchy Levels

Querying Specific Levels

Step 3: Creating New Hierarchy Levels

Creating a Top-Level Structure

Creating Sub-Levels

Step 4: Modifying Existing Levels

Updating Labels

Step 5: Managing Relationships

Assigning Users to Levels

Assigning Trainings

Assigning Taxonomy Terms

Step 6: Cleaning Up

Removing Assignments

Deleting Hierarchy Levels

Step 7: Advanced Operations

Complex Queries

Batch Operations

Best Practices

Error Handling

Query Optimization

Testing Approach

Next Steps