Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omni.co/llms.txt

Use this file to discover all available pages before exploring further.

This guide provides a hands-on reference for building out AI context within an Omni instance focused on customer support and Zendesk tickets. By following this example, you can see how to move beyond basic schema discovery to a high-precision setup where the AI understands complex support logic like SLA targets, ticket lifecycles, and account risk.

Why AI context matters

In support operations, data is often defined by the “state” of a ticket or the urgency of a customer. While Omni understands your tables, ai_context codifies the operational knowledge required for the AI to act as a seasoned support lead. For example, support context could look like:
  • Defining “active issues”: Does “active” mean only ‘new’ tickets, or does it include those ‘pending’ a customer response?
  • SLA logic: Mapping priority levels (urgent vs. normal) to specific response time expectations so the AI can identify breaches.
  • Sentiment and risk: Helping the AI understand that a high volume of tickets for a single account_id isn’t just “work” - it’s a signal of potential churn or a “customer at risk.”

The AI context hierarchy

To build a high-precision instance, think of your context in three layers. Omni applies this logic from the top down, ensuring universal support standards are respected before field-level definitions.
LayerPurposeExample
ModelUniversal truths. The model file defines your universal rules that will exist across your entire Omni model.”All time durations are in hours; our support week is 24/7.”
TopicThe persona. The topic level defines more specific details scoped to your pre-defined datasets.”You are a support ops analyst; ‘Resolved’ means Solved or Closed.”
View/FieldField precision. Specific definitions, synonyms, and allowed values for columns.”’Urgency’ is a synonym for priority. ‘Bug’ is a specific type of ticket.”

Requirements

To implement this example in your own Omni instance, you’ll need:
  • Familiarity with Omni’s modeling layer
  • Permissions in Omni that allow you to edit a shared model
  • A connected data source that contains support-related data
1

Set universal rules in the model file

The model file defines your universal rules that will exist across your entire Omni model. These rules ensure the AI adheres to your core support standards regardless of which topic a user is exploring.
Context that applies to the entire model
ai_context: |-
  ## Global Business Logic
  - All "Time to Resolve" or "Response Time" metrics should be displayed in decimal hours unless minutes are specifically requested.
  - Our support organization operates on a 24/7 basis; do not exclude weekends from duration calculations unless "Business Hours" are specified.
  - When users ask about "At-Risk Customers," prioritize those with more than 5 'Open' tickets or a CSAT score below 3.

  ## Data Handling & Formatting
  - Always hide internal Zendesk system IDs (like user_id) in the final visualization; use Name or Email instead.
  - For any customer satisfaction (CSAT) analysis, the scale is 1-5, where 5 is the best.
  ## Support Definitions
  - "Technical Debt" refers to tickets where the type is 'bug' or 'incident'.
  - "Self-Service" refers to tickets sourced from the 'web' channel that were closed with a single interaction.
2

Set dataset logic in the topic

The topic level defines more specific details scoped to your pre-defined datasets. This tells the AI how to navigate ticket statuses, support channels, and engineering links, like those to a Jira instance.
Topic-level context
base_view: omni_dbt_saas__zendesk_tickets
label: Support Tickets
group_label: Product Analytics
description: |
  Customer support tickets from Zendesk. Use this to track team performance,
  identify product issues, and analyze support channel effectiveness.

ai_context: |-
  This topic focuses on customer support and service operations.

  ## Support Lifecycle definitions:
  - "Open tickets" or "Active issues": filter on status = [new, open, pending].
  - "Resolved tickets": filter on status = [solved, closed].
  - "High priority": filter on priority = [urgent, high].
  - "Feature requests": filter on type = feature_request.
  - "Technical issues": filter on type = problem or bug.

  ## Analysis Logic:
  - Customer Satisfaction (CSAT): Use the satisfaction_score field.
  - Response Time: Use first_response_time_hours.
  - Resolution Time: Use resolution_time_hours.
  - Account Risk: Use account_id to identify customers with high ticket volumes.
  - Engineering Link: Use jira_issue_id to connect support tickets to development work.

  ## Formatting:
  - Always make dimensions (labels/values) the first columns in the table, and measures (counts/sums) after.
3

Add precision at the view level

The view level ensures the AI knows the operational significance of different fields, such as how priority maps to SLAs or how channel reflects customer preference.
View-level context
view: omni_dbt_saas__zendesk_tickets
fields:
  status:
    sql: '"STATUS"'
    all_values: [new, open, pending, solved, closed]
    synonyms: [ticket_status, workflow_status]
    ai_context: |
      New/Open tickets require immediate action. Pending tickets are waiting on a response.
      Solved/Closed represent completed work.

  priority:
    sql: '"PRIORITY"'
    all_values: [urgent, high, normal, low]
    synonyms: [urgency, ticket_priority]
    ai_context: |
      Priority maps to SLA targets: Urgent (<1hr), High (<4hr), Normal (<24hr), Low (<72hr).
      Higher priorities indicate greater business risk.

  type:
    sql: '"TYPE"'
    all_values: [problem, question, task, feature_request, incident, bug]
    ai_context: |
      'Problem' or 'Bug' require engineering attention. 'Feature_request' informs the roadmap.
      'Question' suggests a need for better documentation.

  channel:
    sql: '"CHANNEL"'
    all_values: [web, email, phone, chat, api]
    ai_context: |
      'Phone' is high-cost/urgent. 'Chat' is high-satisfaction/quick.
      'API' represents automated integrations.

The feedback loop

Support trends change with every product release. Use this workflow to keep your AI accurate:
  1. Monitor: Use the AI usage dashboard in the Analytics section to see if users are struggling to find bug reports versus feature requests.
  2. Identify: Did the AI fail because a specific product area wasn’t defined in the context?
  3. Tune: Update the YAML (e.g., add a synonym for “Product Issue” pointing to type = bug).
  4. Verify: Re-run the prompt in the Omni Agent to confirm the AI now maps the term correctly.
SLA breach tip: Use ai_context in your resolution_time_hours field to define a breach.For example: "If priority is urgent and resolution time > 1, this is an SLA breach."This allows users to ask "How many SLA breaches did we have yesterday?"

Next steps