Last August, BIM360 exposed custom attribute API of document to get definitions, get attributes values, and update attributes values. In this February, the API to create definitions is exposed.
Before March 23, 2021, the attributes in BIM360 are managed per FOLDER level. Besides inherited attributes (from the parent folder), the folders can contain attributes with same name. This is because the attributes definitions are independent among folders. They are managed in the corresponding folders separately. So, when creating definitions by API, the definition is created directly on this folder. It only checks duplication in this folder.
After release of March 23, 2021, the definitions are managed in PROJECT level. The definitions will be applied to which folders (e.g. 'AAA' in this demo below).
In Project Admin, the administrator can apply to which topmost folders (Plans, Project Files), the sub folders will apply with the attributes. Note: The built-in attributes will apply to the topmost folders in default.
The user could also attach/un-attach the attributes with specific folder in Attributes Settings.
So, when creating a new attribute, internally, the new mechanism will firstly create definitions in project, and attach the definitions reference to specific folder. e.g. two folders can refer to same definition with same name like ‘AAA’ in this snapshot.
Note: the name is NOT case sensitive. AAA, AaA, aaA etc will be treated as same name..
The internal mechanism of API endpoint to create attributes definitions is also updated accordingly.
- If to create ‘AAA’, yet ‘AAA’ definition exists, attach the definition to the folder directly.
- If to create ‘AAA’, yet both ‘AAA’ and ‘aaa’ (or 'Aaa', 'AaA' etc) do not exist, create definition 'AAA’ in project and attach the definition reference to this folder.
- If to create 'AAA', yet ‘aaa’ (or 'Aaa', 'AaA' etc) exists, the backend will treat it as duplicated and refuse to create it. The detail message in response would be like.
{
"code": "CUSTOM_ATTRIBUTE_DUPLICATE_NAME",
"title": "Multiple names duplicated in the project",
"detail": "The name is duplicated with existing attribute id: 2099984, name: aaa (case-insensitive)."
}As to get attributes values, update attributes values, they are not changed.
As to get definitions, for new projects, since it is a kind of reference, the returned data means the definitions that are attached to this folder, instead of the definitions that are only with this folder like before.
The API to get all definitions of project level and more APIs related with new mechanism are on the way. If you have any feedback with the use case, please feel free to contact at forge.help AT autodesk.com
Update on Sep, 2021
On Sep, 2021, BIM360 Docs Custom Attributes enhanced with constraints for text attribute values. With constraints set, members entering attribute values will only be permitted to enter text that conforms to the constraints. Three types are allowed: Alphanumeric, Text or Numeric. And range of the character could be: Any, Fixed and Range. By default, the type is alphanumeric, and length is any. Please check Release Note for details.
From API perspective, NO API yet to get/set constraints. They are on the roadmap of future API. While current API endpoint (updating attributes value) added constraints checking. e.g. if type is not correct, it will throw error like below.
If length does not follow the setting, it will throw the error:
