Request

Response

    Working with Exchange Updates

    Overview

    Exchange updates enable multi-user collaboration where multiple team members can work with the same exchange. When one user publishes changes to an exchange, other users need to synchronize their local copy with the latest cloud version. This guide explains how to implement update workflows using LoadLatestExchange and related APIs.

    Understanding Exchange Synchronization

    When working with exchanges in a collaborative environment, the SDK maintains two states:

    • Cloud State: The latest published version stored in ACC/BIM360
    • Local State: The loaded version in the host application

    These states diverge when:

    • Another user publishes updates to the exchange
    • You’ve loaded an older revision
    • Network synchronization was interrupted

    When to Use LoadLatestExchange

    Use LoadLatestExchangeAsync when you need to synchronize a loaded exchange with the latest cloud version:

    Typical Scenarios:

    1. After receiving update notifications - Another team member published changes
    2. Before making your own changes - Ensure you’re working with the latest version
    3. After network reconnection - Sync exchanges that may have been updated while offline
    4. Periodic refresh - In long-running sessions, periodically check for updates

    When NOT to Use:

    • First-time loading - Use LoadExchange instead
    • Exchange not yet loaded - LoadLatestExchange requires the exchange to already be loaded
    • No cloud connection - Requires network access to fetch updates

    Implementation Patterns

    Basic Update Implementation

    public async Task UpdateExchangeToLatest(string exchangeId)
    {
        try
        {
            // Call LoadLatestExchange to synchronize with cloud
            await connectorAPI.LoadLatestExchangeAsync(exchangeId);
            
            // The SDK automatically triggers OnGetLatestExchangeDataAsync
            // in your BaseExchangeModel implementation
        }
        catch (Exception ex)
        {
            Logger.LogError($"Failed to update exchange {exchangeId}: {ex.Message}");
        }
    }
    
    Show More

    Checking for Updates

    Use GetLatestUpdatesForExchangesAsync to check if updates are available without loading them:

    public async Task<bool> CheckForUpdates(List<ExchangeItem> loadedExchanges)
    {
        // Returns list of exchanges that have newer versions available
        var updatedExchanges = await baseModel.GetLatestUpdatesForExchangesAsync(loadedExchanges);
        
        if (updatedExchanges.Any())
        {
            // Notify user that updates are available
            foreach (var exchange in updatedExchanges)
            {
                bridge.SendNotification(
                    $"Exchange '{exchange.Name}' has been updated by {exchange.LastModifiedBy}",
                    Severity.Information
                );
            }
            return true;
        }
        
        return false;
    }
    
    Show More

    Handling Local Uncommitted Changes

    The SDK does not automatically preserve uncommitted local changes when updating. Implement a workflow to handle this:

    public async Task SafeUpdateExchange(ExchangeItem exchangeItem)
    {
        // Check if local changes exist
        bool hasLocalChanges = CheckForLocalModifications(exchangeItem);
        
        if (hasLocalChanges)
        {
            // Option 1: Warn user and get confirmation
            bool proceed = await ShowUpdateConfirmationDialog(
                "Updating will discard local uncommitted changes. Continue?"
            );
            
            if (!proceed)
            {
                return;
            }
            
            // Option 2: Auto-save local changes before updating
            await UpdateExchangeAsync(exchangeItem, cancellationToken);
        }
        
        // Safe to update - no local changes or user confirmed
        await connectorAPI.LoadLatestExchangeAsync(exchangeItem.ExchangeId);
    }
    
    Show More

    Multi-User Coordination Patterns

    Pattern 1: Update Before Publish

    Always update before publishing your changes to avoid overwriting others’ work:

    public async Task PublishMyChanges(ExchangeItem exchangeItem)
    {
        // Step 1: Get latest version from cloud
        await connectorAPI.LoadLatestExchangeAsync(exchangeItem.ExchangeId);
        
        // Step 2: Apply your local modifications
        await ApplyMyChanges(exchangeItem);
        
        // Step 3: Publish updated exchange
        await connectorAPI.UpdateExchange(exchangeItem.ExchangeId);
    }
    
    Show More

    Pattern 2: Periodic Sync in Long Sessions

    For long-running sessions, periodically check for updates:

    private async Task StartPeriodicUpdateCheck()
    {
        while (connectorIsRunning)
        {
            var loadedExchanges = connectorAPI.GetExchanges()
                .Where(e => e.IsLoaded)
                .ToList();
                
            var updatedExchanges = await baseModel.GetLatestUpdatesForExchangesAsync(loadedExchanges);
            
            if (updatedExchanges.Any())
            {
                // Notify user of available updates
                NotifyUserOfUpdates(updatedExchanges);
            }
            
            await Task.Delay(TimeSpan.FromMinutes(5)); // Check every 5 minutes
        }
    }
    
    Show More

    Pattern 3: Conflict Detection

    Detect potential conflicts before allowing updates:

    public async Task<ConflictStatus> DetectConflicts(ExchangeItem localExchange)
    {
        // Get latest cloud version metadata
        var latestDetails = await Client.GetExchangeDetailsAsync(
            localExchange.CollectionId, 
            localExchange.ExchangeId
        );
        
        // Compare modification times
        if (latestDetails.Value.LastModified > localExchange.LastModified)
        {
            // Check if user has local uncommitted changes
            bool hasLocalChanges = CheckForLocalModifications(localExchange);
            
            if (hasLocalChanges)
            {
                return ConflictStatus.ConflictDetected; // Both cloud and local have changes
            }
            else
            {
                return ConflictStatus.SafeToUpdate; // Only cloud has changes
            }
        }
        
        return ConflictStatus.UpToDate;
    }
    
    Show More

    Implementing OnGetLatestExchangeDataAsync

    Override this method to handle the actual data update in your host application:

    protected override async Task OnGetLatestExchangeDataAsync(
        ExchangeItem exchangeItem, 
        CancellationToken cancellationToken)
    {
        // Step 1: Remove old geometry from host application
        await RemoveOldGeometry(exchangeItem.ExchangeId);
        
        // Step 2: Fetch latest exchange data
        var exchangeData = await Client.GetExchangeDataAsync(
            exchangeItem.CollectionId,
            exchangeItem.ExchangeId,
            cancellationToken
        );
        
        // Step 3: Load new geometry into host application
        await LoadGeometryIntoHost(exchangeData);
        
        // Step 4: Preserve user preferences (visibility, selection, etc.)
        await RestoreUserPreferences(exchangeItem.ExchangeId);
        
        await base.OnGetLatestExchangeDataAsync(exchangeItem, cancellationToken);
    }
    
    Show More

    Best Practices

    Team Coordination

    1. Communicate before major updates - Let team know you’re publishing significant changes
    2. Update before making changes - Always sync to latest before starting work
    3. Publish frequently - Smaller, more frequent updates reduce conflict potential
    4. Use meaningful revision descriptions - Help team understand what changed

    Data Integrity

    1. Save before updating - Commit or publish local changes before loading latest
    2. Validate after update - Verify geometry and properties loaded correctly
    3. Handle update failures - Implement retry logic and error notifications
    4. Log update operations - Track when updates occur for debugging

    Performance Optimization

    1. Batch update checks - Check multiple exchanges in one call using GetLatestUpdatesForExchangesAsync
    2. Avoid excessive polling - Don’t check for updates too frequently
    3. Update only when needed - Use metadata comparison before full update
    4. Cancel long operations - Support cancellation tokens for large exchanges

    Error Handling

    Common Update Failures

    public async Task<bool> TryUpdateExchange(string exchangeId)
    {
        try
        {
            await connectorAPI.LoadLatestExchangeAsync(exchangeId);
            return true;
        }
        catch (UnauthorizedAccessException ex)
        {
            // User lost access to exchange
            bridge.SendNotification(
                "Access denied. You may have been removed from this project.",
                Severity.Error
            );
            return false;
        }
        catch (HttpRequestException ex)
        {
            // Network connectivity issue
            bridge.SendNotification(
                "Cannot update exchange. Check your network connection.",
                Severity.Warning
            );
            return false;
        }
        catch (Exception ex)
        {
            // Unknown error
            Logger.LogError($"Update failed: {ex.Message}");
            bridge.SendNotification(
                "Failed to update exchange. See logs for details.",
                Severity.Error
            );
            return false;
        }
    }
    
    Show More

    Complete Example: Multi-User Update Workflow

    public class CollaborativeExchangeManager
    {
        private readonly IConnectorAPI connectorAPI;
        private readonly IInteropBridge bridge;
        private readonly Dictionary<string, DateTime> localModifications = new();
        
        public async Task HandleExchangeUpdate(string exchangeId)
        {
            var exchangeItem = connectorAPI.GetExchangeItem(exchangeId);
            if (exchangeItem == null) return;
            
            // Check for local uncommitted changes
            bool hasLocalChanges = localModifications.ContainsKey(exchangeId);
            
            if (hasLocalChanges)
            {
                // Warn user about potential data loss
                bridge.SendNotification(
                    $"Exchange '{exchangeItem.Name}' has updates. Your uncommitted changes will be lost if you update now.",
                    Severity.Warning,
                    timeoutMs: 0, // Don't auto-close
                    link: null,
                    linkText: "Learn more"
                );
                
                // Optionally: offer to save first
                // await UpdateExchangeAsync(exchangeItem, CancellationToken.None);
            }
            
            // Update to latest
            await connectorAPI.LoadLatestExchangeAsync(exchangeItem.ExchangeId);
            
            // Clear local modifications tracking
            localModifications.Remove(exchangeId);
            
            // Notify success
            bridge.SendNotification(
                $"Exchange '{exchangeItem.Name}' updated to latest version.",
                Severity.Success,
                timeoutMs: 3000
            );
        }
        
        private bool CheckForLocalModifications(string exchangeId)
        {
            return localModifications.ContainsKey(exchangeId);
        }
        
        public void TrackLocalModification(string exchangeId)
        {
            localModifications[exchangeId] = DateTime.Now;
        }
    }
    
    Show More

    See Also