SolarNet API global objects

SolarNetwork API Global Objects

This page documents objects used throughout the SolarQuery, SolarIn, and SolarUser APIs.

Object	Description
General response	A general response structure used by most API methods.
Date parsing	How SolarNetwork parses date and time values in API requests.
Date formatting	How SolarNetwork formats date and time values in API responses.
Datum	The fundamental time-stamped data structure collected by SolarNetwork.
Datum samples	The measurement fact data structure collected by SolarNetwork.
Datum auxiliary	Special events associated with a time-stamped data stream.
Datum stream	A collection of datum with a common identifier over time.
Device operating states	Standarized device operating state enumeration.
Location	Location information.
Sky conditions	Standarized atmospheric sky conditions enumeration.
Metadata	Common metadata structure associated with users, nodes, and data streams.
Metadata filter	Common metadata search filter syntax.
Order by	Request parameter used for queries that support ordering of the results.
Security policy	Rules and constraints for security tokens.
Wildcard patterns	Wildcard syntax used in security policies and various queries.
Setting specifier	API for UI metadata.
User application event	Application event associated with user accounts.

General response

Many SolarNet API methods return a general result object with the following standard properties:

Property	Type	Description
success	boolean	Indicates if the request was processed successfully.
message	string	An optional message, often used to convey an error message when success is false.
code	string	An optional error code included sometimes when success is false.
data	any	The optional response data, specific to the API method.

Note that additionally properties might be provided by specific API methods. A trivial example response looks like this, in JSON:

{
  "success" : true,
  "data": {}
}

Date parsing

When parsing dates in API requests, times, and timestamps (date + time) in SolarNetwork API requests, the following syntaxes are used. Consult specific API method documentation for what form(s) are supported. The syntax patterns used here are those as defined in the Java DateTimeFormatter class.

⚠️ Note that unless otherwise noted, the .SSS pattern means milliseconds of second and exactly 3 digits must be provided. This is different from how API responses format dates. See Date formatting for details.

Type	Syntax	Example	Description
Date	yyyy-MM-dd	2022-02-24	A year/month/day date without any time zone.
Time	HH:mm:ss.SSS	14:30:15.387, 14:30	An hour/minute/second time without any time zone. Some APIs accept values without seconds and/or fractional seconds.
Timestamp	yyyy-MM-dd HH:mm:ss.SSS	2022-02-24 14:30:15.387, 2022-02-24 14:30	A date + time without any time zone, or an API-defined implicit UTC time zone. Some APIs accept values without seconds and/or fractional seconds.
Epoch timestamp	64-bit integer	1645713015387	The number of milliseconds since the Unix epoch of midnight 1 Jan 1970, UTC.
Period	ISO-8601	P1Y2M3W4D, P4W	A date-based amount of time in the ISO-8601 calendar system.

Date formatting

When rendering dates, times, and timestamps (date + time) in SolarNetwork API responses, the following syntaxes are used. Consult specific API method documentation for what form(s) are supported. The syntax patterns used here are those as defined in the Java DateTimeFormatter class.

⚠️ Note that the .SSS pattern means fractional seconds and may contain anywhere between 1 to 9 digits. The entire fraction may be omitted when equal to 0. This is different from how API requests parse dates. See Date parsing for details.

Type	Syntax	Example	Description
Local date	yyyy-MM-dd	2022-02-24	A year/month/day date without any time zone.
Local time	HH:mm:ss.SSS	14:30:15.387345, 14:30	An hour/minute/second time without any time zone.
Local timestamp	yyyy-MM-dd HH:mm:ss.SSS	2022-02-24 14:30:15.387345, 2022-02-24 14:30	A date + time without any time zone. Some APIs accept values without seconds and/or fractional seconds.
Timestamp	yyyy-MM-dd HH:mm:ss.SSSZ	2022-02-24 14:30:15.387345Z	A date + time in a specific time zone. Usually the UTC time zone is used, which may be abbreviated to the literal Z character.
Epoch timestamp	64-bit integer	1645713015387	The number of milliseconds since the Unix epoch of midnight 1 Jan 1970, UTC.
Period	ISO-8601	P1Y2M3W4D, P4W	A date-based amount of time in the ISO-8601 calendar system.

Datum

The datum is the fundamental time-stamped data structure collected by SolarNodes and stored in SolarNetwork. It has a flexible structure with the following core properties:

Property	Type	Description
nodeId	number	A unique ID assigned to nodes by SolarNetwork.
sourceId	string	A node-unique identifier that defines a single stream of data from a specific source, up to 64 characters long. Certain characters are not allowed, see below.
created	date	A time stamp of when the datum was collected, or the date the datum is associated with.
samples	datum samples	The measurements.

A datum is uniquely identified by the three combined properties (nodeId, sourceId, created).

Datum source IDs

Source IDs are arbitrary strings used to distinguish different sources of data within a single node. For example, a node might collect data from an energy meter on source ID Meter and a solar inverter on Solar. SolarNetwork does not place any restrictions on source ID values, other than a 64-character limit. However, there is are some conventions used within SolarNetwork that are useful to follow, especially for larger deployment of nodes with many source IDs:

• Use as short as possible IDs, for example Meter1 is better than Schneider ION6200 Meter - Main Building.
• Use a path-like structure to encode a logical hierarchy, in least specific to most specific order. For example /S1/B1/M1 could imply the first meter in the first building on the first site.
• The + and # characters should not be used. This is actually a constraint in the MQTT protocol used in parts of SolarNetwork, where the MQTT topic name includes the source ID. These characters are MQTT topic filter wildcards, and cannot be used in topic names.
• Avoid using wildcard special characters.

The path-like structure becomes useful in places where wildcard patterns are used, like security policies or datum queries. It is generally worthwhile to spend some time planning on a source ID scheme to use when starting a new project with SolarNetwork.

Datum samples

The datum object contains a datum samples structure within it that holds the measurements obtained for a datum. A datum sample is a collection of named properties, for example:

{
	"watts": 123,
	"wattHours": 987654321,
	"mode": "auto"
}

Datum property classifications

Internally, the properties are further organized into three classifications: i for instantaneous, a for accumulating, and s for status. These classifications help SolarNetwork understand how to aggregate the datum samples over time. When SolarNode uploads a datum to SolarNetwork, the sample will include the classification groups. The previous example would thus more accurately be represented like this:

{
	"i": {
		"watts": 123
	},
	"a": {
		"wattHours": 987654321
	},
	"s": {
		"mode": "auto"
	},
	"t": [
		"online"
	]
}

Normally you won't have to deal with these classifications, however, as SolarNetwork hides them when returning datum data through the SolarQuery API. You might come across them in some SolarNode plugins that allow configuring dynamic sample properties to collect, when SolarNode can't implicitly know which classification to use. Some APIs do, however, require fully classified sample objects, like those dealing with datum auxiliary objects.

Standard property names

Although SolarNetwork allows for arbitrary property names in the datum samples it collects, there are several standard property names that you should consider using when appropriate.

Standard general properties

Property	Units	Classif.	Description
opState		s	A standardized device operating state code.
opStates		s	A bitmask of hardware-specific operating state code values.

Standard energy properties

Property	Units	Classif.	Description
apparentPower	VA	i	An apparent power reading, in volt-amperes.
current	A	i	An electric current reading, in amperes.
dcPower	W	i	A DC power reading, in watts.
dcVoltage	V	i	A DC electric potential reading, in volts.
effectivePowerFactor	VA	i	An effective power factor reading.
frequency	Hz	i	An AC frequency, in hertz.
lineVoltage	V	i	An AC phase electric potential reading, between two phases, in volts.
neutralCurrent	A	i	A neutral current reading, in amperes.
phase		s	An AC phase value, one of: PhaseA, PhaseB, PhaseC, Total.
phaseVoltage		i	An AC phase electric potential reading, one phase and neutral, in volts.
powerFactor		i	A power factor reading.
reactivePower	var	i	A reactive power reading, in reactive volt-amperes.
voltage	V	i	An electric potential reading, in volts.
wattHours	Wh	a	An energy reading, in watt-hours. For example a "lifetime" accumulating value from a power meter or PV inverter.
watts	W	i	A real or active power reading, in watts.

Standard atmospheric properties

Property	Units	Classif.	Description
atm	Pa	i	Atmospheric pressure, in pascals
co2	PPM	i	CO2 level, in parts per million.
dew	°C	i	A dew point, in degrees Celsius.
humidity	%	i	A relative humidity as an integer percentage (0 - 100).
irradiance	W/m2	i	Solar irradiance, in watt per meter squared.
lux	lx	i	Luminous flux per meter squared (light intensity).
sky		s	A textual description of the sky conditions, e.g. "clear", "cloudy".
skies		s	A bitmask of standardized sky condition codes.
temp	°C	i	A temperature, in degrees Celsius.
visibility	m	i	A visibility distance, in meters.

Datum auxiliary

Datum auxiliary records represent special events that occur at a specific point in time for a specific node and datum source. The record contains a final property that holds the final data associated with the datum source at the event date, and a start property that holds the starting data. These records are used by some SolarQuery API methods when calculating differences in a datum source between two points in time.

Property	Type	Description
created	string	The event date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone. Note that when posting this value may also be specified as a millisecond epoch number value.
nodeId	number	The node ID.
sourceId	string	The source ID.
type	string	The datum auxiliary type.
updated	string	The record last modified date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone.
notes	string	A comment to include that describes the event record.
final	object	A general datum sample representing the final data associated with the datum immediately before the created date.
start	object	A general datum sample representing the starting data associated with the datum at the created date.
meta	object	An optional metadata object for client application use.

Note that both the final and start general datum sample objects currently support only the accumulating (a) property set.

Here's an example datum auxiliary object used for a Reset event, where a meter was replaced so that the energy reading went from 12345789 in the old meter to 123 in the new meter, expressed as JSON:

{
  "success": true,
  "data": {
    "created": "2019-02-06 18:35:50.943Z",
    "nodeId": 11,
    "sourceId": "Foo",
    "type": "Reset",
    "updated": "2019-02-06 18:35:51.165Z",
    "notes": "Meter replaced.",
    "final": {
      "a": {
        "wattHours": 123456789
      }
    },
    "start": {
      "a": {
        "wattHours": 123
      }
    },
    "meta": {
      "m": {
        "foo": "bar"
      }
    }
  }
}

Datum auxiliary within datum stream

It helps to think of datum auxiliary records as part of the stream of data represented by their associated datum source. Imagine a datum stream where a meter is replaced. There will be a gap in time between meter readings while the meter is removed and then replaced, and the readings drop back to nearly zero once readings are captured again from the new meter. This scenario would like this:

Date	Reading (Wh)	Difference Prev
2014-03-01 19:53:17	5631504	0
2014-03-01 19:53:18	5631518	14
2014-03-01 21:02:30	44555	-5586963
2014-03-01 19:53:18	44567	12

If we want to know the overall amount of energy reported by this meter, adding the Difference Prev column yields

0 + 14 - 5,586,963 + 12 = -5,586,937 Wh

This is obviously not correct. Let's add a datum auxiliary record for the meter replacement, like this:

Date	Final Reading (Wh)	Starting Reading (Wh)
2014-03-01 20:00:00	5632000	0

Now we can merge that record with the original datum stream, resulting in a "split" stream:

Date	Reading (Wh)	Difference Prev
2014-03-01 19:53:17	5631504	0
2014-03-01 19:53:18	5631518	14
2014-03-01 20:00:00	5632000	496

Date	Reading (Wh)	Difference Prev
2014-03-01 20:00:00	0	0
2014-03-01 21:02:30	44555	44555
2014-03-01 19:53:18	44567	12

Adding up the Difference Prev column of both portions of the split stream yields

0 + 14 + 496 + 0 + 44,555 + 12 = 45,077 Wh

That is a much better answer.

Datum stream

Internally SolarNetwork stores datum in a stream format, where a stream is uniquely identified by the combination of an object ID and a source ID. An object ID can be either a node ID or a location ID. Each stream is assigned a unique stream ID by SolarNetwork, the first time a datum is stored with an object and source ID combination that does not exist in SolarNetwork yet.

Over time, some SolarNetwork APIs have been developed to make use of datum streams for more efficient use of resources, such as reducing the bandwidth required to post datum to SolarIn.

Datum stream kind

A datum stream has an associated kind that what the stream's object ID represents. The kind appears in APIs in coded form, defined by this table:

Kind	Code
Node	n
Location	l

Datum stream metadata

SolarNetwork automatically maintains some metadata about each datum stream. The metadata includes the stream, object, and source IDs, the stream kind, a location, and a list of datum property names for each datum property classification. SolarNetwork maintains the datum property lists automatically, and will add new names to the end but will never remove a value or change the list order.

Property	Type	Description
streamId	UUID String	The stream's unique ID, assigned by SolarNetwork.
objectId	Long	A node or location ID.
sourceId	String	A unique identifier assigned by users.
zone	String	A time zone identifier associated with the stream's location.
kind	String	A datum stream kind code value that identifies the type of stream.
location	Object	An optional set of properties describing the stream's location.
i	Array<String>	An ordered list of instantaneous datum properties names, as seen by SolarNetwork.
a	Array<String>	An ordered list of accumulating datum properties names, as seen by SolarNetwork.
s	Array<String>	An ordered list of status datum properties names, as seen by SolarNetwork.

Here is an example of the metadata for a datum stream, in JSON form:

{
  "streamId": "a66e3344-3791-4113-afff-22b44eb3c833",
  "objectId": 123,
  "sourceId": "meter/a",
  "zone": "Pacific/Auckland",
  "kind": "n",
  "location": {
    "country": "NZ",
    "region": "Wellington",
    "locality": "Wellington",
    "zone": "Pacific/Auckland"
  },
  "i": ["current","voltage","watts"],
  "a": ["wattHours"],
  "s": ["status"]
}

Stream datum

A stream datum is a datum that contains the datum sample property values without any description of what the values represent. Because it only holds the datum property values, it is usually necessary to obtain the stream's metadata to be able to interpret the meaning of the data.

Index	Type	Description
0	Long	The datum timestamp, in milliseconds since the epoch.
1	Long	The stream ID, upper 64 bits.
2	Long	The stream ID, lower 64 bits.
3	Array<Decimal>	The instantaneous property values, or null.
4	Array<Decimal>	The accumulating property values, or null.
5	Array<String>	The status property values, or null.
6	Array<String>	The tags, or null.

Here's an example stream datum using the same a66e3344-3791-4113-afff-22b44eb3c833 stream example shown in the datum stream metadata section, in JSON form. Note the stream ID values are shown in unsigned form:

[
  1623110379000,
  11992579225817268499,
  12681893233508468787,
  [13.4,240.0,3216.0],
  [585092900],
  ["overtemp"],
  ["error"]
]

Here's that same stream datum, this time showing the stream ID values as signed values:

[
  1623110379000,
  -6454164847892283117,
  -5764850840201082829,
  [13.4,240.0,3216.0],
  [585092900],
  ["overtemp"],
  ["error"]
]

When combined with the example datum stream metadata, this stream datum can be expressed as a general datum in JSON form like this:

{
  "created":  "2021-06-07 23:59:39.000Z",
  "nodeId":   123,
  "sourceId": "meter/a",
  "i": {
    "current": 13.4,
    "voltage": 240.0,
    "watts":   3216.0
  },
  "a": {
    "wattHours": 585092900
  },
  "s": {
    "status": "overtemp"
  },
  "t": ["error"]
}

Standard device operating states

The following values represent a standarized set of operating states for devices, typically devices being monitored by nodes:

Name	Code	Description
Unknown	0	An unknown state.
Normal	1	Normal operating state.
Starting	2	A startup/initializing state.
Standby	3	A standby/low power state.
Shutdown	4	A shutdown/off state.
Fault	5	A faulty state.
Disabled	6	A disabled state.
Recovery	7	A recovery state.
Override	8	An overridden state.

Location

A location represents a physical place. Each node has a location associated with it, and location datum streams have a location associated with them. A location has the following properties, but only country and timeZoneId are required to be present:

Name	Type	Description
country	string	A standard 2-character country code.
timeZoneId	string	A time zone identifier.
region	string	A region identifier.
stateOrProvince	string	A state or province name.
locality	string	A locality (city) name.
postalCode	string	A postal code.
street	string	A street address.
latitude	number	A decimal latitude value.
longitude	number	A decimal longitude value.
elevation	number	An elevation, in meters.

⚠️ Note that when querying location data generally only details up to the postalCode property is returned. Full details are only available for the locations associated with your own nodes.

Standard sky conditions

The following values represent a standarized set of sky conditions:

Name	Code	Description
Clear	1	Clear sky.
ScatteredClouds	2	Scattered/few clouds.
Cloudy	3	Mostly cloudy.
Fog	4	Fog.
Drizzle	5	Drizzle/light rain.
ScatteredShowers	6	Very occasional/light rain.
Showers	7	Occasional/light rain
Rain	8	Mostly rain.
Hail	9	Hail.
ScatteredSnow	10	Occasional/light snow.
Snow	11	Mostly snow.
Storm	12	Storm.
SevereStorm	13	Servere storm.
Thunder	14	Thunder/lightning storm.
Windy	15	Windy.
Hazy	16	Hazy.
Tornado	17	Tornado.
Hurricane	18	Hurricane.
Dusty	19	Dust/sand storm.

Metadata

In SolarNetwork metadata can be associated with the following items:

• users
• nodes
• node datum sources
• node datum auxiliary

Metadata objects share a common structure across all these items:

Property	Type	Description
m	object	An arbitrary object data structure. Traditionally this was meant to be used as a single-level key/value pair style object.
pm	object	An arbitrary object of objects data structure. Traditionally this was meant to be used as a true multi-level tree of key/value pairs and values.
t	array	An array of strings to be treated as a set of tags. Duplicate values are discarded.

For each associated object type, typically unique ID, creation date, and modification date properties are also available. For example a node metadata object includes a nodeId property.

Metadata example

Here's an example metadata object, expressed as JSON:

{
	"created" : "2016-11-11 07:57:46.561Z",
	"updated" : "2016-11-13 19:31:53.225Z",
	"m" : {
		"building" : "Warehouse",
		"room"     : "Office"
	},
	"pm" : {
		"hours": {
			"M-F"   : "08:00-18:00",
			"Sa-Su" : "10:00-14:00"
		},
		"managers": {
			"John" : "john@example.com",
			"Jane" : "jane@example.com"
		}
	},
	"t" : [
		"operations",
		"red"
	]
}

Metadata filter

Some API method accept a metadata filter string, which is written much like a LDAP search filter. In its simplest form a filter is composed of a key path, a comparison operator, and a value, enclosed in parentheses, like this:

(t=operations)

Here the key path is t, the comparison operator is =, and the value is operations. The filter could be described as find metadata with a tag equal to "operations". More complex filters can be formed by joining two or more of this basic form with a logic operator, like this:

(&(t=operations)(m/room=Office))

Here the logic operator is & which stands for a logical and operation. The filter could be described as find metadata with a tag equal to "operations" AND a "room" property equal to "Office".

Metadata filter comparison operators

The supported comparison operators are:

Operator	Description
=	Exact equality match.
<	Less than; numerically when applied to number values or lexicographically when applied to strings.
<=	Less than or equal to; numerically when applied to number values or lexicographically when applied to strings.
>	Greater than; numerically when applied to number values or lexicographically when applied to strings.
>=	Greater than or equal to; numerically when applied to number values or lexicographically when applied to strings.
~=	Regular expression match; patterns follow the JavaScript regular expression syntax.

Metadata filter logic operators

The supported logic operators are:

Operator	Description
&	Logical "and"
|	Logical "or"
!	Logical negation, or "not"

Metadata filter key paths

The key path of each component in a metadata filter is a URL-like path starting at the root of the metadata object. Path separators represent descending into nested objects. A leading / is assumed, and can be omitted if desired. Using the example metadata object above, here are the key paths available:

Key path	Value
/created	2016-11-11 07:57:46.561Z
/updated	2016-11-13 19:31:53.225Z
/m/building	Warehouse
/m/room	Office
/pm/hours/M-F	08:00-18:00
/pm/hours/Sa-Su	10:00-14:00
/pm/managers/John	john@example.com
/pm/managers/Jane	jane@example.com
/t	Array of [operations, red]

For array property values such as the /t path, all values in the array are considered for matching.

Metadata filter key path wildcards

A special ** path segment may be used in a key path, which represents 0 or more segments of any name. The last path segment may be specified as * which represents any property name. Here are some examples of wildcards using the same example metadata:

Key path	Matching paths
/m/*	/m/building, /m/room
/pm/hours/*	/pm/hours/M-F, /pm/hours/Sa-Su
/**/John	/pm/managers/John
/**/managers/*	/pm/managers/John, /pm/managers/Jane

Order By parameter

Some API methods support sorting the result with an orderBy request parameter. This parameter is a comma-delimited list of sort keys, any of which can have a ~ character appended to make the sort on that key in descending order. The left-to-right order of the key values define the ordering of the results such that the results are sorted by the left-most key first, then each subsequent key that follows.

Each API method that supports this parameter will define the sort key values that can be used in that method.

Example

An example URL query string to sort by id in ascending order then creation in descending order:

?orderBy=id,creation~

Security Policy

Security policy objects can be associated with security tokens. In general security policies are permissive by default, and are configured with rules that restrict access. A policy object contains the following items:

Parameter	Type	Description
apiPaths	array of strings	A list of API URL paths to restrict access to. API paths represent SolarNetwork API URL paths, starting after the /pub or /sec path segment. Wildcard patterns are permitted. Access to a particular API is allowed as long as some path pattern matches. A path can start with ! to negate the path so that paths that do not match are allowed. If not specified, all paths are allowed.
minAggregation	string	A minimum datum aggregation type to restrict access to. If not specified, all levels of aggregate data are allowed, including raw data.
nodeIds	array of numbers	A list of node IDs the policy restricts access to. If not specified, all nodes associated with the token's account are allowed.
nodeMetadataPaths	array of strings	A list of node metadata paths to restrict access to. Wildcard patterns are permitted. The metadata structure is treated like a path using object keys as path segment names. If not specified, all node metadata is allowed.
notAfter	string	A timestamp in ISO 8601 timestamp format in the UTC time zone, after which the token is not valid, for example 2020-02-01 20:12:34.
refreshAllowed	boolean	If refreshing this token is allowed, then applications given a signing key rather than the token's private password can refresh the key as long as the token has not expired.
sourceIds	array of strings	A list of datum source IDs the policy restricts access to. Wildcard patterns are permitted. Access to a datum source implies access to any associated datum source metadata. If not specified, all source IDs associated with the token's account are allowed.
userMetadataPaths	array of strings	A list of user metadata paths to restrict access to. Wildcard patterns are permitted. The metadata structure is treated like a path using object keys as path segment names. If not specified, all user metadata is allowed.

Wildcard patterns

Wildcard patterns are used in places like security policies, metadata queries, and datum queries. The values a wildcard pattern is compared to are treated like URL paths, using / as path delimiters. The text between the path delimiters are called path segments. The following special characters can be used in wildcard patterns:

Special	Description
?	Match a single character in a path segment.
*	Match zero or more characters in a single path segment.
**	Match zero or more path segments.

Wildcard pattern examples

Here are some example source ID wildcard patterns and how they would be interpreted, using the following source IDs:

• /power
• /power/meter
• /power/meter/1
• /switch/1
• /switch/2
• /switch/3/a
• /switch/3/b
• /basement/bedroom/lights
• /basement/bedroom/heater
• /basement/tvroom/lights
• /basement/tvroom/heater
• /ground/dining/lights

Pattern	Matches
/power/**	/power, /power/meter, and /power/meter/1
/power/*	/power/meter
/**/1	/power/meter/1 and /switch/1
/**/lights	/basement/bedroom/lights, /basement/tvroom/lights, and /ground/dining/lights
/basement/**/lights	/basement/bedroom/lights, /basement/tvroom/lights

Here are some example metadata wildcard patterns and how they would be interpreted, using the following metadata object:

{
	"m" : {
		"building" : "Warehouse",
		"room"     : "Office"
	},
	"pm" : {
		"hours": {
			"M-F"     : "08:00-18:00",
			"Sa-Su"   : "10:00-14:00",
			"holiday" : {
				"M-F"     : "09:00-17:00",
				"Sa-Su"   : "Closed"
			}
		},
		"managers": {
			"John" : "john@example.com",
			"Jane" : "jane@example.com"
		},
		"building" : {
			"floors"    : 3,
			"employees" : 48
		}
	}
}

Pattern	Matches
/m/*	/m/building, and /m/room
/**	everything
/pm/hours/*	/pm/hours/M-F and /pm/hours/Sa-Su
/**/building/**	/m/building, /pm/building/floors, and /pm/building/employees

Setting specifier

Some SolarNetwork APIs return lists of setting specifier objects, which are metadata objects that describe the configurable properties of a service. When calling an API method that uses such a service, the request can include parameters for the described settings. Applications can also use the settings to render a friendly UI for accessing the service.

For example, imagine an API /upload that requires credentials to upload data somewhere. SolarNetwork could expose an API like /upload/settings that returns information about what the supported settings are, like this:

[
	{
	  "type": "net.solarnetwork.settings.TextFieldSettingSpecifier",
	  "key": "username",
	  "defaultValue": "",
	  "secureTextEntry": false
	},
	{
	  "type": "net.solarnetwork.settings.TextFieldSettingSpecifier",
	  "key": "password",
	  "defaultValue": "",
	  "secureTextEntry": true
	}
]

This result informs the caller that username and password parameters are used. Thus invoking the API might look like /upload?username=foo&password=bar.

Basic setting specifier properties

Property	Type	Description
key	string	The name of the configurable setting.
type	string	The type of data entry the setting represents.

Setting specifier types

The supported setting types are:

Type	Description
net.solarnetwork.settings.TextFieldSettingSpecifier	A simple string setting.
net.solarnetwork.settings.ToggleSettingSpecifier	A boolean on/off setting.

Setting specifier - TextField

The TextField setting specifier is designed for text and password form elements.

Property	Type	Description
secureTextEntry	boolean	Toggle secure setting mode. See notes below.

When the secureTextEntry property is true the setting is treated as a secure setting and a password form element should be used when rendering the setting into a UI form. API endpoints that return secure setting property values will only return a cryptographic digest of the actual value. When posting a form that includes a secure setting, the setting value can be omitted, left blank, or left as its original digest value to leave the property value unchanged; otherwise the setting value will be updated to whatever is submitted.

Setting specifier - Toggle

The Toggle setting specifier is designed for on/off or yes/no type form elements.

Property	Type	Description
trueValue	boolean,number,string	The value that should be used to represent a true or enabled setting value.
falseValue	boolean,number,string	The value that should be used to represent a false or disabled setting value.

The trueValue and falseValue properties are often literal boolean true and false values. However that might be specified as numbers (e.g. 1 and 0) or strings (e.g. "yes" and "no"). When posting toggle setting values with a form submission, the values specified in the setting must be used.

Localized setting specifiers

Some responses include a localizedInfoMessages response object that provides localized descriptions of setting specifiers or service descriptions. The locale of the response is determined by the Accept-Language HTTP header passed on the request. If not provided, the default locale of the SolarNetwork service will be used, which is en (English).

The localizedInfoMessages objects contains pairs of localized messages for each setting specifier key value returned in the same response. The localized message pairs are in the form X.key (a title) and X.desc (a longer description) where X is a setting specifier key. For example, a response might look like:

{
  "id": "net.solarnetwork.central.datum.export.standard.CsvDatumExportOutputFormatService",
  "locale": "en-NZ",
  "settingSpecifiers": [
	{
	  "key": "includeHeader",
	  "defaultValue": true,
	  "trueValue": true,
	  "falseValue": false,
	  "transient": false,
	  "type": "net.solarnetwork.settings.ToggleSettingSpecifier"
	}
  ],
  "localizedDescription": "Export data in comma separated values (spreadsheet) format.",
  "localizedInfoMessages": {
	"includeHeader.key": "Include Header",
	"includeHeader.desc": "Toggle the inclusion of a CSV header row."
  },
  "localizedName": "CSV"
}

A single includeHeader setting is defined for this service. The localizedInfoMessages object thus defines the title for that setting via includeHeader.key (Include Header) and a description via includeHeader.desc (Toggle the inclusion of a CSV header row.).

User application event

SolarNetwork generates application events related to user accounts, and adds them to a queryable event stream. Each event contains a set of tags that identify the type of event, and data properties related to the event. SolarNetwork maintains events for a minimum of 1 year before deleting them. The structure of the events is like this:

Property	Type	Description
created	string	The event creation date, in yyyy-MM-dd HH:mm:ss.SSS'Z' format in the UTC time zone. ⚠️ Note that the SSS fractional seconds supports microsecond precision (up to 6 decimal digits).
eventId	string	A unique ID for the event.
userId	number	The ID of the user account associated with the event.
tags	array<string>	An array of tags.
msssage	string	Optional description of the event.
data	object	Optional event-specific properties.

A JSON example of a user application event looks like this:

{
  "userId": 123,
  "created": "2022-08-09 03:03:28.533452Z",
  "eventId": "0182808e-a615-7712-bd86-80acee3b28cd",
  "tags": [
    "ocpp",
    "message",
    "received"
  ],
  "data": {
    "cp": "1234ZY",
    "action": "Heartbeat",
    "messageId": "rukjys5f8q9fjce8x79kl4is"
  }
}

User application event types

The following tables detail the type of events SolarNetwork generates.

OCPP user application events

The possible OCPP event data properties are shown below (not all events contain all properties):

Property	Type	Example	Description
action	string	Heartbeat	The OCPP action (message type).
cp	string	1234ZY	A charge point identifier.
error	string	Invalid syntax.	An error description.
errorCode	string	FormationViolation	An OCPP error code.
errorDescription	string	Invalid message payload.	A description of the OCPP error.
errorDetails	string	The DataTransfer message was not valid.	Details of the OCPP error.
message	object	{"status":"ACCEPTED"}	A JSON OCPP message payload.
messageId	string	rukjys5f	The ID of the OCPP message.

The following table lists the possible OCPP events:

Name	Tags	Properties	Description
Charge point connected	ocpp, charger, connected	cp	A charge point has successfully connected to SolarNetwork.
Charge point disconnected	ocpp, charger, disconnected	cp	A charge point has disconnected from SolarNetwork.
Charge point instruction sent	ocpp, instruction, sent	action, cp, message	SolarNetwork has sent an OCPP instruction to a connected charge point.
Charge point instruction error	ocpp, instruction, error	error	An error occurred sending an OCPP instruction to a charge point.
OCPP message received	ocpp, message, received	action, cp, message, messageId	SolarNetwork received an OCPP message from a charge point.
OCPP message sent	ocpp, message, sent	action, cp, message, messageId	SolarNetwork sent an OCPP message to a charge point.
OCPP message sent error	ocpp, message, sent, error	cp, error, errorCode, errorDescription, errorDetails, messageId	SolarNetwork sent an error response to a charge point.

Security user application events

The possible security event data properties are shown below (not all events contain all properties):

Property	Type	Example	Description
email	string	example@example.com	The email address associated with the authentication.
roles	array<string>	["ROLE_BILLING","ROLE_OCPP","ROLE_USER"]	List of security roles associated with the account.
token	string	doidij40439rj4943u94094j	The security token associated with the authentication.

The following table lists the possible OCPP events:

Name	Tags	Properties	Description
Authentication success	security, auth, success	email†, roles, token†	A user has successfully authenticated to SolarNetwork.
Authentication logout	security, auth, logout	email†, roles, token†	A user has successfully logged out of SolarNetwork.

^† The availability of this property depends on the nature of the event.