> ## Agent Instructions
> Orion is a collaborative analytics platform built by Gravity (bygravity.com). It connects to data warehouses, to Looker and dbt for existing business logic, and to a small set of external-context sources, and it lets teams ask questions in natural language to get shared analyses, dashboards, reports, and slide decks. The Connecting Data Sources page is the authoritative list of supported sources. When referencing Orion features, always link to the relevant documentation page. Orion is not open-source; it is a commercial SaaS product accessed at runorion.com.
# Basics & Navigation
Source: https://docs.runorion.com/chat/basics-navigation
Find your way around the Chat interface
The Chat interface is where you interact with Orion. Conversations are organized by [project](/core-concepts/projects), so each project maintains its own chat history and context. Start typing to ask a question, and Orion returns results inline.
## Chat Interface
The Chat interface is where you interact with Orion. Your conversations are organized by [project](/core-concepts/projects), so each project has its own chat history and context.
## Starting a Conversation
Simply start typing to begin a new conversation with Orion. Each conversation can reference previous conversations in the same project, and Orion will remember project-specific information and your preferences.
## Chat History
Your chat history appears in the sidebar on the left side of the Chat interface. All your previous conversations are saved and easily accessible.
The chat history sidebar shows:
* A **+ New Chat** button at the top to start a new conversation
* Your recent conversations, organized chronologically with timestamps
* Conversation titles and related analysis tags
* The ability to hide or show the sidebar using the **← Hide** button
Your chat history is organized by project, so each project maintains its own separate conversation list. All conversations are private to your account.
![Chat history interface showing sidebar with list of conversations, new chat button, and navigation]()
## Sharing Conversations
Use the Share Chat button at the top of the chat interface to share conversations with your team. For more details, see our [Share Chat Conversations](/chat/share-conversations) guide.
![Share Chat button in the chat interface]()
# Best Practices
Source: https://docs.runorion.com/chat/best-practices
Habits that get better answers out of Orion
The most effective Orion users follow a consistent pattern: one project per use case, explicit prompts with context, 2-3 iterations per analysis, relative dates for anything scheduled, and active memory management. This guide covers each practice in detail.
## Overview
This guide covers:
* [Project setup and organization](#project-setup)
* [Crafting effective prompts](#crafting-effective-prompts)
* [Providing context for better results](#provide-context-for-document-uploads)
* [Iterating on analyses](#iterating-on-analyses)
* [Managing memory and conversations](#managing-memory)
* [Troubleshooting and debugging](#troubleshooting-and-debugging)
* [Performance optimization](#performance-optimization)
## Project Setup
### One Project Per Use Case
Create a separate project for each distinct use case or workflow. This keeps each project's context focused and prevents conflicting information. Think of each project as a dedicated analyst for that specific team or use case.
### Keep Context Consistent
Keep the context you give Orion clear and consistent. Conflicting information confuses Orion, and it can live in multiple places:
* [User profile settings](/profile-settings/profile-management)
* [Project settings](/core-concepts/projects)
* [Knowledge Base pages](/core-concepts/knowledge-base)
* [Company information page](/configuration/company-information)
* [Memory](/chat/memory)
* Exploratory conversations
Review all these areas to ensure consistency.
### Memory Configuration
* **Private Project** - each project should have its own memory context
### Use Relative Dates
When creating a re-runnable or scheduled analysis, use relative date instructions instead of absolute dates. Include the word "evergreen" to ensure all instructions, queries, and generated code use relative dates that will work when rerun.
## Crafting Effective Prompts
### Be Explicit and Clear
Be explicit in your requests. Ambiguous prompts lead to assumptions, which can be incorrect, especially when working with a new project. Spell out exactly what you want rather than assuming Orion will infer your intent.
### Answer Clarifying Questions Consistently
When Orion asks clarifying questions, answer them in a consistent format (e.g., numbered points). If you want this format used every time, tell Orion to "remember this for next time."
### Provide Context for Document Uploads
When uploading documents or spreadsheets, provide supplemental context:
* What columns the document contains
* Where the data came from
* What the data represents
* Any relevant background information
For example: "I uploaded a spreadsheet. It has these following columns and it came from this source. It's a merge history from GitHub and contains details about team members."
### Explore Data First
Get Orion familiar with your data before diving in. Start by asking "tell me a little bit about the data that's available." This quick step helps Orion understand your data structure and confirms it has the access it needs, setting you up for more effective analysis down the road.
### Figure Out Your Assumptions
Identify the assumptions you make as a human analyst and explicitly state them to Orion. Don't assume Orion has background knowledge - provide that extra context upfront, even if it takes a few extra minutes.
Here are some questions to help surface assumptions in data analysis work:
**About the data itself**
* What do you believe is true about how this data was collected?
* What are you taking for granted about the completeness of this dataset?
* What do you assume the values in each field actually represent?
**About the problem and context**
* What do you believe caused the patterns you expect to find?
* What are you assuming about how this data relates to the real-world phenomenon you're studying?
* What do you take as given about the time period this data covers?
**About the analysis approach**
* What must be true about the data for your chosen method to be valid?
* What are you assuming about the relationships between variables?
* What do you believe about how representative this sample is of the broader population you care about?
**About stakeholders and use**
* What are you assuming about what the audience already knows or believes?
* What do you take for granted about how the results will be used?
* What do you assume the decision-maker actually needs from this analysis?
**About yourself**
* What prior beliefs might be shaping which patterns you notice or ignore?
* What are you assuming you understand correctly about the domain?
* Where might your expertise (or lack of it) create blind spots?
## Iterating on Analyses
### Expect Multiple Iterations
**Don't expect the first analysis to be perfect.** Plan for 2-3 iterations before you get a result you're happy with:
1. **First iteration**: Usually gets you to 80-90% - review and provide feedback
2. **Second iteration**: Refine based on feedback, adjust focus and formatting
3. **Third iteration**: This is typically the one you can share or re-use in the future
Think of Orion like a colleague who needs feedback to improve, not a superhuman that gets everything right immediately.
### Two Modes of Work
There are two distinct phases when working with Orion:
1. **Setup phase**: Creating projects and getting initial analyses running
2. **Refinement phase**: Editing insights, adjusting formatting, and fine-tuning outputs
The refinement phase typically takes about 10 minutes to go from 90% to 100% ready.
### Formatting and Editing
After an analysis runs, use chat to:
* Simplify content
* Change formatting
* Adjust specific sections
* Remove or add emojis (you can say "no emojis" if you don't want them)
* Specify chart preferences
You can also configure these preferences in project settings to influence default outputs.
## Managing Memory
### Explicitly Request Memory
**You must explicitly tell Orion to remember things.** Say "remember this" when you want something saved to memory. Orion won't automatically form memories from conversations to avoid saving hallucinations.
Orion may occasionally ask if something should be remembered, but it's more reliable to explicitly request it.
### When to Remember
Remember important information that:
* Applies to the project long-term
* Should influence future analyses
* Represents preferences or requirements
* Helps avoid repeating mistakes
## Organizing Conversations
### When to Start a New Chat
* **Start a new chat** when you want to explore something completely different
* **Use the same chat** for slight variations (e.g., "do this for November instead of October")
### Don't Delete Chats
Keep your chat history. Don't delete chats - let them accumulate. They serve as a record of your work and can be useful for reference.
### Sharing Chats
Use the share feature to share your chats and notebooks with others. Anyone you share a chat with can pick up where you left off in the conversation.
## Troubleshooting and Debugging
### Handling Skepticism
If Orion doesn't get something right the first time, don't lose confidence. It may need:
* More context
* Missing data
* Better instructions
Use the troubleshooting features to help Orion improve rather than assuming it can't handle the task.
## Performance Optimization
### Manage Data Volumes Carefully
**Start small, then expand.** If you eventually want to analyze years of data, don't start there:
1. Begin with a limited date range (e.g., "today and this day last year")
2. Get it working correctly with the smaller dataset
3. Once it's working, expand the date ranges
Starting with billions of rows and years of data is asking for trouble - it's slower, more expensive, and harder to debug.
### Check Data Availability
Before running full analyses, use chat to check data availability. Ask Orion to explore what data is available and identify any gaps or issues upfront rather than waiting for the entire analysis to run.
### Use Tools in the Right Order
Orion has access to exceptional tools, but they need to be used in the right order. Power users can guide Orion to be more efficient by:
* Coaxing out data details upfront
* Identifying missing information early
* Ensuring proper tool sequencing
## Project Settings Tips
### Visualization Preferences
![Visualization preferences settings showing different chart type options]()
In project settings, you can specify:
* Chart types and formats (e.g., "three to five columns of numeric and categorical optimized for waterfall")
* Emoji preferences (you can request no emojis)
* Output formatting preferences
These settings heavily influence insight output, so configure them based on your needs.
### Automation Features
When available, leverage automation features:
* **Calendar integration**: Reference Orion in calendar event descriptions (e.g., "Orion: I will need this data for this meeting")
* **Slack integration**: Orion can remember the last 10-20 messages in channels it's been invited to
* **Scheduled analyses**: Save re-runnable analyses to refresh on a recurring schedule
## Key Takeaways
1. **[One project per use case](#one-project-per-use-case)** - keep things focused
2. **[Expect 2-3 iterations](#expect-multiple-iterations)** - the first analysis won't be perfect
3. **[Be explicit](#be-explicit-and-clear)** - spell out assumptions and requirements
4. **[Use "remember this"](#explicitly-request-memory)** - explicitly request memory formation
5. **[Start small with data](#manage-data-volumes-carefully)** - expand date ranges after it's working
6. **[Use relative dates](#use-relative-dates)** - include "evergreen" for re-runnable or scheduled analyses
7. **[Explore data first](#explore-data-first)** - understand structure before diving in
8. **[Provide context for uploads](#provide-context-for-document-uploads)** - don't assume Orion will figure it out
# File Uploads
Source: https://docs.runorion.com/chat/file-uploads
Bring your own files into an analysis
Upload files to Chat to provide context to Orion or use as data sources in analyses.
## Upload Scope
You have two options for where to upload files:
* **Chat**: Upload a file directly in any chat conversation. The file is available to Orion within that conversation only.
* **Project**: Upload a file to the project itself so it's available as context across all chats in that project.
Use chat uploads for one-off files relevant to a specific question, and project uploads for reference material you want Orion to draw on consistently.
## How to Upload a File
1. Click the **plus icon (+)** in the chat text input area
2. Select **Attach File**
3. Choose one or more files from your computer
4. The files will appear in the chat before you send your message
5. Send your message to include the files in the conversation
You can upload multiple files at once. The maximum is 5 files per message.
## Supported File Types
Orion supports the following file formats for upload:
* **PDF** (.pdf) - PDFs and documents
* **Word Documents** (.doc, .docx) - Microsoft Word files
* **Excel Spreadsheets** (.xlsx) - Excel workbooks
* **CSV Files** (.csv) - Comma-separated values
* **Text Files** (.txt) - Plain text documents
## Two Ways Files Are Used
Orion intelligently determines how to use uploaded files based on context:
### 1. Context for Chat Conversations
Use files to provide context that Orion will read and reason with:
* **Company policies or SOPs** - Help Orion understand your processes
* **Meeting transcripts** - Reference discussions and decisions
* **Research documents** - Provide background information
* **Product specifications** - Share technical details
* **Data samples** - Show examples of data structure or format
* **Analysis guidelines** - Specify how to perform calculations or analysis
When files are used for context in Chat, Orion reads the file content to
inform its responses but doesn't create a separate data source.
### 2. Data Sources in Analysis
**Excel files (.xlsx only)** can be used as data sources for Orion to query directly:
* Upload one or multiple XLSX files
* Orion treats them as queryable data sources
* Each sheet in the XLSX becomes a table that Orion can analyze
* Multiple XLSX files create multiple data sources for the analysis
When you use an XLSX file as a data source, you'll see the file appear in the **right-hand "draft analysis" pane** under the **"Data Sources"** section. This indicates the file is being treated as a queryable dataset for your analysis.
Orion automatically detects whether you're providing a file for context or as
a data source based on your request. For analyses, structure your Excel files
as clean tables with clear column headers.
## Providing Context for File Uploads
When uploading files, especially new documents that Orion hasn't seen before, provide supplemental context about the file to help Orion interpret it correctly:
* **Describe the file contents** - Explain what the file contains and its purpose
* **List column names** (for spreadsheets) - Specify what columns are included
* **Indicate the source** - Mention where the file came from (e.g., "downloaded from GitHub", "exported from our CRM")
* **Explain the context** - Share relevant details about the data (e.g., "this contains merge history for my team members")
Orion can examine the first few rows of a file and make assumptions, but providing this additional context upfront makes a substantial difference in how Orion interprets and uses the file in your analysis.
## File Upload Tips
* **File size** - Keep files reasonably sized for faster uploads (typically under 10MB)
* **Multiple files** - Upload multiple XLSX files at once for complex analyses
* **Excel structure** - Use clear column headers and avoid merged cells for best results in analyses
* **Privacy** - Only upload files with appropriate data you're comfortable sharing with Orion
Be cautious when uploading files containing sensitive information. Ensure you
have appropriate permissions to use the data.
# Memory
Source: https://docs.runorion.com/chat/memory
Teach Orion preferences that persist across conversations
Orion's memory system lets it retain your preferences, project-specific context, and data requirements across conversations. Tell Orion to "remember this" explicitly, and it will apply that knowledge to every future analysis in the project, making results faster and more accurate over time.
## Overview
* [What is memory?](#what-is-memory)
* [How is memory isolated?](#how-is-memory-isolated)
* [What can be remembered?](#what-can-be-remembered)
* [How does memory work?](#how-does-memory-work)
* [What are best practices for memory?](#what-are-best-practices-for-memory)
* [FAQs](#faqs)
## What Is Memory?
Memory allows Orion to retain important information about your preferences, project specifics, and data requirements across conversations. The more context Orion has, the better it can build insights tailored to your needs.
## Quick Start
In [Chat](/chat/basics-navigation), you can ask Orion to remember something, check what it remembers, or update and remove memories.
**Ask Orion to remember something:**
> "Remember that we always use the Q4 filter for year-end reports"
**Check what Orion remembers:**
> "What do you remember about this project?"
**Update or remove a memory:**
> "Forget that I preferred pie charts - I now want bar charts instead"
You'll see a notification when Orion saves a memory. There's no dedicated memory page, but you can ask Orion what it remembers at any time.
## How Is Memory Isolated?
Memory is isolated to each project by default. The **Private Project** toggle controls this:
* **New projects:** Below the project description in the "New Project" menu
* **Existing projects:** Settings → Details tab (bottom of page)
This toggle is **on by default**. When enabled, Orion won't access memories from other projects, keeping your data and preferences organized.
## What Can Be Remembered?
Memory captures anything that helps Orion understand your needs: project-specific filters and data structures, format and visualization preferences, calculation methods, recurring workflows, and quality standards.
**Examples:**
* "We always run reports on the first of the month"
* "I prefer weekly summaries with three bullet points and clear action items"
* "Use the regional breakdown for all sales analyses"
If it's relevant to how you work with Orion, it's worth remembering.
## How Does Memory Work?
Orion creates memories through two paths:
**Automatic detection:** During conversations, Orion may flag important information and add it to memory. You'll see a notification when this happens.
**Explicit requests:** For critical information, tell Orion directly: "Remember that I prefer data tables over pie charts."
![Memory Saved notification]()
Be explicit for important information. Don't rely solely on automatic
detection for critical preferences.
## What Are Best Practices for Memory?
**Start early.** Set up memory when you begin a project to establish preferences from the start.
**Be specific:**
* ✅ "Remember that I prefer weekly summaries with three bullet points and clear action items"
* ❌ "Remember my preferences"
**Review periodically.** Ask Orion what it remembers and update as your needs evolve.
**Focus on patterns.** Memory is most valuable for information that applies across multiple conversations. Don't worry about one-off requests.
**Be project-aware.** Since memory is project-specific, set it up in each project where you need it.
## FAQs
**Q: Does memory transfer between projects?**
A: No. Memory is isolated to each project by default. Set up memory in each project where you want Orion to remember specific information.
**Q: How do I update or remove a memory?**
A: Tell Orion what changed: "Forget that I preferred pie charts - I now want bar charts instead."
**Q: How does memory improve my experience?**
A: Memory provides context that helps Orion build better insights. The more it understands about your preferences and requirements, the more accurate and useful its analyses become.
# Rooms
Source: https://docs.runorion.com/chat/rooms
Work with teammates and Orion in one shared chat
A room is a chat conversation with more than one person in it. Everyone in a room shares one
thread: the same history, the same analyses, and Orion's answers as they stream in. Rooms are how
a team investigates a question together instead of pasting results back and forth.
Everything on [Basics & Navigation](/chat/basics-navigation) still applies. A room is a normal
conversation that happens to have more than one participant.
## Rooms vs. Sharing a Copy
[Sharing a conversation](/chat/share-conversations) and starting a room are different things:
* **Send a copy.** The link is read only. The recipient reads the history, then continues it as
their own separate conversation. You never see what they do next.
* **Start a room.** Everyone stays in the same conversation. All participants post into it, see
each other's messages, and watch Orion work live.
Send a copy to hand work off. Start a room to do the work together.
Rooms cannot be copied. Once a conversation has more than one participant, the copy link is no
longer offered, because forking a room would hand one person a private duplicate of everyone
else's messages.
## Start a Room
The **+** sits in the **Rooms** header of the chat history sidebar.
![The Rooms header in the chat history sidebar, with the plus button outlined in red]()
Search by name or email. Each person you select moves up to the invite list. Nothing exists
yet at this point, so you can still remove anyone or cancel.
![The Start a room dialog, with two people staged on the invite list and the Create room button enabled]()
Orion creates the room and opens it for you.
The **Start a room** button on the chat home screen opens the same dialog.
## Turn an Existing Chat Into a Room
Any solo chat becomes a room the moment you add someone to it.
Go to the chat you want to work on together.
On a solo chat the control is labeled **Share**.
Search by name or email and select them.
They join this conversation, not a copy of it, and they see everything already in it from the
beginning. Once the conversation is a room, the same control is labeled **People** and shows the
participants' avatars.
Adding someone exposes the whole transcript to them, including anything discussed before they
joined. The dialog warns you before you add.
![The People dialog on an existing room, showing Add people with a search box, the In this room roster with the owner marked You and a remove control beside the other member, and the How Orion responds options]()
## Finding Your Rooms
The chat history sidebar splits into two sections, **Rooms** and **Chats**. Room rows carry a stack
of participant avatars, so you can tell at a glance who is in each one. Five rooms show by default,
and **Show all** expands the rest.
## Who Can Add and Remove People
* **The conversation owner** adds and removes participants. Orion enforces this server side, so the
controls do not appear for anyone else.
* **Any participant** can leave. Open the three-dot menu on the room's row in the sidebar and choose
**Leave room**.
* **Tenant admins** can read a room they are not in, but cannot post to it. They see a banner saying
so instead of the chat input.
Leaving does not erase history. Your earlier messages stay in the transcript, attributed to you.
## Addressing Orion
In a room, Orion does not answer every message. You address it with `@orion`.
Type `@` in the chat input and pick **Orion** from the menu, or type `@orion` directly. The mention
renders as a chip in the sent message. Clicking a suggested follow-up or a recommendation inside a
room addresses Orion for you.
Orion is the only participant you can address this way. The rest of the `@` menu references content,
such as a metric or a wiki page, not people. To get a teammate's attention, write their name as
ordinary text.
## How Orion Responds
Rooms have two response modes. Change them in the **People** dialog, under **How Orion responds**:
| Mode | What Orion does |
| ---------------------------- | --------------------------------------------------------------------- |
| **When mentioned** (default) | Replies only when you `@orion`. |
| **Listening** | Replies when a message looks meant for it, and whenever you `@orion`. |
A new room starts in **When mentioned**, including a solo chat you have just added someone to. In
either mode, `@orion` always gets a reply.
Any participant can change the mode, and the change applies to everyone in the room. Viewers are
the exception: a Viewer can change it only in a room they own.
Solo chats work differently: Orion replies to every message, and the setting is not offered.
Each change is recorded in the room's timeline, so the transcript shows a notice like
"Priya set Orion to listening" at the point it happened.
## Replying to a Specific Message
Rooms add a **Reply** action to messages. Select the reply arrow on a message, and it appears as a
quote card above the chat input. The card stays on your message after you send it, so a busy room
still reads in order.
You cannot reply to your own message, or to a message that is still streaming.
## What You See While Orion Works
* **Typing indicators.** Avatars appear above the chat input while a teammate is typing, and while
Orion is working on a turn.
* **Everyone watches the same answer.** Participants see Orion's response, including notebook cells,
as it is generated, not after it finishes.
* **Streams survive a reload.** If your connection drops or you refresh mid-answer, you rejoin the
stream in progress. Opening a room while a turn is already running catches you up on it.
## Room Activity
Rooms show light activity notices inline in the transcript:
* "You started this room"
* "Priya added Marcus"
* "Marcus left this room"
* "Priya set Orion to reply only when mentioned"
A run of similar notices collapses into one line, such as "You added Dana plus 9 others",
with the full list on hover. Inviting ten people costs one line, not ten.
## Important Notes
* **Rooms cannot be forked** - the read-only copy link is offered on solo chats only
* **Attribution comes from the server** - names and avatars are resolved from the room's participant
list, not from anything the browser sends
* **Response mode is per room** - it does not change the defaults for your other conversations
* **Leaving preserves history** - your past messages stay in the transcript after you leave
# Running Analyses
Source: https://docs.runorion.com/chat/running-analyses
Ask a question and get an analysis back
To run an analysis in Orion, open a project, type a question in plain language, and Orion writes the query, runs it against your connected data sources, and returns results (charts, tables, and code) directly in chat. Every analysis is captured as a reusable notebook you can re-run for fresh data, schedule on a recurring cadence, or turn into a report, dashboard, or slide deck.
## Quick Start
1. **Create or select a [Project](/core-concepts/projects)**: Click "New Project" or select an existing one. When creating a new project, you'll be prompted to select from the [data sources](/configuration/data-sources) your administrator has connected.
2. **Open Chat and ask your question**: Type your question in the Chat interface. Orion gets to work immediately, querying your data and returning results inline.
3. **Review and refine**: Ask follow-up questions, request edits, or adjust formatting. Your analysis stays in your chat history as a notebook you can return to and re-run any time.
## How Analysis Works
When you ask Orion to analyze something, it writes and runs code, queries your connected data sources, and returns results inline in your chat, with no waiting.
You can ask natural language questions like:
* "What were our top 10 customers by revenue last quarter?"
* "Show me a breakdown of churn by product line over the last 90 days"
* "Compare this month's signups to the same period last year"
Be specific and provide context. Clear questions and explicit guidance help
Orion understand your needs. The more context you provide upfront, the better
your results.
## What is a Notebook?
A notebook is Orion's record of an analysis: the instructions, the logic, and the code. Orion captures it automatically as the analysis runs and keeps it in your chat history, so there is no save step. Return to it any time to re-run it and get fresh results.
Notebooks are especially powerful when combined with [relative (evergreen) date ranges](/chat/best-practices#use-relative-dates). Because the analysis uses instructions like "last 30 days" rather than hardcoded dates, re-running a notebook always reflects the most current data.
## What You Can Do After an Analysis
Your analysis is automatically kept as a [notebook](#what-is-a-notebook) in your chat history, so there is no save step. From there you can:
* **Schedule it**: Set the notebook to run automatically on a daily, weekly, or custom schedule
* **Share or publish**: Share the results with teammates or publish as a dashboard
* **Pin metrics**: Pin key numbers from the analysis as metric tiles for at-a-glance tracking
* **Get a report**: Generate a formatted report from the analysis output
* **Get slides**: Turn the analysis into a presentation-ready slide deck
* **Ask follow-up questions**: Continue the conversation to dig deeper, refine results, or kick off a new related analysis
## How Orion Improves Over Time
Orion becomes a better analyst through three mechanisms:
* **[Memory](/chat/memory)**: Learns your preferences, project specifics, and data requirements
* **[Feedback Loops](/chat/best-practices#iterating-on-analyses)**: Each refinement helps Orion understand your expectations
* **[Knowledge Base](/core-concepts/knowledge-base)**: Structured business context Orion applies across every analysis
Start early with context. Enable Knowledge Base pages and use Memory from the
beginning. The more context you provide upfront, the faster Orion adapts.
## Next Steps
Tips for getting the most out of your analyses
Bring your own data into an analysis
Help Orion remember preferences and context across analyses
Organize your work and set project-level instructions
# Share Chat Conversations
Source: https://docs.runorion.com/chat/share-conversations
Hand a conversation to a teammate to continue
Share any Orion chat conversation with a teammate by copying a link. The recipient sees the full conversation history and can continue the analysis independently from where you left off.
To keep working in the same conversation instead of handing over a copy, start a [Room](/chat/rooms).
## How to Share a Conversation
When you find a conversation that would be helpful for someone else on your team, you can easily share it:
1. **Select Share** - The control sits at the top right of the conversation
2. **Copy the link** - In **Share this chat**, copy the link to your clipboard
3. **Share with your team** - Send that link to whoever needs access to the conversation
The same dialog also holds **Work on it together**, which adds someone to this conversation instead
of handing them a copy. That turns it into a [Room](/chat/rooms).
![Share Chat button in the chat interface]()
## What Happens When Someone Opens Your Shared Conversation
When a team member opens your shared conversation link, they'll see:
* A blue conversation box that displays the full conversation history
* A message indicating this conversation was shared with them
* The ability to continue the conversation as their own
![Recipient view of a shared chat, prompting the user to continue the conversation.]()
## Important Notes
* **Conversations are isolated** - All chat history is isolated to specific users and projects
* **Continue independently** - Once someone continues a shared conversation, the original user won't see their messages from that point forward
* **Great for onboarding** - Sharing conversations is a great way to help team members understand how conversations work and see examples of effective interactions with Orion
# Company Information
Source: https://docs.runorion.com/configuration/company-information
Company context Orion applies to every project
Company Information allows administrators to provide comprehensive context about your organization that Orion will reference across all [projects](/core-concepts/projects) and [conversations](/chat/basics-navigation).
## Accessing Company Information
1. Go to **Configuration** in the left-hand navigation menu
2. Select the **Company Information** tab
## What to Include
The Company Information section is where you store global company context. This is a large text field where you can provide:
### Data Context
* **Data sources** - Where your company data comes from
* **Data pipeline** - How data flows through your systems
* **Update frequency** - When and how often data is updated
* **Data quality notes** - Any important caveats or considerations
### Business Context
* **Company overview** - Your company mission, focus areas, and goals
* **Business terminology** - Industry-specific terms and definitions
* **Acronyms** - Common abbreviations used in your organization
* **Business rules** - Key processes and policies that affect data
### Domain Knowledge
* **Organizational structure** - How teams and departments relate
* **Key metrics** - Important KPIs and how they're calculated
* **Historical context** - Important events or changes that affect analysis
* **Industry nuances** - Sector-specific factors relevant to your data
## How Orion Uses Company Information
The information you provide in Company Information:
* **Applies globally** - Used across all projects and conversations for every user
* **Improves accuracy** - Helps Orion understand context and make better recommendations
* **Enhances insights** - Ensures analyses align with your business reality
* **Saves time** - Users don't need to repeat context in each project
## Best Practices
The more comprehensive and detailed your Company Information, the better Orion
can serve your entire organization. Update this section whenever significant
business changes occur.
# Data Sources Management
Source: https://docs.runorion.com/configuration/data-sources
Connect and manage the data sources your tenant queries
Orion connects to three kinds of source: your data warehouse, the tools holding your business logic, and a few services that add outside context. Administrators connect each one once, at the tenant level.
## Accessing Data Sources
1. Go to **Configuration** in the left-hand navigation menu
2. Select the **Data Sources** tab
![The Data Sources tab in Configuration, showing connected data source tiles]()
Once you've set up access on the source side (service accounts, API keys), this page is where you enter those connection details.
BigQuery needs one value from Orion as well. The connection form shows the Orion service account that you grant access to in Google Cloud. You never have to ask us for it. See [Connecting Data Sources](/connecting-data-sources#bigquery) for the full setup.
## How Data Sources Work
Data sources are configured at the tenant level and made globally available:
* **Tenant-level setup** - Administrators connect data sources once in Configuration
* **Tenant-wide by default** - Connected data sources are available across the tenant, subject to each user's role and group membership
* **Role limits** - What a user can do with a data source depends on their [role](/configuration/groups#roles-at-a-glance): Admins manage connections, Analysts query them, and Viewers query only where a project owner allows it
* **Group scoping** - [Groups](/configuration/groups) limit which data sources their members can use
* **Project-level selection** - Each [project](/core-concepts/projects) can choose which data sources to use
* **Multiple data sources** - A project can connect to multiple data sources simultaneously
## Supported Data Sources
Orion currently supports connections to:
* **BigQuery** - Google's data warehouse platform
* **Snowflake** - Cloud data platform
* **Databricks** - Lakehouse data platform
* **Redshift** - Amazon's cloud data warehouse
* **Amazon Athena** - Serverless SQL over data in S3, via the AWS Glue catalog
* **Microsoft Fabric** - Microsoft's analytics warehouse
* **PostgreSQL** - Open-source relational database
* **MySQL** - Open-source relational database
* **Delta Lake** - Delta tables on cloud storage (ADLS Gen2 or GCS)
* **Looker** - Dashboards, Looks, and LookML business logic
* **dbt** - Model metadata and lineage, used to enrich a warehouse connection
Two lightweight external-context sources round out the list:
* **News API** - News headlines pulled into analyses for external context (free newsapi.org key)
* **Weather** - Historical and forecast weather from Open-Meteo, no key required
For the credentials, grants, and step-by-step setup each source needs, see [Connecting Data Sources](/connecting-data-sources).
Beyond these tenant-level connections, users can also upload Excel files in chat and query them as ad hoc data sources for a single analysis. See [File Uploads](/chat/file-uploads).
## Adding a Data Source
As an administrator, you can:
1. Click the **Add Data Source** tile
2. Select the type of data source from the supported list
3. Provide the necessary connection credentials and configuration
4. Save the connection
![The Choose a data source modal listing supported source types]()
The data source is now available for all users to select when setting up projects.
Each data source has its own access requirements. See [Connecting Data
Sources](/connecting-data-sources) for the credentials, grants, and network
access each one needs.
## Managing Data Sources
Administrators can:
* **Update credentials** - Change connection details if needed
* **Monitor status** - Check the health of data source connections
* **Remove data sources** - Disconnect data sources from the tenant
* **View usage** - See which projects are using each data source
Start with one or two data sources and expand as your team's analytical needs
grow.
# Global Configuration
Source: https://docs.runorion.com/configuration/global-configuration
The admin hub for tenant-wide settings
Global Configuration is the admin hub for tenant-wide settings (company information, data source connections, and user management) that apply to every user and project in your Orion instance.
This section is for tenant administrators. Configuration changes affect all
users in your Orion tenant.
## Accessing Global Configuration
As an administrator, access Global Configuration from the left-hand navigation menu by clicking on **Configuration**.
## Configuration Tabs
Global Configuration is organized into several tabs:
### Company Information
Store company-wide context and information that applies to all projects and conversations. See [Company Information](/configuration/company-information) for details.
### Data Sources
Connect and manage data sources for your entire tenant. See [Data Sources Management](/configuration/data-sources) for details.
### User Management
Manage tenant users and their permissions. See [User Management](/configuration/user-management) for details.
## Important Notes
Changes made in Global Configuration affect all users in your tenant. Ensure
you have the necessary permissions before making changes.
Configuration is still being enhanced with additional features and capabilities. Check back for updates.
# Groups
Source: https://docs.runorion.com/configuration/groups
Model teams and departments as shared-access units
Groups let you organize users into cohorts that share access to the same set of [projects](/core-concepts/projects), [data sources](/configuration/data-sources), [Knowledge Base](/core-concepts/knowledge-base) pages, and [Integrations](/knowledge-base/wiki-integrations). Use them to model teams, departments, end customers, or any other grouping that maps to a set of people who should see the same resources.
## When to use Groups
Sales, Marketing, Finance, and Operations each get their own group with the
projects, data sources, and Knowledge Base pages relevant to their work.
Agencies and consultancies can give each end customer their own group,
keeping their projects and data isolated from other customers in the same
tenant.
A user can belong to several groups at once, for example an executive who
needs visibility into Sales, Marketing, and Operations.
If you don't create any groups, Orion behaves exactly as before. Groups are an
additive feature: your existing users, projects, and permissions are
unaffected until you opt in by creating a group.
## Accessing Groups
Group management lives alongside user management in **Settings → Manage Users**. The page has two tabs: **Users** and **Groups**.
![Groups tab in Manage Users showing existing groups with member and project counts]()
## Creating a Group
From the Groups tab, click **+ New Group**. Give the group a clear name and an optional description.
![New Group dialog with Name and Description fields]()
If a non-admin user creates a group, they automatically become its first Group Admin. Tenant Admins who create groups manage them via their tenant role and are not added as members.
### Naming Groups with Prefixes
When creating a group, the modal offers the option to select a **prefix** or choose no prefix. Prefixes are a purely organizational label: they make related groups sort and display together, but confer no shared access or functional relationship between groups. A group named `Verizon / Sales` and one named `Verizon / Marketing` are completely independent; the prefix just keeps them visually adjacent.
The first group you create under a prefix acts as the **catch-all group** for that prefix, a landing zone you can add users to before their specific sub-group is ready. For example, you might create `Verizon` first, add new users there while you're still setting up sub-groups, then move them into `Verizon / Sales` or `Verizon / Marketing` once those are configured.
Use prefixes consistently from the start. It is significantly harder to
reorganize groups after members and projects have been added. A naming
convention like `[Customer] / [Team]` or `[Department] / [Sub-team]` works
well for most organizations.
## Group Roles
Each user has a role **within each group they belong to**. A group role only controls what someone can do inside that group: it is separate from and independent of their tenant role.
Manage everything in the group: add and remove members, add projects, data
sources, Knowledge Base pages, and integrations, and delete the group.
Full working access to everything in the group. Can create new projects and
share them with others. Can also create new groups and automatically becomes
the Admin of any group they create.
Read-only access to the group's projects, data, Knowledge Base pages, and
integrations. Cannot manage group settings or data source configuration, and
can query data only where a project owner allows it.
### Roles at a Glance
The table below covers all six roles across both levels, tenant and group. Tenant roles apply across the entire Orion instance; group roles apply only within the specific group.
| Capability | Admin | Analyst | Viewer | Group Admin | Group Analyst | Group Viewer |
| -------------------------------------------- | :------------: | :---------------------: | :---------------: | :---------------: | :---------------: | :-----------------: |
| **Scope** | Full tenant | Projects they belong to | Approved projects | Own group(s) only | Own group(s) only | Group projects only |
| Invite users to tenant | ✓ | - | - | ✓³ | - | - |
| Manage tenant-wide settings & data sources | ✓ | - | - | - | - | - |
| See all users, groups & projects | ✓ | - | - | - | - | - |
| Create groups | ✓ | - | - | ✓ | ✓¹ | - |
| Manage group members | ✓ | - | - | ✓ | - | - |
| Manage group data sources, KB & integrations | ✓ | - | - | ✓ | - | - |
| Delete a group | ✓ | - | - | ✓ | - | - |
| Create & share projects | ✓ | ✓ | - | ✓ | ✓ | - |
| Run analyses & chat | ✓ | ✓ | - | ✓ | ✓ | - |
| View accessible projects | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Query data sources | ✓ | ✓ | Per-project² | ✓ | ✓ | Per-project² |
1. A Group Analyst automatically becomes Group Admin of any group they create.
2. Project owners can extend Viewer access to allow data queries on a per-project basis in Project Settings.
3. Group Admins can invite new users to the tenant through the group's **Invite by email** flow, but not through Settings directly.
**Tenant roles and group roles are independent.** A tenant Viewer can be a
Group Admin. A tenant Analyst can be a Group Viewer in one group and a Group
Admin in another. Orion always evaluates the role that applies to the specific
resource someone is trying to access, so what a user can do in chat, sharing,
and editing may differ from one project to the next.
### Users with roles across multiple groups
Tenant Admins always have full visibility across every group. For everyone else (tenant Analysts and Viewers), group roles can vary between groups. A user can simultaneously be:
* A **Group Admin** in a group they created or were promoted in
* A **Group Analyst** in a colleague's group they were invited to contribute to
* A **Group Viewer** in a third group where they only need read access
This means two users with the same tenant role may have very different effective access depending on which groups they belong to and what roles they hold there. When troubleshooting unexpected access, check both the user's tenant role and their role within each relevant group.
## Onboarding new users
Whether you're adding an internal teammate or one of your customers, the safest default is the same: invite them as a tenant **Viewer**, then layer their real access on top through groups.
A tenant Viewer is a blank canvas: they cannot see any projects, data sources, or Knowledge Base pages by default. From there, add them to the right group(s) with a group role that matches what they need to do:
* **Group Viewer**: read-only access to the group's projects, data, Knowledge Base, and integrations
* **Group Analyst**: full working access; can create and share projects within the group
* **Group Admin**: full administrative control of the group, including adding members
This keeps tenant-wide settings and any unrelated projects off-limits while giving the user everything they need inside their group. The pattern works equally well for an internal employee joining a single team and for a customer who should only see their own group's projects.
The [**Invite by email**](#inviting-new-users-directly-into-a-group) flow from inside a group is the fastest way to apply this pattern:
From the group's detail page, click **Add member**, then **Invite by email**
at the bottom of the picker.
Choose **Viewer**. This is the user's baseline across the entire tenant and
keeps everything outside their group off-limits.
Choose **Group Admin**, **Group Analyst**, or **Group Viewer** based on what
they need to do inside this group.
The invitee receives an email and, on first login, lands in Orion with both
roles applied automatically.
Reserve tenant **Admin** and **Analyst** roles for people who genuinely need
tenant-wide reach. For everyone else (internal or external), "tenant Viewer +
Group \[role]" is the safest default.
## Managing a Group
Click any group from the Groups tab to open its detail view. From here you can manage everything the group has access to using the tabs along the top.
![Group detail view showing the Members tab with tabs for Projects, Data Sources, Knowledge Base, and Integrations]()
The header shows who created the group and when. Click the group name or description to edit them inline.
### Members
The Members tab lists everyone in the group along with their group role.
#### Adding existing users to a group
Click **Add member** to open the member picker. The list shows users from your tenant who aren't already in the group. Pick the role they should have within the group, then add them.
![Add Members modal with a search field, a list of candidates, and a Join as role picker]()
#### Inviting new users directly into a group
If the person you want to add isn't in your tenant yet, click **Invite by email** at the bottom of the picker. You'll select their tenant role first (Admin, Analyst, or Viewer), then their group role. The invitee will receive an invitation email and, on first login, lands in Orion with both roles applied.
Inviting users directly into a group is the fastest way to onboard a new team
or customer cohort. They land in Orion already configured with the right
access, no second step required.
### Projects
The Projects tab lists the group's projects. Everyone in the group can access them with permissions matching their group role.
![Group detail view on the Projects tab showing the group's projects]()
Click **Add project** to add more projects to the group. The picker shows projects you have access to.
![Add Projects modal with a checkbox list of projects and a selection counter]()
A single project can belong to more than one group, useful for shared work that spans multiple teams.
Creating a new project does not automatically add it to a group. A project
belongs only to the user who created it until a Group Admin or Group Analyst
explicitly adds it to the group from this tab.
### Data Sources
When a project is added to a group, the [data sources](/configuration/data-sources) attached to that project automatically become available to everyone in the group, so you don't need to enable them separately. The Data Sources tab is **additive**: use it to expose data sources to the group *beyond* what its projects already provide.
![Group detail view on the Data Sources tab with a checkbox list of available data sources]()
### Knowledge Base
The Knowledge Base tab controls which [Knowledge Base](/core-concepts/knowledge-base) pages and folders the group can use. You can select individual pages or whole folders.
Each linked page also has an **Auto-inject** switch: when on, the page is automatically included in chat context for everyone in the group, with no per-project enablement needed. See [Default Pages (Auto-Inject)](/knowledge-base/creating-pages#default-pages-auto-inject).
![Group detail view on the Knowledge Base tab showing a folder tree with checkboxes]()
Selecting a **whole folder** means any new pages added to that folder later
are automatically available to the group. This is the easiest way to keep a
department's reference material in sync as it grows.
### Integrations
The Integrations tab controls which [integrations](/profile-settings/integrations) the group has access to.
![Group detail view on the Integrations tab showing connected integrations]()
## How users get access to a project
A user can be given access to a project in two ways:
1. **Through a group**: they're a member of a group that the project belongs to. Their permissions match their role in the group.
2. **Directly**: they were invited to the project individually from the project's Share menu, independent of any group.
The two methods work side by side. Removing someone from a group doesn't cancel any direct invite they have, and removing a direct invite doesn't remove them from the group.
The Project Settings modal shows which groups currently have access to the project, alongside its other settings.
## Deleting a Group
To delete a group, open it and click **Delete group** in the upper-right corner. The confirmation dialog summarizes what will happen:
![Delete group dialog showing confirmation steps]()
* **Members** lose access to anything they only had through this group. They keep any direct project access they were granted individually.
* **Projects** that are only used by this group can either be transferred to the group's Admins (who keep access individually) or deleted along with the group.
* **Data Sources, Knowledge Base pages, and Integrations** are not deleted, they simply leave the group.
If you choose to delete a project alongside the group, you'll be asked to type the project's name to confirm.
Deleting a group is permanent. The group and its membership are gone for good.
Members who had no other way to access projects will be left as Viewers with
no projects to see until someone adds them again.
# Sudo
Source: https://docs.runorion.com/configuration/sudo
Act as another user, or let Gravity support do it
Sudo lets an admin temporarily act as another user, useful when a teammate reports a bug you can't reproduce, or when Gravity support needs to investigate something specific to your tenant. A banner sits across the top of every page during a sudo session so you always know you're acting on someone else's behalf, and every session is recorded in your tenant's activity log.
## Two ways to use Sudo
A tenant admin opens **Manage Users**, finds a user in their tenant, and
clicks **Sudo**. No invitation needed: admins already have full authority
in the tenant.
A tenant admin invites a Gravity support engineer by email and sets how long
the access lasts. The engineer signs in through a dedicated Gravity-only
entry point and can then sudo as a user in the tenant.
## Sudoing as a teammate
1. Open **Settings → Manage Users**.
2. Find the user you want to act as.
3. Click the **Sudo** icon on their row.
You'll be redirected to the home page, now acting as that user. An amber banner appears across the top with the target user's name and an **Exit sudo** button.
The Sudo button is only available to tenant admins, and only for active users
in your own tenant.
## Granting Gravity support access
If a Gravity support engineer needs to investigate something in your tenant, you can grant them temporary access from the **Support Access** section of **Manage Users**.
1. Open **Settings → Manage Users → Support Access**.
2. Click **Grant access**.
3. Enter the Gravity engineer's email address.
4. Choose how long the grant lasts: **8 hours**, **24 hours**, **7 days**, or **30 days**.
5. Add a short note describing the reason (e.g. a support ticket number). The note is required so the access is traceable.
The Gravity engineer can then sign in through Gravity's dedicated support entry point. Once signed in, they pick a user to sudo as and a red banner appears across every page they visit, showing your tenant name, the note you wrote, and when the grant expires.
Granting access lets a Gravity engineer sign in to your tenant and act as one
of your users. Only grant access in response to a request you initiated (a
support ticket, an incident, or a scheduled investigation) and pick the
shortest TTL that covers the work.
### Revoking access
You can revoke a grant at any time. From the **Support Access** section, find the grant and click **Revoke**. Any sudo session running under that grant ends within 15 minutes: Gravity's session is rechecked on a short timer, and a revoked grant fails the next check.
## What changes during a sudo session
* **A banner is always visible**: amber for intra-tenant sudo, red for Gravity support sudo. The banner shows who you're acting as and an **Exit sudo** button.
* **Your normal session is preserved.** Exiting sudo (or letting the session expire) drops you back into your own account, not the login screen.
* **A sudo session can do anything the target can do.** This is intentional: the point is to reproduce what the target sees, including saving forms, running analyses, and editing settings. Be deliberate about destructive actions.
* **Everything is logged.** Every action taken during a sudo session is recorded in your tenant's activity log, along with the identity of the real driver, so "what did Drew do while signed in as Alice" is fully attributable.
## FAQ
No notification is sent. Sudo activity is recorded in your tenant's activity
log, which admins can review.
A session lasts 15 minutes and refreshes silently every 12 minutes as long
as you're active. Exiting sudo or closing the tab ends the session
immediately. For Gravity-support sudo, the underlying grant also has its own
TTL (8 hours to 30 days), and once that expires, no new sessions can start,
even if the engineer is mid-investigation.
Only tenant admins. Analysts and viewers do not see the Sudo button on the
Manage Users page and cannot start a sudo session through the API.
Yes. Sudo events (`session started`, `session ended`, `grant created`,
`grant revoked`) flow through the same activity stream as the rest of Orion.
Contact your Gravity account team if you need a custom report.
# User Management
Source: https://docs.runorion.com/configuration/user-management
Invite people and set what they can reach
Orion has three tenant-level roles (Admin, Analyst, and Viewer) that control baseline permissions. Admins invite users, assign roles, and manage group membership from **Settings > Manage Users**. Users and [Groups](/configuration/groups) are managed from the same page.
## Accessing User Management
User Management is available to tenant Admins. To access it:
1. Click your **username** in the bottom-left corner
2. Select **Manage Users**
The page has two tabs: **Users** (everyone in the tenant) and **Groups** (groups of users that share access to projects, data, and knowledge).
![Manage Users page on the Users tab, with columns for User, Role, Project Access, and Groups]()
The Users table shows each user's tenant role, the number of projects they can access, and the groups they belong to. Use the search box to filter by name, email, role, or project.
## Inviting New Users
To invite a new team member to your Orion tenant:
1. Navigate to **Settings → Manage Users**
2. From the **Users** tab, click **Invite user**
3. Enter the new user's email address
4. Choose the appropriate role
5. Send the invitation
The new user will receive an email with instructions to complete their account setup. See [User Onboarding & Invitations](/profile-settings/user-onboarding) for more details.
To onboard a new user **directly into a group**, invite them from inside that
group instead. Open the group, click **Add member**, then **Invite by email**
and the invitee is automatically added to the group with the role you pick on
first login. See
[Groups](/configuration/groups#inviting-new-users-directly-into-a-group) for
details.
## Tenant Roles
Every user has a tenant role that defines their baseline permissions across the entire tenant.
Full control of the tenant. Can invite users, create and manage groups,
connect data sources, and assign users to projects.
Can do just about anything within a project: chat, run analyses, and share
projects. Cannot add existing users to other projects directly.
Read-only access to approved projects and content. Cannot run analyses or
make changes.
Carefully consider permission levels when inviting users, especially for
administrative roles.
### Tenant roles vs. group roles
If you use [Groups](/configuration/groups), each user also has a **group role** in every group they belong to (Group Admin, Group Analyst, or Group Viewer). Group roles are independent of tenant roles and only apply inside that group, so a tenant Viewer can still be a Group Admin in a group they manage.
For a side-by-side comparison of all six roles, see [Groups → Roles at a Glance](/configuration/groups#roles-at-a-glance).
## User Management Tasks
Administrators can:
* **Invite new users**: add team members to the tenant
* **Assign tenant roles**: control each user's baseline permissions
* **Manage group membership**: see which groups a user belongs to and their role in each
* **Modify permissions**: update existing user roles
* **Deactivate users**: remove user access while preserving history
* **Remove users**: completely delete user accounts
* **[Sudo as a user](/configuration/sudo)**: temporarily act as another user to troubleshoot issues from their point of view
## Best Practices
Follow the principle of least privilege: grant users the minimum permissions
they need to do their job. For tenants using Groups, prefer group membership
over direct project access: it's easier to audit and easier to revoke when
someone's role changes.
# Connecting Data Sources
Source: https://docs.runorion.com/connecting-data-sources
What each data source needs: credentials, grants, and network access
These guides walk through what Orion needs to connect to each supported data source, and how to grant that access. Most connections are configured once at the tenant level by an administrator.
Every guide ends the same way: take the connection details you produced and enter them in Orion under **Configuration → Data Sources → Add Data Source**. See [Data Sources Management](/configuration/data-sources) for a tour of that page. If you'd rather not enter them yourself, share the details with your Gravity contact and we'll configure the connection for you.
## How Orion connects
A few principles apply to every connection:
Orion only ever issues read queries (`SELECT` and metadata introspection).
It never runs DDL, DML, or stored procedures against your systems.
We recommend a dedicated service user or service account scoped to just the
data you want Orion to analyze.
Any credentials you share (passwords, keys, secrets) are encrypted at rest
in our database.
For private databases that aren't publicly reachable (behind a VPC, private
subnet, firewall, or VPN), allowlist Orion's egress IPs so we can reach them.
All Orion services egress through the same set of IPs, so a single allowlist
entry covers everything. Your production egress IP range is provided by your
Gravity contact during onboarding.
## Choose your data source
***
## BigQuery
Orion connects to BigQuery using **service account impersonation**. You create a service account in your project and grant Orion's service account permission to impersonate it. No credentials or keys are ever shared.
For every Google Cloud Console step below, make sure you are in the correct
GCP project. Most setups use a single project for both the service account and
the source data. If your datasets live in a different project from the one
that runs Orion's queries, see [Querying datasets in another
project](#querying-datasets-in-another-project).
1. Go to **Google Cloud Console → IAM & Admin → Service Accounts**
2. Click **Create Service Account**
3. **Name:** `external-orion-data-access` (or your preferred naming)
4. **Description:** "Service account for Orion data access"
5. Click **Create and Continue**
6. Skip role assignment for now → click **Done**
We'll refer to this as the **BigQuery Service Account** going forward.
Orion queries BigQuery by impersonating the service account you just created. To allow that, grant Orion's own service account the **Service Account Token Creator** role on it.
Orion shows you the address to use. Go to **Configuration → Data Sources**, click **Add Data Source**, and choose **BigQuery**. The **Orion Service Account** sits under the Service Account Email field, with a button to copy it.
Then, in Google Cloud Console:
1. Navigate to **IAM & Admin → Service Accounts**
2. Find the BigQuery Service Account you just created
3. Select the **Principals With Access** tab and click **Grant Access**
4. **Add principal:** the Orion Service Account address you copied
5. **Assign role:** **Service Account Token Creator**
6. Click **Save**
1. Navigate to **BigQuery**
2. Create a new dataset, a dedicated dataset reserved for Orion's use (we recommend a descriptive name like `orion_scratch`)
3. Grant the BigQuery Service Account **Data Editor** access to this dataset
The scratch dataset **must be in the same region** (or multi-region) as the
datasets you wish to query via Orion.
Orion uses this dataset to efficiently stream query results to a binary format optimized for quick analysis. Temp tables created here are automatically cleaned up.
In **BigQuery**, for each dataset or table you want to share:
1. Select the dataset → click **Share Dataset**
2. Add the BigQuery Service Account email
3. **Assign role:** **BigQuery Data Viewer**
4. Click **Add**, then **Done**
1. Navigate to **IAM**
2. Locate your BigQuery Service Account and click **Edit**
3. Assign the roles: **BigQuery Job User**, **BigQuery Connection User**, and **BigQuery Read Session User**
4. Click **Save**
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **BigQuery**. The form asks for exactly what the steps above produced:
| Field | From |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Project ID** | The GCP project that runs Orion's queries: where the service account, scratch dataset, and query jobs live |
| **Service Account Email** | The BigQuery Service Account from step 1 |
| **Scratch Dataset** | The dataset from step 3 |
| **Data Project ID** *(optional)* | The GCP project where your source datasets live, if it differs from **Project ID**. Leave blank when everything is in one project |
| **Location** | The GCP location of your datasets (defaults to the `US` multi-region) |
![The Configure BigQuery Connection form in Orion, with the Orion Service Account shown under the Service Account Email field]()
The **Orion Service Account** shown on this form is Orion's own address, the one you granted access to in step 2. You do not enter it anywhere. Your instance has its own address, so copy it from your own screen rather than from the picture above.
No credentials need to be shared.
**One project or two?** Most customers keep the service account, scratch
dataset, and source data in a single project and leave **Data Project ID**
blank. Fill it in only when your datasets live in a different project from
the one running Orion's queries. See [Querying datasets in another
project](#querying-datasets-in-another-project).
### Querying datasets in another project
Orion separates the project that **runs** your queries from the project that **stores** your data. The two roles map to the two form fields:
* **Project ID** is the compute and billing project. The service account, the scratch dataset, and every query job live here. Grant **BigQuery Job User**, **BigQuery Connection User**, and **BigQuery Read Session User** on this project (step 5), plus **Data Editor** on the scratch dataset (step 3).
* **Data Project ID** is where your source datasets live. Grant the service account **BigQuery Data Viewer** on those datasets (step 4).
When both are the same project, leave **Data Project ID** blank and Orion uses **Project ID** for everything. When your data lives elsewhere, set **Data Project ID** to that project. Orion then qualifies your tables against it while still running jobs and writing scratch results in **Project ID**. The service account still only needs impersonation set up once, in the project where it was created.
### Per-user OAuth (optional)
By default, Orion queries BigQuery through the shared service account above. With **per-user OAuth**, Orion instead runs each person's BigQuery queries under their own Google identity, so what each user can see in Orion follows the BigQuery permissions they already have, rather than a single shared service account.
Per-user OAuth builds on the service account setup above, so complete that
first. The service account is still used for unattended work such as scheduled
refreshes with no individual owner and schema introspection.
Use it when you want each person's data access in Orion to match their existing BigQuery roles.
1. In **APIs & Services → OAuth consent screen**, set the **User type** to **Internal** so only your Google Workspace users can sign in
2. In **APIs & Services → Credentials**, click **Create Credentials → OAuth client ID**
3. **Application type:** Web application
4. Add the **Authorized redirect URI** provided by your Gravity contact. It points at Orion's OAuth callback, for example `https://g.runorion.com/datasource/bq-oauth/callback`
5. Click **Create**, then copy the **Client ID** and **Client Secret**
On the BigQuery data source (**Configuration → Data Sources**), open the **Connection** tab, click **Edit**, and set:
| Field | Value |
| -------------------------- | --------------------------------------------------- |
| **Authentication Mode** | Per-user OAuth |
| **OAuth Client Reference** | A short name for this client (e.g. `acme-bigquery`) |
| **OAuth Client ID** | From the previous step |
| **OAuth Client Secret** | From the previous step |
Save. The client ID and secret are sent to Orion's gateway and stored encrypted; they are never written to Orion's database. To rotate the secret later, enter the new values and save again. Leave them blank to keep the current ones.
The first time someone opens a project that uses this data source, Orion prompts them to connect. They click **Connect BigQuery**, sign in with Google, and consent once. From then on their queries run under their own identity.
Each person must sign in with the Google account whose email matches their
Orion sign-in. If your team signs in to Orion with Google (SSO), this
matches automatically.
A couple of things to know:
* **Scheduled work runs as its creator.** A metric or workflow that someone schedules runs under that person's connected account. Work with no individual owner uses the service account.
* **If a user disconnects or loses BigQuery access**, their scheduled work pauses until they reconnect. This is deliberate: Orion never falls back to broader access than the user has.
[↑ Back to all data sources](#choose-your-data-source)
***
## Snowflake
Orion connects to Snowflake using **key pair authentication**. You create a dedicated service user, grant it read-only access to the data you want analyzed, and associate a public key with it. Orion holds the matching private key to authenticate.
**Connection information**
| Field | Description |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Account** | Your Snowflake [account identifier](https://docs.snowflake.com/en/user-guide/admin-account-identifier) (e.g. `orgname-account_name` → `orgname-account_name.snowflakecomputing.com`) |
| **User / Role / Warehouse / Database / Schema** | Standard [connection context](https://docs.snowflake.com/en/user-guide/gen-conn-config) values used by Snowflake clients and drivers |
**Required grants** (on the role you configure for the connection)
```sql theme={null}
GRANT USAGE ON WAREHOUSE TO ROLE ;
GRANT USAGE ON DATABASE TO ROLE ;
GRANT USAGE ON SCHEMA . TO ROLE ;
GRANT SELECT ON ALL TABLES IN SCHEMA . TO ROLE ;
```
**Key pair authentication setup**
Generate an encrypted private-public key pair (RSA 2048 or 3072 recommended).
```bash theme={null}
# Encrypted private key (an optional passphrase is recommended)
openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
# Associated public key
openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
```
The private key stays on your system. The public key (`rsa_key.pub`) is added to the Snowflake user.
```sql theme={null}
CREATE USER orion_svc
DEFAULT_ROLE =
MUST_CHANGE_PASSWORD = FALSE;
```
Assign the relevant role with the grants listed above.
```sql theme={null}
ALTER USER orion_svc SET RSA_PUBLIC_KEY='';
```
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Snowflake**. Enter the connection information from the table above (account, user, warehouse, role; database and schema are optional) and upload the **private key** file. Provide the passphrase if the key is encrypted.
**What we store:** Orion uses the private key to authenticate connections. We store the encrypted key and passphrases in our database, and we encrypt your encrypted key. See the [Snowflake key pair documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth).
[↑ Back to all data sources](#choose-your-data-source)
***
## Databricks
Orion connects to Databricks using a dedicated **Service Principal** and a **SQL Warehouse** for compute. We strongly recommend OAuth M2M authentication.
We recommend a dedicated Service Principal for Orion. Follow the [official documentation](https://docs.databricks.com/en/admin/users-groups/service-principals.html) to create one.
Follow the [official documentation](https://docs.databricks.com/en/dev-tools/auth/oauth-m2m.html)
to create a **Client ID** and **Client Secret**. Copy the Client Secret
immediately; you only get one chance to see it.
Follow the [official documentation](https://docs.databricks.com/en/dev-tools/auth/pat.html).
PATs are legacy and being phased out by Databricks, so prefer OAuth M2M.
SQL Warehouses are the compute resources used to execute queries. Either identify an existing warehouse, or create a dedicated one following the [official documentation](https://docs.databricks.com/en/compute/sql-warehouse/create.html). Make note of the warehouse's **HTTP Path**.
Grant the Service Principal **read access** to all catalogs, schemas, and tables you want Orion to analyze, plus access to the **SQL Warehouse** used to execute queries.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Databricks**. Give the connection a name and optional description, then fill in:
| Field | Description | Example |
| --------------------------------- | ------------------------------------------ | ------------------------------ |
| **Host** | The host URL for your Databricks | `abc-123.cloud.databricks.com` |
| **Warehouse HTTP Path** | The HTTP path to your chosen SQL Warehouse | `/sql/1.0/warehouses/abc123` |
| **Client ID** & **Client Secret** | OAuth M2M credentials | |
Optionally include a **Databricks Catalog** to limit the scope of data a
given connection can access.
[↑ Back to all data sources](#choose-your-data-source)
***
## Looker
Orion connects to Looker using a dedicated user account with analyst-level (read-only) permissions plus API credentials. You'll also grant the account access to the Spaces (folders) that hold your dashboards and Looks.
**Standard deployment:** We request a Looker account for the email **`orion@gravity.foundation`**, with permissions matching those of a typical analyst at your organization. Orion only needs **read** access.
**Required permissions** (in addition to analyst-level access)
* **Models** ([docs](https://cloud.google.com/looker/docs/admin-panel-users-roles)): can be scoped to necessary models via model sets; includes the `explore` permission
* **`see_system_activity`**, **`see_lookml`**, **`see_sql`**
* **`see_user_dashboards`** (or provide PDFs of sample dashboards instead)
* **`create_custom_fields`**: enables building custom fields via **+ Add**
* **`login_special_email`**: only if using non-email (third-party) authentication
**Content access (Spaces / folders)**
Model permissions and content access are configured separately in Looker. The Orion user also needs **view access** to the Spaces where your dashboards and Looks are stored:
Navigate to the folder(s) containing your key dashboards.
Click **Manage Access** on the folder.
Add the Orion user (or a group it belongs to) with **View** access.
Without this step, the Orion user will have model and query permissions but
won't be able to see any saved dashboard content. See [Managing access to
folders](https://cloud.google.com/looker/docs/managing-spaces-and-folders).
**API credentials:** Generate API keys for `orion@gravity.foundation` ([docs](https://cloud.google.com/looker/docs/api-auth)). Then, in Orion, go to **Configuration → Data Sources**, click **Add Data Source**, choose **Looker**, and enter your Looker **base URL**, the **`client_id`**, and the **`client_secret`**.
**Third-party authentication:** If you use Okta or another third-party provider, add the **`login_special_email`** permission. Navigate to the **Roles** section of the Admin panel (`https://[organization].cloud.looker.com/admin/roles`) and, if you don't already have external users, create a new permission set. See the [Looker documentation](https://cloud.google.com/looker/docs/admin-panel-users-roles#login_special_email).
### LookML augmentation (optional)
Beyond querying dashboards and Looks, Orion can read your LookML business logic directly from its GitHub repository, reusing the dimensions, measures, and joins you have already defined to write better SQL. Setup takes about 10 minutes and needs a GitHub repository admin for one step.
The GitHub account that owns the token you create must have **Read** access to
the LookML repository (see Step 9). A valid token from an account without repo
access fails with a "repository not found" error. If you are not a repo admin,
loop one in for Step 9.
On the **Configuration → Data Sources** page, open the Looker datasource and select the **Augmentation** tab.
![The Coffee Rush Looker datasource in Orion Configuration, with the Connection, Refresh Data, Augmentation, Schema, and Migration tabs]()
Click the **Create token** link to open GitHub.
![The Create token link beneath the Personal Access Token field on the Augmentation tab]()
On GitHub, begin creating a **fine-grained personal access token**.
![GitHub's fine-grained personal access tokens page with the Generate new token button]()
* **Resource owner:** select the organization or account where the Looker GitHub repository lives.
* **Expiration (TTL):** set the token expiration. We recommend the longest your security policy allows; GitHub's maximum for fine-grained tokens is 1 year (366 days).
![The new fine-grained token form with token name, resource owner, and expiration fields]()
When this token expires, Orion can no longer pull your LookML repo. Schema sync and the nightly enrichment that reads your LookML will fail with an authentication error, and any insights that depend on that business logic go stale until you issue a new token and update the connection. Set a reminder to rotate the token before it expires.
Choose the Looker repository from the dropdown.
Grant read-only access, nothing more:
* **Contents:** Read-only
* **Metadata:** Read-only
![Repository access set to the LookML repo, with Contents and Metadata permissions set to Read-only]()
Generate the token and copy it. You will not be able to view it again.
Back in Orion, enter the repository URL, the PAT, and the rest of the configuration (see the **Augmentation** tab in Step 2), then save.
The account that owns the token must have at least **Read** access to the LookML repo, or Orion authenticates but cannot see the repo and the connection fails with "repository not found."
A repository admin:
1. In GitHub, open the LookML repository → **Settings → Collaborators and teams** (under **Access**).
2. Under **Manage access**, click **Add people** (or **Add teams** if you manage access by team).
3. Enter the username of the account tied to the token, or the service account created for Orion.
4. Set the role to **Read**. No write or admin access is required.
5. Send the invitation.
6. The account owner **accepts the invite**. Until they do, access does not take effect and the connection will still fail.
7. Return to the Orion connection and reconnect.
![The LookML repository's Collaborators and teams page in GitHub, under Settings, with the Add people option]()
Use a shared service account rather than an individual's personal account. If a person leaves or loses access, a personal-account token breaks the connection.
On the **Augmentation** tab, click **Test Connection**. This verifies that Orion can reach the repository with the token and branch you configured, without running a full sync.
* **Success:** the connection is valid. Orion can authenticate and see the repo. Click **Sync Now** to pull the LookML files. When it finishes, **Status** shows **Synced**, along with the file count and the latest commit.
* **Failure:** read the error message:
* **"Repository or branch not found"** usually means the token's account lacks Read access to the repo (revisit Step 9), or the branch name is wrong. Leave **Branch** blank to use the repo default, or enter the correct branch.
* **"Authentication failed"** means the token is invalid or expired. Generate a new one (Steps 3-7) and re-enter it.
* **"Access forbidden"** means the token is missing a permission or, if your org enforces SSO, has not been SSO-authorized for the organization.
Once the test passes and the first sync completes, Orion is reading your LookML.
[↑ Back to all data sources](#choose-your-data-source)
***
## PostgreSQL
Orion connects to PostgreSQL with username/password authentication. Create a dedicated read-only user and grant it `SELECT` on the schemas and tables you want analyzed.
**Connection information**
| Field | Description |
| ------------ | ------------------------------------------------------------------------ |
| **Host** | PostgreSQL server hostname / IP address |
| **Port** | PostgreSQL server port (default: `5432`) |
| **Database** | Target database name |
| **User** | PostgreSQL username for authentication |
| **Password** | User password for authentication |
| **SSL Mode** | `disable` / `allow` / `prefer` / `require` / `verify-ca` / `verify-full` |
**Required grants**
```sql theme={null}
GRANT CONNECT ON DATABASE TO ;
GRANT USAGE ON SCHEMA TO ;
GRANT SELECT ON ALL TABLES IN SCHEMA TO ;
-- So future tables are visible automatically:
ALTER DEFAULT PRIVILEGES IN SCHEMA GRANT SELECT ON TABLES TO ;
```
**Setup**
```sql theme={null}
CREATE USER orion_svc WITH PASSWORD '';
```
In `postgresql.conf`: set `listen_addresses = '*'` so PostgreSQL accepts connections, and `ssl = on` for SSL connections.
In `pg_hba.conf`:
```text theme={null}
host orion_svc md5
hostssl orion_svc md5 # SSL-only
```
Restart the PostgreSQL service, then assign the grants listed above to the service user.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Postgres**. Enter the connection information from the table above (host, port, database, user, password, SSL mode).
**What we store:** username/password authentication; we encrypt your plain-text password in our database. See the PostgreSQL docs on [connection parameters](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS), [access control](https://www.postgresql.org/docs/current/ddl-priv.html), and [client authentication](https://www.postgresql.org/docs/current/client-authentication.html).
[↑ Back to all data sources](#choose-your-data-source)
***
## MySQL
Orion connects to MySQL with username/password authentication. Create a dedicated user and grant it read-only access to the target database.
**Connection information**
| Field | Description |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Host** | MySQL server hostname / IP address |
| **Port** | MySQL server port (default: `3306`) |
| **Database** | Target database (schema) name |
| **User** | MySQL username for authentication |
| **Password** | User password for authentication |
| **SSL Mode** | `disable` / `preferred` / `required` / `verify-ca` / `verify-identity` |
| **SSL CA Certificate** (optional) | PEM-encoded CA bundle, required for `verify-ca` / `verify-identity` when the server certificate is not signed by a publicly trusted CA |
In MySQL, a "database" and a "schema" are the same thing. The **Database**
value above is the schema Orion will read from.
**Required grants**
```sql theme={null}
-- Read-only access to all current and future tables/views in
GRANT SELECT, SHOW VIEW ON .* TO ''@'';
FLUSH PRIVILEGES;
```
**Setup**
```sql theme={null}
CREATE USER 'orion_svc'@'' IDENTIFIED BY '';
```
Replace `` with the IP/CIDR Orion will connect from (e.g. `'orion_svc'@'10.0.0.0/8'`), or use `'%'` to allow any source.
Ensure MySQL accepts remote connections in `my.cnf` (or `mysqld.cnf`):
```ini theme={null}
[mysqld]
bind-address = 0.0.0.0
# For SSL:
require_secure_transport = ON
ssl-ca = /path/to/ca.pem
ssl-cert = /path/to/server-cert.pem
ssl-key = /path/to/server-key.pem
```
Optionally require SSL for this user only: `ALTER USER 'orion_svc'@'' REQUIRE SSL;`
Restart the MySQL service, then assign the grants listed above to the service user.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **MySQL**. Enter the connection information from the table above (host, port, database, user, password, SSL mode, and the CA certificate if applicable).
**What we store:** username/password authentication; we encrypt your plain-text password at rest. If you provide an SSL CA certificate, we encrypt the PEM contents alongside it. See the MySQL docs on [access control](https://dev.mysql.com/doc/refman/8.0/en/access-control.html) and [encrypted connections](https://dev.mysql.com/doc/refman/8.0/en/encrypted-connections.html).
[↑ Back to all data sources](#choose-your-data-source)
***
## Redshift
Orion connects to Amazon Redshift (cluster or Serverless workgroup) over the standard PostgreSQL wire protocol (port `5439`) using username/password authentication. Orion only ever issues read (`SELECT`) queries.
**Connection details**
| Field | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Host** | Your cluster endpoint, e.g. `my-cluster.abc123xyz.us-east-1.redshift.amazonaws.com`. For Serverless: `my-workgroup.123456789012.us-east-1.redshift-serverless.amazonaws.com` |
| **Port** | Defaults to `5439` |
| **Database** | The database name to connect to, e.g. `analytics` or `dev` |
| **User** | The read-only user created for Orion (we suggest `orion`) |
| **Password** | The password for that user |
| **SSL Mode** | `require` (default; Redshift clusters always terminate TLS) |
**Database user & permissions**
On Redshift, a user can only see a table in `information_schema` if it has
been granted access, so these grants also determine what Orion can discover.
```sql theme={null}
CREATE USER orion PASSWORD '';
-- For each schema you want Orion to access:
GRANT USAGE ON SCHEMA TO orion;
GRANT SELECT ON ALL TABLES IN SCHEMA TO orion;
-- So future tables are visible automatically:
ALTER DEFAULT PRIVILEGES IN SCHEMA GRANT SELECT ON TABLES TO orion;
```
Orion does not need `INSERT` / `UPDATE` / `DELETE` / `CREATE`, so please do
not grant write access.
**Network access:** Orion connects from our infrastructure, so the endpoint must be reachable on the Redshift port. Allow inbound traffic on port `5439` from Orion's egress IP range in the cluster's VPC security group. See the docs on [managing Redshift security groups](https://docs.aws.amazon.com/redshift/latest/mgmt/working-with-security-groups.html).
**Enter the connection in Orion:** go to **Configuration → Data Sources**, click **Add Data Source**, choose **Amazon Redshift**, and enter the connection details from the table above.
[↑ Back to all data sources](#choose-your-data-source)
***
## Amazon Athena
Orion connects to Amazon Athena to run serverless SQL over data in S3. Table and column metadata comes from your **AWS Glue Data Catalog**; queries run through Athena and write their results to an S3 **output location** you control. Orion only ever issues read (`SELECT`) queries against your tables.
Authentication uses an **IAM access key** for a dedicated user. You create the user, attach a least-privilege policy, and enter the access key ID and secret in Orion.
Every Athena query must write its results somewhere in S3. This is an Athena
requirement, not an Orion one: the output location (or a workgroup that
enforces one) is where Athena stages query output before Orion reads it. The
IAM user therefore needs **write** access to that one output prefix, even
though it only reads your actual data.
**Connection details**
| Field | Description | Example |
| ------------------------- | ------------------------------------------------------------- | -------------------------------- |
| **AWS Access Key ID** | Access key ID for the dedicated IAM user | `AKIA...` |
| **AWS Secret Access Key** | Secret access key for that user | *(sensitive)* |
| **Region** | AWS region where Athena and your Glue catalog live | `us-east-1` |
| **S3 Output Location** | S3 URI where Athena stages query results (must end in `/`) | `s3://my-bucket/athena-results/` |
| **Workgroup** | Athena workgroup to run queries under (defaults to `primary`) | `primary` |
| **Data Catalog** | Athena data catalog name (defaults to `AwsDataCatalog`) | `AwsDataCatalog` |
| **Database** *(optional)* | Scope schema exploration to a single Glue database | `analytics` |
Orion reads the chosen **workgroup's query history** to learn which tables and
columns your team queries most. That history includes the **SQL text** of
every query run in the workgroup. If that is a concern, point Orion at a
dedicated workgroup rather than one shared with sensitive ad-hoc queries.
**IAM setup**
In the AWS IAM console, create a user for Orion (we suggest `orion-athena`) with **programmatic access**, then create an access key for it. Copy the **Access Key ID** and **Secret Access Key**; the secret is only shown once.
Attach a policy granting Athena execution, read-only Glue catalog access, read access to the S3 buckets holding your data, and read/write access to the S3 output location. Scope the resource ARNs to your own buckets, workgroup, and catalog. The policy below is a starting point:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AthenaQueries",
"Effect": "Allow",
"Action": [
"athena:StartQueryExecution",
"athena:StopQueryExecution",
"athena:GetQueryExecution",
"athena:GetQueryResults",
"athena:GetWorkGroup",
"athena:ListWorkGroups",
"athena:ListQueryExecutions",
"athena:BatchGetQueryExecution"
],
"Resource": "*"
},
{
"Sid": "GlueCatalogReadOnly",
"Effect": "Allow",
"Action": [
"glue:GetDatabase",
"glue:GetDatabases",
"glue:GetTable",
"glue:GetTables",
"glue:GetPartition",
"glue:GetPartitions"
],
"Resource": "*"
},
{
"Sid": "S3ReadData",
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation"],
"Resource": [
"arn:aws:s3:::my-data-bucket",
"arn:aws:s3:::my-data-bucket/*"
]
},
{
"Sid": "S3ReadWriteResults",
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:ListBucket", "s3:GetBucketLocation"],
"Resource": [
"arn:aws:s3:::my-bucket",
"arn:aws:s3:::my-bucket/athena-results/*"
]
}
]
}
```
Tighten `ListQueryExecutions` / `BatchGetQueryExecution` and the Glue and
Athena actions to specific workgroup, catalog, and database ARNs if you
want to lock the user down further. The `ListQueryExecutions` /
`BatchGetQueryExecution` pair is only used for the query-history
enrichment described above; omit them if you'd rather not expose query
history.
Make sure the workgroup you name exists in the chosen region, and that either the workgroup enforces an output location or the **S3 Output Location** you enter is writable by the IAM user. If the workgroup enforces its own output location, that setting wins over the value you enter in Orion.
In Orion, go to **Configuration → Data Sources**, click **Add Data Source**, and choose **Amazon Athena**. Enter the connection details from the table above. Leave **Workgroup** and **Data Catalog** at their defaults (`primary` / `AwsDataCatalog`) unless you use custom ones, and set **Database** only if you want to limit schema discovery to one Glue database.
**Network access:** Athena and Glue are reached over their public AWS API endpoints, so no VPC allowlisting is required for the connection itself. If your S3 buckets restrict access by source IP or VPC endpoint policy, allow Orion's egress IP range (provided by your Gravity contact) to reach them.
**What we store:** the IAM access key ID and secret access key, encrypted at rest in our database. To rotate the key later, enter the new values on the data source's **Connection** tab and save; leave the secret blank to keep the current one.
**Known limitations**
* **IAM access key only.** Cross-account IAM role assumption is a planned fast-follow; today the connection uses a long-lived access key, so rotate it on your normal cadence.
* **Output location is mandatory.** Athena cannot run a query without a place to write results, so the workgroup must enforce one or you must supply the **S3 Output Location**.
* **dbt enrichment** is supported on Athena connections (see [dbt](#dbt)); semantic enrichment from a Looker connection can also be projected onto Athena schemas.
[↑ Back to all data sources](#choose-your-data-source)
***
## Microsoft Fabric
Orion connects to a Microsoft Fabric Warehouse using a **Service Principal** (App Registration) in your Microsoft Entra ID tenant. Orion connects over TDS (the SQL endpoint) using ODBC Driver 18 with Service Principal authentication, with no interactive login required.
**Azure App Registration**
1. Create an App Registration in your Entra ID tenant ([docs](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app))
2. Note the **Application (client) ID** and **Directory (tenant) ID**
3. Create a **Client Secret** under **Certificates & secrets** ([docs](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app#add-credentials)) and note the secret **value** (not the Secret ID). Recommended expiry: 12 months
**Fabric Admin Portal settings** (must be enabled by a Fabric Administrator)
1. Navigate to **Fabric Admin Portal → Tenant settings → Developer settings**
2. Enable **Service principals can use Fabric APIs**
3. Scope to a security group containing the Orion Service Principal (recommended), or enable for the entire organization
**Workspace access:** Open the workspace containing your Warehouse, click **Manage access → Add people or groups**, search for the App Registration name, and assign the **Viewer** role (minimum). Contributor is recommended for full metadata access.
**Warehouse SQL endpoint:** Open the Warehouse in Fabric, click **Settings → SQL connection string**. The hostname looks like `xxxxxxxx.datawarehouse.fabric.microsoft.com`. Note the **Database** name (the Warehouse name).
**Credentials summary**
| Field | Description | Example |
| ------------------- | --------------------------------------------- | ---------------------------------------- |
| **Server Hostname** | SQL connection string from Warehouse settings | `xyz.datawarehouse.fabric.microsoft.com` |
| **Database** | Warehouse name | `my-warehouse` |
| **Tenant ID** | Entra ID Directory (tenant) ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| **Client ID** | App Registration Application (client) ID | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` |
| **Client Secret** | App Registration client secret value | *(sensitive)* |
**Enter the connection in Orion:** go to **Configuration → Data Sources**, click **Add Data Source**, choose **Microsoft Fabric Warehouse**, and enter the credentials from the table above.
Orion uses read-only SQL (`SELECT` only) to discover your schema via
`INFORMATION_SCHEMA`, run agent-generated queries, and stream results into its
analysis pipeline. It never executes DDL, DML, or stored procedures. If you
use dbt with Fabric, Orion can enrich metadata with dbt models and lineage;
see [dbt](#dbt).
[↑ Back to all data sources](#choose-your-data-source)
***
## Delta Lake
Orion connects to Delta Lake tables on **Azure Data Lake Storage Gen2** (`abfss://`) or **Google Cloud Storage** (`gs://`). Orion reads the Delta table directly via its transaction log. There is no warehouse, cluster, or notebook to provision.
You provide two things: a **Table URI** pointing at a Delta table folder (or a parent folder containing many Delta tables), and **credentials** with read access to that location.
Orion only performs read-only scans against your storage account / bucket: no
writes, no vacuums, no schema changes.
**Storage account access**
* The Table URI looks like `abfss://@.dfs.core.windows.net/`
* `` can point to a single Delta table folder (containing a `_delta_log/` subdirectory) or a parent folder; in the parent case, Orion exposes every Delta table found underneath
* Confirm **hierarchical namespace** is enabled on the storage account (required for `abfss://`)
**Credentials (pick one)**
Read-only and time-bounded ([docs](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview)).
Scope to the container, permissions read + list (`sp=rl`), expiry 90 days
or longer. Send the token query string (with or without a leading `?`).
Read/write, full access, only if SAS is not viable. Either the raw account
key, or the full connection string.
**What you enter in Orion** (under **Configuration → Data Sources → Add Data Source → Delta Lake**): Table URI (full `abfss://...` string), storage account name (required for SAS tokens), and one of SAS token or account key.
**Bucket access**
* The Table URI looks like `gs:///`
* As with Azure, `` can be a single Delta table folder or a parent folder containing many Delta tables
**Credentials (pick one)**
Create HMAC keys for a service account that has `roles/storage.objectViewer`
(or finer-grained access) on the target bucket.
Workload identity, with no secret to share. Grant the Orion workload
identity your contact provides `roles/storage.objectViewer` on the bucket.
**What you enter in Orion** (under **Configuration → Data Sources → Add Data Source → Delta Lake**): Table URI (full `gs://...` string), and one of HMAC key ID + secret, or confirmation from your Gravity contact that workload identity is configured.
**Parent-folder mode:** point the Table URI at a parent directory (e.g.
`abfss://.../silver/`) and Orion discovers every Delta table underneath on
schema sync. Partition columns need no setup; Orion reads them from the Delta
log for query pruning automatically.
[↑ Back to all data sources](#choose-your-data-source)
***
## dbt
If you use dbt, Orion can enrich an existing warehouse connection with your dbt model descriptions and lineage. You connect Orion to your dbt project's GitHub repository with a read-only fine-grained access token.
1. Navigate to **Settings → Developer Settings → Personal access tokens → Fine-grained tokens**
2. Click **Generate new token**
3. Set your organization as the resource owner (if required)
4. Configure permissions: **Contents** → Read access (**Metadata** is auto-added)
5. Under **Repository access**, select **Only select repositories** and add your dbt project repo only
6. Click **Generate token**, then copy and save it immediately; it won't be shown again
1. In Orion, go to **Configuration → Data Sources**
2. Click the data source tile you want to enrich, then click **Edit**. (The same options appear when first adding a data source.)
3. Check **Add schema enrichment for enhanced metadata** and select **dbt project**
4. Set **dbt Source Type** to **GitHub Repository**
5. Enter the **Repository URL** (your dbt project's GitHub URL) and **Personal Access Token**
6. Click **Save Changes**
![A data source in edit mode with schema enrichment enabled and dbt project selected]()
Make sure there's no trailing slash at the end of the Repository URL.
**dbt Source Type** also supports **dbt Cloud** (host URL, environment ID,
and auth token) and **Upload manifest.json** if you'd rather not connect
the GitHub repository.
Standard dbt projects only require these two fields, **Repository URL** and
**Personal Access Token**. Additional fields are optional.
[↑ Back to all data sources](#choose-your-data-source)
***
## News API
Orion can search news headlines and fold them into an analysis as a dataset, useful for explaining external context behind a change in your numbers ("did coverage spike the week signups jumped?").
Register for a free API key at [newsapi.org](https://newsapi.org/register).
1. In Orion, go to **Configuration → Data Sources** and click **Add Data Source**
2. Select **News API**
3. Enter the key in **NewsAPI.org API Key** and click **Connect Data Source**
Enable News API on a project like any other data source, and users there can ask Orion to pull articles by keyword from the last 1 to 30 days. Results come back with date, title, source, and summary, as a dataset the analysis can correlate against your own data.
News API is a single tenant-wide connection; once added, the tile shows
**Already connected**.
[↑ Back to all data sources](#choose-your-data-source)
***
## Weather
The Weather source pulls daily weather from Open-Meteo. No account or API key is needed: add it from **Configuration → Data Sources → Add Data Source → Weather** and click **Connect Data Source**.
Enable it on a project and users can ask for weather by location and date range: historical actuals back to 1940 and forecasts up to about 16 days out, with conditions, high and low temperatures, and precipitation. The data lands as a dataset the analysis can join against your business data, which is what you want for questions like "do cancellations track with bad weather?"
[↑ Back to all data sources](#choose-your-data-source)
# Knowledge Base
Source: https://docs.runorion.com/core-concepts/knowledge-base
Give Orion the business context it needs to be right
The Knowledge Base is a centralized feature that helps provide Orion with all of your business and analytical context. Think of it as a system for storing all the company information you might provide a new employee during onboarding to help them get up to speed.
![Knowledge Base page with editor]()
## What is the Knowledge Base?
The Knowledge Base uses a traditional wiki-style file and folder structure so you can organize pages of context within folders. It serves as a single source of truth for:
* **Company Context** - Information about your organization, industry, and business rules
* **Metrics & Definitions** - How your company defines key metrics and terminology
* **Standard Operating Procedures (SOPs)** - Step-by-step processes and workflows
* **Analytical Methods** - How to perform certain analyses, calculations, and methodologies
* **Product Documentation** - Details about your products, services, and features
* **Guidelines & Best Practices** - Standards and recommendations for your team
## How Orion Uses Your Knowledge Base
When you enable Knowledge Base pages for a project, Orion will:
* **In Chat** - Use that context for better answers and analysis throughout your conversation
* **In Deliverables** - Include small in-line source citations in reports, slide decks, and dashboards for wiki pages that were referenced
* **In Updates** - Accept suggestions to update wiki pages with new information
The more comprehensive and well-organized your Knowledge Base, the better Orion can tailor its analysis to your specific needs and processes.
## Organization
It's recommended that you create folders based on how your company normally organizes information, such as by department, and then within that, by certain use cases, activities, or scopes.
**Example structure:**
```
Sales/
├── Pricing
├── Contracts
└── Customer Stories
Operations/
├── Payroll Process
├── Returns Policy
└── Escalation Procedures
Product/
├── Features
├── API Documentation
└── Release Process
```
Name folders and files in a way that is as easy to understand for Orion as it would be for a new hire.
## Key Features
Organize content in nested folders (up to 3 levels deep) that mirror your
company structure
Create and edit pages using a markdown editor with live preview
Upload spreadsheets, text files, and documents that automatically convert to
pages
Reorganize pages and folders by dragging them around
Track changes and see who updated pages and when
Enable specific pages for projects to keep Orion focused on relevant context
## Getting Started
To get started with the Knowledge Base:
1. Navigate to the **Knowledge Base** tab in your tenant
2. Create your first folder or page
3. Organize your content into folders that match your company structure
4. Enable pages for projects that should have access to them
Start with essential documentation like company information, key processes,
and business definitions. You can expand your Knowledge Base over time.
## Knowledge Base vs. Project Files
The key difference between Knowledge Base pages and project file uploads:
* **Knowledge Base pages** - Designed for structured, concise context (metrics, definitions, procedures, guidelines) that Orion uses throughout chat and analysis
* **Project file uploads** - Designed for long-form, unstructured documents like dense PDFs with images, charts, and complex text
## Next Steps
Learn how to create and manage Knowledge Base pages
Tips for building an effective Knowledge Base
Connect Knowledge Base pages to your projects
Learn when to use file uploads vs. Knowledge Base pages
# Projects
Source: https://docs.runorion.com/core-concepts/projects
The workspace holding a team's chats, data, and context
Projects serve as the primary organizational mechanism in Orion. Each project brings together your [Chat Conversations](/chat/basics-navigation) and [Analyses](/chat/running-analyses), along with all the context that supports them: [Knowledge Base](/core-concepts/knowledge-base) pages, [data sources](/configuration/data-sources), [uploaded files](/chat/file-uploads), [memories](/chat/memory), and other project-specific details.
## Personal vs Shared Projects
When you create a new project in Orion, it is automatically ***private*** by default until you share it with other team members.
* **Personal (Private) Projects:** Any analyses, insights, or conversations within the project are only accessible by you (aside from admins).
* **Shared Projects:** Projects shared with 1 or more team members. Only those with access to the project can view the contents.
## Creating a Project
![Create new project dialog in Orion]()
### Project Name
Give your project a descriptive name that reflects its purpose (e.g., "Marketing Strategy", "Q4 Sales Analysis", "Customer Churn Research").
### Project Description
The project description helps you and your team quickly understand what the project is about. This short description (up to 500 characters) appears in the project list and is intended for human readers. To give Orion richer context for its analysis, use [Knowledge Base](/core-concepts/knowledge-base) pages.
## Next Steps After Creating a Project
Once you have created a new project, it will appear in the left-hand navigation menu and on the main projects page.
Click into your new project to complete the setup. A dialog will appear prompting you to select a data source for the project. A project must always be connected to at least one data source to work.
![Get started with new project dialog showing data source selection]()
### Selecting a Data Source
The next modal displays a list of available [data sources](/configuration/data-sources) that have been connected by your Admin. Select one by enabling the toggle switch.
![Select data source modal with available data sources]()
### Accessing Project Settings
The Project Settings modal is always accessible by:
* Clicking the **Settings** button in the top right corner of your screen, or
* Clicking the three dots on the project item in the left-hand navigation menu and selecting **Project Settings**
From Project Settings, you can:
* Update the project name and description
* Change the selected data source at any time
## Starter Deliverables (Project Kickstart)
Tenants with Project Kickstart enabled get a running start on new projects. Once a project has a data source plus some context to aim at, Orion offers to explore the data on its own and generate four starter deliverables:
* A **slide deck**
* An interactive **dashboard**
* **Key metrics**, three to five tracked values chosen from your data
* A **narrative report**
The deck, dashboard, and report are saved as rerunnable [Workflows](/core-concepts/workflows), so they can be refreshed on a schedule from day one.
### How it triggers
On a fresh project, a banner counts down ten seconds before starting, with a **Cancel** button if you'd rather begin your own conversation. Kickstart runs at most once per project.
Orion needs something to focus on before it will offer: a [Knowledge Base](/core-concepts/knowledge-base) page, a project description, or project instructions. Without any of those, the banner instead prompts you to add context first.
### Turning it off
To opt a project out, open the project's settings, go to the **Advanced Settings** tab, and enable **Disable automatic starter deliverables**.
Project Kickstart is enabled per tenant. If you don't see the countdown
banner on new projects, it isn't switched on for your tenant.
## Memory Isolation
Memory isolation is enabled by default for all new projects.
When memory isolation is enabled, any memories formed by Orion within this project remain contained to the project itself. These memories will not be accessible in other chat conversations or analyses outside the project.
**Disabling memory isolation** allows memories formed within this project to be accessible across other projects. This is useful when you want Orion to recall memories from one project in order to inform work in another.
## Enabling Knowledge Base Pages
The Knowledge Base is the recommended way to provide your project with structured, organized context. By enabling [Knowledge Base](/core-concepts/knowledge-base) pages for your project, Orion gains access to your organization's centralized documentation.
From the Project Settings modal, click on the **Knowledge Base** tab to enable pages for this project.
![Knowledge Base tab in project settings modal]()
### How to Enable Pages
1. Browse or search for Knowledge Base pages in the catalog
2. Enable the pages you want Orion to have access to for this project
3. Save your changes
**By default**, Orion has no access to any Knowledge Base pages until you explicitly enable them.
### Best Practices for Knowledge Base in Projects
* **Keep it focused** - Enable 8-10 pages maximum per project to keep Orion focused on relevant context
* **Enable strategically** - Only enable pages that are directly relevant to this project's analysis
* **Stay organized** - Use your Knowledge Base folder structure to find related pages
When you enable Knowledge Base pages, Orion will:
* Include them throughout its analysis workflow
* Cite them with inline references in your reports, dashboards, and other deliverables
* Reference them throughout your chat conversations
* Use them to inform analytical decisions and methodology
Knowledge Base pages provide the foundation of structured context that Orion
uses across chat and analysis. Combine them with file uploads for
comprehensive context coverage.
## Uploading Files to a Project
In addition to Knowledge Base pages, you can upload files to provide Orion with detailed reference materials and long-form documentation. From the Project Settings modal, click on the **File Uploads** tab.
![File uploads tab in project settings modal]()
### When to Use File Uploads
Project file uploads are ideal for **long-form, unstructured documents**, especially:
* **Dense PDFs** - Research reports, whitepapers, or detailed analyses
* **Documents with images and charts** - Anything with visual content or complex formatting
* **Transcripts and notes** - Meeting recordings, interview transcripts, or detailed notes
* **Complex layouts** - Documents that are difficult to structure into Knowledge Base pages
File uploads are primarily used within chat conversations for specific reference and research, rather than being integrated throughout your analysis workflow like Knowledge Base pages.
### Supported File Types
Orion currently supports the following file formats for project document uploads:
* **Markdown** (.md, .markdown)
* **PDF** (.pdf)
* **Word Documents** (.docx)
* **Plain Text** (.txt)
Excel spreadsheets are not currently supported for file uploads, but we're
actively working on adding Excel support in an upcoming release. For
spreadsheet data, consider uploading to the Knowledge Base as structured pages
instead.
#### Common Examples of Project Files:
* Research reports and whitepapers
* PDF analyses and detailed documentation
* Meeting transcripts and interview recordings
* Competitor analysis documents with images
* Industry reports and market research
Use file uploads for dense, reference-heavy documents. Use Knowledge Base
pages for structured, reusable context that Orion should consistently apply to
your project.
## Comparing Knowledge Base Pages and File Uploads
Both provide context to Orion, but serve different purposes:
Structured context (metrics, definitions, procedures) used throughout chat
and analysis workflow
Long-form documents (PDFs, transcripts, historical reports) used for
specific reference in chat
## Cloning Projects
Within shared projects, you have the ability to clone projects. This is useful when you want to reuse the same project settings, data sources, and file uploads from an existing project.
For example, if you're using a project for customer-facing analytics reporting and want to use the same project configuration for a new use case, you can simply clone everything from the original project.
![Clone project option in project dropdown menu]()
Memories from an isolated project will not automatically copy into a cloned
project. Each cloned project starts with its own isolated memory.
## Sharing Projects
You can share projects two ways: directly with individual users, or by sharing them with a [Group](/configuration/groups).
### Sharing with individuals
To share a project with one or more users, click the share button in the upper right-hand corner of the project interface.
![Share button in upper right corner of project interface]()
Shared projects enable collaboration and allow you to work together with your team members on analyses.
### Sharing with a Group
If your tenant uses [Groups](/configuration/groups), you can give access to a project by sharing it with a group. Everyone in the group can access the project, with permissions matching their role in the group, so there is no need to invite members individually.
If a group has been given access to the project, Project Settings lists it on the **Details** tab. Administrators see every group with access; everyone else sees only the groups they belong to.
![Project Settings modal showing the Groups with access section listing groups that share the project]()
Direct invites and group access work side by side. Removing someone from a group doesn't cancel any direct invite they have on the project, and removing a direct invite doesn't remove them from the group.
## Project Permissions
Orion supports three tenant roles with varying levels of access. If your tenant uses [Groups](/configuration/groups), users also have a group role that may further shape what they can do within a specific project. See [Groups → Roles at a Glance](/configuration/groups#roles-at-a-glance) for a full breakdown.
Can control who has access to projects. Admins can assign users to projects
from the Manage Users tab and have full control over project access.
Can do just about anything within a project, including chatting with the
project and sharing projects. The only limitation is that analysts cannot
add existing users to other projects.
Can view projects that have been approved and view insights that have been
approved. Viewers have read-only access to approved content.
# Search
Source: https://docs.runorion.com/core-concepts/search
Find anything in your workspace with Cmd+K
Global search lets you find anything in your Orion workspace from a single input. Open it from the sidebar or with a keyboard shortcut.
## Opening Search
* Click **Search** in the left sidebar, or
* Press **⌘K** (Mac) / **Ctrl+K** (Windows/Linux)
Press **Esc** to close.
![Global search showing results for 'cost' across Projects, Artifacts, and Conversations]()
## Filtering Results
By default, search returns results across all content types. Use the filter tabs at the top of the panel to narrow to a specific type:
| Filter | What it searches |
| -------------- | ------------------------------- |
| All | Everything below, combined |
| Projects | Project names |
| Artifacts | Reports, slides, and dashboards |
| Conversations | Chat messages within projects |
| Knowledge Base | Wiki pages |
| Metrics | Tracked metrics |
| Workflows | Scheduled workflows |
## Reading Results
Results are grouped by content type. Each result shows:
* **Name**: the title of the item
* **Type badge** (artifacts only): Report, Slides, or Dashboard
* **Date**: when the item was last updated or created
* **Match count** (conversations only): number of matching messages within that conversation
When no query is typed, search shows recent items for the active filter.
## Keyboard Navigation
| Key | Action |
| ----- | ------------------------ |
| ↑ / ↓ | Move between results |
| Enter | Open the selected result |
| Esc | Close search |
# Workflows
Source: https://docs.runorion.com/core-concepts/workflows
Automate a recurring analysis and the delivery of its results
A Workflow is an automation. It takes an analysis you have already validated, re-runs it on a schedule, and delivers the result to whoever needs it, without anyone opening Orion to make it happen.
They scale with the job. The simplest is one analysis, one schedule, one email. A larger one queries several sources, produces a slide deck and a CSV, decides for itself whether the numbers are worth flagging, and mails different people depending on the answer. Between those two extremes sits most of what a data team currently does by hand every Monday morning.
The recipe is fixed, and that is the point. A Workflow re-runs the notebook you already checked rather than working the analysis out from scratch each time, so the same queries and the same transformations produce this week's numbers. You are not asking a question twice and hoping the answers are comparable.
Workflows are in beta, marked **v2 Beta** in the product. Existing Workflows
keep running, but expect the interface to keep moving.
## Notebook vs Workflow
A Workflow starts from work you have already done in [Chat](/chat/basics-navigation). Get the analysis right there first, then automate it.
| | Notebook | Workflow |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------------ |
| How it is created | Captured automatically as an analysis runs | Built from a notebook you choose to save |
| When it runs | When you ask Orion to re-run it in chat | On a schedule, or on demand |
| Output | Results inline in your conversation | Reports, exports, or both, refreshed in place each run |
| Who sees it | You, and anyone you share the conversation with | Anyone with project access, plus whoever the Workflow emails |
## What a Workflow is Made Of
Open a Workflow and it lays itself out as a graph of steps, running top to bottom.
![Workflow view showing a graph of connected steps: a Scheduled Run trigger, the analysis it runs, slide deck and podcast outputs, a CSV export, and an email notification step]()
* **Trigger**: when the Workflow runs. A schedule, or you pressing Run Now.
* **Analysis**: the notebook that does the work. This is the recipe, frozen at the version you validated.
* **Outputs**: what gets produced. A report, a slide deck, a dashboard, an audio briefing.
* **Exports**: data rather than narrative, such as a CSV of the underlying rows.
* **Notification**: who hears about it, and what gets attached.
Click any step to configure it. The set of steps is not fixed either, so a Workflow can grow new outputs and notifications as the need appears.
Opening a Workflow requires Analyst or Admin on the project. Viewers cannot
open one at all, not even read-only. Your level can come from a group, so
being a Viewer elsewhere in Orion does not necessarily mean you are one here.
See [Project Permissions](/core-concepts/projects#project-permissions).
## Finding Your Workflows
Each project has a dedicated **Workflows** page listing everything in one place. You get to it from the project page: scroll to the **Workflows** strip below Shared Metrics and Published Content, and click **View all**. The strip itself shows only the six most recently run, and it is the way in, so it is worth knowing where it sits.
![A project page with the Shared and Yours toggle near the top and the Workflows section highlighted at the bottom, below Shared Metrics and Published Content. The section carries a v2 Beta badge, a View all link, and one entry listing a weekly schedule, a succeeded status, and a last run two days ago]()
The Workflows page is where you actually work with them. **Shared** and **Yours** tabs separate the project's Workflows from your own, and you get search, card and list views, and sorting by name, creation date, or most recently run.
![The dedicated Workflows page with Shared and Yours tabs, card and list view toggles, a sort control set to Created, and a search field. Four workflow cards each show a preview of the workflow's graph, its name, creator, schedule, and last run]()
Each card previews the Workflow's graph, so you can tell a one-step report from a branching automation before opening anything, alongside its name, who created it, its schedule, the outcome of the last run, and when that run happened. A Workflow that has never run says so.
Workflows are also indexed in [Search](/core-concepts/search) under the Workflows filter.
A Workflow starts out private to its creator, which is why a new one appears under **Yours** rather than **Shared**. See [Sharing and Permissions](/workflows/manage#sharing-and-permissions) for how to change that.
## Next Steps
Turn a finished analysis into an automation, in the dialog or by asking
Formats, templates, publish URLs, and who gets emailed
Schedules, run history, change history, and editing
Decision steps and using metrics as the source
How to build automations that keep working
# Edit a Dashboard
Source: https://docs.runorion.com/dashboards/edit
Change a dashboard by pointing at what is wrong
Dashboards are edited by telling Orion what to change, aimed at the exact element you mean. There are two surfaces for it.
## Editing from chat
With the dashboard open in its panel beside the chat, click **Edit**. The cursor becomes a crosshair, and clicking any card, heading, or text element selects it and offers a **Comment** button.
Your comments collect in a panel, so you can send them together. Click more elements and write what to change about each one. For example, "make this a bar chart", or "this title should say Q3". Then click **Send**. Orion applies the whole batch, the canvas refreshes itself, and edit mode exits. If the result is not correct, send a follow-up reply in the same thread.
Edit mode is off by default, so filters and charts stay interactive until you ask for it.
You can also skip the pointing entirely and just ask in chat: "change the dashboard title to Q1 2026 Report".
## The dashboard editor
A dashboard also has its own editor. From the project page, open the dashboard card's menu and choose **Edit Dashboard**. The **Edit** button on a published dashboard's page opens the same editor.
You cannot drag a card to a new position, and you cannot resize or delete one by hand. Orion builds each dashboard on a layout it writes itself, so the layout is not a grid you rearrange. A banner at the top of the editor says the same thing.
What the editor gives you instead is a way to aim an instruction. Click a card to select it, then describe the change. Every structural change goes through the chat panel, including moving a card, removing one, or reordering a section.
The editor header holds **Save** and **Discard**, an unsaved-changes indicator, and a **Chat** button that docks Orion beside the canvas.
Highlight any text on the dashboard and an **Ask Orion** pill appears, attaching your selection to the next chat message. It is the fastest way to say "this number looks wrong" about the number itself.
Save before asking the chat for an edit. Orion works from the saved version
of the dashboard, and the editor warns you if there are unsaved changes.
## Who can edit
Editing requires edit access on the project: Analysts, Admins, and the project owner. Viewers can [explore](/dashboards/explore) but not change.
# Filter and Explore
Source: https://docs.runorion.com/dashboards/explore
Narrow a dashboard to the slice you care about
Everything on this page works for every project member, including Viewers. No edit access is needed to explore a dashboard.
## Filters
When a dashboard defines filters, a filter bar sits at the top:
* **Date range**: opens a calendar bounded to the dates actually present in the data, with the available range shown underneath. Coarser data swaps the day calendar for From and To pickers at its own grain, month or year.
* **Multiselect**: a checkbox list of the values in the data. The button reads **All** or **N selected**.
* **Numeric range**: **Min** and **Max** inputs, with the data's real range as a guide.
Those three are the whole set. There is no free-text search, and no relative-date preset such as "last 30 days". A dashboard filters on dates, categories, and numeric ranges only.
A **Clear** button appears at the end of the bar whenever any filter is active. A dashboard can also open with a filter already applied, which is why **Clear** sometimes shows before you have touched anything.
![A dashboard with its filter bar outlined in red, holding three controls: Date Range reading All months, Region reading All, and Office Status reading 2 selected, followed by a Clear button. The Region dropdown is open below the bar, listing an unchecked checkbox for each value in the data, from Metro Central through Rural West]()
A date filter over month-grain data, showing the From and To pickers and the range actually available:
![A dashboard with its Date Range filter open and the contents of the dropdown outlined in red: empty From and To month inputs side by side, each with a calendar button, above a line reading Data: Jul 2024 to Jun 2026]()
Filters recompute the dashboard. They do not only hide rows. KPI values, charts, and aggregated tables are recalculated exactly over the filtered dataset. Two caveats show up as labels on the dashboard itself:
* A card that ignores the filters carries a **Not filtered** badge. Hover it to read why that card was left out.
* Narrative and headline text is written from the full dataset, and says so, rather than silently pretending to match your filter.
A **Not filtered** badge is always deliberate. The author must declare each unfiltered card and give a reason for it. The badge never means that someone missed a card. The tooltip gives that reason. Usually the card answers a question that the filters would distort. Examples are a year-to-date total, a benchmark, or a figure from a different source.
![A dashboard where one card, titled Backlog Build vs. Identity Review Rate, carries a small Not filtered badge in its top left corner, outlined in red. The neighbouring cards carry no such badge]()
## Charts and tables
Charts support hover tooltips and clickable legends for isolating series. Tables sort by column, resize, and scroll smoothly at any row count.
Clicking a mark rather than hovering it starts an [investigation](/dashboards/investigate) into that specific number.
## Sharing a filtered view
On a dashboard's own page, active filters are written into the page URL. Copy the browser URL and the recipient opens the dashboard with your exact filter state applied.
# Investigate
Source: https://docs.runorion.com/dashboards/investigate
Click a number to find out why it moved
Filters narrow a dashboard. Investigate explains it.
Click a single value. Orion recomputes that number from the source data. It compares the number with the period before, if one exists. It also breaks the number into its parts. The answer opens in a rail beside the dashboard.
This is not the chat panel. Investigate returns a fixed set of computed facts with their provenance, and declines when the math will not hold up rather than guessing.
## Starting an investigation
Click any mark on a card:
* A point on a line chart
* A bar, including a single segment of a grouped or stacked bar
* A pie segment
* A row in a table
* A KPI tile
The rail opens on the right. The dashboard stays live behind it, so filters and other cards keep working while an answer loads.
![A dashboard with the Investigate rail open over its right edge and the whole rail outlined in red. The rail is headed Applications in Queue and shows the clicked value, how the latest month compares with the one before, and a breakdown by region. The dashboard behind it stays fully rendered rather than shrinking to make room]()
Scatter plots, heat maps, waterfall charts, and box plots are not clickable.
Their marks have no mapping back to a measure, so Investigate is unavailable
on those cards.
## What the answer contains
The rail shows the clicked value immediately, then fills in each computed part as it arrives:
* **The value**: the number recomputed from the source data, not read off the chart
* **Change**: the same measure for the previous period, with the delta and percent change. An incomplete period is compared against the prior period truncated to the same elapsed point, labeled "vs same point in"
* **Signal**: whether the change is a real shift or ordinary variation, judged against the measure's recent history. A sustained shift also reports when it began
* **Breakdown**: which members the number is made of, or which ones moved it. The two are different, and the rail says which one you are looking at
* **Provenance**: the snapshot it was computed from, when it was computed, and which filters were in scope
Color follows the measure, not the arrow. A fall in churn reads as good, a fall in revenue does not.
Where a card offers more than one breakdown dimension, each appears as a chip under the heading. Selecting one reshapes the breakdown in place, without starting a new investigation.
![A dashboard with the Investigate rail open for a KPI called Applications in Queue, and the breakdown portion of the rail outlined in red. Under a heading reading What makes up this number, Region name and Office status are offered as chips with Region name selected, followed by six rows from Metro South down to an Other row, each carrying a count and a percent share. The clicked KPI tile on the dashboard behind is ringed to show where the answer came from]()
## Scope is frozen at the click
An investigation captures the dashboard's filters at the moment you click, so the answer cannot drift while you read it. Chips at the top of the rail show that frozen scope and where each part of it came from.
Change the dashboard filters while the rail is open and a **Filters changed** marker appears. The answer on screen still describes the scope you originally clicked.
## Following the thread
Each answer suggests its own next questions as chips, either a further breakdown or a trend over time. A chip is named for what it will do, like **By Region**. Click a chip to run a new investigation in the same rail. A trail across the top shows where you have been, such as `Actual › Acute`. The **X** at the top right closes the investigation.
For any other question, use the footer. It asks **How was this number made?** and offers **Ask Orion why**. That button sends the current scope to chat.
## When Orion declines
Investigate withholds an answer rather than produce a number it cannot stand behind. The reason is always specific:
| What you see | What it means |
| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| No earlier period to compare against. | There is no prior period in the data at this grain |
| This slice is too small to break down safely. | Splitting it further would rest on too few rows |
| Averages, ratios, and distinct counts can't be split into parts that add up. Ask Orion to compare segments. | The measure is not additive, so a contribution breakdown would be false |
| There is nothing interesting to explore here. | The recomputed value did not reconcile with the displayed one |
| The breakdown is temporarily unavailable. | A transient failure. This one offers **Retry** |
More than one can appear at once, each in its own card. **Ask Orion why** remains available underneath in every case.
![A dashboard with the Investigate rail open and outlined in red. The rail is headed Avg Review Rate and shows the value and a line comparing the latest month against the one before, but in place of a breakdown it carries a single card reading that averages, ratios, and distinct counts cannot be split into parts that add up, suggesting Ask Orion to compare segments]()
The example above is an average. Its value and its movement both resolve, and only the breakdown declines, because a share-of-total split of an average would not add up. Parts of an answer fail independently.
## Who can use it
Anyone who can open the dashboard, including Viewers. Investigate only reads data, it never changes the dashboard. See [Filter and Explore](/dashboards/explore) for the other controls that need no edit access.
# Dashboards
Source: https://docs.runorion.com/dashboards/overview
Build an interactive, filterable view of an analysis
A dashboard is an interactive layout of KPI tiles, charts, tables, and narrative text built from one of your analyses. A report or a slide deck fixes its numbers in place. A dashboard does not. You can filter it, [investigate any number on it](/dashboards/investigate), and every card recalculates.
A dashboard is the product of one analysis, so it carries that analysis's results until the analysis runs again. To keep it current on a recurring basis, make it a [Workflow](/workflows/create) output, and every scheduled run updates it in place.
Reach for a dashboard when people will come back to the same numbers repeatedly. Reach for a report or deck when the finding is the point. See [Workflow Outputs](/workflows/outputs) for that comparison in full.
![A published dashboard titled Regional Service Centers, opening with a dark header that carries the reporting period, duration, office count and headline totals, and a filter row with Date Range, Region, and Office Status dropdowns. Below it, three highlighted KPI tiles for median wait, applications in queue, and worst-case wait, then four more KPI tiles, then a Turnaround and Backlog Trends section holding a line chart of median turnaround by month beside a combination chart of backlog against review rate]()
## Creating a Dashboard
There are three ways to get one:
### From the output picker
Ask for something to share, but do not say what kind. Orion runs the analysis. Then it offers **Choose an output format**, with **Report**, **Slides**, **Dashboard**, and **Pinned Metrics**. Pick **Dashboard**, and Orion builds one from the analysis it just ran.
The picker is not automatic. A question answered in chat does not raise it on its own. It appears when Orion has a result to package and no format has a name yet.
![A finished analysis in chat, ending with Orion asking which format works best. Below it, outlined in red, a card headed Choose an output format offers four illustrated tiles: Report, Slides, Dashboard, and Pinned Metrics]()
### By asking
Ask in chat: "make me a dashboard of this", or "build a dashboard showing revenue by region with a date filter". If you ask before running an analysis, Orion runs the analysis first, so generation takes longer. A placeholder grid with a progress bar shows while the dashboard is assembled.
### As a Workflow output
Choose **Dashboard** as the output format when [creating a Workflow](/workflows/create). The Workflow keeps one dashboard at one URL. Each scheduled run refreshes the data and rewrites the narrative text from the new numbers. The layout and the filters stay the same. Until the first run completes, the dashboard's card on the project page shows **Result pending**.
## Working with the result in chat
The finished dashboard appears in the chat as a thumbnail card. Click the card, or its **Expand dashboard** button. The dashboard opens in a panel beside the chat. There you can use the [filters](/dashboards/explore), [investigate a number](/dashboards/investigate), publish the dashboard, or [edit it](/dashboards/edit).
If you iterate on the same dashboard across a conversation, Orion marks the older thumbnails as superseded, so you always know which card is current. When the dashboard is already open next to the chat, edits confirm with a compact **Dashboard updated** chip and the canvas refreshes on its own.
Every dashboard appears on the project page as soon as it is created, visible
**Only You** until you share it. Publishing and visibility are covered in
[Publish and Share](/dashboards/publish).
# Publish and Share
Source: https://docs.runorion.com/dashboards/publish
Give a dashboard a stable link and decide who sees it
A new dashboard is visible **Only You** until you publish or share it. Publishing gives it a stable link. Visibility controls whether it sits on the project's shared board.
## Publishing
Click **Publish** in the dashboard panel or editor. The dialog asks for:
* **Name**: the name of the dashboard in the list
* **Custom URL**: the link slug, `/share/` plus a name auto-suggested from the title. Edit it to something recognizable, like `revenue-overview`
Publishing copies the link to your clipboard, and the button becomes **Share Link** for grabbing it again later.
Share links require an Orion login and project access. They are for
teammates, not the open internet.
Anyone who opens the link gets the full interactive dashboard. This includes the [filters](/dashboards/explore) and an **Ask Orion** chat toggle. A project member with edit access also gets an **Edit** button.
## Visibility
Independently of the link, a dashboard is either **Only You** or on the **Shared Board**, where every project member sees it on the project page. Change it from the publish dialog or the dashboard card's menu on the project page.
## Managing from the project page
Published dashboards appear as cards on the project page with a live thumbnail and a **Dashboard** label. A dashboard that a Workflow maintains also carries a **Workflow** badge. Each card's menu offers **Open**, **Edit Dashboard**, **View Workflow** where one applies, **Visibility**, and **Delete**.
Deleting a published dashboard cannot be undone.
## Permissions
* **Viewers**: open shared dashboards and share links, use every filter. No publishing, editing, visibility changes, or deleting
* **Analysts**: create, edit, and publish dashboards. They also set the visibility of the dashboards they created
* **Admins and project owners**: manage visibility and deletion for anyone's dashboards
# Welcome to Orion
Source: https://docs.runorion.com/index
Ask your data questions in plain language, as a team
Orion is a collaborative analytics platform built by [Gravity](https://bygravity.com). Connect your data warehouse, ask questions in plain language, and share the resulting analyses, dashboards, reports, and slide decks across your team, all without writing SQL. Orion stores feedback through [Memory](/chat/memory) and learns your preferences over time, so each analysis gets faster and more accurate.
## Get Started
New to Orion? Start here to learn the fundamentals.
Organize your work with Projects - the primary organizational structure in Orion.
Learn the Chat interface and how to navigate Orion's conversation system.
Learn how to run analyses and get reports, dashboards, and other deliverables from Orion.
## Core Features
Explore Orion's powerful capabilities for data analysis and insights.
Orion captures each analysis as a notebook you can re-run any time for fresh results.
How Orion remembers project information and learns from your interactions.
Share chats and analyses with teammates so they can pick up where you left off.
Give Orion the business context it needs to produce more accurate, relevant results.
## Configuration & Setup
Customize Orion to work the way you do.
Connect and manage your data sources for analysis.
Set your personal preferences to tailor how Orion presents data and insights.
Configure company-wide settings and information.
Learn best practices for effective Chat conversations and analysis workflows.
## Need Help?
Reach out to our support team for assistance.
# Best Practices
Source: https://docs.runorion.com/knowledge-base/best-practices
How to write pages Orion actually uses well
## Keep Pages Short and Concise
Rather than creating one super long page, break your content into shorter, more focused pages. This helps Orion navigate and use your knowledge base more effectively.
**Better approach:**
* One page on metrics and definitions
* One page on a standard procedure for a specific analysis
* One page for additional context on a topic
* Separate pages for different processes or guidelines
Shorter, focused pages are easier for both humans and Orion to understand and
reference.
## Start With a Clear Summary
It's recommended that at the very top of each page, you provide a description or summary of what the page contains. The first 250 characters of your page are especially important because:
* Orion uses this text to quickly glance at what the page contains
* It helps determine whether the page is relevant for your analysis
* It acts like an executive summary for the page
**Example:**
```
# Sales Metrics Definitions
Our sales team uses these key metrics to measure performance and health. Updated monthly.
## ARR (Annual Recurring Revenue)
Total committed recurring revenue normalized to an annual value...
```
## Write for Clarity
**Do:**
* Use clear, plain language
* Use headers and formatting to break up content
* Include concrete examples
* Define acronyms and industry terms
* Name folders and files in a way that's easy to understand
**Don't:**
* Use dense paragraphs without structure
* Assume Orion knows your internal terminology
* Mix different types of content on a single page
* Leave pages incomplete or outdated
## Keep Content Current
Your Knowledge Base is only as valuable as the quality and accuracy of its content:
* Review your Knowledge Base quarterly
* Update pages when processes change
* Remove outdated or incorrect information
* Use revision history to track important changes
## Recommended Structure
Organize your folders around your company's natural structure and functions:
**Example organization:**
```
Company Information/
├── Mission & Values
├── Industry & Competitive Landscape
└── Key Contacts
Operations/
├── Sales Process
├── Contracts & Pricing
├── Customer Onboarding
└── Returns & Escalations
Finance/
├── Metrics & KPIs
├── Forecasting Methodology
└── Accounting Practices
Product/
├── Feature Definitions
├── Technical Specifications
└── API Documentation
```
## What to Document First
Start with the essentials that most affect Orion's analysis quality:
1. **Company Information** - Industry, size, geography, business model
2. **Key Definitions** - Important metrics, terminology, product names
3. **Core Processes** - How you operate, key workflows, decision criteria
4. **Data Definitions** - What your data represents, how it's calculated
5. **Guidelines** - Preferences for analysis, communication style, reporting format
## What to Add Later
As your Knowledge Base grows, expand with:
* Competitive intelligence
* Industry trends and context
* Historical decisions and reasons
* Standard templates and formats
* Advanced processes and edge cases
## Per-Project Context Management
When enabling knowledge base pages for a project, it's recommended to keep this between **8-10 pages maximum** per project. This approach:
* Keeps Orion focused on relevant context only
* Improves analysis quality by reducing noise
* Makes the system more effective at navigating your company's context
**Example per-project enablement:**
* **Sales Project** - Enable pages on: Pricing, Sales Process, Key Metrics, Contracts, Customer Definitions
* **Product Project** - Enable pages on: Feature Definitions, Technical Specs, API Documentation, Product Roadmap
* **Finance Project** - Enable pages on: Metrics & KPIs, Forecasting Methodology, Accounting Practices, Budget Guidelines
## Where Project Context Lives
Use the Knowledge Base as the home for company-wide context instead of pasting it into free-text boxes:
* Store your company-wide context in the Knowledge Base
* Enable relevant pages for each project
* Reuse the same pages across projects rather than re-typing context
This creates a more maintainable, reusable system where your context is documented once and enabled where needed.
# Creating & Managing Pages
Source: https://docs.runorion.com/knowledge-base/creating-pages
Write, upload, and organize Knowledge Base pages
## Creating a New Page or Folder
When you navigate to the Knowledge Base tab, you'll see a brand new Knowledge Base where you can start creating new folders and pages. On the left-hand side is your navigation panel.
**To create content:**
1. Right-click on the root or any folder to see options
2. Select **Create Page** or **Create Folder**
3. Enter a name for your content
4. Start editing (if creating a page)
## Folder Structure
You can create a hierarchical folder structure with a **maximum of 3 folder levels deep**. Within folders you can create as many pages as you want.
**Important naming rules:**
* ❌ You cannot have multiple folders with the same name in the root directory
* ❌ You cannot have multiple pages with the same name within a folder
This organizational approach keeps your Knowledge Base clean and prevents naming conflicts.
## Creating Pages
When you create a new page, you have two options:
1. **Write manually** - Use the markdown editor to type and format your content
2. **Upload a file** - Import existing documentation (see supported formats below)
### Supported File Formats for Upload
The Knowledge Base supports uploading:
* Text files (.txt)
* Markdown files (.md)
* Excel spreadsheets (.xlsx)
* CSV spreadsheets (.csv)
PDFs and images are not currently supported file types. For PDFs and complex
documents with images, use project file uploads instead.
When you upload a file, it will automatically be named with the name of the file you uploaded and converted to markdown format.
## Markdown Editor
The page editor provides a markdown editor with live preview. You can:
* Write your content in markdown
* See a live preview of your changes
* Format text, create lists, add headers, and more
* Save your changes when ready
## Key Information About Pages
The **first 250 characters** of your page are especially important. Orion uses this text to quickly understand what the page contains, so it's recommended to:
* Place a summary or description at the very top of the page
* Provide the most important context in those first 250 characters
* Think of it like an executive summary
## Editing & Managing Pages
### To edit a page:
* Click on the page in the left navigation to open it
* Click the **Edit** button in the top right corner
* Make your changes and save
### To rename or delete:
* Right-click on a page or folder
* Select **Rename** or **Delete**
If you try to delete a folder that contains pages, you'll get a warning. You
must first move the files out of that folder before it can be deleted. This is
a safety precaution to prevent accidentally deleting entire folders of
content.
## Organizing Your Knowledge Base
You can reorganize your Knowledge Base by **dragging and dropping** pages or folders into one another. This makes it easy to reorganize your wiki pages without having to recreate them.
## Revision History
We store the revision history of all your pages. In the top left corner above the editor, you can see who updated the page last and when. This helps track changes to your knowledge base over time.
## Locking Pages and the Change Request Flow
Pages can be **locked** to control who can make direct edits. Locking a page enables the change request workflow for that page.
![Knowledge Base page view showing the Unlocked button in the top right corner next to the Edit button]()
### Who Can Lock a Page
Only the **page creator** or an **admin** can lock or unlock a page. Use the lock toggle in the top right of the page view (next to the Edit button).
### What Happens When a Page Is Locked
* **Admins** can always edit and delete directly
* **Non-admins** (analysts, viewers) who edit a locked page submit a **change request** instead of saving directly
* The page creator and admins are notified of pending change requests
* The page's content is unchanged until the change request is approved
### Reviewing Change Requests
Admins and page creators can review pending change requests:
1. Open the page. A banner appears when there are pending requests
2. Click **Review** to see the proposed changes
3. **Approve** to apply the changes, or **Reject** to decline them
4. Optionally add a review note explaining the decision
![Review Changes screen showing a pending edit with a unified diff view, risk level badge, and Approve / Reject buttons]()
The review screen shows:
* **Pending / History** tabs: active requests and past decisions
* **Risk level**: Minor, Careful review, or No risk, based on how much content changed
* **Unified / Split diff**: toggle between views of what changed
* **Edit proposed changes**: modify the submission before approving
* **Show full content**: see the entire page in context
Change requests can also be **bulk approved** from the Change Requests panel in the admin settings.
### Change Request Statuses
| Status | Meaning |
| ------------- | ------------------------------------------------- |
| Pending | Awaiting review |
| Approved | Changes applied to the page |
| Rejected | Changes declined |
| Auto-approved | Applied automatically (low-risk or unlocked page) |
If you are the creator of a page, your own edits bypass the change request
flow even when the page is locked.
## Enabling Pages for Projects
To use Knowledge Base pages in a project:
1. Go to your project settings
2. Navigate to the **Knowledge Base** tab
3. Search for and select the pages you want to enable
4. Orion will have access to these pages when working on the project
By default, Orion has no access to knowledge base folders and files until you
explicitly provide access by enabling them within the project. This keeps
Orion focused on only the context needed for that specific project.
## Default Pages (Auto-Inject)
Administrators can mark a small set of pages as defaults that Orion includes automatically, without anyone enabling them per project. This is an opt-in setting made page by page; nothing is auto-injected until an admin selects it. There are two scopes:
* **Tenant-wide**: on the page itself, open the **...** actions menu and switch on **Project Default** (admins only). The page is included in every project in the tenant, and the sidebar marks it with a globe icon.
* **Per group**: in a [group's](/configuration/groups) **Knowledge Base** tab, each linked page has an **Auto-inject** switch. When on, the page is included in chat context for everyone in that group. Group admins and group analysts can manage this alongside tenant admins.
In a project's Knowledge Base tab, default pages appear pre-checked with a **Global Default** or **Group Default** badge. Projects can add more pages on top but can't opt out of defaults, so keep the set small: defaults ride along in every conversation in scope. Company-wide definitions and business rules belong here; everything else is better enabled per project.
# Knowledge Base
Source: https://docs.runorion.com/knowledge-base/overview
A wiki Orion reads from and cites during analyses
The Knowledge Base is a centralized feature that helps provide Orion with all of your business and analytical context. It's a flexible tool that uses a traditional wiki-style file and folder structure so you can organize pages of context within folders.
## What is the Knowledge Base?
Think of the Knowledge Base as a system for storing all the company information you might provide a new employee during onboarding to help them get up to speed. It serves as a single source of truth for:
* **Company Context** - Information about your organization, industry, and business rules
* **Standard Operating Procedures (SOPs)** - Step-by-step processes and workflows
* **Metrics & Definitions** - How your company defines key metrics and terminology
* **Product Documentation** - Details about your products, services, and features
* **Analytical Methods** - How to perform certain analyses, calculations, and methodologies
* **Guidelines & Best Practices** - Standards and recommendations for your team
When you enable Knowledge Base pages for a project, Orion will have access to this context and can reference it to provide more accurate and relevant insights.
## Organization Structure
It's recommended that you create folders based on how your company normally organizes information, such as by department, and then within that, by certain use cases, activities, or scopes.
**Example structure:**
```
Sales/
├── Pricing
├── Contracts
└── Customer Stories
Operations/
├── Payroll Process
├── Returns Policy
└── Escalation Procedures
Product/
├── Features
├── API Documentation
└── Release Process
```
There's no specific methodology that Orion prefers, but organize folders and files in a way that is as easy to understand for Orion as it would be for a new hire.
## Key Features
Structure your documentation with nested folders (up to 3 levels deep) and
unlimited pages
Create and edit pages using a markdown editor with live preview
Upload spreadsheets, text files, and documents that automatically convert to
pages (supports .txt, .md, .xlsx, .csv)
Reorganize pages and folders by dragging them around
Selectively enable pages for specific projects to keep Orion focused on
relevant context
Orion searches and references your knowledge base during analysis and chat
conversations
## Getting Started
To get started with the Knowledge Base:
1. Navigate to the Knowledge Base tab in your tenant
2. Create your first folder or page
3. Organize your content into folders that match your company structure
4. Enable pages for projects that should have access to them
Start with essential documentation like company information, key processes,
and business definitions. You can expand your Knowledge Base over time.
## How Orion Uses Your Knowledge Base
When you enable Knowledge Base pages for a project:
* **Chat & Analysis** - Orion uses that context for better answers and more accurate analysis throughout your conversation
* **Citations** - In your deliverables (reports, slide decks, dashboards), you'll see small in-line source citations for wiki pages that were referenced
* **Knowledge Updates** - You can ask Orion to update wiki pages with new information or changes
The more comprehensive and well-organized your Knowledge Base, the better Orion can tailor its analysis to your specific needs and processes.
## Knowledge Base vs. Project Files
The key difference between Knowledge Base pages and project file uploads:
* **Knowledge Base pages** - Designed for structured, concise context (metrics, definitions, procedures, guidelines) that Orion uses throughout chat and analysis
* **Project file uploads** - Designed for long-form, unstructured documents like dense PDFs with images, charts, and complex text
# External Wiki Integrations
Source: https://docs.runorion.com/knowledge-base/wiki-integrations
Import pages from Notion, Confluence, and GitHub
Connect external documentation sources to pull content directly into your Knowledge Base.
![]()
Notion
Import pages and databases using a Notion integration token
![]()
Confluence
Browse spaces and pages using your Atlassian email and API token
![]()
GitHub
Import markdown, text, and Word files from any accessible repository
## Adding an Integration
Integrations are managed by admins at the tenant level under **Configuration**.
1. Go to **Configuration** in the left-hand navigation
2. Select the **Knowledge Base** tab
3. Find the integration type (GitHub, Confluence, or Notion)
4. Click **+ Add connection** and enter your credentials
5. Save. Orion validates the connection before storing it
![Configuration > Knowledge Base tab showing GitHub, Confluence, and Notion integrations with existing connections and Add connection buttons]()
Once connected, the integration appears in the list with the connection name and date. Each connection can be renamed (pencil icon), browsed (link icon), or deleted (trash icon).
Only admins can add integrations. Connected integrations are available to all
users for browsing and importing content.
***
## ![]()
Notion
### Setup
Create a [Notion internal integration](https://www.notion.so/my-integrations) for your workspace, then click **+ Add connection** next to Notion in **Configuration → Knowledge Base**:
1. Enter your **Integration Token** (starts with `secret_`)
2. Give the connection a name
3. Save. Orion validates the token before storing it
You must explicitly share each Notion page or database with the integration inside Notion before Orion can access it (**Share** → **Connections** → select your integration).
### What You Can Import
* **Pages**: Imported as markdown with full formatting preserved
* **Databases**: Rendered as markdown tables with all visible properties
* **Child pages**: Browse into a page to see nested child pages and sub-databases
### Browsing
The root level shows all pages and databases shared with your integration. Click into a database to see its rows, or into a page to see child pages.
If a page isn't showing up, check that you've shared it with the integration
in Notion's **Connections** settings.
***
## ![]()
Confluence
### Setup
Generate a [Confluence API token](https://id.atlassian.com/manage-profile/security/api-tokens) from your Atlassian account, then click **+ Add connection** next to Confluence in **Configuration → Knowledge Base**:
1. Enter your **Base URL** (e.g. `https://yourcompany.atlassian.net`)
2. Enter the **Email** associated with your Atlassian account
3. Enter your **API Token**
4. Give the connection a name and save
### What You Can Import
* **Spaces**: Browse all available Confluence spaces
* **Pages**: Navigate root pages in a space, then drill into child pages
* **Page content**: HTML is automatically converted to markdown on import
### Browsing
The root level lists all spaces your token can access. Navigate into a space to see its root pages, then into each page to see children.
Use a dedicated service account token rather than a personal token so the
integration doesn't break if a user leaves the organization.
***
## ![]()
GitHub
### Setup
Create a [personal access token](https://github.com/settings/tokens) with `repo` scope (or `read:org` for organization repositories), then click **+ Add connection** next to GitHub in **Configuration → Knowledge Base**:
1. Enter your **Personal Access Token** (classic `ghp_` or fine-grained `github_pat_`)
2. Give the connection a name and save
### What You Can Import
Supported file types: `.md`, `.txt`, `.docx`
* **Repositories**: Browse all repos accessible to your token
* **Directories**: Navigate folder structures within a repo
* **Files**: Import individual markdown, text, or Word documents
### Browsing
The root level lists all repositories the token can access. Navigate into a repo to browse its directory structure and select files to import.
Fine-grained personal access tokens (`github_pat_`) scoped to specific
repositories are recommended over classic tokens for tighter security.
***
## Importing Content
Import from an external source when creating a new page in the Knowledge Base:
1. In the Knowledge Base, click **+** to create a new page
2. Select the **GitHub**, **Confluence**, or **Notion** tab at the top of the panel
3. Choose a connection from the dropdown (or click **+** to add a new one)
4. Browse the list of pages and select one. A preview loads on the right
5. Choose an import mode and click to import
![Import panel showing the Notion tab selected with a connection picker, page list, and markdown preview with Read & Write and Sync Only options]()
### Import Modes
When importing, you choose how Orion handles the page going forward:
| Mode | Behavior |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Read & Write** | Imports the content as a normal Knowledge Base page. You can edit it freely, and manually sync from the source at any time. |
| **Sync Only** | Keeps the page locked to the external source. Content updates automatically on a daily schedule. Manual edits are not allowed. |
Use **Sync Only** when the source is the authoritative version and you want the Knowledge Base to always reflect it. Use **Read & Write** when you want to import once and then own the content in Orion.
## Syncing Pages
To refresh a **Read & Write** page with the latest content from its source:
1. Open the page in the Knowledge Base editor
2. Click **Sync** in the top toolbar
3. The page content is overwritten with the current version from the source
**Sync Only** pages update automatically, with no manual action required.
Syncing overwrites the page content entirely. Any manual edits made since the
last sync will be lost.
## Managing Integrations
From **Configuration → Knowledge Base**, each connection has three actions:
* **Rename** (pencil icon): change the display name of the connection
* **Browse** (link icon): open the integration browser to import more content
* **Delete** (trash icon): remove the connection. Pages already imported are kept, but they can no longer be synced.
# MCP Server
Source: https://docs.runorion.com/mcp/overview
Let an AI assistant work with your Orion projects directly
The Orion MCP server lets AI assistants (Claude, Cursor, Windsurf, and any MCP-compatible client) interact directly with your Orion projects, metrics, workflows, and knowledge base using the [Model Context Protocol](https://modelcontextprotocol.io/). Point your client at `https://g.runorion.com/mcp`, authenticate with your Orion credentials, and start querying. No installation required.
## What You Can Do
With the Orion MCP server, your AI assistant can:
* **Ask data questions** - Send natural language questions to Orion and get AI-powered analysis
* **Monitor KPIs** - List metrics, check values, and detect anomalies across projects
* **Run workflows** - Trigger insight maker workflows and retrieve results
* **Access reports** - Read dashboards, slide decks, and reports as markdown
* **Search knowledge** - Query your organization's wiki and knowledge base
* **Manage conversations** - Create and continue Orion chat conversations
## Supported Clients
The Orion MCP server works with any MCP-compatible client, including:
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (CLI)
* [Claude Desktop](https://claude.ai/download)
* [Cursor](https://cursor.com)
* [Windsurf](https://windsurf.com)
## Next Steps
Connect your AI assistant to Orion in under a minute.
Browse the full list of available tools.
# Setup
Source: https://docs.runorion.com/mcp/setup
Point your AI client at Orion's remote MCP server
## Prerequisites
* An Orion account with login credentials
That's it. No installation required: Orion runs a remote MCP server that your AI assistant connects to directly.
## Server URL
```
https://g.runorion.com/mcp
```
## Connecting to Claude Code
Run the following command in your terminal:
```bash theme={null}
claude mcp add orion --transport http https://g.runorion.com/mcp
```
Then open Claude Code and authenticate:
1. Type `/mcp` in Claude Code
2. Select the **orion** server
3. Choose **Authenticate**
4. Sign in with your Orion credentials in the browser window that opens
## Connecting to Claude Desktop
1. Go to **Settings > Customize > Connectors**
2. Search for **Orion** in the Connectors search bar
3. Click to add the Orion connector
4. Authenticate with your Orion credentials when prompted
## Connecting to Cursor
1. Open Cursor Settings
2. Go to **MCP Servers**
3. Click **Add Server**
4. Set **Type** to `http`
5. Set **URL** to `https://g.runorion.com/mcp`
6. Authenticate with your Orion credentials when prompted
## Verifying the Connection
Once connected, ask your AI assistant to list your Orion projects:
> "List my Orion projects"
If the connection is working, you should see a list of projects you have access to.
The `ask_orion` tool is the primary way to run analyses. Orion's analyses take
1-2 minutes to complete, so your AI assistant will poll for results
automatically.
# Tools Reference
Source: https://docs.runorion.com/mcp/tools
Reference for every tool the MCP server exposes
The Orion MCP server exposes 20 tools organized into read-only and action categories. Each tool includes annotations so your AI assistant knows which tools are safe to call without confirmation.
## Action Tools
These tools create, modify, or trigger operations in Orion.
### ask\_orion
Send a natural language question to Orion and get an AI-powered data analysis response. This is the primary tool for interacting with Orion.
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------ |
| `message` | string | Yes | The question or analysis request |
| `user_id` | string | Yes | The user ID sending the message |
| `project_id` | string | No | Project ID to scope the analysis |
| `conversation_id` | string | No | Existing conversation ID to continue |
Orion performs multi-step analyses that take 1-2 minutes. After calling
`ask_orion`, use `get_conversation_history` to poll for the final response.
Wait at least 30 seconds between polls.
### create\_conversation
Start a new Orion conversation.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------- |
| `user_id` | string | Yes | The user ID creating the conversation |
| `project_id` | string | No | Project ID to scope the conversation |
| `title` | string | No | Title for the conversation |
### execute\_metric
Trigger execution of a metric to refresh its current value.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------ |
| `metric_id` | string | Yes | The metric ID to execute |
### run\_workflow
Trigger execution of a workflow (insight maker).
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------- |
| `workflow_id` | string | Yes | The workflow ID to run |
### delete\_artifact
Delete a slide deck, dashboard, or report artifact. This is a destructive action.
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------- |
| `artifact_id` | string | Yes | The artifact ID to delete |
## Read-Only Tools
These tools only read data and are safe to call without confirmation.
### list\_projects
List Orion projects the user has access to.
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | -------------------------------------- |
| `search` | string | No | Search text to filter projects by name |
| `limit` | integer | No | Maximum results (default 20) |
### list\_users
List all users in the Orion organization. Returns user ID, name, and role.
### list\_conversations
List chat conversations for a user.
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | ---------------------------- |
| `user_id` | string | Yes | The user ID |
| `project_id` | string | No | Filter by project |
| `limit` | integer | No | Maximum results (default 20) |
### get\_conversation\_history
Read messages from an existing Orion conversation. Use this to poll for results after calling `ask_orion`.
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------- |
| `conversation_id` | string | Yes | The conversation ID |
| `limit` | integer | No | Maximum messages (default 50) |
### list\_metrics
List metrics (KPIs) for a project.
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | --------------------------------- |
| `project_id` | string | Yes | The project ID |
| `pinned` | boolean | No | Filter to pinned/unpinned metrics |
### get\_metric
Get full metric detail including definition, Python code, data sources, and latest result.
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------- |
| `metric_id` | string | Yes | The metric ID |
### get\_metric\_results
Get historical execution results for a metric.
| Parameter | Type | Required | Description |
| ----------- | ------- | -------- | ---------------------------- |
| `metric_id` | string | Yes | The metric ID |
| `limit` | integer | No | Maximum results (default 20) |
### get\_metric\_insights
Get auto-detected metric insights showing significant changes and anomalies for a project.
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | --------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `change_threshold` | float | No | Minimum change to flag, 0.0-1.0 (default 0.2 = 20%) |
### list\_workflows
List workflows (insight makers) for a project.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------- |
| `project_id` | string | Yes | The project ID |
### get\_workflow
Get workflow detail including notebook data, sources, and metric references.
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | --------------- |
| `workflow_id` | string | Yes | The workflow ID |
### get\_workflow\_results
Get execution results for a workflow.
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
| `workflow_id` | string | Yes | The workflow ID |
| `limit` | integer | No | Maximum results (default 20) |
### list\_artifacts
List slide decks, dashboards, or reports for a project.
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | --------------------------------------------------------------------- |
| `project_id` | string | Yes | The project ID |
| `artifact_type` | string | No | Filter by type: `html_slides`, `html_dashboard`, or `markdown_report` |
### get\_artifact
Get the content of a slide deck, dashboard, or report as markdown.
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | --------------- |
| `artifact_id` | string | Yes | The artifact ID |
### search\_wiki
Search the Orion wiki/knowledge base.
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | ----------------------------- |
| `text` | string | Yes | Search text |
| `project_id` | string | No | Scope the search to a project |
| `limit` | integer | No | Maximum results (default 20) |
### list\_recommendations
Get AI-generated recommendations for a project with suggested analysis prompts.
| Parameter | Type | Required | Description |
| ------------ | ------- | -------- | ------------------------------------ |
| `project_id` | string | Yes | The project ID |
| `limit` | integer | No | Maximum recommendations (default 10) |
# Troubleshooting
Source: https://docs.runorion.com/mcp/troubleshooting
Fix the common MCP connection and result problems
## Connection Issues
### Authentication Fails
* Verify you are using valid Orion login credentials
* Try logging in to Orion directly at your organization's URL to confirm your account is active
* Clear your browser cookies and try authenticating again
### Client Cannot Reach the Server
* Confirm the server URL is `https://g.runorion.com/mcp`
* Check that there are no firewall or VPN restrictions blocking access
* Ensure your MCP client supports the `http` transport
## Tool-Specific Issues
### ask\_orion Returns Only an Acknowledgment
This is expected behavior. Orion's analyses are multi-step operations that take 1-2 minutes. The initial response is an acknowledgment. Your AI assistant should automatically poll `get_conversation_history` to retrieve the final analysis.
If the analysis never completes:
* Check that the `project_id` is valid and has connected data sources
* Verify the user has access to the specified project
* Try a simpler question to confirm the pipeline is working
### list\_artifacts Returns Empty
* Verify the project has published artifacts (dashboards, slides, or reports)
* Check that you are using the correct `project_id`
### Metric or Workflow Execution Fails
* Ensure the metric or workflow has valid data source connections
* Check that the underlying data source is accessible
* Try retrieving the metric or workflow details first with `get_metric` or `get_workflow` to inspect its configuration
# Managing Metrics
Source: https://docs.runorion.com/metrics/manage
Run, reschedule, and inspect a metric you already saved
Click any metric card to open its detail sheet. This is where a metric is run, scheduled, visualized, and retired. Opening a metric from the project board also puts its ID in the page URL, so you can share a link that opens straight to the metric.
## The Detail Sheet
From top to bottom:
* **State and visibility** - The state pill (Active, Paused, Error, Draft) and the Shared/Private toggle
* **Name and description** - Click the name to rename it inline
* **Run Now** - Executes the metric immediately. Most runs finish within a minute; slow ones keep running in the background
* **Current Value** - The latest result, rendered per the metric's visualization
* **Schedule** - When the metric refreshes automatically
* **Historical Results** - Up to 20 recent runs, expandable for table results
* **Query & Code** - The sources and transformation behind the value
* **Delete Metric** - Removes the metric and its entire run history
Viewers see a reduced sheet: the current value and history, without the run, schedule, code, or delete controls.
## Visualizing results
What you can adjust depends on the value type:
* **Numbers, percentages, currency** - Render as a large formatted value
* **Tables** - Get a chart-type toggle (table, bar, line, grouped bar, stacked bar, pie, scatter, combo, heatmap, waterfall, boxplot, offered when the data suits them) plus X and Y column selectors. A **Save Visualization** button appears once you change something
* **Field sets** - Render as a tile layout; a layout editor picks which fields show, their labels, and their format
Table results also have a **Download CSV** button that exports the full result set.
For anything beyond chart type and axes, ask Orion in chat: colors, titles, decimal places, prefixes and suffixes, and threshold lines (a marker line on the chart at a value you name, for example a red line at your SLA limit).
## Scheduling
The Schedule section offers **None**, **Hourly**, **Daily**, **Weekly**, **Monthly**, and **At times**:
* **Hourly** - Every 1, 2, 3, 4, 6, 8, or 12 hours, on the quarter hour you pick
* **Daily** - Choose days of the week, including presets for every day, weekdays, or weekends
* **Monthly** - A day of the month, 1st through 28th
* **At times** - Up to five specific times per day
Times are shown in your local timezone and converted automatically. The next scheduled run shows at the top of the section.
## Run history
**Historical Results** lists recent runs with their values; failed runs carry an error icon, and table results expand inline. **Select** enters a selection mode for deleting runs you don't want to keep.
Deleting run history is permanent, and so is deleting the metric itself.
## Query & Code
The **Query & Code** section shows each data source with its variable name. SQL sources render with syntax highlighting, a plain-language summary of what the query does, and a diagram of how data flows through it. Looker sources show the query structure and link back to Looker.
Sources and transformation code are read-only here. To change them, ask Orion in chat:
* "Update the metric to exclude internal accounts"
* "Fix this metric" (after a failed run, Orion repairs the code)
* "Change the metric's schedule to weekdays at 7am"
Orion dry-runs every change against real data before saving it.
## Metrics in chat
* **@-mention** a metric in any chat to bring it into the conversation
* Ask "how is this metric calculated?" for its lineage: sources, transformation, and how data flows between them
* Ask Orion to load a metric's history into an analysis to chart it over time or build it into a deliverable
When Orion discusses a metric, it renders the live metric card in the chat. Click the card to open the full detail sheet.
## Deleting a metric
**Delete Metric** removes the metric and all of its run history, permanently. If a Workflow or notebook references the metric, deletion is blocked and Orion lists the dependents, so you can't silently break a scheduled Workflow. See [Metrics as a source](/workflows/advanced#using-metrics-as-the-source) for how Workflows consume metrics.
## Permissions
* **Viewers** - See shared metrics, open the sheet, browse history
* **Analysts** - Everything: run, rename, schedule, visualize, delete. Sharing to the board is limited to metrics they created
* **Admins and project owners** - Can also change visibility on anyone's metric
# Metrics
Source: https://docs.runorion.com/metrics/overview
Track a number from an analysis over time
A metric is a value Orion tracks over time: revenue this week, active users, churn rate, or a whole table of results. Once created, a metric re-runs on its own schedule, keeps every result as history, and renders as a live card on the project board.
Where a chat analysis answers a question once, a metric keeps answering it. That makes metrics the building block for everything recurring in Orion: project boards your team checks daily, and [Workflows](/workflows/advanced#using-metrics-as-the-source) that read metric values on a schedule.
## What a metric contains
* **Data sources** - One or more queries, SQL or Looker, that pull the raw data
* **A transformation** - Python code that turns the query results into the tracked value
* **A value type** - A number, percentage, currency, string, table, or a small set of fields
* **A visualization** - How the card renders: big number, chart type, colors, labels
* **A schedule** - How often the metric refreshes on its own
* **Run history** - Every execution result, kept so you can see the value over time
Each metric shows a state pill: **Active**, **Paused**, **Error**, or **Draft**.
## Creating a Metric
Metrics are created in chat. Ask Orion to track something, and it builds the metric for you:
* "Track daily active users from BigQuery"
* "Create a metric from this SQL query"
* "Turn the revenue number from this analysis into a metric"
Before anything is saved, Orion validates the metric with a dry run against your real data and shows you the result. The metric is only created after you confirm.
The easiest path: run an analysis in chat first, then ask Orion to track the
number you care about. The metric inherits the validated logic from the
analysis.
### Orion Suggested metrics
Orion can also propose metrics proactively based on your project data. These carry an **Orion Suggested** badge and a banner explaining where they came from, with a **Hide from Shared Board** button if the suggestion misses.
## Shared and personal metrics
The project home page has two tabs:
* **Shared** - The shared board. **Shared Metrics** are visible to every project member.
* **Yours** - **Your Metrics**, everything you created, shared or not.
Every metric card has a visibility button: a single-person icon means **Private**, a multi-person icon means **Shared**. Click it to move a metric on or off the shared board; a confirmation dialog (**Add to Shared Board?**) makes the change explicit.
Visibility can be changed by admins, the project owner, or the metric's creator. Everyone else sees a lock explaining who can.
Sharing a metric is how it becomes a tile on the project board for the whole
team. If the board looks empty, check the **Yours** tab: metrics start out
visible only to their creator.
## Arranging the board
Shared metrics render in a four-column grid on the project page:
* **Reorder** - Drag a card to a new position
* **Resize** - Drag the handle in a card's bottom-right corner to change its footprint
* Layout changes save automatically
## Next steps
* [Managing Metrics](/metrics/manage) - The metric detail sheet: run, schedule, visualize, and delete
* [Metrics as a Workflow source](/workflows/advanced#using-metrics-as-the-source) - Drive scheduled Workflows from tracked metrics
* Metrics are indexed in [Search](/core-concepts/search) under the Metrics filter
# Email Digest
Source: https://docs.runorion.com/profile-settings/email-digest
Get a weekly summary of your projects by email
The Email Digest is a weekly automated email that summarizes the latest insights and activity from your selected Orion projects. Orion personalizes each digest to your role using your profile bio and any additional instructions you provide, so no manual report writing is required.
You can create multiple digests (one per project, say, or one for different audiences), each with its own schedule.
![Email Digest list view]()
## Create a Digest
![Email Digest create form]()
1. Go to **Settings → Email Digest**.
2. Click **Add New Digest**.
3. Fill in the form:
* **Digest Name**: a label for this digest (e.g. "Weekly Marketing Summary").
* **Your Bio**: Orion uses your profile bio to personalize the digest content to your role and preferences. You can edit it inline from this page, or update it in [Profile Management](/profile-settings/profile-management).
* **Additional Instructions** *(optional)*: free-text guidance Orion follows when writing the digest. Use this to focus on specific metrics, highlight anomalies, or set a preferred tone (e.g. "Prioritize conversion metrics and flag any week-over-week drops greater than 10%").
* **Selected Projects**: choose one or more projects. Orion draws insights from all selected projects when composing the digest.
* **Schedule**: pick a day of the week, delivery time, and timezone. Digests are sent weekly.
4. Click **Save Changes**.
At least one project must be selected and a name must be provided before you
can save. The digest will not send until it is enabled.
## Enable or Disable a Digest
Each digest has an **Enabled** toggle visible in the list view. Disable a digest to pause delivery without deleting your configuration. Re-enable it at any time to resume on the existing schedule.
## Edit a Digest
1. Go to **Settings → Email Digest**.
2. Click the icon next to the digest.
3. Update any fields, including the enabled state, schedule, projects, or instructions.
4. Click **Save Changes**.
## Send a Test Digest
Send yourself a one-off digest email at any time to preview the content before the next scheduled delivery.
1. Go to **Settings → Email Digest**.
2. Click the icon next to the digest.
3. Check your inbox. The test email arrives within a few minutes.
You must save your preferences before sending a test digest.
## View Digest History
1. Go to **Settings → Email Digest**.
2. Click the icon next to a digest to open the history drawer.
3. The drawer lists all previously sent digests with their sent timestamps.
## Delete a Digest
1. Go to **Settings → Email Digest**.
2. Click the icon next to the digest.
3. Confirm the deletion in the dialog.
Deleting a digest permanently removes it and stops all future scheduled deliveries immediately.
## How the Digest Content is Generated
When a digest is due, Orion:
1. Fetches recent insights and activity from your selected projects.
2. Uses your profile bio to understand your role, focus areas, and communication preferences.
3. Applies any additional instructions you've set to shape the content.
4. Generates a curated email summary and delivers it to the email address on your account.
The more context you provide in your bio and instructions, the more relevant and personalized the digest will be.
# Integrations & Connectors
Source: https://docs.runorion.com/profile-settings/integrations
Connect Slack, Google, and Fireflies to your account
Orion integrates with Slack (ask questions and start analyses from any channel), Google Calendar (share schedule context), Google Slides (auto-generate presentations from analyses), and Fireflies.ai (bring meeting transcripts into analyses). Connect them from **Settings > Connectors**.
## Accessing Integrations
To connect integrations to your account:
1. Go to **Settings**
2. Select the **Connectors** tab
This is where you can manage connections to external apps and services.
## Slack Integration
### What You Can Do
Connect Orion to Slack to:
* **Message Orion directly** - Type questions and requests in Slack
* **Use @ mentions** - Reference Orion with `@orion` in channels
* **Start analyses** - Kick off analyses and ask questions without leaving Slack
* **Stay in your workflow** - Get insights without switching applications
### Setup
The Slack integration requires two connections:
1. **Workspace Slack** - Connects your Slack workspace to Orion
2. **Individual account** - Links your personal Slack account to your Orion profile
Once connected, you can reference Orion in any channel or direct message to
ask questions or request analyses.
## Google Calendar Integration
### What You Can Do
Connect Orion to your Google Calendar to:
* **Share schedule context** - Allow Orion to see your upcoming and past events
* **Control privacy** - Specify which calendar events Orion can access
* **Enable automation** - Support for future calendar-based automations
### Permissions
When you connect Google Calendar, you can:
* Grant Orion access to specific calendars
* Choose which events to make visible
* Update permissions at any time
Orion respects your privacy settings. You control exactly which calendar
events are visible to Orion.
## Google Slides Integration
### What You Can Do
Connect Orion to Google Slides to:
* **Create presentations** - Have Orion generate slides directly
* **Publish automatically** - Push new slides to your Google Workspace
* **Access existing presentations** - Pull presentations from your workspace
* **Edit content** - View and edit presentations directly through Orion
### Requirements
The Google Slides integration requires:
* Access to your Google Workspace account
* Permission to create and edit presentations in your workspace
Use Google Slides integration to quickly generate reports, presentations, and
shareable insights from your analyses.
## Fireflies.ai Integration
### What You Can Do
Connect Orion to Fireflies.ai to bring your meeting record into chat:
* **Recall meetings** - "What did we discuss in the last meeting?" or "Show me my recent meetings"
* **Pull out decisions** - Action items, summaries, and outlines from any recorded meeting
* **Find the right meeting** - Search by title, check who attended, get the full transcript with speakers and timestamps
* **Feed analyses** - Fold meeting notes into an analysis as context
Orion uses your own Fireflies credentials, so it only sees meetings your Fireflies account can access.
### Setup
1. Go to **Settings > Connectors** and find **Fireflies.ai**
2. Click **Connect**
3. Paste your **Fireflies API Key** and click **Connect Fireflies**
Your API key is in your [Fireflies settings](https://app.fireflies.ai/settings#api). Once connected, the card shows the linked Fireflies account name and email.
# Profile Management
Source: https://docs.runorion.com/profile-settings/profile-management
Keep your account details and bio current
Update your profile information and customize how Orion knows you.
## Accessing Your Profile
To access your profile settings:
1. Click on your **user account icon** in the bottom left corner of the left-hand navigation menu
2. Select **Profile**
This will take you to `Settings > Profile`.
## Editing Your Profile
In your profile settings, you can update:
* **Name** - Your first and last name
* **Username** - Your unique username
* **Email** - Your email address associated with the account
## Profile Bio - Tell Orion About Yourself
The **profile bio** (also called "About Me" section) is one of the most important parts of your profile. This is where you tell Orion:
* **Who you are** - Your role and background
* **What you do** - Your responsibilities and focus areas
* **Your preferences** - Your communication style and analysis preferences
The more detailed your profile bio, the better Orion can personalize your
experience. Include information about your communication preferences and what
types of analysis you typically need.
## Why Your Profile Matters
Your profile information helps Orion:
* **Enhance the [chat](/chat/basics-navigation) experience** - Provide responses tailored to your role and communication style
* **Personalize analyses** - Create insights that align with your specific needs and preferences
* **Improve accuracy** - Better understand context and nuances relevant to your work
# User Onboarding & Invitations
Source: https://docs.runorion.com/profile-settings/user-onboarding
Bring a new teammate into your tenant
Learn how to invite new team members to your Orion tenant and guide them through the account creation process.
## Inviting a New User
To add a new user to your Orion tenant:
1. Navigate to **Settings** in your tenant
2. Select **Manage Users**
3. Enter the new user's email address
4. Choose the permission level to assign them
5. Send the invitation
Only tenant administrators can invite new users.
## Account Creation Process
Once you send an invitation, the new user will receive an email with instructions. Account creation is a two-step process.
### Step 1: Account Details
The new user clicks the invitation link and enters:
* First name
* Last name
* Username
* Password
The email address is pre-filled from the invitation and cannot be changed. If they need a different email, they must request a new invite from an admin.
### Step 2: LinkedIn Profile (Optional)
After setting up their account details, the new user is prompted to add a bio. Orion uses the bio to personalize insights and analysis.
They can either:
* **Paste a LinkedIn profile URL**: Orion will automatically research the profile and generate a bio, including their current role, company, and key interests.
* **Write a bio manually**: Enter a short description of their role and focus areas directly.
* **Skip for now**: Proceed without a bio and add one later via [Profile Management](/profile-settings/profile-management).
Adding a LinkedIn URL is optional but recommended. It allows Orion to tailor
analysis to the user's role and context without any manual writing.
## Getting Started
After account creation, the new user is automatically redirected to `runorion.com`. They can then:
1. Log in with their new credentials
2. Access the tenant
3. Start exploring projects and using Orion
# User Preferences
Source: https://docs.runorion.com/profile-settings/user-preferences
Set the default chart type for your analyses
Set your personal preferences to tailor how Orion presents data and insights to you.
## Accessing User Preferences
To access your preferences:
1. Go to **Settings**
2. Select the **Preferences** tab
## Visualization Preferences
Your visualization preferences determine how Orion formats data when creating tables and charts in your insights and chat conversations.
![Visualization preferences settings showing different chart type options]()
### Available Visualization Options
Choose your preferred visualization type from:
* **Table View** - Standard tabular format
* **Bar Chart** - Simple bar chart visualization
* **Grouped Bar Chart** - Multiple series displayed as grouped bars
* **Stacked Bar Chart** - Stacked bar format for comparative analysis
* **Pie Chart** - Pie chart format for part-to-whole relationships
* **Scatter Plot** - Scatter plot for correlation analysis
* **Combo Chart** - Combined chart with multiple chart types
* **Heat Map** - Color-coded heat map visualization
### How Preferences Affect Your Experience
Your selected visualization preference will influence:
* **Chat insights** - The types of charts you see when asking Orion questions
* **Analysis results** - Default visualization formats for Orion's analyses
* **Data presentations** - How Orion presents data in responses (subject to underlying data compatibility)
Your visualization preference is a default setting. Individual analyses may
use different visualizations when appropriate for the specific data and
analysis type.
# Quickstart
Source: https://docs.runorion.com/quickstart
From first login to your first analysis in about 15 minutes
Orion is an AI-powered analyst: you ask questions in plain language and it queries your data and returns results inline. This guide takes you from logging in to your first analysis in about 15 minutes, then shows what you can do with the result.
If you have joined a shared test or demo workspace, it may already include
example projects, pinned metrics, and dashboards. Open them to see finished
output, then run your own analysis using the steps below.
## Step 1: Open a project
A [Project](/core-concepts/projects) is the primary unit of work in Orion. It bundles your chats, analyses, data sources, and context together.
Pick an existing project from the left-hand navigation, or create a new one.
A project must be connected to at least one [data source](/configuration/data-sources) to run an analysis. New projects prompt you to select from the sources your administrator has connected.
## Step 2: Ask your first question
Open [Chat](/chat/basics-navigation) inside the project and ask a question in plain language. Orion writes and runs the query, returns results inline, and captures the analysis as a [notebook](/chat/running-analyses#what-is-a-notebook) you can re-run any time.
Not sure what is in your data yet? You do not need to know the tables behind it. Start by asking Orion to [explore what is available](/chat/best-practices#explore-data-first), for example:
* "What data can you see?"
* "Tell me a little about the data that's available."
Once you know what is there, ask a specific question:
* "What were our top 10 customers by revenue last quarter?"
* "Show churn by product line over the last 90 days."
* "Compare this month's signups to the same period last year."
Be specific and give context. Clear questions and explicit guidance produce
better results. The more context you provide upfront, the less you have to
correct later.
## Step 3: Refine the result
Your first pass usually gets you most of the way. Ask follow-up questions, request edits, or adjust formatting until the result is right. Each correction also teaches Orion through [Memory](/chat/memory), so it gets faster over time. See [Best Practices](/chat/best-practices) for getting sharper results with less back-and-forth.
## Step 4: Put the result to work
Once an analysis is right, reuse it or turn it into a [deliverable](/chat/running-analyses#what-you-can-do-after-an-analysis):
* **Refresh the numbers** by simply asking Orion in chat to re-run the notebook. It pulls the latest data, no rebuilding required.
* **Turn the notebook into a workflow** to run it on a schedule or trigger an alert when a value crosses a threshold.
* **Generate a report or slide deck** to package the findings for stakeholders.
* **Pin a metric** to surface a key number as a tile on your project page, then publish it as a shared pinned metric.
* **Publish a dashboard** to hand a finished result to a business user.
* **Share it** with a teammate so they can pick up where you left off. See [Sharing conversations](/chat/share-conversations).
* **Set up an email digest** for a weekly AI-generated summary of the project's insights. See [Email digest](/profile-settings/email-digest).
## Next steps
The full analysis lifecycle and what you can produce from it
Get sharper results with less back-and-forth
Give Orion the business context it needs
Organize work and set project-level context
# Advanced Workflows
Source: https://docs.runorion.com/workflows/advanced
Decision steps and using metrics as the source
Most Workflows are a straight line: run the analysis, produce the output, email it. These two features are for the ones that are not.
## Decision Steps
A decision step is a point where the Workflow judges the results and decides what happens next. It is what turns a Workflow from something that always does the same thing into something that responds to what it found.
The mechanics are simple. Steps can be marked **conditional**, which means they do not run on their own. A decision step then reads the run's results and decides whether to release them. Nothing meaningful happened this week, and the report is written but the email never goes out. Churn crossed the line you care about, and it does.
You write the criteria in plain language, the same way you write a notification preference. The difference is scope: a notification preference gates one email, while a decision step can gate several steps at once, including reports and exports rather than just notifications.
A decision runs at one of two points:
* **After dependencies**, before the outputs are generated. Use this to skip producing something entirely when it is not warranted.
* **After reports**, once the artifacts exist. Use this when the judgment depends on reading the finished output.
You control what the decision gets to look at: metric values, notebook outputs, and for late decisions the finished reports and exports. Give it the context the judgment actually needs and no more, since a decision reading everything is slower and no sharper.
If all you want is "email me only when something changed", write it as a
notification preference instead. See [Notification
Preference](/workflows/outputs#notification-preference). Reach for a decision
step when the condition has to gate more than one thing.
## Using Metrics as the Source
A Workflow normally runs a notebook. That is the recommended default and what you get from the Create Workflow dialog.
There is a second option. If you have a set of tracked metrics and what you want is recurring reporting on those specific numbers, a Workflow can read the metrics directly instead of re-deriving them in a notebook. The Workflow becomes a reporting layer over numbers Orion already tracks, rather than an analysis of its own.
Each metric in the Workflow has a **refresh** setting, and it is off by
default. With refresh off, the run uses the metric's last known value rather
than querying for a current one, which means a daily Workflow can email
yesterday's number without anything appearing to be wrong. Turn refresh on
for any metric whose freshness matters.
This is the main thing to get right when using metrics as a source. A notebook-sourced Workflow queries your data on every run by definition. A metric-sourced one only does if you tell it to.
# Workflow Best Practices
Source: https://docs.runorion.com/workflows/best-practices
How to build automations that keep working
A Workflow runs unattended, often for months, in front of people who will not check whether it still makes sense. That changes what "good" means compared to a one-off analysis.
## Get the Analysis Right First
Automating a wrong analysis produces the wrong answer on a schedule, and now it has an audience. Run it in chat, read the numbers, sanity-check a total you already know, and only then save it.
The dry run Orion does before saving proves the recipe executes. It does not prove the recipe is correct. That part is yours.
## Write It Evergreen
Orion rewrites hardcoded dates during [the evergreen check](/workflows/create#the-evergreen-check), but it is cheaper to write them that way from the start. Ask for "the last 30 days" rather than a specific window, and say the word "evergreen" in your original request. See [Use Relative Dates](/chat/best-practices#use-relative-dates).
The same applies to anything else pinned to the moment you happened to run it: a specific customer ID you were investigating, a file you uploaded once, a region you filtered to because it was the one with the problem that day.
## Match the Format to the Reader
The format is not decoration, it is who the thing is for.
* A **dashboard** suits a number someone checks between meetings.
* A **slide deck** suits a recurring meeting where the analysis gets presented.
* A **markdown report** suits findings that need an argument rather than a chart.
* A **podcast** suits people who will genuinely listen and would never open the deck.
* A **CSV export** suits anyone who is going to do their own work with the rows.
If you cannot name the person who reads it, the Workflow probably should not exist yet.
## Be Deliberate About Notifications
The fastest way to make a Workflow ignored is to email everyone every run. Once people learn the email rarely matters, they stop opening it, including the week it does.
Set a notification preference so a run only lands in someone's inbox when it is worth their attention. Send different things to different people rather than one email to everybody: a summary to leadership, the full deck and the data to the team who has to act.
Reserve the whole-project distribution list for the ones that genuinely warrant it.
## Name It for Someone Else
The person who most needs to understand a Workflow six months from now is not you. "Weekly Executive P\&L Analysis" survives a handover. "Untitled report" and "P\&L v3 final" do not.
The same goes for publish URLs. `weekly-revenue` is a link someone can recognize in a bookmark bar. Set it once, early, because [changing it later breaks every link already shared](/workflows/outputs).
## Check In Occasionally
Automations fail quietly. A data source loses reachability, a schema changes underneath, credentials expire, and the Workflow keeps its schedule while producing nothing useful.
Worth a periodic look:
* Runs marked **Partial**, which succeed loudly and fail quietly at the same time.
* Metric-sourced Workflows with **refresh** off, which report stale numbers without erroring. See [Using Metrics as the Source](/workflows/advanced#using-metrics-as-the-source).
* Schedules still running for meetings that no longer happen.
Setting a schedule to **None** stops the runs and the emails while keeping the recipe and its history, which is almost always better than deleting.
## Let It Grow
Start with one analysis, one schedule, one recipient. Add the CSV when someone asks for the rows, the second notification when a different audience appears, a decision step when you notice you only care in certain weeks.
Workflows built that way tend to reflect how the work is actually done. Workflows designed in full up front tend to reflect how someone once imagined it might be.
# Create a Workflow
Source: https://docs.runorion.com/workflows/create
Turn a finished analysis into a scheduled automation
Every Workflow starts from an analysis that already works. Run it in [Chat](/chat/running-analyses), check the numbers, then automate it. Automating a wrong analysis just produces the wrong answer on a schedule.
## Two Ways In
Click **Create Workflow** in the notebook panel, or ask Orion in chat. Both call the same thing underneath, so pick whichever is faster in the moment.
**Asking** is quickest when you already know what you want. In the chat where the analysis ran: "save this as a workflow that runs every Monday at 8am and outputs a dashboard." It also handles schedules the dialog cannot express, like running at several specific times a day.
**The dialog** is the guided version. Open the notebook panel in Chat. At the top you will find **Save as a Workflow**. Click **Create Workflow**.
![A chat with the Analysis Notebook panel open on the right. The Save as a Workflow section and its Create Workflow button sit at the very top of that panel, highlighted, above the notebook's variables, referenced metrics, data extractions, and executed cells]()
## The Dialog
It asks for three things.
Pick Hour, Day, Week, or Month. Week adds a day picker, Month adds a day of
the month, and Hour asks only for the minute it should fire on. Your local
timezone is preselected.
Choose **Markdown Report**, **Slide Deck**, or **Dashboard**. This is the
format the Workflow starts with, not a permanent choice. See [Outputs and
Delivery](/workflows/outputs).
Describe in plain language what makes a run worth an email, for example
"only notify me if revenue changes by more than 10%". Leave it blank to
decide later.
![Create Workflow dialog showing the run frequency, time and timezone pickers, the Markdown Report, Slide Deck and Dashboard format choice, and a plain language notification preference field]()
## What Orion Builds
Submitting the dialog writes exactly the kind of request you would have typed and sends it to Orion, which is why the two routes behave the same.
From there Orion assembles the recipe. Only cells that ran cleanly make it in, so anything that errored is left behind. It then does a full dry run end to end before saving. If that dry run fails nothing is saved and Orion tells you what broke, which is the point: a Workflow that cannot complete once will not complete on a schedule either.
Workflows normally take a notebook as their source, which is what the dialog
produces. If what you actually want is recurring reporting on a set of
tracked metrics, a Workflow can read those directly instead. See [Using
Metrics as the Source](/workflows/advanced#using-metrics-as-the-source).
## The Evergreen Check
A Workflow that hardcodes last quarter's dates would keep reporting last quarter forever, so Orion reviews the analysis for that before saving. You do not have to ask.
The check looks for hardcoded dates and date ranges, filter values and IDs that came from your specific session, and hardcoded file paths, and rewrites them to relative equivalents: a fixed `2026-01-01` cutoff becomes a rolling window.
Writing the analysis that way from the start is still cheaper than having it corrected. See [Use Relative Dates](/chat/best-practices#use-relative-dates).
## Next Steps
Choose formats, set a publish URL, and decide who gets emailed
Schedules, run history, and editing what you built
# Manage Workflows
Source: https://docs.runorion.com/workflows/manage
Schedules, run history, change history, and editing a Workflow after it exists
Once a Workflow is running, most of your time with it is spent on four things: making it run, checking that it did, seeing what someone changed, and changing it yourself.
## Running and Scheduling
The **Scheduled Run** step at the top of the graph is the trigger. It shows the cadence, the time, and the timezone the Workflow runs in, along with the date of the next run. Open it to change any of them.
The schedule offers None, Hourly, Daily, Weekly, Monthly, and At times. A few details worth knowing:
* **Daily** lets you restrict which days actually run, so weekdays-only is a daily schedule with the weekend deselected.
* **Hourly** runs on an interval, from every hour up to every 12 hours, on a minute you pick.
* **At times** runs at several specific times in the same day rather than on an interval.
* **None** disables the schedule without deleting the Workflow or its history. Run Now still works.
* Times display in your local timezone and are stored converted, so a schedule set in New York does not drift for a teammate in London.
* Schedule changes are not saved until you confirm them.
**Run Now** in the header triggers an immediate run without touching the schedule. Use it to confirm a change worked, or to refresh a number ahead of a meeting. Runs happen in the background, so the result appears once it completes rather than instantly.
## Run History
The status in the header opens the run history. Each entry shows the outcome, **Succeeded**, **Failed**, **Partial**, or **Running**, and whether it was scheduled or a manual run, so you can tell an automated result from one someone triggered by hand.
![The Workflow header with its run status highlighted, and the Run History panel it opens listing eleven runs, each showing a succeeded status, how the run was triggered, and how long ago it happened]()
Open a run to see its steps. Each step reports whether it completed and how long it took, and steps that produced something carry a **View** link straight to that artifact.
![Run Details panel showing a succeeded scheduled run that took three minutes and forty-eight seconds, broken into three completed steps with per-step durations and a View link on the step that produced slides]()
When a run fails, the failure surfaces on the Workflow entry in the list. Open the failed step to see the error that stopped it. Common causes are a data source that went unreachable, a schema change, or credentials that expired. See [Troubleshooting](/mcp/troubleshooting#metric-or-workflow-execution-fails).
**Partial** means some steps finished and others did not, so it is always worth opening to see which.
## Change History
Run history tells you what the Workflow did. **Revision History** tells you what people did to it.
Every save writes a revision recording who made it, a summary of what changed, and when. Changing a notification's recipients, switching an output format, or adjusting the schedule each leave a trace. On a Workflow that several people maintain, this is how you answer "why is this suddenly emailing the whole company" without guessing.
## Editing a Workflow
Click any step to open its configuration. The trigger holds the schedule, each output step holds a format and its latest result, and the notification step holds the message and its recipients. You can add steps too, so a Workflow that only writes a report today can gain a CSV export or a second notification later.
The analysis step in the middle is the recipe. It shows the notebook name, how many cells run, and a badge for each kind of data source the cells query, which is the fastest way to see what a run touches without opening the code.
### In Chat
Some things are easier to describe than to click. **Open in Chat**, at the bottom right of the graph, drops you into the project chat with the Workflow already referenced and a prompt started for you.
![Project chat input prefilled with a request to change a workflow, the workflow itself shown as a reference chip inside the message]()
You can do the same from scratch in any project chat by typing `@` and picking the Workflow, the same way you reference a metric or a Knowledge Base page.
Chat is not only for changes. Referencing a Workflow and asking about it works too: what it queries, why last Tuesday's run looked different, what would happen if you changed the window to 90 days. You get an answer without editing anything.
## Sharing and Permissions
A Workflow starts out private to its creator and appears under **Yours**. **Move to Shared Board** hands it to the rest of the project, **Make Private** pulls it back. Either one is on the entry's actions menu, and admins can do it to any Workflow while everyone else can only do it to their own.
Editing anything at all requires Analyst or Admin on the project. See [Workflows](/core-concepts/workflows#what-a-workflow-is-made-of) for what Viewers can and cannot reach.
## Working With Workflows Elsewhere
The [MCP server](/mcp/overview) exposes Workflows to AI assistants like Claude Code and Cursor. You can list them, read their configuration, trigger runs, and pull execution results. See [MCP Tools](/mcp/tools#run_workflow).
## Deleting a Workflow
Delete removes the Workflow and its entire run history, and cannot be undone. If your goal is only to stop the emails and the scheduled runs, set the schedule to **None** and clear the notification's recipients instead. That keeps the recipe and its history intact so you can start it again later.
# Outputs and Delivery
Source: https://docs.runorion.com/workflows/outputs
What a Workflow produces and how it reaches people
A Workflow run produces artifacts and then delivers them. Those are two separate decisions: what gets made, and who ends up looking at it.
A Workflow can carry several outputs at once. The same run can write a slide deck for the meeting, an audio briefing for the commute, and a CSV for whoever wants the underlying rows. Each is its own step on the graph with its own settings.
## Formats
A written report. Best for narrative findings someone will read top to
bottom.
A styled web page of charts and tables. Best for numbers people check at a
glance.
A presentation. Best for recurring meetings where the analysis gets
presented rather than read.
An audio briefing of the same analysis. Best for people who will listen on
the way to work but never open the deck.
You can change an output's format later. The next run regenerates it from scratch in the new format.
## Data Exports
An export is data rather than narrative. Where a report interprets the numbers, an export hands over the rows.
An export step points at a DataFrame your notebook produced, by variable name, and writes it out under a filename you choose. Each export gets its own publish URL, and can be attached to a notification alongside the reports, so the same email can carry the narrative and the raw data behind it.
Reach for one when the recipient is going to do their own work with the numbers: a finance team that wants the line items in a spreadsheet, or a downstream process that reads the file on a schedule.
## Report Configuration
Opening an output step gives you its **Report Configuration**, which controls how the result is written and where it lands.
* **Report Style**: formatting, structure, length, tone, and emphasis, in plain language. This is the main lever for what the output reads like. "Executive summary, one page max" and "five slides for a board meeting" both belong here.
* **Publish URL**: the address the result is published at, `/share/` plus a slug you choose. Set it to something recognizable like `weekly-revenue`.
* **Report Visibility**: who inside the project can view the result.
* **Context Sources**: the notebooks behind the report, plus any [Knowledge Base](/core-concepts/knowledge-base) pages you attach as ground truth.
Because the Publish URL is stable and every run republishes to it, one link stays current forever. That is what makes a Workflow worth handing to someone who will never open Orion.
Changing the slug moves the report. Links you have already shared point at
the old address and will stop working.
### Templates
Report Style controls how the writing reads. A **template** controls how a slide deck looks. Attach one and every run comes back in the same layout and theming, which matters once the same deck goes to the same meeting every week and people navigate it from memory.
Templates are optional and are saved per project. Set one from **Artifact Template** in an output step's Report Configuration. You get them two ways: upload an HTML file, or generate a deck you like in chat and use **Save as template** to keep it.
## Notifications
When a run finishes, a Workflow can email the result out. Open the **Notification** step to control what gets sent and who gets it:
* **Message**: the body of the email that goes out, which you write yourself.
* **Artifacts**: which of the Workflow's outputs and exports get attached. Each report and export is a checkbox, so a Workflow that produces three things can send all three or just one.
* **Recipients**: who receives it, chosen as **Users**, **Groups**, or **Emails**. Users covers people already on the project, searchable by name or email, and Groups covers the project's groups. Emails takes any address you type, which is how you reach someone outside the project.
![Notification Configuration panel showing the message body, three artifact checkboxes for two reports and one export, and recipient tabs for Users, Groups, and Emails with a member search field]()
A Workflow can have more than one notification step, which is how you send a short summary to executives and the full deck plus data to the team that has to act on it.
### Notification Preference
Recipients control who gets email. A **notification preference** controls when. Write it in plain language when you create the Workflow and Orion turns it into a condition evaluated on each run:
* "Only notify me when there is a significant change"
* "Only if churn goes above 5% or a new anomaly shows up"
* "Always notify me"
A Workflow with no condition set notifies on every run. For conditions that gate more than a single email, see [Decision Steps](/workflows/advanced#decision-steps).
Delivery is email only. Workflows do not post to Slack, Teams, or SMS. For a
broader summary of a project's activity, see [Email
digest](/profile-settings/email-digest).