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);
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("---");
}
}
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");
}
}
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)");
}
}
}
}
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; }
}
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