- Overview
- Getting started
- User guide
- Admin guide
- Requester and owner guide
- Permissions and security
- Privacy and data
- Large sites
- Troubleshooting
- FAQ
- Known limitations
- Changelog
Large sites: catalog scan and rate limits
Project Blueprints works on sites of every size. On large sites some background work takes longer, because Jira limits how much every app may call its APIs. This page explains how the app shares that limit and what comes first. It gives no fixed durations: they depend on your site's size and on how busy Jira's shared limits are.
Jira's rate limit and "points"
Jira gives each app a shared hourly allowance of API calls, counted in points. Every read or write costs points, and larger answers cost more. The allowance is shared by all sites that use the app, so Project Blueprints makes sure one site's background work can't use it up.
The app estimates the points of every call and keeps hourly budgets per site for different kinds of work:
| Kind of work | Budget |
|---|---|
| Approval previews, approvals and provisioning of approved requests (including verification) | Not held back by the budgets; they have priority |
| Interactive checks (live key and name checks, blueprint re-validation) | Its own hourly cap per site |
| Re-reads after Jira project events | Its own hourly budget |
| Scans (first catalog scan, reconcile, field-context scans) | An hourly budget: largest in the first hour after installation, smaller for the rest of the first catalog scan, and smallest after that (field-context scans always use the smallest) |
When Jira signals that apps are being rate-limited, Project Blueprints pauses scan work for an hour and shows Rate limit pressure on the Health page with the time it resumes. Provisioning and interactive work continue. If Jira rate-limits a single call, the app waits and retries it; a page that can't wait that long shows when to try again.
Health → Jira API points, last 24 hours shows the app's estimated points per hour.
The first catalog scan
The scan starts at least 90 seconds after installation, because Jira needs about a minute before a new app's access works everywhere. It reads every project on the site, including service, product discovery and customer service projects (they are catalogued, not provisioned), with key, name, type, lead, category, issue count and last activity.
- The scan spends only its hourly scan budget. On large sites the first full catalog can take hours.
- Projects appear in the catalog as they are read. Overview shows "Reading your projects" and Catalog shows "Scan in progress", each with a progress bar; Health → Catalog scan shows the phase and how many projects were read.
- You can capture blueprints, set up policies and approve requests while the scan runs.
- If the scan is interrupted, it continues from where it stopped.
Provisioning comes first
Approved requests are never held back by the scan budgets. Provisioning runs one request at a time per site, step by step. If Jira rate-limits a step, the step waits and retries; the request page shows the step as pending with its attempts. After 5 attempts the request stops as Partial (or as Failed if the project doesn't exist yet), and a Jira admin can retry the remaining steps of a Partial request.
Field-context scan on sites with many custom fields
To find the project-scoped field contexts of a reference project, the capture reads the context-to-project mapping of every custom field on the site (Jira-locked fields are skipped). This runs in the background in the scan budget, so on sites with many custom fields it takes longer.
- The blueprint shows Scanning field contexts with a progress count.
- You can edit the blueprint's general, requester and naming settings meanwhile, and activate it once the capture is Ready.
- Re-capturing scans again.
- Verification of a new project reads only the fields of its blueprint.
Keeping the catalog current
| Source | When |
|---|---|
| Jira project events (created, updated, archived, restored, moved to trash, deleted) | About a minute after the event (the app groups events for 60 seconds); Atlassian may deliver them a few minutes late |
| Daily update | Once a day (review states, flags and counters; up to 500 projects not read for 7 days are read again) |
| Weekly reconcile | Once a week, on Sunday (UTC) by default; set the day in Settings → Catalog |
| Run reconcile now | Health → Catalog scan; at most once an hour |
Projects created outside the app are flagged Outside the gate. Their creator is looked up in Jira's audit log and shows as unknown if the audit log doesn't name one.
Working with a large catalog
- The Catalog page loads 100 projects at a time and holds up to 10,000 in your browser. Use the filters (origin, flags, owner, review, inactivity, blueprint) to narrow the list.
- Export CSV (current filter) exports what the filter shows.
- Bulk actions run in chunks in the background and show their progress.
Health indicators to watch
- Catalog scan: phase (Waiting to start, Scanning, Complete), projects read, last reconcile and the weekly reconcile day.
- Queues: provisioning steps and background jobs waiting.
- Rate limit pressure: shown while Jira is rate-limiting apps.
- Failed provisioning steps and Capture errors.
- Permission checks: whether the fallback is in use.
If the scan makes no progress or a queue doesn't shrink for a long time, download the diagnostics from Health and contact support. See Troubleshooting.