> ## Documentation Index
> Fetch the complete documentation index at: https://support.configview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira setup

## Part 1: Jira Data Ingestion

Set up an Atlassian API token so ConfigView can pull your Jira users, groups and group membership, application-role seat usage, global administrative settings, and (optionally) your organization's API tokens into the dashboard.

This integration uses the **Jira Cloud REST API v3** for users, groups, roles, and settings, plus the **Atlassian organization Admin API** for the optional API-token audit.

***

### Step 1: Create a Jira API Token

1. Go to: [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. **Label:** `ConfigView`
4. Click **Create**
5. Copy the token — you will only see it once

> The token inherits the permissions of the user that created it. For the full data set (groups, application roles, and global settings), create it under a **Jira administrator** account. A non-admin token can still read the user directory.

***

### Step 2: Add the Credentials to ConfigView

ConfigView authenticates to Jira with HTTP Basic auth: your Atlassian account email plus the API token, against your site URL.

1. Go to your ConfigView dashboard: `https://{companyname}.configview.com/admin/secret/`
2. Add the following three secrets (click **Add Secret** for each):

| Secret name      | Value                                                                     |
| ---------------- | ------------------------------------------------------------------------- |
| `JIRA_BASE_URL`  | Your Jira site URL, e.g. `https://acme.atlassian.net` (no trailing slash) |
| `JIRA_EMAIL`     | The Atlassian account email that created the token                        |
| `JIRA_API_TOKEN` | The token from Step 1                                                     |

3. Click **Save**

***

### Step 3: (Optional) Enable the API-Token Audit

The **API Tokens** script lists *every* user API token across your Atlassian **organization** — token label, owner, creation date, last-active date, and expiry — so you can find stale or never-expiring tokens. This uses the org-level Admin API, which needs two extra secrets and an **organization admin** API key.

1. Find your **organization ID**: go to [https://admin.atlassian.com](https://admin.atlassian.com), select your organization — the id is in the URL (`/o/{orgId}/...`).
2. Create an **organization API key** with the `read:tokens:admin` scope (admin.atlassian.com → **Settings → API keys**).
3. Add these secrets at `https://{companyname}.configview.com/admin/secret/`:

| Secret name               | Value                                         |
| ------------------------- | --------------------------------------------- |
| `ATLASSIAN_ORG_ID`        | Your organization id                          |
| `ATLASSIAN_ADMIN_API_KEY` | An org-admin API key with `read:tokens:admin` |

> If you skip this step, the **API Tokens** script still runs — it simply records an empty snapshot with a note explaining the secrets are not set. Every other Jira script is unaffected.

***

### Step 4: Enable the Jira App in ConfigView

1. Go to: `https://{companyname}.configview.com/admin/cron/`
2. You should see **Jira** in the list of available apps
3. Select the scripts you want to run:
   * **Users** — Every Atlassian account visible to the token (active, inactive, app, and customer accounts)
   * **Groups** — All groups on the site (id + name)
   * **Group Members** — One row per group × member, with each member's active flag *(run alongside Groups)*
   * **Application Roles** — Seat and license usage per application role (defined seats, used seats, remaining seats)
   * **Settings** — Global administrative settings: feature flags from `/configuration` plus advanced `application-properties` *(properties need a Jira admin token)*
   * **API Tokens** — Organization-wide user API token inventory for stale/expired-token audit *(needs the Step 3 secrets)*
4. Click **Save**

> **Permission note:** **Users** works with any token. **Groups, Group Members, Application Roles,** and the `application-properties` half of **Settings** call admin endpoints that Jira gates behind administrator permission. When a capability isn't granted, the script records an empty (or partial) snapshot with an explanatory note instead of failing — so it's safe to enable them on any token.

***

### Step 5: Verify

1. Go to: `https://{companyname}.configview.com/admin/status/`
2. Run the **Jira** health check
3. The core checks should pass:

   * Secret Manager access (`JIRA_BASE_URL` / `JIRA_EMAIL` / `JIRA_API_TOKEN`)
   * Jira API auth (`/myself`)
   * `/users/search` endpoint reachable

   The optional capability checks — **Groups**, **Application roles**, **Settings**, and **API tokens** — report **ok** when reachable, or **skip** with a permission/scope note when your token doesn't grant them. A skip is expected for non-admin tokens (or when the Step 3 secrets aren't set) and does not fail the overall health check.

If a check fails, verify:

* `JIRA_BASE_URL` is your full site URL with no trailing slash (`https://acme.atlassian.net`)
* `JIRA_EMAIL` matches the account that created the token
* The `JIRA_API_TOKEN` secret has no extra spaces and has not been revoked at [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)

***

### Data Tables

Each enabled script creates and populates one table:

| Table                    | Script            | Key Columns                                                                                                                                  |
| ------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `jira_users`             | Users             | account\_id, account\_type, display\_name, email, active                                                                                     |
| `jira_groups`            | Groups            | group\_id, name                                                                                                                              |
| `jira_group_members`     | Group Members     | group\_id, group\_name, account\_id, display\_name, email, account\_type, active                                                             |
| `jira_application_roles` | Application Roles | role\_key, name, number\_of\_seats, remaining\_seats, user\_count, group\_count, has\_unlimited\_seats, is\_platform, default\_groups (JSON) |
| `jira_settings`          | Settings          | source, setting\_key, setting\_name, setting\_value                                                                                          |
| `jira_api_tokens`        | API Tokens        | token\_id, label, status, account\_id, user\_name, user\_email, created\_at, expires\_at, last\_active\_at, scopes (JSON)                    |

**Snapshot model.** Every Jira table is a **per-run snapshot** stamped with `run_at`. Query the latest with `WHERE run_at = (SELECT MAX(run_at) FROM <table>)`. Older snapshots are pruned automatically at the end of each run.

`jira_group_members` is built from the latest `jira_groups` snapshot, so enable and run **Groups** before (or alongside) **Group Members**.

`jira_settings.source` distinguishes the two origins: `configuration` (global feature flags like attachments/voting/time-tracking, with nested time-tracking keys flattened as `timeTrackingConfiguration.workingHoursPerDay`) and `application-property` (advanced settings, which require a Jira admin token).

`jira_api_tokens` timestamps (`created_at`, `expires_at`, `last_active_at`) are stored as raw ISO-8601 strings exactly as Atlassian returns them. An empty `expires_at` means the token never expires — useful for security audits.

***

### Troubleshooting

| Issue                                               | Fix                                                                                                                     |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Health check fails on "Jira API auth"               | Verify `JIRA_BASE_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN`; regenerate the token if needed                              |
| `jira_users` has rows but `email` is blank          | Atlassian hides email when the user's profile visibility is restricted. Org admins can relax this in directory settings |
| `jira_groups` / `jira_application_roles` empty      | The token is not a Jira admin. Regenerate the token under an administrator account                                      |
| `jira_group_members` empty                          | Run **Groups** first — membership is expanded from the latest `jira_groups` snapshot                                    |
| `jira_settings` has only `configuration` rows       | The `application-properties` half needs a Jira admin token; the run note will say so                                    |
| `jira_api_tokens` records "API-token audit skipped" | Set `ATLASSIAN_ORG_ID` and `ATLASSIAN_ADMIN_API_KEY` (org-admin key with `read:tokens:admin`) per Step 3                |
| `jira_api_tokens` records "endpoint unreadable"     | The org key is missing the `read:tokens:admin` scope, or `ATLASSIAN_ORG_ID` is wrong                                    |