Tutorial: Connections

Jump to Section

What Does This Tutorial Cover?

A Connection represents a pathway to either a data source or a target, serving as the starting point for all use cases.

Tutorial Prerequisites
Tutorial Preparation
Tutorial Instructions
Tutorial Summary

Tutorial Prerequisites

You have completed the initial Installation of the Intelligence Hub
You have applied your Intelligence Hub license to your environment
It is recommended to read the Getting Started Series before completing this tutorial exercise

Tutorial Preparation

Enable Intelligence Hub MQTT broker
- In the left-hand navigation panel, navigate to Manage, and click Settings
- Under the MQTT Broker section enable the broker, if ports 1885 and 1886 are in use on the server hosting your Intelligence Hub, update to ports of your choosing, otherwise accept the defaults and click save

Import the required Connections

In the left-hand navigation panel, navigate to Manage, and click Project
Within the Import screen, ensure Full Project is off (otherwise your existing project will be overwritten)

Change the Import Type to JSON and paste the following code block into the Project box and click the import button

{
	"productInfo": {
		"company": "HighByte",
		"product": "IntelligenceHub",
		"version": "3.2.0",
		"build": "2023.8.24.982",
		"stage": "Alpha"
	},
	"project": {
		"version": 5,
		"connections": [
			{
				"name": "Tutorial_CMMS_servicelogs",
				"uri": "jdbc.sqlserver://52.10.6.4:1433",
				"tags": [
					"Tutorial"
				],
				"writes": {
					"flattenModeledValues": false
				},
				"storeForward": {
					"enabled": false,
					"maxEntries": 100,
					"waitOnFailureInterval": {
						"duration": 1,
						"units": "Seconds"
					}
				},
				"settings": {
					"database": "serviceinfo",
					"username": "highbyte"
				}
			},
			{
				"name": "Tutorial_MQTT",
				"uri": "mqtt://0.0.0.0:1885",
				"tags": [
					"Tutorial"
				],
				"writes": {
					"flattenModeledValues": false
				},
				"storeForward": {
					"enabled": false,
					"maxEntries": 100,
					"waitOnFailureInterval": {
						"duration": 1,
						"units": "Seconds"
					}
				},
				"settings": {
					"connectionTimeoutSeconds": 10,
					"keepAliveSeconds": 60,
					"requestTimeoutMS": 5000,
					"cleanSession": true,
					"ssl": false,
					"redundantBrokers": [],
					"inputDiscovery": ""
				}
			},
			{
				"name": "Tutorial_OPC_UA",
				"uri": "opc.tcp://52.10.6.4:49320",
				"tags": [
					"Tutorial"
				],
				"writes": {
					"flattenModeledValues": false
				},
				"subscriptions": {
					"subscriptionRate": {
						"duration": 1,
						"units": "Seconds"
					}
				},
				"storeForward": {
					"enabled": false,
					"maxEntries": 100,
					"waitOnFailureInterval": {
						"duration": 1,
						"units": "Seconds"
					}
				},
				"settings": {
					"security": "None",
					"authentication": {
						"type": "Anonymous"
					},
					"connectTimeoutSeconds": 5,
					"requestTimeoutMS": 5000,
					"maxItemsPerRead": 512,
					"maxItemsPerWrite": 256,
					"certificateKeyPair": "app-certificate-private-key",
					"sessionName": ""
				}
			}
		],
		"inputs": [
			{
				"name": "Tutorial_All_Assets",
				"connection": "Tutorial_CMMS_servicelogs",
				"type": "jdbc.sqlserver",
				"qualifier": {
					"query": "select * from [dbo].[cmms_servicelogs]"
				},
				"cacheLifetime": {
					"enabled": false
				}
			}
		],
		"outputs": [],
		"modeling": {
			"models": [],
			"instances": []
		},
		"flows": [],
		"conditions": [],
		"functions": [],
		"tags": [],
		"pipelines": []
	},
	"network": {
		"groups": [],
		"hubs": []
	}
}

Expand Collapse

Update the imported Connections as required
- Navigate to Configure and click Connections, Click Tutorial_MQTT and Update the MQTT settings as required based on the prior preparation step #1
- Navigate to Configure and click Connections, Click “Tutorial_CMMS_servicelogs” and type the following within the password field
```
                          password
```
- Click Save
Setup UNS Client
- In the left-hand navigation panel, navigate to Tools and right click UNS client and open Link in New Tab
- Enter login information
- For Connection select Tutorial_MQTT
- For Subscribed Topics remove the default wildcard entry # and Subscribe to Topic Tutorial/#
- Click Add
- Click Connect and confirm UNS client says “Connected to Tutorial_MQTT”
- Return to the previous tab

Instructions

Login to your Intelligence Hub environment
Reviewing our first connection
- Navigate to Connections
- Select Tutorial_OPC_UA
  - Note: the status will be in “Not Connected” state until an Input or Output is executed
- The Connection should be operational as is, take note within the Overview screen that you have several protocol specific settings
  - OPC UA subscription mode & rate -> Reference User Guide for more information
  - Timeout and read settings -> Useful for tailoring read/write size and general performance optimization
Add our first Input
- Within the Tutorial_OPC_UA Connection navigate to Inputs
  - Take note of the three options of import (Browse, CSV Import and New Input), as a general best practice, using the Browse button is preferred to minimize the manual setting entries
- Click browse
- Navigate to the identifier “Tutorial”
- Click CNC_Fanuc_1001
  - Take note you can select individual tags or Select all
- Select all 23 items
- Click Import Selected
Review the our first Input
- Click Return to Inputs
- Open any tag
  - Take note all settings were imported via the Browse
- Click Test Input to confirm connectivity and view the current tag value
- Open the References panel within the right panel
  - Take note that any configured objects within the Intelligence Hub are browsable from this panel
- Within the References panel, set type to “Input”
- Set Connections to Tutorial_OPC_UA
- Find the Input you opened and take note of the object’s shape
Now we will change the shape of the object and explore additional input settings
- Within the Input settings click Enabled “Include Metadata”
- Click save
- Click Test Input to review the results
  - Note Include Metadata is a common setting you can expect to find in many protocols, this enables you to easily utilize additional source metadata within the Intelligence Hub
- Within the References panel, take note of the object’s structure, you should notice it’s gone from a simple object of 1 value to a complex object of many values
Add a second Input
- Click on Inputs
- Click Browse
- Click the + sign next to Tutorial
- Click Import Selected
Review the new Input
- Open the Tutorial Input
  - Take note this has imported as a different Input type: Branch
- Review the two key Branch settings:
  - Max Branch Depth: How many levels under the specified Identifier you want to read in
  - Cache Interval: How often the branch structure is refreshed (Important for capture changes or new additions under the branch
- Click Test input and review the results
- Within the References panel navigate to your Tutorial branch and review the branch’s structure
  - Note the Branch has multiple assets under it, the base Input has an array of multiple objects with individual tags under each object
Output branch data to the UNS Client
- Navigate to Connections
- Select Tutorial_MQTT
- Click Outputs
- Click New Output
- Enter the following and click create
```
Name: Tutorial_Branch_Output
Topic: Tutorial/Branch
Retain: On
```
- Let’s utilize the Test Write and write a basic string to this Topic, within the Expression to write, enter “Test” and click Write Out
- Review the results in your UNS client
Create a flow to send source branch data
- Navigate to Flows
- Click New Flow
- Enter “Tutorial_Branch_Flow” for name
- Click next
- Within the Sources & Target view, use the References Panel and set Type to Input
- Set Connections to Tutorial_OPC_UA
- Drag your branch “Tutorial” to the Sources panel
- Change Type to Output
- Set Connections to Tutorial_MQTT
- Drag the Tutorial_Branch_Output to the Targets panel
- Click next
- Change your interval to 10 seconds
- Click enable and click submit
- Review results in your UNS client
Work with our second connection
- Navigate to Connections
- Open Tutorial_CMMS_servicelogs
- Review Overview screen and take note of the common settings with a SQL connection
- Navigate to Inputs
- Open Tutorial_All_Assets
  - NOTE: Generally performing select * statements are not a best practice for performance reasons
- Click Test Input and review the results from the Results and Reference Panels
  - NOTE: In the References panel you can see this input is returning an array of data
Create a new input
- Within the Tutorial_All_Assets input, click the clone icon in the upper right corner of the Input view
- Enter “Tutorial_CNC_Assets” as the new Input’s name
Utilize the Object Explorer and add additional logic to the new input
- Update your query from “select * from [dbo].[cmms_servicelogs]” to “select * from [dbo].[cmms_servicelogs] where "
- Click “Open” next to the Object Explorer to browse the default database schema
- Using the Object Explorer click cmms_servicelogs
- Using the Object Explorer map “asset_type” to your query
- Type “ = ‘CNC’ "
- Click Test Input and review the results from the Results and Reference Panels

Tutorial Summary

This exercise focused on the basics of working with Connections. You should be more familiar with navigation and interworking of Connections. We covered basic principals of building Inputs and Outputs. We covered how to use the Reference Panel and Test Inputs to see common starting structures of Inputs: Single values, Complex Objects and Arrays. The upcoming Tutorials will build upon these basic principals.

Tutorial: File Connections