Model Derivative API has the ability to translate composite models (i.e. multiple models linked by the xRefs or external links) into a single Forge Viewer model (saying the SVF) via uploading a ZIP file that contains the host model and links and passing both rootFilename and compressedUrn parameters to the POST job request payload.
curl -X POST \
https://developer.api.autodesk.com/modelderivative/v2/designdata/job \
-H 'Content-Type: application/json; charset=utf-8' \
-H 'Authorization: Bearer {ACCESSTOKEN}'
-H 'cache-control: no-cache' \
-d '{
"input": {
"urn": "dXJuOmFkc2sub2JqZWN0czpvcy5vYmplY3Q6YXBwdGVzdGJ1Y2tldC9iYXNpY19zYW1wbGVfcHJvamVjdC56aXA",
"compressedUrn": true,
"rootFilename": "rac_basic_sample_project_linked.rvt"
},
"output": {
"formats": [
{
"type": "svf",
"views": [
"2d",
"3d"
]
}
]
}
}'But what If we want to achieve the same goal on BIM360 Docs, how can we do? BIM360 Docs doesn't support ZIP file format translation currently.
Fortunately, there is a function called "Upload Linked Files" on the BIM360 Docs Web UI, and we do support a similar thing on the Forge API side. So, let's see how magic it is!
Note. This approach works for file formats like RVT, DWG, IAM (&IPT), etc, not just RVT files.
The following tutorial will use Revit models (rac_basic_sample_project.rvt & rst_basic_sample_project.rvt) as examples, and The rst_basic_sample_project.rvt is a external link inside the rac_basic_sample_project.rvt. (Note. rac_basic_sample_project.rvt is renamed as rac_basic_sample_project_linked.rvt inside this toturial.)
Before getting started, there is something you need to know:
- The RVT files of Revit external links have to be uploaded first before creating link info. (xrefs) on the host RVT file (i.e. parent file) in order to obtain version ids of those external links, e.g. urn:adsk.wipprod:fs.file:vf.b909RzMKR4mhc3O7UBY_8g?version=2
- Revit links within the host RVT file must be set up before uploading it to the BIM360 OSS Bucket (WIPDM). It's a known limitation of the Forge Revit extractor.
- The storage spaces created by POST projects/:project_id/storage could be used once only after uploading a file onto it. After then, you cannot upload new files to this storage space anymore.
Ok, here are the magic steps for the new host RVT model:
- Obtain version ids of the external link files via calling GET Folder Contents or GET items/:item_id.
- Create a storage location and upload the host model as usual (toturial link).
- Create the first version with the xrefs configurations via calling POST projects/:project_id/items with this request body (payload):
{
"jsonapi":{
"version":"1.0"
},
"data":{
"type":"items",
"attributes":{
"displayName":"{{Filename}}",
"extension":{
"type":"items:autodesk.bim360:File",
"version":"1.0"
}
},
"relationships":{
"tip":{
"data":{
"type":"versions",
"id":"1"
}
},
"parent":{
"data":{
"type":"folders",
"id":"{{FolderId}}"
}
}
}
},
"included":[
{
"type":"versions",
"id":"1",
"attributes":{
"name":"{{Filename}}",
"extension":{
"type":"versions:autodesk.bim360:File",
"version":"1.0"
}
},
"relationships":{
"storage":{
"data":{
"type":"objects",
"id":"{{URN}}"
}
},
"refs": { //!<<< The key to set up model links
"data": [{
"type": "versions",
"id": "{{VersionURNforLink1}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}, {
"type": "versions",
"id": "{{VersionURNforLink2}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}, {
"type": "versions",
"id": "{{VersionURNforLink3}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
},
// ... other links
]
}
}
}
]
}Example of the first version request payload:
{
"jsonapi":{
"version":"1.0"
},
"data":{
"type":"items",
"attributes":{
"displayName":"rac_basic_sample_project_linked.rvt",
"extension":{
"type":"items:autodesk.bim360:File",
"version":"1.0"
}
},
"relationships":{
"tip":{
"data":{
"type":"versions",
"id":"1"
}
},
"parent":{
"data":{
"type":"folders",
"id":"urn:adsk.wipprod:fs.folder:co.AijQHeiLT7mqLc1Eow-Geg"
}
}
}
},
"included":[
{
"type":"versions",
"id":"1",
"attributes":{
"name":"rac_basic_sample_project_linked.rvt",
"extension":{
"type":"versions:autodesk.bim360:File",
"version":"1.0"
}
},
"relationships":{
"storage":{
"data":{
"type":"objects",
"id":"urn:adsk.objects:os.object:wip.dm.prod/8447edd0-a468-41ee-b47b-3e7214944b10.rvt"
}
},
"refs": {
"data": [{
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.y6GJ2scBSVSyIRM_wtEsDA?version=1",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}
]
}
}
}
]
}Afterward, you will see structural elements of the rst_basic_sample_project.rvt appear within the rac_basic_sample_project_linked.rvt on the Docs.
In addistion, you may ask how about setting xrefs up for host model and reman its file revision history. Sure, it's quite simple and strightforward by appeding a new tip version. The first two steps are similar to the first-version one:
- Obtain version ids of the file that are going to be linked.
- [IMPORTANT] Creat new storage space for the host model and upload the RVT file onto it again.
- Create a new tip version for configuaring xrefs with calling POST projects/:project_id/versions with this request body (payload):
{
"jsonapi": {
"version": "1.0"
},
"data": {
"type": "versions",
"attributes": {
"name": "{{Filename}}",
"extension": {
"type": "versions:autodesk.bim360:File",
"version": "1.0"
}
},
"relationships": {
"item": {
"data": {
"type": "items",
"id": "{{ItemId}}"
}
},
"storage": {
"data": {
"type": "objects",
"id": "{{URN}}"
}
},
"refs": { //!<<< The key to set up model links
"data": [{
"type": "versions",
"id": "{{VersionURNforLink1}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}, {
"type": "versions",
"id": "{{VersionURNforLink2}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}, {
"type": "versions",
"id": "{{VersionURNforLink2}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
},
// ... other links
]
}
}
}
}Example request payload for creating a tip version:
{
"jsonapi": {
"version": "1.0"
},
"data": {
"type": "versions",
"attributes": {
"name": "rac_basic_sample_project_linked.rvt",
"extension": {
"type": "versions:autodesk.bim360:File",
"version": "1.0"
}
},
"relationships": {
"item": {
"data": {
"type": "items",
"id": "urn:adsk.wipprod:dm.lineage:y3L7YbfAQJWwumMgqjJUxg"
}
},
"storage": {
"data": {
"type": "objects",
"id": "urn:adsk.objects:os.object:wip.dm.prod/8447edd0-a468-41ee-b47b-3e7214944b10.rvt"
}
},
"refs": {
"data": [{
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.y6GJ2scBSVSyIRM_wtEsDA?version=1",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}
]
}
}
}
}So, the final result! Now we use the BIM360 version comparison tool to see the content changes. All structural contents are shown in the architecture model.
UPDATE 2019 Nov. 21th & 2025 Jul 10th:
New way to configure xrefs for an existing host model and reman its file revision history. There is a new query string parameter of the POST projects/:project_id/versions called copyFrom. With this parameter, we can ignore the file uploading processes mentioned above, make our life more easier. So, the API call will become shorter:
Note. If you want to create a link relationship to the links immediately after adding a new version or the first version of the host model, please consider using the method above instead.
// POST https://developer.api.autodesk.com/data/v1/projects/{PROJECT_ID}}/versions?copyFrom={{ESCAPED_VERSION_ID}}
{
"jsonapi": {
"version": "1.0"
},
"data": {
"type": "versions",
"relationships": {
"refs": { //!<<< The key to set up model links
"data": [{
"type": "versions",
"id": "{{VersionURNforLink1}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}, {
"type": "versions",
"id": "{{VersionURNforLink2}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}, {
"type": "versions",
"id": "{{VersionURNforLink2}}",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
},
// ... other links
]
}
}
}
}Example request payload for the new method:
// POST https://developer.api.autodesk.com/data/v1/projects/{{PROJECT_ID}}/versions?copyFrom=urn%3Aadsk.wipprod%3Afs.file%3Avf._AMHUWsSS-S8PHQBILp3lQ%3Fversion%3D1
{
"jsonapi": {
"version": "1.0"
},
"data": {
"type": "versions",
"relationships": {
"refs": {
"data": [{
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.y6GJ2scBSVSyIRM_wtEsDA?version=1",
"meta": {
"refType": "xrefs",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"data": {
"nestedType": "overlay"
}
}
}
}
]
}
}
}
}Troubleshooting for copyFrom:
If you receive an HTTP status 406 with an error message similar to the one below, please consider using the approach without copyFrom above, or consider waiting a little (e.g., 30 seconds or longer) and retry. The root cause of this error is that the APS OSS service continues to process the uploaded file after it has been uploaded. Before the process is done, the file is not copyable. Therefore, we must wait for that or consider using the approach without copyFrom instead.
{
"jsonapi": {
"version": "1.0"
},
"errors": [
{
"id": "bf468308-deb2-4a6e-91dc-b4ea51593804",
"status": "406",
"code": "ERR_STORAGE_NOT_READY",
"title": "Storage is not ready",
"detail": ""
}
]
}
UPDATE 2024 Feb. 29th:
Calling POST projects/:project_id/versions with and without the copyFrom parameter is to append a new version of the host file with the link relationship data, so we can only see the new version data of the host returned in the API response, which means we cannot see the link data in the response of POST projects/:project_id/versions.
We must call another API GET versions/:version_id/relationships/refs with the version ID of either host or links to see the link relationship we just created. Here is an API response example of GET versions/:version_id/relationships/refs:
//GET https://developer.api.autodesk.com/data/v1/projects/{{PROJECT_ID}}/versions/urn:adsk.wipprod:fs.file:vf._AMHUWsSS-S8PHQBILp3lQ%3Fversion=2/relationships/refs
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": {
"href": "https://developer.api.autodesk.com/data/v1/projects/{{PROJECT_ID}}/versions/urn:adsk.wipprod:fs.file:vf._AMHUWsSS-S8PHQBILp3lQ%3Fversion=2/relationships/refs"
},
"related": {
"href": "https://developer.api.autodesk.com/data/v1/projects/{{PROJECT_ID}}/versions/urn:adsk.wipprod:fs.file:vf._AMHUWsSS-S8PHQBILp3lQ%3Fversion=2/refs"
}
},
"data": [
{
"type": "versions",
"id": "urn:adsk.wipprod:fs.file:vf.YGcRKkJnRHCNSZtL2vyapg?version=1",
"meta": {
"refType": "xrefs",
"fromId": "urn:adsk.wipprod:fs.file:vf._AMHUWsSS-S8PHQBILp3lQ?version=1",
"fromType": "versions",
"toId": "urn:adsk.wipprod:fs.file:vf.y6GJ2scBSVSyIRM_wtEsDA?version=1",
"toType": "versions",
"direction": "from",
"extension": {
"type": "xrefs:autodesk.core:Xref",
"version": "1.1",
"schema": {
"href": "https://developer.api.autodesk.com/schema/v1/versions/xrefs:autodesk.core:Xref-1.1"
},
"data": {
"nestedType": "overlay"
}
}
}
}
],
"included": [
// Here will show the items and versions for host and links
]
}