changed-elements-get

changedElements.elements

element-id

changedElements.classIds

class-id

changedElements.modelIds

model-id

changedElements.parentIds

Array of changed elements' parent class Ids

changedElements.parentClassIds

Array of changed elements' operation codes

changedElements.opcodes

opcode

Array of changed elements' type of change

changedElements.type

type-of-change

Array of changed elements' array of changed properties

changedElements.properties

element-properties

Array of changed elements' array of old checksums for each property

changedElements.oldChecksums

checksum-list

Array of changed elements' array of new checksums for each property

changedElements.newChecksums

Changed Element Data

Changed Elements (get)

Element Id in hex string representation of an element.

Element Id

Model Id in hex string representation of a model.

Model Id

EC Class Id in hex string representation of an element.

Class Id

Operation code of change that occurred to an element. Delete: 9, Insert: 18, Update: 23.

Operation Code

Type of change that occurred to an element in bitflags. To be used with iModelJs 'TypeOfChange' class

Type Of Change

Array of properties that have changed in the element between the two changesets

Element Properties

Property Accessor Name of the property that changed on the element

changed-property

Changed Property

Array of checksums for the properties of an element

Checksum List

checksum

Checksum

tracking-response

Enabled flag for tracking.

boolean

Tracking (get)

changesets-get

changesetStatus

object

_links.self.href

string

_links.prev.href

_links.next.href

enable-tracking-body

enable

iModelId

iTwinId

Contains error information and an array of more specific errors.

DetailedError

One of a server-defined set of error codes.

code

A human-readable representation of the error.

message

target

details

Error

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

DetailedErrorResponse

error

Detailed Error Response

ErrorResponse

Error Response

# 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

Base Event eventType

base-event-eventType

enqueuedDateTime

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.

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

jobSucceeded

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.

Reference - Changed Elements | iTwin Platform

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

API references