Request

Response

    Exchange Lifecycle and State Management

    Overview

    Understanding the exchange lifecycle is essential for building robust connectors that handle multi-user scenarios correctly. This guide explains exchange states, persistence models, and synchronization behavior in the Data Exchange SDK.

    Exchange State Models

    DataExchange vs ExchangeItem

    The SDK uses two primary models to represent exchanges at different stages:

    DataExchange - The complete exchange data model:

    public class DataExchange
    {
        public string ExchangeId { get; set; }
        public string Name { get; set; }
        public List<IElement> Elements { get; set; }
        public bool IsExchangeVisible { get; set; }
        // ... complete data representation
    }
    
    Show More

    ExchangeItem - Lightweight metadata for exchange management:

    public class ExchangeItem
    {
        public string ExchangeId { get; set; }
        public string CollectionId { get; set; }
        public string Name { get; set; }
        public bool IsLoaded { get; set; }
        public bool IsExchangeVisible { get; set; }
        public DateTime LastModified { get; set; }
        public string LastModifiedBy { get; set; }
        public string ProjectId { get; set; }
        public string HubId { get; set; }
        // ... metadata only, no geometry
    }
    
    Show More

    Note on LastModified: This timestamp is managed by the cloud service (ACC/BIM360) and is updated whenever an exchange is created or modified via UpdateExchangeAsync. It is the only reliable indicator for detecting whether an exchange has been updated by another user. The timestamp is monotonically increasing and can be safely used for staleness detection and synchronization logic.

    When to Use Each Model

    DataExchange is appropriate for operations that require complete exchange data:

    • Working with elements, geometry, and parameters
    • Creating or updating exchanges
    • Exporting data to other formats

    ExchangeItem is appropriate for lightweight operations and metadata access:

    • Displaying exchange lists in the user interface
    • Tracking which exchanges are currently loaded
    • Checking update status
    • Managing exchange visibility settings

    Cloud-Persisted vs Session-Local Exchanges

    Cloud-Persisted Exchanges

    Cloud-persisted exchanges have the following characteristics:

    • Stored in the ACC/BIM360 hosting provider
    • Accessible across multiple sessions and computers
    • Shared with team members based on project permissions
    • Persist indefinitely until explicitly deleted

    These exchanges are created using the CreateExchangeAsync method:

    // connectorAPI is your IConnectorAPI instance
    // Creates cloud-persisted exchange
    var exchangeItem = await connectorAPI.CreateExchangeAsync(
        "Exchange Name",
        folderId,
        projectId,
        hubId
    );
    // Exchange is immediately available in cloud
    
    Show More

    The lifecycle of a cloud-persisted exchange follows these stages:

    1. Created - Uploaded to cloud and immediately available to all team members with project access
    2. Loaded - Downloaded to the local machine and rendered in the host application
    3. Updated - Local changes are uploaded and the cloud version is incremented
    4. Unloaded - Removed from the host application but remains available in the cloud
    5. Deleted - Permanently removed from cloud storage and no longer accessible

    Session-Local Exchanges

    Session-local exchanges differ from cloud-persisted exchanges in that they:

    • Exist only within the current application session
    • Are not uploaded to cloud storage unless explicitly created via CreateExchange
    • Are lost when the application closes
    • Cannot be accessed by other users or from other computers

    Critical: An exchange is not cloud-persisted until you explicitly call CreateExchangeAsync. Simply loading an exchange from a file or programmatically creating exchange data in memory does not persist it to the cloud. The exchange will be lost when the application closes.

    Session-local exchanges are created when:

    • Loading exchange data from local files
    • Working with temporary or test exchanges
    • Using the SDK without a configured hosting provider
    • Programmatically creating DataExchange objects without calling CreateExchangeAsync

    Example of creating a session-local exchange:

    // Client is your IDataExchangeClient instance
    var exchangeData = await Client.LoadExchangeFromFileAsync("C:\\temp\\exchange.json");
    
    // ElementDataModel is part of your BaseExchangeModel implementation
    // This creates a session-local representation
    var model = ElementDataModel.Create(Client, exchangeData);
    // This exchange exists only in memory, not in cloud
    
    // To persist to cloud, you must explicitly call CreateExchange
    // connectorAPI is your IConnectorAPI instance
    var exchangeItem = await connectorAPI.CreateExchangeAsync(
        exchangeData.Name,
        folderId,
        projectId,
        hubId
    );
    
    Show More

    Automatic vs Explicit Synchronization

    Automatic Synchronization

    The SDK does not automatically synchronize exchanges with the cloud. All synchronization operations require explicit action by the application.

    Operations That Are Not Automatic:

    • Exchange data is not auto-refreshed from the cloud
    • No background polling for updates
    • Changes are not automatically merged
    • Local modifications are not auto-uploaded

    Rationale for Manual Control:

    • Prevents unexpected data overwrites during user workflows
    • Provides application control over synchronization timing
    • Reduces unnecessary network overhead
    • Enables workflow-specific synchronization patterns

    Explicit Synchronization Points

    Applications must explicitly call synchronization methods to update exchange data:

    // Check for updates - baseModel is your BaseReadWriteExchangeModel instance
    var updates = await baseModel.GetLatestUpdatesForExchangesAsync(loadedExchanges);
    
    // Synchronize specific exchange - REPLACES local data with cloud version
    // connectorAPI is your IConnectorAPI instance
    await connectorAPI.LoadLatestExchangeAsync(exchangeId);
    
    // Publish local changes to the cloud
    await connectorAPI.UpdateExchangeAsync(exchangeId);
    
    Show More

    Important: LoadLatestExchangeAsync completely replaces the local exchange data with the latest cloud version. It does not merge changes. Any uncommitted local modifications will be lost. Always publish or save your work before calling this method.

    Update Reflection from Team Members

    How Updates Are Reflected

    When a team member publishes changes to an exchange:

    1. Cloud version updates: A new revision is created in ACC/BIM360
    2. Metadata is updated: The LastModified timestamp is updated in exchange metadata
    3. Local copies become stale: Other users’ loaded copies are not automatically notified
    4. Manual synchronization required: Users must explicitly call LoadLatestExchangeAsync to retrieve updates

    Detecting Updates

    Implement change detection in your BaseExchangeModel. The Client property refers to the IDataExchangeClient instance available in your BaseExchangeModel:

    public async Task<List<ExchangeItem>> DetectOutdatedExchanges(List<ExchangeItem> loadedExchanges)
    {
        var outdated = new List<ExchangeItem>();
        
        foreach (var exchangeItem in loadedExchanges)
        {
            // Client is IDataExchangeClient from BaseExchangeModel
            // GetExchangeDetailsAsync returns Result<DataExchange>
            var latestDetails = await Client.GetExchangeDetailsAsync(
                exchangeItem.CollectionId,
                exchangeItem.ExchangeId
            );
            
            // Check if call succeeded and compare timestamps
            if (latestDetails.IsSuccess && 
                latestDetails.Value.LastModified > exchangeItem.LastModified)
            {
                outdated.Add(exchangeItem);
            }
        }
        
        return outdated;
    }
    
    Show More

    Notification Strategies

    Passive notification displays an indicator in the user interface without interrupting the workflow:

    // Note: ShowUpdateAvailable is not an SDK property - you implement this in your UI
    // Example: Add a custom property to your UI view model
    public class ExchangeListItemViewModel
    {
        public ExchangeItem Exchange { get; set; }
        public bool ShowUpdateAvailable { get; set; }
    }
    
    // In your update detection logic:
    foreach (var viewModel in exchangeListViewModels)
    {
        viewModel.ShowUpdateAvailable = await IsOutdated(viewModel.Exchange);
    }
    
    Show More

    Active notification alerts the user immediately with a message:

    // bridge is your IInteropBridge instance
    var latestDetails = await Client.GetExchangeDetailsAsync(
        exchangeItem.CollectionId,
        exchangeItem.ExchangeId
    );
    
    if (latestDetails.IsSuccess)
    {
        bridge.SendNotification(
            $"Exchange '{exchangeItem.Name}' was updated by {latestDetails.Value.LastModifiedBy}",
            Severity.Information,
            timeoutMs: 5000
        );
    }
    
    Show More

    Blocking notification prevents further actions until the user addresses the update:

    public async Task<bool> ValidateExchangeIsCurrent(ExchangeItem exchangeItem)
    {
        // Check if exchange is outdated
        var latestDetails = await Client.GetExchangeDetailsAsync(
            exchangeItem.CollectionId,
            exchangeItem.ExchangeId
        );
        
        if (latestDetails.IsSuccess && 
            latestDetails.Value.LastModified > exchangeItem.LastModified)
        {
            // bridge is your IInteropBridge instance
            bridge.SendNotification(
                "This exchange has been updated. Please load latest version before making changes.",
                Severity.Warning,
                timeoutMs: 0
            );
            return false;
        }
        return true;
    }
    
    Show More

    Data Persistence Guarantees

    Guaranteed Behavior

    Cloud-persisted exchanges:

    • Persist across application restarts and different computers
    • Published changes become immediately available to all team members after UpdateExchangeAsync completes
    • Remain accessible based on project permissions

    In-memory state:

    • Loaded exchanges remain in memory until explicitly unloaded or the application closes
    • Visibility state changes made via SetExchangeVisibilityAsync persist for the current session only

    Important: Exchange visibility settings are session-local state and are NOT stored in the cloud. Visibility preferences are lost when the application closes or the exchange is unloaded. If you need persistent visibility preferences across sessions, your connector must implement its own storage mechanism (e.g., user settings file, local database, or cloud preference service).

    Non-Guaranteed Behavior

    Data loss scenarios:

    • Local uncommitted changes are lost if not published before updating, unloading, or closing the application
    • Session-local exchanges (loaded from files) are not persisted and are lost when the application closes

    Synchronization limitations:

    • Automatic synchronization is not provided; applications must explicitly call LoadLatestExchangeAsync
    • Conflict resolution is not performed; LoadLatestExchangeAsync replaces local data entirely
    • The SDK uses a “last write wins” model; the most recent UpdateExchangeAsync call overwrites all previous changes

    State Transition Diagram

    Exchange Lifecycle States:
    
    [Created in Cloud] ──LoadExchange──> [Loaded in Host App]
           │                                    │
           │                                    ├──SetVisibility──> [Hidden/Shown]
           │                                    │
           │                                    ├──UpdateExchange──> [Published to Cloud]
           │                                    │
           │<──────LoadLatestExchange───────────┤
           │                                    │
           │                                    └──UnloadExchange──> [Unloaded]
           │
           └──DeleteExchange──> [Deleted from Cloud]
    
    Session-Local Exchange:
    
    [Loaded from File] ──> [In Memory Only]
                               │
                               └──App Closes──> [Lost]
    
    Show More

    Best Practices

    For Connector Developers:

    1. Track loaded state - Maintain accurate IsLoaded status for ExchangeItems
    2. Implement conflict warnings - Detect and warn about potential overwrites
    3. Preserve user preferences in memory - When updating exchanges, restore visibility and selection state after the update completes (Note: these are session-local and not persisted to cloud)
    4. Handle partial failures - Not all exchanges in a batch update may succeed; implement per-item error handling
    5. Provide update status - Show clear feedback when sync operations complete

    Handling Partial Failures

    When updating multiple exchanges, some operations may fail while others succeed. The SDK does not provide atomic batch operations, so you must handle each exchange individually:

    public async Task<BatchUpdateResult> UpdateMultipleExchanges(List<ExchangeItem> exchanges)
    {
        var results = new BatchUpdateResult();
        
        foreach (var exchange in exchanges)
        {
            try
            {
                await connectorAPI.LoadLatestExchangeAsync(exchange.ExchangeId);
                results.Succeeded.Add(exchange.ExchangeId);
            }
            catch (UnauthorizedAccessException ex)
            {
                // User lost access to this specific exchange
                results.Failed.Add(new FailureInfo
                {
                    ExchangeId = exchange.ExchangeId,
                    ExchangeName = exchange.Name,
                    Reason = "Access denied",
                    Exception = ex
                });
            }
            catch (HttpRequestException ex)
            {
                // Network or service error
                results.Failed.Add(new FailureInfo
                {
                    ExchangeId = exchange.ExchangeId,
                    ExchangeName = exchange.Name,
                    Reason = "Network error",
                    Exception = ex
                });
            }
            catch (Exception ex)
            {
                // Unknown error
                results.Failed.Add(new FailureInfo
                {
                    ExchangeId = exchange.ExchangeId,
                    ExchangeName = exchange.Name,
                    Reason = ex.Message,
                    Exception = ex
                });
            }
        }
        
        // Report results to user
        if (results.Failed.Any())
        {
            string message = $"Updated {results.Succeeded.Count} exchanges successfully. " +
                            $"{results.Failed.Count} failed: {string.Join(", ", results.Failed.Select(f => f.ExchangeName))}";
            bridge.SendNotification(message, Severity.Warning);
        }
        
        return results;
    }
    
    public class BatchUpdateResult
    {
        public List<string> Succeeded { get; set; } = new();
        public List<FailureInfo> Failed { get; set; } = new();
    }
    
    public class FailureInfo
    {
        public string ExchangeId { get; set; }
        public string ExchangeName { get; set; }
        public string Reason { get; set; }
        public Exception Exception { get; set; }
    }
    
    Show More

    For Multi-User Scenarios:

    1. Update before publish - Always sync to latest before publishing changes
    2. Check for updates regularly - Implement periodic update detection
    3. Save before syncing - Publish local changes before loading latest
    4. Communicate with team - Use notifications to inform about update availability
    5. Test offline scenarios - Ensure graceful handling when network unavailable