Sync and Data Freshness

User Management maintains a local copy of your organization's user data in Forge SQL. This page explains how synchronization works, what triggers it, and how to plan around sync timing for large organizations.

How Sync Works

The app cannot query Atlassian's Organization API in real time for every page load or operation. Instead, it mirrors user, group, and product access data into its own Forge SQL database. Each sync cycle pulls the latest state from the Organization API and updates the local copy.

Real-Time Data Is Not Available

Due to Forge platform constraints, the app cannot stream live changes from Atlassian. All data shown in the app reflects the state as of the last completed sync. If you need current data before a bulk operation, trigger a manual sync first.

Sync Types

The app uses five sync types, each triggered by different conditions.

Sync Type	Trigger	Purpose
Initial Full Sync	First app launch after installation	Populates the local database with all users, groups, and product access data from your organization
Daily Scheduled Sync	Runs automatically every 24 hours at the configured time	Keeps the local data current with changes made in admin.atlassian.com, SCIM provisioning, or other sites
Pre-Operation Sync	Automatically before bulk operations and automated tasks	Ensures actions target up-to-date user states, reducing the risk of operating on stale data
Manual Sync	Click "Sync Users" in the User Browser	On-demand refresh when you know external changes have occurred (SCIM updates, admin.atlassian.com changes)
Post-Operation Sync	Automatically after bulk operations or automated tasks complete	Captures the results of the app's own actions so the User Browser reflects the new state

Performance Benchmarks

Sync duration depends on the total number of users and groups in your Atlassian organization. These benchmarks are based on observed production data.

Organization Size	Approximate Sync Duration
~900 users	~1 minute
~1,000+ users	20+ minutes
~120,000 users + 110,000 groups	~24 - 28 hours

Schedule Syncs During Off-Peak Hours

For organizations with 1,000+ users, configure the daily scheduled sync to run during off-peak hours (evenings or weekends in your primary timezone). This avoids sync-related slowdowns during business hours. Configure the sync schedule in Settings.

SCIM and Identity Provider Sync

If your organization uses an Identity Provider (IdP) such as Okta, Azure AD, or Google Workspace with SCIM provisioning, user and group changes originate in the IdP and propagate to Atlassian via SCIM. The app's sync process then picks up these SCIM-provisioned changes from the Organization API.

This creates a two-stage pipeline:

IdP to Atlassian - Your IdP pushes changes via SCIM to Atlassian Cloud (timing depends on your IdP configuration)
Atlassian to App - The app's next sync cycle reads the updated data from the Organization API

The total delay before changes appear in the app is the sum of both stages. For time-sensitive changes, trigger a manual sync after confirming the SCIM provisioning has completed in admin.atlassian.com.

SCIM-Managed Groups Are Read-Only

Groups provisioned by SCIM cannot be modified through the app. Attempts to add or remove users from SCIM-managed groups through bulk operations will fail. Make these changes in your IdP instead.

When to Trigger Manual Sync

A manual sync ensures the app reflects the latest organization state. Trigger one before any of these scenarios:

Before a major bulk operation - Ensures you are acting on current user data, not stale records from the last scheduled sync
After changes in admin.atlassian.com - If you added or removed users, changed group memberships, or modified product access outside the app
After SCIM provisioning changes - When your IdP has pushed updates and you need them reflected immediately
Before running an automated task for the first time - Verify the saved filter returns the expected users with current data
After an API key renewal - Confirms the new key works and the sync completes without errors

Trigger a manual sync from the User Browser by clicking the "Sync Users" button.

What Gets Synced

Each sync cycle updates the following data in the local Forge SQL database:

User accounts - Name, email, account status (active, suspended, deactivated, closed), last active timestamp
Group memberships - Which groups each user belongs to, including SCIM-provisioned groups
Product access - Which Atlassian products each user can access (Jira Software, JSM, Confluence, Jira Product Discovery, Bitbucket, Compass)
Site assignments - Which sites each user has access to in multi-site organizations
Roles - User roles across the organization (Organization Admin, Site Admin, User Access Admin, etc.)

Data Freshness

The data shown in the Dashboard and User Browser is only as fresh as the last completed sync. Keep these points in mind:

The daily scheduled sync runs once every 24 hours. Changes made between syncs are not visible until the next sync completes.
Pre-operation syncs run automatically before bulk operations and automated tasks, reducing the window for stale data.
The "Last Synced" timestamp in the User Browser shows when the most recent sync finished.
If user counts in the Dashboard seem incorrect, a manual sync usually resolves the discrepancy.

Troubleshooting

Sync is taking longer than expected

Sync duration scales with the number of users and groups. For large organizations (1,000+ users), syncs can take 20 minutes or more. For very large organizations (100,000+ users), expect 24+ hours for a full sync. This is normal and does not indicate an error. Do not trigger additional syncs while one is in progress.

User Browser shows outdated information

If the User Browser does not reflect recent changes:

Check the "Last Synced" timestamp to see when data was last refreshed
Click "Sync Users" to trigger a manual sync
Wait for the sync to complete (check the sync status indicator)
Reload the User Browser page

Sync fails or does not complete

Common causes for sync failures:

Expired Organization API Key - Check the key status in Settings. If expired, create a new key at admin.atlassian.com and update the app configuration.
Invalid API Key permissions - The API key must have organization-level read access. Verify the key scope in admin.atlassian.com > Settings > API keys.
Network timeout - Very large organizations may hit timeout limits during sync. If syncs consistently fail to complete, contact support.

Automated task ran on stale data

Automated tasks trigger a pre-operation sync before execution. However, if the pre-operation sync takes longer than expected (common in large organizations), the task may start before the sync finishes. To avoid this:

Schedule automated tasks during off-peak hours when sync completes faster
Run a manual sync and confirm completion before manually triggering an automated task
For critical operations, use manual bulk operations instead of scheduled tasks so you can verify data freshness first

Dashboard user counts do not match admin.atlassian.com

Small discrepancies between the app's Dashboard and admin.atlassian.com are expected between sync cycles. If counts differ after a sync:

Confirm the sync completed (check "Last Synced" timestamp)
Verify you are comparing the same scope (the app filters by the selected site; admin.atlassian.com shows organization-wide totals)
JSM customers, JPD contributors, and Confluence guests are not counted as billable users

SCIM changes not appearing after sync

If SCIM-provisioned changes are not visible after a manual sync:

Verify the SCIM provisioning completed in your IdP's audit log
Check admin.atlassian.com to confirm the changes propagated to Atlassian
Trigger another manual sync in the app - the first sync may have started before SCIM provisioning finished

Sync Functionality - Sync controls in the User Browser
Searching and Filtering - Finding users after sync
Creating Automated Tasks - Tasks that depend on synced data
Dashboard - User counts and activity metrics
Settings - Configuring sync schedule
Organization API Key - API key required for sync