Confluence Connector — Unique AI Documentation

Confluence Connector

6 min read

Overview

The Confluence Connector is a service that synchronizes page content and file attachments from Confluence to the Unique knowledge base for RAG ingestion. It supports both Confluence Cloud and Confluence Data Center deployments.

For deployment, configuration, and operational details, see the IT Operator Guide.

Quick Summary

What it does: Synchronizes labeled Confluence pages and their attachments to Unique's AI knowledge base

Supported platforms: Confluence Cloud and Confluence Data Center

Authentication: OAuth 2.0 two-legged (recommended; Cloud and Data Center 10.1+) or Personal Access Token (Data Center below 10.1 only; not recommended)

Scheduling: Configurable automated scans (default: every 15 minutes)

Multi-tenancy: Multiple Confluence instances can be managed in a single deployment

Deployment: Kubernetes-based containerized application

Requirements

Confluence

Requirement Details
Confluence Cloud Active instance with an Atlassian Cloud ID
Confluence Data Center Self-hosted instance with REST API access
Authentication OAuth 2.0 application credentials (recommended) or a Personal Access Token (Data Center below 10.1 only; not recommended)
Permissions Read access to spaces and pages that should be synchronized

Prerequisites:

Authentication Methods

The connector supports OAuth 2.0 two-legged (2LO) for both Confluence Cloud and Data Center (10.1+), which is the recommended authentication method. Personal Access Token (PAT) is supported only on Data Center versions below 10.1 where OAuth 2.0 (2LO) is not available, and is not recommended. For Unique platform communication, cluster_local mode is available for in-cluster deployments and external mode for out-of-cluster deployments via Zitadel OAuth. See the Authentication Guide for full setup instructions, credential management, and token flows.

Features

Core Capabilities

Label-Driven Page Discovery

Automatic Change Detection

Attachment Ingestion

Image Ingestion

When attachment ingestion is enabled, images embedded in a Confluence page (PNG and JPEG) are inlined as base64 data URIs inside the page HTML. The connector parses each page's Confluence storage XML and replaces every <ac:image> macro that points to a Confluence attachment with an <img src="data:image/...;base64,..."> element. The result is a single self-contained page artifact per Confluence page.

Both attachments of the page itself and attachments from another page in the same instance (referenced via <ri:attachment><ri:page/></ri:attachment>) are resolved through the existing Confluence client. External image references (<ac:image><ri:url ri:value="https://..."/></ac:image>) are left untouched in the HTML and never fetched.

When inlining is enabled, image attachments are not ingested as standalone artifacts. Orphan images (attached to the page but not referenced by an in-body macro) are appended to the end of the page body so their content is still inlined. A macro-referenced image that cannot be inlined (download failure, larger than attachments.maxFileSizeMb, a MIME type not in allowedMimeTypes, or a cross-page reference whose page or filename cannot be resolved) keeps its original macro and is not ingested elsewhere.

attachments.imageOcr (enabled by default) only applies when inlining is off and images go through the standalone path. Set it to disabled to defer to the destination scope's own ingestionConfig.jpgReadMode. Other image formats (GIF, WebP, SVG, HEIC, BMP, TIFF) are not currently supported by the Unique ingestion service and should be left out of allowedMimeTypes.

Skipped Content Types

Content types database, whiteboard, and embed are explicitly skipped (no body available via API). Folders are not explicitly skipped but have no body, so they are excluded during ingestion. In both cases, descendants (such as sub-pages under a database or folder) are still discovered and ingested. Live Docs pass through as regular pages. See the Content Type Ingestion Map for the full breakdown by platform.

Scope Management

Scheduled Synchronization

Advanced Features

Multi-Tenancy

Concurrency Control

Observability

Security

v1-Compatible Key Format

How It Works

High-Level Sync Flow

Content Sync Flow

See Technical Reference for detailed architecture and flow documentation.

User Workflow

  1. Administrator Setup (One-time) - Deploy the connector - Configure tenant YAML with Confluence credentials and Unique API endpoints - Set up the root scope in Unique
  2. Confluence Users (Ongoing) - Apply the ai-ingest label to individual pages they want synchronized - Apply the ai-ingest-all label to a parent page to synchronize it and all its descendants
  3. Automated Processing - The connector scans for labeled pages on the configured schedule - Discovers pages and their attachments - Computes a diff against previously ingested content - Ingests new and updated content, removes deleted content

Limitations and Constraints

Not Supported

Considerations

Constraint Impact Mitigation
Pages must be explicitly labeled No automatic sync of unlabeled content Document the labeling workflow for end users
Single ingestion mode (flat) All pages from a space are ingested into a single scope per space Organize content into separate spaces if scope separation is needed
Horizontal scaling not supported Single instance deployment Adequate resource allocation; per-tenant concurrency tuning
Concurrent sync prevention If a sync cycle for a tenant is still running when the next is scheduled, the new cycle is skipped Adjust cron interval or concurrency settings for large instances

Standard References