Setup Guide
Connect Your Jira Projects to Omnio View
Everything you need to have in place on the Jira side before and during the OAuth connection process. Less than 10 minutes from start to finish.
In this guide
Overview
Omnio View connects to your Jira Cloud workspace via Atlassian OAuth 2.0 (3-legged). When you click Connect Jira in the setup wizard, you are redirected to Atlassian to authorise access. This guide covers everything you need to have in place before and during that process.
App owners only: Before any new admin can connect, the OAuth app must be set to Sharing in the Atlassian Developer Console. If this hasn't been done, new admins will see "You don't have access to this app."
Prerequisites
1. An Atlassian Cloud account
Omnio View connects to Jira Cloud only (not Jira Data Center or Server). You need an active Atlassian account with access to at least one Jira Cloud site (e.g. yourteam.atlassian.net).
If your organisation uses Jira Data Center or Server (self-hosted), Omnio View cannot connect to it. Contact your Jira administrator about migrating to Jira Cloud or setting up a Cloud instance.
2. Project-level permissions
Omnio View can only read projects that your Atlassian account has access to. Before connecting, confirm you have the following Jira permissions on each project you want to track:
| Permission | Why Omnio View needs it | How to check |
|---|---|---|
| Browse Projects | Lists your projects in the setup wizard and reads issues, sprints, and boards | Can you open the project board in Jira? If yes, you have this. |
| View Development Tools (optional) | Used if you connect GitHub later for commit/PR metrics | Check Project Settings → Permissions in Jira |
If you cannot see a project in Jira, you will not see it in Omnio View either. Ask your Jira administrator to add you to the project's role or permission scheme.
3. Board configuration (Scrum projects)
If your project uses a Scrum board, Omnio View pulls sprint data (active sprint, velocity, scope changes). For this to work:
- The board must have at least one sprint created (active or completed).
- Story points should be estimated using the Story Points field (Jira's built-in field).
- If you use a different estimation field, Omnio View may not pick up velocity data.
For Kanban or Service Desk projects, no special board configuration is needed — Omnio View fetches all issues directly.
Step-by-step: connecting Jira
Expect two clicks, not one. Due to an Atlassian quirk, if you are not already signed into your Atlassian account, the first click on "Connect Jira" will sign you in but land you on the Atlassian home page instead of the consent screen. Simply go back to Omnio View and click "Connect Jira" a second time.
1 Sign into the correct Atlassian account first
Before starting, make sure your browser is signed into the correct Atlassian account — the one that has access to the Jira projects you want to track.
- Go to id.atlassian.com and check which account is active.
- If it's the wrong account, sign out and sign in with the correct one.
- If you have multiple Atlassian accounts, use an incognito/private browser window and sign into Atlassian first.
Why this matters: Omnio View's redirect uses whatever Atlassian session your browser already has. If the wrong account is active, you will authorise the wrong workspace. Atlassian maintains separate sessions across its domains, so logging out of one does not always log you out of the others.
2 Sign in to Omnio View
In the same browser (or incognito window), go to your Omnio View instance and log in. The setup wizard launches automatically after your first login.
3 Click "Connect Jira" (may need two attempts)
On the Jira step of the setup wizard, click the teal Connect Jira button.
- If you are already signed into Atlassian (Step 1): the consent screen should appear immediately. Skip to Step 4.
- If you are not yet signed in: Atlassian will ask you to sign in. After signing in, Atlassian may drop you on
home.atlassian.cominstead of the consent screen. Go back to Omnio View and click "Connect Jira" again.
4 Authorise Omnio View in Atlassian
Atlassian will show a consent screen listing the permissions Omnio View is requesting. See OAuth scopes explained below for details on each permission.
Click Accept to grant access. You will be redirected back to Omnio View automatically.
If you see "You don't have access to this app": The OAuth app is still in development mode. The app owner needs to enable distribution in the Atlassian Developer Console.
5 Select your project
After a successful connection, Omnio View displays a dropdown of all Jira projects your account can access. Select the project you want to track and click Select.
- You can add more projects later from the Configuration page.
- If no projects appear, check that your Atlassian account has Browse Projects permission on at least one project.
6 Seed AI context from Confluence (optional)
If your project has documentation in Confluence (PRD, vision statement, strategy docs), you can click Pull from Confluence to auto-populate the AI context fields (vision, strategy, goals, sprint goal). This personalises the AI-generated reports and insights.
You can skip this step and set the context manually on the Profile page at any time.
7 Continue setup
Proceed through the remaining wizard steps (GitHub, Recipients, Templates) and click Finish. Your Jira connection is now active.
OAuth scopes explained
When you authorise Omnio View, Atlassian shows the permissions being requested. Here is what each scope does:
| Scope | What it allows |
|---|---|
read:jira-work | Read your Jira issues, sprints, boards, and project data |
write:jira-work | Create and update issues (used for backlog management features) |
read:jira-user | Read basic user profiles (assignees, reporters on issues) |
read:page:confluence | Read Confluence pages (used to seed AI context from your docs) |
write:page:confluence | Create Confluence pages (used to publish sprint retro summaries) |
read:space:confluence | List Confluence spaces (used by the retro publish space picker) |
offline_access | Refresh tokens automatically so you don't have to reconnect weekly |
What happens behind the scenes
When you connect Jira for the first time, Omnio View automatically:
- Upgrades your account from the free plan to a trial.
- Promotes your role to Admin, giving you access to user management, backups, and configuration.
- Assigns your account a tenant ID for multi-tenant isolation — users you create later will inherit this tenant.
- Stores your OAuth tokens and Jira Cloud ID per-user, so each admin connects independently.
- Refreshes tokens automatically (via
offline_access) so you don't need to reconnect.
Switching Atlassian accounts
If the OAuth flow uses the wrong Atlassian account (e.g. a personal account instead of your work account), you need to switch before re-authorising.
Important: Atlassian maintains separate sessions across its domains (id.atlassian.com, auth.atlassian.com, home.atlassian.com). Logging out of one does not guarantee the others are cleared. An incognito window is the most reliable approach.
Option A — Incognito window (most reliable)
- Open an incognito (Chrome: Ctrl/Cmd+Shift+N) or private (Safari/Firefox) window.
- Sign into the correct Atlassian account at id.atlassian.com first.
- Then sign in to Omnio View in the same window.
- Click Connect Jira — the consent screen appears for the correct account.
Option B — Sign out of all Atlassian domains
- Go to id.atlassian.com → avatar (top-right) → Log out.
- Also visit auth.atlassian.com and ensure you are logged out there too.
- Sign in with the correct account, then go to Omnio View and click Connect Jira.
Option C — Atlassian account switcher
On the Atlassian authorisation page, look for "Not you?" or "Switch accounts" beneath the account name and click it. This does not always appear, so Option A is more reliable.
Reconnecting with a different account does not delete your existing Omnio View data. The new connection simply replaces the old OAuth tokens and Cloud ID.
Managing connected apps in Atlassian
To view, revoke, or manage apps you have authorised (including Omnio View), go to the Connected apps tab in your Atlassian Account settings.
Direct link: id.atlassian.com/manage-profile/apps
Or from Jira
- Click your avatar (bottom-left corner of the Jira sidebar).
- Click Manage account — this opens
id.atlassian.com. - In the top navigation bar, click the Connected apps tab.
Connected apps is its own tab in the top navigation — it is not under the Security tab. The tab sits between Account preferences and Link preferences.
From the Connected apps page you can see every third-party app you have authorised, revoke access for an app, and verify that Omnio View appears after a successful connection.
Jira admin checklist
If you are a Jira administrator for your Atlassian site (not just a project member), verify these additional items:
- Your Jira Cloud site is on an active subscription (Free, Standard, Premium, or Enterprise)
- The projects you want to track are visible to your account (Project Settings → People)
- Scrum boards have at least one sprint created with story point estimates
- If using Confluence features: your Confluence site is on the same Atlassian Cloud instance
- Third-party OAuth apps are not blocked by an Atlassian Access policy
- No IP allowlisting rules that would block Omnio View's backend from reaching the Atlassian API
Troubleshooting
"You don't have access to this app"
The Omnio View OAuth app is still in development mode. The app owner needs to enable distribution (set to Sharing) in the Atlassian Developer Console.
The first click on "Connect Jira" doesn't show the consent screen
This is a known Atlassian behaviour: the OAuth state is lost when Atlassian redirects you through a sign-in page. Go back to Omnio View and click Connect Jira again. Since you are now signed in, the consent screen will appear directly on the second attempt.
To avoid this entirely, sign into your Atlassian account before clicking Connect Jira (see Step 1).
Connected the wrong Atlassian account
Atlassian maintains separate sessions across multiple domains. Logging out of one may not clear the others. Use an incognito/private window: sign into the correct Atlassian account first, then sign into Omnio View and click Connect Jira. See Switching Atlassian Accounts above.
A project I have access to in Jira doesn't appear in Omnio View
Your Atlassian account does not have Browse Projects permission on that project. Ask your Jira admin to add your account to the project via Project Settings → People, or to the appropriate permission scheme.
Velocity or sprint data is missing
This typically means the project's board does not have completed sprints, or story points are stored in a non-standard custom field. Verify that your board uses Jira's built-in Story Points field and that at least one sprint has been completed with estimated issues.
Confluence features don't work after connecting
Your OAuth tokens may have been issued before Confluence scopes were added. Go to Configuration and click Reconnect to re-authorise with the updated scopes. This does not affect your Jira connection.
I need to reconnect with a different Atlassian account
First, revoke the existing connection: go to id.atlassian.com → Connected apps and revoke Omnio View. Then use an incognito window: sign into the correct Atlassian account, then Omnio View, and click Reconnect on the Configuration page.
I can't find "Connected apps" in my Atlassian settings
Connected apps is a separate tab in the top navigation bar at id.atlassian.com — it is not under the Security tab. Look for the tab between Account preferences and Link preferences. You can also go directly to id.atlassian.com/manage-profile/apps.
OAuth apps are blocked by my organisation's policy
Your Atlassian site may have an organisation policy that restricts third-party OAuth apps. Check admin.atlassian.com → Security → API tokens & OAuth apps. An Atlassian org admin may need to allowlist Omnio View.
That's it! Once Jira is connected and a project is selected, Omnio View begins pulling data for your dashboard and can generate your first AI-powered report. If you need help, reply to your welcome email or reach out at contact@omnioview.com.