Transforming an iModel - Filtering data by a saved view

Introduction

The Transformations API allows the consumer to transform existing iModel's data into a different iModel. In this tutorial, you will explore how to create a filtered iModel from an existing iModel using a saved view as a filter.

Info

Skill level:

Basic

Duration:

10 minutes

1. Set up your environment

To do this tutorial, it is recommended that you do the Get started with iTwin Platform first. This tutorial expects that you have a registered application as shown in the quick start tutorial and have an iModel with a created saved view.

1.1. Tools

Postman

You need a tool that allows you to send HTTP requests. You can use Postman for it, but any other application is sufficient as well.

Postman

Get

2. Prepare target iModel

Before running the transformation, you first need to have an iModel where transformed data will be written. Create an empty iModel which will be used as the target for your transformation.

Fill in this value before sending the request:

iTwinId - ID of the iTwin where the target iModel should be created.

Example HTTP request for Create iModel Operation

http

POST https://api.bentley.com/imodels
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "My Target iModel",
  "iTwinId": "myTargetITwinId",
  }
}

Example result from Create iModel Operation

json

{
  "iModel": {
      "id": "myTargetIModelId",
      "displayName": "My Target iModel",
      "dataCenterLocation": "East US",
      "name": "My Target iModel",
      "state": "Initialized",
      "createdDateTime": "2025-09-01T14:50:33Z",
      "iTwinId": "myTargetITwinId",
      "isSecured": false,
      "_links": {
          "creator": {
              "href": "https://api.bentley.com/imodels/myTargetIModelId/users/myUseId"
          },
          "changesets": {
              "href": "https://api.bentley.com/imodels/myTargetIModelId/changesets"
          },
          "namedVersions": {
              "href": "https://api.bentley.com/imodels/myTargetIModelId/namedversions"
          },
          "upload": null,
          "complete": null
      }
  }
}

3. Create transformation configuration

Create a new transformation configuration that specifies the source and target iModels, along with the saved view to use as a filter.

Before sending the request, change these values to your own:

YOUR_ACCESS_TOKEN - Replace this value with your generated access token.
sourceIModelId - ID of the source iModel with data which is used as the data source.
targetIModelId - ID of the target iModel that was created in the previous step.
savedViewId - ID of the saved view in the source iModel which is used as a data filter.

Example HTTP request for Create Filter by Saved View Operation

http

POST https://api.bentley.com/transformations/configurations/filter-by-saved-view
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "name": "Demo configuration",
  "sourceIModelId": "mySourceIModelId",
  "targetIModelId": "myTargetIModelId",
  "changesetDescription": "Transformed iModel",
  "transformParameters": {
      "savedViewId": "mySavedViewId",
      "viewMode": "IncludeNewContent"
  }
}

Example result from the Create Filter by Saved View Operation

json

{
    "configuration": {
        "id": "myConfigurationId",
        "name": "Demo configuration",
        "changesetDescription": "Transformed iModel",
        "createdDateTime": "2025-09-01T14:51:33Z",
        "modifiedDateTime": "2025-09-01T14:52:33Z",
        "transformType": "FilterBySavedView",
        "transformParameters": {
            "_links": {
                "savedView": {
                    "href": "https://api.bentley.com/savedViews/mySavedViewId"
                }
            },
            "viewMode": "IncludeNewContent"
        },
        "_links": {
            "sourceIModel": {
                "href": "https://api.bentley.com/imodels/mySourceIModelId"
            },
            "targetIModel": {
                "href": "https://api.bentley.com/imodels/myTargetIModelId"
            }
        }
  }
}

4. Run the transformation

Now start the transformation for the configuration that was just created. You can achieve this by sending an HTTP request for the Create Transformation operation. This starts the background job which processes the iModels.

Before sending the request, these values need to be filled in:

YOUR_ACCESS_TOKEN - Replace this value with your generated access token.
configurationId - ID of the configuration created in the previous step.

Example HTTP request for Create Transformation Operation

http

POST https://api.bentley.com/transformations
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "configurationId": "myConfigurationId"
}

Example result from the Create Transformation Operation

json

{
  "transformation": {
      "id": "myTransformationId",
      "status": "Created",
      "errorMessage": "",
      "processedEntityCount": 0,
      "totalEntityCount": 100,
      "createdDateTime": "2025-09-01T15:00:00Z",
      "startedDateTime": "2025-09-01T15:00:00Z",
      "finishedDateTime": "2025-09-01T15:00:00Z",
      "sourceChangeset": {
          "id": "myEndChangesetId"
      },
      "_links": {
          "configuration": {
              "href": "https://api.bentley.com/transformations/configurations/myConfigurationId"
          }
      }
  }
}

5. Monitor transformation progress

Now you need to wait until your started transformation finishes. You can do this in two ways:

Setup webhook to react to transformations.jobCompleted.v1 event
Poll the transformation endpoint

For now, use the second approach, which means that you have to send Get Transformation HTTP requests to get the latest status and progress of the transformation. Request needs to be repeated until the transformation has Succeeded status.

Before sending the request, replace myTransformationId in the request path with the created transformation ID from the previous step.

Example HTTP request for Get Transformation Operation

http

GET https://api.bentley.com/transformations/myTransformationId
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer YOUR_ACCESS_TOKEN

Example result of the Get Transformation Operation

json

{
  "transformation": {
      "id": "myTransformationId",
      "status": "Succeeded",
      "errorMessage": "",
      "processedEntityCount": 100,
      "totalEntityCount": 100,
      "createdDateTime": "2024-03-05T14:51:33.6133333Z",
      "startedDateTime": "2021-08-02T14:51:33.6133333Z",
      "finishedDateTime": "2021-08-02T14:51:33.6133333Z",
      "sourceChangeset": {
          "id": "myEndChangesetId"
      },
      "lastTargetChangesetPushed": {
          "id": "myEndTargetChangesetId"
      },
      "_links": {
          "configuration": {
              "href": "https://api.bentley.com/transformations/configurations/myConfigurationId"
          }
      }
  }
}

6. Inspect the results

Once the transformation has completed successfully, you can open the target iModel to inspect the filtered results. The target iModel now contains only the elements that were visible in the specified saved view.

Next steps

Update the source iModel and run the transformation again to see how changes are applied
Modify the saved view and run the transformation again to see different filtering results

More resources that you may like

Transformations

An overview and detailed Transformations API documentation.

Webhook tutorial

Learn how to utilize webhooks to react to events like transformation completed events.

Was this page helpful?