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:
- iTwin created and configured. Instructions on how to create a project iTwin 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.
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.
Grab a user token from Api reference "Try it" Section
- Go to Create Storage Connection
- 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.
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 iTwin.
iTwinId - provides iTwin identifier that created iModel will belong to. iTwin 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.
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
GET https://api.bentley.com/imodels HTTP/1.1Request Headers
Accept: application/vnd.bentley.itwin-platform.v2+json
Authorization: Bearer JWT_TOKEN
Content-Type: application/jsonRequest Body
{
"iTwinId":"ITWIN_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
Content-Type: application/json
Location: https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7dResponse Body
{
"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",
"iTwinId":"ITWIN_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"
}
}
}
}