Skip to main content

​
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. Its “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

  • Duality of Pages: Confluence pages can behave as both folders and files. StackOne surfaces this by:
    • Including all pages in both the listFolders and listFiles endpoints
    • Adding metadata flags to indicate whether a page has content, children, or both

​
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.
  1. Site Selection Users first select a site (Confluence instance), if multiple are connected.
  2. Space Listing StackOne loads all spaces (mapped to drives) within the site.
  3. 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)
  4. Nested Pages Pages can be expanded recursively to reveal their nested children.
  5. 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

​
API Usage

StackOne uses the CQL (Confluence Query Language) API to efficiently retrieve content and metadata.
  • 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

  • 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

  • API Token with optional scopes
    • Maximum 1-year expiry
  • Full set of integration scopes:
    • write:confluence-content
    • read:confluence-space.summary
    • read:confluence-props
    • write:confluence-props
    • read:confluence-content.all
    • read:confluence-content.summary
    • search:confluence
    • readonly:content.attachment:confluence

​
Summary