Changed Elements API Tutorial

git clone https://github.com/iTwin/changed-elements-tutorial -b start

git clone https://github.com/iTwin/changed-elements-tutorial

PUT https://api.bentley.com/changedelements/tracking HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

{
"enable":true,
"iModelId":"myIModelId",
"iTwinId":"myITwinId"
}

GET https://api.bentley.com/changedelements/comparison?iTwinId=myITwinId&iModelId=myIModelId&startChangesetId=myStartChangesetId&endChangesetId=myEndChangesetId HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

{
"changedElements": {
  "elements":["0x30000000f69"],
  "classIds":["0x670"],
  "opcodes":[23],
  "modelIds":["0x20000000002"],
  "type":[1],
  "properties":[["UserLabel"]],
  "oldChecksums":[[1448094486]],
  "newChecksums":[[362149254]],
  "parentIds":["0"],
  "parentClassIds":["0"]
}
}

import { IModelApp, IModelConnection } from "@itwin/core-frontend";
import { IModelsClient, NamedVersion, NamedVersionState, toArray } from "@itwin/imodels-client-management";
import { Button, LabeledSelect, SelectOption } from "@itwin/itwinui-react";
import React, { useEffect, useState } from "react";
import { useCallback } from "react";
import { ChangedElementsFeatureOverrides } from "./ChangedElemensFeatureOverrides";
import { ChangedElementsClient } from "./ChangedElementsClient";
import "./ChangedElementsWidget.scss";

/**
* React hook to query named versions
* @param props 
* @returns 
*/
function useNamedVersions(props: { iModel: IModelConnection | undefined }) {
const [versions, setVersions] = useState<NamedVersion[]>();

// Load named versions that can be used for comparison
useEffect(() => {
  const loadChangesets = async () => {
    // Ensure we have a proper iModel with an iModel Id
    if (props.iModel?.iModelId === undefined) {
      console.error("iModel is not valid");
      return;
    }
    /** Uses the IModelClient to the request the Named Version of the IModel. Only selects name and changeset id.  Limited to top 10 Named Versions. */
    const client = new IModelsClient();
    const iModelIterator = client.namedVersions.getRepresentationList({
      urlParams: { $top: 10 },
      iModelId: props.iModel.iModelId,
      authorization: ChangedElementsClient.getAuthorization,
    });

    // Get the versions and set them to our state
    const namedVersions = (await toArray(iModelIterator)).filter((version) => version.state === NamedVersionState.Visible);
    setVersions(namedVersions);
  };
  // Call the asynchronous function to load named versions
  loadChangesets();
}, [props.iModel]);

return versions;
}

export interface ChangedElementsWidgetProps {
iModel: IModelConnection | undefined;
}

export function ChangedElementsWidget(props: ChangedElementsWidgetProps) {
// Named versions of the iModel
const versions = useNamedVersions(props);
// Named version selected in dropdown
const [selectedVersion, setSelectedVersion] = useState<NamedVersion | undefined>();

// Callback for when clicking the 'Visualize Changed Elements' button
const onVisualizeChangedElements = useCallback(async () => {
  // We will implement this later in the tutorial
}, []);

// Callback for when clicking the 'Enable Change Tracking' button
const onEnableTracking = useCallback(async () => {
   // We will implement this later in the tutorial
}, []);

const selectOptions: SelectOption<NamedVersion | undefined>[] = [];
if (versions) {
  for (const version of versions) {
    selectOptions.push({
      value: version,
      label: version.name ?? "Unknown Named Version"
    });
  }
}

// On react select change set the new selected version
const onReactSelectChange = (option: any) => {
  setSelectedVersion(option);
};

return (
  <div className="widget-container">
    <div className="widget-label">Select Named Version:</div>
    <LabeledSelect
      value={selectedVersion}
      options={selectOptions}
      onChange={onReactSelectChange} />
    <Button className={"widget-button"} onClick={onVisualizeChangedElements}>
      Visualize Changed Elements
    </Button>
    <Button className={"widget-button"} onClick={onEnableTracking}>
      Enable Change Tracking
    </Button>
  </div>
);
}

.widget-container {
margin: 8px;
}

.widget-label {
color: white;
font-size: 14px;
}

.widget-button {
width: 100%;
}

import {
AbstractWidgetProps,
StagePanelLocation,
StagePanelSection,
UiItemsProvider,
} from '@bentley/ui-abstract';
import { UiFramework } from '@bentley/ui-framework';
import * as React from 'react';
import { ChangedElementsWidget } from './ChangedElementsWidget';

export class ChangedElementsUiProvider implements UiItemsProvider {
public readonly id = 'ChangedElementsProviderId';

public provideWidgets(
  stageId: string,
  stageUsage: string,
  location: StagePanelLocation,
  section?: StagePanelSection
): ReadonlyArray<AbstractWidgetProps> {

  const widgets: AbstractWidgetProps[] = [];
  if (
    location === StagePanelLocation.Right &&
    section === StagePanelSection.Start
  ) {
    const changedElementsWidget: AbstractWidgetProps = {
      id: 'ChangedElementsWidget',
      label: 'Changed Elements',
      getWidgetContent() {
        return (
          <ChangedElementsWidget iModel={UiFramework.getIModelConnection()} />
        );
      },
    };

    widgets.push(changedElementsWidget);
  }

  return widgets;
}
}

import { ChangedElementsUiProvider } from "./ChangedElementsUiProvider";

<Viewer
contextId={contextId}
iModelId={iModelId}
authConfig={{ config: authConfig }}
onIModelAppInit={onIModelAppInit}
backend={{ buddiRegion: 103 }}
uiProviders={[new ChangedElementsUiProvider()]}
/>

import { ChangedElements } from "@itwin/core-common";
import { IModelApp, IModelConnection } from "@itwin/core-frontend";
import { Authorization } from "@itwin/imodels-client-management";

/**
* Class for using the Changed Elements API
*/
export class ChangedElementsClient {
/**
 * Get base URL for changed elements API
 * @returns URL for changed elements API
 */
public getUrl() {
  return "https://api.bentley.com/changedelements";
}

/**
 * Function to form the URL for the comparison operation of changed elements API
 * @param iModelId iModel Id to query for
 * @param iTwinId iTwin Id of the iModel
 * @param startChangesetId Start changeset for comparison data
 * @param endChangesetId End changeset for comparison data
 * @returns Url for querying changed elements from the changed elements API
 */
public getComparisonOperationUrl(
  iModelId: string,
  iTwinId: string,
  startChangesetId: string,
  endChangesetId: string
) {
  return this.getUrl() +
    "/comparison?iModelId=" + iModelId +
    "&iTwinId=" + iTwinId +
    "&startChangesetId=" + startChangesetId +
    "&endChangesetId=" + endChangesetId;
}

/**
 * Function to form the URL for the enable change tracking operation of changed elements API
 * @returns Url for enabling/disabling change tracking
 */
public getEnableChangeTrackingUrl() {
  return this.getUrl() + "/tracking"
}

/**
 * Get authorization for getting named versions
 * @returns 
 */
public static async getAuthorization(): Promise<Authorization> {
  if (!IModelApp.authorizationClient)
    throw new Error("AuthorizationClient is not defined. Most likely IModelApp.startup was not called yet.");

  const token = await IModelApp.authorizationClient.getAccessToken();
  const parts = token.split(" ");
  return parts.length === 2
    ? { scheme: parts[0], token: parts[1] }
    : { scheme: "Bearer", token };
}

/**
 * Gets the changed elements between two changesets using the changed elements API
 * This results in a GET request to the comparison endpoint
 * @param iModel iModel to test
 * @param startChangesetId Start changeset Id
 * @param endChangesetId End changeset Id
 * @returns ChangedElements object or undefined
 */
public async getComparison(
  iModel: IModelConnection,
  startChangesetId: string,
  endChangesetId: string
): Promise<ChangedElements | undefined> {
  // Parse out iModel Id and iTwin Id
  const iModelId = iModel.iModelId;
  const iTwinId = iModel.iTwinId;
  // Ensure they are properly defined
  if (iModelId === undefined || iTwinId === undefined) {
    throw new Error("IModel is not properly defined");
  }

  // Get the request URL for the comparison operation
  const url: string = this.getComparisonOperationUrl(iModelId, iTwinId, startChangesetId, endChangesetId);
  // Options for the request
  const authorization = await ChangedElementsClient.getAuthorization()
  const options = {
    method: "GET",
    headers: {
      Authorization: authorization.scheme + " " + authorization.token,
      Accept: "application/vnd.bentley.itwin-platform.v1+json",
    },
  };
  try {
    // Execute the request
    const response = await fetch(url, options);
    // Ensure we got a proper response
    const body = await response.json();
    if (response.status === 200 && body?.changedElements !== undefined) {
      // If so, cast the changedElements object of the body as a ChangedElements type
      return body.changedElements as ChangedElements;
    }
    // Something went wrong, log it to console
    console.error("Could not get changed elements. Status: " + response.status + ". Body: " + response.body);
  } catch (e) {
    console.error("Error obtaining changed elements: " + e);
  }

  // We did not get a proper response, return undefined
  return undefined;
}

/**
 * Enable or disable change tracking for an iModel
 * This will cause the iModel to be monitored for named versions
 * Whenever a named version gets created, the changed elements API will process the changesets
 * so that a comparison operation can be made against the new named versions
 * @param iModel IModel to track change for
 * @param value true for enabling, false for disabling
 * @returns true if successful, false if failed
 */
public async enableChangeTracking(
  iModel: IModelConnection,
  value: boolean,
): Promise<boolean> {
  // Parse out iModel Id and iTwin Id
  const iModelId = iModel.iModelId;
  const iTwinId = iModel.iTwinId;
  // Ensure they are properly defined
  if (iModelId === undefined || iTwinId === undefined) {
    throw new Error("IModel is not properly defined");
  }

  // Get the request URL for the comparison operation
  const url: string = this.getEnableChangeTrackingUrl();

  const authorization = await ChangedElementsClient.getAuthorization()
  // Options for the request
  const options = {
    method: "PUT",
    headers: {
      Authorization: authorization.scheme + " " + authorization.token,
      Accept: "application/vnd.bentley.itwin-platform.v1+json",
    },
    body: JSON.stringify({
      enable: value,
      iModelId,
      iTwinId,
    })
  };
  try {
    // Execute the request
    const response = await fetch(url, options);
    // Ensure we get a proper response
    if (response.status === 202) {
      return true;
    }
    // Something went wrong, log it to console
    console.error("Could not enable change tracking. Status: " + response.status + ". Body: " + response.body);
  } catch (e) {
    console.error("Error change tracking: " + e);
  }

  // We did not get a proper response, return undefined
  return false;
}
}

import { ChangedElementsClient } from "./ChangedElementsClient"; 

// Callback for when clicking the 'Enable Change Tracking' button
const onEnableTracking = useCallback(async () => {
const iModel = props.iModel;
// Ensure our iModel is defined
if (iModel) {
  // Create a changed elements client object
  const client = new ChangedElementsClient();
  // Enable change tracking for the iModel
  await client.enableChangeTracking(iModel, true);
}
}, [props.iModel]);

// Callback for when clicking the 'Visualize Changed Elements' button
const onVisualizeChangedElements = useCallback(async () => {
  const iModel = props.iModel;
  if (iModel === undefined || iModel.changeset.id === undefined) {
    console.error("iModel is not valid");
    return;
  }
  if (selectedVersion?.changesetId === undefined || selectedVersion.changesetId == null) {
    console.error("Selected version is not defined");
    return;
  }
  const client = new ChangedElementsClient();
  const endChangesetId = iModel.changeset.id;
  const startChangesetId = selectedVersion.changesetId;
  const changedElements = await client.getComparison(
    iModel,
    startChangesetId,
    endChangesetId
  );
  // Log the results to console to inspect them
  console.log(changedElements);
  const viewport = IModelApp.viewManager.selectedView;
  if (changedElements && viewport) {
    // Emphasize the changed elements in the view
    EmphasizeElements.getOrCreate(viewport).emphasizeElements(
      changedElements.elements,
      viewport
    );
  }
}, [selectedVersion, props.iModel]);

import { DbOpcode, Id64String } from "@itwin/core-bentley";
import { ChangedElements, FeatureAppearance } from "@itwin/core-common";
import { FeatureOverrideProvider, FeatureSymbology, Viewport } from "@itwin/core-frontend";

/**
* Feature Override Provider to visualize changed elements and colorize them
* in the viewport
*/
export class ChangedElementsFeatureOverrides implements FeatureOverrideProvider {
// Array of inserted element Ids
private _insertedElements: Id64String[] = [];
// Array of updated element Ids
private _updatedElements: Id64String[] = [];

/**
 * Constructor
 * @param changedElements Changed Elements to visualize
 */
public constructor(changedElements: ChangedElements) {
  // Go over all changed elements array, all arrays are guaranteed to have same size
  for (let i = 0; i < changedElements.elements.length; ++i) {
    // Element Id of the changed element
    const elementId: Id64String = changedElements.elements[i];
    // Operation code of the changed element
    const opcode: DbOpcode = changedElements.opcodes[i];
    // Add the element Id to the proper list
    switch (opcode) {
      case DbOpcode.Delete:
        // Deleted elements do not exist in the current version of the iModel
        // Displaying non-iModel elements in the same view is out of scope for this tutorial
        break;
      case DbOpcode.Update:
        this._updatedElements.push(elementId);
        break;
      case DbOpcode.Insert:
        this._insertedElements.push(elementId);
        break;
    }
  }
}

/**
 * Adds the colorization and emphasis of the elements we care about
 * @param overrides Overrides to be updated with our changed elements
 * @param viewport Viewport we are overriding features on
 */
public addFeatureOverrides(overrides: FeatureSymbology.Overrides, viewport: Viewport): void {
  // Create a default appearance for non-changed elements, set it to transparent light gray
  const defaultAppearance = FeatureAppearance.fromJSON({
    rgb: {r: 200, g: 200, b: 200},
    transparency: 0.9,
    // Make unchanged elements non-locatable
    // This is to allow selecting changed elements that are behind unchanged elements in the view
    nonLocatable: true,
  });
  // Override the default coloring for all other elements
  overrides.setDefaultOverrides(defaultAppearance);

  // Create an appearance with the color green for inserted elements and emphasize them
  const insertedAppearance = FeatureAppearance.fromJSON({
    rgb: {r: 0, g: 255, b: 0},
    emphasized: true,
  });
  // Override the inserted elements with the appearance
  this._insertedElements.forEach((elementId: string) => {
    overrides.override({
      elementId,
      appearance: insertedAppearance
    });
  });

  // Create an appearance with the color blue for updated elements
  const updatedAppearance = FeatureAppearance.fromJSON({
    rgb: {r: 0, g: 0, b: 255},
    emphasized: true
  });
  // Override the updated elements with the appearance
  this._updatedElements.forEach((elementId: string) => {
    overrides.override({
      elementId,
      appearance: updatedAppearance
    });
  });
}
}

// Updated callback for when clicking the 'Visualize Changed Elements' button
const onVisualizeChangedElements = useCallback(async () => {
  const iModel = props.iModel;
  if (iModel === undefined || iModel.changeset.id === undefined) {
    console.error("iModel is not valid");
    return;
  }
  if (selectedVersion?.changesetId === undefined || selectedVersion.changesetId == null) {
    console.error("Selected version is not defined");
    return;
  }
  const client = new ChangedElementsClient();
  const endChangesetId = iModel.changeset.id;
  const startChangesetId = selectedVersion.changesetId;
  const changedElements = await client.getComparison(
    iModel,
    startChangesetId,
    endChangesetId
  );
  // Log the results to console to inspect them
  console.log(changedElements);

  const viewport = IModelApp.viewManager.selectedView;
  if (changedElements && viewport) {
    // Ensure we are not currently visualizing changed elements
    const oldProvider = viewport.findFeatureOverrideProviderOfType(ChangedElementsFeatureOverrides);
    if (oldProvider) {
      // If we are, drop the override provider so that we start with a clean viewport
      viewport.dropFeatureOverrideProvider(oldProvider);
    }
    // Create our feature override provider object
    const overrideProvider = new ChangedElementsFeatureOverrides(changedElements);
    // Add it to the viewport
    viewport.addFeatureOverrideProvider(overrideProvider);
  }
}, [selectedVersion, props.iModel]);