Forge Data Management API: items, versions and attachments

By Philippe Leefsma (@F3lipek)

This post shows the part of my server application that deals with items, versions and attachments. You can find the detailed curl commands that you need to send exposed by the step-by-step section of the API documentation: upload a file, however I thought it could be useful to take a look at a concrete implementation in my node.js sample.

The first thing to understand is that the Data Management API is composed by several services, the lowest level one being Object Storage Service (OSS). This service is exposed for 2-legged and 3-legged OAuth applications but with some differences: for 2-legged your app gets access to private buckets and objects that you are creating at your will. For 3-legged, the Data Service still relies on OSS, however your app needs to let that service decide which bucket and object keys to use when it needs to upload a new file or create a new version of an existing item.

The diagram below summarises the situation, the "OSS Private bucket" (lower-right) is the 2-legged part of the service, the rest is 3-legged:

Each item can have at least one or multiple versions. A version is really a logical representation of the actual file stored of the cloud. There is a direct link between version and file.

The step-by-step tutorial shows how to create a new item with the service and how to create a new version of an existing item. What I want to illustrate here is how to handle that workflow concretely. The code below illustrates how to upload a file to the service: if no item with the same display name exists under the target folder, it will create a new one, otherwise it will create a new version of that item and append to it.

You can refer to the complete code by looking at the implementation of my DMSvc service. I split the code on my server in those multiple micro-services which makes it easy to reuse in different parts of the app or even other projects.

The other feature I added to my sample recently is about attachments: an attachment is a reference between two versions under the same project. It is limited to version-version at the moment but should be extended to link a version to an item or folder in the future. The step-by-step tutorial from the help file can be found there. Below is the code that shows how to get and create version attachments:

All this can be tested in the live demo of my Data Management sample at: https://dm.autodesk.io. As illustrated in the picture below, you can visualise versions and attachments info for the selected item (by clicking on the clock icon in upper treeview). From there it is possible to either drop or pick a file to attach to this version. If the attached file doesn't exist in the target folder, a new item will be created and the first version will be attached, otherwise a new version will be added to the item.

The UI also allows to create an attachment by specifying "manually" the versionId: right-click on Attachments and select "Attach by version Id":

You can easily find out what is the version Id you are looking for by selecting another item, display its versions and use the context menu command again: "Show version details"