- Overview
- Getting started
- User guide
- Admin guide
- Requester and owner guide
- Permissions and security
- Privacy and data
- Large sites
- Troubleshooting
- FAQ
- Known limitations
- Changelog
User guide
This guide explains the concepts behind Project Blueprints and every page of the app. Step-by-step admin tasks are in the Admin guide; the requester's and owner's view is in the Requester and owner guide.
Concepts
Blueprints
A blueprint describes how a new project (space) is set up.
- A company-managed blueprint is captured from a company-managed software or business reference project. It records the project type, category and default assignee; the seven scheme associations (permission, notification, issue security, work type, work type screen, workflow and field scheme — or the field configuration scheme on sites not yet migrated to field schemes); project roles with their users and groups; components; versions; the project properties you select; and project-scoped custom-field contexts.
- A team-managed blueprint starts from Jira's built-in Kanban or Scrum template. It applies only the project lead (who becomes the project's Administrator) and the app's own governance properties. Jira has no API to copy a team-managed project's configuration.
New projects share the blueprint's schemes, like Jira's "share settings" option. The app never copies, edits or deletes a scheme. A change to a shared scheme affects every project that uses it, as it always does in Jira.
A blueprint has a status: Draft → Active → Archived. Only active blueprints can be requested. Re-capture reads the reference project again and creates a new blueprint version if the configuration changed. Requests that were already submitted stay pinned to the version they were submitted against.
Requests and their statuses
| Status | Meaning |
|---|---|
| Pending approval | Submitted; waiting for a Jira admin |
| Waiting for 2nd approval | The blueprint needs two approvals; one is given |
| Approved | All approvals given; provisioning is queued |
| Provisioning | The app is creating and setting up the project |
| Done | Created and verified; everything matches the plan |
| Done with notes | Created; verification passed with notes (for example a deactivated account was skipped), or an admin closed a partial request as it is |
| Partial | The project exists, but not every step finished or verification found differences. An admin can retry the remaining steps (within 7 days of the approval) or leave it as is |
| Failed | The project wasn't created (for example Jira refused it, or provisioning stopped before the create step). Nothing was created |
| Blocked | Provisioning didn't start because a pre-check failed (for example an approver lost Administer Jira). Nothing was created |
| Rejected | A Jira admin rejected the request with a reason |
| Withdrawn | The requester withdrew it while it was pending |
| Expired | Nobody decided within the expiry period (14 days by default) |
| Cancelled | A Jira admin closed it without a decision |
An open request reserves its key: two open requests can't use the same key. Rejected, withdrawn, expired and cancelled requests release the key.
Approvals
Only users with Administer Jira can approve. Their permission is checked fresh at the moment of approval.
- Four-eyes: a requester can't approve their own request. Exceptions: the self-approval setting (off by default) and the one-time guided test.
- Second approval: a blueprint can require two approvals; the second must come from a different Jira admin.
- Lead confirmation: if the project lead isn't the requester, the approver confirms that this person becomes project lead (project administrator).
- Exact preview: the approver sees exactly what will be created. If anything changed since the preview, the approval is refused as stale and a new preview is shown.
- One decision at a time: two admins can't decide on the same request at once.
Provisioning steps
After approval, the app works through a fixed sequence of steps in the background, one request at a time per site:
| Step | What it does |
|---|---|
| Pre-check | Licence, kill switch, approvals complete, every approver still holds Administer Jira, plan unchanged |
| Create project | Creates the project with every scheme association, lead and category in one call |
| Record provenance | Writes the project property com.matify.pbj.provenance (request, blueprint, requester, approvers) |
| Add role members | Adds the blueprint's users and groups to the project roles |
| Remove default role members (exact mode) | Only in exact role mode, only on the new project |
| Create component / Create version | One step per component and version |
| Assign field context | Assigns project-scoped field contexts |
| Write project property | Copies the properties selected in the blueprint |
| Write owner and review date | Writes com.matify.pbj.governance |
| Update tracking work item | Only if tracking work items are on |
| Verify against blueprint | Re-reads the project and compares it with the plan |
| Add to catalog | Adds the project to the catalog with origin Governed |
Every step is recorded. Steps are retried automatically when Jira rate-limits or returns a server error. Before it repeats a create or add whose outcome is unknown, the app reads Jira first. If creating the project times out, the app looks the key up and continues only when its own records (and the project's name, lead and schemes) show that the app created that project; otherwise the request fails and that project isn't touched.
Verification results
| Result | Meaning |
|---|---|
| Verified (PASS) | Everything matches the plan |
| Verified with notes (PASS_WITH_NOTES) | Matches, with notes, for example deactivated accounts skipped or Jira's default role members kept in additive mode |
| Partial (PARTIAL) | Some items are missing or differ |
| Failed (FAIL) | The project couldn't be found when it was verified |
The verification table lists every item with expected value, actual value and Match, Note or Mismatch.
Catalog origins and flags
| Origin | Meaning |
|---|---|
| Governed | Created through Project Blueprints |
| Outside the gate | Created directly in Jira after the installation. The creator comes from Jira's audit log, or shows as unknown |
| Pre-existing | Existed before the installation |
| Adopted | A pre-existing project that a Jira admin brought under governance with a bulk action. Projects created outside the gate keep that origin |
| Flag | Shown when |
|---|---|
| Naming | Key or name doesn't match the site's default naming policy |
| No owner | No owner recorded |
| Owner inactive | The owner's Atlassian account is inactive |
| Lead inactive | The project lead's account is inactive |
| Review due | The review date is within the next 30 days |
| Review overdue | The review date has passed |
| Inactive | No work item updated for longer than the inactivity threshold (180 days by default) |
| Team-managed | A team-managed project that wasn't created through the app (outside the gate or pre-existing), while the Team-managed projects setting flags them |
| No category | No project category, when a category is required in Settings |
Owners and reviews
Every governed project gets an owner and a review date (today plus the blueprint's review interval). When a review comes up, the owner confirms under My projects that the project is still needed, recommends archiving, or proposes a new owner. The app never archives or deletes a project; admins decide in Jira.
The ledger
The ledger is an append-only, hash-chained record. Each entry's hash covers the previous entry's hash and the entry's sequence number, time, type, request, project and blueprint IDs, its details and a pseudonymous reference to the actor, so changing or removing any of these breaks the chain (Verify integrity checks it). The readable summary, the project key and the actor's account ID are shown with the entry but are not part of the hash; the account ID is removed when Atlassian reports the account as closed, without breaking the chain. It records requests, approvals (each approver), rejections, expiries, the start of provisioning, the project creation, failed steps and the result, verification, cancellations, resumes, changes to blueprints, policies and settings, the kill switch, owner changes, reviews, projects detected outside the gate, free-text redactions, tombstones for closed accounts and the uninstall. Each provisioning step is listed on the request page.
Jira's own audit log names only the app as the creator of a project, because the app creates projects in the background. The ledger and the project's provenance property record the people who requested and approved it.
Requester pages (Apps → Project Blueprints)
These pages are in Jira's top navigation under Apps → Project Blueprints. Every Jira user can open them; what they can do depends on their permissions.
Request a project
Three input steps: Blueprint → Details → Review, then Submitted. The blueprint gallery shows only active blueprints the requester may use (a blueprint can be limited to certain groups), with "You'll get", "Won't apply" and how many approvals are needed. If requests aren't open, the requester lacks the permission, the licence is inactive or the kill switch is on, the page explains that instead.
My requests
The requester's own requests with status, progress, a link to the new project and the tracking work item (if enabled). Opening a request shows its timeline, provisioning steps and the verification table. Withdraw works while the request is pending. Request similar starts a new request pre-filled from this one (except the key and category).
My projects
Projects the user owns, with review date, review status, last review, last activity, origin and flags, and the actions Still needed, Recommend archive and Transfer ownership….
Admin pages (Jira settings → Apps → Project Blueprints)
Overview
The Get started checklist (until done), key figures (pending approvals, provisioned this month, created outside the gate in the last 30 days, reviews overdue, projects without owner), Needs attention (up to 10 items with one action each), projects created outside the gate in the last 30 and 90 days, projects provisioned per month, and recent activity.
Approvals
Tabs Pending, Waiting for 2nd approval, In progress and History, with a filter by key, name or blueprint. A request page shows the requester's details and the policy result at submission, the grouped plan (Project, Schemes, Roles & members, Components, Versions, Field contexts, Properties, warnings, skipped items and all steps in order), the timeline and the decision panel: Approve and create {KEY}, Reject… and Cancel request. After approval it shows live progress, the step list, the verification table and, where they apply, Stop after current step, Retry remaining {n} steps for {KEY} and Leave as is and close.
Blueprints
The list of blueprints with reference project, type, status, capture state, version, approvals, request and provisioning counts and warnings. Capture from project and New team-managed blueprint create new ones. The editor has the tabs General, Requesters & approvals, Naming & metadata, Roles, Components & versions, Fields & properties and Fidelity report, and the actions Activate, Archive, Re-validate (checks that the referenced schemes, role members, category and field contexts still exist), Re-capture (company-managed blueprints), Export JSON and Delete (only draft or archived blueprints that no request uses).
Policies
Naming & key policies and metadata forms, each with a live tester (Try a key and name). A blueprint references at most one of each.
Catalog
Every project on the site, with filters (key or name, origin, flags, type, style, category, owner, review, inactivity, blueprint; sort by key, name, last activity or review date). The catalog loads 100 rows at a time, up to 10,000 in the browser. Select rows for the bulk actions Assign owner, Set review date, Mark reviewed and Set blueprint reference. A row opens a panel with the project's details, provenance, reviews (with Confirm new owner for pending transfers), timeline, links to Jira and Re-read from Jira. Export CSV (current filter) exports what the filter shows.
Ledger
The ledger, newest first, filterable by type, request ID, project ID and actor. Verify integrity re-checks the whole chain. The Exports section holds the ledger, request, review and evidence exports.
Health
See the Health section below.
Settings
See the Settings section below.
Project settings → Governance
For project administrators (Administer projects on that project) and Jira admins. It shows the project's provenance (requested by, approved by, blueprint, approval and creation date, request ID), or its origin if it wasn't created through the app; its owner, review date, review status, last review and flags; and Request owner change, which a Jira admin then confirms in the app.
Exports
All exports are built in your browser and saved on your computer. CSV files are UTF-8 with a byte-order mark, and cells that a spreadsheet would run as a formula are neutralised.
| Export | Where | Contents |
|---|---|---|
| Evidence report CSV | Ledger → Exports (date range) | Every project created on the site in the range: governed (requester, approvers, blueprint, verification result, ledger sequence) or outside the gate (creator if known) |
| Catalog CSV | Catalog (current filter) | The catalog rows the filter shows |
| Requests CSV | Ledger → Exports | Requests with status and decisions |
| Reviews CSV | Ledger → Exports | Owner reviews (attestations) |
| Ledger CSV / JSON | Ledger → Exports | Ledger entries; the JSON includes the chain head |
| Blueprint JSON | Blueprint editor → Export JSON | One blueprint and its captured configuration |
| Diagnostics JSON | Health → Download diagnostics | Versions, settings, counts, scan and queue state for support; no personal data, no project names |
Exports contain Atlassian account IDs (no display names). Handle them like other admin data.
Health
| Indicator | What it shows |
|---|---|
| Catalog scan | Phase (first scan or reconcile), projects read, start and finish, last reconcile, weekly reconcile day, Run reconcile now |
| Queues | Provisioning steps and background jobs waiting, kill switch, licence state, installation date |
| Permission checks | Mode, whether the permission-check fallback is in use, last error, field mode (field schemes or legacy field configuration schemes), ledger integrity and when it was last checked |
| Jira API points, last 24 hours | Estimated rate-limit points the app used per hour |
| Probes | Whether the app's own permissions and reads work as expected |
| Failed provisioning steps | Each failed step with a link to its request |
| Capture errors | Blueprints whose capture failed |
| Rate limit pressure | Shown when Jira is rate-limiting apps, with the time background work resumes |
| Diagnostics | Download diagnostics |
Settings
Every settings change is recorded in the ledger.
| Section | Setting | Default | Range / options |
|---|---|---|---|
| Requests | Open requests | Off | On / off (confirmation) |
| Requests | Who can request | Nobody (the permission is granted to nobody) | Managed in Jira's Global permissions (Open Global permissions in Jira) |
| Requests | Create a tracking work item for every request | Off | Tracking project, work type, optional default assignee |
| Requests | Review reminder work items | Off | Needs tracking work items on |
| Approvals | Pending requests expire after (days) | 14 | 1–60 |
| Approvals | Allow Jira admins to approve their own requests | Off | Enable by typing ALLOW SELF-APPROVAL |
| Approvals | Approvals required for new blueprints | One Jira admin | One / two different Jira admins |
| Catalog | Inactive after (days without work item updates) | 180 | 30–730 |
| Catalog | Default review interval (days) | 365 | 30–1,095 |
| Catalog | Require a project category | Off | On / off |
| Catalog | Team-managed projects | Flag team-managed projects created outside the gate | Allowed / flag only (the app can't block native creation) |
| Catalog | Weekly reconcile day (UTC) | Sunday | Any weekday |
| Data | Keep finished requests (months) | 24 | 6–60 |
| Data | Keep reviews (months) | 36 | 12–120 |
| Data | Delete all app data | — | Type DELETE PROJECT BLUEPRINTS DATA |
| Safety | Pause all approvals and provisioning (kill switch) | Off | On / off (confirmation) |
Shortening a retention period requires typing REDUCE RETENTION; older records are deleted at the next weekly run.
Licensing
While the licence is inactive, the app is read-only: no new requests, approvals, provisioning or scans, and no changes to blueprints, policies or settings (open requests can still be withdrawn or cancelled); catalog, requests, ledger and exports stay readable. See README.