Raledo

Appearance

Component Sync for Jira - User Manual ​

Table of Contents ​

  1. Overview
  2. Key Features
  3. Prerequisites
  4. Installation
  5. Getting Started
  6. Managing Master Components
  7. Selecting Spaces
  8. Synchronizing Components
  9. Troubleshooting
  10. Best Practices
  11. FAQ
  12. Known Limitations

Overview ​

Component Sync for Jira is a Jira Cloud administration tool that helps standardize component management across multiple spaces. The app allows administrators to maintain a master list of components and synchronize them to selected spaces automatically or on-demand.

Target Audience: Jira administrators managing multiple spaces who need consistent component definitions across their Jira instance.

Key Benefit: Eliminates the need to manually create and maintain identical components across multiple spaces, reducing administrative overhead and ensuring consistency.

Key Features ​

  • Master Component Management - Create and maintain a centralized list of components with names, descriptions, and assignee types
  • Space Selection - Choose which spaces receive synchronized components through an easy-to-use interface
  • Auto-Sync - Automatically add new master components to selected spaces when they are created
  • Manual Sync - Trigger on-demand synchronization to update all selected spaces at once
  • Error Tracking - View detailed error logs when synchronization issues occur
  • Bulk Operations - Select or deselect all spaces with a single toggle

Prerequisites ​

Before using Component Sync for Jira, ensure you have:

  • Jira or Site Administrator privileges. This is required to install, setup, configure and use the app.
  • At least one Jira space (for testing synchronization)

Installation ​

Step 1: Install the App ​

  1. Log in to your Jira Cloud site as an administrator
  2. Navigate to Settings (gear icon) > Apps
  3. Click Manage apps in the sidebar
  4. Click Upload app or follow the installation link provided by your Forge app developer
  5. Enter the app installation URL or upload the app file
  6. Click Upload to begin installation

Step 2: Grant Permissions ​

During installation, Component Sync for Jira will request the following permissions:

  • manage:jira-space - Required to create and modify components in spaces
  • read:jira-work - Required to read space and component information
  • write:jira-work - Required to create components
  • storage:app - Required to store master component list and configuration
  1. Review the requested permissions
  2. Click Grant access to authorize the app

Step 3: Access the Admin Page ​

  1. Navigate to Settings (gear icon) > Apps
  2. Right click the "..." menu next to Apps and select Manage Apps
  3. In the sidebar, look for Component Sync for Jira under the Apps section
  4. Click to open the administration interface

Getting Started ​

Once installed, the Component Sync for Jira admin page displays three main tabs:

  1. Components - Manage your master component list
  2. Spaces - Select which spaces receive synchronized components
  3. Sync - Control synchronization and view error logs

The app version is displayed in the top-right corner of the admin page.

Initial Setup Workflow ​

For first-time setup, follow this recommended sequence:

  1. Create master components in the Components tab
  2. Select target spaces in the Spaces tab
  3. Enable auto-sync or manually trigger sync in the Sync tab
  4. Monitor the sync results and error log

Managing Master Components ​

The Components tab allows you to create and maintain a master list of components that will be synchronized to selected spaces.

Adding a New Component ​

  1. Navigate to the Components tab
  2. Click the Add Component button in the top-right corner
  3. In the modal dialog, fill in the component details:
    • Name (required) - The component name, must be unique
    • Description (optional) - A brief description of the component
    • Assignee Type - How issues assigned to this component should be routed:
      • Space Default - Use the space's default assignee setting
      • Component Lead - Assign to the component lead (if specified)
      • Space Lead - Assign to the space lead
      • Unassigned - Leave issues unassigned
  4. Click Create to save the component

Note: If auto-sync is enabled, the new component will be automatically added to all selected spaces immediately after creation.

Editing a Component ​

  1. Locate the component in the master components table
  2. Click the Edit button in the Actions column
  3. Modify the component details in the modal dialog
  4. Click Save to update the component

Important: Editing a master component does not automatically update existing components in spaces. You must trigger a manual sync to propagate changes.

Deleting a Component ​

  1. Locate the component in the master components table
  2. Click the Delete button in the Actions column
  3. In the confirmation dialog, click Delete to confirm removal

Warning: Deleting a master component does not remove it from spaces where it has already been synchronized. You must manually delete components from individual spaces if needed.

Component Table Columns ​

The master components table displays:

  • Name - The component name
  • Description - Component description (or "-" if not provided)
  • Assignee Type - The configured assignee routing type
  • Actions - Edit and Delete buttons

Selecting Spaces ​

The Spaces tab displays all accessible Jira spaces and allows you to select which spaces should receive synchronized components. Note, that team-managed spaces are not displayed since they do not have components.

Selecting Individual Spaces ​

  1. Navigate to the Spaces tab
  2. Locate the space in the table
  3. Toggle the Component Sync switch to enable synchronization for that space
  4. The selection is saved automatically

Note: Spaces with synchronization enabled will receive all master components during the next sync operation i.e. Creating a Component, or clicking the Sync Now button.

Using the Filter ​

To quickly find specific spaces:

  1. Enter text in the Filter Spaces field at the top of the table
  2. The table will filter to show only spaces matching your search term (by name or key)
  3. Clear the filter to see all spaces again

Note: Filtering only searches spaces currently displayed on the page. Use pagination to see additional spaces.

Selecting All Spaces ​

To enable synchronization for all spaces at once:

  1. Locate the Select/Deselect All toggle in the top-right corner
  2. Toggle it to the on position
  3. All spaces across all pages will be selected

Warning: This operation affects all spaces in your Jira instance. Ensure this is your intention before proceeding.

Deselecting All Spaces ​

To disable synchronization for all spaces:

  1. Locate the Select/Deselect All toggle in the top-right corner
  2. Toggle it to the off position
  3. All spaces will be deselected

Space Table Columns ​

The spaces table displays:

  • Avatar - Space icon
  • Name - Space name
  • Key - Space key
  • Space lead - Name of the space lead (or "-" if not set)
  • Component Sync - Toggle to enable/disable synchronization for this space

Pagination ​

Spaces are displayed 25 per page. Use the pagination controls at the bottom of the table to navigate between pages.

Synchronizing Components ​

The Sync tab provides controls for synchronizing master components to selected spaces and viewing synchronization results.

Understanding Auto-Sync ​

Auto-sync automatically adds new master components to selected spaces when they are created.

How it works:

  • When enabled, creating a new master component immediately triggers synchronization to all selected spaces
  • Only newly created components are synchronized; existing components are not updated
  • Failed synchronizations are logged in the error log

To enable auto-sync:

  1. Navigate to the Sync tab
  2. Check the Enable Auto-Sync checkbox
  3. The setting is saved automatically

To disable auto-sync:

  1. Navigate to the Sync tab
  2. Uncheck the Enable Auto-Sync checkbox

Best Practice: Enable auto-sync if you frequently add new master components and want them immediately available in all spaces. Disable it if you prefer to review components before synchronizing.

Compass vs Jira Components ​

This app managed Jira Components. If your project is set to use Compass, then you will not see the Jira Components in the Components view. Use the

Performing Manual Sync ​

Manual sync updates all selected spaces with all master components.

When to use manual sync:

  • After editing master component details
  • After selecting additional spaces
  • To retry failed synchronizations
  • When auto-sync is disabled

To trigger manual sync:

  1. Navigate to the Sync tab
  2. Click the Sync Now button
  3. Wait for the sync operation to complete (a spinner indicates progress)
  4. Review the sync summary that appears after completion

Understanding Sync Summary ​

After a sync operation completes, a summary displays:

  • Successful - Number of components successfully created or updated
  • Failed - Number of components that failed to sync (see error log)
  • Skipped - Number of components that already exist and were skipped
  • Total - Total number of spaces and components processed

Note: The summary remains visible until the next sync operation.

Viewing the Last Sync Time ​

Below the Sync Now button, the timestamp of the last sync operation is displayed.

Example: "Last sync: 11/19/2025, 3:45:12 PM"

Viewing the Sync Error Log ​

The error log displays detailed information about failed synchronization attempts.

Error log table columns:

  • Space - Space key and name where the error occurred
  • Component - Name of the component that failed to sync
  • Error - Error message describing what went wrong
  • Timestamp - When the error occurred

Common errors include:

  • Permission issues (insufficient permissions to create components in the space)
  • Duplicate component names (component already exists with a different configuration)
  • Network or API failures

Clearing the Error Log ​

To clear all errors from the log:

  1. Click the Clear All Errors button
  2. In the confirmation dialog, click Clear All Errors to confirm
  3. The error log will be emptied

Note: Clearing the error log does not resolve the underlying issues. You should address the errors before clearing them.

Error Log Pagination ​

Errors are displayed 25 per page. Use the pagination controls at the bottom of the table to navigate between pages.

Troubleshooting ​

Problem: Components Not Appearing in Spaces ​

Possible Causes:

  • Space is not selected in the Spaces tab
  • Auto-sync is disabled and manual sync has not been triggered
  • Sync failed with an error (check the error log)

Solutions:

  1. Navigate to the Spaces tab and verify the space is selected
  2. Navigate to the Sync tab and click Sync Now to trigger manual sync
  3. Check the error log for any failed synchronization attempts
  4. Review the error message and address the underlying issue

Problem: Sync Fails with Permission Error ​

Error Message: "Insufficient permissions to create component in space X"

Cause: The app does not have permission to modify components in the target space, or the space has restricted permissions.

Solutions:

  1. Verify the app has the required permissions (manage:jira-space, write:jira-work)
  2. Check space permissions to ensure the app can create components
  3. Contact your Jira administrator if you cannot modify space permissions

Problem: Duplicate Component Name Error ​

Error Message: "A component with this name already exists in space X"

Cause: The space already has a component with the same name as the master component.

Solutions:

  1. Rename the master component to use a unique name
  2. Manually delete or rename the conflicting component in the target space
  3. Trigger a manual sync after resolving the conflict

Problem: Cannot Select All Spaces ​

Symptom: The "Select/Deselect All" toggle does not work

Cause: The toggle may be disabled if there are no spaces or if a sync is in progress.

Solutions:

  1. Wait for any in-progress sync operations to complete
  2. Verify that spaces exist in your Jira instance
  3. Refresh the admin page and try again

Problem: Changes to Master Components Not Reflected in Spaces ​

Cause: Editing a master component does not automatically update existing components in spaces.

Solution:

  1. After editing a master component, navigate to the Sync tab
  2. Click Sync Now to propagate changes to all selected spaces

Note: The sync operation will update existing components in spaces with the new details from the master component list.

Problem: Error Log Shows Old Errors ​

Cause: Errors remain in the log until manually cleared.

Solution:

  1. Address the underlying issues causing the errors
  2. Navigate to the Sync tab
  3. Click Clear All Errors to remove resolved errors from the log
  4. Trigger a new sync to verify issues are resolved

Best Practices ​

Component Naming Conventions ​

  • Use clear, descriptive component names that are self-explanatory
  • Establish a naming convention and document it for your team
  • Examples: "Backend", "Frontend", "Database", "API", "UI"
  • Avoid special characters that might cause issues in Jira

Managing Master Components ​

  • Create all master components before selecting spaces to avoid multiple sync operations
  • Review component details carefully before saving to minimize the need for edits
  • Use descriptions to provide context about each component's purpose
  • Set appropriate assignee types based on your team's workflow

Space Selection Strategy ​

  • Start by selecting a small number of test spaces before rolling out to all spaces
  • Use the filter to find related spaces and select them in batches
  • Document which spaces use synchronized components for future reference
  • Consider creating a Jira space category for spaces using synchronized components

Synchronization Strategy ​

  • Enable auto-sync if you manage components centrally and want immediate propagation
  • Disable auto-sync if you prefer to review and test components before synchronizing
  • Schedule regular manual syncs (e.g., weekly) if auto-sync is disabled
  • Monitor the error log regularly to catch and resolve synchronization issues promptly

Error Management ​

  • Review the error log after each sync operation
  • Address errors promptly to ensure all spaces remain synchronized
  • Document common errors and their resolutions for your team
  • Clear the error log only after verifying issues are resolved

Testing Changes ​

Before rolling out component changes organization-wide:

  1. Create a test space
  2. Select only the test space in the Spaces tab
  3. Create or modify master components
  4. Trigger a manual sync
  5. Verify the components appear correctly in the test space
  6. If successful, select additional spaces and sync again

Maintenance Tasks ​

Perform these tasks regularly:

  • Weekly: Review the error log and address any failed synchronizations
  • Monthly: Audit master components to remove unused or outdated components
  • Quarterly: Review space selections to ensure only active spaces are synchronized
  • Annually: Review assignee type settings to ensure they align with current workflows

FAQ ​

Q: What happens if I delete a master component? ​

A: Deleting a master component removes it from the master list but does not remove it from spaces where it has already been synchronized. You must manually delete the component from individual spaces if needed.

Q: Can I sync components to a single space without affecting others? ​

A: No. The sync operation affects all selected spaces simultaneously. To sync to a single space, you must deselect all other spaces first, perform the sync, then re-select the other spaces.

Q: What happens if a component already exists in a space? ​

A: If a component with the same name already exists in a space, the sync operation will skip it and log it as "skipped" in the sync summary. The existing component will not be modified.

Q: Can I sync components from spaces back to the master list? ​

A: No. Component Sync for Jira operates in one direction only: from the master list to spaces. You cannot import components from spaces into the master list.

Q: Will synchronization overwrite existing components in spaces? ​

A: No. If a component with the same name already exists in a space, it will be skipped. The sync operation only creates new components; it does not modify or delete existing ones.

Q: Can I use Component Sync with Jira Server or Data Center? ​

A: No. Component Sync for Jira is a Forge app designed for Jira Cloud only. It does not support Jira Server or Data Center deployments.

Q: How many spaces can I synchronize at once? ​

A: There is no hard limit on the number of spaces you can synchronize. However, syncing a very large number of spaces may take several minutes to complete.

Q: What permissions do I need to use this app? ​

A: You must be a Jira administrator to access the Component Sync admin page. The app itself requires manage:jira-space, read:jira-work, write:jira-work, and storage:app permissions.

Q: Can I customize which components sync to which spaces? ​

A: No. All selected spaces receive all master components. You cannot selectively sync specific components to specific spaces. If you need this functionality, consider using multiple instances of the app or manually managing components.

Q: Will auto-sync trigger for edited components? ​

A: No. Auto-sync only triggers when a new master component is created. Editing an existing master component does not trigger auto-sync. You must manually sync to propagate edits.

Q: Can I see which spaces have a specific component? ​

A: Not directly within the app. You would need to navigate to individual spaces in Jira to verify which components exist. The error log can help identify spaces where sync failed.

Q: What happens if a sync operation fails partway through? ​

A: The sync operation continues attempting to sync all components to all spaces. Failed operations are logged in the error log, and the sync summary shows which operations succeeded, failed, or were skipped.

Known Limitations ​

Sync Direction ​

Component Sync for Jira only syncs from the master list to spaces. You cannot import existing components from spaces into the master list.

One-to-All Sync Model ​

All selected spaces receive all master components. You cannot selectively sync specific components to specific spaces.

No Automatic Update Propagation ​

Editing a master component does not automatically update existing components in spaces. You must manually trigger a sync to propagate changes.

No Deletion Propagation ​

Deleting a master component does not remove it from spaces where it has already been synchronized.

Component Name Uniqueness ​

Component names must be unique within the master list. Jira also enforces component name uniqueness within each space.

Jira Cloud Only ​

The app only supports Jira Cloud. Jira Server and Data Center are not supported.

No Component Lead Management ​

The app does not manage component leads. You must manually set component leads in individual spaces if needed.

No Audit Log ​

The app does not maintain a historical audit log of sync operations beyond the current error log.

No Rollback Functionality ​

Once components are synchronized to spaces, you cannot roll back the operation. You must manually delete unwanted components from spaces.

Session Timeout ​

Long-running sync operations may be interrupted if your Jira session times out. Refresh the page and retry the sync if this occurs.

Version and Support ​

This user manual applies to Component Sync for Jira version 1.0.0 and later.

The app version is displayed in the top-right corner of the admin page. If you encounter issues not covered in this manual, note the version number when reporting problems to your system administrator or the app developer.

For questions or support, please visit our support portal or contact Raledo through the Atlassian Marketplace.

Documentation for Raledo Products

Copyright © Raledo Ltd