Beeye Terminology Guide

This guide helps translate between user terminology and Beeye GraphQL API terms.

Quick Reference Card

Field Access Patterns

  • Projects: company { projects(first: 100) { items { iD projectName } } }
  • Employees: company { employees(first: 100) { items { id fullName } } }
  • Tasks: company { tasks(first: 100, where: [...]) { items { id name } } }
  • Planning: company { taskPlanning(where: [...]) { items { date amount } } }

Critical Field Names

  • Project ID: iD (NOT id) - capital I, capital D
  • Employee ID: id (lowercase)
  • Employee name: fullName (NOT name)
  • Project name: projectName (NOT name)

Required Patterns

  • All list queries: Must include first: N parameter
  • Paginated results: Always use items { ... } wrapper
  • Filters: Always use array syntax where: [{...}] not where: {...}
  • Filter values: Always arrays of strings: value: ["value"] not value: "value"

Common Mistakes to Avoid

Project Fields

  • ❌ projects { id } → ✅ projects(first: 100) { items { iD } }
  • ❌ projects { name } → ✅ projects(first: 100) { items { projectName } }
  • ❌ projects(first: 10) { id } → ✅ projects(first: 10) { items { iD } }
  • ❌ projects { iD } (missing first) → ✅ projects(first: 100) { items { iD } }

Employee Fields

  • ❌ employees { name } → ✅ employees(first: 100) { items { fullName } }
  • ❌ employees { id } → ✅ employees(first: 100) { items { id } } (id is lowercase for employees)
  • ❌ employees { items { fullName } } (missing first) → ✅ employees(first: 100) { items { fullName } }

Pagination

  • ❌ company { projects { iD } } → ✅ company { projects(first: 100) { items { iD } } }
  • ❌ company { employees { fullName } } → ✅ company { employees(first: 100) { items { fullName } } }
  • All list queries require first parameter and use items array

Filter Syntax

  • ❌ where: { path: "iD", comparison: equal, value: ["123"] } → ✅ where: [{ path: "iD", comparison: equal, value: ["123"] }]
  • ❌ where: { path: "name", comparison: contains, value: "John" } → ✅ where: [{ path: "fullName", comparison: contains, value: ["John"] }]
  • where is always an array of WhereExpression objects, never a single object
  • value is always an array of strings, even for single values

Type Name Exploration

  • ❌ Exploring "Company" → ✅ Explore "CompanyGraph"
  • ❌ Exploring "Employee" → ✅ Explore "ResourcesGraph"
  • ❌ Exploring "Project" → ✅ Explore "ProjectGraph"
  • ❌ Exploring "Task" → ✅ Explore "ProjetTaskGraph"
  • Use ExploreGraphQlType with the correct type names, or it will auto-map common aliases

Core Concepts

Projects

  • User terms: "project", "job", "engagement", "mission", "initiative", "client project"
  • GraphQL field: projects (under company)
  • Key fields:
    • iD or id: Project identifier
    • projectName: Project name
    • startDate / endDate: Project timeline
    • responsable_Id: Project manager/owner ID
    • externalId: External system identifier
    • activityFamily_Id: Category/type of project

Client

  • User terms: "client", "customer"
  • GraphQL field: fondDeFinancement (often found under projects)
  • Key fields:
    • id: Client identifier
    • name: Client name
  • Note: In GraphQL, clients are often called fondDeFinancement and represent the client of a project

Tasks

  • User terms: "task", "work item", "assignment", "deliverable", "activity", "work package"
  • GraphQL field: tasks (under company) or projetTasks (under a project)
  • Key fields:
    • id: Task identifier
    • name: Task name
    • startDate / projectedEnd / realEnd: Task timeline
    • taskId: Task ID (used in planning)
    • projectId: Parent project ID
    • ressource_Id: Assigned resource ID

Resources / Employees / People

  • User terms: "employee", "resource", "user", "collaborateur" (French), "person", "team member", "staff", "worker", "consultant"
  • GraphQL field: employees (under company)
  • Key fields:
    • id: Employee/resource identifier
    • fullName: Full name
    • userId: User account ID
    • Skills, bill rates, titles, etc.

Planning / Allocations

  • User terms: "allocation", "assignment", "booking", "planning", "schedule", "workload", "capacity planning"
  • GraphQL fields:
    • taskPlanning: Planned hours (forward-looking planning)
    • bookings: Confirmed bookings (actual assignments/budgets/estimates)
    • conflicts: Days where a user is planned more than their available hours
  • Key concepts:
    • Task Planning: Future/planned work allocation with hours per day
    • Bookings: Confirmed time allocations with start/end dates (also called "budget" or "estimate")
    • Note: Sometimes users refer to taskPlanning as "booking". The LLM must infer from context whether they mean actual bookings (budgets/estimates) or taskPlanning (forward-looking planning)
    • Allocation: General term for assigning work to resources
    • Capacity: Total available hours for a resource, stored in DailyCapacity for the user
    • Utilization: Percentage of capacity being used
    • Conflict: A day where user is planned more than their available hours (plannedAmount > capacityAmount)

Time & Dates

  • User terms: "this week", "next month", "Q1", "sprint", "period"
  • GraphQL: Date fields use ISO 8601 format (YYYY-MM-DD)
  • Common patterns:
    • Date ranges: startDate and endDate fields
    • Planning dates: date field in taskPlanning
    • Booking periods: startDate and endDate in bookings

Common User Queries → GraphQL Translation

"Show me all my projects"

query {
  company {
    projects(first: 100) {
      items {
        iD
        projectName
        startDate
        endDate
      }
    }
  }
}

"Who's working on project X?"

query {
  company {
    projects(
      where: [
        {
          path: "iD"
          comparison: equal
          value: ["X"]
        }
      ]
      first: 100
    ) {
      items {
        iD
        projectName
        projetTasks {
          id
          name
          ressource_Id
        }
      }
    }
  }
}

"What's John's workload this week?"

# Step 1: Find John's id
query {
  company {
    employees(
      where: [
        {
          path: "fullName"
          comparison: contains
          value: ["John"]
        }
      ]
      first: 10
    ) {
      items {
        id
        fullName
      }
    }
  }
}

# Step 2: Query taskPlanning for John's resourceId and date range
# (Use the resourceId from step 1, and calculate startOfWeek/endOfWeek dates)
query {
  company {
    taskPlanning(
      where: [
        {
          path: "resourceId"
          comparison: equal
          value: ["<resourceId from step 1>"]
        }
        {
          path: "date"
          comparison: greaterThanOrEqual
          value: ["2024-01-01"]
        }
        {
          path: "date"
          comparison: lessThanOrEqual
          value: ["2024-01-07"]
        }
      ]
    ) {
      items {
        date
        amount
        resourceId
      }
    }
  }
}
# Sum the 'amount' field for all items to get total planned hours (not capacity - capacity is in DailyCapacity)

"Show me conflicts / over-allocations"

query getConflictsAfterADate {
  company {
    id
    name
    conflicts(
      first: 100
      where: [
        {
          path: "date"
          comparison: greaterThanOrEqual
          value: ["2025-12-19"]
        }
      ]
    ) {
      totalCount
      items {
        date
        capacityAmount
        plannedAmount
        user {
          id
          fullName
        }
        taskPlannings {
          amount
          projects {
            iD
            projectName
            fondDeFinancement {
              id
              name
            }
          }
          projetTasks {
            id
            name
            startDate
            projectedEnd
          }
        }
      }
    }
  }
}

Conflict Definition: A conflict is a day where a user is planned more than their available hours (plannedAmount > capacityAmount). The conflicts entry point already pre-filters for this condition, so all results returned are conflicts by definition.

Key Fields:

  • date: Date of the conflict
  • capacityAmount: User's maximum work hours (available capacity)
  • plannedAmount: Total hours planned for this user for this date
  • user: The user/resource experiencing the conflict (ResourceGraph type)
  • taskPlannings: List of plannings for the user for this date, includes tasks and project information
    • amount: Hours planned for this specific planning
    • projects: Project information (note: fondDeFinancement = Client)
    • projetTasks: Task information

Filtering Conflicts: Filters follow the same pattern as always using WhereExpression with path, comparison, and value.

Filter by time period (e.g., "this month"):

where: [
  {
    path: "date"
    comparison: greaterThanOrEqual
    value: ["2025-01-01"]
  },
  {
    path: "date"
    comparison: lessThanOrEqual
    value: ["2025-01-31"]
  }
]

Filter by user (using path propagation):

where: [
  {
    path: "user.fullName"
    comparison: contains
    value: ["John"]
  }
]

You can combine filters and use any user field via path propagation (e.g., user.id, user.fullName, user.resourceId).

"What tasks are due this month?"

query {
  company {
    tasks(
      where: [
        {
          path: "projectedEnd"
          comparison: greaterThanOrEqual
          value: ["2024-01-01"]
        }
        {
          path: "projectedEnd"
          comparison: lessThanOrEqual
          value: ["2024-01-31"]
        }
      ]
      first: 100
    ) {
      items {
        id
        name
        projectedEnd
        realEnd
      }
    }
  }
}

Field Name Variations

Beeye GraphQL uses mixed naming conventions:

  • camelCase: projectName, startDate, fullName
  • PascalCase: iD, Id (note: iD not id for projects!)
  • snake_case: resourceId, projectId, taskId

Important: Project IDs use iD (capital I, capital D), not id!

Pagination

Most entry points that support the first parameter also support pagination via the pageInfo object.

Pagination Structure:

{
  pageInfo {
    hasNextPage
    endCursor
  }
}

How to use pagination:

  • first: Number of items to fetch per page
  • after: Cursor for next page (set to endCursor from previous page's pageInfo)
  • For the first page, after should be null or omitted
  • Check hasNextPage to know if there are more pages
  • Use endCursor from current page as after parameter for next page

Example:

# First page
query {
  company {
    projects(first: 100) {
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        iD
        projectName
      }
    }
  }
}

# Next page (using endCursor from first page)
query {
  company {
    projects(first: 100, after: "<endCursor from previous page>") {
      pageInfo {
        hasNextPage
        endCursor
      }
      items {
        iD
        projectName
      }
    }
  }
}

Common Filters

Use the where parameter in GraphQL queries with WhereExpression input type. Multiple filters in an array are combined with AND logic by default.

WhereExpression Structure

{
  path: "fieldName"
  comparison: equal
  value: ["value"]  # Array of strings, can have multiple values
  connector: and    # Optional: and or or (default: and)
  negate: false    # Optional: negate the expression
}

Complex Filter Paths

Filter paths can traverse relationships using dot notation. This works for all graphs, not just specific ones.

Example: Filter employees where their direction name contains "aaaaa"

where: [
  {
    path: "direction.directionName"
    comparison: contains
    value: ["aaaaa"]
  }
]

Example: Filter projects by manager's name

where: [
  {
    path: "responsable.fullName"
    comparison: contains
    value: ["John"]
  }
]

You can traverse multiple levels: "level1.level2.level3.fieldName"

Comparison Values

  • Equality: equal, in, notIn
  • Numeric/Object/Date: greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual
  • String: startsWith, endsWith, contains, like

Connector Values

  • and (default) - combine with AND logic
  • or - combine with OR logic

Common Filter Examples

Equals:

where: [
  {
    path: "fieldName"
    comparison: equal
    value: ["value"]
  }
]

Greater than or equal (for dates/numbers):

where: [
  {
    path: "projectedEnd"
    comparison: greaterThanOrEqual
    value: ["2024-01-01"]
  }
]

Less than or equal:

where: [
  {
    path: "projectedEnd"
    comparison: lessThanOrEqual
    value: ["2024-12-31"]
  }
]

Contains text:

where: [
  {
    path: "name"
    comparison: contains
    value: ["text"]
  }
]

In list (multiple values):

where: [
  {
    path: "id"
    comparison: in
    value: ["id1", "id2", "id3"]
  }
]

Starts with:

where: [
  {
    path: "projectName"
    comparison: startsWith
    value: ["Project"]
  }
]

Multiple filters (AND by default):

where: [
  {
    path: "projectedEnd"
          comparison: greaterThanOrEqual
    value: ["2024-01-01"]
  }
  {
    path: "projectedEnd"
    comparison: lessThanOrEqual
    value: ["2024-01-31"]
  }
]

OR logic using connector:

where: [
  {
    path: "field1"
    comparison: equal
    value: ["value1"]
    connector: or
  }
  {
    path: "field2"
    comparison: greaterThan
    value: ["value2"]
  }
]

Complex nested filters (using groupedExpressions for OR logic):

where: [
  {
    groupedExpressions: [
      {
        path: "field1"
        comparison: equal
        value: ["value1"]
        connector: or
      },
      {
        path: "field2"
        comparison: greaterThan
        value: ["value2"]
        connector: or
      }
    ]
  }
]

Status & State Fields

  • isTentative: Planning is tentative (not confirmed)
  • realEnd: Actual completion date (vs projectedEnd)

Workspace Context

  • workSpaceId: Optional workspace/team context for planning
  • Some queries may filter by workspace

Tips for LLMs

  1. Always check field names: Use ExploreGraphQlType to see exact field names
  2. Handle pagination: Large lists need multiple queries with after cursor
  3. Date formats: Always use ISO 8601 (YYYY-MM-DD)
  4. Project IDs: Use iD not id for projects
  5. User language: Translate user terms to GraphQL fields using this guide
  6. Planned hours calculation: Sum amount from taskPlanning for a resource in a date range to get total planned hours. Capacity is stored in DailyCapacity for the user.
  7. Conflicts: Use the conflicts entry point to find days where users are over-allocated. This entry point already filters for plannedAmount > capacityAmount, so all results are conflicts by definition.
  8. Filter syntax: Use WhereExpression input type with comparison enum values (equal, greaterThanOrEqual, contains, etc.) - all lowercase camelCase
  9. Multiple filters: Multiple filters in array use AND by default; use connector: Or for OR logic
  10. Value arrays: value field is always an array of strings, even for single values
  11. GraphQL queries: Write complete GraphQL queries with proper filter structure in the where parameter

Example: Understanding "Show me who's overloaded"

User says: "Show me who's overloaded"

Translation steps:

  1. "overloaded" = conflicts (planned hours > capacity)
  2. Use the conflicts entry point under company
  3. Filter by date range if needed using where parameter
  4. The query returns all conflicts with:
    • User information
    • Date of conflict
    • Capacity vs planned amounts
    • All task plannings causing the conflict (with project and task details)
  5. Note: fondDeFinancement in projects = Client