21 Dec 2016

Setting up external references between files

Default blog image

When the Data Management and Model Derivative API's got introduced, replacing the previous ones that were bundled with the Viewer, then you had to upload complex models in a zip file. By complex model I mean those that consist of multiple files referencing each other. In case of AutoCAD DWG files these references would be called "XREF's" in case of others it's just "File References" or "Referenced Documents"

The good thing about using the zip approach is that it contains all the files needed in a single place and so the Model Derivative service can resolve all the references automatically. The bad thing about it is that you might have to upload the same file again and again in different zip files in order to create viewables that can be shown in the Viewer.

The Data Management API is now capable of setting up XREF (it's going with the AutoCAD naming convention) relationships between files which will be honoured by the Model Derivative API when it's doing a translation.

Note: relationships can only be set up between files that reside in the same A360 (or Fusion Team, BIM 360 Team) Project.

To show how it works I uploaded an assembly and a referenced part document to A360. As you'd expect, the translation of the part file succeeded, but the assembly's failed:


If you check with a sample app like http://derivatives.autodesk.io/ then you'll run into the same issue, that the translation fails for the assembly:


With that sample you can also check the manifest of the file in the Console window of the browser and you'll find the reason why the translation failed. Which is, as expected, that the part file could not be found:


Using the POST /relationships/refs endpoint of the given file version on A360 you can add 
xrefs:autodesk.core:Xref relationship from the assembly to the part, which will be honoured by the Model Derivative API when doing the translation and looking for the part. 

The version id of the files I'm using:
AssemblyTest.iam (v1): urn:adsk.wipprod:fs.file:vf.cwgYCF5LQOShkzKA414Zbw?version=1 
AssemblyTest.ipt (v1): urn:adsk.wipprod:fs.file:vf.E0ObBbVgQP-Nko5AfMNHDw?version=1

Using those we can send this POST request:


  "jsonapi": {
    "version": "1.0"
  "data": {
    "type": "versions",
    "id": "urn:adsk.wipprod:fs.file:vf.E0ObBbVgQP-Nko5AfMNHDw?version=1",
    "meta": {
      "extension": {
        "type": "xrefs:autodesk.core:Xref",
        "version": "1.0",
        "data": {}

Now we need to ask for the SVF translation of the assembly again. In order to do that you can either use the x-ads-force: true header value when POST-ing the job,  or delete the manifest of the assembly before asking for the translation (that would delete the result of other jobs as well though).

After that the translation succeeded:


And now the relationship shows up in A360 as well:



Related Article