Optimizing AI context for SaaS and sales operations

This guide provides a hands-on reference for building out AI context within a SaaS-focused Omni instance, specifically centered on Salesforce Opportunities. By following this example, you can see how to move beyond basic schema discovery to a high-precision setup where the AI understands complex sales logic and terminology like “pipeline,” “IQCC,” and “weighted forecasts.”

Why AI context matters

While Omni understands your schema, ai_context lets you encode sales-specific knowledge — like what ‘pipeline’ means or how to calculate IQCC — so the AI can answer questions accurately. For example, sales context could look like:

Defining terminology: Does “pipeline” mean every open deal, or only “new business” in specific stages?
Handling personas: Automatically filtering by a manager’s specific region or segment when they ask about my team using user attributes.
Calculating velocity: Defining terms like IQCC (In-Quarter Create & Close) so the AI can track speed-to-revenue without manual intervention.

The AI context hierarchy

To help the AI return accurate, business-aligned answers, you can add context to the underlying data model. For this example, think of the context in three layers: model, topic, and view. Omni applies this logic from the top down - starting at the model level - allowing you to set universal rules that get more specific as you move toward individual fields.

Layer	Purpose	Example
Model	Universal truths. Global business logic and formatting rules that apply to all queries in the model.	”All revenue is ARR; our fiscal year begins Feb 1st.”
Topic	The persona. The topic level defines more specific details scoped to your pre-defined datasets.	”You are a Sales Ops Analyst; ‘Pipeline’ excludes ‘Renewals’ by default.”
View/Field	Field precision. Specific definitions, synonyms, and allowed values for columns.	”’Stage’ is a synonym for `stage_name`. ‘Won’ means `is_won = true`.”

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 SaaS or sales-related data

Setting universal rules in the model file

The model file defines your universal rules that will exist across the entire model. These rules act as permanent guardrails, ensuring the AI adheres to your core business standards regardless of which topic in the model a user is exploring.

Model-level context

ai_context: |-
  ## Global Business Logic
  - All currency values represent Annual Recurring Revenue (ARR) unless otherwise specified.
  - Our Fiscal Year follows a standard calendar (Jan-Dec), but "Fiscal Quarter" should be used for all board reporting.
  - When users say "My Team" or "My Territory," always reference the `user_attributes` for Segment and Region.

  ## Data Handling & Formatting
  - Always hide internal Salesforce 18-digit IDs from the final visualization unless troubleshooting is requested.
  - Prefer 'Close Date' for any historical revenue analysis and 'Created Date' for pipeline generation analysis.

  ## SaaS Definitions
  - "Net New" refers specifically to 'New Business' + 'Expansion' - 'Churn'.
  - A "Logo" refers to a unique Account. When asked for "Logo Count," use a distinct count on `account_id`.

Setting dataset logic in the topic

Topic-level context defines more specific details scoped to your pre-defined datasets. This tells the AI how to navigate stages, deal types, and user permissions for Salesforce data.

Topic-level context

base_view: omni_dbt_saas__opportunities
group_label: Sales & Revenue
display_order: 5
description: |
  Sales pipeline and revenue data from Salesforce. This topic enables comprehensive sales analysis including pipeline management, revenue forecasting, sales performance tracking, win/loss analysis, and sales cycle analysis.

ai_context: |-
  You are an expert sales data analyst.

  When someone asks about their team or how their team is doing or their pipeline or says something like "my team" always filter account.segment = {{ omni_attributes.segment }} and account.region = {{ omni_attributes.region }}

  ## Opportunity Definitions:
  - "Pipeline" means open new opportunities (status = Open Pipeline, type = New Business).
  - "Lost deals": filter on stage_name = Closed Lost and status = Closed.
  - "Won deals": filter on stage_name = Closed Won and status = Closed.
  - "Active trials": filter on stage_name = [Trial, Trial Positive].
  - "IQCC" (In-Quarter Create Close): Type = New Business opportunities that were closed won in the same quarter they were created.

  ## Sales Analysis Logic:
  - Revenue/Sales: Always use omni_dbt_saas__opportunity.amount_sum.
  - Sales Reps: Use the name omni_dbt_saas__user.name. Never return an ID.
  - If asked about risks, show competitors, days since last stage change, and loss_reason.
  - Use close_date for revenue timing and sales cycle analysis.

sample_queries:
  Active Trials:
    query:
      fields:
        [
          "omni_dbt_saas__opportunities.close_date[date]",
          omni_dbt_saas__opportunities.name,
          omni_dbt_saas__user.name,
          omni_dbt_saas__opportunities.stage_name,
          omni_dbt_saas__opportunities.amount_sum
        ]
      base_view: omni_dbt_saas__opportunities
      filters:
        omni_dbt_saas__opportunities.type:
          is: New Business
        omni_dbt_saas__opportunities.stage_name:
          is: [ Trial, Trial Positive, Negotiate ]
    description: Show a list of all active trials
    prompt: Show me all active trials
    ai_context: "This is a list of all active trials."

  Deals Won this Quarter:
    query:
      fields:
        [
          omni_dbt_saas__opportunities.name,
          omni_dbt_saas__user.name,
          "omni_dbt_saas__opportunities.close_date[date]",
          omni_dbt_saas__opportunities.competitor,
          omni_dbt_saas__opportunities.stage_name,
          omni_dbt_saas__opportunities.amount_sum
        ]
      base_view: omni_dbt_saas__opportunities
      filters:
        omni_dbt_saas__opportunities.type:
          is: [ New Business, Expansion ]
        omni_dbt_saas__opportunities.close_date:
          time_for_duration: [ 1 quarters ago, 1 quarters ]
        omni_dbt_saas__opportunities.stage_name:
          is: Closed Won
    description: List of deals won in this quarter
    ai_context: All the deals that have closed this quarter.

  Won iARR:
    query:
      fields: [ omni_dbt_saas__opportunities.amount_sum ]
      base_view: omni_dbt_saas__opportunities
      filters:
        omni_dbt_saas__opportunities.type:
          is: [ New Business, Expansion ]
        omni_dbt_saas__opportunities.is_won:
          is: true
    description: how much iARR we've won across all time
    prompt: What is our total won iARR?
    ai_context: use this when asked about our total iarr

Include sample queries. By including all three sample_queries above, you ensure the AI has explicit examples of how to handle trials, quarterly wins, and cumulative revenue.

Adding precision at the view level

View-level context ensures the AI knows the difference between a lead source and a forecast category, and provides synonyms to catch natural language variations.

View-level context

view: omni_dbt_saas__opportunities
fields:
  stage_name:
    sql: '"STAGE_NAME"'
    all_values: [Closed Lost, Closed Won, Qualified, Trial Positive, Pre-Qualified, Trial, Negotiate]
    synonyms: [Stage, Pipeline Stage, Opportunity gate]
    ai_context: |
      Early stage deals are prequalified and qualified. Late stage deals are trial positive and negotiate.

  amount:
    sql: '"AMOUNT"'
    synonyms: [deal_amount, contract_value, ARR]
    ai_context: |
      Use this field for revenue forecasting. Use amount_sum measure for aggregated totals.

  type:
    sql: '"TYPE"'
    all_values: [New Business, Expansion, Renewal]
    ai_context: |
      Distinguish between new customer acquisition (New Business), expansion/upsell, and renewals.

  lead_source:
    sql: '"LEAD_SOURCE"'
    all_values: [Referral, Inbound, Outbound, Organic]
    ai_context: |
      The channel the opportunity was generated from. Use this if asked where an opportunity came from.

Iterating on AI context

Improving AI quality is an iterative process. Use this workflow to refine your context:

Monitor: Use the AI usage dashboard in the Analytics section to find queries with negative (👎) feedback.
Identify: Did the AI fail due to a missing synonym or lack of business logic?
Tune: Update the YAML at the appropriate level (Model, Topic, or View).
Verify: Re-run the prompt in the Omni Agent to ensure the fix worked.

When you correct the AI in a chat session (e.g., "Actually, always use Fiscal Year"), click the (brain) icon to have the AI learn from the conversation and propose model changes to incorporate the correction.

Next steps

Model-level ai_context — Reference for model-level ai_context syntax
Topic-level ai_context — Reference for topic-level ai_context syntax
View-level ai_context — Reference for view-level ai_context syntax
Optimize models for Omni AI — Broader guidance on optimizing your model for AI