> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**. 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

| 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 **`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.

### Navigation Flow

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

| 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

* **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

| 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    |