Update a Document’s Custom Attribute Values
This tutorial demonstrates how to update a document’s custom attribute values in BIM 360 Document Management. The steps include retrieving custom attribute values and definitions, and updating the custom attribute values.
For more information about custom attributes, see the Help documentation.
Before You Begin
- Register an app.
- Provision your app to acquire access to your BIM 360 account, to both BIM 360 Account Administration and Document Management.
- Acquire a 3-legged OAuth token or a 2-legged OAuth token with
data:read
anddata:write
scopes. - Find the account ID, project ID, folder ID, and document ID of the document that you want to set custom attributes for, by following the initial steps of the Download Files tutorial.
Step 1: Retrieve the Document’s Custom Attribute Values
Before updating a document’s custom attribute values, we recommend first checking the current custom attribute values. Call POST versions:batch-get using the project ID and document ID to retrieve the values that are currently assigned to the custom attributes. Note that only custom attribute that have been assigned a value will appear in the response.
curl -X POST \
https://developer.api.autodesk.com/bim360/docs/v1/projects/:project_id/versions:batch-get \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"urns": [
"urn:adsk.wipprod:fs.file:vf.AS3XD9MzQvu4MakMF-w7vQ?version=1"
]
}'
{
"results": [
{
"urn": "urn:adsk.wipprod:fs.file:vf.AS3XD9MzQvu4MakMF-w7vQ?version=1",
"itemUrn": "urn:adsk.wipprod:dm.lineage:AS3XD9MzQvu4MakMF-w7vQ",
"name": "Oct.pdf",
"title": "Bin Work",
"number": "E1001",
"createTime": "2019-04-18T03:33:36+0000",
"createUserId": "CGZ5PG7PZMAS",
"createUserName": "Tom Jerry",
"lastModifiedTime": "2019-04-18T03:33:36+0000",
"lastModifiedUserId": "CGZ5PG7PZMAS",
"lastModifiedUserName": "2019-04-18T03:33:36+0000",
"storageUrn": "urn:adsk.objects:os.object:wip.dm.prod/ c4a75bbc-24eb-41a3-a58b-48e51942222e.pdf",
"storageSize": 7164826,
"entityType": "SEED_FILE",
"revisionNumber": 1,
"processState": "PROCESSING_COMPLETE",
"approvalStatus": {
"label": "Approved w/ comments.",
"value": "approved"
},
"customAttributes": [
{
"id": 101,
"type": "string",
"name": "n1",
"value": "v1"
},
{
"id": 102,
"type": "array",
"name": "n2",
"value": "v2"
}
]
}
]
}
The response shows that values have been assigned to 2 custom attributes: a text field (string
) attribute and a drop-down (array
) attribute. To update the drop-down attribute, you need to call GET custom-attribute-definitions to find all the potential values (see next step).
Note that the response only displays custom attributes that have been assigned a value. To find the full list of the document’s custom attributes including custom attributes that have not been assigned a value you need to call GET custom-attribute-definitions (see next step).
Step 2: Retrieve the Document’s Custom Attribute Definitions
You need to carry out this step if you want to find the full list of the document’s custom attributes including custom attributes that have not been assigned a value, or you want to find the list of potential values for a drop-down list. Otherwise, you can skip to the next step.
Call GET custom-attribute-definitions using the project ID and folder ID to get a full list of the document’s custom attribute definitions including the list of potential values for a drop-down list.
curl -X GET \
https://developer.api.autodesk.com/bim360/docs/v1/projects/:project_id/folders/urn%3Aadsk.wipprod%3Afs.folder%3Aco.hGZHbcx2QHufgVMs_IDFlg/custom-attribute-definitions?offset=0&limit=50 \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '{
"urns": [
"urn:adsk.wipprod:fs.file:vf.AS3XD9MzQvu4MakMF-w7vQ?version=1"
]
}'
{
"results": [
{
"id": 101,
"name": "n1",
"type": "string"
},
{
"id": 102,
"name": "n2",
"type": "array",
"arrayValues": [
"v1",
"v2",
"v3"
]
},
{
"id": 103,
"name": "n3",
"type": "date"
},
{
"id": 104,
"name": "n4",
"type": "string"
},
{
"id": 105,
"name": "n5",
"type": "string"
}
],
"pagination": {
"limit": 50,
"offset": 0,
"totalResults": 5
}
}
The response shows the full list of the document’s custom attribute definitions, including custom attributes that have not yet been assigned values, as well as the potential values that you can assign to a drop-list attribute.
Step 3: Update the Document’s Custom Attribute Values
Call POST custom-attributes:batch-update using the project ID and document ID to set the custom attribute values.
Note the following:
- To clear a custom attribute value set the value to
null
. - If you are setting a date type, you need to use the ISO8601 format.
- If you are setting a drop-down type, you need to use one of the values listed in the
arrayValues
array (see the previous step).
curl -X POST \
https://developer.api.autodesk.com/bim360/docs/v1/projects/:project_id/versions/urn%3Aadsk.wipprod%3Afs.file%3Avf.AS3XD9MzQvu4MakMF-w7vQ%3Fversion%3D1/custom-attributes:batch-update \
-H 'Authorization: Bearer nFRJxzCD8OOUr7hzBwbr06D76zAT' \
-d '[
{
"id": 101,
"value": null
},
{
"id": 102,
"value": "v3"
},
{
"id": 103,
"value": "2020-04-05T00:00:00+0000"
},
{
"id": 105,
"value": "viewed"
}
]'
{
"results": [
{
"id": 102,
"name": "n2",
"type": "array",
"value": "v3"
},
{
"id": 103,
"name": "n3",
"type": "date",
"value": "2020-04-05T00:00:00+0000"
},
{
"id": 105,
"name": "n5",
"type": "string",
"value": "viewed"
}
]
}