Request

Response

    Working with Exchange Descriptions

    Exchange descriptions provide a way to document changes made to exchanges, similar to commit messages in version control systems. This feature helps teams track the evolution of exchanges and understand what changed in each version.

    This feature is available to all users through both the SDK and Connector UI.

    This tutorial focuses on SDK usage. For UI-specific guidance, see Customizing Exchange Creation/Loading.

    Overview

    When creating or updating an exchange, you can add a description that explains what changed. These descriptions are:

    • Stored with each exchange version
    • Visible in the Connector UI version history
    • Retrievable through the SDK via revision history
    • Optional but recommended for collaboration

    Setting Descriptions

    When Creating or Updating an Exchange

    Set the Description property on the ElementDataModel before syncing:

    var elementDataModel = ElementDataModel.Create(client);
    
    // Add or modify elements
    var element = elementDataModel.AddElement("1", "Wall");
    var wallCategory = elementDataModel.Classify(element, ClassificationSystem.Category, "Walls");
    var wallFamily = elementDataModel.Classify(element, ClassificationSystem.Family, "Wall", parent: wallCategory);
    var wallType = elementDataModel.DefineType(system: "Type", name: "Generic Wall", parent: wallFamily);
    elementDataModel.SetType(element, wallType);
    
    // Set description explaining the changes
    elementDataModel.Description = "Added structural walls for Level 2 per design revision A";
    
    // Sync to exchange
    var response = await client.SyncExchangeDataAsync(exchangeIdentifier, elementDataModel);
    
    Show More

    Description Best Practices

    Write clear, concise descriptions that explain:

    • What changed
    • Why the change was made
    • Which design phase or milestone it relates to

    Good examples:

    elementDataModel.Description = "Updated HVAC duct sizes per mechanical engineer feedback";
    elementDataModel.Description = "Added fire egress doors to meet code requirements";
    elementDataModel.Description = "Removed temporary construction elements";
    

    Avoid:

    elementDataModel.Description = "Update"; // Too vague
    elementDataModel.Description = "Changed stuff"; // Not helpful
    elementDataModel.Description = ""; // Better to omit than leave empty
    

    Retrieving Descriptions

    From Exchange Revisions

    Get descriptions from the revision history:

    var exchangeIdentifier = new DataExchangeIdentifier
    {
        ExchangeId = "exchange-id",
        CollectionId = "collection-id",
        HubId = "hub-id"
    };
    
    var revisionsResponse = await client.GetExchangeRevisionsAsync(exchangeIdentifier);
    
    if (revisionsResponse.IsSuccess)
    {
        foreach (var revision in revisionsResponse.Value)
        {
            Console.WriteLine($"Revision: {revision.Id}");
            Console.WriteLine($"Date: {revision.LastModifiedUTC}");
            Console.WriteLine($"Description: {revision.Description ?? "(No description)"}");
            Console.WriteLine("---");
        }
    }
    
    Show More

    From Loaded Exchange Data

    When loading an exchange, the SDK automatically populates the Description with the latest revision’s description:

    var exchangeData = await client.GetExchangeDataAsync(exchangeIdentifier);
    
    if (!string.IsNullOrEmpty(exchangeData.ElementDataModel.Description))
    {
        Console.WriteLine($"Latest change: {exchangeData.ElementDataModel.Description}");
    }
    

    UI Integration

    Create Exchange Modal

    When users create exchanges through the Connector UI, they see a “Description” field where they can add an initial description.

    Update Exchange Modal

    When updating an existing exchange through the UI, users are prompted to “Describe what changed” - encouraging them to document their modifications.

    Version History Tooltip

    In the exchange list, hovering over the version chip displays the description for that version, making it easy to identify specific changes without opening the exchange.

    Complete Example

    using Autodesk.DataExchange;
    using Autodesk.DataExchange.DataModels;
    using Autodesk.DataExchange.Interface;
    using Autodesk.DataExchange.Models;
    
    public async Task UpdateExchangeWithDescription()
    {
        // Initialize client
        var sdkOptions = new SDKOptions
        {
            ConnectorName = "My Connector",
            ConnectorVersion = "1.0.0",
            // ... other options
        };
        
        var client = new Client(sdkOptions);
        
        // Exchange identifier
        var exchangeIdentifier = new DataExchangeIdentifier
        {
            ExchangeId = "existing-exchange-id",
            CollectionId = "collection-id",
            HubId = "hub-id"
        };
        
        // Load existing exchange
        var exchangeData = await client.GetExchangeDataAsync(exchangeIdentifier);
        var elementDataModel = exchangeData.ElementDataModel;
        
        // Make changes
        var wall = elementDataModel.GetElementById("wall-123");
        if (wall != null)
        {
            wall.Name = "Fire-Rated Wall";
        }
        
        // Add description
        elementDataModel.Description = "Updated wall assembly to fire-rated per fire marshal review";
        
        // Sync changes
        var response = await client.SyncExchangeDataAsync(exchangeIdentifier, elementDataModel);
        
        if (response.IsSuccess)
        {
            Console.WriteLine("Exchange updated successfully with description");
        }
    }
    
    Show More

    Revision History Example

    public async Task DisplayRevisionHistory(DataExchangeIdentifier exchangeIdentifier)
    {
        var revisionsResponse = await client.GetExchangeRevisionsAsync(exchangeIdentifier);
        
        if (revisionsResponse.IsSuccess)
        {
            var revisions = revisionsResponse.Value.OrderByDescending(r => r.LastModifiedUTC);
            
            Console.WriteLine("Exchange Change History:");
            Console.WriteLine("========================");
            
            foreach (var revision in revisions)
            {
                Console.WriteLine($"\nVersion: {revision.Id}");
                Console.WriteLine($"Date: {revision.LastModifiedUTC:yyyy-MM-dd HH:mm:ss}");
                
                if (!string.IsNullOrEmpty(revision.Description))
                {
                    Console.WriteLine($"Changes: {revision.Description}");
                }
                else
                {
                    Console.WriteLine("Changes: (No description provided)");
                }
            }
        }
    }
    
    Show More

    Use Cases

    Design Coordination

    // Architectural update
    elementDataModel.Description = "Shifted grid lines 2' north per structural coordination";
    
    // MEP update
    elementDataModel.Description = "Rerouted ductwork to avoid structural beam conflict";
    

    Construction Phases

    // Phase planning
    elementDataModel.Description = "Updated model to reflect Phase 2 scope of work";
    
    // As-built updates
    elementDataModel.Description = "As-built: Revised pipe routing per field conditions";
    

    Design Reviews

    // Client feedback
    elementDataModel.Description = "Updated lobby ceiling height per client design review comments";
    
    // Code compliance
    elementDataModel.Description = "Added guardrails to meet updated accessibility requirements";
    

    API Reference

    IElementDataModel.Description

    Gets or sets the description for the exchange.

    Type: string

    Usage:

    public interface IElementDataModel
    {
        /// <summary>
        /// Gets or sets the description for the exchange. 
        /// This description will be included when syncing the data to the exchange.
        /// </summary>
        string Description { get; set; }
    }
    
    Show More

    IExchangeRevision.Description

    Gets the description associated with the revision.

    Type: string (read-only)

    Usage:

    public interface IExchangeRevision
    {
        /// <summary>
        /// Gets the description associated with the current exchange revision.
        /// </summary>
        string Description { get; }
    }
    

    Notes

    • Descriptions are optional but highly recommended for team collaboration
    • Empty or null descriptions are acceptable but provide no documentation value
    • Descriptions are stored as plain text - avoid sensitive information
    • The SDK automatically retrieves the latest description when loading an exchange
    • UI users can add descriptions without using SDK APIs