CreateUpdateInfo@1
Node CreateUpdateInfo@1 is used to create an update info object in the payload. Update info objects are used to track changes in the data for OctoMesh's Asset Repository and Time Series Repository.
- See ApplyChanges@1 for an example of how to use the update info object.
- See FilterLatestUpdateInfo@1 for an example of how to filter the latest update info object.
Adapter Prerequisites
Node Configuration
For fields path, targetPath, targetValueWriteMode, and targetValueKind, see Overview.
transformations:
- type: CreateUpdateInfo@1
targetPath: _updateItems # Path where the update info object should be stored in the payload
targetValueKind: Array # The target value kind, should be an array to store multiple update info objects
targetValueWriteMode: Append # The target value write mode, should be 'Append' to add the update info object to the array
updateKind: UPDATE # The update kind, should be 'UPDATE' to indicate an update, other options are 'INSERT'
rtId: 5fc8fda18b2fc75f925e21af # The runtime ID of the asset that should be updated, if updateKind is 'UPDATE'
rtIdPath: $.assetId # The path to the runtime ID in the payload, any valid JSON path is allowed. This property can be defined instead of the rtId property
rtWellKnownNamePath: $.Name # the path to the runtime well known name in the payload; this property has an index in the database
ckTypeId: Industry.Energy/Photovoltaic.Module # The CK type ID of the asset that should be updated, if updateKind is UPDATE
timestampPath: $.timestamp # The path to the timestamp in the payload, any valid JSON path is allowed
attributeUpdates: # The attribute updates that should be applied to the asset, multiple updates are allowed
- attributeName: PeakPower # The name of the attribute that should be updated
attributeValueType: Double # The value type of the attribute that should be updated
valuePath: $.productionPower # The path to the value in the payload, any valid JSON path is allowed
value: "demo" # A constant value that should be used. This property can be defined instead of the valuePath property
Example Using Enum
The following shows a basic example of how to use the CreateUpdateInfo@1 to initialize an Enum.
transformations:
- type: CreateUpdateInfo@1
targetPath: _updateItem
updateKind: INSERT
ckTypeId: EnergyCommunity/Customer
attributeUpdates:
- attributeName: InvoiceCycle
attributeValueType: Enum
value: Monthly # When defining the value for a Enum ensure that you are using the "name" property the "key" will not be recognised
Atomic Update of One RecordArray Item (recordArrayItemUpdates)
recordArrayItemUpdates changes single records of a RecordArray attribute in one atomic database update, without reading the entity first. Use it when several pipeline executions change different records of the same entity at the same time (for example one state per data point of a Control, delivered by FromPipelineDataEvent@1 to several consumers in parallel).
The read-modify-write pattern (GetRtEntitiesByType@1 → UpdateRecordArrayItem@1/@2 → attributeUpdates with the whole array → ApplyChanges@2) is not safe under parallel executions: every execution writes back the whole array it read, so a change made in the meantime by another execution is overwritten and lost. With recordArrayItemUpdates only the named members of the matched record are written; other records, other members and changes of parallel executions stay untouched. If two executions change the same record, the last write wins (correct for a value snapshot).
transformations:
- type: CreateUpdateInfo@1
targetPath: $._updates
targetValueKind: Array
updateKind: UPDATE # only UPDATE is supported
ckTypeId: Loxone/Control
rtIdPath: $.controlRtId
recordArrayItemUpdates:
- attributeName: States # RecordArray attribute of the entity
matchAttributeName: ExternalId # record member that identifies the record (String, Integer, Integer64 or Enum)
updatesPath: $.states # optional: one item update per element of this array; paths below are relative to the element
matchValuePath: $.pollUuid # or matchValue: <static value>
attributeUpdates: # members of the matched record to write
- attributeName: CurrentValue
valuePath: $.value # or value: <static value>; "=now()" is the current UTC time
- attributeName: LastUpdate
value: =now()
- type: ApplyChanges@2
entityUpdatesPath: $._updates
| Field | Description |
|---|---|
attributeName | The RecordArray attribute of the entity |
matchAttributeName | The record member that identifies the record. It cannot be written by the same entry |
matchValue / matchValuePath | The key of the record to change (compared as text and converted to the type of the key member). matchValuePath takes precedence |
updatesPath | Optional. JSON path to an array: one item update per element, matchValuePath and the valuePath of the attribute updates are relative to the element (like UpdateRecordArrayItem@2). Without it the paths address the payload |
attributeUpdates | attributeName plus valuePath or value. Scalar members only (String, Integer, Integer64, Double, Boolean, DateTime, DateTimeOffset, TimeSpan, Enum). A path without a value writes null (an error for a mandatory member) |
Behavior:
- The engine checks every entry against the Construction Kit before it writes: an unknown attribute or member, a value that does not fit the member's type, an attempt to write the key member and every
Secretmember are refused with a message that names the type, the attribute and the member. Nothing is written. - If no record matches (or the entity does not exist), nothing is written (no version change) and
ApplyChanges@2logs one warning; the pipeline continues. If several entries are sent and only some match, the others are skipped silently. - Several updates of the same entity in one
ApplyChanges@2call are merged; all item updates are kept in order, for the same record the last value wins. attributeUpdatesfor other attributes may be combined withrecordArrayItemUpdatesin the same node; they are written in the same statement. Updating the whole array of the same attribute in the same update is refused as ambiguous.- The entity must already hold the array. The permissions are those of an ordinary update of the entity.
- Display name rules that reference the
RecordArrayare not recomputed by an item update (the entity is not read).