Matify/Project Blueprints for Jira

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:

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:

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

TabSettingNotes
GeneralName, description (for admins), gallery text (for requesters)
GeneralProject description templateOptional; metadata field IDs in braces (e.g. {client}), {key} and {name} are filled in from the request
GeneralReview interval (days)30–1,095; the owner confirms the project is still needed after this many days
Requesters & approvalsAllowed requester groupsEmpty = everyone who holds Request projects (Project Blueprints)
Requesters & approvalsApprovals requiredOne Jira admin, or two different Jira admins
Requesters & approvalsProject leadThe requester; the requester chooses any user; or a fixed user
Requesters & approvalsOwnerThe requester; the project lead; or the requester chooses an owner (required)
Naming & metadataNaming & key policy, required metadata formManaged on the Policies page
Naming & metadataProject categoryNo category; always the same category (the reference project's category is used); or the requester chooses from a list
RolesRole modeAdditive (default) or exact (company-managed only)
RolesAdditional role membersAdd the requester, the owner, the project lead, a specific user or a specific group to a role
Components & versionsCreate the captured components / versionsOn by default; versions are created unreleased
Fields & propertiesProject properties to copyNone 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 reportWill apply / Won't apply, capture warnings, schemesRead-only

Role modes

The project lead becomes project administrator. When the lead isn't the requester, the approving admin must confirm it.

Lifecycle, versions and archiving

Naming & key policies

Policies → New naming policy:

FieldPurpose
Key pattern (regex)Always combined with Jira's rule: a capital letter, then capital letters or digits, 2–10 characters
Key templateSuggests a key from metadata tokens, e.g. {CLIENT}
Name templatee.g. {Client} – {Initiative}; shown to requesters as the expected format
Name pattern (regex)Optional rule for names
Reserved keys and wordsComma-separated; these can't be used
Minimum / maximum key length2–10
ActiveInactive 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.

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.

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:

ActionEffect
Assign ownerRecords a new owner
Set review dateSets the next review date
Mark reviewedRecords 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 referenceLinks 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:

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

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.

2. Which status do you have?

StatusDoes the project exist?What it means
FailedNoJira 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
BlockedNoA pre-check stopped provisioning before the first write. Nothing was created
PartialYesThe project exists, but some steps didn't finish, or verification found differences

3. Decide what to do with a Partial request

  1. 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."
  2. 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.
  3. 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

CauseWhat you seeRemedy
An approver lost Administer Jira before the first writePBJ-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 projectPBJ-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-PREVIEWThe 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 createdPBJ-STEP-FAILED, "Provisioning stopped unexpectedly before the project was created."The requester submits again
The blueprint version is gonePBJ-BLUEPRINT-CHANGEDThe requester submits again
The key was taken by someone else while the project was being createdPBJ-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

6. What to send to support

  1. Health → Download diagnostics (no names, e-mail addresses or project content).
  2. The error code and its ref from the message.
  3. The request ID (in the Request column of Ledger entries for this request, and in the requester's My requests details).
  4. The ledger sequence numbers of the relevant entries (Ledger → filter by request ID).
  5. 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.