How Required Custom Attributes Influences Uploading Documents to Autodesk Docs

Autodesk Docs introduced a new feature: Custom Attributes of Files can be required or not. By default, it is not required. When any attribute is required, the uploading file will follow the behaviors as below in Autodesk Docs UI, which are influenced by the status of Holding Area (HA):

HA is on: before uploading the file, the user is asked to input the values of required attributes. If not, Autodesk Docs still allows the file to be uploaded, but the file will be moved to HA, waiting for inputting required attributes. As long as all required attributes are input with the value, the file will be moved to the folder to normal operations.
When creating a new version, moving files, copying files, restoring files, the validation mechanism also runs. If the values have been available, it will reuse them. Otherwise, it will also send the file to HA. After inputting the values, the file will be moved to the folder as normal.

HA is off: similarly, before uploading, the user is also asked to input all required attributes. If any field is missing, Autodesk Docs will refuse to upload the file. HA=off is a rare case. We suggest you be careful to set it off.

Please check product help for more details.

From API perspective, as well known, to create the file item in the folder, we will follow the steps of uploading document tutorial. The new feature will influence the workflow:

HA is on: The step (create file item) will succeed, while the non-conforming file will be sent to HA because missing required attributes. The related APIs of Data Management do not support inputting custom attributes. data.attributes.extension.data.conformingStatus of the file item/version indicates it is NON_CONFORMING.
```
{
  "processState": "PROCESSING_COMPLETE",
  "extractionState": "SUCCESS",
  "splittingState": "NOT_SPLIT",
  "reviewState": "NOT_IN_REVIEW",
  "revisionDisplayLabel": "1",
  "sourceFileName": "simple-walls-only.rvt",
  "conformingStatus": "NON_CONFORMING"
}
```
You will use the API custom-attributesbatch-update to input the attributes values. After that, the file will be moved to folder. And data.attributes.extension.data.conformingStatus = CONFORMING.

Other scenarios such as creating the new version is also similar to UI, if required attributes are missing, the file is sent to HA. After the attributes are input, it will be moved to the folder as normal.

Note: conformingStatus is also used to identify whether the file name follows naming standard (when the folder applies with the standard). Only when both name follows naming standard and required attributes are input with values, this attribute can be CONFORMING. Check out the other blog to learn more on API behaviors of naming standards.
HA is off: The step (create item, or create new version) will fail with the error as below. Since custom-attributesbatch-update API requires a valid version id from the successful creating item/version, no approach now to input the attributes values in such scenario. So, when your application receives such error, please note this is related to the missing attributes. If your scenario must set HA=off, please be aware of this limitation.
```
  {
     "id": "46ab85ad-894c-41bb-8fa7-a20a6cf081fd",
     "status": "400",
     "code": "ERR_REQUIRED_ATTRIBUTE_VALUE_INVALID",
     "title": "Missing required attributes value.",
     "detail": "The required attribute value should not be empty"
   }
```

Limitations

As mentioned above, when HA=off, the file item/version cannot be created if required attributes values are missing. We have logged wish to handle such scenario. Current workaround is to communicate with the ACC account/project admin to enable HA=on if it is fine to that workflow.
The Data management API (create item/version) does not support inputting values of custom attributes.
No API tells which attributes are required, either no API set attributes to required. The related wishes are also logged.
No API manipulates HA (on/off).
Empty string is not allowed with Text attribute.

If you have any feedback, welcome to contact us by https://aps.autodesk.com/get-help.

Tags:

Autodesk Construction Cloud (ACC) APIs