Request

Response

    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.

    ../../../_images/time_based_history.png

    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 HistoryChanges API 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): Model
    • component(componentId: ID!, composition: BOMCompositionEnum = WORKING, time: DateTime, state: String): Component
    • drawing(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:

    • Model
    • DesignItem
    • ConfiguredDesignItem
    • DrawingItem
    • BasicItem

    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 startTime is omitted, results start at the beginning of the entity’s history. If endTime is omitted, results extend to the most recent change. If filterTypes is empty or omitted, all change types are returned.

    • pagination — a PaginationInput that 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 }
                    }
                }
            }
        }
    }
    
    Show More

    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 }
        }
    }
    
    Show More

    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 }
                }
            }
        }
    }
    
    Show More

    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.