# Changed Elements

The Changed Elements API provides consumers with the elements that have changed in an iModel between two changesets. This API has four operations:

1. Enable Change Tracking
2. Get Change Tracking
3. Get Comparison
4. Get Changesets

Before obtaining a comparison, it is necessary to enable change tracking of an iModel. This means that the API will be listening to the following events:
1. New Named Version Created
2. Changeset Group Completed

When any of those events trigger, the API will process the new changes and store a summary of all the elements that have changed.

After tracking is enabled and the iModel is processed, the comparison endpoint may be used to query for a summary of changed elements between any two given `ChangeSets`.

changed-elements

This information is included in every event the webhook will receive.

base-event

content

object

Base Event eventType

base-event-eventType

enqueuedDateTime

string

iTwinId

messageId

webhookId

Base Event

Event that gets triggered when a changed element comparison job is complete

changedElements.jobCompleted.v1-event

Globally Unique Identifier of the changed element comparison job.

jobId

Globally Unique Identifier of the iModel.

iModelId

Boolean flag indicating success or failure of the changed element comparison job.

jobSucceeded

boolean

changedElements.jobCompleted.v1

# Changed Elements

The Changed Elements API provides consumers with the elements that have changed in an iModel between two changesets.

Operations Include:

- [Create Comparison Job](operations/create-comparison-job/) Creates a comparison. The comparison will be queued when first created and will progress to completion. When completed, it will contain all the comparison info. Use [Get Comparison Job](operations/get-comparison-job/) for information on comparison.

- [Delete Comparison Job](operations/delete-comparison-job/) Deletes all stored data relating to comparison. 

- [Get Comparison Job](operations/get-comparison-job/) Gets comparison based on the job id. The comparison will contain the job status, start and end changeset ids, and comparison progress. If the comparison is complete, the response will also include a href to the comparison information.


changed-elements-v2

---

Enables or disables change tracking for an iModel. This operation requires you to pass the enable value, iModel Id and project Id in the body of the request as a JSON object.

Once enabled, when creating a new named version of an iModel, or when a changeset group completes, the changesets are processed to find all changed elements. You can then request this data using the `GET /comparison` operation.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `changedelements:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

enable-change-tracking

The body should contain a JSON object with the enable value, iModel Id and project Id.

OAuth access token with scope `changedelements:modify`

Authorization

Setting to `application/vnd.bentley.itwin-platform.v1+json` is recommended.

Accept

default

Change tracking for iModel was updated successfully.

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

HeaderNotFound

application/json;InvalidAuthorizationScheme

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

The user has insufficient permissions for the requested operation.

This response indicates that disabling change tracking is not possible because the iModel is not valid.

A URL parameter was malformed or the body of the request is invalid.

This response indicates that the user has sent too many requests in a given amount of time.

The number of requests exceeds the rate-limit for the client subscription.

retry-after

---

Get a list of processing statuses for changesets in an iModel. This list allows you to inspect which changesets are ready to be used to generate a comparison summary.

---

get-changesets

Amount of changesets to return in a single result. Optional.

$top

Amount of changesets to skip when returning results. Optional.

$skip

Id of the iTwin where the iModel resides.

Id of the iModel to query for status of changesets.

OAuth access token with scope `changedelements:read`

This response indicates that provided iTwin or iModel was not found.

This response indicates that a URL parameter was malformed or there are missing required parameters.

---

Obtains which elements have changed in the iModel between the given start and end changesets.

This information will only be available after change tracking has been enabled and the processing operation completes.

### Understanding Change

The comparison returns a [ChangedElements](https://www.itwinjs.org/reference/core-common/entities/changedelements/) object. This interface contains different arrays of the same size. Each element is specified by a single index in all arrays. Some of the relevant arrays to understand what changes occurred to an element are listed below:

**opcodes**: Contains the operation codes that tells us if the element was inserted, updated, or deleted in the change. See [DbOpcode](https://www.itwinjs.org/reference/core-bentley/besqlite/dbopcode/) for more information. The appropriate values are listed below:

| Opcode | Description |
|:------:|-----------|
| 9 | Element was deleted |
| 23 | Element was modified |
| 18 | Element was inserted |

&nbsp;
&nbsp;

**type**: Contains the type of change that occurred to the element. This number is a bit-flag and can be used to know whether the element had property changes, geometric changes, placement changes, indirect changes, and hidden property changes. See [TypeOfChange](https://www.itwinjs.org/reference/core-common/entities/typeofchange/) for more information. Below is a table with the values and their meaning:

| Type | Value | Description |
|------|:-----:|-------------|
| Property | 1 | A property in the element changed |
| Geometry | 2 | The geometry of the element changed |
| Placement | 4 | The placement of the element changed. This means that the element changed its volume, origin or rotation. |
| Indirect | 8 | Indirect change occurred to this element by a related instance that provides properties for it |
| Hidden | 16 | Hidden properties of the element changed |

### Authentication

Requires `Authorization` header with valid Bearer token for scope `changedelements:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-comparison

[Deprecated] Id of the iTwin the iModel resides in.

projectId

Changeset Id for the beginning of the comparison range.

startChangesetId

Changeset Id for the ending of the comparison range.

endChangesetId

This response indicates that provided comparison results are not ready or unexistent.

A URL parameter was malformed or there are missing required parameters.

---

Get tracking information about an iModel.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `changedelements:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-tracking

Id of the iModel to query tracking information.

Samples - Changed Elements | iTwin Platform

Compare ChangedElements between Version and colorizing them by operation.

ecc2e721-1760-47b7-b3db-4647a84c2cfa

This tutorial will teach you how to use the Changed Elements API to visualize change in your iTwin Application