Synchronize a file from iTwin Storage

Introduction

This is a walk-through how to synchronize a file from iTwin Storage to an iModel using Synchronization API. Synchronization API works in project and iModel context. To synchronize a set of files a connection has to be created. Connection is an aggregation of properties like file metadata which is needed for synchronization. Connections can be run on demand which starts a file specified in the connection conversion to an iModel.

Info

Skill level:

Basic

Duration:

30 minutes

1. Register an Application

To build an application on the iTwin Platform, you will need to register a client. In this tutorial Synchronization, Data Management and Administration APIs will be used.

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 Synchronization, Data Management and Administration APIs
  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.

Grab a token from Api reference “Try it” Section


  1. Go to Create Connection - Synchronization
  2. Click “Try it” button.
  3. On Authorization section select “AuthorizationCode”.
  4. After popup closes Authorization header with token value should be visible.
  5. Save token value for this tutorial.

3. Create an iModel

An iModel is a specialized information container for exchanging data associated with the lifecycle of infrastructure assets. In this tutorial we will create an empty iModel and will synchronize it with design file data. To create an iModel a request has to be sent.

Request


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

POST https://api.bentley.com/imodels
Authorization: Bearer <access_token>
Content-Type: application/json

Request Body


There are two required properties for the create iModel payload.

  • name - iModel name is required which uniquely identifies the iModel within the Project or Asset.
  • projectId or assetId - provides Project or Asset identifier that created iModel will belong to.

These properties are mutually exclusive and only one must be provided.

  • 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 that after completing this step, you will be provided with both a PROJECT_ID (i.e. ProjectId) and an iModel_ID which will be required in a later step.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "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 } } }

4. Get fileId from Storage API

iTwin File Storage API store files and folders under some folder. To get root files and folder we can use “Get top level folders and files by project” API.

Request


That can be done by sending a GET https://api.bentley.com/storage/?projectId=PROJECT_ID request.

  1. Authorization header with valid Bearer token is required.
  2. PROJECT_ID where files and folders are stored.
GET https://api.bentley.com/storage/?projectId=PROJECT_ID
Authorization: Bearer <access_token>
Content-Type: application/json

Response


The request response contains a file Id which will be used in next step.

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 { "items": [{ "id": "FOLDER_ID", "type": "folder", "displayName": "1", "description": null, "path": "1", "createdBy": "4ebeaf72-3c42-4734-b41a-485c6c2ecb67", "lastModifiedBy": "4ebeaf72-3c42-4734-b41a-485c6c2ecb67", "createdDateTime": "2019-07-16T08:41:05.6415752Z", "lastModifiedDateTime": "2020-01-07T08:46:47.5422276Z", "parentFolderId": "mCbnk2CSr0K4bAkoDGgNEZgm55Ngkq9CuGwJKAxoDRE" },{ "id": "FILE_ID", "type": "file", "displayName": "Test.dgn", "description": null, "path": "Test.dgn", "size": "38400", "createdBy": "4ebeaf72-3c42-4734-b41a-485c6c2ecb67", "lastModifiedBy": "4ebeaf72-3c42-4734-b41a-485c6c2ecb67", "createdDateTime": "2020-06-23T11:13:42.3498148Z", "lastModifiedDateTime": "2020-07-07T11:46:44.9573652Z", "parentFolderId": "mCbnk2CSr0K4bAkoDGgNEZgm55Ngkq9CuGwJKAxoDRE" }], "_links": { "self": { "href": "https://api.bentley.com/storage?projectId=PROJECT_ID&$skip=0&$top=100" }, "prev": { "href": "https://api.bentley.com/storage?projectId=PROJECT_ID&$skip=0&$top=100" }, "next": { "href": "https://api.bentley.com/storage?projectId=PROJECT_ID&$skip=100&$top=100" }, "folder": { "href": "https://api.bentley.com/storage/folders/mCbnk2CSr0K4bAkoDGgNEZgm55Ngkq9CuGwJKAxoDRE" } } }

5. Create a Connection

The synchronization process is based on connections that establish links from design files to iModels. There could be multiple connections for an iModel, and those could be executed on-demand multiple times to synchronize changes. In this step we will be creating such connection.

Request


Creating a Connection requires sending a POST request to the synchronization/imodels/storageConnections endpoint.

  1. Authorization header with valid Bearer token is required.
  2. IMODEL_ID of created imodel from step 3.
  3. We will need to specify what file from File Storage should be mapped to a connection. To do that we will need a file id from previous step response.
POST https://api.bentley.com/synchronization/imodels/storageConnections
Authorization: Bearer <access_token>
Content-Type: application/json

Request Body


  • displayName - user facing connection name
  • iModelId: - imodel Id which should contain created connection
  • sourceFiles - information about source files from File Storage
    • storageFileId - id of the file from Storage API
    • connectorType - connector which file should be processed with identificator.
1 2 3 4 5 6 7 8 { "displayName": "Connection1", "iModelId": "IMODEL_ID", "sourceFiles": [{ "storageFileId": "FILE_ID", "connectorType": "MSTN" }] }

Response


The request response contains created connection properties values. Id is going to be needed in next step

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "connection": { "id": "CONNECTION_ID", "displayName": "connection1", "iModelId": "IMODEL_ID", "projectId": "PROJECT_ID", "_links": { "iModel": { "href": "https://api.bentley.com/imodels/IMODEL_ID" }, "project": { "href": "https://api.bentley.com/projects/PROJECT_ID" }, "lastRun": null } } }

6. Run a Connection

A Run defines a single Connection synchronization process. It can be initialized manually by sending run start request.

Request


Running a connection requires sending a POST request to the synchronization/imodels/connections/{connectionId}/run[?imodelId] endpoint with valid connectionId.

  1. Authorization header with valid Bearer token is required.
  2. CONNECTION_ID which should be started for processing. Use the value from previous step response.
POST https://api.bentley.com/synchronization/imodels/storageConnections/CONNECTION_ID/run
Authorization: Bearer <access_token>
Content-Type: application/json

Response


On successful request, operation returns http status code 202/accepted - the request is accepted for processing and will be executed in the background. If there is already an active run in progress for this connection, new run is being added to the queue.

202 Accepted

7. Get runs statuses

A run contains synchronization process status. To get runs history and statuses get reqest has to be made.

Request


Getting Run status requires sending a GET request to the synchronization/imodels/storageConnections/{connectionId}/runs endpoint with valid connectionId.

  1. Authorization header with valid Bearer token is required.
  2. CONNECTION_ID which runs we want to get.
POST https://api.bentley.com/synchronization/imodels/storageConnections/CONNECTION_ID/runs
Authorization: Bearer <access_token>
Content-Type: application/json
Response

At the end of synchronization run state should be “Completed” and result “Success”.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "runs": [{ "id": "41062244-3e62-42a3-8232-9f2b4d31be16", "state": "Completed", "result": "Success" }], "_links": { "self": { "href": "https://api.bentley.com/Synchronization/imodels/storageConnections/CONNECTION_ID/runs?$skip=0&$top=100" }, "prev": { "href": "https://api.bentley.com/Synchronization/imodels/storageConnections/CONNECTION_ID/runs?$skip=0&$top=100" }, "next": { "href": "https://api.bentley.com/Synchronization/imodels/storageConnections/CONNECTION_ID/runs?$skip=100&$top=100" } } }

8. Conclusion

In this tutorial we have gone through a file from iTwin Storage synchronization process:

  1. Create an empty imodel
  2. Create a connection
  3. Run the connection
  4. Get run status.

After successfull run, design file changes should be in an iModel. Next step could be to create a Named Version.

Continue learning

Congratulations for the completion of your first synchronization! You’ve now know a lot on the subject, but there’s still possibilities to learn more to unleash the platform capabilities.

More resources that you may like

Synchronization API documentation

An overview and detailed Synchronization API documentation.

Data Management API documentation

An overview and detailed Data Management API documentation.