Task 1 - Retrieve Differences of an Element Group
In this tutorial, you will learn how to use the Diff API to query the changes between a specified version and the latest version of an ElementGroup.
The Diff API allows you to retrieve the differences from a version against the latest of an ElementGroup and its elements. You can also paginate through the property differences of a particular element.
Step 1 - Retrieve Element Differences of an ElementGroup By Version From the Latest
The following steps demonstrate how you can run the diffElementGroupByVersionWithLatest query to get the changes in an ElementGroup after a particular version.
- Enter the following query in the Query Pane of the AEC Data Model Explorer.
Query
query diffElementGroupByVersionWithLatest($elementGroupId: ID!, $startVersion: Int, $changeFilter:[DifferenceType] $pagination: PaginationInput) { diffElementGroupByVersionWithLatest(elementGroupId: $elementGroupId, startVersion: $startVersion, changeFilter:$changeFilter, pagination: $pagination) { pagination{ pageSize cursor } result{ type element{ id name } differences { pagination{ cursor pageSize } results{ type oldItem{ name value } item{ name value } } } } } }Show More - In the query variable pane enter the following values, replacing the placeholders for elementGroupId and startVersion.
The elementGroupId will be the id of the particular elementGroup you are interested in, and the startVersion will be the version of that elementGroup that you want to see the changes after against the latest.
Query Variables
{ "elementGroupId": "{{YOUR_ELEMENT_GROUP_ID}}", "startVersion" : {{YOUR_START_VERSION}}, "changeFilter": ["REMOVAL", "ADDITION", "MODIFICATION"], "pagination": { "limit": 100 } }Show MoreThe change filter can also be adjusted to query what kind of changes you are interested in for elements. The supported types of changes are: REMOVAL, ADDITION and MODIFICATION.
Supported Change Filter Types
Type Filtered Change ADDITION Shows elements that have been added MODIFICATION Shows elements that have been modified REMOVAL Shows elements that have been removed Note: Not specifying a changeFilter, will retrieve all the element differences.
- Click Play. The response should be similar to the following code-block:
Response
{ "data": { "diffElementGroupByVersionWithLatest": { "pagination": { "pageSize": 73, "cursor": null }, "result": [ { "type": "MODIFICATION", "element": { "id": "YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ35jNG5FNXNFRlRrbVB5ODM0cnlOTFN3XzIwOTEyYg", "name": "Concrete Slab 6\"" }, "differences": { "pagination": { "cursor": null, "pageSize": 3 }, "results": [ { "type": "MODIFICATION", "oldItem": { "name": "Volume", "value": 178.76503887821477 }, "item": { "name": "Volume", "value": 187.54936329898482 } }, { "type": "MODIFICATION", "oldItem": { "name": "Perimeter", "value": 189.64061013477095 }, "item": { "name": "Perimeter", "value": 207.41600094799753 } }, { "type": "MODIFICATION", "oldItem": { "name": "Area", "value": 1172.998942770438 }, "item": { "name": "Area", "value": 1230.6388667912388 } } ] } }, { "type": "ADDITION", "element": { "id": "YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ35jNG5FNXNFRlRrbVB5ODM0cnlOTFN3XzI4NzkxOQ", "name": "" }, "differences": { "pagination": null, "results": null } }, { "type": "REMOVAL", "element": { "id": "YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ35jNG5FNXNFRlRrbVB5ODM0cnlOTFN3XzIwZGRkYg", "name": "Model Lines" }, "differences": { "pagination": null, "results": null } } ] } } }Show More
Step 2 - Retrieve and Paginate Property Differences of an Element By Version From the Latest
The following steps demonstrate how you can run the diffElementByVersionWithLatest query to retrieve and paginate through the property differences of a particular element you are interested in.
- Enter the following query in the Query Pane of the AEC Data Model Explorer.
Query
query diffElementByVersionWithLatest($elementId: ID!, $startElementGroupVersion: Int, $pagination: PaginationInput) { diffElementByVersionWithLatest(elementId: $elementId, startElementGroupVersion: $startElementGroupVersion) { type element{ id name } differences(pagination: $pagination) { pagination{ cursor pageSize } results{ type oldItem{ name value } item{ name value } } } } }Show More - In the query variable pane enter the following values, replacing the placeholders for elementId and startElementGroupVersion.
The elementId can be retrieved from Step 1 for the particular element whose property differences you are interested in, the startElementGroupVersion will be the same as the startVersion in Step 1.
Query Variables
{ "elementId": "{{YOUR_ELEMENT_ID}}", "startElementGroupVersion" : {{YOUR_START_VERSION}}, "pagination": { "limit": 3 } } - Click Play. The response should be similar to the following code-block:
Response
{ "data": { "diffElementByVersionWithLatest": { "type": "MODIFICATION", "element": { "id": "YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ35jNG5FNXNFRlRrbVB5ODM0cnlOTFN3XzI2MTEwMA", "name": "Commercial/Retail 76" }, "differences": { "pagination": { "cursor": "Y3Vyc34zfjM", "pageSize": 3 }, "results": [ { "type": "MODIFICATION", "oldItem": { "name": "Room Name", "value": "Commercial/Retail" }, "item": { "name": "Room Name", "value": "Unoccupied" } }, { "type": "MODIFICATION", "oldItem": { "name": "Room Number", "value": "108" }, "item": { "name": "Room Number", "value": "Unoccupied" } }, { "type": "MODIFICATION", "oldItem": { "name": "Area", "value": 213.99606898281348 }, "item": { "name": "Area", "value": null } } ] } } } }Show MoreThe cursor provided can then be used to paginate through the property differences in subsequent queries.