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]);