- Overview
- Getting started
- User guide
- Admin guide
- Requester and owner guide
- Permissions and security
- Privacy and data
- Large sites
- Troubleshooting
- FAQ
- Known limitations
- Changelog
Admin guide
This guide is for Jira administrators who run Project Blueprints. Every admin page and action needs the Administer Jira global permission, checked on the server. Concepts and page descriptions are in the User guide.
Blueprints
Company-managed blueprints: Capture from project
Blueprints → Capture from project. Pick a company-managed software or business reference project. Team-managed, archived and service projects are rejected with an explanation. You can give the blueprint a name; it defaults to the project name followed by "blueprint", and requesters see it in the gallery.
The capture only reads. It records:
- project type, category and default assignee (the project URL is recorded but not applied);
- the seven scheme associations: permission, notification, issue security, work type, work type screen, workflow, and field scheme (or the legacy field configuration scheme on sites not yet migrated to field schemes);
- project roles with their users and groups;
- components (name, description, lead, default assignee);
- versions (name and description; new projects get them unreleased, without dates);
- the project property keys of the reference project (you choose which to copy);
- project-scoped custom-field contexts.
Not copied: the Jira-managed role atlassian-addons-project-access and app accounts (Jira manages them), properties you don't select, locked fields (Jira-managed fields such as the "Category" field of business projects) and global contexts.
Field contexts are found by a background scan of all custom fields: for each field the app reads which contexts apply to which projects. The blueprint shows Scanning field contexts while this runs. You can edit General, Requesters & approvals and Naming & metadata meanwhile; the content tabs fill in, and the blueprint can be activated, once the capture is Ready. A field with more than one non-global context for the reference project is captured but marked "Not applied (multi-context field: …)", because Jira's assign API accepts one context per field and project.
If the capture fails, nothing in Jira was changed. Fix the cause (shown on the blueprint and under Health → Capture errors) and re-capture.
Team-managed blueprints
Blueprints → New team-managed blueprint. Choose a name and Jira's built-in template: Kanban (team-managed) or Scrum (team-managed). There is no reference project and no configuration copy, because Jira has no API for team-managed configuration. The blueprint applies:
- the project lead, who becomes the project's Administrator;
- the app's governance and provenance properties.
Exact role mode, additional role members, components and versions are not available for team-managed blueprints. The team configures everything else in the project itself.
Configuring a blueprint
| Tab | Setting | Notes |
|---|---|---|
| General | Name, description (for admins), gallery text (for requesters) | |
| General | Project description template | Optional; metadata field IDs in braces (e.g. {client}), {key} and {name} are filled in from the request |
| General | Review interval (days) | 30–1,095; the owner confirms the project is still needed after this many days |
| Requesters & approvals | Allowed requester groups | Empty = everyone who holds Request projects (Project Blueprints) |
| Requesters & approvals | Approvals required | One Jira admin, or two different Jira admins |
| Requesters & approvals | Project lead | The requester; the requester chooses any user; or a fixed user |
| Requesters & approvals | Owner | The requester; the project lead; or the requester chooses an owner (required) |
| Naming & metadata | Naming & key policy, required metadata form | Managed on the Policies page |
| Naming & metadata | Project category | No category; always the same category (the reference project's category is used); or the requester chooses from a list |
| Roles | Role mode | Additive (default) or exact (company-managed only) |
| Roles | Additional role members | Add the requester, the owner, the project lead, a specific user or a specific group to a role |
| Components & versions | Create the captured components / versions | On by default; versions are created unreleased |
| Fields & properties | Project properties to copy | None pre-selected; keys added by Jira or other apps are marked "usually not needed" and their values aren't captured, so they can't be selected for copying |
| Fidelity report | Will apply / Won't apply, capture warnings, schemes | Read-only |
Role modes
- Additive (recommended): the blueprint's members are added; Jira's default role members on the new project stay. Verification notes the kept defaults.
- Exact: on the new project only, default role members that aren't in the blueprint are removed (the project lead stays). The preview shows this as one step with a warning; which members Jira adds by default is only known once the project exists, so the step list reports how many were removed. Existing projects are never touched.
The project lead becomes project administrator. When the lead isn't the requester, the approving admin must confirm it.
Lifecycle, versions and archiving
- Activate makes a blueprint requestable. It needs a capture that is Ready and saved changes.
- Saving changes to an active blueprint applies them to requests submitted from then on. Pending requests keep their lead, owner and number of approvals, but their plan is built again at approval with the saved role, component, version, property, description and review settings; the approver sees the updated plan.
- Re-capture reads the reference project again and creates a new version if anything changed. Pending requests stay pinned to the captured version they were submitted against; the request page shows that version next to the blueprint name. If that version is no longer available, the approver sees
PBJ-BLUEPRINT-CHANGEDand the requester must submit again. - Re-validate checks that the referenced schemes, the role members (users), the category and the field contexts still exist and are unchanged.
- Archive hides the blueprint from the gallery. Pending requests from it stay open; projects already created keep their link. An archived blueprint can't be changed or reactivated; capture the reference project again as a new blueprint (Capture from project) or create a new one.
- Delete (draft or archived blueprints that no request uses) removes the blueprint from the app; its captured snapshot is cleaned up by the weekly maintenance. A blueprint that requests reference is kept as evidence; archive it instead. Projects created from it are not changed; the ledger keeps its history.
Naming & key policies
Policies → New naming policy:
| Field | Purpose |
|---|---|
| Key pattern (regex) | Always combined with Jira's rule: a capital letter, then capital letters or digits, 2–10 characters |
| Key template | Suggests a key from metadata tokens, e.g. {CLIENT} |
| Name template | e.g. {Client} – {Initiative}; shown to requesters as the expected format |
| Name pattern (regex) | Optional rule for names |
| Reserved keys and words | Comma-separated; these can't be used |
| Minimum / maximum key length | 2–10 |
| Active | Inactive policies are not applied to new requests |
Patterns are limited to 200 characters. When you save, the app works out how much backtracking a pattern can cause on a 255-character value and refuses patterns that could be slow: a repeated group that contains alternatives or its own repetition (like (a|b)* or (a+)+), backreferences, lookahead or lookbehind, more than two open-ended repetitions on one path, and syntax the check doesn't support. The message says how to rewrite the pattern. A stored pattern that fails the check (for example after an app update made it stricter) is never run: nothing passes it until you update the policy. Values checked against a metadata field's pattern can be at most 255 characters.
Try a key and name tests the unsaved policy live and shows the messages requesters would see, plus suggested keys and names.
In the request form, key and name are checked as the requester types against the policy and against Jira's own key and name availability. When a key is taken, Jira suggests an alternative.
Deleting a policy: a policy that a blueprint uses can't be deleted ("This policy is used by a blueprint. Remove it from the blueprint first."). Submitted requests keep the result they were checked with.
Metadata forms
Policies → New metadata form builds the extra fields a requester fills in. Field types: Text, Number, Date, Single select, User. Each field has a label, an ID, an optional template token (used by key and name templates), help text, options (single select), an optional pattern (regex, text fields only) and a Required flag.
Values are stored on the request and written into the new project's property com.matify.pbj.governance. Project properties can be read through Jira's REST API by people and apps with access to the project, so don't ask for sensitive personal data in metadata fields.
Approvals
Pending requests are in Approvals → Pending (and Waiting for 2nd approval). Open a request to see the exact plan.
- Approve and create {KEY} is the only approval button. It names the key that will be created.
- Four-eyes: you can't approve your own request: "You can't approve your own request. Ask another Jira admin to approve it."
- Second approver: if the blueprint needs two approvals, the first approval moves the request to Waiting for 2nd approval. The first approver sees "You gave the first approval. A different Jira admin must give the second approval."
- Lead confirmation: if the lead isn't the requester, tick "I confirm {lead} becomes project lead (project administrator)".
- Reject… needs a reason of at least 10 characters. Templates are offered (existing project covers this, naming, wrong blueprint, more detail needed, duplicate). The requester sees the reason under My requests; the tracking work item, if enabled, gets a comment that the request was rejected (without the reason). The key is released and nothing is created.
- Cancel request closes a pending request without a decision and releases the key.
- Expiry: pending requests expire after 14 days by default (Settings → Approvals, 1–60 days) and release their key.
- Self-approval setting: off by default. Turning it on needs typing
ALLOW SELF-APPROVAL. When it is on, a Jira admin who is also the requester approves by typing the project key, and the ledger records a self-approval. Use it only on sites with a single Jira admin. - Stale previews: the plan is built again when you approve. If it changed since you opened the request (for example the blueprint, a group or a user changed), the approval is refused, the page shows "The preview changed" with the updated plan, and you give every confirmation again. If a referenced scheme was deleted or the key or name is now used by another project, the request becomes Blocked instead.
- Decision lock: two decisions on the same request never overwrite each other. If another admin changes the request at the same moment, you see "This request is being changed right now. Reload in a moment." or "The request changed while you were approving it. Reload and check it again."
- Approvals are blocked while the kill switch is on or the licence is inactive.
Your Administer Jira permission is checked fresh when you approve. Before the first write, the provisioning job checks again that every approver still holds it.
Tracking work items and reminder work items
Project Blueprints sends no e-mail. To let people get Jira notifications, turn on Settings → Requests → Create a tracking work item for every request and choose a tracking project, a work type and optionally a default assignee.
- One work item is created per request (not for the guided test) in that one project, with the requester as reporter (if Jira refuses the work item, for example because of the reporter, it is created again without reporter, default assignee and details). It contains the blueprint, key, purpose, metadata and request ID, and has the label
pbj-request. - Approval, rejection and completion are added as comments, so Jira's notification scheme of the tracking project reaches the people involved.
- The app never edits existing work items.
- If Jira refuses the work item (for example because a data security policy blocks app access to work items, or the tracking project's settings don't allow it), the request continues without it and the failure is recorded for Health. Requests are never blocked by tracking.
Review reminder work items (needs tracking on, off by default): once a week (Mondays, UTC), one work item per owner whose projects are due or overdue for review, assigned to the owner, label pbj-review. The number per run is capped.
Catalog: adopting projects and bulk actions
Select projects in the Catalog and choose a bulk action:
| Action | Effect |
|---|---|
| Assign owner | Records a new owner |
| Set review date | Sets the next review date |
| Mark reviewed | Records a review with you as reviewer; the next review date becomes today plus the review interval of the project's blueprint (or the default review interval if it has none) |
| Set blueprint reference | Links the project to a blueprint (reference only; nothing is applied) |
Each bulk action shows a confirmation with the count. It writes only the app's own project property com.matify.pbj.governance and the catalog row, in chunks. No configuration, permission or membership is changed. A pre-existing project becomes Adopted; a project created outside the gate keeps that origin, so it stays visible as outside the gate.
The catalog panel of a project also offers Re-read from Jira, links to the project and its settings, and, when archiving is recommended (inactive project or an owner's recommendation), a link to archive it in Jira yourself.
Owner transfers
Owners propose a new owner from My projects → Transfer ownership…; project administrators can do the same from Project settings → Apps → Governance → Request owner change. The request appears in Overview → Needs attention and in the project's catalog panel under Reviews. Choose Confirm new owner. Until then the current owner stays.
The catalog is the authority for owner, review date and last review. The app reads them from com.matify.pbj.governance only when it first sees a project (for example after a reinstall). Project properties can be read by everyone with Browse Projects on the project and changed by its project admins through Jira's REST API; if someone changes these values in the property directly, the catalog keeps its values and the app rewrites the property the next time it reads the project (scan, project event or Re-read from Jira).
Kill switch
Settings → Safety → Pause all approvals and provisioning (kill switch), off by default. While it is on:
- no request can be approved;
- approved requests that haven't started wait and stay Approved. When you turn the kill switch off, they start at once. If the approval is older than 24 hours by then, the request becomes Blocked and the requester submits again;
- a running provisioning stops after its current step; nothing is undone. The request becomes Partial and can be retried after you turn the kill switch off (within 7 days of the approval). If the project hadn't been created yet, it becomes Failed instead, nothing is created and the key is released;
- requests stay readable, and requesters see "New project requests are paused".
An inactive licence pauses provisioning the same way. Approved requests that haven't started are picked up by the daily job once the licence is active again (the same 24-hour limit applies).
Redacting free text
If a requester put personal or confidential data into the purpose or a text metadata field, open the request (Approvals → any tab) and choose Redact free text…. After confirmation, the purpose, the reject reason and the values of text metadata fields are replaced with [redacted] in the request, in the app's stored plan and in the project's com.matify.pbj.governance property; stored name and key suggestions are removed. Select, number, date and user values are kept. The ledger records who redacted how many fields. Jira's project description (if the blueprint's description template used metadata) and a tracking work item are not changed (the app never edits existing work items); edit them in Jira. Redaction isn't offered while a request is approved and waiting to start or being provisioned; redact it once provisioning has finished.
Data: retention and deletion
- Keep finished requests: 24 months by default (6–60). Pruned requests leave their ledger entries.
- Keep reviews: 36 months by default.
- Shortening either needs typing
REDUCE RETENTION; older records are deleted at the next weekly run. - Delete all app data (Settings → Data): type
DELETE PROJECT BLUEPRINTS DATA. It cancels queued jobs and deletes every blueprint, policy, request, catalog row, review and ledger entry. It doesn't touch Jira: projects, properties and work items remain. Export the ledger and evidence report first if you need them. The button stays available when the licence is inactive, so you can always remove the app's data.
Details: Privacy and data.
Partial provisioning runbook
Use this when a request ends as Partial, Failed or Blocked, or provisioning seems stuck.
1. Read the request
Open Approvals → In progress or History (or Overview → Needs attention) and open the request.
- The message at the top says what happened, with an error code. "Nothing was deleted. The step list shows exactly what exists."
- The step list shows every step that has started, with status (Done, Skipped, Failed, Pending), attempts and a detail line with the error code. Steps marked Done exist in Jira; Pending and Failed steps, and steps not listed yet, were not completed.
- The verification table (if verification ran) compares each item with the plan.
- Ledger entries for this request shows the full history with sequence numbers (types such as Step failed, Provision partial, Provision failed, Blocked, Resumed).
2. Which status do you have?
| Status | Does the project exist? | What it means |
|---|---|---|
| Failed | No | Jira refused to create the project (PBJ-CREATE-400, PBJ-JIRA-403), the key was taken while the project was being created (PBJ-KEY-TAKEN), or provisioning stopped before the project was created. Nothing was created |
| Blocked | No | A pre-check stopped provisioning before the first write. Nothing was created |
| Partial | Yes | The project exists, but some steps didn't finish, or verification found differences |
3. Decide what to do with a Partial request
- Retry remaining steps: choose Retry remaining {n} steps for {KEY}. Only a Jira admin can do this, only within 7 days of the approval, and not while the kill switch is on or the licence is inactive. No new approval is needed: the remaining steps of the approved plan run. Fix the cause first (for example a group or field context that Jira rejected), otherwise the same step fails again. After 7 days you see "The approval is older than 7 days. Leave the project as is, or create a new request."
- Leave as is and close: the remaining steps are not run, the project keeps what was created, the request becomes Done with notes and the project is catalogued as governed. Use this when the missing items don't matter or you add them by hand in Jira.
- Clean up manually in Jira: if you don't want the project, first close the request with Leave as is and close (this releases the key reservation), then move the project to trash yourself in Jira (Project settings → Move to trash). The catalog marks the project as trashed when it reads the project again after Jira's trash event.
A running provisioning can be stopped with Stop after current step. The stop takes effect at the next step boundary after it is recorded, so the step that is running finishes (steps take about a second each, so one or two more may complete). The request ends as Partial; if the project hadn't been created yet, it ends as Failed, nothing is created and the key is released.
If a provisioning makes no progress (for example after a platform outage), the next daily run starts it again once it has made no progress for at least an hour. After 24 hours without progress it stops: as Partial if the project exists (retry or leave as is), otherwise as Blocked.
4. Blocked cases
| Cause | What you see | Remedy |
|---|---|---|
| An approver lost Administer Jira before the first write | PBJ-PERM-ADMIN, "An approver no longer has the Jira administrator permission." | Re-approval needed: the requester submits again (Request similar) and a current Jira admin approves the new request |
| A scheme the blueprint references was deleted, the project lead is no longer an active user, or the key or name is now used by another project | PBJ-SCHEME-MISSING, with a message naming the problem (for example "The key … is already used by another project") | Fix the cause (for a deleted scheme: re-capture the blueprint), then the requester submits again (with another key if the key is taken) |
| Something changed since the approval (blueprint, schemes or members) | PBJ-STALE-PREVIEW | The requester submits again; approve the new preview |
| The approval is older than 24 hours and the project wasn't created yet (for example the kill switch or an inactive licence held it that long) | PBJ-STALE-PREVIEW, "The approval is older than 24 hours." | The requester submits again |
| Provisioning made no progress for 24 hours before the project was created | PBJ-STEP-FAILED, "Provisioning stopped unexpectedly before the project was created." | The requester submits again |
| The blueprint version is gone | PBJ-BLUEPRINT-CHANGED | The requester submits again |
| The key was taken by someone else while the project was being created | PBJ-KEY-TAKEN or PBJ-CREATE-400 (the request is Failed, not Blocked) | Submit again with another key |
A blocked request can't be resumed or re-approved; the remedy is always a new request. A blocked request still reserves its key. Cancel it with Cancel request where the request page offers it, which releases the key at once; otherwise the reservation lapses on its own about a day after the request's original expiry date. Until then the new request needs a different key. In the background, provisioning never falls back to a user's permissions. If the app can't confirm an approver's permission (for example because Jira's permission-check API fails), nothing is created: the job retries, and if the permission still can't be confirmed when the approval is 24 hours old, the request becomes Blocked.
5. What the app never does
- It never deletes, trashes, archives or renames a project, also not a partially provisioned one.
- It never rolls back steps that succeeded.
- It never blindly repeats a write whose outcome is unknown; it reads Jira first.
- It never takes over a project it didn't create, even if the key matches.
- It never changes a scheme.
6. What to send to support
- Health → Download diagnostics (no names, e-mail addresses or project content).
- The error code and its ref from the message.
- The request ID (in the Request column of Ledger entries for this request, and in the requester's My requests details).
- The ledger sequence numbers of the relevant entries (Ledger → filter by request ID).
- What you did and what you expected.
Email support@matifyapps.de or use the support page. Don't post account IDs or project content in the public tracker.