Export data from an iModel

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.

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.

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.

3. Create a Connection

The export process uses connections that link to iModels. For example, you can create multiple connections to an iModel and execute them on-demand multiple times to export changes. So let’s make such a connection in this step.

To create a connection, send a POST request to the export/connections endpoint.

1. Authorization header with a valid Bearer token is required.
2. IMODEL_ID of the iModel we want to export.

• displayName - a user-friendly name for the connection
• iModelId - The ID of the iModel containing the connection
• [Optional] authenticationType - one of User or Service. The authentication type defaults to User and uses a refresh token to get an access token for long exports. For now Export only supports User authenticationType.

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

4. 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.

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.

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

“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.

5. Run a Connection

A run defines a single connection export process. Send a run start request to initialize the export process.

exportType is a required property. Valid values are IFC or LandXML. Additionally, the following optional parameters are also available:

• inputOptions -

  • changesetId - Changeset Id of the iModel.
  • mappingFileId - User-defined mapping file Id.

• outputOptions -

  • folderId - Folder Id to store the output file.
  • saveLogs - Set to save the logs of export.
  • replaceOlderFile - Set to replace the older file for same imodel.
  • location - Location type one of “USER_BLOBS_TORAGE” or 'STORAGE’. Defaults to STORAGE (STORAGE API).
  • outputSasUrl - Output file SAS url if the location is 'USER_BLOBS_TORAGE’.
  • logsSasUrl - Logs file SAS url if the location is “USER_BLOBS_TORAGE” ans saveLogs is set.

• ifcVersion - Ifc Version if the export type is “IFC” (One of 'IFC4.3 RC1’, 'IFC2x3’, 'IFC2x3 CV 2.0’, 'IFC4 RV 1.2’).

Send a POST request to the export/connections/{connectionId}/runs endpoint with valid connectionId to run a connection.

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.

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.

6. Get runs statuses

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

Getting Run status requires sending a GET request to the export/connections/{connectionId}/runs endpoint with valid connectionId.

1. Authorization header with valid Bearer token is required.
2. CONNECTION_ID which runs we want to get.

At the end of export, the run state should be Completed, and result Success.

7. Conclusion

In this tutorial we have gone through a iModel export process:

1. Create a connection
2. Run the connection
3. Get run status.

After successful run, output file could be found in the location provided (Storage API by default).

Continue learning

More resources that you may like