Confluence Integration
StackOne File Picker Integration: Confluence
StackOne integrates with Atlassian Confluence to support document selection and navigation through Confluence spaces and pages. Unlike traditional file systems, Confluence is a knowledge base platform, and its structure reflects that—where “pages” can act as both files and folders depending on how they are used.
This document explains how StackOne models Confluence content, how we use the API, and how the custom file picker behaves.
Confluence Structure vs StackOne Model
| Confluence Concept | StackOne Equivalent | Notes |
|---|---|---|
| Space | drive | Top-level container for content within a site |
| Page with children | folder/file | A page can act as both a folder and a file |
-
Duality of Pages: Confluence pages can behave as both folders and files. StackOne surfaces this by:
- Including all pages in both the
listFoldersandlistFilesendpoints - Adding metadata flags to indicate whether a page has content, children, or both
- Including all pages in both the
File Download
Confluence offers two endpoints for downloading files:
GET exportword?pageId={.id}GET /wiki/rest/api/content/{id}?expand=body.export_view
These allow the download of files in either:
- Word
- HTML
StackOne uses the second endpoint to download files natively and allow the export of files as .doc.
File Picker Flow
The Confluence File Picker is custom-built by StackOne to present a consistent folder-like interface.
Navigation Flow
-
Site Selection Users first select a site (Confluence instance), if multiple are connected.
-
Space Listing StackOne loads all spaces (mapped to drives) within the site.
-
Top-Level Pages Once a space is selected, users see a tree of pages. Each page is:
- Clickable as a file (if it has content)
- Expandable as a folder (if it has children)
-
Nested Pages Pages can be expanded recursively to reveal their nested children.
-
Selection Options Users can:
- Select a page as a file (if it contains content)
- Navigate through it as a folder (if it contains child pages)
StackOne Modeling Approach
| StackOne Model Object | How It Maps to Confluence |
|---|---|
drive | A Confluence space |
folder | A page with child pages |
file | A page with content or an attached document |
metadata | Indicates if an item has hasContent, hasChildren, or both |
path | Virtualized to reflect the nested hierarchy of pages within a space |
API Usage
StackOne uses the CQL (Confluence Query Language) API to efficiently retrieve content and metadata.
| Operation | API Used | Notes |
|---|---|---|
| List sites | Configured in StackOne per connected account | No Confluence API call; configuration-level |
| List spaces in site | GET /wiki/rest/api/space | Lists all available spaces |
| List pages in a space | GET /wiki/rest/api/content/search?cql=... | Filters top-level or nested pages using CQL |
| Upload attachment to page | POST /api/v2/pages | Used for file uploads |
| Download attachment | GET rest/api/content/{id}?expand=body.export_view | Direct file download endpoint |
-
Search Strategy:
- StackOne uses CQL queries to list content scoped to a space and parent page
- This allows accurate retrieval of both files and folders under any point in the hierarchy
-
Handling Dual-Use Pages:
- A page may appear as both a file and a folder
- StackOne reflects this with flags and exposes both capabilities in the picker
File Semantics
| Type | Displayed As | Condition |
|---|---|---|
| Page with body | File (can be selected) | body.storage.value present |
| Page with children | Folder (can be expanded) | ancestors.length > 0 |
- Pages without content or children are still shown but cannot be selected
- Pages with both content and children can be both selected and expanded
Permissions & Auth
-
OAuth 2.0 with Atlassian Identity
-
Required scopes:
read:confluence-content.allread:confluence-space.summarywrite:confluence-content(for uploads)
Summary
| Area | Confluence |
|---|---|
| Picker UX | Custom-built hierarchical UI |
| Root Model | Site → Space → Page (acts as file/folder) |
| File API | CQL-based search of pages and attachments |
| Folder Behavior | Pages act as folders if they contain child pages |
| File Behavior | Pages act as files if they have content or attachments |
| Selection Logic | Pages can be both selectable and expandable simultaneously |
| StackOne Normalization | All content mapped to unified file / folder objects |
Let me know if you’d like this exported to Markdown or included in a broader API reference. I can also generate sample API responses or SDK snippets if needed.