Create an empty iModel

Introduction

This quick start is intended to help you understand what an iModel is and how to leverage iTwin Platform iModels API for managing it.

By the end of this walk-through, you will be able to create an empty iModel using iModels API which later on can be used as a destination iModel for your synchronization workflow.

Info

Skill level:

Basic

Duration:

5 minutes

Prerequisites

This tutorial assumes that you already have:

  • Project created and configured. Instructions on how to create a project can be found here.

1. Register an Application

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. Make sure that your application is associated with iModels, Library, RealityData and Storage APIs and has realitydata:read imodels:read imodels:modify library:read storage:read storage:modify scopes enabled.

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.

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

Here you can use Client ID generated from previous registration step.
  1. Go to Create Connection - Synchronization
  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. Create an empty iModel

An iModel is a specialized information container for exchanging data associated with the lifecycle of infrastructure assets. iModels were created to facilitate the sharing and distribution of information regardless of the source and format of the information.

iTwin Platform iModels API is based on iModelHub cloud service which enables alignment, accountability and accessibility of infrastructure digital twins. It is the control center for iModels and is responsible for coordinating concurrent access to iModels as well as changes made to them.

An empty iModel is created by sending a HTTP POST message to https://api.bentley.com/imodels/ endpoint with the payload describing the iModel to be created.

There are two required properties for the create iModel payload.

name - iModel name is required which uniquely identifies the iModel within the Project.
projectId - provides Project identifier that created iModel will belong to. Project identifier is required property.
description - free form text field so you could give more information about the iModel.
extent - iModels usually are placed at some location on the Earth. This property allows to specify the maximum rectangular area on the Earth which encloses the iModel. The maximum extent is used to help keep your iModel clean. When new elements are imported, those outside the extent will be flagged for further processing. This extent will also help to zoom to the area of interest in web viewers.

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

You can execute the request in Create iModel documentation page, “Try it” section.

Since an empty iModel does not contain any graphical elements or any data it cannot be opened yet for viewing. In order to bring data to the created iModel you may setup synchronization connection which will transform engineering data from native design formats to iModel. Once the synchronization has been setup and executed, viewing session can be started.

Request Syntax


HTTP
GET https://api.bentley.com/imodels HTTP/1.1

Request Headers


HTTP
Accept: application/json
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Request Body


JSON
{
  "projectId":"PROJECT_ID",
  "name":"Sun City Renewable-energy Plant",
  "description":"Overall model of solar farms in Sun City",
  "extent":{
    "southWest":{
      "latitude":46.13267702834806,
      "longitude":7.672120009938448
    },
    "northEast":{
      "latitude":46.302763954781234,
      "longitude":7.835541640797823
    }
  }
}

Response Headers


HTTP
Content-Type: application/json
Location: https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d

Response Body


JSON
{
  "iModel":{
    "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",
    "extent":{
      "southWest":{
        "latitude":46.13267702834806,
        "longitude":7.672120009938448
      },
      "northEast":{
        "latitude":46.302763954781234,
        "longitude":7.835541640797823
      }
    },
    "_links":{
      "creator":{
        "href":"https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
      }
    }
  }
}