The Data Exchange service has been accessible to developers through GraphQL API and .Net SDK.
The .Net SDK is very powerful and is usually used to create connectors from/to Data Exchange service to/from non-Autodesk products and services.
The GraphQL API was always aiming for simplicity and consequently being limited to reading data from already existing exchanges, created in ACC environment by the user.
Thus, if a developer needed to create an exchange programmatically, the only solution was to rely on .Net SDK and if the developer in question had no experience with .Net, this is a blocker. Another issue with .Net SDK is that it is limited (at least for now) only to Windows environment and this constitutes an issue for automation workflows (that may rely on *nix environments).
To address the issue, the GraphQL API was reinforced with a mutation call that now allows creating exchanges programmatically. There are currently two data sources you can use:
- Revit files with saved views
- AEC Data Model filters
The creation of the exchanges using Data Exchange GraphQL API can be made through a mutation call that is generic enough for all formats but takes into account some particularities. A very good example is creation of an exchange from Revit file compared to creating it from AEC Data Model. A Revit model will contain views and when creating an exchange you have to specify the View from which you would like to create the exchange. In case of AEC Data Model, you can specify the Categories, Family and Type of components that should be included into the exchange.
Mutation API in action
The first step to go through is to join our public beta for this new API
- First take this survey to enter the beta group
- Then join the discussion and post any questions in this forum
- Then the documentation for the new mutation API is here
To illustrate the creation of the exchanges using Data Exchange GraphQL API, we will use the https://aps-dx-explorer.autodesk.io/ tool, but the same results can be achieved using Postman, Insomnia or any other tool or programming language capable of making REST calls (under the hood a GraphQL query is sent to a REST endpoint).
Navigating to the source file
To be able to trigger creation of an exchange from a given file/model, it has to be in ACC Docs. At least for now, no other source locations are supported. Once it is in ACC the navigation to it can be done as before, with a slight exception.
The calls to get hubs and projects are same:
When it comes to get the content of the folders, before it was possible to get only the exchanges, while now, due to a schema change, it allows getting the name and id of the items:
This change to the schema was necessary to facilitate creation of the exchange because the id of the item will be used as the input, which we will see in next workflows.
Creating exchanges from Revit file
Use case: we have an Revit file in ACC and we don't want to share the entire Revit model, but just a view of it, so we decide to create an exchange from a view of a Revit file and share the exchange instead.
Using the new mutation API is very simple and in case of Revit model, it requires just:
- id of the Revit file - which can be found when query the folder content and looking at the needed id within items list
- id of the folder - this is the way specifying the place where the exchange will be created and it can be the same or it can be any other folder within the same project.
- ViewName - so that the system knows which View to use as a reference
Having all this, the call will look like this:
Here worth mentioning several things:
- it is a mutation instead of usual query
- we specify in the body that we are interested in id and name of the exchange we create
- getting back the id and the name of the exchange doesn't mean that the exchange was created and ready to be used, it just means that the name and id was allocated to this exchange and the process was started and depending on the job complexity it can be already ready or it can take some time.
If you immediately take the exchange id that was given to you and try to run the exchange query (usually presented as GetExchangeInfo), you will get a response full of "[404 Not Found] The specified resource was not found." errors like bellow:
Thus, give it some time to process the exchange and use the exchange query to see if the results are ready or check the status of it using the new dedicated call:
The status can be:
- IN_PROGRESS - The exchange is being created.
- COMPLETED - The exchange has been completed processing.
- FAILED - The exchange creation failed.
Creating exchanges from AEC Data Model
Use case: we have an AEC Data Model, and we want to share a subset of this model, based on some filters.
In case of an AEC Data Model, the workflow is similar to Revit workflow, except that in this case we have to specify the "filter", so that the system know which component subset to use as a reference.
Currently, within the filter function, only the levels of Category, Family, and Type are supported. For instance, you can use a filter such as "(category=='Windows')". It is important to note that even complex filters with [and]/[or] criteria are supported, and we are in the process of developing additional filter types. We welcome your feedback to help us prioritize the features that are most essential for your workflow.
Conclusion
Before, if your pipeline required creation of exchanges from certain (e.g. Revit) models, you had to manually do that by going to ACC, selecting the file, selecting the view and triggering creation of the exchange. With addition to Data Exchange GraphQL API of this new functionality, it is now possible not only to automate all this, but also it opens the way to more complex workflows, like:
- automatic creation of an exchange when Revit file was added to ACC (some Webhook API involved)
- automatic creation of an exchange for all model existent in a folder
- automatic creation of the exchanges for all 3D views a Revit file contains (some Model Derivative API involved)
and many others.
Just to illustrate the ease of use of this new addition to Data Exchange GraphQL API in automation context, a simple CLI sample was created, that can be used as a reference.
We are open for suggestions on currently supported formats (Revit and AEC Data Model) and we would be glad to hear from you on next file formats that should be supported next and what selection criteria should be specified to ease selecting the needed subset of the model.
We invite you to influence our development efforts by joining the public beta for this API - and then by providing feedback on the DX Graph QL API Public BETA user forum. Here, you can also propose desired features and request additional supported formats.