Cloud Integrations Expressions

Cloud Datum Stream Mapping Property entities can be configured as a dynamic expression that can perform a calculation on the acquired cloud data values. For example, imagine a Cloud Datum Stream acquires a datum with properties like this:

{
    "created": "2024-11-13 04:20:00Z",
    "nodeId": 123,
    "sourceId": "test/meter",
    "i": {
        "voltage_a": 287.652,
        "voltage_b": 287.652,
        "voltage_c": 287.318
    }
}

Here the meter has provided 3-phase voltage properties, but you would like the overall voltage as well, on a voltage property. You can use an expression property to do that, like this:

{
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage",
    "valueType": "s",
    "valueReference": "round(rms({voltage_a, voltage_b, voltage_c}), 1)"
}

The valueType value s means Spel Expression and the valueReference value is the actual expression. In this example, a rms() function is passed the three phase voltage values to calculate the root-mean-square value, which is then passed to round() to round the result to at most one decimal place.

After the expression is evaulated, the resulting datum then looks like this:

{
    "created": "2024-11-13 04:20:00Z",
    "nodeId": 123,
    "sourceId": "test/meter",
    "i": {
        "voltage_a": 287.652,
        "voltage_b": 287.652,
        "voltage_c": 287.318,
        "voltage":   287.5
    }
}

Spel Syntax

"Spel" stands for Spring Expression Language. See the Spring Expression Language Syntax guide for more details.

The Cloud Datum Stream expression support is very similar to SolarNode Datum Expressions. Expressions can refer to datum properties directly, and many helper functions are provided.

ExpressionRoot object

Some functions return ExpressionRoot objects. An ExpressionRoot object supports all the properties and functions described in this guide.

Properties

The following properties are available:

Property	Type	Description
node	NodeInfo	A NodeInfo object, for node datum streams only. This can be used to obtain the node's time zone, for example.

NodeInfo object

The NodeInfo object has the following properties:

Property	Type	Description
nodeId	long	A node ID.
userId	long	The ID of an account owner.
country	String	The ISO 3166-1 alpha 2-character country code associated with the node, for example NZ.
zone	ZoneId	The time zone associated with the node. Useful with date time functions, for example now(node.zone) will return the current node-local time.

Functions

The following sections detail the functions that are available to Cloud Datum Stream expressions.

Bit functions

The same bitwise integer manipulation functions provided in SolarNode are available.

Date time functions

The same date time functions provided in SolarNode are available.

Datum stream functions

Often Cloud Datum Streams acquire multiple datum at once, for example multiple datum for a single datum stream over time, or multiple datum streams, or both. The following functions make it possible to perform calculations that draw from values in any of the available datum streams.

For example, imagine a Cloud Datum Stream that collects two datum streams, one from a weather station and another from a PV inverter. You could configure an expression on the PV inverter stream that uses data from the weather stream, perhaps a calculation of the expected PV generation based on the weather conditions. Here's a contrived example that multiplies a "cloudiness" percentage collected by the weather station by a pre-computed expected output rate provided by a tariff schedule in the node's metadata:

latest('weather').cloudiness
* resolveNodeTariffScheduleRate('/pm/modelled-output', now(node.zone))

For another example, imagine a Cloud Datum Stream that collects many PV inverter datum streams, with source IDs like inv/1, inv/2, and so on. You could use an expression to sum up the total combined output of all inverter watts properties like this:

sum(latestMatching('inv/*').![watts])

💡 Keep in mind that only datum from the active cloud service data request will be available.

Datum stream test functions

The following functions test the availability of datum matching certain criteria. Generally they are each closely associated with a datum stream query function.

Function	Arguments	Result	Description
hasLatest(source)	String	boolean	Returns true if latest(source) returns a value.
hasLatestMatching(pattern)	String	boolean	Returns true if latestMatching(pattern) returns a non-empty result.
hasOffset(offset)	int	boolean	Returns true if offset(offset) returns a value.
hasOffset(source, offset)	String, int	boolean	Returns true if offset(source,offset) returns a value.
hasOffsetMatching(pattern, offset)	String, int	boolean	Returns true if offsetMatching(pattern, offset) returns a non-empty result.

Datum stream query functions

Function	Arguments	Result	Description
latest(source)	String	ExpressionRoot	Provides access to the latest available datum matching the given source ID, or null if not available. This is a shortcut for calling offset(source,0).
latestMatching(pattern)	String	ExpressionRoot[]	Return a collection of the latest available datum matching a given source ID wildcard pattern. This is a shortcut for calling offsetMatching(pattern,0).
offset(offset)	int	ExpressionRoot	Provides access to a datum from the same stream as the current datum, offset by offset in time, or null if not available. Offset 1 means the next earlier datum with the same source ID as this datum, and so on.
offset(source, offset)	String, int	ExpressionRoot	Provides access to an offset from the latest available datum matching the given source ID, or null if not available. Offset 0 represents the "latest" datum, 1 the one before that, and so on.
offsetMatching(pattern, offset)	String, int	ExpressionRoot[]	Return a collection of datum matching a given source ID wildcard pattern, each offset by offset in time. Offset 0 represents the "latest" datum, 1 the next earlier, and so on.

Math functions

The same math functions provided in SolarNode are available.

Node metadata functions

Node metadata can be accessed with the following functions:

Function	Arguments	Result	Description
nodeMetadata()		MetadataOperations	Returns a MetadataOperations object for the metadata associated with the datum's node ID. For location datum this returns null.
nodeMetadata(path)	String	Object	Extract the value at a metadata key path on the metadata associated with the datum's node ID. For location datum this returns null.
nodeTariffSchedule(path)	String	TariffSchedule	Extracts a TariffSchedule object from node metadata at a given path. For location datum this returns null.
resolveNodeTariffScheduleRate( path, date, rateName)	String, LocalDateTime, String	Object	Resolve a tariff schedule rate from node metadata at a given path, date, and tariff rate name. For location datum this returns null. The date and rateName arguments are optional. If no date is given then the current time in the UTC time zone will be used. If no rateName is given then the first-available resolved rate will be returned.

Metadata operations

A MetadataOperations object provides the same properties and functions as SolarNode Datum metadata.

Tariff schedules

A TariffSchedule object represents a set of time-based criteria with associated tariffs. A tariff in this scheme is nothing more than a set of one or more number values, each with an associated name. See the SolarNode TariffSchedule object functions guide for details on the properties and functions that are avaialble on a TariffSchedule object.

Property functions

The same property functions provided in SolarNode are available.