Docs: Thing Type Editing

Mon, 01 Jan 0001 00:00:00 +0000

Thing-Types define the configuration for Edge Processing.

Top Level Configuration

Label: The label to use for the Thing-Type specification.
Is Active: If a Thing’s Thing-Type is not active (i.e. this option is deselected), the Thing’s data will not be aggregated and every message will be forwarded from the Gateway to the Cloud. It is not recommended to deactivate a Thing-Type that is assigned to Things, except for brief troubleshooting; otherwise, it could potentially result in higher costs and missed Alerts.
Sample Message: Used to auto-populate the Sensors section of the Thing-Type Specification.
Aggregate Type: Determines when to send the aggregated messages. It can be configured to “None”, “Seconds”, or “Count”.

None: Forward every message received from the device to the cloud.
Seconds: Aggregate the last N seconds of Thing data, where N is defined by the Aggregate Interval field.
Count: Aggregate the last N messages from a Thing, where N is defined by the Aggregate Interval field.

Aggregate Interval: Used in conjunction with the Aggregate Type field to determine the frequency of aggregation performed on the Gateway.
Offline Timeout (Seconds): Used to determine if a Thing is offline. If a device has not communicated in the time specified in this field, then an Offline Alert is sent to ServiceNow.

Sensor Settings

Include Undefined Sensors: When not selected any unrecognized sensor value(s) will be trimmed from the messages before processing
Enable Sensor Type Conversion: When selected the raw sensor values will be convereted into the Data Types specified below

Thing Type Record Page

Digital Twin Children

See the Digital Twins page for details on configuring this section.

Sensors

This section defines all the Sensors for the Thing-Type. Note if you have a sample message in JSON format, you can paste the message in the Sample Message field and select Parse to auto-fill the Sensors section.

Label: The display name of the sensor data on plots.
Sensor Name: The name of the field in the actual Thing’s data message.

Example

Sensor Name = sensorABC, expects a field like {... "sensorABC": 123, ...} to be in the data message from the Thing.

Data Type: Specifies the type of data expected from each Sensor.
Aggregate Function: Determines how the data is aggregated in the Gateway.

NONE: Use the last received value as the value for the Sensor for Calculations, Alerts, and Cloud updates.
SUM: Sum all values received during the Aggregate Interval as the value for the Sensor for Calculations, Alerts, and Cloud updates.
AVG: Average all values received during the Aggregate Interval as the value for the Sensor for Calculations, Alerts, and Cloud updates.
MIN: Use the minimum of all values received during the Aggregate Interval as the value for the Sensor for Calculations, Alerts, and Cloud updates.
MAX: Use the maximum of all values received during the Aggregate Interval as the value for the Sensor for Calculations, Alerts, and Cloud updates.

Context Fields

Context Fields are configured in the Context Data Setup Page.

ML Models

This section defines all the ML Models available on a Gateway. These Models have been developed by a Data Scientist and uploaded to the BDC IoT Cloud. NOTE: This section is only available on Gateway Thing Types.

See Machine Learning for more information.

Label: The label to use for the Calculated Field.
Model Name: The unique name of the model.
Input Features: The features required by this model. These will be mapped in the ML Inferences.
Model Parameters: Configuration values for the model itself.

ML Models

ML Inferences

This section defines all the ML Inference Fields for a Thing-Type. Each of these represent a result of executing an ML Model with a set of input values from IoT Sensors.

Label: The label to use for the ML Inference field.
Name: The name of the ML Inference field. It’s also the name referenced by other Calculations and Alerts.
Model: The ML Model (defined on the corresponding Gateway Thing Type) that will be executed.
Data Type: Determines the assumed data type for the result of the Calculation.
Formula: The mapping of Model Input Features to IoT Sensor values.

ML Inferences

Calculated Fields

This section defines all the Calculated Fields for a Thing-Type. All Sensor data is aggregated prior to computing the Calculated Fields. It can be assumed that all Sensor data is up-to-date in conformance with the aggregation settings defined by each Sensor.

Label: The label to use for the Calculated Field.
Field Name: The name of the field when this calculation is sent to the Cloud. It’s also the name referenced by other Calculations and Alerts.

Example

Field Name = calcABC results in {... "calcABC": 123, ...}, when data is sent to the Cloud and referenced as calculation.calcABC in other Calculations and Alerts.

Data Type: Determines the assumed data type for the result of the Calculation.
Formula: The actual formula to evaluate. The formula should be any Javascript statement that returns an assignable value. The formula can use any Sensor, Calculated Field, or Context Field in the computation. Sensor values are available in the sensor namespace (e.g. sensor.sensorABC), other Calculated Fields are available in the calculation namespace (e.g. calculation.calcABC), and Context Fields are available in the context namespace (e.g. context.contextABC).

Alert Conditions

This section defines all the Alert Conditions for a Thing-Type. Alerts are a special subset of Calculated Fields. Alerts are computed after all Calculated Fields have been computed, so it can be assumed that all Calculated Fields are using the most recent data. The result of the Alert calculation should be a boolean value, True if an Alert should be sent to ServiceNow, False otherwise.

Label: The label to use for the Alert Condition.
Condition Name: The name of the field when this alert is sent to the Cloud.

Example

Condition Name = alertABC results in {... "alertABC": 123, ...}, when data is sent to the Cloud.

Alert Type: Determines the type of Alert sent to ServiceNow. Each Alert sent to ServiceNow will include this Alert Type, which can be used in your Processes to take actions (like update the IoT Thing Status for a given Thing).
Alert Interval / Units: Determines how often this Alert is re-broadcasted. If the Alert condition has persisted longer than the amount of time specified by this field, the Alert will be sent to ServiceNow again to retrigger any automated processes. It is recommended to keep the Alert Interval at rather large values to avoid retriggering your processes.

Formula: The actual formula to evaluate. The formula should be a Javascript statement, and can use any Sensor or Calculated Field in the calculation. The formula should result in a boolean value; It will be evaluated as if it’s boolean — i.e. if the value is “falsy” it will result in no Alert. Otherwise it will result in an Alert. Sensor values are available in the sensor namespace (e.g. sensor.sensorABC), Calculated Fields are available in the calculation namespace (e.g. calculation.calcABC), Context Fields are available in the context namespace (e.g. context.contextABC), and other Alert Conditions are available in the alert namespace (e.g. alert.alertABC).

Examples

The formula, sensor.SensorA > 40 executes the relational operation, comparing SensorA to the literal 40. If this Condition Name was, DeviceThawed, then the resulting message to the Cloud could be:

{
 "sensor": {
  "SensorA": 39
 },
 "alert": {
  "DeviceThawed": false
 }
}

- OR -

{
 sensor: {
  "SensorA": 41
 },
 alert: {
  "DeviceThawed": true
 }
}

… with the later triggering an Alert with the defined Alert Type to ServiceNow. Anytime an Alert is sent to ServiceNow, the accompanying data message is included and can be used in your Flows. See the Processes section for more details.

The formula, calculation.CalcA === "Cold" executes the strictly-equal equality operator, comparing CalcA to the literal "Cold". If this Condition Name was, DeviceCold, then the resulting message to the Cloud could be:

{
 "sensor": {
  "SensorA": 39
 },
 "calculation": {
  CalcA: "Cold"
 },
 "alert": {
  "DeviceCold": true
 }
}

Sample Result: This field is automatically calculated based on the formula entered using the data provided in the sample message to populate the sensor and calculation namespaces.

Formula Editor

The Formula Editor Page now helps in writing formulas (both Calculated Fields and Alert Conditions). It allows the user to select data pills for any sensor, calculated field, digital twin value, function, or operator and copy them to the clipboard. The user can then paste the value anywhere in their formula field.

Formula Editor with Data Pills

Examples

The formula, sensor.SensorA + sensor.SensorB, will add the aggregated value of SensorA to the aggregated value of SensorB. If this Calculated Field name was CalcA, then the resulting message to the Cloud could be:

{
 sensor: {
  "SensorA": 40,
  "SensorB": 2
 },
 calculation: {
  "CalcA": 42
 }
}

The formula, (sensor.SensorA > 40) ? "Not Cold" : "Cold", will execute the Javascript ternary operator (basically an assignable if-else statement). If this Calculated Field name was ColdState, then the resulting message to the Cloud could be:

{
 sensor: {
  "SensorA": 39
 },
 calculation: {
  "ColdState": "Cold"
 }
}

- OR -

{
 "sensor": {
  "SensorA": 41
 },
 "calculation": {
  "ColdState": "Not Cold"
 }
}.

Sample Result: This field is automatically calculated based on the formula entered using the data provided in the sample message to populate the sensor and calculation namespace.

Docs: Thing Type Synchronizing

Mon, 01 Jan 0001 00:00:00 +0000

Thing Types definitions are stored in both ServiceNow and the IoT Cloud. You can update and Save them to ServiceNow, and choose when to “Push” them to the cloud. The “Last Modified” and “Last Synchronized” Dates help you to track their status.

Import New Thing Types…

From the main Thing Types screen, you can select the Import action to Import Thing Types from either the IoT Cloud or a local file into ServiceNow. There are two tabs, Remote Configurations and Upload File.

Remote Configurations

Note

This import brings the full details of the selected thing types and their dependencies stored on the IoT Cloud.

Thing Types Import

Thing Types Workspace Import

Upload File

Select a file saved using the Export action to import all of the thing types and their dependencies.

Note

This import brings the full details of the selected thing types and their dependencies stored on the local file.

Upload Thing Types

Export Thing Types

From the main Thing Types list page in the workspace, you can select thing types and click the Export action to save your thing types configurations to a local file. This file can be used to backup and move changes between instances.

Export Thing Types

Sync

Sync ∇ (Pull from the IoT Cloud)

When Editing a Thing Type, you can choose to Sync the full definition from the IoT Cloud into ServiceNow. This would typically be used if the Thing Type has been edited and you wish to rollback, or if you are setting up a new ServiceNow Instance but reusing a IoT Cloud org.

Sync Δ (Push to the IoT Cloud)

To deploy the latest Thing Type definition to the IoT Cloud (and the Edge Gateways), simply Sync the Thing Type.

Audit Trail (From the IoT Cloud)

To view the history of a Thing Type definition in the IoT Cloud, use the View History UI Action to view the Audit Trail.

Thing Type Audit Trail

Note

The View Detail button shows the detailed content behind each change
The Revert button will replace the Thing Type editor with the previous values. After reviewing the changes the user can then Save and Sync as they wish. This will not delete any records, including sensors, digital twin roles, alert conditions, calculated fields, context fields, ml models, and model interfaces. These records need to be deleted manually through any supported method in ServiceNow.

Bolt Data Connect – Thing Types

Docs: Thing Type Editing

Top Level Configuration

Sensor Settings

Digital Twin Children

Sensors

Example

Context Fields

ML Models

ML Inferences

Calculated Fields

Example

Alert Conditions

Example

Examples

Formula Editor

Examples

Docs: Thing Type Synchronizing

Import New Thing Types…

Remote Configurations

Note

Upload File

Note

Export Thing Types

Sync

Sync ∇ (Pull from the IoT Cloud)

Sync Δ (Push to the IoT Cloud)

Audit Trail (From the IoT Cloud)

Note