Confluence-Jira Comment Sync Connector

A bidirectional comment synchronization app for Atlassian Confluence and Jira, built with the Atlassian Forge platform. This app enables real-time synchronization of comments between Confluence pages and Jira issues, making collaboration seamless across both platforms.

Features

• Bidirectional Comment Sync: Comments flow automatically between linked Confluence pages and Jira issues
• Thread Preservation: Maintains comment threading structure across both platforms
• Real-time Updates: Comment edits synchronize automatically
• Loop Prevention: Smart detection prevents infinite sync loops
• Author Attribution: Original author names displayed in bold with platform indicator
• Space-Level Configuration: Configure default Jira projects per Confluence space
• Automatic Mapping: Manages page-to-issue mappings using native properties

Tech Stack

• Platform: Atlassian Forge, Node.js 22.x (ARM64)
• Frontend: React 18.2.0, @forge/react, @forge/bridge
• Backend: @forge/api, @forge/resolver, @forge/kvs
• APIs: Confluence API v2, Jira REST API v3, ADF (Atlassian Document Format)
• Tools: ESLint

Project Structure

Connector/
├── manifest.yml                          # App configuration and permissions
├── src/
│   ├── frontend/space-settings.jsx      # Space settings UI
│   ├── resolvers/index.js               # Backend resolver functions
│   ├── triggers/
│   │   ├── confluenceCommentCreated.js  # Confluence comment handler
│   │   ├── confluenceCommentUpdated.js  # Confluence update handler
│   │   └── jiraCommentCreated.js        # Jira comment handler
│   └── utils/
│       ├── threadingHelpers.js          # Comment posting utilities
│       ├── confluenceProperties.js      # Confluence property management
│       └── issueProperties.js           # Jira property management

Prerequisites

1. Install Forge CLI:

   npm install -g @forge/cli

2. Login to Forge:

   • Generate API token: https://id.atlassian.com/manage/api-tokens
   • Login:

     forge login

3. Requirements: Admin access to your Atlassian Confluence and Jira instance

Installation

# Install dependencies
cd ConfluenceJiraPipeline/Connector
npm install

# Deploy to Forge
forge deploy

# Install on your site
forge install

During installation:

• Select Confluence as the product
• Enter your site URL (e.g., your-site.atlassian.net)
• Approve the requested permissions

Configuration

Space Settings

1. Navigate to Space Settings > Connector Space Settings in any Confluence space
2. Select a default Jira project
3. Choose a default issue type (optional)
4. Click Save

Linking Pages to Issues

Link Confluence pages to Jira issues through the Space Settings UI by entering the page ID and issue key. Once linked, comments will sync bidirectionally.

Usage

Comment Syncing

Comments automatically sync between linked pages and issues:

• From Confluence: Comments appear in Jira with "Author Name (via Confluence):"
• From Jira: Comments appear in Confluence with "Author Name (via Jira):"
• Replies: Thread structure is preserved across platforms
• Updates: Edits sync automatically without creating duplicates

How It Works

Event Triggers

The app listens to three Forge triggers:

• avi:confluence:created:comment - Confluence comment creation
• avi:confluence:updated:comment - Confluence comment updates
• avi:jira:commented:issue - Jira comment creation

Sync Process

1. User creates/updates comment in either platform
2. Trigger fires and handler checks for sync marker (prevents loops)
3. Handler looks up linked page/issue from stored properties
4. Handler fetches user details for author attribution
5. Handler posts formatted comment to the other platform
6. Handler stores comment mapping for future updates

Loop Prevention

Hidden markers prevent infinite sync loops:

• Confluence: <span data-sync-marker> (hidden HTML)
• Jira: [synced-by: confluence→jira] (text marker)

Data Storage

• Confluence Properties: Store issue mappings and comment thread data on pages
• Jira Issue Properties: Store page mappings and root comment IDs on issues
• KVS: Store space-level default project settings

Development

Local Development

Use Forge tunnel for faster iteration without redeploying:

forge tunnel

Making Changes

1. Edit files in src/
2. Run linter: npm run lint
3. Deploy: forge deploy

Installed sites automatically receive updates.

View Logs

forge logs

Permissions

The app requires scopes to:

• Read/write Confluence pages, comments, properties, and users
• Read/write Jira issues, comments, and users
• Access app-level storage

See manifest.yml:52-66 for complete permission list.

Troubleshooting

Comments not syncing?

• Verify page-issue mapping exists in Space Settings
• Check app permissions are approved
• View logs: forge logs

Author names missing?

• Check user exists in both platforms
• Review logs for user API fetch errors

Sync markers detected incorrectly?

• Review SYNC_MARKERS arrays in trigger files

Limitations

• One-to-one page-issue mapping only
• Rich formatting may be simplified (images, tables)
• 256MB memory limit per function
• Subject to Atlassian API rate limits

Future Enhancements

• Smart panel/macro for easier linking
• Rich media support (images, attachments)
• Bulk comment import
• Multi-issue linking
• @mention translation
• Reactions and emoji sync

License

MIT

---

Documentation: https://developer.atlassian.com/platform/forge/