> ## 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.

# Optimizing AI context for SaaS and sales operations

> A hands-on guide to configuring AI context at the model, topic, and view levels using a SaaS and Salesforce example.

export const categoryIcons = {
  'administration': 'lock',
  'api': 'terminal',
  'connections': 'database',
  'dashboards': 'table-columns',
  'embed': 'code',
  'errors': 'exclamation',
  'modeling': 'wrench',
  'patterns': 'plus',
  'schedules & alerts': 'envelope',
  'visualizations': 'chart-column',
  'workbooks': 'book'
};

export const GuideSidebar = ({category, relatedLinks, updatedDate}) => {
  const [progress, setProgress] = React.useState(0);
  React.useEffect(() => {
    const sidebar = document.querySelector('.guide-sidebar');
    if (!sidebar) return;
    let container = sidebar.parentElement;
    while (container && !container.querySelector('.guide-header')) {
      container = container.parentElement;
    }
    if (container && !container.classList.contains('guide-page-layout')) {
      container.classList.add('guide-page-layout');
    }
  }, []);
  React.useEffect(() => {
    const handleScroll = () => {
      const scrollTop = window.scrollY;
      const docHeight = document.documentElement.scrollHeight - window.innerHeight;
      const scrollPercent = docHeight > 0 ? scrollTop / docHeight * 100 : 0;
      setProgress(Math.min(100, Math.max(0, scrollPercent)));
    };
    window.addEventListener('scroll', handleScroll, {
      passive: true
    });
    handleScroll();
    return () => window.removeEventListener('scroll', handleScroll);
  }, []);
  const icon = category ? categoryIcons[category.toLowerCase()] || 'book' : 'book';
  return <aside className="guide-sidebar">
      <div className="guide-sidebar-content">
        <a href="/guides" className="guide-sidebar-back">
          <Icon icon="arrow-left" iconType="solid" size={14} />
          <span>All guides</span>
        </a>

        <div className="guide-sidebar-section">
          <div className="guide-sidebar-label">Progress</div>
          <div className="guide-sidebar-progress">
            <div className="guide-mascot">
              <svg viewBox="0 0 450 450" width="48" height="48">
                <defs>
                  <clipPath id="progressClip">
                    <rect x="0" y={450 - progress * 4.5} width="450" height={progress * 4.5} />
                  </clipPath>
                  <linearGradient id="blobbyGradient" x1="55.9753" y1="0" x2="492.197" y2="169.724" gradientUnits="userSpaceOnUse">
                    <stop stopColor="#BCA2F3" />
                    <stop offset="0.572917" stopColor="#FF7AA2" />
                    <stop offset="1" stopColor="#F3D4A2" />
                  </linearGradient>
                </defs>

                {}
                <circle cx="223.901" cy="223.901" r="213.901" transform="matrix(-0.999988 -0.0049013 0.00491945 -0.999988 447.797 449.992)" fill="#FAFAFA" stroke="#480B38" strokeWidth="20" />

                {}
                <circle cx="223.901" cy="223.901" r="213.901" transform="matrix(-0.999988 -0.0049013 0.00491945 -0.999988 447.797 449.992)" fill="url(#blobbyGradient)" stroke="#480B38" strokeWidth="20" clipPath="url(#progressClip)" />

                {}
                <path d="M310.41 195.084C310.41 200.052 301.362 212.472 284.328 212.472C266.585 212.472 258.246 201.294 258.246 195.912" stroke="#480B38" strokeWidth="17.3883" strokeMiterlimit="1.33344" strokeLinecap="round" />
                <circle cx="21.168" cy="21.168" r="21.168" transform="matrix(-1 0 0 1 388.658 169.001)" fill="#480B38" />
                <circle cx="21.168" cy="21.168" r="21.168" transform="matrix(-1 0 0 1 223.467 169.001)" fill="#480B38" />
              </svg>
            </div>
            <span className="guide-sidebar-progress-text">{Math.round(progress)}%</span>
          </div>
        </div>

        {category && <div className="guide-sidebar-section">
            <div className="guide-sidebar-label">Category</div>
            <div className="guide-sidebar-category">
              <Icon icon={icon} iconType="solid" size={14} />
              <span>{category}</span>
            </div>
          </div>}

        {updatedDate && <div className="guide-sidebar-section">
            <div className="guide-sidebar-label">Last updated</div>
            <div className="guide-sidebar-date">{updatedDate}</div>
          </div>}

        {relatedLinks && relatedLinks.length > 0 && <div className="guide-sidebar-section">
            <div className="guide-sidebar-label">Related</div>
            <ul className="guide-sidebar-links">
              {relatedLinks.map((link, index) => <li key={index}>
                  <a href={link.href}>{link.title}</a>
                </li>)}
            </ul>
          </div>}
      </div>
    </aside>;
};

export const GuideTitle = ({title}) => {
  return <div className="guide-header">
      <h1 className="guide-title">{title}</h1>
    </div>;
};

<GuideSidebar
  categoryIcons={categoryIcons}
  category="patterns"
  updatedDate="March 2026"
  relatedLinks={[
{ title: "Model-level ai_context", href: "/modeling/models/ai-context" },
{ title: "Topic-level ai_context", href: "/modeling/topics/parameters/ai-context" },
{ title: "View-level ai_context", href: "/modeling/views/parameters/ai-context" },
{ title: "Optimize models for Omni AI", href: "/modeling/develop/ai-optimization" }
]}
/>

<GuideTitle title="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

<Steps>
  <Step title="Setting universal rules in the model file" titleSize="h2">
    The [model file](/modeling/models) 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.

    ```yaml title="Model-level context" wrap theme={null}
    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`.
    ```
  </Step>

  <Step title="Setting dataset logic in the topic" titleSize="h2">
    [Topic-level](/modeling/topics) 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.

    ```yaml title="Topic-level context" wrap expandable theme={null}
    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
    ```

    <Tip>
      **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.
    </Tip>
  </Step>

  <Step title="Adding precision at the view level" titleSize="h2">
    [View-level](/modeling/views) context ensures the AI knows the difference between a **lead source** and a **forecast category**, and provides synonyms to catch natural language variations.

    ```yaml title="View-level context" wrap theme={null}
    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.
    ```
  </Step>
</Steps>

## Iterating on AI context

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

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

<Tip>
  When you correct the AI in a chat session (e.g., `"Actually, always use Fiscal Year"`), click the <Icon icon="brain" iconType="regular" /> (brain) icon to have the AI [learn from the conversation](/ai/learn-from-conversation) and propose model changes to incorporate the correction.
</Tip>

## Next steps

* [Model-level ai\_context](/modeling/models/ai-context) — Reference for model-level `ai_context` syntax
* [Topic-level ai\_context](/modeling/topics/parameters/ai-context) — Reference for topic-level `ai_context` syntax
* [View-level ai\_context](/modeling/views/parameters/ai-context) — Reference for view-level `ai_context` syntax
* [Optimize models for Omni AI](/modeling/develop/ai-optimization) — Broader guidance on optimizing your model for AI