Link a Confluence page to your knowledge base
Product changes
Previously, a JSM project admin could link a full Confluence space or a Confluence folder (native or cross-site) to the Knowledge Base. This feature introduces Granular Linking — Page Support, allowing project admins to link an individual Confluence page (and its descendants) directly to the Knowledge Base:
Native Confluence pages — pages from a Confluence space on the same site as the JSM project.
Cross-site Confluence pages — pages from a Confluence space on a different Atlassian site within the same organisation.
This feature launches after Multi-Linking (kb_multi_linking_support_enabled) and Folder Support (kb-confluence-granular-folder-support) and coexists with them — pages can be mixed with spaces, folders, and third-party sources within the same KB. Linking a page exposes that page and its descendants. Articles from all linked sources are surfaced together to Agents and Help-seekers across JSM touchpoints — Help Center, Virtual Service Agent (VSA), Issue View, and Portal. Native page articles can also be categorized in KB Hub.
Note: Third-party sources (SharePoint / Google Drive) already supported folder-only linking and are unchanged by this feature. Page linking applies to Confluence Cloud only (native + cross-site); Confluence Server / Data Centre continues to support space linking only.
Before
For Confluence, project admins could link an entire space or a folder to the Knowledge Base. Linking a specific page tree (a page plus its descendants) was not possible.
After
Project admins can now link a Confluence page (native and cross-site) directly to the KB. Linking a page exposes that page and its descendants, giving finer-grained control over which content is surfaced to agents and help-seekers. Pages coexist with space, folder, and third-party sources in the same KB.
Key behaviours
Page linking includes descendants. Linking a page exposes that page and its child pages. The picker label may say "Specified content", but the effective scope is the page tree rooted at the selected page. This is expected behaviour.
Permission inheritance for display. A page inherits and displays the view/edit permissions of its parent space in KB Settings. The displayed value is the parent space's permission, not the page's own effective permissions — so it may not reflect the actual access for a given user if the page itself is restricted in Confluence.
Page permissions cannot be updated from KB Settings. Page sources do not support view/edit permission updates. The current inherited space permission is shown, but all other permission options are disabled (same posture as folders).
Visibility cross-link rule. A page already linked as INTERNAL cannot be linked as EXTERNAL. The reverse is allowed — a page already linked as EXTERNAL can also be linked as INTERNAL.
Feature-gate dependency on Folder Support. The specified-content picker currently requires
kb-confluence-granular-folder-supportas well askb-confluence-granular-page-support. Turning on only the page flag is not sufficient for the picker to appear.Confluence Cloud only. Page linking is not available for Confluence Server / Data Centre connections.
Article view. Native Confluence articles open as an iframe in the same tab. Cross-site (and typically 3P) articles open in a new tab to the source.
KB Hub categorization is native-only. Articles from a linked native page (including the linked page itself and its children) can be categorized in KB Hub. Cross-site / third-party article categorization remains greyed out.
Overview page caveat. The Overview page can surface as covering all articles because it acts as the default parent page for a Confluence space. This is expected — do not treat it as a regression without confirming against this caveat.
Failure scenarios
Scenario | Mitigation |
|---|---|
Project admin cannot see pages / "Specified content" in the Add knowledge picker | Confirm all three gates are ON for the tenant: |
Page link fails with "not allowed to link" error | Check whether the same page is already linked as INTERNAL and the admin is trying to link it as EXTERNAL — that direction is blocked by design. For cross-site, the admin must have space-admin permissions on the parent space. For persistent issues, ping |
Cross-site Confluence page not appearing in suggestions | The project admin must be a space admin of the target cross-site Confluence space, and both sites must belong to the same Atlassian organisation. If those conditions are met and the page still doesn't appear, escalate via |
Articles from a linked page not surfacing in Help Center / VSA / Issue View / KB Hub | Confirm the page was linked correctly in KB Settings and that the page flag is ON. Linking a page includes that page and its descendants — an empty page with no children will only surface itself. Indexing may take a few minutes after linking. If the issue persists, ping |
Customer says linking a page also linked child pages they did not select | This is expected. Linking a page exposes that page and its descendants. The picker label "Specified content" does not mean only the single selected page. Advise the customer this is by design. |
Customer cannot link an INTERNAL page as EXTERNAL | This is expected. A page already linked as INTERNAL cannot be linked as EXTERNAL. The reverse (EXTERNAL → INTERNAL) is allowed. |
Customer wants to roll back page linking for their project | Project admin can unlink the page from KB Settings. For a full gate exclusion, both |
Rollout plan
The delivery of incremental product changes is tracked by the Atlas project: ATLAS-115112
Timing | Targeted Users | Rollout % | Date |
|---|---|---|---|
Dogfooding | Hello (ITSD) internal | Dogfood | TBD |
Day 1 | Prod Rollout | 5% | TBD |
Day 2 | Prod Rollout | 10% | TBD |
Day 3 | Prod Rollout | 25% | TBD |
Day 5 | Prod Rollout | 50% | TBD |
Day 10 | Prod Rollout | 100% | TBD |
Roll-out Plan — Moderate Rollout
Dogfooding → 5% (1d) → 10% (1d) → 25% (1d) → 50% (2d) → 100%
Rolling back
To roll back the changes for a specific customer, ping !disturbed in #jsm-cloud-nebula to have the customer excluded using targeting rules.
Multiple cases? If you think many customers are impacted, escalate to DoS to get a decision on whether to halt the roll-out or roll back for all customers.
How do I turn it off?
Attention Support: Feature flags should only be toggled for urgent reasons, such as causing an incident or unexpected behaviours that break the product. Flags should not be toggled if the customer simply opposes the change.
Do not turn off kb-confluence-granular-folder-support or kb_multi_linking_support_enabled to mitigate a page-linking issue unless Engineering confirms that is required — those flags also gate folder linking and multi-source linking.
Per-tenant rollback — both steps are required:
Add the tenant to
page_rollback_safety_enabled(Switcheroo). This is a defensive safety net that silently drops orphaned page linked-sources after page linking is disabled.Add a per-tenant targeting override to exclude the tenant from
kb-confluence-granular-page-support(Switcheroo).
Do not turn off only kb-confluence-granular-page-support without enabling rollback safety — leftover page sources can be left in an unsafe state.
Contact !disturbed in #jsm-cloud-nebula to action this. Prefer per-customer exclusions over a full rollback. For a full rollback, escalate to DoS.
Troubleshooting
Known issues
Known Limitation Specified-content picker depends on the folder gate: Turning on only
kb-confluence-granular-page-supportis not sufficient. The specified-content dropdown does not appear unlesskb-confluence-granular-folder-supportis also ON.Known Limitation Page linking includes descendants: The picker label says "Specified content" but linking a page adds that page and all child pages. This is expected behaviour, not a bug.
Known Limitation Overview / top-level space page: Selecting the Overview (default parent) page of a space can surface as covering all articles in that space. Expected caveat — confirm before filing a regression.
Known Limitation Visibility cross-link (INTERNAL → EXTERNAL blocked): A page already linked as INTERNAL cannot be linked as EXTERNAL. The reverse (EXTERNAL → INTERNAL) is allowed.
Known Limitation Permission updates blocked: Linked page sources do not support view / edit permission updates from KB Settings. Controls are disabled / read-only (same as folders).
Known Limitation Cross-site / third-party page categorization not supported: In KB Hub, categorization is enabled for native sources only. For cross-site and third-party article rows the category control is greyed out.
Known Limitation Create / edit article and page-deletion unlink are out of scope: Create-article in KB Hub remains space-centric. Automatic unlink when a linked page is deleted in Confluence is not yet implemented.
Issue Articles not indexed immediately: Articles from a newly linked page (or newly added child pages) may not all appear in KB Hub / search immediately. Indexing delays of a few minutes are expected; persistent gaps should be escalated.
Issue Picker layout with a large number of pages: Selecting a large enough number of pages can break the picker layout. Under investigation from bug bash. [This one will be fixed]
Reporting issues
If a support case is definitely related to the changes covered by this feature, add a "caused by" link from the GSAC ticket to the relevant FD/Atlas ticket so that the Feature Lead can see it.
Add the component Knowledge Base & Confluence integration to the ticket so we can measure how much friction these changes caused in that area of the product.
How to report problems
Raise a bug in the
JSDCLOUDproject on JAC with the component —Knowledge Base & Confluence integration.Ask general questions in #jsm-cloud-nebula (use
!disturbed).
Was this helpful?