Matify/Project Blueprints for Jira

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 workBudget
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 eventsIts 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.

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.

Keeping the catalog current

SourceWhen
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 updateOnce a day (review states, flags and counters; up to 500 projects not read for 7 days are read again)
Weekly reconcileOnce a week, on Sunday (UTC) by default; set the day in Settings → Catalog
Run reconcile nowHealth → 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

Health indicators to watch

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.