Expert Use of the AEC Data Model API: A Technical Deep Dive into Enhancing Your Data Potential and Efficiency in AEC Projects

ZHONG WU: Hello, everyone. Welcome to AU 2024. Today, we are going to have a technical deep dive into our AEC Data Model APIs. We will showcase how you can enhance your data potential and efficiency in AEC projects.

First, quick introduction on the presenters for this class. I'm Zhong Wu, a developer advocate from Autodesk developer advocacy and support team, focused on the APS service in AEC industry, including ACC, BIM360 APIs, and AEC Data Model, and also Revit Design Automation, extra. Today with me we have Mike and Joao. So Mike and Joao, can you do a quick introduction?

JOAO MARTINS: Yes. Thank you, Zhong. My name is Joao Martins. I'm also from developer advocacy and support team. Work mostly with also AEC related APIs and mostly with .NET. I can help with support, events, and presentations like this. Glad to help. To you, Mike.

MIKE ENGEL: Yep. And I'm Mike Engel, a product manager here with our Autodesk teams working in support of AEC industry and the AEC software products we deliver, particularly today focused on our AEC Data Model.

ZHONG WU: Yeah. Thank you. Yeah. And this is the safe harbor statement. Please read the statement. One thing you need to be aware is that please don't make your business decision based on the presentation. Talk to us before making any decisions. Yeah. So in today's session, Mike will provide a quick recap of the Autodesk data strategy and what is a AEC Data Model.

Then Joao and I will move on to introduce the details and the key principles of AEC Data Model. And we will walk you through in details in different capabilities of AEC Data Model APIs and introduce our core code samples. After that, yeah, Mike will take over to showcase a couple of core successful stories created by our customers using AEC Data Model APIs.

So yeah. Before handing to Mike, I want to bring one reminder here. This class assumes you have a basic knowledge of web programming. Seems without a deep dive into AEC Data Model APIs, it's not very complex, but you may feel a little challenged if you don't have any programming skills. So now let's kick off the session by Mike for data strategy and Data Model introduction.

MIKE ENGEL: Thanks, Zhong. Yep. First thing we want to do is just do a quick recap of Autodesk journey to granular data to just set some context of what you'll be seeing in the presentation. Over the years, we've seen three key trends emerging and accelerating. You, our customers, need more automation, whether this is to increase productivity, improve efficiency or just faster time to market and your solutions.

There is a need for increased collaboration, whether that is within organizations or across disciplines. And we see a continued trend towards industry convergence across AEC manufacturing and media and entertainment industries. And at the foundation of all of these trends, we see the foundation of data.

To respond to these challenges in our data strategy as we look towards the next three years, we're focused on three key areas. Data granularity, data interoperability, and data accessibility. And this presentation with the AEC Data Model will be mostly focused on data granularity. If we look at it today, files are the smallest unit of collaboration. But file based collaboration is very painful. Files move between different products, organizations.

There's a patchwork of standards, which results in challenges like translation and the fact that multiple disciplines cannot work on the same design simultaneously. It also leads to mistakes as design teams manage these different files and their versions. And lastly, it makes the exchange of data across organizational boundaries difficult and often putting IP at risk.

It's clear we need better design to make data management by putting together a standardized way of describing data, allowing for real time or close to real time access to this data and ensuring access controls so that you have the right data available to the right people at the right time. Imagine a world where data and workflows come together across the entire product lifecycle. At Autodesk, our vision with the industry data models to democratize access to design and make data normally trapped within files so that your customers can deliver better and cheaper products to market faster.

We wish to unlock a valuable design and make granular data that is generated by the Autodesk flagship products and provide access to this granular information via APIs. We look to delight you by building a net new experiences through industry clouds on granular data. Lastly, but not least, we hope to enable value differentiating outcomes that will fuel the digital transformation and disrupt the industry. Now let's look a little more specifically at the AEC Data Model.

Our specific vision for the AEC Data Model and the AEC industry is to provide a vision where we provide open, extensible data platform which connects the AEC and O teams in the tools of their choice. Providing value through secure, compliant support of this data, scalability across the diversity of it, connected experiences, easily accessible, mutable, and extendable along with granularized and regionalized.

And today, as we'll see in the API, this first ability with the AEC Data Model is generally available. In June of 2024, we released this to general availability to all Autodesk subscribers of Autodesk Docs. Currently, it is compatible with Revit 2024 and above in Autodesk Docs, and you can enable it for your account today by accessing it in the account admin and toggling on AEC Data Model activation. Now, we'll hand it back off to Zhong to give you more details on this API.

ZHONG WU: Thanks, Mike. Was a great introduction. Now Joao and I will go deep dive into our AEC Data Model APIs, including the concept and also the user scenarios. So I believe you guys here are familiar with the BIM data. So BIM and AEC does not fit nicely into an Excel spreadsheet. It's complex.

Sometimes it's a folder system which looks like a tree structure. Other times, inside of the design model, it's more like a graph structure. REST API works great when the data is a simple, flat list, but for data like a folder system or BIM data model, REST API is not efficient. You have to recursively call the REST APIs to get the result. Joao, is there a better solution here?

JOAO MARTINS: Yes, Zhong. That's what GraphQL is, an interface language designed by Facebook that makes it fast to work with complex data structures, like trees and graphs. AEC Data Model stores data in a graph structure, which makes it a perfect match for GraphQL. With a stronger interface like GraphQL, we can be faster about how we get the AEC data. Just one fast request instead of hundreds of requests from different REST endpoints.

So to recap, basically, it is easier to read. You have one endpoint, not hundreds. You have granular access to the graph data. You can choose the shape of your response to fit your workflow. Under the hood, when you send a request, a resolver is calling the APS endpoints on your behalf. You just call the API once and let the resolver do the heavy lifting. Faster for you and faster for Autodesk.

ZHONG WU: Cool, Joao. Yeah, so GraphQL seems working perfectly with AEC data. Let's look at the core AEC Data Model constructs. First of all, the top level category within the API schema is element group. In some cases, you may also consider it simply as a model or a design. It contains elements and its version based. So each elemental group includes multiple elements. Elements are the building blocks of AEC data.

For example, a window instance, a wall instance and a wall type and a window type, they are all elements. So it provides a good flexibility to adapt to different requirements. So it is very easy to be extended in future. Different elements may have dependency or relationship. For example, a wall instance belongs to a wall type. This relationship is represented by reference property in AEC Data Model.

Properties are very important data within an element. They are well defined data describing the element, such as Revit parameters, including area, volume. Last but not least, each property also has property definition, which provides detailed metadata about the property, including unit and types and extra. With this concept, Joao, maybe you can explain them in more detail with an example.

JOAO MARTINS: Yes, Zhong. As an example, let's consider a restart from one project, including all of its disciplines available through the AEC Data Model. At the entry level of our hierarchy, we have the element groups that you explained. In this example, let's assume a group of elements in the architectural design. The next level represents each one of the individual elements available. In this example, we can think about one specific window.

Now, in a more granular level, we have access to these window's properties. We can think about one, for example, the head height. And lastly, each property will have its own definition. So in this case, we can think about the units being used by this property. In this graph context, each element also has the reference property which connects these elements with each other according to the hierarchy of the model. In the case of a window, we could, for example, obtain its reference level, its type, materials, and any element associated.

ZHONG WU: Yeah. Thank you. Thank you, Joao. So after you understand the constructs of AEC Data Model, let's take a look at the details of AEC Data Model queries to understand its capabilities. Sometimes, for example, we would like to get all the elements among the ACC, the whole hub, or the whole project. For example, to get all the windows instance within the hub. Joao, I know that we can use the simple query, elements by hub or elements by project. But can you do a live demo to show how easy it is?

JOAO MARTINS: Yes, sure. Let me change here from presentation to a live demonstration. In this case, first, let's focus on retrieving all the elements from the hub. I already ran this query here to retrieve all my hubs. And from one of my hubs IDs-- in this case, I'm picking this one-- I can simply use the query you shared in the presentation. The elements by hub.

So in this case right here, to use this query, I need to specify one hub ID. I just need to pass the hub ID, and also, I'm going to add a filter. And this filter specifically, precisely, it is going to return only the elements from the windows category. To address that, I can use this syntax, specifying the property.name.category equals to windows.

And after that, in my response, I have the freedom, the flexibility to specify precisely which data is going to be returned. In this case, I'm only interested in the name and ID. As soon as I send this request, remember, we are going to see the resolver. The resolver will take place and it will fetch the data according to what we specify in the query and return that in a list for us. Here you can see all of the elements from a hub. OK, Zhong?

ZHONG WU: Yeah. Cool. So how about you get the elements from the project?

JOAO MARTINS: That's also possible. And to achieve that, we can simply take advantage of another query. Instead of elements by hub, we have also the elements by project query. And this one, instead of specifying one hub ID, we need to specify a project ID. So let me pick one of the available projects. I'll grab this one that we use in our bootcamps and replace right here. And if we use the same filter, we are going to also return-- we can also see the result, all of our elements from the windows category. OK?

ZHONG WU: Yeah. Cool. Yeah. Looks super easy to do that. Yeah. But how about retrieve elements at a specific version of design? Because that's quite common when we are doing the design. And yeah, it seems like we can use the query elements by element group at version. So can you also show us the details, Joao?

JOAO MARTINS: Sure. For that, we can take advantage of a different query. As you mentioned it, we have one to query elements by this element group at version. And with this query, we need to specify both the element group ID-- let me pick one element group here. I'm going to grab this one because this one has two versions. And we also need to specify the version number. Let me add this in a different line. And in this case, let me pass the version two.

To fetch also only the elements from the windows category, we can add the same filter as we were using before. And after passing this filter, removing this, we can specify the data being returned. So in here, let me add the name of our elements, the ID, and let me also add the properties. This way we can see also the properties from each one of our elements. And if we run this query-- let me just verify this.

And if we run this query once more, resolvers will take place, and it is going to retrieve true as a result. As you can see in this case, we have a empty array because there is no windows in this model. If we check the model I got, it is from HVAC. So we can expect the empty result. But if we change from windows to ducts, we know that HVAC models has ducts. We can now see a list containing all of the available ducts from our design at this specific version. OK, Zhong?

ZHONG WU: Yeah, cool, Joao. Yeah. But let me ask, can we do some more specific query? For example, can I query all the ducts which has a length more then-- longer than some specific value?

JOAO MARTINS: It is never enough for you, right, Zhong. But yeah, we can achieve that. We just need to pass another filter. We can specify property with the syntax property.name-- let's use the length property. And we are intersecting only those ones with values bigger than-- we have 0.1 here. Let me think. Let me see if I can grab a bigger one. 0.2. Let's use bigger than 0.2. And if we run this request, the resolvers take place and return to us only the elements passing this additional filter, only the ones with length bigger than 0.2. OK?

ZHONG WU: Great. Yeah. Thanks, Joao. Yeah. Now we understand how to retrieve elements. Yeah, but there's one specific requirement. Building a quality assurance process, there is a requirement to validate the data property definitions used across a design, like data names, unit, and types. So, Joao, can you demonstrate to us how to get these available property definitions with AEC Data Model query?

JOAO MARTINS: Yes, sure. That's another cool capability. We can check all of the properties available from our designs. To achieve that, first, the entry point would need to be one element group so we can use any query that returns an element group. So let's use this element group tip, and this requires us to specify one element ID. I'm going to use the same element group ID we used before, so we are referring to the same element, to the same element group, same design.

And in here, we have one specific query that returns to us the property definitions. This will be basically a list containing all of the properties definitions as specified. We can add the properties, names, IDs, and description. What's more, as soon as you send this request, resolvers take place and return to us the property definitions from this design. You can see left attachment, part type, and so on. Back to you, Zhong.

ZHONG WU: Yeah, that's awesome. Yeah, this query seems very simple and powerful. Yeah. But sometimes in the real world, seems a little complicated. Here is one case. So I have a model of building which includes a couple of levels, and I want to place different furniture on different level. So I want to build in this kind of relationship. And after that, if I use AEC Data Model queries, how can I use the query to get all the furnitures for one specific level?

JOAO MARTINS: Yes. This is a bit more complex scenario, but since all of this data is available in a graph structure, we can also address that. So for that, to achieve that, we can take advantage of the references between the elements. First thing we can do is retrieve the elements by element group. For this, we need to specify the element group ID. In this case, let me use this different sample right here. The basic sample project. You are probably used to that one.

And now I'm going to pass a filter. And this filter will be slightly different from the one we've been using before. This filter will focus on retrieving the levels. First thing we need to do is retrieving the levels. So we can filter based on the levels category. And let's also add another filter to return only the instances. As you mentioned, Zhong, elements can be referring to instances or types. Since we only want to return the instances, we can take advantage of the element context.

And in here, let me pass the value equal to instance. And now specify what we need to obtain inside the results. Let's add the name and the ID, and that should be enough. As soon as we send the request, this request, we can see all of the levels available in this element group. Now we can take advantage of the reference between the reference property that connects each level with each element from furniture category.

We can do this by applying or adding another query. And this query is the reference by. The elements, the furniture specific, they have a reference with the name level with the connection with the instance levels. So we can add this reference name and also a filter. This filter, it is going to return to us only the elements from the furniture category. Furniture. And let me ask another one. It is missing something here. I need to add as a query. Now it is correct.

And let's also filter to retrieve only the instances. Let me copy this here. And after that, let's list all of our instances from furniture by typing its names, IDs, and also the properties. As soon as we send this request, we can now see the previous list but appended, nested to this list. We can see for each level the list of furnitures available with all of its properties.

And another cool feature from the Explorer is that we can also add the Viewer context. So if I copy this version of the file here, paste it here, and turn on Viewer, now I have access to the Viewer context. And the Explorer works in a way that as soon as I send a query, this query once more, it is going to filter the view, the scene to match only the elements from our response. OK? So we can see that we have all of our elements from furniture category divided by level.

ZHONG WU: Excellent. Thanks, Joao. Yeah. I believe your demo provides a lot of confidence for us to try these AEC Data Model queries. Looks very simple but powerful. And I know that you also created some code samples to demonstrate the usage of AEC Data Model APIs with our very popular and powerful tool, AEC Data Model Explorer, which you used to demo the query, one of them. I think we are pretty interested in the implementation for that, especially how to connect with the IPS Viewer. Can you talk in some details about the implementation of these samples?

JOAO MARTINS: Sure, Zhong. We have that here in some slides. So if we move to the next one. This is, for example, a lecture sharing the Data Model Explorer. As you mentioned it, it connects with Viewer and is a good place for you to experiment focusing entirely on the query. And the cool feature I just shared is that it connects the elements from the response with the elements from Viewer.

And the way it works is because it takes advantage of the properties. More specifically, there is a property called external ID that you can take advantage when connecting the same element from Revit Perspective Viewer or Model Derivative perspective and AEC Data Model perspective. This is what we are doing to match the element in response with the element in the rendered scene by Viewer Library. So basically when you translate designs, you can take advantage of unique IDs. In this case, the unique ID from Revit is a GU ID that is also available in other platform.

Just like that, you can also use, if it makes sense in your workflow, the element ID. The element ID is also present as the Revit element ID in AEC Data Model and it is also available in the name of each element when you query a data through Model Derivative and Viewer. So keep this in mind. If you want to connect across multiple platforms, you can always take advantage of external ID or unique ID.

OK. Before sharing the sample codes, QR codes, let me go over how you can view our samples available. We have one organization, one GitHub organization, and in here you can see repos containing samples across taking care of many of our APIs. For AEC Data Model, we can simply filter by AEC, and you see here a list with all of the available ones. You can take advantage of the Explorer source code. So you can fork, build your own, implementing this code for your own purposes. Up to you.

And we also have another sample that takes advantage of AEC Data Model, and this is the dashboard one. We have seen how you can send requests, but in this one, this case here is focusing about connecting, taking advantage of this data that you can query to build tables and charts. So the sample works in a way that as soon as you sign in, you can select one of the hubs you have available. Let me pick this one, and select one project.

As soon as you select one project, it will start fetching data from using the AEC Data Model API. And in this case, it's going to fetch data about your rooms available and your doors available across the entire project to build these dashboards. Here, you can basically see all of the properties available and this in a chart split by the types that you are using. So it can be very useful. Combining with the power of the queries and the filtering capabilities, you can generate dashboards with all of the flexibility and granularity that this API supports.

The last sample is in cases where you want to connect the data from the AEC Data Model with Viewer, or even compare what's available with Model Derivative and what's available with AEC Data Model. Zhong will share details when to use each service, but this sample is good for you to quickly check how to obtain the properties from Viewer or Model Derivative perspective and how to obtain the same properties from AEC Data Model API.

It is just like the tutorial, we have the hubs browser tutorial we have. You have the tree view where you can specify one hub, expand, and go to one specific project. Let me find this one. Expand here. And as soon as we select a model, we can select one element and view this element's properties. This is the properties. These are the properties coming straight from Viewer, from Model Derivative, from the derivatives of the design. If you click this extension now, you can see side by side the properties from Model Derivative and the properties from AEC Data Model.

Not only the properties from this design, but this sample also takes advantage of the references and released here the properties from type, from its family and its reference level, phase created. Base constraint is a level. Top constraints is another level. And then you can easily see what is available and how to fetch that. OK? To take advantage of each one of these samples, you can either go to our hippo repo or scan one of these QR codes. Feel free to scan this. Let me stay here for 3, 2, 1 seconds. And back to you, Zhong. Thank you very much.

ZHONG WU: Yeah, cool. So yeah, with those code samples, I think you should have a basic idea about how to use AEC Data Model APIs. But last but not least, if you are working with APIs for a while, as Joao mentioned, you must have a couple of different services to get the BIM data. And confused by the differences among them you may be. Yeah. Here are some key point may help you to make the decision.

So I won't talk in very detail, but in general, if you are trying to support a wider range of industrial file format and you don't work with ACC or BIM360, so maybe you can think about a Model Derivative service. If your model is mainly about Revit and you want to do some comprehensive operations to extract some specific data which you cannot get directly from other service, then you need to think about the Revit design automation.

So if your model is hosting ACC or BIM360 and you will do a lot of querying between different versions, then think about the Model Properties service. And if you want to exchange a subset of model to other products, so then Data Exchange should be your best friend. But as we talked most of today, if you want to do a lot of queries based on some specific elements from the whole hub or whole project or the model and you just want to list some data you are interested instead of get the whole data, so then AEC Data Model might be your choice.

JOAO MARTINS: OK, Zhong. So can you share the details about one specific case? Point me to the proper service. Let's say that I want to write information back into the Revit design being, let's say two cases, modify one property available in Revit or append one property for cost, for example. What would be the best solution? What would be the best service to address that?

ZHONG WU: Yeah, that's actually a good question. So yeah, so you are asking about how to modify the existing property or add a customized property to the BIM data, right? Yeah. There are two scenarios. So if we are talking about write back the information to the model, the first scenario is that you want to or want to modify to the original model, which is, for example, Revit model.

So if you are trying to do that, to modify the original model, then the only way or only solution is design automation Revit. So this service provides you the ability to modify the original file, original model. But if you just want to add or modify a property for the cloud data. So for example, I want to add some cost information to the BIM model. You don't need to modify the original model.

Then stay tuned. AEC Data Model will provide you a very powerful extension which help you to support the extension property. So this is still working in progress, but it will come soon. So yeah. With this feature, you can add or modify the AEC Data Model properties very easily. So yeah. That's it. OK. With that, let's hand over to Mike for some successful stories based on AEC Data Model.

MIKE ENGEL: Yep. Thanks, guys. It's always great to see the amazing information that's capable with the AEC Data Model. As an extension of that, before we wrap up, I want to take a few minutes to showcase three of the solutions some of the customers, like many of you, are exploring and have created using these APIs and the capabilities.

So the first example we'll show here is from one team where they lead developments of what they refer to as the Digital Building Logbook. And they envision it to serve as a centralized repository for all of their building related information, supporting the AEC industry towards climate neutrality and building a more circular economy. This logbook is envisioned to include general details, administrative records, construction data, energy performance, and operational information.

This effort aims to streamline the organization of diverse data types and address the challenges related to data interoperability and disconnected data. They found leveraging the AEC Data Model, the DBL, as they refer to it, will enable efficient data queries and robust search capabilities to extract and access this rich data from models without the need of the original authoring tools, effectively mitigating one of their challenges with respect to interoperability and disconnected data issues common across the AEC industry. The DBL enhances the user experiences further by breaking down data for various user personas across the lifecycle of a building.

Second sample we want to share with you is from NTI, another Autodesk platinum partner, and has been closely working with our Autodesk products for quite some time. As part of some early engagement, NTI explored how the AEC Data Model APIs can be leveraged to bring in granularized data in real time from the Revit models into a BIM data management app they are currently building.

The BIM data management app's goals to empower nondesigner personas, those outside of Revit, to efficiently interact with the model and extend, annotate, and approve the information pertaining to the model without needing compulsory interface with the designer or the authoring app who's creating the model.

The third example is from Avixi, which specializes in making BIM achieve better outcomes for its clients. Here, Avixi is using the AEC Data Model API to extract Revit model data in the form of schedules so they can run quality control on this design data outside of the app. Typically, this process happens manually, and they wait for Revit models to load, export the data to Excel, then run the process of verifying the data to get a read on the model health. Taking approximately 15 minutes just to open the model, often, with additional effort to extract and process that data.

They found with this new workflow in the API, they can now accomplish the same task in 30 seconds, and they never need to open Revit in the process. Applying the same workflow over and over throughout a project lifecycle, they envision to save massive amounts of time and impact the quality of the project they deliver. So with that, those samples, we'll hand it back to Zhong to wrap it up.

ZHONG WU: Thank you, Mike. Yeah. So before ending the session, I'd like to influence two coming events here. In November, we will have our APS online training. This is for beginner to get started to learn APS service. And in December, we will have a developer accelerator in Atlanta. So this is for people who are familiar with APS, basically, and want to create a prototype based on your requirements. So with that, thank you, everyone.