Distribution – byNeuron

Distribution definitions are configured on timeseries definition. It defines the strategy how ingested events are distributed to new events.

There are 2 strategies:

Linear distribution The value of an event is distributed equally for a specified interval

Profiled distribution: The value of an event is distributed according to a configured profile for a specified interval

💡

Important note: distribution uses the timestamp and a to date of an event, to determine the period over which the event value need to be distributed.

General configuration

Property	Description
strategy	`required` `linear` or `profile`. Defines the strategy of distributing.
interval	`required` `15min`, `day`, `week`, `month`, `year` (no default) Need to be smaller or equal to the period to be distributed.
fractionalDigits	`0-15` (default: `6`) How many digits the distributed values should have, any rest value will be added up on the value of last distributed event.
keepOriginal	Whether or not to keep the original value after distribution (default: `true`). When `true`, the distributed event will contain a reference to the original event. The original event will have the code, eventOrigin: `ORIGINAL` and the distributed event will have the code, eventOrigin: `DISTRIBUTED`.
indexSetCodes	Index set codes can be automatically set on the distributed events by specifying a `type` and `code`. The codes must exist.
keyValueSets	Key value sets can be automatically set on the distributed events by specifying a `key` and `values`.
profileConfig	Required when strategy is `profile`.

Profile configuration

The profile configuration consists of 2 ways to identify the profile which need to be used.

Predefined, by referencing an external ID of a timeseries

Dynamically, by specifying a 'path' of a relation to retrieve the profile timeseries

Additionally there are 2 properties which are taken into account when specifying the relation. This is because a relation is timesliced and some situations need be handled:

usage: What to do when multiple different profiles are identified over a period?

nullifyInactiveProfiles: What to do with inactive profiles (meaning inactive gaps in timeslices)?

usage

Used to determine what to do with multiple profiles.

option	Description
`lastOnly`	The last profile is used for for the whole period (this is default behavior).
`lastAndRedistribute`	In a first step the last profile is used for for the whole period, then in a second step for the sub periods where another profile was present the sum is taken for that sub period and redistributed according to the old profile.

nullifyInactiveProfiles

Used to determine what to do with inactive profiles.

option	Description
`true`	The distribution values are set to 0. This has a serious implication that there will be a mismatch between the value to distribute and the sum of redistributed values!!
`false`	The distribution according to the last known profile is left intact.

Error handling

When an event can not be distributed, error codes with the reason are stored on the original event.

Error codes

Code Type: eventDistributionError

Code	Description
CALENDAR_DATA_INCOMPLETE
CALENDAR_ERROR
PERIOD_TOO_SMALL	Event can not be distributed because the period is too small for the specified interval
PROFILE_DATA_INCOMPLETE	Profile data is missing data for interval periods
PROFILE_ERROR
PROFILE_NOT_ACTIVE	For the period there are not active profiles related
PROFILE_NOT_FOUND	Profile can not be found for the period and within the context of the timeseries
REMOVE_FAILED
ROUNDING_ERROR
STRATEGY_NOT_SUPPORTED_ERROR
TO_DATE_NOT_FOUND	To date is needed to determine the period over which the value is distributed

Example

"distributionDefinition": {
	"strategy": {
		"type": "profile",
		"profileConfig": { 
			"timeseriesExternalId": "E1B" 
			"relation": { 
				"entityType": "ItemAccessPointRelation",
				"hasTarget": "AccessPoint",
				"targetRole": "accessPointRole#METERING_POINT",
				"hasSource": "Item",
				"sourceRole": "itemRole#PROFILE"
			},
			"usage": "lastAndRedistribute", 
			"nullifyInactiveProfiles": false 
		}
	},
	"interval": "day",
	"fractionalDigits": 2,
	"keepOriginal": true,
	"indexSetCodes": [
		{
			"type": "someCodeType",
			"code": "SOME_CODE"
		}
	],
	"keyValueSets:": [
		{
			"key": "someKey",
			"value": "someValue"
		}
	]
}