File Naming Standards API of BIM360 Docs and Autodesk Docs

File Naming Standards

We are pleased to announce that file naming standard API for BIM 360 Docs and Autodesk Docs is now available. In this first phase of naming standard API release, the API is read-only. You can check if a given folder is enforced with naming standard and if a given file satisfies the standard. You can also retrieve the standard definition. If you are not familiar with file naming standard feature, please take a look at product help that you can find here. This ISO 19650 based naming standard was first introduced in BIM 360 Docs and Autodesk Docs since March 2021. Note: the feature is enabled only to the newer projects. i.e., you do not see it if your project was created prior to the release of this feature.    

When you enforce naming standard to a folder, related attributes are defined automatically. You can also add custom attributes, which are shared with common custom attribute definitions. 

In the UI, you have an option to enable “holding area” (HA for short). When enabled, holding area is used to temporarily store non-conforming documents. Once the name conforms the standards, the document will be visible in the folder as normal. If HA is turned off, the system will prohibit the user from uploading non-conforming documents.  When accessing folder structures using Data Management API, the file kept in HA will be listed just like any other files; i.e., hidden is also false. the difference is that it will have a confirmingStatus attributes set as NON_CONFORMING. We will come to more detail below shortly.   

Naming Standard  API 

As to API, we now have one new endpoint GET Naming Standards that retrieves the definition of file naming standard for a project. This end point works for both BIM360 Docs and Autodesk Docs.  

GET:     https://developer.api.autodesk.com/bim360/docs/v1/projects/:projectId/naming-standards/:id 

Below is an example of response: 

Attributes of naming convention are the data in fields, while attributes of related attributes are the data in metadata. The optional attribute tells the attribute is required or not.

Available data types are: 

• ALPHANUMERIC: Accepts all characters.
• NONNUMERIC_TEXT: Accepts all characters, excluding 0-9.
• NUMERIC: Accepts 0-9, comma ',', plus '+', minus '-', percent '%', period '.', underscore '_'.
• ARRAY: A drop-down list.

Enhancement in Data Management API

Data Management API is enhanced with a feature to check if a given folder is enforced with naming standard and if a given file satisfies the naming standard. 

• get top folders, get folder contents and get specific folder has a new attribute data.attributes.extension.data.namingStandardIds. It will tell if the folder is enforced with standard. It is an array of standard ids. Currently, one standard only.
• get folder contents, get item and get version has a new attribute  data.attributes.extension.data.conformingStatus.  It will tell the conforming status of the document:
  • NONE: means this folder is not enforced with any standard
  • NON_CONFORMING: the folder is enforced with the standard, but this document name does not conform the standard. It is in the HA.
  • CONFORMING: the folder is enforced with the standard, and this document name conforms the standard.

As the UI and API has slightly different behavior, let us take a look a few cases and explain some more detail.  

Case Study

In practice, there might be a few scenarios with the API when working with naming standard.  

Case#1: name is non-standard yet HA is on
In this case, it will work as usual when uploading the models to the folder by API (uploading document tutorial). After create item succeeds, the document will be hold on in HA. The document will be in the status NON_CONFORMING. The translation of the document (to generate manifest of SVF) will be still processed automatically.
  
One discrepancy with UI is: If the web application calls get folder contents by the 3 legged token logged with common project member, the documents in HA will be returned, while in UI, only project admin can view the documents in HA.
 
Case #2 name is non- standard yet HA is off
In this case, although create storage and upload to oss can succeed, create item will fail with the error 400 and the message: The file name is not conforming to the required naming standard. It exactly checks the standards such as length, value, type etc. If any of them does not match the standard, it will throw error 400.
 
Case #3 HA is on, name is changed from non- standard to standard
In this case, in UI, the documents will be visible in the folder as usual. In API, we can call PATCH version, or POST new version with standard name. Then the document will be moved from HA to visible area like UI does. The document will be in the status CONFORMING.