Getting Started: Dynamic References and Parameterization

This article applies to HighByte Intelligence Hub version 4.2 and later. For version 4.1 and earlier, please see this article.

What Does This Article Cover?

• What is a Dynamic Reference?
• Dynamic Reference Example
• What is Parameterization?
• Parameterization Example

Example Project

Download Example Project Here

This example project contains pre-configured examples of dynamic referencing and parameterization. It can be downloaded and imported into Intelligence Hub. It relies primarily on HighByte Intelligence Hub’s integrated MQTT broker. The MQTT broker must be enabled for this example to function. More information about that broker is available on the HighByte User Guide and Knowledge Base. It can be observed using the UNS Client.

Dynamic References

Often times, configurations cannot be hard-coded in Intelligence Hub. This may be the case when certain logic may be necessary on a data payload to determine to which destination data should be written. Consider, for example, a pipeline where a data payload contains a reference to which MQTT topic should be written. In that case, a mechanism to inject a piece of the payload data into the infrastructure configuration.

Dynamic references allow this behavior. Pieces of data payloads (events) can be extracted and used in configurations using “handlebar notation”.

The “Handlebars” refer to the set of double curly-braces surrounding an expression. This expression is evaluated usually a piece of the event in question. For example, in a pipeline configuration, some stages would allow accessing a piece of the active event by entering “” in the configuration. This may be helpful in determining which topic to write to in MQTT with a “WriteNew” stage. In the example configuration above, the pipeline “Dynamic_Reference” uses a Transform stage to create some random numbers as data and as a topic. This pipeline also contains a WriteNew stage that uses that “topic” attribute to write to one of two MQTT topics by using a dynamic reference in the topic field of the stage.

DynamicRef/

It should be noted that a dynamic reference of would also have worked here. “this” is a contextual reserved work that refers to event.value in the pipeline context.

Parameterization

Dynamic references allow extraction of information from context. Sometimes, however, it is not immediately apparent that data can be extracted and injected into another Intelligence Hub element, but these things can often be built to accept parameters, and parameters can be filled by dynamic references.

For instance, consider the opposite of the above problem: It could be advantageous to read from one MQTT topic or another depending on some pipeline data. But the read stage does not have a field where a topic is defined. An input can still be established that will read depending on a topic, but configuration starts at the input.

The example configuration contains the connection “Internal MQTT with the input “arbitraryTopic”. To configure this input, a parameter must be designated in the parameters menu. This will be the name of the variable to be passed in with a parameter.

Then, the parameter may be used in the input with in handlebar notation. Note the ‘topic’ parameter is now displayed in the “Parameters” box.

In this case, “this” refers to the object that has been passed into the input from the connection call. That configuration will come next. This input won’t work on its own, it will require that a topic be provided. If a default value is provided in the parameter configuration (optional), that value will be used if a parameter is not provided. In this example, an entire path is generated, but it is entirely possible to hard-code a portion of the path, and to supply only a portion from a parameter.

The pipeline “Parameterized_Input” contains a transform stage that creates a string for one of two MQTT topic paths: “dataTopics/t1,” or “dataTopics/t2.” This is committed to the event, and then in the next read stage, the arbitratyTopic input was configured as the data source and a box appears reflecting the parameter defined in the input. This box can be filled with a dynamic reference to the topic generated in the transform stage.

This example demonstrates an input with a single parameter, but many could be configured. This may be helpful in generating semi-rigid but still complex paths like:

Home//location/center//

Each parameter should be defined in the parameters menu and filled out with the reference.

Parameters in Instances and Strings

References - GUI

Instances are able to both receive and export parameters. They have the same parameters definition menu, and when they call references directly, they have the same parameter menu to fill. They can even pass the parameter they receive into the parameter they require. Instances also use the handlebar notation where “this” refers to the object they have been passed. In the example project, the instance “Reference_Instance” demonstrates using parameters in an instance.

Scrolling down…

This instance will need to be read while supplying the parameter “parameter,” which it will then pass to the arbitraryTopic MQTT input as “topic.”

Expressions - Stringified

However, when using an instance with the “Expression” expression type, connection references aren’t displayed with a graphical user interface (GUI); instead, they have a “stringified” format. It is certainly still possible to ship parameters to the connection by placing a JSON object of the format

{“parameter1”:”value1”,”parameter2”:”value2”}

Within the handlebars of a reference, after the text, within parenthesis. This object may be built on-the-fly within the connection, or built prior and injected.

)}}

In the example project provided, another instance – “Expression_Instance” - provides similar functionality as “Reference_Instance,” but uses Expression Mode instead. This may be valuable if additional javascript logic must be executed.

Above is a fairly complicated set of references producing a single input. One interesting fact to consider is that references are resolved before any code is executed, and results replace handlebar expressions directly. Note that

Additionally, it is possible to construct an object to pass as the set of parameters, but this won’t always work in an instance.

Because handlebar expressions are resolved before any code is executed, it would not be feasible to construct an object within the instance because that construction would occur after the connection reference has already been resolved.

Other related material:

• Dynamic references (User Guide)
• Parameterization (User Guide)
• Templating (User Guide)