Documentation
Page Properties Check user guide
How to use the app and understand its limits.
Check the Content Properties (formerly Page Properties) tables you already use against rules you choose. The app reads only. It does not change Confluence pages or replace your document register.
Only pages you can view are checked. Pages you cannot view are not counted in results and cannot cause duplicate findings. A check is a snapshot of the readable selection at run time, not proof about every page on the site.
Create a check schema
- Open Page Properties Check in Confluence's Apps navigation. In Saved checks, choose Create check or Use Document register template.
- Enter a short Name. Saved checks are shared: every app user on the site can view, edit or delete them. Use general field names and rules; do not put personal, confidential or page-content values into the schema.
- Choose a Label, a Root page (page URL or ID), or both. A page tree includes its root page and descendants. Add an optional Space key to narrow the selection. A space key alone is insufficient. Labels accept letters, numbers, underscores and hyphens; page URLs must belong to this site and contain a numeric page ID. An unreadable root page is rejected without revealing its title.
- Optionally enter a Content Properties ID to check macros with that ID. Leave it empty to consider all Content Properties macros on each page. When several readable macros contribute the same key, the first value is used and a different later value produces a warning. Within a macro, only the first table is checked.
- Keep Require a Content Properties macro enabled to report pages without the macro. If you disable it, a page without a macro can pass without field checks.
- Add field rules and choose Save check. Correct any field errors before saving. If the saved version has changed, Reload latest version loads it, or Save as a new check keeps your edits under a new identity. Review your edits before replacing them with the latest version. If reloading confirms that the check was deleted, the reload action disappears; your inputs remain and Save as a new check is still available.
For each Field key, choose Required field to report a missing key and Must not be empty to reject an existing empty cell. Template placeholder text counts as empty. These are separate rules: a non-empty rule alone does not make an absent key required. Use Must be unique among checked pages for a document number. Duplicate comparison ignores case and normalizes whitespace.
Choose Text, Date or Allowed values. Date rules accept the formats you select: YYYY-MM-DD, DD.MM.YYYY, D.M.YYYY, DD/MM/YYYY, MM/DD/YYYY and D MMM YYYY (English month names). A native Confluence date element is recognized directly. Calendar dates must be real; choose one convention if day/month order would be ambiguous. For allowed values, enter one value per line; matching ignores case, and a comma can be part of a value.
The Document register template uses these rules. Change the field keys to match your tables and supply your own label or page tree.
| Field key | Template rule |
|---|---|
| Document ID | Required, non-empty text, unique among checked pages. |
| Owner | Required, non-empty text. Mentions are not looked up to find names. |
| Review date | Required, non-empty date; YYYY-MM-DD or DD.MM.YYYY. |
| Status | Required, non-empty; Draft, In review, Approved or Obsolete. |
You can save at most 50 checks on a site, within a shared total of 32 KiB. Each complete saved check must fit within 8 KiB; it can have 1–30 field rules. Shorten long names or allowed-value lists if saving reports a size error. Duplicate opens an unsaved copy; saving it creates a separate check.
Run a check
- Choose the check in Saved check under the run area, then select Run check. Creating, editing or deleting a check updates this list without reloading the app. The initially shown check stays selected when another is created. If the selected check is deleted, choose another check explicitly before starting a new run; Run again is disabled until then. Changes to saved checks leave existing results in the tab, and a fresh run uses the selected check's current settings.
- If Confluence asks for access, choose Allow access in the dialog it shows. After granting access, run the check again. Confluence permissions still determine what you can read.
- Watch Selected, Checked and Skipped and the current progress, such as Selecting pages, Checking pages or Waiting for access. Pause stops further steps after the current request settles. Continue resumes the unfinished work. Keep this tab open; the check does not continue as a background job after the page is closed.
- Use Cancel to stop. Only results already accepted remain in this tab. Partial results appears once at least one page has been checked or skipped; an interruption before then does not show an empty results table. A late response is not added. Try again resumes unfinished work after a recoverable failure; Run again starts a fresh check.
- Review the summary and result list. Filter by status or finding code. Open a finding's page link to review or change the page yourself in Confluence, then start a fresh check.
Results and extracted values are not saved. Closing or reloading the app page discards them. Starting a new run replaces the previous run's results. Check schemas remain saved until deleted.
Read results
| Status | Meaning |
|---|---|
| pass | No finding for that page against these rules. A page allowed to have no macro can pass without field checks. |
| warn | At least one warning, with no error or unverifiable finding. Review the table structure or key naming. |
| fail | At least one error. This takes precedence even if the page also has unverifiable content or warnings. |
| unverifiable | No error, but at least one value or structure could not be checked reliably. This is not a pass. |
Skipped counts selected pages omitted from checking, including pages no longer readable or current and selection-cap omissions. Truncated means the selection hit the 1,000-page cap. Cancelled, failed, skipped or incomplete runs do not establish that the whole selection passes. Duplicate detection covers only results obtained in this run, including when results are partial or truncated. It never compares against restricted pages, other runs or a saved index of document numbers.
Finding codes
Severity is fixed for each code. The result explains the relevant field or table; apply any correction yourself in Confluence.
| Code | Severity | Meaning and next step |
|---|---|---|
| NO_PROPERTIES_MACRO | error | No Content Properties macro was found and the check requires one. Add the appropriate macro or change the selection/rule. |
| MACRO_ID_NOT_FOUND | error | No macro matches the requested Content Properties ID. Compare the check's ID with the macro setting. |
| DUPLICATE_MACRO_ID | warning | Several macros have the selected ID. Their readable values are combined; review whether the ID should identify one macro. |
| NESTED_IN_MACRO | warning | The macro is inside another macro. The native report may omit it; review the nesting. |
| UNREADABLE_BODY | unverifiable | The page body could not be read. Retry or review access; the app does not guess its contents. |
| NO_TABLE | error | The macro contains no table. Review its body. |
| MULTIPLE_TABLES | warning | The macro has several tables; only the first is checked. Review the other tables separately. |
| NO_HEADER | error | No header row or header column. The native report ignores this table; add the appropriate header. |
| HEADER_ROW_AND_COLUMN | error | A header row and a header column are both present. Use one orientation. |
| MERGED_CELLS | unverifiable | Merged cells prevent reliable interpretation. Review the layout and separate cells if appropriate. |
| ROW_WITHOUT_KEY | warning | Rows without a key/header cell are ignored (for example, “1 row has no header cell and is ignored.”). Add the intended key or remove irrelevant rows. |
| EXTRA_COLUMNS | warning | Only the first value column is checked. Review extra columns separately. |
| EXTRA_ROWS | warning | Only the first value row is checked in a horizontal table. Review extra rows separately. |
| EMPTY_KEY | error | A header cell is empty. Supply its intended field key. |
| MACRO_IN_KEY | error | A macro is in the key column, which Confluence does not support. Use a text key. |
| KEY_LEADING_WHITESPACE | warning | A key starts with whitespace. Remove it if the native report cannot match the key. |
| DUPLICATE_KEY | error | A key occurs more than once within a table. The first value is used; review the duplicate rows/columns. |
| CONFLICTING_KEY | warning | Selected macros on one page give different values for the same key. The first readable value is used; reconcile them. |
| MISSING_KEY | error | A required key is absent. Add it or adjust the rule. |
| KEY_VARIANT | warning | A key differs from the expected spelling only in case or punctuation. Its value is still checked; align the key spelling. |
| EMPTY_VALUE | error | A value must not be empty. Whitespace and template placeholders count as empty. |
| INVALID_DATE | error | The text is not a real date in a chosen format. Review the date and the accepted formats. |
| VALUE_NOT_ALLOWED | error | The value is outside the allowed list. Review the value or update that rule. |
| VALUE_NOT_CHECKABLE | unverifiable | A value uses unsupported/mixed content, such as another macro or nested table. Review it manually; external macro output is not fetched. |
| DUPLICATE_VALUE | error | A field marked unique repeats on other checked pages (for example, “1 other page” or “2 other pages”). Follow the related page links and review the numbers. |
Limits and recovery
- Visibility: only current published pages you can read are checked, including Live Docs. The app excludes blogposts, drafts and archived pages. Pages can change while a run is in progress; rerun after changes.
- Coverage: vertical and horizontal tables are supported in the Storage representation. Unusual structures, nested macros or mixed values may be unverifiable. This check does not guarantee that a native report includes every page, and it does not certify ISO or regulatory compliance.
- Selection size: at most 1,000 pages selected per run; the shared monthly allowance permits up to 500 page-check attempts. Narrow the label, space or page tree when truncated. Narrow results also narrow the set in which duplicates can be found.
- Rate limits: a Confluence slowdown can pause a run with a countdown. The app tries automatic continuation at most three times per run; after that, use Continue when the countdown ends. Use Pause during page selection or checking to stop automatic continuation. When the app is busy, it shows "The app is busy with another task." The run waits briefly and continues automatically without using these three retries. Use Cancel to stop the wait.
- Site usage budget: selection requests, checks of the root page and content-reading attempts share an hourly request budget across the site's users. Checking the root page, including when you save a check, does not consume the separate checked-page budget. The editor identifies the request budget when it prevents saving. Empty searches, failures and retries can consume the request budget. If a budget is exhausted, keep the partial result and continue after the displayed UTC reset time. Deleting checks does not reset these budgets. These are usage limits; processing speed is not guaranteed.
- Large responses and errors: if a result is too large or Confluence fails to respond, the app reports a failure instead of claiming completion. For an oversized result, narrow the selection or simplify the rules, save the changed check and use Run again. Runs with many very large pages (roughly 1 MB or more of page source each) take longer: when a request runs short of time, the app keeps the pages it has already checked and reads the rest of the batch in another request, which uses another operation and counts those pages again as page-check attempts. Pages so large that even a few of them take longer to read than one request may take can still end the run with Check interrupted. Narrow the selection the same way: use a more specific Label, a Space key or a smaller page tree under Root page. Try again is available for temporary connection or storage failures, not for repeating the same oversized result or the same large pages. Unreadable content remains marked or skipped.
- Access and licensing: production requires an active Marketplace license. With an inactive license, you can still view and delete saved checks; saving and running are blocked. Ask a Confluence admin to review the license in Manage apps.
- Scope: no page editing, document approval, publication enforcement, private schemas, background schedules, notifications, CSV export or AI. The app never assigns document numbers or resolves mentions to people.
Delete saved checks
Choose Delete on a saved check and confirm. Cancel leaves it saved. To remove all schemas for everyone on the site, choose Delete all checks, type exactly DELETE and confirm. Deletion affects the shared configuration and leaves Confluence pages unchanged. Both deletion options remain available with an inactive license. Deleting a single check uses one of the site's 26 monthly operations and the shared byte allowance. When the remaining monthly allowance no longer covers a deletion, or during a temporary service pause, that single deletion is declined and the saved check remains; you can delete it once the allowance renews at the start of the next calendar month (UTC), or use Delete all checks to remove all saved checks on the site. Delete all checks uses its own monthly reserve instead of the 26 operations and works once per calendar month (UTC), including one retry if a run is interrupted, even when the monthly allowance is exhausted or during a temporary service pause. Once completed or after its reserve is used, Delete all checks is available again once the allowance renews at the start of the next calendar month (UTC). Removing the app from the site starts Atlassian's Forge retention process for all app storage, including saved checks, and is possible at any time.
Deleting schemas does not delete the site usage counter. Uninstalling the app starts Atlassian's Forge-hosted storage lifecycle; it does not promise immediate removal of platform recovery copies. See Privacy and security for retention and recovery limits.
Monthly usage allowance
Each site shares 26 operations and up to 500 page-check attempts per calendar month (UTC), plus 110 saved-check loads. Opening the app or another page of the list uses one saved-check load. Editing, duplicating or starting a saved check loads that check alone and uses two more. Saving, deleting a single check, checking a selected root page, selecting pages and checking a batch each use an operation; Delete all checks uses a separate monthly reserve once per calendar month (UTC), including one retry if interrupted, instead of one of the 26 operations. Retries count again. Existing hourly limits still apply.
Opening the app reads only a short list of check names, sizes and field counts. The list shows three checks at a time; use Saved checks page or More saved checks to navigate. The first opening on a site prepares this list once and uses two saved-check loads. If checks were saved before the list existed, that opening reads them once to learn their names and sizes, and it is the only opening that does. This covers older checks that can add up to at most 32 KiB, counting a check whose size was never recorded as 8 KiB. A larger older collection may appear as Saved check 1, Saved check 2, and so on. Saving a new check is available again when the checks that remain leave room for it inside 32 KiB, counting a check whose size was never recorded as 8 KiB. A change that makes one of those checks smaller can be saved sooner. Their full names and rules remain available when opened. Saved checks share 32 KiB per site, with at most 50 checks and 8 KiB per check.
A tested month with 50 checks filling 32 KiB supports 30 openings plus 10 runs of 25 pages each. With 10 small checks, 100 openings are supported. These examples use short check names and evenly sized checks, without editing during the month. Larger individual checks, long names, extra list pages, edits and retries can use the shared allowance sooner. Settings and usage totals share 125 KB of reserved reads and 160 KB of reserved writes per month, including a safety allowance for storage operations and a fixed reserve of 6 KiB of reads and 10 KiB of writes for Delete all checks. A separate tested month starting with an empty list supports 25 saves of small checks, including a list refresh after each save. Those 25 checks can all be deleted in another month with no other operations. These are separate examples, not combined allowances. Saving, changing or deleting a check first reads the whole list of checks, so the more checks a site keeps, the fewer of these fit in a month. In tested months, a site with 40 checks of about 650 bytes each could delete 12 of them, and a full collection of 50 checks filling 32 KiB allowed 10 changes, each time with the list reloaded afterwards. A check that fills the full 8 KiB limit adds about 8 KB of reads every time it is run: after 30 openings, 6 runs of it fit in the month when the saved checks together fill the full 32 KiB, and 6 runs when it is the only saved check. Slow loads stop after one second for a list or two seconds for a check or Delete all checks; try again if needed. Such attempts can still use the allowance. The next UTC month resets the allowance. Existing results in the tab remain available.
During a temporary service pause, saved checks and results already in the current tab remain readable, and Delete all checks remains available once per calendar month (UTC) through its dedicated reserve; new checks, changes, single-check deletion and page reads are paused. When the remaining monthly allowance no longer covers a deletion, a single-check deletion is declined and can be made again once the allowance renews at the start of the next calendar month (UTC). Delete all checks remains available once per calendar month (UTC) until its reserve is used, and again at the start of the next calendar month; a Confluence admin can also remove the app from the site at any time. Results are still discarded when the tab closes. Removing the app follows Atlassian’s data-retention policy.
Monthly usage totals and coordination records contain no account IDs or customer content. They are shared by the installation, survive deletion of saved checks, and roll over when work starts in a new UTC month.