Apis Foundation 9

The AEClient module has the following item types

OPC AEItem

HiddenItem

StatusItem

Properties

The AEClient module has the following properties:

Name	Description	ID	Flags
Active	FALSE, if the Event Subscription is to be created inactive.	1050	Persisted
BufferMax Size	The requested maximum number of events that will be sent in a single callback. A value of 0 means that there is no limit to the number of events that will be sent in a single callback.	1031	Persisted, ExpertPage
BufferTime	The buffer time (in milliseconds) tells the server how often to send event notifications. A value of 0 means that the server should send event notifications as soon as it gets them.	1030	Persisted, ExpertPage
CmnItemIDPrefix	Common source ItemId prefix. This string will prefix each item's 'ItemID' when communicating with the OPC AE server. Items in this module will have names without this prefix in the Apis namespace.	1011	Persisted, ExpertPage
Computer	The computer hosting the OPC server. Leaving it blank, the localhost will be used.	1001	Persisted, Computer
FilterArea	Events and conditions available in the server are organized within one or more process areas. An Area is a grouping of the plant.	1044	Persisted, ExpertPage
FilterCategory	The categories supported by a given event type	1041	Persisted, ExpertPage
FilterEventType	The filter criteria supported by the connected event server.	1040	Persisted, Enumerated
FilterSeverityHigh	The severity high, indicates the highest severity of interest. This is also commonly called 'priority', especially in relation to process alarms.	1043	Persisted, ExpertPage
FilterSeverityLow	The severity is low, indicating the lowest severity of interest. This is also commonly called 'priority', especially in relation to process alarms.	1042	Persisted, ExpertPage
FilterSource	The source of the event in the OPC AE Server	1045	Persisted, ExpertPage
Operation Mode	The type of mode of the Bee.	1010	Persisted, Enumerated
PDS Area	The PDS area which an event subscription should be linked to.	1032	Persisted, ExpertPage
PDS ProcessUnit	The PDS Process Unit associated with this subscription.	1033	Persisted, ExpertPage
ReconnectSrvShutdown	Reconnect after an intended OPC server shutdown. This might cause problems when administering the OPC server.	1008	Persisted, ExpertPage
ReconnectTime	The time to wait before attempting to reconnect the server after an RPC failure.	1007	Persisted, ExpertPage
Server	The ProgID of the OPC server.	1002	Persisted, Enumerated, ProgID
SrvApisEventProcessingInterval	The time in seconds Apis uses for processing an event.	1092	PerformancePage
SrvCLSID	The CLSID of the OPC server.	1006	InfoPage
SrvCurrentTime	The current time (UTC) as known by the OPC server.	1071	InfoPage
SrvEventSubscribtion	Status of the event subscription.	1093	InfoPage
SrvLCID	Locale ID of values coming from the server. You might need to specify this property if the OPC server provides string values that is converted to another type in your client (e.g. DDE bridges)	1009	Persisted, ExpertPage
SrvStartTime	The time (UTC) the OPC server was started.	1070	InfoPage
SrvState	The current status of the OPC server.	1073	Enumerated, InfoPage
SrvSupportBrowsing	The status of server support browsing	1077	InfoPage
SrvUpdateCalls	The number of times the OPC server has called back to this client with updated item values.	1094	PerformancePage
SrvUpdateCallsFailure	The number of times the module has failed to process an event.	1096	PerformancePage
SrvUpdateCallsNotHandled	Number of update calls not handled due to manually creation mode.	1097	PerformancePage
SrvUpdateCallsOK	The number of times the module has successfully processed an event.	1095	PerformancePage
SrvUpdateTime	The time the OPC server sent the last data value update to this client, as known by the server.	1072	PerformancePage
SrvUpdateTimeClient	The time when this client received the last update, as known by the client.	1090	PerformancePage
SrvUpdateTimeInterval	The time in seconds between the last two updates.	1091	PerformancePage
SrvVendorInfo	Vendor specific information about the OPC server.	1075	InfoPage
SrvVersion	The version number of the OPC server (major-minor-build).	1074	InfoPage
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TraceEventMessages	If this is 'true', the module writes to the log files for log view in Apis Management Studio the information received on IOPCEventSink::OnEvent	1061	Persisted, ExpertPage
TraceOPCServer	Report specific OPC calls, return from those calls, as well as callbacks to the log files for log view in Apis Management Studio.	1060	Persisted, Enumerated, ExpertPage

See also Module Properties

Commands And Events

The AEClient module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

External source item from an OPC AE Server

The OPCAEItem item type has the following properties:

Name	Description	ID	Flags
AlarmArea	The default alarm area for the item.	10100	Persisted
ProcessUnit	The PDS process unit associated with this item. A process unit can be a piece of equipment or location, among other things.	5716	Persisted, ReadOnly
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly
ValueAssignment	Assign the item to one of the OPC Event data.	10200	Persisted, Enumerated

Properties

HiddenItem

The HiddenItem item type has the following properties:

Name	Description	ID	Flags
AlarmArea	The default alarm area for the item.	10100	Persisted
ProcessUnit	The PDS process unit associated with this item. A process unit can be a piece of equipment or location, among other things.	5716	Persisted, ReadOnly
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly
ValueAssignment	Assign the item to one of the OPC Event data.	10200	Persisted, Enumerated

Properties

The StatusItem item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Apis Alarm Area

The AlarmArea module monitors items in Apis Hive and generates alarms and events based on configurable criteria.

When an AlarmArea module is added to Hive, it will create a new event-category global attribute named after the module (e.g. MyAlarmAreaEvtCategory if the module is named "MyAlarmArea"). This attribute must then be added to all items that should be monitored, and set to one of the following values to specify the monitoring behavior on each item:

Discrete: The item value is either normal or not normal.
Level: The item value is expected to be within a certain range.
Watchdog: The item value is expected to be regularly updated.
WatchQuality: The item quality is expected to be good.

After setting the EvtCategory attribute, each item must be configured depending on the category selected for the item:

For the "Discrete" category, set the AlmNormalState attribute.
For the "Level" category, set the AlmH, AlmHH, AlmL and AlmLL attributes.
For the "Watchdog" category, set the AlmWatchdogPeriods attribute. A period is the time given in the ScanPeriod property of the AlarmArea module.
For the "Watch Quality" category, no additional attributes are necessary for proper configuration.

Another way to initiate alarm monitoring is to specify the AlmPrimaryArea attribute. Type the name of the AlarmAreaBee to be used to monitor the selected items. The default name is AlarmArea.

Mapping to Apis Chronical

By default, the AlarmArea module will create one Chronical eventsource for each item it monitors. The eventsource will be named after the item, and it will be linked below the sources "ApisHive/Areas/$AREANAME" and "ApisHive/Modules/$MODULENAME". When the state of an alarm is modified, the AlarmArea module will generate an event in Chronical to reflect the change.

The Chronical eventtypes used for these events are:

OffNormalAlarm for 'Discrete' monitoring.
LevelAlarm for 'Level' monitoring.
WatchdogAlarm for 'Watchdog' monitoring.
QualityAlarm for 'WatchQuality' monitoring.

The events will be reported on the eventsource created for the item, and they will use the item name for the "Sourcename" field defined in Chronical.

Some Chronical attributes can be added to each item to modify the default behaviour:

ChronicalEventType specifies the eventtype to use for events on the item.
ChronicalParent specifies a custom parent for the item instead of the default "ApisHive/Modules/$MODULENAME".
ChronicalSourceName specifies a custom value for the "Sourcename" eventfield.

Provider: Prediktor

Properties

The AlarmArea module has the following properties:

Name	Description	ID	Flags
AckRequired	By disabling this property, alarms generated by this module will be sent with acknowledge not required.	3400	Persisted, ExpertPage
AlmSeverityOfInactive	The severity of events when going from active to inactive.	1670	Persisted, Enumerated, ExpertPage
AlmSeverityStep	The step in severity when moving from one subcondition to another e.g. from HI to HIHI.	1650	Persisted, ExpertPage
AreaName	The name of the process area this module represents. Several areas can be listed using ';' (semicolon).	1010	Persisted
AreaPath	The path to the area this module represents. A hierarchical is specified using '.' (dot).	1020	Persisted, ExpertPage
DefaultAlmSeverity	The default value of the AlmSeverity attribute for new alarm items.	1600	Persisted, ExpertPage
DefaultWatchdogPeriods	The default value of the AlmWatchdogPeriods attribute for new watchdog category items.	1700	Persisted, ExpertPage
EnableAlarmEvaluation	This is used to disable alarm evaluation	3300	Persisted, ExpertPage
EnableEvaluationItem	If set, this item's value will enable (true) or disable (false) alarm evaluation.	3310	Persisted, ApisItem, ExpertPage
EnableInitialNormalReport	By default, the first evaluation of an alarm condition is not reported if the alarm is in normal state. This property, when set, makes the AlarmAreaBee always report the result of the initial alarm evaluation.	3330	Persisted, ExpertPage
FreshestValue	When TRUE, all items will be read directly from their physical source to receive the freshest possible values.	2010	Persisted, ExpertPage
InhibitAll	Supress all alarm generation from this module.	3200	Persisted
InhibitQuality	Supress alarms when quality is equal or worse than this.	3100	Persisted, Enumerated, ExpertPage
InvertInhibitSignals	Invert the value read from the inhibit signals, so that a 'false' inhibit value will prevent the alarm.	1710	Persisted, ExpertPage
PriorityLevel	Specifies the priority level for the working thread of this ApisAlarmAreaBee instance.	3000	Persisted, Enumerated, ExpertPage
ResetAlarms	By setting this property to true all alarms will be reset if either EnablealarmEvaluation or EnableEvaluationItem is FALSE	3320	Persisted, ExpertPage
ScanPeriod	The scan period in milliseconds for testing the event conditions.	1300	Persisted
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
UseSourceTimestamps	If set to 'true', the timestamps of the monitored items will be used as event timestamps when they occur. If set to 'false', the time the event was detected by this AlarmArea module is used.	1400	Persisted, ExpertPage
WatchdogQualityEvaluation	Set this property to true to include evaluation of the different quality OPC_QUALITY_GOOD	3550	Persisted, Enumerated, ExpertPage

Informational properties:

Name	Description	ID	Flags
AlmAttributeID	The global alarm attribute ID assigned from Apis Hive.	301200	InfoPage
ApisConditionEventSinkCookie	The value of the cookie assigned to this module from the Apis Event Server.	301800	InfoPage
AreaName	The name of the process area this module represents. Several areas can be listed using ';' (semicolon).	1010	Persisted
ConfigObserverCookie	The cookie identifying this module amongst the configuration aware clients of Apis Hive.	301400	InfoPage
Server compatibility	Status about which version of interface supported	301600	InfoPage
TimeSrvEventID	The time client event ID assigned from the Apis time server.	301100	InfoPage

Performance properties:

Name	Description	ID	Flags
AlarmEvalTime	The time in milliseconds used to evaluate alarms.	101007	PerformancePage
HiveLastUpdCount	The number of items reported as updated at the previous request.	101006	PerformancePage
NumAlmItems	Number of items this ApisAlarmArea instance stores to its database.	101000	PerformancePage
UpdSinceQueryTime	The time used when requesting updated items from the Hive.	101005	PerformancePage

See also Module Properties

Commands And Events

The AlarmArea module has the following Commands and Events:

Commands

Name	Description	Command Type
ResetEvents	Reset any active or unacked/ackrequired event in the area	Asynchronous
ResetEventsNotify	Reset any active or unacked/ackrequired event in the area and notify AE clients	Asynchronous
Scan	A command initiating a Scan cycle of the items monitored by this AlarmAreaBee instance.	Synchronous
Scan_DataPush	This command ensure that all items and samples in the data push package, are used for alarm evaluation where applicable. See also: APIS data transfer mechanism; Data Push	Synchronous

See also Commands And Events

BytePopulator

This module imports and exports content as byte array via file or REST api

Provider: Prediktor

The BytePopulator module has the following item types

RESTItem

FileItem

Properties

The BytePopulator module has the following properties:

Name	Description	ID	Flags
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ExternalItem report	A status-report for the External Item manager of this module	110	InfoPage
ExtItem full refresh	When true, the external items manager will force a full refresh initially on start/reset when reading items. I.e. items not yet initialized in their source, will also trigger an external item update. Default is true.	150	Persisted, ExpertPage
ExtItem pass-through quality	Specifies the quality of external item values that will pass through external item transfers. If external item qualities has worse quality the this mask, the external item transfer is blocked. Default is 'Any quality'.	400	Persisted, Enumerated, ExpertPage
LogLevel	Specifies the loglevel for diagnostic messages from this module.	500	Persisted, Enumerated

See also Module Properties

Commands And Events

The BytePopulator module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified by user. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
ReadSources	Trigger items with attribute 'OnlyReadWhenTriggered' enabled to read sources	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Item type: FileItem

Item which makes it possible to interpret files as byte array or write byte array to file

The FileItem item type has the following properties:

Name	Description	ID	Flags
Enabled	This attribute indicated whether the items operations is enabled or not	10009	Persisted
ExtItemOverrideMethod	This attribute decides what method to use when assigning a value from an external item.	5999	Persisted, Enumerated, BitMask
File Path	This attribute contains the path to the file that should be read or written	10003	Persisted
FileReader status	This attribute indicated whether the file read operation went well or not	10007	Persisted, ReadOnly
FileWrite status	This attributes indicated whether the file write went well or not	10006	Persisted, ReadOnly
NewTimestampEveryReadCycle	This attribute indicated whether the item should get a new timestamp even if the content is the same	10008	Persisted
OnlyReadWhenTriggered	This attribute indicates whether the item should only read source when triggered, and not when it is attempted to be read itself	10010	Persisted
OperatingMode	This attribute selects whether it content is read or should be written	10001	Persisted, Enumerated
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage

Item type: RESTItem

Item which makes it possible to GET content from REST server as byte array or POST byte array to REST server

The RESTItem item type has the following properties:

Name	Description	ID	Flags
Enabled	This attribute indicated whether the items operations is enabled or not	10009	Persisted
ExtItemOverrideMethod	This attribute decides what method to use when assigning a value from an external item.	5999	Persisted, Enumerated, BitMask
GET status	This attribute indicates whether the GET went well or not	10005	Persisted, ReadOnly
NewTimestampEveryReadCycle	This attribute indicated whether the item should get a new timestamp even if the content is the same	10008	Persisted
OnlyReadWhenTriggered	This attribute indicates whether the item should only read source when triggered, and not when it is attempted to be read itself	10010	Persisted
OperatingMode	This attribute selects whether it content is read or should be written	10001	Persisted, Enumerated
POST status	This attribute indicated whether the POST went well or not	10004	Persisted, ReadOnly
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
URL	URL specifies which URL the item utilises for communication	10002	Persisted, URL
Value	Item value	2	NormalPage

Apis Connection Manager

This module is used to configure connections to external services, and clusters of such configurations.

Provider: Prediktor

Item types:

OpcUa Connection Item

OpcUa Cluster Item

OpcUa Replication Item

Item Types

OpcUa Connection Item

An item used to configure the connection to one OpcUa server. This connection setup can then be used by the OpcUa and OpcUaProxy modules, and/or be part of an OpcUa cluster,

The OpcUa connection item has the following standard properties:

Name	Description	ID	Flags
Name	The name selected for the OpcUa connection configuration.
Endpoint URL	The server endpoint, e.g. 'opc.tcp://servername:4880'	10010	Persisted
Reverse connection	If true, the endpoint URL is used for reverse connections	10016	Persisted
ServiceLevel NodeId	The nodeid to read the servicelevel from.	10180	Persisted
Security mode	The level of security used when communicating with this server (one of 'None', 'Sign', 'Sign and encrypt')	10020	Persisted, Enumerated
Security policy	The security policy used when communicating with this server.	10021	Persisted, Enumerated
Authentication	The type of authentication to use when connecting to this server (one of 'Anonymous', 'Username/password')	10030	Persisted, Enumerated
Username	The username to use when authenticating with the server.	10031	Persisted
Password	The password to use when authenticating with the server.	10032	Persisted, Password
Pki provider	The Pki (certificate) provider to use when 'Security mode' is different from 'None', or 'Authentication' is different from 'Anonymous'.	10040	Persisted, Enumerated
Application certificate (SSL)	The name of the file containing the application certificate that will be sent to the server. If not specified, the default SSL application certificate for the Apis instance will be used.	10041	Persisted
Application private key (SSL)	The name of the file containing the private key for the application certificate. If not specified, the default SSL private key for the Apis instance will be used.	10042	Persisted
Server certificate (SSL)	The name of the file containing a copy of the servers application certificate.	10043	Persisted
Storage path (SSL)	The path to the root PKI directory. If not specified, the default pki directory for this Apis instance will be used (<INSTALL_DIR>\Config\<INSTANCE_NAME>\pki).	10044	Persisted
Application certificate (W32)	The subject-name of the application certificate that will be sent to the server. If not specified, the default Windows certificate for the Apis instance will be used.	10050	Persisted
Server certificate (W32)	The subject-name of the servers application certificate.	10051	Persisted
Storage path (W32)	Name of the folder in Windows Certificate Store where the application- and server-certificates are stored.	10052	Persisted

The OpcUa connection item has the following advanced properties:

Name	Description	ID	Flags
Watchdog interval	The number of seconds between each read of the servers status-variable. When one such read-operation fails, a reconnect sequence will be started.	10060	Persisted
Reconnect interval	The number of seconds between each reconnect attempt when the server is not responding.	10061	Persisted
Rpc timeout	The number of seconds to wait for rpc replies.	10070	Persisted
Session timeout	The number of seconds to keep the session alive in the server when there is no rpc requests from the client.	10071	Persisted
Token timeout	The number of seconds between security token renewals.	10072	Persisted
Cluster	When specified, this connection item becomes part of the selected cluster.	10090	Persisted, Enumerated

The OpcUa connection item has the following informational properties:

Name	Description	ID	Flags
Servicelevel	The last servicelevel received from the server. This is used for automatic failover between servers in a cluster.	10060	Persisted

OpcUa Cluster Item

An item used to configure a cluster of two or more redundant OpcUa servers. This item defines the cluster and its failover behavior, while the connection information for each server in the cluster are defined by OpcUa connection items.

Each OpcUa cluster can be selected as a server configuration option in the OpcUa and OpcUaProxy modules, thereby giving these module types transparent failover support.

A failover between servers can occur when the ServiceLevel reported by each server changes. The ServiceLevel is a number from 0 to 255 with the following semantics:

Levels 0-1: The server is not able to provide any data from its data sources
Levels 2-199: The server has lost connection to some, but not all, of its data sources
Levels 200-255: The server is connected to all of its data sources

There are different failover rules for each ServiceLevel group:

The active server has ServiceLevel 0-1: a failover occurs if another server has a ServiceLevel greater than 1.
The active server has ServiceLevel 2-199: a failover occurs if another server has a ServiceLevel greater than 199, or if another server has a ServiceLevel greater than the ServiceLevel of the active server plus the value of the 'Failover deadband' property.
The active server has ServiceLevel 200-255: failovers do not occur

Additionally, failovers never occur more frequently than specified by the 'Failover interval' property.

The OpcUa cluster item has the following standard properties:

Name	Description	ID	Flags
Name	The name selected for the cluster. This name will become available as a Server configuration option in the OpcUa and OpcUaProxy modules.
Value	The server endpoint currently having the highest ServiceLevel for this cluster (read-only). The active OpcUa connection of the cluster does not necessarily change even when this value changes.	2

The OpcUa cluster item has the following advanced properties:

Name	Description	ID	Flags
Failover timeout	Number of seconds to wait for additional servers to come online (after the first server reponse), before selecting a server as the current endpoint for the cluster.	10100	Persisted
Failover interval	Minimum number of seconds between failovers.	10101	Persisted
Failover deadband	Minimum ServiceLevel difference required to trigger a failover (only applies to servicelevels below 200).	10102	Persisted

OpcUa Replication Item

This itemtype is used to trigger a replication of another ApisHive instance. Each module with items in the replicated server will get an equally named OpcUa module in the replicating client, and one OpcItem for each item in the server. Global attributes for Logger and AlarmArea modules will also be replicated to the client.

The OpcUa Replication item has the following properties:

Name	Description	ID	Flags
ExtraProperties	Array of additional item properties to replicate for each item	10130	Persisted
ModulenameFilter	Optional filter used to restrict which modules to replicate. Supports wildcards such as '*', '?' and '#'	10150	Persisted
ModuletypeFilter	Semicolon-separated list of moduletypes to replicate. If empty, all moduletypes are replicated.	10160	Persisted
OpcUa server	The name of the OpcUa connection or cluster which should be replicated	10120	Persisted
PublishingInterval	The publishing interval to use on all OpcUa modules	10140	Persisted
ReplicationMode	Specifies how the replication should work	10125	Persisted, Enumerated
SamplingInterval	The sampling interval in milliseconds set on each replicated item	10145	Persisted
StandardPropSync	When to synchronize selected OpcUA Standard Properties from server nodes to local apis item attributes	10128	Persisted, EnumeratedFlags
SyncGlobalAttrs	If enabled, the replication item will synchronize global attributes	10135	Persisted
Value	Boolean value indicating if a replication is currently running. Set this to TRUE to trigger the replication.	2	NormalPage

The ExtraProperties setting specifies an array of Apis Attributes that should be replicated when the SyncStdProperties command is executed on each module.

When ReplicationMode is "Copy", all items found on the server gets a matching OpcItem in the client. When ReplicationMode is "Mirror", a normal "Copy" replication is performed but any OpcItem in the client that is not found on the server gets deleted from the client.

StandardPropSync is a multi-select property with the following options:

First time adding items
Each session
After replication

If "After replication" is activated, the "SyncStdProperties" command is executed on each module after synchronizing the module properties and items.

ApisEventBus

Apis module used to process events

Provider: Prediktor

The EventBus module has the following item types

Properties

The EventBus module has the following properties:

Name	Description	ID	Flags
Description	A user defined description of this module instance.	900	Persisted, InfoPage
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
LogLevel	Specifies the loglevel for diagnostic messages from this module.	500	Persisted, Enumerated
Text1	A generic user defined text related to this module instance.	910	Persisted, InfoPage
Text2	A generic user defined text related to this module instance.	911	Persisted, InfoPage
Text3	A generic user defined text related to this module instance.	912	Persisted, InfoPage
Text4	A generic user defined text related to this module instance.	913	Persisted, InfoPage

See also Module Properties

Commands And Events

The EventBus module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified by user. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

Item used to define an event channel/stream

The Channel item type has the following properties:

Name	Description	ID	Flags
BatchTime	Time used to batch events, in seconds	10060	Persisted
BatchSize	Maximum number of events per batch. Overrides BatchTime if both attributes are specified.	10070	Persisted
IsConsumer	This attribute is TRUE on items that can consume events	10010	ReadOnly, InfoPage
IsProducer	This attribute is TRUE on items that can produce events	10020	ReadOnly, InfoPage

Properties

Item used to route and/or transform an event stream

The Router item type has the following properties:

Name	Description	ID	Flags
InputChannel	The input channel for events consumed by this item	10030	Persisted, DynamicEnumeration
IsConsumer	This attribute is TRUE on items that can consume events	10010	ReadOnly, InfoPage
IsProducer	This attribute is TRUE on items that can produce events	10020	ReadOnly, InfoPage
OutputChannel	The output channel for events produced by this item	10040	Persisted, DynamicEnumeration
Script	The XSLT scipt that will be executed on incoming events to produce outgoing events	10100	Persisted, Multiline

Properties

Item used to subscribe to events from Apis Chronical

The Source.Chronical item type has the following properties:

Name	Description	ID	Flags
Eventsource	Path to the root eventsource to monitor	10200	Persisted, ApisEventSourcePath
Eventtype	Name of the root eventtype to monitor	10210	Persisted, DynamicEnumeration
IsConsumer	This attribute is TRUE on items that can consume events	10010	ReadOnly, InfoPage
IsProducer	This attribute is TRUE on items that can produce events	10020	ReadOnly, InfoPage
OutputChannel	The output channel for events produced by this item	10040	Persisted, DynamicEnumeration

Properties

Item used to write events to a SQL database

The Sink.Db item type has the following properties:

Name	Description	ID	Flags
ConnectionString	ADO Connectionstring for the database	10400	Persisted
InputChannel	The input channel for events consumed by this item	10030	Persisted, DynamicEnumeration
IsConsumer	This attribute is TRUE on items that can consume events	10010	ReadOnly, InfoPage
IsProducer	This attribute is TRUE on items that can produce events	10020	ReadOnly, InfoPage

Properties

Item used to send emails. The Sink.Smtp item will automatically use TLS if the server supports the STARTTLS command.

The Sink.Smtp item type has the following properties:

Name	Description	ID	Flags
Server	Address of smtp server, e.g. 'smtp.office365.com:587'	10500	Persisted
Username	Username used to authenticate with the smtp server	10510	Persisted
Password	Password used to authenticate with the smtp server	10520	Persisted
From	Email address used in the 'From:' field	10530	Persisted
To	Email address(es) used in the 'To:' field	10540	Persisted
Cc	Email address(es) used in the 'Cc:' field	10550	Persisted
Bcc	Email address(es) used in the 'Bcc:' field	10560	Persisted
Importance	Value of 'Importance:' field (0=Normal, 1=High, 2=Low)	10560	Persisted, DynamicEnumeration
IsConsumer	This attribute is TRUE on items that can consume events	10010	ReadOnly, InfoPage
IsProducer	This attribute is TRUE on items that can produce events	10020	ReadOnly, InfoPage

Properties

Item used to log events to a tracefile

The Sink.Tracelog item type has the following properties:

Name	Description	ID	Flags
Enabled	Enable/disable tracing of events	10050	Persisted
InputChannel	The input channel for events consumed by this item	10030	Persisted, DynamicEnumeration
IsConsumer	This attribute is TRUE on items that can consume events	10010	ReadOnly, InfoPage
IsProducer	This attribute is TRUE on items that can produce events	10020	ReadOnly, InfoPage
TraceFile	Full path to the trace-file	10300	Persisted

Apis FileReader

This is a called ApisFileReader which reads data from a file and inserts it into the namespace of Apis Hive

Provider: Prediktor

The FileReader module has the following item types

FileItem

AnalogueVectorItem

Properties

The FileReader module has the following properties:

Name	Description	ID	Flags
Alarm command	The command executed when there hasn't been any file update in 'TimeToAlarm' milliseconds in the specified directory. This typically is the full path to an executable or similar.	1610	Persisted, ExpertPage
Alarm command parameters	The parameters sent to the command in 'Alarm command'.	1620	Persisted, ExpertPage
Completion port handle	The handle of the I/O completion port in use.	50120	InfoPage
Directory handle	The handle of the monitored directory.	50110	InfoPage
FileChangeTimeout	The maximum amount of milliseconds to wait for a file change notification to occur before the directory is manually scanned for filechange(s).	1350	Persisted, Enumerated, ExpertPage
FileChangeToParseDelay	A delay in milliseconds indicating how long to wait from a file is detected as changed until it is actually being parsed by the FileParserObject.	1400	Persisted, ExpertPage
Filename Pattern	A filename pattern including the path for files that will be sent to the parser	1150	Persisted, File
FileParser	The ProgID identifying the parser component used by this module when parsing the file(s).	1300	Persisted, Enumerated, ProgID
FileReader trace file¹	If set, internal file update handling of the ApisFileReaderBee will be traced to this file. Should only be used for short time periods and for verbose troubleshooting of file update dynamics.	2000	Persisted, File, ExpertPage
LastFileChangeTime	The time of the last notification of a matching file-change the module has registered.	100000	PerformancePage
LastFileParserFileName	The name of file last parsed.	103000	PerformancePage
LastFileParserFileTimeUsage	The time used by the file-parser to handle last file update.	102000	PerformancePage
LastUpdatedItemCount	The number of items updated by the last file-change notification.	101000	PerformancePage
ScanDirectoryOnStart	If true, the SourceDirectory will be scanned once upon startup to look for matching files, if false directory will be scanned on startup but depend on directory changes and/or FileChangeTimeout for first scan.	1340	Persisted, ExpertPage
SourceDirectory	The directory which the module shall monitor for file changes.	1100	Persisted, Hidden, Folder
TimeToAlarm	The time in milliseconds that the module delays when lack of fileupdates until the alarm action specified in the 'Alarm command' property is executed.	1600	Persisted, ExpertPage
UseApisTime	Use Apis timestamps instead of the timestamps given by the parser component.	1500	Persisted, ExpertPage

Additional FileReader properties, shared with the specific:

Name	Description	ID	Flags
FavorArrayItems	When 'true', the module tell it's file parser object to use vector and matrices as item types when applicable.	10000	Persisted, ExpertPage
Database login	Same as User ID in connection string. If blank, integrated security will be used.	10005	Persisted, User, ExpertPage
Database login password	Used when Database login is other than blank.	10006	Persisted, Password, ExpertPage
Database name	The name of the database on given server, used in connection string.	10004	Persisted, ExpertPage
Database server	The server machine where the database exists, used in connection string.	10003	Persisted, ExpertPage
FileParser debug trace file	If specified, the complete filename of a tracefile used for debugging from parsers. Whether or not a file is generated, is parser specific behavior. If empty, no tracefile will be used.	10009	Persisted, File, ExpertPage
Honeystore database	If applicable, the name of the Honeystore database to use for parser component.	10008	Persisted, ExpertPage
Locale ID	The locale ID to be used when parsing files.	10001	Persisted, ExpertPage
Offset from UTC	The offset from UTC can be used by the parser component when handling files. Norwegian timezone is +60.	10002	Persisted, ExpertPage
Parser specific enum	This property may have meaning for some types of parsers, other may not use it.	10007	Persisted, DynamicEnumeration, ExpertPage

See also Module Properties ¹: FileReader trace file has default a maximum count of 10 files with maximum size of 64 MB, other values can be specified in the module specific registry key using DWORD values TraceToFileMaxCount and TraceToFileMaxSize

Commands And Events

The FileReader module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

FileItem

A generic item parsed from a file

The FileItem item type has the following properties:

Name	Description	ID	Flags
MapKey	The key of item in m_Handles map (parser handle)	10100	Hidden
Quality	Item quality	3	ReadOnly
ReqVartype	The type requested to be delivered for the value of this item from the server. Only change this one for special situations.	10200	Persisted, ReadOnly, Hidden, Enumerated
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	ReadOnly

AnalogueVectorItem

An analogue vector item of 4 byte floats parsed from a file

The AnalogueVectorItem item type has the following properties:

Name	Description	ID	Flags
Dimension	The dimension of a vector item (number or elements)	5007	Persisted, ReadOnly
MapKey	The key of item in m_Handles map (parser handle)	10100	Hidden
Quality	Item quality	3	ReadOnly
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	ReadOnly

Apis HAGovernor

This is an Apis module that governs High Availability tasks for an Apis Hive instance. I.e. synchronizing configuration, time-series and event data between redundant instances.

Provider: Prediktor

The HAGovernor module has the following item types

Command Item

State Item

Function item

Tutorial

To use the Apis HA Governor module, please refer to this topic: Getting Started

Properties

The HAGovernor module has the following properties:

Name	Description	ID	Flags
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ExpertMode	Set this to true, to make other properties writable and put the module into expert mode.	1500	ExpertPage
HA Deputies	Different High Availability deputies performing different tasks.	1900	Persisted, EnumeratedFlags
Hive Instances	An array of one or more Hive instance(s) that take part in the same HA Cluster, as: <computername or ip>:<port>. E.g: localhost:5555	2000	Persisted, TcpIpAddr
LogLevel	Specifies the loglevel for diagnostic messages from this module.	500	Persisted, Enumerated
PingInterval	The pinging interval, in seconds, of the HA Governor and deputies (where applicable).	1850	Persisted
RedundancySupport	RedundancySupport indicates what redundancy is supported by the Server.	2110	Persisted, DynamicEnumeration
ServerPort	The port number of the HA Governor Communication server for this instance.	1800	Persisted
ServerUriArray	ServerUriArray is an array with the URI of all redundant Servers of the OPC UA Server.	2120	Persisted, TcpIpAddr
TrendHistory_LastUpToDate	The last time (in UTC) the HA Governor has determined that the Trend History of this instance, was up to date compared with all Hive Instances.	3010	Persisted, ReadOnly
EventHistory_LastUpToDate	The last time (in UTC) the HA Governor has determined that the Event History of this instance, was up to date compared with all Hive Instances.	3020	Persisted, ReadOnly

See also Module Properties

Commands And Events

The HAGovernor module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified by user. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Command Item

An item that represents a command to apply on this module.

The Command Item item type has the following properties:

Name	Description	ID	Flags
Command type	This attribute defines the command type of the command item.	10130	Persisted, ReadOnly, Hidden
Description	Item description	101	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage

State Item

An item that represents a well defined state of this module.

The State Item item type has the following properties:

Name	Description	ID	Flags
Description	Item description	101	Persisted
Quality	Item quality	3	ReadOnly
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	ReadOnly

High Availability Data Concept

By High Availability (HA), we do not mean full redundancy, but something that is close and in many situations serves the same purpose adequately.
In short, the HA provided by this module, will be like described below. There are 2 Hive instances involved; one local instance and one remote instance.

Configration Data

For now, synchronizing configuration data is not supported, and is required to be synchronized manually.

TimeSeries data

TimeSeries data will be synchronized like this: When your local Hive instance starts, the HAGovernor will request all items that are trended locally from the local instance. For each of these items, it will try to retrieve from the remote instance timeseries data from the time period when the local instance was not running. All timeseries data received from the remote instance, will be inserted into the corresponding timeseries data of the local instance. If any (for some reason) timeseries data already exists locally for the time period when your local instance was not running, it will be overwritten.

Event data

Event data will be synchronized like this: When your local Hive instance starts, the HAGovernor will request all event data from the remote instance, from the time period when the local instance was not running. All Event data received from the remote instance, will be inserted into the event data of the local instance. If any (for some reason) event data already exists locally for the time period when your local instance was not running, it will be not be overwritten.

Also, please refer to this section: Apis High Availability.

Getting Started

This module uses an proprietary TCP protocol to exchange timeseries and event data between this Hive instance and another redundant Hive instance.
For now, synchronizing configuration data is not supported, and is required to be synchronized manually.

What is meant by High Availability (HA), is described here: High Availability Data Concept

Basic configuration

Assuming you have 2 Hive instances, that has redundant configuration, one local and one remote. We will now describe how to configure an ApisHAGovernorBee on each of these instances in a HA setup

In your local Hive instance, add new Apis module of type ApisHAGovernor.
In your remote Hive instance, add new Apis module of type ApisHAGovernor.
Specify a free and valid ServerPort property on both added modules.
On the Hive Instances property of your local Hive instance, specify the endpoint to the remote Hive instance. Eg: <remote computername or IP>:<port from step 3.>
On the Hive Instances property of your remote Hive instance, specify the endpoint to the local Hive instance. Eg: <local computername or IP>:<port from step 3.>
Specify the HA Deputies property you want to use on both added modules. (Note: the Config Sync deputy is not implemented and will have no effect).
Restart the modules to apply the changes.

When restarting the modules or their Hive instances, the HA Governor will synchronize TimeSeries/Event data from the timestamps of the properties TrendHistory_LastUpToDate / EventHistory_LastUpToDate depending on which deputies were activated in the HA Deputies properties.

Advanced operation

If you want to manually control from what time a Timeseries/Event synchronization shall start, you can set the ExpertMode property to true. Then, the properties TrendHistory_LastUpToDate / EventHistory_LastUpToDate will become writable and you may specify a custom start time. Synchronization from that time will take place the next time the module or the Hive instance is restarted.

The property RedundancySupport will reflect and control the RedundancySupport exposed by the OpcUa server of this Hive instance (if enabled).

The property ServerUriArray will reflect and control the ServerUriArray exposed by the OpcUa server of this Hive instance (if enabled).

Apis HSMirror

This Apis module, connects to an Apis HoneyStore real-time Historian, and exposes the trend items of its databases as items in this Hive instance.

Provider: Prediktor

The HSMirror module has the following item types

Properties

The HSMirror module has the following properties:

Name	Description	ID	Flags
AutoConfig	Select a strategy for automatically configuing the items of this module, based on changes in the databases of the Apis HoneyStore historian. Typically used in combination with property Database-ItemFilters. Enum options are: Manual: No automatic configuration, items must be addedand deleted manually. AutoAdd: When trend-items matching the Database-ItemFilters are added to HoneyStore, items are automatically added to this module. Also, when module is started, HoneyStore is investigated for matching trend-items and if found, automatically added to this module. AutoDelete: When trend-items matching the Database-ItemFilters are deleted from HoneyStore, items are automatically added to this module. Note, when module is started, HoneyStore is not investigated for missing trend items to delete. The reason for this is that we don't want items to disappear when HoneyStore databases are temporarily put into Disabled or Admin modes and this Hive instance is restarted. AutoAddAndDelete: Same as selecting both AutoAdd and AutoDelete.	2000	Persisted, Enumerated
Database-ItemFilters	When specified; a vector of "DataBase.ItemName" filters to use for automagic item configuration, wildcard syntax is supported. If an empty array, items must be added/deleted manually to the module. When specified, this also works as filter(s) for browsing the namespace of HoneyStore when adding HoneyStoreItems.	2010	Persisted
Description	A user defined description of this module instance.	900	Persisted, InfoPage
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
HS-Computer	HS-Computer\nThe computer hosting the Apis HoneyStore Historian. Leave empty for localhost, or enter a valid hostname/IP-address.	1100	Persisted, TcpIpAddr
LogLevel	Specifies the loglevel for diagnostic messages from this module.	500	Persisted, Enumerated
PersistValToInitVal	Choose strategy for copying and persisting current value to the InitValue.	1500	Persisted, Enumerated
Text1	A generic user defined text related to this module instance.	910	Persisted, InfoPage
Text2	A generic user defined text related to this module instance.	911	Persisted, InfoPage
Text3	A generic user defined text related to this module instance.	912	Persisted, InfoPage
Text4	A generic user defined text related to this module instance.	913	Persisted, InfoPage

See also Module Properties

Commands And Events

The HSMirror module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified by user. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Item type: HoneyStoreItem

An item mirrored from a HoneyStore database trend item.

The HoneyStoreItem item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality	3	ReadOnly
Rights	Item access rights	5	ReadOnly
SrcItemID	Item ID in source	5030	Persisted
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	ReadOnly

Item type: Variable

User defined item, which can be written and read.

The Variable item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10010	Persisted, Enumerated

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

Apis IEC104

A module for support of the IEC 60870-5 standard.

General information about the protocol.

Implemented using the MZ Automation IEC 60870-5-104 library.

Limitations:

Only client is supported
Only one connection/server

Provider: Prediktor

The Apis IEC 104 module has the following item types:

Properties

The module contains the following standard properties:

Name	Description	ID	Flags
Mode	Specifies the run mode of the module. When in Offline mode, the module do not communicate (read/write) with any external system. When in Online mode, the module has normal communication (read/write) with external system.	501	Persisted
IP Address	The IP address to the server	1601	Persisted,TCP/IP address
Port Number	The port number the IEC 104 server is running on (plain default=2404, TLS default=19998)	1602	Persisted
TLS	Set this to enable TLS connection	1620	Persisted,Enumerated
TLS Public Key	Full path to .pem file that contains the public key	1630	Persisted,File
TLS Password	Password of the public key file if it has one	1631	Persisted
TLS Certificate	Full path to own .cer file that contains own certificate (x.509)	1632	Persisted,File
TLS CA Certificate	Path to .cer file from certificate authority (x.509)	1633	Persisted,File
TLS Server Certificate	Path to server .cer file (x.509)	1634	Persisted,File
TLS Strict	If set to true only known certificates are accepted. Connections with unknown certificates are rejected even if they are signed by a trusted authority	1635	Persisted
TLS Timeout	TLS renegotiation timeout in ms (-1 (disabled) by default)	1636	Persisted
TLS Min	Min TLS version required for slave (Not selected,SSL 3.0,TLS 1.0,TLS 1.1,TLS 1.2,TLS 1.3)	1637	Persisted
TLS Max	Max TLS version required for slave(Not selected,SSL 3.0,TLS 1.0,TLS 1.1,TLS 1.2,TLS 1.3)	1638	Persisted
TLS Validation	Enables the validation of the certificate trust chain (enabled by default) ¹	1639	Persisted
K	MMaximum number of unconfirmed I-frames¹ that can be sent before waiting for S-frame (acknowledgement) from the receiver (server).	1655	Persisted
W	Maximum number of I-frames that can be received before sending an S-frame (acknowledgment) to the sender (server).	1656	Persisted
T0 [s]	Timeout for connection establishment[seconds] ¹	1657	Persisted
T1 [s]	Timeout for receiving S-frame (ack) for sent I-frames. Resends the I-frames data after this timeout. [seconds]	1658	Persisted
T2 [s]	Timeout for sending S-frame (ack) for received I-frames. Maximum time before sending an S-frame (ack). [seconds]	1659	Persisted
T3 [s]	Timeout for data exchange. If no frames are exchanged for T3 period, a S-frame (test) is sent to verify the connection is alive. [seconds]	1660	Persisted

The module contains the following advanced properties:

Name	Description	ID	Flags
Watchdog Mode	Watchdog Item will monitor the item specified in Watchdog Item for activity, and Any Item will register any change in any items as activity	1640	Persisted,Enumerated
Watchdog Timeout [ms]	Max time since last registered activity before connection considered lost [milliseconds]	1642	Persisted
Watchdog Item	The item name to use when watchdog mode is set to monitor a specific item	1643	Persisted
Poll	Periodically send commands to get latest values from server	1644	Persisted,Enumerated
Poll Period [ms]	Period between each read command request when auto read items is activated. [milliseconds]	1645	Persisted

See also Module Properties

¹ See basic overview of IEC 104 Communication

Commands And Events

The module has the following events:

Name	Description	Event Type
ServerConnected	Event triggered after established connection to server	Normal
ServerDataChanged	Event triggered after receiving data from server	Normal
ServerDisconnected	Event triggered after disconnection to server	Normal

The module has the following commands:

Name	Description	Command Type
Reconnect	Trigger reconnect to the server	Asynchronous

Item Types

Information Item

Receives process information in monitor direction (server->client).

The item type has the following properties:

Name	Description	ID	Flags
CA	Common address	18700	Persisted
IOA	Information object address	18701	Persisted
Scale	Will scale the value according to y=ax+b, where a=scale	21389	Persisted
Offset	Will scale the value according to y=ax+b, where b=offset	21390	Persisted
COT	Cause of transmission of last received value	18702	ReadOnly
Type id	Type id of last received value	18703	ReadOnly
Quality	The IEC 104 specific quality of last received value	18707	ReadOnly

Interrogation Command Item

Sends an interrogation command in control direction (client->server).

The item type has the following properties:

Name	Description	ID	Flags
CA	Common address	18700	Persisted
COT	Cause of transmission	18702	Persisted
QOI	Specifies the behavior of the server when processing the command	18706	Persisted

On success, the corresponding Information Items on the same CA should be updated with the latest values from the server.

To trigger an interrogation command:

Configure the interrogation command with the properties listed above;
Set a new value on the item - not sent to server, only used for triggering an interrogation command;
On success; the value on the item is set;
On failure; the value on the item is not set - check log for more information.

Process Command Item

Sends process information in control direction (client->server) when it is updated with new values.

The item type has the following properties:

Name	Description	ID	Flags
CA	Common address	18700	Persisted
IOA	Information object address	18701	Persisted
COT	Cause of transmission	18702	Persisted
Command	Type of command to send	18704	Persisted
Qualifier	Specifies the behavior of the server when processing the command	18705	Persisted

Sends a value, with the given attributes, to the server. It sends the value the item is set to.

To trigger a process command:

Configure the process command with the properties listed above;
Set a new value on the item - this value is sent as part of the command to the server;
On success; the value on the item is set and the values of the information items with the same CA should be updated;
On failure; the value on the item is not set - check log for more information.

Read Command Item

Sends a read command in control direction (client->server).

The item type has the following properties:

Name	Description	ID	Flags
CA	Common address	18700	Persisted
IOA	Information object address	18701	Persisted

On success, reads the current value of the information item on the server and should be reflected on the corresponding Information Item.

To trigger a read command:

Configure the read command with the properties listed above;
Set a new value on the item - not sent to server, only used for triggering a read command;
On success; the value on the item is set and the value of the corresponding information item should be updated;
On failure; the value on the item is not set - check log for more information.

Test Command Item

Sends a test command in control direction (client->server).

The item type has the following properties:

Name	Description	ID	Flags
CA	Common address	18700	Persisted

Can be used to e.g. keep the connection alive.

To trigger a test command:

Configure the test command with the properties listed above;
Set a new value on the item - not sent to server, only used for triggering a test command;
On success; the value on the item is set;
On failure; the value on the item is not set - check log for more information.

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

Control Parameters

IEC 104 data communication is bidirectional, i.e. both client and server can be sender and receiver of messages, which is divided into three set of frames which serves different purposes:

I-frames (Information Frames): payload that contains data (measurements, commands, etc) and incremental sequence number (sq);
S-frames (Supervisory Frames): used primarily for management and control of I-frames (Receive Ready for receipt and indicate the receiver is ready to accept more I-frames);
U-frames (Unnumbered Frames): used to test network connectivity (TESTFR_ACT, TESTFR_CON).

The transmission is regulated with a set of link control parameters: K,W,T0-T3, ref Properties

Connection Establishment

Parameters: T0
Used by: client
Usage: Ensuring that the client does not indefinitely wait for a respons.
Value: Typically the T0 timer is set to about 30 seconds, providing a reasonable window to accommodate network delays and server processing times.

Example:

Client connects to the server and waits for T0 for server to accept connection request;
Client aborts after T0 timeout;

Data Transmission

Parameters: K, W, T1, T2
Used by: client and server
Usage: Ensures all I-frames are received orderly and processed by the receiver
Values: The sender will stop sending I-frames and wait for S-frame either when number of I-frames sent before last received S-frame reach K or T1 timeout. The receiver will send S-frame when number of received I-frames reach W or T2 timeout. To avoid the sender to wait for S-frames from the receiver, W and T2 for the receiver should be less than K and T1 for the sender, typically 1/2.

Example:

Server sends up to K number of I-frames before stopping and waiting for ack (S-frame);
Server resends the I-frames sent after last received ack if no acknowledment is received before T1 timeout;
Client sends the ack after it has received W number of I-frames or T2 has timed out.
Server resets the K counter and T1 timer when receiving ack and continue sending I-frames;

Example 2:

Client has X number of command items where X > Server value of W
Client tries to send a command item for all items at once
Client will only be able to send X - Server value of W commands before the Server has processed and sent ack (S-frame)
Client will in Apis see good quality for the first successfully sent Server value of W command items and bad quality for the rest

Connection Integrity

Parameters: T3
Used by: client and server
Usage: Ensures connection is alive
Values: Typically to avoid unnecessary sending of U-frames, T3 should be greater than the other timers, typically set to 20 seconds.

Example:

Client receives no I-frames within T3 timeout peroid;
Client sends an U-frame (TESTFR_ACT) to test connection;
Server sends an U-frame (TESTFR_CON) back to Client to confirm connection;

Choosing Client Values Based On Server Values

Calculating client parameters from server parameters

Formula and example values for calculating client side parameters:

Parameter	Server Value	Client Formula	Server Example	Client Example
K	K_S	W_S * 2	12	16
W	W_S	K_S / 2	8	6
T0			30s	30s
T1	T1_S	T2_S * 2	16s	20s
T2	T2_S	T1_S / 2	10s	8s
T3			20s	20s

Choosing Server Values or Client Values With Unknown Server Values

Considerations for choosing K

Setting the "k" parameter has significant implications for the performance and efficiency of the network communication. The choice of a low vs. a high "k" value affects several aspects of the protocol's operation:

Low k Value (e.g., k=1):

Increased Acknowledgments: A low "k" value means that each I-frame must be acknowledged before the next one can be sent. This can significantly increase the number of acknowledgment messages (S-frames), adding to the overhead in the communication.
Lower Throughput: The need for frequent acknowledgments limits the number of I-frames that can be sent in a given period, potentially reducing the overall throughput of application data.
Higher Sensitivity to Latency: The communication becomes more sensitive to network latency. Each I-frame's transmission depends on the round-trip time (RTT) for the acknowledgment of the previous frame, making the data transfer rate more susceptible to delays.
Improved Error Recovery: On the positive side, a low "k" value can lead to faster error detection and recovery since any lost or unacknowledged frame will halt the transmission more quickly, allowing for prompt retransmission.

High k Value (e.g., k=1000):

Reduced Acknowledgments: A higher "k" value allows more I-frames to be sent before an acknowledgment is required, reducing the overhead caused by acknowledgment messages and potentially making the communication more efficient.
Higher Throughput: More I-frames can be "in-flight" before an acknowledgment is needed, which can significantly increase the data transmission rate, especially in networks with high latency.
Buffer and Memory Considerations: Both the client and server must have sufficient buffer space to handle the higher number of unacknowledged I-frames. This requires careful resource management, especially in systems with limited memory.
Delayed Error Recovery: With more unacknowledged frames allowed, it may take longer to detect and recover from errors. Lost or corrupted frames might only be identified after more frames have been sent, potentially complicating error recovery processes.

The choice between a low and high "k" value depends on the specific requirements of the application and the characteristics of the network. A low "k" may be preferred in networks where minimizing latency and quick error recovery are critical, albeit at the cost of throughput. A high "k" might be advantageous in stable networks with high latency or where maximizing throughput is desired, provided that the system can handle the increased memory and processing requirements for managing a larger number of unacknowledged frames. Balancing these factors is key to optimizing the performance and reliability of IEC 104 communications.

A commonly used range for "k" in many implementations is between 12 and 128. This range is considered to provide a good balance between throughput and the ability to quickly recover from errors in a variety of network conditions. However, the optimal value within this range, or even outside of it, should be determined based on testing and evaluation in the specific network environment and application context where it will be used.

Considerations for choosing W

A common recommendation is to set W to approximately half of K. This guideline helps to ensure that acknowledgments are received and processed before reaching the maximum number of unacknowledged I-frames, thus reducing the risk of transmission stops and enhancing data integrity.

For example, if `K = 32`, then `W` might effectively be set to around 16.

This ratio helps in managing network traffic more smoothly and prevents the scenario where the sender has to stop sending frames and wait for acknowledgments too frequently (which would happen if W is too low) or too infrequently (which risks data overflow and errors if W is too high).

Considerations for choosing T0

Recommended Setting: Typically, T0 is set to 30 seconds. This provides sufficient time for connection attempts even over slower or less reliable networks.

Considerations for choosing T1

Recommended Setting: T1 is usually set to around 15 seconds. This duration is enough to cover most transmission delays that might occur in typical network conditions.

Considerations for choosing T2

Recommended Setting: T2 is generally set shorter than T1, around 10 seconds. It should be less than T1 to ensure that a test frame can be sent and acknowledged before the T1 timeout for data frames.

Considerations for choosing T3

Recommended Setting: T3 is commonly set to 20 seconds. This setting should be longer than T1 and T2 to allow sufficient time for the test frames to be acknowledged under normal conditions.

Additional Considerations

Network Characteristics: These recommended settings can serve as a good starting point, but optimal values might vary based on specific network performance characteristics and requirements. Considerations include network latency, reliability, bandwidth, and the criticality of the application.
Adjustments and Testing: It is advisable to adjust and test these timers in the specific deployment environment to find the best settings that ensure reliable communication while minimizing unnecessary traffic.
Consistency with Standards: If there are industry-specific standards or regulations that dictate timer settings, those should take precedence to ensure compliance and interoperability.

These settings help balance the performance and reliability of the IEC 60870-5-104 communication by efficiently managing the connection lifecycle and error recovery processes. Adjustments based on actual network conditions and system performance are crucial for maintaining optimal operations.

Apis IEC 61850

A module for support of the IEC 61850 standard.

The standard is mapped to many protocols, including the MMS protocol used in this module.

The module will act as a client connecting to an IEC 61850 server over the MMS protocol.

The module is using the MZ Automation IEC 61850 library.

Provider: Prediktor

The IEC 61850 module has the following item types:

Properties

The module contains the following standard properties:

Name	Description	ID	Flags
Mode	Specifies the run mode of the module. When in Offline mode, the module do not communicate (read/write) with any external system. When in Online mode, the module has normal communication (read/write) with external system.	501	Persisted
Hostname	The IP address to the server	1601	Persisted,TCP/IP address
Port	The IP port number to the server	1602	Persisted
Authentication mode	Authentication mode for connecting to the server	1603	Persisted,Enumerated
Connection state	The connection state to the server	1604	ReadOnly,Enumerated
Password	Authentication password to connect to server	1610	Persisted
Watchdog mode	Monitor the connection to the server with the watchdog and auto reconnect if connection is assumed lost	1605	Persisted,Enumerated
Watchdog timeout	Max time (ms) between last received message and time when watchdog is active	1606	Persisted
Watchdog item	The item name to use when watchdog mode is set to monitor a specific item	1607	Persisted
Poll mode	Poll mode of the module	1608	Persisted
Poll period	Time (ms) between each poll cycle	1609	Persisted

Notes regarding Poll mode:

Polling DataObjects is most expensive network wise as it make a network request per DataObject, e.g. 1000 DataObject items -> 1000 network requests.
Polling DataSets is less expensive as it make one network request per DataSet item, which can contain many if not all DataObject items.
Prefered way should be to have Poll Mode set to Disabled; group the DataObject items into logical DataSet objects; have a report for each DataSet that subscribes to updates from the server. A similiar polling like behaviour can be configured in the report with Integrity as TrgOps and Integrity period set to the desired poll period. This will require the minimal network traffic as the client is not sending any explicit network requests, only server is sending data back to the client with regular interval.

Commands And Events

The module has the following events:

Name	Description	Event Type
ServerConnected	Event triggered after established connection to server	Normal
ServerDataChanged	Event triggered after receiving data from server	Normal
ServerDisconnected	Event triggered after disconnection to server	Normal

The module has the following commands:

Name	Description	Command Type
Reconnect	Trigger reconnect to the server	Asynchronous

Item Types

DataObject

DataObject items maps to IEC61850 concept of DataObjects on the server, where each DataObject has a set of functionally constrained (FC) data attributes.

The item type has the following properties:

Name	Description	ID	Flags
Scale	Will scale the value according to y=ax+b, where a=scale	5005	Persisted
Offset	Will scale the value according to y=ax+b, where b=offset	5006	Persisted
SrcItmID	Data reference to the DataObject, usually on the form LDName/LNodeName.Object [string]	5030	Persisted
Functional contraint	Functional constraint of the data object	17001	Persisted
V	Data Attribute (DA) used for item value [string]	17003	Persisted
Q	Data attribute (DA) used for item quality [string]	17004	Persisted
T	Data attribute (DA) used for item time [string]	17005	Persisted
Attributes	Available data attributes on the data object	17002	ReadOnly
IEC Quality	The IEC61850 specific quality of last received value	17006	ReadOnly

For scalar DataObjects, VQT attributes can be flat, e.g. v or nested structures e.g. level1.level2.v.

In the case where DataObject is an array, the items in the array can be accessed with

SrcItmID = LDName/LNodeName.arrayObject(0) and VQT attributes = myStruct.myVal
SrcItmID = LDName/LNodeName.arrayObject and VQT attributes = (0).myStruct.myVal.

The (1) method is prefered if the VQT values are located in the same index, otherwise (2) can be used but will be more inefficient as it will read the whole array.

All available VQT attributes are listed in the Attributes attribute of the item.

Note regarding VQT attributes:

V is mandatory and must match an item in the the available data attributes.
Q and T is optional, but if set must match a an item in the available data attributes. They must also match with the expected type, which for Q is a bitstring and T is a utc-time. If not set, the default values of good quality and current time is used. Failing to satisfy these requirements will result in a config error quality on the item.

Notes regarding Quality:

Apis will set the item qualities to NOT_CONNECTED if it client looses connection to the server.
Apis will set the item qualities to CONFIG_ERROR if srcItemID or VQT attributes are invalid.
Apis will set the item qualities to COMM_ERROR if reading invalid/error data from the server.

DataSet

Item representing the IEC61850 concept of an DataSet on the server.

The item type has the following properties:

Name	Description	ID	Flags
SrcItemID	DataSet reference, must be on the form LDName/LNodeName.dataSetName . [string]	5030	Persisted
Nodes	Array of DataObject/DataAttribute items, must be on the form LDName/LNodeName.dataObject[FC] or LDNAME/LNodeName.dataObject.dataAttribute(arrayIndex)[FC].[string[]]	17002

Note:

DataSet cannot be modified or deleted when referenced by any reports.
Always have the DataSet items in the module that is refered to by any reports.

Change SrcItemID: If DataSet exists on server, the DataSet item will point to the existing DataSet on the server. If it does not exist, it will

try to delete the old DataSet on the server,
try to create a new DataSet with the Nodes array on the server. This will effectively either be a rename of the DataSet or a copy of the previous DataSet. Example: Change SrcItemID from Device1/Node1.Dataset1 -> Device1/Node1.Dataset2, this will result in both Dataset1 and Dataset2 on the server if Dataset1 can not be deleted (e.g. used in a report), with Dataset2 containing the same nodes as Dataset1. The new Dataset2 can now be modified/deleted untill used in a report.

Change Nodes: If DataSet exist on the server, the DataSet will be deleted and recreated with the new set of nodes. If it can not be deleted, the quality will change to CONFIG_ERROR and the reason/error is printed in the log. If it can be deleted, or the DataSet is not already present on the server, a new DataSet will be created with the new set of nodes. If there is any configuration issues with the nodes, the item quality will change to CONFIG_ERROR and the reason/error is printed in the log. Example: if the reason it cannot be changed is because the DataSet cannot be modified or deleted, a possible workaround is to change the SrcItmID to create a copy of the DataSet, and then changing the nodes on the new DataSet.

Delete Item: If DataSet is not in use, e.g. reference in any reports, the DataSet on the server will be deleted. If it is not possible to delete the DataSet on the server, only the item will be deleted and the error/reason is printed to the log. Resolve the issue, add the DataSet item again, and delete it again to permanently delete it from the server.

Basic Item Properties

BufferedReport

Reporting allows a server to send data based on events and without explict request by the client. What data is sent and which events that cause the reports to be sent are configured through the attributes of the item.

Main characteristics of Buffered Reports:

Buffered Reports involve an intermediary buffering of report data within the IED before it is sent to the client. This buffer stores a sequence of reports.
In case of a communication interruption or if the client is temporarily unable to receive reports, the buffered reports are stored in the IED and can be retrieved once the communication is restored. This ensures that no data is lost during the period of communication failure.
Buffered reporting is more complex and requires additional memory and processing resources within the IED. It is essential for applications where data continuity and retrieval of missed reports are critical, such as in disturbance recording or where detailed post-event analysis is required.

The item type has the following properties:

Name	Description	ID	Flags
SrcItmID	Data reference to the buffered report, on the form LDName/LNodeName.BR.reportName. [string]	5030	Persisted
DataSet	The DataSet reference, must be on the form LDName/LNodeName.dataSetName. [string]	17007
Integrity period [ms]	The integrity period specifies the interval for the periodic sending of intergrity messages in report if integrity is specified as trigger option in the report. [0-4,294,967,295]	17008
Trigger options	Specifies which events will trigger reports	17009
GI	Setting this parameter to true will initiate a report to be sent to the client. This report will contain all the data of the associated data set. The GI parameter will be reset to false automatically by the server once the report has been sent	17011
Enabled	By setting this variable to true reporting will be enabled. Note that changing/writing and configuration fields of the RCB will fail as long as reporting is enabled	17012
ResvTms [ms]	Value of -1 = reserved by configuration for a certain set of clients, value 0 = report is not reserved, value > 0 = the time that the reservation shall be maintained after the association was closed or interrupted. [-32,768 to 32,767]	17013
Report ID	The report ID identifies the RCB that has caused the generation of the report. [string]	17014
Optional fields	A bitstring where each bit indicates whether an optional field is included in the reports. The following optional fields exist: sequence-number, report- timestamp, reason-for-inclusion, data-set-name, data-reference, buffer-overflow, entryID, segmentation, and conf-revision. For URCBs the values of buffer-overflow and entryID are ignored	1705
Buffer time [ms]	For buffered reports, this is the interval between each report sent from the server. [0-4,294,967,295]	17016
Purge buffer	If the rate of report generation exceeds the transmission or processing capacity, the buffer may become full. If enabled, older reports in the buffer may be purged (deleted) to make room for new reports. This ensures that the most recent and relevant data is available for transmission, at the cost of losing older, untransmitted reports.	17018
Sequence number	Number of received events from the server, incremented each time a new update is received from the server.	17017	ReadOnly

Notes:

Make sure DataSet item that corresponds to the DataSet reference used in the report is present.

DataReport

Main characteristics of Data Reports (Unbuffered Reports):

Data Reports, or Unbuffered Reports, are sent directly from the IED (Intelligent Electronic Device) to the client without any intermediary storage of the report data within the IED.
If there is a communication interruption or if the client is unable to receive the report (for example, due to network congestion or client unavailability), the reports that occur during this time are lost. There is no mechanism to retrieve missed reports once the communication is restored.
This type of reporting is simpler and requires less memory and processing power within the IED, making it suitable for applications where real-time monitoring is essential, and data loss during communication failures is acceptable.

The item type has the following properties:

Name	Description	ID	Flags
SrcItmID	Data reference to the report, on the form LDName/LNodeName.RP.reportName. [string]	5030	Persisted
DataSet	The DataSet reference, must be on the form LDName/LNodeName.dataSetName. [string]	17007
Integrity period [ms]	The integrity period specifies the interval for the periodic sending of intergrity messages in report if integrity is specified as trigger option in the report. [0-4,294,967,295]	17008
Trigger options	Specifies which events will trigger reports	17009
Reserved	if the setting was successful the RCB will be reserved exclusively for this client	17010
GI	Setting this parameter to true will initiate a report to be sent to the client. This report will contain all the data of the associated data set. The GI parameter will be reset to false automatically by the server once the report has been sent	17011
Enabled	By setting this variable to true reporting will be enabled. Note that changing/writing and configuration fields of the RCB will fail as long as reporting is enabled	17012
Report ID	The report ID identifies the RCB that has caused the generation of the report. It equals the RptID field of the RCB.	17014
Optional fields	A bitstring where each bit indicates whether an optional field is included in the reports caused by this RCB. The following optional fields exist: sequence-number, report- timestamp, reason-for-inclusion, data-set-name, data-reference, buffer-overflow, entryID, segmentation, and conf-revision. For URCBs the values of buffer-overflow and entryID are ignored	1705
Sequence number	the current sequence number of the RCB. After sending a report the RCB will increment the sequence number by one	17017	ReadOnly

Apis IEC 62056Bee

Description of ApisIEC62056Bee

Provider: Prediktor

The IEC62056Bee module has the following item types

StatusItem

Properties

The IEC62056Bee module has the following properties:

Name	Description	ID	Flags
Com port	Serial IO Com port id. Must Start with COM	1055	Persisted, ExpertPage
Communication type	Choose the communication type for the connection to the meter	1020	Persisted, Enumerated
Communicationtimeout	The communication timeout period in milliseconds	1050	Persisted, ExpertPage
Connected	Status if Apis is connected to device.	1200	InfoPage
ConnectedTime	Last time host connected device.	1215	InfoPage
Device Address	RS485 Address of the device. Will be ommitted if not set. 32 characters Max	1017	Persisted
Enable	If true the module will try to connect the equipment with IP address and port number specified (default: false).	1010	Persisted
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ItemUpdateInterval	The interval in seconds that the module will try to update the read items.Minimum value is 1.	1013	Persisted
LastMsgRcv	Last message received from device.	1210	InfoPage
LastMsgSend	Last message send to device.	1205	InfoPage
Log file	The file name for Seg scale serial IO log.	1090	Persisted, ExpertPage
Log file Maxsize	The max size of the log file before it get recycled (Default value=5.000.000 [bytes]).	1085	Persisted, ExpertPage
MaxParseTime	The maximum time used to parse a SF message [ms].	1300	PerformancePage
Meter manufacturer	Choose the right configuration for the meter. This selection affects the use of protocolmode and item creation	1015	Persisted, Enumerated
Password Level 1	Password used for level 1 data read.	1035	Persisted
Password Level 2	Password used for level 2 data read.	1040	Persisted
Password Level 3	Password used for level 3 data read.	1045	Persisted
ReconnectInterval	The interval in seconds that the module will try to connect to a device after lost connection.Minimum value is 1.	1012	Persisted
Serial IO Data bits	The serial IO Data bits	1065	Persisted, ExpertPage
Serial IO Stop bits	The serial IO Stop bits	1070	Persisted, Enumerated, ExpertPage
Serial IO Stop bits	The serial IO Stop bits	1080	Persisted, Enumerated, ExpertPage
TCP/IP address	The IP address of the meter. Used for TCP communication	1025	Persisted, URL
TCP/IP port	The IP port of the meter. Used for TCP communication	1030	Persisted

See also Module Properties

Commands And Events

The IEC62056Bee module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

A Register Readout items main purspose is to read out specific register data

The Register Readout item type has the following properties:

Name	Description	ID	Flags
Address	Register address.	11000	Persisted
Enable	Set to true to enable the item in the configuration.	10005	Persisted
Index	The index of the data field.	11010	Persisted
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	ExpertPage
Length	The length of the data field.	11020	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

A Register Readout items main purspose is to read out specific register data, after Set/Reset register is changed

The Register Set/Reset Readout item type has the following properties:

Name	Description	ID	Flags
Address	Register address.	11000	Persisted
Enable	Set to true to enable the item in the configuration.	10005	Persisted
Index	The index of the data field.	11010	Persisted
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	ExpertPage
Length	The length of the data field.	11020	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Reset Value	Value the Transaction Manager will check against.	12040	Persisted
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Set Value	Value to set in the Set/Reset register.	12030	Persisted
Set/Reset Address	Set/Reset Register address.	12000	Persisted
Set/Reset Length	Set/Reset Length of the data field in the register.	12020	Persisted
Set/Reset Offset	Set/Reset Offset of the data field in the register.	12010	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

A Register Data Interpreter Item main purpose is iterpret data read out bu registerreadoutItems

The Register Data Interpreter item type has the following properties:

Name	Description	ID	Flags
Enable	Set to true to enable the item in the configuration.	10005	Persisted
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	11120	Persisted
Second Value Length	The length of the second data field in the register.	13040	Persisted
Second value start index	Zero-based index indicating where to start interpreting the read second data.	13030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Value Arithmetic	The arithmetic used on values from first and second register data. On subtraction, the second value will be subtracted from the first.	13001	Persisted, Enumerated
Value Cut Off Type	The cut off type is used on values to cut of positive or negative values.	13005	Persisted, Enumerated
Value interpretation type	This property determines how to interpret the data file value: String: reads the value as a plain string; BCD (Binary Coded Digital): reads the value as an integer and scales it according to the scale property.	11100	Persisted, Enumerated
Value Length	The length of the data field in the register.	13020	Persisted
Value start index	A zero-based index indicating where to start interpreting read data.	13010	Persisted

Properties

This item is used to expose internal status information

The StatusItem item type has the following properties:

Name	Description	ID	Flags
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Apis Interpreter

This module interprets single line ascii string terminated by terminating character like <CR><LF> received from serial port or TCP socket

Provider: Prediktor

The Interpreter module has the following item types

More information

Characteristics of the Interpreter module:

Reads ASCII string from a device and interprets to numeric value(s).
Supports Read and Write.
Supports query, Write->Read (synchronous)
Can act as a simple TCP server
Supports, serial and TCP/IP communication (TCP and UDP)

Further, as an integrated module in the Apis Hive, the following optional features are available:

High performance data logging to the Apis Honeystore historian, with OPC Historical Data Access server interface

Properties

The Interpreter module has the following properties:

Name	Description	ID	Flags
ACK	If Greater or equal "0" this value is sent as ACK on successful receive	1273	Persisted, ExpertPage
Serial BaudRate	Baud rate for serial communication. Valid only when Comm. type is Serial	1210	Persisted, Enumerated, ExpertPage
Buffer size	Size of buffer (min. 10).	1270	Persisted, ExpertPage
Serial COM port	The COM port to use. Valid only when Comm. type is Serial	1200	Persisted, Enumerated
Comm. type	Communication method, Serial or Winsock	1110	Persisted, Enumerated
Client command timeout	Time to wait for client command in (seconds) before giving up and reset connection	1320	Persisted
Serial DataBits	Number of bits in the bytes transmitted and received. Valid only when Comm. type is Serial	1230	Persisted, Enumerated, ExpertPage
Mode of operation	Read, Write, Write->Read, TCP-Server. Write->Read; Writes and then reads responce, TCP-Server acts as a stream server	1120	Persisted, Enumerated
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
Field separator	Separation character for values when multiple values in one string.	1075	Persisted, Enumerated, ExpertPage
Serial FlowControl	Flow control for serial communication. Valid only when Comm. type is Serial	1250	Persisted, Enumerated, ExpertPage
IP address	IP Address of Interpreter server. Valid only when Comm. type is Winsock	1310	Persisted, Computer
Interpret	Interpret string to numeric value(s)	1072	Persisted, ExpertPage
Serial Parity	Parity scheme for the serial communication. Valid only when Comm. type is Serial	1220	Persisted, Enumerated, ExpertPage
IP port	The TCP/UDP port of Interpreter server. Valid only when Comm. type is Winsock	1311	Persisted
RawValueReceive	Last telegram raw value received	1500	ReadOnly, PerformancePage
RawValueSend	Last telegram raw value received sent	1501	ReadOnly, PerformancePage
RawValueSend(hex)	Last telegram raw value received sent (hex)	1502	ReadOnly, PerformancePage
ResetOnTimeout	Reset communication when timeout error occurs.	1262	Persisted, ExpertPage
SkipAfterTermChar	Bytes rejected after termination character. Typical CRC.	1272	Persisted, ExpertPage
SkipLeft	Number of characters to skip on left side of telegram.	1073	Persisted, ExpertPage
SkipRight	Number of characters to skip on right side of telegram.	1074	Persisted, ExpertPage
Start character	If Greater or equal "0" this value is used as start character for synchronization	1269	Persisted, ExpertPage
Serial StopBits	Number of stop bits to be used. Valid only when Comm. type is Serial	1240	Persisted, Enumerated, ExpertPage
Terminating character	The character terminating the string.	1271	Persisted, Enumerated, ExpertPage
Timeout	Time-out interval, in milliseconds.	1261	Persisted, ExpertPage
Timer	Polling interval in TCP-Send mode transmit interval (seconds)	1055	Persisted
TracefileMaxSize	The max size of the trace file before the file is truncated in bytes. Default is 50 MB => 50 * 1024 * 1024	15000	Persisted, ExpertPage
TraceToFile	This is used to trace detail information about the incoming data over the link	15010	Persisted, File, ExpertPage
Trim control chars	Remove control characters like <CR> <LF> <STX> etc. from telegram prior to update item. Useful when you need to receive "control" characters	1280	Persisted, ExpertPage
IP protocol	Protocol type TCP/UDP. Valid only when Comm. type is Winsock	1312	Persisted, Enumerated

See also Module Properties

Commands And Events

The Interpreter module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
DataReady	Event indicating that new data is ready, i.e. item is updated with new value an timestamp. Use case: Connect HandleExteralItems on consuming modules to this event to instantly transfer value.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
StartSend	Triggers send of SendItems when Direction is Write or Write->Read.	Asynchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

A Interpreter item, built from raw data or measurement elements

The InterpreterItem item type has the following properties:

Name	Description	ID	Flags
Address	Position of field to interpret when multiple items in one telegram.	5020	Persisted
CRC calculation	CRC calculation. On InterpreterItem check CRC on telegram. On InterpreterSendItem generate CRC	10010	Persisted, Enumerated
CRC position	The position of CRC from RIGHT
CRC order	Byte order of multibyte CRC. MSB/LSB	10022	Persisted
CRC Skip Left	The number of bytes to exclude from CRC calculation left.	10030	Persisted
CRC Skip Right	The number of bytes to exclude from CRC calculation right.	10040	Persisted
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
Update only on change	Update timestamp only when value changes.	10005	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Unit	EU units - this is the unit this item value uses. For example: centimetres, kilograms, kilowatts, etc.	100	Persisted
Value	The current value of the item.	2	ReadOnly

Properties

A Interpreter item, built from raw data or measurement elements

The InterpreterItem item type has the following properties:

Name	Description	ID	Flags
Address	Position of field to interpret when multiple items in one telegram.	5020	Persisted
CRC calculation	CRC calculation. On InterpreterItem check CRC on telegram. On InterpreterSendItem generate CRC	10010	Persisted, Enumerated
CRC position	The position of CRC from RIGHT
CRC order	Byte order of multibyte CRC. MSB/LSB	10022	Persisted
CRC Skip Left	The number of bytes to exclude from CRC calculation left.	10030	Persisted
CRC Skip Right	The number of bytes to exclude from CRC calculation right.	10040	Persisted
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
Update only on change	Send value only when value has changed.	10005	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Unit	EU units - this is the unit this item value uses. For example: centimetres, kilograms, kilowatts, etc.	100	Persisted
Value	The current value of the item.	2	ReadOnly

Properties

Toggle this value to force write in Write mode

The CommandItem item type has the following properties:

Name	Description	ID	Flags
Description	Toggle this item to connect to the Interpreter server; true: is connect, false: is disconnect	01	Persisted
ExtItemOverrideMethod	This attribute decides what method to use when assigning a value from an external item.	5999	Persisted, Enumerated, BitMask
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
ResetCommand	Reset when value has been sent (Write Mode).	10110	Persisted
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Parent	The Item handle of the parent item to this item, an item in the same module as this item.	5500

The Parent attribute must be added manually and must point to InterpreterSendItem to be sendt.

Properties

Item telling if module is connected to the Interpreter server; true: is connected, false: is disconnected

The State Item item type has the following properties:

Name	Description	ID	Flags
Description	Item telling if module is connected to the Interpreter server; true: is connected, false: is disconnected.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Apis Java

This module connects to an Java application using JNI, exchanging data with Apis. Module is called ApisJava.

Provider: Prediktor

The Java module has the following item types

Properties

The Java module has the following properties:

Name	Description	ID	Flags
AddItembufferSnaphostAvg	The average duration in milliseconds of adding item snaphots	1530	PerformancePage
ApplicationFilePath	The file path in which the applicationsfiles should reside	1152	Persisted, Folder
AutoDeletePersistenceItems	If PersistedStateDestination is Items (or Both files and items) items will be created behind the scenes in which the states will be stored. An item of this type will be removed if the last persistence action did not include the state which corresponds to this certain item and this property is set to true. The reason why one might to turn off this option is to reduce the time spent on persisting the states	1590	Persisted, ExpertPage
Dbg-ExceptionHandlerMode	This value determines how an exception is handled. ONLY USE FOR DEBUGGING PURPOSES!	3000	Persisted, Enumerated, ExpertPage
EventReportLevel	The level of the reported events from the java application. (E.g. if Warning is chosen, Warning and Alarm events will be reported, but the Information events will not.)	1197	Persisted, Enumerated
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ExternalItem report	A status-report for the External Item manager of this module	110	InfoPage
ItemWriteMasking	Set the quality level of items that will be written to the Java application from this module	1200	Persisted, Enumerated, ExpertPage
JavaAppStartfile	Name of file which the Java-application will open when it is first started by the ApisJavaBee. The path of this file is set in the ApplicationPath property	1150	Persisted
JavaAppVisible	If false all of the windows of this Java-application shall be closed.	1140	Persisted, ExpertPage
LibraryFilePath	The file path in which library files should reside	1154	Persisted, Folder
MaxItemBufferSize	The maximum time steps item values will be buffered	1195	Persisted
NativeJavaClass	The java class which contains the defintion of the native C-functions	1090	Persisted, ReadOnly, ExpertPage
OneStepTimeLapse	The duration in milliseconds of the previous call to 'OneStep' function	1500	PerformancePage
OneStepTimeLapseAvg	The average duration in milliseconds of all calls to 'OneStep' function	1505	PerformancePage
OneStepTimeLapseJavaAvg	The average duration in milliseconds of all calls to 'OneStep' function, inside the java application.	1525	PerformancePage
OneStepTimeLapseMax	The maximum duration in milliseconds of any call to 'OneStep' function	1510	PerformancePage
PersistedStateDestination	Decides where the destination of the persisted states. They may be persisted to File(s), Item(s), or Both. State persistence is turned off by selecting None	1570	Persisted, Enumerated, ExpertPage
PersistValToInitVal	Choose strategy for copying and persisting current value to the InitValue. Tip: Consider using an InitVQTFromHoneystore attribute instead, for better performance.	1220	Persisted, Enumerated, ExpertPage
RMIServerInfo	The complete RMI Server info, if applicable, of the Java application	1550	InfoPage
Run	States whether the java application is simulating. (I.e . whether the OnOneStep() java method should be called on regular basis.)	1095	Persisted
SaveAction	Determines when the java application will be saved	1148	Persisted, Enumerated, ExpertPage
StartupJavaClass	The java class which contains the startup method (StartupMethod)	1040	Persisted, ReadOnly, ExpertPage
StartupJavaMethod	The static method which will be called after the JVM and the StartupJavaClass have been loaded	1050	Persisted, ReadOnly, ExpertPage
StateFileFolder	The folder in which the file(s) recides (Working folder)	1600	Persisted, ExpertPage
StateLoggers	The loggers which will log the state if PersistedStatesDestination is Items	1580	Persisted, ExpertPage
SupportsAttributes	If true the java application supports item-attribute reflection	1610	ReadOnly, Hidden
SupportsItemsPersistence	True if state can be persisted to items	1620	ReadOnly, Hidden
SupportsPrimitiveArrays	Indicates whether primitive array transfer is supported (this is a more optimal way of transferring vectors and matrices)	1560	ReadOnly, Hidden
Timer	A timer which generates events. If set to less than 50, the timer is not active.	1160	Persisted
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TimeStep	The time step in the java application (ms)	1159	Persisted

See also Module Properties

Commands And Events

The Java module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
OneStepDone	An event indicating that the OnOneStep() java method is finished.	Normal
OnTimer	An event fired when at a rate given by the ModelRefreshInterval or Timerperiod property	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
OneStep	A command calling the OnOneStep() java method.	Asynchronous
RefreshTimestamps	Will force refresh of the time stamps of items (Scalar, Vector and Matrix).	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

Scalar value of arbitrary type.

The Scalar item type has the following properties:

Name	Description	ID	Flags
InputValue	If true, this item is an input value into the Java-application (Write). If it's set to false, then this value is an output from the Java-application (Read).	10030	Persisted
Itemtype	Decides which type (e.g. Double, String, Bool) the item is to be. (Bool=10, Double=20, String=30)	10020	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Vector value of arbitrary type

The Vector item type has the following properties:

Name	Description	ID	Flags
Dimension	The dimension of a vector item (number or elements).	5007	Persisted
InputValue	If true, this item is an input value into the Java-application (Write). If it's set to false, then this value is an output from the Java-application (Read).	10030	Persisted
Itemtype	Decides which type (e.g. Double, String, Bool) the item is to be. (Bool=10, Double=20, String=30)	10020	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Matrix value of arbitrary type

The Matrix item type has the following properties:

Name	Description	ID	Flags
Columns	The number or columns in matrix item.	5009	Persisted
InputValue	If true, this item is an input value into the Java-application (Write). If it's set to false, then this value is an output from the Java-application (Read).	10030	Persisted
Itemtype	Decides which type (e.g. Double, String, Bool) the item is to be. (Bool=10, Double=20, String=30)	10020	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Rows	The number of rows in a matrix item.	5008	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Item that holds a time value

The TimeItem item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Item which contains a value of a state

The PersistenceItem item type has the following properties:

Name	Description	ID	Flags
PersistenceHierarchy	A string array containing the persistence hierarchy.	10200	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10100	Persisted, Enumerated

Properties

Contains the file name of a file in which states will be stored

The StateFileItem item type has the following properties:

Name	Description	ID	Flags
FileAccess	Decides whether the file specified in the item is in read, write, or read/write mode (Read=0, Write=1, Read/Write=2).	10300	Persisted, Enumerated
ForceStopBeforeRead	This property will force the application to go to a "STOPPED" state before loading the state file. If this attribute is false, the application must be put in the "STOPPED" state manually.	10330	Persisted
IncludeStateFileFolder	If this property is true, the state file will be put in the "StateFileFolder", otherwise it will be stored in the current directory.	10320	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
TriggerOnChange	If true, the state file will be read/written to when the item changes.	10310	Persisted
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Will trigger read/write of states

The StateTriggerItem item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
ReadStates	If this property is set to "true", it triggers the reading of states, if "false" it triggers writing.	10400	Persisted
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Performs a specific command when set to true. The command is decided by attribute COMMAND (10500)

The CommandItem item type has the following properties:

Name	Description	ID	Flags
CommandType	This attribute allows you to select the type of command to use.	10500	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Reset	Setting this property to true will perform a reset in the java application on the next iteration.	10700	Persisted
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Contains the current status of the module represented as an integer. UNDEFINED = 0, STOPPED = 1, RUNNING = 2, WAITINGFORSTOP = 3, LOADING = 4, LOADED = 5

The StatusItem item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
StatusAsString	Set this property to display the current status as a string instead of an integer.	10600	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Apis Logger

This module stores item data into the Apis Honeystore real-time trend historian. Data are retrieved through the Apis OPC HDA server and the APIS Hive UA server. Any OPC HDA and UA client can then access the data.

Global attributes

The Apis Logger registers 2 global attributes to the Hive:

The regular global boolean attribute that turns trending on/off for the item in question, given the same name as the Apis Logger module itself, ie. LoggerName
A global expression attribute that when used, represents an expression to be applied upon the value before it is stored to the database. The attribute is given the name LoggerName_Expr.

Logging of raw values (VQTs)

To store the raw VQTs of an item into a timeseries, you simply add the regular logger attribute (named LoggerName) to that item, and set its value to true.

Logging of calculated values (VQTs)

To store a derived, calculated value instead of the raw value, you also add the global expression attribute (name LoggerName_Expr) to the item, and specify the desired expression. You will also have to add and set the regular logger attribute to the item, and set its value to true.

When storing a calculated value, instead of the raw value, i.e. using the LoggerName_Expr attribute, the value type of the samples will typically be 8 byte float (unless the "calculation" result is a raw value), and the HDA quality part will be Calculated. Further, the name of the item in the HoneyStore database, will be the same as in the case of plain logging; the item ID in the Hive configuration.

Valid Expressions are the same as for the Calculations Operator of Legacy function item. There is one limitation however, you cannot use more than a single external input to the expression. Meaning just a single ex1 is allowed in the Expression.

Hint: If you would like to trend both the raw, as well as a calculated value of an item, you will need to use 2 different Apis Logger modules, targetting to different HoneyStore databases. Also, then you should specify the TimeseriesAccessOrder of the logger modules.
Further, if you want to access timeseries for both stored items inside your Hive configuration, you can use an ApisHSMirrorBee to expose the items having the higher TimeseriesAccessOrder.

Provider: Prediktor

Properties

The Logger module has the following configuration properties:

Name	Description	ID	Flags
AutoDeleteDB	Set to TRUE if the database of this module shall be automatically deleted when the module itself is deleted.	1500	Persisted, ExpertPage
AutoDeleteTrend	Specifies whether trends automatically will be deleted from the database when they are deleted from the namespace of Apis Hive and/or when their global log attribute is set to 'false'.	1475	Persisted, Enumerated, ExpertPage
AutoLoggerItemIDFilters	A set of item ID wildchar filters that items must satisfy to be automatically logged when their logg attribute goes to true. Only applies when DefaultLogAttributeValue is true!	1610	Persisted, ExpertPage
Cache size	The size of each cache in bytes, default value is 10040 bytes	1420	Persisted, ReadOnly, ExpertPage
Database	The public name of the database into which this instance logs data.	1010	Persisted, ReadOnly
Database pool recycle strategy	Tells how to recycle the databases in the databasename pool, when Log-switch item triggers a change of active database. None (no database pooling) - reuse existing database name. The current database is renamed by appending its creation date and time to its name, and a new database is created having same name as before, or named according to the value of Log-switch new database name item. When strategy is None, the Log-switch databasename pool is ignored. Sliding (first always active) - means that the first database in the pool always is the active, a switch simply shifts the history of the first to second, second to third and last to nothing. When strategy is Sliding, the Log-switch databasename pool must contain at least one database name. Circular (next in pool active) - means that the next database in the pool will set as the active when a switch is triggered. When strategy is Circular , the Log-switch databasename pool must contain at least one database name.	1718	Persisted, Enumerated, ExpertPage
DefaultLogAttributeValue	The default value of the global log attribute when added to items. Note! If you change this property, you need to restart the Hive instance to make it take effect.	1600	Persisted, ExpertPage
FlushingStrategy	Determines the strategy to use when temporarily flushing the whole cache file to disk.	3010	Persisted, Enumerated, ExpertPage
FreshestValue	When TRUE, all items will be read directly from their physical source to receive the freshest possible values.	2010	Persisted, ExpertPage
Historylength_Unit	Total length of historical data in database is given by multiplying this property with the Historylength_X property.	1410	Persisted, Enumerated
Historylength_X	Total length of historical data in database is given by multiplying this property with the Historylength_Unit property.	1400	Persisted
Log timestamp-filter item	A reference to an item giving a maximum timestamp filter for item value imestamps. Items having timestamps newer than this filter value, will not be logged. Only applies when Recordtype is Eventbased.	1750	Persisted, ApisItem, ExpertPage
Log-enable item	When the value of this item is 'true', the module is logging timeseries. When value is 'false', logging is disabled.	1740	Persisted, ApisItem, ExpertPage
LogOnStart	When 'true' and property RecordType is 'Eventbased...', a sample will be written to the database at every time the mode of the database changes to Online, every time a 'LogEnable' item goes true and everytime the module enters the 'Started' runningstate.	1650	Persisted, ExpertPage
LogStateResolution	If using any of 'Log-switch item', 'Log-enable item', 'Log-trigger item' or 'Log-switch new database name item' properties, this is the internal polling period in Apis when checking for updated item states.	1690	Persisted, ExpertPage
Log-switch databasename pool	A pool of databasenames that will be re-used when the Log-switch item toggled. If this pool is empty, the current database name (according to Database-property) will be re-used and the previous database will be set to read-only and renamed by appending the creation-date to its name.	1720	Persisted, ExpertPage
Log-switch item	Set to an item that will control when active log/database is switched. If ie. the current database will be renamed, set in read-only mode and a new database will be started. If set to a boolean item; log switches when value toggles 'false' to 'true'. If set to a non-boolean item; log switches when value changes.	1700	Persisted, ApisItem, ExpertPage
Log-switch new database name item	When the database is switched using Log-switch item, and the Database pool recycle strategy is None, the value of this item holds the name of new database to switch to. If the Database pool recycle strategy is other than None, this property is ignored.	1710	Persisted, ApisItem, ExpertPage
Log-trigger item	Set to an item that will control when data is sampled and stored to the database. If set to a boolean item; data is stored when value toggles 'false' to 'true'. If set to a non-boolean item; data is stored when value changes.	1730	Persisted, ApisItem, ExpertPage
MaxItems	Maximum number of items (trends) in this database.	1050	Persisted, ReadOnly
Path	The directory path of the database files.	1020	Persisted, ReadOnly, Folder
PriorityLevel	Specifies the priority level for the working thread of this ApisLoggerBee instance.	3000	Persisted, Enumerated, ExpertPage
Recordtype	This property determines how data logged by this module, is stored to the database: Sampled Stores data, without quality info, at a regular time interval given by Resolution Sampled with quality Stores data, with quality info, at a regular time interval given by Resolution Eventbased with quality Stores data, with quality and timestamp info, whenever data (Value, quality or timestamp) changes. The data is scanned for changes at a regular time interval, given by Resolution	1210	Persisted, Enumerated
Resolution	When 'Recordtype' is one of the sampled options, this is the sampling period in seconds. If 'Recordtype' is 'Eventbased with quality', this is the internal polling period in Apis when checking for updated item values.	1300	Persisted
TimeseriesAccessOrder	An unsigned integer, determining the order of this ApisLoggerBee module for handling timeseries requests, when an item is logged by more than one ApisLoggerBee module.	301202	Persisted

Informational properties:

Name	Description	ID	Flags
CachePath	The path to the location of the cache-file of the database.	301015	InfoPage
ConfigObserverCookie	The cookie identifying this module amongst the configuration aware clients of Apis Hive.	301400	InfoPage
Database Handle	The internal handle of this database in Apis Honeystore.	301010	InfoPage
Disk Usage max	The maximum usage of disk space given in giga bytes on the drive that the database of this module are configured to reside.	301052	InfoPage
Enabled	When 'true', the module is logging timeseries, when 'false' logging is disabled	301000	InfoPage
EnabledReason	An explanatory text for the 'Enabled' property.	301001	InfoPage
LogAttributeID	The global log attribute ID assigned from Apis Hive.	301200	InfoPage
LogExprAttributeID	The global log expression attribute ID assigned from ApisHive.	301201	InfoPage
RAM Usage	The usage of physical memory (RAM) in mega bytes for the database of this module.	301050	InfoPage
TimeSrvEventID - LogState	The time-server EventID assigned from the Apis time server for the LogState timer.	301150	InfoPage
TimeSrvEventID - Sampler	The time-server EventID assigned from the Apis time server for data-sampling timer.	301100	InfoPage

Performance properties:

Name	Description	ID	Flags
AvgReadTime	The average time in milliseconds spent reading items from Apis Hive.	101010	PerformancePage
AvgStoreTime	The average time in milliseconds spent storing items to Apis Database.	101020	PerformancePage
AvgTotalTime	The average time in milliseconds spent in iterating loop.	101030	PerformancePage
HiveLastUpdCount	The number of items reported as updated at the previous request.	101006	PerformancePage
NumLogItems	Number of items this ApisLogger instance stores to its database.	101000	PerformancePage
NumPendingItems	Number of pending items this ApisLogger instance is waiting to get correct meta info, to be able to create and store to its database.	101001	PerformancePage
PeakReadTime	The maximum time in milliseconds spent reading items from Apis Hive.	101040	PerformancePage
PeakStoreTime	The maximum time in milliseconds spent storing items to Apis Database.	101050	PerformancePage
PeakTotalTime	The maximum time in milliseconds spent in iterating loop.	101060	PerformancePage
UpdSinceQueryTime	The time used when requesting updated items from the Hive.	101005	PerformancePage

See also Module Properties

Commands And Events

The Logger module has the following Commands and Events:

Events

Name	Description	Event Type
LogDone	An event notifying that a Log-cycle issued by the log-command of this LoggerBee instance has completed.	Normal

Commands

Name	Description	Command Type
Log	A command initiating a Log cycle of the items logged by this LoggerBee instance.	Synchronous
Log_DataPush	This command ensure that all items and samples in the data push package, are stored to the HoneyStore database where applicable. See also: APIS data transfer mechanism; Data Push	Synchronous

See also Commands And Events

Apis Modbus Master

This module communicates with Modbus slave as a Modbus master using Modbus RTU or TCP

Provider: Prediktor

The Modbus module has the following item types

More information

Modbus Specifications and Implementation Guides

Characteristics of the Apis Modbus Master module:

Implements Modbus Master
Supports: Modbus TCP, RTU over TCP/IP and Modbus RTU (serial)
Support redundant slaves in TCP mode
Uses following Modbus function codes:
- 1 Read Coil status
- 2 Read Input status
- 3 Read Holding registers
- 4 Read Input registers
- 5 Force single Coil
- 6 Preset single Register
- 16 Preset multiple Registers
Supports following data types
- 2 byte signed int
- 4 byte signed int
- 2 byte unsigned int
- 4 byte unsigned int
- 8 byte unsigned int
- 4 byte float
- 8 byte float
- Unicode String (UTF-16)
- ACSII String (UTF-8)
- 2 byte signed int (Sign and magnitude)
- 4 byte signed int (Sign and magnitude)
- 2 byte float (Half-precision floating-point
Endianness
- Big-endian
- Little-endian
Bit numbering
- MSB..LSB
- LSB..MSB

Further, as an integrated module in the Apis Hive, the following optional features are available:

High performance data logging to the Apis Honeystore historian, with OPC Historical Data Access server interface

Properties

The Modbus module has the following properties:

Name	Description	ID	Flags
AdressMapping	True: Registertype base adress is subtracted from address given in SrcItemID, eg. daddr = SrcItemID - 40000 , for Holding registers	1125	Persisted
AdressOffset	True: Registers are adressed starting at zero: register 1 is adressed as 0	1127	Persisted
BaudRate	Baud rate for serial communication. Only valid when Comm. type is Serial	1210	Persisted, Enumerated, ExpertPage
Byteorder	Byte transfer order	1121	Persisted, Enumerated
COM port	The COM port to use. Only valid when Comm. type is Serial	1200	Enumerated, ExpertPage
Comm. type	Communication method; Serial, TCP/IP or None. Set to None if not connected to simulate signals.	1110	Persisted, Enumerated
DataBits	Number of bits in the bytes transmitted and received. Only valid when Comm. type is Serial	1230	Persisted, Enumerated, ExpertPage
Default Slaveaddress	The Slaveaddress (Unit ID) on Modbus slave, this property can be set individually on item level.	1260	Persisted, ExpertPage
Endian	Modbus is a "big-endian" protocol: that is, the more significant byte of a 16-bit value is sent before the less significant byte. It seems obvious that 32-bit and 64-bit values should also be transferred using big-endian order. However, some manufacturers have chosen to treat 32-bit and 64-bit values as being composed of 16-bit words, and transfer the words in little-endian order. For example, the 32-bit value 0x12345678 would be transferred as 0x56 0x78 0x12 0x34. Select LittleEndian to use this mixed ordering.	1120	Persisted, Enumerated
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
FlowControl	Flow control for serial communication. Only valid when Comm. type is Serial	1250	Persisted, Enumerated, ExpertPage
Function Delay	Delay between multiple function calls where inquired data is not organized continuous in modbus registers and multiple calls are required on every read cycle. (ms)	1060	Persisted
IP address or host name	Ip Address or host name of Modbus server. Only valid when Comm. type is TCP/IP	1310	Persisted, Computer
Handle no response	How no or invalid response from particular slave is handled. Quality com_failure, keep last value and timestamp Quality unsertain, keep last value and timestamp Quality good, keep last value and timestamp	1310	Persisted, Computer
LastQuery	Last command to modbus slave	1500	ReadOnly, PerformancePage
LastResponse	Last modbus slave response	1501	ReadOnly, PerformancePage
Number Of Redundant Slaves	The maximum number of redundant slave for this instance, valid range is 0-2.	2000	Persisted, ExpertPage
Parity	Parity scheme for the serial communication. Only valid when Comm. type is Serial	1220	Persisted, Enumerated, ExpertPage
Port or service	The TCP port or the name of the service socket of Modbus server. Only valid when Comm. type is TCP/IP	1311	Persisted
Poll interval	Set this to other than 0 for a timer based polling (seconds)	1055	Persisted
Read optimization	Valid only for function codes 03 Read Holding Registers and 04 Read Input Registers. Read strategy if data is organized in series with no gap in registry. Continuous Datatype: (default) Multiple values are read of same datatype. Continuous Address: Multiple values are read regardless of datatype.
RedundantComputer_1	The computer hosting the redundant Modbus slave, if configured.	2010	Persisted, ExpertPage
RedundantPort_1	The TCP port of the redundant Modbus slave, if configured.	2011	Persisted, ExpertPage
RedundantComputer_2	The computer hosting the redundant Modbus slave, if configured.	2020	Persisted, ExpertPage
RedundantPort_2	The TCP port of the redundant Modbus slave, if configured.	2021	Persisted, ExpertPage
Reset socket on no response	Resets socket immediately on no response, set to false if some request might not response, in order to maintain communicaton to working register	2021	Persisted, ExpertPage
Socket timeout	The timeout, in seconds, for blocking send and receive calls. Only valid when Comm. type is TCP/IP	1315	Persisted
StopBits	Number of stop bits to be used. Only valid when Comm. type is Serial	1240	Persisted, Enumerated, ExpertPage
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TracefileMaxSize	The max size of the trace file before the file is truncated in bytes. Default is 50 MB => 50 * 1024 * 1024	15000	Persisted, ExpertPage
TraceToFile	This is used to trace detail information about the incoming data over the link	15010	Persisted, File, ExpertPage

See also Module Properties

Commands And Events

The Modbus module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
ReadDone	An event signalled when a read of modbus slave has finished.	Normal
WriteDone	An event signalled when a write to modbus slave has finished.	Normal
PollDone	An event signalled when a complete poll operation of slave has finished. User case: Connect this event to "Start Polling" command of another Modbus module accessing same slave without polling rate to avoid to modules to access same slave simultaneously, to reduce risk of corrupt response.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
Start Polling	Initiate a poll from slave.	Asynchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

Single bit Read-Only Starting address 0x10001 to 0x1FFFF when address mapping is active or 0 to FFFF when addressmapping deactivated

The DiscretesInput item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
External quality tag	External tag overriding quality.	100040	Persisted
External quality mask	Bitmap representing quality bits field, when External quality tag is used.	100041	Persisted
External pattern bad quality	Bit pattern determinating bad quality, when External quality tag is used.	100042	Persisted
External mask unertain quality	Bit pattern determinating unsertain quality, when External quality tag is used.	100043	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Read single	Force master to read this item only in a single request. Used to optimize error handling. WARNING: Enabling this feature on numerous items will affect overall performance	10032	ReadOnly
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Unit	EU units - this is the unit this item value uses. For example: centimetres, kilograms, kilowatts, etc.	100	Persisted
Value	The current value of the item.	2	ReadOnly

Properties

Single bit Read-Write Starting address 0x00001 to 0x0FFFF when address mapping is active or 0 to FFFF when addressmapping deactivated

The Coil item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Direction	Direction of data. Input (false) or Output (true).	5040	Persisted
External quality tag	External tag overriding quality.	100040	Persisted
External quality mask	Bitmap representing quality bits field, when External quality tag is used.	100041	Persisted
External pattern bad quality	Bit pattern determinating bad quality, when External quality tag is used.	100042	Persisted
External mask unertain quality	Bit pattern determinating unsertain quality, when External quality tag is used.	100043	Persisted
EvaluationOrder	What order to use to evaluate the values: Apis: The value is written to the slave on every cycle; Slave: The value is read from the slave before the write. The value is only written to the slave when its changed in Apis.	10020	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Read single	Force master to read this item only in a single request. Used to optimize error handling. WARNING: Enabling this feature on numerous items will affect overall performance	10032	ReadOnly
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Unit	EU units - this is the unit this item value uses. For example: centimetres, kilograms, kilowatts, etc.	100	Persisted
Value	The current value of the item.	2	NormalPage
Write immediately	Send value immediately to slave on set value independet of polling rate (Valid only when Direction = true).	10125	NormalPage

Properties

16 bit word Read-Only Starting address 0x30001 to 0x3FFFF when address mapping is active or 0 to FFFF when addressmapping deactivated

The InputRegister item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Byteorder	Only valid when Valutype is Unicode String or ASCII, overrides module Byteorder. Byte transfer orde	10013	Persisted, Enumerated
Endian	Only valid when the Valuetype property is set to "Unicode String" or "ASCII". This property overrides the module's endian. Modbus is a "big-endian" protocol: that means the more significant byte of a 16-bit value is sent before the less significant byte. Be careful with 32-bit and 64-bit values, which may not be transferred using big-endian order. Some manufacturers treat 32-bit and 64-bit values as being composed of 16-bit words, and transfer the words in little-endian order. For example, the 32-bit value 0x12345678 would be transferred as 0x56 0x78 0x12 0x34. Select LittleEndian to use this mixed ordering.	10012	Persisted, Enumerated
External quality tag	External tag overriding quality.	100040	Persisted
External quality mask	Bitmap representing quality bits field, when External quality tag is used.	100041	Persisted
External pattern bad quality	Bit pattern determinating bad quality, when External quality tag is used.	100042	Persisted
External mask unertain quality	Bit pattern determinating unsertain quality, when External quality tag is used.	100043	Persisted
Modulus	Value = registerhigh x Modulus + registerlow. Valid only for 4 byte signed and unsigned int	10015	Persisted, Enumerated
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Read single	Force master to read this item only in a single request. Used to optimize error handling. WARNING: Enabling this feature on numerous items will affect overall performance	10032	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
StringSize	The number of buffers to read. Only valid when "Valuetype" is "Unicode String" or "ASCII".	10011	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Unit	EU units - this is the unit this item value uses. For example: centimetres, kilograms, kilowatts, etc.	100	Persisted
Value	The current value of the item.	2	ReadOnly
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10010	Persisted, Enumerated

Properties

16 bit word Read-Write Starting address 0x40001 to 0x4FFFF when address mapping is active or 0 to FFFF when addressmapping deactivated

The HoldingRegister item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Direction	Direction of data. Input (false) or Output (true).	5040	Persisted
Byteorder	Only valid when Valutype is Unicode String or ASCII, overrides module Byteorder. Byte transfer orde	10013	Persisted, Enumerated
Endian	Only valid when the Valuetype property is set to "Unicode String" or "ASCII". This property overrides the module's endian. Modbus is a "big-endian" protocol: that means the more significant byte of a 16-bit value is sent before the less significant byte. Be careful with 32-bit and 64-bit values, which may not be transferred using big-endian order. Some manufacturers treat 32-bit and 64-bit values as being composed of 16-bit words, and transfer the words in little-endian order. For example, the 32-bit value 0x12345678 would be transferred as 0x56 0x78 0x12 0x34. Select LittleEndian to use this mixed ordering.	10012	Persisted, Enumerated
External quality tag	External tag overriding quality.	100040	Persisted
External quality mask	Bitmap representing quality bits field, when External quality tag is used.	100041	Persisted
External pattern bad quality	Bit pattern determinating bad quality, when External quality tag is used.	100042	Persisted
External mask unertain quality	Bit pattern determinating unsertain quality, when External quality tag is used.	100043	Persisted
EvaluationOrder	What order to use to evaluate the values: Apis: The value is written to the slave on every cycle; Slave: The value is read from the slave before the write. The value is only written to the slave when its changed in Apis.	10020	Persisted, Enumerated
Modulus	Value = registerhigh x Modulus + registerlow. Valid only for 4 byte signed and unsigned int	10015	Persisted, Enumerated
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
StringSize	The number of buffers to read. Only valid when "Valuetype" is "Unicode String" or "ASCII".	10011	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Unit	EU units - this is the unit this item value uses. For example: centimetres, kilograms, kilowatts, etc.	100	Persisted
Value	The current value of the item.	2	NormalPage
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10010	Persisted, Enumerated
Write immediately	Send value immediately to slave on set value independet of polling rate (Valid only when Direction = true).	10125	NormalPage

Properties

Command for controlling module. #Connect# Toggle this item to connect to the Modbus slave/server; true: is connect, false: is disconnect

The Command Item item type has the following properties:

Name	Description	ID	Flags
Description	Toggle this item to connect to the Modbus server; true: is connect, false: is disconnect.
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

The item #Connected# telling if module is connected to the Modbus slave/server; true: is connected, false: is disconnected.

The item #Response_Ok# telling if module is receiving valid response from the Modbus slave/server; true: is ok, false: no or invalid response.

The State Item item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

Apis ModbusSlave

This module acts as an Modbus slave.

Provider: Unspecified

The ModbusSlave module has the following item types

More information

Characteristics of the Apis Modbus Slave module:

Implements Modbus Slave
Supports Read and Write.
Supports, Modbus TCP and Modbus RTU.
Supports functioon codes:
- 1 Read Coil status
- 2 Read Input status
- 3 Read Holding registers
- 4 Read Input registers
- 5 Force single Coil
- 6 Preset single Register
- 15 Force multiple Coils
- 16 Preset multiple Registers

Further, as an integrated module in the Apis Hive, the following optional features are available:

High performance data logging to the Apis Honeystore historian, with OPC Historical Data Access server interface

Item Types

Properties

Single bit Read-Only Starting address 0x10001 to 0x19999 when address mapping is active or 0 to FFFF when addressmapping deactivated

The DiscretesInput item type has the following properties:

Name	Description	ID	Flags
Inverted	If this attribute is true, the incoming value is inverted before writing to the Modbus register.	10070	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly

Properties

Single bit Read-Write Starting address 0x00001 to 0x09999

The Coil item type has the following properties:

Name	Description	ID	Flags
Inverted	If this attribute is true, the incoming value is inverted before writing to the Modbus register.	10070	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly

Properties

16 bit word Read-Only Starting address 0x30001 to 0x39999

The InputRegister item type has the following properties:

Name	Description	ID	Flags
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rawvalue	The raw, untranslated value of the item.	10075	Persisted
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Valuetype	Item canonical datatype in Modbus register.	10045	Persisted, Enumerated

Properties

16 bit word Read-Write Starting address 0x40001 to 0x49999

The HoldingRegister item type has the following properties:

Name	Description	ID	Flags
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rawvalue	The raw, untranslated value of the item.	10075	Persisted
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
Slaveaddress	The slave address (Unit ID) of the Modbus slave (overrides the module property).	10030	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Valuetype	Item canonical datatype in Modbus register. This determines what kind of data this field holds. For example: string, integer, etc.	10045	Persisted, Enumerated

Commands And Events

The ModbusSlave module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Properties

The ModbusSlave module has the following properties:

Name	Description	ID	Flags
BaudRate	Baud rate for serial communication. Only valid when Comm. type is Serial	1040	Persisted, Enumerated
Byteorder	Byte transfer order	1038	Persisted, Enumerated
COM port	The COM port to use. Only valid when Comm. type is Serial	1060	Persisted, Enumerated
Comm. type	Communication method, Serial or TCP/IP.	1025	Persisted, Enumerated
DataBits	Number of bits in the bytes transmitted and received for serial communication.	1072	Persisted, Enumerated
Default Slaveaddress	The Slaveaddress (Unit ID) on Modbus slave, this property can be set individually on item level.	1035	Persisted
Endian	Modbus is a "big-endian" protocol: that is, the more significant byte of a 16-bit value is sent before the less significant byte. It seems obvious that 32-bit and 64-bit values should also be transferred using big-endian order. However, some manufacturers have chosen to treat 32-bit and 64-bit values as being composed of 16-bit words, and transfer the words in little-endian order. For example, the 32-bit value 0x12345678 would be transferred as 0x56 0x78 0x12 0x34. Select LittleEndian to use this mixed ordering.	1037	Persisted, Enumerated
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
Exception Code	Exception code to send for testing purpose, valid only when Send Exception property is greater that 0	16010
Handshaking	Handshaking option for serial transmission	1070	Persisted, Enumerated
IP address	Endpoint Ip address of Modbus server. Only valid when Comm. type is TCP/IP	1301	Persisted
Master command timeout	Time to wait for master command in (seconds) before giving up and reset connection	1302	Persisted
Message timeout	Time interval, the active message is reported (in seconds).	1090	Persisted
Parity	Parity scheme for the serial communication. Only valid when Comm. type is Serial	1050	Persisted, Enumerated
Port	The endpoint TCP/UDP port of Modbus server. Only valid when Comm. type is TCP/IP	1300	Persisted
Send Exception	This is used to simulate exception to master for test purposes. Set value to greater that 0, to enable exception response. 1 - exception on every response 2 - exception on every second response and so on.
StopBits	Number of stop bits to be used for serial communication.	1074	Persisted, Enumerated
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TracefileMaxSize	The max size of the trace file before the file is truncated in bytes. Default is 50 MB => 50 * 1024 * 1024	15000	Persisted, ExpertPage
TraceToFile	This is used to trace detail information about the incomming data over the link	15010	Persisted, File, ExpertPage
Writetimeout	Time to wait (milliseconds) before giving up an attempt to write to master	1080	Persisted

See also Module Properties

Set up an Modbus Slave

Follow the guide Add Module to Apis Hive, but this time select a module of type ApisModbusSlave from the Module type drop down list, name it "ModbusSlave" in this case.

After adding the module, select the new module named "ModbusSlave" from theSolution Explorer.

Basic setup, communication interface

The module supports both serial (RTU) and TCP/IP (Modbus TCP) interface, depending on your needs. In the Properties Editor, enter values for:

TCP/IP based server:
- Comm. type: TCP/IP
- IP address: The endpoint IP address of your ModbusSlave server.
- Port: The endpoint TCP port of your ModbusSlave server.
Serial communication based server :
- Comm. type receive : Serial
- Com port: Com port connected to the slave.
- BaudRate: Baud rate of your slave serial setup.
- DataBits: Data bits of your slave serial setup.
- FlowControl: Handshake of your slave serial setup.
- Parity: Parity of your slave serial setup.
- StopBits: Stop bits of your slave serial setup.

Further in the Properties Editor:
- Default Slave address : Note! this is the initial property when new items are created.
- Assure the byte order and endianness is according to your needs
Press "Apply" when done.

Add Items (registers)

Now follow the guide Add Items to a Module, but this time select the Modbus module and add items of one of the register types:

Coil
DiscretesInput
InputRegister
HoldingRegister

Example Holding register:

Expose data

To expose data, ModbusSlave Items must be connected to a source item . See Connecting Items

The Worker.Signal1 is now exposed to Modbus masters (clients) in Holding register 40002 as 8 byte float.

Trouble shooting

If no connection or data received:

Use 3 party terminal application like putty to check if server is sending telegrams.
Check firewall settings for the port.
Check network connection to server, (ping)

ApisMQTTClientBee

This module can be used to subscribe to messages on topics from a MQTT broker. The messages can be decoded and stored in Value Items. Currently we support simple Json formated messages. See Json messages for details. To configure this module, set up the needed property, MQTTAddress, MQTTPort, MQTTClient (any textstring), MQTTServicelevel, MQTTTransport (TcpServer or TcpServerTls if security is needed).

By using secure communication (TcpServerTls) a certificate from the server will be added under default certificatepatch (..instancename/pki/rejected/xxxx.crt) . This certificate should be checked and moved to the thrusted directory to allow secure communication with this broker.

When these parameters are ok then the status-item shall show value "Connected". Add a TopicItem by right-clicking the module on the left side. Configure the Topic by setting the correct topic to listen to. It is possible to listen to several topics. The value for topic-item will go up by one as it receives messages from the broker.

Then add ValueItem. Connect the Item to a topic by the property "TopicItem", and then select the correct textvalues for properties "Key", "TimeId", "QualityId", and "ValueId", (See JSONMessage). When these properties are correctly set up, the value-item will show quality "Good".

"Auto create items" property in TopicItem can also be turned on to automatically decode the message from the broker and create the value items instead of having to manually set up the value items.

Provider: Prediktor

Json messages

The ApisMQTTClientBee module has the following item types

Topic

Value Item

Status

ApisMQTTClientBee Item Types

Topics Covered:

Item type: Topic

Topic item class description

The Topic item type has the following attributes:

Name	Description	ID	Flags
Topic	The topics to read messages from	11000	Persisted
Auto create items	If selected then the client will auto create items received in messages	11113	Persisted

Item type: ValueItem

ValueItem item class description

The ValueItem item type has the following attributes:

Name	Description	ID	Flags
Topic item	The topic this item is getting the message from	11101	DynamicEnumeration,APISLocalItem,Persisted
Key	The key this item is getting values from	11103	Persisted
Time id	The id of timevalue in message	11110	Persisted
Quality id	The id of qualityvalue in message	11111	Persisted
Value id	The id of value in massage	11112	Persisted

Item type: Status

This item is used to expose internal status information

The Status item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality	3	ReadOnly
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	ReadOnly

Commands And Events

The MQTTClientBee module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified by user. The timer resolution is specified by the 'ExchangeRate' property.	Timer
HandleExternalItems_DataPush	Event fired when an external items update iteration has been handled. Ie. one per command 'HandleExternalItems', one or more per command 'HandleExternalItems_DataPush'.	Normal
DataChanged	VQTs are updated (only for VQT 2 messages).	Normal
OneMessageDecoded	A message (containing one or more VQTs) has been decoded.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
HandleExternalItems_DataPush	Command for updating external items from the item data pushed as input parameter to the command, ie. fired by ApisOpcUaBee event 'ServerDataChanged_DataPush'. When fired, the module will update any external items part of the data, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Properties

The MQTTClientBee module has the following properties:

Name	Description	ID	Flags
Client certificate	The filename of the clients certificate when broker expect a client certificate to accept connection.	1015	Persisted, File
Exchangerate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
External item report	A status-report for the External Item manager of this module	110	InfoPage
ExtItem full refresh	When true, the external items manager will force a full refresh initially on start/reset when reading items. I.e. items not yet initialized in their source, will also trigger an external item update. Default is true.	150	Persisted, ExpertPage
ExtItem pass-through quality	Specifies the quality of external item values that will pass through external item transfers. If external item qualities has worse quality the this mask, the external item transfer is blocked. Default is 'Any quality'.	400	Persisted, Enumerated, ExpertPage
Loglevel	Specifies the loglevel for diagnostic messages from this module.	500	Persisted, Enumerated
MQTT address	Address to MQTT broker	1002	Persisted
MQTT clean session	If selected then the client will not get history messages the broker has stored for this clientid since last disconnection.	1009	Persisted
MQTT clientid	A string that define/identify the clients session at the broker.	1004	Persisted
MQTT password	The clients password.	1006	Persisted, Password
MQTT port	MQTT broker port	1003	Persisted
MQTT service level	Quality of service	1008	Persisted, Enumerated
MQTT transport	Transmission protocole: TcpServer, use unencrypted communication. TcpServeTLS use encrypted communication.	1011	Persisted, Enumerated
MQTT user	The clients username.	1005	Persisted
MQTTVersion	Version to use when connecting to server	1010	Persisted, Enumerated

See also Module Properties

JSON messages

The messages that are published to the broker should be JSON type. There are three types of messages which can be decoded by APIS:

VQT messages : This type of message can be used to update or create value items.
Meta messages : This type of message can be used to update the attributes of an existing value item.
Event messages : This type of message can be used to write any events or alarms to any existing tag in APIS.
Historical messages : This type of message can be used to write historical data for a value item directly to honeystore.

VQT messages

Currently there are two versions of the MQTT message formats that are supported in APIS.

VQT Version 1

Version 1 for MQTT messages is a simple JSON object that contains the following keys:

Message type
Message version
Value
Quality
Timestamp

All the values defined in a VQT1 message will have the same timestamp. If timestamp is not defined, the values will be associated with the current time on the system.

VQT1 Example


	{

		"messagetype": "vqt", 
		"version": 1, 
		"t": "2022-09-22T06:06:28.891+00:00", 
		"Tag1": 43, 
		"Tag2": 58,
		"Tag3": 80,
		"q": 0

	}

User can define the text strings for the time,value and quality of an item. The text strings for Time id, Value id and Quality id in a message must match the Time id, Value id and Quality id for the value items in the property editor. Note: Timezone information needs to be provided in the timsestamps.

For the above example message, the properties for a value items in APIS should be set as follows:

Value item	Value id	Time id	Quality id
Tag 1	Tag1	t	q
Tag 2	Tag2	t	q
Tag 3	Tag3	t	q

Mandatory Fields in message:

messagetype
version
value id string

Quality Codes

The quality codes for the value items in VQT 1 messages are as follows:

Quality	Codes
Good	0
Bad	Anything other than 0

VQT Version 2

Version 2 for MQTT messages is a simple JSON object that contains the following keys:

Message type
Message version
Quality
Timestamp
Payload

Payload is the content of the message. It is an array/list of JSON objects for value items and has the following attributes:

k (Key)
v (Value id)
t (Time id)
q (Quality id)

All these attributes for value items shall be represented as key:value pairs in the payload.

Timestamp can be defined for the entire message or inside the payload object for every item separately.
With VQT2, it is also possible to have multiple timestamped values associated with a value item in a message i.e there can be multiple JSON objects for a single value item by including multiple timestamps inside the payload.
If timestamp is not defined, the values will be associated with the current time on the system.

VQT2 Example


	{
		"messagetype": "vqt",
		"version": 2,
		"payload": 
			[
				{
					"k": "Tag1",
					"v": 10,
					"t": "2022-09-22T06:06:32.913554+00:00",
					"q": 192
				},

				{
					"k": "Tag1",
					"v": 3,
					"t": "2022-09-23T05:56:36.930429+00:00",
					"q": 192
				},

				{
					"k": "Tag2",
					"v": 70,
					"q": 192
				},

				{
					"k": "Tag3",
					"v": 98,
				}
			]
	}

The text strings for value id, time id and quality id are fixed in this version to "v", "q" and "t" respectively and must be defined accordingly in the message.

For the above example message, the properties for a value items in APIS should be set as follows:

Value item	Key
Tag 1	Tag1
Tag 2	Tag2
Tag 3	Tag3

Mandatory Fields in message:

messagetype
version
payload
k (key)
v (value)

Quality Codes

The quality codes for the value items in VQT 2 messages are as follows:

Quality	Codes
Good	192
Local override	216
Bad	0
Config error	4
Not connected	8
Device failure	12
Sensor failure	16
Last known	20
Comm failure	24
Out of service	28
Waiting for initial data	32
Uncertain	64
Last usable	68
Sensor cal	80
EGU exceeded	84
Sub normal	88

Meta messages

Meta messages can be used to write or edit the attributes/properties of MQTT value items existing in APIS environment.

A meta message is a JSON object that contains the following keys:

Message type
Payload

Payload is the content of the message. It is an array of JSON objects for value items containing the properties which need to be written/edited as the keys in its key:value pairs.

While trying to edit any attribute of an item, make sure that it's writable and that the key of the value item is provided. Index or id should be taken as a value for properties that have a dropdown menu or list to select from.

Meta Example


	{
		"messagetype" : "meta",
		"version" : 1,
		"payload": 
			[
				{
                    			"k" : "Tag1",
                    			"eu": 105,
                    			"description": "Description for tag 1",

				},

				{
                    			"k": "Tag2",
                    			"Offset": 100,

				},

				{
                    			"k": "Tag3",
                    			"AlmPrimaryArea": "AlarmArea1",
                    			"AlmLL": 0,
                    			"AlmL": 100,
                    			"AlmH": 200,
                    			"AlmHH": 350,
                    			"AlmHelp": "Help for alarm",
                    			"Logger": True,

				},

			]
	}

Mandatory Fields in message:

Message type
Payload
k (key)

Event messages

Event messages can be used to write events or alarms to a tag/variable/item in the APIS environment.

An event message is a JSON object that contains the following keys:

Message type
Payload

Payload is the content of the message. It is an array of JSON objects for events which need to be written to the items and can have the following attributes per event:

source
type
timestamp
severity
state
current value

Source is the location of the item (that you want to write an event to) inside the apis event server.

States of Alarms/Events:

Possible states of alarms can be:

None
Enabled
Active
AckRequired
Acked
Confirmed
Suppressed
Shelved
Substates

Event Example

			{		
				'messagetype': 'event', 
				'version': 1,
                                'payload':
                                    [
                                        {
                                            'type': 'LevelAlarm',
                                            'source': 'ApisHive/Areas/TestArea/TestWorker.Variable1',
                                            'time': '2022-09-22T11:52:02.438+00:00',
                                            'severity': 780,
                                            'state': 'Enabled,Acked',
                                            'currentvalue': 300,
                                        },
                                        {
                                            'type': 'OffNormalAlarm',
                                            'source': 'ApisHive/Areas/TestArea/TestWorker.Variable2',
                                            'time': '2022-09-22T11:52:02.438+00:00',
                                            'activetime': '2022-09-22T11:50:00.000+00:00',
                                            'severity': 780,
                                            'state': 'Enabled,Active,AckRequired',
                                            'currentvalue': 0,
                                            'message': 'Alarm on'
                                        },
                                        {
                                            'type': 'WatchdogAlarm',
                                            'time': '2022-09-22T11:52:02.438+00:00',
                                            'activetime': '2022-09-22T11:50:00.000+00:00',
                                            'source': 'ApisHive/Areas/TestArea/TestWorker.Variable3',
                                            'severity': 780,
                                            'state': 'Enabled,Active,Suppressed',
                                            'currentvalue': 150,
                                            'message': 'Value frozen'
                                        },
                                        {
                                            'type': 'WatchdogAlarm',
                                            'time': '2022-09-22T11:52:02.438+00:00',
                                            'activetime': '2022-09-22T11:50:00.000+00:00',
                                            'source': 'ApisHive/Areas/TestArea/TestWorker.Variable4',
                                            'severity': 835,
                                            'state': 'Enabled,Confirmed',
                                            'currentvalue': 100,
                                            'message': 'Value frozen for the last 10 seconds'
                                        },
                                        {
                                            'type': 'WatchdogAlarm',
                                            'time': '2022-09-22T11:52:02.438+00:00',
                                            'source': 'ApisHive/Areas/TestArea/TestWorker.Variable5',
                                            'severity': 780,
                                            'state': 'Enabled,Active,Shelved',
                                            'currentvalue': 100,
                                            'activetime': '2022-09-22T11:50:00.000+00:00',
                                            'message': 'Bad quality'
                                        },
                                    ]
                     }

Mandatory Fields in message:

message type
payload
type
source
time
severity
state
currentvalue

Historical messages

Historical messages can be used to add data to the honeystore for value items. This type of message adds data directly to the database that's responsible for logging the value items.

Historical message type is a JSON object that contains the following keys:

Message type
Message version
Payload

The payload is an array of JSON objects and can contain historical data for one or multiple value items with each JSON object inside the array dedicated to a single value item.

The payload array contains JSON objects with the following elements/keys:

k
v
overwrite

where,
'k' defines the tag/value item for which the history needs to be written,
'v' is an array of VQTs containing the actual historical values along with their timestamps and qualities defined,
'overwrite' is a True/False value that defines whether the history needs to be overwritten or not.

Note: The VQTs need to be ordered in the 'oldest to newest' timestamp order inside the 'v' array

Historical message Example


{
    "messagetype":"historical",
    "version":1,
    "payload":
    [
        {
            "k":"tag1",
            "v":
            [
                {
                    "v":25,
                    "q":192,
                    "t":"2022-09-25T20:00:00.000+00:00",                    
                },
                {
                    "v":23,
                    "q":192,
                    "t":"2022-09-25T21:00:00.000+00:00"
                }
            ],
            "overwrite":true
        },

        {
            "k":"tag2",
            "v":
            [
                {
                    "v":40,
                    "q":192,
                    "t":"2022-09-25T10:02:00.000+00:00",                    
                },
                {
                    "v":34,
                    "q":192,
                    "t":"2022-09-25T12:03:00.000+00:00"
                }
            ],
            "overwrite":true
        }
    ]
}

Mandatory Fields in message:

messagetype
payload
v (array field)
k (key)
v (value)
t (timestamp)

Apis OPC

The Apis OPC Client module connects the Apis system to an OPC Data Access Server. An OPC Data Access Server is a software driver that enables a standard way of accessing real-time data from a system. For further information about OPC technology, see: http://www.opcfoundation.org/.

Provider: Prediktor

The OPC module has the following item types:

More information

Characteristics of the ApisOPCBee Client module:

Implements an OPC Data Access 1.01a and 2.05a client.
Supports both polling and subscriptions when reading data.
Supports both asynchronous and synchronous writing.
Automatically re-connects if connection to the OPC Server breaks down (such as temporarily loss of network connections etc.)

Further, as an integrated module in the Apis Hive, the following optional features are available:

High performance data logging to the Apis Honeystore historian, with OPC Historical Data Access server interface
Enhances OPC DA 1.01a servers to OPC DA 2.05a servers
Cross connection between OPC servers, or cross connection between an OPC server and another Apis Access module
Conventional and Advanced Control with Apis Soft PLC or Apis Advanced Soft Controller
Access to OPC data, through Apis Process Explorer WEB application, as well as other Apis report generation tools.

Properties

The OPC module has the following properties:

Standard properties

Name	Description	ID	Flags
Computer	The computer hosting the OPC server.	1000	Persisted, Computer
DataSource	This property tells the OPC server how to retrieve its data. 'Cache' means that the OPC server should use any internal cached data, 'Device' means that the OPC server should refresh the data from any underlying device (ie. PLC)	1019	Persisted, Enumerated
Deadband	Percent deadband for item updates, when ReadMode is subscribe.	1022	Persisted
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ReadMode	How items are beeing read from the server.	1020	Persisted, Enumerated
Server	The ProgID of the OPC server. Can also use a class ID directly, eg. if the class id is known and server browsing is unavailable.	1001	Persisted, Enumerated, ProgID
Updaterate	Updaterate in milli-seconds for the items, when ReadMode is Subscribe x.0. When ReadMode is Asynch I/O, the intervall between each issued Refresh call. When ReadMode is Synch I/O, the intervall betweean each Read call.	1021	Persisted
WriteMode	How items are being written to the server.	1030	Persisted, Enumerated

Advanced properties

Name	Description	ID	Flags
CmnItemIDPrefix	Common source ItemId prefix. This string will prefix each item's 'ItemID' when communicating with the OPC server. Items in this module will have names without this prefix in the Apis namespace.	1012	Persisted, ExpertPage
DelayServerConnect	Delay server connect on startup, connection will be performed when all modules are fully initialized.	1045	Persisted, ExpertPage
ForceOutOfProc	Prevent the opc server from beeing loadad into the memory space of Apis.	1010	Persisted, ExpertPage
ForceRefreshOnConnect	By enabling this with subscription (1.0 or 2.0), the client will request a distinct refresh of all items from the server after a connect. Note that the OPC server should refresh all items afer an Advise, this is a feature for working with OPC servers that do not meet the specifiaction regarding this.	1007	Persisted, ExpertPage
GroupActive	Active flag for the group. Automatic item activation will cause this flag to change dynamically when needed.	1033	ExpertPage
ItemActivation	Item activation strategy.	1034	Persisted, Enumerated, ExpertPage
ItemActiveTimeout	The interval in seconds to wait before an item is deactivated when there has been no reads from the item. (Only for 'ItemActivation' = 'automatic with timeout')	1036	Persisted, ExpertPage
ItemPropSync	When to synchronize OPC DA properties with Apis item attributes	1038	Persisted, Enumerated, ExpertPage
NumberOfRedundantServers	The maximum number of redundant servers for this instance, valid range is 0-5.	2000	Persisted, ExpertPage
ReconnectSrvShutdown	Reconnect after an intended OPC server shutdown. This might cause problems when administering the OPC server.	1008	Persisted, ExpertPage
ReconnectTime	The time to wait before attempting to reconnect the server after an RPC failure, or time interval for watchdog evaluation if watchdog is configured.	1006	Persisted, Enumerated, ExpertPage
RedundantCmnItemIDPrefix_x	Common source ItemId prefix for the redundant server 'x'. This string will prefix each item's 'ItemID' when communicating with the OPC server. Items in this module will have names without this prefix in the Apis namespace.	20x2	Persisted, ExpertPage
RedundantComputer_x	The computer hosting the redundant OPC server 'x', if configured.	20x0	Persisted, Computer, ExpertPage
RedundantServer_x	The ProgID of the redundant OPC server 'x', if configured.	20x1	Persisted, Enumerated, ProgID, ExpertPage
SerializeCallsToOPCServer	Set this property to <true> if the OPC Server is not handling simultaneous calls properly.	1042	Persisted, ExpertPage
ServerWatchdog	A strategy for server communication monitoring. This can be useful when dealing with erronous servers that stop to operate correctly. Values are: none=0 Restart if update interval > ReconnectTime Restart if watchdog item(s) update interval > ReconnectTime Restart if watchdog item(s) update or bad quality interval > ReconnectTime	1039	Persisted, Enumerated, ExpertPage
ServerWatchdogItems	Set to one or more local items, when using a ServerWatchdog utilizing watchdog item(s)	1043	Persisted, ApisLocalItem, ExpertPage
SrvConfigFile	The configuration file of the server. This file is used with the optional IPersistFile implementation of the OPC server.	1004	DSN, ExpertPage
SrvLCID	Locale ID of values coming from the server. You might need to specify this property if the OPC server provides string values that is converted to another type in your client (e.g. DDE bridges)	1018	Persisted, ExpertPage
SuppressVendorQuality	When true, any vendor specific item quality will be suppressed, only the standard OPC Foundation bits of the quality flag, will be set for item qualities	1025	Persisted, ExpertPage
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TraceOPCServer	Report specific OPC calls, return from those calls, as well as callbacks to the log files for log view in Apis Management Studio.	1040	Persisted, Enumerated, ExpertPage
TraceToFile¹	If set, all OPC calls and callbacks will be traced to this file. Should only be used for short time periods and for verbose troubleshooting of communication.	1041	Persisted, File, ExpertPage
UseApisTime	Use Apis timestamps instead of the timestamps given by the OPC server.	1023	Persisted, ExpertPage

Information properties

Name	Description	ID	Flags
DebugInfo	Debug information for advanced troubleshooting	1058	ReadOnly, InfoPage
ExternalItem report	A status-report for the External Item manager of this module	110	InfoPage
RedundantSrvCLSID_x	The CLSID of the redundant OPC server 'x', if configured.	20x3	Persisted, ReadOnly, InfoPage
SrvActive	Currently active server, when using redundant severs, this tells which of the two that is currently set as active server (Primary / Redundant).	1046	ReadOnly, InfoPage
SrvBandWidth	The approximate percent of bandwith in use by the OPC server	1055	ReadOnly, InfoPage
SrvCapabilities	The capabilities of the OPC server.	1048	Persisted, ReadOnly, InfoPage
SrvCLSID	The CLSID of the OPC server.	1005	Persisted, ReadOnly, InfoPage
SrvCurrentTime	The current time (UTC) as known by the OPC server.	1051	ReadOnly, InfoPage
SrvGroupCount	The total number of groups (all public and private) being managed by the OPC server	1054	ReadOnly, InfoPage
SrvStartTime	The time (UTC) the OPC server was started.	1050	ReadOnly, InfoPage
SrvState	The current status of the OPC server	1053	ReadOnly, Enumerated, InfoPage
SrvVendorInfo	Vendor specific information about the OPC server	1057	Persisted, ReadOnly, InfoPage
SrvVersion	The version number of the OPC server (major-minor-build)	1056	Persisted, ReadOnly, InfoPage

Performance

Name	Description	ID	Flags
SrvAvgItemsPerCall	The average number of items in each update call.	1064	ReadOnly, PerformancePage
SrvLastPendWCTID	The last pending write complete transaction ID.	1092	ReadOnly, PerformancePage
SrvLastUpdateInterval	When ReadMode is Subscribe or Asynch I/O, the time in seconds between the last two updates. When ReadMode is Sync I/O, the time interval between the last successful Reads.	1061	ReadOnly, PerformancePage
SrvLastUpdateTID	The last update or read transaction ID that was received.	1072	ReadOnly, PerformancePage
SrvLastWCTID	The last received write complete transaction ID.	1094	ReadOnly, PerformancePage
SrvPercentUpdateInvalid	The percentage of all updated items that was invalid (e.g. unknown item handles).	1070	ReadOnly, PerformancePage
SrvPercentUpdateSuccess	The percentage of all updated items that have been updated with success.	1066	ReadOnly, PerformancePage
SrvPercentUpdateUnneccessary	The percentage of all updated items that was unneccessary (neither value nor quality had changed).	1068	ReadOnly, PerformancePage
SrvPercentWriteCmplFail	The percentage of all write complete items that have failed.	1088	ReadOnly, PerformancePage
SrvPercentWriteCmplInvalid	The percentage of all write complete items that was invalid (e.g. unknown item handles).	1090	ReadOnly, PerformancePage
SrvPercentWriteCmplSuccess	The percentage of all write complete items that have succeded.	1086	ReadOnly, PerformancePage
SrvUpdateCalls	The number of times the OPC server has called back to this client with updated item values.	1062	PerformancePage
SrvUpdateTime	The time the OPC server sent the last data value update to this client, as known by the server.	1052	ReadOnly, PerformancePage
SrvUpdateTimeClient	When ReadMode is Subscribe or Asynch I/O, the time when this client received the last update, as known by the client. When ReadMode is Synch I/O, the time of the last successful Read.	1060	ReadOnly, PerformancePage
SrvWriteCmplCalls	The number of times the OPC server has called back to this client with updated item values.	1082	PerformancePage
SrvWriteCmplTimeClient	The time when this client received the last write complete call, as known by the client.	1080	ReadOnly, PerformancePage

Commands And Events

The OPC module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
ServerConnected	The OPC server if connected.	Normal
ServerDataChange	The OPC server has sent a subscription based data change notification.	Normal
ServerFirstTimeDataChanged	The OPC server has sent a subscription based data change notification first time after reconnect.	Normal
ServerShutdown	The OPC server has sent a shutdown notification.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
ResetExternalItems	Resets the external item manager, by forcing a full refresh of all external items when the 'HandleExternalItems' is fired next time.	Synchronous
Reconnect	Reconnects to the OPC server.	Asynchronous
Reset	Resets the OPC items in the client by performing a synchronous read from server.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

Item Types

OPC Item

An item in an OPC server

The OPC Item item type has the following properties:

Standard

Name	Description	ID	Flags
SrcItemID	Item ID in source	5030	Persisted

Advanced

Name	Description	ID	Flags
ActiveInServer	True when this item is active in the OPC server.	10110	ReadOnly, ExpertPage
LocalOverrideToBad	If true, a good:local override item quality from the server will be remapped to a bad quality.	10130	Persisted, ExpertPage
ReqVartype	The type requested to be delivered for the value of this item from the server. Only change this one for special situations.	10100	Persisted, Enumerated, ExpertPage

Information

Name	Description	ID	Flags
Client handle	The client handle of the item, as registered with the OPC sever. When negative, the item has not been accepted by the OPC server.	10160	ReadOnly, InfoPage

Command Item

An item that represents a command to apply on this module.

The Command Item item type has the following properties:

Name	Description	ID	Flags
Command argument 1	This attribute may be used by an item to specify additional arguments.	10150	Persisted
Command type	This attribute allows you to select the type of command to use.	10140	Persisted, ReadOnly, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Trans OPC Item

An OPC item with automatic calculation of a linear transformation.

The Trans OPC Item item type has the following properties:

Name	Description	ID	Flags
ActiveInServer	True when this item is active in the OPC server.	10110	ReadOnly, ExpertPage
Client handle	The client handle of the item, as registered with the OPC sever. When negative, the item has not been accepted by the OPC server.	10160	ReadOnly, InfoPage
LocalOverrideToBad	If true, a "good:local" override item quality from the server will be remapped to a "bad" quality.	10130	Persisted, ExpertPage
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
ReqVartype	The type requested from the server for the value of this item. Only change this property in special circumstances.	10100	Persisted, Enumerated, ExpertPage
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

State Item

An item that represents a well defined state of this module.

The State Item item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Module State Items

An item which retrieves status information from the module

The Module state items item type has the following properties:

Name	Description	ID	Flags
Item type	The item type this item aggregates statistics on, when applicable. Use the number inside the parentheses in "FileAdd" configuration files.	19001	Persisted, ReadOnly, DynamicEnumeration
Module state	The kind of module state information represented by this item. This can be a number of items having a given quality, a total number of items, the time the newest/oldest item was updated. Use a number inside the parentheses in "FileAdd" configuration files.	19000	Persisted, ReadOnly, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Item Attribute Items

An item which exposes an attribute of another item in the module

The Item attribute items item type has the following properties:

Name	Description	ID	Flags
Attribute ID	The ID of the attribute this item exposes from an item.	19002	Persisted, ReadOnly, DynamicEnumeration
ParentItem	The parent item name of this item.	5502	Persisted, ReadOnly, ApisLocalItem
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

Apis OpcUa

This module connects to an OPC server, and provides access to OPC items.

Provider: Prediktor

The OpcUa module has the following item types

OPC UA catch-up

OPC UA Catch-up

Properties

The OpcUa module has the following properties:

Name	Description	ID	Flags
BrowseTypeFilter	The type definition base class for nodes returned from browsing.	1025	Persisted, Enumerated, ExpertPage
BatchSize	The batch size for the number of operations per rpc message towards the ua server. Default is 10000.	1054	Persisted, ExpertPage
CatchupChunkSize	How many values to read per node during catch-up read operations. Maps to 'numValuesPerNode' parameter of 'ReadRawModifiedDetails'. Default is 1000.	1261	Persisted, ExpertPage
CatchupMode	Enables data catch-up functionality of the communication. NoCatchup: No data catch-up, just pure real-time communication. SerializedFull: Historical data is streamed through Hive sample-by-sample, until we have caught up real-time. Note that this requires the UA server to implement the OPC UA HA profile! SerializedFull_PauseAfterInitial: Same as 'SerializedFull', but with one stop in playback sequence after first StepNext, use CommandItem #ContinueCatchup# to continue playback sequence. SerializedPartial: Only data missing locally, per item, is read from remote server and streamed through Hive, sample-by-sample, until we have caught up real-time. SerializedPartial_PauseAfterInitial: Same as 'SerializedPartial', but with one stop in playback sequence after first StepNext, use CommandItem #ContinueCatchup# to continue playback sequence. Direct: Data periods missing locally are read from the UA server and written directly to any configured Honeystore timeseries database for the item(s). Note that to fully benefit from using catch-up, the UA server is required to implement the OPC UA HA profile! More details on how to use catch-up can be found here.	1250	Persisted, Enumerated, ExpertPage
CatchupChunkCount	How many chunks of data to cache during catch-up history read operations. Must be between 0-255. Default is 5	1260	Persisted, ExpertPage
CatchupPeriod	The maximum period of time to look back for historical data, when initiating a catch-up operation. Select a preset, or enter a custom value in seconds.	1262	Persisted, Enumerated, ExpertPage
EnableModelChangeEvent	By enabling this property, any model change events issued from the OPC server as a result of items being added, will automaticlly add items to this module.	1230	Persisted, ExpertPage
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ItemNameFormat	How to generate item names on items from the UA NodeID, DisplayName and/or BrowseName. Set of predefined choices, or a custom string, containig following specifiers: {dn} = DisplayName {bn} = BrowseName {ni} = NodeId Example: {bn}mystring{dn}	1020	Persisted, Enumerated, ExpertPage
ItemNameSeparator	A character or string used when concatenating item names. Applies only when ItemNameFormat is ConcatenateDisplayName or ConcatenateBrowseName.	1022	Persisted, ExpertPage
LifetimeCount	Requested lifetime count. The lifetime count shall be a minimum of three times the keep keep-alive count. When the publishing timer has expired this number of times without a Publish request being available to send a NotificationMessage, then the Subscription shall be deleted by the Server.	1052	Persisted, ExpertPage
MaxKeepAliveCount	Requested maximum keep-alive count. When the publishing timer has expired this number of times without requiring any NotificationMessage to be sent, the Subscription sends a keep-alive Message to the Client. The negotiated value for this parameter is returned in the response. If the requested value is 0, the server shall revise with the smallest supported keep-alive count.	1051	Persisted, ExpertPage
NotificationsPerPublish	The maximum number of notifications that the Client wishes to receive in a single Publish response. A value of zero indicates that there is no limit. The number of notifications per Publish is the sum of monitoredItems in the DataChangeNotification and events in the EventNotificationList.	1053	Persisted, ExpertPage
PublishingInterval	This interval defines the cyclic rate that the Subscription is being requested to return Notifications to the Client. This interval is expressed in milliseconds. The negotiated value for this parameter returned in the response is used as the default sampling interval for MonitoredItems assigned to this Subscription. If the requested value is 0 or negative, the server shall revise with the fastest supported publishing interval.	1050	Persisted
QualityOverriding	This property controls whether the module itself is allowed to set item qualities, in some situations. If 'when connection lost', qualities will be set to 'Bad: not connected', when connection to ua server gets lost. If 'when write fails', qualities will be set to whatever the write class returned when a failed write happens. If set to 'never', no qualities other than what is received from the UA server will be set on item qualities. Note: this property only applies when CatchupMode = NoCatchup.	1340	Persisted, Enumerated, ExpertPage
Server	The OpcUa connection or OpcUa cluster item to use for the server connection.	1000	Persisted, Enumerated
ServerWatchdog	A strategy for server communication monitoring. This can be useful when dealing with erronous servers that stop to operate correctly.	1360	Persisted, Enumerated, ExpertPage
ServerWatchdogItems	Set to one or more local items, when using ServerWatchdog = 'Restart if watchdog item(s) update interval > ReconnectTime'	1365	Persisted, ApisLocalItem, ExpertPage
SrvLCID	Locale ID of values coming from the server. You might need to specify this property if the OPC server provides string values that is converted to another type in your client (e.g. DDE bridges)	1218	Persisted, ExpertPage
StandardPropSync	When to synchronize selected OpcUA Standard Properties from server nodes to local apis item attributes (EngineeringUnit, EURange, InstrumentRange). First time adding item Each session After replication	1310	Persisted, EnumeratedFlags, ExpertPage
SubscriptionActive	Active flag for the subscription.	1300	Persisted, ExpertPage
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TraceLogLevel	The level of trace messages to log.	1420	Persisted, Enumerated, ExpertPage
TraceOPCServer	Report specific OPC calls, return from those calls, as well as callbacks to the log files for log view in Apis Management Studio.	1400	Persisted, Enumerated, ExpertPage
TraceToFile¹	If set, all OPC calls and callbacks will be traced to this file. Should only be used for short time periods and for verbose troubleshooting of communication.	1410	Persisted, File, ExpertPage
TraceToFileVerbosity	Specifies how much information that are written to the trace-file, if property 'TraceToFile' is set to a valid file. (Property ID: 1411)	1411	Persisted, File, Enumerated, ExpertPage
UseApisTime	Use Apis timestamps instead of the timestamps given by the OPC server.	1223	Persisted, ExpertPage
WriteMode	How items are being written to the server. Synchronous: items are written through a blocking call; Asynchronous; items are written through a non-blocking call. When the module is data, it might be desirable to do so without blocking any executing thread/operation, like any other eventbroker commands configured on the same eventbroker event, i.e. like External items transfer.	1201	Persisted, Enumerated
WriteTimeStamp	Select the timestamp to include, if any, when writing a data value to the OPCUA server.	1500	Persisted, ExpertPage

Informational properties:

Name	Description	ID	Flags
DebugInfo	Debug information for advanced troubleshooting	2200	ReadOnly, InfoPage
ExternalItem report	A status-report for the External Item manager of this module	110	InfoPage
RevisedKeepAliveCount	The actual maximum keep-alive count. The Server should attempt to honor the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.	2111	InfoPage
RevisedLifetimeCount	The lifetime of the Subscription shall be a minimum of three times the keep-alive interval negotiated by the Server.	2112	InfoPage
RevisedPublishingInterval	The actual publishing interval that the Server will use, expressed in milliseconds. The Server should attempt to honor the Client request for this parameter, but may negotiate this value up or down to meet its own constraints.	2110	InfoPage
ServerNamespaceArray	The NamespaceArray of the UA server.	2060	Persisted, ReadOnly, InfoPage
SrvActive	Currently active server, when using redundant severs, this tells which of the two that is currently set as active server (Primary / Redundant).	2050	ReadOnly, InfoPage
SrvCurrentTime	The current time (UTC) as known by the OPC server.	2121	ReadOnly, InfoPage
SrvStartTime	Time (UTC) the server was started. This is constant for the server instance and is not reset when the server changes state. Each instance of a server should keep the time when the process started.	2120	ReadOnly, InfoPage
SrvState	The current status of the OPC server	2105	ReadOnly, InfoPage
UaLibSessionStatus	The last session status change, as reported by the UA client library.	2100	ReadOnly, InfoPage
UaLibSubscriptionStatus	The last subscrption status change, as reported by the UA client library.	2101	ReadOnly, InfoPage

Performance properties:

Name	Description	ID	Flags
SrvLastWriteCallTime	The last time we have written (one or more items) to the OPC server.	3080	ReadOnly, PerformancePage
SrvAvgItemsPerCall	The average number of items in each update call.	3064	ReadOnly, PerformancePage
SrvLastUpdateInterval	The time in seconds between the last two updates.	3061	ReadOnly, PerformancePage
SrvPercentUpdateInvalid	The percentage of all updated items that was invalid (e.g. unknown item handles).	3070	ReadOnly, PerformancePage
SrvPercentUpdateSuccess	The percentage of all updated items that have been updated with success.	3066	ReadOnly, PerformancePage
SrvPercentUpdateUnneccessary	The percentage of all updated items that was unnecessary (neither value nor quality had changed).	3068	ReadOnly, PerformancePage
SrvPercentWriteCmplFail	The percentage of all write complete items that have failed.	3088	ReadOnly, PerformancePage
SrvPercentWriteCmplInvalid	The percentage of all write complete items that was invalid (e.g. unknown item handles).	3090	ReadOnly, PerformancePage
SrvPercentWriteCmplSuccess	The percentage of all write complete items that have succeeded.	3086	ReadOnly, PerformancePage
SrvUpdateCalls	The number of times the OPC server has called back to this client with updated item values.	3062	PerformancePage
SrvUpdateTimeClient	The time when this client received the last update, as known by the client.	3060	ReadOnly, PerformancePage
SrvWriteCalls	The number of times the OPC server has called back to this client with updated item values.	3082	PerformancePage

Connection properties:

The following properties have been deprecated by the introduction of the Server property.
When the Server property is set to "<Custom configuration>", the properties in this list behave as in prior versions of Apis Hive. When the Server property is set to an OpcUa connection or OpcUa cluster, the properties in this list gets the additional flags ReadOnly and Hidden (except the ServerEndpoint property, which becomes ReadOnly but not Hidden; this property can then be used to check which server endpoint is active when connecting to an OpcUa cluster).

Name	Description	ID	Flags
Authentication	The authentication method used when connecting to server. Can be: Anonymous Username/password If set to 'Username/password, the properties 'Username' and 'Password' must also be specified.	1061	Persisted, Enumerated (ReadOnly, Hidden)
CertificatePath	Use this property to specify which certificate the OpcUaBee should use when connecting to the server. When property 'PkiType' is 'Win32', this property specifies the subject-name of a certificate in the Windows Certificate Store. Typically this will be the name of the ApisHive instance. Example using Win32: "ApisHive" When property 'PkiType' is 'OpenSSL', this property specifies the name of a certificate file in the '<certificatestore>\trusted' folder. Example using OpenSSL: "ApisHive.der"	1042	Persisted, File (ReadOnly, Hidden)
CertificateStorePath	This property specifies where the OpcUaBee should look for certificates. Default value is empty. If PkiType is "Win32", this property specifies a folder within the Windows Certificate Store. If the property is empty, the OpcUaBee will use the value "UA Applications". If PkiType is "OpenSSL", this property specifies a file system path relative to the ApisHive instance configuration folder. If the property is empty, the OpcUaBee will use the value "pki", which resolves to the folder "<APISDir>\Config<InstanceName>\pki".	1041	Persisted, Folder (ReadOnly, Hidden)
MessageSecurity	This property sets the required security level for OpcUa messages. When setting this property, you may also have to set others. If set to: Unsecure: You must set 'SecurityPolicy' to 'None'. 'Signed' or 'Signed and encrypted:' You must sprecify a 'SecurityPolicy' other than 'None'	1045	Persisted, Enumerated (ReadOnly, Hidden)
NetworkTimeout	This property specifies the timeout period for RPC messages sent to the OpcUa server, measured in milliseconds. Default is 5000.	1111	Persisted (ReadOnly, Hidden)
PkiType	This property selects which certificate handling implementation to use (PKI=Public Key Infrastructure). The options are: OpenSSL: using the filesystem to access certificates Win32: using the Windows Certificate Store.	1040	Persisted, Enumerated (ReadOnly, Hidden)
Password	Password used to authenticate with server. Only applies when the property 'Authentication' is 'Username/password'.	1003	Persisted (ReadOnly, Hidden)
PrivateKeyPath	This propery is used to select the private key for the active certificate. When PkiType is 'OpenSSL', the property specifies the name of a key-file in the "<certificatestore>\private" folder, encoded in PEM format. Typically, if CertificatePath is "ApisHive.der", PrivateKeyPath would be "ApisHive.pem". When PkiType is 'Win32', this property is ignored (the Windows Certificate Store handles the link between certificates and their private key).	1043	Persisted, File (ReadOnly, Hidden)
ReconnectTime	The time to wait before attempting to reconnect the server after an RPC failure, or time interval for watchdog evaluation if watchdog is configured.	1355	Persisted, Enumerated, ExpertPage
RedundantCertificatePath	This property is identical to the CertificatePath property, but for the redundant server.	1542	Persisted, File, ExpertPage
RedundantCertificateStorePath	This property is identical to the CertificateStorePath property, but for the redundant server.	1541	Persisted, Folder, ExpertPage
RedundantMessageSecurity	This property is identical to the MessageSecurity property, but for the redundant server.	1545	Persisted, Enumerated, ExpertPage (ReadOnly, Hidden)
RedundantPkiType	This property is identical to the PkiType property, but for the redundant server.	1540	Persisted, Enumerated, ExpertPage (ReadOnly, Hidden)
RedundantPrivateKeyPath	This property is identical to the PrivateKeyPath property, but for the redundant server.	1543	Persisted, File (ReadOnly, Hidden)
RedundantSecurityPolicy	The OpcUa securitypolicy URI do use when connecting to the redundant server. Default value is "http://opcfoundation.org/UA/SecurityPolicy#None"	1546	Persisted, Enumerated (ReadOnly, Hidden)
RedundantServerCertificatePath	Path/name of redundant server certificate. This property must refer to a valid certificate when RedundantMessageSecurity is either "Signed" or "Signed and encrypted".	1544	Persisted, File, ExpertPage (ReadOnly, Hidden)
RedundantServerEndpoint	The Endpoint URL of any redundant OPC UA server. The use of a redundant server when the primary server is unavailable is triggered by setting this property.	1501	Persisted, ExpertPage (ReadOnly, Hidden)
SecurityPolicy	The OpcUa securitypolicy URI do use when connecting to the server. Default value is "http://opcfoundation.org/UA/SecurityPolicy#None"	1046	Persisted, Enumerated (ReadOnly, Hidden)
ServerCertificatePath	Path/name of server certificate. This property must refer to a valid certificate when MessageSecurity is either "Signed" or "Signed and encrypted". If MessageSecurity is 'None', this property is ignored. When property 'PkiType' is 'Win32', this property specifies the subject-name of a certificate in the Windows Certificate Store. Example using Win32: "ApisHiveUaServerInstance" When property 'PkiType' is 'OpenSSL', this property specifies the name of a certificate file in the '<certificatestore>\trusted' folder. Example using OpenSSL: "ApisHiveUaServerInstance.der"	1044	Persisted, File (ReadOnly, Hidden)
EndpointUrl	The endpoint URL used to connect with an OPC UA server. Syntax: opc.tcp://{HostName or IP address}:{port number} Example: opc.tcp://localhost:4850	1001	Persisted (ReadOnly)
ReverseConnection	Specifies if the client or the server should initiate the connection	1005	Persisted (ReadOnly)
SessionTimeout	Requested maximum number of milliseconds that a Session should remain open without activity. If the Client fails to issue a Service request within this interval, then the Server shall automatically terminate the Client Session. Default is 60000 milliseconds.	1112	Persisted (ReadOnly, Hidden)
TokenTimeout	The timeout in seconds, of the security token if using 'MessageSecurity' other than 'None'. Default is 60000 seconds.	1113	Persisted (ReadOnly, Hidden)
Username	Username used to authenticate with server. Only applies when the property 'Authentication' is 'Username/password'.	1002	Persisted (ReadOnly, Hidden)

See also Module Properties

Commands And Events

The OpcUa module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
ExternalItemsHandled_DataPush	This event is fired after it has executed a HandleExternalItems_DataPush command. The data push package part of this ExternalItemsHandled_DataPush event, are all the resulting VQTs (Function items, ordinary external item transfer, etc.) from the HandleExternalItems_DataPush command. On this ExternalItemsHandled_DataPush event, one can hook any _DataPush command(s) (Log; Scan; UaServerUpdateMonitorItems; HandleExternalItems), to chain a path of execution with data transferred alongside. APIS data transfer mechanism; Data Push	Timer
ServerConnected	The OPC server if connected.	Normal
ServerDataChanged	The OPC server has sent a subscription based data change notification.	Normal
ServerDataChanged_DataPush	The OPC server has sent a subscription based data change notification. This event is fired when the UA client receives data from the UA server, and the items and samples in the data push package are the ones that is received from the server. See also: APIS data transfer mechanism; Data Push	Normal
ServerFirstTimeDataChanged	The OPC server has sent a subscription based data change notification first time after reconnect.	Normal
Catchup-StepNextDone	Event telling that one data set from catch-up-manager has been applied to items of the module!	Normal
Catchup-Done	Event telling that the catch-up opertation has completed and that module is running in normal real-time mode.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
HandleExternalItems_DataPush	This command ensure that all samples for all items and samples in the data push package are applied/used in the external item manager, including in services as Data Validation, Ext Items Transfer Control, etc. See also: APIS data transfer mechanism; Data Push	Synchronous
ResetExternalItems	Resets the external item manager, by forcing a full refresh of all external items when the 'HandleExternalItems' is fired next time.	Synchronous
Reconnect	Reconnects to the OPC server.	Asynchronous
Reset	Resets the OPC items in the client by performing a synchronous read from server.	Synchronous
SyncStdProperties	Start synchronization of standard OPCUA properties for all items	Asynchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous
Catchup-StepNext	Step the catch-up data 'playback' one step ahead, updating the item values according to next step. The event Catchup-StepNextDone, is fired when all items have their updated values set, to hook other commands onto.	Synchronous

See also Commands And Events

Item Types

OPC Item

An item in an OPC UA Server

The OPC Item item type has the following properties:

Name	Description	ID	Flags
DeadbandType	The monitoring deadband. Default = None.	10550	Persisted, Enumerated
DeadbandValue	The value of the monitoring deadband. Ignored when 'Deadband' is 'None'.	10560	Persisted
DiscardOldest	A boolean parameter that specifies the discard policy when the queue is full and a new notification is to be queued. It has the following values: True - the oldest (first) notification in the queue is discarded. The new notification is added to the end of the queue; False - the last notification added to the queue gets replaced by the new notification. Default = true.	10530	Persisted
ExcludeFromCatchup	If true, this item is excluded from catchup, ie. no historical data is read from the server, for this item, during the catchup process.	10600	Persisted
MonitoringMode	The monitoring mode parameter is used to enable and disable the sampling of a MonitoredItem, and also to provide for independently enabling and disabling the reporting of notifications. This capability allows a MonitoredItem to be configured to sample, sample and report, or neither. Default = Reporting.	10500	Persisted, Enumerated
MonitorState	The actual state of the monitored item.	11030	ReadOnly
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
QueueSize	The requested size of the "MonitoredItem" queue. Default = 1.	10520	Persisted
RevisedQueueSize	The actual queue size that the Server will use.	11020	ReadOnly
RevisedSamplingInterval	The actual sampling interval that the Server will use. This value is based on a number of factors, including capabilities of the underlying system. The Server shall always return a revisedSamplingInterval that is equal or higher than the requested samplingInterval. If the requested samplingInterval is higher than the maximum sampling interval supported by the Server, the maximum sampling interval is returned.	11010	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SamplingInterval	The interval that defines the fastest rate at which the MonitoredItem(s) should be accessed and evaluated. This interval is defined in milliseconds. The value 0 indicates that the Server should use the fastest practical rate. The value -1 indicates that the default sampling interval defined by the publishing interval of the subscription is requested. A different sampling interval is used if the publishing interval is not a supported sampling interval. Any negative number is interpreted as -1. Default = -1.	10510	Persisted
SrcUaNodeId	UA Node ID in source.	5031	Persisted
SrcUaNodeId-HA	UA Node ID in source, used for reading history, if the UA server has different nodeids for reading real-time data versus historical data. If empty, history reads defaults to using the 'SrcUaNodeId'.	10505	Persistd
Time	The date and time when this item was last updated.	4	ReadOnly
Trigger	This property specifies the conditions under which a data change notification should be reported: Status: Report a notification ONLY if the StatusCode associated with the value changes; StatusOrValue: Report a notification if either the StatusCode or the value change. The Deadband filter can be used in addition for filtering value changes; StatusOrValueOrTimestamp: Report a notification if either StatusCode, value, or the SourceTimestamp changes. If a Deadband filter is specified, this trigger has the same behaviour as StatusOrValue. Default = StatusOrValueOrTimestamp.	10540	Persisted, Enumerated
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Write as server datatype	If false, using current value datatype when writing this item to the server. If true, convert to datatype initially reported by server for this item, when writing to the server.	10610	Persisted, Expert

Command Item

An item that represents a command to apply on this module.

The Command Item item type has the following properties:

Name	Description	ID	Flags
Command argument 1	This attribute may be used by an item to specify additional arguments.	10150	Persisted
Command type	This attribute allows you to select the type of command to use.	10140	Persisted, ReadOnly, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Trans OPC Item

An item in an OPC UA Server, with automatic calculation of a linear transformation.

The Trans OPC Item item type has the following properties:

Name	Description	ID	Flags
DeadbandType	The monitoring deadband. Default = None.	10550	Persisted, Enumerated
DeadbandValue	The value of the monitoring deadband. Ignored when 'Deadband' is 'None'.	10560	Persisted
DiscardOldest	A boolean parameter that specifies the discard policy when the queue is full and a new notification is to be queued. It has the following values: True - the oldest (first) notification in the queue is discarded. The new notification is added to the end of the queue; False - the last notification added to the queue gets replaced by the new notification. Default = true.	10530	Persisted
ExcludeFromCatchup	If true, this item is excluded from catchup, ie. no historical data is read from the server, for this item, during the catchup process.	10600	Persisted
MonitoringMode	The monitoring mode parameter is used to enable and disable the sampling of a MonitoredItem, and also to provide for independently enabling and disabling the reporting of notifications. This capability allows a MonitoredItem to be configured to sample, sample and report, or neither. Default = Reporting.	10500	Persisted, Enumerated
MonitorState	The actual state of the monitored item.	11030	ReadOnly
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
QueueSize	The requested size of the "MonitoredItem" queue. Default = 1.	10520	Persisted
RevisedQueueSize	The actual queue size that the Server will use.	11020	ReadOnly
RevisedSamplingInterval	The actual sampling interval that the Server will use. This value is based on a number of factors, including capabilities of the underlying system. The Server shall always return a revisedSamplingInterval that is equal or higher than the requested samplingInterval. If the requested samplingInterval is higher than the maximum sampling interval supported by the Server, the maximum sampling interval is returned.	11010	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SamplingInterval	The interval that defines the fastest rate at which the MonitoredItem(s) should be accessed and evaluated. This interval is defined in milliseconds. The value 0 indicates that the Server should use the fastest practical rate. The value -1 indicates that the default sampling interval defined by the publishing interval of the subscription is requested. A different sampling interval is used if the publishing interval is not a supported sampling interval. Any negative number is interpreted as -1. Default = -1.	10510	Persisted
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
SrcUaNodeId	UA Node ID in source.	5031	Persisted
SrcUaNodeId-HA	UA Node ID in source, used for reading history, if the UA server has different nodeids for reading real-time data versus historical data. If empty, history reads defaults to using the 'SrcUaNodeId'.	10505	Persistd
Time	The date and time when this item was last updated.	4	ReadOnly
Trigger	This property specifies the conditions under which a data change notification should be reported: Status: Report a notification ONLY if the StatusCode associated with the value changes; StatusOrValue: Report a notification if either the StatusCode or the value change. The Deadband filter can be used in addition for filtering value changes; StatusOrValueOrTimestamp: Report a notification if either StatusCode, value, or the SourceTimestamp changes. If a Deadband filter is specified, this trigger has the same behaviour as StatusOrValue. Default = StatusOrValueOrTimestamp.	10540	Persisted, Enumerated
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Write as server datatype	If false, using current value datatype when writing this item to the server. If true, convert to datatype initially reported by server for this item, when writing to the server.	10610	Persisted, Expert

State Item

An item that represents a well defined state of this module.

The State Item item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

OPC Method Item

A method item in an OPC UA Server, letting you invoke a method on an object.

The OPC Method Item item type has the following properties:

Name	Description	ID	Flags
SrcUaNodeId	UA Node ID in source.	5031	Persisted
MethodId	The NodeId of the method to invoke, on the uaserver object.	12000	Persistd

The method items also automatically creates necessary OPC Method Input Arguments Item(s) and OPC Method Output Arguments Item(s), according to the definition of the method item in the UA server, represent any necessary inputs and outputs for the method.

Event Monitor Item

An item used to subscribe to events from the OPC UA server.

The Event Monitor Item has the following properties:

Name	Description	ID	Flags
SrcUaNodeId	The UA Node ID in the source server which should be monitored for events.	5031	Persisted
EventType NodeId	The UA Node ID of the base EventType this monitor should subscribe to.	13000	Persisted
UnmappedEventsourceAction	The action to perform when a received event has an unknown eventsource	13001	Persisted
LookupSourcePathTemplate	Template string used to construct an eventsource path from the received event fields	13002	Persisted
UnmappedEventtypeAction	The action to perform when a received event has an unknown eventtype	13003	Persisted
CatchupPeriod	Maximum number of seconds with event history to catchup after being disconnected	13110	Persisted

The property UnmappedEventsourceAction can have one of the following values, which decide the action to take when an event with unknown eventsource nodeid is received:

DropEvent: the event is dropped
UseModuleAsEventsource: the module containing the Event Monitor Item is used as the eventsource
LookupSourcename: the sourcename field of the event is used to lookup a fully qualified itemname in Apis Hive. If such an item is found, it will be used as the event source, automatically creating the needed source in Apis Event Server if required.
LookupSourcepath: A sourcepath is created from the property LookupSourcePathTemplate, and if exactly one event source in Apis Event Server matches the path, this is used as the event source.

The property LookupSourcePathTemplate is a string with injected event field values. Any event field can be referenced in the template with the syntax $(BrowseName), e.g. "Server/Plant/*/ABC-$(SourceName)". The search is case-insensitive and supports the following operators:

*: matches zero or more characters
?: matches one character
#: matches one digit
[]: match any character between the '[' and ']', unless the first character after '[' is '^', in which case the logic is inverted.

The property UnmappedEventtypeAction can have one of the following values, which decide the action to take when an event with unknown eventtype is received:

DropEvent: the event is dropped
UseParentType: traverse the OPC UA eventtype hierarchy and use the first known parent-type

The property CatchupPeriod, with a value greater than 0, causes the Event Monitor Item to perform history-read requests for periods where the OpcUa-module has been disconnected. This happens simultaneously with subscribing for realtime events.

Namespace Item

An item that represents a semantics caching namespace.

The namespace item type has the following properties:

Name	Description	ID	Flags
Name	The name of the item is the uri for the namespace it represents on the remote server the ua client module is connected to
Exposed URI / Value	The uri representing the namespace on the hive UA server. This may or may not be the same uri as the source uri on the remote server	15020	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Namespace store	Path to the database file containing the cached model for the namespace	15030	Persisted
Separator char	Character used to separate parts of function item names. Normally '.' is used to indicate parent-child like separation.	15040	Persisted
Name elements	What should make up the parts of function item names. Either browsename or displayname, possibly with the nodeid appended.	15050	Persisted, Enumerated
Name termination	When to stop following parent nodes for inclusion in function item names. Stop at naming root: Stop at the first parent object node having a property of the naming root property type. Stop at first object node: Stop at the first parent that is an object node.	15060	Persisted, Enumerated
Name generation	Determines when to generate function items fordata variables in the namespace. If no types in namespace: Only generate function items if there are no types defined by the namespace. Always, Never, Data variables that are not instance declarations: Unless a data variable is part of a type definition (instance declaration), it will have a function item generated for it.	15070	Persisted, Enumerated
URI for naming root	The uri-part of the node id for the naming root property type.	15080	Persisted
Naming root id type	The identifier-type-part of the node id for the naming root type.	15090	Persisted
Naming root identifier	The identifier-part of the node id for the naming root type	15100	Persisted
Naming root subtypes	Wether subtypes of the naming root type should be treated as a naming root	15110	Persisted
Naming root fail policy	What to do if the objects folder is reached without identifying an object having a naming-root property along the way. Fail: Generate an error, Stop at first object node: Regenerate the name, but stop at the first object node. Stop at objects folder: Use the full path to the objects folder.	15120	Persisted, Enumerated
Update Apis eventtypes	If set, custom eventtypes defined in the namespace will be created in Apis Chronical.	15160	Persisted

Item type: Module State Items

An item which retrieves status information from the module

The Module state items item type has the following properties:

Name	Description	ID	Flags
Item type	The item type this item aggregates statistics on, when applicable. Use the number inside the parentheses in "FileAdd" configuration files.	19001	Persisted, ReadOnly, DynamicEnumeration
Module state	The kind of module state information represented by this item. This can be a number of items having a given quality, a total number of items, the time the newest/oldest item was updated. Use a number inside the parentheses in "FileAdd" configuration files.	19000	Persisted, ReadOnly, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Item Attribute Items

An item which exposes an attribute of another item in the module

The Item attribute items item type has the following properties:

Name	Description	ID	Flags
Attribute ID	The ID of the attribute this item exposes from an item.	19002	Persisted, ReadOnly, DynamicEnumeration
ParentItem	The parent item name of this item.	5502	Persisted, ReadOnly, ApisLocalItem
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

OPC UA Catch-Up

Overview

This document describes the Catch-Up functionality implemented in the Apis Hive OPC UA client module. The Apis Hive OPC UA client module provides as default a standard OPC UA client with Node subscription and method call functionality.

In the cases of communication loss between an OPC UA server and OPC UA client, most OPC UA servers provides a short term buffering of subscription values. When clients re-connects after a relative short termed communication loss, the server start sending the buffered values. This standard OPC UA functionality will only work on short-term communication losses and are dependent on client/server buffer settings and server capabilities.

To accommodate problems with lost data after a long-term communication failure Prediktor has implemented the Catch-Up functionality in the OPC UA client. Unlike classic OPC, OPC UA provides both Data Access and History Access through the same interface. Apis Hive OPC UA client uses the History Access capability in OPC UA to read the logged values on the subscription nodes provided from the server for the duration of the communication failure. When all available history values on the subscription nodes are read up to the time of the re-connect, the client continues to read the subscribed node value through OPC UA Data Access as normal.

To get Catch-Up in Apis Hive UA client bee to work as intended, the server need to provide history data on all the items that the client subscribes to through Data Access.

The resolution on the logged data is not necessary the same as the negotiated sample-interval on the subscription nodes on source system. Differences between the logging interval and sample interval will result in different resolution on data collected through catch-up periods than through normal data access. Careful configuration on both the source server and client is necessary to accommodate this, if correct data resolution through both the catch-up (History Access) and Data Access data is important for the data consuming system.

Dependencies

The Apis Hive OPC UA bee has no Apis Hive dependencies.

Status Items

The Apis Hive OPC UA bee has a set of status items:

Item	Visibility	Description
#Connected#	Always	Item telling if module is connected to the OPC server; true: is connected, false: is disconnected.
#Session-State#	Always	Item telling the current status of the OpcUA session.
#Subscription-State#	Always	Item telling the current status of the OpcUA subscription.
#Endpoint#	Always	The URL to the OpcUA server.
#Catchup-State#	Catchup	Item telling the current state of data catch-up process. Realtime means no cathup is running, otherwise some sort of cathup related state.
#Catchup-PointInTime#	SerializedCatchup	Item telling the current point in time for the catchup process, when catch-up process is active.
#Catchup-RealTimeBufferCount#	SerializedCatchup	Item telling the current number of buffered real-time data callbacks during the catchup process, when catch-up process is active.
#Catchup-ReadChunksCount#	SerializedCatchup	Item telling the total number of data chunks read from the UA server during the catchup process, when catch-up process is active.
#Catchup-ReadChunksErrors#	Catchup	Item telling the total number of failed data chunks reads from the ua server during the catchup process, when catch-up process is active.
#Catchup-ReadSamplesCount#	SerializedCatchup	Item telling the total number of data samples read from the UA server during the catchup process, when catch-up process is active.
#Catchup-Speed#	SerializedCatchup	Item telling how many times faster than real-time the catchup process is running (note that a low figure may indicate both bad performance as well as high data density).
#Catchup-Progress#	DirectCatchup	Item telling the progress of direct catchup, in how many items have finished [#finished-read/#finished-writes/#total-items].
#Catchup-ReadSpeedAvg#		Item telling the average read speed of the UA server, in samples per millisecond.
#Catchup-StepNextTimeAvg#	SerializedCatchup	Item telling the average duration of a StepNext iteration, in milliseconds.
#Catchup-WrittenSamplesCount#	DirectCatchup	Item telling the total number of data samples written during the direct catchup process, when catch-up is active.
#Catchup-WrittenChunksCount#	DirectCatchup	Item telling the total number of data chunks written during the direct catchup process, when catch-up is active.
#Catchup-WriteSpeedAvg#	DirectCatchup	Item telling the average history write speed, in samples per second.

Command Item

The Apis Hive OPC UA bee has a catch-up relevant command item:

Item	Description
$Cmd_Catchup-Continue$	Trigger continuation of the catch-up prosess, when catch-up type is SerializedFull_PauseAfterInitial or SerializedPArtial_PauseAfterInitial

The command item is added through the add item method. The command type id: 10140.

Catch-Up relevant module properties

CatchUpMode: The data catch-up functionality of the communication. Set this to enable catch-up. Property ID: 1250
- NoCatchup: No data catch-up, just pure real-time communication.
- SerializedFull: Historical data is streamed through Hive sample-by-sample, until we have caught up real-time. Note that this requires the UA server to implement the OPC UA HA profile!
- SerializedFull_PauseAfterInitial: Same as 'SerializedFull', but will stop in playback sequence after first StepNext, use CommandItem $Cmd_Catchup-Continue$ to continue playback sequence.
- SerializedPartial: Only data missing locally, per item, is read from remote server and streamed through Hive, sample-by-sample, until we have caught up real-time.
- SerializedPartial_PauseAfterInitial: Same as 'SerializedPartial', but with one stop in playback sequence after first StepNext, use CommandItem #ContinueCatchup# to continue playback sequence.
- Direct: Historical data is written diectly into an APIS HoneyStore timeseries database (when item is logged), and the realtime data starts to updated immediately on the item as when no catch-up is in use.
  Note! When using Direct catch-up, it is important that the related Honeystore database(s) have their Capabilities property set to accepting Out-of-sequence data.
CatchUpPeriod: The maximum period to look back for historical data when initiating a catch-up operation. Select a pre-set value, or enter a value in seconds. Property ID: 1262
CatchUpChunkSize: How many values to read per node during catch-up read operations. Maps to 'numValuesPerNode' parameter of 'ReadRawModifiedDetails'. Default is 5000. Property ID: 1261
CatchupChunkCount: How many chunks to cache during catch-up read operations. Must be between 0-255. Default is 5.Property ID: 1260
CatchUpPeriod: The maximum period to look back for historical data when initiating a catch-up operation. Select a pre-set value, or enter a value in seconds. Property ID: 1262

CONFIGURATION OF SERIALIZED CATCH-UP

Catch-Up operation, step by step

When the OPC UA Client module re-connects after a period of communication loss, and if configured to do automatic catch-up, the OPC UA Client module will start to read the history data on the subscription items, starting from the time when the connection was lost, possibly limited by the set CatchUpPeriod module property. During this period of history data read, the module will buffer all Data Access subscription values in the module until all history data are read from the source system. After all the available item data is read up to the time of the re-connect, the module continuous with normal OPC UA Data Access subscription operation. During the Catch-Up the OPC UA Client Bee updates the configured data items in steps, assuring that all History data values for the items are written to the tags. Only single values are updated in each step.

Implications on memory usage

The OPC UA Client module reads the data in chunks. The number and size of the chunks for each item is configurable through the module properties: CatchUpChunkSize and CatchupChunkCount. The values set on these properties together with the number of items and item types will have implications on memory usage. The buffering of the OPC UA Data Access subscription items will also add to the memory consumption, so careful choice of Catch-up period must be selected to avoid out-of-memory situations. It is recommended to use the 64bit version of Apis Hive to ensure enough memory in high item volume solutions.

Timestamps

Item values read through OPC UA History Access (and OPC UA Data Access) will keep the server data timestamp through all the External Item transfers in Apis Hive, if not the TimeReferenceItems module property is set explicit. We recommend not using the TimeReferenceItems property in a catch-up solution.

EventBroker

Each Apis module normally have set of events and a set of commands. An event in one module can cause a command to be fired in another module. The mapping of the events to commands are done in the Event Broker. The OPC UA client module has a specific event CatchUp-StepNextDone and a specific command CatchUp-StepNext, that fires when a catch-up step is done and triggers each step in the catch-up process respectively. The module also fires a ServerDataChanged event after a new set of item values are received, both during catch-up and normal operation. Only a single value for each item are updated for each trigging of the ServerDataChanged event.

Trig the CatchUp-StepNext command by the CatchUp-StepNextDone event on the OPC UA Client Module, to ensure proper operation of events during normal operation.

This will be coverd in more detail below.

Figure 1, Event broker, CatchUp-StepNext on CatchUp-StepNextDone.

Apis Hive Inter-module data exchange

When using the Catch-Up functionality in the Apis Hive OPC UA Client Bee, it is important to configure the Apis Hive Data Exchange accordingly.

It is important to use the synchronized event/command functionality in the Apis Hive Event Broker instead of asynchronous timer-based Data Exchange

ExternalItem transfer in Apis

Apis Hive is a module based system environment that gives you the opportunity to collect, process and store real-time data. Different modules in Apis Hive provides different functionality, but common to all is the inter-module data exchange provided by the ExternalItem functionality.

Example of data exchange between modules

In this example system, we use a simple setup consisting of tree modules in an Apis Hive default instance:

A connection module, the OpcUa Client bee, named OpcUaBee.
A process module, the Calculate Bee, named Calculate.
A store module, the Logger Bee, named ClientLogger.

A simple view of the modules:

Figure 2, Apis Hive with Calculate, Logger and OpcUa client module.

The OpcUaBee module has one subscription item that reads a sine signal from the a source systemed named CustomerServer. The Item is named CustomerServer.Worker.Sine. Further the Calculate module has one item, named SineTimes2, which has CustomerServer.Worker.Sine as input through the external item connection.

Figure 3, Item connection.

Data exchange, by exchange rate (not recommended with catch-up):

Normally, data exchange (ExternalItem) is configured at destination side by adding one or more external items to an item by the item attributes. Second the destination module need to be set to use a specific Exchange rate, a definition of the period between each read of the connected items, normally in the millisecond area. In this way, the items will be inter-connected, and read at a specific time period.

Data exchange, by event broker:

In the figure below, we see that the OpcUa trigger the ClientLogger module to log, the Calculate module to handle its external items and the ClientLogger module to log again when ServerDataChanged event fires. The reason for logging twice is to ensure that history values that could be needed by calculate operations are properly logged before calculations are trigged, and results from the calculations are logged. Values on items that has not changed will not be logged.

We also see that CatchUp-StepNext is triggered as before by CatchUp-StepNextDone.

Figure 4, Event broker.

Catch-Up steps summary

The steps of the Catch-Up summed up:

The module re-connects after a period of lost communication
The buffering of the OPC UA Data Access subscription data on the items starts immediately
The module decides from what timestamp to start to read item history data from, based on time of communication loss or reconnect-time and CatchUpPeriod setting.
The module starts to read history data in chunks and trigger the event in event broker for each change in item value.
If configured, the external item values are synchronously updated through the Event Broker event ServerDataChanged for each value update.
After all history data is read, the OPC UA Client Module continuous with normal OPC UA Data Access subscription operation.
If configured, the external item values are synchronously updated through the Event Broker for each value update.

Recommendations

Use event-broker to handle Apis Hive Data Exhange, trigging of CatchUp-StepNext command by the CatchUp-StepNextDone event is a must.
Ensure proper configuration of both client and source system server to achieve same data sampling rate of both History Access item data and item subscription (OPC UA Data Access) data.

CONFIGURATION OF DIRECT CATCH-UP

Direct catch-up is more straight forward to use, and is the correct choice if:

you want the realtime values for items to be applied on the UA client items rights away.
you just need to fetch historical data for periods where the UA client was not running.
you don't need to perform calculations and/or alarming on the items when catching up.

When using direct catch-up, the missing item data will be retrieved item-by-item. This means that during the catchup process, some items will have all their missing database fetched, as other items will not.

ADVANCED CATCH-UP CONFIGURATION

When running catchup towards misbehaving UA servers, i.e. servers not returning an initial VQT for all subscribed items after creating the subscription, the catchup process will be stuck waiting forever to get started. This is because the catchup process needs to have an initial VQT for all its items, to be able to determine the End times to use for the history read operations.

To allow the catchup process top run such UA servers, two strategies has been implemted as a workaround.
If forced, the highest time of the current local computer time and server time (as reported by the UA server), will be used as endtimes for the stale items.

These strategies are:

MaxEqualMissingEndtimesCatchupContinue: After 3 (default) publish responses during startup, with the UA server failing to update any new VQTs, the catchup process will be forced to start.
The default value of 3 can be changed through registry key value MaxEqualMissingEndtimesCatchupContinue of the module.
MaxWaitSecondsMissingEndtimesCatchupContinue: After 600 seconds (default) since startup, with the UA server failing to update all VQTs, the catchup will be forced to start.

To modify the values any of these two settings, create DWORD values named MaxEqualMissingEndtimesCatchupContinue and/or MaxWaitSecondsMissingEndtimesCatchupContinue, for the for the actual Opc UA client module, and ehter other values.
E.g., for a Hive instance named AI_Catchup and an OPCUA client module named OpcUa and new default values 60 (=0x3c) and 120 (=0x78):

[HKEY_LOCAL_MACHINE\SOFTWARE\Prediktor\Apis\AI_Catchup\Modules\OpcUa]  
"MaxEqualMissingEndtimesCatchupContinue"=dword:0000003c  
"MaxWaitSecondsMissingEndtimesCatchupContinue"=dword:00000078

Apis OpcUa Proxy

This module is used to configure federation of selected namespaces from other OpcUa servers.

Provider: Prediktor

Item types:

Namespace item

Item Types

Namespace item

NamespaceItem

The Namespace item is used to configure one remote OpcUa namespace for federation through the OpcUa server in this Apis instance.

It has the following standard properties:

Name	Description	ID	Flags
Name	The namespace uri on the remote server.		Persisted
Exposed uri	If specified, a custom uri used to represent the remote uri when exposing the federated namespace in the OpcUa server in this Apis instance.	10010	Persisted
Value	The uri exposed by the OpcUa server in this Apis instance (read-only). This value is equal to the"Exposed uri" property when that property has been specified. When not, "Value" equals "Name", i.e. the actual namespace uri on the remote server.	2

Properties

The OpcUaProxy module has the following standard properties:

Name	Description	ID	Flags
OpcUa server	The server configuration to use for this proxy module. The list of available servers is populated with OpcUa connection and OpcUa cluster items defined by ApisCnxMgr modules.	1001	Persisted, Enumerated
Impersonate	If checked, the authentication information provided by each OpcUa client connecting to this Apis instance, will be used when federating OpcUa messages for the client to the selected server. If not checked, all clients will reuse the authentication information configured by the selected OpcUa connection item.	1002	Persisted
Optional	If checked, browsing of the local OpcUa server and other federated OpcUa servers will work even if this module does not have a connection with its OpcUa server	1003	Persisted

The OpcUaProxy module has the following informational properties:

Name	Description	ID	Flags
Endpoint url	The current endpoint url for the selected server.	1100

Apis OpcUa Method

A module for querying and iterating over collections using OPC UA methods.

Currently the supported integration is SQL server, which can be used to connect to an SQL server for querying using stored procedures available on the server and general select statements.

The module exposes a set of objects and methods in OPC UA that can be used for querying and iterating over the collections.

Provider: Prediktor

The OPC UA Method module has the following item types:

Item Types

Stored Procedure Item

This item type is an SQL Item for querying the SQL database using select statements.

The item type has the following properties:

Name	Description	ID	Flags
Stored procedure	The name of the stored procedure on the SQL server	18653	Persisted

The item type exposes stored procedures from an SQL server into an OPC UA namespace. It is configured by adding items in APIS that specifies the name of the stored procedure that is to be exposed. The parameters from the stored procedure is infered onto the First method exposed in the OPC UA namespace.

The available stored procedures can be browsed when adding new Stored procedure items in APIS.

Select Item

This item type is an SQL Item for querying the SQL database using select statements.

Parameters of the item type:

Name	Description	ID	Flags
Select statement	Select statement for querying the SQL server	18653	Persisted, Multiline

The select statement is a parameterized string containing the query, and with the paramaters as specified on the following format:

@[myparam]:[param datatype]

An example of this could be

select * from my_table
where my_int_column = @a:int

In OPC UA this would expose an object with a First method that takes the max number of rows and a parameter @a that must be of type int.

Supported datatypes:

int
float
datetime
nvarchar

SQL Items

SQL item types consists of

The items are used to collect data from an SQL server using either select queries or invoking stored procedures. The items exposes objects in OPC UA namespace that contains methods for iterating over the data return from the queries.

The items exposes two methods in the OPC UA namespace

First
Next

The parameters of the First method is the max numbers of rows to return in each query, and the parameters as defined in either the stored procedure or the select query. The supported SQL data types and the corresponding mapping to the OPC UA datatypes is listed in the table below.

SQL datatype	UA built-in type ID
int	6
datetime	13
nvarchar	12
float	10
bigint	8

OPC UA Datatypes

First will return the data as an matrix containing the result of the query. If the results exceeds the max number of rows argument, First will also return an continuation point id. The continuation point id can then be used an argument when calling Next, which will return the next batch of results.

Notes

When theres a continuation point, the user should always resolve the rest of the data by calling Next methods until theres no more continuation points. This will ensure the connection is closed.

Properties

The module contains the following standard properties:

Name	Description	ID	Flags
Connection string	Standard SQL connection string	2563	Persisted

For a connection to a Microsoft SQL server:

Provider=MSOLEDBSQL;Data Source=SERVER_URI;Initial Catalog=DB_NAME;User ID=USERNAME;Password=PASSWORD;

Note:

The Provider for a Microsoft SQL server must be MSOLEDBSQL.

PostgreSQL

To use the module with a PostgreSQL server, do the following:

Install psqlODBC using Stack Builder application
Configure ODBC data source using ODBC Data Source Administrator

System DSN: Add
Select PostgreSQL ODBC Driver(UNICODE)
Specify parameters, e.g. database=postgres,server=localhost,username=postgres,port=5432,password=xxx
Test the connection

Specify connection string for the module, e.g.

Provider=Microsoft OLE DB Provider for ODBC Drivers;Data Source=PostgreSQL35;location=postgres;User ID=postgres;password=xxx;timeout=1000;
Data Source is the Name of the data source as specified in ODBC Data Source Administrator

Make sure the user has read/write permissions to the database and tables used in the module:

Right-click on the table and click Properties
Go to Security tab and grant permissions

Apis PerformanceMonitor

Module for collecting performance data from a local or remote machine.

Provider: Prediktor

The PerformanceMonitor module has the following item types

Performance Counter

Perfmon Command

Properties

The PerformanceMonitor module has the following properties:

Name	Description	ID	Flags
Computer	The computer to connect to for getting Performance Monitor data. Left blank for local computer.	1002	Persisted
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
Interval	The update interval for the Performance Counters, in ms. Determines how often the module will poll the system for updates.	1001	Persisted

See also Module Properties

Commands And Events

The PerformanceMonitor module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Add new Performance Counter items

You can add new Performance Counter items by right-click on PerformanceMonitor --> Add Items --> Performance Counter:

A dialog then pops up to allow you to configure the items to be created:

You MUST click on the Browse button to choose from all system predefined Performance Counters to add.

The Browse button brings up another dialog:

In this dialog, choose one or more Performance Counter and click Ok. You can also search for keywords in the Search bar on the top.

For example, if you want to monitor the incoming and outgoing internet connection speed, you can choose "@IPv4/Datagrams/sec":

Click Ok, you will see a new Performance Counter is added:

Now you have added a new Performance Counter item, you can use it as the same as other OPC items.

Identify Processes By Instance Name

When you use the system built-in utility Perfmon.exe to monitor multiple instances of the same process and you have more than one instances of the same executable file running at the same time, you have probably noticed that Perfmon.exe differentiates the process by giving them an arbitrary numbered name, for example ApisHive, ApisHive#1 and ApisHive#2. This behavior is most likely not what you would expect, since it is not very clear which process responds to which ApisHive instance you started, and the random numbers change every time you restart your ApisHive instances.

PerformanceBee improves this by adding the instance name to the process name, such as ApisHive_apishiveinstance, ApisHive_anotherinstance, where ApisHive is the process name(executable file name) and apishiveinstance is the instance name. This works even after you restart your ApisHive instances.

Now only ApisHive instances are identified in this way.

To support this, there are some configurations need to be done:

On target machine(machine being monitored):

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\PerfProc\Performance\ProcessNameFormat set to 2. (DWORD)
Service named RemoteRegistry is running.
ApisHive instances are running using different names.
The monitoring account (usually a domain account, which is also used to launch the PerformanceBee on the monitoring machine) is added into user group “Performance Log Users” and “Performance Monitor Users”
The monitoring account is allowed in WMI\Root\CIMV2\Securities (use WMI Control snapin, wmimgmt.msc)

On monitoring machine:

The monitoring account(the account that launched PerformanceBee) can be added to related user groups on target machine.

Item Types

Properties

A Performance Counter describes a measurable property of a machine, remote or local, such as CPU load.

The Performance Counter item type has the following properties:

Name	Description	ID	Flags
Performance Counter Category	The category that the Performance Counter belongs in.	10001	Persisted
Performance Counter Instance	Instance name for the Performance Counter, when it is necessary to distinguish between them. Left blank for single-instance counters.	10002	Persisted
Performance Counter Name	The name given to the Performance Counter within its category.	10003	Persisted
Performance Counter Sample Exposure	The aspect of the Performance Counter to expose. Default means to expose the appropriate value depending on the counter type. RawValue exposes the CounterSample.RawValue Int64 Property of the counter. Calculated exposes the 4 byte floating point value resulting from the CounterSample.Calculate Method of the counter.	10004	Persisted
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

This item controls whether the Performance Monitor module is running or not.

The Perfmon Command item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Apis Replay

This module will playback values recorded to an OPC HDA server.

Provider: Prediktor

The Replay module has the following item types

More information

Properties

The Replay module has the following properties:

Name	Description	ID	Flags
ActiveBuffer	The buffer which data is replayed	13000	ReadOnly, PerformancePage
ActiveBuffer1	Status if the buffer is active	11900	ReadOnly, InfoPage
ActiveBuffer2	Status if the buffer is active	12400	ReadOnly, InfoPage
CmnItemIDPrefix	Common source ItemId prefix. This string will prefix each item's 'ItemID' when communicating with the OPC HDA server, and used as a filter when browsing this server's items.	1030	Persisted
CmnItemIDPrefix item	Common source ItemId prefix. This string will prefix each item's 'ItemID' when communicating with the OPC HDA server, and used as a filter when browsing this server's items.	1031	Persisted, ApisItem, ExpertPage
Computer	The computer hosting the OPC HDA server.	1010	Persisted, Computer
CurrentPlayIndex	The index of the active buffer	12900	ReadOnly, PerformancePage
EndTime	The latest time (UTC) of the history to be read.	1065	Persisted
EndTimeBuffer1	The end time of the buffer	12300	ReadOnly, InfoPage
EndTimeBuffer2	The end time of the buffer	12800	ReadOnly, InfoPage
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ItemCountBuffer1	The count of values in the buffer	12000	ReadOnly, InfoPage
ItemCountBuffer2	The count of values in the buffer	12500	ReadOnly, InfoPage
ItemPropSync	How to synchronize item attributes from historian HDA attributes	1095	Persisted, Enumerated, ExpertPage
PrefetchStrategy	PrefetchStrategy	11700	Persisted, Enumerated
Realtime	Fetches the freshest HDA value, ignoring start/end time	1082	Persisted, ExpertPage
ReportBufferStatus	Reports buffer status to the log files for log view in Apis Management Studio	11800	Hidden, InfoPage
Resolution	The time between updates [seconds]	1075	Persisted
Server	The ProgID of the OPC HDA server.	1020	Persisted, Enumerated, ProgID
ServerCLSID	The CLSID of the specified OPC HDA server	10000	Persisted, ReadOnly, InfoPage
SrvCurrentTime	The current time (UTC) as known by the OPC server.	11100	ReadOnly, InfoPage
SrvLCID	Locale ID of values coming from the server. You might need to specify this property if the OPC server provides string values that is converted to another type in your client (e.g. DDE bridges)	1040	Persisted, ExpertPage
SrvMaxRetVals	The maximum number of return values supported by the server.	11200	ReadOnly, InfoPage
SrvStartTime	The time (UTC) the OPC server was started.	11000	ReadOnly, InfoPage
SrvState	The current status of the OPC HDA server	11300	ReadOnly, Enumerated, InfoPage
SrvStatusString	Status string in the OPC HDA server.	11400	ReadOnly, InfoPage
SrvVendorInfo	Vendor specific information about the OPC HDA server	11600	ReadOnly, InfoPage
SrvVersion	The version number of the OPC HDA server (major-minor-build)	11500	ReadOnly, InfoPage
Start on load	If true replay starts when module starts	1088	Persisted, ExpertPage
StartTime	The earliest time (UTC) of the history to be read.	1060	Persisted
StartTimeBuffer1	The start time of the buffer	12200	ReadOnly, InfoPage
StartTimeBuffer2	The start time of the buffer	12700	ReadOnly, InfoPage
Step on NextTime	Perform step when NextTime is set	1083	Persisted, ExpertPage
SynchronousReadAggregate	The aggregate to read from the OPC HDA server when using synchronous replay. Applies to data returned for SynchronousItems only.	1087	Persisted, DynamicEnumeration
SynchronousReadDelay	A delay in milliseconds inserted before the ReadSynch command, 0 to disable delay.	1085	Persisted
TimeMode	The time mode used to timestamp items.	1050	Persisted, Enumerated, ExpertPage
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TracefileMaxSize	The max size of the trace file before the file is truncated in bytes. Default is 50 MB => 50 * 1024 * 1024	15000	Persisted, ExpertPage
TraceServerState	This is used to trace detail information about internal steps of a replay sequence. Note: Be care full of enabling 'PlayBackValues' and 'All Calls' since this can result in mutch disk activity.Disabled - Trace not activeTraceCall - The different function calls which are called during replayWaitForData - The request for dataStatusChange - On status changeReadServer - When data is read from serverCurrentIndex - Current index being replayedFireBrokerEvent - When broker event is sendPlayBackValues - The values being replayedCommands - Commands being sentStartupSequence - The startup sequence of replay beeRequestMoreData - Not used at the momentActivatedItems - When items are set active for replayAll Calls - Trace active for all types	15020	Persisted, Enumerated, ExpertPage
TraceToFile	This is used to trace detail information about the internal status of the replay session. The type of status to trace is given by the property 'TraceServerState'	15010	Persisted, File, ExpertPage
UseHDATimestamp	Use HDA Timestamp for each interval, if false the item timestamp is used. Applies to data returned for SynchronousItems only when aggregate is Interpolative zero-order	2000	Persisted, ExpertPage
UseRelativeTime	Use relative Start and End time, valid only for aggregate data.	1072	Persisted, ExpertPage
ValueCountBuffer1	The count of values in the buffer	12100	ReadOnly, InfoPage
ValueCountBuffer2	The count of values in the buffer	12600	ReadOnly, InfoPage

See also Module Properties

Commands And Events

The Replay module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
OnPlaybackDone	An event that notifies that a playback step has finished. Necessary if another module is to be synchronized with the playback mechanism.	Normal
OnSynchReadDone	An event that notifies that a synchronous read operation has finished for all the SynchronousItem's of this module.	Normal
OnSynchReadEnd	An event that notifies that a synchronous start time is bigger than end time.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
ReadSynch	A command initiating a synchronized read operation into the OPCHDA server for all SynchronousItems.	Synchronous
StartSyncRead	Initialize sync read.	Synchronous
StepSynch	A command initiating a synchronized step operation into the OPCHDA server for all SynchronousItems.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

An item available for synchronous replay from the OPC HDA server.

The SynchronousItem item type has the following properties:

Name	Description	ID	Flags
AlwaysActive	This property forces the item to always be in the active item set.	10030	Persisted
ItemActive	The status for if the item is active or not.	10025	ReadOnly
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

Time (UTC) of the history to be read.

The Time item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

RelativeTime (UTC) of the history to be read.

The RelativeTime item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Integrated control item

The Control item item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Replay state

The State item item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Apis SegScaleBee

Description of ApisSegScaleBee

Provider: Prediktor

Batch weight of the last batch

The SegScaleBee module has the following item types

Int VectorVariable

String VectorVariable

Double VectorVariable

Int Trigger In

Properties

The SegScaleBee module has the following properties:

Name	Description	ID	Flags
Com port	Serial IO Com port id. Must Start with COM	1002	Persisted
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
Log file	The file name for Seg scale serial IO log.	1010	Persisted, ExpertPage
Log file Maxsize	The max size of the log file before it get recycled (Default value=5.000.000 [bytes]).	1009	Persisted, ExpertPage
Log level	Defines the log level	1011	Persisted, Enumerated, ExpertPage
Scale address	The RS 485 bus address of the Seg scale	1003	Persisted
ScaleRole	Defines the SegScaleBee role type. The items will be generated based on the role of the module.	1001	Persisted, ReadOnly, Enumerated, ExtraInfo
Serial IO Baud Rate	The serial IO Baud Rate	1004	Persisted, ExpertPage
Serial IO Data bits	The serial IO Data bits	1006	Persisted, ExpertPage
Serial IO Stop bits	The serial IO Stop bits	1007	Persisted, Enumerated, ExpertPage
Serial IO timeout	The serial IO communication timeout period in milliseconds	1005	Persisted, ExpertPage
Weight margin	The margin in kilograms period, in seconds, for weight to indicate stand-still state	1012	Persisted, ExpertPage
Weight stand still period	The period, in seconds, for weight to standstill to indicate stand-still state	1008	Persisted, ExpertPage

See also Module Properties

Commands And Events

The SegScaleBee module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

Int Status Item

The Int Status Item item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

Bool Status Item

The Bool Status Item item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	Decides which type (e.g. Double, String, Bool) the item is to be. (Bool=10, Double=20, String=30)	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

String Status Item

The String Status Item item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

The weight

The Weight item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

Double Status Item

The Double Status Item item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

Int Input

The Int Input item type has the following properties:

Name	Description	ID	Flags
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Double Input Item

The Double Input Item item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Bool Input Item

The Bool Input Item item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

String Input Item

The String Input Item item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

The batch level trigger will change value when weight reaches batch size

The Batch weight of the last batch item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

Int VectorVariable

The Int VectorVariable item type has the following properties:

Name	Description	ID	Flags
Dimension	The dimension of a vector item (number or elements).	5007	Persisted
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

String VectorVariable

The String VectorVariable item type has the following properties:

Name	Description	ID	Flags
Dimension	The dimension of a vector item (number or elements).	5007	Persisted
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Double VectorVariable

The Double VectorVariable item type has the following properties:

Name	Description	ID	Flags
Dimension	The dimension of a vector item (number or elements).	5007	Persisted
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	Decides which type (e.g. Double, String, Bool) the item is to be. (Bool=10, Double=20, String=30)	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Int Trigger In

The Int Trigger In item type has the following properties:

Name	Description	ID	Flags
Inputs	The item handle (unique identifier) of the inputs.	5510	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Apis Semantics

This module defines an opc ua namespace and allows mapping data variables in the model to hive function items. If a semantics module is removed from a hive instance, its' unique namespace uri cannot be re-used by a new instance of a semantics module before the hive instance has been restarted. If the namespace model for the semantics module needs to be replaced (ie. by importing an updated model from a nodeset2 xml file), importing the model without first deleting it, will replace the existing model without having to restart the hive instance.

Provider: Prediktor

The semantics module has the following item types

Module State Items

Item Attribute Items

Function item

Properties

The Worker module has the following properties:

Name	Description	ID	Flags
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ExtItem pass-through quality	Specifies the quality of external item values that will pass through external item transfers. Default is 'Good and Uncertain qualities'	400	Persisted, Enumerated, ExpertPage
ExtItemCalculationSequence	Decides whether data validation or data transfer will be performed first in the external item manager.	300	Persisted, Enumerated, ExpertPage
PersistValToInitVal	Choose strategy for copying and persisting current value to the InitValue. Tip: Consider using an InitVQTFromHoneystore attribute instead, for better performance.	1650	Persisted, Enumerated
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
Objectstore	Path to the (sqlite) database containing the ua model for the namespace. The path may be expressed relative to the hive instance's configuration folder.	1020	Persisted
Uri	The unique uri identifying the namespace	1025	Persisted
Update of uri-metainfo	Specifies wether the PublicationDate, ModelVersion and LastChanged properties for the namespace should be maintained automatically or manually.	1027	Persisted, Enumerated
ModelVersion	The current model version	1028	Persisted
PublicationDate	The publication date for the namespace model	1029	Persisted
LastModified	The last modified date for the namespace model	1030	Persisted
Nameoptions	What should make up the parts of function item names. Either browsename or displayname, possibly with the nodeid appended.	1050	Persisted, Enumerated
Valuename separator	Character used to separate parts of function item names. Normally '.' is used to indicate parent-child like separation.	1065	Persisted
Name termination	When to stop following parent nodes for inclusion in function item names. Stop at naming root: Stop at the first parent object node having a property of the naming root property type. Stop at first object node: Stop at the first parent that is an object node.	1095	Persisted, Enumerated
Naming root type URI	The uri-part of the node id for the naming root property type.	1100	Persisted
Naming root type ID type	The identifier-type-part of the node id for the naming root type.	1101	Persisted, Enumerated
Naming root type ID	The identifier-part of the node id for the naming root type	1102	Persisted
Allow naming root subtypes	Wether subtypes of the naming root type should be treated as a naming root	1103	Persisted
Missing nameroot policy	What to do if the objects folder is reached without identifying an object having a naming-root property along the way. Fail: Generate an error, Stop at first object node: Regenerate the name, but stop at the first object node. Stop at objects folder: Use the full path to the objects folder.	1105	Persisted, Enumerated
Function item generation	Determines when to generate function items fordata variables in the namespace. If no types in namespace: Only generate function items if there are no types defined by the namespace. Always, Never, Data variables that are not instance declarations: Unless a data variable is part of a type definition (instance declaration), it will have a function item generated for it.	1115	Persisted, Enumerated
Assign Ids	If set, unique ids must be assigned by the client when creating new objects. If not set, unique (numerical) ids will be automatically generated when creating new objects.	1080	Persisted
Database busy timeout	Timeout in ms specifying max time to wait before returning BUSY error when the database is locked. Hive must be restarted in order for changes to this parameter to take effect.	1150	Persisted, ExpertPage
Retries when busy	The maximum number of times to retry a db transaction when the operation fails with a BUSY error. Hive must be restarted in order for changes to this parameter to take effect.	1155	Persisted, ExpertPage
Update Apis Eventtypes	If set, custom eventtypes defined in the namespace will be created in Apis Chronical.	1160	Persisted, ExpertPage

See also Module Properties

Item Types

Item type: Variable

User defined item, which can be written and read.

The Variable item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10010	Persisted, Enumerated

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

Apis SQL

The ApisSQL module reads and/or writes data to/from any SQL relational database.

Provider: Prediktor

The SQL module has the following item types

More information

SQL Procedure Examples

Get SQLBee Values

Pu and Get SQLBee Values

Write Data Target

Properties

The SQL module has the following properties:

Name	Description	ID	Flags
ADO CommandTimeout	Indicates how long to wait (in seconds) while executing an SQL command before terminating the attempt and generating an error. The default is 30 seconds. If you enter the value 0, SQL commands will never timeout.	1090	Persisted
AvgSQLQTime	The average query time in milliseconds for SQL queries performed. This is averaged from the last time the statistics were reset or Apis was restarted.	100000	PerformancePage
Connection state	The current state of the connection to the database. This field allows you to see if the bee is connected to the database, if it has the appropriate security rights and if the stored procedure ran successfully.	10000	InfoPage
Custom ConnectionString	When not using MS SQL Server, or if you want to have full control over the connection string, you can specify a custom connection string here. NOTE! When this property is in use, the database login, database login password, database name, and database server are ignored.	1040	Persisted, ExpertPage
Database login	The same as User ID in a standard connection string. If this field is blank, integrated security will be used.	1020	Persisted, User
Database login password	The password to use when accessing the SQL database.	1030	Persisted, Password
Database name	The name of the database on given server, used in the connection string.	1015	Persisted
Database server	The server machine where the database exists, used in the connection string.	1010	Persisted
Description	A description of this module, useful for future maintenance to describe what this module should do.	101	Persisted
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
Last executed SQL	The last executed SQL statement, the text last sent to the SQL server for execution. This field can be useful for debugging, as it allows you to see exactly what SQL is being sent to the SQL server.	10100	InfoPage
LastRecordsetParseTime	The last time a recordset was received and parsed from the SQL Server.	100100	PerformancePage
Locale ID	The locale ID to be used when parsing files. This is a unique id for the country and language, used to determine multiple factors including date formats and decimal points.	1057	Persisted
MaxSQLQTime	The maximum query time in seconds for the SQL queries performed since the last time the statistics were reset or Apis was restarted.	100001	PerformancePage
PDS snapshot SourceDatabase	The name of the snapshot source database. Must be specified when running queries on a PDS snapshot, use this field together with the property 'PDS snapshot usage'	1046	Persisted, ExpertPage
PDS snapshot usage	Whether to use PDS Snapshots or not. When snapshots are to be used, specify the name of the source database database in property 'PDS snapshot SourceDatabase' as well , and the SQL query will be executed on a snapshot acquired from the PDS Snapshot Manager.	1045	Persisted, Enumerated, ExpertPage
Provider	The provider of the module.		Persisted
SQL statement	The SQL statement to execute. Can be an 'execute statement' or a fully qualified file name containing the statements to execute. This, in combination with the SQL statement type property, decides what text to send to SQL server.	1080	Persisted
SQL statement type	This dropdown property has two options: Execute as text - the text will be sent to the SQL database as it's written and executed. For example, SELECT * FROM AnyTableName; Execute as stored procedure - A name of a stored procedure with predefined signature that will be executed with arguments (mandatory when using Write items). The write items are sent as XML, which is covered in further detail in the Quick Start Guide.	1079	Persisted, Enumerated
Table schema	How the data will be returned from the SQL executed. 'By rows' means item name, value, timestamp and quality are in one row, in this order. 'By columns' means item name(s) is column header(s), value in first row, timestamps and quality are not supported.	1075	Persisted, Enumerated
Timer interval	Timer interval in milliseconds, must be >= 50 ms. Ensure that this is not smaller than the runtime of the SQL executed, or the server may struggle to keep up with demand from the module.	1110	Persisted
TimeReferenceItem	An item, the value of which will be used as the time reference for this module instead of the system time when setting the timestamp on items.	200	Persisted, ApisItem, ExpertPage
Version	The version of SQL Bee this module is running.		Persisted

See also Module Properties

Commands And Events

The SQL module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
OnTimer	An event fired when at a rate given by the ModelRefreshInterval or Timerperiod property	Normal
UpdateDone	An event for when the updating of the recordset is done.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
SynchUpdate	Updates the recordset synchronously.	Synchronous
Update	Update the recordset.	Asynchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Read Item Properties

Item type for reading scalar, vector and matrix values from the database.

The Read item item type has the following properties:

Name	Description	ID	Flags
InitValueEnabled	Whether this item has an initial value on start up of Apis Hive. If enabled, this allows for the setting of a value so the initial value isn't blank or null on each restart.		Persisted
Item type	A field indicating what type of item this is. This is always set to "Read item" for Read Items.		ReadOnly
Name	The name of this item. This is independent of the name of the item from SQL server (see the SrcItemID property).		Persisted
Quality	Item quality. This indicates the current quality of the signal from SQL Server. The quality may be "Good" meaning the field is being read correctly, "Bad:Connect error" meaning that there's a problem with the database location or security properties on the module, or "Bad:Config error" meaning there's another problem with the connection to the database, or the field is not found in the database results.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly
Valuetype	Item canonical datatype. The type of value this field contains. For example, string, int, datetime, etc.	10031	Persisted, Enumerated

Write Item Properties

Item type for writing scalar values to the database.

The Write item item type has the following properties:

Name	Description	ID	Flags
InitValueEnabled	Whether this item has an initial value on start up of Apis Hive. If enabled, this allows for the setting of a value so the initial value isn't blank or null on each restart.		Persisted
Item type	A field indicating what type of item this is. This is always set to "Write item" for Write Items.	5801	ReadOnly
Name	The name of this item. This is independent of the name of the item from SQL server (see the SrcItemID property).	100	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly
Valuetype	Item canonical datatype. The type of value this field contains. For example, string, int, datetime, etc.	10031	Persisted, Enumerated
WriteUpdatedOnly	This field is set to true by default, and means that values will only be sent to SQL Server if the value has changed since the last time the command was run. If the value has no changed, it will be omitted from the list of parameters in the XML to SQL Server.	11000	Persisted

Write Vector Properties

Item type for writing vector values to the database.

The Write vector item item type has the following properties:

Name	Description	ID	Flags
Arraytype	The data type of the values to be held in the matrix. For example, string, int, datetime, etc.	10041	Persisted
Dimension	The dimension of a vector item (number or elements).	5007	Persisted
InitValueEnabled	Whether this item has an initial value on start up of Apis Hive. If enabled, this allows for the setting of a value so the initial value isn't blank or null on each restart.		Persisted
Item type	A field indicating what type of item this is. This is always set to "Write vector item" for Write Vector Items.	5801	ReadOnly
Name	The name of this item. This is independent of the name of the item from SQL server (see the SrcItemID property).	100	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly
WriteUpdatedOnly	This field is set to true by default, and means that values will only be sent to SQL Server if the value has changed since the last time the command was run. If the value has no changed, it will be omitted from the list of parameters in the XML to SQL Server.	11000	Persisted

Write Matrix Properties

Item type for writing matrix values to the database.

The Write matrix item item type has the following properties:

Name	Description	ID	Flags
Arraytype	The data type of the values to be held in the matrix. For example, string, int, datetime, etc.	10041	Persisted
Columns	The number or columns in matrix item.	5009	Persisted
InitValueEnabled	Whether this item has an initial value on start up of Apis Hive. If enabled, this allows for the setting of a value so the initial value isn't blank or null on each restart.		Persisted
Item type	A field indicating what type of item this is. This is always set to "Write matrix item" for Write Matrix Items.	5801	ReadOnly
Name	The name of this item. This is independent of the name of the item from SQL server (see the SrcItemID property).	100	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Rows	The number of rows in a matrix item.	5008	Pesisted
SrcItemID	The item ID in the source. This is the item ID this item uses to fetch data from the source.	5030	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly
WriteUpdatedOnly	This field is set to true by default, and means that values will only be sent to SQL Server if the value has changed since the last time the command was run. If the value has no changed, it will be omitted from the list of parameters in the XML to SQL Server.	11000	Persisted

Trigger Item Properties

Item which can trigger an SQL update.

The Triggeritem item type has the following properties:

Name	Description	ID	Flags
InitValueEnabled	Whether this item has an initial value on start up of Apis Hive. If enabled, this allows for the setting of a value so the initial value isn't blank or null on each restart.		Persisted
Item type	A field indicating what type of item this is. This is always set to "Triggeritem" for Trigger Items.	5801	ReadOnly
Name	The name of this item. This is independent of the name of the item from SQL server (see the SrcItemID property).	100	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

SQL Examples

WriteDataTarget

This query creates table (WriteDataTarget) with all necessary columns to be able to read/write data from Apis SQL module.


USE [TestDB]

GO

/****** Object: Table [dbo].[WriteDataTarget] Script Date: 06/08/2009 15:53:05 ******/

SET ANSI_NULLS ON

GO

SET QUOTED_IDENTIFIER ON

GO

CREATE TABLE [dbo].[WriteDataTarget](

[ID] [int] IDENTITY(1,1) NOT NULL,

[ItemID] [nvarchar](max) NOT NULL,

[ItemValue] [nvarchar](max) NOT NULL,

[ItemTimestamp] [datetime] NOT NULL,

[ItemQuality] [smallint] NOT NULL,

[Row] [smallint] NULL,

[Col] [smallint] NULL,

CONSTRAINT [PK_WriteDataTarget] PRIMARY KEY CLUSTERED

(

[ID] ASC

)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]

) ON [PRIMARY]

GO

PutAndGetSQLBeeValues


--USE [TestDB]

--GO

/****** Object: StoredProcedure [dbo].[PutAndGetSQLBeeValues] Script Date: 12/09/2005 08:50:44 ******/

SET ANSI_NULLS ON

GO

SET QUOTED_IDENTIFIER ON

GO

if (not exists(

select SS.Name, SO.Name from Sys.objects SO

INNER JOIN Sys.schemas SS ON SS.schema_id = SO.schema_id

where SS.Name = 'dbo' and SO.Name = 'PutAndGetSQLBeeValues' and SO.type = 'P'))

BEGIN

exec ('CREATE PROCEDURE dbo.PutAndGetSQLBeeValues AS')

END

GO

-- =============================================

-- Create date: 30/5-2009

-- Description: Sample SP for reading and writing data to/from SQL server using Apis SQL Bee

-- =============================================

ALTER PROCEDURE [dbo].[PutAndGetSQLBeeValues]

-- Add the parameters for the function here

@ByRows bit = 1,

@ModuleName nvarchar(max) = '',

@TriggerName nvarchar(max) = '',

@xmlWriteData xml = null

AS

BEGIN

-- SET NOCOUNT ON added to prevent extra result sets from interfering with SELECT statements.

SET NOCOUNT ON;

------------------------------------------------------------------

-- First handle WRITE operations:

-- GENERIC CODE:

-- The Format of the XML Document give as input param @xmlWriteData:

-- <?xml version="1.0" encoding="utf-16"?>

-- <ROOT>

-- <ItemSample ItemID="SQLBee1.MyWriteItem1" ItemValue="1.1" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" />

-- <ItemSample ItemID="SQLBee1.MyWriteItem2" ItemValue="3.14" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" />

-- <ItemSample ItemID="SQLBee1.MyWriteItem3" ItemValue="6.28" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" />

-- :

-- <ItemSample ItemID="SQLBee1.MyWriteVector1" ItemValue="1.1" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="0"/>

-- <ItemSample ItemID="SQLBee1.MyWriteVector1" ItemValue="2.1" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="1"/>

-- <ItemSample ItemID="SQLBee1.MyWriteVector1" ItemValue="3.1" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="2"/>

-- <ItemSample ItemID="SQLBee1.MyWriteVector1" ItemValue="4.1" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="3"/>

-- :

-- <ItemSample ItemID="SQLBee1.MyWriteMatrix1" ItemValue="1.1" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="0" Col="0"/>

-- <ItemSample ItemID="SQLBee1.MyWriteMatrix1" ItemValue="2.1" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="1" Col="0"/>

-- <ItemSample ItemID="SQLBee1.MyWriteMatrix1" ItemValue="1.2" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="0" Col="1"/>

-- <ItemSample ItemID="SQLBee1.MyWriteMatrix1" ItemValue="2.2" ItemTimestamp="2009-05-29 12:00:00.000" ItemQuality="192" Row="1" Col="1"/>

-- </ROOT>

--print convert(nvarchar(max), @xmlWriteData)

Declare @WriteDataTable TABLE

(

ItemID nvarchar(max),

ItemValue nvarchar(max),

--ItemType smallint,

ItemTimestamp datetime,

ItemQuality smallint,

Row smallint,

Col smallint

)

DECLARE @hXmlDoc int

Exec sp_xml_preparedocument @hXmlDoc Output, @xmlWriteData

if (@hXmlDoc is not null)

begin

INSERT INTO @WriteDataTable(ItemID, ItemValue, ItemTimestamp, ItemQuality, Row, Col)

SELECT ItemID, ItemValue, ItemTimestamp, ItemQuality, Row, Col

FROM

OPENXML(@hXmlDoc, '/ROOT/ItemSample',1)

WITH (ItemID nvarchar(max), ItemValue nvarchar(max), ItemTimestamp datetime, ItemQuality smallint, Row smallint, Col smallint)

end

Exec sp_xml_removedocument @hXmlDoc

-- Then use contents of @WriteDataTable to insert into target system

-- END OF GENERIC CODE:

-- CUSTOMER SPECIFIC CODE!

-- Sample 1: Insert into target table:

--insert into WriteDataTarget

--select * from @WriteDataTable

-- Sample 2: Call a customer specific stored procedure

--Exec CustomerStoredProc

-- convert( real, select ItemValue from @WriteDataTable where ItemID = 'Tagnavn 1'),

-- convert( real, select ItemValue from @WriteDataTable where ItemID = 'Tagnavn 2'),

-- convert( real, select ItemValue from @WriteDataTable where ItemID = 'Tagnavn 3'),

-- convert( real, select ItemValue from @WriteDataTable where ItemID = 'Tagnavn 4')

------------------------------------------------------------------

-- Then handle READ operations:

-- Insert statements for procedure here

-- Below is sample code for generating a dummy namespace and dummy values:

Declare @TS datetime

Set @TS = GetUtcDate()

if @ByRows = 1

begin

Declare @RandomTable TABLE

(

ItemName varchar(64),

ItemValue varchar(128),

ItemTimestamp datetime

)

insert into @RandomTable select 'BoolValue', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue', 'StringValue X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue2', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue2', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue2', 'StringValue2 X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue2', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue3', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue3', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue3', 'StringValue3 X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue3', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue4', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue4', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue4', 'StringValue4 X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue4', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue5', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue5', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue5', 'StringValue5 X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue5', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'StringArray', '[2] elem1-' +cast(round(100*RAND(), 0) as varchar(128)) + '; elem2-' + cast(round(100*RAND(), 0) as varchar(128)) + ';', @TS

insert into @RandomTable select 'DoubleArray', '[2] ' + cast(100*RAND() as varchar(128)) + '; ' + cast(100*RAND() as varchar(128)) + ';', @TS

select * from @RandomTable

end

else

begin

Select

cast(round(Rand(), 0) as bit) as 'ColBoolValue',

10*RAND() as 'ColFloatValue',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue',

getDate() as 'ColDateValue',

cast(round(Rand(), 0) as bit) as 'ColBoolValue2',

10*RAND() as 'ColFloatValue2',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue2',

getDate() as 'ColDateValue2',

cast(round(Rand(), 0) as bit) as 'ColBoolValue3',

10*RAND() as 'ColFloatValue3',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue3',

getDate() as 'ColDateValue3',

cast(round(Rand(), 0) as bit) as 'ColBoolValue4',

10*RAND() as 'ColFloatValue4',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue4',

getDate() as 'ColDateValue4',

cast(round(Rand(), 0) as bit) as 'ColBoolValue5',

10*RAND() as 'ColFloatValue5',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue5',

getDate() as 'ColDateValue5',

'[2] tkst-' +cast(round(100*RAND(), 0) as varchar(128)) + '; tkst-' + cast(round(100*RAND(), 0) as varchar(128)) + ';' as 'StringArray',

'[2] ' + cast(100*RAND() as varchar(128)) + '; ' + cast(100*RAND() as varchar(128)) + ';' as 'DoubleArray'

end

END

GetSQLBeeValues


USE [TestDB]

GO

/****** Object: StoredProcedure [dbo].[GetSQLBeeValues] Script Date: 12/09/2005 08:50:44 ******/

SET ANSI_NULLS ON

GO

SET QUOTED_IDENTIFIER ON

GO

-- =============================================

-- Author: <Author,,Name>

-- Create date: <Create Date,,>

-- Description: <Description,,>

-- =============================================

CREATE PROCEDURE [dbo].[GetSQLBeeValues]

-- Add the parameters for the function here

@ByRows bit = 1

--<@Param2, sysname, @p2> <Datatype_For_Param2, , int> = <Default_Value_For_Param2, , 0>

AS

BEGIN

-- SET NOCOUNT ON added to prevent extra result sets from

-- interfering with SELECT statements.

SET NOCOUNT ON;

waitfor delay '00:00:01'

-- Insert statements for procedure here

--SELECT @p1, @p

Declare @TS datetime

Set @TS = GetUtcDate()

if @ByRows = 1

begin

Declare @RandomTable TABLE

(ItemName varchar(64), ItemValue varchar(128), ItemTimestamp datetime)

insert into @RandomTable select 'BoolValue', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue', 'row X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue2', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue2', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue2', 'row X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue2', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue3', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue3', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue3', 'row X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue3', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue4', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue4', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue4', 'row X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue4', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'BoolValue5', cast(round(Rand(), 0) as varchar(128)), @TS

insert into @RandomTable select 'FloatValue5', cast(10*RAND() as varchar(128)), @TS

insert into @RandomTable select 'StringValue5', 'row X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV', @TS

insert into @RandomTable select 'DateValue5', cast(getDate() as varchar(128)), @TS

insert into @RandomTable select 'StringArray', '[2] tkst-' +cast(round(100*RAND(), 0) as varchar(128)) + '; tkst-' + cast(round(100*RAND(), 0) as varchar(128)) + ';', @TS

insert into @RandomTable select 'DoubleArray', '[2] ' + cast(100*RAND() as varchar(128)) + '; ' + cast(100*RAND() as varchar(128)) + ';', @TS

select * from @RandomTable

end

else

begin

Select

cast(round(Rand(), 0) as bit) as 'ColBoolValue',

10*RAND() as 'ColFloatValue',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue',

getDate() as 'ColDateValue',

cast(round(Rand(), 0) as bit) as 'ColBoolValue2',

10*RAND() as 'ColFloatValue2',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue2',

getDate() as 'ColDateValue2',

cast(round(Rand(), 0) as bit) as 'ColBoolValue3',

10*RAND() as 'ColFloatValue3',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue3',

getDate() as 'ColDateValue3',

cast(round(Rand(), 0) as bit) as 'ColBoolValue4',

10*RAND() as 'ColFloatValue4',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue4',

getDate() as 'ColDateValue4',

cast(round(Rand(), 0) as bit) as 'ColBoolValue5',

10*RAND() as 'ColFloatValue5',

'column X' +cast(round(100*RAND(), 0) as varchar(128)) + 'XEV' as 'ColStringValue5',

getDate() as 'ColDateValue5',

'[2] tkst-' +cast(round(100*RAND(), 0) as varchar(128)) + '; tkst-' + cast(round(100*RAND(), 0) as varchar(128)) + ';' as 'StringArray',

'[2] ' + cast(100*RAND() as varchar(128)) + '; ' + cast(100*RAND() as varchar(128)) + ';' as 'DoubleArray'

end

END

Apis StateSave

This module saves and load values of items from the namespace of Apis Hive to ascii file.

Provider: Prediktor

The StateSave module has the following item types

Properties

The StateSave module has the following properties:

Name	Description	ID	Flags
AwaysReportStateChange	Set this value to false when you only want to fire 'StateSave' or 'StateLoad' event on successfully save or load of state of one or more state file.	1800	Persisted, ExpertPage
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
SkipModuleName	When true, module part of item names are omitted when saving/loading statesave files. This property applies only when NOT using global Key attribute to lookup statesave items.	1700	Persisted
StateFileFolder	The folder in which the file(s) recides (Working folder)	1600	Persisted, Folder

See also Module Properties

Commands And Events

The StateSave module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
StatesDeleted	A state-delete operation has been performed.	Normal
StatesLoaded	A state-load operation has been performed.	Normal
StatesSaved	A state-save operation has been performed.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

A StateSave file item

The StateFileName item type has the following properties:

Name	Description	ID	Flags
CreateDirectory	Whether to attempt to create file directory if it doesn't exist.	10306	Persisted
DeleteDir	Deletes the snapfile directory after a delete of snapfile, if the directory is empty.	10320	Persisted
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
FileAccess	Decides whether the file specified in the item is in read, write, or read/write mode (Read=0, Write=1, Read/Write=2).	10300	Persisted, Enumerated
FilePrefix	A fixed value to include before the file name.	10302	Persisted
FileSuffix	A fixed value to include after the file name.	10304	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
TriggerOnChange	If true, the state file will be read/written to when the item changes.	10310	Persisted
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

The folder in which the file(s) recides (Working folder)

The StateFileFolder item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

A StateSave item

The StateSaveLoad item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

A StateSave delete item

The StateSaveDelete item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Apis TaskScheduler

This module schedules non-Apis tasks for execution.

Provider: Prediktor

The TaskScheduler module has the following item types

Task

Properties

The TaskScheduler module has the following properties:

Name	Description	ID	Flags
DefaultFolder	Default browsing folder for files to use when adding tasks.	1010	Persisted, Folder
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ShowWebBrowser	Show the window which navigates to- and prints 'HTMLprint' tasks.	1020	Persisted
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage

See also Module Properties

Commands And Events

The TaskScheduler module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Task

Properties

An executable command in the OS or a file to apply a verb to.

The Task item type has the following properties:

Name	Description	ID	Flags
CurrentState	The CURRENT_STATE of a task.	11000	Persisted, Hidden
Directory	The directory in which to execute the task.	10050	Persisted, Folder
File	The file to execute, print etc..	10005	Persisted, File
NextTime	The next execution time of the task in the local timezone.	10010	Persisted
Parameter	The parameters to send to the task (if needed).	10040	Persisted
Period	The time period between each repetition of the task.	10020	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Show	How to display the task when executed.	10060	Persisted, Enumerated
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Verb	The verb to apply to this task (normally 'print' or 'open').	10030	Persisted, Enumerated

Apis UaAcClientBee

Used to communicate to OPC UA AC servers.

Provider: Prediktor

ApisSimpleAttributeFilterItem

The UaAcClientBee module has the following item types

ApisStatusItem

ApisAlarmConditionItem

ApisAlarmMonitorItem

Properties

The UaAcClientBee module has the following properties:

Name	Description	ID	Flags
Area	The default area to link the source item in Apis Hive (default: Area).	1140	Persisted
Certificate	Specifies the certificate used when connecting to an OpcUA server (default = Apis Hive instance certificate)	1490	Persisted, Enumerated, ExpertPage
CertificateSubject	The server certificate subject	3050	InfoPage
CertificateThumbprint	The server certificate thumbprint	3060	InfoPage
CurrentKeepAliveCount		3010	InfoPage
CurrentLifetimeCount		3020	InfoPage
CurrentPriority		3040	InfoPage
CurrentPublishingEnabled		3030	InfoPage
CurrentPublishingInterval		3001	InfoPage
Enabled	The parameter is used to enable or disable the module (default:false).	1050	Persisted
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
KeepAliveCount	When this counter reaches the value calculated for the lifetime of a Subscription based on the MaxKeepAliveCount parameter, the Subscription is closed. Minimum value is 5 (default:10).	1200	Persisted
LifetimeCount	A value that contains the number of consecutive publishing timer expirations without Client activity before the Subscription is terminatedSubscription LifetimeCount. Minimum value is 5 (default:10).	1250	Persisted
MaxNotificationsPerPublish	The maximum number of notifications that the Client wishes to receive in a single Publish response. A value of zero indicates that there is no limit (default:1000)	1300	Persisted
Operation Mode	The type of mode of the Bee (default: Both_auto).	1112	Persisted, Enumerated
OperationTimeout	The OperationTimeout should be twice the minimum value for PublishingInterval*KeepAliveCount (default=20000)	1150	Persisted
Password		1450	Persisted, Hidden, Password, ExpertPage
Priority	Indicates the relative priority of the Subscription. When more than one Subscription needs to send Notifications, the Server should dequeue a Publish request to the Subscription with the highest priority number. A Client that does not require special priority settings should set this value to zero .Subscription Priority (default:0)	1350	Persisted
PublishingInterval	This interval defines the cyclic rate that the Subscription is being requested to return Notifications to the Client. This interval is expressed in milliseconds Subscription PublishingInterval. The value 0 is invalid (default:1000).	1170	Persisted
ReconnectTimout	The timeout for reconnecting server. The unit is in sec and value >5 is valid, and 0 will disabled it (default: 30).	1125	Persisted
RefreshSupported	If server support refresh function of alarms (default=true).	1145	Persisted
StorePath	The path of the certificate store (Default='LocalMachine\UA Applications')	1550	Persisted, ExpertPage
StoreType	The type of the certificate store (Default=Windows)	1500	Persisted, Enumerated, ExpertPage
SubjectName	The subject name of the certificate. Required if Certificate=Custom.	1600	Persisted, ExpertPage
TraceLogMaxSize	The max size of the trace log file. The value of '<0' means no limits and the value of '=0' means the log is turned off.When the log size if specified the size must be greater than 100KByte.Note: The unit is in KBytes and the file is located in configuration folder (Default='0')	1800	Persisted, ExpertPage
URL	OPC UA server url (http OR opc.tcp).	1100	Persisted
Username		1400	Persisted, Hidden, ExpertPage

See also Module Properties

Commands And Events

The UaAcClientBee module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

Internal items that are used to inform you about the status.

The ApisStatusItem item type has the following properties:

Name	Description	ID	Flags
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	Persisted, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

This item is used to link an OPC UA Alarm&Condition event to an item source in Apis.

The ApisAlarmConditionItem item type has the following properties:

Name	Description	ID	Flags
Area	This is the source item reference.	10025	Persisted, ExpertPage
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	Persisted, ExpertPage
OpcEventType	The source item reference.	10150	Persisted, Enumerated, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SourceName	The name of the source event object.	10050	Persisted, ExpertPage
SourceUri	The source URI of the item reference (Default:nsu=http://opcfoundation.org/UA/;i=2253).	10075	Persisted, ExpertPage
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Properties

This item is used to configure monitoring of alarms in UA.

The ApisAlarmMonitorItem item type has the following properties:

Name	Description	ID	Flags
AreaUri	The source URI of the item reference (Default:nsu=http://opcfoundation.org/UA/;i=2253).	10065	Persisted, ExpertPage
Enabled	Whether this item Is enabled or not.	10012	Persisted
EventType	The type of event to subscribe to.	10175	Persisted, Enumerated
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	Persisted, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
SimpleAttributeFilters	The SimpleAttributeOperand structure is used in the select clause to select the value to return. It returns it if an event meets the criteria specified by the where clause.	10200	Persisted, ApisLocalItem
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

This iem is used to create filters which when set up monitoring on items

The ApisSimpleAttributeFilterItem item type has the following properties:

Name	Description	ID	Flags
AttributeType	The type of attribute used in the simple operand expression. For example, string, integer, etc.	10400	Persisted, Enumerated
BrowsePath	The browse path used in the simple operand expression.	10375	Persisted, Enumerated
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
ItemHandle	The handle of the item - this is the unique ID for the item. This property is often hidden.	10001	Persisted, ExpertPage
LiteralOperand	The operand used in the filter expression.	10300	Persisted, Enumerated
LiteralValueType	The value type of the literal value. The value of the item is used to set the "LiteralValue".	10275	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
TypeDefinition	The type definition used in the "Simple operand" expression.	10350	Persisted, Enumerated
Value	The current value of the item.	2	NormalPage

Apis UaPublisherBee

This module can be used to publish information to Microsoft Eventhub. We create the messages according to the OpcUa spesification defined in "OpcUa Part 14 PubSub Release 1.04 Specification".

Also see: Stream data to broker

We only support the Json messages defined in 7.3.2 JSON Message Mapping and Json_Simplified

We use a standard communication protocol AMQP, MQTT, and Kafka to send the information to the broker. We also have the possibilities store the created messages in files, but this is to check the messages layout and content for more debugging purpose.

The property "BrokerType" define the communication to the broker. Below is a description how to configure different

File:

Select this and define a filename under an existing directory. e.g "c:/pubsub/data.json" in the property "FileName".The file will be created, and for every message sent, a new line in the file will be added. There is a maximum size of the file and then a new file will be created. Up to 10 files and then the files will be reused.

AMQP:

Then AMQP kommunication is used. Properies starting with AMQP has to be set. Se the Stream data to broker for more information.

MQTT:

The properties starting with the "MQTT." define this communication. Check the used broker to get the details. The MQTTTransport define either plain or secure communication. The value TcpServerTls represent secure communication. Then the certificate from the broker will be stored in the rejected directory for certs. (e.g. ...Config/InstanceName/pki/rejected) . If you thrust this broker and the certificate, move it to the "thrusted" directory.

Provider: Prediktor

JSON messages

UaPublisher data flow

The UaPublisherBee module has the following item types

Writer Group

Variable DataSetWriter

Status

Properties

The UaPublisherBee module has the following properties:

				</tbody>
			</table>

See also Module Properties

Commands And Events

The UaPublisherBee module has the following Commands and Events:

Events

Name	Description	ID	Flags
_DataSetWriterId_	hidden prop to book-keep the DataSetWriterIdAttribute put on dataset writer items	5010	Persisted, Hidden
_WriterGroupIdProperty_	hidden prop to book-keep the WriterGroupIdAttribute put on writer group items	5011	Persisted, Hidden
Backfill databasename	The name of the database where messages are stored when they could not be transmitted to the broker	6010	Persisted, File
Backfil databasesize	The maximun size of Backfill database in Gb. If 0 , then no limit in database-size is set.	6011	Persisted
Broker type	File: messages are witten to a file. AMQP: sending messages to Microsoft Azure Eventhub. MQTT: sending the messages to a MQTT broker.	1100	Persisted, Enumerated
DeltaTime	Dataset with newest timestamp older than now - deltatime (in seconds) will be sent to Backfill address. If 0 then no time-evaluation is done.	6007	Persisted
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ExternalItem report	A status-report for the External Item manager of this module	110	InfoPage
ExtItem full refresh	When true, the external items manager will force a full refresh initially on start/reset when reading items. I.e. items not yet initialized in their source, will also trigger an external item update. Default is true.	150	Persisted, ExpertPage
ExtItem pass-through quality	Specifies the quality of external item values that will pass through external item transfers. If external item qualities has worse quality the this mask, the external item transfer is blocked. Default is 'Any quality'.	400	Persisted, Enumerated, ExpertPage
LogLevel	Specifies the loglevel for diagnostic messages from this module.	500	Persisted, Enumerated
Message encoding	The encoding to use: Json: The message will be created according to the opcua json publishe spesification. See opcua documentation. UADP: Not in use. Json_Simplifies: A simplifier json format. See dokumentation. Json_Simplified_2: A simplifier json format with common timestamp and quality. See dokumentation.	5000	Persisted, Enumerated
Metadata directory	The directory where metadata files are created. If empty or invalid, no meta data will be created.	6000	Persisted, Folder
PublisherId	The PublisherId is a unique identifier for a Publisher within a Message Oriented Middleware	1010	ReadOnly, ReadOnlyAfterCreate
Reset counters	Resets all counters for the publisher.	6005	Persisted, Folder
Tracecverbosity	The trace verbosity when property LogLevel is set to Debug or higher. (If LogLevel < Debug, this property has no effect.	1005	Persisted, Enumerated
Transport protocol	The TransportProtocol to use (Datagram or Broker)	1050	Persisted, Hidden, Enumerated
AMQP main address	The connectionstring to Azure Event Hub. In addition the EntityPath have to be added to the WriterGroup item property AMQP main EntenityPath."	2100	Persisted
AMQP backfill address	The connectionstring to Azure Event Hub. In addition the EntityPath have to be added to the WriterGroup item property AMQP backfill EntenityPath."	2120	Persisted
AMQP communication	The communication to use.	1101	Persisted
AMQP connectiontype	Wether there are one connection per group(Multiple), one connection for all groups (Single), or a new connection for each transaction(Transient).	2122	Persisted
Filename	The Filename when BrokerType is File.	2300	Persisted, Hidden, File
MQTT main address	Address to MQTT broker	2402	Persisted
MQTT main port	MQTT broker port.	2403	Persisted
MQTT main clientid	A string that define/identify the clients session at the broker.	2404	Persisted
MQTT main user	The clients username.	2405	Persisted
MQTT main password	The clients password.	2406	Persisted
MQTT main clean session	Not relevant when sending data.	2409	Persisted
MQTT main version	Select between V3.1.1 or V5.0	2410	Persistede
MQTT main transport	Transmission protocole: TcpServer, use unencrypted communication. TcpServeTLS use encrypted communication.	2411	Persisted
MQTT main client certificate	The filename of the clients certificate when broker expect a client certificate to accept connection.	2415	Persisted
MQTT backfill address	Address to MQTT broker	2502	Persisted
MQTT backfill port	MQTT broker port.	2503	Persisted
MQTT backfill clientid	A string that define the client at the broker.	2504	Persisted
MQTT backfill user	Username this client use when connecting to MQTT broker.	2505	Persisted
MQTT backfill password	Username this client use when connecting to MQTT broker.	2506	Persisted
MQTT backfill clean session	Not relevant when sending data.	2509	Persisted
MQTT backfill version	Select between V3.1.1 or V5.0	2510	Persistede
MQTT backfill transport	Transmission protocole: "TcpServer", use unencrypted communication. "TcpServeTLS" use encrypted communication.	2511	Persisted
MQTT backfill client certificate	The filename of the clients certificate when broker expect a client certificate to accept connection.	2515	Persisted

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified by user. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

JSON messages

We support two main type of messages: Json defined by OpcUa and Json_Spesial defined by Prediktor. At present time we do not support the binary message UADP..

Json_Spesial Message

The Json_Simplifies is simple and fixed Json format consist of one object with element named "data" that holds an array of VQT objects. In addition the object can be expanded by the user with a fixed string. The Italicized part is here an example of a user defined extension. This can be added in UserExtra parameter (id : 11045) for a Writer Group Item. This has to expand the object with a valid Json format.

When using this format the UaPublisherBee will autocratically split or concatenate DataSet to maximize the message size without being too large. Because of this the user do not need to tune the number of values to control the message-size.

Json_Spesial Example


{

"data": [

_"schema": "apis/schemas/vqt.json","dataType":"raw","plant":"myPlant",_

{"tag": "test2.Worker.mySignal1","time": "2019-02-09T11:44:34.8905431Z","value": 145.126114,"status": 0},

{tag": "test2.Worker.mySignal2","time": "2019-02-09T11:44:34.8895786Z","value": 126.807716,"status": 0},

. . .

]

}

Json Message defined by OPC Unified Architecture.

This format is defined in the "OPC Unified Architecture Specification Part 14: PubSub Release 1.04", and the user should look at chapter 7.2.3 Json Message Mapping where this is described in details. Below is an example where we have a WriterGroup with property JsonNetworkMessageContentMask (id:11100 ) set to NetWorkMessageHeader=true, DataSetMessageHeader=true, and PublisherId=true. The VariableDataSet Writer property DataSetFieldContent (id:12060) set to StatusCode=true, and SourceTimeStamp=true. To test how the JSON change look in documentation, or try it out by change the parameters anf write the messages to a file.

Json Message Example


{

"MessageId": "5aaf34fe-51d8-4ddc-a294-3e8d3db3b5ab",

"MessageType": "ua-data",

"PublisherId": "UaPublisherBee1",

"Message": [

{

"DataSetWriterId": "2",

"PayLoad": {

"test2.Worker.Signal1": {

"Value": 0.911874,

"SourceTimestamp": "2019-02-13T15:03:33.1637587Z"

},

"test2.Worker.Signal2": {

"Value": 426.613861,

"SourceTimestamp": "2019-02-13T15:03:33.1637587Z"

},

"test2.Worker.Signal3": {

"Value": 113.692924,

"SourceTimestamp": "2019-02-13T15:03:33.1637587Z"

}

}

},

{

"DataSetWriterId": "2",

"PayLoad": {

"test2.Worker.Signal1": {

"Value": 0.889142,

"SourceTimestamp": "2019-02-13T15:03:34.163777Z"

},

"test2.Worker.Signal2": {

"Value": 423.00354,

"SourceTimestamp": "2019-02-13T15:03:34.163777Z"

},

"test2.Worker.Signal3": {

"Value": 113.268066,

"SourceTimestamp": "2019-02-13T15:03:34.163777Z"

}

}

}

]

}

UaPublisher Data Flow

Below is a picure visualize the internal data flow in the ApisUaPublisherBee.

The OpcUa bee creates new DataSet every time new values from the OpcUa-server arrive. The DataSet is transfered to UaPublisher and added to the DataQue. Each writer in UaPublisher has it own que. The QueSize is defined by the property MaxDataSetMessageBufferSize (id: 121100) and should be 2-3 times the expected size in a PublishInterval (id:11020). By setting the DiagnosticLevel for the Variabel DataSetWrter to debug you get a status DataSetQueSize showing the current number of DataSet in the DataQue.

On PublishInterval (id:11020) the WriterGroup empty all DataQue convert the DataSet according to specification and store the messages in the MessageQue. The maximum size of MessageQue is defined by the paramete NetworkMessageQueSize (id:11025). It is one que for each WriterGroup. If the MessageQue is dfull, then the message is written to the Database (DB).

There is one thread for each MessageQue that sends the messages to the specified destination. If a sending fails, the message will be resent once, and if that one also fail, the message is stored in the DB. When e.g. the network to an Eventhub is down all messages will end up in the DB.

Messages in DB are sent to the Backfill eventhub. Messages are deleted from DB when messages are successfully written to Eventhub.

If the OpcUaBee that represent the DataSet are configured with catchup, all DataSet are converted to JsonMessages and stored directly in DB. If there are added sizelimits to the DB, the UaPublisher will wait until DB er ready for more. In this case no DataSet will be lost.

APIS UaPublisherBee Item Types

Topics Covered:

Writer Group Properties

Items representing a Publisher WriterGroup.

The Writer Group item type has the following properties:

Name	Description	ID	Flags
DataSetOrdering	The DataSetOrdering defines the ordering of the DataSetMessages in the NetworkMessages. The default value is Undefined.	11210	Persisted, Hidden, Enumerated
Diagnostics level	Define the level of diagnostics to be created.	10150	Persisted, Enumerated
Enabled	Whether the item is enabled or not.	10100	Persisted
GroupVersion	The parameter GroupVersion with DataType VersionTime defines the expected value in the field GroupVersion in the header of the NetworkMessage. The default value 0 is defined as null value, and means this parameter shall be ignored.	11200	Persisted, Hidden
JsonNetworkMessageContentMask	The parameter NetworkMessageContentMask defines the optional header fields to be included in the NetworkMessages produced by the WriterGroup. The DataType for the JSON NetworkMessage mapping is JsonNetworkMessageContentMask. (See doc OpcUa Part 14 1.0.4 chapter 6.3.2.2.1)	11100	Persisted, EnumeratedFlags
KeepAliveTime	The KeepAliveTime with DataType Duration defines the time in milliseconds until the Publisher sends a keep alive DataSetMessage in the case where no DataSetMessage was sent in this period by a DataSetWriter. The minimum value shall equal the PublishingInterval.	11030	Persisted
Max NetworkMessage queuesize	Maxium number of NetworkMessages in the internal queue.	11025	Persisted
MaxNetworkMessageSize	The maximum size in bytes for networkmessages created by the Writergroup. It refers to the size of the complete message including padding and signature without any additional headers added by the transport protocol mapping. If the size of a message exceeds the "Max message size", the behaviour depends on the message mapping./td>	11010	Persisted
MessageRepeatCount	The MessageRepeatCount with DataType Byte defines how many times every NetworkMessage is repeated. The default value is 0 and disables the repeating.	11060	Persisted, Hidden
MessageRepeatDelay	The MessageRepeatDelay with DataType Duration defines the time between NetworkMessage repeats in milliseconds. The parameter shall be ignored if the parameter MessageRepeatCount is set to 0.	11065	Persisted, Hidden
AMQP partitionkey	The key used to generate a hash code which decides the partition the message will be sent to when using AMQP.	11015	Persisted
Priority	The Priority with DataType Byte defines the relative priority of the WriterGroup to all other WriterGroups across all PubSubConnections of the Publisher. If more than one WriterGroup needs to be processed, the priority number defines the order of processing. The highest priority is processed first. The lowest priority is 0 and the highest is 255.	11040	Persisted, Hidden
PublishingOffset	The SamplingOffset with the DataType Duration defines the time in milliseconds for the offset of creating the NetworkMessage in the PublishingInterval cycle. Any negative value indicates that the optional parameter is not configured. In this case the Publisher shall calculate the time before the PublishingOffset that is necessary to create the NetworkMessage in time for sending at the PublishingOffset.	11240	Persisted, Hidden
PublishInterval	The PublishingInterval with the defines the interval in milliseconds for publishing NetworkMessages and the embedded DataSetMessages created by the related DataSetWriters	11020	Persisted
Quality	Item quality	3	ReadOnly
AMQP main EntityPath	A string parameter specifies the EntityPath in the broker.	11053	Persisted
AMQP backfill EntityPath	A string parameter specifies the EntityPath in the broker.	11054	Persisted
MQTT main topic	The topic string parameter specifies the queue this WriterGroup send messages to.	11050	Persisted
MQTT backfill topic	The topic string parameter specifies the queue this WriterGroup send messages to.	11051	Persisted
RequestedDeliveryGuarantee	The RequestedDeliveryGuarantee parameter with DataType BrokerTransportQualityOfService specifies the delivery guarantees that shall apply to all NetworkMessages published by the WriterGroup unless otherwise specified on the DataSetWriter transport settings.	11055	Persisted, Enumerated
Rights	Item access rights	5	ReadOnly
SamplingOffset	TThe SamplingOffset with the DataType Duration defines the time in milliseconds for the offset of creating the NetworkMessage in the PublishingInterval cycle. Any negative value indicates that the optional parameter is not configured. In this case the Publisher shall calculate the time before the PublishingOffset that is necessary to create the NetworkMessage in time for sending at the PublishingOffset.	11230	Persisted, Hidden
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
UadpNetworkMessageContentMask	The parameter NetworkMessageContentMask defines the optional header fields to be included in the NetworkMessages produced by the WriterGroup. The DataType for the UADP NetworkMessage mapping is UadpNetworkMessageContentMask.	11220	Persisted, Hidden, EnumeratedFlags
UserExtra	UserExtra is a static Json-part that is added to the Json_spesial message	11045	Persisted
Value	Item value	2	ReadOnly
WriterGroupId	The WriterGroupId with DataType UInt16 is an identifier for the WriterGroup and shall be unique across all WriterGroups for a PublisherId. All values, except for 0, are valid. The value 0 is defined as null value.	11000	Persisted, ReadOnly

Variable DataSet Writer Properties

Items representing a variable DataSet writer.

The Variable DataSetWriter item type has the following properties:

				</tbody>
			</table>

Status Properties

This item is used to expose internal status information

The Status item type has the following properties:

Name	Description	ID	Flags
ConfiguredSize	The parameter ConfiguredSize with the DataType UInt16 defines the fixed size in bytes a DataSetMessage uses inside a NetworkMessage. The default value is 0 and it indicates a dynamic length. If a DataSetMessage would be smaller in size (e.g.because of the current values that are encoded) the DataSetMessage is padded with bytes with value zero.In case it would be larger, the Publisher shall set bit 0 of the DataSetFlags1 to false to indicate that the DataSetMessage is not valid.	12510	Persisted, Hidden
DataSetFieldContentMask	A DataSet field consists of a value and related metadata. In most cases the value comes with status and timestamp information. Set flags to decide what to include in addition to the value in the DataSetMessage.(See OpcUa Part 14 1.04 chapter 7.2.3.3)	12060	Persisted, EnumeratedFlags
DataSet connected data	The name of the corresponding PublishedDataSet. I.e. the name of an apis module in this instance, that implements the IApisPublishedDataSet interface, and that will provide the dataset to publish.	12100	Persisted, DynamicEnumeration
DataSetWriterId	The DataSetWriterId with defines the unique ID of the DataSetWriter for a PublishedDataSet. It is used to select DataSetMessages for a PublishedDataSet on the Subscriber side. It shall be unique across all DataSetWriters for a PublisherId. All values, except for 0, are valid DataSetWriterIds. The value 0 is defined as null value.	12050	Persisted, ReadOnly
Diagnostics level	Define the level of diagnostics to be created.	10150	Persisted, Enumerated
Enabled	Whether the item is enabled or not.	10100	Persisted
JsonDataSetMessageContentMask	The DataSetMessageContentMask defines the flags for the content of the DataSetMessage header.	12400	Persisted, EnumeratedFlags
KeyFrameCount	The KeyFrameCount with DataType UInt32 is the multiplier of the PublishingInterval that defines the maximum number of times the PublishingInterval expires before a key frame message with values for all published Variables is sent.The delta frame DataSetMessages contains just the changed values.If no changes exist, the delta frame DataSetMessage shall not be sent.If the KeyFrameCount is set to 1, every message contains a key frame.	12070	Persisted
MajorVersion	The MajorVersion reflects the time of the last major change of the DataSet content.	18050	ReadOnly, InfoPage
DataSet message buffer size	The maximum number of DataSet that can be buffered internaly	12110	Persisted
MinorVersion	The MinorVersion reflects the time of the last change of the DataSet content.	18051	ReadOnly, InfoPage
Quality	Item quality	3	ReadOnly
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
UadpDataSetMessageContentMask	The UadpDataSetMessageContentMask defines the flags for the content of the DataSetMessage header, when using UADP message mapping.	12500	Persisted, Hidden, EnumeratedFlags
Value	Item value	2	ReadOnly
WriterGroup itemname	The WriterGroupItem for this dataset writer.	10200	Persisted, APISLocalItem, DynamicEnumeration
Value identifier	The names to use in messages to identify values. SourceNodeId: selecr opcu ua nodeid to the value. ItemName: use the APIS itemname, SourceNodeId_Regex: Use the opcus nodid, but in addition manipulate this with regex. ItemName_Regex: Use APIS itemname and manipulate it with regex.	12205	Persisted
Regex source	If the name shall use regex: This parameter holds the string to search for.	12210	Persisted
Regex replace	If the name shall use regex: This parameter holds the replace string.	12220	Persisted

Name	Description	ID	Flags
DiagnosticsClassification		14020	Persisted, ReadOnly, Enumerated
DiagnosticsLevel		14010	Persisted, ReadOnly, Enumerated
Quality	Item quality	3	ReadOnly
Reset	Resets this status item	14000	Persisted
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	ReadOnly

Module Status	Description	DiagnisticsLevel	DiagnosticClassification
DBMessageCount	The number of messages currently stored in the database	Basic	Information
MainPublisher.SentMessages	Number of sent messages	Basic	Information
BackfillPublisher.SentMessages	Number of messages sent to backfill eventhub	Basic	Information
LostMessages	Number of lost mesages	Basic	Error
MainPublisher.ResolvedAddress	status of resolving the address to the eventhub	Basic	Information
BackfillPublisher.ResolvedAddress	status of resolving the address to the backfill eventhub	Basic	Information

Writer Group Status	Description	DiagnisticsLevel	DiagnosticClassification
ConversionError	number of error when converting data to JSON	basic	Error
PublisherExceedsTimer	used time in sendigprosess	Advanced	Information
BackfillPublisherExeedsTimer	used time in sendingprosess	Advanced	Information
SentNetworkMessages	number of sent messages	Info	Information
FailedTransmissions	number of failed transmissions	Info	Information
RemovedNetworkMessagtes	removed messages	Info	Information
SendMessageQueSize	Number currently in the messageque	Debug	Information
SendThread	current status of the messagethread	Debug	Information

Variable DataSet Writer Status	Description	DiagnisticsLevel	DiagnosticClassification
RemovedDataSetMessages	Number of removed datasetmessages	Info	Information
KeyFrameCount	Number KeyFramest sent	Info	Information
DataSetsReceived	Number of dataset veceived	Info	Information
MessageSequenceNumber	the current MessageSequenceNumber	Info	Information
DataSetQueSize	The current size of the Dataset que	debug	Information

Apis VectorFunctionBee

General vector function bee.

Provider: Prediktor

Child item - DoubleVectorItem

The VectorFunctionBee module has the following item types

Child item - BooleanItem

Child item - TriggerItem

Child item - IntegerItem

Child item - DoubleItem

Child item - StringItem

FunctionItem

AggregatedItem

Properties

The VectorFunctionBee module has the following properties:

Name	Description	ID	Flags
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted

See also Module Properties

Commands And Events

The VectorFunctionBee module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

Boolean child item type.

The Child item - BooleanItem item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
MandatoryAttribute	An attribute that determines if the child item is mandatory or not.	10003	Persisted, ReadOnly
ParentItem	The parent item name of this item.	5502	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Trigger child item type.

The Child item - TriggerItem item type has the following properties:

Name	Description	ID	Flags
MandatoryAttribute	An attribute that determines if the child item is mandatory or not.	10003	Persisted, ReadOnly
ParentItem	The parent item name of this item.	5502	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Integer (Int32) child item type.

The Child item - IntegerItem item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
MandatoryAttribute	An attribute that determines if the child item is mandatory or not.	10003	Persisted, ReadOnly
ParentItem	The parent item name of this item.	5502	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Double child item type.

The Child item - DoubleItem item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
MandatoryAttribute	An attribute that determines if the child item is mandatory or not.	10003	Persisted, ReadOnly
ParentItem	The parent item name of this item.	5502	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

String child item type.

The Child item - StringItem item type has the following properties:

Name	Description	ID	Flags
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
MandatoryAttribute	An attribute that determines if the child item is mandatory or not.	10003	Persisted, ReadOnly
ParentItem	The parent item name of this item.	5502	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Double array child item type.

The Child item - DoubleVectorItem item type has the following properties:

Name	Description	ID	Flags
ExtItemOverrideMethod	This attribute decides what method to use when assigning a value from an external item.	5999	Persisted, Enumerated, BitMask
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
MandatoryAttribute	An attribute that determines if the child item is mandatory or not.	10003	Persisted, ReadOnly
ParentItem	The parent item name of this item.	5502	Persisted, ApisLocalItem, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Function item.

The FunctionItem item type has the following properties:

Name	Description	ID	Flags
FunctionDefinitionAttribute	The function definition implemented by a function item.	10001	Persisted, Enumerated, ExtraInfo
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

An aggregated item to perform functions on. Use external input.

The AggregatedItem item type has the following properties:

Name	Description	ID	Flags
FunctionListAttribute	A semi-colon ';' separated list of function instances to use in calculations.	10002	Persisted
InitValue	The initial value, set during initialisation of the Apis Module. In other words, when Apis Hive is restarted, this is the value the item will be set to.	5002	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
TriggerAwareAttribute	If set to true, this item's value will be recalculated when one of its function item's trigger items has been triggered.	10004	Persisted
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Apis WITS client

This module sends / receives data on WITS level 0. For further information about WITS 0, see: W.I.T.S. Wellsite Information Transfer Specification

Provider: Prediktor

The WITS module has the following item types

WITSItem

Command Item

State Item

More information

Characteristics of the ApisWITS Client module:

Implements WITS 0 client.
Supports both passive and active and passive communication.
Supports Read and Write.
Supports, serial and TCP/IP communication (TCP and UDP)
Supports automatic tag generation of predefined WITS records. For more information on predefined WITS records, refer to W.I.T.S. Wellsite Information Transfer Specification

Further, as an integrated module in the Apis Hive, the following optional features are available:

High performance data logging to the Apis Honeystore historian, with OPC Historical Data Access server interface

Properties

The WITS module has the following properties:

Name	Description	ID	Flags
Active	server mode, some WITS servers (Pason i.a.) only send data when receiving request message, Set this property to true to activate request message, see property Request Message."	1050	Persisted, ExpertPage
Autogenerate	Automatic Tag Database Generation of predefined WITS records, based on telegram from server. For more information on predefined WITS records, refer to W.I.T.S. Wellsite Information Transfer Specification	1057	Persisted, Enumerated, ExpertPage
BaudRate receive	Baud rate for serial communication, valid only when Comm.type Serial is selected	1210	Persisted, Enumerated, ExpertPage
COM port receive	The COM port to use, valid only when Comm.type Serial is selected	1200	Persisted, Enumerated
Comm. type receive	Communication method, Serial or Winsock	1110	Persisted, Enumerated
DataBits receive	Number of bits in the bytes transmitted and received, valid only when Comm.type Serial is selected	1230	Persisted, Enumerated, ExpertPage
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
FlowControl receive	Flow control for serial communication, valid only when Comm.type is Serial	1250	Persisted, Enumerated, ExpertPage
ForceUpdate	Update time stamp even though value has not changed (Default=true).	1000	Persisted, ExpertPage
IP address receive	Ip Address of WITS server, valid only when Comm. type Winsock is selected	1310	Persisted, Computer
Last telegram	Last raw telegram received from WITS server	30000	ReadOnly, PerformancePage
Parity receive	Parity scheme for the serial communication, valid only when Comm.type Serial is selected	1220	Persisted, Enumerated, ExpertPage
Poll Interval	Set this to bigger than 0.01 for a timer based polling (seconds)	1055	Persisted
Port receive	The TCP/UDP port of WITS server.Valid only when Comm. type Winsock is selected	1311	Persisted
Port send	The TCP/UDP port of WITS server	1513	Persisted, Hidden
Protocol	Protocol TCP or UDP Valid only when Comm. type Winsock is selected	1312	Persisted, Enumerated
Request Message	This parameter specifies the message portion of the frame that the driver will send to request solicited data. Valid only when server mode is Active	1051	Persisted, Enumerated, ExpertPage
StopBits receive	Number of stop bits to be used, valid only when Comm.type Serial is selected	1240	Persisted, Enumerated, ExpertPage
Timeout	Time-out interval, in seconds when timerbased.	1120	Persisted
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
TracefileMaxSize	The max size of the trace file before the file is truncated in bytes. Default is 50 MB => 50 * 1024 * 1024	15000	Persisted, ExpertPage
TraceToFile	This is used to trace detail information about the incomming data over the link	15010	Persisted, File, ExpertPage

See also Module Properties

Commands And Events

The WITS module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
ReceiveDone	An event signalled when a receive from WITS serever is successful.	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
StartReceive	Initiate a receive of data from WITS server.	Asynchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Properties

A WITS item, built from raw data or measurement elements

The WITSItem item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Direction	Direction of data. Input (false) or Output (true).	5040	Persisted
Field	The field of the item.	5037	Persisted
Offset	The linear transformation addend to use when calculating and item value. (Value = RawValue * Scale + Offset)	5006	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Record	The record of the item.	5036	Persisted
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Scale	The linear transformation multiplier to use when calculating the item value. (Value = RawValue * Scale + Offset)	5005	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Unit	EU units - this is the unit this item value uses. For example: centimetres, kilograms, kilowatts, etc.	100	Persisted
Value	The current value of the item.	2	ReadOnly
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10010	Persisted, Enumerated

Properties

A command for controlling module

The Command Item item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Properties

Item telling if module is connected to the WITS server; true: is connected, false: is disconnected

The State Item item type has the following properties:

Name	Description	ID	Flags
Description	A description of what this item does. This is free text, so you can write anything you like here.	101	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Apis Worker

This module generates signals of different types.

Provider: Prediktor

The Worker module has the following item types

Properties

The Worker module has the following properties:

Name	Description	ID	Flags
ExchangeRate	The exchange rate in milliseconds for the 'ExternalItems' timer event. By default, used for updating external items values.	100	Persisted
ExtItem pass-through quality	Specifies the quality of external item values that will pass through external item transfers. Default is 'Good and Uncertain qualities'	400	Persisted, Enumerated, ExpertPage
ExtItemCalculationSequence	Decides whether data validation or data transfer will be performed first in the external item manager.	300	Persisted, Enumerated, ExpertPage
PersistValToInitVal	Choose strategy for copying and persisting current value to the InitValue. Tip: Consider using an InitVQTFromHoneystore attribute instead, for better performance.	1650	Persisted, Enumerated
RandomizeItemAttribs	Give item attributtes such as signal amplitude and period random initial values when items are added.	1500	Persisted
TimeReferenceItem	An item who's value will be used as the time reference for this module instead of the system time, when timestamping items.	200	Persisted, ApisItem, ExpertPage
UpdateInitvalsOnSave	If True, items having initial values will have them updated from their current values when configuration is saved.	1600	Persisted, ReadOnly, Hidden, ExpertPage

Informational properties:

Name	Description	ID	Flags
ExternalItem report	A status-report for the External Item manager of this module	110	InfoPage

See also Module Properties

Commands And Events

The Worker module has the following Commands and Events:

Events

Name	Description	Event Type
ExternalItems	Timer event for handling of external items. By default, the command 'HandleExternalItems' is connected to this event, but that can be modified. The timer resolution is specified by the 'ExchangeRate' property.	Timer
ExternalItemsHandled_DataPush	This event is fired after it has executed a HandleExternalItems_DataPush command. The data push package part of this ExternalItemsHandled_DataPush event, are all the resulting VQTs (Function items, ordinary external item transfer, etc.) from the HandleExternalItems_DataPush command. On this ExternalItemsHandled_DataPush event, one can hook any _DataPush command(s) (Log; Scan; UaServerUpdateMonitorItems; HandleExternalItems), to chain a path of execution with data transferred alongside. APIS data transfer mechanism; Data Push	Timer
TrigEvt1	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt1'	Normal
TrigEvt2	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt2'	Normal
TrigEvt3	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt3'	Normal
TrigEvt4	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt4'	Normal
TrigEvt5	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt5'	Normal
TrigEvt6	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt6'	Normal
TrigEvt7	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt7'	Normal
TrigEvt8	Event triggered by a TrigEvtBrokerCmd item with 'EventBrokerEntry=TrigEvt8'	Normal

Commands

Name	Description	Command Type
HandleExternalItems	Command for reading external items. When fired, the module will read all its external items, and update/notify the ones that has changed.	Synchronous
HandleExternalItems_DataPush	This command ensure that all samples for all items and samples in the data push package are applied/used in the external item manager, including in services as Data Validation, Ext Items Transfer Control, etc. See also: APIS data transfer mechanism; Data Push	Synchronous
UpdateItemTimestamp	Command used for updating the value of the item specified in the 'TimeReferenceItem' property, when configured.	Synchronous

See also Commands And Events

Item Types

Item type: Signal

A function, periodic in time

The Signal item type has the following properties:

Name	Description	ID	Flags
Amplitude	This is the amplitude of the signal.	10001	Persisted
Bias	A constant value added to the signal.	10005	Persisted
Overridden quality	The actual quality the item value should have, used for simulating qualities.	10100	Persisted, Enumerated
Period	The time period between each repetition of the task.	10004	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly
Waveform	The waveform of the signal.	10002	Persisted, Enumerated

Item type: Time

The current time as a DATE type

The Time item type has the following properties:

Name	Description	ID	Flags
Local time	When true, the time is converted to a local time, when false the time is UTC time.	10022	Persisted
MinTimeBeforeUpdate	The minimum time that can elapse (in seconds), before the item value will be updated.	10009	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Variable

User defined item, which can be written and read.

The Variable item type has the following properties:

Name	Description	ID	Flags
AutoResetTimeout	The timeout for automatically resetting the value. The timeout is in milliseconds. To disable the autoreset, type 0.	10020	Persisted, ExpertPage
AutoResetValue	The value to set when the AutoResetTimeout occurs.	10019	Persisted, ExpertPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10010	Persisted, Enumerated

Item type: VariableVector

Vector of variables, which can be written and read.

The VariableVector item type has the following properties:

Name	Description	ID	Flags
Dimension	The dimension of a vector item (number or elements).	5007	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10025	Persisted, Enumerated

Item type: BitSelect

A boolean item whose value is set from a bit-position of an external item

The BitSelect item type has the following properties:

Name	Description	ID	Flags
BitPosition	The start bit position of the object. This property is only applicable for BOOL and BITSTRING objects,	10011	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Item type: String formatter

An item which formats a string based on external item(s) and a format-control string

The String formatter item type has the following properties:

Name	Description	ID	Flags
DecimalPoint	What character to use as a decimal-point, For example, in English-speaking countries it's period '.' but in many European countries, it's comma ','	10017	Persisted, Enumerated
Format as UTC	When true, time formatted strings are treated as in UTC. If this value is false, they are treated as being in the local timezone.	10018	Persisted
FormatAsVector	Format the external item as a vector, using the prefix, suffix, and separator.	10013	Persisted
FormatControlString	The format-control string used when formatting the string value of this item, based on its external item(s).	10012	Persisted
FormatVector separator	The separator when formatting the string as a vector.	10016	Persisted
FormatVectorPrefix	The prefix when formatting the string as a vector.	10014	Persisted
FormatVectorSuffix	The suffix when formatting the string as a vector, or the character used to trim the result string.	10015	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
TrimCharacter	This property is the value used to trim the string.	10027	Persisted
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Format Control String

The format-control string used when formatting the string value of this item, based on its external item(s)

A format specification, which consists of optional and required fields, has the following form:

%[flags] [width] [.precision] [{h | l | ll | I | I32 | I64}]type

Each field of the format specification is a single character or a number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign is followed by a character that has no meaning as a format field, the character is copied to stdout. For example, to print a percent-sign character, use %%.

The optional fields, which appear before the type character, control other aspects of the formatting, as follows:

type

Required character that determines whether the associated argument is interpreted as a character, a string, or a number (see the "Type Field Characters" table in Type Field Characters).

flags

Optional character or characters that control justification of output and printing of signs, blanks, decimal points, and octal and hexadecimal prefixes (see the "Flag Characters" table in Flag Directives). More than one flag can appear in a format specification.

width

Optional number that specifies the minimum number of characters output (see Width Specification).

precision

Optional number that specifies the maximum number of characters printed for all or part of the output field, or the minimum number of digits printed for integer values (see the "How Precision Values Affect Type" table in Precision Specification).

h| l| ll| I| I32| I64

Optional prefixes to type-that specify the size of argument (see the "Size Prefixes" table in Size and Distance Specification).

Flag Characters

Flag	Meaning	Default
	Left align the result within the given field width.	Right align.
+	Prefix the output value with a sign (+ or ) if the output value is of a signed type.	Sign appears only for negative signed values ().
0	If width is prefixed with 0, zeros are added until the minimum width is reached. If 0 and appear, the 0 is ignored. If 0 is specified with an integer format (i, u, x, X, o, d) and a precision specification is also present (for example, %04.d), the 0 is ignored.	No padding.
blank (' )	Prefix the output value with a blank if the output value is signed and positive; the blank is ignored if both the blank and + flags appear.	No blank appears.
#	When used with the o, x, or X format, the # flag prefixes any nonzero output value with 0, 0x, or 0X, respectively.	No blank appears.
	When used with the e, E, f, a or A format, the # flag forces the output value to contain a decimal point in all cases.	Decimal point appears only if digits follow it.
	When used with the g or G format, the # flag forces the output value to contain a decimal point in all cases and prevents the truncation of trailing zeros. Ignored when used with c, d, i, u, or s.	Decimal point appears only if digits follow it. Trailing zeros are truncated.

Type Field Character

Character	Type	Output format
c	int or wint_t	When used with printf functions, specifies a single-byte character; when used with wprintf functions, specifies a wide character
C	int or wint_t	When used with printf functions, specifies a wide character; when used with wprintf functions, specifies a single-byte character.
d	int	Signed decimal integer.
i	int	Signed decimal integer.
o	int	Signed octal integer.
u	int	Unsigned decimal integer.
x	int	Unsigned hexadecimal integer, using "abcdef."
X	int	Unsigned hexadecimal integer, using "ABCDEF."
e	double	Signed value having the form [ ]d.dddd e [sign]dd[d] where d is a single decimal digit, dddd is one or more decimal digits, dd[d] is two or three decimal digits depending on the output format and size of the exponent, and sign is + or .
E	double	Identical to the e format except that E rather than e introduces the exponent.
f	double	Signed value having the form [ ]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision.
g	double	Signed value printed in f or e format, whichever is more compact for the given value and precision. The e format is used only when the exponent of the value is less than 4 or greater than or equal to the precision argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.
G	double	Identical to the g format, except that E, rather than e, introduces the exponent (where appropriate).
a	double	Signed hexadecimal double precision floating point value having the form []0xh.hhhh p±dd, where h.hhhh are the hex digits (using lower case letters) of the mantissa, and dd are one or more digits for the exponent. The precision specifies the number of digits after the point.
A	double	Signed hexadecimal double precision floating point value having the form []0Xh.hhhh P±dd, where h.hhhh are the hex digits (using capital letters) of the mantissa, and dd are one or more digits for the exponent. The precision specifies the number of digits after the point.
n	Pointer to integer	Number of characters successfully written so far to the stream or buffer; this value is stored in the integer whose address is given as the argument. See Security Note below.
p	Pointer to void	Prints the address of the argument in hexadecimal digits.
s	String	When used with printf functions, specifies a single-bytecharacter string; when used with wprintf functions, specifies a wide-character string. Characters are printed up to the first null character or until the precision value is reached.
S	String	When used with printf functions, specifies a wide-character string; when used with wprintf functions, specifies a single-bytecharacter string. Characters are printed up to the first null character or until the precision value is reached.
t T	Time	Used to format Time object, terminate with &t or &T. see Time format %T%Y.%#m.%d %H:%M:%S&T output: 2006.9.06 18:02:21

How Precision Values Affect Type

Type	Meaning	Default
a, A	The precision specifies the number of digits after the point.	Default precision is 6. If precision is 0, no point is printed unless the # flag is used.
c, C	The precision has no effect.	Character is printed.
d, i, u, o, x, X	The precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision.	Default precision is 1.
e, E	The precision specifies the number of digits to be printed after the decimal point. The last printed digit is rounded.	Default precision is 6; if precision is 0 or the period (.) appears without a number following it, no decimal point is printed.
f	The precision value specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits.	Default precision is 6; if precision is 0, or if the period (.) appears without a number following it, no decimal point is printed.
g, G	The precision specifies the maximum number of significant digits printed.	Six significant digits are printed, with any trailing zeros truncated.
s, S	The precision specifies the maximum number of characters to be printed. Characters in excess of precision are not printed.	Characters are printed until a null character is encountered.

Width SpecificationCharacters

The second optional field of the format specification is the width specification. The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added to the left or the right of the values depending on whether the flag (for left alignment) is specified until the minimum width is reached. If width is prefixed with 0, zeros are added until the minimum width is reached (not useful for left-aligned numbers).

The width specification never causes a value to be truncated. If the number of characters in the output value is greater than the specified width, or if width is not given, all characters of the value are printed (subject to the precision specification).

If the width specification is an asterisk (*), an int argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. A nonexistent or small field width does not cause the truncation of a field; if the result of a conversion is wider than the field width, the field expands to contain the conversion result.

Size Prefixes for printf and wprintf Fomat-Type Specifiers

To specify	Use prefix	With type specifier
long int	l (lowercase L)	d, i, o, x, or X
long unsigned int	l	o, u, x, or X
long long	ll	d, i, o, x, or X
short int	h	d, i, o, x, or X
short unsigned int	h	o, u, x, or X
__int32	I32	d, i, o, x, or X
unsigned __int32	I32	o, u, x, or X
__int64	I64	d, i, o, x, or X
unsigned __int64	I64	o, u, x, or X
ptrdiff_t (that is, __int32 on 32-bit platforms, __int64 on 64-bit platforms)	I	d, i, o, x, or X
size_t (that is, unsigned __int32 on 32-bit platforms, unsigned __int64 on 64-bit platforms)	I	o, u, x, or X
long double	l or L	f
Single-byte character with printf functions	h	c or C
Single-byte character with wprintf functions	h	c or C
Wide character with printf functions	l	c or C
Wide character with wprintf functions	l	c or C
Single-byte character string with printf functions	h	c or C
Single-byte character string with wprintf functions	h	c or C
Wide-character string with printf functions	l	c or C
Wide-character string with wprintf functions	l	c or C
Wide character	w	c
Wide-character string	w	s

Thus to print single-byte or wide-characters, use format specifiers as follows.

To print charachter as	Use function	With format specifier
single byte	printf	c, hc, or hC
single byte	wprintf	C, hc, or hC
wide	wprintf	c, lc, lC, or wc
wide	printf	C, lc, lC, or wc

Time format arguments

The format argument consists of one or more codes; as in printf, the formatting codes are preceded by a percent sign (%). Characters that do not begin with % are copied unchanged

The formatting codes for are listed below:

Format code	Meaning
%a	Abbreviated weekday name
%A	Full weekday name
%b	Abbreviated month name
%B	Full month name
%c	Date and time representation appropriate for locale
%d	Day of month as decimal number (01 31)
%H	Hour in 24-hour format (00 23)
%I	Hour in 12-hour format (01 12)
%j	Day of year as decimal number (001 366)
%m	Month as decimal number (01 12)
%M	Minute as decimal number (00 59)
%p	Current locale's A.M./P.M. indicator for 12-hour clock
%S	Second as decimal number (00 59)
%U	Week of year as decimal number, with Sunday as first day of week (00 53)
%w	Weekday as decimal number (0 6; Sunday is 0)
%W	Week of year as decimal number, with Monday as first day of week (00 53)
%x	Date representation for current locale
%X	Time representation for current locale
%y	Year without century, as decimal number (00 99)
%Y	Year with century, as decimal number
%z, %Z	Either the time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown
%%	Percent sign

As in the printf function, the # flag may prefix any formatting code. In that case, the meaning of the format code is changed as follows.

Fomrat code	Meaning
%#a, %#A, %#b, %#B, %#p, %#X, %#z, %#Z, %#%	# flag is ignored.
%#c	Long date and time representation, appropriate for current locale. For example: "Tuesday, March 14, 1995, 12:41:29".
%#x	Long date representation, appropriate to current locale. For example: "Tuesday, March 14, 1995".
%#d, %#H, %#I, %#j, %#m, %#M, %#S, %#U, %#w, %#W, %#y, %#Y	Remove leading zeros (if any).

Item type: Multiplexer

An item which multiplexes external items. ExternalItem1 is selector, ExternalItem2 = input1, ..., ExternalItemN = input(N-1)

The Multiplexer item type has the following properties:

Name	Description	ID	Flags
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Item type: TrigEvtBrokerCmd

An item which when set to true, fires an event in the Apis Event Broker. Use to control firing of commands.

The TrigEvtBrokerCmd item type has the following properties:

Name	Description	ID	Flags
EventBrokerEntry	Select the event in the event broker to trigger when this item is set.	10021	Persisted, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Item type: VariableMatrix

Matrix of variables, which can be written and read.

The VariableMatrix item type has the following properties:

Name	Description	ID	Flags
Columns	The number or columns in matrix item.	5009	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Rows	The number of rows in a matrix item.	5008	Persisted
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage
Valuetype	Item canonical datatype. This is the type of data the field holds. For example: integer, string, datetime, etc.	10025	Persisted, Enumerated

Item type: Expression

An item which runs a set of criterion on its external input. The output can be used as selector in a multiplexer item.

The Expression item type has the following properties:

Name	Description	ID	Flags
Expressions	An array of expressions used to calculate the value of this item.	5111	Persisted
No-match quality	The output quality used if there's no expression match.	10033	Persisted, Enumerated
No-match value	The output value used if there's no expression match.	10032	Persisted
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	NormalPage

Item type: Module State Items

An item which retrieves status information from the module

The Module state items item type has the following properties:

Name	Description	ID	Flags
Item type	The item type this item aggregates statistics on, when applicable. Use the number inside the parentheses in "FileAdd" configuration files.	19001	Persisted, ReadOnly, DynamicEnumeration
Module state	The kind of module state information represented by this item. This can be a number of items having a given quality, a total number of items, the time the newest/oldest item was updated. Use a number inside the parentheses in "FileAdd" configuration files.	19000	Persisted, ReadOnly, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Item Attribute Items

An item which exposes an attribute of another item in the module

The Item attribute items item type has the following properties:

Name	Description	ID	Flags
Attribute ID	The ID of the attribute this item exposes from an item.	19002	Persisted, ReadOnly, DynamicEnumeration
ParentItem	The parent item name of this item.	5502	Persisted, ReadOnly, ApisLocalItem
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

Items

An item, also known as a tag or signal, represents real-time values either originating from an external system (PLC, DCS, etc.), or values calculated or derived from such values within the Apis Hive environment (calculated control value, logical signal, etc.).

In most cases, a module will bring items into the Apis Hive environment, but there are also cases when a module doesn't provide items by itself, e.g. the ApisLoggerBee module.

Item attributes

Items are typically real-time process data or calculated data, and they have several attributes associated with them. All items have the standard OPC attributes: value; quality; timestamp; rights.

Additionally, items will typically have more attributes, dependent on the items purpose, and will vary for different types of items. Such attributes can be divided into two categories: custom attributes and predefined Apis/OPC attributes (for example, descriptions and engineering units).

Custom attributes

Attributes specific to the purpose of the item. E.g. the amplitude of a sine signal.

Predefined Apis / OPC attributes

Attribute of a more generic nature. See OPC DA Item attributes and "Predefined Apis attributes".

Item types

There are three main item types; scalar values, vector values and matrices.

A scalar value is typically a flow signal, temperature, etc. from an external system.
A vector value typically is a spectrum from an NIR instrument, or control vector in a Model-based Predictive Control (MPC) system.
A matrix value typically is a system matrix in an MPC system.

Shared Item Types

Item type: Module State Items

An item which retrieves status information from the module

The Module state items item type has the following properties:

Name	Description	ID	Flags
Item type	The item type this item aggregates statistics on, when applicable. Use the number inside the parentheses in "FileAdd" configuration files.	19001	Persisted, ReadOnly, DynamicEnumeration
Module state	The kind of module state information represented by this item. This can be a number of items having a given quality, a total number of items, the time the newest/oldest item was updated. Use a number inside the parentheses in "FileAdd" configuration files.	19000	Persisted, ReadOnly, Enumerated
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Item Attribute Items

An item which exposes an attribute of another item in the module

The Item attribute items item type has the following properties:

Name	Description	ID	Flags
Attribute ID	The ID of the attribute this item exposes from an item.	19002	Persisted, ReadOnly, DynamicEnumeration
ParentItem	The parent item name of this item.	5502	Persisted, ReadOnly, ApisLocalItem
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Type	The item canonical data type - the specific type of this item. Whether it's an integer, string, date, etc.	1	ReadOnly
Value	The current value of the item.	2	ReadOnly

Item type: Module events items

An item holding a string-array of the most recent simple event(s) generated by the module.

The Module events items item type has the following properties:

Name	Description	ID	Flags
EventCount	The number of most recent simple event(s) to keep in item string-array value.	19003	Persisted
EventSeverityFilter	A severity filter for simple event(s) to keep in item string-array value.	19004	Persisted, Enumerated
Quality	Item quality	3	ReadOnly
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	ReadOnly
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	ReadOnly

Item type: Function item

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

This item has two different calculators (algorithm syntax), C# and Legacy (proprietary), see:

The Function item item type has the following properties:

Name	Description	ID	Flags
Expression	An expression used to calculate the value of this item	5110	Persisted
Expressions	Definitions of array inputs to the calculator (applicable for C# only)	5111	Persisted
Calculator	Specifies which calculator to use, C# or legacy	19101	Persisted
DataChangeTrigger	The DataChangeTrigger is an enumeration that specifies the conditions for when the Function item should be reported as updated inside APIS after a calculation. Quality: Report as updated only if the Qualtiy associated with the value changes. QualityValue: Report as updated if either the Qualtiy or the Value change. QualityValueTimestamp: Report as updated if either Quality, Value or the Timestamp change (default).	19102	Persisted, Enumerated
External Items	The external items that are inputs to the formula given by the Expression property	20000 ... 20000+N	Persisted
Quality	Item quality	3	NormalPage
Rights	Item access rights	5	ReadOnly
Time	Item timestamp	4	NormalPage
Type	Item canonical datatype	1	ReadOnly
Value	Item value	2	NormalPage
Valuetype	Item canonical datatype.	19100	Persisted, Enumerated

Item type: Function item - C# calculator

This Item is a calculated value based on existing items in Hive. The calculation uses an expression with C# syntax to perform a calculation based on inputs from external Items.

Make sure to select C# for the function item Calculator attribute.

Looking for the Advanced content?

Calculation

The Expression is the body of a method with the following definition:

VQT Compute(VQT[] ex, VQT[][] arr)
{
	//Your expression will be placed here by the framework
}

ex is an array of the external items. The order is the same as the order of the external items in Hive.

arr is an array of arrays of the external items that are a part of arrays. These arrays are defined on the Expressions attribute. (See more on arrays below)

The parameters ex and arr are variants of type VQT with Value, Quality and Timestamp:

public readonly struct VQT
{
  public object Value // The value of the item
  //One of the primitive types: float, double, int, short, byte, sbyte, decimal, uint, ulong, ushort, long, bool 

  public OpcDaQuality Quality // OPC DA quality. enum : ushort. OPC DA qualities are 2 bytes

  public ulong Timestamp // FILETIME

  public double DblVal //Value as double, can be used if you know the value is of type double or it's ok to convert to double

  public int IntVal // Value as int, can be used if you know the value is of type int

  public bool BoolVal // Value as bool, can be used if you know the value is of type bool
}

The datatype of the variants Value is the same as in Hive.

The C# function items has built in operators for these variants, so they can be used as if they are normal primitive values. I.e. the following expression adds the first 2 items in the external items array:

return ex[0] + ex[1];

You can even omit the 'return' and the ';' if you have a oneliner and just type:

ex[0] + ex[1]

The expression can include various operators, functions, loops and logic operators. The item type of the returned value is usually the same as the inputs. A lot of the built in methods will return an 8 byte float.

In most cases when using expressions of kind All*, e.g. AllGoodCount, you will most likely need to have the module property ExtItem pass-through quality is set to Any quality.
Otherwise, one or more external item having a bad quality will prevent the Function item from being evaluated completely.
See also: ExtItem pass-through quality.

Operator	Description	Example
+	The sum of two values	ex[0] + ex[1]
-	The subtraction of one value from another	ex[0] - ex[1]
*	The multiplication of two values	ex[0] * ex[1]
/	The division of one value by another	ex[0] / ex[1]
%	The modulus of one value by another	ex[0] % ex[1]

Function	Description	Example	Item Type
Abs	The absolute value	Abs(ex[0])	8 byte float
Sin	The sine of a value, in radians	Sin(ex[0])	8 byte float
Asin	Returns the angle, θ, measured in radians, such that -π/2 ≤θ≤π/2 . The argument is a number must be greater than or equal to -1, but less than or equal to 1 Remarks: A positive return value represents a counterclockwise angle from the x-axis; a negative return value represents a clockwise angle. Multiply the return value by 180/Math.PI to convert from radians to degrees	Asin(ex[0])	8 byte float
Sinh	The hyperbolic sine of value. If value is equal to NegativeInfinity. The parameter is an angle, measured in radians. Remarks: The angle, value, must be in radians. Multiply by Math.PI/180 to convert degrees to radians.	Sinh(ex[0])	8 byte float
Asinh	Returns the angle whose hyperbolic sine is the specified number	Asinh(ex[0])	8 byte float
Cos	The cosine of a value, in radians	Cos(ex[0])	8 byte float
Acos	Returns the angle, θ, measured in radians, such that 0 ≤θ≤π. The argument is a number must be greater than or equal to -1, but less than or equal to 1 Remarks: Multiply the return value by 180/Math.PI to convert from radians to degrees.	Acos(ex[0])	8 byte float
Cosh	The hyperbolic cosine of value. If value is equal to NegativeInfinity or PositiveInfinity, PositiveInfinity is returned. If value is equal to NaN, NaN is returned. The parameter is an angle, measured in radians. Remarks: The angle, value, must be in radians. Multiply by Math.PI/180 to convert degrees to radians.	Cosh(ex[0])	8 byte float
Acosh	Returns the angle whose hyperbolic cosine is the specified number	Acosh(ex[0])	8 byte float
Tan	The tangent of a value, in radians	Tan(ex[0])	8 byte float
Atan	Returns the angle, θ, measured in radians, such that -π/2 ≤θ≤π/2. -or- NaN if d equals NaN, -π/2 rounded to double precision (-1.5707963267949) if d equals NegativeInfinity, or π/2 rounded to double precision (1.5707963267949) if d equals PositiveInfinity. Remarks: A positive return value represents a counterclockwise angle from the x-axis; a negative return value represents a clockwise angle. Multiply the return value by 180/Math.PI to convert from radians to degrees	Atan(ex[0])	8 byte float
Tanh	The hyperbolic tangent of value. If value is equal to NegativeInfinity, this method returns -1. If value is equal to PositiveInfinity, this method returns 1. If value is equal to NaN, this method returns NaN. The parameter is an angle, measured in radians. Remarks: The angle, value, must be in radians. Multiply by Math.PI/180 to convert degrees to radians.	Tanh(ex[0])	8 byte float
Atanh	Returns the angle whose hyperbolic tangent is the specified number	Atanh(ex[0])	8 byte float
Exp	Exponent of an expression	Exp(ex[0])	8 byte float
Floor	Rounds the value to nearest integer towards minus infinity	Floor(ex[0])	8 byte float
Ceiling	Returns the smallest integral value that is greater than or equal to the specified	Ceiling(ex[0])	8 byte float
Log	The natural (base e) logarithm of a specified number	Log(ex[0])	8 byte float
Neg	Invert sign	Neg(ex[0])	8 byte float
Bit	The bit value at specified index	Bit(ex[0], 3) (returns 0 or 1)	int32
Pow	The first value raised to the power of the second value	Pow(ex[0] , 2)	8 byte float
Sqrt	The square root of a value	Sqrt(ex[0])	8 byte float
Max	Return max value of an array of values	Max(ex)	8 byte float
Max (scalars)	Return max value of two values	Max(ex[0], ex[1])	8 byte float
Min	Return min value of an array of values	Min(ex)	8 byte float
Min (scalars)	Return min value of two values.	Min(ex[0],ex[1])	8 byte float
AllGoodMin	Return the minimum of an array that have good quality. If no good value exists, then double.MaxValue and bad quality is returned.	AllGoodMin(ex)	8 byte float
Avg	Return the average of an array of values Quality will be the worst quality.	Avg(ex)	8 byte float
AllGoodAvg	Return the average of an array that have good quality. If no good value exists, then 0.0 and bad quality is returned.	AllGoodAvg(ex)	8 byte float
AllGoodMax	Return the maximum of an array that have good quality. If no good value exists, then double.MinValue and bad quality is returned.	AllGoodMax(ex)	8 byte float
Median	Return the median of an array	Median(ex)	8 byte float
AllGoodMed	Return the median of an array that have good quality. If no good value exists, then NAN and bad quality is returned.	AllGoodMed(ex)	8 byte float
Var	Return the variance of an array. Normalized with N, this provides the square root of the second moment around the mean	Var(ex)	8 byte float
AllGoodVar	Return the variance of the elements in an array that have good quality. Normalized with N, this provides the square root of the second moment around the mean If no good value exists, then NAN and bad quality is returned.	AllGoodVar(ex)	8 byte float
Std	Return the standard deviation of an array. Normalized with N, this provides the square root of the second moment around the mean If no good value exists, then NAN and bad quality is returned.	Std(ex)	8 byte float
AllGoodStd	Return the standard diviation of all external items that have good quality. If no good value exists, then NAN and bad quality is returned.	AllGoodStd(ex)	8 byte float
AllCount	Return the size of an array.	AllCount(ex)	int
AllGoodCount	Return the number of all external items that have good quality.	AllGoodCount(ex)	int
Sum	Return the sum of an array. Quality will be the worst quality.	Sum(ex)	8 byte float
AllGoodSum	Return the sum of all external items that have good quality. If no good value exists, 0.0 and bad quality is returned.	AllGoodSum(ex)	8 byte float
AllGoodGreatherThanAvg	Return the the average of all good values greather than x. If no good value exists, then NAN and bad quality is returned.	AllGoodGreatherThanAvg(ex, x)	8 byte float
AllGoodLessThanAvg	Return the the average of all good values less than x. If no good value exists, then NAN and bad quality is returned.	AllGoodLessThanAvg(ex, limit)	8 byte float
Delay	Delay a signal a number of steps (number of external item transfers). Maximum number of delays is 3600.	Delay(5, ex[0]) This will delay the first external item 5 steps.	Same as input
LowPassFilter	Will lowpass filter a signal with the specified time constant. Only inputs with quality Good will be used in the filter. If input is not Good, output will have Uncertain quality	LowPassFilter(60.0, ex[0]) The time constant here is 60 seconds. dT in the filter is the time difference between current and previous external item timestamp.	8 byte float
MovingAvg	Moving average for a specified window size. Computed on every external item transfer. Maximum window size is 3600. Only inputs with quality Good will be used in the algoritm. If some inputs are not Good, output will have Uncertain quality. If all inputs are not Good, output will be Bad	MovingAvg(5, ex[0]) The window size here is 5.	8 byte float
MovingTimeAvg	Moving average for a period of time (window). Computed on every external item transfer. Maximum window size is 3600 seconds. Only inputs with quality Good will be used in the algoritm. If some inputs are not Good, output will have Uncertain quality. If all inputs are not Good, output will be Bad. Tip: If your intension is to low pass filter a signal, use the LowPassFilter method instead, it is much more efficient.	MovingTimeAvg(5.0, ex[0]) The window size here is 5 seconds.	8 byte float
Hysteresis	Hysteresis for a specified deadband. The output value will not change before the input value moves outside of the deadband. The timestamp will change even if the value does not	Hysteresis(2, ex[0]) The deadband here is 2. Example of inputs/outputs: Input 1 output 1 Input 2 output 1 Input 3 output 3 Input 4 output 4 Input 5 output 5 Input 4 output 5 Input 3 output 5 Input 2 output 2 Input 1 output 1 Input 0 output 0	Same as input
PosFlankDelay	For a boolean input signal, any positive flank (from false to true) will have to stay positive (true) for certain amount of time before the output goes positive (true). NB! This method requires at least one extra external item that changes continuously. The first element in the external item array must be the signal to filter. This is a requirement do to the fact that the external item update mechanism only happens on external item change.	PosFlankDelay(5.0, ex) The delay period here is 5 seconds. Note that the whole external item array, ex, is used as an argument.	Boolean
NegFlankDelay	For a boolean input signal, any negative flank (from true to false) will have to stay negative (false) for certain amount of time before the output goes negative (false). NB! This method requires at least one extra external item that changes continuously. The first element in the external item array must be the signal to filter. This is a requirement do to the fact that the external item update mechanism only happens on external item change.	NegFlankDelay(5.0, ex) The delay period here is 5 seconds. Note that the whole external item array, ex, is used as an argument.	Boolean
GetDateTime	The value of this function item is the timestamp, in OLE Automation date format, of the external item (UTC). The datatype of this function item must be Date.	GetDateTime(ex[0])	DATE
GetUnixTime	The value of this function item is the timestamp, in milliseconds since 1.1.1970, of the external item (UTC). The value is a double including milliseconds as decimals.	GetUnixTime(ex[0])	8 byte float (default)

Logic	Description	Example
>	Greater than	ex[0] > ex[0]
>=	Greater than or equal	ex[0] >= 2.5
<	Smaller than	ex[0] < 3.4
<=	Smaller than or equal	ex[0] <= ex[1]
==	Equal	ex[0] == ex[1]
<>	Not equal	ex[0] != ex[1]
!=	Not equal	ex[0] != ex[1]
!	Not	!( ex[0] > ex[1] )

Loops

Standard C# loops can be used in an Expression:

For loop:

for (int i = 0; i < ex.Length; i++)
{
	if (ex[i] > 10.0)
		return true;
}

While loop:

bool hit = false;
int index = 0;
while(index < ex.Length && !hit)
{
	if (ex[index] > 10.0)
		hit = true;
	index++;
}
return hit;

Array External Items

The external items can be organized into arrays (arr) that enter the Compute method:

VQT Compute(VQT[] ex, VQT[][] arr)

Sometimes it's natural to organize some of the external items into arrays. Example: we have one status item and 3 temperature measurements as inputs, it might be natural to place the temperatures in a separate array, to i.e. compute the average temperature.

By using the Expressions attribute (note that it ends with an s, different attribute from Expression) on the function item, you can organize the external items into arrays. In the example we have 4 external items, say the first three are temperatures and the last is Status. The Expressions attribute then becomes:

[1] ex1, ex2, ex3;

'[1]' means 1 array, consisting of external items ex1, ex2 and ex3. The array content is separated by ';', so two arrays would be:

[2] ex1, ex2; ex3, ex4;

The external items that are in arrays will not be a part of ex parameter. In our example, ex will be 1 long.

if (ex[0] == 0) // Status check, note index is 0 even though status is the forth external item
	return 0; // Status indicated error

var tempMean = Avg(arr[0]); // Temp average, the first array (and only, in this case)
if (tempMean > 30.0)        // Temp too high
	return 3;

return 1; // Ok

Example 1

Expression:

ex[0] + ex[1] + 5.14

Example 2

Expression:

if(ex[1] > 0.0 && ex[2] > 0.0)
	return 100.0*1000.0*ex[0]/(ex[1]*ex[2]);
return 0.0;

Example 3

Expression:

if (ex[0] == true) return 3; //Waiting

if (arr[0].Length > 0)
{
	if (arr[0].Any(a => a == 4)) return 4; //Leak detected

	var tankCount = 0.0;
	var tankOkCount = 0.0;

	for (int i = 0; i < arr[0].Length; i++)
	{
		tankCount++;
		if (arr[0][i] == 0)
			tankOkCount++;
	}

	if (tankCount == 0.0)
		return 0; //Ignore

	var tanksProdusingFrac = tankCount > 0.0 ? tankOkCount / tankCount : 0.0;

	if (tanksProdusingFrac < 0.9) return 2; //Error
	if (tanksProdusingFrac < 1.0) return 1; //Warning
}

return 0;

Specifying a non-existing External Item

If you want to specify a dummy/non-existing external item in the list of external items, you can specify external item(s) named ##DummyExternalItem.
Items having this name will be given special handling inside APIS and will not be used in the calculation. This is useful when you want to use the same expression for multiple items, but some of the items have different number of external items.
Note that to achieve this, you must apply the configuration by import from a text file. Using the Add items dialog in Apis Management Studio together with File add will also work.

See the Advanced content for more information.

Item type: Function item - C# calculator - Advanced

Here we will go deeper into how to use C# function items.

Calculation

The standard doc does not show the whole truth about the method the expression is executed in context of. The full definition is:

VQT Compute(VQT[] ex, VQT[][] arr, IItemContext itemContext, Func<IState> state, ICsScriptLog log)
{
	//Your expression will be placed here by the framework
}

itemContext is defined as follows:

public interface IItemContext
{
    /// <summary>
    /// Handle of Hive item
    /// </summary>
    int ItemHandle { get; }

    /// <summary>
    /// Func item expression
    /// </summary>
    string Expression { get; }

    /// <summary>
    /// Func item expression arrays
    /// </summary>
    string[] ExpressionArrays { get; }
}

state is actually a method (Func) that will give you an instance of IState. You can store values between computations on the state instance:

public interface IState
{
    bool Contains(StateKey key);
    byte GetOrAdd(StateKey key, byte defaultValue);
    sbyte GetOrAdd(StateKey key, sbyte defaultValue);
    short GetOrAdd(StateKey key, short defaultValue);
    ushort GetOrAdd(StateKey key, ushort defaultValue);
    int GetOrAdd(StateKey key, int defaultValue);
    uint GetOrAdd(StateKey key, uint defaultValue);
    long GetOrAdd(StateKey key, long defaultValue);
    ulong GetOrAdd(StateKey key, ulong defaultValue);
    float GetOrAdd(StateKey key, float defaultValue);
    double GetOrAdd(StateKey key, double defaultValue);
    decimal GetOrAdd(StateKey key, decimal defaultValue);
    string GetOrAdd(StateKey key, string defaultValue);
    IList<VQT> GetOrAdd(StateKey key, IList<VQT> defaultValue);
    VQT GetOrAdd(StateKey key, VQT defaultValue);

    void AddOrUpdate(StateKey key, byte defaultValue);
    void AddOrUpdate(StateKey key, sbyte defaultValue);
    void AddOrUpdate(StateKey key, short defaultValue);
    void AddOrUpdate(StateKey key, ushort defaultValue);
    void AddOrUpdate(StateKey key, int defaultValue);
    void AddOrUpdate(StateKey key, uint defaultValue);
    void AddOrUpdate(StateKey key, long defaultValue);
    void AddOrUpdate(StateKey key, ulong defaultValue);
    void AddOrUpdate(StateKey key, string defaultValue);
    void AddOrUpdate(StateKey key, float defaultValue);
    void AddOrUpdate(StateKey key, double defaultValue);
    void AddOrUpdate(StateKey key, decimal defaultValue);
    void AddOrUpdate(StateKey key, IList<VQT> defaultValue);
    void AddOrUpdate(StateKey key, VQT defaultValue);
    void Remove(StateKey key);
    void Clear();
}

The StateKey is a unique key for entries in the state:

public struct StateKey
{
    /// <summary>
    /// Key for storing values in an instance of IState
    /// </summary>
    /// <param name="paramId">The id of the parameter to store</param>
    /// <param name="algId">The id of the algorithm (method)</param>
    /// <param name="extItemHandles">The external item handles</param>
    public StateKey(int paramId, int algId, int[] extItemHandles)
    {
        _paramId = paramId;
        _algId = algId;
        _extItemHandles = extItemHandles.OrderBy(e => e).ToArray();
    }
    ...
}

log is a logger provided by Hive. Log entries will end up in the Hive log:

public interface ICsScriptLog
{
    bool IsDebugEnabled { get; }

    bool IsInfoEnabled { get; }

    bool IsWarnEnabled { get; }

    bool IsErrorEnabled { get; }

    bool IsFatalEnabled { get; }

    void Info(object logEntry);

    void Info(object logEntry, Exception e);

    void InfoFormat(string formatString, params object[] args);

    void Warn(object logEntry);

    void Warn(object logEntry, Exception e);

    void WarnFormat(string formatString, params object[] args);

    void Error(object logEntry);

    void Error(object logEntry, Exception e);

    void ErrorFormat(string formatString, params object[] args);

    void Fatal(object logEntry);

    void Fatal(object logEntry, Exception e);

    void FatalFormat(string formatString, params object[] args);

    void Debug(object logEntry);

    void Debug(object logEntry, Exception e);

    void DebugFormat(string formatString, params object[] args);
}

Example expression

Next, we will show how to use the state and log in an expression. In the example we are creating a low pass filter:


//VQT Compute(VQT[] ex, VQT[][] arr, IItemContext itemContext, Func<IState> state, ICsScriptLog log) <- context
//{
    //Expression start
    var timeConstant = 60.0;

    int algId = GetAlgorithmId("Acme_LowPass"); // Generate an id for the method. Use a string that is globally unique and means something in your context.
                                                // Here we are making a lowpass filter for the company 'Acme'

    var myState = state();     // Get the state from the environment.
    var filteredId = 1;        // Id of filter value (previously filtered value)
    var timestampId = 2;       // Id of the timestamp of previous external item

    var filteredValueKey = new StateKey(filteredId, algId, new[] { ex[0].ItemHandle });    // Generate unique key for filtered value
    var timestampKey = new StateKey(timestampId, algId, new[] { ex[0].ItemHandle });       // Generate unique key for previous timestamp

    if (!myState.Contains(filteredValueKey)) // If first time, add values to the state and return
    {
        myState.AddOrUpdate(filteredValueKey, ex[0].DblVal);
        myState.AddOrUpdate(timestampKey, ex[0].Timestamp);
        return ex[0];
    }

    var prevFiltered = myState.GetOrAdd(filteredValueKey, 0.0);   // Get previous filtered value
    var prevTimestamp = myState.GetOrAdd(timestampKey, 0UL);      // Get previous timestamp

    var dT = (ex[0].Timestamp - prevTimestamp) / 1e7; // -> sec

    if (dT <= 0.0)
    {
        log.Error($"dT is '{dT}', not a legal value");
        return ex[0];
    }

    double filtered;
    if (timeConstant > dT) // Prevent unstable filter
    {
        filtered = prevFiltered + dT * (ex[0].DblVal - prevFiltered) / timeConstant; // Compute new filtered value
    }
    else
    {
        log.Warn($"timeConstant > dT, unstable. Consider increasing your time constant");
        filtered = ex[0].DblVal;
    }

    myState.AddOrUpdate(filteredValueKey, filtered); // Update state with new filterd value
    myState.AddOrUpdate(timestampKey, ex[0].Timestamp); // Update state with new timestamp

    return new VQT(filtered, ex[0].Quality, ex[0].Timestamp); // Return filtered value
    //Expression end
//}

Pitfall !

If the state key is not unique, the state will be shared and the results will be a mess. I.e. If one call the same method twice in an expression for the same external item:

var lp1 = LowPassFilter(timeConstant, ex[0], state);
// Do something with lp1
var lp2 = LowPassFilter(timeConstant, ex[0], state); // <- same as lp1
// Do something with lp2

In the case abowe, do not lowpass ex[0] twice.

Item type: Function item - Legacy calculator

This Item is a calculated value based on existing items in Hive. The calculation is formula based on inputs from external Items.

Calculation

The formula can an expression with the names ex1, ex2,ex3,...exN. The formula can include the following Operators, Functions, and Logic.
In most cases when using expressions of kind All*, e.g. AllGoodCount, you will most likely need to have the module property ExtItem pass-through quality is set to Any quality.
Otherwise, one or more external item having a bad quality will prevent the Function item from being evaluated completely.
See also: ExtItem pass-through quality.

Operator	Description	Example	Item Type
+	The sum of two values	ex1 + ex2	8 byte float (default)
-	The subtraction of one value from another	ex1 - ex2	8 byte float (default)
*	The multiplication of two values	ex1 * ex2	8 byte float (default)
/	The division of one value by another	ex1 / ex2	8 byte float (default)
%	The modulus of one value by another	ex1 % ex2	8 byte float (default)

Function	Description	Example	Item Type
(	Left bracket	1.0 / ( ex1 + ex2 )
)	Right bracket	1.0 / ( ex1 + ex2 )
/**/	Comment. In a function Item everything between /* and */ will be omitted.	/* a comment */
abs	The absolute value	abs(ex1)	8 byte float (default) or custom scalar number
asinh	Represents the inverse of the hyperbolic sine function	asinh(ex1)	8 byte float (default) or custom scalar number
acosh	Represents the inverse of the hyperbolic cosine function.	acosh(ex1)	8 byte float (default) or custom scalar number
atanh	Represents the inverse of the hyperbolic tangent function.	atanh(ex1)	8 byte float (default) or custom scalar number
arcsin	Returns the angle, θ, measured in radians, such that -π/2 ≤θ≤π/2 . The argument is a number must be greater than or equal to -1, but less than or equal to 1 Remarks: A positive return value represents a counterclockwise angle from the x-axis; a negative return value represents a clockwise angle. Multiply the return value by 180/Math.PI to convert from radians to degrees	arcsin(ex1)	8 byte float (default) or custom scalar number
arccos	Returns the angle, θ, measured in radians, such that 0 ≤θ≤π. The argument is a number must be greater than or equal to -1, but less than or equal to 1 Remarks: Multiply the return value by 180/Math.PI to convert from radians to degrees.	arccos(ex1)	8 byte float (default) or custom scalar number
arctan	Returns the angle, θ, measured in radians, such that -π/2 ≤θ≤π/2. -or- NaN if d equals NaN, -π/2 rounded to double precision (-1.5707963267949) if d equals NegativeInfinity, or π/2 rounded to double precision (1.5707963267949) if d equals PositiveInfinity. Remarks: A positive return value represents a counterclockwise angle from the x-axis; a negative return value represents a clockwise angle. Multiply the return value by 180/Math.PI to convert from radians to degrees	arctan(ex1)	8 byte float (default) or custom scalar number
cos	The cosine of a value, in radians	cos(ex1)	8 byte float (default) or custom scalar number
cosh	The hyperbolic cosine of value. If value is equal to NegativeInfinity or PositiveInfinity, PositiveInfinity is returned. If value is equal to NaN, NaN is returned. The parameter is an angle, measured in radians. Remarks: The angle, value, must be in radians. Multiply by Math.PI/180 to convert degrees to radians.	cosh(ex1)	8 byte float (default) or custom scalar number
exp	Exponent of an expression	exp( ex1 )	8 byte float (default)
floor	Rounds the value to nearest integer towards minus infinity	floor(ex1)	16 byte fixed point (default) or custom scalar number
ln	Logarithm of a value	ln(ex1 + ex2)	8 byte float (default)
neg	Invert sign	neg(ex1)	8 byte float (default) or custom scalar number
pow	The first value raised to the power of the second value	pow(ex1 , ex2)	8 byte float (default) or custom scalar number
sin	The sine of a value, in radians	sin(ex1)	8 byte float (default) or custom scalar number
sinh	The hyperbolic sine of value. If value is equal to NegativeInfinity. The parameter is an angle, measured in radians. Remarks: The angle, value, must be in radians. Multiply by Math.PI/180 to convert degrees to radians.	sinh(ex1)	8 byte float (default) or custom scalar number
sqrt	The square root of a value	sqrt(ex1)	8 byte float (default) or custom scalar number
tan	The tangent of a value, in radians	tan(ex1)	8 byte float (default) or custom scalar number
tanh	The hyperbolic tangent of value. If value is equal to NegativeInfinity, this method returns -1. If value is equal to PositiveInfinity, this method returns 1. If value is equal to NaN, this method returns NaN. The parameter is an angle, measured in radians. Remarks: The angle, value, must be in radians. Multiply by Math.PI/180 to convert degrees to radians.	tanh(ex1)	8 byte float (default) or custom scalar number
max	Return max value of two values.	max(ex1,ex2)	8 byte float (default) or custom scalar number
min	Return min value of two values.	min(ex1,ex2)	8 byte float (default) or custom scalar number
allgoodavg	Return the average of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodavg()	8 byte float (default)
allgoodmin	Return the minimum of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodmin()	8 byte float (default)
allgoodmax	Return the maksimum of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodmax()	8 byte float (default)
allgoodmed	Return the median of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodmed()	8 byte float (default)
allgoodstd	Return the standard diviation of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodstd()	8 byte float (default)
allgoodvarians	Return the varians of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodvarians()	8 byte float (default)
allgoodcount	Return the number of all external items that have good quality.	allgoodcount()	int
allgoodsum	Return the sum of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodsum()	int (default)
allgoodcountvalue	Return the number of all external items that have good quality and value equal to the given value.	allgoodcountvalue(5.1)	int
allgoodlastdatetime	Return the newest timestamp of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodlastdatetime()	DATE
allgoodlastunixtime	Return the newest timestamp of all external items that have good quality. The value is a double with ms as decimals. If no good extenal value exist, then NAN and bad quality is returned.	allgoodlastunixtime()	8 byte float (default)
allgoodfirstdatetime	Return the oldest timestamp of all external items that have good quality. If no good extenal value exist, then NAN and bad quality is returned.	allgoodfirstdatetime()	DATE
allgoodfirstunixtime	Return the oldest timestamp of all external items that have good quality. The value is a double with ms as decimals. If no good extenal value exist, then NAN and bad quality is returned.	allgoodfirstunixtime()	8 byte float (default)
allgoodgreatherthanavg	Return the the average of all good values greather than X. If no good extenal value exist, then NAN and bad quality is returned.	allgoodgreatherthanavg(XX)	8 byte float (default)
allgoodlessthanavg	Return the the average of ajl good values less than X. If no good extenal value exist, then NAN and bad quality is returned.	allgoodlessthanavg(XX)	8 byte float (default)
allavg	Return the average of all external items. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allavg()	8 byte float (default)
allmin	Return the minimum of all external items that have good quality. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allmin()	8 byte float (default)
allmax	Return the maksimum of all external item. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allmax()	8 byte float (default)
allmed	Return the median of all external. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allmed()	8 byte float (default)
allstd	Return the standard diviation of all external items. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allstd()	8 byte float (default)
allvarians	Return the varians of all external. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allvarians()	8 byte float (default)
allcount	Return the number of all external items.	allcount()	int
allsum	Return the sum of all external items. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allsum()	int (default)
allcountvalue	Return the number of all external items that have value equal to the given value. Quality will be the worst quality. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allcountvalue(5.1)	int
allgreatherthanavg	Return the the average of all values greather than X. If error in conversion to double, the value will be omitted, and quality will be set to BAD	allgreatherthanavg(XX)	8 byte float (default)
alllessthanavg	Return the the average of all values less than X. If error in conversion to double, the value will be omitted, and quality will be set to BAD	alllessthanavg(XX)	8 byte float (default)
movingavg	Calculate the moving average of the last 5 values of calculation defined in the brackets	movingavg(ex1)	8 byte float (default) or custom scalar number
movingavgXX	Create an moving average of last XX values	movingavg10(ex1)	8 byte float (default) or custom scalar number
deltaavg	Create an moving average of last 5 values, but the value is only updated when calculation is based on 5 new values.	deltaavg(ex1)	8 byte float (default) or custom scalar number
deltaavgXX	Create an moving average of last XX values, but the value is only updated when calculation is based on XX new values.	deltaavg10(ex1)	8 byte float (default) or custom scalar number
movingtimeavgXX	Calculate the moving average of the last XX seconds of the calculation defined in the brackets. If XX is 60, then the function return the moving average of the last 60 seconds. If XX is omitted, a default value 5 is used.	movingavg100(ex1)	8 byte float (default)
deltatimeavgXX	Calculate the moving time average of the last XX seconds of the calculation defined in the brackets. If XX is 60, then the function return the moving average of the last 60 seconds every 60 seconds. The calculation is also synchronized to XX. If XX is 60 a new value will be calculated every minute (60 seconds) e.g. 10:01:00 and 10:02:00, etc. If XX is 600, there will be a new value at 10:00:00, 10:10:00, 10:20:00, etc. If XX is omitted, a default value 5 is used.	deltatimeavg60(ex1)	8 byte float (default)
deltatimeendXX	Calculate/return the last sample of the last XX seconds of the calculation defined in the brackets. If XX is 60, then the function return the moving average of the last 60 seconds every 60 seconds. The calculation is also synchronized to XX. If XX is 60 a new value will be calculated every minute (60 seconds) e.g. 10:01:00 and 10:02:00, etc. If XX is 600, there will be a new value at 10:00:00, 10:10:00, 10:20:00, etc. If XX is omitted, a default value 5 is used.	deltatimeend60(ex1)	8 byte float (default)
delay	Delay the value 1 step.	delay(ex1/ex2)	8 byte float (default)
delayXX	Delay the value XX step.	delay5(ex1/ex2)	8 byte float (default)
pulsedetect	Detect a pulse defined as the previous value below 0.5 and current valiue above 0.5. If a puls is detected the return value is 1 else the value is 0.	pulsedetect(ex1)	8 byte float (default)
pulsecount	Count the number of detected pulses. A puls is defined bu the function pulsdetect. The counting starts from 0 when Apis is started.	pulsecount(ex1)	8 byte float (default)
filetime2oadate	Converts a FILETIME value into the equivalent OLE Automation date. A Windows file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 midnight, January 1, 1601 A.D. (C.E.) Coordinated Universal Time (UTC). Windows uses a file time to record when an application creates, accesses, or writes to a file. An OLE Automation date is a 8 byte floating-point number whose integral component is the number of days before or after midnight, 30 December 1899, and whose fractional component represents the time on that day divided by 24. The base OLE Automation Date is midnight, 30 December 1899.	filetime2oadate(ex1)	DATE
unixtime2oadate	Converts a Unix Timestamp into the equivalent OLE Automation date. Unix Timestamp is the number of seconds that have elapsed since UTC 1970-01-01T00:00:00Z. The OLE Automation data type is described above.	unixtime2oadate(ex1)	DATE
unixtimems2oadate	Converts a Unix Timestamp with milliseconds (Unix time multiplied with 1000), into the equivalent OLE Automation date. Unix Time and OLE Automation data types are described above.	unixtimems2oadate(ex1)	DATE
getdatetime	Take the timestamp of the value and use this as the value itself.	getdatetime(ex1)	DATE
getunixtime	Take the timestamp of the value and use this as the value itself. The value is a double including milliseconds as decimals.	getunixtime(ex1)	8 byte float (default)
if-elseif-else	Add possibilities to have IF - ELSEIF - ELSE construction in function Items. ELSE part is mandatory, but the ELSEIF can be omitted or added several times.	If (ex1 > 2) {ex1ex2} ElseIf (ex1 > 1) {(ex3+1)ex1} Else {5.0}	8 byte float (default)

Logic	Description	Example	Item Type
>	Greater than	(ex1 > ex2)	8 byte float ( 0.0 or 1.0)
>=	Greater than or equal	( ex1 >= 2.5 )	8 byte float ( 0.0 or 1.0)
<	Smaller than	( ex1 < 3.4)	8 byte float ( 0.0 or 1.0)
<=	Smaller than or equal	( ex1 <= ex2 )	8 byte float ( 0.0 or 1.0)
==	Equal	( ex1 == ex2 )	8 byte float ( 0.0 or 1.0)
<>	Not equal	( ex1 != ex2 )	8 byte float ( 0.0 or 1.0)
!=	Not equal	( ex1 != ex2 )	8 byte float ( 0.0 or 1.0)
!	Not	!( ex1 > ex2 )	8 byte float ( 0.0 or 1.0)

Logical expressions are written like (ex1 > 4.5), the result however will be a double value either 0.0 (false) or 1.0 (true). These expressions can be a part of a formula.

The result of a calculation will always be a double value.

External Items

The values ex1, ex2 are the values from the external items defined in the external items attribute.

Example 1

Expression:
ex1+ex2 + ex1+ 5.14

External Items:
ex1 : Worker.signal1
ex2: Worker.Signal2

Example 2

Expression:
(ex1+3.2) / ex2+5.3 / ( ex2-ex1 )-ex3 + Ln( ex1+ex2 ) * ( ex1 > 5.2 )

External Items:
ex1 : Worker.signal1
ex2: Worker.Signal2
ex3: Worker.Signal4

Example 3

Expression:
Ln( ex1+ex2+ Abs(ex1) )

External Items:
ex1 : Worker.signal1
ex2: Worker.Signal2

Global Attributes

By global attributes, we mean attributes that can be added dynamically to any item in the Apis Hive environment at any time. There are three main categories of global items: global attributes defined by an Apis module; predefined Apis attributes; predefined OPC attributes.

Defined by modules

Some modules register global attributes in the Apis Hive environment. These global attributes can be added dynamically to any item in the Apis Hive namespace at any time. The module owning the global attribute, defines the meaning of it.

An example using ApisLoggerBee

The ApisLoggerBee module defines a global attribute called the Log attribute. This attribute controls whether or not an item is being stored to the Apis Honeystore historian as a time series. If this attribute is added to an item, and the value of the attribute is set to true, the item is being stored.

Predefined Apis attributes

The predefined OPC attributes are attributes that have been defined by the OPC Foundation according to the OPC DA specification. These attributes are described here, Predefined Apis attributes.

Predefined OPC attributes

The predefined OPC attributes are attributes that have been defined by the OPC Foundation according to the OPC DA specification. These attributes are described here, OPC DA Item Attributes.

Item Attributes

Items have attributes (sometimes also referred to as properties). They can be changed by selecting one or more items in the Solution Explorer or an item view. The attributes are changed in the Property Editor.

Adding item attributes

Attributes can be added to items by selecting one or more items in the Solution Explorer or a view, and then clicking the "Add Property button" in the Property Editor. A dialog box will appear listing attributes/properties that can be added. Select one or more attributes and click "Ok" to add the attributes.

Removing item attributes

Attributes can be removed from items by selecting one or more items in the Solution Explorer or a view, and then clicking the "Remove Property" button in the Property Editor. A dialog box will appear where attributes that can be removed are listed. Select one more attributes and click "Ok" to remove the attributes.

Note: Not all the attributes can be removed. Only the ones which have been added previously.

Basic Item Properties

All items have a set of basic properties, these are:

Standard

Name	Description	ID	Flags
Value	The current value of the item.	2	NormalPage
Quality	Item quality - this tells you whether an item currently has a good or bad quality. It might be bad, for example, because it isn't connected or is set to the wrong type.	3	ReadOnly
Time	The date and time when this item was last updated.	4	ReadOnly
Rights	Item access rights - this property may be "read", or "read write". This means that the property may only be read from, or also can be written to. For OPC items, this written value will be passed on to the external items this item comes from.	5	ReadOnly

Enumerated Item Properties

Some Apis Hive properties / attributes have enumerated values. i.e. You may select from a predefined list of attribute values. The enumerated values and matching integers are listed here in order to make configuration with text files easier.

Monitoring - Pulse Triggering - MonMethod

None => 0,
ValueChanged => 1,
ValueChangedAutoReset => 2

Data transfer control - ExtTransferCtrlMethod

Always => 0,
When CtrlItem changes from zero => 1,
When CtrlItem is zero => 2,
When CtrlItem is non zero => 3,
When CtrlItem becomes > argument => 10,
When CtrlItem becomes < argument => 11,
When CtrlItem becomes = argument => 12,
When CtrlItem becomes <> argument => 13,
When CtrlItem > argument => 20,
When CtrlItem < argument => 21,
When CtrlItem = argument => 22,
When CtrlItem <> argument => 23

External item override - ExtItemOverrideMethod

Default => 0,
Assign a complete value from external item => 1

Data validation - DVMethod

The method that decides which data validation tests to use.
None => 0x0,
BQ => 0x1,
R => 0x2,
ROC => 0x4,
WD => 0x8,
DF => 0x10,
ADF => 0x20,
SPC => 0x40,
____ 2 rules ____
BQ_R => 0x3,
BQ_ROC => 0x5,
R_ROC => 0x6,
BQ_WD => 0x9,
R_WD => 0xa,
ROC_WD => 0xc,
BQ_DF => 0x11,
R_DF => 0x12,
ROC_DF => 0x14,
WD_DF => 0x18,
BQ_ADF => 0x21,
R_ADF => 0x22,
ROC_ADF => 0x24,
WD_ADF => 0x28,
DF_ADF => 0x30,
BQ_SPC => 0x41,
R_SPC => 0x42,
ROC_SPC => 0x44,
WD_SPC => 0x48,
DF_SPC => 0x50,
ADF_SPC => 0x60,
____ 3 rules ____
BQ_R_ROC => 0x7,
BQ_R_WD => 0xb,
BQ_ROC_WD => 0xd,
R_ROC_WD => 0xe,
BQ_R_DF => 0x13,
BQ_ROC_DF => 0x15,
R_ROC_DF => 0x16,
BQ_WD_DF => 0x19,
R_WD_DF => 0x1a,
ROC_WD_DF => 0x1c,
BQ_R_ADF => 0x23,
BQ_ROC_ADF => 0x25,
R_ROC_ADF => 0x26,
BQ_WD_ADF => 0x29,
R_WD_ADF => 0x2a,
ROC_WD_ADF => 0x2c,
BQ_DF_ADF => 0x31,
R_DF_ADF => 0x32,
ROC_DF_ADF => 0x34,
WD_DF_ADF => 0x38,
BQ_R_SPC => 0x43,
BQ_ROC_SPC => 0x45,
R_ROC_SPC => 0x46,
BQ_WD_SPC => 0x49,
R_WD_SPC => 0x4a,
ROC_WD_SPC => 0x4c,
BQ_DF_SPC => 0x51,
R_DF_SPC => 0x52,
ROC_DF_SPC => 0x54,
WD_DF_SPC => 0x58,
BQ_ADF_SPC => 0x61,
R_ADF_SPC => 0x62,
ROC_ADF_SPC => 0x64,
WD_ADF_SPC => 0x68,
DF_ADF_SPC => 0x70,
____ 4 rules ____
BQ_R_ROC_WD => 0xf,
BQ_R_ROC_DF => 0x17,
BQ_R_WD_DF => 0x1b,
BQ_ROC_WD_DF => 0x1d,
R_ROC_WD_DF => 0x1e,
BQ_R_ROC_ADF => 0x27,
BQ_R_WD_ADF => 0x2b,
BQ_ROC_WD_ADF => 0x2d,
R_ROC_WD_ADF => 0x2e,
BQ_R_DF_ADF => 0x33,
BQ_ROC_DF_ADF => 0x35,
R_ROC_DF_ADF => 0x36,
BQ_WD_DF_ADF => 0x39,
R_WD_DF_ADF => 0x3a,
ROC_WD_DF_ADF => 0x3c,
BQ_R_ROC_SPC => 0x47,
BQ_R_WD_SPC => 0x4b,
BQ_ROC_WD_SPC => 0x4d,
R_ROC_WD_SPC => 0x4e,
BQ_R_DF_SPC => 0x53,
BQ_ROC_DF_SPC => 0x55,
R_ROC_DF_SPC => 0x56,
BQ_WD_DF_SPC => 0x59,
R_WD_DF_SPC => 0x5a,
ROC_WD_DF_SPC => 0x5c,
BQ_R_ADF_SPC => 0x63,
BQ_ROC_ADF_SPC => 0x65,
R_ROC_ADF_SPC => 0x66,
BQ_WD_ADF_SPC => 0x69,
R_WD_ADF_SPC => 0x6a,
ROC_WD_ADF_SPC => 0x6c,
BQ_DF_ADF_SPC => 0x71,
R_DF_ADF_SPC => 0x72,
ROC_DF_ADF_SPC => 0x74,
WD_DF_ADF_SPC => 0x78,
____ 5 rules ____
BQ_R_ROC_WD_DF => 0x1f,
BQ_R_ROC_WD_ADF => 0x2f,
BQ_R_ROC_DF_ADF => 0x37,
BQ_R_WD_DF_ADF => 0x3b,
BQ_ROC_WD_DF_ADF => 0x3d,
R_ROC_WD_DF_ADF => 0x3e,
BQ_R_ROC_WD_SPC => 0x4f,
BQ_R_ROC_DF_SPC => 0x57,
BQ_R_WD_DF_SPC => 0x5b,
BQ_ROC_WD_DF_SPC => 0x5d,
R_ROC_WD_DF_SPC => 0x5e,
BQ_R_ROC_ADF_SPC => 0x67,
BQ_R_WD_ADF_SPC => 0x6b,
BQ_ROC_WD_ADF_SPC => 0x6d,
R_ROC_WD_ADF_SPC => 0x6e,
BQ_R_DF_ADF_SPC => 0x73,
BQ_ROC_DF_ADF_SPC => 0x75,
R_ROC_DF_ADF_SPC => 0x76,
BQ_WD_DF_ADF_SPC => 0x79,
R_WD_DF_ADF_SPC => 0x7a,
ROC_WD_DF_ADF_SPC => 0x7c,
____ 6 rules ____
BQ_R_ROC_WD_DF_ADF => 0x3f,
BQ_R_ROC_WD_DF_SPC => 0x5f,
BQ_R_ROC_WD_ADF_SPC => 0x6f,
BQ_R_ROC_DF_ADF_SPC => 0x77,
BQ_R_WD_DF_ADF_SPC => 0x7b,
BQ_ROC_WD_DF_ADF_SPC => 0x7d,
R_ROC_WD_DF_ADF_SPC => 0x7e,
____ 7 rules ____
BQ_R_ROC_WD_DF_ADF_SPC => 0x7f

Data validation - DvSubstMethod

last good => 1,
InitVal => 2,
AltExtItem => 3,
PassThrough => 4,
Follow ROC => 5,
Default => 255

Engineering unit - EU

See ApisDIR/Bin/EngUnit.xml

Item Qualities

When using External Item Data Validation, Apis Hive will mark the item quality with Prediktor-specific qualities when validation fails. In compliance with the OPC DA specification, vendor specific item qualities are supported inside the upper 8 bits of the 16-bit quality word.

Apis uses the following item qualities:

Quality name	Quality value(16 bit word)	Description
bad quality	256	Item value had bad quality
range	257	Item value failed range check
roc	258	Item value failed rate of change check
watchdog	259	Item value failed watchdog check
difference	260	Item value failed difference check
abs difference	261	Item value failed absolute value of difference check
spc unable	262	Item value failed SPC check cause unable to perform check (ie. data conversion failure)
spc 1beyza	263	Item value failed SPC check cause One point beyond zone A
spc 9beycent	264	Item value failed SPC check cause Nine points in a row in zone C or beyond on one side of CL
spc 6incdec	265	Item value failed SPC check cause Six points in a row steadily increasing or decreasing
spc 14altupdo	266	Item value failed SPC check cause Fourteen points in a row alternation up and down
spc 2of3inza	267	Item value failed SPC check cause Two out of three points in a row in zone A or beyond
spc 4of5inzb	268	Item value failed SPC check cause Four out of five points in a row in zone B or beyond
spc 15inzc	269	Item value failed SPC check cause Fifteen points in a row in zone C above or below CL
spc 8outzc	270	Item value failed SPC check cause Eight points in a row on both sides CL with none in zone C

Optional Alarm Configuration

Specify severity by setting the AlmSeverityList attribute.

To specify the alarm text, change the AlmHelp attribute. Different texts can be specified for each sub-condition by adding new texts to the AlmHelp attribute, separated by a semicolon. If no text is given, automatically generated text is sent to clients. If only one set of text is given, it'll be used for all sub-conditions. If more than one text is given they must be positioned in the AlmHelp string as follows:

Event category	Sub condition	AlmHelp text position (1 based)
Discrete	Not normal	2
Discrete	Normal	1
Level	LoLo	5
Level	Lo	4
Level	Hi	3
Level	HiHi	2
Level	Normal	1
Watchdog	Frozen	2
Watchdog	Updating	1
WatchQuality	Good	3
WatchQuality	Uncertain	2
WatchQuality	Bad	1

Events can be delayed for a certain amount of ScanPeriods by setting the AlmActiveDelayPeriods attribute. You might need to add this attribute to your items the same way you added the AlarmAreaEvtCatregory attribute. If the conditions becomes inactive within the delay, no event will be issued.

Predefined Item Properties

The tables below are a summary of the attributes defined by Apis Hive, which may be applied to any item in Apis Hive.

Some Apis Hive attributes have enumerated values, e.g. you may select between a predefined list of attribute values. Check the list of enumerated values and matching integers to get an overview of these attributes.

Internal attributes

Note: These attributes should not be added

ID	Name	Description	Type
5000	Handle	Handle of an item - used when persisting the runtime state.	4 byte integer
5001	TypeID	The type ID of an item.	4 byte integer
5003	ItemID	The name of the item.	string
5002	InitValue	The initial value of an item.	-
5045	InitValueQuality	Initial value quality of an item (only valid when having an InitValue).	-
5046	InitValueTimestamp	Initial value timestamp of an item (only valid when having an InitValue).	-
5047	InitVQTFromHoneystore	If true, the initial value, quality and timestamp will be fetched from the last logged sample in Apis Honeystore.Note! To successfully use this attribute, the item in question must be logged to Honeystore by an ApisLoggerBee module.	Boolean

Alternative value presentations

ID	Name	Description	Type
5004	RawValue	The Raw 32-bit untranslated value.	4 byte integer
5005	Scale	Linear transformation multiplier, a floating-point value.	8 byte real
5006	Offset	Linear transformation addend, floating point value.	8 byte real

Vector and matrix attributes

ID	Name	Description	Type
5007	Dimension	The number of elements for a vector item (vector only)	2 byte unsigned integer
5008	Rows	The number of rows for a matrix item (matrix item only)	2 byte unsigned integer
5009	Columns	The number of columns for a matrix item (matrix item only)	2 byte unsigned integer

Item location attributes

ID	Name	Description	Type
5010	ProcStationID	Process station ID, a 32 bit integer	4 byte integer
5011	ProcArea	Process area	string
5012	Location	General location attribute string	string
5013	Station	Station name	string

Object attributes

ID	Name	Description	Type
5015	ObjectClass	The object class this item belongs to	string
5016	ObjectInstance	The object instance this item belongs to	string
5017	ObjectProperty	The object property this item represents	string

Item bus/network location attributes

ID	Name	Description	Type
5020	Address	Bus/network address 1	4 byte integer
5021	Address2	Bus/network address 2	4 byte integer
5022	Address3	Bus/network address 3	4 byte integer
5023	Address4	Bus/network address 4	4 byte integer
5026	Segment	Bus/network segment number	2 byte integer
5028	SegmentPos	Position within segment	2 byte integer

ID	Name	Description	Type
5030	SrcItemID	Item ID in source (often defaults to Item Name in Apis)	string
5031	SrcUaNodeId	UA NodeID in source, mostly relevant from OPC UA communication modules.	string
5032	InstrumentName	Instrument name	string

ID	Name	Description	Type
5034	Source	The source of the item	string
5035	Table	The table of the item	string
5036	Record	The record of the item	string
5037	Field	The field of the item	string

Directional attributes

ID	Name	Description	Type
5040	Direction	Direction flag, Input when false or Output when true	Boolean

Display attributes

ID	Name	Description	Type
5050	Display	Operator display associated with the item	string
5054	Xpos	X-pos, graphical x-position of the item	4 byte integer
5055	Ypos	Y-pos, graphical y-position of the item	4 byte integer
5056	Width	Width, width of the item	4 byte integer
5057	Height	Height, height of the item	4 byte integer

Device attributes

ID	Name	Description	Type
5060	DevType	Device type	string
5062	DevVendor	Device vendor	string
5064	DevSerNum	Device serial number	string

ID	Name	Description	Type
5070	MaxStringLength	An indication of the maximum length of the value of a string item. Must be used when logging string items to the Apis Honeystore historian, to control how many characters will be stored for each sample.	4 byte integer
5071	MaxCacheDuration	When the item are logged to Apis Honeystore, the maximum duration in seconds, for the item cache when the item is logged by ApisLoggerBee!	4 byte unsigned integer
5080	LowerBound	LBound, The lower bound of items in vector	4 byte real
5081	UpperBound	UBound, The upper bound of items in vector	4 byte real
5090	RowNames	The names of the rows in a vector or matrix, separated by ';'	array of strings
5091	ColNames	The names of the columns in a matrix, separated by ';'	array of strings
5100	ArgumentItem	An item whose value is used to calculate this item	string
5105	FormatString	A general purpose format string, used when applying string formatting to calculate the value of this item.	string
5110	Expression	An expression used to calculate the value of this item	string
5111	Expressions	An array of expressions used to calculate the value of this item	array of string
5130	Rate	An attribute which keeps the value rate	8 byte unsigned integer
5135	Horizon	An attribute which keeps the value horizon	8 byte unsigned integer
5220	Coefficients	Vector of coefficients used for calculation purposes	array of 8 byte real

Composition attributes

ID	Name	Description	Type
5500	Parent	The Item handle of the parent item to this item, an item in the same module as this item.	4 byte integer
5502	ParentItem	The Item name of the parent item to this item, an item in the same module as this item.	string
5505	Aggregate	The item handle of the aggregate this item is part of	4 byte integer
5510	InputItemsLocal	Array of item handles regarded as input-items to this item, only for items in the same module.	array of 4 byte integers
5511	InputItems	Array of item handles regarded as input-items to this item, for items in any module.	array of 4 byte integers
5514	InputFlags	Flags associated with the inputs	array of 4 byte integers
5520	OutputItemsLocal	Array of item handles regarded as output-items from this item, only for items in the same module.	array of 4 byte integers
5521	OutputItems	Array of item handles regarded as output-items from this item, for items in any module.	array of 4 byte integers
5524	OutputFlags	Flags associated with the outputs	array of 4 byte integers

Alarm attributes

ID	Name	Description	Type
5600	AlmSeverity	Severity of alarm associated with this item (according to OPC AE). 1 is the lowest, while 1000 is the highest.	4 byte integer
5610	AlmSeverityList	Severity of alarm associated with this item (according to OPC AE). 1 to 1000 as the allowable range.	string
5630	AlmNormalState	The normal state of a discrete alarm/event (according to OPC AE) associated with this item. A deviation from this value will generate a discrete event.	Variant
5635	AlmActiveDelayPeriods	The number of periods an item is active before an alarm is raised.	2 byte integer
5640	AlmWatchdogPeriods	The max number of periods this item can have the same value before a watchdog alarm is raised.	2 byte integer
5650	AlmInhibitItem	The Item ID of another item whose value will be used to inhibit this alarm if set to true. Changed from a string to a 4 byte unsigned integer at start-up, i.e. 4 byte unsigned integer runtime	string
5652	AlmInhibitOffDelay	The time in milliseconds the alarm inhibit state is delayed before going off	4 byte integer
5653	AlmResetItem	The Item ID of another item, whose value (when true) will reset the alarm of the source when it is inhibitted	string

Chronical attributes

ID	Name	Description	Type
5250	ChronicalEventType	Name of the eventtype to use for new events. This will override the default eventtype generated by the AlarmArea module	string
5252	ChronicalParent	Path to an eventsource to use as the parent source for the item. This will override the default location of the items eventsource	string
5255	ChronicalSourceName	Value of the SourceName field on new events. This will override the default sourcename used by the AlarmArea module	string

General purpose attributes

ID	Name	Description	Type
5800	Text1	General purpose attribute	string
5801	Text2	General purpose attribute	string
5802	Text3	General purpose attribute	string
5803	Text4	General purpose attribute	string
5810	ActivationCount	The number of times this item has been activated	4 byte unsigned integer
5811	ExecutionCount	The number of times this item has been executed	4 byte unsigned integer
5900	UserLev	The user level needed to access this item 0 -255 (BYTE)	2 byte unsigned integer
5940	ExtendedRights	Extended access rights, used to restrict access to items beyond the OPC Item attributes.	1 byte unsigned integer
5950	TypeFlags	This item is protected from users without the required level	4 byte integer

Data validation attributes

ID	Name	Description	Type
5670	DvMethod	The method that decides which data validation tests to use. See "Data Validation Method".	2 byte unsigned integer
5672	DvHiRange	The high limit for a DV range check	8 byte real
5673	DvLoRange	The low limit for a DV range check	8 byte real
5674	DvMaxRoc	The maximum rate of change for a DV rate of change check	8 byte real
5676	DvWdTime	The time limit in seconds for a DV watchdog check	8 byte real
5677	DvCompareItem	The comperand item to use when using any of the difference data-validation methods, ie. The difference is calculated by subtracting the value of the item referenced from the value of the item owning this attribute.	string
5678	DvCompareValue	The compare-value to use when using any of the difference data-validation methods. i.e. If the difference is bigger than the value of this attribute, the data is invalid.	8 byte real
5680	DvSPCUCL	The upper control limit in SPC	8 byte real
5681	DvSPCLCL	The lower control limit in SPC	8 byte real
5682	DvSPCTest	The value assigned causes tests to be performed (multiple selects possible)	string
5683	DvSPCUSL	The upper SPC specification limit item reference, specified as an item reference or value directly.	string
5684	DvSPCLSL	The lower SPC specification limit item reference, specified as an item reference or value directly.	string
5685	DvSPCCL	The central line in SPC, specified as an item reference or value directly. If CL is not specified, UCL and LCL will be used to calculate it.	string
5690	DvSubstMethod	This method decides which data validation substitute value to use, see Data Validation Substitution Method.	2 byte unsigned integer
5692	DvAltExtItem	An alternative external item, to fetch a DV substitute value from	string
5695	DvSuppressAlarm	If true (default behaviour), successive DV alarms of same subcondition are suppressed from being notified to the Alarm server of this Hive instance, ie. suppressed from any AE clients and Alarm database. If false, no DV alarms are suppressed.	Boolean

ID	Name	Description	Type
5960	ExtItemMetaTransfer	An enum deciding what kind of metadata to transfer from source to destination external item(s). EngineeringUnit - The EU and Unit attributes are transferred. Description - The Description attribute is transferred. EURange - The High/Low EU attributes are transferred. InstrumentRange - The High/Low Instrument Range attributes are transferred.	4 byte unsigned integer
5970	MonMethod	The method that decides how external items are monitored. See Pulse Monitoring	2 byte unsigned integer
5971	MonTrueValue	This value is set on the monitoring item if the monitoring method is true	Variant
5972	MonFalseValue	This value is set on the monitoring item if the monitoring method is false	Variant
5980	ExtTransferCtrlMethod	The control method that decides when external items are transferred. See "External Item Data Transfer Control Methods"	2 byte unsigned integer
5982	ExtTransferCtrlItem	The Item ID of another item, whose value will control the transfer of external item values to this item	string
5984	ExtTransferCtrlArgument	The argument to use with the method	string
5986	ExtTransferCtrlInhibitQuality	The quality to set when external item value transfer is inhibited. One of: none=0 quality: bad=65536 quality: uncertain=65600 quality: good=65728 quality: bad:config error=65540 quality: bad:not connected=65544 quality: bad:device failure=65548 quality: bad:sensor failure=65552 quality: bad:last known value=65556 quality: bad:comm failure=65560 quality: bad:out of service=65564 quality: bad:waiting for initial data=65568 quality: uncertain:last usable=65604 quality: uncertain:sensor not accurate=65616 quality: uncertain:engineering units exceeded=65620 quality: uncertain:sub normal=65624 quality: good:local override=65752	4 byte unsigned integer
5990	ExtRowSelect	The vector/matrix row in an external vector/matrix item to copy to this scalar item	2 byte integer
5991	ExtColSelect	The vector/matrix column in an external vector/matrix item to copy to this scalar item	2 byte integer
5994	ExternalItem Filters	One or more item name template(s) to use for connecting many external items. When set not an empty array, this attribute takes control over the external item configuration for its item. This means that upon startup, and when changing this attribute at run-time, an operation is triggered that resolves all matching items and connects them to the as external items. Any existing connections no longer matching the filter(s) are removed. An empty array is ignored, and external items can be configured as if this attribute were not present on the item. To make the ExternalItem Filters perform better, one should avoid having a wildcard ''* in the first part of the filter, before the first '.' separating the item names from its module name part.	array of string
5998	ExtItemPaddingValue	A padding value to be used when assigning missing external item values to an array item, ie. when assigning a source array item of dim 3 to a target item of dim 5	-
5999	ExtItemOverrideMethod	This attribute decides what method to use when assigning a value from an external item, see external item External Item Override Methods	2 byte unsigned integer

External item attributes

ID	Name	Description	Type
20000	ExternalItem1	External Item (Apis item name of the external item which will be automatically copied to this item)	string
85535	ExternalItemMax	Max external item ID	string

PDS Connection attributes

ID	Name	Description	Type
5714	ProcessCell	The PDS Process Cell associated with this item	4 byte integer
5715	ProcessUnitClass	The PDS Process Unit Class associated with this item	4 byte integer
5716	ProcessUnit	The PDS Process Unit associated with this item	4 byte integer
5718	Equipment	The PDS Equipment associated with this item	4 byte integer
5730	Identifier	The PDS Identifier associated with this item	4 byte integer
5732	MaterialDefinition	The PDS Material Definition associated with this item	4 byte integer
5734	MaterialClass	The PDS Material Class associated with this item	4 byte integer
5736	MaterialQuality	The PDS Material Quality associated with this item	4 byte integer
5742	CarrierClass	The PDS Carrier Class associated with this item	4 byte integer
5744	Carrier	The PDS Carrier associated with this item	4 byte integer
5752	DataClass	The PDS Data Class associated with this item	4 byte integer
5754	DataDefinition	The PDS Data Definition associated with this item	4 byte integer
5764	EventSource	The PDS Event Source associated with this item	4 byte integer
5774	EU	The PDS Engineering unit (engineering unit) associated with this item	4 byte integer
5775	GuiEU	The default GUI PDS Engineering Unit associated with this item.	4 byte integer

ID	Name	Description	Type
5300	DEPRECATED_MessageTypeID	DEPRECATED! The MessageTypeID of an ApisMessage	4 byte unsigned integer
5301	DEPRECATED_MessageCategory	DEPRECATED! The MessageCategory of an ApisMessage	4 byte unsigned integer

ID	Name	Description	Type
6000	DEPRECATED_GemVID	DEPRECATED! SECS/GEM Variable ID	4 byte unsigned integer
6001	DEPRECATED_GemVIDClass	DEPRECATED! SECS/GEM Variable Class ID	1 byte unsigned integer
6010	DEPRECATED_GemCEIDTrig	DEPRECATED! SECS/GEM Collection Event ID for item used as trigger. Values below 1000 are reserved for internal usage, and will be ignored on item attributes.	4 byte unsigned integer
6020	DEPRECATED_GemTIDSnd	DEPRECATED! SECS/GEM Terminal ID for equipment generated text	4 byte unsigned integer
6021	DEPRECATED_GemTIDRcv	DEPRECATED! SECS/GEM Terminal ID for host generated text	4 byte unsigned integer
6030	DEPRECATED_GemALID	DEPRECATED! SECS/GEM Alarm ID of an alarm. Values below 1000 are reserved for internal usage, and will be ignored on item attributes.	4 byte unsigned integer
6031	DEPRECATED_GemALCEIDOn	DEPRECATED! SECS/GEM Alarm CEID for an alarm going ON.	4 byte unsigned integer
6032	DEPRECATED_GemALCEIDOff	DEPRECATED! SECS/GEM Alarm CEID for an alarm going OFF.	4 byte unsigned integer

ID	Name	Description	Type
6100	DEPRECATED_IEC104TypeID	DEPRECATED! IEC104 TypeID, used by IEC104 server to expose Apis items, enumeration of supported IEC104 TypeIDs:Not in use=0Single point information[Bool]=1Bitstring 32 bits[Int32,UInt32]=7Measured value[Float32]=13	1 byte unsigned integer

ID	Name	Description	Type
5150	DEPRECATED_HSDimensionID	DEPRECATED! This attribute maps this item value to instances of a Dimension definition in the Apis HoneyStore Indexing database	string
5151	DEPRECATED_HSMeasurementID	DEPRECATED! This attribute maps this item value to instances of a Measurement definition in the Apis HoneyStore Indexing database	string
5152	DEPRECATED_HSLocationID	DEPRECATED! This attribute maps this item value to instances of a Location definition in the Apis HoneyStore Indexing database	string

DataTypes

Although data types are visualized as strings in most places in Apis, it is sometimes necessary to know the code for a data type. The following table is a brief overview, mapping the types to their code value.

Description	Value
Character	16
Unsigned character	17
2 byte integer	2
4 byte integer	3
8 byte integer	20
2 byte unsigned integer	18
4 byte unsigned integer	19
8 byte unsigned integer	21
4 byte real	4
8 byte real	5
Boolean	11
String	8
Date	7
Variant	12
Decimal	14
Error	10
Currency	6
Filetime	64
Array	8192
Vector	4096
Null terminated string	30
Wide null terminated string	31

FileFormats

It is possible to export parts of a configuration to text files.

What can be exported is:

Event - Command configuration

The event-command configuration will be exported to a tab separated text file called ##EventBrokerConfig_<time>.txt. An example of such a file is:

// File generated by Apis Snapins Configuration Export<br />

// ##version:2## (do not modify this line)

##EventBrokerConfiguration## (EventModuleName.EventID CommandModuleName.CommandID)

ApisCalculate 1.8000& ApisCalculate 1.8000

ApisJava1.110 ApisJava1.100

ApisJava1.8000 ApisJava1.8000

ApisJava1.8000 ApisJava1.120

ApisOPC1.8000 ApisOPC1.8000

Java.110 Java.100

Java.8000 Java.8000

The third line indicates that this is configuration for event-commands, and the following lines represent connections between events and commands.

The spaces between the events and command must be tabs.

Modules

There will be one file for each module in the configuration. The files will be named <NameOfModule>_##ModuleProperties_<time>.txt.

An example of such a file is:

// File generated by Apis Configuration Export

// ##version:2## (do not modify this line)

ModuleCLSID {d8e2d2c7-7bd5-4afa-8811-85e863c1d3a0}

ModuleName ApisCalculate 1

ModuleStorageCLSID {4c854c93-c667-11d2-944b-00608cf4c421}

##Module properties##

ExchangeRate TimeReferenceItem ExtItemCalculationSequence ExtItem pass-through quality UpdateInitvalsOnSave PersistValToInitVal Calculation&nbsp TraceToFile

100 200 300 400 1600 1650 1700 1900

0 0 64 False 0 True

The module properties are registered immediately below the <em>##Module properties##</em> line.

The first line contains the name of the property and is not actually used when importing.

The second line contains the ids of the properties.

The third line contains the values of the properties.

Items

There will be one file for each item type in each module. The files will be named <NameOfModule>_<NameOfItemType>_<time>.txt.

An example of such a file is:

// File generated by Apis Configuration Export

// ##version:2## (do not modify this line)

ModuleCLSID {983b4ae2-abb9-11d2-9424-00608cf4c421}

ModuleName ApisWorker1

ModuleStorageCLSID {4c854c93-c667-11d2-944b-00608cf4c421}

ItemType Signal [ID:1]

//##Module properties## (uncomment this and the next three lines to import module properties):

//ExchangeRate TimeReferenceItem ExtItemCalculationSequence ExtItem pass-through quality RandomizeItemAttribs UpdateInitvalsOnSave PersistValToInitVal

//100 200 300 400 1500 1600 1650

//2000 0 64 True False 0

//ItemID Amplitude Waveform Address Period Overidden quality Address2 Bias UALogger2 UALogger Type

0 10001 10002 5020 10004 10100 5021 10005 UALogger2 UALogger

Signal1 600 0 0 60 192 0 10 True False 4

Signal2 600 0 0 60 192 0 20 True False 4

Signal3 700 0 0 60 192 0 30 True False 4

Signal4 700 0 0 60 192 0 20 True False 4

Signal5 800 0 0 60 192 0 10 True False 4

Signal6 800 0 0 60 192 0 13 True False 4

Signal7 900 0 0 60 192 0 14 True False 4

Signal8 900 0 0 60 192 0 15 True False 4

The first part of the file is the same as for the modules, except it also contains a line for the item type, and that module properties are commented out.

The last part is a list of items. The columns are the properties of the item. The first column should always have id 0, and is the name of the item.

The spaces between the events and command must be tabs.

External items

In order for the Apis modules to exchange values, the items defined in Apis may have an attribute called ExternalItem. Exchanging values in the Apis context simply means copying the value of one item from one module to another item (typically in another module).

The ExternalItem attribute(s) is a string that contains the name of the item whose value is to be retrieved. It is always the item that receives the value from another item that defines the external item.

The external item feature in Apis may be utilised in many ways. In addition to raw copy of the value from an external item, functionality such as data validation and pulse trigging is available. Confer the linked topics below for a detailed description.

Apis Online SPC

Apis offers online SPC monitoring of signals as part of the data validation feature, i.e. one of the data validation methods available is SPC.

How to set up a monitoring:

Create an item ("SPC Tag"). Add the following attributes: DvMethod = SPC, DvSPCUCL, DvSPCLCL, DvSPCTest and DvSubstMethod (optional) and set the appropriate values. Make the item you want to monitor ("Signal Tag") an external item to the "SPC Tag".

An alarm is triggered if one or more of the SPC tests fails. The alarm will be logged in the system log, but it is also possible to send it out as an e-mail notification.

SPC Test input codes

The set of SPC tests to apply when performing online SPC on a signal may be configured via the Apis attribute named "DvSPCTest". The table below lists the SPC tests and the code to use as input to "DvSPCTest". It is possible to select multiple tests. In such cases the input codes for the desired tests are entered as a semi colon separated list, e.g. 1;3;4.

Input code	Short description	Description
1	1BEYZA	One point beyond zone A
2	9BEYCENT	Nine points in a row in zone C or beyond on one side of CL
3	6INCDEC	Six points in a row steadily increasing or decreasing
4	14ALTUPDO	Fourteen points in a row alternation up and down
5	2OF3INZA	Two out of three points in a row in zone A or beyond
6	4OF5INZB	Four out of five points in a row in zone B or beyond
7	15INZC	Fifteen points in a row in zone C above or below CL
8	8OUTZC	Eight points in a row on both sides CL with none in zone C

Example zones and control limits

External Item Data Transfer Control

This feature makes it possible to control when an external item’s value shall be transferred to another item. It may not always be the case that we want the value to be transferred regardless of the value. Here we may select between different rules for when a transfer should be carried out depending on the external item value. In addition we may set up the system such that the value is transferred from different external items depending on the value of a third item (MUX).

The following item attributes must be specified:

Attribute ID

Name

Description

Type

5980

ExtTransferCtrlMethod

The control method that decides when external items are transferred to the item of the attribute. One of the following may be selected:

Name	Meaning	Value
always	Always transfer external item values	0
when CtrlItem changes from zero	Transfer once when control item (ExtTransferCtrlItem) value changes from 0	1
when CtrlItem is zero	Transfer when control item (ExtTransferCtrlItem) value = 0	2
when CtrlItem is non zero	Transfer once when control item (ExtTransferCtrlItem) value is != 0	3
when CtrlItem becomes > argument	Transfer once when control item (ExtTransferCtrlItem) value becomes greater than argument value (ExtTransferCtrlArgument)	10
when CtrlItem becomes < argument	Transfer once when control item (ExtTransferCtrlItem) value becomes less than argument value (ExtTransferCtrlArgument)	11
when CtrlItem becomes = argument	Transfer once when control item (ExtTransferCtrlItem) value becomes equal argument value (ExtTransferCtrlArgument)	12
when CtrlItem becomes <> argument	Transfer once when control item (ExtTransferCtrlItem) value becomes different argument value (ExtTransferCtrlArgument)	13
when CtrlItem > argument	Transfer once when control item (ExtTransferCtrlItem) value is greater than argument value (ExtTransferCtrlArgument)	20
when CtrlItem < argument	Transfer once when control item (ExtTransferCtrlItem) value is less than argument value (ExtTransferCtrlArgument)	21
when CtrlItem = argument	Transfer once when control item (ExtTransferCtrlItem) value is equal to argument value (ExtTransferCtrlArgument)	22
when CtrlItem <> argument	Transfer once when control item (ExtTransferCtrlItem) value is different from argument value (ExtTransferCtrlArgument)	23

2 byte unsigned integer

5982

ExtTransferCtrlItem

The Item ID of another item, whose value will control the transfer of external item values to this item

5984

ExtTransferCtrlArgument

The argument to use with the ExtTransferCtrlMethod

5986

ExtTransferCtrlInhibitQuality

(Note that not all item-types
will have this functionality
implemented)

The quality to set when external item value transfer is inhibited, as a result of the chosen ExtTransferCtrlMethod. When other than none, data is still transferred during control method failure. When none, data transfer stops during control method failure.
The attribute is enumerated, with the following options:

Name	Meaning	Value
none	Quality is not set/altered upon control method failure, but data transfer is inhibited	0
quality: bad	Quality is set to this value upon control method failure, but data is still transferred	65536
quality: uncertain	Quality is set to this value upon control method failure, but data is still transferred	65600
quality: good	Quality is set to this value upon control method failure, but data is still transferred	65728
quality: bad:config error	Quality is set to this value upon control method failure, but data is still transferred	65540
quality: bad:not connected	Quality is set to this value upon control method failure, but data is still transferred	65544
quality: bad:device failure	Quality is set to this value upon control method failure, but data is still transferred	65548
quality: bad:sensor failure	Quality is set to this value upon control method failure, but data is still transferred	65552
quality: bad:last known value	Quality is set to this value upon control method failure, but data is still transferred	65556
quality: bad:comm failure	Quality is set to this value upon control method failure, but data is still transferred	65560
quality: bad:out of service	Quality is set to this value upon control method failure, but data is still transferred	65564
quality: bad:waiting for initial data	Quality is set to this value upon control method failure, but data is still transferred	65568
quality: uncertain:last usable	Quality is set to this value upon control method failure, but data is still transferred	65604
quality: uncertain:sensor not accurate	Quality is set to this value upon control method failure, but data is still transferred	65616
quality: uncertain:engineering units exceeded	Quality is set to this value upon control method failure, but data is still transferred	65620
quality: uncertain:sub normal	Quality is set to this value upon control method failure, but data is still transferred	65624
quality: good:local override	Quality is set to this value upon control method failure, but data is still transferred	65752

4 byte unsigned integer

Note: The module property ExtItemCalculationSequence is important in data validation and transfer. It decides whether data validation or data transfer will be performed first in the external item manager. Available values: TransferBeforeValidation, ValidationBeforeTransfer.

Alternatively

ExtItemOverrideMethod. This attribute decides what method to use when assigning a value from an external item. One of the following may be selected: “Default” or “Assign complete value from external item”.

External Item Data Validation

This feature makes it possible to perform various data validations of data values on Apis external items before making use of the data. An alarm is triggered when a data validation fails. The alarm will be logged in the system log, but it is also possible to send it out as an e-mail notification. When a validation fails, the invalid data may be substituted according to different rules.

The data-validation is performed when the value of the item connected as the external item changes. When an item fails a data-validation check, the quality of the item will include some Apis specific quality information, see Apis Vendor Specific Item Qualities for details.

Data-validation methods

Apis supports the following data validation methods:

Data validation method	Abbreviation	Value*	Description	Related item attribute(s)
None	None / 0	0
Bad quality	BQ / 1	1	Validation fails when the quality of the item becomes bad
Range	R /	2	Validation fails when the value of the item violates a range check	DvHiRange, DvLoRange
Rate of change	ROC	4	Validation fails when the value of the item changes to fast	DvMaxRoc
Watchdog	WD	8	Validation fails when the value of the item stops updating	DvWdTime
Difference	DF	16	Validation fails when the difference of the value of the item compared to the value of an other item is too big	DvCompareValue, DvCompareItem
Absolute difference	ADF	32	Validation fails when the absolute value of the difference of the value of the item compared to the value of an other item is too big	DvCompareValue, DvCompareItem
SPC	SPC	64	Any of the supported SPC tests, see Apis Online SPC.	DvSPCTest, DvSPCLCL, DvSPCUCL

*) When using File-add, the values of the desired DV methods must be OR-ed together. Eg: R | ROC = 6

The following item attributes are used in data validation:

Name

Description

Type

5670

DvMethod

The method that decides which data validation tests to use. Any combination the following is possible: None, BQ, R, ROC, WD, DF, ADF, SPC.

2 byte unsigned integer

5672

DvHiRange

The high limit for DV range check.

5673

DvLoRange

The low limit for DV range check.

5674

DvMaxRoc

The maximum rate of change for DV rate of change check.

5676

DvWdTime

The time limit in seconds for DV watch dog check.

5677

DvCompareItem

An external item used by data-validation methods DF and/or ADF, when comparing values.

5678

DvCompareValue

The value to compare the difference with, when using data-validation methods DF and/or ADF

5680

DvSPCUCL

The upper control limit in SPC.

5681

DvSPCLCL

The lower control limit in SPC.

5682

DvSPCTest

The assignable causes tests to perform (multiple selects possible, e.g. 1;3;4). 1 - 1BEYZA, 2 - 9BEYCENT, 3 - 6INCDEC, 4 - 14ALTUPDO, 5 - 2OF3INZA, 6 - 4OF5INZB, 7 - 15INZC, 8 - 8OUTZC. Test codes explained.

5690

DvSubstMethod

The method that decides which data validation substitute value to use. One of the following may be selected:

Name	Meaning	Value
last good	Substitute with last good value when data validation fails	1
InitVal	Substitute with InitVal attribute when data validation fails. If no InitVal is associated with the item, it uses the last good value	2
AltExtItem	Substitute with an alternative external item (DvAltExtItem). If no alternative external item can be obtained, it uses the last good value	3
PassThrough	No substitution occurs, external item is passed through as if no validation failed	4
Follow ROC	Substitute with a value that increases/decreases with a rate of change limitation according to the maximum rate of change (DvMaxRoc).	5
Default	First, value is substituted after a Follow ROC strategy, if DvMethod specifies ROC. Then, if DvMethod specifies Range, a range check validation is performed. If Range-chack fails, an AltExtItem substitution is performed if an DvAltExtItem is specifed. If none of the above mentioned substitution occurs, the default substitution is last good..	255

2 byte unsigned integer

5691

DvSubstQuality

The quality to use when data validation substitution takes place. This attribute lets the user control the quality for item values when Data Validation substitution takes place, the quality can be overridden to bad, uncertain or good, by specifying the desired quality using the DvSubstQuality attribute.

The APIS Vendor specific quality bits, telling what violation is broken , will still be added to the quality. I.e. when using Range validation, the quality of the item during a violated state is decided according to the table below, but with Apis Vendor quality range added to the quality.

Name	Meaning	Value
Default	The quality follows the quality of the source item, with any with Apis Vendor quality violation state added to it.	255
Bad	The quality is always set to bad, with any with Apis Vendor quality violation state added to it.	0
Uncertain	The quality is always set to uncertain, with any with Apis Vendor quality violation state added to it.	64
Good	The quality is always set to good, with any with Apis Vendor quality violation state added to it.	192

unsigned character

5692

DvAltExtItem

An alternative external item to fetch a DV substitute value from. Used when 'DvSubstMethod'='AltExtItem'.