Changed Elements V3 API Overview

Introduction

The Changed Elements API helps you identify the differences in an iModel over a range of changesets. This API generates a configurable diff report that highlights the changes that occurred in the iModel, allowing developers to integrate the results into their applications. For example, they can create color-coded visualizations to represent these changes.

Key Features

• Flexible change strategies: Choose from optimized output formats for 3D visualization, detailed auditing, or change categorization.
• Structured results: Get JSON reports highlighting deleted, added, and modified elements.

Use Cases

Comparing changes in engineering data is essential for workflows in construction, architecture, engineering, and facilities management. Enhance your applications with change timelines and detailed analysis for better visualization and decision-making.

• Change management and version control: Integrate change comparison results to track and compare modifications made by multiple stakeholders, ensuring the integrity of the iTwin.
• Risk mitigation and error prevention: Identify discrepancies between different versions of iModels to prevent costly errors and reduce rework and delays.
• Effective collaboration and communication: Create color-coded visualizations to highlight changes, allowing team members to understand modifications without checking individual files, thereby saving days of manual effort.
• Ensuring compliance and deliverables quality control: Comparing various iModel versions helps verify that updates comply with standards and prevents disputes among stakeholders by providing clear evidence of changes.

Workflow

To retrieve changes between the specified range of changesets, follow these steps:

1. Create diff job: Use the POST /diff endpoint to create a diff job by specifying the iModel, changeset range, and strategy.
2. Check job status: Use the GET /diff/{id} endpoint to monitor job progress.
3. Query job history: Use the GET /diff endpoint to view all diff jobs for an iModel.

The diagram below illustrates the workflow:

Note: Depending on the range and size of the changesets, jobs may take several minutes to complete. Currently, you must poll the status endpoint to check for completion. Support for iTwin event notifications is planned for a future release.

Configuration

The API supports the diffing strategies below. Each strategy controls the format of the output, performance of processing, and verbosity of results.

Basic Strategy

---

Simplified results optimized for viewer applications. Contains element ids in big integer format, class full names and operation type:

[
  {
    "id": "9800022",
    "classFullName": "MySchema:MyClass",
    "operation": "Inserted"
  }
  // ...
]

Note: The operation field returns one of the following values: Inserted, Updated, or Deleted.

VersionCompare Strategy

---

Provides the same result format as the Changed Elements V2 API for backward compatibility. Matches the ChangedElements interface:

{
  "changedElements": {
    "elements": ["0x1", "0x2"],
    "classIds": ["0xc1", "0xc2"],
    "modelIds": ["0xa1", "0xa2"],
    "opcodes": [9, 18],
    "type": [1, 2],
    "properties": [["PropA", "PropB"], ["PropC"]],
    "parentIds": ["0xe", "0xf"],
    "parentClassIds": ["0xce", "0xcf"]
  }
}

Full Strategy

---

Combines all changes found in the changeset range while excluding geometry streams. Provides very verbose results that encapsulate everything that changed in the iModel. This format uses the core-backend definition of ChangedECInstance:

[
  {
    "ECInstanceId": "0x1",
    "ECClassId": "0xc1",
    "$meta": {
      "op": "Updated"
      // ...
    }
    // ...
  }
]

Tutorial

For more information on how to use the API, please check the Changed Elements API V3 Tutorial