OrgJQL Documentation

Complete guide to organizational JQL functions for Jira

Table of Contents

Overview

OrgJQL extends Jira's JQL (Jira Query Language) with powerful organizational hierarchy functions, enabling you to query issues based on team structures and reporting relationships. Whether you need to find all issues assigned to a specific manager's team or track work across organizational boundaries, OrgJQL provides the tools to make complex organizational queries simple and efficient.

Key Benefits

  • Simplified Queries: Transform complex user lists into simple organizational references
  • Dynamic Updates: Organizational changes automatically reflect in existing queries
  • Performance Optimized: Precomputation system ensures fast execution at scale
  • Integration Ready: RESTful APIs for seamless integration with HR systems and automation tools

Getting Started

Quick Start Video Tutorial

Quick Start Video Tutorial

Watch this 2-minute walkthrough to get OrgJQL up and running in your Jira instance. Learn how to upload organizational data, test your first query, and start using organizational functions.

Watch Video

Quick Setup (3 Steps)

  1. 1 Update Org Data: Navigate to the "Update Org Data" section in the OrgJQL admin panel
  2. 2 Test Your Query: Use the built-in query tester to verify your organizational structure
  3. 3 Execute in Jira: Run your orgOf() queries directly in Jira's Issue Navigator

First Query Example

Once your organizational data is configured, you can immediately start using organizational queries:

assignee in orgOf("jane.smith")

This finds all issues assigned to Jane Smith and everyone who reports to her, recursively through the organizational hierarchy.

Managing Organizational Data

Update Org Data Video Tutorial

Update Org Data Walkthrough

Step-by-step guide through the Update Org Data page. Learn how to upload data files, use different formats, test your organizational structure, and manage data updates effectively.

Watch Video

Manual Data Entry (Ideal for Testing)

The easiest way to get started with OrgJQL is to manually upload your organizational data through the web interface. This approach is perfect for trying out the system or managing smaller organizations.

Quick Setup Process

  1. Access Update Org Data: Click on "Update Org Data" in the OrgJQL admin panel
  2. Upload Your Data: Click "Add Data" or "Upload Data File" to start the upload process
  3. Choose Your Format: The system accepts data in JSON or TSV
  4. Save and Test: Save your data and immediately test it with JQL queries

Easy Data Formats

OrgJQL uses user/manager data to construct the structure of you organization. Provide this information using unique values for each person. Usernames or emails work best (fullnames will also work as long as your Jira Admin ensures that fullnames are unique).
Option 1: Copy from Spreadsheet (Easiest)

If you have your org chart in Excel or Google Sheets, simply copy and paste the User and Manager columns:

john.doe jane.smith
alice.cooper jane.smith
jane.smith engineering.director
engineering.director
Option 2: JSON Format (Most Flexible)

For structured data entry, use this simple JSON format:

 {
  "records": [
    {"user": "john.doe", "manager": "jane.smith"},
    {"user": "alice.cooper", "manager": "jane.smith"},
    {"user": "jane.smith", "manager": "engineering.director"},
    {"user": "engineering.director", "manager": ""}
  ]
}

Important Data Guidelines

  • User Names: Must exactly match Jira usernames or email addresses
  • Top-Level Managers: Leave the manager field empty for top-level executives
  • Case Sensitivity: User names are case-sensitive - double-check spelling
  • Format Flexibility: The system automatically detects and converts your chosen format

Testing Your Setup

After uploading your data:

  1. Navigate to the "Test Queries" tab
  2. Try a simple query like orgOf("jane.smith")
  3. Verify that the expanded JQL shows the correct users
  4. Use your query in Jira's Issue Navigator

Understanding the Update Org Data Page

The Update Org Data page is your control center for managing organizational information in OrgJQL.

At-a-Glance Status Dashboard

When you first visit the page, you'll see two status cards that instantly show you:

  • Organization Data Status: Whether you have organizational data loaded, when it was last updated, and how many employee records are stored
  • API Token Status: How many API tokens you have for automated integrations and when they were last used

Three Main Functions

Manage Data Tab
  • Easy upload options
  • Manual vs API guidance
  • View/edit current data
API Tokens Tab
  • Generate secure tokens
  • Monitor API usage
  • Integration examples
Test Queries Tab
  • Validate queries
  • See user inclusion
  • Test before production

Production API Setup

API Integration Video Tutorial

API Integration Tutorial

Complete guide to setting up automated API integrations. Learn how to generate tokens, configure webhooks, integrate with HR systems, and set up automated data synchronization for production use.

Watch Video

For production deployments, automated data synchronization ensures your organizational queries stay current without manual intervention.

API Token Management

  1. Generate API Token: Use the Web Trigger Token Manager in the admin panel
  2. Secure Storage: Store tokens securely in your integration system
  3. Regular Rotation: Implement token rotation as part of your security practices

Automated Data Updates

Update Organizational Data

Endpoint:Use forge webtrigger and pick update-org-jql to retrieve the endpoint to use for updating your org data

Authentication: Use one of the API Tokens you generated in the prior step

curl -X POST "https://your-app-url/webtrigger/update-org-data" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgData": {
      "type": "json",
      "records": [
        {"user": "john.doe@company.com", "manager": "jane.smith@company.com"},
        {"user": "alice.cooper@company.com", "manager": "jane.smith@company.com"},
        {"user": "jane.smith@company.com", "manager": "director@company.com"}
      ],
      "userDisplayname": "HR System Integration"
    }
  }'

Integration Best Practices

  • Regular Sync: Schedule organizational data updates to run after HR system changes
  • Incremental Updates: Update only changed organizational contexts when possible
  • Error Handling: Implement retry logic for network failures and API rate limits
  • Monitoring: Track API response codes and precomputation completion status
  • Validation: Verify organizational data integrity before sending to OrgJQL

Using OrgJQL Functions

Basic Syntax

orgOf(user)
  • user: Root of org of interest
  • Returns: JQL-compatible user list for everyone rolling up to the specified user

Query Examples

Manager and Direct Reports

assignee in orgOf("jane.smith")

Reviewing JQL Executions

Understanding Precomputations

OrgJQL uses a precomputation system to ensure fast query execution:

  • Background Processing: Organizational queries are processed and cached automatically
  • Real-Time Updates: Changes to organizational data trigger precomputation refresh
  • Performance Optimization: Large organizational queries execute in milliseconds

Monitoring Execution Status

  1. Navigate to Review JQL Executions in the admin panel
  2. Monitor precomputation status and completion times
  3. Identify queries that may need optimization
  4. Track organizational data usage patterns

Performance Optimization

  • Regular Refresh: Schedule periodic precomputation refresh during off-peak hours
  • Incremental Updates: Target specific organizational contexts for faster updates
  • Monitoring: Track query execution times and optimize slow-performing organizational structures

Troubleshooting

Common Issues

"orgOf function not recognized"

Cause: OrgJQL app not properly installed or deployed

Solution: Verify app installation and ensure latest deployment is active

"No users found for organizational query"

Cause: Organizational data not configured or user identifiers don't match Jira users

Solution: Verify organizational data format and ensure user identifiers match Jira usernames/email addresses

"Query timeout or slow performance"

Cause: Precomputations not current or very large organizational hierarchy

Solution: Refresh precomputations and consider breaking large queries into smaller organizational scopes

"API authentication failed"

Cause: Invalid or expired API token

Solution: Generate new API token and update integration credentials

Data Format Requirements

User Identifiers

  • Must match Jira user account names or email addresses exactly
  • Case-sensitive matching
  • Support for both username and email formats

Organizational Hierarchy

  • Manager field can be empty for top-level users
  • Circular references are automatically detected and prevented
  • Maximum hierarchy depth: 20 levels

Getting Help

  • Built-in Help: Use the Help section in the OrgJQL admin panel
  • Query Testing: Verify organizational queries with the integrated query tester
  • API Documentation: Reference the complete API documentation for integration details

Advanced Topics

Data Security and Validation

Access Control

  • API tokens provide scoped access to organizational data updates
  • Token usage is logged for audit purposes
  • Administrative functions require appropriate Jira permissions

Scalability Considerations

Large Organizations

  • Tested with organizational hierarchies up to 10,000+ users
  • Precomputation system scales automatically with organization size
  • Memory-efficient processing for complex organizational queries

OrgJQL provides reliable, scalable organizational query capabilities for Jira. From initial testing with manual data entry to enterprise-grade automated integration, OrgJQL adapts to your organizational needs while maintaining fast, consistent query performance.