> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-2/guides/migration/migrating-from-highbyte-intelligence-hub.md). # Migrating from HighByte Intelligence Hub 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](/2-4-2/data-flows/service-commissioning-files.md). 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](/2-4-2/monitoring/data-explorer.md) 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](/2-4-2/tools/cybus-connectware-gpt.md) is a ChatGPT assistant that already knows the service commissioning file format. * Basic knowledge of the Connectware [services](/2-4-2/data-flows/services.md) concept (for example, [service commissioning files](/2-4-2/data-flows/service-commissioning-files.md), [connections](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md), and [endpoints](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md)). ## 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](/2-4-2/data-flows/service-commissioning-files/resources/cybus-connection.md) | One connection per Intelligence Hub connection, carrying the protocol settings from the `uri` and `settings` properties. | | Input | [Cybus::Endpoint](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md) | Inputs reference their connection by name and carry the address in the `qualifier` property. | | Output | [Cybus::Endpoint](/2-4-2/data-flows/service-commissioning-files/resources/cybus-endpoint.md) or [Cybus::Mapping](/2-4-2/data-flows/service-commissioning-files/resources/cybus-mapping.md) | 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](/2-4-2/data-flows/service-commissioning-files/resources/cybus-mapping.md) | The trigger interval becomes the endpoint polling interval; `On change` trigger modes map to a Rule Engine `cov` rule. | | Pipeline transform stages | [Rule Engine](/2-4-2/data-flows/rule-engine.md) | 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](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client.md) | | Modbus TCP | [Modbus/TCP](/2-4-2/connectors/shop-floor-connectors/modbus-tcp.md) | | MQTT | Integrated MQTT broker, or the [MQTT connector](/2-4-2/connectors/enterprise-connectors/mqtt.md) for external brokers | | Sparkplug | [Sparkplug B Integration](/2-4-2/guides/system-connectivity/industry-standards-interoperability/sparkplug-b-integration.md) | | Kafka | [Kafka](/2-4-2/connectors/enterprise-connectors/kafka.md) | | REST Client | [HTTP/REST](/2-4-2/connectors/enterprise-connectors/http-rest.md) | | Microsoft SQL Server | [MSSQL](/2-4-2/connectors/enterprise-connectors/mssql.md) | | MySQL, PostgreSQL, other JDBC | [SQL](/2-4-2/connectors/enterprise-connectors/sql.md) | | InfluxDB | [InfluxDB](/2-4-2/connectors/enterprise-connectors/influxdb.md) | 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](/2-4-2/connectors/shop-floor-connectors/siemens-simatic-s7.md), [S7+](/2-4-2/connectors/shop-floor-connectors/siemens-simatic-s7-plus.md), and [EtherNet/IP](/2-4-2/connectors/shop-floor-connectors/ethernet-ip.md) 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](/2-4-2/guides/migration/migrating-from-kepware-kepserverex.md). ### 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](/2-4-2/data-flows/node-red-workbench.md). | | 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](/2-4-2/data-flows/agents.md) 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: {% code lineNumbers="true" %} ```bash 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 ``` {% endcode %} * `${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](https://guide.highbyte.com/configuration/administration/project/export/) and [Project API](https://guide.highbyte.com/configuration/administration/project/project_api/) documentation. {% hint style="info" %} 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. {% endhint %} ## Translating the Export with an AI Assistant {% hint style="warning" %} 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](/2-4-2/tools/cybus-connectware-gpt.md#data-privacy). {% endhint %} Copy the following prompt and attach the project export: {% code title="AI translation prompt" lineNumbers="true" expandable="true" %} ``` 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=;s=" for identifierType "String", "ns=;i=" 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.] ``` {% endcode %} 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](/2-4-2/tools/cybus-connectware-extension-vs-code.md) 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](/2-4-2/guides/system-connectivity/industry-standards-interoperability/using-connectware-as-an-opc-ua-client.md). 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-4-2/data-flows/services/managing/installing.md). 2. Enable the service. See [Enabling Services](/2-4-2/data-flows/services/managing/enabling.md). **Result:** Connectware connects to the migrated sources directly and the connections reach the **Connected** state. {% hint style="info" %} 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. {% endhint %} ## Verifying the Data Open the [Data Explorer](/2-4-2/monitoring/data-explorer.md) 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: {% code title="intelligencehub-project.json (excerpt)" lineNumbers="true" expandable="true" %} ```json { "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 } } ] } } ``` {% endcode %} 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: {% file src="/files/i8FeMB3ayEzKpDNNOhfp" %} {% code title="highbyte-migration-example.yml" lineNumbers="true" expandable="true" %} ```yaml 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 ``` {% endcode %} For all OPC UA connection and endpoint properties, see [OPC UA Connection Properties](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client/opcuaconnection.md) and [OPC UA Endpoint Properties](/2-4-2/connectors/shop-floor-connectors/opc-ua/opc-ua-client/opcuaendpoint.md). {% hint style="info" %} Disclaimer: HighByte is a registered trademark of HighByte, Inc. Intelligence Hub is a product of HighByte, Inc. Cybus is not affiliated with HighByte, Inc. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cybus.io/2-4-2/guides/migration/migrating-from-highbyte-intelligence-hub.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.