Skip to main content

Connector Configuration

Use this page before creating a DFS Lite connector. It lists the information a data owner or integration engineer should prepare for each source type.

Open:

Data Integration > Connectors > Add Connector

Configuration flow​

Configuration pattern​

Every connector setup follows the same pattern:

  1. Identify the source owner.
  2. Choose connector type.
  3. Enter connection settings.
  4. Choose sync strategy.
  5. Test the connection.
  6. Check the connector capability matrix and use only the supported browse, preview, subscribe, or poll-read path.
  7. Save the connector.
  8. Add mappings.

Common fields​

FieldUse
Connection nameHuman-readable name for the source.
DescriptionSource purpose, owner, site, and operating context.
ModeLocal or DFS Proxy routing, depending on deployment.
Sync strategyRealtime, interval, or on-demand only when the connector implements that access path.
CredentialsOnly the authentication modes listed for that connector in the capability matrix.
Advanced settingsTimeouts, polling interval, security mode, or source-specific options.

OPC UA​

Use OPC UA for industrial automation systems and equipment telemetry.

Prepare:

  • endpoint URL;
  • security policy: None or Basic256Sha256;
  • anonymous, username/password, or supported X.509 user authentication;
  • for Basic256Sha256, an application URI, client application identity reference, and server trust-list reference;
  • for X.509 user authentication, a separate user identity reference unless identity reuse is explicitly approved;
  • an optional certificate revocation-list reference;
  • namespace information;
  • node IDs or browse path;
  • expected sampling or polling frequency;
  • source-side read permissions.

Validation checks:

  • endpoint is reachable from the DFS runtime;
  • None is used only with no message security and anonymous or username/password authentication;
  • Basic256Sha256 selects SignAndEncrypt and the exact server endpoint/token combination;
  • the client application certificate URI matches the configured application URI;
  • the server certificate chains to the tenant trust list and is not revoked;
  • browse returns expected nodes;
  • a configured-node poll read returns expected timestamps and values;
  • units and scale factors are confirmed by the source owner.

Certificate settings contain only secret://<name> references. The backend resolves PKCS#12 stores and password sidecars below <security-root>/<tenant-id>/; private keys are never stored in connector JSON. Operators must mount that root read-only and restrict each .p12 and .password file to its owner. Missing material, symlinks, cross-tenant paths, wrong passwords, expired or mismatched certificates, untrusted servers, and unsupported policy/auth combinations fail closed. Basic256 and policies other than None and Basic256Sha256 remain unsupported.

BACnet​

Use BACnet for building automation systems and facility points.

Prepare:

  • network route or gateway information;
  • device IDs;
  • object identifiers;
  • polling interval;
  • point list from BMS or facility team;
  • units and expected ranges.

Validation checks:

  • target devices respond;
  • object list matches the BMS point schedule;
  • stale or unavailable objects are excluded;
  • polling interval fits facility-system load and operational needs.

Modbus​

Use Modbus when the source exposes values through Modbus TCP registers. Serial RTU is unsupported by the DFS connector.

Prepare:

  • host and port;
  • unit ID;
  • register map;
  • register type;
  • address offset convention;
  • data type and byte order;
  • scale factors;
  • polling interval.

Validation checks:

  • register values match the source owner's reference values;
  • byte order and signedness are correct;
  • transformed values are in the expected range;
  • polling stays within device capacity.

MQTT​

Use MQTT for topic-based IoT and streaming payloads.

Prepare:

  • broker URL;
  • port and TLS requirements;
  • optional username and password;
  • topic pattern;
  • payload format;
  • timestamp field;
  • quality of service expectation;
  • retained message behavior.

Validation checks:

  • connector can subscribe to the expected topic;
  • sample payloads parse correctly;
  • timestamp, equipment ID, and metric fields are present;
  • topic naming convention is stable.

MQTT is inbound subscribe-only. It does not support browse, poll read, connector preview, on-demand sync, or publish.

REST​

Use REST for enterprise APIs, cloud services, or custom data services.

Prepare:

  • base URL;
  • authentication method;
  • endpoint path;
  • query parameters;
  • pagination behavior;
  • response field paths;
  • timestamp field;
  • expected request frequency;
  • rate limit.

Validation checks:

  • test request succeeds;
  • response shape matches the expected mapping;
  • pagination preserves all records;
  • rate limits are respected;
  • error responses are understandable to operators.

CSV​

Use CSV for first imports, offline data, historian exports, and staged files.

Prepare:

  • file source or upload;
  • delimiter;
  • header row;
  • timestamp column;
  • equipment or asset key column;
  • unit columns or unit convention;
  • timezone;
  • file update schedule.

Validation checks:

  • expect the connector test to fail until file data has parsed into the runtime buffer;
  • treat a passing CSV test as loaded-data readiness, not watched-source connectivity;
  • header names are stable;
  • timestamp parsing is correct;
  • required columns are present;
  • duplicate rows are understood;
  • source file naming convention is clear.

JDBC​

Use JDBC for PostgreSQL and Microsoft SQL Server databases available through the packaged runtime drivers.

Prepare:

  • database URL;
  • credentials;
  • table or query;
  • timestamp column;
  • primary or natural key;
  • metric columns;
  • filter conditions;
  • expected row volume;
  • least-privilege access approval.

Validation checks:

  • query returns only the needed data;
  • timestamp and key columns are stable;
  • row volume is safe for the sync strategy;
  • the database account is restricted to the required read operations.

The connector accepts exactly one parsed read-only SELECT or read-only CTE. It rejects write, DDL, procedure-call, row-locking, SELECT INTO, multi-statement, and unsupported SQL forms before opening the execution pool. Runtime-owned timeout, row, fetch, column, cell, per-cell byte, total-byte, query-length, and parser-time limits apply; connector settings can only request lower values. Connections and transactions request read-only mode, but the source account must still have only SELECT on the minimum required schemas and tables. Keep credentials out of the JDBC URL so pool and driver diagnostics never receive URL secrets. The catalog exposes PostgreSQL and Microsoft SQL Server templates; MySQL is unavailable because its driver is not packaged.

Fabric​

Choose the Fabric mode before preparing the configuration:

  • OneLake mode lists paths and returns .parquet file references. It does not decode tabular rows and does not provide connector preview.
  • SQL endpoint mode reads allowlisted tabular columns and supports connector row preview.

Prepare:

  • OneLake tenantId, clientId, clientSecret, workspaceId, and deltaPath; or
  • SQL endpoint sqlEndpointJdbcUrl, username/password, sqlEndpointTable, sqlEndpointColumns, optional schema/timestamp column, row limit, and query timeout;
  • refresh expectation;
  • column schema;
  • owner and data classification.

Validation checks:

  • connection is enabled for the tenant;
  • OneLake file inventory is visible, or the configured SQL endpoint table and columns are visible;
  • SQL endpoint preview returns expected rows when row access is required;
  • data classification allows downstream use.

Confirm Fabric availability with the project owner before documenting it as a required connector in a customer runbook.

Expected output​

After configuration, the project should have:

  • a connector configuration that can be retested by another operator;
  • source-owner, system, and site context recorded in the name or description;
  • sync strategy aligned with the operational use case;
  • credentials and route approved for the target environment;
  • a clear next step using only the operations supported by the selected connector.

If the connector cannot pass testing, do not hand it to mapping work. Record the failing check, source owner, environment route, and next action before stopping.

Security checklist​

Before saving production connectors:

  • use approved credentials;
  • avoid shared personal accounts;
  • confirm network route and firewall approval;
  • prefer read-only access when writeback is not required;
  • record source owner and support contact;
  • confirm that source data is allowed in the target tenant.

Next step​

After connector configuration succeeds, use Browse and Preview only when the selected connector supports the required operation. Otherwise validate through its poll-read, subscription, or file-import path.