Introducing the Autodesk Tandem API: Building Your First Digital Twin

JAMES AWE: Hello. Welcome to Tandem Data API. My name is James Awe, and we're going to talk about the new API for Tandem. And if you haven't heard about Tandem yet, it is a digital twin product from Autodesk that's fairly new. And we're going to go over the API and do a little bit of an overview of the product itself in case many of you haven't seen it, and then we'll dive into a few details about how to get started. And so, let's dive in.

So, first of all, I'm sure you've seen this slide in many presentations, the safe harbor statement, which is basically legalese to say, don't make any purchasing or investment decisions based on what I say here, and please do not copy or distribute without permission.

So first of all, what is a digital twin? I think most of us have a feeling for what it is. It's a digital representation of something in the real world that gives us insight into what's going on in that real world asset and allows some kind of control. But there's a lot of variation in what the definition of that could be. So let's examine what we're talking about here.

So, first of all, many people jump to this kind of conclusion. They've seen the Hollywood version of a digital twin where Tom Cruise hacks into the building management system and controls the elevators and figures out where all the HVAC ducts are to crawl through. And that certainly is a long-range vision of what a digital twin is. But that kind of digital twin would cost millions of dollars to create and is not very repeatable. But it is the long-term vision for what we're talking about when we talk about a digital twin for a building.

Luckily, there's a company called Verdantix, which has defined a very clear maturity model for digital twins starting at a descriptive twin, which you can think of as the BIM model that's the basis for interacting with the twin of the building. So that would establish the location and-- the existence and location of assets within the building, tell you where all the spaces are, things like that to give you the building context.

And then, the next level up from that is informative which is what you usually think of when you think of sensors in the building, reporting real-time information back to the twin so you know what's going on currently in the building. All the way up to autonomous, which is the Tom Cruise hacking into the elevator and controlling it from the twin.

So Tandem has focused on these bottom two. And the reason for that is they're foundational. There's no way you can hack into the elevator if you don't know there is an elevator and where it is.

So we're marching up this digital twin maturity model but focusing on those first two and trying to make it a repeatable process so that it doesn't cost millions of dollars every time you want to create a twin for a building. We're going to make that easy and repeatable from the normal process of the BIM lifecycle.

So that's depicted in this slide. So, as you probably know, Autodesk has been involved in the design part of buildings for many, many years with products like AutoCAD and Revit and then taking that data into construction with things like the Autodesk Construction Cloud.

And then, now, what we're talking about with Tandem is picking up all that data at the handover point and passing it on to the operations phase of the building. So we want this continual digital thread that gets passed along through the full project lifecycle and leverage all of that digital data that's already been built up.

So what currently happens is, usually, the owner specifies a BIM deliverable when they start the project. But it's not very clearly defined. So they get a stack of papers or they get Revit models that they can't really use because the owner doesn't use Revit. So there's a drop-off in that digital thread. And we're trying to create Tandem to make that more continuous so the handover process gives the owner something that they can use to operate the building.

So we talked about those first two phases in the digital twin maturity model. That first one was the descriptive twin or what we internally call twin-building. So how do you get that basic BIM model that's usable in the owner's face to establish the existence and location of all the assets in the building?

Well, most of that data comes from Revit or IFC. That's what currently is the input source for that. We're also looking at Navisworks and AutoCAD files. That's coming in the future. And then, there's also data coming in from other places like Autodesk Docs. So a lot of the installation and maintenance manuals come from Autodesk Docs. And those can be attached to the twin as well.

So you want that data to come in from those source files that establish the BIM model. And then you want to be able to verify that it's complete, that it's consistent, that everything's been classified. So that's all part of the twin building process to get that BIM context set up.

And then, the next part of it is the IoT part of it. So using the real-time information that's coming in from sensors and building management systems that are on site and reporting that data.

And then, once you get that, you want to be able to display it in graphs, and heat maps, and other kinds of visual display to give you insight into what's going on. And then, once you have that insight, be able to act on it and make an informed decision about how to maintain something, take something offline, whatever it might be.

So I know many of you haven't seen the product. So I have a few videos that just show you some basic functionality so you get an idea of what we're talking about. So the first one I want to show is just the ability to navigate through the data. So for an owner, they're most interested in things like levels, and spaces, and systems.

And so, the data is organized very cleanly so that they can navigate those things as you would expect. And, here, we've grouped everything by object type. So that once you get them all-- objects to the same type together, you can check to make sure the data is consistent.

So here we've taken all of those items on the right-hand side. And we're presenting them in the inventory table in the bottom. And it's very easy to see that the data is consistent. And if it's not, then it's easy to change. So, normally, that data is hard to access because it's buried and not very visual. But the inventory table brings it to the surface.

The next one is views. So most CAD-like products have some notion of saved views. And here it's really important because Tandem is used for data visualization scenarios that are nice to be able to pull up quickly and check on the different views in the system. So we just make that easy to establish and restore those views, kind of like a visual report.

The next one is floor plans. So most of us are used to construction floor plans, which are the construction documents that have lots of symbology, and dimensions, and all that kind of stuff. Not very useful to the owner because they don't need that information. But they do like to have a 2D view because it's easier to parse the different rooms.

So Tandem allows for a dynamic 2D view that acts as a floor plan-- simplified floor plan. But it's also still all interactive. So anything that you could do directly in the model, you can still do on the floor plan and dynamically present that information in a 2D view, which is very helpful to the owners.

And, as I said, their primary method of navigation through the system is going to be things like levels and spaces. So Tandem also makes that very easy. So here we're searching for spaces called neighborhood and isolating those. And we'll drill down on those, and you can actually see the equipment that's in a given space.

Now, I'd like to pause here for just a second because this is an important feature. This model is actually-- or this facility, the twin, is actually three [INAUDIBLE] models composed together. So there's an architectural model, a mechanical model, and a structural model.

And most aggregation software to date that aggregates those models together loses track of how it logically fits together because they're isolated-- the elements are isolated into individual buckets for each model. What Tandem does is smooth over those divisions between the models so that you can understand that given a space that was defined in the architectural model, what assets from the other model are in that space?

That's not so easy to do using previous products. So Tandem is a big step forward in understanding the relationship of all these elements in more of a logical way as presented via space or a level.

The next thing you might want to do is when you drill into a particular asset, you might want to find the documents that are associated with it. So, in this case, we can pull up and find the PDFs that represent either the installation manual, the maintenance manual.

There's a lot of static PDF-type documentation that would normally be in a notebook someplace on somebody's shelf or in a box of papers in the basement someplace. And just having Tandem be the digital hub for all that information makes navigating to those assets and then finding all the related information easier.

Heat maps is something that you might have seen before. We had a research project called Project Dasher, which was data visualization for all of the IoT sensors in the building, so temperature sensors, CO2, occupancy, all of those things. So Tandem has all of that as well. We ported that over from Dasher. And it makes it easy to visualize hotspots or areas of activity.

And it also works with the 2D floor maps. So here we've gone to the 2D view, and the heat map still works. And then, of course, you can dig into all of the data behind that, all the time series data, and look at charts, or restrict the time zone, restrict a certain variable. So all that information is available to view either in chart form or in the context of the building.

And then, systems is the HVAC system, the water system, whatever, is also another important thing that needs to be maintained. And often, you'll want to know-- the owner will want to know-- if this piece of equipment goes offline, or needs to be replaced, or whatever, what areas does it affect? So being able to trace the connectivity of the whole system all the way down to where it's going to dump out into a given space or room is important.

And the other part of this feature that's interesting is the data doesn't always come in completely clean from a source model like Revit. So we allow you to clean up some of those places where the connectivity is not perfect, or it could come in from IFC incomplete, and the owner has the ability to adjust the system and make sure that it's analytically correct to support their decision-making process.

And then, lastly, this is-- it's not obvious to everybody unless you've been through this problem. But one of the things that's super valuable is understanding the completeness of the data. So you could have a property that's associated with certain types of assets. And then, figuring out whether that property has actually been specified is not easy unless you somehow bring that to the surface.

So dashboards allows you to set up basically a visual report that says, for these given types of assets, I'm expecting to see these properties associated with it. And if they haven't been filled out, show me where they are, because somebody didn't do a good enough job of completing all of the data that I'm expecting.

So dashboards give you great insight into the consistency and the completeness of the data so that you can trust the reports that you're generating or the analysis that you're generating from that data.

So that was a teaser of the product itself. And we're going to talk about the API. But the API is not necessarily super useful unless you have the product, because you have to be able to set up the facility and attach all that data. And then you can use the API to automate it or connect it to other systems.

So if you're a developer looking to get started, the first thing you're going to want to do is get your hands on the product itself so that you can set up a test facility in order to use the API against it. So you can go to the website that's listed and sign up for a free copy.

And the interesting thing to point out is that there's a very generous free tier. So, as a developer, you will never have to hit a paywall-- at least I don't think-- [LAUGHS] because it is this generous tier that you can set up test facilities-- as many as you want-- as long as you don't go over these generous limits per facility you'll never pay anything. So if you want to, if you're interested, go sign up, get the product, get familiar with it.

And then, diving into the platform itself, there is two APIs available. The REST API is the foundational API. It has been in beta. We're taking off the beta label this week at Autodesk University. So that will become official.

And then, there's also a JavaScript SDK that allows you to use an embedded viewer so that you can get the graphics with it. So that is-- I'll show you an example of that in a few minutes. But that's very usable and capable. It's just not well-documented yet. And we just haven't had time to clean it up. But anybody who wants to get started with that scenario of embedding a viewer, it's certainly doable. It's just that it's still going to have the beta label on it for a little bit longer.

And then, eventually, we want to be able to do extensions to the product, like you can do in Revit and AutoCAD, where you get the entire product and you can add your own custom commands to it. We haven't started that yet, but we know people are going to want that. And there's a lot of valuable use cases for that. So, eventually, we will get there. But it's just not available yet.

So what would you use the API for? Well, it's pretty well-known that digital twins by themselves are not very useful unless they're integrated with other systems. The whole idea is to visualize these other things that are hard to visualize. So IoT sensors are a classic example of you wouldn't know what the data is unless you can somehow present it in a compelling way, so integrations with IoT systems, building management systems, things like that.

And there's also lots of mission-critical systems that the owner uses to manage the building that also don't have any kind of good visual context. So maintenance management systems are a classic example of that. If anybody's familiar with Maximo, lots of facility owners depend on Maximo for the maintenance management. But it's very table-oriented.

So you see a list of assets, but you don't know where they are, and you can't figure out the context, unless you have something like Tandem to show you that building context. So there's a long tail of individual IoT sensors and other management systems that benefit by being integrated into Tandem where we have that solid BIM context that helps a lot. So, anyway, that's a big developer opportunity to go after all those integrations.

I've done a few of these integrations myself. So I did, for our own Autodesk facility in Toronto, we have it outfitted with VergeSense occupancy sensors. We have Robin room reservation system. And what I did is I hooked up to those systems, and then I used Tandem to run reports. I used the embedded Tandem viewer to run reports.

So what you see on screen-- I don't remember what the exact-- I think this was the Robin. And I asked it to highlight all the spaces based on their availability. So green meant that those conference rooms were available. Yellow meant that they were booked. And I can't remember what status blue was, but there's one blue one in there.

And I did the same thing for VergeSense, where it made a heatmap for the occupancy to show which spots were most occupied. And I did one for Maximo that would basically light up the assets that, based on their work order status. So if it needed repair, it would be color-themed one way. And if it was completed it would be themed another way.

So it just demonstrates the capability to integrate with those other systems and run a visual report of what's in them. And it also aggregates across systems. So you might see that a heat map is telling you that it's hot in a certain room, hotter than expected.

And then you could compare that against the VergeSense occupancy sensors and say, oh, well, it's not hot because the equipment is failing, it's hot because there's 50 people in a room that that's fairly small. So combining the integration between systems is also an interesting thing.

So let's dive into a couple of the details. This is not going to be a deep dive-- [COUGHS] excuse me. I'm not going to be a deep dive. I'm not going to try to teach you the API. But we do just want to give you an overview of what it's like to interact with it.

So the first thing you may have noticed is that, when I was showing the demo videos of the product itself, it might have looked a lot like the APS viewer, which is also-- might also know as the Forge Viewer or LMV. It goes by many names these days, but, basically, the browser-based viewer that's been a component in APS for quite a while.

And it is mostly the same. So the frontend part of it where you select, and isolate, and color things, that's all the same as the Forge Viewer. But the backend is different.

So the data layer talks directly to the Tandem database. It allows the addition of your own properties, user-defined properties. It handles incremental updates from the source files so you don't get what we call a Big Bang publish that basically creates everything from scratch every time. If you do updates, it remembers the history of what was there before.

And that improved data layer is ideal for lots of use cases. So the Forge Viewer before was great. But in terms of managing data, it was a little bit limited. And so, this Tandem viewer basically addresses some of those things. And there's also a new implementation of WebGPU which it makes it much faster for large models which, of course, everybody can benefit from performance.

So, like I said, the embedded viewer is part of the JavaScript SDK. That is available, but it's still going to be in beta for a while. But, like I said, it is very usable. And if you're-- especially if you know the APS Forge Viewer already, then it's pretty easy to use.

But we're going to talk about the REST API. So that's the foundation to everything, that they all map down to that REST API. So I'll give you some examples of that.

So it talks directly to the Tandem database server. So this is mostly about the data. And it's very efficient and powerful. But it also has these cryptic payloads which we'll see a couple of examples of. But it's designed to be extremely efficient. And it's what's used by the Tandem product itself.

So some common use cases are that you can assign classifications. We'll see why classifications are important in a second. Read and write all the element properties, read and add, read, add, delete the associated documents, like the PDF manuals that I talked about earlier. And then, push and pull stream data. So stream data is the IoT time series data from the sensors.

So it uses the same authentication that all the other APS APIs do. So if you're already familiar with those, it's going to be the same. Tandem supports both 3-legged and 2-legged authorization. So you can use it as if you were a logged-in user, or you can use it as a service that's been authorized by either the facility or the Tandem account to give that service access.

And then, it has this granular data model. Like I said, it's mostly about the data that makes this super interesting above and beyond, say, the [INAUDIBLE] viewer. So it has this granular data model where a facility is composed of multiple models which is composed of multiple elements.

And then, each element has a bunch of properties organized by what we call families and columns. And if you're a Revit-familiar person, don't confuse it with Revit families. These terms actually come from Google Bigtable. It just really means a group of properties. And we'll see an example of this in a couple of slides.

And then, if you look at the bottom left, you'll see this history. So not only does the property have a value, it has a history of values. So this one has been changed multiple times. So that's super important, because you want to-- somebody looking at this data wants to trust it. And if they don't know where that data came from, and they don't know who's changed it, they're going to trust it less. So that granular history is very important in this context.

And then, the biggest feature is this Custom Schema. So you want to be able to add your own properties to the model that track certain things about all these assets. Those are properties. We call them parameters, but same thing as a property. Those are things that were never specified during the design phase in Revit. And they need to be added by the owner.

So the way you do that-- and we're going to walk through this example-- but at a high level, there's a account-wide library of parameters or properties that get created. Then you map those to a classification. And then, any element that's classified a certain way is going to automatically get that set of parameters that are associated with the classification.

So, in this picture, it was set up that anything that's classified as doors and frames gets the set of properties that are in red. And so, all doors and frames will end up with those properties.

So just a walk-through of what that looks like in the product itself. There's a facility template that you can apply to a particular facility or twin. Within that template is a classification system. So that's what defines how you classify the elements. And we support standard things like uniformat and masterformat. But you can also do your own classification system. So you're going to be in hierarchical classification system you dream of, you can have that applied.

And then, like I said, a set of parameters can then be assigned to a particular classification. And then, when that object is classified with it, it's going to inherit these properties. So in this case, anything classified as PR, products, is going to get those four parameters that I've specified in this screen.

So then, back to the API. Now we just need to read and write those properties and classify elements in order for that data to be found and updated. As I said earlier, the API is designed to be super efficient. So on the right-hand side, you see examples of payloads for the REST call. And it looks a little bit cryptic.

But like I said, it's very powerful. So we're not going to go through all the examples in this class, but it's available in the documentation. And I'll show you an interactive tool that allows you to experiment with the different calls towards the end.

So, earlier, I talked about columns and families are sets of properties that can be attached. So this example shows different families of properties. So there's common ones that every element has, so like the name of the element or the level it belongs to, those are all in this family called n colon.

There's properties that came from the source file, like from the original Revit file. Those are read-only. And they come in, and the user can't change them because they have been defined in the original Revit source file. So those are all in the family r. And then, user-defined properties are read-write, and they are in the z family.

And it's not really important to dive into here, but it shows up in the API that you need to know, when you're calling for properties, you need to specify which families are you interested in to read the properties back.

So, internally, those have-- it's a little bit complex because, for each model, a property can have a different identifier. Remember that facilities are usually always an aggregation of multiple models. And so, each one of those is a separate model in the database. And if you're searching across the entire facility for a given property, you need to know what we call a qualified property ID.

So in the picture on the right, I have the ID of that property is z colon 5Ac, which just means it's a user-defined property. Its internal ID is 5Ac. But it shows up in the UI as a Maximo ID as the property name.

So whenever you use the API, you have to look up in the schema what the internal name is, because you can't use the user-facing name that shows up in the product UI, because it's not the same in every model. So most applications, they'll just read this schema ahead of time, make a mapping table, and then they don't have to do as many lookups every time they need it.

So the same thing happens with write. So there's one REST endpoint to do all of the write operations, which is called mutate. And, basically, either you're inserting or updating an existing value or you're deleting it. So the first argument to it is just an i or a d. And then you have some kind of mutation that's applied to a given element or key.

Key is the identifier of an element like a wall. And you just construct the payload to say, I want to make these changes to these particular elements. So in the example on the right, we're adding a classification override and we're saying, this came in from Revit classified as something, and we're going to override it and say that it's something else. So that's an example of using an update.

Then there's also APIs to get all the documents that are associated with the facility. So on the left is a screenshot from the product that shows there's a bunch of catalogs and warranty information that was attached. And those are all retrievable via the API. They're also addable via the API. So you can see in the payload that there's links to an Autodesk Docs repository, where those PDFs exist.

And it's important to note that there's a copy of the file that's stored in Tandem, so that the Tandem data set is completely free of the original source. But it keeps a link back to the original, and it will alert you if that original has been updated. So you can always go get an updated copy.

But we want the twin itself to be separate, because somebody's going to hand this over to the owner to operate. And you don't want dependencies on accounts that you don't have access to back in the original ACC Docs.

And then, the last thing you might use the API for is handle the streams. So, remember, the streams are IoT data that's coming in, IoT time series data. And there's multiple ways to do it. So this is a case where there's multiple REST endpoints to handle the operation. So you can push data into a specific stream. You can push data into multiple streams in one call with a webhook.

And you can also connect to Azure IoT hub. So if you're familiar with the whole IoT space, Microsoft has invested a lot in Azure IoT hub to coordinate all the devices. And so, it's already handled one layer of management of all those devices. And we made it easy to leverage that by just pointing to your Azure IoT hub and giving an authorization. And then, Tandem will read it all from there. So if you already have Azure IoT hub, it can be leveraged.

So just a recap of where all this data is coming from. Tandem operates as a digital hub for all the information associated with the building. So on the left-hand side, that maps back to the twin building part where it's the BIM model context. We're importing things from Revit, and Docs, and Excel, and wherever you're capturing information about the assets and the facility.

And then, the green side is that time series data coming in from IoT sensors or data coming in from these other systems, like maintenance management systems like Maximo or whatever. So it's going to pull data from multiple sources, associate it all together, clean it up in a lot of cases, and make sure it's consistent, and present it to the owner in a way that is most useful to them.

The original BIM model is probably not the best way for the owner to navigate it. So we smooth over the rough edges, clean it up, make it consistent, and present it in a way that's most useful.

So getting started with the API, I like to point people to these two TestBed applications that we have done. So the reason is, because without writing any code, you can go into these applications and just interactively try things out and see what the results are.

And then you can go, dive into the-- you can steal the code, and copy and paste for particular-- steal's the wrong word. You can leverage the examples and just copy and paste stubs that will do certain functionality. So it's just a much faster way to get started than going straight to the Docs and starting from scratch.

So I want to show you both of these quick example. And the links are at the bottom. You can go and try them out yourself, or they're publicly posted. So there's one for JavaScript. And then, this is an example of the embedded viewer scenario.

And then there's one for the straight REST API. They work exactly the same. It's not the exact same code, but they are similar in concept. And the only difference is the REST one, the image you see on the left is just a static thumbnail. It's not an embedded viewer. So there's no-- you can't interact with it the same way you can the other one.

So let me get out of the presentation for a sec, and we'll go over to these applications. And so, this is the REST API one. And I have all of-- first of all, you log in, and then you get access to all the facilities you've set up. So you would have had to have Tandem the product which, like I said earlier, is free and isn't going to cost you anything to set up a sample facility. Once you log in, you get access to those. You can switch between them.

And then you just call these stub functions. So I talked about the history feature earlier. So if I wanted to-- I guess that's in the JavaScript one, sorry. If I want to see the history of all the changes to this model, all the output goes to the debug window of Chrome. But I can see, these were all the changes that happened. I get the name of the person who changed it, what they did. So that's just an example of the history feature.

And then, earlier, we were talking about the scan function, which is how you read properties and the cryptic payloads that happen. So you could go straight to the documentation and try creating those REST calls yourself. But I think it's easier to come here and go run these.

So I'm going to do an example of the scan function. And I put in the URN of the model I'm looking for, which in this case is the architectural model that's part of here, and the key. And the key is the element ID of this wall that you see in the front. And you didn't see how I got those, but I can show you in a second.

And if I say I just want the user-defined properties and say, OK, then what returns in the debugger window is the results from that REST call. And you'll see, there's a group of properties here all beginning with z and the value. So those are the qualified property names and the values that show up for those.

And then, I could test. I go, well, how can I call that a different way? And so, I'll bring that up again. And I'll say, well, this time I want to include all these other properties. And I'll see that I got not only the z family that we saw before, but I got the r family of properties, which was all the Revit-defined properties. I got n, which is common, and l is links to other objects, like a link to the floor that this element is on.

So I don't want to belabor the point. I'll let you play with these apps yourself. But they're really useful for experimenting with the API, seeing what the result is, and then drilling down in the code. If I now want to see the code for this, I can either go to the project in GitHub and get it, or I can just call it up in the browser and go, oh, this is-- here was the code that did that. So it's a quick way to learn.

And you can also use them together to debug or reverse-engineer things. So how did I get, when I called up the scan function, how did I get this model URN and this key for that particular element? Well, that's available really easily in the JavaScript embedded viewer.

So if I say, this wall, there's a function here that will convert viewer ID to element ID. And I can just grab this and paste it someplace. Also, the model that this came from is right here. So that's how I got those two pieces of information.

So, anyway, these tools are super useful for understanding the API and reverse-engineering how some of this stuff works. There's also the regular documentation that you can go read like a normal REST API. So that'll be available as well. But these tools, I think, are very useful to get you started.

All right, so given that, that's the end. So we have time for questions. And we'll take it from there.