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.
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.
Follow this article to implement Authorization code workflow in your application.
- Go to Create Configuration
- Click “Try it out” 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. 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.
In order to do that, send a GET https://api.bentley.com/export/authorizationInformation?redirectUrl=REDIRECT_URL request.
- Authorization header with valid Bearer token is required.
- REDIRECT_URL is a url of where a user should be redirected after successful token renewal.
Get Authorization Information Request Syntax and Headers
GET https://api.bentley.com/export/authorizationInformation?redirectUrl=REDIRECT_URL HTTP/1.1 Authorization: Bearer JWT_TOKEN Content-Type: application/json
“isUserAuthorized” with value “true” means, user has a valid refresh token and can run long running export.
Get Authorization Information Response Body
{ "authorizationInformation": { "isUserAuthorized": true, "_links": { "authorizationUrl": { "href": null } } } }
“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
{ "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
POST https://api.bentley.com/export/startExport HTTP/1.1
Request Headers
Accept: application/json Authorization: Bearer JWT_TOKEN Content-Type: application/json
Request Body
{ "projectId": "ProjectId", "iModelId": "IModelId", "changesetId": "ChangesetId", "folderId": "FolderId", "mappingFileId": "MappingFileId", "saveLogs": true, "replaceOlderFile": false, "exportType": "ExportType", "ifcVersion": "IfcVersion" } }
Response Headers
Content-Type: application/json
Response Body
{ "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.