February 10, 2020

Work with Custom Attributes of BIM 360 Issue by API

Follow @Xiaodong Liang

In BIM 360, we can define custom attributes for issue. Four types are available: string, numeric, paragraph and dropdown list. In dropdown list, we define the options.

6

 

Once the definitions are available, apply them with Issue Type. In default, we apply the attributes with all types. We can also apply specific attributes with specific issue types. When an issue is created, it inherits generic custom attributes of [All Issue Types], and also the specific attributes of its own.

4

 

 

When an issue is created, it will show up the fields of custom attributes which are available with the issue type (both inherited attributes and specific attributes)

7

GET:issue-attribute-definitions returns the array of definitions. It includes the basic information of an attribute. It also includes the permission of the logged user (authorized with 3 legged token) on what actions and which data the user can execute. e.g. the son response corresponds to the attributes defined in the UI above, yet indicating the permissions of the logged user (some data are removed for succinct). For dropdown list, the options are defined as pair of value & id. Value is what is visible in BIM 360 UI, while id is like a GUID which is used by API, in order to uniquely differentiate the options.

[
        {
            "id": "1bb89548-8495-49d0-8d3b-ee497c5a2c12",
            "containerId": "2eb58c29-ecab-4770-94bc-24307832f284",
            "title": "demo string attribute",
            "description": "This is a demo string attribute",
            "dataType": "text",
            "isRequiredDefault": false,
            "<other data>":"<other data...... >"
            "permittedActions": [
                "edit",
                "delete"
            ],
            "permittedAttributes": [
                "title",
                "description",
                "isRequiredDefault",
                "metadata"
            ]
        },
        {
            "id": "0fd54b00-052f-499a-a75a-b109dacfafeb",
            "containerId": "2eb58c29-ecab-4770-94bc-24307832f284",
            "title": "demo numeric attribute",
            "description": "This is a demo numeric attribute",
            "dataType": "numeric",
            "isRequiredDefault": false,
            "<other data>":"<other data...... >"
            "permittedActions": [
                "edit",
                "delete"
            ],
            "permittedAttributes": [
                "title",
                "description",
                "isRequiredDefault",
                "metadata"
            ]
        },
        {
            "id": "b1309f6e-59db-4440-b3fd-b53d0caecb29",
            "containerId": "2eb58c29-ecab-4770-94bc-24307832f284",
            "title": "demo paragraph attribute",
            "description": "This is demo paragraph attribute",
            "dataType": "paragraph",
            "isRequiredDefault": false,
            "metadata": {},
            "<other data>":"<other data...... >"
            "deletedAt": null,
            "permittedActions": [
                "edit",
                "delete"
            ],
            "permittedAttributes": [
                "title",
                "description",
                "isRequiredDefault",
                "metadata"
            ]
        },
        {
            "id": "703cec73-b6d3-4f8d-971c-a72f37f783b6",
            "containerId": "2eb58c29-ecab-4770-94bc-24307832f284",
            "title": "demo dropdown list attribute",
            "description": "This is demo dropdown list attribute",
            "dataType": "list",
            "isRequiredDefault": false,
            "metadata": {
                "list": {
                    "options": [
                        {
                            "value": "room",
                            "id": "021ffa0a-d0c6-4a02-8e08-f17c4b1e23ae"
                        },
                        {
                            "value": "floor",
                            "id": "51081205-3403-4e94-8219-6a90b2e6c405"
                        },
                        {
                            "value": "wall",
                            "id": "6925eebb-7b62-4492-ac25-c6dbffb93460"
                        },
                        {
                            "value": "window",
                            "id": "667829b7-cc40-4056-9d37-f80cb1463678"
                        }
                    ]
                }
            },
            "<other data>":"<other data...... >"
            "permittedActions": [
                "edit",
                "delete"
            ],
            "permittedAttributes": [
                "title",
                "description",
                "isRequiredDefault",
                "metadata"
            ]
        },
        {
            "id": "147aba91-df11-4dbb-9d75-d590cc572e6a",
            "containerId": "2eb58c29-ecab-4770-94bc-24307832f284",
            "title": "demo string attributes for specific issue type",
            "description": "This is demo string attributes for specific issue type",
            "dataType": "text",
            "isRequiredDefault": false,
            "metadata": {},
            "<other data>":"<other data...... >"
            "permittedActions": [
                "edit",
                "delete"
            ],
            "permittedAttributes": [
                "title",
                "description",
                "isRequiredDefault",
                "metadata"
            ]
        }
    ]

GET:issue-attribute-mappings returns the list of mapping between issue types and custom attribute definitions. IF it is an attribute for all issue types, mappedItemId = container id of issue, mappedItemType = ‘container’. If it is an attribute for specific issue type/subtype, mappedItemId = issue type id, mappedItemType = ‘issueType’ or ‘issueSubtype’. e.g. in the two demo mapping, one attribute is for issue types, the other is for one issue type only. By GET: ng-issue-types, we can know it is Safety. 

[
        {
            "id": "0beb01ae-1c79-4120-bfaa-aa66b7a943de",
            "containerId": "<issue container id>",
            "attributeDefinitionId": "1bb89548-8495-49d0-8d3b-ee497c5a2c12",
            "mappedItemId": "<issue container id>,
            "mappedItemType": "container",
            "<other data>":"<other data...... >"
            "permittedActions": [
                "change_order",
                "edit",
                "delete"
            ],
            "permittedAttributes": [
                "isRequired"
            ]
        }, 
        {
            "id": "436ea483-86a5-4241-a37e-f1af2ed0c394",
            "containerId": "<issue container id>",
            "attributeDefinitionId": "147aba91-df11-4dbb-9d75-d590cc572e6a",
            "mappedItemId": "<issue type id>",
            "mappedItemType": "issueSubtype",
             "<other data>":"<other data...... >" 
            "permittedActions": [
                "change_order",
                "edit",
                "delete"
            ],
            "permittedAttributes": [
                "isRequired"
            ]
        }
] 

GET:Issues or GET:Issues/:Id returns the custom attributes. For string, numeric, paragraph, it tells the direct data. While for dropdown list, it tells option name and option definition GUID. Next, by the result of GET:issue-attribute-definitions, we can get the exact value of the options with their ids.

With POST:Issues, or PATCH:Issues/:id, we can create issue with custom attribute values, or update issue with updated custom attributes values. The payload format is same to the response of getting issue. The only trick is to input dropdown (list) option definition id as its value, instead of the meaningful string. 

{
    "data": {
      "type": "quality_issues",
      "id": "6eb89c9c-f293-4db4-a5e2-fef6ebd8010f",
      "attributes": {
          "custom_attributes": [ 
                {
                    "id": "0fd54b00-052f-499a-a75a-b109dacfafeb",
                    "title": "demo numeric attribute",
                    "type": "numeric",
                    "value": "12345678"
                },
                {
                    "id": "1bb89548-8495-49d0-8d3b-ee497c5a2c12",
                    "title": "demo string attribute",
                    "type": "text",
                    "value": "just a  text ...."
                },
                {
                    "id": "703cec73-b6d3-4f8d-971c-a72f37f783b6",
                    "title": "demo dropdown list attribute",
                    "type": "list",
                    "value": "021ffa0a-d0c6-4a02-8e08-f17c4b1e23ae"
                },
                {
                    "id": "b1309f6e-59db-4440-b3fd-b53d0caecb29",
                    "title": "demo paragraph attribute",
                    "type": "paragraph",
                    "value": "paragraph demo ....."
                }
            ]
      }
    }
  }

 

 

Posted by

Xiaodong Liang has been with Autodesk since 2007, focusing on providing programming support, consulting, training and evangelism to external developers. He started his career China and now lives in Beijing, China. Xiaodong is currently a developer consultant in the team Developer Technical Services (DevTech), the worldwide team of API gurus providing technical services through the Autodesk Developer Network. He supports...

Related Posts