Hey Community!
This is a long one, so read the TL;DR below to see if it applies to you 
TLDR: We are changing how data sent from the Revit Connector is structured. If you are consuming Revit data in Grasshopper or other programmatic environments, this might be a breaking change. Read below about the
Collectionclass and the necessary actions.
Release 2.13 of the Objects Kit introduced the Collections class in the Core library. The Collections class is a modest but powerful addition that provides a common semantic reference across all Connectors while maintaining the principle of unopinionated Speckle commits. The Collections class essentially serves as a formalised version of a Base object with a detached “elements” property and the extra semantic property of collectionType. This enables better organisation and understanding of data and improved compatibility and interoperability between different applications.
Advantages of Collections
- Improved interoperability: By having a standardised way of organising data, the Collections class facilitates smoother data exchange between various applications, allowing users to work with different software platforms more effectively.
- Enhanced data organisation: The Collections class offers a formalised structure for organising data, which helps users understand the relationships between different elements and manage complex data hierarchies more efficiently.
- Maintain unopinionated commits: While aiming for a more consistent data organisation, the Collections class still adheres to the principle of unopinionated Speckle commits. This ensures users can adapt the data structure according to their needs and workflows.
- Simplified development: For developers creating custom applications or connectors, the Collections class provides a standardised structure, reducing the complexity of handling data from different sources and simplifying the development process.
The Impact on Revit Commits and Potential Issues
This change should be seamless and invisible for users who send and receive into and from Connectors as we work to make Collections the de-facto organisational structure. For users building on the Open Access Data, there may be some hurdles to bridge. In particular, if one has hard coded the previous unique Revit data structure.
How Revit Commits are structured
Revit commits to date have been very particular about how Revit users think about the BIM Object libraries they are used to. All objects belong to a set of element categories: Walls, Generic Models, Structural Columns… and so on. It was with this thought pattern the existing commit structure was conceived. Every commit from Revit grouped Elements from each category together.
What will change
Note: This change will only affect new commits created with version 2.14, and later; it does not apply to older version commits. If you use a custom script or definition to process commits across different versions, please ensure your workflow accommodates the previous and updated data structures.
Collections can also group elements of similar characteristics together. Workflows, including Grasshopper, Dynamo, and custom-developed apps with hard-coded data structures based on the previous hierarchy, may be affected. The breaking change will arise if your Grasshopper script or Dynamo graph expects the root of every committed Version to have Categories at the root as properties named by the category. Your dashboards, applications, or notebooks will also break if you have been writing with this expectation hard coded.
Before: A name property as a detached array of Floor objects
After: The same collection of floors found in the Root commit Collection elements property
Precisely the same elements are isolated by the two actions before and after.
Why the change?
No longer will code have to fork and twist to accommodate whether a commit came from Revit, Rhino or AutoCAD, a singular organisational approach means less branching code, less fragility and more predictability. As more Connectors are added to the Speckleverse, more applications are interfacing with the Open Access Data. More and more Specklers are expanding their workflows to being multi-tool and multiplayer; we are confident that this transition will ultimately benefit the entire Speckle ecosystem.
Preparing for the Change
Most standard workflows will not be impacted. Nevertheless, some tweaks will be needed to work if you consume data from Revit. Specifically:
From C# or Python
To date, a commit from Revit was a Speckle Base object with List properties for each of the Revit categories with constituent elements being sent. So you may have previously hardcoding their discovery like this:
var walls = myCommitObject["@walls"]; // Or any specific category
Now that the commit object is a Collection, which implicitly has an elements property for all its object data content. Then you could translate this into the more verbose:
// The commit object is a Collection which implicitly has the
// property of an element for all its object data content.
// This adds the new method if the old property is not found.
var walls = myCommitObject["@walls"] ?? myCommitObject.elements
.OfType<Collection>()
.FirstOrDefault(coll => coll.name == "walls")?.elements;
NOTE: Our developer documentation beavers are hard at work making updates that reflect the changes we’re announcing today. With those changes comes a recommended alternative way of doing this; A more robust traversal of the commit, more flexibility in handling many data structures (not just Revit categories) and obviating the need for branching code in the future.
Grasshopper
Previously the Walls category would have shown up on the Receive node:
Now all data will come from the elements property.
The 2.14 Release includes a new node for Speckle Grasshopper makes it easier to find and filter Speckle data. Flatten Collection
And to use that for example:
More examples will be available on Release.
Dynamo
Something similar will be necessary for changes in Dynamo; speak up if this is something you need to put out fires.
PowerBI, Rhino, Blender, Sketchup, etc.
Sit back and enjoy the show - If you haven’t done something fancy with PowerQuery or built something that relies on the specific naming of Rhino layers, everything should work as usual — if it doesn’t, let us know!
Testers welcomed
To ensure a smooth transition, we invite you to test release candidates for the new version of the Revit connector. By participating in this testing phase, you’ll have the opportunity to provide valuable feedback and help us refine the new data hierarchy before it becomes widely available.
PowerBI, Excel and other application Connectors should cope with the change without you noticing, but we always appreciate the community shouting loudly if they don’t.
Install the Release Candidate by accepting work-in-progress versions:
Do the same for the Rhino/Grasshopper Connector to get hold of Flatten Collections!
