Overview
Backstage Sync for Compass automatically synchronizes your Backstage Software Catalog with Atlassian Compass, keeping your component information up-to-date across both platforms.
Getting Started
Prerequisites
- Admin access to Atlassian Compass
- Backstage instance with API access
- API token or OAuth credentials for Backstage
Initial Setup
1. Install the App
- Navigate to Compass Admin Settings
- Find "Backstage Sync Configuration" in the apps section
- Click to open the configuration page
2. Configure Backstage Connection
- Enter your Backstage instance URL (e.g., https://backstage.company.com)
- Provide authentication credentials:
- API Token (recommended)
- Or OAuth client ID/secret
- Click "Test Connection" to verify setup
3. Configure Sync Settings
- Sync Schedule: Choose between hourly, daily, or real-time sync
- Component Mapping: Select how Backstage components map to Compass
- Field Mapping: Configure which Backstage fields sync to Compass attributes
- Sync Direction: Enable unidirectional or bidirectional sync
Features
Automatic Component Discovery
The app automatically discovers new components in your Backstage catalog and creates corresponding components in Compass.
Real-time Updates
When webhook integration is enabled, changes in Backstage are reflected in Compass within seconds.
Sync Dashboard
Access the global Sync Dashboard to:
- View overall sync status
- Monitor sync performance
- Review error logs
- Track component mapping
Component-Level Sync Status
On each Compass component page, view:
- Last sync timestamp
- Sync history
- Field-level sync status
- Manual sync trigger
Using the App
Viewing Sync Status
1. Navigate to Apps → Backstage Sync Dashboard
2. View the summary cards showing:
- Total components synced
- Last sync time
- Success/failure rates
- Pending sync queue
Triggering Manual Sync
1. Go to the Sync Dashboard
2. Click "Sync Now" button
3. Monitor progress in real-time
Troubleshooting Sync Issues
Component Not Syncing
- Verify component exists in Backstage catalog
- Check component meets filter criteria
- Review error logs in Sync Dashboard
- Ensure proper permissions for both systems
Field Mapping Issues
- Navigate to Admin Configuration
- Review Field Mapping settings
- Ensure field names match between systems
- Check data type compatibility
Authentication Errors
- Verify API token is valid
- Check token has required permissions
- Test connection from Admin page
- Review network connectivity
Webhook Configuration
Setting Up Webhooks
1. Copy webhook URL from Admin Configuration
2. In Backstage, configure webhook for catalog events:
catalog:
webhooks:
- url: https://your-compass-instance.atlassian.net/gateway/api/compass/backstage-webhook
events:
- entity.create
- entity.update
- entity.delete
3. Test webhook with sample event
Supported Events
- Component created
- Component updated
- Component deleted
- Relationship changed
- Metadata updated
Best Practices
Optimize Sync Performance
- Use incremental sync when possible
- Configure appropriate sync frequency
- Filter unnecessary components
- Monitor API rate limits
Data Consistency
- Establish clear ownership model
- Define primary source of truth
- Use field mapping for standardization
- Regular audit of synced data
Security Considerations
- Rotate API tokens regularly
- Use least-privilege access
- Monitor access logs
- Enable audit trails
Common Use Cases
Development Teams
- Keep service ownership updated
- Track technical documentation links
- Maintain dependency relationships
- Sync deployment information
Platform Teams
- Centralize service catalog
- Enforce naming conventions
- Track compliance metadata
- Monitor service health
Management
- Unified view of services
- Track ownership changes
- Monitor service lifecycle
- Generate compliance reports
FAQ
Q: How often does the sync run?
A: By default, sync runs hourly. You can configure this to run more or less frequently based on your needs.
Q: Can I exclude certain components from syncing?
A: Yes, use the filter configuration in Admin settings to include/exclude components based on type, tags, or custom criteria.
Q: What happens to deleted components?
A: Depending on your configuration, deleted components can be either marked as deprecated or removed from Compass.
Q: Is historical data preserved?
A: Compass maintains component history. The sync app provides audit logs for sync operations.
Q: Can I sync custom fields?
A: Yes, custom Backstage fields can be mapped to Compass custom fields through the Field Mapping configuration.
Support
Getting Help
- Review this documentation
- Check the Sync Dashboard for error details
- Contact support at support@quantify.tech
- Report issues via Atlassian Marketplace
Feature Requests
Submit feature requests through:
- Atlassian Marketplace reviews
- Support email
- Community forums
Updates and Changelog
The app is regularly updated with new features and improvements. Check the Marketplace listing for the latest version and changelog.