> ## Documentation Index > Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt > Use this file to discover all available pages before exploring further. # Categories > Use AI-powered categories to automatically classify tickets by topic with name, description, and example phrases that train the classifier. Categories use AI-powered classification to automatically organize tickets when they're created, analyzing ticket content to determine the best classification match. *** ## Understanding categories Categories automatically classify tickets based on the criteria you define. Each category includes: * **Name**: The category label shown on tickets * **Description**: Explains what types of tickets belong in this category * **Examples**: Sample phrases that help AI classify tickets accurately ### Categories vs tags While both help organize tickets, they serve different purposes: | Feature | Categories | Tags | | -------------- | ---------------------------------- | -------------------------------------- | | **Assignment** | Automatic via AI | Manual, AI-assisted, or workflow-based | | **Purpose** | Primary classification | Flexible labeling | | **Limit** | One per ticket | Multiple per ticket | | **Examples** | "Password Reset", "Hardware Issue" | "Urgent", "VIP", "Needs Review" | Many teams use categories for primary classification and tags for additional context like priority, status, or team assignments. *** ## Set up categories ### Create categories Go to **Settings > Workspaces > Categories**. Click **New Category** to open the creation form. Enter a clear, descriptive label like "Password Reset" or "Software Request". Explain what belongs in this category - "Requests to reset user passwords or unlock accounts". Include sample phrases that represent this category: * "I forgot my password" * "Can't log into my account" * "Need to reset my credentials" Click **Create** to save the category. ### Use templates Import pre-built category sets for common use cases. Templates provide ready-to-use categories with names, descriptions, examples, icons, and colors already configured. Go to **Settings > Workspaces > Categories**. Click **New from template**. Browse categories organized by department (IT Support, HR, Facilities, etc.) and select multiple categories to import. Click **Create** to add them to your workspace. You can select up to 100 categories at once when importing from templates. After import, customize any category to match your team's specific needs. ### Edit categories You can modify category details at any time: * Name and description * Example phrases * Default category status Changes to examples and descriptions will affect future AI classifications but won't reclassify existing tickets. ### Default category Every workspace requires exactly one default category. You can manually assign the default category to tickets that don't fit into other categories. The first category you create automatically becomes the default category. You can change this later by editing another category and marking it as default. To change the default category: Edit the category you want to make default. Toggle **Set as default** to enabled. Save changes. The previous default category is automatically unset. ### Delete categories Go to **Settings > Workspaces > Categories**. Select the category to delete. Click **Delete**. * You cannot delete the default category * Tickets assigned to deleted categories will show "No category" until manually updated *** ## How classification works When a ticket is created, Ravenna automatically analyzes its content and assigns the most appropriate category by examining the ticket's title, description, and initial messages against your category descriptions and example phrases. ```mermaid theme={"system"} graph TD A["Ticket Created"] --> B["Analyze Content"] B --> C{"Match Found?"} C -->|Yes| D["Assign Best
Matching Category"] C -->|No| E["Leave Unclassified"] D --> F["Classification Complete"] E --> F ``` If AI can't find a good match, the ticket remains unclassified (no category assigned). You can manually assign a category anytime, including your default category for tickets that don't fit elsewhere. Auto-classification only runs when tickets are first created and don't already have a category assigned. This means: * Categories you manually set during ticket creation won't be overwritten * Categories assigned by workflows stay as you configured them * You can always manually change a category without AI changing it back *** ## Use categories ### View and assign categories Categories appear on tickets in multiple places: * **Ticket detail**: Category badge displayed in ticket attributes * **Ticket table**: Category shown as a customizable column in table view * **Ticket list**: Category shown in list view * **Analytics**: Category-based reporting and grouping While categories are typically assigned automatically, you can manually set or change a ticket's category: Open the ticket you want to categorize. Click the category field in ticket attributes. Select a different category from the dropdown. Manual assignments take precedence over auto-classification. The AI will not overwrite categories you've manually set. ### Filter and analyze Use categories to filter your ticket list and focus on specific topics. Category filters work in: * Ticket list views * Saved filters and views * Analytics dashboards Categories enable reporting capabilities: * Ticket volume by category * Resolution time by topic * Category trends over time * Team workload by category type ### With agent rules Categories can be referenced in agent rules to create conditional logic and automation based on ticket topics. Use `@` mentions to reference categories in agent rule instructions. For example: When a ticket with category @Password Reset is created, set the priority to URGENT When you mention a category in a rule, the agent gains access to that category's details (name, description, examples) as reference context. This helps the agent understand ticket topics and apply appropriate logic. Common patterns: * Auto-escalate specific categories: "When @Security Issue tickets are created, assign to Security Team" * Set priorities by topic: "For @Hardware Failure tickets, set priority to HIGH" * Conditional workflows: "If category is @Software Request, run approval workflow" ### With workflows Categories can trigger workflows when assigned or changed on tickets. Learn more about [Category Assigned workflow trigger](/documentation/automate/workflows/triggers-actions) Common workflow patterns: * Auto-assign tickets to specialized teams based on category * Set priority automatically for specific category types * Send notifications when critical categories are assigned * Route tickets through approval workflows by category *** ## Best practices Good category descriptions help AI classify tickets accurately: * **Be specific**: "Password reset requests for user accounts" * **Include context**: "Hardware issues including laptops, monitors, and peripherals" * **Use clear language**: "Software installation and license requests" * **Avoid overlap**: Keep categories distinct from each other Example phrases train the AI. Include 5-10 diverse examples using natural language that matches how your users actually describe issues: * ✅ "I can't access my email" * ✅ "Locked out of my account" * ✅ "Need to reset my password" * ❌ "password" (too generic) * ❌ "authentication failure" (too technical) * **Start small**: Begin with 5-10 core categories. You can always add more later. * **Avoid overlap**: Keep categories distinct. "Password Issues" and "Login Problems" overlap - combine them instead. * **Review regularly**: Check tickets in your default category to spot patterns that need their own category. * **Test and adjust**: Monitor classification accuracy in the first week and refine examples as needed. Many teams use both: categories for the primary topic (Password Reset, Hardware Issue) and tags for additional context like team ownership or urgency (IT Team, High Priority). *** ## Common questions No, each ticket can only have one category assigned. This ensures clear primary classification. Use tags if you need additional labels. The ticket remains unclassified (no category assigned). You can manually assign a category anytime, including your default category for tickets that don't fit elsewhere. No, classification only runs when tickets are created. To update existing tickets, manually change their categories or use bulk actions. Add more diverse example phrases that match how your users actually describe issues. Check tickets in your default category to spot misclassifications and adjust examples accordingly. Not directly, but you can use category templates which provide pre-configured categories. If you've customized categories in one workspace, you'll need to recreate them manually in others. Yes, tickets created from integrations (Linear, Jira, Notion) are classified the same way as tickets from other sources. The category exists only in Ravenna - it doesn't sync back to the integration. ## Mental model A category is a single-label classification assigned to a ticket. Every ticket can have zero or one category. Categories are workspace-scoped and AI-assigned at ticket creation time. Categories vs. tags: | | Categories | Tags | | -------------- | ---------------------------------------------------------------- | --------------------------------------- | | **Per ticket** | Zero or one | Zero or many | | **Assignment** | Automatic (AI at creation) | Manual, AI-assisted, or workflow-based | | **Purpose** | Primary topic classification | Flexible supplementary labeling | | **Mutability** | Can be changed manually or by workflow, but AI will not reassign | Can be added/removed freely at any time | Use categories for the primary "what is this request about" classification. Use tags for supplementary metadata like urgency, team ownership, or process state. *** ## Classification behavior Auto-classification runs once: when a ticket is created and has no category already set. The system analyzes the ticket's title, description, and initial messages against all category descriptions and example phrases in the workspace. **What prevents auto-classification:** * A category was manually set during ticket creation. * A workflow assigned a category before the classifier ran. * The classifier found no confident match (ticket remains unclassified, not assigned to default). **What does not trigger reclassification:** * Editing a ticket's title or description after creation. * Updating category descriptions or examples (affects future tickets only). * Adding messages to an existing ticket. Manual category changes always take precedence. The AI will never overwrite a manually assigned category. *** ## Writing effective categories Classification accuracy depends on the quality of descriptions and example phrases. **Descriptions** should define the scope clearly and specifically. "Requests to reset user passwords or unlock accounts" is better than "Password stuff." **Example phrases** should mirror how users actually describe their issues, not how support agents would categorize them: * Good: "I can't log into my email", "My account is locked out", "Need to reset my credentials" * Bad: "password", "authentication failure", "credential management" Include 5-10 diverse examples per category. Cover different phrasings of the same intent. **Avoiding overlap:** If two categories could reasonably match the same ticket, they overlap. "Password Issues" and "Login Problems" overlap significantly. Combine them into one category or make the descriptions mutually exclusive (e.g., "Password resets for self-service accounts" vs. "SSO and authentication errors with corporate login"). Start with 5-10 core categories. Review tickets landing in the default category to identify patterns that need their own category. Refine examples based on misclassifications. *** ## Integration with agent rules and workflows **Agent rules:** Reference categories in rules using `@Category Name`. When a category is mentioned in a rule, the agent gains access to that category's details as context. Common rule patterns: * Priority escalation: "When a ticket is categorized as @Security Issue, set priority to urgent and assign to the security team." * Workflow triggers: "If category is @Software Request, trigger @Software Approval Workflow." * Conditional responses: "For @Password Reset tickets, guide the user through self-service reset before escalating." **Workflows:** The "Category Assigned" trigger fires when a category is assigned to a ticket (either by AI or manually). Use this to build automation based on ticket topic, such as routing to specialized teams, setting priority, or notifying specific channels. *** ## Constraints and gotchas * One category per ticket. For multiple labels, use tags. * Every workspace requires exactly one default category. The default category cannot be deleted. * Auto-classification only runs at ticket creation. There is no bulk reclassification. Updating category descriptions or examples does not affect existing tickets. * If the classifier has no confident match, the ticket remains unclassified (no category), not assigned to the default category. The default is only assigned manually. * Deleting a category removes it from all tickets that had it. Those tickets show "No category" until manually updated. * Categories are workspace-scoped. There is no way to import categories from one workspace to another directly. Use templates for common starting sets. * Categories do not sync to external integrations. A category assigned in Ravenna does not appear in Jira, Linear, or other connected systems. * Template import supports up to 100 categories at once.