23 Nov 2021
Model Derivative SVF2 enhancements - Part 2 Metadata
SVF2 and Metadata API Endpoints
We have added some additional functionality to help with metadata/properties access. To start, let’s explain the difference between SVF and SVF2 metadata.
Because the SVF2 format is referencing geometry now instead of having individual instances, the object id system was updated. For a specific job, whether SVF or SVF2 the object ids help you to identify individual objects and work with them from metadata perspective. As documented, the external id is still a unique id based on the source format (for example, in Revit, it is the UniqueID property of an element, or in AutoCAD, it is the handle). But unfortunately, not all formats have a true external id source (for example Inventor format). Because of this, some developers used the object id to link to external data to the objects. When SVF2 beta came along, we were providing SVF object ids and metadata and this quickly was viewed as a problem, and a change request was accepted. The update for this came during the beta cycle and seemed to resolve the issue for a viewer session where external data was not linked. However, developers who were relying on SVF object ids had broken workflows, especially those using BIM 360 docs.
We now have a few additional options that can help developers manage between these two formats:
From Model Derivative perspective… The main concept is to think of each format as mutually exclusive.
- If you specify “SVF output type”, then the metadata API endpoint will provide “SVF data” and object ids.
- If you specify “SVF2 output type”, then the metadata API endpoint will provide “SVF2 data” and objects ids.
The Forge Viewer will load SVF2 and use SVF2 IDs when referencing metadata internally to the Forge Viewer APIs. If Forge Viewer falls back to SVF, then it will use SVF IDs when referencing metadata internally. Forge Viewer does not use the metadata API endpoint, to retrieve metadata, so there is no conflict.
From the BIM 360 Docs perspective, it becomes more complicated…
Again, for Forge Viewer, you can use the previously mentioned api/env parameters, and everything again will behave correctly due to Viewer “fallback” behavior. A session’s metadata and object ids will be fine.
But what happens from external data connectivity perspective? If the developer used external ids, again there should be no problem as those are always accurate. But in the case where object ids are used, this is where it becomes tricky. It’s assumed that in this scenario that you have connected using SVF object ids, and when the job is an SVF2 output type in later BIM 360 jobs, now there is a mismatch. We have exposed an additional and optional parameter to certain API endpoints to help generate the SVF1 metadata when needed. See these docs… https://forge.autodesk.com/en/docs/model-derivative/v2/change_history/changelog/#release-date-2021-08-26 for pointers to the changed APIs. The two main APIs that come into play here are the metadata endpoints when called on a BIM 360 doc URN. If the job is now SVF2, but you need to access SVF objectid oriented metadata, you can use those endpoints with a new “fallback” value in the header parameter named “x-ads-derivative-format” to force the API to return the SVF formatted metadata. Please note this is provided as a convenience, and it would be best to eventually move to the SVF2 metadata (and ideally use external ids to link the data whenever possible).
One final “tip” is part of the Forge Viewer as of Version 7.46. The blog post here explains the details: https://forge.autodesk.com/blog/temporary-workaround-mapping-between-svf1-and-svf2-ids and the update is explained in the Viewer Changelog (https://forge.autodesk.com/en/docs/viewer/v7/change_history/changelog_v7) for 7.46. This discussion covers how to map between the SVF and SVF2 objectids.