Create iModel Named Version

Introduction

This quick start is intended to guide you through the steps to create a new iModel Named Version.

By the end of this walk-through, you will be able to create a new Named Version within selected iModel using iModels API which later on can be opened with the viewer.

Info

Skill level:

Basic

Duration:

10 minutes

Prerequisites

This tutorial assumes that you already have:

An empty iModel created.
- Instructions to create an empty iModel can be found here
Synchronization of design files to the iModel configured and synchronized.
- Instructions to synchronize a file can be found here

You will need to register an application to use the iTwin Platform APIs. You can use the Register button to automatically create your first single page application (SPA). This will allow you to configure Authorization Code Flow for your SPA application and get the correct access token.

Once generated, you will be shown a few lines of code under the button.

IMJS_AUTH_CLIENT_CLIENT_ID - this is the unique identifier for your application. Displayed on application details page as Client ID.
IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen whether or not to authenticate your app. Displayed on application details page as one of Redirect URIs.
IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where users can be returned to after logging out. Displayed on application details page as one of Post logout redirect URIs.
IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. Displayed on application details page as Scopes.

Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial.

Register a basic SPA App for this tutorial

Requires you to sign in. Will automatically generate a Single page application (SPA) that is required to complete this tutorial. You will be able to manage your SPA from your My apps page.

2. Get a token

To make request to API user token is needed. There are several ways to get it.

Implement Authorization Code Flow in the application

Follow this article to implement Authorization code workflow in your application.

Here you can use Client ID generated from previous registration step.

Grab a user token from Api reference "Try it" Section

Go to Get iTwin iModels - iModels
Click "Try it" button.
On Authorization section select "AuthorizationCode".
After popup closes Authorization header with your user token value should be visible.
Save user token value for this tutorial.

Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

3. Get a list of iModels in the Project

First of all we need to select an iModel where we want to create a Named Version.

To retrieve a list of iModels in the project send a HTTP GET request to https://api.bentley.com/imodels/?iTwinId=ITWIN_ID and provide iTwinId query parameter.

Note: please replace dynamic parameters (JWT_TOKEN and ITWIN_ID) with relevant values from previous steps.

You can execute the request in Get iTwin iModels documentation page, "Try it" section.

Response from the server has a list of iModels in the specified project. Once you find an iModel for which you want to create a Named Version you can use the changesets link to retrieve all Changesets of an iModel.

Request Syntax

http

GET https://api.bentley.com/imodels/?iTwinId=ITWIN_ID HTTP/1.1

Request Headers

http

Accept: application/vnd.bentley.itwin-platform.v2+json
Prefer: return=representation
Authorization: Bearer JWT_TOKEN

Response Headers

http

Content-Type: application/json
Etag: "P7yWLBoFpMcFbE25CKMLNCqoZ4Q="

Response Body

json

{
"iModels":[
  {
    "id":"5e19bee0-3aea-4355-a9f0-c6df9989ee7d",
    "displayName":"Sun City Renewable-energy Plant",
    "name":"Sun City Renewable-energy Plant",
    "description":"Overall model of wind and solar farms in Sun City",
    "initialized":true,
    "createdDateTime":"2020-10-20T10:51:33.1700000Z",
    "iTwinId":"ITWIN_ID",
    "_links":{
      "creator":{
        "href":"https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
      },
      "changesets":{
        "href":"https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets"
      }
    }
  },
  {
    "id":"e5692781-32b8-473d-8752-908468f46926",
    "displayName":"Power Town Processing Plant",
    "name":"Power Town Processing Plant",
    "description":"Overall model of processing plant in Power town",
    "initialized":true,
    "createdDateTime":"2020-10-20T10:51:33.1700000Z",
    "iTwinId":"ITWIN_ID",
    "_links":{
      "creator":{
        "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
      },
      "changesets":{
        "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/changesets"
      }
    }
  }
],
"_links":{
  "self":{
    "href":"https://api.bentley.com/imodels?iTwinId=ITWIN_ID&$skip=0&$top=100"
  },
  "prev":{
    "href":"https://api.bentley.com/imodels?iTwinId=ITWIN_ID&$skip=0&$top=100"
  },
  "next":{
    "href":"https://api.bentley.com/imodels?iTwinId=ITWIN_ID&$skip=100&$top=100"
  }
}
}

4. Get a list of Changesets in the iModel

By sending a HTTP GET message to changesets link retrieved from previous step (https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/changesets) we can retrieve a list of Changesets in the iModel.

You can execute the request in Get iModel Changesets documentation page, "Try it" section.

Response contains a list of Changesets. If the Changeset has a Named Version the response contains a link to it otherwise the link is null. You can see that our example has a Named Version created only for the first Changeset.

Request Syntax

http

GET https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/changesets HTTP/1.1

Request Headers

http

Accept: application/vnd.bentley.itwin-platform.v2+json
Prefer: return=representation
Authorization: Bearer JWT_TOKEN

Response Headers

http

Content-Type: application/json
Etag: "20EzIoC8ZD/iWVKQt4AnPlr/Otg="

Response Body

json

{
"changesets":[
  {
    "id":"a1ecbdc8c4f6173004f9f881914a57c5511a362b",
    "displayName":"1",
    "description":"Changeset 0",
    "index":1,
    "parentId":"",
    "pushDateTime":"2020-10-21T06:34:45.007Z",
    "application":{
      "name":"iTwin Synchronizer"
    },
    "_links":{
      "creator":{
        "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
      },
      "namedVersion":{
        "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/namedversions/a9f63fc0-ecab-440b-ba59-1a617e15f543"
      }
    }
  },
  {
    "id":"7caef8ab5afcd99c9e618fb37978c3a03d0409c7",
    "displayName":"2",
    "description":"Changeset 1",
    "index":2,
    "parentId":"a1ecbdc8c4f6173004f9f881914a57c5511a362b",
    "pushDateTime":"2020-10-21T06:34:48.123Z",
    "application":{
      "name":"iTwin Synchronizer"
    },
    "_links":{
      "creator":{
        "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
      },
      "namedVersion":null
    }
  },
  {
    "id":"a587345859410ce5c2811c7c558d4578938efa00",
    "displayName":"3",
    "description":"Changeset 2",
    "index":3,
    "parentId":"7caef8ab5afcd99c9e618fb37978c3a03d0409c7",
    "pushDateTime":"2020-10-21T06:34:51.13Z",
    "application":{
      "name":"Synchro Modeler"
    },
    "_links":{
      "creator":{
        "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/users/27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d"
      },
      "namedVersion":null
    }
  },
  {
    "id":"13a61888798b687d41f7c748d7414b428766281f",
    "displayName":"4",
    "description":"Changeset 3",
    "index":4,
    "parentId":"a587345859410ce5c2811c7c558d4578938efa00",
    "pushDateTime":"2020-10-21T06:34:54.13Z",
    "application":{
      "name":"Synchro Modeler"
    },
    "_links":{
      "creator":{
        "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/users/27e3ecc7-ae44-4c9d-b0b5-2f65ec146f1d"
      },
      "namedVersion":null
    }
  }
],
"_links":{
  "self":{
    "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/changesets?$skip=100&$top=100"
  },
  "prev":{
    "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/changesets?$skip=0&$top=100"
  },
  "next":{
    "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/changesets?$skip=200&$top=100"
  }
}
}

5. Create a Named Version

Lets say we want to create a new Named Version on the latest Changeset. To do that we need to send a HTTP POST message to https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/namedversions endpoint with the payload describing the Named Version to be created.

name - Named Version name is required which uniquely identifies the Named Version within iModel.
description - free form text field so you could give more information about the Named Version.
changesetId - provides Changeset identifier the Named Version will be created for. If not provided a baseline iModel Named Version will be created.

You can execute the request in Create iModel Named Version documentation page, "Try it" section.

Once the Named Version is created you can start viewing session.

Request Syntax

http

POST https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/namedversions HTTP/1.1

Request Headers

http

Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN

Request Body

json

{
"name": "Wind farm design",
"description": "Finalized wind farm design in Power Town",
"changesetId": "13a61888798b687d41f7c748d7414b428766281f"
}

Response Headers

http

Content-Type: application/json
Location: https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/namedversions/8a7d2fef-9613-47ff-b7e4-9081d51b1716

Response Body

json

{
"namedVersion":{
  "id":"3020441b-e179-4334-a59a-4fb8deb93df1",
  "displayName":"Wind farm design",
  "name":"Wind farm design",
  "description":"Finalized wind farm design in Power Town",
  "createdDateTime":"2020-10-21T06:42:57.6700000Z",
  "state":"visible",
  "_links":{
    "creator":{
      "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/users/ea4dfb9f-7f66-4c6f-82c5-0efad1636a1f"
    },
    "changeset":{
      "href":"https://api.bentley.com/imodels/e5692781-32b8-473d-8752-908468f46926/changesets/13a61888798b687d41f7c748d7414b428766281f"
    }
  }
}
}

Continue learning

React to iModel events

Guide on how to use the Webhooks REST API to subscribe to iModel events.

More resources that you may like

Data Management API documentation

An overview and detailed Data Management API documentation.

Overview of iModel

An overview of iModel data structure.