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:
- After receiving update notifications - Another team member published changes
- Before making your own changes - Ensure you’re working with the latest version
- After network reconnection - Sync exchanges that may have been updated while offline
- Periodic refresh - In long-running sessions, periodically check for updates
When NOT to Use:
- First-time loading - Use
LoadExchangeinstead - 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}");
}
}
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;
}
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);
}
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);
}
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
}
}
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;
}
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);
}
Best Practices
Team Coordination
- Communicate before major updates - Let team know you’re publishing significant changes
- Update before making changes - Always sync to latest before starting work
- Publish frequently - Smaller, more frequent updates reduce conflict potential
- Use meaningful revision descriptions - Help team understand what changed
Data Integrity
- Save before updating - Commit or publish local changes before loading latest
- Validate after update - Verify geometry and properties loaded correctly
- Handle update failures - Implement retry logic and error notifications
- Log update operations - Track when updates occur for debugging
Performance Optimization
- Batch update checks - Check multiple exchanges in one call using
GetLatestUpdatesForExchangesAsync - Avoid excessive polling - Don’t check for updates too frequently
- Update only when needed - Use metadata comparison before full update
- 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;
}
}
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;
}
}