Migrating from HighByte Intelligence Hub

How to export a HighByte Intelligence Hub project as JSON and translate its connections, inputs, and outputs into a Connectware service commissioning file with the help of an AI assistant.

This guide shows you how to migrate a HighByte Intelligence Hub configuration to Connectware by exporting the project as JSON and translating it into a service commissioning file. Intelligence Hub stores its entire project as a single JSON file, which makes the connectivity layer a good candidate for AI-assisted translation. In more detail, the following topics are covered:

• Understanding how Intelligence Hub concepts map to Connectware resources

• Exporting the project as JSON, from the UI, the file system, or the Project API

• Translating the export into a service commissioning file with an AI assistant

• Reviewing the generated service commissioning file

• Verifying the migrated data points in the Data Explorer

A complete worked example, from JSON export to service commissioning file, is available at the end of this guide.

Prerequisites

To follow this guide, you will need the following:

• A running instance of Cybus Connectware with licenses for the connectors that replace your Intelligence Hub connections.

• Access to the Intelligence Hub configuration UI, the appData directory of the installation, or the Project API. This guide targets Intelligence Hub 4.x exports; differences to 3.x are noted where relevant.

• Network access from Connectware to the systems that Intelligence Hub currently reads from and writes to.

• An AI assistant to translate the export. Any capable large language model (LLM) works. Cybus Connectware GPT is a ChatGPT assistant that already knows the service commissioning file format.

• Basic knowledge of the Connectware services concept (for example, service commissioning files, connections, and endpoints).

How Intelligence Hub Concepts Map to Connectware

An Intelligence Hub project is organized in connections that own inputs and outputs, pipelines that move and transform events, and a modeling layer of models and instances. Connectware organizes connectivity in resources of a service commissioning file:

Intelligence Hub concept	Connectware resource	Notes
Connection	Cybus::Connection	One connection per Intelligence Hub connection, carrying the protocol settings from the uri and settings properties.
Input	Cybus::Endpoint	Inputs reference their connection by name and carry the address in the qualifier property.
Output	Cybus::Endpoint or Cybus::Mapping	MQTT outputs to the Unified Namespace become mapping topics on the Connectware broker; outputs to external systems become write endpoints.
Pipeline with Flow trigger	Cybus::Mapping	The trigger interval becomes the endpoint polling interval; On change trigger modes map to a Rule Engine cov rule.
Pipeline transform stages	Rule Engine	JSONata transform, filter, and cov rules cover common stages. JavaScript stages must be rewritten.
Model and instance	No direct equivalent	Connectware has no standalone modeling layer. Payload shaping is reproduced with JSONata transforms; schema validation is not.
Namespace / UNS client views	MQTT topic hierarchy	The topic structure on the Connectware broker is the namespace.

Mapping Connections to Connectors

The following Intelligence Hub connection types have a native Connectware counterpart:

Intelligence Hub connection	Connectware connector
OPC UA TCP	OPC UA Client
Modbus TCP	Modbus/TCP
MQTT	Integrated MQTT broker, or the MQTT connector for external brokers
Sparkplug	Sparkplug B Integration
Kafka	Kafka
REST Client	HTTP/REST
Microsoft SQL Server	MSSQL
MySQL, PostgreSQL, other JDBC	SQL
InfluxDB	InfluxDB

Intelligence Hub has no native Siemens S7 or EtherNet/IP connection: PLCs of these families are typically reached through an intermediary OPC UA server such as KEPServerEX. Connectware connects to S7, S7+, and EtherNet/IP devices natively, so a migration is an opportunity to remove the intermediary server for those devices. If you migrate such a setup, see also Migrating from Kepware KEPServerEX.

What Does Not Migrate 1:1

Intelligence Hub feature	Connectware approach
Models and instances	Reproduce payload shapes with JSONata transform rules in mappings. Type and schema validation has no equivalent.
JavaScript expressions and stages	Rewrite as JSONata rules, or move the logic to the Node-RED Workbench.
Buffer, file format, and Switch stages	No direct counterpart. burst rules cover simple buffering; file-based staging and content routing need redesign.
Store-and-forward settings	Handled differently: Connectware agents buffer data during connection loss.
Encrypted credentials	Passwords in Intelligence Hub exports are AES-encrypted and bound to the source installation. Collect credentials separately and pass them as parameters.
Cloud, historian, and AI connectors	Out of scope for the connectivity layer. Route data to these systems through the enterprise connectors or keep a reduced Intelligence Hub for them.

Exporting the Intelligence Hub Project

There are three equivalent ways to get the project JSON:

• UI export: Open Project > Export, select Full Project (or select individual objects), review the JSON on the Review Results tab, and click Download.

• File system: The running configuration is the appData/intelligencehub-configuration.json file. Timestamped backups of every change are in the appData/backups/ directory.

• Project API: Log in and download the export over REST:

TOKEN=$(curl -s -X POST "https://${HUB_HOST}:45245/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "${HUB_USER}", "password": "${HUB_PASSWORD}"}' | jq -r .token)

curl -s "https://${HUB_HOST}:45245/v1/project/export" \
  -H "Authorization: Bearer ${TOKEN}" -o intelligencehub-project.json

• ${HUB_HOST} is the hostname or IP address of the Intelligence Hub installation; 45245 is the default port.

• ${HUB_USER} and ${HUB_PASSWORD} are credentials of an Intelligence Hub user.

For details, see the Project Export and Project API documentation.

The export format follows the product version. Intelligence Hub 4.0 replaced flows with pipelines, so 3.x exports contain a flows array that 4.x exports do not. State your Intelligence Hub version when you hand the export to an AI assistant.

Translating the Export with an AI Assistant

Passwords in the export are encrypted, but connection URIs, usernames, topic structures, and expressions are readable. Review the export and remove anything sensitive before you paste it into an AI tool, and check the data privacy terms of the tool you use. See also the privacy notes for Cybus Connectware GPT.

Copy the following prompt and attach the project export:

AI translation prompt

You are translating a HighByte Intelligence Hub project export (JSON) into a
Cybus Connectware service commissioning file (YAML). Produce one complete,
valid service commissioning file with description, metadata, parameters,
definitions, and resources.

Structural rules:
- The export has "project.connections" (each with a "uri" and "settings"),
  "project.inputs" and "project.outputs" (each referencing their parent
  connection by name in the "connection" property), and "project.pipelines".
- Create one Cybus::Connection per Intelligence Hub connection that has a
  Connectware connector (OPC UA, Modbus TCP, MQTT to external brokers,
  Kafka, REST, SQL databases, InfluxDB). Parse host and port from the "uri".
- Create one Cybus::Endpoint per input, referencing its connection with
  !ref. For OPC UA inputs, build the nodeId from the qualifier:
  "ns=<namespaceIndex>;s=<identifier>" for identifierType "String",
  "ns=<namespaceIndex>;i=<identifier>" for "Numeric". Flag inputs with
  identifierType "Path" or types other than "Tag" for manual review.
- Polling: if the connection subscribes ("subscriptions.subscriptionRate"),
  convert the rate to milliseconds and use it as samplingInterval and
  publishInterval. If a pipeline Flow trigger polls the input, use the
  trigger interval instead. Trigger mode "On change" becomes a Rule Engine
  cov rule on the mapping.
- MQTT outputs that publish to the Unified Namespace become Cybus::Mapping
  entries publishing to the same topic on the Connectware broker. Outputs to
  external systems become write endpoints on the matching connector.
- Create one Cybus::Mapping that connects every input endpoint to its topic.
  If an output qualifier defines the topic, reuse it; otherwise mirror the
  input names, lowercase kebab-case.
- Credentials in the export are encrypted and unusable. Define every host,
  username, and password as a parameter. Do not include credential values.
- Models, instances, and JavaScript expressions do not translate. Where an
  instance shapes a payload from several inputs, generate a mapping with a
  JSONata transform rule that produces the same object shape, and flag it
  for review. List every model, instance, JavaScript expression, and
  unsupported pipeline stage at the end under "Not migrated".

After the YAML, output a migration report: number of connections, inputs,
and outputs translated, all assumptions made, and every flagged item that
needs manual review.

[Attach the Intelligence Hub project export JSON. State your Intelligence
Hub version.]

For large projects, use the selective export (Project > Export with individual objects or by tag) and translate one connection at a time.

Reviewing the Generated Service Commissioning File

Work through this checklist before installing:

1. Validate the file structure. The Cybus Connectware Extension for VS Code validates service commissioning files against the official schemas as you edit.

2. Check every connection against the original: host, port, and security settings. For OPC UA, match securityPolicy and messageSecurityMode to what the server actually offers.

3. Spot-check translated OPC UA NodeIds against an OPC UA browser, as described in Using Connectware as an OPC UA Client.

4. Review every generated JSONata transform against the original instance or pipeline logic.

5. Confirm that no credentials ended up in the file and that all site-specific values are parameters.

6. Compare the endpoint count against the migration report of the AI assistant and the input count of the project.

Installing the Service

1. Install the service commissioning file. See Installing Services.

2. Enable the service. See Enabling Services.

Result: Connectware connects to the migrated sources directly and the connections reach the Connected state.

For read-only validation, Connectware and Intelligence Hub can usually read the same sources at the same time, which allows you to compare live values before you switch consumers over. Check the session and connection limits of your OPC UA servers and devices first.

Verifying the Data

Open the Data Explorer and subscribe to the topics of the migrated service:

• Every migrated input publishes on its topic with plausible values.

• Values match between Intelligence Hub and Connectware for the same data point.

• Payload shapes produced by JSONata transforms match what the original instances produced. Compare a sample message from each system side by side.

• Data arrives at the expected rate.

Worked Example

The following export excerpt contains one OPC UA connection with one input, and an MQTT output that publishes to a Unified Namespace topic. The property names follow the Intelligence Hub 4.x export format:

intelligencehub-project.json (excerpt)

{
  "productInfo": {
    "company": "HighByte",
    "product": "IntelligenceHub",
    "version": "4.0.0"
  },
  "project": {
    "version": 9,
    "connections": [
      {
        "name": "Machine_OPC_UA",
        "uri": "opc.tcp://192.168.1.100:4840",
        "subscriptions": {
          "subscriptionRate": { "duration": 1, "units": "Seconds" }
        },
        "settings": {
          "security": "Basic256Sha256-SignEncrypt",
          "authentication": {
            "type": "Username_Basic256",
            "username": "opcua-user",
            "password": { "type": "Encrypted" }
          }
        }
      },
      {
        "name": "Plant_MQTT",
        "uri": "mqtt://192.168.1.10:1883",
        "settings": { "cleanSession": true, "ssl": false }
      }
    ],
    "inputs": [
      {
        "name": "CNC_Temperature",
        "connection": "Machine_OPC_UA",
        "type": "opc.tcp",
        "qualifier": {
          "namespaceIndex": 2,
          "identifierType": "String",
          "identifier": "Machines.CNC_1001.Temperature",
          "type": "Tag",
          "dataType": "Real32"
        }
      }
    ],
    "outputs": [
      {
        "name": "UNS_Publish",
        "connection": "Plant_MQTT",
        "type": "mqtt",
        "qualifier": { "topic": "site/area/line/cnc1001", "qos": 0 }
      }
    ]
  }
}

Applying the translation rules produces the following service commissioning file. The OPC UA connection keeps its security settings, the input becomes an endpoint with the NodeId ns=2;s=Machines.CNC_1001.Temperature sampled at the one-second subscription rate, and the MQTT output topic moves to the integrated Connectware broker. The Plant_MQTT connection itself needs no counterpart, because publishing to MQTT is what the mapping does natively:

highbyte-migration-example.yml

2KB

Open

highbyte-migration-example.yml

description: >
  Service commissioning file migrated from the Intelligence Hub connection
  Machine_OPC_UA with the input CNC_Temperature (Example)

metadata:
  name: HighByte Intelligence Hub Migration Example
  provider: cybus
  homepage: https://www.cybus.io
  version: 1.0.0

parameters:
  opcuaHost:
    description: Host of the connection Machine_OPC_UA
    type: string
    default: 192.168.1.100

  opcuaPort:
    description: Port of the connection Machine_OPC_UA
    type: integer
    default: 4840

  opcuaUsername:
    description: Username for the OPC UA server
    type: string
    default: ''

  opcuaPassword:
    description: Password for the OPC UA server (encrypted in the export, set on install)
    type: string
    default: ''

resources:
  # Intelligence Hub connection "Machine_OPC_UA"
  machineOpcuaConnection:
    type: Cybus::Connection
    properties:
      protocol: Opcua
      targetState: connected
      connection:
        host: !ref opcuaHost
        port: !ref opcuaPort
        username: !ref opcuaUsername
        password: !ref opcuaPassword
        options:
          securityPolicy: Basic256Sha256
          messageSecurityMode: SignAndEncrypt

  # Input "CNC_Temperature": subscription rate 1 second
  cncTemperature:
    type: Cybus::Endpoint
    properties:
      protocol: Opcua
      connection: !ref machineOpcuaConnection
      subscribe:
        nodeId: ns=2;s=Machines.CNC_1001.Temperature
        samplingInterval: 1000
        publishInterval: 1000

  # Output "UNS_Publish": topic moves to the integrated Connectware broker
  mapping:
    type: Cybus::Mapping
    properties:
      mappings:
        - subscribe:
            endpoint: !ref cncTemperature
          publish:
            topic: site/area/line/cnc1001/temperature

For all OPC UA connection and endpoint properties, see OPC UA Connection Properties and OPC UA Endpoint Properties.

Disclaimer: HighByte is a registered trademark of HighByte, Inc. Intelligence Hub is a product of HighByte, Inc. Cybus is not affiliated with HighByte, Inc.