Tracking Confluence

Tracking Confluence

Discovery

What discovery provides:

• resources: List of accessible Atlassian sites with cloudId, url, name
• currentUser: Your accountId, name, and email (for CQL queries like creator = currentUser())
• spaces: Available spaces with id, key, name, type (global/personal); includes byType counts
• recentPages: Last 10 modified pages with title, spaceKey, type, modified
• hints: Pagination model info (cursor-based via _links.next)

Why run discovery:

• Get cloudId required for all Confluence API calls
• Know available spaces before creating pages
• Get your accountId for CQL queries
• Understand pagination model (cursor-based, not offset-based)

Tools

Pages: getConfluencePage(cloudId, pageId, expand?), createConfluencePage(cloudId, spaceId, title, body, contentFormat?), updateConfluencePage(cloudId, pageId, title, body, contentFormat?, versionMessage?), getConfluencePageDescendants(cloudId, pageId)

Spaces: getConfluenceSpaces(cloudId, limit?), getPagesInConfluenceSpace(cloudId, spaceId)

Comments: getConfluencePageFooterComments(cloudId, pageId), getConfluencePageInlineComments(cloudId, pageId), createConfluenceFooterComment(cloudId, pageId, body)

Search: searchConfluenceUsingCql(cloudId, cql, maxResults?)

Quick Patterns

Get cloudId (always first):

const resources = await getAccessibleAtlassianResources();
const cloudId = resources[0].id;
const siteUrl = resources[0].url;

Create page:

const spaces = await getConfluenceSpaces({ cloudId, limit: 10 });
const spaceId = spaces.results[0].id;
const result = await createConfluencePage({ cloudId, spaceId: spaceId.toString(), title: 'Page Title', body: '# Markdown', contentFormat: 'markdown' });
const url = `${siteUrl}/wiki/spaces/${spaceId}/pages/${result.id}`;

Search pages:

const results = await searchConfluenceUsingCql({ cloudId, cql: 'space = "DOCS" AND type = page AND title ~ "API"', maxResults: 10 });
results.results.forEach(page => console.log(page.title, page.url));

Update page:

const page = await getConfluencePage({ cloudId, pageId: '12345' });
await updateConfluencePage({ cloudId, pageId: '12345', title: 'Updated', body: '# New content', contentFormat: 'markdown' });

Pagination

Pattern:

let allResults = [];
let response = await getConfluenceSpaces({ cloudId, limit: 25 });
allResults.push(...response.results);
while (response._links?.next) {
  // _links.next contains the full path for the next page
  // Re-call with updated parameters from the next link
  response = await getConfluenceSpaces({ cloudId, limit: 25 /* next cursor handled internally */ });
  allResults.push(...response.results);
}

Workflows

Create page: getAccessibleAtlassianResources() → getConfluenceSpaces({cloudId}) → createConfluencePage({cloudId, spaceId, title, body}) → return ${siteUrl}/wiki/spaces/${spaceId}/pages/${result.id}

Find pages: getAccessibleAtlassianResources() → searchConfluenceUsingCql({cloudId, cql: 'type = page AND title ~ "topic"'})

Update page: getConfluencePage({cloudId, pageId}) → updateConfluencePage({cloudId, pageId, title, body, contentFormat: 'markdown'})

CQL Reference

Operators: =, !=, ~ (contains), IN, >=, <=

Fields: space, type, title, text, created, modified, creator, contributor, label

Examples: space = "DOCS" AND type = page, title ~ "API", created >= -7d ORDER BY created DESC, label = "important", creator = currentUser()

CQL Best Practices

Content Formats

Recommendation: Use markdown as the default contentFormat. Only use storage when you need Confluence-specific macros (code blocks, panels, etc.).

SDK Utilities

Import from @connections/_utils (NOT from format module):

import { format, normalize, countBy, groupBy, parseArgs, parallel } from "@connections/_utils";

Defensive Coding

// ❌ WRONG — crashes if space.links is undefined
const webUrl = space.links.webui;

// ✅ CORRECT — safe access with fallback
const webUrl = space.links?.webui ?? "N/A";

Fields commonly missing at runtime: space.links, space.homepage, page.version, result._links, start, limit, size.

Troubleshooting

Connection Resilience

• Always use cloudId from discovery output, never hardcode
• If discovery fails with auth errors, re-authenticate the Atlassian connection and re-run discovery
• For multi-site workspaces, discovery returns all accessible sites in resources[] — pick the correct cloudId for the target site

Output Format

Present results as a structured report:

Tracking Confluence Report
══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations