- Overview
- Getting started
- User guide
- Admin guide
- Requester and owner guide
- Permissions and security
- Privacy and data
- Large sites
- Troubleshooting
- FAQ
- Known limitations
- Changelog
Getting started
This page takes you from installation to the first real project (space) created through Project Blueprints. You can do it in one session. How long each step takes depends on the size of your site and on Jira's rate limits, so this page gives no fixed durations.
1. Install
Install Project Blueprints for Jira from the Atlassian Marketplace. A Jira site administrator approves the app's permissions; they are explained in Permissions and security. Then open Jira settings → Apps → Project Blueprints.
The admin pages are only for users with the Administer Jira global permission. Everyone else sees "You need Jira administrator permission to use this page". The app checks this on the server for every call, not only in the menu.
Right after installation the app changes nothing in Jira:
- Requests are off ("Open requests" is off in Settings).
- The global permission Request projects (Project Blueprints) is granted to nobody.
- There are no blueprints yet, so nothing can be requested.
2. The first minutes: the catalog scan
You don't have to start anything. The catalog scan begins by itself at least 90 seconds after installation (Jira needs about a minute before a newly installed app's access works everywhere). It reads every project on the site and fills the Catalog.
- Overview shows "Reading your projects" with a progress bar while the scan runs.
- Health → Catalog scan shows the phase (Waiting to start, Scanning, Complete, Paused) and how many projects have been read.
- On small sites the first projects appear quickly. On large sites the first full catalog can take hours, because the scan spends only a limited budget of Jira's rate limit per hour. You can use the app meanwhile. See Large sites.
New projects are added as they are created, through Jira's project events. A weekly reconcile (Sunday, UTC, by default) and a daily update keep the catalog complete.
A Welcome to Project Blueprints panel states three facts: requests are off until you open them, the app never deletes or archives projects, and no data leaves Atlassian. Dismiss only hides the panel.
3. Work through "Get started"
The Overview shows a Get started checklist with five steps. It disappears when all five are done.
Step 1: Review your project catalog
Choose Open the catalog. Each row shows key, name, type, owner, review date, last activity, origin and flags. Projects that existed before the installation have the origin Pre-existing. Projects created directly in Jira from now on get the origin Outside the gate. Details: User guide.
Step 2: Capture your first blueprint
Choose Capture from project and pick a company-managed software or business project you consider a good standard. Team-managed and archived projects can't be picked (the list says why); a service project is refused with an explanation when you start the capture.
The capture only reads. It records the project's scheme set, roles and members, components, versions, category, project properties and project-scoped field contexts. The reference project is not changed.
- The core read runs first (status Capturing).
- Field contexts are then found by a background scan of all custom fields (status Scanning field contexts). On sites with many custom fields this takes longer.
- While the scan runs you can already edit the General, Requesters & approvals and Naming & metadata tabs. The Roles, Components & versions, Fields & properties and Fidelity report tabs fill in when the capture is Ready.
- Open the Fidelity report tab. It lists what will apply to new projects and what won't apply (for example board configuration, filters, dashboards, automation rules, work items, priority scheme, multi-context fields).
- Under Fields & properties, select the project properties you want to copy. None are pre-selected.
- Choose Save changes, then Activate. Activation is possible once the capture is Ready.
Before activating, look at Requesters & approvals: who may request from this blueprint (empty = everyone with the request permission), how many approvals it needs (one or two Jira admins), and who becomes the project lead and the owner. All options are in the Admin guide.
Step 3: Run a guided test request
Choose Start guided test. It needs one active blueprint whose capture is Ready.
- Pick the blueprint. The key is pre-filled with PBJTEST and the name with "Project Blueprints test"; change them if you like. The key is checked again before approval.
- Create test request creates one request as if a requester had submitted it, and opens it in Approvals.
- Read the preview: project, schemes, roles and members, components, versions, field contexts, properties, warnings and skipped items.
- Tick This is a test project and choose Approve and create PBJTEST. This is the one time you may approve a request yourself without the self-approval setting. The ledger records it as a Test self approved entry.
- Watch the steps run. At the end you see Project PBJTEST created and verified (or created, with notes in the verification table).
- Remove the test project yourself: open Project settings from the success message and move the project to trash in Jira. The app never deletes projects.
The guided test can be used once per site.
Step 4: Set your naming and key policy
Choose Open policies, then New naming policy. You can set a key pattern, a key template, a name template or pattern, reserved keys and words, and the minimum and maximum key length. Every rule is always combined with Jira's own key rule (a capital letter first, then capital letters or digits, 2–10 characters). Use Try a key and name to see what requesters will see before you save. Then reference the policy from your blueprint (Naming & metadata tab).
If you want requesters to fill in extra details (for example cost centre or client), create a New metadata form and reference it from the blueprint too. See the Admin guide.
Step 5: Open requests and grant the permission to a group
- Choose Open Global permissions in Jira. Grant Request projects (Project Blueprints) to the groups that may request projects (Jira settings → System → Global permissions).
- In Settings → Requests, turn on Open requests and confirm. Everyone who holds the permission can then request projects from the blueprints their groups may use. Every request still needs a Jira admin's approval.
Requesters don't see Atlassian's "Allow access" consent screen in the normal flow; the app checks their permission itself. See Permissions and security.
4. Your first real request, end to end
- The requester opens Apps → Project Blueprints → Request a project (in Jira's top navigation), picks a blueprint, fills in name, key and the other details, reviews and chooses Submit request. See the Requester and owner guide.
- A Jira admin opens Approvals → Pending, opens the request and reads the preview. The key is checked against Jira again when the preview is built and again at approval.
- If the project lead isn't the requester, the admin ticks "I confirm … becomes project lead (project administrator)".
- The admin chooses Approve and create {KEY}, or Reject… with a reason of at least 10 characters. If the blueprint needs two approvals, a different Jira admin gives the second one.
- Project Blueprints creates and sets up the project in the background, then verifies it. Progress appears on the request page for the admin and under My requests for the requester.
- The result is Done, Done with notes, Partial, Failed or Blocked. When the request is Done or Done with notes, the new project appears in the catalog with origin Governed, its owner and its first review date.
If the plan changed between the preview and the approval (for example the blueprint, a group or a user), the approval is refused as stale and the new preview is shown. If a referenced scheme was deleted or the key or name was taken meanwhile, the request is blocked instead. If provisioning stops halfway, follow the Partial provisioning runbook.
5. A short routine
- Overview → Needs attention: pending approvals, failed or partial requests, projects created outside the gate, overdue reviews and owner changes waiting for confirmation.
- Catalog: filter by origin Outside the gate to see projects created directly in Jira, or by flag No owner to assign owners in bulk.
- Ledger → Exports: the evidence report for audits (every project in a date range that was created through the app or detected as created outside the gate).