Request

Response

    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

    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"
          ]
      }'
    
    Show More
    {
        "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"
                    }
                ]
            }
        ]
    }
    
    Show More

    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"
          ]
      }'
    
    Show More
    {
        "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
        }
    }
    
    Show More

    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"
          }
      ]'
    
    Show More
    {
        "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"
            }
        ]
    }
    
    Show More