Export data from an iModel

Introduction

This quick start is intended to help you export data from an iModel to different formats like IFC or LandXML and store it in the iTwin Storage. Export API works in project and iModel context. In this walk-through, you will be able to start an export.

Info

Skill level:

Intermediate

Duration:

20 minutes

1. Register an Application

You will need to register an application to use the iTwin Platform APIs. 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 Export API and has export:modify export:read scopes enabled.

Single page application

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 requests to the API, a 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 need to use Client ID generated from previous registration step.

Grab a user token from Api reference “Try it out” Section

  1. Go to Create Configuration
  2. Click “Try it out” 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. Store refresh token for user

The export process usually takes time and is performed in the background. For that, we need to store the user’s refresh token. To get the authorization information, use the Get Authorization Information API. This API will return the current status and a redirect URL where user has to be redirected on the browser if the token has to be renewed.

Request

In order to do that, send a GET https://api.bentley.com/export/authorizationInformation?redirectUrl=REDIRECT_URL request.

  1. Authorization header with valid Bearer token is required.
  2. REDIRECT_URL is a url of where a user should be redirected after successful token renewal.

Get Authorization Information Request Syntax and Headers

HTTP
GET https://api.bentley.com/export/authorizationInformation?redirectUrl=REDIRECT_URL HTTP/1.1
Authorization: Bearer JWT_TOKEN
Content-Type: application/json

Response if user has a valid refresh token

“isUserAuthorized” with value “true” means, user has a valid refresh token and can run long running export.

Get Authorization Information Response Body

JSON
{
    "authorizationInformation": {
        "isUserAuthorized": true,
        "_links": {
            "authorizationUrl": {
                "href": null
            }
        }
    }
}

Response if user does not have a valid refresh token

“isUserAuthorized” with value “false” means, user does not have valid refresh token and cannot run long running export. To refresh token user has to be redirected to authorizationUrl from response.

Get Authorization Information Response Body

JSON
{
    "authorizationInformation": {
        "isUserAuthorized": false,
        "_links": {
            "authorizationUrl": {
                "href": "https://connect-itwinbridgeportal.bentley.com/authenticate?redirect_url=REDIRECT_URL"
            }
        }
    }
}

4. Start Export

To start the Export, call the endpoint Start Export

These are the required properties for the endpoint:

  • projectId - Project Id.
  • iModelId - iModel Id of an iModal that is going to be used for the export.
  • exportType - Export Type ("IFC" or "LandXML").

These are the optional properties for the endpoint:

  • changesetId - Changeset Id of the iModel.
  • folderId - Folder Id to store the output file.
  • mappingFileId - User-defined mapping file Id.
  • saveLogs - Set to save the logs of export.
  • replaceOlderFile - Set to replace the older file for same imodel.
  • ifcVersion - Ifc Version if the export type is “IFC” (One of 'IFC4.3 RC1’, 'IFC2x3’, 'IFC2x3 CV 2.0’, 'IFC4 RV 1.2’).

To execute the request, go to StartExport page and use the “Try it out” section.

Request Syntax

HTTP
POST https://api.bentley.com/export/startExport HTTP/1.1

Request Headers

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

Request Body

JSON
{
  "projectId": "ProjectId",
  "iModelId": "IModelId",
  "changesetId": "ChangesetId",
  "folderId": "FolderId",
  "mappingFileId": "MappingFileId",
  "saveLogs": true,
  "replaceOlderFile": false,
  "exportType": "ExportType",
  "ifcVersion": "IfcVersion"
  }
}

Response Headers

HTTP
Content-Type: application/json

Response Body

JSON
{
  "start-export-status":{
    "status": "started"
  }
}

5. Waiting for the export to finish

Once completed the output file will be uploaded to the storage. To get that use the storage API.

6. Conclusion

We’ve successfully started an export to export the iModel data.

Continue learning

More resources that you may like

Export API documentation
An overview and detailed Export API documentation.