Time Based History
The Manufacturing Data Model now supports time-based history, enabling you to resolve objects at specific points in time. This feature enhances your ability to manage concurrency, track changes, and maintain the integrity of design data. With time-based history, each object’s state is driven by time. When fetching an object, you can pass a time parameter to retrieve the state of the object as it was at that specific moment. For example, you can fetch an object as it was yesterday at noon, and all elements within that object will be resolved to their state at that time. For more detailed information, please refer to Versions and changes in Autodesk Fusion documentation.
Why Time Based History?
Time-based history is essential for several reasons:
- Concurrency Management: This feature allows multiple users to update properties or edit designs simultaneously without blocking each other. It improves workflow efficiency, as you do not have to wait for others to finish their changes.
- Efficiency: Time-based history reduces the rapid creation of numerous versions, as versions are created only when you decide to do so.
- Enhanced History Tracking: The
HistoryChangesAPI provides a detailed view of all events affecting an object, ensuring transparency and accountability.
Objects Utilizing Time-Based History
Time-based history shows up in the schema in two related ways:
Root queries that accept a time: DateTime argument
These queries resolve the entity (and everything reachable through it) to its state at the supplied time. If time is omitted, the latest state is returned.
model(modelId: ID!, composition: AssemblyCompositionEnum = WORKING, time: DateTime): Modelcomponent(componentId: ID!, composition: BOMCompositionEnum = WORKING, time: DateTime, state: String): Componentdrawing(drawingId: ID!, time: DateTime): Drawing
Types that expose a history field returning HistoryChanges
These types let you walk the change log for a given entity:
ModelDesignItemConfiguredDesignItemDrawingItemBasicItem
HistoryChanges
The HistoryChanges API is a powerful tool for tracking changes and understanding the evolution of design data. It is a paginated container that holds a list of HistoryChange entries describing the events that have occurred to a given object over time, including updates to properties, descriptions, part number assignments, version and revision creation, and more. HistoryChanges is now an important aspect of managing design changes.
The shape of the response is:
type HistoryChanges {
pagination: Pagination
results: [HistoryChange]!
}
Filtering and pagination
The history field accepts two arguments:
input— a HistoryInput that narrows results by time range and change type:input HistoryInput { startTime: DateTime endTime: DateTime filterTypes: [HistoryChangeTypeEnum] }If
startTimeis omitted, results start at the beginning of the entity’s history. IfendTimeis omitted, results extend to the most recent change. IffilterTypesis empty or omitted, all change types are returned.pagination— aPaginationInputthat splits long histories into pages.
Change types and subtypes
HistoryChange is an interface. Each entry returned by the API resolves to one of several concrete subtypes (for example, ModelWrittenHistoryChange, PropertiesUpdatedHistoryChange, VersionCreatedHistoryChange, or ComponentPartNumberHistoryChange) depending on the kind of change that occurred. All subtypes share the same common fields (id, description, author, and timestamp), which can be selected directly. To read fields that are specific to a subtype, use __typename together with inline fragments (... on TypeName).
For the full list of values you can pass in filterTypes, see the HistoryChangeTypeEnum reference. For the full list of subtypes that implement HistoryChange and their type-specific fields, see the HistoryChange reference.
Example Usage of HistoryChanges
Example 1:
The following query retrieves the most recent history changes for a Model. It uses __typename to discriminate between change types and inline fragments to pull subtype-specific fields.
query GetModelHistory($modelId: ID!) {
model(modelId: $modelId) {
id
history(
input: { filterTypes: [PROPERTY_UPDATED, VERSION_CREATED] }
pagination: { limit: 50 }
) {
pagination { cursor }
results {
__typename
id
timestamp
description
author { id name }
... on PropertiesUpdatedHistoryChange {
properties {
definition { name }
value
}
}
... on ComponentPartNumberHistoryChange {
partNumber { value }
}
... on VersionCreatedHistoryChange {
version { id }
}
}
}
}
}
The response includes the type of change (via __typename), the timestamp, the author who made the change, and a description, plus any subtype-specific data you select. This information is crucial for understanding the history and evolution of design data, enabling better decision-making and collaboration among team members.
To fetch a single HistoryChange by its ID directly, use:
query GetHistoryChange($historyChangeId: ID!) {
historyChange(historyChangeId: $historyChangeId) {
__typename
id
timestamp
description
author { id name }
}
}
Example 2:
The following query retrieves a model object as it existed at a specific point in time, along with its history changes.
query GetModelAtTime($modelId: ID!, $time: DateTime) {
model(modelId: $modelId, time: $time) {
id
timestamp
name {
value
}
history(pagination: { limit: 25 }) {
results {
__typename
description
timestamp
author { id name }
}
}
}
}
In this example, Model.timestamp is the point in time at which the model was resolved (i.e., the time you supplied, or the current time if it was omitted), not the model’s last-modified time. Each entry in history.results carries its own timestamp for when that specific change occurred. This information is essential for understanding the state of the model at a given point in time and for tracking changes over time.