Release Version: BetaRelease VersionBeta Vendor Support: Official Integration: Free To Automate

Setup

Prerequisites

  1. Grant IMSURGE Agent Access
    • Log into your iTwin IoT project and navigate to Users and Roles.
    • Add the service account service-LqaqMInpOh69L2ofbWdMHuNNv@apps.imsoidc.bentley.com.
    • Assign the IoT Creator role.
  2. Create a Data Source Connection
    • In your iTwin IoT project, go to the Connections tab.
    • Create a Data Source API Import connection. This will display a Connection ID in the form /api/XXXXX/node.

Integration Setup

No separate credential setup is required for this integration.

The IMSURGE integration setup screen will prompt you for the following details.

  • Project ID – the UUID from the project URL (e.g. https://itwiniot.bentley.com/71b7138c-a99f-4187-8140-f12de7acd15e).
  • Connection ID – the API endpoint of the Data Source connection you created (e.g. /api/4A7B32/node).

Pipeline Setup

When you select iTwin IoT as a pipeline target, configure Use known sensor matchings under Target Settings. This option controls how IMSURGE models the pipeline’s sensor data in iTwin IoT:

  • Enabled (default) – IMSURGE attempts to match each sensor to a known iTwin IoT sensor definition using the source integration type, available metrics, and sensor metadata. A successful match uses the definition’s data shape. If no known match is available, IMSURGE uses a generic sensor definition.
  • Disabled – IMSURGE always uses a generic sensor definition. Disable matching when the source contains already processed or calculated data that a known sensor definition might calculate again. Applying both calculations could produce incorrect values.

This setting applies only to the pipeline being created and cannot be changed after the pipeline is saved. To use a different value, create a new pipeline.

Reference

Field Description Required
Project ID UUID from the iTwin IoT project URL ✓
Connection ID API endpoint of the Data Source connection (/api/XXXXX/node) ✓
Field Description Default
Use known sensor matchings Match source sensors to known iTwin IoT sensor definitions when possible. When disabled or when no match is available, use a generic sensor definition. Enabled
Data Types Recommended Export Notes
Numeric or categorical time series Match pipeline schedule Ensure units and labels are consistent
Metadata Not exported as target data Available metadata may be used to match a known sensor definition

Limitations

  • Pipeline-based configuration – iTwin IoT device and sensor definitions are saved on the pipeline. Deleting a pipeline removes its associated devices and sensors.
    If you want to run multiple pipelines to the same iTwin IoT device or sensors with different polling rates, use the Clone/Duplicate feature to copy a pipeline and adjust the polling rate on the clone. This can be useful for workflows such as having an hourly instrument sync alongside a nightly 24-hour backfill to capture out-of-order data from instruments that occasionally go offline.
  • Metadata support – available metadata, including unit of measure, may not always map to a known sensor definition. IMSURGE uses a generic sensor definition when no match is available. If additional known metric values are required for data imported through IMSURGE, use iTwin IoT’s calculator feature or contact iTwin IoT support for assistance.

External References