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

1. Register an Application

To build an application on the iTwin Platform, you will need to register a client.

Click the Register Application button to automatically register a client for this quick start. You can find registered application in My apps page.

Optional: Manual Application registration process


To manually register a client:

  1. Go to https://developer.bentley.com
  2. Click the Sign In button and sign-in using your Bentley account credentials
    • If you have not already registered, click Register now and complete the registration process.
  3. Click on your user icon and navigate to the My Apps page
  4. Click the Register New button
  5. Give your application a Name
  6. Select the Data Management API
  7. Select application type SPA (Single Page Web Application)
  8. Enter Redirect URL
    • For this tutorial use https://localhost:3000
  9. Leave post logout redirect URIs empty.
  10. Click the Save button
Note the Client ID that is generated during the registration process. You will need this in a later step.

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


  1. Go to Get Project iModels - iModels
  2. Click “Try it” button.
  3. On Authorization section select “AuthorizationCode”.
  4. After popup closes Authorization header with your user token value should be visible.
  5. 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/?projectId=PROJECT_ID and provide projectId query parameter.

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

You can execute the request in Get project 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


1 GET https://api.bentley.com/imodels/?projectId=PROJECT_ID HTTP/1.1

Request Headers


1 2 3 Accept: application/vnd.bentley.itwin-platform.v1+json Prefer: return=representation Authorization: Bearer JWT_TOKEN

Response Headers


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

Response Body


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 { "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", "projectId": "PROJECT_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", "projectId": "PROJECT_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?projectId=PROJECT_ID&$skip=0&$top=100" }, "prev": { "href": "https://api.bentley.com/imodels?projectId=PROJECT_ID&$skip=0&$top=100" }, "next": { "href": "https://api.bentley.com/imodels?projectId=PROJECT_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


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

Request Headers


1 2 3 Accept: application/vnd.bentley.itwin-platform.v1+json Prefer: return=representation Authorization: Bearer JWT_TOKEN

Response Headers


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

Response Body


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 { "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


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

Request Headers


1 2 Accept: application/vnd.bentley.itwin-platform.v1+json Authorization: Bearer JWT_TOKEN

Request Body


1 2 3 4 5 { "name": "Wind farm design", "description": "Finalized wind farm design in Power Town", "changeSetId": "13a61888798b687d41f7c748d7414b428766281f" }

Response Headers


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

Response Body


1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "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" } } } }

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.