• Get Started
  • Documentation
  • Samples
  • Blog
  • Pricing
    • Free Trial
    Table of contents
    Overview
    Supported formats
    Available Events
    Tutorials
    Samples
    Changelog
    Synchronization
    Download API definition:

    Synchronization API Overview

    Introduction

    The Synchronization API allows you to integrate engineering data into your iTwin composition. With this API, you can synchronize data from a variety of CAD and BIM applications, as well as different file formats. Requests are handled through specific Connectors, enabling the aggregation and alignment of data within an iModel. This ensures that your iTwin stays current and up-to-date.

    Key Features

    • Synchronize files directly from your document management system or the storage location where it resides using pre-authenticated URLs.
    • Synchronize files directly from iTwin Storage.
    • A wide range of connectors is available to facilitate your synchronization setup. Refer to the Supported formats section for the complete list of supported formats.
    • Set the required synchronization configuration on the iTwin, iModel, or Connection scopes to define how data needs to be processed.
    • Troubleshoot data or synchronization issues using the Diagnostic Reports.

    Familiarize with important concepts while completing the Synchronization API accreditation course.

    Integrations

    With Manifest Connections, you can set up synchronizations for any document management system that supports pre-authenticated file access URLs.

    Here are some resources to help you get started quickly:

    • Azure Blob Storage: Follow the tutorial or the sample on synchronizing a file from Azure Blob Storage.
    • SharePoint: Refer to the SharePoint sample.

    Workflow

    Manifest Connections

    iTwinSynchronizerSteps

    To create and run initial synchronization:

    1. Get pre-authenticated file access URLs from the file storage that you are using.
    2. Create Manifest Connection: Use the synchronization/imodels/manifestconections endpoint to create a connection that establishes links between your design files and iModel.
    3. Run Connection: Use the synchronization/imodels/manifestconnections/{connectionId}/runs endpoint to run the created connection by passing access URLs.
    4. Get Run Status: Use the synchronization/imodels/manifestconnections/{connectionId}/runs/{runId} endpoint to check the run status.
    5. Chech Diagnostic Report: Use the synchronization/reports?{iModelId}&{runId}[&taskId] endpoint to inspect any found issues.

    To update an iModel when engineering data is changed:

    1. Get pre-authenticated file access URLs from the file storage that you are using.
    2. Run Connection again: Use the synchronization/imodels/manifestconnections/{connectionId}/runs endpoint to run the required connection by passing access URLs.

    You can also use the synchronization/imodels/manifestconnections/{connectionId}/sourcefiles/{sourceFileId} endpoints to add, update, or delete the required design file from the Manifest Connection.

    Basic Concepts

    Familiarize yourself with these concepts that are used throughout the documentation:

    Term
    Definition
    Connector
    An iTwin Connector will process a file from an application such as MicroStation, Revit, and many more, transforming the model's content—including geometry, properties, and relationships—into an iModel. It also creates a schema based on the source data. You can synchronize multiple models using the same Connector or use different Connectors for various models to achieve the desired iModel.
    Connectors identify differences in the source models between job runs. This synchronization results in Changesets, which contain the modifications sent to the iModel service. This is the key distinction between a Connector and a one-time converter.
    During the initial synchronization, the Changeset will include the entire model's content. In subsequent synchronization runs, Changesets will reflect only the incremental differences between the existing iModel and your changes. If there are no modifications to the source model, the Connector will not process the synchronization, and no Changesets will be generated.
    Connection
    The synchronization process relies on connections that link design files to iModels. For instance, an iModel may have multiple connections, and these connections can be executed on-demand multiple times to ensure continuous synchronization of changes. Additionally, the history of these synchronization runs is preserved and available for monitoring.
    Source File
    A source file entity establishes a connection between a specific file in the data source and the iTwin connector during synchronization. Mark the source file as a spatial root if it contains coordinate reference system information. Use the Spatial alignment guide to learn more about ensuring accurate and precise geolocation.
    Run
    A run represents a single synchronization process for a connection. It has properties such as status, duration, and others. Only one run can exist per connection at any given time.
    Authorization
    The synchronization process occurs in the background and may take time. Based on your application type, there are two methods to call the API:
    • User-Centered Applications/User Intercase: Use the user authorization workflow and provide the connection owner's refresh token obtained from the Get Authorization Information API. This API will also provide a redirect URL if the token needs renewal.
    • Backend Service: For applications without a user interface, use a service-type application when registering a client and set the authenticationType to "Service" on the connection.

    Media Links

    • The Synchronization API - Accreditation course
    • iTwin Developer Conference 2022. Synchronization API: Connectors to the Rescue - YouTube
    • iTwin Developer Webinar. iTwin Synchronization: Bring Together a Wide Array of Disparate Engineering Data - YouTube

    Was this page helpful?