AggreGate Documentation

2000-2013 Tibbo Technology Inc.

AggreGate Documentation

Table of Contents
Foreword 0

Part I Introduction
1 About ................................................................................................................................... This Manual 2 About ................................................................................................................................... Tibbo Technology Inc. 3 Copyright ................................................................................................................................... Notice 4 Documentation ................................................................................................................................... Feedback 5 Quick ................................................................................................................................... Start Guide 6 License ................................................................................................................................... Issues

27
27 28 28 28 28 29

Part II System Basics

1 Primary ................................................................................................................................... AggreGate Features 2 Connecting ................................................................................................................................... Your Devices 3 Benefits ................................................................................................................................... of AggreGate 4 System ................................................................................................................................... Components 5 Unified ................................................................................................................................... Data Model 6 Managing ................................................................................................................................... Your Devices 7 Enterprise ................................................................................................................................... Integration 8 AggreGate ................................................................................................................................... Customization

30
30 31 34 35 36 37 39 39

Part III AggreGate Server

1 Requirements ................................................................................................................................... 2 Deployment ................................................................................................................................... and Administration

40
40 43

Installing ......................................................................................................................................................... AggreGate Server 43 Installation.................................................................................................................................................. 43 Upgrade .................................................................................................................................................. 43 Uninstallation .................................................................................................................................................. 44 Startup and ......................................................................................................................................................... Shutdown 44 Service Mode .................................................................................................................................................. 46 Command.................................................................................................................................................. Line Parameters 47 Shutting Down .................................................................................................................................................. The Server 47 Net Admin.................................................................................................................................................. 49 Net Admin ........................................................................................................................................... and Startup Script Command Reference 49 Startup Scripts .................................................................................................................................................. 50 Configuration ......................................................................................................................................................... 51 Server Configurator .................................................................................................................................................. 51 Client-based .................................................................................................................................................. Configuration 51 File-based.................................................................................................................................................. Configuration 52 Global Configuration .................................................................................................................................................. Options 53 General Settings ........................................................................................................................................... 53 Database ........................................................................................................................................... 55 Cluster ........................................................................................................................................... 59 Web Applications ........................................................................................................................................... 59

2000-2013 Tibbo Technology Inc.

Contents

Dynamic DNS ........................................................................................................................................... 61 Mail Settings ........................................................................................................................................... 63 Advanced Mail ........................................................................................................................................... Settings 65 SMS Sending ........................................................................................................................................... 69 Event Processing ........................................................................................................................................... Rules 70 Custom Event ........................................................................................................................................... Writers 72 Default User ........................................................................................................................................... Permissions 73 Additional Permissions ........................................................................................................................................... For New Users 73 Default Synchronization ........................................................................................................................................... Options 73 Statistics ........................................................................................................................................... 73 Active Plugins ........................................................................................................................................... 74 Logging ......................................................................................................................................................... 74 Logging Configuration .................................................................................................................................................. File 74 Logging Categories .................................................................................................................................................. 76 Logging Levels .................................................................................................................................................. 79 Logging Framework .................................................................................................................................................. Documentation Sources 80 Database ......................................................................................................................................................... 80 Switching .................................................................................................................................................. To Another Database Engine 81 Switching Database ........................................................................................................................................... To MySQL 82 Switching Database ........................................................................................................................................... To Microsoft SQL Server 84 Switching Database ........................................................................................................................................... To Oracle 84 Switching Database ........................................................................................................................................... To PostgreSQL 84 Switching Database ........................................................................................................................................... To Firebird 85 Database .................................................................................................................................................. Converter 85 Database Schema .................................................................................................................................................. and Interaction 85 Database Performance .................................................................................................................................................. Tuning 87 Failover Cluster ......................................................................................................................................................... 87 Database Failover .................................................................................................................................................. 89 AggreGate-Based ........................................................................................................................................... Database Replication 91 Database...................................................................................................................................... Cluster Configuration File 92 Native Database ........................................................................................................................................... Replication 93 Sharing Single ........................................................................................................................................... Database 94 AggreGate .................................................................................................................................................. Server Failover 95 Distributed ......................................................................................................................................................... Operations 99 Distributed .................................................................................................................................................. Architecture Contepts 100 Distributed .................................................................................................................................................. Architecture Configuration 101 Configuring .................................................................................................................................................. Providers 102 Configuring .................................................................................................................................................. Consumers 103 Distributed .................................................................................................................................................. Server Status 103 Permissions .................................................................................................................................................. in Distrubuted Environment 103 Data Backup ......................................................................................................................................................... and Restoration 104 Moving AggreGate ......................................................................................................................................................... Server Installation 105 Safe Mode ......................................................................................................................................................... 106 Managing ......................................................................................................................................................... Pre-Built Resources 107 System Tray ......................................................................................................................................................... Menu 108 Dealing with ......................................................................................................................................................... Time Zones 108

3 Users ...................................................................................................................................

108

Default Administator ......................................................................................................................................................... 109 User Account ......................................................................................................................................................... Management 109 User Self-Registration ......................................................................................................................................................... 109 User Account ......................................................................................................................................................... Configuration 110 Properties .................................................................................................................................................. 110 Account Settings .................................................................................................................................................. 111 Resources .................................................................................................................................................. 111

2000-2013 Tibbo Technology Inc.

AggreGate Documentation
User Photo .................................................................................................................................................. 111 Permissions .................................................................................................................................................. 111 Alerts .................................................................................................................................................. 112 User Account ......................................................................................................................................................... Status 112 Resetting......................................................................................................................................................... User Account Password 112 Suspending ......................................................................................................................................................... User Accounts 112 Users in ......................................................................................................................................................... Distributed Architecture 112

4 Devices ...................................................................................................................................

113

Device Metadata ......................................................................................................................................................... 113 Device Assets ......................................................................................................................................................... 113 Device Variables ......................................................................................................................................................... (Settings) 114 Device Snapshots .................................................................................................................................................. (Settings Cache) 115 Settings Synchronization .................................................................................................................................................. Options 115 Settings Synchronization .................................................................................................................................................. Status 117 Device Setting .................................................................................................................................................. Statistics 117 Master Values .................................................................................................................................................. of Device Settings 120 Device Functions ......................................................................................................................................................... (Operations) 120 Device Events ......................................................................................................................................................... 121 Adding New ......................................................................................................................................................... Devices 121 Generic Device ......................................................................................................................................................... Properties 123 Synchronization ......................................................................................................................................................... 126 Device Status ......................................................................................................................................................... 127 Device Location ......................................................................................................................................................... Tracking 128 Device Performance ......................................................................................................................................................... 129

5 Device ................................................................................................................................... Drivers

129

AggreGate ......................................................................................................................................................... Agent 130 BACnet ......................................................................................................................................................... 133 URL Monitor ......................................................................................................................................................... (HTTP) 139 JMX (Java ......................................................................................................................................................... Management Extensions) 140 Local File ......................................................................................................................................................... 143 Local Folder ......................................................................................................................................................... 144 Modbus ......................................................................................................................................................... 145 Modem ......................................................................................................................................................... 148 Network ......................................................................................................................................................... Host 150 Ping Monitoring .................................................................................................................................................. 153 Ping Settings ........................................................................................................................................... 153 Ping Monitoring ........................................................................................................................................... Results 153 SNMP Monitoring .................................................................................................................................................. 154 Generic TCP .................................................................................................................................................. Service Monitoring 154 Generic TCP ........................................................................................................................................... Service Settings 154 Generic TCP ........................................................................................................................................... Service Monitoring Results 155 Generic UDP .................................................................................................................................................. Service Monitoring 155 Generic UDP ........................................................................................................................................... Service Settings 155 Generic UDP ........................................................................................................................................... Service Monitoring Results 155 HTTP Server .................................................................................................................................................. Monitoring 156 DNS Server .................................................................................................................................................. Monitoring 156 DNS Service ........................................................................................................................................... Settings 156 DNS Monitoring ........................................................................................................................................... Results 156 POP3 Server .................................................................................................................................................. Monitoring 157 POP3 Service ........................................................................................................................................... Settings 157 POP3 Monitoring ........................................................................................................................................... Results 157 IMAP Server .................................................................................................................................................. Monitoring 158 IMAP Service ........................................................................................................................................... Settings 158 IMAP Monitoring ........................................................................................................................................... Results 158

2000-2013 Tibbo Technology Inc.

Contents

SMTP Server .................................................................................................................................................. Monitoring 158 SMTP Service ........................................................................................................................................... Settings 159 SMTP Monitoring ........................................................................................................................................... Results 159 E-mail Round-Trip .................................................................................................................................................. Monitoring 159 E-mail Round-Trip ........................................................................................................................................... Service Settings 159 E-mail Round-Trip ........................................................................................................................................... Monitoring Results 160 FTP Server .................................................................................................................................................. Monitoring 160 FTP Service ........................................................................................................................................... Settings 160 FTP Monitoring ........................................................................................................................................... Results 161 Traceroute .................................................................................................................................................. Monitoring 161 Traceroute ........................................................................................................................................... Service Settings 162 Traceroute ........................................................................................................................................... Monitoring Results 162 SSH Server .................................................................................................................................................. Monitoring 163 SSH Service ........................................................................................................................................... Settings 163 SSH Monitoring ........................................................................................................................................... Results 164 SSH Operations ........................................................................................................................................... 164 DHCP Monitoring .................................................................................................................................................. 164 DHCP Service ........................................................................................................................................... Settings 164 DHCP Monitoring ........................................................................................................................................... Results 165 LDAP Monitoring .................................................................................................................................................. 165 LDAP Service ........................................................................................................................................... Settings 165 LDAP Monitoring ........................................................................................................................................... Results 165 Radius Monitoring .................................................................................................................................................. 166 Radius Service ........................................................................................................................................... Settings 166 Radius Monitoring ........................................................................................................................................... Results 166 WMI Monitoring .................................................................................................................................................. 166 NMEA 0183 ......................................................................................................................................................... 166 OPC (OLE ......................................................................................................................................................... for Process Control) 168 SMB/CIFS ......................................................................................................................................................... (Shared Resource Monitoring) 171 SNMP (Simple ......................................................................................................................................................... Network Management Protocol) 173 Network Host .................................................................................................................................................. SNMP Polling 175 SNMP Polling ........................................................................................................................................... Settings 176 SNMP Polling ........................................................................................................................................... Results 176 SNMP Notifications .................................................................................................................................................. Monitoring 178 SNMP Notifications ........................................................................................................................................... Monitoring Global Configuration 178 SNMP Notifications ........................................................................................................................................... Sources Automatic Discovery 178 SNMP Global .................................................................................................................................................. Settings 178 MIB Files Directory ........................................................................................................................................... 178 SNMP User ........................................................................................................................................... Table 179 SQL Database ......................................................................................................................................................... 180 Virtual Device ......................................................................................................................................................... 182 WebSphere ......................................................................................................................................................... MQ 184 WMI (Windows ......................................................................................................................................................... Management Instrumentation) 186 Configuring .................................................................................................................................................. Remote Access to WMI 189 Mass-enabling .................................................................................................................................................. Remote Access to WMI 190 WMI Configuration ........................................................................................................................................... Script 200 WMI Network ........................................................................................................................................... Scanning 203

6 Event ................................................................................................................................... Filters

206

Filter Expressions ......................................................................................................................................................... 207 Event Highlighting ......................................................................................................................................................... 210 Event Filter ......................................................................................................................................................... Configuration 211 Filter Properties .................................................................................................................................................. 211 Filter Rules .................................................................................................................................................. 211 Primary Visible .................................................................................................................................................. Fields 212

2000-2013 Tibbo Technology Inc.

AggreGate Documentation
Additional .................................................................................................................................................. Visible Fields 212 Custom Highlighting .................................................................................................................................................. 213 History Browser .................................................................................................................................................. Settings 213 Parameterized ......................................................................................................................................................... Filters 213 Build-In Filters ......................................................................................................................................................... 215 Event Filters ......................................................................................................................................................... in Distributed Architecture 216

7 Alerts ...................................................................................................................................

216

Variable ......................................................................................................................................................... Triggers 217 Event Triggers ......................................................................................................................................................... 222 Alert Event ......................................................................................................................................................... 224 Notifications ......................................................................................................................................................... 225 Corrective ......................................................................................................................................................... Actions 227 Action Parameter .................................................................................................................................................. Processing 228 Alert Acknowledgement ......................................................................................................................................................... 228 Alert Configuration ......................................................................................................................................................... 229 Alert Properties .................................................................................................................................................. 229 Event Triggers .................................................................................................................................................. 230 Variable Triggers .................................................................................................................................................. 230 Notification .................................................................................................................................................. Settings 231 Escalation .................................................................................................................................................. Settings 232 Automatic .................................................................................................................................................. Corrective Actions 232 Interactive .................................................................................................................................................. Corrective Actions 233 Alert States ......................................................................................................................................................... 233 Alert Lifecycle ......................................................................................................................................................... 234 Active Instances ......................................................................................................................................................... 235 Pending ......................................................................................................................................................... Instances 236 Alert Escalation ......................................................................................................................................................... 237 Alerts Security ......................................................................................................................................................... 237 Alerts Performance ......................................................................................................................................................... 238 Alert Examples ......................................................................................................................................................... 238 Alerts in ......................................................................................................................................................... Distributed Architecture 240

8 Reports ...................................................................................................................................

241

Source Data ......................................................................................................................................................... Expression 241 Report Template ......................................................................................................................................................... 242 Report Types ......................................................................................................................................................... 242 Launching ......................................................................................................................................................... Reports 242 Viewing ......................................................................................................................................................... Reports 244 Report Configuration ......................................................................................................................................................... 245 Report Properties .................................................................................................................................................. 245 Additional .................................................................................................................................................. Report Parameters 245 Parameterized ......................................................................................................................................................... Reports 246 Reports ......................................................................................................................................................... Security 246 Reports ......................................................................................................................................................... Performance 247 Built-in Reports ......................................................................................................................................................... 247

9 Groups ...................................................................................................................................

248

Managing ......................................................................................................................................................... Group Members 249 Group Types ......................................................................................................................................................... 249 Batch Member ......................................................................................................................................................... Operations 249 Dynamic ......................................................................................................................................................... Groups 250 Group Status ......................................................................................................................................................... 250 Member ......................................................................................................................................................... Properties Replication 252 Group Member ......................................................................................................................................................... Context Masks 252 Group Configuration ......................................................................................................................................................... 253

2000-2013 Tibbo Technology Inc.

Contents

Group Properties .................................................................................................................................................. 253 Group Status .................................................................................................................................................. 253 Replication .................................................................................................................................................. Options 254 Groups Security ......................................................................................................................................................... 254 Groups ......................................................................................................................................................... Performance 255 Master Values ......................................................................................................................................................... of Member Properties 255 Groups in ......................................................................................................................................................... Distributed Architecture 256

10 Trackers ...................................................................................................................................

257

Tracker Status ......................................................................................................................................................... 257 Tracker ......................................................................................................................................................... Configuration 258 Tracker Properties .................................................................................................................................................. 258 Status Table .................................................................................................................................................. 258 Tracker Statistics ......................................................................................................................................................... 259 Trackers ......................................................................................................................................................... Security 259 Trackers ......................................................................................................................................................... Performance 259 Tracker Examples ......................................................................................................................................................... 260 Built-In Trackers ......................................................................................................................................................... 260 Trackers ......................................................................................................................................................... in Distributed Architecture 260

11 Common ................................................................................................................................... Data

260

Uses of Common ......................................................................................................................................................... Data 261 Custom Data .................................................................................................................................................. Storage 261 Custom Properties .................................................................................................................................................. 261 Master Properties .................................................................................................................................................. of Devices 262 Master Properties .................................................................................................................................................. of Group Members 263 Common ......................................................................................................................................................... Table Contents 263 Common ......................................................................................................................................................... Table Configuration 264 Common.................................................................................................................................................. Table Properties 264 Common.................................................................................................................................................. Table Fields 264 Custom Properties .................................................................................................................................................. 265 Common ......................................................................................................................................................... Table Record Permissions 265 Common ......................................................................................................................................................... Data Performance 266

12 Scheduled ................................................................................................................................... Jobs

266

Job Triggers ......................................................................................................................................................... 267 Action Parameter ......................................................................................................................................................... Processing 269 Job Configuration ......................................................................................................................................................... 270 Job Properties .................................................................................................................................................. 270 Simple Schedule .................................................................................................................................................. 270 Advanced .................................................................................................................................................. Schedule 270 Jobs Security ......................................................................................................................................................... 271 Jobs Performance ......................................................................................................................................................... 271

13 Queries ...................................................................................................................................

271

Context ......................................................................................................................................................... References 274 Field References ......................................................................................................................................................... 277 Query Configuration ......................................................................................................................................................... 278 Debugging ......................................................................................................................................................... Queries 278 Query Executor ......................................................................................................................................................... Widget 280 Editable Query ......................................................................................................................................................... Results 280 Parameterized ......................................................................................................................................................... Queries 282 Queries ......................................................................................................................................................... Performance 283 Query Examples ......................................................................................................................................................... 284 Query Language ......................................................................................................................................................... Syntax 299 Query Language ......................................................................................................................................................... Functions 300

2000-2013 Tibbo Technology Inc.

AggreGate Documentation 14 Models ................................................................................................................................... 303

Model Types ......................................................................................................................................................... 304 Model Lifecycle ......................................................................................................................................................... 305 Model Rules ......................................................................................................................................................... 305 Rule Set .................................................................................................................................................. Types 306 Sequential ........................................................................................................................................... Rule Sets 306 Dependent ........................................................................................................................................... Rule Sets 307 Referring .................................................................................................................................................. Rule Sets 307 Model Bindings ......................................................................................................................................................... 307 Model Configuration ......................................................................................................................................................... 307 Model Properties .................................................................................................................................................. 307 Model Variables .................................................................................................................................................. 308 Model Variable ........................................................................................................................................... Statistics 309 Model Functions .................................................................................................................................................. 309 Model Events .................................................................................................................................................. 309 Rule Sets .................................................................................................................................................. 310 Bindings .................................................................................................................................................. 311 Models Security ......................................................................................................................................................... 311 Models ......................................................................................................................................................... Performance 312

15 Widgets ...................................................................................................................................

312

Creating ......................................................................................................................................................... Widgets 314 Widget Template ......................................................................................................................................................... 314 Widget Types ......................................................................................................................................................... 314 Widget Default ......................................................................................................................................................... Context 315 Widget Configuration ......................................................................................................................................................... 315 Launching ......................................................................................................................................................... Widgets 316 Widget Input .................................................................................................................................................. Parameters 317 Widget Execution .................................................................................................................................................. 317 Widget Layout ......................................................................................................................................................... 318 Grid Layout .................................................................................................................................................. 318 Absolute.................................................................................................................................................. Layout 322 Components ......................................................................................................................................................... 322 Label .................................................................................................................................................. 323 Text Field .................................................................................................................................................. 325 Password .................................................................................................................................................. Field 326 Formatted .................................................................................................................................................. Text Field 328 List .................................................................................................................................................. 331 Text Area .................................................................................................................................................. 332 HTML Area .................................................................................................................................................. 334 Button .................................................................................................................................................. 334 Toggle Button .................................................................................................................................................. 337 Radio Button .................................................................................................................................................. 339 Check Box .................................................................................................................................................. 340 Combo Box .................................................................................................................................................. 340 Date/Time .................................................................................................................................................. Picker 341 Data Table .................................................................................................................................................. Editor 344 Event Log .................................................................................................................................................. 345 Slider .................................................................................................................................................. 347 Spinner .................................................................................................................................................. 348 Progress.................................................................................................................................................. Bar 349 Image .................................................................................................................................................. 350 Vector Drawing .................................................................................................................................................. 352 Creating Dynamic ........................................................................................................................................... Vector Images 355 Video Player .................................................................................................................................................. 358

2000-2013 Tibbo Technology Inc.

Contents

Meter .................................................................................................................................................. 360 Compass .................................................................................................................................................. 362 Map .................................................................................................................................................. 364 Device .................................................................................................................................................. 367 Graph .................................................................................................................................................. 369 LED Display .................................................................................................................................................. 374 Button Group .................................................................................................................................................. 375 Containers ......................................................................................................................................................... 376 Root Panel .................................................................................................................................................. 376 Panel .................................................................................................................................................. 378 Tabbed Panel .................................................................................................................................................. 379 Split Panel .................................................................................................................................................. 381 Layered Panel .................................................................................................................................................. 382 Subwidget .................................................................................................................................................. 382 Charts ......................................................................................................................................................... 384 Building Chart .................................................................................................................................................. Dataset 385 Custom Data ........................................................................................................................................... 388 Events-based ........................................................................................................................................... Charts 392 Variables-based ........................................................................................................................................... Charts 393 Variable...................................................................................................................................... Series Propagation 393 Variable...................................................................................................................................... Series Types 393 Statistics-Based ...................................................................................................................................... Series 394 Trending ........................................................................................................................................... 395 Debugging .................................................................................................................................................. Charts 397 Category.................................................................................................................................................. Charts 397 Line Chart ........................................................................................................................................... 397 Area Chart ........................................................................................................................................... 401 Bar Chart........................................................................................................................................... 404 Interval Bar ........................................................................................................................................... Chart 415 Statistical........................................................................................................................................... Chart 417 Gantt Chart ........................................................................................................................................... 419 Mixed Category ........................................................................................................................................... Chart 422 Combined ........................................................................................................................................... Domain Category Chart 425 Combined ........................................................................................................................................... Range Category Chart 427 XY Charts .................................................................................................................................................. 429 XY Line Chart ........................................................................................................................................... 429 XY Area Chart ........................................................................................................................................... 436 XY Bar Chart ........................................................................................................................................... 440 Interval Chart ........................................................................................................................................... 449 Error Chart ........................................................................................................................................... 450 Deviation ........................................................................................................................................... Chart 453 Vector Chart ........................................................................................................................................... 455 Bubble Chart ........................................................................................................................................... 457 Financial Chart ........................................................................................................................................... 459 Block Chart ........................................................................................................................................... 463 Mixed XY........................................................................................................................................... Chart 469 Combined ........................................................................................................................................... Domain XY Chart 472 Combined ........................................................................................................................................... Range XY Chart 475 Other Charts .................................................................................................................................................. 478 Spider Chart ........................................................................................................................................... 478 Polar Chart ........................................................................................................................................... 481 Pie Chart ........................................................................................................................................... 485 Ring Chart ........................................................................................................................................... 486 Composite .................................................................................................................................................. Charts 488

2000-2013 Tibbo Technology Inc.

10

AggreGate Documentation
Chart Common .................................................................................................................................................. Properties 489 Axis ........................................................................................................................................... 490 Category ...................................................................................................................................... Axis 491 Extended ...................................................................................................................................... Category Axis 493 Value Axis ...................................................................................................................................... 493 Number...................................................................................................................................... Axis 495 Date Axis ...................................................................................................................................... 495 Period Axis ...................................................................................................................................... 496 Logarithmic ...................................................................................................................................... Axis 497 Symbol Axis ...................................................................................................................................... 497 Block Frame ........................................................................................................................................... 498 Image Subtitle ........................................................................................................................................... 498 Item Label ........................................................................................................................................... Position 499 Legend ........................................................................................................................................... 500 Legend Item ...................................................................................................................................... 501 Marker ........................................................................................................................................... 501 Category ...................................................................................................................................... Marker 504 Value Marker ...................................................................................................................................... 505 Interval Marker ...................................................................................................................................... 505 Rectangle ........................................................................................................................................... Insets 506 Title ........................................................................................................................................... 506 Chart Common .................................................................................................................................................. Events 507 Chart Plots .................................................................................................................................................. 509 Category Plot ........................................................................................................................................... 511 Line Annotation ...................................................................................................................................... 517 Text Annotation ...................................................................................................................................... 518 Pointer Annotation ...................................................................................................................................... 519 Item Label ...................................................................................................................................... Generator 520 Tool Tip ...................................................................................................................................... Generator 520 XY Plot ........................................................................................................................................... 521 Box Annotation ...................................................................................................................................... 528 Data Image ...................................................................................................................................... Annotation 529 Image Annotation ...................................................................................................................................... 529 Item Label ...................................................................................................................................... Generator 530 Legend Annotation ...................................................................................................................................... 530 Line Annotation ...................................................................................................................................... 531 Pointer Annotation ...................................................................................................................................... 532 Polygon...................................................................................................................................... Annotation 533 Shape Annotation ...................................................................................................................................... 534 Text Annotation ...................................................................................................................................... 534 Title Annotation ...................................................................................................................................... 535 Tool Tip ...................................................................................................................................... Generator 535 Pie Plot ........................................................................................................................................... 536 Chart Renderers .................................................................................................................................................. 542 Category Renderer ........................................................................................................................................... 548 Category ...................................................................................................................................... Bar Renderer 549 Category ...................................................................................................................................... Line Renderer 552 XY Renderer ........................................................................................................................................... 554 XY Line ...................................................................................................................................... Renderer 556 Gauges ......................................................................................................................................................... 557 Simple Gauge .................................................................................................................................................. 558 Simple Arc .................................................................................................................................................. Gauge 563 Radial Gauge .................................................................................................................................................. 568 Radial Bargraph .................................................................................................................................................. Gauge 568

2000-2013 Tibbo Technology Inc.

Contents

11

Arc Gauge .................................................................................................................................................. 569 Half-Round .................................................................................................................................................. Gauge 570 Quarter-Round .................................................................................................................................................. Gauge 570 Linear Gauge .................................................................................................................................................. 571 Linear Bargraph .................................................................................................................................................. Gauge 572 Counter Gauge .................................................................................................................................................. 573 Gauge Common .................................................................................................................................................. Properties 573 Radial Gauge ........................................................................................................................................... Common Properties 584 Component ......................................................................................................................................................... Properties 586 Custom Properties .................................................................................................................................................. 588 Border .................................................................................................................................................. 588 Font .................................................................................................................................................. 590 Paint .................................................................................................................................................. 590 Stroke .................................................................................................................................................. 593 Shape .................................................................................................................................................. 594 Component ......................................................................................................................................................... Events 595 Mouse Event .................................................................................................................................................. 598 Keyboard .................................................................................................................................................. Event 599 Bindings......................................................................................................................................................... 604 Binding Properties .................................................................................................................................................. 604 Binding Target .................................................................................................................................................. 605 Binding Expression .................................................................................................................................................. 606 Binding Activator .................................................................................................................................................. 607 Binding Condition .................................................................................................................................................. 607 Binding Performance .................................................................................................................................................. 607 Binding Examples .................................................................................................................................................. 608 Widget Scripts ......................................................................................................................................................... 610 Widget Event ......................................................................................................................................................... Log 613 Widgets ......................................................................................................................................................... Security 614 Widgets ......................................................................................................................................................... Performance 614 Widget Examples ......................................................................................................................................................... 614 Widget Player ......................................................................................................................................................... 614 Web Widget ......................................................................................................................................................... Player 615 Device Maps ......................................................................................................................................................... 616 Touchscreen ......................................................................................................................................................... Support 616

16 Dashboards ...................................................................................................................................

617

Dashboard ......................................................................................................................................................... Layouts 618 Dashboard ......................................................................................................................................................... Types 619 Dashboard ......................................................................................................................................................... Elements 619 Opening ......................................................................................................................................................... Dashboards 621 Dashboard ......................................................................................................................................................... Configuration 623 Dashboard .................................................................................................................................................. Properties 623 Dashboard .................................................................................................................................................. Elements 624 Dashboards ......................................................................................................................................................... Security 624

17 Auto ................................................................................................................................... Run

625

Auto-Run......................................................................................................................................................... Action Configuration 626 Auto Run ......................................................................................................................................................... in Distributed Architecture 626

18 Favourites ...................................................................................................................................

626

Favourite......................................................................................................................................................... Configuration 627 Favourites ......................................................................................................................................................... in Distributed Architecture 627

19 Scripts ...................................................................................................................................

628

Script Configuration ......................................................................................................................................................... 629 Using Scripts ......................................................................................................................................................... In Expressions 630

2000-2013 Tibbo Technology Inc.

12

AggreGate Documentation
Script Examples ......................................................................................................................................................... 630 Scripts Security ......................................................................................................................................................... 631

20 Web ................................................................................................................................... Control Center 21 Web ................................................................................................................................... Desktop

631 632

Accessing ......................................................................................................................................................... Web Desktop 632 Login and ......................................................................................................................................................... Logout 633 User Interface ......................................................................................................................................................... 634 Toolbar .................................................................................................................................................. 635 System ......................................................................................................................................................... Tree 636 Context Menu .................................................................................................................................................. 636 Event Log ......................................................................................................................................................... 637 Current Events .................................................................................................................................................. 637 Event History .................................................................................................................................................. 638 Context Menu .................................................................................................................................................. 638 Acknowledging .................................................................................................................................................. Events 639 Exporting .................................................................................................................................................. Events 640 Properties ......................................................................................................................................................... Editor 640 Data Table ......................................................................................................................................................... Editor 643 Editing Data .................................................................................................................................................. 645 Context Menu .................................................................................................................................................. 649 Sorting and .................................................................................................................................................. Filtering 649 Data Export/Import .................................................................................................................................................. 649 Report Creation .................................................................................................................................................. 649 Entity Selector ......................................................................................................................................................... 649 Favourites ......................................................................................................................................................... 651 Trackers......................................................................................................................................................... 651

22 Context ................................................................................................................................... Reference

651

Administration ......................................................................................................................................................... 652 Alerts ......................................................................................................................................................... 654 Alert ......................................................................................................................................................... 656 Auto Run ......................................................................................................................................................... 662 Action: Add .................................................................................................................................................. Action to Auto Run 664 Auto Run......................................................................................................................................................... Action 664 Common ......................................................................................................................................................... Data 666 Action: Create .................................................................................................................................................. Common Table from Variable 668 Common ......................................................................................................................................................... Data Table 668 Config ......................................................................................................................................................... 671 Dashboards ......................................................................................................................................................... 672 Dashboard ......................................................................................................................................................... 673 Devices ......................................................................................................................................................... 675 Device ......................................................................................................................................................... 677 Drivers/Plugins ......................................................................................................................................................... Configuration 685 Driver/Plugin ......................................................................................................................................................... Configuration 686 Event Filters ......................................................................................................................................................... 687 Event Filter ......................................................................................................................................................... 688 Action: Parameterize .................................................................................................................................................. 692 Events ......................................................................................................................................................... 693 Favourites ......................................................................................................................................................... 697 Action: Add .................................................................................................................................................. Action to Favourites 698 Favourite ......................................................................................................................................................... 699 Groups ......................................................................................................................................................... 701 Group ......................................................................................................................................................... 702 Action: Create .................................................................................................................................................. Group Status Tracker 707

2000-2013 Tibbo Technology Inc.

Contents

13

Models ......................................................................................................................................................... 708 Model ......................................................................................................................................................... 709 Queries ......................................................................................................................................................... 714 Action: Execute .................................................................................................................................................. Native Query 716 Query ......................................................................................................................................................... 716 Action: Execute .................................................................................................................................................. Query 718 Reports ......................................................................................................................................................... 719 Report ......................................................................................................................................................... 721 Action: Preview .................................................................................................................................................. Source Data 725 Action: Schedule .................................................................................................................................................. Report 725 Action: Send .................................................................................................................................................. Report by E-mail 725 Root Context ......................................................................................................................................................... 726 Scheduled ......................................................................................................................................................... Jobs 742 Scheduled ......................................................................................................................................................... Job 744 Scripts ......................................................................................................................................................... 747 Script ......................................................................................................................................................... 748 Trackers......................................................................................................................................................... 750 Action: Build .................................................................................................................................................. Tracker 752 Tracker ......................................................................................................................................................... 753 Users ......................................................................................................................................................... 756 Action: New .................................................................................................................................................. User Account 759 Action: View .................................................................................................................................................. User Summary 759 User ......................................................................................................................................................... 759 Utilities ......................................................................................................................................................... 763 Widgets ......................................................................................................................................................... 770 Widget ......................................................................................................................................................... 774

Part IV AggreGate Client

1 Operation ................................................................................................................................... Modes 2 Requirements ................................................................................................................................... and Installation 3 Command ................................................................................................................................... Line Parameters 4 Uninstallation ................................................................................................................................... 5 Startup ................................................................................................................................... and Shutdown 6 Workspaces ................................................................................................................................... and Server Connections 7 Main ................................................................................................................................... Window

776
776 777 777 778 778 779 780

Admin Mode ......................................................................................................................................................... 779

Main Menu ......................................................................................................................................................... 780 Status Bar ......................................................................................................................................................... 781 Customizing ......................................................................................................................................................... Dockable Windows 781 Simple Mode ......................................................................................................................................................... 784

8 System ................................................................................................................................... Tree

784

Context ......................................................................................................................................................... Menu 786 Drag and......................................................................................................................................................... Drop Operations 787 Copy and ......................................................................................................................................................... Paste Operations 788 Node Reordering ......................................................................................................................................................... 788 Node Searching ......................................................................................................................................................... and Filtering 789 Custom ......................................................................................................................................................... Nodes 789 Workspace .................................................................................................................................................. Configuration Node 789 Server Node .................................................................................................................................................. 789 Servers Node .................................................................................................................................................. 791 Local Server ......................................................................................................................................................... Auto-connection 791

2000-2013 Tibbo Technology Inc.

14

AggreGate Documentation 9 Event ................................................................................................................................... Log 791

Current Events ......................................................................................................................................................... 793 Event History ......................................................................................................................................................... 793 Context ......................................................................................................................................................... Menu 794 Acknowledging ......................................................................................................................................................... Events 794 Exporting ......................................................................................................................................................... Events 795

10 Properties ................................................................................................................................... Editor 11 Data ................................................................................................................................... Table Editor

795 801

Editing Data ......................................................................................................................................................... 803 Context ......................................................................................................................................................... Menu 808 Sorting and ......................................................................................................................................................... Filtering 809 Row Grouping ......................................................................................................................................................... 810 Data Export/Import ......................................................................................................................................................... 810 Report Creation ......................................................................................................................................................... 812 Editing Bindings ......................................................................................................................................................... 813

12 Report ................................................................................................................................... Viewer 13 Entity ................................................................................................................................... Selector 14 Expression ................................................................................................................................... Builder 15 Text ................................................................................................................................... Editor 16 Code ................................................................................................................................... Editor 17 Favourites ................................................................................................................................... 18 Trackers ................................................................................................................................... 19 Device ................................................................................................................................... Browser 20 Report ................................................................................................................................... Editor 21 GUI ................................................................................................................................... Builder

814 815 817 819 820 824 824 825 826 827

Main Menu ......................................................................................................................................................... 828 Toolbar ......................................................................................................................................................... 829 Work Form ......................................................................................................................................................... 830 Resources ......................................................................................................................................................... Window 833 Entity Selector ......................................................................................................................................................... 834 Component ......................................................................................................................................................... Palette 834 Component ......................................................................................................................................................... Properties 835 Editing Widget ......................................................................................................................................................... Layout 836 Editing Grid .................................................................................................................................................. Layout 836 Editing Absolute .................................................................................................................................................. Layout 842 Managing ......................................................................................................................................................... Bindings 842 Drag and......................................................................................................................................................... Drop Operations 844

22 Error ................................................................................................................................... Dialogs 23 Interactive ................................................................................................................................... Guide 24 Logging ...................................................................................................................................

846 847 848

Part V AggreGate Agent

1 Generic ................................................................................................................................... Information About Agent 2 Agent ................................................................................................................................... Core Concepts 3 Representation ................................................................................................................................... Of Devices In Agent 4 Event ................................................................................................................................... Generation

848
850 850 851 852

2000-2013 Tibbo Technology Inc.

Contents 5 Agent ................................................................................................................................... Contexts 6 Communications ................................................................................................................................... Between Agent and AggreGate Server

15 852 853

Part VI System Internals

1 Data ................................................................................................................................... Tables

854
854

Table Format ......................................................................................................................................................... 855 Editors/Renderers ......................................................................................................................................................... 857 Data Table ......................................................................................................................................................... Bindings 860 Data Tables ......................................................................................................................................................... Smart Copy 861 Building ......................................................................................................................................................... a Data Table From a Parameters List 862 Naming Expression ......................................................................................................................................................... Resolution Environment 863

2 Contexts ...................................................................................................................................

863

Context ......................................................................................................................................................... Masks 865 Context Copy ......................................................................................................................................................... Operations 866 Visible and ......................................................................................................................................................... Real Context Trees 868

3 Variables ...................................................................................................................................

869

Common ......................................................................................................................................................... Variables 871 info (Context .................................................................................................................................................. Information) 871 children (Context .................................................................................................................................................. Children) 872 variables.................................................................................................................................................. (Context Variables) 872 functions.................................................................................................................................................. (Context Functions) 873 events (Context .................................................................................................................................................. Events) 873 actions (Context .................................................................................................................................................. Actions) 874 contextStatus .................................................................................................................................................. (Context Status) 874 activeAlerts .................................................................................................................................................. (Active Alerts) 875 groupMembership .................................................................................................................................................. (Group Membership) 875 validity (Validity) .................................................................................................................................................. 876 Processing ......................................................................................................................................................... Historical Values 876 Variables......................................................................................................................................................... Performance 878

4 Functions ...................................................................................................................................

878

Common ......................................................................................................................................................... Functions 879 makeCopy .................................................................................................................................................. (Make Copy) 879 delete (Delete) .................................................................................................................................................. 880 Functions ......................................................................................................................................................... Performance 880

5 Events ...................................................................................................................................

880

Event Parameters ......................................................................................................................................................... 881 Event Levels ......................................................................................................................................................... 882 Event Listeners ......................................................................................................................................................... 882 Event History ......................................................................................................................................................... 882 Event Acknowledgement ......................................................................................................................................................... 882 Event Enrichment ......................................................................................................................................................... 883 Event Management ......................................................................................................................................................... 884 Event Filtering .................................................................................................................................................. 884 Event Aggregation .................................................................................................................................................. 884 Event Masking .................................................................................................................................................. 884 Event Correlation .................................................................................................................................................. 885 Root Cause .................................................................................................................................................. Analysis 885 Event Lifecycle ......................................................................................................................................................... 885 Common ......................................................................................................................................................... Events 885 info (Information) .................................................................................................................................................. 885 childAdded .................................................................................................................................................. (Child Added) 886

2000-2013 Tibbo Technology Inc.

16

AggreGate Documentation
childRemoved .................................................................................................................................................. (Child Removed) 886 variableAdded .................................................................................................................................................. (Variable Added) 887 variableRemoved .................................................................................................................................................. (Variable Removed) 887 functionAdded .................................................................................................................................................. (Function Added) 887 functionRemoved .................................................................................................................................................. (Function Removed) 888 eventAdded .................................................................................................................................................. (Event Added) 888 eventRemoved .................................................................................................................................................. (Event Removed) 888 actionAdded .................................................................................................................................................. (Action Added) 889 actionRemoved .................................................................................................................................................. (Action Removed) 889 actionStateChanged .................................................................................................................................................. (Action State Changed) 889 infoChanged .................................................................................................................................................. (Info Changed) 890 contextStatusChanged .................................................................................................................................................. (Status Changed) 890 updated (Variable .................................................................................................................................................. Updated) 890 change (Variable .................................................................................................................................................. Changed) 891 Events Performance ......................................................................................................................................................... 891

6 Actions ...................................................................................................................................

892

Action Execution ......................................................................................................................................................... Modes 893 Interactive .................................................................................................................................................. Actions 893 Headless .................................................................................................................................................. Actions 893 Action Grouping ......................................................................................................................................................... 894 Drag and......................................................................................................................................................... Drop Actions 895 Variable-Related ......................................................................................................................................................... Actions 895 Event-Related ......................................................................................................................................................... Actions 895 Execution ......................................................................................................................................................... Parameters 896 UI Procedures ......................................................................................................................................................... 896 Edit Data .................................................................................................................................................. 896 Edit Properties .................................................................................................................................................. 897 Edit Text .................................................................................................................................................. 898 Show Event .................................................................................................................................................. Log 898 Show Message .................................................................................................................................................. 899 Show Error .................................................................................................................................................. 899 Show Report .................................................................................................................................................. 900 Show System .................................................................................................................................................. Tree 900 Confirm .................................................................................................................................................. 901 Browse .................................................................................................................................................. 902 Select Entities .................................................................................................................................................. 902 Start Interactive .................................................................................................................................................. Tutorial 902 Common ......................................................................................................................................................... Actions 902 Call Function .................................................................................................................................................. 903 Configure .................................................................................................................................................. 904 Create .................................................................................................................................................. 905 Create From .................................................................................................................................................. Template 905 Delete .................................................................................................................................................. 905 Edit Context .................................................................................................................................................. Permissions 906 Export .................................................................................................................................................. 907 Import .................................................................................................................................................. 908 Make Copy .................................................................................................................................................. 908 Monitor Related .................................................................................................................................................. Events 909 Search/Filter .................................................................................................................................................. 909 Replicate.................................................................................................................................................. 909 Replicate.................................................................................................................................................. To Children 910 View Status .................................................................................................................................................. 910

7 Expression ................................................................................................................................... Language

911

Data Types ......................................................................................................................................................... and Type Conversion 911

2000-2013 Tibbo Technology Inc.

Contents

17

Expression ......................................................................................................................................................... Syntax 912 Literals .................................................................................................................................................. 912 Operators .................................................................................................................................................. 913 Functions .................................................................................................................................................. 914 References .................................................................................................................................................. 921 Comments .................................................................................................................................................. 922 Expression ......................................................................................................................................................... Evaluation Environment 922 Expression ......................................................................................................................................................... Examples 922 Expression ......................................................................................................................................................... Debugging 923 Expressions ......................................................................................................................................................... Security 924 Expressions ......................................................................................................................................................... Performance 924

8 References ...................................................................................................................................

925

Standard......................................................................................................................................................... References 926 Environment ......................................................................................................................................................... References 930

9 Security ................................................................................................................................... and Permissions

931

Permission ......................................................................................................................................................... Levels 932 Default Context ......................................................................................................................................................... Permission Level 933 Permissions ......................................................................................................................................................... Table 933 Default Permissions ......................................................................................................................................................... Table 934 Permission ......................................................................................................................................................... Checking 935

10 Statistics ...................................................................................................................................

936

Statistics......................................................................................................................................................... Channel Properties 938 Working With .................................................................................................................................................. Keys 942 Channel Types .................................................................................................................................................. 942 Data Processing ......................................................................................................................................................... Sequence 943 Charting ......................................................................................................................................................... Statistical Data 944 Statistics......................................................................................................................................................... Configuration Examples 944 RRD Technology ......................................................................................................................................................... 945 Rates, normalization .................................................................................................................................................. and consolidation 945 Server-side ......................................................................................................................................................... vs Device-side Aggregation 947

11 Resource ................................................................................................................................... Validity 12 Plugins ................................................................................................................................... 13 Bindings ...................................................................................................................................

948 950 951

Server Bindings ......................................................................................................................................................... 952 Binding Target .................................................................................................................................................. 952 Binding Expression .................................................................................................................................................. 953 Binding Activator .................................................................................................................................................. 954 Binding Condition .................................................................................................................................................. 954

14 Window ................................................................................................................................... Location 15 Parameterization ................................................................................................................................... Engine 16 Enabling ................................................................................................................................... Serial Communications

955 956 959

Part VII Development and Integration

1 AggreGate ................................................................................................................................... SDK

960
960

AggreGate ......................................................................................................................................................... Server API 961 Error Reporting ......................................................................................................................................................... 963 Driver Development ......................................................................................................................................................... Kit (DDK) 963 Implementing .................................................................................................................................................. a Driver 964 Working .................................................................................................................................................. with Device Assets 967 Synchronization .................................................................................................................................................. Sequence 967

2000-2013 Tibbo Technology Inc.

18

AggreGate Documentation
Handling.................................................................................................................................................. Asynchronous Variable Updates 968 Managing .................................................................................................................................................. Incoming Device Connections 968 Plugin SDK ......................................................................................................................................................... 969 Plugin Descriptor .................................................................................................................................................. 971 Agent SDK ......................................................................................................................................................... 972 Implementing .................................................................................................................................................. a Java Agent 972

2 .NET ................................................................................................................................... API 3 Web ................................................................................................................................... Service

974 976

Accessing ......................................................................................................................................................... Web Service 976 Web Service ......................................................................................................................................................... Functions 977 Web Service ......................................................................................................................................................... Examples 979

4 Programming ................................................................................................................................... Guide

980

Basic Concepts ......................................................................................................................................................... 980 Essential......................................................................................................................................................... Classes and Interfaces 981 Finding and ......................................................................................................................................................... Accessing Arbitrary Data 982 Logging ......................................................................................................................................................... 983 Working ......................................................................................................................................................... with Data Tables 983 Creation .................................................................................................................................................. 984 Manipulation .................................................................................................................................................. 985 Working ......................................................................................................................................................... with Contexts 986 Manipulating .................................................................................................................................................. Variables 987 Calling Functions .................................................................................................................................................. 989 Listening.................................................................................................................................................. and Processing Events 990 Declaring......................................................................................................................................................... Variables, Functions, Events and Actions 992 Defining and .................................................................................................................................................. Implementing Variables 992 Defining and .................................................................................................................................................. Implementing Functions 994 Defining and .................................................................................................................................................. Implementing Events 995 Defining and .................................................................................................................................................. Implementing Actions 996 Dealing with ......................................................................................................................................................... Access Permissions 997

Part VIII Device Server Management

1 HTTP ................................................................................................................................... Proxy Service 2 Dynamic ................................................................................................................................... DNS Service 3 Link ................................................................................................................................... Service 4 Device ................................................................................................................................... Servers, Device Server Accounts and External Device Servers Accounts 5 Device ................................................................................................................................... Servers 6 Device ................................................................................................................................... Server Plugins

998
998 999 1000 1002 1003 1009

Transparent ......................................................................................................................................................... Data Routing (Link Service) 1010 Dynamic ......................................................................................................................................................... DNS 1010 HTTP Proxy ......................................................................................................................................................... 1011

7 External ................................................................................................................................... Device Servers 8 Tools ................................................................................................................................... 9 Troubleshooting ................................................................................................................................... Device Server Connections 10 Setting ................................................................................................................................... Definition Files 11 Contexts ...................................................................................................................................

1012 1017 1018 1018 1018

Device Server ......................................................................................................................................................... 1018 Device ......................................................................................................................................................... Servers 1024 External......................................................................................................................................................... Device Server 1027 External......................................................................................................................................................... Device Servers 1030

2000-2013 Tibbo Technology Inc.

Contents

19

Part IX Network Management and Monitoring

1 Overview ................................................................................................................................... 2 Getting ................................................................................................................................... Started

1033
1033 1033

AggreGate ......................................................................................................................................................... Network Manager Installation 1034 Configuring ......................................................................................................................................................... 1034 Monitoring ......................................................................................................................................................... 1035 Managing ......................................................................................................................................................... 1036

3 AggreGate ................................................................................................................................... Network Manager Basics

1036

Network......................................................................................................................................................... Management Concepts 1037 Management .................................................................................................................................................. Subjects 1037 Management .................................................................................................................................................. Tasks 1037 Management .................................................................................................................................................. Participants 1038 Management .................................................................................................................................................. Interactons 1039 AggreGate ......................................................................................................................................................... Network Manager Architecture 1042 Metrics ......................................................................................................................................................... 1043 Availability .................................................................................................................................................. And Operability Metrics 1044 Performance .................................................................................................................................................. Metrics 1045 Data Processing ......................................................................................................................................................... 1045 Protocols ......................................................................................................................................................... And Technologies 1046 Network......................................................................................................................................................... Management Tools 1047

4 Configuring ................................................................................................................................... AggreGate Network Manager

1047

Configuring ......................................................................................................................................................... Drivers and Plugins 1048 SNMP Configuration .................................................................................................................................................. 1048 Discovery .................................................................................................................................................. Configuration 1048 Syslog Configuration .................................................................................................................................................. 1048 NetFlow .................................................................................................................................................. Configuration 1049 Configuring/Administering ......................................................................................................................................................... Devices and Services 1049 Manually .................................................................................................................................................. Adding and Configuring Devices And Services 1050 Network........................................................................................................................................... Host Device Configuration 1051 Local File ........................................................................................................................................... Configuration 1051 Local Folder ........................................................................................................................................... Configuration 1051 SQL Database ........................................................................................................................................... Configuration 1052 JMX Configuration ........................................................................................................................................... 1052 Discovering .................................................................................................................................................. Devices and Services 1052 Administering .................................................................................................................................................. Devices and Services 1052 Administering ......................................................................................................................................................... AggreGate Network Manager Tools 1052 Setup Monitoring ......................................................................................................................................................... Profile Action 1052 Configuring ......................................................................................................................................................... Environment 1053 Configuring .................................................................................................................................................. SNMP Devices 1053 Configuring .................................................................................................................................................. WMI Devices 1054 Receiving .................................................................................................................................................. Windows Log Events 1054 TCP/IP .................................................................................................................................................. limitations of desktop versions of Windows 1054

5 Network ................................................................................................................................... Devices Discovery

1055

Discovery ......................................................................................................................................................... Process 1055 Search .................................................................................................................................................. Stage of Discovery 1056 Service Selection ........................................................................................................................................... and Setup 1056 Host Addresses ........................................................................................................................................... Specification 1058 Discovery ........................................................................................................................................... Tuning 1059 Scanning ........................................................................................................................................... 1060 Result Processing .................................................................................................................................................. 1060

2000-2013 Tibbo Technology Inc.

20

AggreGate Documentation
Discovery ........................................................................................................................................... Results Review 1060 Applying........................................................................................................................................... Discovery Results 1061 Discovery ........................................................................................................................................... Status Report 1061 Using Discovery ......................................................................................................................................................... 1061 Interactive .................................................................................................................................................. Multiple-Device Discovery 1062 Interactive .................................................................................................................................................. Single-Device Discovery 1062 Headless .................................................................................................................................................. Multiple- and Single-Device Discovery 1062 Rediscovering .................................................................................................................................................. Device Services 1063 Automatic .................................................................................................................................................. Discovery 1063 Default ......................................................................................................................................................... Discovery Settings 1063

6 Network ................................................................................................................................... Topology Monitoring

1063

Network......................................................................................................................................................... Topology Discovery 1063 Editing ......................................................................................................................................................... Network Topology 1064 Browsing ......................................................................................................................................................... Network Topology 1065

7 Network ................................................................................................................................... Mapping 8 Event ................................................................................................................................... Masking and Device Dependencies 9 SNMP ................................................................................................................................... Monitoring and Management

1066 1067 1068

SNMP Basics ......................................................................................................................................................... 1068 SNMP Versions .................................................................................................................................................. 1069 Structure .................................................................................................................................................. of Management Information 1069 SNMP Operations .................................................................................................................................................. 1070 SNMP Security .................................................................................................................................................. 1070 Using SNMP ......................................................................................................................................................... in AggreGate Network Manager 1070 Configuring .................................................................................................................................................. SNMP 1071 Configuring ........................................................................................................................................... SNMP Agents 1071 SNMP ...................................................................................................................................... Setup on Windows Systems 1072 Enabling ...................................................................................................................................... SNMP Agent on Windows Systems 1072 Configuring ...................................................................................................................................... SNMP Agent on Windows Systems 1074 SNMP ...................................................................................................................................... Setup on Linux Systems 1075 Enabling ...................................................................................................................................... SNMP Agent on Linux Systems 1075 Configuring ...................................................................................................................................... SNMP Agent on Linux Systems 1076 SNMP ...................................................................................................................................... Setup on Solaris Systems 1076 Enabling ...................................................................................................................................... SNMP Agent on Solaris Systems 1076 Configuring ...................................................................................................................................... SNMP Agent on Solaris Systems 1077 SNMP ...................................................................................................................................... Setup on Cisco Devices 1077 SNMP ...................................................................................................................................... Setup on Microsoft SQL Server 1078 SNMP ...................................................................................................................................... Setup on Lotus Domino Server 1078 SNMP ...................................................................................................................................... Setup on Oracle Servers 1078 Configuring ........................................................................................................................................... SNMP in AggreGate Network Manager 1079 Global SNMP ...................................................................................................................................... Configuration 1079 Managing ...................................................................................................................................... MIB Files 1080 Configuring ...................................................................................................................................... SNMP Devices 1081 SNMP Monitoring .................................................................................................................................................. 1084 SNMP Polling ........................................................................................................................................... 1084 Receiving ........................................................................................................................................... SNMP Traps and Informs 1085 SNMP ...................................................................................................................................... Trap Sources Automatic Discovery 1086 Using SNMP ........................................................................................................................................... Data 1086 Managing .................................................................................................................................................. Devices Using SNMP 1086 Sending .................................................................................................................................................. SNMP Traps and Informs 1087

10 WMI ................................................................................................................................... Monitoring and Management

1088

WMI Use ......................................................................................................................................................... Cases 1089 Controlling .................................................................................................................................................. Windows Services 1090

2000-2013 Tibbo Technology Inc.

Contents

21

Managing .................................................................................................................................................. Printers 1090 Windows .................................................................................................................................................. Event Log Monitoring via WMI 1091

11 Availability ................................................................................................................................... Monitoring 12 Performance ................................................................................................................................... Monitoring

1091 1092

CPU Performance ......................................................................................................................................................... Monitoring 1092 Storage ......................................................................................................................................................... Monitoring 1093 Process......................................................................................................................................................... Monitoring 1094 Process .................................................................................................................................................. Instance Count Chart 1095 Generic ......................................................................................................................................................... Service Performance Monitoring 1096

13 Network ................................................................................................................................... Traffic and Bandwidth Monitoring

1096

Network......................................................................................................................................................... Interface Traffic Chart 1097 Network......................................................................................................................................................... Interface Bandwidth Utilization 1098 Network......................................................................................................................................................... Interface Errors Chart 1098 Network......................................................................................................................................................... Interface Discards Chart 1098 Network......................................................................................................................................................... Interface Utilization Alert 1098 Network......................................................................................................................................................... Interface Down Alert 1098 Network......................................................................................................................................................... Interface Administrative Shutdown Alert 1098 Network......................................................................................................................................................... Interface State Change Alert 1098 Interface ......................................................................................................................................................... Traffic Summary Report 1099 Interface ......................................................................................................................................................... Traffic Top 10 And 50 Reports 1099 Interface ......................................................................................................................................................... Bandwidth Utilization Over 50% And 90% Reports 1099 Interface ......................................................................................................................................................... Bandwidth Utilization Top 10 And 50 Reports 1099

14 NetFlow-based ................................................................................................................................... Traffic Decomposition

1100

NetFlow......................................................................................................................................................... Basics 1100 Supported ......................................................................................................................................................... NetFlow Versions 1101 System ......................................................................................................................................................... Requirements 1101 Configuring ......................................................................................................................................................... Flow Exporters 1101 Configuring ......................................................................................................................................................... Flow Processing 1102 Configuring .................................................................................................................................................. NetFlow Plugin 1102 Configuring .................................................................................................................................................. DNS and NetBIOS Resolution 1102 Configuring .................................................................................................................................................. Device Accounts of NetFlow Sensors 1102 Viewing ......................................................................................................................................................... NetFlow Processing Statistics 1102 Flow Data ......................................................................................................................................................... Aggregation 1102 Visualizing ......................................................................................................................................................... Traffic Flows 1102 Optimizing ......................................................................................................................................................... NetFlow Processing Performance 1103

15 Database ................................................................................................................................... Monitoring

1103

MySQL ......................................................................................................................................................... Monitoring 1103 Oracle Monitoring ......................................................................................................................................................... 1104 Microsoft ......................................................................................................................................................... SQL Server Monitoring 1104 PostgreSQL ......................................................................................................................................................... Monitoring 1104

16 Filesystem ................................................................................................................................... Monitoring

1104

Local File ......................................................................................................................................................... Monitoring 1104 Local Folder ......................................................................................................................................................... Monitoring 1104 Log File......................................................................................................................................................... Monitoring 1105

17 Event ................................................................................................................................... Monitoring and Consolidation

1105

Syslog ......................................................................................................................................................... 1105 Syslog Events .................................................................................................................................................. Monitoring and Consolidation 1105 Syslog Alerts ........................................................................................................................................... 1106 Syslog Message ........................................................................................................................................... Source Automatic Discovery 1107 Syslog Messages .................................................................................................................................................. Sending 1107 SNMP Notifications ......................................................................................................................................................... 1107 SNMP Notification .................................................................................................................................................. Alerts 1107

2000-2013 Tibbo Technology Inc.

22

AggreGate Documentation
WMI Events ......................................................................................................................................................... 1108 Windows ......................................................................................................................................................... Log Events 1108

18 Application/Service ................................................................................................................................... Monitoring

1108

Web Server ......................................................................................................................................................... Monitoring 1109 Web Page .................................................................................................................................................. Monitoring 1109 Apache.................................................................................................................................................. Web Server Monitoring 1109 Apache ........................................................................................................................................... Dashboard 1110 Apache ........................................................................................................................................... Alerts 1110 Microsoft .................................................................................................................................................. IIS Monitoring 1111 Application ......................................................................................................................................................... Server Monitoring 1111 JBoss Monitoring .................................................................................................................................................. 1111 Tomcat .................................................................................................................................................. Monitoring 1111 Oracle Application .................................................................................................................................................. Server Monitoring 1111 Lotus Domino .................................................................................................................................................. and Lotus Notes Monitoring 1111 Microsoft .................................................................................................................................................. SharePoint Monitoring 1111 WebSphere ......................................................................................................................................................... MQ Monitoring 1111 FTP Server ......................................................................................................................................................... Monitoring 1112 E-mail Server ......................................................................................................................................................... Monitoring 1112 POP3 Monitoring .................................................................................................................................................. 1112 IMAP Monitoring .................................................................................................................................................. 1112 SMTP Monitoring .................................................................................................................................................. 1112 E-mail Round-Trip .................................................................................................................................................. Monitoring 1112 Postfix Monitoring .................................................................................................................................................. 1113 Active Directory ......................................................................................................................................................... (LDAP) Monitoring 1113 SSH Server ......................................................................................................................................................... Monitoring 1113 Radius ......................................................................................................................................................... Server Monitoring 1113 DNS Server ......................................................................................................................................................... Monitoring 1113 DHCP Server ......................................................................................................................................................... Monitoring 1113 Generic ......................................................................................................................................................... TCP Service Monitoring 1113 Generic ......................................................................................................................................................... UDP Service Monitoring 1113

19 Active ................................................................................................................................... Directory Monitoring 20 VMware ................................................................................................................................... Monitoring

1114 1114

Microsoft ......................................................................................................................................................... DNS Server Monitoring 1114

VMware ......................................................................................................................................................... Alerts 1114 Virtual Machine .................................................................................................................................................. State Alert 1115 Virtual Machine .................................................................................................................................................. CPU Load Alert 1115 Virtual Machine .................................................................................................................................................. Absolute Memory Utilization Alert 1115 Virtual Machine .................................................................................................................................................. Relative Memory Utilization Alert 1115 Virtual Machine .................................................................................................................................................. HDD Read Rate Alert 1115 Virtual Machine .................................................................................................................................................. HDD Write Rate Alert 1116 VMware ......................................................................................................................................................... Charts 1116 Virtual Machine .................................................................................................................................................. CPU Utilization Chart 1117 Virtual Machine .................................................................................................................................................. Memory Usage Charts 1117 Virtual Machine .................................................................................................................................................. Disk Performance Charts 1117 Virtual Machine .................................................................................................................................................. Network Performance Charts 1117 VMware ......................................................................................................................................................... Reports 1117 VMware ......................................................................................................................................................... Information Widget 1118

21 Printer ................................................................................................................................... Monitoring

Printer Printer Printer Printer

1119

State ......................................................................................................................................................... Alert 1120 ......................................................................................................................................................... Marker Alert 1120 Cover ......................................................................................................................................................... Status Alert 1120 ......................................................................................................................................................... Information Widget 1120

2000-2013 Tibbo Technology Inc.

Contents 22 Wireless ................................................................................................................................... Device Monitoring 23 Java ................................................................................................................................... Monitoring and Management 24 .NET ................................................................................................................................... Monitoring 25 Configuration ................................................................................................................................... and Change Management

23 1121 1124 1124 1124

Configuration ......................................................................................................................................................... Management Setup 1125 Configuration ......................................................................................................................................................... Backup and Restoration 1125 Managing .................................................................................................................................................. Historical Configurations 1125 Baseline .................................................................................................................................................. Configurations 1125 Viewing.................................................................................................................................................. Configuration Differences 1125 Scheduling ......................................................................................................................................................... Configuration Backups 1125 Automatic ......................................................................................................................................................... Backups Upon Changes 1125 Compliance ......................................................................................................................................................... Management 1125 Configuration ......................................................................................................................................................... and Command Scripts 1126

26 IP ................................................................................................................................... SLA Monitoring

1126

IP SLA Monitoring ......................................................................................................................................................... Concepts 1126 IP SLA Test ......................................................................................................................................................... Types 1126 Understanding ......................................................................................................................................................... IP SLA Technology 1127 Latency.................................................................................................................................................. 1127 Jitter .................................................................................................................................................. 1128 Packet Loss .................................................................................................................................................. 1128 Mean Opinion .................................................................................................................................................. Score (MOS) 1128 Test Topology .................................................................................................................................................. 1128 Configuring ......................................................................................................................................................... IP SLA Tests 1129 Preparing .................................................................................................................................................. for IP SLA Monitoring 1129 Importing .................................................................................................................................................. Existing Tests 1129 Updating .................................................................................................................................................. Tests 1129 Creating .................................................................................................................................................. New Tests 1130 Deleting .................................................................................................................................................. Tests 1130 Synchronizing .................................................................................................................................................. Tests 1130 IP SLA Test .................................................................................................................................................. Properties 1130 IP SLA Test .................................................................................................................................................. Schedule 1138 IP SLA Test .................................................................................................................................................. Reactions 1139 IP SLA Test .................................................................................................................................................. Statistics 1140 IP SLA Test .................................................................................................................................................. History 1141 IP SLA Alert .................................................................................................................................................. Thresholds 1142 Understanding .................................................................................................................................................. Polling Frequency 1142 Browsing ......................................................................................................................................................... IP SLA Status and Statistics 1142 IP SLA Test .................................................................................................................................................. Groups 1143 IP SLA Dashboards .................................................................................................................................................. 1143 IP SLA Alerts .................................................................................................................................................. 1143

27 VoIP ................................................................................................................................... Monitoring 28 Management ................................................................................................................................... Operations

1143 1143

SNMP Management ......................................................................................................................................................... 1144 Control ......................................................................................................................................................... via WMI 1144 Remote ......................................................................................................................................................... Script Execution 1144 Network......................................................................................................................................................... Management Actions 1144 Execute .................................................................................................................................................. Remote Script 1144 Send SNMP .................................................................................................................................................. Trap 1144 Send Syslog .................................................................................................................................................. Message 1144 Wake-on-LAN .................................................................................................................................................. 1145

29 Alerting ...................................................................................................................................

1145

2000-2013 Tibbo Technology Inc.

24

AggreGate Documentation 30 Reporting ................................................................................................................................... 31 Dashboards ................................................................................................................................... 32 Charts ................................................................................................................................... 33 Trackers ................................................................................................................................... 34 Widgets ................................................................................................................................... 35 Event ................................................................................................................................... Filters 36 Models ................................................................................................................................... 37 Helpdesk ................................................................................................................................... / Trouble Ticketing System Integration 38 Asset ................................................................................................................................... Management 39 Network ................................................................................................................................... Management Context Reference 1149 1151 1151 1154 1154 1154 1155 1156 1156 1157

Compliance ......................................................................................................................................................... Policies 1158 Compliance ......................................................................................................................................................... Policy 1158 Discovery ......................................................................................................................................................... 1159 IP SLA Tests ......................................................................................................................................................... 1160 IP SLA Test ......................................................................................................................................................... 1160 Network......................................................................................................................................................... Management 1160

Part X SCADA/HMI
1 Overview ................................................................................................................................... 2 Architecture ................................................................................................................................... 3 Getting ................................................................................................................................... Started 4 Connecting ................................................................................................................................... to PLCs 5 Creating ................................................................................................................................... HMIs 6 Trending ................................................................................................................................... and Charting 7 SCADA ................................................................................................................................... Security 8 OPC ................................................................................................................................... Server Discovery 9 Maintenance ................................................................................................................................... 10 Demo ................................................................................................................................... HMIs

1162
1163 1163 1164 1165 1165 1167 1168 1168 1168 1169

Symbol ......................................................................................................................................................... Library 1165

Filter Plant ......................................................................................................................................................... Demo 1170 Bottling ......................................................................................................................................................... Line 1171

Part XI Time and Attendance

1 Overview ................................................................................................................................... 2 Connecting ................................................................................................................................... Time Recorders 3 Setting ................................................................................................................................... Up Organization Structure 4 Managing ................................................................................................................................... Cardholders

1171
1171 1171 1173 1174

Importing ......................................................................................................................................................... Cardholders 1176 Attendance ......................................................................................................................................................... Exceptions 1178

5 Managing ................................................................................................................................... Cards/Badges 6 Managing ................................................................................................................................... Shifts 7 Managing ................................................................................................................................... Raw Attendance Events 8 Attendance ................................................................................................................................... Data Processing

1179 1179 1183 1184

2000-2013 Tibbo Technology Inc.

Contents 9 Time ................................................................................................................................... and Attendance Reports 10 Context ................................................................................................................................... Reference

25 1186 1189

Report ......................................................................................................................................................... Comments 1189

Attendance ......................................................................................................................................................... 1189 Cardholders ......................................................................................................................................................... 1191 Cardholder ......................................................................................................................................................... 1193 Departments ......................................................................................................................................................... 1197 Department ......................................................................................................................................................... 1198 Divisions ......................................................................................................................................................... 1200 Division......................................................................................................................................................... 1201 Organizations ......................................................................................................................................................... 1203 Organization ......................................................................................................................................................... 1204 Shifts ......................................................................................................................................................... 1206 Shift ......................................................................................................................................................... 1207

Part XII Tutorials

1 Performing ................................................................................................................................... an Action With Multiple Devices 2 Copying ................................................................................................................................... Objects Between User Accounts 3 Granting ................................................................................................................................... One User Access to Objects of Another User 4 Creating ................................................................................................................................... a Widget to Monitor a Device 5 Manipulating ................................................................................................................................... SVG Images 6 Handling ................................................................................................................................... Component Events 7 Creating ................................................................................................................................... a Dashboard to Monitor Your Devices in Real-Time 8 Monitoring ................................................................................................................................... Device Parameters Using a Chart 9 Building ................................................................................................................................... Complex Chart 10 Building ................................................................................................................................... a Device Status Report 11 Scheduled ................................................................................................................................... Report Emailing 12 Adding ................................................................................................................................... Custom Properties 13 Using ................................................................................................................................... Resource and Device Templates 14 Keeping ................................................................................................................................... History of Object Changes 15 Scheduling ................................................................................................................................... Device Downtime 16 Selecting ................................................................................................................................... and Processing Events 17 Creating ................................................................................................................................... Consumption Reports 18 Predicting ................................................................................................................................... SLA Breakdowns 19 Intelligent ................................................................................................................................... Baseline Alerts 20 Adding ................................................................................................................................... Links to Tables 21 Opening ................................................................................................................................... a Pop-Up Report 22 Using ................................................................................................................................... Multi-level Subwidgets

1210
1211 1213 1215 1217 1224 1230 1233 1239 1244 1250 1254 1258 1263 1267 1269 1270 1272 1276 1279 1281 1283 1289

Part XIII Troubleshooting

1 AggreGate ................................................................................................................................... Server Startup Problems 2 AggreGate ................................................................................................................................... Server Runtime Errors 3 AggreGate ................................................................................................................................... Server Not Responding

1297
1297 1298 1299

2000-2013 Tibbo Technology Inc.

26

AggreGate Documentation 4 AggreGate ................................................................................................................................... Server Connection Problems 5 AggreGate ................................................................................................................................... Client Runtime Errors 6 Performance ................................................................................................................................... Optimization 1301 1301 1301

Part XIV Appendix

1 AggreGate ................................................................................................................................... Communication Protocol 2 Data ................................................................................................................................... Table Encoding 3 Data ................................................................................................................................... Tables XML Encoding 4 Regular ................................................................................................................................... Expressions Syntax 5 Date ................................................................................................................................... and Time Formatting Patterns 6 Number ................................................................................................................................... Formatting Patterns 7 Common ................................................................................................................................... Constants 8 CSV ................................................................................................................................... Import/Export Options 9 Report ................................................................................................................................... Template Generation 10 Configuring ................................................................................................................................... DCOM for Remote Access 11 OS-Based ................................................................................................................................... Failover Cluster

1303
1303 1306 1312 1318 1321 1322 1324 1325 1325 1327 1330

Index

2000-2013 Tibbo Technology Inc.

Introduction

27

1 Introduction
Last update: 08/29/2013

Tibbo AggreGate is a complete device management solution that employs modern network technologies to control, configure and monitor different electronic devices. It also helps you to aggregate device data into a common database, where you can "slice and dice" it according to your needs, as well as let other enterprise applications transparently access it. The AggreGate saves costs and simplifies setup when trying to create a large network of devices and computers which are spread over a wide-area network (WAN) or the Internet. It introduces new concepts in M2M (Machine-2-Machine) technology, also known as Industrial Control or SCADA. In a complex WAN environment your devices may be distributed over multiple network segments, located behind firewalls, routers, bridges, etc. The core part of AggreGate, called AggreGate Server, solves the problem of communication between devices installed within various protected local networks and networks with dynamic addressing by acting as a middle-man. AggreGate Server provides a rich set of features for managing device networks and routing data. The core components are Java-based and may be deployed on most present-day hardware and operating systems. AggreGate provides two user interfaces: a graphical, cross-platform client application and a web interface. Both can be used for system administration and normal operation activities. Connecting your devices to the system is easy and cost-effective. Any existing device may work with AggreGate regardless of its communication protocol even if it's not network-enabled. You can bridge your existing devices into the system using programmable hardware modules (Agents), or by protocol conversion via software device drivers. When designing a new device from scratch, you could include Agent right into your original design. This would allow your device to act autonomously even when the central server is not available. Being a hardware manufacturer, Tibbo has vast experience of creating custom solutions for different types of devices - we can help. AggreGate provides industry-specific solutions for many vertical markets: Network Management, SCADA/HMI, Time and Attendance, Access Control, Building Automation, Fleet Management, Vending Machines, Remote Monitoring, and more.

1.1 About This Manual

This manual is a work-in-progress. AggreGate is a very large system, and is in a continuous process of development, enhancement and debugging. In this manual, the AggreGate documentation team attempts to play "catch-up" with the ever-increasing pace of AggreGate development. Thus, we would recommend you to keep a few points in mind while reading this text: Due to the sheer extent of AggreGate, there's a definite learning curve to the system. We have attempted to use a gradient approach throughout the manual, with many topics building on earlier topics. Please try to read the manual in-sequence wherever possible - like a textbook. If you do decide to skip around and use the manual as a reference, please skip to earlier topics when you come across a term you're unfamiliar with. Terms are usually defined when they're first introduced in the text. The same system component might have several topics dedicated to it, requiring different levels of familiarity with the system. You can always look for an earlier topic dealing with the same system component -- it'll have simpler explanations.

2000-2013 Tibbo Technology Inc.

28

AggreGate Documentation

Above all, we strive to provide easy-to-read, easy-to-follow documentation, which is accurate yet friendly. We recognize our users are real people who want to get something done with the system, and we hope this manual will help. Good luck.

1.2 About Tibbo Technology Inc.

AggreGate is made and supported by Tibbo Technology Inc., a leading manufacturer of programmable Ethernet converters and controllers. Located in Taipei, Taiwan, Tibbo brings simplicity to the embedded world defined by the enormous complexity of operating systems, programming languages, and design tools. Tibbo's hardware, Tibbo-BASIC programming language with its Tibbo IDE software, and the AggreGate system offer a complete solution for delivering robust, distributed automation and monitoring systems.

1.3 Copyright Notice

2000-2013 Tibbo Technology Inc. All rights reserved. Under the copyright laws, this manual or the software described within, can not be copied, in whole or part, without the written consent of the manufacturer, except in the normal use of the software to make a backup copy. The same proprietary and copyright notices must be affixed to any permitted copies as were affixed to the original. This exception does not allow copies to be made for others, whether or not sold, but all of the material purchased (with all backup copies) can be sold, given, or loaned to another person. Under the law, copying includes translating into another language or format. Specifications and descriptions subject to change without notice.

1.4 Documentation Feedback

As part of our ongoing efforts to produce effective documentation, Tibbo asks that you send us any comments, additions or corrections for the documentation. Your feedback is very important to us and we will use it to improve our products and services. Please send your comments to aggregate@tibbo.com. Thank you for your help.

1.5 Quick Start Guide

One of the major design goals for AggreGate is quick installation and deployment. Getting AggreGate up and running takes just a few steps. Here is the list of actions you need to take in order to deploy and test out the Tibbo AggreGate: Make sure
40

your PC can run the AggreGate Server.

43

Download and install Run

44

AggreGate. The distribution bundle includes both AggreGate Server and AggreGate Client.

the AggreGate Server software.

777

Download, install

and run
779

778

AggreGate Client.

Create the workspace

and log in to it.

Create a server connection 779 for your AggreGate Server (AggreGate Client will do that automatically if it detects a AggreGate Server running on the same machine). Username of default administrator
109 's

account is admin, default password is also admin.

Connect any Devices

113

to AggreGate Server.

When these steps are complete, AggreGate is running in normal operations mode. At that point you may start controlling, configuring and monitoring system operators, etc.
37

your Devices, creating user accounts

108

for

If this procedure did not work as planned for some reason, please read the rest of the manual before contacting Support. Tibbo AggreGate is a complex product and has a learning curve.

2000-2013 Tibbo Technology Inc.

Introduction

29

1.6 License Issues

AggreGate uses Named Licenses that are locked to the PC or server where AggreGate Server is running. If you have purchased AggreGate License, you need to report your AggreGate Server Activation Key to Tibbo so that we may generate a Names License file to activate your AggreGate Installation. As AggreGate License is locked to a certain AggreGate Server installation, it is necessary to perform a production installation of AggreGate Server before proceeding. This means that AggreGate Server must be installed on the same PC where it will run during production use. See Installing AggreGate Server 43 for details. It's possible to activate a license on the installation of a trial version of AggreGate. There is no need to reinstall the system.

Getting AggreGate Server Activation Key

There are two ways to obtain the Activation Key: Using the Tray Menu of a running AggreGate Server instance Using the activation.txt file

GETTING THE ACTIVATION KEY USING THE TRAY MENU

This method should be used in most cases, except for when AggreGate Server cannot be started successfully (e.g. due to an expired trial license) or when it is running in a headless environment (e.g. on a Linux server). 1. Start
44

AggreGate Server.
108

2. Right-click the tray menu

icon and select View Activation Key. The Activation Key dialog will pop up:

3. Click Copy To Clipboard. 4. Paste the Activation Key into an e-mail message and send it to Tibbo.

GETTING THE ACTIVATION KEY FROM FILE

When AggreGate Server is launched, it writes its Activation Key into a file named activation.txt that is located within the AggreGate Server installation directory. This happens even if AggreGate Server cannot complete its startup successfully because of an expired trial license or for any other reason. To get your activation key, launch AggreGate Server at least once, then open activation.txt in any text editor.

Activation Procedure
Activating your AggreGate License is very simple. Once you've purchased a commercial AggreGate license and sent your Activation Key to Tibbo, we send you your Named License file by e-mail. This file is called server.license. To activate your license, just put this file into your AggreGate Server installation directory (overwrite any existing Trial License file) and restart AggreGate Server.

A file manager used to copy the license file under Windows must be started in elevated mode (i.e. with Administrator permissions). Failure to do so will cause the license file to be written to a wrong folder due to a "File and Registry Virtualization" feature of latest Windows versions. In this case AggreGate Server will not be able to access the new license and will use the old one, likely failing to start with License Expired and similar errors. To open Windows Explorer in elevated mode, find the Explorer in the Start menu, right-

2000-2013 Tibbo Technology Inc.

30

AggreGate Documentation

click on it, and select "Run as Administrator".

2 System Basics
AggreGate is made up from a central server, one or more devices, and one or more web-based or GUI clients. The server and clients are connected to an IP network. Devices may be connected to AggreGate Server via IP network, serial ports, or any other method. The central server is actually a Java application running on Windows, Linux/Unix, Mac OS, or any other Java-enabled operating system. It is the only component of the system that attempts to stay online and connected to the network permanently. Network-enabled devices may use a wired or wireless connection to the network, such as WiFi, GPRS, or any other suitable wireless communications media. Some devices may be permanently connected to the network, while some may only connect to the network periodically. For example, devices may be configured to only turn themselves on at predefined time intervals or connect to the network when they detect an event that needs to be reported to the server. Unstable connection of other devices to the network may be caused by inherent unreliability of communications media being used. For example, WiFi and GPRS networks do not guarantee a constant connection to the network. The client (AggreGate Client) is a Java application running on a computer. The clients do not need to be permanently connected to the network for the system to function properly. The network may be a local-area network, wide-area network, or the Internet. Different segments of the network may use different communications media, such as Ethernet, WiFi, GPRS, or any other suitable media that is available now or will be available in the future.

2.1 Primary AggreGate Features

Device Connectivity Features
Multiprotocol vendor-agnostic framework. Direct support for many types of devices and device protocols (SNMP Modbus 145 , OPC 168 , and more).
154 ,

Hardware Controllers. Almost all present-day electronic devices may be connected to the system using programmable controllers (Agents 848 ). Software Device Drivers. Devices that are already network-enabled may be connected using a custom device driver 129 . Modular, scalable system architecture. New data processing/aggregation modules may be installed into server core as plug-ins 950 . The special Device Normalization technology ensures generic flexible approach for controlling, configuring and monitoring different types of hardware devices. Automatic discovery 1012 and provisioning of devices. Remote configuration Device data caching server.
677

of devices. and synchronization allows to configure devices that are temporarily disconnected from the
182

115

Device Simulator. Virtual software-based device

is available for testing and debugging purposes.

Device Management Features

Hierarchical multi-user A secure GUI client
776 108

environment with access control permissions

632 .

931 .

is available, along with a legacy web client of device status and events capabilities.
882 880 .

Real-time monitoring

791 206

Flexible event filtering

Support for event acknowledgements Customizable Alerts

216

by system operators, including e-mail acknowledgements.

supporting different types of notifications (sound, popup messages, e-mail, SMS etc.).
232 .

Support for pending alerts and alert escalation

Alert-to-action bindings 227 allow to execute corrective actions when alert is raised. Corrective actions may be controlled by operator or execute in non-interactive mode with pre-defined user input. Advanced reporting
241

facility, automatic report generation

812

from any viewed/edited data.

Built-in report editor, report printing and exporting in different formats.

2000-2013 Tibbo Technology Inc.

System Basics
Charting, support for many chart types, including dynamically updated charts. Integrated SQL-based query language
257 271

31

for data mining and batch configuration updates.

Trackers for monitoring mission-critical data. Every tracker has an unlimited number of user-defined states, indicated by color highlighting. Advanced job scheduler
248 266

for periodic execution of any device-related or system actions.

Grouping and group operations are available for different system objects (user accounts, alerts, event filters, queries etc.) and hardware devices. Advanced replication 909 of configuration between any similar system objects and devices. Configuration may be copied even between devices that use different firmware versions. Common data 260 tables store any custom data in a user defined format. System-wide or users personal common tables may contain master-copies of device settings that are used to configure multiple devices. Favorites Auto-run
626 625

allow access to commonly used actions. facility to start actions automatically upon operator login.
847

Interactive guides
1000

greatly that help new users to become familiar with basic system operations.

Link Service transparently routes data through the server between devices and computers located in private networks and hidden from each other by firewalls. Dynamic DNS Service
999

helps to locate devices that have no static IP addresses.

HTTP Proxy Service 998 provides global access to the web pages that are stored on the web servers embedded into devices located in private networks.

Development & Integration Features

Widgets 312 feature allow creating custom forms, GUI components and complex Human-Machine Interfaces (HMI) to configure and monitor your devices. Integrated GUI Builder application to create your widgets from scratch in WYSIWYG mode. Widgets may be combined into a dashboard to provide quick and convenient access to system-critical parameters. Expression language Expression Builder.
911

for flexible alert triggering rules, event filtering, and other data processing. Interactive

Support for server-side pure-Java scripts for fine-grained real-time server control and custom operations. Multiple time zones 108 support. Automatic time conversion in the case when server, users and devices are located in different time zones. Export/import any system or device data to numerous formats, including XML, HTML, CSV, XLS, PDF, RTF etc. Embedded Web-service Java and .NET software.
960 974 976

allows integration with third-party enterprise applications.

API's are available for easy integration with the customers CRM, ERP and other legacy
39

Flexible customization resources.

options, support for internationalization, localization and user-provided graphical and text

Java-based architecture, key system components work under most modern operating systems. Server component supports headless remote installation and administration. Compatible with most present-day database servers. An embedded database fast deployment. Failover clustering
87 80

is bundled with the server to ensure

for ensuring high availability.

99

Distributed architecture

for load balancing and multi-tier installations.

Comprehensive manual with many examples and tutorials 1210 .

2.2 Connecting Your Devices

Tibbo hardware and software products make it cheap and easy to network-enable your smart device and connect it to AggreGate. There are five ways to make an existing or new device work with AggreGate. The first four ways below describe how to connect devices in so-called "Intelligent Mode". In this mode, AggreGate is used to store and process data collected from the devices, and control and monitor them. AggreGate "understands" device settings, operations and events and therefore provides comprehensive control, configuration, monitoring and management capabilities.

(1) Connecting Device Using Standard Protocol

2000-2013 Tibbo Technology Inc.

32

AggreGate Documentation

If your device supports one of the standard communication protocols (e.g. SNMP), it may be directly connected to AggreGate using a bundled device driver 129 . No software or hardware protocol conversion is required in this case. Just set up all necessary physical connections and your device is ready to communicate with AggreGate Server.

(2) Connecting An Existing Device With AggreGate Agent

Using this method, you embed a Tibbo module, such as the EM1000, into your device. This module runs a BASIC application called Agent 848 . You modify the source for the Agent application so that it interfaces with your device ("understands" its communication protocol). It is then used as a transparent interface between AggreGate and your device, allowing you to access all device settings, data and events from within AggreGate.

Note that if for some reason you are unable to embed a device into your existing circuit, you can always use an external BASIC-Programmable Controller (such as the DS1202, the stand-alone version of the EM1202) running the Agent application.

(3) Designing A New Device Based On Programmable Module

Tibbo module, such as the EM1000, is powerful enough to serve as the central processor for your application. You can connect it directly to the various sensors and circuits of your device, and use it as the main CPU, locally controlling your

2000-2013 Tibbo Technology Inc.

System Basics

33

device's operation. In effect, you will be taking the Agent 848 application and greatly expanding and customizing it. You would be saving the cost of a CPU for your device, and still be able to connect to AggreGate and enjoy all of its benefits.

(4) Designing A New Device Using The AggreGate Communications Protocol

AggreGate's communication protocol 1303 is open and well-documented. For some large-volume applications, it may sometimes be economical to write a complete implementation of this protocol for the microcontroller you are already using. The microcontroller would then connect to AggreGate just like a device running Agent does. From the system's point of view, there would be no difference, and the device would work smoothly as a part of the system.

(5) Leaving Your Device Intact and Creating A Special Driver

You could also tackle the problem from a strictly software angle. A driver is a software component allowing AggreGate to "understand" the protocol for an existing device. Use Driver Development Kit 963 for coding a driver for your device to connect it to AggreGate without making any modifications to the device itself.

2000-2013 Tibbo Technology Inc.

34

AggreGate Documentation

(6) Using AggreGate To Transfer Raw Data (Without Processing It)

You might want to use AggreGate to just route data between your devices and/or computers running some devicespecific client software. In this case, AggreGate doesn't have to "understand" the data that being transferred, and does not store or process it. The Device Server converts data from the format supported by the device (RS232, USB etc.) to Ethernet traffic and routes it to and from the AggreGate Server.

This mode doesn't use the full power of AggreGate's data processing functions, but can be useful in several situations: When devices are located in different LANs protected by firewalls and thus cannot connect to each other. In this case AggreGate Server acts as a middle-man and routes data between these devices.

When devices don't have static IP addresses. In this case they can be registered in DNS by the AggreGate Server and can be accessed by their host names instead of IP addresses. Sometimes devices located in protected networks have embedded web-servers. These web-servers cannot be accessed directly, but AggreGate Server provides an HTTP proxy service that allows to establish a secure HTTP connection with the server instead of connecting to the device directly. AggreGate Server forwards this connection to the device. See Device Server Management
998

for more information.

2.3 Benefits of AggreGate

When designing a distributed system, most companies face the need to develop some kind of back-end software that will manage remote devices. A well-designed back-end software would adhere to a client/server paradigm, and creating such a software may be a daunting task that is both expensive and time-consuming. The often overlooked irony of any such development is just how similar it is to other projects of this kind. Analysis of typical distributed systems shows to up 90% of all required functionality of these systems is always the same. AggreGate provides a rich set of features and facilities to perform common device management and monitoring tasks. Device-specific operations may be implemented by custom software modules, or be performed by legacy software that communicates with AggreGate.

2000-2013 Tibbo Technology Inc.

System Basics

35

Benefits of using AggreGate for Device Management

IMMEDIATE BENEFITS:
Fast deployment and easy integration with existing enterprise software: AggreGate lets you leverage your existing infrastructure. No need to ditch anything you are currently using, or re-train your employees to use some new system. Take what you have, and expand on it. Predictive maintenance and automated operations : Vending machines can "call home" to let you know stock is running low, well before it runs out. This is just one example. Integrating most typical device management operations in a single distributed system: You don't need third-party applications for solving most typical device management tasks. Highly scalable and flexible architecture, easy customization for the customer's needs : you can have "your own" branded software system. Multi-user client-server environment, configurable access permissions: Allow multiple roles in your organization to access your device, but all on a "need to know" basis. Maximum availability along with maximum security - a winning combination. Automated reactions to alert conditions, including automatic execution of corrective actions: Common problems will be solved without intervention of system operators. User-defined business rules triggering interactive and non-interactive execution of custom procedures : Even in normal operating conditions many machine-to-machine, machine-to-enterprise and machine-to-human interactions may be automated and joined into complex chains.

LONG-TERM BENEFITS:
Reduced operational costs: By using reports and alerts you will know exactly what goes on in your distributed system. Points of waste (of time, money or other resources) will 'pop out'. Optimizing becomes obvious and easier. Reduced number of human errors: Manual alert acknowledgements increase operator accountability. Also, automated business rules and non-interactive actions performed on alerts allow the system to auto-correct some errors. High ROI: With reduced downtimes, your revenue-generating infrastructure will be working harder and more efficiently. Increased customer satisfaction, due to increased overall efficiency : With your system working as a concerted whole, customers enjoy a unified experience. Reduced number of field service visits and support call: Reduced number of field service visits and support calls: You could troubleshoot your devices remotely. Reboot your device, change its internal settings, and perform many other operations that normally require an on-site technician. Improved mean time to repair (MTTR): Not only will you get immediate notice when something goes wrong, you will also know exactly what went wrong. Get error codes, run diagnostics and perform other needed operations so that when your technician gets to the site, he knows exactly what the problem is. Eliminate the guesswork!

2.4 System Components

AggreGate is a complex multi-tier system. It includes four key components: AggreGate Server processing, etc. AggreGate Client
40

- the core component that is responsible for data routing and aggregation, business-rules - a GUI front-end application to control and monitor all other components.

776

AggreGate Agent 848 - a programmable gateway for converting device native protocol into AggreGate protocol and network-enabling the device. Device 113 - this is a general designation for any intelligent device that provide configurable settings and operations and can generate events. These are the machines you control with AggreGate.

AggreGate Integration Layers

2000-2013 Tibbo Technology Inc.

36

AggreGate Documentation

2.5 Unified Data Model

One of the most important and innovative concepts of AggreGate Platform is the unified server data model. This model is designed for aggregating various data from diverse hardware devices in a single system by converting data items into a "normalized" representation. Such normalized data can be: Stored in a central database; Uniformly processed and routed by bundled data mining tools; Presented, exported and imported using standard components; Made available in the integrated visual editors; Exposed to external systems using an SDK, different APIs and web services.

Contexts
The heart of the AggreGate data model is the context tree. The context tree is hierarchical structure of data containers called contexts 863 . The purpose of context is providing unified access to a certain system resource or hardware device. Thus, context exposes several objects:

Variables 869 (also called properties or settings ) for browsing or altering the configuration of underlying objects. Functions
878 (also called operations or methods) for performing operations with underlying objects by passing input and getting back output

Events 880 that are asynchronously generated by underlying objects and event routed listeners to that were previously registered within the context by someone wishing to receive event no Actions
892 that combine internal operations of underlying object and interaction with the human system operator within a single dynamic workflow

We might say that context acts as a "proxy" for a certain resource that is a subject for control or monitoring.

Data Tables
Another core concept of AggreGate data model is a standard data item called Data Table
854 .

This is a tabular data

2000-2013 Tibbo Technology Inc.

System Basics

37

structure used for representing: Values of variables Input and output values of functions Data associated with certain event instances Any other pieces of data flowing inside AggreGate Data Tables are very similar to the database tables since they have zero or more rows and several fields of certain format 856 . Here are several important facts about Data Tables: 1. For the sake of unification, scalar values (numbers, strings, booleans, dates) are represented as single-cell Data Tables, i.e. tables having one row and one field

2. Lists of diverse values are usually represented as single-row tables with multiple fields of diffe

formats, while arraysare better represented by single-field tables with multiple rows.
3. If type of Data Table's field is also Data Table, each cell in this field contains a nested Data Table. There could be an unlimited level of table nesting. 4. Data Table format descriptor 855 contains comprehensive information about field types, their meanings, value validation and presentation rules, cell cross-dependencies, etc.

2.6 Managing Your Devices

With AggreGate deployed in your facility, users may log in to AggreGate Server using the web interface or AggreGate Client and manage various hardware devices. AggreGate provides a rich set of device management operations. To be able to use the full range of these operations you need to connect your devices to the system in intelligent mode 32 .

Automatic Discovery And Provisioning Of Devices

The system uses generic approach for locating and configuring new devices: Device discovery. All network-enabled devices may be discovered by using broadcast commands and network scanning. AggreGate Server automatically creates device accounts for discovered devices thus making them available for system operators. Device provisioning. Every device that was discovered or is accessible by the server in the IP network may be automatically configured to connect to AggreGate Server on startup, complete the login sequence and start normal data exchange. The device then automatically reconnects to the server in the case of power failures or temporary communication problems.

Direct Management Operations

Direct management operations allow to work with devices that are currently connected to the server in real-time. These operations include: Configuration of remote devices. The settings for each device are clearly displayed, along with informative textual descriptions. Numerous types of devices may be supported, and the user's input is validated on the server itself before configuration is applied to the device, thus ensuring reliability and improving speed. Controlling devices. System operators may initiate operations provided by hardware devices. Most operations take input parameters and produce some output that may be reviewed upon execution. Monitoring device events. Events may be viewed in the Event Log immediately as they are received from hardware. Events may also require acknowledgement by operators. Event filtering. Events may be filtered out of the Event Log. Important events can be also highlighted in color.

Working With Offline Devices

When a device is disconnected from the server for some reason, you can still execute some operations with device data: Delayed configuration. View and edit settings of offline devices. These settings are read from server cache, and

2000-2013 Tibbo Technology Inc.

38

AggreGate Documentation

any changes are written back to the cache. The actual hardware device is reconfigured according to the new settings next time it synchronizes with the server. Browsing event history. Events received from devices are stored in the server database. Old events may be viewed even when the device is offline. Event history may be filtered and sorted according to different rules. Managing historical events. Events stored in the event history may be acknowledged and deleted by users that have access to the device which originated the event.

Device Status Monitoring

System operators constantly track the health of all hardware: System Tree status indication . Every device in the main "system tree" is represented by a dynamic icon giving a quick hint about its status. Extended status information is just a few clicks away. Trackers feature. Trackers are used to watch device settings or setting combinations in real-time. Each tracker may have an unlimited number of user-defined states indicated by color highlighting.

Customizing Access Control

Every device in the system is registered under a particular user account. However, the security environment provided by AggreGate allows flexible control of access to different devices: Sharing devices between users accounts. It is possible to let a user access a device which belongs to another user. Setting up permission levels. These define which operations a given user may execute with a device.

Group Operations
System operators may execute batch actions with several devices, as a group. Such grouped operations have several benefits: Device groups . Device groups facilitate selection of several devices to execute some operation with them. Devices may either be added to permanent groups or be dynamically grouped to execute just a single action. A device may belong to several groups. Reuse of input. If the operation executed requires input parameters, you specify them just once. The same parameters will be used for every device in the group. Aggregation of output . The output of all grouped operations is accumulated and presented to the user in a single "status report".

Alerting Services
Multi-functional alerts help detect and resolve device problems. Primary features of alerts: Different types of notifications. Support for visual, sound, e-mail and other types of notifications for alert owner and other system operators. Event and state triggers. Every alert may be triggered by device events, or by certain operating conditions or device status. Pending alerts. Pending alerts require operator acknowledgement. Support for pending alert instances may be enabled or disabled for any single alert. Alert escalation. Customizable escalation rules, including time-based escalation and escalation activated by a certain number of pending alert instances. Corrective actions. When an alert is raised, AggreGate Server may execute some corrective actions in automatic mode or request the system operator to execute some actions interactively.

Replication Of Device Configuration

AggreGate greatly simplifies configuring multiple devices in the same way and copying settings between different devices: One-to-one and one-to-many replication. Replication may be performed from one device to another specific device, to a whole group of devices, or to all devices accessible by the system operator. Selection of replicated settings. Before the actual replication process begins, the user may select which settings will be replicated and correct their values on-the-fly (right before they're replicated). Cross-firmware replication. Settings may be copied even between devices with different firmware versions.

2000-2013 Tibbo Technology Inc.

System Basics

39

Aggregated status report. Replication results are shown as a single status report containing a list of all errors (if any) in the replication action.

Data Querying and Reports

AggreGate Server data processing features let you select device data and present it to users in a convenient form: Query language. Integrated SQL-based query language helps find, filter, group and sort any device data. Editable queries. Editable query results let you select certain settings of several devices and edit them all at once, as a single table. Automatic report creation. Any data selected by a query or other method may be presented as a printable report. Data export. Report data may be exported to many well-known formats including PDF, HTML and XLS.

Periodic Job Execution

AggreGate Server includes an advanced job scheduler that can be used to set up automatic execution of different operations with hardware devices. Here are some basic properties of the job scheduling engine: Simple and advanced job triggers. Simple triggers allow periodic job execution, while advanced triggers let you set up complex calendar-based execution patterns. Predefined user input. If a scheduled action requires user input, this input may be pre-defined when the action is scheduled, for a non-interactive execution. Execution status reports. Successful job execution (as well as any problems) are logged and may be reviewed at any time.

Custom Forms And Human-Machine Interfaces (HMI)

Widgets are user-created graphical mini-applications, used as custom data manipulation forms and interfaces for monitoring, configuring and controlling devices/processes. GUI Builder. Integrated development environment for creating widgets in WYSIWYG mode from within AggreGate Client. Dashboard . Widgets may be combined into a virtual "dashboard", concentrating mission-critical status information and functions and making them more accessible and tangible than ever.

Other Device Management Features

Favourites. A Favourites table lets you execute commonly used actions with a single mouse click. Auto-Run. Functions may be automatically executed upon operator logon - the a widget Dashboard (see above) may be made to pop up upon login, for example.

2.7 Enterprise Integration

Tibbo AggreGate can collect and store all information from remote devices to a central server, giving your enterprise systems real-time data to speed operations. For example, a product fault detected using AggreGate can cause a trouble ticket to be automatically generated in a CRM system, dispatching field technicians with detailed information on required repairs. Usage data can be sent to billing and supply chain management systems, eliminating error-prone manual steps and vastly reducing process time delays (at times, even from months to minutes). Enterprise integration is enabled through Web Services and .NET API 974 .
976 ,

open-source Software Development Kit (SDK)

960

for Java,

2.8 AggreGate Customization

Tibbo provides flexible branding options for AggreGate, to create a distribution especially prepared and fine-tuned to your company's needs. These options include: Internationalization. All text resources may be translated to any language. Localization. This includes custom rules for formatting date/time and some other country-specific values. For example, a customized AggreGate bundle may define pre-defined date/time patterns 1321 . Substitution in text resources . It is possible to substitute single words or word combinations in all text resources without actually translating all resources to a different language. For example, if your Devices have Wi-Fi connectivity, you may wish to call them Access Points.

2000-2013 Tibbo Technology Inc.

40

AggreGate Documentation

Substitution of images . This includes changing product logos, splash screens, different icons etc. Further User Interface customization. Custom graphical components, themes, etc. Custom alerts 216 , reports 241 , event filters 206 , widgets 312 and other system objects. A customized AggreGate distribution may include any number of these objects that are created specifically for your needs. For example, if you are creating a system to monitor water tanks, it may include an Overflow Detected alert and Water Volume in Tank (per-hour) report. Custom plugins. Custom AggreGate Server plugins may allow connecting new intelligent hardware devices to the system, introduce new server contexts 863 of add new actions 892 to existing contexts. Custom Web-Services and Application Programming Interfaces (APIs) for interaction with different third-party systems. Such APIs act as a bridge between AggreGate and third-party systems such as billing, video surveillance and other enterprise-grade software. Database conversion scripts. These scripts may be helpful for importing/exporting data from different systems. Personalized startup scripts. Such scripts perform non-standard data processing operations that can't be easily requested from user interface components, such as changing alert settings en-masse. These scripts are usually launched on server startup and perform one-time actions. Contact Tibbo for more information about available customization options.

3 AggreGate Server
This chapter covers AggreGate Server, the core component of Tibbo AggreGate. It is responsible for data routing and aggregation, business-rules processing, etc. AggreGate is a complex system, containing many data processing modules. The interplay between these modules - the way the are used together - is what gives AggreGate its great flexibility and power. By getting to know each of these modules, you will eventually form an understanding of the system as a whole, and will be able to "cook up" solutions to whatever real-time scenario comes your way.

3.1 Requirements
AggreGate Server can potentially run under virtually any Java-enabled OS. It has been tested and verified to correctly run under the following Operating Systems: Windows 2000, XP, Vista, 2003 Server, 2008 Server, and 7 (32-bit and 64-bit versions) Linux (32-bit and 64-bit versions) Mac OS X

Hardware Requirements
AggreGate is a comprehensive device management solution capable of monitoring device networks of all sizes. Most AggreGate Server installations perform well on desktop-class systems. However, when managing larger networks or devices that generate significant amount of data, you need to give additional consideration to the hardware and system configuration used. Several factors can impact system scalability. The first is the number of devices that you will be monitoring with AggreGate. Performance tuning may be required when there are more than 100 devices. The second is the amount of data you collect from each device. The third factor to consider is monitoring time intervals. For example, if you set your synchronization time intervals to collect data every second instead of the default time intervals, AggreGate Server will have to work harder and system requirements will increase. Finally, the number of simultaneous operators accessing the system will directly impacts performance. When planning your AggreGate installation, keep in mind that CPU and memory usage is highly dependent to the types of managed devices and device drivers. In situations where many devices are controlled, it is recommended to use a dedicated, faster server. Server RAM usage depends on: Number of connected devices Number of device settings, operations and event types Number and complexity of data processing tools (alerts, reports and, especially, widgets) Number of concurrent client connections If you have additional questions or are experiencing performance problems, please contact Tibbo to speak with one of

2000-2013 Tibbo Technology Inc.

AggreGate Server
our system engineers or visit AggreGate website.

41

AggreGate Server Hardware

We provide several hardware configuration tables that are suitable for systems with low, medium and high per-device load. The below hardware requirements are just estimations. For example, a single controller providing ten thousand I/O channels that are polled at 10 Hz rate can require a dedicated powerful AggreGate Server for adequate data processing and storage. On the contrary, one server can support 100 000 hardware Agents 848 that connect to the server once per day to send several events each.

HARDWARE REQUIREMENTS FOR SERVERS WITH LOW PER-DEVICE LOAD

Low-level load implies an average of 10-30 settings/operations/events per device, with relatively small number of simple data processing tools (alerts, reports, trackers, models, widgets). Each device generates an average of less than 100 event instances per day. Each device generates an average of less than 100 event instances per day. Device Count Up to 10 Up to 30 Up to 100 Up to 300 Up to 1000 Up to 3000 Up to 10000 Up to 30000 Over 30000 CPU 500 MHz 1 GHz CPU Cores 1 1 RAM 256 Mb 512 Mb 1 GB 2 GB 4 GB 8 GB 16 GB 32 GB Disk Space 2 GB 5 GB 15 GB 50 GB 150 GB 500 GB 1000 GB 2000 GB 64-bit operating system highly recommended 64-bit operating system only, dedicated database server recommended 64-bit operating system and dedicated database server are required 64-bit operating system and dedicated database server are required, consider using multiple servers within distributed architecture 99 64-bit operating system and dedicated database server are required, using multiple servers within distributed architecture is highly recommended
99

Comments Such configuration is compatible with embedded environments (e.g. ARM Linux) Such configuration is compatible with embedded environments (e.g. ARM Linux)

1.5 GHz 1 3 GHz 2*3 GHz 2*3 GHz 4*3 GHz 4*3 GHz 8*3 GHz 2 4 8 16 24

32+

64 GB or more

4000 GB

HARDWARE REQUIREMENTS FOR SERVERS WITH MEDIUM PER-DEVICE LOAD

Medium-level load implies an average of 30-100 settings/operations/events per device, and an average number of data processing tools (alerts, reports, trackers, models, widgets). Each device generates an average of less than 1000 event instances per day. Device Count Up to 30 Up to 100 Up to 300 Up to 1000 Up to 3000 Up to 10000 CPU CPU Cores RAM 1 GB 2 GB 4 GB 8 GB 16 GB 32 GB Disk Space 10 GB 30 GB 100 GB 300 GB 1000 GB 2000 GB 64-bit operating system highly recommended 64-bit operating system only, dedicated database server recommended 64-bit operating system and dedicated database server are required 64-bit operating system and dedicated database server are required, consider using multiple servers within distributed Comments

1.5 GHz 1 3 GHz 2*3 GHz 2*3 GHz 4*3 GHz 4*3 GHz 2 4 8 16 24

2000-2013 Tibbo Technology Inc.

42

AggreGate Documentation

architecture Over 10000 8*3 GHz 32+ 64 GB or more 4000 GB

99

64-bit operating system and dedicated database server are required, using multiple servers within distributed architecture is highly recommended

99

HARDWARE REQUIREMENTS FOR SERVERS WITH HIGH PER-DEVICE LOAD

High-level load implies an average of 100+ settings/operations/events per device, with a large number of complex data processing tools (alerts, reports, trackers, models, widgets). Each device generates an average of more than 1000 event instances per day. Device Count Up to 30 Up to 100 Up to 300 Up to 1000 Up to 3000 Over 3000 CPU 3 GHz 2*3 GHz 2*3 GHz 4*3 GHz 4*3 GHz 8*3 GHz CPU Cores 2 4 8 16 24 RAM 4 GB 4 GB 8 GB 16 GB 32 GB Disk Space 20 GB 60 GB 200 GB 600 GB 2000 GB 64-bit operating system highly recommended 64-bit operating system only, dedicated database server recommended 64-bit operating system and dedicated database server are required 64-bit operating system and dedicated database server are required, consider using multiple servers within distributed architecture 99 64-bit operating system and dedicated database server are required, using multiple servers within distributed architecture is highly recommended
99

Comments

32+

64 GB or more

4000 GB

External Database Hardware

If AggreGate Server is using an external database, hardware requirements for the database server machine are normally same as requirements for the machine running AggreGate Server itself. Thus, it means that database server hardware requirements depend to the number of devices connected to the AggreGate Server and an average perdevice load. AggreGate Server should be connected to the database server via a fast dedicated network link. Dedicated Gigabit Ethernet link with latency (ping time) less than 5 milliseconds will ensure sufficient performance in almost every case.

Software Requirements
AggreGate Server requires the following software to work:

JAVA VIRTUAL MACHINE (JVM)

JVM is the only absolute requirement to run the AggreGate Server. The JVM may be bundled with the installer itself or pre-installed on the target system (see installation 43 ). The minimal version of JVM required to run the AggreGate Server is 1.6 (Java 6).

RELATIONAL DATABASE MANAGEMENT SYSTEM (RDBMS)

AggreGate Server requires an RDBMS to operate. Distribution packages supplied by Tibbo include a simple database engine that is used by default. For large-scale systems we recommend using an industrial-grade stand-alone RDBMS. AggreGate Server is compatible with a wide range of third-party database servers: MySQL PostgreSQL Oracle Microsoft SQL Server Firebird and many others.. AggreGate Server and the RDBMS don't have to be installed on the same server. It is also possible to configure AggreGate Server to work with remote database, but in this case its performance will depend on network conditions.

2000-2013 Tibbo Technology Inc.

AggreGate Server

43

DOMAIN NAME SYSTEM (DNS) SERVER

To use the Dynamic DNS 999 Service you need an RFC-2136 compliant DNS Server. This can be local or remote server. RFC-2136 (Request For Comments) specification is called "Dynamic Updates in the Domain Name System". Dynamic updates are supported by most present-day DNS Servers, including BIND and Windows 2000/2003 DNS service.

SMTP MAIL SERVER

A mail server is required to allow AggreGate Server to send alert notification e-mails. AggreGate Server is can communicate with virtually any SMTP mail server, including ones that require authentication.

3.2 Deployment and Administration

This chapter describes deployment, configuration and administration of the AggreGate Server. The AggreGate Server is a cross-platform Java-based product optimized for easy and fast installation. For further information, see AggreGate Server Installation
43

and AggreGate Server Configuration

51

3.2.1 Installing AggreGate Server

This chapter describes installation of the AggreGate Server software. Before installing the software be sure to check installation requirements 40 and procedure 43 . Most AggreGate installation bundles include both AggreGate Server and AggreGate Client be optionally selected during installation, while Server component is mandatory. However, AggreGate Client is also distributed as a standalone installer.
776 .

The Client may

3.2.1.1 Installation
Tibbo supplies pre-packaged installation files for the following operating systems: Windows 98, NT, 2000, XP, 2003 Server, Vista, 2008 Server, and 7 Different versions of Linux Mac OS X Installers for the other Java-enabled operating systems (FreeBSD and other unices, Solaris, etc.) are available on demand. To install the product, just run the installer executable file and follow the instructions. On some systems, you need to make the installation package 'executable' before running it.

Installation Modes
Installation can run in GUI, console or silent mode. GUI mode is selected by default. Console mode installation is activated by launching installer with '-i console' command line option, for silent mode user '-i silent'. Console mode is suitable for installation on systems that have no graphical user interface (this is the case with most UNIX servers).

Database Selection
By default, AggreGate uses an embedded database engine 80 that is not intended for production use. The server should be switched 81 to an enterprise class database as soon as possible after the installation. However, some distributions of AggreGate Server include pre-configured MySQL bundle 80 . If you are not planning to use another enterprise database (MS SQL, PostgreSQL, Oracle, or any other), it's recommended to enable MySQL package during installation. This will auto-configure AggreGate Server to use MySQL database right after the installation.

3.2.1.2 Upgrade
Upgrade is a complex procedure. Make sure to backup all data according to the below instructions to minimize system downtime if it fails.
To upgrade AggreGate Server to the new version, please follow this instructions carefully in order to protect server

2000-2013 Tibbo Technology Inc.

44

AggreGate Documentation

database from being corrupted: 1. Stop all AggreGate Clients 2. Stop AggreGate Server or service if server is running in the Windows Service Mode 3. Backup the database! Refer to Data Backup and Restoration
104 46

section for details.

Database backup is an important operation. Failing to backup the database before upgrade may result to data loss!
4. Backup AggreGate Server installation folder. Refer to Data Backup and Restoration
104

section for details.

Server installation folder backup is an important operation that should not be skipped in the production environment.
5. Upgrade server by running the installer of the new version 6. Upgrade all installations of AggreGate Client. Make sure to backup AggreGate Client installation folders before backup. 7. Upgrade firmware of all Devices 8. Start server or service 9. Check server log
74 113

if necessary

to make sure that server has been started successfully and database was upgraded

10.Start AggreGate Clients If the upgrade fails or the system does not work as expected, roll back to the previous version of AggreGate Server and AggreGate Client by restoring their installation folders and AggreGate Server database from backup. Contact Tibbo technical support for solving the problem.

Creating New Resources

The upgraded version of AggreGate may include lots of new built-in resources (alerts, reports, widgets, etc.). These resources are not created automatically during upgrade. If you'd like to make use of them, run Create Resources ( ) action from the root context 726 and select resources to create. See Managing Built-In Resources 107 for details.

3.2.1.3 Uninstallation
AggreGate Server is uninstalled by running uninstall executable file from AggreGate Server installation directory. It's recommended to stop the server manually before uninstallation. AggreGate Server uninstaller does not remove files created or modified by the AggreGate Server itself during its operation (configuration files, database, logs, etc.). To completely wipe out all AggreGate Server data, delete its installation once the uninstaller has finished working. This may be necessary to perform a "clean" reinstallation.

3.2.2 Startup and Shutdown

AggreGate Server is started by a special Launcher created during the installation process. Launcher type depends on the operating system: Under Windows, launcher is a small executable file, ag_server.exe, accessible through the Start menu (Start > Programs > AggreGate > Server) or as a desktop shortcut:

Under Unix , it's the AggreGate_server shell script, for example. AggreGate Server installer creates three launchers whose extension depends on the operating system: ag_server for a normal startup

2000-2013 Tibbo Technology Inc.

AggreGate Server
ag_server_console for starting server and showing its output in the console window (note, that logging and other destinations is not disabled in this case) ag_server_service for starting server as a service
46 74

45
to files

AggreGate Server may access privileged ports, i.e. port numbers below 1024. For example, it listens for SNMP Traps on UDP port 162. Therefore in most cases on Linux and Mac OS, it should be run with the root user privileges.
On Mac OS X for instance, AggreGate Server can be started from command line with the following command (assuming the application is installed in the /Application/AggreGate/ folder):

sudo

/Applications/AggreGate/ag_server.app/Contents/MacOS/JavaApplicationStub

SERVER STARTUP PROBLEMS

If your AggreGate Server fails to start or appears to work incorrectly, please check the following sections: AggreGate Server Startup Problems
1297

AggreGate Server Runtime Errors 1298 AggreGate Server Not Responding

1299

Launcher Properties File

Launcher properties file may be used to pass additional options to Java Virtual Machine running AggreGate Server. This file it located in the same directory with the launcher itself. Its name matches the launcher's name, and its extension is .vmoptions. For example, additional JVM options for a launcher called ag_server.exe are passed using Launcher Properties File ag_server.vmoptions. In this file, each line is interpreted as a single VM parameter.

It's absolutely necessary to add newline character (i.e. press ENTER when finished entering line text) in the end of every line of .vmoptions file. If there is no newline character in the end of line, it will be ignored! For example, is you have a one-line .vmoptions file, the only line must also end with new line character: -classpath/a jdbc-driver.jar<newline_character>
CHANGING LANGUAGE
Default launcher properties file contains -Duser.language=XX option that is used to define language used by AggreGate Server. Default language is selected during AggreGate Server installation process.

If the language was changed after the first launch of AggreGate Server, database 80 will contain data (system resource descriptions, events, etc.) in the language that was active during previous launches.
MODIFYING THE CLASSPATH
The following options may be added to the *.vmoptions files to modify the classpath of the AggreGate Server's Java Virtual Machine:

-classpath [classpath] -classpath/a [classpath] -classpath/p [classpath]

Replace the classpath of the generated launcher. Append to the classpath of the generated launcher. Prepend to the classpath of the generated launcher.

It's necessary to put exactly one space between -classpath parameter and its value.

2000-2013 Tibbo Technology Inc.

46

AggreGate Documentation

NEW TERM: A class path is the directory path specifying where compiled Java files are located on the local
system.

Append to classpath option of Launcher Properties File may be useful when making new Java libraries available to AggreGate Server. For example, Java Database Connectivity (JDBC) driver file path should be appended to the classpath when switching to another database engine 81 .

ADJUSTING MEMORY USAGE

The following options may be added to the *.vmoptions files in order to control amount of memory used by AggreGate Server:

-Xms

Initial amount of memory used by AggreGate Server. This parameter should be followed by the number of megabytes and m character, no spaces are allowed inside. For example, Xms200m parameter instructs the AggreGate Server to use 200 megabytes of memory at startup. Default value is 100 megabytes.

-Xmx

Maximum amount of memory that can be used by AggreGate Server. This parameter should be followed by the number of megabytes and m character, no spaces are allowed inside. For example, -Xmx1024m parameter allows AggreGate Server to use a maximum of 1 gigabyte. Default value is 800 megabytes.

Too high value of -Xmx parameter may cause AggreGate Server startup to fail because Java Virtual Machine needs this amount of memory to be available in a single contiguous block. In this case, switch to a 64-bit operating system and install 64-bit version of AggreGate Server. -Xss
Stack size of a single server thread, 128 kilobytes by default. Stack size should be decreased if thread creation failures caused Out Of Memory errors appear in AggreGate Server log file. Increase stack size is some device drivers or system components produce Stack Overflow errors.

3.2.2.1 Service Mode

AggreGate Server may be started in service mode (see Startup and Shutdown 44 section for details). A service runs independently of logged-on users and can be run even if no user is logged on. A service cannot rely on the presence of a console, nor can it open windows. Service mode behaviour depends on the operating system. AggreGate Server service is registered by the installer. It is configured for auto-launch during operating system startup.

Microsoft Windows
When the service is installed, it can be controlled through Start > Control Panel > Administration > Services.

INSTALLING AND UNINSTALLING THE SERVICE

You can also install the service from the command line by passing /install to the service executable ( ag_server_service.exe). To prevent the automatic startup of your service when the computer is booted, pass the argument /install-demand instead. As a second parameter after the /install parameter, you can optionally pass a service name. In that way you can install a service with a different service name than the default name. Service is uninstalled by passing /uninstall to the service executable. All command line switches also work with a prefixed dash instead of a slash (i.e, -uninstall) or two prefixed dashes (i.e, --uninstall).

STARTING AND STOPPING THE SERVICE FROM COMMAND LINE

2000-2013 Tibbo Technology Inc.

AggreGate Server

47

To start or stop the service, the /start and /stop options are available. In addition, a /status argument shows if the service is already running. The exit code of the status command is 0 when the service is running, 3 when it is not running and 1 when the state cannot be determined (for example, when service is not installed on Windows).

Linux/Unix
For Unix service executables, the start, stop, restart and status arguments are available for the control script ( ag_server_service). This script is located in AggreGate Server installation directory, but a symlink to it is also created in services initialization directory ( /etc/init.d or /etc/rc.d/init.d). The stop command waits for the service to shut down. The exit code of the status command is 0 when the service is running and 3 when it is not running.

status command shows whether AggreGate Server daemon is running or not.

STARTING/STOPPING THE SERVICE
To start AggreGate Server, run the following command: service ag_server_service start To stop the server: service ag_server_service stop

3.2.2.2 Command Line Parameters

AggreGate Server can be run with any of the following command-line parameters: Parameter Description Enable safe mode
106 .

-a -c

Create database 80 structure. This option instructs AggreGate Server to try (re-)creating its database schema including all tables and indexes. No existing tables or indexes will be affected by this operation.
50

-e <filename> Execute script

file <filename> on startup.

52

-f <filename> Use global configuration file -h

<filename>.

Print the list of command line options and exit.

-o <directory Set home directory to <directory>. > -p <user> < pass>

Set new password <pass> for account Example: %program
108

<user>.

files%\AggreGate\Server\AggreGate_server.exe -

p admin 12345
This command will start AggreGate Server and change password of user admin to 12345.

-s <filename> Execute SQL commands -u

50

contained in file <filename> on startup.

Update database 80 structure after upgrading AggreGate Server to newer version. This option forces AggreGate Server to create missing database tables add missing fields into existing tables. Note, that no indexes are ever created by this operation. When migrating to a new database engine 81 , it's always necessary to use -c command line option for creating all tables with indexes.

3.2.2.3 Shutting Down The Server

There are several ways to shut down the AggreGate Server: Using a AggreGate Client Using a Web Desktop
632 , 776

application, when connected to the server with appropriate permissions.

when logged on with appropriate permissions.

108 .

Using the System Tray Icon menu

2000-2013 Tibbo Technology Inc.

48

AggreGate Documentation
49

Using the Net Admin

interface.
46

By stopping Windows/Linux service is the server is running in service mode

By manually killing all server processes if the server is not responding to any other shutdown attempts.

In some cases, it may take up to several minutes for the AggreGate Server to complete the shutdown sequence and save cached data to the database. Terminating server process during shutdown by using operating system tools can cause data loss.
When shutting down the virtual machine the AggreGate Server is running on, the AggreGate Server shutdown sequence is automatically executed as well.

Server Shutdown Methods

All AggreGate Server shutdown methods are described below.

USING AGGREGATE CLIENT

To stop the server via AggreGate Client connection: Find the server node ( Right-click on it Select Stop Server from context menu You should have Administrator
932

) in the System Tree

784

permissions in the Root context

726

to be able to stop the server remotely.

USING WEB DESKTOP

To stop the server from inside the Web Desktop Find the server node ( Right-click on it Select Stop Server from context menu You should have Administrator
932 632 :

) in the System Tree

permissions in the Root context

726

to be able to stop the server.

USING TRAY MENU

Select Stop Server item from AggreGate Server tray menu
108 .

The tray menu is not available if server is running in service mode

46

STOPPING THE OPERATING SYSTEM SERVICE

To stop the AggreGate Server if it is running in service mode
46

Under Windows, go to Start Menu > Control Panel > Administration > Services, find AggreGate Server service, right-click on it and select Stop. Under Linux, open a console and type service ag_server_service stop.

USING NET ADMIN

Access the Net Admin 49 interface via telnet to port 6440, and use it to shut the server down (S command) or restart it (R command).

MANUALLY KILL THE PROCESSES

This method is not recommended, as it might kill other Java processes running on the host. It should be used only if the server is not responding to all other shutdown attempts.

2000-2013 Tibbo Technology Inc.

AggreGate Server

49

Under Windows, the processes to kill are ag_server.exe, ag_server_service.exe, ag_server_console.exe. Kill all instances of these processes using the Task Manager (Ctrl+Shift+Esc under Windows). Under Unix , the processes to kill are ag_server, ag_server_service, ag_server_console and java. There are many Java processes active at any one time. Kill the process with the lowest PID (Process ID). This is important. Killing another process will not resolve the problem. There are specific instances where one should kill another process than the one with the lowest PID, but these are special cases, which depend on specific server configurations. Killing the process with the lowest PID will most likely resolve this situation.

3.2.2.4 Net Admin

Net Administrator is a feature used to control the server from the local host without any authorization. Net Admin can be used even when it is not possible to connect to the server using AggreGate Client or access its Web Desktop 632 , and the System Tray icon 108 is also unavailable (i.e. on a system without graphical user interface). If is usually used to debug AggreGate Server installations if other methods (<%AGCL%> 776 , Web Desktop 632 ) are not working for some reason. Net Admin is accessed using Telnet or any other Telnet-like software. You have to telnet from the PC on which the AggreGate Server is running. You cannot access the Net Admin from any other host. To access the Net Admin: Make sure you are working on the server actually running AggreGate Server. Telnet to 127.0.0.1 (localhost), port 6440. You should get a connection, and no prompt. Type a Net Admin command and hit Enter. Net Admin commands are described in the Net Admin and Startup Script Command Reference 49 . If the command was successful, you will get an A (Ack) and an optional answer text. If the command failed, you will get an E (Error) and an optional error description. The Net Admin interface is enabled by default. It is used during automatic upgrade or uninstallation of the AggreGate Server. If untrusted users have local access (by Unix shell or physical access) to the host running AggreGate Server, this feature should be disabled for security reasons. It can be disabled using the Web Admin interface.

3.2.2.4.1 Net Admin and Startup Script Command Reference

This article contains a reference of commands supported by Net Admin
49

and Startup Scripts

50

processing engine.

Command arguments are separated by the "/ " character. Every line in a startup script may contain just one command.

Executing Net Admin and Startup Script commands that change the state of server context tree may put server into the inconsistent state or corrupt the database. Backup your database before executing
SUPPORTED COMMANDS
E R W Stop server Restart server Restart Web Server embedded into the AggreGate Server

S/ context_mask /variable/value_for_row1_column1/ Set value of a context 863 variable 869 . Sets a value of variable ' value_for_row1_column2/... variable' in every context corresponding 865 to 'context_mask ' to the Data Table 854 created 50 from the subsequent command parameters. C/context_mask/function/value_for_row1_column1/ Calls function 'function ' from every context corresponding value_for_row1_column2/... 'context_mask ' passing data table created 50 from the subsequent command parameters as an input value. F/context_mask/variable/setField/setValue[/ searchField/searchValue]
865

to

Set field 'setField' of first record of value of variable 'variable' in every context corresponding 865 to 'context_mask ' to 'setValue'. If 'searchField' and 'searchValue' parameters are specified, value is changed in the records where value of field ' searchField' equals ' searchValue'.

2000-2013 Tibbo Technology Inc.

50

AggreGate Documentation

Creating A Data Table using Command Arguments

During the processing of some commands (Set Variable, Call Function etc.) a Data Table command arguments as described here 862 .
854

is created from the list of

If an argument value is surrounded with "$" characters, AggreGate Server will take the data for that parameter from the filename specified. The filename should be in the AggreGate Server installation directory. For example, if the parameter value is "$parameterizer.xml$", AggreGate Server will obtain the data for that parameter from " parameterizer.xml".

3.2.2.5 Startup Scripts

AggreGate Server can execute two types of scripts during its startup: Command scripts and SQL scripts.

Commands Scripts
A Command script may contains the same commands that are accepted by the Net Admin 49 , one per line. These commands are described in the Net Admin and Startup Script Command Reference 49 . Commands that are not applicable during the startup of the server (i.e. " stop server", "restart server ") are not executed. Any output provided by the executed commands is discarded. Commands Scripts may be used to repair damaged AggreGate Server installations or pre-create system objects (Event Filters 206 , Alerts 216 etc.) in custom installations. Command scripts may include comments: Lines beginning with # will not be processed. To execute a command script, run AggreGate Server with the with a -e <filename> command line option. (Where filename is the name of the script file).

EXAMPLE OF A COMMAND SCRIPT

# Create new event filter called "Keytroller Events" for every user in the system C/users.*.filters/create/keytroller/Keytroller # Show some additional fields in Event Log S/users.*.filters.keytroller/additionalFields/description/Description/Keytroller Events/1/timestamp/Description/Keytroller Events/1/userid/Description/Keytroller Events/1/username/Description/Keytroller Events/1/machine/Description/Keytroller Events/1/data/Description/Keytroller Events/1 # Do not show event names in Event Log F/users.*.filters.keytroller/shownFields/event/0 # Do not show event data in Event Log F/users.*.filters.keytroller/shownFields/data/0 # Do not show event acknowledgements in Event Log F/users.*.filters.keytroller/shownFields/ack/0 # Set default Device Driver to Keytroller F/config/general/defaultDevicePlugin/com.tibbo.linkserver.plugin.device.keytroller Events

SQL Scripts
SQL Script contains SQL commands that are executed directly on the AggreGate Server database during server startup, one per line. To execute a command script, run AggreGate Server with the with a -s <filename> command line option. (Where filename is the name of the script file). SQL scripts may include comments: Lines beginning with # will not be processed. Executing SQL commands may corrupt your AggreGate Server database. Backup your database before executing any SQL scripts.

EXAMPLE OF SQL SCRIPT

# Emergency removal of user account 'john' and all associated data: (may be useful if account was # corrupted) # Removing user account

2000-2013 Tibbo Technology Inc.

AggreGate Server delete from ag_users where ag_username = 'john' # Removing Device Server accounts delete from ag_deviceservers where ag_owner = 'john' # Deleting all persistent properties in all contexts delete from ag_properties where ag_context like 'users.john.%' # Deleting persistent events in contexts owner by John delete from ag_events where ag_context like 'users.john.%'

51

3.2.3 Configuration
There are several basic ways to perform configuration of AggreGate Server: Using Server Configurator
51

utility.
51

Using AggreGate Client software (see Client-based configuration Through the Web Desktop
632

).

using a standard browser like Internet Explorer or Mozilla Firefox.

By editing an XML configuration file (see File-based configuration 52 ). This is for troubleshooting, and can be used to correct one or two settings when AggreGate Server can't start and other methods are not available.

3.2.3.1 Server Configurator

Server Configurator is a small utility shipped with AggreGate. It opens server global settings in a Properties Editor 795 and allows to adjust them. The settings are loaded from and saved to AggreGate configuration file (server.xml by default). Server Configurator allows to adjust only file-based 53 server global settings, not the ones stored in the database. Thus, only a small amount of server settings can be changed using the utility. These are mostly the settings required to start the server, e.g. database connection settings. For changing other settings, start configuration of a running server using AggreGate Client or Web Desktop. Server Configurator utility accepts a single command line option: path of server configuration file. If this option is omitted, the default file (server.xml) is edited.

3.2.3.2 Client-based Configuration

Once AggreGate Server is running, you can easily access its global configuration options from within AggreGate Client
776 , by launching the Configure Server 726 ( ) action from the context menu for the Server Node Tree) 784 . Some additional information may be found here 726 . 789

(in the System

Once you save the new settings, the Configure Server asks for a confirmation and then reboots AggreGate Server. Some settings are system-critical, and providing them with incorrect values may prevent AggreGate Server from starting correctly after reboot. In this case, client-based configuration may not be available. You're going to have to manually edit the configuration file to fix it (see file-based configuration 52 ). So make sure you know what you're doing when editing these global settings. Here is what the AggreGate Server Global Settings dialog looks like in AggreGate Client:

2000-2013 Tibbo Technology Inc.

52

AggreGate Documentation

3.2.3.3 File-based Configuration

File-based configuration should be used if AggreGate Server fails to start and other configuration methods are not available. The default configuration file is server.xml. An alternative filename can be specified using the '-f <filename>' command line option 47 . It is important to note that AggreGate Server not only loads configuration file at startup, but also saves its settings during shutdown. Manual changes made in the file while AggreGate Server is running will be overwritten. The configuration file is in XML (eXtensible Markup Language) format. Here is an excerpt:

<config> <firstLaunch>false</firstLaunch> <previousVersion>31001</previousVersion>

2000-2013 Tibbo Technology Inc.

AggreGate Server <locale>ru</locale> <usersSelfRegistration>true</usersSelfRegistration> <configGuiMode>auto</configGuiMode> <netAdminPort>6440</netAdminPort> <netAdminEnabled>true</netAdminEnabled> <databaseDriver>org.apache.derby.jdbc.EmbeddedDriver</databaseDriver> <databaseUrl>jdbc:derby:database;create=true</databaseUrl> ... </config>

53

The file is generated automatically by AggreGate Server, and there's no need to manually add options to it. When troubleshooting, you might have to change the value of some settings. You can find detailed description of available settings under Global configuration
53

3.2.3.4 Global Configuration Options

This chapter global settings of the AggreGate Server. If global settings were changed, server must be restarted in order to activate new settings. Global settings can be edited using Server Configurator 51 , Web Admin 632 or AggreGate Client Server Configuration 51 section for more information on how to access these settings. The following setting groups are available: Settings Group Genera
53 55 776 .

See AggreGate

Storage Location Configuration File Configuration File Configuration File

59 52 52 52 52 52 52

Database Cluster
59

, Database Cluster Configuration File

92

Web Applications Dynamic DNS Mail Settings

61 63

Configuration File Configuration File Configuration File

65

Advanced Mail Settings SMS Sending

69

Database

80 52

Configuration File
70 72 73

Event Expiration Times Custom Event Writers

Database Database Database Database

80 80 80 80

Default User Permissions

Additional Permissions For New Users 73

73

Default Synchronization Options Database Statistics

73 74

80

Database Database

80 80

Active Plugins

3.2.3.4.1 General Settings

This group defines AggreGate Server global parameters that do not belong to any subcategory.

Server Instance Description

Key name in the configuration file: serverDescription Value type: String

2000-2013 Tibbo Technology Inc.

54

AggreGate Documentation

Possible values: Any printable string Default value: Textual description of this AggreGate Server instance.

Server Time Zone

Key name in the configuration file: timezone Value type: String Possible values: A list of time zones supported by Java VM Default value: Time zone set up in the operating system under which AggreGate Server is launched, or GMT if the OS time zone can't be detected. See Dealing with Time Zones 108 for more info.

Server IP Address
Key name in the configuration file: serverIp Value type: String Possible values: Any valid IP address or empty string Default value: "" (empty) If this setting is set to a valid IP address, AggreGate Server listens for incoming connections of Devices, AggreGate Clients and Web Desktop 632 users only on this IP address. This setting may be useful to run multiple instances of AggreGate Server on a single hardware server that has several IP addresses. In this case, every instance of AggreGate Server will accept incoming connections on the same ports, but on different IP addresses. Set this setting to a non-empty value only if it's absolutely necessary to accept connections only on a single IP or network interface. For example, if Server IP is set to 192.168.1.5, the AggreGate Client running on the same machine won't be able to connect to the server using localhost address.

Other system services that accept incoming network connections, such as SNMP Trap Listener setting to listen for connections on a certain IP address only.

178 ,

use this

This IP address is also written as a Destination IP to the External Device Servers 1012 that are being connected AggreGate Server.

1014

to the

Server Host Name

Key name in the configuration file: serverHostName Value type: String Possible values: any valid network host name or empty string Default value: "" (empty) If this setting has a value, it is used as an additional alias
60

by the embedded web server.

1011 .

Also, it is used to access Device Servers that work through HTTP Proxy

Enable users self-registration

Key name in the configuration file: usersSelfRegistration Value type: Boolean Possible values: true or false Default value: true When enabled, anyone who can access Web Desktop 632 or an AggreGate Client 776 installation can register a user account, log in and use AggreGate Server. When this option is disabled only registered users with corresponding permissions can add new user accounts 109 .

Enable GUI mode

Key name in the configuration file: configGuiMode Value type: String

2000-2013 Tibbo Technology Inc.

AggreGate Server
Possible values: yes, no, auto Default value: auto

55

This option defines whether the AggreGate Server will make any output to the GUI (Graphical User Interface) of the server. GUI output used includes: Splash Screen at startup, icon 108 in the System Tray, and error message boxes. When this option is disabled, no output to the GUI will be made.

Client port number

Key name in the configuration file: clientPort Value type: Integer Possible values: 1-65535 Default value: 6460 This option defines the port on which client connections will be accepted.

Enable Net Admin

Key name in the configuration file: netAdminEnabled Value type: Boolean Possible values: true or false Default value: true This option enables or disables local Telnet access to the Net Admin 49 interface. It is recommended to turn this option off if untrusted users have local (physical or shell) access to the host running AggreGate Server.

Net Admin port number

Key name in the configuration file: netAdminPort Value type: Integer Possible values: 1-65535 Default value: 6440 This option defines the port on which local Net Admin
49

connections will be accepted.

Statistics data folder

Key name in the configuration file: statisticsFolder Value type: String Possible values: Any allowed folder name. Default value: statistics Relative or absolute path of folder that is used for statistical channel
936

data storage.

3.2.3.4.2 Database
Options in this group control how AggreGate Server stores its data in the database
80

Database Clustering
Key name in the configuration file: databaseCluster Value type: Boolean Possible values: true or false Default value: false If this option is disabled, AggreGate Server works with a single database, that is the "classic" behaviour. If enabled, the server works with multiple databases by replicating all write operations to each database and loadbalancing all read operations. In this case: Database URL
56

setting is disabled

2000-2013 Tibbo Technology Inc.

56

AggreGate Documentation
56

Cluster Databases

table is enabled, allowing to configure databases participating in the cluster.

89

See database failover cluster

for more information.

Database Driver
Key name in the configuration file: databaseDriver Value type: String Possible values: Any Java class name corresponding to a JDBC driver Default value: org.apache.derby.jdbc.EmbeddedDriver This option defines which JDBC (Java Database Connectivity) database driver will be used. Technically, it's a name of the driver's main java class. For example, to use MySQL database for data storage set this option to com.mysql. jdbc.Driver. Consult JDBC driver documentation to find out the proper value. To allow AggreGate Server load any third-party JDBC database driver, a JAR (Java Archive) file containing this driver must be added to the server classpath by putting it into /lib subdirectory of AggreGate Server installation or using AggreGate Server Launcher Properties File 45 .

Database URL
Key name in the configuration file: databaseUrl Value type: String Possible values: Database-dependent path string Default value: jdbc:derby:database;create=true This is a database-specific string that defines the database type, the file system path (local or network) to a database containing AggreGate Server data tables and any additional options. To figure out the correct value for your selected JDBC database driver, please consult its documentation. The default value for this option makes AggreGate Server use its embedded Apache Derby database to store data in ordinary text files in the database/ subdirectory of the AggreGate Server installation.

Cluster Databases
Key name in the configuration file: N/A, value is stored in Database Cluster Configuration File Value type: Data Table Possible values: N/A Default value: N/A The Cluster Databases table allows to view status and configure all databases in the Database Failover Cluster by AggreGate Server. Each database in the cluster is configured by the following settings: Database ID . A unique user-defined string identifier of the database in the cluster. Database URL. The address of the database. See Database URL specific notes 81 for more information.
56 91 92

used

setting of non-clustered database and database-

Weight. The greater is database weight in the cluster, the more read requests it will get. Local. This flag should be set if the database is located on the same server machine with this AggreGate Server instance. Active. This is a read-only field that shows whether a database is currently being used by the cluster.

SAVING CLUSTER DATABASES

When the Cluster Databases table is being saved, the server performs several procedures for the new and changed database records: Connection with each database is being tested Each newly added database is activated
92

, i.e. connected to the working cluster

Data is being synchronized between new/changed database and other databases in the cluster Since data synchronization may take significant time, saving Cluster Databases table may hang for several minutes.

2000-2013 Tibbo Technology Inc.

AggreGate Server

57

MANUAL CLUSTER DATABASES EDITING

Cluster databases are stored in the Database Cluster Configuration File without using Server Configurator 51 .
92

. It is possible to edit this file directly

93

Database Username
Key name in the configuration file: databaseUsername Value type: String Possible values: Any username suitable for the database server Default value: sa This option defines which username is used to log on to the database server. The default value allows connection to AggreGate Server's embedded database engine.

Database Password
Key name in the configuration file: databasePassword Value type: String Possible values: Any password suitable for the database server Default value: "" (empty) This option defines which password is used to log on to the database server. The default value allows connection to AggreGate Server's embedded database engine.

Database SQL Dialect

Key name in the configuration file: databaseSqlDialect Value type: String Possible values: Value Database Server InterSystems Cache DB2 DB2 AS/400 DB2 OS390 Apache Derby (v10.7 or above) Firebird FrontBase H2 Hypersonic SQL Informix Ingres Interbase JDataStore Mckoi SQL Mimer SQL MySQL 5 MySQL Oracle (any version) Oracle 9/10g Pointbase

Cache71Dialect DB2Dialect DB2400Dialect DB2390Dialect DerbyTenSevenDialect FirebirdDialect FrontbaseDialect H2Dialect HSQLDialect InformixDialect IngresDialect InterbaseDialect JDataStoreDialect MckoiDialect MimerSQLDialect MySQL5InnoDBDialect MySQLInnoDBDialect OracleDialect Oracle9Dialect PointbaseDialect

2000-2013 Tibbo Technology Inc.

58

AggreGate Documentation

PostgreSQLDialect ProgressDialect SAPDBDialect SQLServerDialect Sybase11Dialect SybaseDialect SybaseAnywhereDialect

Default value: DerbyTenSevenDialect

PostgreSQL Progress SAP DB Microsoft SQL Server Sybase 11 Sybase Sybase Anywhere

This option defines the Java class name for the database SQL dialect. For example, use MySQLDialect if you use MySQL database to store data. If your database server is not listed in the table above, please contact the technical support team.

Minimum Connection Pool Size

Key name in the configuration file: databaseMinimumPoolSize Value type: Integer Possible values: 1 or more Default value: 3 The minimum number of database connections to keep in the pool.

Maximum Connection Pool Size

Key name in the configuration file: databaseMaximumPoolSize Value type: Integer Possible values: 1 or more Default value: 200 The maximum number of database connections to keep in the pool. Maximum pool size must be set lower than the maximum number of simultaneous connections allowed to the backend database. Failure to do so will result to significantly degraded performance or unpredictable database errors.

Connection Checkout Timeout

Key name in the configuration file: databaseCheckoutTimeout Value type: Long Possible values: 0 or more Default value: 30000 Defines how long (in milliseconds) the server will wait for each database connection to be acquired from the connection pool. Zero value means wait indefinitely. Zero value is recommended for production environment, but default value defines relatively short timeout for the sake of fast database problem detection during system deployment.

Batch Size (zero to disable batch updates)

Key name in the configuration file: databaseBatchSize Value type: Integer Possible values: 0 or more Default value: 50 Maximum number of changes in a batch update, i.e. JDBC2 batch size.

Disable Connection Pooling

Key name in the configuration file: databaseDisablePooling Value type: Boolean

2000-2013 Tibbo Technology Inc.

AggreGate Server
Possible values: true or false Default value: false When connection pooling is disabled, all database connection errors are logged connectivity, for example when switching to a new database engine 81 .
74

59

. This helps to troubleshoot database

This option should be turned on only temporarily, for debugging purposes. It greatly reduces server performance.

3.2.3.4.3 Cluster
Options in this group are responsible for the AggreGate Server failover cluster
87

node configuration.

Cluster Role
Key name in the configuration file: clusterRole Value type: Integer Possible values: 0 for None, 1 for Master and 2 for Failover Default value: 0 Defines role of this AggreGate Server installation in the failover cluster.

Failover Mode
Key name in the configuration file: clusterFailoverReadonly Value type: Boolean Possible values: true or false Default value: false Defines whether this failover node works in read-only mode, i.e. its database write operations are disabled.

Node Failure Detection Time

Key name in the configuration file: clusterFailureDetectionTime Value type: Long Possible values: 4000 to 86400000 Default value: 20000 Time in milliseconds required for the cluster nodes to mark a certain node as "dead" if it does not perform database updates. Failover nodes will activate themselves and switch to Failover Master mode if master node is inactive for longer than the Node Failure Detection Time Master node will emit a warning event if no failover nodes are alive for longer than the Node Failure Detection Time

3.2.3.4.4 Web Applications

Options in this group control the behaviour of the AggreGate Server Web Applications (Web Desktop 976 , HTTP Proxy 1011 etc).
632 ,

Web Service

Enable Embedded Web Server

Key name in the configuration file: webServerEnabled Value type: Boolean Possible values: true or false Default value: true Defines whether AggreGate Server's integrated web server is enabled. If it's disabled, all web-based services (Web Desktop 632 , Web Services 976 , etc.) are not available.

Enable Web Desktop

2000-2013 Tibbo Technology Inc.

60

AggreGate Documentation

Key name in the configuration file: webDesktopEnabled Value type: Boolean Possible values: true or false Default value: true Defines if the Web Desktop
632

application is loaded during AggreGate Server startup and available for connections.

Enable Web Service

Key name in the configuration file: webServiceEnabled Value type: Boolean Possible values: true or false Default value: true Defines if the AggreGate Server Web Service
976

is available for other applications.

Enable non-secure access to web applications

Key name in the configuration file: webNonSecureAccessEnabled Value type: Boolean Possible values: true or false Default value: false Defines if AggreGate Server Web Applications may be accessed using a non-secure HTTP protocol. Normally this option should be disabled to allow only secure HTTPS (SSL-based) access.

Comma-separated list of host name aliases

Key name in the configuration file: webAppsAliases Value type: String Possible values: One or more network host names separated by commas Default value: "" (empty) Defines the host name(s) by which AggreGate Server Web Applications (Web Admin, Web Service, HTTP Proxy 1011, etc. ) can be accessed. This option will work if the specified host names are correctly setup in the DNS. It should be set in addition to configuring your DNS server.

Port number to listen for HTTPS (secure) connections

Key name in the configuration file: webAppsSslPort Value type: Integer Possible values: 1-65535 Default value: 8443 Defines the port number on which Web Admin application will be available. You can change this option's value to 443 if there are no other web servers listening on this port. 443 is the default HTTPS port number. It is not recommended to use 80 as the value of this option, because 80 is default port number for non-secure HTTP protocol.

Port number to listen for HTTP (non-secure) connections

Key name in the configuration file: webAppsNonSslPort Value type: Integer Possible values: 1-65535 Default value: 8080 Defines the port number on which AggreGate Server Web Applications will be available. You can change this option's value to 80 if there are no other web servers listening on this port. 80 is the default HTTP port number.

2000-2013 Tibbo Technology Inc.

AggreGate Server

61

3.2.3.4.5 Dynamic DNS

Options in this group are responsible for the Dynamic DNS service
999 .

Enable dynamic DNS updates

Key name in the configuration file: ddnsEnabled Value type: Boolean Possible values: true or false Default value: false Allows connecting Device Servers 1003 to register in the DNS. For a Device Server to register itself in dDNS, dDNS registration must also be enabled in its settings.

Zone name
Key name in the configuration file: ddnsZone Value type: String Possible values: Any valid DNS domain name Default value: "" (empty) This option defines DNS zone (domain) name to which AggreGate Server will add hosts corresponding to Device Servers. This can be a domain name in your company's local DNS (within your LAN or Intranet) or a global Internet domain name like "company.com" (if you own one).

IP address of DNS server

Key name in the configuration file: ddnsServerIp Value type: String Possible values: Any IP address Default value: "" (empty) Defines the IP address of the DNS server used for Dynamic DNS updates.

Port number on DNS server to communicate with

Key name in the configuration file: ddnsServerPort Value type: Integer Possible values: 1-65535 Default value: 53 Defines the destination port number on the DNS server used for Dynamic DNS updates.

Enable Transaction Signature (TSIG) keys

Key name in the configuration file: ddnsUseTsigKeys Value type: Boolean Possible values: true or false Default value: false This option enables using Transaction Signature (TSIG) keys for making communication with DNS server secure. TSIG keys are a form of DNS security. You can learn more about them at http://en.wikipedia.org/wiki/TSIG

TSIG key name

Key name in the configuration file: ddnsTsigKeyName Value type: String Possible values: Any string value conforming to the Dynamic DNS specification Default value: "" (empty)

2000-2013 Tibbo Technology Inc.

62

AggreGate Documentation

Defines the name of the key to be used for Transaction Signatures (TSIG).

TSIG key value

Key name in the configuration file: ddnsTsigKeyValue Value type: String Possible values: Any string value conforming to the Dynamic DNS specification Default value: "" (empty) Defines the value of key to be used in Transaction Signatures (TSIG).

Enable TCP mode

Key name in the configuration file: ddnsTcpMode Value type: Boolean Possible values: true or false Default value: true If this option is set to true, TCP protocol is used for DNS updates, otherwise all transactions are performed using UDP.

Timeout for DNS operations, seconds

Key name in the configuration file: ddnsTimeout Value type: Integer Possible values: Any positive integer number Default value: 10 Defines timeout for DNS update operations. If no answer is received from the DNS server within this time, the DNS update operation is considered unsuccessful.

TTL for new DNS records, seconds

Key name in the configuration file: ddnsTtl Value type: Integer Possible values: Any positive integer number Default value: 600 Defines Time To Live (TTL) interval that is set for all newly created DNS records. When a caching (recursive) nameserver queries the authoritative nameserver for a resource record, it will cache that record for the time (in seconds) specified by the TTL. A low value of this setting leads to high number of dDNS updates. A high value results in a slower update of information (and thus less update requests). This value is counted in seconds (600 equals 10 minutes).

Host pattern for registering external IPs

Key name in the configuration file: ddnsHostPatternForExternalIPs Value type: String Possible values: String containing special tokens Default value: $n.$o.ext Defines the host name pattern which will be used for external Device Servers. The string is parsed and the following substitutions are made: $n is changed to the device name of a particular Device Server (as defined in its internal settings) $o is changed to the owner name of a particular Device Server (also, as defined in the device's settings) The result is used as a prefix to the zone name to form a fully qualified domain name. So for example, with the default value for this setting, if we have a Device Server called LightSaber and the owner name is Luke, and the domain is DeathStar.com, we would access the Device Server using the DNS address lightsaber.luke.deathstar.com .

2000-2013 Tibbo Technology Inc.

AggreGate Server

63

Host pattern for registering internal IPs

Key name in the configuration file: ddnsHostPatternForInternalIPs Value type: String Possible values: String containing special tokens Default value: $n.$o.int Defines host name pattern which will be used for registering Device Servers whose IP addresses are internal (within your LAN). The string is parsed and the following substitutions are made: $n is changed to the device name of a particular Device Server $o is changed to the owner name of a particular Device Server The result is used as a prefix to to the zone name to form a fully qualified domain name (for details, see example above).

3.2.3.4.6 Mail Settings

Options in this group are used to define how AggreGate Server interacts with E-mail (SMTP and POP3) servers.

Enable Mail Sending

Key name in the configuration file: mailSendingEnabled Value type: Boolean Possible values: true or false Default value: false Allows AggreGate Server to send e-mail messages.

Outgoing mail server address (IP or host name of SMTP server)

Key name in the configuration file: mailOutgoingAddress Value type: String Possible values: Any valid IP address or host name Default value: localhost This option defines the address of SMTP mail server used by AggreGate Server. Example: To enable mail sending via Google Mail (@gmail.com) server, set this property to smtp.gmail. com.

Outgoing mail server username (login)

Key name in the configuration file: mailOutgoingUsername Value type: String Possible values: Any username suitable for mail server Default value: "" (empty) This option defines the username used during SMTP authentication.

Outgoing mail server password

Key name in the configuration file: mailOutgoingPassword Value type: String Possible values: Any password suitable for mail server Default value: "" (empty) This option defines the password used during SMTP authentication.

2000-2013 Tibbo Technology Inc.

64

AggreGate Documentation

Sender address for mail messages

Key name in the configuration file: mailSenderAddress Value type: String Possible values: Any valid e-mail address Default value: AggreGate Server@your-domain.com This option defines the e-mail address specified in the FROM header of mail messages sent by AggreGate Server.

Sender name for mail messages

Key name in the configuration file: mailSenderName Value type: String Possible values: Any valid e-mail sender name Default value: AggreGate Server This option defines sender name specified in the FROM header of mail messages sent by AggreGate Server

Enable Mail Receiving

Key name in the configuration file: mailReceivingEnabled Value type: Boolean Possible values: true or false Default value: false Allows AggreGate Server to receive e-mail messages.

Incoming mail server address (IP or host name of POP3 server)

Key name in the configuration file: mailIncomingAddress Value type: String Possible values: Any valid IP address or host name Default value: localhost This option defines the address of POP3 mail server used by AggreGate Server. Example: To enable mail receiving via Google Mail (@gmail.com) server, set this property to pop.gmail. com.

Incoming mail server username (login)

Key name in the configuration file: mailIncomingUsername Value type: String Possible values: Any username suitable for mail server Default value: "" (empty) This option defines the username used during POP3 authentication.

Incoming mail server password

Key name in the configuration file: mailIncomingPassword Value type: String Possible values: Any password suitable for mail server Default value: "" (empty) This option defines the password used during POP3 authentication.

2000-2013 Tibbo Technology Inc.

AggreGate Server

65

Incoming mail check period (seconds)

Key name in the configuration file: mailCheckPeriod Value type: Integer Possible values: 1 or more Default value: 120 Defines how often AggreGate Server checks for incoming mail messages if Enable Mail Receiving setting is active.

3.2.3.4.7 Advanced Mail Settings

The Advanced Mail Settings table allow to fine-tune mail sending/receiving parameters. Each parameter is defined by Name , Type and Description . However, all parameters are entered in the string form, and parameter's Type just explain how parameter value is interpreted. For example, if parameter is boolean, its string value should be true or false. In most cases, e-mail operations can be properly set up by using only basic options 63 . Use advanced settings only if your basic settings do not work and you're familiar with e-mail operations.

Example: To enable mail sending via an SSL-secured SMTP server, set the following advanced options: mail.smtp.port=465 mail.smtp.auth=true mail.smtp.ssl.enable=true Example: To enable mail sending via Google Mail (@gmail.com) server, use the following advanced options: mail.smtp.port=587 mail.smtp.auth=true mail.smtp.ssl.enable=true mail.smtp.ssl.protocols=TLSv1

Generic Parameters
Name mail.debug mail.from mail.mime. address.strict mail.host Type Description boole an Strin g boole an Strin g The initial debug mode. Default is false. The return email address of the current user. Enables strict parsing of message headers. The default is true. The default host name of the mail server. Used if the mail.protocol .host property isn't set. Specifies the default message access protocol ("pop3", "pop3s", "imap" or "imaps"). Specifies the default message transport protocol ("smtp" or "smtps"). The default user name to use when connecting to the mail server. Used if the mail.protocol .user property isn't set. The default password to use when connecting to the mail server. Used if the mail.protocol . password property isn't set. The host name of the mail server for the specified protocol. Overrides the mail.host property. The port number of the mail server for the specified protocol. If not specified the protocol's default port number is used.

mail.store.protocol Strin g mail.transport. protocol mail.user mail.password mail.protocol .host mail.protocol .port Strin g Strin g Strin g Strin g int

2000-2013 Tibbo Technology Inc.

66

AggreGate Documentation

mail.protocol .user mail.protocol . password

Strin g Strin g

The user name to use when connecting to mail servers using the specified protocol. Overrides the mail.user property. The password to use when connecting to mail servers using the specified protocol. Overrides the mail.password property.

SMTP Parameters
Note that if you're using the "smtps" protocol to access SMTP over SSL, all the properties would be named "mail.smtps.*".

Name mail.smtp.port

Type int

Description The SMTP server port to connect to. Defaults to 25. Socket connection timeout value in milliseconds. Default is infinite timeout. Socket I/O timeout value in milliseconds. Default is infinite timeout. Local host name used in the SMTP HELO or EHLO command. Should not normally need to be set if your name service are configured properly. Local address (host name) to bind to when creating the SMTP connection. Should not normally need to be set, but useful with multi-homed hosts where it's important to pick a particular local address to bind to. Local port number to bind to when creating the SMTP connection.

mail.smtp. int connectiontimeout mail.smtp.timeout mail.smtp. localhost mail.smtp. localaddress mail.smtp. localport mail.smtp.ehlo int String

String

int

boolea If false, do not attempt to sign on with the EHLO command. Defaults to true. Normally n failure of the EHLO command will fallback to the HELO command; this property exists only for servers that don't fail EHLO properly or don't implement EHLO properly. boolea If true, attempt to authenticate the user using the AUTH command. Defaults to false. n String If set, lists the authentication mechanisms to consider, and the order in which to consider them. Only mechanisms supported by the server and supported by the current implementation will be used. The default is "LOGIN PLAIN DIGEST-MD5 NTLM", which includes all the authentication mechanisms supported by the current implementation.

mail.smtp.auth mail.smtp.auth. mechanisms

mail.smtp.auth. login.disable mail.smtp.auth. plain.disable mail.smtp.auth. digest-md5. disable mail.smtp.auth. ntlm.disable mail.smtp.auth. ntlm.domain mail.smtp.auth. ntlm.flags mail.smtp. submitter mail.smtp.dsn. notify mail.smtp.dsn.ret mail.smtp. allow8bitmime

boolea If true, prevents use of the AUTH LOGIN command. Default is false. n boolea If true, prevents use of the AUTH PLAIN command. Default is false. n boolea If true, prevents use of the AUTH DIGEST-MD5 command. Default is false. n boolea If true, prevents use of the AUTH NTLM command. Default is false. n String int String The NTLM authentication domain. NTLM protocol-specific flags. See http://curl.haxx.se/rfc/ntlm.html#theNtlmFlags for details. The submitter to use in the AUTH tag in the MAIL FROM command. Typically used by a mail relay to pass along information about the original submitter of the message. Mail clients typically do not use this. The NOTIFY option to the RCPT command. Either NEVER, or some combination of SUCCESS, FAILURE, and DELAY (separated by commas). The RET option to the MAIL command. Either FULL or HDRS.

String String

boolea If set to true, and the server supports the 8BITMIME extension, text parts of messages n that use the "quoted-printable" or "base64" encodings are converted to use "8bit" encoding if they follow the RFC2045 rules for 8bit text.

2000-2013 Tibbo Technology Inc.

AggreGate Server

67

mail.smtp. sendpartial

boolea If set to true, and a message has some valid and some invalid addresses, send the n message anyway, reporting the partial failure with an exception. If set to false (the default), the message is not sent to any of the recipients if there is an invalid recipient address. boolea If set to true, attempt to use SASL to choose an authentication mechanism for login. n Defaults to false. String String String A space or comma separated list of SASL mechanism names to try to use. The authorization ID to use in the SASL authentication. If not set, the authentication ID (user name) is used. The realm to use with DIGEST-MD5 authentication.

mail.smtp.sasl. enable mail.smtp.sasl. mechanisms mail.smtp.sasl. authorizationid mail.smtp.sasl. realm

mail.smtp.quitwait boolea If set to false, the QUIT command is sent and the connection is immediately closed. If set n to true (the default), causes the transport to wait for the response to the QUIT command. mail.smtp.ssl. enable boolea If set to true, use SSL to connect and use the SSL port by default. Defaults to false for the n "smtp" protocol and true for the "smtps" protocol.

mail.smtp.ssl. boolea If set to true, check the server identity as specified by RFC 2595. These additional checks checkserveridentit n based on the content of the server's certificate are intended to prevent man-in-the-middle y attacks. Defaults to false. mail.smtp.ssl.trust String If set to "*", all hosts are trusted. If set to a whitespace separated list of hosts, those hosts are trusted. Otherwise, trust depends on the certificate the server presents. Specifies the port to connect to when using SSL. If not set, the default port will be used.

mail.smtp.ssl. socketFactory. port mail.smtp.ssl. protocols mail.smtp.ssl. ciphersuites mail.smtp. mailextension mail.smtp.starttls. enable

int

string

Specifies the SSL protocols that will be enabled for SSL connections. The property value is a whitespace separated list of tokens. Allowed values are SSLv3 and TLSv1. Specifies the SSL cipher suites that will be enabled for SSL connections. The property value is a whitespace separated list of tokens. Extension string to append to the MAIL command. The extension string can be used to specify standard SMTP service extensions as well as vendor-specific extensions. See RFC 1869 and other RFCs that define specific extensions.

string

String

boolea If true, enables the use of the STARTTLS command (if supported by the server) to switch n the connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must configured so that the client will trust the server's certificate. Defaults to false. boolea If true, requires the use of the STARTTLS command. If the server doesn't support the n STARTTLS command, or the command fails, the connect method will fail. Defaults to false. boolea If set to true, use the RSET command instead of the NOOP command to check connection n state. In some cases sendmail will respond slowly after many NOOP commands; use of RSET avoids this sendmail issue. Defaults to false. boolea If set to true (the default), insist on a 250 response code from the NOOP command to n indicate success. The NOOP command is used to determine if the connection is still alive. Some older servers return the wrong response code on success, some servers don't implement the NOOP command at all and so always return a failure code. Set this property to false to handle servers that are broken in this way. Normally, when a server times out a connection, it will send a 421 response code, which the client will see as the response to the next command it issues. Some servers send the wrong failure response code when timing out a connection. Do not set this property to false when dealing with servers that are broken in this way.

mail.smtp.starttls. required mail.smtp.userset

mail.smtp.noop. strict

POP3 Parameters
Note that if you're using the "pop3s" protocol to access POP3 over SSL, all the properties would be named "mail.pop3s.*".

Name

Type

Description

2000-2013 Tibbo Technology Inc.

68

AggreGate Documentation

mail.pop3.port

int

The POP3 server port to connect to. Defaults to 110. Socket connection timeout value in milliseconds. Default is infinite timeout. Socket I/O timeout value in milliseconds. Default is infinite timeout.

mail.pop3. int connectiontimeout mail.pop3.timeout int mail.pop3. rsetbeforequit

boolea Send a POP3 RSET command when closing the folder, before sending the QUIT command. n Useful with POP3 servers that implicitly mark all messages that are read as "deleted"; this will prevent such messages from being deleted and expunged unless the client requests so. Default is false. String Local address (host name) to bind to when creating the POP3 socket. Should not normally need to be set, but useful with multi-homed hosts where it's important to pick a particular local address to bind to. Local port number to bind to when creating the POP3 socket.

mail.pop3. localaddress mail.pop3. localport mail.pop3.apop. enable mail.pop3.ssl. enable mail.pop3.ssl. checkserveridenti ty mail.pop3.ssl. trust mail.pop3.ssl. socketFactory. port mail.pop3.ssl. protocols mail.pop3.ssl. ciphersuites

int

boolea If set to true, use APOP instead of USER/PASS to login to the POP3 server, if the POP3 n server supports APOP. APOP sends a digest of the password rather than the clear text password. Defaults to false. boolea If set to true, use SSL to connect and use the SSL port by default. Defaults to false for the n "pop3" protocol and true for the "pop3s" protocol. boolea If set to true, check the server identity as specified by RFC 2595. These additional checks n based on the content of the server's certificate are intended to prevent man-in-the-middle attacks. Defaults to false. String If set to "*", all hosts are trusted. If set to a whitespace separated list of hosts, those hosts are trusted. Otherwise, trust depends on the certificate the server presents. Specifies the port to connect to when using SSL. If not set, the default port will be used.

int

string

Specifies the SSL protocols that will be enabled for SSL connections. The property value is a whitespace separated list of tokens. Specifies the SSL cipher suites that will be enabled for SSL connections. The property value is a whitespace separated list of tokens.

string

mail.pop3.starttls. boolea If true, enables the use of the STLS command (if supported by the server) to switch the enable n connection to a TLS-protected connection before issuing any login commands. Note that an appropriate trust store must configured so that the client will trust the server's certificate. Defaults to false. mail.pop3.starttls. boolea If true, requires the use of the STLS command. If the server doesn't support the STLS required n command, or the command fails, the connect method will fail. Defaults to false. mail.pop3. disabletop mail.pop3. disablecapa mail.pop3. forgettopheaders boolea If set to true, the POP3 TOP command will not be used to fetch message headers. This is n useful for POP3 servers that don't properly implement the TOP command, or that provide incorrect information in the TOP command results. Defaults to false. boolea If set to true, the POP3 CAPA command will not be used to fetch server capabilities. This is n useful for POP3 servers that don't properly implement the CAPA command, or that provide incorrect information in the CAPA command results. Defaults to false. boolea If set to true, the headers that might have been retrieved using the POP3 TOP command n will be forgotten and replaced by headers retrieved as part of the POP3 RETR command. Some servers, such as some versions of Microsft Exchange and IBM Lotus Notes, will return slightly different headers each time the TOP or RETR command is used. To allow the POP3 provider to properly parse the message content returned from the RETR command, the headers also returned by the RETR command must be used. Setting this property to true will cause these headers to be used, even if they differ from the headers returned previously as a result of using the TOP command. Defaults to false. boolea If set to true, the POP3 provider will cache message data in a temporary file rather than in n memory. Messages are only added to the cache when accessing the message content. Message headers are always cached in memory (on demand). The file cache is removed when the folder is closed or the Server is stopped. Defaults to false. String If the file cache is enabled, this property can be used to override the default directory used for temporary files.

mail.pop3. filecache.enable

mail.pop3. filecache.dir

2000-2013 Tibbo Technology Inc.

AggreGate Server

69

mail.pop3. boolea The content of a message is cached when it is first fetched. Normally the cached content is keepmessagecont n purged if memory is low, in which case the content will be fetched again if it's needed. If ent this property is set to true, all cached content will be kept intact, preventing the memory from being reused until the folder is closed. Defaults to false.

3.2.3.4.8 SMS Sending

Options in this group are used to define how AggreGate Server sends SMS messages. Messages are sent via the Clickatell SMS Gateway. Clickatell is not free, but has several advantages: Highly reliable delivery of SMS messages to most countries of the world No need to connect a cellular phone to your server No third-party software is required Simple configuration Tibbo is not affiliated with Clickatell in any way. Clickatell does not pay or remunerate Tibbo in any way, and is not otherwise a Tibbo client or partner. The grounds for this recommendation are purely technical.

To start using Clickatell SMS sending service: 1. Register at http://www.clickatell.com. 2. Log in to Clickatell Central. 3. Go to Manage My Products. 4. Add an HTTP/S connection. 5. Enter only connection name and leave all settings at the defaults (you may want to customize some settings, e.g. lock the IP from which SMS messages are accepted). 6. Enter your Clickatell settings in AggreGate Server SMS Sending configuration and enable SMS sending.

Enable SMS Sending

Key name in the configuration file: smsSendingEnabled Value type: Boolean Possible values: true or false Default value: false Allows AggreGate Server to send SMS messages.

Clickatell Account Username

Key name in the configuration file: smsClickatellUsername Value type: String Possible values: Any string Default value: "" (empty) Defines Clickatell username. Should match your Clickatell server login.

Clickatell Account Password

Key name in the configuration file: smsClickatellPassword Value type: String Possible values: Any string Default value: "" (empty) Defines Clickatell password. Should match your Clickatell server password.

2000-2013 Tibbo Technology Inc.

70

AggreGate Documentation

Clickatell Account API ID

Key name in the configuration file: smsClickatellApiId Value type: String Possible values: Any string Default value: "" (empty) Specifies ID of connection (API) created on Clickatell server. This connection must be of HTTP/S format. Be sure to specify the connection ID (numeric), not the connection name.

Sender Number (International Format)

Key name in the configuration file: smsSender Value type: String Possible values: Any valid cellular phone number Default value: "" (empty) Number of the phone to be used as SMS messages sender. This number must be registered with Clickatell.

3.2.3.4.9 Event Processing Rules

The Event Processing Rules table defines: what events will be suppressed before any processing, routing and storage; how the system finds event duplicates and aggregates them to reduce total number of events; how long persistent events
880

will be stored in event history

882 .

The format of the Event Processing Rules table: Context Mask Every record in the table defines processing rules for an event in every context matching this mask 865 . For example, if we specify Expiration Period of 1 month for the "login" event (in the Event column) and set the Context Mask to "users.admin" (matches the User 759 context of the admin user), information about the logins of the system administrator will be stored for a period of one month. If Context Mask is set to "users.*", successful logins of all users will be stored for the same custom time period. If the mask is not specified (i.e. NULL), the rule is applied to events in all contexts. Event Pre-filter Name of the event whose processing rules are defined by this record. Expression 911 used to suppress events that do not match certain criteria. Suppressed events won't be stored in database, delivered to listeners, and processed by any system module. If pre-filter expression is defined, events will be suppressed if it returns FALSE. Pre-filter Expression Resolution Environment Default Context
927 922

Context of event. Data Table containing event-specific data

881 .

Default Data Table 927 Default Row Environment Variables 930 Deduplication ID Expression
927

0 Standard
931

variables only.

Expression 911 used to calculate deduplication IDs of events. The expression will be evaluated into a String. If the RAM-based events queue (whose size is defined by Number of Events to Store in RAM parameter) contains an event with the same deduplication ID, the current event will be treated as a duplicate of this event: Number of previous event's duplicates will be increased by 1.

2000-2013 Tibbo Technology Inc.

AggreGate Server

71

Creation time of previous event will be updated to match creation time of the duplicate. Thus, creation time of the most recent duplicate is preserved. The event will be delivered to subscribed listeners only if Duplicate Dispatching is enabled Number of Events to Store in RAM Duplicate Dispatching Expiration Period Number of events to keep in memory and use for finding duplicates according to Deduplication ID Expression. Defines whether an event those duplicates were found in memory should be further routed and delivered to subscribers (listeners). Duration of persistent storage. Default duration is 100 days, after which events are permanently deleted from the history records. You can customize the duration of storage ("time-to-live") for different events. Note that in practice events may be available in event history a little bit longer than specified by this setting, because the cleanup process (removing expired events) runs every several minutes. Zero expiration period value disables persistent storage of events pointed by the rule. Enrichments A table defining what enrichments two columns: Enrichment Name Enrichment value Expression One a newly created event instance matches this rule, each value expression is evaluated to a string. A new enrichment with name taken from this table and value equal to the expression result is added to the event instance. Enrichment Expression Resolution Environment Default Context
927 922 883

are added to events pointed by the rule. This table has

Context of event. Data Table containing event-specific data

881 .

Default Data Table 927 Default Row Environment Variables 930

927

0 Standard
931

variables only.

When an event occurs, AggreGate Server processes the Event Processing Rules table from the the first to the last record. If the context in which an event has occurred matches the mask defined by a record, the server uses parameters defined in this record to store the event and stops going over the list. I.e, the first match applies, even if masks in later lines also match the context. Thus, rules with narrower context masks should generally precede rules with wider masks. If this context doesn't match any mask defined in the table, default parameters defined in the event definition will be used to store and process the event. Example: assuming we have the following table of event processing rules: Context Mask users.admin users.* Event login login Expiration Period 1000 hours 200 hours

According to this table, AggreGate Server will store logins of "admin" user for 1000 hours, logins of all other users will be stored for 200 hours. Example: let's say we have the following event processing rule: Context Mask Event Pre-filter Deduplication ID Number of Events to Expression Store in RAM Expiration Period

2000-2013 Tibbo Technology Inc.

72

AggreGate Documentation

users. admin. devices. virtual1

event 1

{int} < 10

{int}

10

3 Months

According to this table, AggreGate Server will process event event1 originated from a certain Virtual Device 182 with context path users.admin.devices.virtual1. This event has, among the others, an Integer int field. The above rule will work as follows: All events having value of int field greater or equal to 10 will be suppressed; For other events, the deduplication ID will be calculated. This ID will match value of int field. According to the above rule, events with the same value of int field will be filtered out as duplicates of the first event with such int field value. Once the number of events in memory will exceed 10 , the oldest events will be removed and no longer eligible for duplicates search. Note, that copies of these events stored in database (and preserving information about duplicates) will be kept intact.

3.2.3.4.10 Custom Event Writers

The Custom Event Writers table configures which events CSV files, in addition to the normal event history 882 . The format of the Custom Event Writers table: Writer Type Name Context Mask Event Name Type of custom writer. Currently, two types are supported: database and CSV file. Name of the writer. Use of the name depends on writer type, e.g. it is the database name for the database writer or file name (without extension) for the CSV file writer. Mask
865 880

will be stored in custom destinations, such as database or

of contexts to watch for the event to be written into custom storage.

Name of the event to store.

Database Event Writer

Normally, AggreGate Server stores historical events in database 80 in its own custom format. The events table (it's called ag_events) is fully managed by the server and should not be accessed by third party applications. Database event writes provides a method for storing selected events into a dedicated table. This table has several differences from the normal events storage: Event's are added to this table once they occur. AggreGate Server does not attempt to delete expired events from this table. No other modifications of existing events are performed. Server creates a dedicated table column for every field described in event format
880 .

Any third-party applications may execute selection of modification queries over this table to get access to AggreGate Server events. It's possible to access this table even during AggreGate Server operation. Custom events table structure: Field ag_id ag_datetime ag_context ag_event ag_level ev_* Type Long (bigint) Timestamp (datetime) String (varchar) Ttring (varchar) Integer (int) Different type Comments Event ID Event timestamp Event context Event name Event level
882

(numeric value)

Custom event-specific fields

CSV Event Writer

This event writer appends selected events to a Character-Separated Values (CSV) file. This is a simple text file that

2000-2013 Tibbo Technology Inc.

AggreGate Server
may be parsed by any application. CSV file fields: Event ID Event timestamp (formatted according to yyyy-MM-dd Event context Event name Event level
882

73

HH:mm:ss.SSS pattern 1321 )

(numeric value)

Custom event-specific fields

3.2.3.4.11 Default User Permissions

This property defines the default permissions 931 and resource availability for newly created AggreGate Server users 108 . It is used to build a permissions table 934 and resources table 111 when a new user account is created. Each record of Default User Permissions controls availability of a certain container context 863 and access to this container: If Available flag is unchecked in any record, resource container of type pointed by this record won't be available for any AggreGate Server user. If Enabled flag is unchecked in any record, the newly created user will have no access to resources of type pointed by this record. However, other users may have access to it. Permission level 932 that new user will have for the resources enabled in Default User Permissions is specified during user registration. This level may be later changed by editing user's personal permissions table 933 .

3.2.3.4.12 Additional Permissions For New Users

This property defines a list additional records that will be added into permission table 934 for newly created AggreGate Server users 108 . It is used to build a permissions table when a new user account is created. The table has two fields: Context mask
865 ,

specifying the range of contexts where the record applies;

932

Permission level

of the user in every such context.

Context masks may contain a special % character. It will be replaced by the new user's username during account creation. Example: If the context mask field of the additional permissions table contains users.%.alerts and the new user's name is john , his permissions table will contain a record for users.john.alerts . Additional Permissions is very similar to Default User Permissions 73 table. The difference is that Default User Permissions help to quickly set up permissions of new users just by clicking on several check boxes while Additional Permissions provide a more fine-grained control based on direct specification of user permission table records. Additional permissions table has higher priority than Default User Permissions 73 . Records from additional permissions table are added into permissions table of a new user before records that are specified by Default User Permissions.

3.2.3.4.13 Default Synchronization Options

This tabular property is used to globally set up default synchronization options 115 for Device settings. These options are used for the settings of newly added Devices. Existing Devices use their own copies of setting synchronization options and do not inherit values from this global table.

3.2.3.4.14 Statistics
This tabular property is used to globally set up default statistical channels 936 for Device settings. These channels are created for newly added Devices and may be re-created upon device driver reset 678 . Existing Devices use their own copies of statistical channel properties 938 and do not inherit values from this global table.

2000-2013 Tibbo Technology Inc.

74

AggreGate Documentation

3.2.3.4.15 Active Plugins

This property specifies what server plugins Server installation are enabled by default.
950

are enabled. All plugins installed to the /plugins folder of AggreGate

A plugin cannot be disabled if some other plugins depending on it are enabled.

Disabling plugins may cause incorrect or inconsistent behaviour of the system. For example, disabling a device driver plugin 129 will bring down all Devices 113 using this driver.

3.2.4 Logging
As with most server software, the primary method to report all events and activities of AggreGate Server is logging. AggreGate Server employes an advanced logging facility which is easily configurable through an ordinary text file. Logging configuration can be changed at runtime without restarting the AggreGate Server. AggreGate Server uses Apache Log4J logging library for log output. It is highly customizable and allows multiple levels and sources of logging information along with numerous log destinations. Logging output can be redirected to: Console Text files XML files Windows event logs UNIX syslog Database Remote network server E-mail messages Java Message Service (JMS) And many other destinations.. The AggreGate Server logging configuration file is located in the installation directory and is called logging.xml. The structure of this file is briefly described in logging configuration file 74 section. It also contains a list of logging categories used by different components of AggreGate to produce logging output. Default Logging Configuration File 74 defines two logging destinations: console and log file called server. log that is located in AggreGate Server installation directory. Logging is performed at Info level 79 .

3.2.4.1 Logging Configuration File

This section describes the default logging configuration file along with some details common to AggreGate Server logging configuration. Here is the default config:

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd"> <log4j:configuration debug="false" xmlns:log4j="http://jakarta.apache.org/log4j/">

<appender name="console" class="org.apache.log4j.ConsoleAppender"> <param name="threshold" value="debug"/> <layout class="org.apache.log4j.PatternLayout"> -

<param name="ConversionPattern" value="%d{HH:mm:ss,SSS} %-5p %-25c %m [%t] %C.%M (%F:%L)%n"/>

2000-2013 Tibbo Technology Inc.

AggreGate Server </layout> </appender>

75

<appender name="file" class="org.apache.log4j.DailyRollingFileAppender"> <param name="threshold" value="debug"/> <param name="file" value="server.log"/> <param name="append" value="true"/> <param name="DatePattern" value=".yyyy-MM-dd"/> <layout class="org.apache.log4j.PatternLayout"> <param name="ConversionPattern" value="%d{dd.MM.yyyy HH:mm:ss,SSS} %-5p %-25c %m [%t] %C.%M (%F:%L)%n"/>

</layout> </appender>

<logger name="org.apache"> <level value="error"/> </logger>

<logger name="ag" additivity="false"> <level value="warn"/> <appender-ref ref="file"/> <appender-ref ref="console"/> </logger>

<logger name="ag.alerts"> <level value="info"/> </logger>

<!-- Other logging categories are skipped -->

<root> <priority value="warn"/> <appender-ref ref="console"/> <appender-ref ref="file"/> </root>

</log4j:configuration>
The default logging configuration is represented by a root configuration element, two appenders (destinations for log output) and several named logging categories. The root element (<root>) defines the global logging level as warning (<priority value="warn"/>) (see logging levels 79 for more information). It applies to all messages coming from the system libraries used by the server core. Logging of the server itself is performed using info level. This is specified by the <level value="info"/> tag that is located in <logger name="ag.*">. To switch the server to debug-level logging in a certain category 76 , change this tag to <level value="debug"/>. The <logger> elements define which level is used for logging from each subsystem of AggreGate Server.

2000-2013 Tibbo Technology Inc.

76

AggreGate Documentation

This logging configuration also defines two appenders named CONSOLE and FILE. An Appender is a destination for logging output. It can be a text file, e-mail message etc (see below for a complete listing of all available appenders). Each appender is configured by its own <appender> element. This element must also specify a name of Java class responsible for this appender. In the listing above both appenders include a <layout> elements, that defines how the logged information will be formatted. The FILE appender includes several other <param> elements containing some additional options. For more information, consult manuals or books mentioned in logging framework documentation sources 80 chapter.

More About Appenders (An Edited Excerpt From The Log4j Manual)
Log4j allows logging requests to print to multiple destinations. In log4j speak, an output destination is called an appender. Currently, appenders exist for the console, files, GUI components, remote socket servers, JMS, NT Event Loggers, and remote UNIX Syslog daemons. More than one appender can be attached to a logger. Here is a brief list of available appenders:

COMMON APPENDERS
FileAppender , appends log events to a file. RollingFileAppender, extends FileAppender to backup the log files when they reach a certain size. DailyRollingFileAppender , extends FileAppender so that the underlying file is rolled over at a user-specified frequency. ConsoleAppender, appends log events to System.out or System.err using a layout specified by the user. The default target is System.out.

NETWORK APPENDERS
SocketAppender, sends LoggingEvent objects to a remote a log server, usually a SocketNode. SocketHubAppender, sends LoggingEvent objects to a set of remote log servers, usually a SocketNodes . JMSAppender, a simple appender that publishes events to a JMS Topic. The events are serialized and transmitted as JMS message type ObjectMessage. NTEventLogAppender, appends to the NT event log system.

THIRD-PARTY APPENDERS
JDBCAppender SNMPTrapAppender

SPECIAL APPENDERS
AsyncAppender, lets users log events asynchronously. It uses a bounded buffer to store logging events. ExternallyRolledFileAppender, listens on a socket on the port specified by the PORT_OPTION for a "RollOver" message. When such a message is received, the underlying log file is rolled over and an acknowledgment message is sent back to the process initiating the roll over. JDBCAppender, provides for sending log events to a database. SMTPAppender, sends an e-mail when a specific logging event occurs, typically on errors or fatal errors. SyslogAppender, sends messages to a remote syslog daemon. TelnetAppender is a log4j appender that specializes in writing to a read-only socket. WriterAppender, appends log events to a Writer or an OutputStream depending on the user's choice.

3.2.4.2 Logging Categories

This section describes logging categories that are relevant to AggreGate Server, AggreGate Client components of AggreGate.
776

and other

Category Name
ag.alerts

Description
Messages related to Alerts
216 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

77

ag.autorun ag.bindings

Messages related to Auto Run

625 . 951 .

Messages related to Data Bindings level.

Most logging in this category is performed at Debug

ag.commands

Logging of command exchange between different components of the system. Most logging in this category is performed at Debug level. Device Server 1003 commands are logged at Debug level in this category.

ag.commands. device_server ag.commands. agent ag.commands. client ag.commands. distributed ag.commondata ag.clients ag.cluster ag.config ag.context

Agent

848

commands are logged at Debug level in this category.

Client

776

commands are logged at Debug level in this category.

Distributed architecture category.

99

consumer-provider commands are logged at Debug level in this

Messages related to Common Data

260 . 776 . 87

Messages related to AggreGate Clients

Messages related to Failover and Load Balancing Cluster Messages related to Global Configuration Generic messages related to Contexts level. Info
885 51

of AggreGate Server.

863 .

Most logging in this category is performed at Debug

ag.context.info ag.context.children

events in AggreGate Server context are logged at Info level in this category.

Messages related to context tree structure management. Most logging in this category is performed at Debug level. Messages related to context Variables (Properties) performed at Debug level. Messages related to context Functions level. Messages related to context Events level. Messages related to context Actions level.
878 . 869 .

ag.context. variables ag.context. functions ag.context.events

Most logging in this category is

Most logging in this category is performed at Debug

880 .

Most logging in this category is performed at Debug

ag.context.actions

892 .

Most logging in this category is performed at Debug

ag.core

This category is used for logging messages from core of AggreGate Server and AggreGate Client. Miscellaneous messages that can be hardly categorized are also related to this category. Thread management messages. Messages related to Dashboards
617 .

ag.core.thread ag.dashboards ag.database

Logging related to database interaction. Most logging in this category is performed at Debug level. Generic messages related to interaction between AggreGate Server and hardware devices. Messages related to discovery of hardware devices.

ag.device ag.device. discovery ag.device.sync ag.device.agent

Messages related to synchronization Messages related to Agent

848 .

126

of AggreGate Server and hardware devices.

2000-2013 Tibbo Technology Inc.

78

AggreGate Documentation

ag.device.* ag.device_browser ag.device_server ag.device_server. inbands ag.data_table

Other messages produced by different device drivers Messages related to Device Browser Messages related to Device Servers Messages related to Device Servers level in this category Messages related to Data Tables level.
825

129 .

component of AggreGate Client.

1003 . 1003

inband command processing are logged at Debug

854 .

Most logging in this category is performed at Debug

ag.data_table.filter

Messages related to Data Tables 854 filtering (used by Event Filters) category is performed at Debug level. Messages related to Data Table Editor
801

206 .

Most logging in this

ag. data_table_editor ag.dns

component of AggreGate Client.

Messages related to Domain Name System servers interaction. Specifically used by Dynamic DNS 1010 device driver. Messages related to Entity Selector Messages related to Event Filters Messages related to Event Log
791 815

ag.entity_selector ag.eventfilters ag.event_log ag. expression_builder ag.expressions ag.favourites ag.groups ag.gui ag.gui_builder ag.guide ag.mail

component of AggreGate Client.

206 .

component of AggreGate Client.

817

Messages related to Expression Builder

component of AggreGate Client.

Messages related to Expression Messages related to Favourites Messages related to Groups

911

processing.

626 .

248 .

Generic messages related to Graphics User Interface (GUI). Messages related to GUI Builder
827

(component of AggreGate Client).

847 .

Messages related to Interactive Guides

Messages related to processing of outgoing and incoming E-mail messages and interaction with mail servers. Messages related to Models
303 . 49

ag.models ag.net_admin ag.performance

Messages related to Net Admin

Messages related to system performance issues, such as operations that take longer than expected. Minor performance decrease is logged at Debug level, while serious degradations are reported using higher levels. Generic messages related to Plugins Messages related to Properties Editor
950 . 795

ag.plugins ag. properties_editor ag.protocol

component of AggreGate Client.

Messages related to AggreGate Communications Protocol performed at Debug level. Messages related to AggreGate Communications Protocol this category is performed at Debug level. Messages related to Queries Messages related to Reports
271 . 241 .

1303 .

Most logging in this category is

ag.protocol.caching

1303

format caching. Most logging in

ag.queries ag.reports

2000-2013 Tibbo Technology Inc.

AggreGate Server

79

ag.resource

Messages related to resources management. Most logging in this category is performed at Debug level. Messages related to Scheduled Jobs Messages related to Scripts
628 266 . 610 .

ag.scheduler ag.scripts ag.security

and Widget Scripts

Messages related to security and permission checking. Most logging in this category is performed at Debug level. Messages related to statistics collection (Statistical Process Control). Standard output of different AggreGate libraries and components is redirected to this logging category. All logging in this category is performedat Debug level. Standard error output of different AggreGate libraries and components is redirected to this logging category. All logging in this category is performed at Info level. Messages related to the System Tree Messages related to Trackers Messages related to Users
257 . 784

ag.statistics ag.stdout

ag.stderr

ag.system_tree ag.trackers ag.users ag.web ag.widgets

component of AggreGate Client.

108 . 632 .

Generic messages related to AggreGate Server Web Desktop Messages related to Widgets
312 .

3.2.4.3 Logging Levels

AggreGate Server uses five predefined logging levels: Fatal logging level is used to report only the most severe messages. The AggreGate Server usually stops if a fatal error is detected and reported. Error messages do not cause AggreGate Server to stop immediately when they are reported, but they indicate that there are serious problems with the server operation and that action is needed to prevent server failure. Warning messages show that something has gone wrong, but usually AggreGate Server can recover from such issues automatically and no immediate action is required. Info messages reflect normal AggreGate Serveractivities. These messages should be used for monitoring by a system administrator. Debug messages are used to solve problems if AggreGate Server does not behave as expected. Debug output is disabled by default. Enabling debug-level logging for all categories can lead to extremely high volume of logged messages and seriously affect AggreGate Server performance. Enable debug output temporarily only if you are absolutely sure that you need this. This level of logging is usually only enabled if advised by Tibbo support team. By default, logging is performed at Info level. It's recommended to change logging level to Warning during production use to improve performance and reduce size of log files. When problems arise, it may be necessary to set logging level in individual categories to Debug for troubleshooting. To modify the logging level, perform the following steps: Edit logging.xml. Find the section that says:

<logger name="ag.category_name"> <priority value="info"/> </logger>

Change the priority value entry (info above) to the logging level you want to specify. Usually changes take effect within 20 seconds of saving the corrected logging configuration file was saved. In some cases it may be necessary to restart the AggreGate Server in order to activate changes.

2000-2013 Tibbo Technology Inc.

80

AggreGate Documentation
The string priority value= appears in other sections of the file. Most importantly, it appears under the section </root>. Modifying this value under the section root (especially to higher logging levels, such as debug) may affect performance considerably, and even cause the AggreGate Server to halt or freeze.

3.2.4.4 Logging Framework Documentation Sources

AggreGate Server uses the Log4j library for logging output. This is a highly scalable, robust, and versatile logging framework. A full description of its features goes beyond the extent of this manual. You can find additional information about Log4j in the following books and web resources:

Log4j official site The Complete Log4j Manual Logging in Java with the JDK 1.4 Logging API and Apache log4j

3.2.5 Database
AggreGate Server uses a relational database to store persistent data, such as: 1. Information about User Accounts 2. Values of all persistent context objects) 3. History of persistent events
880 108

and Device Server Accounts

869

1003

in dedicated tables

863

variables

(properties of Alerts, Event Filters, Widgets and other system

AggreGate Server communicates with the database engine using a JDBC driver, so it can work with most modern Relational Database Management Systems. JDBC stands for the Java DataBase Connectivity API. It is a standardized way for Java-based applications to interact with a wide range of databases and data sources. JDBC differs from ODBC (Microsoft's Open DataBase Connectivity standard) primarily in the fact that JDBC is written in Java, and thus can be used without modification in cross-platform environments. Additionally, whereas ODBC is a complex standard that is becoming technically out-dated, JDBC is a modern, clean specification for cross-vendor database access.

Embedded Database
The AggreGate Server distribution package includes an embedded database engine (Apache Derby) that is used by default. This database can be used for system testing.

Embedded database is not suitable for long-term production usage! Using embedded database in production installations will cause high memory usage and performance troubles. It's necessary to switch to any enterprise-grade database once the system was switched into production mode.
See switching to another database engine
81

for more information on how to change the database used by the server.
55

A separate group of server global configuration settings engine.

controls how AggreGate Server interacts with the database

The embedded database's data is located in /db subfolder of AggreGate Server installation folder.

Bundled MySQL Package

Some distributions of AggreGate Server include pre-configured MySQL bundle. MySQL is a well-known powerful free database server that can serve AggreGate installations with thousands of devices. If the bundled MySQL package is selected during installation, will be downloaded from Tibbo website and installed in / mysql subfolder of AggreGate Server installation folder. It is already fine-tuned to be used with the AggreGate Server, so no additional configuration should be necessary in most cases.

MANAGING BUNDLED MYSQL INSTALLATION

The bundled MySQL server is normally auto-launched during Windows startup. To start/stop it manually: Go to Start Menu > Control Panel > Administration > Services

2000-2013 Tibbo Technology Inc.

AggreGate Server
Find MySQL for AggreGate service Right-click on it to see the list of control function in context menu If the MySQL service fails to start, see its error log file (mysql/error.log) to find out failure details.

81

3.2.5.1 Switching To Another Database Engine

This section describes how to make AggreGate Server use another database engine. By default, AggreGate Server uses an embedded database engine that's good for small installations (up to 20-30 devices). For larger installations it's recommended to use some production-grade database server, such as MySQL, Oracle, Microsoft SQL Server, PosrgreSQL, Firebird, or other database management system. Several versions of AggreGate Server contain a dedicated MySQL Database Server bundle inside the distribution package. If such a bundle was selected for installation, the server will be auto-configured to use enterprise-grade MySQL database. In this case, switching to another database engine is not necessary. To switch AggreGate Server to another database engine, use the following procedure: 1. Make a backup of your AggreGate Server configuration file (server.xml in AggreGate Server installation folder). Put it into AggreGate Server installation folder and call it server_old.xml. 2. Install and configure your database engine if it was not yet installed. 3. Create a new database in your database engine. This database will be used by AggreGate Server to store its data. 4. Create a new user account in your database engine. This account will be used by AggreGate Server to access the database. 5. Grant the new user account permissions for the AggreGate Server database. It will require permissions to CREATE, ALTER and DROP tables, as well as INDEX them. Also, it must be able to INSERT, UPDATE, DELETE and SELECT data in all tables. 6. Shut down AggreGate Server if it's running. 7. Put your JDBC (Java Database Connectivity) database driver file into the /lib subfolder of AggreGate Server installation folder. This file usually has a .jar extension. For example, the JDBC driver for MySQL database engine is called MySQL-connector-java-X.X.XX-ga-bin.jar, where X.XX.XX is the driver version. The JDBC driver may be provided by the original maker of the database (Oracle etc), or by a third party. There is an alternative method of making your JDBC driver available to AggreGate Server: Create a new server.vmoptions Launcher Properties File folder and open it for editing in a text editor.
45

file in the AggreGate Server installation

Write -classpath/a <JDBC_Driver_File_Path> in the first and only line of this file. JDBC_Driver_File_Path is the full path of JDBC database driver file (or name of this file, if it is located in the AggreGate Server installation directory). 8. Start Server Configurator 51 utility, or start AggreGate Server and launch Configure Server Database tab in the server configuration dialog.
726

action. Switch to

9. Change the Database Driver Global Configuration Setting 55 setting to the name of Java class representing the database driver. This name is provided by the JDBC driver manufacturer. For example, MySQL database driver class is called com.MySQL.jdbc.Driver. More information on Global Configuration Settings may be found here 53 . 10. Set the Database URL Global Configuration Setting to point to your database engine. Its format is also provided by the JDBC driver manufacturer. For MySQL it has the following format: jdbc:MySQL://[host][:port]/ [database], where [host] is the IP or hostname of the MySQL server (can also be an empty string or localhost), [port] is the port number on which the MySQL server is running (optional - the default port is used if it's not specified), and [database], which is the name the of database containing AggreGate Server data. You can use AggreGate Server for the database name. For example, if your MySQL server runs on 192.168.0.1, on the default port, use the following URL: jdbc:MySQL://192.168.0.1/AggreGate Server. 11. Specify the correct Database Username and Database Password Global Configuration Settings. These credentials are used to access the database specified by the Database URL setting. 12. Set the Database Dialect Global Configuration Setting to the predefined value corresponding to the type of your database. See Database Dialect 57 global configuration setting for more info. 13. Save the new settings. Do not restart the server, even if you're prompted to do that. 14. Stop the server configurator (or AggreGate Server). 15. Run database converter
85

utility that is located in AggreGate Server installation folder to move data from the old

2000-2013 Tibbo Technology Inc.

82

AggreGate Documentation

database to the new one. 16. Wait for the converter to finish working. depending on the database size, it may take from several seconds to several hours. 17. Start the AggreGate Server. 18. Voila! All done, you're now using the new database. The maximum number of parallel connections allowed by your database server must be greater than the value of Maximum Connection Pool Size 58 global property of AggreGate Server. In most cases, the default number of parallel connections allowed by the database server is lower and should be adjusted. Refer to your database server documentation to find out how to increase this limit.

3.2.5.1.1 Switching Database To MySQL

Several versions of AggreGate Server contain a dedicated MySQL bundle inside the distribution package. If such a bundle was selected for installation, the server will be auto-configured to use MySQL database, and the below steps are not necessary. If a dedicated instance of MySQL was installed, its files are located in the mysql/ subfolder of AggreGate Server installation. The database data is located in the mysql/data/ subfolder. The installer configures dedicated MySQL instance for auto-launch during OS startup. Default configurations of AggreGate Server and MySQL are optimized for maximum interaction performance. Note, that dedicated MySQL instance is pre-optimized for performance and its memory requirements are quite high. You'll probably need to reconfigure bundled MySQL installation if your server has less than 4 Gb of RAM. To use MySQL as AggreGate Server's database engine, follow the generic instructions from Switching To Another Database Engine 81 article. Here is a list of notes specific to MySQL: 1. MySQL's JDBC driver (MySQL Connector for Java ) is already included in AggreGate Server distribution. The driver file is called MySQL-connector-java-5.X.XX-ga-bin.jar, it is located in the /lib subfolder of AggreGate Server installation folder. To ensure maximum performance and compatibility with the latest versions of MySQL, you may want to update MySQL JDBC driver to the most recent version. At the time of this writing, it is available at http:// www.mysql.com/products/connector/j/. 2. Set Database Driver in AggreGate Server Global Configuration Setting to com.mysql.jdbc.Driver. This is the java class name for the MySQL driver. 3. The Database URL setting for the MySQL database has the following format: jdbc:mysql://[host][:port] [/database], where host is the IP or hostname of the MySQL server (can be an empty string or localhost), port is port name on which MySQL server is running (omit this part of URL to use the default value), and database name is the name of database that contains AggreGate Server's data. You can use server for the database name. For example, if your MySQL server runs at 192.168.0.1 with its default port, use the following URL: jdbc: mysql://192.168.0.1/server. 4. Set Database Dialect setting to MySQL 5 (MySQL5InnoDBDialect) is you are using MySQL 5 or MySQL ( MySQLInnoDBDialect) for older versions.

MySQL Setup
AggreGate requires several configuration changes to be made in MySQL configuration. These changes are normally applied using MySQL configuration file ( my.ini by default). 1. Add max_allowed_packet=100M to the configuration to allow large queries. 2. Set max_connections to the value higher than Maximum Connection Pool Size configuration setting (e.g. max_connections=1000).
58

global AggreGate Server

3. Set innodb_buffer_pool_size to maximum amount of RAM that MySQL should use. In the case of dedicated database server, set this option to 80% of available RAM. 4. Set innodb_log_file_size to 25-50% of innodb_buffer_pool_size.

MYSQL CONFIGURATION FILE

An example of MySQL configuration file suitable for large AggreGate installations with thousands of devices is provided below.

[client] port = 3306

2000-2013 Tibbo Technology Inc.

AggreGate Server socket = /tmp/mysql.sock

83

[mysqld] port = 3306

socket = /tmp/mysql.sock default-storage-engine = INNODB datadir = /d a ta/mysql innodb_data_home_dir = /data/mysql innodb_log_group_home_dir = /data/my sq l

skip-external-locking max_connections = 1000 max_allowed_packet = 100M

innodb_flush_log_at_trx_commit = 0 innodb_buffer_pool_size = 2 G innodb_log_file_size = 5 0 0 M innodb_log_buffer_size = 8M innodb_additional_mem_pool_size = 20M innodb_lock_wait_timeout = 1200

key_buffer_size = 384M sort_buffer_size = 20M read_buffer_size = 20M read_rnd_buffer_size = 20M query_cache_size = 100M

table_open_cache = 10000 table_definition_cache = 10000

thread_cache_size = 32 innodb_file_io_threads = 8 innodb_thread_concurrency = 0

Changing Buffer Sizes

MySQL installation bundled with AggreGate Server for Windows is configured for high performance servers. If the server is installed on a low-grade machine (e.g. on a laptop), the MySQL server may fail to start due to the buffer memory allocation problem. In this case, it's necessary to decrease buffer sizes: Make sure that MySQL for AggreGate service/process is not running on the server machine or stop it if it's running (you can control the service from Control Panel > Administration > Services) Edit mysql/my.ini file located in the AggreGate Server distribution folder Decrease innodb_buffer_pool_size, e.g. set it to 500M Decrease innodb_log_file_size to 25-50% of the innodb_buffer_pool_size, e.g. set it to 200M Delete MySQL log files (mysql/ib_logfile0 and mysql/ib_logfile1)

2000-2013 Tibbo Technology Inc.

84

AggreGate Documentation

Start MySQL for AggreGate service again

3.2.5.1.2 Switching Database To Microsoft SQL Server

To use Microsoft SQL Server AggreGate Server's database engine, follow the generic instructions from Switching To Another Database Engine 81 article. Here is a list of notes specific to Microsoft SQL Server: 1. Download and install the latest Microsoft SQL Server JDBC Driver. At the time of this writing, it is available at http://msdn.microsoft.com/data/jdbc/. 2. Put sqljdbc4.jar into the /lib subfolder of AggreGate Server installation folder. 3. Set Database Driver in AggreGate Server Global Configuration Setting to com.microsoft.sqlserver. jdbc.SQLServerDriver. This is the java class name for the Microsoft SQL Server driver. 4. The Database URL setting for the Microsoft SQL Server database has the following format: jdbc:sqlserver:// [serverName[\instanceName][:port]][;property=value[;property=value]], where jdbc: sqlserver:// is known as the sub-protocol and is constant, serverName is the DNS name or IP address of the server to connect to (can be locahost), instanceName is the instance to connect to on serverName (If not specified, a connection to the default instance is made), portNumber is the port to connect to on serverName (The default is 1433). For example, if your Microsoft SQL Server runs on 192.168.0.1, on the default port, use the following URL to connect to the default instance: jdbc:sqlserver://192.168.0.1:1433. You can also omit the default port and use jdbc:sqlserver://192.168.0.1 instead. 5. Set Database Dialect setting to SQLServerDialect.

3.2.5.1.3 Switching Database To Oracle

To use Oracle as AggreGate Server's database engine, follow the generic instructions from Switching To Another Database Engine 81 article. Here is a list of notes specific to Oracle: 1. Download the proper version of Oracle JDBC Driver for Java (JDK) 1.6 and store it on the machine running AggreGate Server. At the time of this writing, it is available at http://www.oracle.com/technology/software/tech/java/ sqlj_jdbc/. 2. Put ojdbc.jar into the /lib subfolder of AggreGate Server installation folder. 3. Set Database Driver in AggreGate Server Global Configuration Setting to oracle.jdbc.OracleDriver. This is the java class name for the Oracle driver. 4. The Database URL setting for the Oracle database has the following format: jdbc:oracle:thin:@host[: port]:database, where host is the IP or hostname of the Oracle server (can be an empty string or localhost), port is port name on which Oracle server is running (omit this part of URL to use the default value), and database name is the name of database that contains AggreGate Server's data. You can use server for the database name. For example, if your Oracle server runs at 192.168.0.1 with its default port, use the following URL: jdbc:oracle: thin://192.168.0.1:server. 5. Set Database Dialect setting to Oracle9Dialect if you are using Oracle 9 or above and to OracleDialect otherwise.

3.2.5.1.4 Switching Database To PostgreSQL

To use PostgreSQL as AggreGate Server's database engine, follow the generic instructions from Switching To Another Database Engine 81 article. Here is a list of notes specific to PostgreSQL: 1. Download PostgreSQL JDBC4 driver for your version of database server and store it on the machine running AggreGate Server. At the time of this writing, it is available at http://jdbc.postgresql.org/. 2. Put postgresql-X.X-XXX.jdbc4.jar into the /lib subfolder of AggreGate Server installation folder. 3. Set Database Driver in AggreGate Server Global Configuration Setting to org.postgresql.Driver. This is the java class name for the PostgreSQL driver. 4. The Database URL setting for the PostgreSQL database has the following format: jdbc:postgresql://host[: port]/database, where host is the IP or hostname of the PostgreSQL server (can be an empty string or localhost), port is port name on which PostgreSQL server is running (omit this part of URL to use the default value), and database name is the name of database that contains AggreGate Server's data. You can use server for the database name. For example, if your PostgreSQL server runs at 192.168.0.1 with its default port, use the following URL: jdbc:postgresql://192.168.0.1/server. 5. Set Database Dialect setting to PostgreSQLDialect.

2000-2013 Tibbo Technology Inc.

AggreGate Server

85

3.2.5.1.5 Switching Database To Firebird

To use Firebird as AggreGate Server's database engine, follow the generic instructions from Switching To Another Database Engine 81 article. Here is a list of notes specific to Firebird: 1. Download Jaybird JCA/JDBC driver for your version of database server and store it on the machine running AggreGate Server. At the time of this writing, it is available at http://www.firebirdsql.org/index.php? op=devel&sub=jdbc. 2. Put jaybird-full-X.X.X.jar into the /lib subfolder of AggreGate Server installation folder. 3. Set Database Driver in AggreGate Server Global Configuration Setting to org.firebirdsql.jdbc. FBDriver. This is the java class name for the Firebird driver. 4. The Database URL setting for the MySQL database has the following format: jdbc:firebirdsql:host[/ port]:/path/to/db.fdb, where host is the IP or hostname of the Firebird server (can be an empty string or localhost), port is port name on which Firebird server is running (omit this part of URL to use the default value), and /path/to/db.fdb is the path to database file that contains AggreGate Server's data. You can use server for the database name. For example, if your Firebird server runs at localhost on port 3050, and AggreGate Server data is in C:\db\server.fdb, use the following URL: jdbc:firebirdsql:localhost/3050:C:\\db\\server.fdb. 5. Set Database Dialect setting to FirebirdDialect. 6. Set Batch Size to zero. This is necessary since Firebird JDBC driver doesn't support batch inserts of objects with BLOB fields.

3.2.5.2 Database Converter

Database converter (db_converter) utility is located in AggreGate Server installation folder. It is used to move AggreGate Server database data from one database to another.

db_converter executable file accepts two arguments: path of the old AggreGate Server configuration file (that
contains old database configuration) and path of the new configuration file. So, the command to execute is: db_converter server_old.xml server.xml.

3.2.5.3 Database Schema and Interaction

AggreGate Server database schema is fully dynamic, new tables are created and deleted by the server on the fly in order to reflect system resource creation, removal and reconfiguration. However, there are a few basic tables that exist in every installation: Table ag_properties Description Contains values of all persistent server context variables 869 . AggreGate Server generates relatively low number of INSERT and DELETE requests to this table when system objects are created and destroyed. The number of SELECTs is also relatively low due to server-side memory caching. However, ag_properties table is extensively UPDATE'd because values of persistent resource properties are modified and the server saves changed values to the database. For example, devices 113 that use persistent value cache updates during synchronization 126 . Fields: context - full path of context
863 115

cause a lot of ag_properties

those variable's value is stored in the table row

property - name of the variable data - a data table separators ag_events

854

representing variable value encoded into string

1306

using invisible

Contains all server context events 880 except for ones that are stored in other (custom) tables. See Context Event Storage section below for details. Fields: context - full path of context
863

the event was fired in

name - name of the event (i.e. event type) creationtime - timestamp of event occurrence (or last event occurrence if multiple duplicates

2000-2013 Tibbo Technology Inc.

86

AggreGate Documentation

were registered) expirationtime - future timestamp of planned event expiration time level - event level permissions - custom permissions required to access the event instance or null if permissions specified by event definition should be used count - number of registered event's duplicates
70 882 883

ack - an encoded list of event's acknowledgements

enrichments - an encoded list of event's enrichments

format - an encoded format of the event or null if format specified by event definition should be used data - a data table separators ag_data
854

representing event data

881

encoded into string

1306

using invisible

Contains binary data blocks 857 that are embedded into context variable 869 values. Those blocks are extracted into this separate table when variable value is being persisted in ag_properties table. However, binary blocks are not loaded once variable value is loaded from ag_properties. The blocks are only loaded on-demand, i.e. by explicit requests of AggreGate Server modules, clients of external applications. Used for interaction between failover cluster
87

ag_heartbeat

nodes.

Context Event Storage

Large AggreGate installation can store billions of persistent context events 880 in the database. Those events are dynamically distributed between different tables in order to optimize storage and retrieval performance. The below table lists database tables that are normally created to store events of different types. Format of all event tables matches the format of ag_events table described above. Access to event tables normally comprises a lot of INSERT operations. A new record is inserted every time a persistent server event is registered. The DELETE statements are issued over event table in two cases: If a system resource is deleted all associated events are also deleted Expired events are periodically purged by a scheduler
266

task

The number of SELECT queries performed to event tables is relatively low. The events are loaded in the following cases: If an Event Log
791

is opened, causing subsequent activation of an event filter

695

206

If events are directly loaded by get()

function of Events context

764

If variable history is explicitly loaded by variableHistory() During initial visualization of a widget chart In several similar cases
384

function of Utilities context

that's configured to include historical events or variable values

Despite events are rarely loaded, the number of events loaded by a single query is not limited by the platform since certain installations require millions of events to be loaded at once. System architects designing AggreGate-based solutions should take care of this and consider maximum number of loaded events when building server-side data processing chains and visualization dashboards. An attempt to load too large number of events at once will cause AggreGate Server memory depletion and and reproduce itself as severe performance degradation caused by Java Virtual Machine garbage collection, possibly causing full server freeze or internal memory errors. The event tables list available in this documentation is not complete. Diverse AggreGate Server modules and plugins may request creation of other dedicated event tables that are not mentioned here. All events that weren't explicitly configured to use a custom table are written to ag_events table. Table ag_info ag_alerts Description Contains Info Contains Alert
885 224

events. events.

2000-2013 Tibbo Technology Inc.

AggreGate Server

87

ag_xxx _change

Contains all Change 891 events representing changes of variables in a single device context 677 (matching device xxx ). Note, that the table name can be truncated due server-wide database table name length restriction.

Direct Access to AggreGate Server Database

Direct access of third-party applications to AggreGate Server database is strongly discouraged. AggreGate is a powerful platform offering a mature SDK and diverse kinds of APIs for local and remote access to all data elements contained in the server database. However, API-based access will always inherit proper locking, permission checking 931 , and performance optimizations. Direct modification of data contained in AggreGate Server database will in most cases cause incorrect system behaviour. However, direct read (SELECT) operations may be used in rare cases. Please contact Tibbo for consulting on how to avoid direct database access.

3.2.5.4 Database Performance Tuning

Maximized performance of AggreGate Server database is the key factor for ensuring high performance of a whole AggreGate installation. Here is the short list of generic database performance optimization hints: 1. AggreGate Server uses a lot of INSERT and UPDATE queries, so make sure to follow database manufacturer's advices for increasing INSERT/UPDATE performance. 2. The number of allowed simultaneous connections must be greater then the Maximum Connection Pool

Size

58

global configuration setting.

3. When variables values

869 containing large binary blocks (sounds, images, firmware files) are stored in the database, AggreGate Server saves them using a single INSERT/UPDATE transaction. Thus, the maximum size of data transferred in one transaction should not be limited, or should be limited by a sufficiently large value (we recommend the limit of 100 MB).

4. For large installations, we recommend disabling synchronous flushing of INSERT'ed or UPDATE'd data

to the disk upon transaction commit. This may bring significant performance improvements.
5. If database server is running on the same machine with AggreGate Server, we recommend allow it

using 25-40% or RAM, leaving the rest for AggreGate. Also, avoid swapping.

Database Connections Pool Performance Tuning

This advanced section discovers how AggreGate Server manages database connection pool. AggreGate Server uses Java connection pooling library called c3p0 to manage database connections. The default settings of the c3p0 library can be overridden by adding new values to hibernate.properties file located in the AggreGate Server installation directory. Here is an example of hibernate.properties file content: # Ensure proper database problem handling hibernate.c3p0.checkoutTimeout=30000 # Too high idle time is known to cause errors caused by DBMS-initiated disconnections hibernate.c3p0.maxIdleTime=300 The configuration settings of the c3p0 library are described here: http://www.mchange.com/projects/c3p0/. All c3p0 properties should be prefixed with "hibernate.".

3.2.6 Failover Cluster

AggreGate has built-in support for building a failover cluster to ensure high availability of provided services. The failover cluster consists of two or more installations of AggreGate Server and one or more installations of the underlying database engine 80 . High availability is a system design approach and associated service implementation that ensures a prearranged level of operational performance will be met during a contractual measurement period. The objective of failover cluster is reaching 100% availability of the server. The cluster consists of Master Node and

2000-2013 Tibbo Technology Inc.

88

AggreGate Documentation

one or more Failover Nodes . During normal operation, the master node is servicing all operations. All failover nodes are running in standby mode and monitoring the state of master node. The failover nodes are automatically switched to Failover Master mode (i.e. activated) in the following cases: Network or power outage of the master node Major hardware or software failure of the master node Both master and failover nodes are full installations of AggreGate Server that can work on its own. However, master and all failover nodes share the same database.

AggreGate Cluster Features

The integrated failover clustering engine has some unique features: No dependencies to third-party software or operating system services, such as Linux Heartbeat or Microsoft Cluster Service Cluster nodes intercommunication is performed via the database, no additional setup of node-to-node IP communications is necessary Database mirroring is optional and may be implemented using DBMS native replication or AggreGate-based replication Cluster nodes benefit from database load balancing Cluster nodes may run on different operating systems and hardware

Failover Cluster Basics

The failover cluster includes two separate levels of ensuring high availability service: database failover and AggreGate Server failover. Database failover implies setting up more than one installation of the database engine 80 . This database engine is used by both master and failover nodes. If one of the database installations fail, the other(s) will continue to server AggreGate Server requests. AggreGate Server failover technology comprises one Master server and one or more Failover servers that share the same (possibly clustered/replicated) database. The failover servers are activated when the master server fails due to any reason. AggreGate Master server may run on the same physical machine with the "first part" of clustered/replicated database installation, while Failover server may share physical hardware with the second database engine installation. This allows to build a complete failover solution using just two physical servers. For further information see: Database Failover
89 95

AggreGate Server Failover

Failover Cluster Setup

Perform the following steps to set up AggreGate Server failover cluster: Install two or more copies of AggreGate Server on different physical servers. Configure database failover 89 on every server, i.e. configure all servers to use a single shared (and possibly clustered/replicated) database. In most cases it will be sufficient to complete AggreGate-based database replication configuration procedure 92 . AggreGate cluster nodes communicate with each other via a shared database cluster, so using a single common database for all cluster nodes is an absolute requirement. Change Cluster Role 59 global configuration setting of the one server to Master. Change roles of the other servers to Failover. See Server Configuration 51 for details. Change Failover Mode only. Start all servers.
59

of one failover server to the Normal. Change mode of the other failover servers to Read-

2000-2013 Tibbo Technology Inc.

AggreGate Server

89

Failover servers must be started in Service Mode

46

The master node should start normal operations, while failover nodes should switch to standby mode, showing "Monitoring Master Server Status" message on the splash screens.

Cluster Servers Security

All servers in the cluster have access to all information flowing inside AggreGate. Therefore, the same security precautions should be taken for both Master and Failover servers.

3.2.6.1 Database Failover

AggreGate Master and Failover servers 87 share the same database 80 used to store configuration data and historical system events. This database should be protected from failures by replicating the data between several physical locations. There are three ways of setting up the database in the failover cluster environment: AggreGate Database Replication Engine Native Database Replication Non-replicated Database
94 93 91

(not recommended)

AggreGate Database Replication Engine

The common way of setting up database replication is using database replication engine integrated into AggreGate Server 91 to write data into multiple independent databases and load-balance read operations.

Native Database Replication

2000-2013 Tibbo Technology Inc.

90

AggreGate Documentation
93

The second way of AggreGate Server database replication is using native replication technology server to build a database failover cluster.

of the database

Non-replicated Database
Some AggreGate Server installation may also share a single non-clustered database 94 between Master and Failover servers. However, this method doesn't protect the whole system from database server failures.

2000-2013 Tibbo Technology Inc.

AggreGate Server

91

Preferred Database Failover Method

In most cases, database failover clustering should be implemented using AggreGate built-in database replication method 91 . Its configuration is as simple as setting up two or more separate database server instances and editing several global configuration options. However, this method guarantees database data integrity and ensures optimal performance.

3.2.6.1.1 AggreGate-Based Database Replication

AggreGate Server has built-in High Availability Database Cluster engine that may perform database replication and load balancing 89 in a generic database-independent way. This engine normally shares the same configuration on AggreGate Master and Failover servers. It is configured to: Monitor connections with several database servers. Write any data generated by AggreGate Server to all databases. Once certain data is requested by AggreGate Server, choose a less-loaded database to get data from. This ensures load balancing between database servers. Once a certain database has been recovered after temporary failure or unavailability period, synchronize the data between the failed database and other (active) databases.

Pros and Cons

Pros: Configuration is easy and database-independent. Data is replicated to all database cluster nodes to ensure reliability. Database servers load balancing upon read operations. Cons: Slight overhead of AggreGate Master server during database write operations.

2000-2013 Tibbo Technology Inc.

92

AggreGate Documentation

All database nodes must use the same auth credentials.

Configuration
Below is the list of configuration changes required to set up AggreGate database replication.

DATABASE SERVERS
Set up two or more identical database servers. Configure all servers to accept connections from IP addresses or host names of AggreGate Master and Failover servers.

MASTER AGGREGATE SERVER

Start Server Configurator
51

.
55

Enable Database Clustering

option in the Database tab.

Edit the Cluster Databases 56 table by adding a record for each of the database servers. Make sure that you've specified correct URL of each database. Make sure that Database Username, Database Password and Database Dialect settings in the Database tab match your databases. Save global configuration and start the server. It should now connect to the database cluster. All databases in the cluster must use the same username/password pair for accepting AggreGate Server connections.

FAILOVER AGGREGATE SERVER

Perform the same changes as on the Master server, i.e. enable Database Clustering and add records to the Cluster Databases table.

Database Failure Handling

The database clustering engine performs periodic checks of each database's availability and integrity. If a certain database has failed it is disconnected from the cluster and marked as Not Active. The server does not attempt to perform further read/write operations with this database.

Database Activation and Synchronization

The server periodically checks availability of all inactive databases. If an inactive database appears to be alive, the server will automatically reactivate it. This process involves synchronizing data between reactivated database and other databases in the cluster, and thus, may take significant time and cause high consumption of server resources.

Viewing Database Cluster Status

To view the status of individual databases participating in the database cluster, open Cluster Databases 56 table in the AggreGate Server global configuration. Active field in this table indicates whether a database is currently being used by the cluster.

Cluster Databases State Persistence

AggreGate remembers what cluster databases are active and persists this information between server restarts. The data is stored in OS-dependent way, e.g. in system registry (for Windows systems) or file (for Linux systems). To make sure that cluster configuration file always matches remembered databases state, remove cluster databases only via server configurator 51 utility or other 51 AggreGate Server configuration methods. Do not remove database accounts from the database cluster configuration file 92 by editing this file directly.

3.2.6.1.1.1 Database Cluster Configuration File

The database cluster configuration file is called database.cluster.xml. It is located in AggreGate Server installation directory. This file defines: The list of databases that will store AggreGate Server data

2000-2013 Tibbo Technology Inc.

AggreGate Server
Database load balancing rules Synchronization strategy for the recovered database cluster nodes In most cases, this file should not be edited directly. Use Cluster Databases Configurator 51 utility to make changes to database cluster settings.
56

93

table accessible via Server

Configuring Database Cluster File

Here is the list of changes necessary to manually set up database replication: Set the dialect attribute of <cluster> tag according to your database type: Database Type Apache Derby Firebird, InterBase H2 HSQLDB IBM DB2 Ingres Mckoi MySQL MySQL MaxDB Oracle PostgreSQL Sybase Standard (SQL-92 compliant) Attribute Value derby firebird h2 hsqldb db2 ingres mckoi mysql maxdb oracle postgresql sybase standard

Make sure that number of <database/> blocks matches the number of databases in the failover cluster. Add/ remove blocks if necessary. Assign a unique ID to every database by editing id attribute of every <database/> block. Set value in every <driver> tag to the name of your JDBC driver class name. See Database Driver 56 for details about driver class names. Also, check database-specific notes 81 to find out where to get the driver and what is its class name. Put your database driver file into /lib subfolder of AggreGate Server installation folder. Check database-specific notes 81 for details. Set the <url> tag to your database connection URL. URLs will likely be different for all databases in the cluster, since URL usually includes database server address. See Database URL 56 and database-specific notes 81 for details. Properly set <username> and <password> tags for each database. All databases in the cluster must use the same username/password pair for accepting AggreGate Server connections.

3.2.6.1.2 Native Database Replication

Most modern enterprise-grade databases have native support for clustering and data replication. AggreGate Server may benefit from native database clustering by auto-switching between primary and failover database nodes, while the database engine manages data replication between nodes. The following database engines compatible with AggreGate Server support failover clustering technology: Oracle MySQL

2000-2013 Tibbo Technology Inc.

94

AggreGate Documentation

Microsoft SQL Server PostgreSQL

Pros and Cons

Pros: Data is replicated to all database cluster nodes to ensure reliability. Native replication guarantees fast and efficient data replication between nodes. When a database cluster node temporarily fails, the subsequent synchronization of data between failed node and other nodes is performed by the DBMS engine with minimal overhead. Cons: Building a native database cluster can be a complex challenge. AggreGate Server JDBC (database) driver must be configured to auto-switch to failover database servers.

Configuration
Below is the list of configuration changes required to set up native database clustering.

DATABASE SERVERS
Refer to your database server documentation for details on how to build a cluster.

MASTER AGGREGATE SERVER

If your master server is not yet configured to work with the clustered database, switch
81

it to your database server.

Refer to your JDBC driver documentation for details on how to configure the addresses of failover servers. In most cases this is performed by specifying failover server addresses in the Database URL 56 .

FAILOVER AGGREGATE SERVER

Use exactly the same database configuration as on the Master server.

3.2.6.1.3 Sharing Single Database

Master and failover installations of AggreGate Server may share the same non-clustered database. This database may be located: On a separate physical machine On the same physical machine with Master server or one of the failover servers

Pros and Cons

This method of configuring the database in the clustered environment is the simplest since it does not require any additional settings. Howerver, in this case the database is not replicated and all data is stored in the single location. Thus, the database is a bottleneck of a whole failover cluster. Corruption of the data or failure of the database server software will cause service interruption. Therefore, such database setup has a few limited use cases.

Configuration
Below is the list of configuration changes required to set up Master and Failover nodes to use the single non-clustered database.

DATABASE SERVER
Allow your database server to accept incoming connections from IP addresses of Master and all Failover nodes. Allow firewall running on the database server host to accept connections on the database port (e.g. port 3306 for MySQL database) from IP addresses of Master and all Failover nodes.

MASTER AGGREGATE SERVER

If the server is already configured to connect to the above database server, leave its configuration intact. Otherwise, switch
81

your master server to the above database server.

2000-2013 Tibbo Technology Inc.

AggreGate Server

95

FAILOVER AGGREGATE SERVER

Use exactly the same database configuration as on the Master server. If your database engine is running on the same physical machine with master server, you may need to change the database address in the Database URL setting 56 from localhost to the IP address or host name of the Master server machine.

3.2.6.2 AggreGate Server Failover

AggreGate Server failover cluster includes: Single Master Server One or more Failover Servers

Clustered or replicated database shared between all servers The failover servers are activated when the master server fails, e.g. due to: Network outage Hardware failure Operating System crash AggreGate Server failure Shortage of disk space Any other reason

Failover Server Modes

Failover servers may work in Normal Mode or Read-only Mode. The difference between these modes is explained below. The mode of failover server is controlled by Failover Mode 59 global cluster setting.

NORMAL FAILOVER MODE

In Normal Failover Mode, failover server take full control control or AggreGate cluster upon Master Server failure. It controls and monitors the devices, services operators connections, etc. All configuration changes and events are stored in the database and will be available for the Master server once it becomes operative again.

READ-ONLY FAILOVER MODE

In Read-Only Failover Mode, failover server does not perform any change to the underlying database. Its behaviour appears to be similar to the Normal Failover server at first glance: devices are being controlled and their configuration settings may be changed by operators, actions can be executed, and all system functions are available. However, no configuration changes and events are stored in the database. This causes several limitations: Historical events received by Read-Only Failover Server will not be available, e.g. when browsing event history of building charts All configuration changes will be lost if Master Server is re-activated or Failover Server is restarted Read-only Failover Nodes are very useful for quickly restoring cluster reliability in case of permanent Master node failure: Make
98

a Normal Failover node new Master node

59

Make a Read-only Failover node new Normal Failover node by editing its Failover Mode setting

global cluster

The above operations will take mere minutes, however cluster reliability will be preserved for the case of new Master node failure. It is now possible to set up a new Read-only Failover node without any rush.

Only one Normal Failover node is allowed within a high availability cluster. Other failover nodes must work in Read-Only Mode.

Failover Scenarios
This section describes several common Failover Cluster configurations. Note that database cluster
89

is shown as a

2000-2013 Tibbo Technology Inc.

96

AggreGate Documentation

"cloud" on the below images. In practice, databases participating the database cluster will run on the same physical servers with AggreGate Server installations.

TWO NODES
The most common failover cluster configuration includes two servers: Master Server and Normal Failover Server. Once the Master fails, the Failover switches to Failover Master mode, taking over Master's operations.

THREE NODES
The three nodes failover cluster helps to maintain system reliability even when the Master server has failed.

2000-2013 Tibbo Technology Inc.

AggreGate Server

97

If the Master server fails, three nodes cluster will work similar to two nodes cluster. This allows to protect from Failover Master's failure and gives system administrators spare time to restore three nodes operation.

2000-2013 Tibbo Technology Inc.

98

AggreGate Documentation

Failover Mode Operation

If a Master node fails, it stops performing regular database updates called "heart beats". The absence of these updates is notified by the Failover nodes. If no Master heart beats occur for longer than a Node Failure Detection Time 59 , the failover nodes are activated and start servicing normal system activities, such as device control operations and operator actions. The service interruption interval equals to the sum of Node Failure Detection Time and failover node activation time. This gap is typically less than a minute.

Disconnection of Failover Nodes

If a failover node is disconnected from the cluster, e.g. for an update, cluster operation continues without any change. However, the Master server constantly monitors the heart bean of Failover nodes. If no failover nodes seem to be alive for longer than the Node Failure Detection Time, Master server will fire a warning event in the Administration context 652 .

Failover Alert
Once a Master Server of AggreGate failover cluster fails, the Failover node raises a Failover Alert 217 . This helps to quickly notify system administrators of the situation. By default, an e-mail message is sent to the administrators. It is however recommended to configure an SMS message to be sent in case of Failover alert. See Alert SMS Notifications for details.

227

Making Failover Server a Master

In some rare cases the Master server may be completely lost in a severe accident, e.g. due to a major hardware failure. In this case it's necessary to make one of the Failover nodes the Master node. To switch a Failover node to the Master mode: Set up a new Failover node to preserve total number of nodes in the cluster Change Cluster Role
59

global configuration setting of the switched node to the Master

2000-2013 Tibbo Technology Inc.

AggreGate Server
Restart the new Master node

99

Configuring Client for Failover

To prepare AggreGate Client
776

to work in the clustered environment:

Create two or more server connections 779 in your workspace: first one for the Master Server and others for the Failover servers. Specify addresses or Master and Failover servers in the connection settings. Disable connections to the Failover servers to suppress startup connection errors. This is necessary since Failover nodes won't accept AggreGate Client connections while working in standby mode.

Once the Master node fails (and you'll get connection errors), just enable one of the failover connections

Configuring Web Desktop for Failover

Once the Master node of the high availability cluster fails, the system operators won't be longer able to log in to the Web Desktop 632 since the IP address an host name of Failover node differs from the address of failed Master node. There are two resolutions for this issue: All operators may manually navigate to the URL of the Failover node. In practice, this URL may be bookmarked in their browsers for emergency cases. It is possible to set up automatic DNS redirection. Search the Internet for "DNS failover" to find available solutions. Here is just one useful link: http://www.simplefailover.com/scenario3.aspx

3.2.7 Distributed Operations

AggreGate is one of a few device monitoring/management systems in the world that supports true distributed architecture. This architecture is designed to assure unlimited scalability by balancing all operations between AggreGate servers subdivided in multiple layers. Such common distributed architecture is expected to serve as a base for any modern and prospective management software. Unlike nodes of AggreGate failover cluster 87 , servers participating the distributed architecture are completely independent. Each server has its own database 80 , local user accounts 108 and associated permissions, etc.

Purpose of Distributed Operations

The primary objectives of distributed architecture are: Scalability. Lower-level servers may be heavily loaded by near-real-time control and extensive polling of devices. However, in practice the number of devices that can be managed by a single server is limited to several thousands. To scale the system for larger number of devices, it's reasonable to install multiple servers and join them into a distributed installation. Load Balancing. Each server in a distributed installation solves its own task. Network management servers check availability and operability of IP network infrastructure, while physical access control servers are serving requests from door/turnstile controllers. In addition, the supervising operations (such as generating and emailing reports) can be performed by a central server. Firewall Penetration . Secondary "probe" servers may be installed in remote locations and connect to the central server themselves. System operators connect to the central server only, so there is no need to setup VPNs and port forwarding to the secondary servers. Centralization . Secondary servers may work in fully automated mode, while their overall operation may be supervised by a single human via primary server installed in the central control room.

EXAMPLE 1: SMART CITY MANAGEMENT

Here is an example of multi-tier AggreGate-based architecture for smart city management/monitoring: Layer 1: physical hardware (network routers, controllers, industrial equipment, etc.) Layer 2: direct management servers (network monitoring server, access control server, building automation server, etc.) Layer 3: building control center servers (one server per a building, consolidates information from all "specialized" L ayer 2 servers in this building)

2000-2013 Tibbo Technology Inc.

100

AggreGate Documentation

Layer 4: urban district servers (the final destination for escalated lower-level alerts, real-time monitoring by human operators, integration with CRM systems) Layer 5: HQ server (supervision of area-wide servers, collection of overall reports and alerts) Any particular AggreGate server in the above schema may, indeed, be a multi-node failover cluster
87

EXAMPLE 2: MULTI-SEGMENT NETWORK MANAGEMENT

AggreGate Network Manager system build atop of AggreGate Platform is one of the most typical use cases for the distributed architecture. Large segmented networks of corporations and telecom operators cannot be monitored from a single location due to routing restrictions, security concerns and limited bandwidth between geographically separated segments. Thus, the unified monitoring system is usually composed of several components: A primary or central server consolidating aggregated information from all network segments Secondary or probe servers that perform polling of devices in isolated segments Specialized servers, such as a traffic decomposition server that handles billions of NetFlow events per day Secondary and specialized servers act as data providers for the primary server, exposing a part of their data model for the control center. This can be: The whole content of probe server's context tree, allowing full monitoring and configuration through the central server. In this case probe server is just used as a proxy for overcoming network segmentation issues. Alerts generated by probe servers. In this case 99% of jobs are performed remotely, but central server operators are immediately notified about issues raised in secondary segments. A custom set of probe server's data, such as certain mission-critical devices and important overview reports. The actual polling and report generaion will be performed by the secondary server, allowing to properly balance system load

Distributed Architecture Plugin

The consumer/provider connectivity of AggreGate Server is enabled by Distributed global configuration context 686 of this plugin provides access to: Providers configuration
102 103 103

Architecture plugin

950 .

The

Consumers configuration Distributed server status

3.2.7.1 Distributed Architecture Contepts

All AggreGate Servers have common model of their internal data: the context tree 863 . Each context in this tree is responsible for managing certain device 113 or system resource, be it alert 216 or report 241 . In the distributed architecture, each server can act as provider or consumer of data to/from other servers: Consumer gets a certain sub-tree of other server's context tree and connects its own context tree (i.e. imports contexts from other servers) Provider allows other servers to use its contexts (i.e. exports its contexts to other servers) The consumer's context that acts as a base for attaching provider's context sub-tree is called Mount Point. Each provider may have multiple mount points, i.e. connect multiple sub-trees to the consumer server's context tree.

2000-2013 Tibbo Technology Inc.

AggreGate Server

101

Once a consumer server has imported a context sub-tree from another server, the server's own contexts may interact with imported contexts. Here are several examples: If server B imports a device context 677 from server A , it may declare an alert that checks certain metric of this device and fire an alert if threshold is exceeded. In this case, the physical device will be polled by server A, but the alert will be processed by server B. If server B imports a user account context 759 from server A , the system operators may fully control all devices and resources of this user by connecting to server B. However, all modifications will be redirected to server A and saved in its database 80 . This may be useful if operators have no direct access to the server A, e.g. if it's installed in the private LAN. Finally, server B may import the whole context tree from server A . In this case, any resource from server B may access all resources of server A, allowing any type of interaction.

Communications Between Providers and Consumers

All communications between consumer and provider servers are performed via IP networks using SSL-secured connections. The communications are truly bidirectional: Consumers can connect to providers and accept incoming provider connections. Similarly, providers can connect to consumers themselves and accept incoming consumer connections. The two-way communications eliminate any troubles may be caused by different network configurations and firewalls. Any AggreGate Server can be consumer and provider simultaneously. Moreover, it can have multiple links, i.e. import contexts from several servers and export its own contexts to several other (or even the same) servers.

3.2.7.2 Distributed Architecture Configuration

The global configuration of AggreGate's distributed operations engine can be accessed via Edit Driver/Plugin Options action of Distributed Architecture plugin's global configuration context 686 . Here is the list of available configuration options: Port Number to Listen for Provider Connections. The port on that incoming connections from provider servers are accepted. Must match port number specified in remote server's consumers table 103 . Port Number to Listen for Consumer Connections. The port on that incoming connections from consumer servers are accepted. Must match port number specified in remote server's providers table 102 .

2000-2013 Tibbo Technology Inc.

102

AggreGate Documentation

Command Timeout. Timeout for consumer-provider communication commands.

3.2.7.3 Configuring Providers

Providers configuration table can be accessed via Edit Driver/Plugin Options action of Distributed plugin's global configuration context 686 . Every provider has the following properties: Name . The unique name of provider. Name must follow context naming conventions
863 .

Architecture

Connection Type . For Incoming connection, this consumer awaits and accepts TCP connections from providers. For Outgoing connections, the consumer establishes its own TCP connection to provider. Address. Address of provider server. Valid for Outgoing provider connections. Port. Port number on provider server to connect to. Valid for Outgoing provider connections. Username. Name of user account
108

to use for authorization on provider server.

Password. Password for the above user account. Mount Points. The list of remote context sub-trees or individual contexts that will be attached to the local context tree. Properties of a mount point are described below.

Mount Point Configuration

Name . When the root context of the remote context sub-tree will be attached to the local tree, its local name will differ from the remote name. This local name is defined by the mount point's Name setting. Local Path (Mount Point) . Path of context that will act as a "connection point" for contexts imported from the provider server. This is the path on local (consumer) server. Remote Path (Root Node of Imported Context Subtree) . Path of root context of context sub-tree what will be imported from provider server. This is the path on remote (provider) server.

EXAMPLE
Imagine that provider server has the following contexts:

A A.B A.B.C1 A.B.C2

The consumer server wants to import context sub-tree rooted at A.B. The imported sub-tree should be connected at path X.Y of the provider context. For the above setup, we can use the following Mount Point configuration options: Name : P Local Path: X.Y Remote Path: A.B Once the consumer-provider connection is established and import operation succeed, we'll get the following relations between paths of contexts: Context Path on Provider Server A.B A.B.C1 A.B.C2 Matching Context Path on Consumer Server X.Y.P X.Y.P.C1 X.Y.P.C2 It may seem more logical that paths on consumer server should start from X.Y.B. However, the name of root imported context is substituted by provider name (i.e. B substituted by P). This is necessary to avoid name duplication. For example, the consumer server has "admin" context in "users", and we want to import "admin" context from provider server by using "users" as a mount point. We can name the provider "provider_admin" and, thus, the path of root imported context on consumer server will be "users.provider_admin".

2000-2013 Tibbo Technology Inc.

AggreGate Server

103

The root context name substitution also helps to import remote root context (whose context path equals to empty string).

3.2.7.4 Configuring Consumers

Consumers configuration table defines outgoing connections to consumer servers. Once this provider server connects to a remote consumer server, it tells the latter what providers table 102 entry should be used to import contexts from this server. The consumers table can be accessed via Edit Driver/Plugin Options action of Distributed global configuration context 686 . Every consumer has the following properties: Name . The Name of providers table
102

Architecture plugin's

entry to use on the remote consumer server.

Address. Address of consumer server. Port. Port number on consumer server to connect to.

3.2.7.5 Distributed Server Status

AggreGate server provides access to the status of connected consumers and providers. To access the status, use View Status action of Distributed Architecture plugin's global configuration context 686 . There are two status tables: Providers Status. Shows details about servers those data is imported by this server. Consumers Status. Shows details about servers that import data from this server.

Providers Status
Providers status table has the following fields: Name . Name of provider. Connection Type . Incoming or outgoing. Active. Shows whether provider is active. Connected. Shows whether provider is connected. Address. The IP address of provider server.

Consumers Status
The list of consumer status table fields: Name . Name of local provider the consumer is connected to. Connection Type . Incoming or outgoing. Active. Shows whether consumer is active. Address. The IP address of consumer server.

3.2.7.6 Permissions in Distrubuted Environment

Once connection between consumer server (CS) and provider server (PS) is established, the CS authenticates on the PS using certain PS user 108 's credentials. Thus, CS gets the permissions 931 of this user at the PS. All operations on the PS that are initiated by the CS (or human operators of the CS) are performed according these permissions. Simply speaking, at the side of provider the consumer is nothing more than a Client in.
776

that has connected and logged

However, if the operators of CS want to access contexts imported from PS, they must connect to the CS and authenticate as a certain CS user first. Let's resume the above. Imagine that server B (the consumer) imports context "context123" from server A (the provider). The local path of this context at server B is "mount.context123" (according the provider configuration). The server B authenticates at server A as user "userA" (defined on server A). Human operator connects to server B and

2000-2013 Tibbo Technology Inc.

104

AggreGate Documentation

wants to perform an operation with imported context. He authenticates at server B as user "userB" (or course, defined on server B). Here are the required permissions: User "userB" on server B must have permissions to access the context "mount.context123" at server B. User "userA" on server A must have permissions to access the context "context123" at server A.

3.2.8 Data Backup and Restoration

AggreGate is used for mission critical applications, so it's very important to ensure data integrity and fast recovery from failures. AggreGate Server has been designed to assure easy backups of both Database 80 and server configuration. It's strongly recommended to perform system backup on a regular basis. The AggreGate installation backup may include the following steps: Server Installation Folder Backup . Periodic backup highly recommended when AggreGate Server installation is not mirrored by a failover server 87 . Server Configuration Folder Backup. Recommended if the full server installation folder backup is not performed. Statistics Backup. Recommended if the full server installation folder backup is not performed. Embedded Database Backup. Recommended if the full server installation folder backup is not performed. External Database Backup. Highly recommended if the external database is not mirrored, see database failover 89 for details.

If the server is going to be upgraded, the following backup operations are obligatory before the upgrade: Server Installation Folder Backup External Database Backup

Server Installation Folder Backup

AggreGate Server installation 43 process does not perform any modifications to operating system's configuration files or the Windows registry. No files are stored outside of the main installation directory. AggreGate Server itself also stores all files created during normal system operation within the same directory. Thereby creation of full system backup of AggreGate Server installation is as easy as making a full copy of server installation directory (e.g. %program files%/AggreGate under Microsoft Windows) and archiving it. In the case of major problems (such as disk drive failure or database corruption by an erroneous script 628 ), previously archived installation can be restored by simple extraction of the most recent backup archive to the same machine where is was running before the failure, or even to another server. No additional actions are required, server may be started immediately when extraction process finishes. Server installation folder backup will already include: Server Configuration File Backup (make sure that the default configuration file is used, see notes below) Statistics Backup (make sure that the default statistics location is used, see notes below) Embedded Database Backup (make sure that the default embedded database folder is used, see notes below) However, backup copy of the server installation folder will not include an external database backup It may be necessary to obtain new license file if backup is restored to another server. See License Issues for more information.
105 .

29

Server Configuration File Backup

The server configuration file 52 contains basic AggreGate Server settings, such as name of installation and database access settings. To backup server configuration file, make a copy of server.xml file located in the AggreGate Server installation folder and store this copy in a safe place. The server may use configuration file those name is specified as a command line parameter that you're backing up the proper file.
47

. Make sure

2000-2013 Tibbo Technology Inc.

AggreGate Server

105

Statistics Backup
The statistical channels 936 store data in the /statistics subfolder of AggreGate Server installation folder. This folder should be backed up to preserve statistical archives. Location of the statistics storage folder can be changed in the global server configuration you're backing up the proper folder.
55

. Make sure that

Embedded Database Backup

The embedded database engine 80 that is included in all AggreGate Server bundles stores database data in the /db subdirectory of server installation. To backup the whole embedded database, do the following: 1. Stop the server 2. Copy the /db subdirectory of AggreGate Server installation directory to a backup location. Compressing contents of the /db folder will decrease backup size 5-10 times.

Location of the embedded database can be changed in the global server configuration you're backing up the proper folder.

55

. Make sure that

External Database Backup

Large AggreGate Server installations with hundreds of managed devices usually store data on an external database server, such as MySQL or Oracle. Such installations require an external database backup to be performed in addition to the Server Installation Folder Backup 104 in order to get a full copy of AggreGate Server installation. The server stores all data in several tables located within one database (see Database 80 and Database Settings 55 sections for figuring out what database is used to store server data). This database should be backed up during server backup. Method of backing up the database depends on the Database Management Engine used by a certain AggreGate Server installation and it's outside the scope of this article.

BUNDLED MYSQL DATABASE BACKUP

If the AggreGate Server is using the bundled MySQL database server package, it's possible to backup its database using the following method: - Execute the following command from the server installation folder:

mysql/mysqldump --port=3316 --user=root --skip-lock-tables your_database_name > database.sql

- Compress the resulting database.sql file and store it in the safe location

3.2.9 Moving AggreGate Server Installation

Relocating or replicating AggreGate Server installation from one machine to another can be useful in the following cases: at first stages of project development, for moving from a development PC to a production server if a production server is switched to a new hardware configuration or operating system The relocation process comprises following steps: 1. Installation of AggreGate Server on a new machine 2. Configuration file copying 3. Database replication 4. Statistics replication

Installing New AggreGate Server

2000-2013 Tibbo Technology Inc.

106

AggreGate Documentation

A fresh copy of AggreGate Server should be installed on a new server machine. Version of AggreGate Server installed on a new machine must be same (recommended) or newer than AggreGate Server version of a moved installation. The new installation should include the same set or vertical market extensions (and, thus, AggreGate Server plugins and drivers 129 ) as the old installation.
950

Copying Configuration File

Second, server.xml global configuration file 52 should be copied from the old installation to the new one by overriding default config file of the new installation.

Database Replication
Third step is moving server database
80

to the new installation. There are several ways to perform this:

1. By installing a fresh copy of database engine on the new server and manually moving database files according to database server's database relocation instructions. 2. By installing a fresh copy of database engine on the new server, creating an empty database, and following Switching to Another Database Engine 81 instruction set to move data from the old database to the new one. 3. If the new AggreGate Server installation should use same standalone database that was used by the old one, just check/modify databaseUrl parameter in the copied server configuration file (server.xml) to make sure IP address or host name of the database server is the correct one that should be used from the new server location. If AggreGate Server uses a bundled MySQL or Apache Derby database, the database relocation should be very simple: For bundled MySQL database, just copy /mysql subfolder of old AggreGate Server installation folder to the new server. Make sure both servers are stopped during this process! When the copy is created, make sure MySQL autostarted during startup of the new server machine. For example, on a Windows machine it's possible to use mysqld --install command to install MySQL as a service. See details here: http://dev.mysql.com/doc/refman/4.1/en/ windows-start-service.html For bundled Apache Derby database, just copy /db subfolder of old AggreGate Server installation folder to the new server. Make sure both servers are stopped during this process!

Statistics Replication
To relocate a Round-Robin Database used by statistical process control Make sure both old and new servers are stopped Move /statistics folder from the old installtion to the new one. Check statisticsFolder parameter the old configuration file ( server.xml) to locate statistics folder in the old installation (it's located in AggreGate Server installation folder by default). Check or modify statisticsFolder parameter in the new installation's configuration file to find out the proper destination of copies statistics folder.
936

module:

3.2.10 Safe Mode

AggreGate Server may be launched in safe mode by using -a command line parameter. Safe mode is used to avoid different startup errors, launch a partially functioning AggreGate Server and delete and/or fix resources that produce these startup errors. Differences between safe mode and normal startup: Devices Alert Job
216 113

are not synchronized with the server

triggers are not processed and no alerts are raised

266

scheduler is not started and not jobs are executed

257 625

Tracker Autorun Script

values are not calculated actions are not executed

628

execution is not allowed

2000-2013 Tibbo Technology Inc.

AggreGate Server

107

3.2.11 Managing Pre-Built Resources

Distribution bundles of AggreGate and derived products provide numerous out-of-the-box resources, such as alerts 216 , event filters 206 , reports 241 and widgets 312 . These resources are pre-configured for solving different data management tasks. The resources may be included into AggreGate core or different plugins 950 . By default, all built-in resources are created during first server startup. However, there may be necessary to create resources manually in the following cases: If some resources were deleted by mistake or because they were corrupted by inaccurate editing If AggreGate Server was upgraded

Creating Resources
To create resources provided by AggreGate core or plugins, run Create Resources ( 726 . You will be prompted to select resources to be created: ) action from the root context

Resource list can be sorted, filtered and grouped by resource types and categories.

Once the resources were created, you can easily modify them. If a certain resource was corrupted and you didn't make a backup, just delete it and run Create Resources action again to restore it.

Deleting Resources
It's possible to delete built-in resources like any other AggreGate Server resources. However, to simplify batch removal of multiple resources, Delete Resources ( be used. ) action from the root context
726

can

2000-2013 Tibbo Technology Inc.

108

AggreGate Documentation

3.2.12 System Tray Menu

After AggreGate Server starts, a new icon appears in the System Tray. It looks like this: The tray menu is not available if server is running in Service Mode
46

Clicking this icon will bring up menu with the following items: Open AggreGate Server Control Center. Opens AggreGate Server Control Center Open AggreGate Client Download Page. Forwards to a AggreGate Client Open Help in Browser. Opens the online version of this manual. View Activation Key. Allows to view and copy the activation key View Server Log . Opens Event Log events.
791 29 776 631

in the browser window.

download page.

.
74

window showing server log messages

. Technically, shows Log

46

652

context

Restart Server . Restarts the server. Note, that restart is available only if server runs in service mode Stop Server. Stops the AggreGate Server.

3.2.13 Dealing with Time Zones

AggreGate is a distributed system. In a large AggreGate installation, different components may be deployed in several countries or even on several continents. Thus, AggreGate Server, users, and Devices 113 may be located in different time zones. You have to configure time zones properly when setting up the system. Once you do that, timestamps will be automatically converted during system operation. Here is a list of principles used by AggreGate when operating in multiple time zones: 1. AggreGate assumes that server is located in the Server Time Zone specified in the Global Configuration Settings 2. The Time Zone for every user is defined in the user account settings
108 . 124 . 53

3. The Time Zone for every Device is defined in the Device account settings 4. By default, the time zone for new users is undefined. 5. By default, the time zone for new Devices is undefined.

6. When the Device synchronizes 126 its internal clocks with the Server, time is converted from Server's time zone to the Device's time zone. If Device's time zone is undefined, it's assumed to be located in owning user's time zone. If owning user's time zone is undefined too, no time conversion occurs. 7. When events are loaded from the Device and stored in the event history, the event's internal time is converted from the Device's time zone to the Server time zone. If Device's time zone is undefined, it's assumed to be located in owning user's time zone. If owning user's time zone is undefined too, no time conversion occurs. 8. Internally, AggreGate Server stores all date/time values in UTC. 9. When timestamps are shown to the user in AggreGate Client 776 or Web Desktop 632 , the local time in the User's time zone is used. If user's time zone is undefined all timestamps in Web Desktop 632 are shown using Server Time Zone; all timestamps in AggreGate Client 776 are shown using default time zone of the PC running AggreGate Client. 10. The Time zone defined in the operating system running AggreGate Server is used only once: to set a default time zone for the AggreGate Server. Once that's done, only the time zone defined in the server settings is used.

3.3 Users
The AggreGate Server is built as a multi-user server . Ordinarily, one person installs and manages the AggreGate Server itself, and numerous other people use it to access their Device Servers 1003 , Devices 113 and other objects like Alerts 216 , Event Filters 206 etc. These users (i.e. system operators) can all belong to the same company, or they can be paying customers who purchase AggreGate Server access from a vendor who installed AggreGate Server on his own servers. Users access the server through user accounts . Immediately following AggreGate Server installation, only a single account exists in the system, default administrator 109 . For someone to gain access to AggreGate Server using one of its User Interfaces (AggreGate Client 776 , Web Service 976 , etc), they must be authenticated and authorized by the server. The only operation that does not require prior authentication is self-registration 109 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

109

Related tutorial: Granting One User Access to Objects of Another User

1215

Ownership
Every user account owns different system objects: Alerts 216 , Widgets 312 etc. The Contexts 863 of all these objects always exist, but a user's permission table may prevent him from accessing his own objects. Objects that are accessible by newly created users are defined by Default User Permissions 73 global AggreGate Serversetting.

Administering Users
Two contexts are used to administer users: One is the general Users 756 context, for actions related all users accounts. The other is the User 759 context, corresponding to a single user account.

3.3.1 Default Administator

The default administrator's account is the only user account that is created on a new AggreGate Server installation:

Username: admin Password: admin

You are advised to change the password as soon as possible.

The default administrator has permissions to do everything. Technically speaking, his permissions table a single record that grants him Administrator -level 932 access to all AggreGate Server contexts 863 : Context Mask * Permissions Administrator

933

contains just

The default administrator account cannot be deleted, and its permissions table cannot be edited.

3.3.2 User Account Management

There are two ways to create new user accounts: Creation by users with administrative permissions Account self-registration In most cases, the first method should be used. System administrators may create user accounts using the New User Account 759 action in the Users context. The only parameters that should be specified during account creation are a username and password. All other settings are set to default. The method of building the default permissions table for the new account is described 934 in Security and Permissions article.

Deleting User Accounts

Deleting a user account permanently destroys all resources owned by the user, such as device accounts etc.
113 ,

alerts

216 ,

3.3.3 User Self-Registration

Self-registration allows AggreGate operators to create their own accounts, using any AggreGate Server User Interface. This method is available only if Enable users self-registration 54 global setting is turned on. When this setting is enabled, if a user attempts to log in (in AggreGate Client, etc) with a non-existent username, they will be prompted to register a new account. If he confirms the registration, a new user account will be created in AggreGate Server with the credentials specified bythe user. Check details here 789 .

2000-2013 Tibbo Technology Inc.

110

AggreGate Documentation

Self-registration may be securely used only in private networks where no untrusted users may access the AggreGate Server. User accounts are removed using the Delete 759 action of a User 759 context. When an account is removed, all associated Device Server Accounts, Device Accounts, Alerts and other objects are also destroyed. Account removal is a permanent operation which may not be undone. User cannot delete his own account. One of your users lost his password? See User Forgot His Password
112 !

The Users 756 context that allows to manage users is visible in AggreGate Server User Interfaces (e.g. in AggreGate Client) only if a user's permissions allow him access to more than one user account.

3.3.4 User Account Configuration

This section covers user account configuration properties. All properties described here are available via Configure
904

action of a User context

759 .

3.3.4.1 Properties
This property defines the basic options of a user account. Username First Name Last Name Password Country Region/State/Province/ Area ZIP Code City Address 1 Address 2 Comments Company Department E-mail Address Phone No. Fax No. Time Zone Name of user account, and also name of User 759 context. This is a read-only property which may not be changed once the account is created. First name of the account owner. Last name of the account owner. Account password that is used by user to log in. User's country. User's region. User's postal code. User's city. User's address. Second line of user's address. Additional info about the account. User's company. User's department. User's E-mail address. User's phone number. User's fax number. User's time zone settings, used to show correct time for this user. Also, Devices 113 registered under account are assumed to be located in this time zone if no time zone is explicitly specified in the Device Account. See Dealing with Time Zones 108 for more info. User's locale setting identified by a two-letter country code that affects various user interface parameters. Date pattern 1321 defines how date values are formatted when shown to the user.

Locale Date Pattern

2000-2013 Tibbo Technology Inc.

AggreGate Server

111

Time Pattern Week Start Day

Time pattern 1321 defines how time values are formatted when shown to the user. Controls the first day of week displayed in calendar. Possible options are Sunday and Monday.
760

These may be accessed via the childInfo

variable.

3.3.4.2 Account Settings

This property defines different settings of a user account. Account Enabled Activation Time Expiration Time User login is not allowed if account is disabled. If activation time is set, user login is not allowed until this time. If expiration time is set, user login is not allowed after this time.
109 .

These settings are read-only for account of default administrator

These may be accessed via the settings

761

variable.

3.3.4.3 Resources
The Resources table defined what types of resources (such as alerts, widgets, or reports) does the user have. If a certain type of resources it disabled in this table, the user's account will not have a container context 863 for resources of this type, i.e. it won't be possible to create and manage such resources. If a user already had some resources of a certain type and this type of resources was disabled in Resources table, the existing resources will not be deleted. However, those resources won't be available until the resource type will be reenabled. Disabling resources differs from disabling access 111 to these resources. If a access to certain resource or resource container is not granted in user's permissions table, other users will still be able to access and manage these resources. However, if a certain resource type is disabled in Resources table, the container and its child resources will be unavailable for all AggreGate Server users. The default availability for all resources types is globally configurable through the Default User Permissions The resources table may be accessed via the resources
762 73

table.

variable.

3.3.4.4 User Photo

This property be used to store a personal photo of this user, up to 200 Kb in size. The photo may be referred to from different facilities, such as login/logout reports. It can be accessed via the photo variable.
762

3.3.4.5 Permissions
This tabular property contains user's permissions table found in Security and Permissions 931 topic. Context Mask Permissio ns Mask
865 111 .

All information related to the user's permissions may be

of contexts to those this record will be applied

932

Permission level

for this record.

A user may not change his own permissions. User permissions can be accessed via the permissions
761

variable.

2000-2013 Tibbo Technology Inc.

112

AggreGate Documentation

3.3.4.6 Alerts
This property defines that popup alert notifications Notifications of alerts that are owned by the user Notifications of all alerts accessible by the user
225

will be visible to this user:

3.3.5 User Account Status

Account status information may be viewed using View Status fields: Account Creation Time
910

action of a User context

759 .

It contains the following

Read-only property, shows when the account was created.

110

Last Account Update Time Read-only property, shows when the account's basic properties

were last updated.

3.3.6 Resetting User Account Password

It sometimes happens that a user forgets his password. In such a case, the user must alert the system administrator, who will re-set his password. In most cases system administrator can just open settings of the user account in the UI and change value of Password field. In other cases, e.g. when password of the system administrator himself is lost, the password can be reset using command line.

Changing User Password Using Command Line

Resetting the password is done using the -p command line option option is -p <username> <password>.
47

of the AggreGate Server. The syntax for this

So, assuming the user johndoe forgets his password and alerts the administrator, here's what the administrator would do to reset johndoe's password to foobar: Shut down AggreGate Server (see Shutting Down the Server
47

).

Run AggreGate Server once more, with the command line argument -p johndoe foobar. johndoe's password would now be foobar and he would be able to login.

3.3.7 Suspending User Accounts

To temporarily disable a user account, edit the User Account Settings
111

and deactivate the Account Enabled flag.

933

To disable user's access only to certain resources or operations, edit the User Permissions Table specify a None permission level for necessary contexts.

and

3.3.8 Users in Distributed Architecture

This section describes specifics of users behavior in a distributed installation
99

of AggreGate.

If a user account from a provider server is connected to a context tree on a consumer server, the user account itself and all resources owned by the user become available for users of the consumer server. However, users of the provider server cannot login to the consumer server using their login credentials. If consumer server users access resources of a connected provider server's user account, their effective permission level 932 for a certain provider server's resource is defined by: The provider-server-side permission level of a user the consumer server as logged in as The consumer-server-side permission level of a user that performs the operation See permissions in distributed environment
103

for more information.

2000-2013 Tibbo Technology Inc.

AggreGate Server

113

3.4 Devices
A device is any electronic equipment or other data source configured and controlled by Tibbo AggreGate. The "representation" of device within AggreGate Server is called Device Account . AggreGate Server works with different types of Devices using Device Drivers 129 . These drivers know how to "talk" to a certain device using its native protocol. Every Device Driver provide a normalized representation of one or more Device as Contexts 863 . This normalization process involves several steps: Creation of one Device Context
677

per every Device that works with AggreGate.

869 . 892

Conversion of Device internal settings and configuration options into context Variables (Properties) Conversion of control operations supported by the Device into context Functions helping to execute these functions interactively (Call Function 903 actions). Conversion of events generated by Device into context Events
880 . 878

and corresponding Actions

All these operations help to provide unified methods of Device configuration, control and monitoring within AggreGate infrastructure. When a Device is represented as a context with variables, functions, and events, you can use all of AggreGate's management and monitoring features (Alerts 216 , Reports 241 , Widgets 312 etc.) to work with it.

Administering Devices
Two contexts 863 are used to administer Devices: One is the general Devices 675 context that acts as a container of all Device or a single user 108 . The other is the Device 677 context, corresponding to a single Device. There are two additional contexts related to Devices: All Devices context under the User 759 context and All Devices under the Root 726 context. These contexts provide access to grouped actions 894 for all Devices belonging to a particular user account 108 , and all Devices in the system, respectively. Related tutorials: Creating a Widget to Monitor a Device
1217 1233

Creating a Dashboard to Monitor Your Devices in Real-Time Monitoring Device Parameters Using a Chart 1239 Building a Device Status Report 1250 Adding Custom Properties
1258 1269

Scheduling Device Downtime

3.4.1 Device Metadata

Every Device provides some or all of the following data objects: Device settings
114

that are available in the form of Device context variables

869 . 892

Device operations 120 available as functions 878 of Device context. AggreGate Server also creates one action every device operation for convenient interactive or non-interactive execution of them. Device events Device assets
121 113

per

, i.e. events

880

of Device context.

for building logically grouping settings, operations and events into hierarchical group tree.

The unified name of these objects is device metadata. The metadata is retrieved from a device during a full synchronization 126 .

3.4.2 Device Assets

Modern devices provide hundreds or even thousands of settings, operations and events. Such a large number of resources requires some kind of grouping for convenient management. In AggreGate, groups of device resources are called Device Assets. Assets are organized in a hierarchical tree-like structure. If a certain device driver 129 supports assets, it provides the list of root assets, each of them having a list of children assets. System operators may enable/disable assets so to ensure that only necessary device data is processed. Here are several examples of device assets:

2000-2013 Tibbo Technology Inc.

114

AggreGate Documentation

For SNMP 173 devices, an asset is a MIB file supported by device. Disabling it disables reading of all OIDs defined in the MIB file. Each asset of a WMI 186 device is a single WMI class. If the asset is enabled, system exposes properties/methods/ events of all instances of this class. For BACnet 133 devices, root assets represent BACnet object types, while child assets match object instances. Thus, it's possible to disable processing of both whole object types and individual instances. Every group of OPC Server
168

properties is represented by a separate asset. Child assets are property subgroups.

Managing Device Assets

There are two ways to enable/disable device assets: The asset list may be initially edited during device account creation
121 677

Assets of existing device accounts may be managed via Edit Device Properties

action

Re-reading Device Assets

Normallt, the list of device assets is read from hardware only once during device account creation and cached on the server. It's not re-read even during full synchronization cycles 126 in order to maximize system performance. To force re-reading information about device assets (e.g. after device reconfiguration) use Reset Device Driver 678 action. If the Metadata Reading Mode synchronization cycle.
124

property of device account is set to Read all , the assets are re-read on every

3.4.3 Device Variables (Settings)

Device variables (also called device setting variables or device settings ) are variables mapped to settings of the hardware device by the corresponding device driver 129 .
869

of a device context that are

It's important to discern device setting variables from variables of a device context that match configuration properties of the device account, such as device IP address and port number. Device setting variables are read/written from/to the actual hardware device or data source, while account property variables just define server-side device communication parameters. Device setting variables some peculiarities: During initial device synchronization 126 server creates a device snapshot 115 , i.e. server-side settings cache that contains most recent values of device settings received from the hardware device or data source. Each device setting variable may have custom synchronization (polling) period, history storage duration, and other per-setting synchronization options 115 . Each device setting variable has an associated synchronization status aggregated synchronization status of the whole device account 128 .
117 .

Those synchronization statuses define the

Once a device setting variable is read by any system module or an external application, its value is retrieved from the server-side device settings cache 115 and returned. No device I/O is performed unless the setting uses direct synchronization mode 115 . Once a device setting variable is written any system module or an external application, new value is written to the server-side device settings cache and a partial synchronization 127 is requested. No synchronous device I/O is performed. In addition to configuring database 80 storage period for "raw" historical values of device setting variables, it's possible to create statistical channels 117 for aggregating them in a round-robin database to ensure compact storage and fast access. Examples of device settings: "Temperature" read-only setting of thermometer supporting Modbus TCP protocol. Tabular read-only setting of an SNMP-capable network host that represents the table of device's network interfaces. Writable "Orientation" setting of an access control terminal. The setting could be set to "Desktop" or "Wall mount".

2000-2013 Tibbo Technology Inc.

AggreGate Server

115

3.4.3.1 Device Snapshots (Settings Cache)

When AggreGate Server first reads values of Device internal settings, it stores these values in the database. This is called creating device snapshot or settings cache. Users can then view and edit settings for any Device, even if it is not currently connected to the AggreGate Server.

NEW TERM: A Device Setting Variable is a variable of a Device context

Device setting.

677

that corresponds to a cached

NEW TERM: A cache is a collection of data duplicating original values stored elsewhere or computed earlier.
A cache is used when the original data is expensive (usually in terms of access time) to fetch or compute, while reading the cache is "cheap" (i.e, easy and quick). When you're viewing or editing Device settings, you're actually working with the server's cache. There is no way to edit the actual Device settings directly. New settings are written to the Device on synchronization. The Settings Cache is periodically synchronized
126

with the Device. Synchronization occurs in the following cases:

When a Device connects to the AggreGate Server; When setting values are changed in the cache (using AggreGate Client for example) while a Device is connected to the server; Periodically, as defined by the Synchronization Period
123

setting.

Every setting is synchronized according to the following algorithm: If the setting value does not exist in the server cache, it is cached (i.e. its value is read from the Device and stored in the server cache); If the setting value in the server cache was changed later than in the Device, the cached value is written to the Device; If the setting value in the Device was changed later than in the server cache, the cached value is replaced by the current value of the Device setting; Otherwise, no action is performed.

3.4.3.2 Settings Synchronization Options

It is possible to define custom synchronization options for every settings of Device. Access to per-setting synchronization options is provided by Edit Device Settings 677 action of Device context. Here is a list of synchronization options available for each Device setting: Option Description

Synchronization Mode There are several synchronization modes available: Normal Synchronization . Value of setting is synchronized between AggreGate Server and Device during every synchronization cycle. Synchronization Disabled. No synchronization is performed for this setting.

Device to Server Only . Forces the server to make server-side value read-only and disable device write operations for this setting. This is useful when a device/driver report setting as writable, but the actual write operations fail (e.g. due to insufficient permissions). Direct Device Access . Value of setting is read directly from Device when it is requested by system components. If some system component tries to modify system values, changes are also written directly to the Device. With this setting, read/write operations may fail if Device I/O fails or Device returns an error. Direct Device Writes. Same as above, but applies only to write operations. Value reading is performed from the settings cache 115 , same as in Normal Synchronization mode. Use Server-Side Master Value. In this mode server-to-device synchronization is always performed for this setting. Data contained in common table specified by Master Value setting (see below) is used instead of Device-level cached value. More information is available here 262 .

2000-2013 Tibbo Technology Inc.

116

AggreGate Documentation

Ignore Modification Time. Ignores both server-side and device-side setting modifications timestamps. Setting is synchronized from server to device if value was changed on the server and from device to server otherwise. Custom . Uses a custom synchronization handler provided by the system, if any. This mode is usually enabled automatically by the system if custom handler is available, but may be overridden by a human. Update History Storage Time If this option is set to a non-zero value (i.e. update history saving is enabled) a persistent Updated 890 event will be generated every time when setting value is modified in the server cache. This may happen if new value differing from the previous one is read from remote device or some system component modifies the cache. Updated event contains value of the variable, so its history 882 may be used as a source data for reports 241 and charts 384 . Saving of history is disabled by default to prevent avalanche-like increase of database size. If set to Changes if value read from value. All Values synchronization of Only (-1), historical value is saved (and Updated event is generated) only a device during current synchronization differs from the previous (cached) (0) option causes a historical value to be stored during every the Device setting.

History Rate

If set to any positive integer number, historical values will be saved to database only every Nth synchronization cycle, where N is value of History Rate. However, Update events are generated on every synchronization cycle and interested parties will be notified about all value changes. This option may also affect collection of statistics 936 . If Changes Only mode is active or rate is set to a high value, the statistical channel will receive few data items, and it can mark certain aggregation periods (hours, days, etc.) as "data unavailable". If Update History Storage Time is not set (i.e. history is not stored), the synchronization period is rather short and the setting itself has complex format (e.g. many fields or nested tables), setting History Mode to All Values may improve performance, since server won't load old cached value and compare it with a new one during every synchronization. Custom Synchronization Period Filter This option may be used to define a custom synchronization period for a certain setting. Default value is NULL (<Not set>), so setting value is synchronized during the full synchronization cycle. Custom period is useful when it's necessary to read some fast-changing data from the Device. If this filter expression device and server:
911

is defined, it will be used to filter out values coming from both

If value is being synchronized from device to server and filter expression returns FALSE, value won't be written into server cache 115 . This helps to treat some device-provided values as "bad" and drop them out. If value is being changed by system operator, server component or external system and filter expression returns FALSE, the change request fails with an error. Filter Expression Evaluation Environment

Filter Expression Resolution Environment Default Context

927

922

Context of current device.

Default Data Table

927

Current value, either taken from device or provided by system operator, server module or external system.

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

2000-2013 Tibbo Technology Inc.

AggreGate Server

117

Example: abs({.:temperature$celsius} - {celsius}) > 0.5 This filter expression compares celsius temperature retrieved during previus synchronization with the new value just received from a device. The synchronization is performed only if their difference exceeds 0.5 degrees, allowing to avoid chattering of server-side value. Master Value Common table
260

that is used as a master value for this setting.

681

These may be accessed via the settingSyncOptions

variable.

3.4.3.3 Settings Synchronization Status

Every setting value in the server cache is contained in a variable 869 in the server context 863 corresponding to the Device. When settings are being viewed or edited (e.g, using the Properties Editor 795 of AggreGate Client), the Synchronization Status of every setting appears by the setting description.

AVAILABLE SYNCHRONIZATION STATUSES

Synchronization Status takes on the following values:

Ico n

Status Synchronized from Device to Server

Description Indicates that value was arrived from a Device and stored in the server cache.

Synchronized from Server Indicates that value was changed in the server cache and written to the Device. to Device Waiting for Synchronization Synchronization Error Synchronization Disabled Direct Device Access Indicates that the value in the server cache was changed since last synchronization but was not written to Device yet. Indicates that an error has occurred when synchronization was last attempted for this setting. Synchronization Mode
115

is set to Synchronization

Disabled for this setting.

Synchronization Mode is set to Direct Device Access for this setting.

3.4.3.4 Device Setting Statistics

AggreGate Server allows to create statistical channels 936 for device setting variables. Statistical channels keep longterm aggregated history for numeric values such as traffic, power consumption, voltage, noise levels, temperature, people counters, and whatever else.

Managing Channels

2000-2013 Tibbo Technology Inc.

118

AggreGate Documentation
677

The device's statistical channels may be managed using Edit Device Properties Statistics ( ) table containing channel definitions. Each definition comprise:

action. It provides access to

Channel Name. This is a unique ID of the channel that is used to refer it, e.g. when building charts

384 .

Variable. Name of variable 869 the channel is based on. Simply speaking, AggreGate Server generates a new Primary Data Point 945 for the channel each time this variable is changed. Enabled. Controls whether the channel is active and collects data. Default channels should be disabled instead of deleting them in order to prevent their re-creation. Properties. These are parameters
938

of statistical data collection, storage and processing.

Here is how channel list looks like in AggreGate Client:

Viewing Brief Statistics

To view brief statistics for all channels, run View Status 910 ( ) action and switch to Statistics tab. Note, that only channels with Show In Statistics option enabled will be visible. Here is how brief channel statistics look like in AggreGate Client:

If channel is using keys its brief statistics:

942 ,

the Dataset summary dialog will be shown first, allowing to select a Dataset (key) to view

2000-2013 Tibbo Technology Inc.

AggreGate Server

119

Viewing Detailed Statistics

To view detailed channel statistics, launch Configure Device View Statistics (
677

) action, right-click on a variable (setting) and select

). The list of channels associated with the variable will pop up first:

Select a channel to view the list of enabled Archives

937 :

And finally, select an Archive to view its detailed statistics grouped by time periods:

2000-2013 Tibbo Technology Inc.

120

AggreGate Documentation

An alternative way of viewing device setting statistics is using global View Statistics

729

action.

Global Channels
Global server configuration defines the list of default statistical channels 73 that are applied for newly created devices. Each global channel configuration includes name of variable. If a new device has variable with such name, a new channel is created to store variable's value for this device. Channel properties are copied from the default channel definition and may be fine-tuned manually later on.

3.4.3.5 Master Values of Device Settings

It is possible to set up master values for Device settings. Master values are stored in the form of Common Data 260 tables instead of the normal server cache. Every common table contains the value for a single Device setting, so the values of simple settings such as String or Number are stored in a table containing just one column and one row. When synchronizing a Device with the server, the AggreGate Server tries to detect if there are common tables containing setting values. If Global Common Data contains a table with the same name as the setting name, the value of the setting (from the common table) will be written to all Devices in the system which have settings with this name. If the common table is found in User Common Data, its contents will be used for all Devices under the user's account (which have a setting by this name). If the server finds that some setting should be synchronized using a common table, synchronization is always performed from AggreGate Server to the Device. The contents of a common table are never overridden or modified according to the value of a Device setting. If a setting is synchronized using a common table, you can't view or change its value using a Configure Device action. Instead of its value, you'll see a read-only string, like Using Common Table XXX contained in YYY:

See Master Properties of Devices

262

in Common Data

260

for more information.

3.4.4 Device Functions (Operations)

Device functions (also called device operation functions or device operations) are functions execution if bridged to the actual hardware device by the corresponding device driver 129 .
878

of a device context those

Once a system module or an external application requests a device function (operation) execution, the driver takes

2000-2013 Tibbo Technology Inc.

AggreGate Server

121

function input, converts it to device's native format and sends to the hardware device with a request to execute the operation. Once the operation is complete, the driver converts device-provided reply into function output and returns this output back to the calling side. Examples of device operations: "Open door" operation of an access control terminal that activates a door relay. "Perform garbage collection" operation of a Java application connected to AggreGate using JMX protocol. "Schedule self-test" operation of a vehicle control terminal. This operation may accept a "self-test time" parameter and return a tabular test report if self-test time was set to "now".

3.4.5 Device Events

Device events are events 880 of a device context that are generated by the corresponding device driver corresponding asynchronous messages are received from the actual hardware device or data source. Examples of device events: "Card read" operation of an access control terminal. An event instance contains ID of the read RFID card. "Pressure threshold exceeded" event of a controller performing validation of pressure readings against setpoints. "Cabinet door tamper" event of a large container-based industrial device equipped with own security sensors.
129

once

3.4.6 Adding New Devices

New device is connected to the system using Add Device Driver 129 :
675

action of Devices Context. At first step, select Device

Now you need to enter unique Name and Description for Device Account and specify connection parameters:

2000-2013 Tibbo Technology Inc.

122

AggreGate Documentation

Click OK to test connection with the device. If connection cannot be established, you'll see the error dialog:

In case of error the system will allow to correct connection parameters and retry connecting. To skip connection testing and force account creation, just click on Cancel when connection properties dialog is shown for the second time. You will be able to correct connection parameters later. Once connection with device is established, the system reads definitions of assets several seconds. provided by device. It may take

113

If asset selection is not supported by device driver, this step will be skipped.

When asset reading is finished, the system shows device asset tree to the operator, allowing to select which assets will be controlled by AggreGate:

2000-2013 Tibbo Technology Inc.

AggreGate Server

123

Click OK in the asset selector to save your choice and finish device creation. After the end of creation process new Device Context 677 representing this device in the system will be created. Here is how it looks like in System Tree 784 of AggreGate Client:

Now you will be prompted to specify synchronization device properties dialog and finish registration.

properties and other device

parameters . Click OK to close

Once account registration is over, the device will be synchronized 126 with the server. After first full synchronization all device settings, operations and events will be cached 115 and made available for other system facilities, such as alerts or widgets. Device will switch into Online, Synchronized status
127 ,

indicated by a green tick icon:

3.4.7 Generic Device Properties

Some settings are common to Devices of different types. They can be accessed by the Edit Connection Properties action of any Device context.
677

Field Description
Device Name. Name of the device context 677 , required to refer to this Device from other parts of the system. It should satisfy the context naming conventions 863 . Device Description. Textual description of the Device. It may indicate Device type, location, purpose or other important characteristics. Device Type . Type of the Device. In most cases the type is auto-detected, but sometimes it may be necessary to specify it manually to enable proper processing of device data. Generic device type instructs AggreGate Server that no special processing of device data or custom communication activities are necessary. Synchronization Period. This setting defines how often full Device synchronization the server is performed. However, individual Device settings may have custom synchronization period defined by Device Settings Synchronization Options 115 .
126

Field Name
name

description

type

with

syncPeriod

2000-2013 Tibbo Technology Inc.

124

AggreGate Documentation

Interrupt Synchronization And Reconnect On Error. Causes the synchronization process to stop if an error occurs during the synchronization of any setting. This also forces AggreGate Server to disconnect from the device and reconnect before the next synchronization. Enabling this option may be very useful when I/O or device error during synchronization of one setting will most likely repeat during synchronization of the the remaining settings. Suspend Device. Suspended Devices are never synchronized with the server. Enable Extended Status. Enables/disables extended device synchronization status
128 .

interruptOnError

suspend extendedStatus timeZone

Time Zone. Time zone the Device is located in. May be used by device driver for timestamp conversions, e.g. when synchronizing device internal clock with the server. Metadata Reading Mode. Defines when the server should read definitions of device settings, operations, events and assets. There are three modes: Do not read. All definitions are read just once, after the connection of the device. This mode is suitable for improving performance if the definitions of already-connected devices never change. Read definitions of settings, operations and events. This is a default mode that is suitable for most cases. Server re-reads all metadata except for assets on every synchronization cycle, reflecting changes found in the device. Asset 113 definitions are not read. Read all . In this mode, server will read full device metadata, including assets 113 , on every synchronization cycle. This mode is suitable if assets of the connected device may change at any time. This may slow down the performance if device has large number of assets. Settings Cache Mode. Defines the location of settings cache In the database
80 115 :

metadata

cache

(default mode, settings will be available right after server restart)

In memory (settings will not be available after server restart until the end of first device synchronization 126 ) Device Dependency Expression. This expression 911 is evaluated before every synchronization 126 . If evaluation result is false , synchronization is not performed. dependency

Dependency Expression Resolution Environment Default Context

927

922

Context of current device.

Default Data Table

927

None.

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

It's a common practice to make device dependency expression referring to the online status of some other Device. For example, in a network management system it may be useful to disable synchronization for a group of devices that are connected to AggreGate Server through a router if the router itself is offline (i.e. not accessible). In this case, the following dependency expression may be used for each of these devices:

{users.admin.device.router:status$connectionStatus} == 0
It's possible to find out the numeric value of the Offline connection status (zero above) by browsing the selection values in the variable information for the status 682 variable of a Device context.

2000-2013 Tibbo Technology Inc.

AggreGate Server

125

Status Expression. The expression is recalculated in the end of every synchronization 126 cycle. It should return textual description of current device status. This status can be displayed on device maps 616 , dashboards 617 , etc. To see the resulting status, check Status 682 variable of Device context.

status

Status Expression Resolution Environment Default Context

927

922

Context of current device.

Default Data Table

927

None.

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

Color Expression . The expression is recalculated in the end of every synchronization 126 cycle. It should return result of Color type. This color will be used to color-code the device on device maps 616 , dashboards 617 , etc. To see the resulting color, check Status 682 variable of Device context.

color

Color Expression Resolution Environment Default Context

927

922

Context of current device.

Default Data Table

927

None.

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

Latitude Expression. See Device Location Tracking

128

for details.

latitude

Latitude Expression Resolution Environment Default Context

927

922

Context of current device.

Default Data Table

927

None.

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

2000-2013 Tibbo Technology Inc.

126

AggreGate Documentation

Longitude Expression. See Device Location Tracking

128

for details.

longitude

Longitude Expression Resolution Environment Default Context

927

922

Context of current device.

Default Data Table

927

None.

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

Location History Storage Period . Defines how long to keep the history of latitude/ longitude changes. Enable Offline Alert. Flag that controls whether or not a Device Offline alert generated if the Device stays in disconnected state for some time. These may be accessed via the genericProperties
680 217

locationStoragePerio d offlineAlert

will be

variable.

3.4.8 Synchronization
Device Synchronization is a periodic process allowing AggreGate Server to create and maintain a server-side Device "image" by reading Device metadata and reading/writing Device settings. Synchronization helps the following: Allow internal modules, operators and third-party systems to browse available device settings, operations and events; Enable quick access and manipulation of Device settings values. All changes to the device configuration are stored in the server-side cache 115 and written to the device on the "best effort" basis. The actual algorithm of synchronization depends on the Device driver primary steps: Establishing a connection between AggreGate Server and Device; Reading Device metadata , i.e. information about available settings, operations and events and creating appropriate variables, functions and events in Device Context 677 to access them; Synchronizing setting values between Device and server cache
115 . 129

type, but in most cases it includes three

Viewing Synchronization Status

Device synchronization status is reflected by device icon: Newly added devices that didn't synchronize yet or are currently synchronizing have question mark icons:

Fully synchronized devices that doesn't have any synchronization troubles have checkmark icons: Devices with server-side configuration changes that are pending to get written into hardware have clock icons:

Devices with synchronization errors have exclamation mark icons:

VIEWING SYNCHRONIZATION PROGRESS

2000-2013 Tibbo Technology Inc.

AggreGate Server

127

If Extended Device Status 124 setting of device account is enabled or current synchronization was explicitly requested by a system operator, device status 128 icon will show the progress of current synchronization: Connection stage is indicated by lightning icons: Metadata reading stage is indicated by looking glass icons: Setting values synchronization stage is indicated by arrow icons:

Enable Extended Device Status if you have trouble detecting current state of your device

Synchronization Types
There are three types of synchronization:

FULL SYNCHRONIZATION

This is the "standard" type of synchronization, and it includes all three steps:
Connection (only if connection isn't yet established) Device metadata acquisition Reading/writing device settings Full synchronization is performed once per device Synchronization Period
123 .

PARTIAL SYNCHRONIZATION
Partial synchronization is performed for reading/writing device settings that have Custom Synchronization Period 116 . This type of synchronization is pretty fast since is doesn't include connection (if it's already established), metadata acquisition, and reading/writing values of all device settings. Just one setting is read from or written to the device.

Partial synchronization occurs every time Custom the Synchronization Period of a certain setting elapses.
CONNECT-ONLY SYNCHRONIZATION
Connect-only synchronization forces the server to establish a connection to the device and pass authentication/ authorization. No data is usually read from or written to the device. Such synchronization helps the server to detect device connection status
127 .

This type of synchronization is performed only at server startup, and only if time passed since previous full synchronization doesn't exceed the Synchronization Period 123 .

3.4.9 Device Status

Device status may be viewed using View Status Connection between server and Device Result of the last synchronization
126 910

action of Device context

677 .

It includes information about:

and/or progress of the ongoing one

Custom textual and color statuses (calculated according to Status Expression and Color Expression settings of device account 123 ) A combination of current connection and synchronization status is represented by Device Context state icon).
678

(context

Connection Status
Connection status indicates the whether AggreGate Server is able to communicate with the Device. Connection statuses: Unknown. Connection has not yet been tested since device account creation or server startup. Online. Connection between AggreGate Server and Device is established.

2000-2013 Tibbo Technology Inc.

128

AggreGate Documentation
882

Offline. There is no connection between AggreGate Server and Device. Check event history of connection failure. Suspended. Device is suspended by server-side configuration or dependency attempts are performed.
124

to find out the cause

check failed. No connection

Synchronization Status
Synchronization status shows: Overall result of last synchronization. Progress of current synchronization, if Extended Status is enabled in Device Generic Properties Synchronization statuses: Synchronized. Waiting for synchronization . Synchronization Error.
123 .

Not synchronized or synchronization in progress. Extended synchronization statuses: Connecting. AggreGate Server is attempting to connect to Device. Reading Metadata. AggreGate Server is reading information about device settings, operations and events. Synchronizing Settings. AggreGate Server is synchronizing setting values between Device and server cache
115 .

Settings Synchronization Status

This table reports synchronization status for every device setting variable. In includes the following for every variable:

Date/time of last synchronization. I/O duration for last synchronization, i.e. time elapsed by device driver for reading/writing settings value from the hardware. Updated on Server flag that is true if setting value was updated in the server cache and new value is not yet written to the hardware. Textual description of current setting synchronization status.

3.4.10 Device Location Tracking

AggreGate Server device accounts provide a generic way to obtain, store and process geographical locations of physical devices. Location information can be dynamically updated by polling the device or manually specified inside the device account. The account can also keep track of position history. The actual positions of devices and their historical tracks can be displayed on maps and satellite images. For example, Map 364 widget component provides an extremely easy way to track devices on Google Maps.

Calculating Device Location

Each device account has two special settings: Latitude Expression Longitude Expression These expressions can be specified by editing generic device properties 123 . Each expression is recalculated in the end of every synchronization cycle. It should return a floating point number representing current device latitude/longitude. Normally, these expressions calculate the coordinates by performing some mathematical operations over device settings that contain information about latitude and longitude. For example, it's quite easy to convert value stores in degrees, minutes and seconds to a floating point value using an expression.

2000-2013 Tibbo Technology Inc.

AggreGate Server

129

To manually specify device position, write Latitude Expression and Longitude Expression that return floating point constants, e.g. 12.4459.

Viewing Device Location

Most AggreGate facilities, such as Map widget component, obtain location information automatically once correct Latitude Expression and Longitude Expression are defined. Numeric values of current latitude and longitude are available via Location 683 variable of Device context.

3.4.11 Device Performance

Since devices are key components of AggreGate Server, they often have decisive influence to the performance of the whole server. Performance of each particular device is a multiplication of the following factors: Performance of the underlying device driver drivers. Number of device settings device account).
114 129 .

This might be especially important in case of customer-written device

116

and their custom synchronization period

(or global synchronization period

80

123

of the

Device settings history storage period and rate in combination with performance of the server database Number and complexity of statistical channels based on device variables The frequency of device operation
120 117 .

calls by other system modules and external applications.

Number of events received from the device and stored in the server database, as well as complexity of their processing chains (such as model rules 305 processing triggered by these events).

3.5 Device Drivers

Device Driver is a special type of plugin 950 that defines how AggreGate Server interacts with a certain type of hardware devices. The driver is specified during creation of a Device account 113 . Tibbo regularly creates new AggreGate Server device drivers for different types of hardware devices and protocols. Please, check AggreGate website for the most recent list of available device drivers.

See Device Server Plugins 1009 for the list of drivers processing Device Server data streams.

See Driver Development Kit

963

for details on creating new drivers.

Driver Reference

The subsections of current section are devoted to different device drivers that are bundled w AggreGate core and diverse vertical market solutions.
Description of every driver includes the following: Section Driver Information Global Settings Notes Driver details, such as driver plugin ID, etc. Global configuration
130

of driver plugin.
130

User-level Settings User-level configuration Device Properties Device Assets Device Settings

of driver plugin.

Device-level configuration 130 of driver plugin. This includes connection settings, manually configured definitions of device resources, etc. Description of method used by the driver to define device assets
113 .

Description of method used by the driver to create variables corresponding to the hardware

2000-2013 Tibbo Technology Inc.

130

AggreGate Documentation

device's settings. Device Operations Device Events Description of method used by the driver to create functions/actions corresponding to the hardware device's operations. Description of method used by the driver to create event definitions corresponding to the types of events provided by hardware device. This sections also illustrates how and when are the event instances received from the hardware and converted into AggreGate events. Details on how and when the driver switches the device between Online and Offline status Any information on the driver-specific peculiarities of Device synchronization process
126 . 127 .

Connection Handling Synchronization Details

Setting Levels
Every driver has up to three levels of settings: Global Settings. These affect the default behaviour of drivers. Global settings may be edited only by users with sufficient permissions. User-level Settings . These affect the behaviour of a driver only if it is assigned to a Device that belongs to a certain user account 108 . When the driver is communicating with a certain Device, it uses the user-level settings stored in the Device owner's account. Device-level Settings (Device Properties). These settings define how the device driver connects to the Device, communicates with it, and processes Device data. Many drivers do not use all three setting levels.

Administering Device Drivers

Two context types are used to administer Device Drivers: first is the general Drivers/ Plugins Configuration 685 context, which serves as a container. The other is the Driver/ Plugin Configuration 686 context, which holds the configuration for a single driver. These appear in two places: Under the Root Under the User
726 759

context, where they contain global settings context, where they contain user-level settings

If a given driver doesn't contain settings on one of these levels, the corresponding Device Driver Configuration context will not be created (i.e, won't exist in the System Tree). Device Level settings for a driver may be accessed using the Edit Device Properties action of a Device 677 context.
677

3.5.1 AggreGate Agent

AggreGate Agent device driver is a Device Driver 129 that allows AggreGate Server to interact with Agent 848 . Technically, Agent is a BASIC application that creates and maintains a Context Tree 863 with a node for each physical Device 113 (piece of hardware) connected to it. Actually, a Device may also be implemented by custom code that is a part of Agent. The variables 869 of each Device context correspond to the Device's settings. Each such context also has functions 878 which let you perform some operations with the Device, and events 869 which are used to monitor the Device's state and changes in its operating conditions. AggreGate Server uses the AggreGate Communications Protocol 1303 to communicate with Agent.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.agent

Global Settings
Port number to listen for Agents. Incoming connections from Agents will be accepted on this port. Command Timeout. Timeout for commands sent using AggreGate communication protocol. Broadcast Command Timeout . Timeout for commands sent via broadcast during Agents discovery. Automatically register device accounts for new Agents . Allows Agents to tell their passwords to AggreGate

2000-2013 Tibbo Technology Inc.

AggreGate Server
Server, and forces the server to auto-register Agent accounts if new Agents try to connect.

131

User Level Settings

None defined.

Device Properties
Password. Agent's password.

Connection Handling
This driver makes the device Online if: An Agent is currently connected to the server and passed login sequence Basic Agent operations has completed successfully

Synchronization Details
Agent driver performs synchronization following algorithm:
126

of AggreGate Server and Devices provided by Agent according to the

1. Reads the list of available contexts and their parent-child relationship from the Agent. 2. Creates a server context for every context found in Agent. This context allows AggreGate users to interact with Agent directly or through a variable cache 115 . 3. Synchronizing Agent's internal real-time clock with the time on the server. Time is converted to the time zone specified for the Device. 4. Reads definitions of variables, functions and events from every context available in Agent. It doesn't read the values contained within these Data Tables yet -- just their format. More about variable definitions here 870 . 5. Finds common tables settings).
120

that may be used as a "master values" for variables found in Agent (such as Device

6. Creates a property cache 115 (if this is the first time this Device is connecting) or updates it according to variable definitions read on the previous step. Only variables that belong to the group 870 named default are synchronized with the server and available for editing by users. The property cache is created only in server contexts corresponding to Device contexts in Agent. Variables corresponding to internal Agent settings are modified by the server directly, without a cache. 7. Sets up a Configure Device
677

action in every context corresponding to a Device context in Agent.

8. Creates an appropriate action 892 for every Device context function within the default group. Such an action allows users to call the Agent function, specify its parameters and view its output. 9. Sets up a Monitor Related Events action in every context corresponding to a Device context in Agent to show all events arriving from Agent which belong to the default group. 10. Synchronizes variable values between the server cache and Agent for every context corresponding to a Device context in Agent. The exact structure of communications between Agent and AggreGate Server during synchronization is described under Communications Between Agent and AggreGate Server 853 .

Additional Actions of Agent's Devices Context

Devices Context 675 provided by Agent can have several additional actions 892 . Most of them are defined by a custom Agent BASIC application. For example, if Agent works with some sensors of terminals that are connected to its serial ports, there may be a Detect Devices action causing Agent to rescan its serial ports, find out which devices are currently connected and update list of provided Device Contexts 677 . There are two additional actions of Devices Context that are always provided by Agent:

CONFIGURE AGENT
This Configure 904 action is used to configure Agent itself, i.e. set parameters of defining how Agent communicates with hardware devices connected to it, how it converts the native protocol of these devices to AggreGate Communications Protocol 1303 and what variables, functions and events are provided by Agent in Device contexts 677 corresponding to these devices.

2000-2013 Tibbo Technology Inc.

132

AggreGate Documentation

REBOOT AGENT
This action reboots programmable module that runs the Agent BASIC application. Technically, this is a Call Function action that calls reboot function from Agent's root context.
903

Agent Discovery
Agent Discovery is the process of locating all hardware Agents in the local network segment and automatically creating Discovered Agent Accounts for them. A local network segment means there are only network hubs (no routers, bridges, firewalls, etc.) between the PC and all other devices on that segment. Hardware Agents which are located behind a router (i.e, you have the computer running AggreGate Server, and to actually get to the Agent its packets need to go via a router) cannot be auto-discovered by AggreGate Server because the broadcast UDP datagrams used to find them on the network are not forwarded by the router. However, it is still sometimes possible to connect such Agents to the AggreGate Server, if they can be accessed by their IP addresses (in other words, if there is a network path to them). Each discovered Agent is uniquely identified by its MAC-address. Discovery will detect all local Agents even if some of them have the same IP-address or an IP-address which is invalid or unreachable. A correctly configured IP-address is not required for the AggreGate Server to be able to access Agents in the discovery mode. During the discovery process, AggreGate Server creates a new Discovered Agent context (account) for every Agent detected. All Discovered Agent contexts that were created during previous executions of discovery are destroyed before any new contexts are created. There's no way to "manually" create a Discovered Agent Account, only using the discovery process. If automatic discovery of Agents is not enabled and it was not launched manually, the Discovery context will not contain any Agent accounts. Discovery may be initiated by one of the two actions in Discovery context: Agents Discovery Agents Discovery and Auto-Connection

Connecting External Agents to the AggreGate Server

Connecting an Agent to AggreGate Server is the process of reconfiguring a hardware Agent to make it connect to the AggreGate Server immediately after startup. There are several ways to do this: 1. Connecting a previously discovered 1013 Agent using its account
1027 .

2. Automatically connecting all discovered Agents to AggreGate Server without user interaction. 3. Manually configuring discovered a Agent that was not successfully connected by the above functions. 4. Manually connecting a Agent that was not detected by the discovery process but may be accessed by AggreGate Server.

CONNECTING A PREVIOUSLY DISCOVERED AGENT TO AGGREGATE SERVER

This procedure is initiated by the Connect Agent to AggreGate Server action of the Discovered Agent context. The user must specify
896

several parameters before connection process is started:

Login Password. Required if a password is defined in the settings of the hardware Agent. This password will be used by AggreGate Server to access the settings of the hardware Agent. Owner Name. Name of the AggreGate Server user 108 who will own (or already owns) an Agent Account that will be used to authenticate this hardware Agent during its login to AggreGate Server. The "Owner name" setting of the hardware Agent will be set to this value. Device Name. Name of the above Device Account this value.
113 .

Device name setting of the hardware Agent will be set to

Force connection even if Agent is already configured for AggreGate Server or has incompatible firmware. By default, the connection procedure fails with an error message if the Agent is already configured to connect to the AggreGate Server or has an outdated firmware version (one that doesn't fully support automated configuration for AggreGate Server). This option disables checking of the Agent setting values and its version number. The forced connection operation will complete successfully, but Agent may not be able to actually connect to the AggreGate Server or log in. If the Agent does not login to the AggreGate Server within several seconds after the forced connection procedure has been completed, configure the Agent manually (depending on the device type, this can be done using keypad/LCD or web interface).

2000-2013 Tibbo Technology Inc.

AggreGate Server

133

AUTOMATIC CONNECTION OF DISCOVERED AGENTS TO AGGREGATE SERVER

If discovery was started using Agents Discovery and Auto-Connection action, AggreGate Server automatically executes the Connect discovered Agent to the AggreGate Server 132 procedure for every Agent detected during the discovery 132 process. It is useful for quickly connecting multiple Agents that are plugged into the local network segment. Automatic connection fails if: The Agent requires a password to access its settings, or The Agent is already configured for connection with the AggreGate Server on startup, or The Agent's firmware does not support auto-connection.

3.5.2 BACnet
The BACnet Device Driver 129 allows AggreGate Server to communicate with devices supporting BACnet/IP Protocol. The BACnet is widely used in building automation and control systems for applications such as heating, ventilating, and air-conditioning control, lighting control, access control, and fire detection systems. The BACnet driver provides connectivity to equipment using the BACnet protocol over IP networks (often referred to as BACnet/IP or Annex J).

SUPPORTED OBJECT TYPES

The below list contains all BACnet object types that may be read, written and processed by AggreGate via BACnet driver. Analog Input Analog Output Analog Value Binary Input Binary Output Binary Value Calendar Command Device Event Enrollment File Group Loop Multi State Input Multi State Output Notification Class Program Schedule Averaging Multi State Value Trend Log Life Safety Point Life Safety Zone Accumulator Pulse Converter Event Log Trend Log Multiple Load Control Structured View Access Door

SUPPORTED SERVICES
The below list contains all BACnet services that may be accessed using the driver.

BACnet Service Who-Is ReadProperty ReadPropertyMultiple WriteProperty SubscribeCOV SubscribeCOVPropert y

BACnet Interoperability Building Block (BIBB) DM-DDB-A DS-RP-A DS-RPM-A DS-WP-A DS-COV-A DS-COVP-A

BACnet Interoperability Building Block (BIBB) describe the services supported by a BACnet device or application ( Annex K of BACnet specification).

SEGMENTATION SUPPORT

2000-2013 Tibbo Technology Inc.

134

AggreGate Documentation

The BACnet Device Driver 129 supports segmented requests and segmented responses. Both requests and responses support window sizes between 1 and 127 bytes.

Driver Information
Driver Plugin com.tibbo.linkserver.plugin.device.bacnet 129 ID:

Global Settings
To participate in a BACnet network, AggreGate Server emulates a BACnet device that communicates with other devices in the network. This device is called Local Device in terms of the driver. Global settings are used to set up this Local Device. Property Device ID Description The Device ID is used to uniquely identify Local BACnet device, it can be in the range of 0 to 4194304. There cannot be more than one device using the same Device ID in one network. Broadcast address mask for Who-Is request. The amount of time (in milliseconds) that the driver will wait for an I-Am response after sending a Who-Is service request. Specifies the local UDP port that the driver will bind to for all communications on the channel. The default setting is 47808 (0xBAC0). Typically, all BACnet/IP devices on an Ethernet network use the same port. This parameter specifies the time that the driver will wait for an expected response from the device before retrying or going on to the next request. The valid range is 100 to 9999 milliseconds. Stands for the same timeout as above, but for segmented requests. This parameter specifies the number of message segments that can be sent before a segment acknowledge message must be returned by the receiving party. The sender proposes a window size, and the receiver determines the actual size (which will be no larger than the proposed size). Thus, the driver will use this setting as the proposed window size for requests, and as the actual window size limit for responses from the device. Larger settings will likely increase performance on a reliable network, though smaller settings will allow communications problems to be detected earlier and corrected with fewer segments being resent. The valid range is 1 to 127. Specifies the number of times that the driver will retry a confirmed request before giving up. This parameter specifies the overall length or number of bytes of message segments that the driver will accept. The driver will attempt to read the maximum APDU length allowed by the target device on startup, and will use the smallest of the local or remote limits when sending requests. A smaller setting may be needed in order to accommodate the limitations of hardware between the driver and target device. Options include 50, 128, 206 (fits LonTalk frame), 480 (fits ARCNET frame), 1024, and 1476 (fits ISO 8803-3 frame). The largest value 1476 is generally the best choice. Limits the number of items that can be packed into Read Property Multiple requests. The actual number of items packed into a request can vary depending on how many items are due for reads or writes at a given time. Generally, the higher the value, the better the performance. For large requests or responses, however, performance gain may be diminished by message segmentation. Unfortunately, there are no general rules for determining the optimum setting. To refine a particular application, users should experiment with this setting. Devices that do not support read property multiple or write property multiple services should be set to 1. Same as above, but for devices with no transmit segmentation supported.

Broadcast Address Connection Timeout Port

Timeout

Segment Timeout Segment Window

Retries Max APDU Length Accepted

Max Read Multiple References Segmented

Max Read Multiple References Non Segmented

User Level Settings

None defined.

Device Properties

2000-2013 Tibbo Technology Inc.

AggreGate Server

135

CONNECTION SETTINGS
Connection settings define how AggreGate Server communicates with a certain BACnet device. The following connection properties are available:

Property Addressing Method

Description There are three ways to address a BACnet device: By address/port. In this case device Instance Number is detected by sending Who-Is request to specified address/port. By device instance number. In this case IP address and port of device with specified Instance Number is detected by sending a broadcast Who-Is request to an IP range specified by Broadcast Address global setting. Combined. May be used for communicating with devices that do not support Who-Is identification. In this case, both address/port and instance number must be specified.

IP Address or Host Name Port Instance number

Address of a BACnet device to connect to. An IP port of device to connect to. An identifier of a remote device.

Device Assets
The driver creates one root asset for every BACnet object type supported by the device. Each asset's children match to the individual instances of this object found in the device.

Device Settings
The BACnet Device Driver 129 creates one Device setting variable per every discovered property of every BACnet Device's object. The variables are divided into several groups. Properties of the Device Object are put in a Basic Properties group. All other settings are divided into groups by Object Type: Analog Input, Analog Output, etc. In every Object Type group, a new subgroup is created for every Object Instance if it has properties of corresponding type.

Device Operations
The BACnet Device Driver
129

context provides the following functions and actions:

SUBSCRIBE COV
This function allows to subscribe/unsubscribe from object's Change of Value (COV) notifications. COV facility allows the driver to receive notifications upon changes of remote BACnet object's property. If an object provides COV reporting, then changes of certain object's properties trigger sending COV notifications to subscribed clients. After successful subscription the Device Driver a COV notification.
129

will asynchronously update

device settings cache

115

upon receiving

There are some risks related to using COV subscriptions. These are problems intrinsic to event-based systems, such as unexpected link failure problems, lost subscriptions on device reset, etc. Critical data items should be periodically polled in addition to receiving their updates via COV notifications. Format of the function input parameters has the following fields: Name subscribe Type Boolea n Long Description Flag indicating whether subscription or unsubscription should be performed.

subscriberProces sIdentifier

It is a numeric "handle" meaningful to identify the subscription within the driver. Do not use the same process identifier for different subscriptions. The same identifier should be used later to unsubscribe from COV notifications.

2000-2013 Tibbo Technology Inc.

136

AggreGate Documentation

monitoredObjectI dentifier

DataTa ble

Holds the identifier of the object within the receiving device for which a subscription is desired. There are two fields: objectType instanceNumber

issueConfirmedN otifications lifetime

Boolea n Long

Defines whether the device should issue ConfirmedCOVNotifications or UnconfirmedCOVNotifications when changes occur. The desired lifetime of the subscription. A value of zero shall indicate an indefinite lifetime, meaning no automatic cancellation. A non-zero value indicates the period of time before the subscription will be automatically canceled.

The function has no output parameters. For more information about COV subscriptions see ALARM AND EVENT SERVICES: SubscribeCOV Service section of BACnet specification.

SUBSCRIBE COV PROPERTY

This function is similar to above, but it allows to subscribe for change notifications occurred to the properties of a particular object. Format of the function input parameters has the following fields: Name subscribe Type Boolea n Long Description Flag indicating whether subscription or unsubscription should be performed.

subscriberProcess Identifier

It is a numeric "handle" meaningful to identify the subscription within the driver. Do not use the same process identifier for different subscriptions. The same identifier should be used later to unsubscribe from COV notifications.

monitoredObjectI dentifier

DataTa ble

Holds the identifier of the object within the receiving device for which a subscription is desired. There are two fields: objectType instanceNumber

issueConfirmedNo tifications lifetime

Boolea n Long

Defines whether the device should issue ConfirmedCOVNotifications or UnconfirmedCOVNotifications when changes occur. The desired lifetime of the subscription. A value of zero shall indicate an indefinite lifetime, meaning no automatic cancellation. A non-zero value indicates the period of time before the subscription will be automatically canceled. Identifies the property whose changes should be tracked.

monitoredPropert yIdentifier covIncrement

Integer

Float

The minimum change in the monitored property that will cause a COVNotification to be issued by a BACnet device. This parameter is ignored if the BACnet type of the monitored property is not REAL.

The function has no output parameters.

READ PROPERTY
This function is used to request value of a single property of a certain BACnet Object. The function has the following input parameters: Name Type Description

2000-2013 Tibbo Technology Inc.

AggreGate Server

137

objectIdentifier

DataT able

Identifies the object whose property is to be read and returned in the response. There are two fields: objectType instanceNumber

propertyIdentifier

Intege r Long

Identifies the property to be read and returned by this service.

propertyArrayInde x

If the referred property is an array, this optional parameter indicates the array index. If it is omitted (i.e. NULL) the entire array should be read.

The function output is value of a referenced property. Its format depends on property type. You can use Read Property and Read Property Multiple functions to read proprietary propertyIdentifier parameter to desirable property index. properties. Simply set

READ PROPERTY MULTIPLE

This function is used to request values of one or multiple properties of one or multiple BACnet Objects . Format of the function input parameters (can have multiple records) has the following fields: Name objectIdentifier Type DataT able Description Identifies the object whose property is to be read and returned in the response. There are two fields: objectType instanceNumber propertyReference s DataT able The list of properties to read from the object, specified by two fields: propertyIdentifier propertyArrayIndex The special property identifiers ALL, REQUIRED, or OPTIONAL can also be used. The function output parameters format: Name objectIdentifier Type DataT able Description Object identifier, specified by: objectType instanceNumber results DataT able Read results for properties of the above object in the form of table with several fields: error (Boolean) propertyIdentifier (Integer) propertyArrayIndex (Integer) readResult (DataTable) readResult field contains property value or error text is error has occurred.

WRITE PROPERTY
The function is used to modify the value of a single property of a BACnet object. Format of the function input parameters:

2000-2013 Tibbo Technology Inc.

138

AggreGate Documentation

Name objectIdentifier

Type DataT able

Description Identifies the object whose property is to be read and returned in the response. There are two fields: objectType instanceNumber

propertyIdentifier

Integ er Long

Identifies the property to be read and returned by this service.

propertyArrayInd ex valueType

If the referred property is an array, this optional parameter indicates the array index.

String

BACnet value type. This parameter makes sense only in interactive function call mode. It is used to set the format for the parameter below. New property value.

value

DataT able Integ er

priority

An integer in the range 1-16, which indicates the priority assigned to this write operation. For more information about priorities see BACnet PROCEDURES: Command Prioritization section of BACnet specification.

The function has no output parameters.

Device Events
No events provided by the driver.

Connection Handling
This driver makes the device Online if: Local BACnet Device successfully created and initialized. A remote BACnet device identified itself during Who-Is/I-Am exchange (if Addressing Method device connection setting is not Combined). The following properties of the remote Device Object were successfully read: Max APDU Length Accepted, Segmentation Supported, Vendor Identifier (if Addressing Method device connection setting is Combined)

Synchronization Details
Synchronization between AggreGate Server and BACnet Device includes the following steps: Reading remote device's supported services and creating appropriate device operations. Recognizing all objects present in the remote device by reading Object List property of Device object of remote BACnet unit. Discovering properties of all found objects. The BACnet driver combines two strategies for discovering object properties: requesting the Object to return all its properties; reading every property defined in BACnet specification for the appropriate Object Type. The first strategy allows to discover proprietary object properties if a device has them, while the second one will discover only standard BACnet properties. Proprietary properties can be discovered during synchronization if a device supports special property identifier ALL in ReadPropertyMultiple service. All device settings have read/write access, but the device itself can restricts write access to them. In case of trying to

2000-2013 Tibbo Technology Inc.

AggreGate Server
set a write-protected variable, a Write Access Denied error will be generated by the device.

139

3.5.3 URL Monitor (HTTP)

HTTP Device Driver
129

allows AggreGate Server to monitor web servers and web pages (URLs).

A web server is a computer program that delivers (serves) content, such as web pages, using the Hypertext Transfer Protocol (HTTP), over the World Wide Web. HTTP driver provides monitoring of any web server (Apache, IIS, etc.) by checking whether a monitored device accepts HTTP(S) requests and responds with correct pages. The driver supports GET and POST requests, authorization and other options for HTTP(S) requests.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.http

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
CONNECTION PROPERTIES
Connection settings define how AggreGate Server communicates with a certain HTTP server. These settings can be accessed using Edit Device Properties 677 action of the Device Context. Here is a list of available connection properties: Setting Address Protocol Port URL Request Type Post Data Enable Authorization Username Password Use Client Certificates Keystore File Keystore Type Keystore Password Additional HTTP Headers Description IP address or host name of the HTTP server. HTTP or HTTP Secure (HTTPS). Port the HTTP server is running on. Path to a monitored resource located on the specified HTTP server. Two HTTP request methods are currently supported: GET and POST. Data to be submitted with POST request, in the string form. Enables realm authorization (if it's required). User name to be used for authorization. Password for authorization. Enables usage of client certificates to authenticate on the server if HTTPS protocol is used. Path to keystore file contaning the client certificates. This is a local filesystem path on the machine running AggreGate Server. Keystore file type: JKS or PKCS12. Password decrypting keystore file (optional). Additional information to be included in request header. Specified as a table with the following fields: Header Name Header Value Agent Timeout User agent string. HTTP server operations timeout.

2000-2013 Tibbo Technology Inc.

140

AggreGate Documentation

Device Settings
HTTP device driver creates the only Device setting variable indicating the result of HTTP request. This variable includes the following fields that may be analyzed using different AggreGate modules:

Property Successful Response Time, milliseconds Reply Code Headers Reply Error

Description Indicates that web server monitor had no error during last page read. Server response time. HTTP response code. HTTP response headers table. HTTP response body, i.e. web page contents. Error text, or NULL if request was successful (even if HTTP response code is not 200/OK).

Device Operations
Execute HTTP Request. This operations sends a raw HTTP GET or POST request to the device and returns the output. Input values include URL, request method, POST data and additional HTTP headers. Values returned are success flag, response time, HTTP reply code, headers, returned page text and error text.

Device Events
No events provided by the driver.

Connection Handling
HTTP device is deemed Online if no error occurred during connection and HTTP request execution, and valid HTTP response was obtained.

Synchronization Details
HTTP monitor connects to the IP host, sends an HTTP request built using provided configuration (port, URL, request type and data, HTTP headers, agent, timeout) and analyzes the response. If authentication is enabled in the settings and Basic Access Authentication is required to access a web page the driver also sends an authorization request.

3.5.4 JMX (Java Management Extensions)

The JMX Device Driver 129 allows AggreGate Server to communicate with Java-based applications and Application Servers using Java Management Extensions (JMX) protocol. Functionality provided by the driver: Discovery of MBeans provided by an MBean Server (JMX host). Creation of a Device context setting
142

per every avilable MBean attribute.

142

Creation of a Device context operation

per every operation provided by MBean.

142

Creation of a Device context event definition Execution of MBean queries.

per every notification type provided by MBean.

MBean Queries
MBean queries allow selecting multiple MBeans of the equal format. Each query results to a table that lists all properties of selected MBeans in its columns, one MBean instance per row.

MBEAN QUERY SYNTAX

An query text consists of two parts, the domain and the key properties, separated by the colon character (:). The domain is a string of characters not including the colon (:). It may include occurrences of the wildcard characters

2000-2013 Tibbo Technology Inc.

AggreGate Server

141

asterisk (*) or question mark (?). The asterisk matches any sequence of zero or more characters, while the question mark matches any single character. If the domain is empty, it will be replaced in certain cases by the default domain of the MBean server. The key properties are an unordered comma-separated set of keys and associated values. Each key is a nonempty string of characters which may not contain any of the characters comma (,), equals (=), colon, asterisk, or question mark. The same key may not occur twice in a given query. The key properties list may contain a single asterisk element (*) which means that MBeans selected by the query may contain any number of other (unspecified) properties. Example: java.lang:type=GarbageCollector,* This MBean query lists all MBeans in java.lang domain that have type property those value equals to GarbageCollector. Those MBeans may have any number of other properties with any values. Each value associated with a key is a string of characters that is either unquoted or quoted. An unquoted value is a possibly empty string of characters which may not contain any of the characters comma, equals, colon, quote, asterisk, or question mark. A quoted value consists of a quote ("), followed by a possibly empty string of characters, followed by another quote. Within the string of characters, the backslash (\) has a special meaning. It must be followed by one of the following characters: o Another backslash. The second backslash has no special meaning and the two characters represent a single backslash. o The character 'n'. The two characters represent a newline ('\n'). o A quote. The two characters represent a quote, and that quote is not considered to terminate the quoted value. An ending closing quote must be present for the quoted value to be valid. o A question mark (?) or star (*). The two characters represent a question mark or star respectively. Some other MBean query examples:

*:type=Foo,name=Bar to match names in any domain whose exact set of keys is type=Foo,name=Bar. d:type=Foo,name=Bar,* to match names in the domain d that have the keys type=Foo,name=Bar
plus zero or more other keys.

*:type=Foo,name=Bar,* to match names in any domain that has the keys type=Foo,name=Bar plus
zero or more other keys.

d:type=F?o,name=Bar will match e.g. d:type=Foo,name=Bar and d:type=Fro,name=Bar. d:type=F*o,name=Bar will match e.g. d:type=Fo,name=Bar and d:type=Frodo,name=Bar. d:type=Foo,name="B*" will match e.g. d:type=Foo,name="Bling". Wildcards are recognized even inside quotes, and like other special characters can be escaped with \.
A quote, question mark, or star may not appear inside a quoted value except immediately after an odd number of consecutive backslashes. Spaces have no special significance in an MBean query. For example, the string domain: key1 = value1 , key2 = value2 represents an query with two keys. The name of each key contains six characters, of which the first and last are spaces. The value associated with the key " key1 " also begins and ends with a space. No part of a query may contain a newline character ('\n'), whether the domain, a key, or a value, whether quoted or unquoted. The newline character can be represented in a quoted value with the sequence \n.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.jmx

Global Settings
None defined.

User Level Settings

None defined.

2000-2013 Tibbo Technology Inc.

142

AggreGate Documentation

Device Properties
CONNECTION PROPERTIES
Connection properties define how AggreGate Server communicates with a JMX server. These settings may be accessed using the Edit Device Properties 677 action of Device Context. The following connection properties are available: Property Host Port Username Password Custom Service URL Ignore Attributes Producing Read Errors Description IP address of host name to connect to. Port to connect to. Username to use for authentication. Password to use for authentication. Custom URL of JMX service. Service URL already includes host and port, so Host and Port settings are not used if it's specified. If enabled, no setting variables will be created for the MBean attbitutes that has generated read errors during MBean meta-data analysis (e.g. first attribute read attempt).

MBEAN QUERIES
This property contains a table of MBean queries Property Name Description Query Description Name of Device setting variable that will contain query results. Description of Device setting variable that will contain query results. Text of the query.
140 :

Device Assets
The driver creates one root asset for every MBean instance provided by the MBean server. The list of MBeans available on a JMX host may change at any time. To force the server re-reading list of MBeans (assets) on every synchronization, switch Metadata Reading Mode 124 setting of a JMX device account to Read all .

Device Settings
JMX device driver creates one Device setting variable per every attribute of every discovered MBean. These variables are grouped by MBean names and/or descriptions to facilitate navigation. Additionally, one setting variable is created per every query defined in MBean Queries table. This tabular variable lists properties of MBeans selected by the query.

Device Operations
JMX device driver creates one Device context function and action per every operation provided by every discovered MBean. These actions are grouped by MBean names and/or descriptions to facilitate navigation.

Device Events
JMX device driver creates one Device context event definition per every notification type of every discovered MBean. The driver automatically adds a notification listener for every notification and generates a AggreGate Server event when a notification is received.

Connection Handling
This driver makes the device Online if: TCP connection to a JMX host was successfully established JMX RMI connector authentication and authorization did not fail

2000-2013 Tibbo Technology Inc.

AggreGate Server

143

Synchronization Details
Synchronization between AggreGate Server and JMX host includes the following steps: Reading a list of available MBeans. Reading information about attributes provided by every MBean. Reading information about operation provided by every MBean. Reading information about notifications provided by every MBean. Reading/writing values of all attributes. Executing all MBean queries and reading attributes of all MBeans matching those queries. Subscribing to the notifications.

3.5.5 Local File

Local File Device Driver
129

provides monitoring for files located on the AggreGate server.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.file

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
Local file monitoring can be configured using the following properties: Field Name Path Read Contents Incremental Reading Field Description Specifies the file location (full path). Enables/disables reading of the file contents. Switches between reading the whole file and incremental reading. Incremental reading is ideal for log file analysis. If it's enabled, the server remembers previous file size and, during the next synchronization cycle, reads data starting from the previous end point to the end of file. If the file size has not grown since the previous cycle, no reading is performed. If file size has decreased, the reading is restarted from file start (this is suitable to handle log file rotation. Maximum number of bytes that the server will read if incremental reading is enabled.

Maximum Read Size

Backlog Read Size Number of bytes to include from previous steps of incremental reading. Allow Editing Calculate Checksum Allows or prohibits modification of the file contents. Enables/disables file checksum calculation.

Device Settings
Local File device driver creates two Device setting variables: Variable Name attributes Variable Description File Attributes Comments Contains the file attributes:

2000-2013 Tibbo Technology Inc.

144

AggreGate Documentation

Last Modification Time (modificationTime) Size (size) Checksum calculated using Adler-32 algorithm ( checksum) contents File Contents Read-only (if Read Contents 143 option is on) or editable (if Allow Editing 143 option is also on) file contents.

Device Operations
No operations provided by the driver.

Device Events
No events provided by the driver.

Connection Handling
If all I/O operations with the file have finished successfully, the local file Device is deemed "online". If no file exists at the path specified, or any error was encountered while accessing the file, the local file Device is considered "offline".

Synchronization Details
As Local File is a Device Driver 129 , it performs a "synchronization 126 " with AggreGate Server like any other driver. During synchronization, attributes and contents of the file are obtained. Also, if editing is allowed and a user has edited server copy of file contents, the new contents are written to the file.

3.5.6 Local Folder

Local Folder Device Driver
129

provides monitoring for folders located on the AggreGate server.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.folder

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
Local Folder driver checks the existence of the folder, acquire folder attributes, load and inspect folder contents (files and subfolders). Contents of a folder can be analyzed recursively (including subfolders) or non-recursively. Besides that, the items to be processed can be filtered using wildcard or regular expression. This can be configured using the following properties: Field Name Path Read Contents Recursive Files To Include Field Description Specifies folder location, i.e. full path. Enables/disables reading of folder contents. If disabled, only contents of the specified folder will be analyzed. Otherwise, all its subfolders will be processed recursively. Specifies filter for folder items. The options are to process all files and folders, or to select only those satisfying specified regular or wildcard expression.

Device Settings

2000-2013 Tibbo Technology Inc.

AggreGate Server
Local Folder device driver creates two Device setting variables: Variable Name Folder Attributes Variable Description attributes Comments Contains the following attributes: Last Modification Time (modificationTime)

145

Size, i.e. total size of all files selected according to Recursive and Files To Include options ( size) File count, i.e. total number of files selected according to Recursive and Files To Include options (fileCount) Folder Contents contents List of folder items (files and subfolders) with the following fields: Type Relative Path Size

Device Operations
No operations provided by the driver.

Device Events
No events provided by the driver.

Connection Handling
If all I/O operations with the folder have finished successfully, the local folder Device is deemed "online". If no folder exists at the path specified, or any error was encountered while accessing the folder, the local folder Device is considered "offline".

Synchronization Details
Local Folder Devices are synchronized 126 with AggreGate Server like any other Device. During synchronization, attributes and contents of the folder are obtained.

3.5.7 Modbus
The Modbus Device Driver 129 allows AggreGate Server to communicate with devices supporting Modbus Protocol. These devices may be connected to the system and, like with all other types of devices, their data is converted into a unified form, so they can be accessed from different AggreGate facilities. See Devices 113 article for more information about the "normalized" representation of devices in Tibbo AggreGate. The Modbus driver supports both network versions (Modbus TCP and Modbus UDP) and serial versions (Modbus RTU, Modbus ASCII and Modbus BIN) of the protocol. Modbus serial devices should be connected to the COM ports of the PC running AggreGate Server. To connect Modbus serial devices to an IP network, use Tibbo's programmable module (such as DS1206) running the Modbus Converter application.

CONFIGURING AGGREGATE SERVER FOR SERIAL COMMUNICATIONS

See Enabling Serial Communications
959

if you have troubles connecting to Modbus Serial devices.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.modbus

Global Settings
None defined.

2000-2013 Tibbo Technology Inc.

146

AggreGate Documentation

User Level Settings

None defined.

Device Properties
CONNECTION SETTINGS
Connection settings define how AggreGate Server communicates with a certain Modbus device. These settings may be accessed using the Edit Device Properties 677 action of Device Context. The following connection properties are available: Property Modbus Version Unit ID IP address or host name Port Encoding Baud Rate Incoming Flow Control Outgoing Flow Control Data Bits Stop Bits Parity Timeout Retries Reconnect on every command Description A choice of Modbus TCP, Modbus UDP and Modbus Serial. Modbus Unit ID. Identification (address) of a remote slave connected on a serial line or on other buses (e.g. RS485). Address of Modbus device (for Modbus TCP/UDP). Modbus device port (IP port number defaulting to 502 for Modbus TCP/UDP; Serial port name for Modbus Serial). A choice of RTU, ASCII or BIN (for Modbus Serial). Baud Rate (for Modbus Serial). Incoming flow control type: None, CTS/RTS, or XON/XOFF (for Modbus Serial). Outgoing flow control type: None, CTS/RTS, or XON/XOFF (for Modbus Serial). Serial data bits (for Modbus Serial). Serial stop bits (for Modbus Serial). Serial parity (for Modbus Serial). Command timeout (default is 5 seconds). Number of retries for each command. Forces every Modbus TCP transaction to be performed in a separate connection.

DEVICE REGISTERS
This property contains a list of Modbus device registers that are accessed and managed by AggreGate. Once a new Modbus device is added, one or more registers have to be configured to make device data available for the system. Each Modbus register is represented by a single variable 869 of Device Context 677 . Modbus devices do not provide metadata, so AggreGate Server cannot learn about available Modbus registers of a particular device. That is why it's necessary to configure Device Registers manually. Here is a list of properties of each Modbus register: Property Name Description Type Format Register Address (decimal) Size Description Register name. This will be used as a Device Context it may contain only letters, digits and underscore.
677

variable used to access the register, so

Register textual description. Will be used as the description of the Device Context variable. Modbus register type. Possible values are Coil, Discrete Input, Input Register and Holding Register . Defines how to interpret value of one or more adjacent Input or Holding Registers. See type conversion 147 section for details. Address of the Modbus register in decimal form. Number of registers to read by a single modbus I/O operation and store in one AggreGate Server context variable. It may be useful to read multiple registers at once in the following cases:

2000-2013 Tibbo Technology Inc.

AggreGate Server

147

If they logically represent an array If they logically represent a string If they logically represent different parts of a complex data item that should be read in one atomic operation The actual number of registers read in a single I/O operation will be N * M, where N is the number of registers required to hold one AggreGate Server-side value depending on Type and Format M is the value of Size parameter For example: if Type is Input Register, Format is 8-byte Float, and Size is 4, server will read 32 registers and represent them as a 4-element array (single-column Data Table 854 ) with Floating point numbers if Type is Holding Register, Format is Varchar, and Size is 64, server will read 64 registers and as a single-cell Data Table containing String value. This setting has the default value of 1. The default should not be changed in most cases. You can import the list of registers from a file (e.g. CSV file) by using Import 801 component.
801

function of Data Table Editor

If you wish to connect several similar Modbus devices to AggreGate, you could fill in the Device Registers table only once and then copy it to other devices using the Replicate 909 action.

Device Settings
Modbus device driver creates one Device setting variable per device register.

TYPE CONVERSION
The following table shows how Modbus Registers are converted to Device context variables. Note that number of rows in each variable depends on the value of Size parameter. By default, all variables are single-row, i.e. scalar. Register Type Coil Discrete Input Input Register Format N/A N/A 2-Byte Int Unsigned 2-Byte Int Signed 4-Byte Int Unsigned 4-Byte Int Signed 4-Byte Int Unsigned Swapped 4-Byte Int Signed Swapped 4-Byte Float 4-Byte Float Swapped 8-byte Int Signed 8-byte Int Signed Swapped 8-byte Float AggreGate Server Variable Format Readable/Writable, 1 Column of type Boolean Read-Only, 1 Column of type Boolean Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Long Readable/Writable, 1 Column of type Long Readable/Writable, 1 Column of type Float

8-byte Float Swapped Readable/Writable, 1 Column of type Float

2000-2013 Tibbo Technology Inc.

148

AggreGate Documentation

2-byte BCD 4-byte BCD Char

Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type Integer Readable/Writable, 1 Column of type String. Server reads number of registers specified by Size parameter and represents them as a string that will always have 64-characters length. Readable/Writable, 1 Column of type String. Server reads number of registers specified by Size parameter and represents them as a string. This string will be terminated by the first zero-value register. Same to Input Register with equal Format, but Read-Only.

Varchar

Holding Register

Any

Device Operations
No operations provided by the driver.

Device Events
No events provided by the driver.

Connection Handling
This driver makes the device Online if: Serial port was opened successfully (for Modbus Serial devices) TCP connection with the device was successfully established (for Modbus TCP devices) Always (for Modbus UDP devices)

Synchronization Details
Synchronization between AggreGate Server and Modbus device includes the following steps: Creating a Settings Cache device register.
115

according to the Device Registers list. Each variable is used to access a single Modbus

Reading Modbus register values and storing these values in settings cache.

3.5.8 Modem
The modem Device Driver 129 allows AggreGate Server to control a GSM modem or any other modem that is based on AT command set. Modem devices are often used to send SMS messages in response to alerts 216 .

CONFIGURING AGGREGATE SERVER FOR SERIAL COMMUNICATIONS

In most cases the modem is connected to a serial port of AggreGate Server machine. See Enabling Serial Communications 959 to find out to get access to a serial device.

RECEIVING SMS MESSAGES

The modem device driver fires an SMS event in Administration context each time a new message is received.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.modem

Global Settings
None defined.

User Level Settings

None defined.

2000-2013 Tibbo Technology Inc.

AggreGate Server

149

Device Properties
CONNECTION SETTINGS
Connection settings define how AggreGate Server communicates with a modem. These settings may be accessed using the Edit Device Properties 677 action of Device Context. The following connection properties are available: Property Mode IP address or host name Port Baud Rate Incoming Flow Control Outgoing Flow Control Data Bits Stop Bits Parity Timeout Description A choice of TCP, UDP and Serial. Address of the modem (for TCP/UDP mode). Modem listening port (for TCP/UDP mode) or name of serial port the modem is connected to (for Serial mode). Baud Rate (for Serial mode). Incoming flow control type: None, CTS/RTS, or XON/XOFF (for Serial mode). Outgoing flow control type: None, CTS/RTS, or XON/XOFF (for Serial mode). Serial data bits (for Serial mode). Serial stop bits (for Serial mode). Serial parity (for Serial mode). Command timeout (default is 5 seconds).

COMMANDS
This property contains a list of modem commands that will be periodically sent to the modem on every synchronization 126 cycle. Last reply to each command will be available as a single variable 869 of Device Context 677 . The commands table if pre-filled with commonly used modem status commands.

Here is a list of properties of each modem command: Property Name Description Command Wait for Standard Reply Description Command name. This will be used to name the Device Context reply, so it may contain only letters, digits and underscore.
677

variable used to access the

Command textual description. Will be used as the description of the Device Context variable. The text of command to sent (should include "AT" prefix for most commands). If enabled, wait until the modem replies with OK. If disabled, stop receiving reply once a newline character is received.

If you wish to connect several similar modem devices to AggreGate, you could fill in the Commands table only once and then copy it to other devices using the Replicate 909 action.

Device Settings
Modem device driver creates one Device setting variable per every command found in the Commands table. The variable contains text of reply received from modem.

Device Operations
SEND SMS
This operation is used to send an SMS message via connected GSM modem. It prompts user to enter recipient's number and SMS text first.

2000-2013 Tibbo Technology Inc.

150

AggreGate Documentation

Add Send SMS action to an alert's automatic corrective actions when the alert is raised.

232

list to enable sending SMS notifications

EXECUTE CUSTOM COMMAND

Allows to send a custom command to modem.

Device Events
SMS

Fired when AggreGate Server receives an incoming SMS message. Event Name Permissions: Records: Record Format
Field Name sender text
855

sms

Accessible at Observer permission level 1 :

Field Type String String Notes Sender's number. Message text.

932

Connection Handling
This driver makes the device Online if connection with modem was successfully established and it has replied OK to two commands: ATE0 and AT.

Synchronization Details
Synchronization between AggreGate Server and modem device includes the following steps: Creating a Settings Cache modem command.
115

according to the Commands list. Each variable is used to access the reply to a single

Executing modem commands and storing the replies in settings cache.

3.5.9 Network Host

Network Host device driver permits AggreGate Server to access a single IP network host for monitoring it's status and various services/applications running on it. The following table presents available services, their global settings, configuration properties and monitoring results (presented as device settings): Monitoring Service Ping
153 154 154 155

Configuration Ping Settings

153

Properties

Monitoring Results Ping Results

153 176 155 155

Operations

SNMP

SNMP Polling Settings

176 154 155

SNMP Results

SNMP Operations

174

Generic TCP Generic UDP HTTP DNS POP3 IMAP

156 156 157 158

Generic TCP Service Settings Generic UDP Service Settings HTTP Settings DNS Settings POP3 Settings
156 157 158

Generic TCP Results Generic UDP Results HTTP Results DNS Results POP3 Results IMAP Results
156 157 158

HTTP Operations

140

IMAP Server Settings

2000-2013 Tibbo Technology Inc.

AggreGate Server

151

SMTP
159

158

SMTP Server Settings

159 159

SMTP Results
160

159

E-mail Round-Trip FTP

160 161

E-mail Round-Trip Settings FTP Server Settings Traceroute Settings SSH Settings
163 164 165 166 160 162

E-mail Round-Trip Results FTP Results

161 162

Traceroute SSH
163 164 165 166

Traceroute Results SSH Results

164 165 165 166

SSH Operations

164

DHCP LDAP

DHCP Settings LDAP Settings

DHCP Results LDAP Results

Radius WMI
186

Radius Settings WMI Settings

186

Radius Results

Refer to Device Settings section in WMI 186 chapter

WMI Operations

187

NETWORK DEVICE DISCOVERY

Network Host driver supports device discovery. Discovery is the process of scanning a number of IP network hosts, finding available services/applications, and creating device accounts for them. The comprehensive description of network discovery is available in AggreGate Network Manager documentation.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.ip

Global Settings
Global settings defined by Network Host driver are presented in the Global Settings column of Network Host Services table 150 .

User Level Settings

None defined.

Device Properties
Network Host driver properties define configuration parameters used by AggreGate Network Manager to monitor corresponding network host. Most of the properties present settings of services supported by Network Host driver. They are presented in the Configuration Properties column of Network Host Services table 150 . Other Device properties are: Host Address (address) property. It specifies IP Address or Host Name of the network host to be monitored. Connection Status Expressions (connectionStatusExpressions) property. It defines how does each service affect the online status of the whole network host.

Device Assets
IP host assets are divided in two root groups: SNMP assets and WMI assets: If SNMP service is enabled, one asset is created for every SNMP MIB file supported by the device. Supported MIB files are detected automatically by polling the SNMP agent. If WMI service is enabled, one asset is created for every available WMI class.

Device Settings
Network Host device settings are: Host status Monitoring results for services enabled on this network host. Refer to Monitoring Results column of Network Host Services table
150 .

Device Operations

2000-2013 Tibbo Technology Inc.

152

AggreGate Documentation
150 .

Refer to Operations column of Network Host Services table

Device Events
Network hosts can generate two different types of events: Service Outages (described below) and SNMP Notifications (described in SNMP device driver 174 chapter).

SERVICE OUTAGE
This event is generated by a service once if goes back "online" after a certain period of downtime.

Event Name Permissions Records

outage

Accessible at User permission level 1

932

The outage event has the following format: Field Name Field Type
String Date Long String

Notes

service start duration reason

Service that was down. Outage start date and time. Outage duration in seconds Outage reason.

Connection Handling
The Network Host driver has a configurable Online/Offline status detection policy. This helps to bring the device account offline if a certain service experiences a user-defined operability problem. The status detection configuration is performed through the Connection Status Expressions table. Each line of this table describes a service or custom formula that affects online status of the network host device. The table has three fields: Comment. This field is a human-readable description of the table record. Enabled Expression. An expression 911 that defines whether the record is "active", i.e. really affects device status. The expression should return a Boolean value (true/false). If it returns false, the record is deemed disabled and doesn't affect connection status of the network host. Connection Status Expression. An expression 911 that defines current "connection status" of the service, i.e. whether the service is available and has no errors. This expression should return a Boolean value (true/false) or null. If it returns true or false, the corresponding service is deemed online or offline respectively. If the expression returns null, the connection status of the service is considered unknown. The Connection Status Expressions table is analyzed on the end of every synchronization 126 cycle. Records those Enabled Expression return false are skipped. After that, connection status of the network host is calculated upon Connection Status Expression result of remaining records: If at least one Connection Status Expression returns null, the connection status of the network host is deemed Unknown Otherwise if at least one Connection Status Expression returns false, the network host is deemed Offline Otherwise the network host is deemed Online This example shows how to modify the HTTP service configuration to bring the network host offline if an HTTP reply code is not 200 (Successful):

Comment: HTTP Enabled Expression: {httpSettings$enabled} Connection Status Expression: hasVariable({.:}, 'http') && {http$successful} && {http$replyCode} != 200

2000-2013 Tibbo Technology Inc.

AggreGate Server
Statuses of individual services may be checked using Configure Device
677

153

action.

Synchronization Details
Network Host driver uses synchronization procedures of particular services enabled for the monitored device. Refer to the appropriate service subsection for detailed synchronization descriptions.

3.5.9.1 Ping Monitoring

Ping service allows: Checking IP host status by monitoring its reachability/availability Measuring round-trip times. It operates by sending Internet Control Message Protocol (ICMP) echo requests to the monitored host and collecting statistics of ICMP responses.

Operation
Refer to Ping Settings
153

subsection for a list of configuration parameters used.

Ping services performs ping request and adds its results to a cache. The size of the cache is defined by service configuration. The oldest results are removed from the cache when it's size is exceeded. Ping service is denoted Offline if several consecutive requests fail. The number of the requests considered is defined by Number of failed Echo Requests activating offline status configuration parameter. In other words, if any of the most recent requests was successful the services is deemed Online. The cached results are used to calculate ping statistics: average round-trip time, packet loss rate and last round-trip time. See also Ping Monitoring Results 153 subsection.

3.5.9.1.1 Ping Settings

The following settings are used by Ping service Property Enabled Timeout, milliseconds Packet Data Size, bytes Number of Echo Requests for Packet Loss Calculation Number of failed Echo Requests activating offline status
153 :

Description Enables/disables ping for this host. If no reply is received within this time period, ping attempt is considered as failed. Size of ICMP packet data (excluding headers). To calculate Packet Loss Rate, AggreGate Server takes several last ping results specified by this setting, and calculates percentage of failed requests. Number of consecutive failed ping attempts that will change connection status 152 of network host to Offline.

3.5.9.1.2 Ping Monitoring Results

The following table presents Ping monitoring results:

Property Successful

Description Indicates that at least one of most recent requests was successful. Number of requests considered is defined by Number of failed Echo Requests activating offline status configuration parameter 153 . Average round-trip time for of a number of non-failed ping attempts specified by Number of Echo Requests for Packet Loss Calculation property. Percentage of failed ping attempts. Number of Echo Requests for Packet Loss Calculation property defines how many ping attempts are used for calculation. Round-trip time of last non-failed ping attempt.

Average Round-Trip Time, milliseconds Packet Loss Rate, % Last Round Trip Time, milliseconds

2000-2013 Tibbo Technology Inc.

154

AggreGate Documentation

3.5.9.2 SNMP Monitoring

Simple Network Management Protocol support is provided by SNMP device driver . Network Host device driver utilizes SNMP driver and presents its features as a service. Refer to SNMP device driver 173 section for details.

3.5.9.3 Generic TCP Service Monitoring

TCP Service is a network service that uses Transmission Control Protocol (TCP) to communicate with its clients. Network Host device driver supports availability/operability monitoring for several TCP services per IP host.

Synchronization Details
Generic TCP Service status is checked during synchronization. The service is deemed Online if all configured services/ ports are online. Status of particular TCP service is checked using one of the three procedures: TCP connection checking immediate reply checking (without sending any data) sending data and checking the reply Effective check procedure is determined by Send Data property as described below.

CONNECTION CHECK
Connection check is performed if Send Data is not specified, i.e. is null. The following operations are performed in this case: 1. A TCP connection is established to the associated port of the device. 2. Response is immediately read. The check is deemed succeeded if connection was successfully established. Response is included in result data record, but does not affect status of the service.

IMMEDIATE REPLY CHECK

Immediate reply check is performed if Send Data is empty string. The following operations are performed: 1. A TCP connection is established to the associated port of the device. 2. Response is immediately read. The check is deemed succeeded if connection was successfully established and non-empty response received . Response is included in result data record.

SEND DATA AND REPLY CHECK

Send and reply check is performed if Send Data is non-empty string. The following operations are performed: 1. A TCP connection is established to the associated port of the device. 2. Data specified in service configuration is sent via this connection. 3. A response is read. The check is deemed succeeded if connection was successfully established, the data was successfully sent and non-empty response received. Response is included in result data record.

3.5.9.3.1 Generic TCP Service Settings

The following settings presented by TCP Services/Ports (tcpSettings) variable are used to monitor a particular service/port (see also Generic TCP Service Monitoring 154 ): Property Port Timeout, milliseconds Description Port number to connect to. This timeout is used twice: for establishing TCP connection and waiting for a reply.

2000-2013 Tibbo Technology Inc.

AggreGate Server

155

Send Data

Raw data to send, in the string form. Default value is null. This value determines service status check procedure, see Generic TCP Service Monitoring section 154 for details.

3.5.9.3.2 Generic TCP Service Monitoring Results

A separate variable is created for every monitored TCP service. The variables are named Generic TCP Service, Port (genericTcp) followed by port number. For example, variable for TCP service at port 2345 is named as Generic TCP Service, Port 2345 (genericTcp2345). The variables have the following fields:

Field Successful Error Response Time, milliseconds Reply

Description Indicates that connection with a service was established without errors. Connection or data transfer error, or NULL is there were not errors. Service response time. Reply received from a service, in the string form. NULL if no reply were received or error occurred.

3.5.9.4 Generic UDP Service Monitoring

UDP Service is a network service that uses User Datagram Protocol (UDP) to communicate with its clients.

Network Host device driver supports availability/operability monitoring for UDP services of any kind (hence the term "generic" used here). Several UDP services can be configured to be monitored at a particular IP host.

Synchronization Details
Generic UDP service monitoring is very similar to Generic TCP service monitoring 154 except that UDP (User Datagram Protocol) is connectionless. Therefore the monitoring procedure for a particular UDP service is confined to sendingreceiving cycle: 1. Data specified in service configuration is sent to the provided port of the IP host. 2. A reply is awaited. Is some data is received within the specified timeout it is included in result data record. The procedure is executed for every configured service/port. A particular service is considered Online if send and receive operations were successful. The whole Generic UDP Service is deemed Online if all configured services/ports are online.

3.5.9.4.1 Generic UDP Service Settings

The following properties presented by UDP Services/Ports (udpSettings) variable are used to monitor a particular UDP service (see also Generic UDP Service Monitoring section 155 ): Property Port Timeout, milliseconds Send Data Description Port number to connect to. A period of time alloted to wait for a reply. Raw data to send, in the string form.

3.5.9.4.2 Generic UDP Service Monitoring Results

A separate device setting variable is created for every monitored UDP service (see Generic UDP Service Monitoring section 155 ). The variables are named Generic UDP Service, Port (genericUdp) followed by port number. For example, variable for UDP service at port 5432 is named as Generic UDP Service, Port 5432 (genericUdp5432). The variables have the following fields:

Field

Description

2000-2013 Tibbo Technology Inc.

156

AggreGate Documentation

Port Successful Error Reply Response Time, milliseconds

Port number used to send data to. Indicates that the reply was successfully received. Data transfer error, or NULL is there were not errors. Reply received from a service, in the string form. NULL if no reply were received or error occurred. Service response time.

3.5.9.5 HTTP Server Monitoring

HTTP support is provided by HTTP device driver. Network Host device driver utilizes HTTP driver and presents its features as a service. Refer to HTTP device driver 139 section for details.

3.5.9.6 DNS Server Monitoring

A Domain Name System (DNS) server is a server that stores the DNS records and responds with answers to queries against its database. Domain Name System (DNS) monitor allows to monitor availability and operability of DNS server by sending lookup requests and obtaining server's responses. The responses collected as monitoring results can be used to analyze the validity of DNS server operation.

Synchronization Details
The DNS monitor can be configured to send several lookup requests. Each request comprises Record Type and Host Name to resolve. Service executes all the specified lookup requests and acquire result responses. The service is deemed Online if all the requests were successfully executed.

3.5.9.6.1 DNS Service Settings

DNS server monitor Property Enabled Port Protocol Timeout, milliseconds Requests
156

has the following settings presented by DNS Monitoring (dnsSettings) variable: Description Enables/disables DNS server monitoring. Port number the DNS server is running on. Communication protocol: UDP or TCP . Timeout for DNS operations. DNS requests to execute. Request properties: Request Type: A , AAAA, CNAME, NS or MX. Request: host name to include in request.

3.5.9.6.2 DNS Monitoring Results

DNS monitoring result is presented by DNS (dns) variable and includes service status and server responses for each DNS lookup request configured:

Field Successful Details

Description Indicates that all requests were successfully executed. Detailed results for particular queries:

2000-2013 Tibbo Technology Inc.

AggreGate Server

157

Field Request Request Type Result Error

Description Request data (host name), read-only. Request type, read-only. DNS server response text (usually IP address or host name). NULL if there were errors. Error text, or NULL if no error occurred while executing request.

3.5.9.7 POP3 Server Monitoring

POP server is a computer program that delivers e-mail messages using the Post Office Protocol (POP). POP3 (POP version 3) is current standard of the protocol. POP3 server monitor allows to check availability and ensure proper functioning of a POP3 e-mail server.

Synchronization Details
POP3 monitor connects to specified mail server and performs authentication using parameters specified in service settings 157 . Then it requests size of INBOX folder and messages count in it. If all the operations were performed successfully the service is deemed Online and message statistics are stored as monitoring results 157 . If an error is encountered the service is denoted as Offline and the error text is saved in monitoring results.

3.5.9.7.1 POP3 Service Settings

POP3 monitoring
157

configuration includes the following properties presented by POP3 Settings (pop3Settings):

Property Enabled Port Timeout, milliseconds User Name Password

Description Enables/disables POP3 server monitoring. Port number the POP3 server is running on. Timeout for operations. User name to use for logging in to mailbox. Password to use for logging in to mailbox.

3.5.9.7.2 POP3 Monitoring Results

The monitoring result are stored in the POP3 (pop3) variable with the following format:

Property Successful Number of Messages Messages Total Size, bytes Error

Description Indicates that there were not errors during last mailbox check. Number of e-mails in the mailbox. Total size of all e-mails in the mailbox (raw size, includes headers). Error text, or NULL if no error occurred during last check.

2000-2013 Tibbo Technology Inc.

158

AggreGate Documentation

3.5.9.8 IMAP Server Monitoring

IMAP server is a computer program that delivers e-mail messages using the Internet Message Access Protocol (IMAP). IMAP server monitor allows to check availability and proper functioning of a IMAP e-mail server.

Synchronization Details
IMAP monitor connects to IMAP server, performs authentication and fetches message count and total size of all messages from a specified folder. Required parameters are specified as service settings 158 . If a connection with the IMAP server was established without errors and message statistics was successfully obtained, the service is deemed Online. Otherwise error message is saved and service is denoted Offline. Refer to IMAP Monitoring Results 158 section for their detailed description.

3.5.9.8.1 IMAP Service Settings

The following properties specify IMAP server monitoring ) variable:
158

parameters presented by IMAP Settings (imapSettings

Property Enabled Port Timeout, milliseconds User Name Password Folder Check Recent Messages Only

Description Enables/disables IMAP server monitoring. Port number the IMAP server is running on. Timeout for operations. User name to use for logging in to mailbox. Password to use for logging in to mailbox. Folder to check (optional, use default folder is not selected). When enabled, only unread messages are included to the mailbox statistics.

3.5.9.8.2 IMAP Monitoring Results

Monitoring results are stored in the IMAP (imap) variable and available as the device settings with the following format:

Property Successful Number of Messages Messages Total Size, bytes Error

Description Indicates that there were no errors during last mailbox check. Number of e-mails in the mailbox, or number of unread messages if Check Recent Messages Only flag is set. Total size of all e-mails in the mailbox (raw size, includes headers), or total size of unread messages if Check Recent Messages Only flag is set. Error text, or NULL if no error occurred during last check.

3.5.9.9 SMTP Server Monitoring

SMTP server is a computer program that provides sending and receiving e-mail messages using the Simple Mail Transfer Protocol (SMTP). Typically SMTP is used by client e-mail applications only for sending messages. SMTP server monitor allows to check availability and ensure proper functioning of SMTP e-mail server.

Synchronization Details
SMTP server is monitored by establishing a connection with the server and passing its authorization procedure. No email messages are actually sent. Refer to SMTP Service Setting 159 subsection for its configuration details. If connection and authorization are successfully performed the service is deemed Online. Otherwise it is marked as

2000-2013 Tibbo Technology Inc.

AggreGate Server
Offline and error message is saved in SMTP monitoring results
159 .

159

3.5.9.9.1 SMTP Service Settings

SMTP server monitor variable:
158

has the following configuration properties presented by SMTP Settings (smtpSettings)

Property Enabled Port Timeout, milliseconds User Name Password

Description Enables/disables SMTP server monitoring. Port number the SMTP server is running on. Timeout for operations. User name to use for logging in to mailbox. Password to use for logging in to mailbox.

3.5.9.9.2 SMTP Monitoring Results

SMTP monitoring results are stored in the SMTP (smtp) variable. They comprise operation status and error message if one was encountered:

Property Successful Error

Description Indicates that there were not errors during last SMTP server check. Error text, or NULL if no error occurred during last check.

3.5.9.10 E-mail Round-Trip Monitoring

E-mail round-trip monitoring service ensures the end-to-end delivery of e-mail messages, making it possible to check functioning of mail system in whole.

Synchronization Details
The idea behind this kind of monitoring is to ensure that the e-mail messages are successfully delivered through the monitored server. To perform this, round-trip monitor generates and sends a test message. During the next synchronization the service checks that the test message has been dropped to the incoming mailbox. All test messages are removed from the incoming mailbox right after the check. The send/receive operations are performed in every synchronization cycle. Sender and recipient addresses and e-mail retrieving protocol to be used are specified as service settings
159 .

E-mail round-trip monitor uses SMTP service settings 159 for sending outgoing test emails. The sender and recipient of these emails are defined in E-mail-round trip service configuration 159 . A user can select either POP3 or IMAP protocol to be used for retrieving previously sent messages. E-mail round-trip monitor uses POP3 service settings test emails.
157

or IMAP service settings

158

for receiving back the

E-mail round-trip service is deemed Online if test emails are being sent and received successfully. If send/receive operations fail due to an error or previously sent test message was not found in the mailbox, service is marked as Offline. The errors encountered during sending and receiving operations are saved in monitoring results 160 .

3.5.9.10.1 E-mail Round-Trip Service Settings

E-mail round-trip monitoring 159 is configured using the following properties presented by E-mail Round-Trip Settings (emailSettings) variable:

Property

Description

2000-2013 Tibbo Technology Inc.

160

AggreGate Documentation

Enabled E-mail Retrieval Protocol Sender Address Recipient Address

Enables/disables E-mail round-trip monitoring. The protocol for managing incoming messages. An e-mail address to be specified in the FROM field of test e-mail message. An e-mail address of the recipient the test message is addressed to.
159 ,

E-mail round trip monitor uses SMTP messages.

and POP3

157

or IMAP

158

options for sending and retrieving

3.5.9.10.2 E-mail Round-Trip Monitoring Results

E-mail round-trip monitoring results are stored in E-mail Round-Trip (emailRoundTripResult) variable with the following format:

Property Successful Sending Error Receiving Error

Description Indicates that there were not errors during last SMTP server check. Sending error text, or NULL if no error occurred during sending test message. Receiving error text, or NULL if no error occurred during retrieving test message.

3.5.9.11 FTP Server Monitoring

File Transfer Protocol (FTP) is a standard network protocol used to copy a file from one host to another over a TCP/IP-based network, such as the Internet. FTP server monitor provides FTP server operability testing by checking server status and reading attributes of a remote file using FTP protocol.

Synchronization Details
FTP monitoring configuration settings are described in FTP Service Settings The following operations are performed during synchronization: Connection to FTP server is established. Authentication procedure is passed. Server status information is obtained and saved in monitoring results. File is located using path specified in parameters. File timestamp (which is usually its last modification time) and size (in bytes) attributes are obtained. Disconnection is performed. All these operations should be successfully finished to make the service Online. Server status and file information are stored as monitoring results 161 . If any of the operations fails the server is deemed Offline. Error encountered during synchronization is saved in the monitoring results. Note that a path specified in service configuration should refer to a regular file (i.e. not point to a directory or include wildcard characters). If monitor is unable to find the file using specified path the FTP service is deemed Offline.
160

subsection.

3.5.9.11.1 FTP Service Settings

FTP server monitor variable: Property
160

configuration includes the following parameters presented by FTP Settings (ftpSettings)

Description

2000-2013 Tibbo Technology Inc.

AggreGate Server

161

Enabled Port User Name Password Path Read Contents Incremental Reading

Enables/disables FTP server monitoring. Port number the FTP server is running on. User name to use for authentication. Password to use for authentication. Path of file or folder to be monitored (optional). Defines whether the above file/folder contents should be read. Switches between reading the whole file and incremental reading. Incremental reading is ideal for log file analysis. If it's enabled, the server remembers previous file size and, during the next synchronization cycle, reads data starting from the previous end point to the end of file. If the file size has not grown since the previous cycle, no reading is performed. If file size has decreased, the reading is restarted from file start (this is suitable to handle log file rotation.

Maximum Read Size Timeout, milliseconds

Maximum number of bytes that the server will read if incremental reading is enabled. FTP server operations timeout.

3.5.9.11.2 FTP Monitoring Results

FTP monitoring results are available as FTP (ftp) variable variable:

Property Successful Error Server Status Folder Contents File Contents

Description Indicates, that ftp server monitor had no errors during last file read. Error description, or NULL if there were no errors. FTP server status reply. Table containing attributes of monitored file or all files in the monitored folder: file name, size and last modification time. Contents of the monitored file.

3.5.9.12 Traceroute Monitoring

Traceroute allows to track the route taken by packets across an IP network.

Traceroute monitoring service implements traceroute functionality providing an ability to test an IP network host availability/reachability. This may help to detect and diagnose various network problems. The traceroute monitor supports both known traceroute implementation methods: using ICMP echo requests and UDP datagrams. The network route traced during monitoring is available for analysis by any of AggreGate data processing facilities. For example, it's possible to trigger an alert if number of hops exceeds a threshold, or hop N has a certain IP address.

Synchronization Details
Traceroute service synchronization includes the following steps: 1. Basic traceroute procedure is executed by sending ICMP or UDP datagrams from local to destination host. Starting with time to live (TTL) field of datagram set to 1 and subsequently incrementing it, information about intermediate network nodes (hop) is collected. The process stops either if the destination host is reached or if max number of hops is encountered. The traceroute procedure uses parameters specified as service settings 162 . 2. The collected information is processed and analyzed producing monitoring results
162

The Traceroute service is deemed Online if both steps a successfully performed and destination host was reached with the specified number of hops. Otherwise service is denoted as Offline and error message is saved in monitoring results.

Configuring Firewall to Enable Route Tracing

Certain operating systems may require additional configuration in order to allow AggreGate Server to receive incoming ICMP messages used by ICMP traceroute.

2000-2013 Tibbo Technology Inc.

162

AggreGate Documentation

For example, under Windows Vista/Seven, you need to perform the following steps: Go to Start Menu > Control Panel > Administration > Windows Firewall with Advanced Security Select Inbound Rules in the left pane Select New Rule... in the right pane Select For port and click Next Select TCP and All local ports, then click Next Click Next in Action and Profile dialogs (all profiles should be selected) Enter any filter name and click OK Double-click on the newly created rule in the main pane Switch to Protocols and ports tab and select ICMPv4 in Protocol type combo box Click OK to close the dialog.

3.5.9.12.1 Traceroute Service Settings

The following settings presented by Traceroute Settings (tracerouteSettings) variable are used for Traceroute monitoring 161 :

Property Enabled Protocol Maximum Packets per Hop Maximum Number of Hops Timeout, milliseconds

Description Enables/disables traceroute. Switches between ICMP (standard traceroute method on ICMP packets) and UDP (Van Jacobson's Traceroute algorithm on UDP packets) traceroute methods. Number of retries for contacting each hop. If destination host was not reached within this hop count, traceroute is interrupted. Timeout for every traceroute packet.

3.5.9.12.2 Traceroute Monitoring Results

Traceroute monitoring results are provided by Traceroute (traceroute) variable. It comprises the following fields:

Field Successful Error Traceroute Details

Description Indicates that traceroute procedure was completed successfully and destination host was reached. Error that occurred while tracing route or processing results, if any. Detailed traceroute results (i.e. the route to host). For each hop the following information is presented:

Field IP Address Host Name Response Time, milliseconds Error

Description IP address of the host hop. Host name of the hop, if resolved by reverse DNS. Hop response time. Error that occurred while contacting a hop, if any.

2000-2013 Tibbo Technology Inc.

AggreGate Server

163

3.5.9.13 SSH Server Monitoring

An SSH server is a computer program that accepts connections from client systems and allows data to be exchanged between the two network devices via secure channel using Secure Shell (SSH) protocol. SSH is used primarily to access shell accounts as a replacement for Telnet and other insecure remote shells. SSH monitor provides availability and operability monitoring for SSH servers. The service also provides remote script execution. This means the SSH monitoring service can be used for performing various administration tasks on remote systems.

Synchronization Details
SSH monitor performs the following operations during synchronization: 1. Establishes connection to the SSH server. 2. Authenticates using name and password specified by service settings
163 .

3. [Optional] Uploads script to the remote host. Script is specified in the settings' Script field as an explicit text or a file. Monitor first tries to upload script using scp; if the attempt fails it creates file using echo commands. 4. [Optional] Executes uploaded script using sh command. Script execution output is intercepted and saved in monitoring results 164 . 5. Closes connection. If all the operations are executed successfully the SSH service is deemed Online. If no script is specified in service parameters (i.e. Script field is NULL) steps 3 and 4 are omitted; thus, only connection, authentication and disconnection operations are performed. If an error was encountered during execution the service is denoted as Offline and error message is saved in Error field.

Execute Remote Script Action

Additionally, an Execute script on remote server using SSH (executeRemoteScript) action Root context 726 . It accepts connection settings and script as input parameters:
892

is installed in

Property Address Port Timeout, milliseconds User Name Password Script

Name address port timeout userName password script

Description Host address Port number the SSH server is running on. Timeout for SSH operations. User name to use for authorization. Password to use for authorization. Script specified as explicit text or as a file; may be NULL.

Results of the script execution are presented in the following format:

Property Successful Error Result

Name successful error result

Description Indicates that no error occurred during connection to SSH server, authorization, and remote script execution. Error text, if any. Output of a remote script.

3.5.9.13.1 SSH Service Settings

The following settings presented by SSH Settings (sshSettings) variable are used to monitor an SSH
163 server:

Property

Description

2000-2013 Tibbo Technology Inc.

164

AggreGate Documentation

Enabled Port User Name Password RSA or DSA Private Key

Enables/disables SSH monitoring and remote script execution. Port number the SSH server is running on. User name to use for authorization. Password to use for authorization. Private key to use for authorization. The key should be inserted in text format. For example, RSA key normally starts with -----BEGIN RSA PRIVATE KEY----- prefix and ends with -----END RSA PRIVATE KEY----- suffix. Password for the private key decryption. Script specified as explicit text or as a file; may be NULL. Timeout for operations.

Private Key Password Script Timeout, milliseconds

3.5.9.13.2 SSH Monitoring Results

SSH monitoring results are presented by SSH (ssh) variable with the following format:

Property Successful Error Result

Description Indicates that no error occurred during connection to SSH server, authorization, and remote script execution. Error text, if any. Output of a remote script.

3.5.9.13.3 SSH Operations

SSH service provides a single operation: Execute Script via SSH. This operations allows to load script file, connects to the device and authorizes using SSH settings 163 , executes the script on the remote host, and returns its output.

3.5.9.14 DHCP Monitoring

DHCP server is a computer program that provides automatic configuration service for IP network devices using Dynamic Host Configuration Protocol (DHCP) protocol. DHCP monitoring service provides ability to check availability and operability of a DHCP (Dynamic Host Configuration Protocol) server.

Synchronization Details
DHCP monitor sends a DHCPDISCOVER message to the monitored server and waits for an answer. The message includes MAC address specified in DHCP configuration settings 164 . If an answer is successfully received within a specified timeout the service is deemed Online. An IP address server replied with is stored in monitoring results Otherwise the service becomes Offline and error message is saved in results.

165 .

3.5.9.14.1 DHCP Service Settings

DHCP monitor
164

uses the following settings presented by DHCP Settings (dhcpSettings) variable:

Property Enabled MAC Address Timeout, milliseconds

Description Enables/disables DHCP monitoring. Client hardware (MAC) address to be used in the request. (It should be a AggreGate server MAC address for most cases.) Timeout period to wait for the service to reply.

2000-2013 Tibbo Technology Inc.

AggreGate Server

165

3.5.9.14.2 DHCP Monitoring Results

DHCP monitoring results are presented by DHCP (dhcp) variable in the following format:

Property Successful Error Reply

Description Indicates that the DHCP request were successfully sent and a correct reply received. Error text, if any. IP address (a value in the yiaddr field of DHCP message -- refer to RFC 2131 for details) the service replied.

3.5.9.15 LDAP Monitoring

A directory service is a software system that stores, organizes and provides access to information organized in a directory. LDAP server is an element of the directory service that provides access to a portion of the directory using LDAP protocol. Lightweight Directory Access Protocol (LDAP) is an application protocol for querying and modifying data of directory services. LDAP server monitor provides availability and operability monitoring for directory services (including Microsoft Active Directory).

Synchronization Details
LDAP monitor executes the following synchronization procedure: 1. Connection to server is established using settings specified
165 .

2. Search request is constructed using specified context name and filter parameters, and executed. Example: Search with Context Name set to "cn=Users,dc=host,dc=domain,dc=com" in Microsoft Active Directory server should return children of "Users" node, i.e. users registered at the host.domain. com. Adding "cn=SQL*" as Query Filter will limit the result set to users having name started with "SQL". 3. Connection is closed. Service is deemed Online if all the operations are successfully executed; search results are saved. If an error occurs it is stored in monitoring result and service is marked as Offline.

3.5.9.15.1 LDAP Service Settings

LDAP monitor
165

uses the following settings presented by LDAP Settings (ldapSettings) variable:

Property Enabled Port Username Password LDAP Query Context Name LDAP Query Filter

Description Enables/disables LDAP monitoring. Port number the LDAP server can be connected on. User name utilized for authorization. Password used for authorization. Distinguished name of context to search in. The filter expression to use for the search (according to RFC 2254). The value may be null or empty, in which case it is just ignored by the search.

3.5.9.15.2 LDAP Monitoring Results

LDAP monitor saves search results in LDAP (ldap) variable as a table with the following fields:

Property Successful

Description Indicates that the LDAP search was successfully performed.

2000-2013 Tibbo Technology Inc.

166

AggreGate Documentation

Error LDAP Query Results

Error text, if any. A table presenting all the strings returned from server as an LDAP search result.

3.5.9.16 Radius Monitoring

Remote Authentication Dial In User Service (RADIUS) is a networking protocol that provides centralized Authentication, Authorization, and Accounting management for computers to connect and use a network service. RADIUS server is a computer program that can authenticate, authorize and account users or devices for accessing a network and certain services it provides. RADIUS monitor allows to check availability and basic operability of a RADIUS server by passing through its authentication procedure.

Synchronization Details
RADIUS monitor performs authentication procedure (see RFC 2138) using parameters specified in configuration settings 166 : an Access-Request is constructed and sent to monitored host. If a response is received within specified timeout period and the response packet type is Access-Accept the service is deemed Online. If an error occurs it is stored in monitoring results and service is denoted Offline.

3.5.9.16.1 Radius Service Settings

Radius service
166

uses the following settings presented by Radius Settings (radiusSettings):

Property Enabled Authentication Port Username Password Radius Secret Timeout, milliseconds

Description Enables/disables Radius monitoring. A port number used to send authentication request to. Authentication user name. Authentication password. A secret used by RADIUS protocol to obfuscate passwords. Timeout period to wait for the service to reply.

3.5.9.16.2 Radius Monitoring Results

The following fields are used to store RADIUS monitoring results presented by Radius (radius) variable:

Property Successful Error

Description Indicates that the LDAP search was successfully performed. Error text, if any.

3.5.9.17 WMI Monitoring

WMI support is provided by WMI device driver. Network Host device driver utilizes WMI driver and presents its features as a service. Refer to WMI device driver 186 section for details.

3.5.10 NMEA 0183

The NMEA Device Driver 129 allows AggreGate Server to retrieve data from GPS receivers and other equipment compliant to the National Marine Electronics Association (NMEA) 0183 standard.

SUPPORTED NMEA STATEMENTS

Global Positioning System (GPS) talker : GPGGA. Global Positioning System Fix Data. Time, Position and fix related data for a GPS receiver

2000-2013 Tibbo Technology Inc.

AggreGate Server
GPGLL. Geographic Position Latitude/Longitude GPGSA. GPS DOP and active satellites GPGSV. Satellites in view GPRMC. Recommended Minimum Navigation Information GPVTG. Track Made Good and Ground Speed Garmin Proprietary talker : PGRME . Estimated Position Error PGRMF. Position Fix Sentence PGRMT . Sensor Status Information PGRMV. 3D Velocity

167

CONFIGURING AGGREGATE SERVER FOR SERIAL COMMUNICATIONS

See Enabling Serial Communications
959

if you have troubles connecting to NMEA devices.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.nmea

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
CONNECTION SETTINGS
Connection settings define how AggreGate Server communicates with a certain NMEA device. These settings may be accessed using the Edit Device Properties 677 action of Device Context. The following connection properties are available: Property Port Baud Rate Incoming Flow Control Outgoing Flow Control Description Serial port name. Baud Rate. Incoming flow control type: None, CTS/RTS, or XON/XOFF. Outgoing flow control type: None, CTS/RTS, or XON/XOFF.

Device Settings
The following Device settings are provided by NMEA device driver:

NMEA DATA
This tabular setting contains values of all NMEA statement fields. It has the following format: Field Name Age Description Name of field Time passed since the value was received from the NMEA device. Note that age is time between receiving the value from the device and the last synchronization does not include time passed since the last synchronization. This effectively means that Age will increase if no NMEA data is being received or value of field
126 .

It

2000-2013 Tibbo Technology Inc.

168

AggreGate Documentation

became empty inside the most recent NMEA statements. Value Field value string (exactly as it appears inside an NMEA statement)

The below list shows supported field names and their positions inside NMEA statements: GPGGA,utc,latitude,northHemi,longitude,eastHemi,quality,numberOfSatellites,horDilution,height,, geoidalHeight,,diffCorrection,diffStationId, GPGLL,latitude,northHemi,longitude,eastHemi,utc, GPGSA,mode,fixtype,s1,s2,s3,s4,s5,s6,s7,s8,s9,s10,s11,s12,posDilution,horDilution,verDilution, GPGSV,gsvnum,gsvcur,satInView GPRMC,utc,status,latitude,northHemi,longitude,eastHemi,speedOverGroundKnots,courseOverGround, utcdate,magnVariation,magnVarDirection, GPVTG,courseOverGround,,magnCourse,,speedOverGroundKnots,,speedOverGround, PGRME,HPE,,VPE,,EPE, PGRMF,GPSWeek,GPSSeconds,utcdate,utc,GPSLeapSecondCount,latitude,northHemi,longitude,eastHemi, mode,fixType,speedOverGround,courseOverGround, PGRMT,GPSModel,romChecksum,recvFailure,storedDataLost,timeLost,oscillatorDrift,dataCollection, boardTemperature,boardConfig PGRMV,eastVelocity,northVelocity,upVelocity,

LOCATION
Device location: latitude and longitude.

Device Operations
No operations provided by the driver.

Device Events
No events provided by the driver.

Connection Handling
This driver makes the device Online if the serial port was opened successfully.

Synchronization Details
This driver constantly receives and parses NMEA statements pushed by the device. Any supported statement with valid checksum is stored by the driver internally to make the most recent data available at the time of next synchronization. During synchronization
126 ,

driver uses its internal data to fill in the NMEA Data table and Location setting.

3.5.11 OPC (OLE for Process Control)

OLE for Process Control (OPC) Device Driver 129 allows AggreGate Server to communicate with OPC Servers, i.e. act as OPC Client. Data provided by OPC Servers (and hardware devices "behind" them) is converted into unified form to allow access from different AggreGate facilities. See Devices 113 article for more information about the "normalized" representation of devices in Tibbo AggreGate. Unlike most OPC Clients which require the OPC Server and OPC Client to reside on the same computer, AggreGate Server communicates with OPC Servers using Distributed COM (DCOM) technology. It allows AggreGate Server to access OPC Servers via IP networks or the Internet. Another advantage of using DCOM is that AggreGate Server provides access to OPC Servers from operating systems other than Microsoft Windows, including Linux/Unix and Mac OS. AggreGate Server's OPC Driver supports the OPC Data Access specification. Support for other OPC Standards and Specifications, including OPC Alarm and Events, will be implemented in future versions of AggreGate. In order to allow AggreGate Server to access your OPC Server, it's necessary to configure DCOM service on the machine running it for remote access. See Configuring DCOM for Remote Access 1327 for information on this subject.

2000-2013 Tibbo Technology Inc.

AggreGate Server

169

OPC SERVER DISCOVERY

OPC device driver supports OPC server discovery. Discovery is the process of scanning a number of IP network hosts, finding available OPC servers, and creating device accounts for them. The comprehensive description of OPC server discovery is available in AggreGate SCADA/HMI documentation.

OPC ITEM QUALITY

The quality of OPC items is reported as status 871 of corresponding device setting variables. To check the status of a certain setting, open OPC device configuration in the Properties Editor and hold mouse over the setting status icon. Item quality will be shown in the tooltip:

To see the quality of all items at once, open Settings Synchronization Status tab of device status quality is shown in Synchronization Status column:

910

dialog. Item

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.opc

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
OPC SERVER CONNECTION PROPERTIES
Connection settings define how AggreGate Server communicates with a certain OPC Server. These settings may be accessed using Edit Device Properties 677 action of Device Context. Here is a list of available connection properties: Setting Host Domain User Password Application Class ID (CLSID) Description IP address or host name of OPC Server. Name of OPC Server's Windows Domain (optional). Name of Windows User Account used to access the OPC Server using DCOM. Password of Windows User Account. Class Identifier of the OPC Server. (E.g. F8582CF2-88FB-11D0-B850-00C0F0104305)

2000-2013 Tibbo Technology Inc.

170

AggreGate Documentation

Programmatic Identifier (PROGID) Timeout Group Name

Programmatic Identifier of OPC Server. (E.g. Matrikon.OPC.Simulation.1) Timeout for OPC server operations. Name of item group used for adding OPC items controlled by AggreGate Server. Should be set to Auto-generation in most cases.

It it sufficient to specify either CLSID or PROGID of the OPC Server, not both of them.

Device Assets
Hierarchical structure of assets provided by the OPC device driver exactly matches tree-like structure of OPC item groups.

Device Settings
OPC device driver creates one Device setting variable for every OPC server item.

TYPE CONVERSION
The following table shows how OPC types are converted to AggreGate types OPC Type VT_BOOL VT_BSTR VT_NULL VT_EMPTY VT_INT VT_I1 VT_I2 VT_I4 VT_UI1 VT_UI2 VT_UI4 VT_DECIMAL VT_DATE VT_I8 VT_R4 VT_R8 VT_CY AggreGate Type Boolean String String String Integer Integer Integer Integer Integer Integer Integer Integer Date Float Float Float Float
856 :

Device Operations
No operations provided by the driver.

Device Events
No events provided by the driver.

Connection Handling
This driver makes the device Online if:

2000-2013 Tibbo Technology Inc.

AggreGate Server
TCP connection to an OPC server was successfully established DCOM authorization did not fail

171

Synchronization Details
OPC Servers are synchronized 126 with AggreGate Server like any other Devices. Synchronization between AggreGate Server and OPC Server includes the following steps: Reading information about settings provided by OPC Server and creation of Settings Cache into several groups, according to OPC Server's internal division. Reading OPC Server setting values and storing these values in settings cache.
115 .

Settings are divided

OPC Server Status

View Device Status Bandwidth Build Number Current Time Group Count Last Update Time Major Version Minor Version Server State (Available states are: Communication Failure, Failure, Configuration Error, Running, Suspened, Test and Unknown) Server State Code Start Time Vendor Information
910

action of OPC Server's Device Context provides additional information about OPC Server status:

3.5.12 SMB/CIFS (Shared Resource Monitoring)

SMB/CIFS Device Driver 129 provides monitoring for files and folders shared via Server Message Block (SMB) technology that's also referred as Common Internet File System (CIFS) or Microsoft Windows Network.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.samba

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
SMB/CIFS device account is configured by the following properties: Field Name Address Path Read Contents Recursive Field Description IP Address or host name of the SMB server. Location (full path) of a remote file or folder to be monitored. Enables/disables reading of the file contents. Enables/disables recursive reading for folders.

2000-2013 Tibbo Technology Inc.

172

AggreGate Documentation

Incremental Reading

Switches between reading the whole file and incremental reading. Incremental reading is ideal for log file analysis. If it's enabled, the server remembers previous file size and, during the next synchronization cycle, reads data starting from the previous end point to the end of file. If the file size has not grown since the previous cycle, no reading is performed. If file size has decreased, the reading is restarted from file start (this is suitable to handle log file rotation. Maximum number of bytes that the server will read if incremental reading is enabled.

Maximum Read Size

Backlog Read Size Number of bytes to include from previous steps of incremental reading. Allow Editing Calculate Checksum Enable Authentication Username Password Allows or prohibits modification of the file contents. Enables/disables file checksum calculation. Enables/disables access to password-protected resources. Username to use for authentication. Password to use for authentication.

Device Settings
SMB/CIFS device driver creates the following Device setting variables: Variable Name attributes Variable Description File Attributes Comments This variable is created only if Path points to a file. Contains the file attributes: Last Modification Time (modificationTime) Size (size) Checksum calculated using Adler-32 algorithm ( checksum) attributes Folder Attributes This variable is created only if Path points to a folder. Contains the folder attributes: Last Modification Time (modificationTime) Size (size) File Count (fileCount) contents File Contents This variable is created only if Path points to a file. It contains read-only (if Read Contents 143 option is on) or editable (if Allow Editing 143 option is also on) file contents. contents Folder Contents This variable is created only if Path points to a folder. List of folder items (files and subfolders) with the following fields: Type (itemType) Relative Path (itemPath) Size (itemSize)

Device Operations
No operations provided by the driver.

Device Events
No events provided by the driver.

2000-2013 Tibbo Technology Inc.

AggreGate Server

173

Connection Handling
The SMB/CIFS device will be deemed online if the following steps was successfully completed: Connection to the remote server was established Authentication was successful (if enabled) The remote resource specified by Path setting exists and is available All I/O operations with the resource (e.g. file/folder content reading or writing) was successfully completed

Synchronization Details
During synchronization
126

of an SMB/CIFS device with the server, the following operations are performed:

If the Path points to a file, attributes and (optionally) contents of the file are obtained If the Path points to a folder, attributes of the folder and list of files located in this folder and (if Recursive is enabled) its subfolders are retrieved If editing is allowed and a user has edited server-side copy of file contents, the new contents are written to the file

3.5.13 SNMP (Simple Network Management Protocol)

The SNMP Device Driver 129 provides communications via Simple Network Management Protocol (SNMP ) allowing to exchange management information with SNMP-compliant network devices. All versions of SNMP protocol (v1, v2(c) and v3) are supported including secure communications introduced in SNMP version 3. Like with all other types of devices, data collected from SNMP devices is converted into unified form to allow accessing them from different AggreGate facilities. See Devices 113 article for more information about the "normalized" representation of devices in Tibbo AggreGate. There are two basic SNMP monitoring methods described further in this section: polling 178 ) monitoring 178 . Refer to SNMP Global Settings
178 175

and event (

178 Trap/Inform

subsection for details about global settings used by SNMP service.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.snmp

Global Settings
See SNMP Global Settings
178 .

User Level Settings

None defined.

Device Properties
Device properties define SNMP communication parameters for the particular device. They comprises: Host Address (address) property that specifies IP Address or Host Name of the network host to be monitored Polling Settings
176

that are used to periodically obtain current status of the SNMP device (poll

175

it).

Device Assets
The driver creates one root asset for every MIB file supported by the device. Supported MIB files are detected automatically by polling the SNMP agent. Assets for MIBs that are marked as Default in MIB Directory will be enabled automatically.

Device Settings
SNMP device settings present results of the last polling operation
176 .

2000-2013 Tibbo Technology Inc.

174

AggreGate Documentation

Device Operations
Get SNMP Variables. This operations serves for pulling values of raw SNMP OIDs from the device. The connection settings defined in device account are used. Set SNMP Variables. This operations serves for pushing values of raw SNMP OIDs into the device. The connection settings defined in device account are used.

Device Events
SNMP devices generate two different types of events: Service Outage (indicating SNMP downtime as described in Network Host device driver 152 chapter) and SNMP notification (see below).

SNMP NOTIFICATION
SNMP driver generates events on reception of SNMP notifications (both traps and informs). Refer to SNMP Notifications Monitoring 178 section for details. Since SNMP driver listens for the notifications from all network hosts (not only hosts that match to a certain Device account 113 ), the Trap events are generated in the Network Management context instead of Device context 677 .

Event Name Permissions Records

trap

Accessible at User permission level 1

932

The trap event has the following format: Field Name Field Type
String String String String

Notes

agentAddress version type enterprise

SNMP Agent Address, i.e. IP address of the object generating the trap. Trap version. Trap type (Trap or Inform). Enterprise. Corporation or organization that originated the trap. This is the object identifier (OID) assigned to the vendor implementing the agent. Equals to the value of the sysObjectID variable, and it is unique for each implementer of an SNMP agent. Generic Trap Type ID. Integer, see table below. Specific Trap Type ID. Defined when Generic Trap Type is set to Enterprise. Trap OID.

genericTrap specificTrap oid

Integer Integer String

timestamp

Date

Elapsed time, in hundredths of a second, from the last reinitialization of the agent to the event generating the trap. Variable Bindings. Extra information, dependent on generic-trap type.

variableBindin gs engineID

Data Table String

SNMP engine ID of the trap originator.

The following Generic Trap Type ID values are defined for genericTrap field: Value 0 Name coldStart Description The agent is reinitializing. Configuration data or MIB variable values, or both, might have changed. Restart the measurement epochs.

2000-2013 Tibbo Technology Inc.

AggreGate Server

175

1 2 3 4 5 6

warmStart linkDown linkUp authenticationFailur e egpNeighborLoss enterpriseSpecific

The agent is reinitializing but configuration data or MIB variable values have not changed. The agent has detected that a known communications interface has been disabled. The agent has detected that a known communications interface has been enabled. A message was received that could not be authenticated. An Exterior Gateway Protocol (EGP) neighbor was lost. Vendor-specific trap. Specific Trap Type ID should be defined.

Connection Handling
This driver makes the device Online if SNMP polling operation reports no errors.

Synchronization Details
The synchronization procedure executes SNMP polling operations, refer to SNMP polling
175

section for details.

3.5.13.1 Network Host SNMP Polling

SNMP polling refers to synchronous process of sampling the status of an external device using SNMP get operations. SNMP polling is implemented by AggreGate as Device synchronization
126

procedure.
176

The synchronization procedure uses parameters specified in SNMP Settings two types of synchronization that can be applied to monitored devices.

to perform SNMP operations. There are

FULL SNMP SYNCHRONIZATION

Full SNMP synchronization includes the following steps: Checking SNMP communication with the monitored device. This is performed by connecting to the device and sampling one SNMP variable. Reading device metadata and variable values by performing SNMP Walk. SNMP walk is an operation that uses SNMP GETNEXT requests to query all the variable available at the monitored device and their values. Correlating obtained metadata with MIB Files Directory type, description etc.). entries to get more information about each setting (its
869

178

Converting SNMP device settings into AggreGate Server Context Variables Storing obtained data in settings cache. Refer to SNMP Polling Results monitoring results are presented by device driver driver.
176

and creating the Settings Cache

115 .

section for detailed description of how SNMP

The SNMP monitoring service is considered Online if all operations are successfully performed. Any error encountered during synchronization is saved in monitoring results and renders the service Offline. Notice that SNMP walk operation provides a list SNMP variables along with their values. Thus no additional steps are required to synchronize particular variables. On the other hand, SNMP walk is a long operation. Therefore it is not performed during the very first device synchronization. Thus, service just checks that SNMP communications is supported by the managed device and quickly reports the result as service status. Full synchronization is issued right after the first synchronization completes. This method eliminates long synchronization delays for newly added devices.

PARTIAL SYNCHRONIZATION
If there is no need to re-read all the device metadata and merely several known variables should be refreshed full synchronization is not performed. Instead, only these variables are polled using SNMP get operations and device cache is updated accordingly.

2000-2013 Tibbo Technology Inc.

176

AggreGate Documentation

3.5.13.1.1 SNMP Polling Settings

The following settings are used to poll Setting Protocol Port SNMP Protocol Version Read Community Write Community Description Communication protocol (UDP or TCP). Port number on SNMP Agent. Version of SNMP protocol to use. Name of SNMP Community to use during read operations. Commonly used name is public. Name of SNMP Community to use during write operations. Commonly used name is private.
175

SNMP devices:

Command Retries Number of request retries to be send before SNMP operation fails. Command Timeout, milliseconds Maximum PDU size, bytes Data To Process Timeout for SNMP requests.

Maximum size of Protocol Data Unit (PDU) sent by AggreGate Server. Commonly used values are 484 (should be supported by any SNMP device) and 1472 (supported by most devices). Defines, what kind of SNMP variables should be read and processed. The allowed values are: Value All values available in MIB directory All values found by SNMP walk (slow!) Description Only the values whose descriptions are found MIB Files Directory used. All unrecognized SNMP OIDs will be ignored.
178

are

All the values found during SNMP walk operations will be used. This may slow synchronization operation and increase server memory utilization.

Initial OID Security Level

An OID used to check device availability (connection status) and initiate SNMP walk operations during device synchronization. By default, this is .1.3.6. SNMP v3 security configuration. There are three available security levels: Authentication disabled, privacy (encryption) disabled Authentication enabled, privacy (encryption) disabled Authentication enabled, privacy (encryption) enabled

User Name Authentication Protocol Authentication Password Privacy (Encryption) Protocol Privacy (Encryption) Passphrase

User name for SNMP v3 authentication and privacy (encryption). MD5-based authentication or SHA-based SNMP v3 authentication. Password for SNMP v3 authentication. DES-based encryption or AES-based encryption for SNMP v3 .

Password for SNMP v3 encryption.

3.5.13.1.2 SNMP Polling Results

SNMP polling operation status is presented by SNMP (snmp) variable with the following fields:

Field Successful

Description Indicates that SNMP communications are supported by the managed device and last synchronization procedure was successful.

2000-2013 Tibbo Technology Inc.

AggreGate Server

177

Error

Text of error encountered during the last synchronization.

SNMP polling results are presented as Device setting variables according to the following rules: If a group of OIDs represent SNMP Table, one tabular device setting variable is created for them. In all other cases, one device setting variable is created per OID.

Device Setting Variable Names

Device setting variable names for SNMP variables are constructed by the following rules: If a MIB symbol is found for a certain OID, device setting name equals to MIB symbol name (ex.: sysDescr, hrStorageTable). If no MIB data is found for an OID, device setting name equals to OID itself. Dots are substituted by underscores to make a valid name (ex.: 1_3_6_1_2_1_5_27_1_5_2_0).

Device Setting Variable Descriptions

Device setting variable descriptions for SNMP variables are constructed by following rules: If a relevant MIB file is found for an OID, description constructed in accordance with Variable Descriptions defined for this MIB file.
178

setting

If full MIB data is not found, variable description includes symbolic name for recognized part of OID followed by numeric unrecognized part. Full variable OID is also included in parentheses. For example: iso.org.dod.

internet.mgmt.mib-2.icmp.27.1.5.1.0

(1.3.6.1.2.1.5.27.1.5.1.0)

Device Setting Variable Grouping

Device setting variables are grouped by MIB filed the corresponding OIDs are defined in. Setting variables corresponding to OIDs not found in MIB directory are put into Unrecognized SNMP OIDs group.

SNMP Type to AggreGate Conversion

SNMP types are converted to AggreGate types SNMP Type OctetString Counter32 Counter64 Integer (Integer32) UnsignedInteger32 (Gauge32) Counter32 IpAddress TimeTicks DateAndTime Object Identifier
856 ,

as described in the following table:

AggreGate Type String Long String Integer Long Long String Long Date String

2000-2013 Tibbo Technology Inc.

178

AggreGate Documentation

3.5.13.2 SNMP Notifications Monitoring

SNMP notifications are asynchronous notifications sent from SNMP agent to manager.

There are two types of notification requests defined by SNMP standards: Trap requests and Inform requests. Both types of notification requests are supported by AggreGate Network Manager. SNMP notifications monitoring is controlled by global configuration 178 options of SNMP driver. Listening for notifications is enabled by turning on Receive SNMP Notifications option. If this option is enabled, AggreGate Server listens for SNMP notifications on the specified port (see SNMP Notifications Listening Port). Notifications will be received from any SNMP device either via UDP or TCP protocol depending on the SNMP Notifications Transport Protocol. For SNMP version 3 secure notifications the specified Local Engine ID will be used. SNMP driver may receive SNMP notifications from SNMP agents and converts them to context events here 152 . Record associated with the AggreGate event presents notification's properties.
880

as described

SNMP notification event's data can be used to monitor important events on your network, analyze them and react accordingly.

3.5.13.2.1 SNMP Notifications Monitoring Global Configuration

SNMP driver includes the following global SNMP notifications monitoring settings: Field Receive SNMP Notifications SNMP Notifications Transport Protocol SNMP Notifications Listening Port Local Engine ID Description When enabled, AggreGate Server receives SNMP notifications and generates trap events. Protocol used to deliver SNMP notifications: UDP or TCP. Port number used to listen for SNMP notifications. Local engine ID for SNMP version 3 notifications.

3.5.13.2.2 SNMP Notifications Sources Automatic Discovery

SNMP driver includes the SNMP Notification Sources Automatic Discovery option. When this option is enabled AggreGate Server will automatically discover all the devices sent SNMP traps. Network Discovery plugin should be loaded. See SNMP Notifications 178 for details of SNMP notifications monitoring.

3.5.13.3 SNMP Global Settings

SNMP driver includes the following global SNMP settings: SNMP Notifications Monitoring MIB Files Directory SNMP Users Table
178 179 178 178

settings

table

SNMP Trap Sources Automatic Discovery

setting

3.5.13.3.1 MIB Files Directory

SNMP agents do not provide full meta information about their properties (SNMP object identifiers). Most data necessary to present settings of SNMP devices is exctacted from Management Information Base (MIB) files. MIB (Management Information Base) files contain detailed information about objects provided by SNMP devices. SNMP Device driver has a built-in repository of MIB files. MIB Files Directory table allows to manage this repository. This table has the following fields:

2000-2013 Tibbo Technology Inc.

AggreGate Server

179

Field SNMP Variable Name MIB File Variable Descriptions

Description Description of a MIB file. MIB file data. Defines how descriptions of device setting variables are formed. There are three choices: By MIB symbol name (default) By first sentence of MIB symbol description (sentences are assumed to be delimited by dots) By first line of MIB symbol description Correct value of this setting depends on the structure of MIB file and may be different for MIB files of different hardware manufacturers. The default value of this setting shows names of MIB symbols in variable descriptions, but it's always possible to see the full symbol descriptions by checking variable help (detailed description). This help is usually shown in tooltips in AggreGate Server User Interfaces. Here is an example screenshot from AggreGate Client 776 :

Enabled

If this option is off, MIB file is not loaded on server startup and not used to obtain information about device settings. If other MIB files depend to the disabled MIB file, their loading may fail.

Default Loaded Load Errors

If this option is on, MIB is denoted as default. It will be enabled automatically in assets list. Read-only flag indicating whether the MIB was loaded successfully and is being used by the driver. This field contains MIB loading and compilation errors, if any.

The MIB files that are denoted as loaded in this table are actually used by SNMP driver to get information about SNMP device settings and traps.

Built-In MIB Files

There are more than two hundred of MIB files that are essential for SNMP monitoring and therefore are bundled with AggreGate Server distribution. They contain information about MIB objects of frequently monitored SNMP devices, such as routers, servers, network printers etc.

MIB Files Auto Loading

SNMP Device driver may automatically load one or more MIB files from the disk drive and add them to the MIB Database during AggreGate Server startup. To activate this function, put your MIB files into the /mib subdirectory of AggreGate Server installation and start/restart the server. MIB files will be added to the MIB database and used by the driver.

3.5.13.3.2 SNMP User Table

SNMP User Table presents a user security database used to communicate via SNMP version 3 protocol. As specified by SNMPv3 standards, user information is referenced by a combination of the Username (also called a "security name") and Engine ID, identifying an authoritative SNMP application in the conversation.

2000-2013 Tibbo Technology Inc.

180

AggreGate Documentation

The information in the SNMP User Table is presented in the following format: Field Username Authoritative Engine ID Security Level Description User name Engine ID. This field can be left blank. In that case AggreGate Network Manager will try to discover it as specified by SNMPv3 standard. One of the three standard security levels: Authentication disabled, privacy (encryption) disabled Authentication enabled, privacy (encryption) disabled Authentication enabled, privacy (encryption) enabled Authentication Protocol Authentication Password Privacy (Encryption) Protocol Privacy (Encryption) Password MD5-based or SHA-based SNMPv3 authentication. Password for SNMPv3 authentication. DES-based or AES-based SNMPv3 encryption.

Password for SNMPv3 encryption.

3.5.14 SQL Database

The SQL Database driver provides a method of monitoring any JDBC-compliant Database Management System (DBMS). Almost all modern database servers provide a Java Database Connectivity drivers, and thus may be monitored and controlled by AggreGate. The driver has the following capabilities: Checking database server availability and status; Executing selection queries and providing access to query results;

2000-2013 Tibbo Technology Inc.

AggreGate Server
Executing dynamically generated insert/update/delete queries.

181

It's necessary to add at least one "probe" query to ensure database operability checking. If no queries were added, the driver will establish connection upon the first synchronization cycle 126 and do nothing during subsequent synchronizations, providing no reliable database availability and operability data. It's always possible to use a very simple test query, such as SELECT 1 or SELECT 1 FROM table.

Adding Database JDBC Drivers

To allow AggreGate Server to load a third-party JDBC database driver supplied by your database server vendor, a JAR (Java Archive) file containing this driver must be added to the server classpath by putting it into /lib subdirectory of AggreGate Server installation or using AggreGate Server Launcher Properties File 45 . SQL Database driver can be also used to connect to Open Database Connectivity (ODBC) data sources via a JDBC-ODBC bridge that is a part of AggreGate Server installation. No additional drivers should be added in this case. The Database URL syntax to use is jdbc:odbc:odbc_data_source_name.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.database

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
DATABASE CONNECTION PROPERTIES
Property Database URL Description This is a database-specific string that defines the database type, the path (local or network) to a database to execute queries on and any additional options. To figure out the correct value for your selected JDBC database driver, please consult its documentation. This property defines which username is used to log on to the database server. This property defines which password is used to log on to the database server. Table containing advanced properties of database connection. The table has two columns: Property and Value . The list of supported properties can be found in JDBC driver documentation.

Database Username Database Password Additional Properties

QUERIES
This is a tabular setting defining what queries will be executed using a database server. Field Name Description Expressions Read Query Description Name of device setting variable containing query result. Description of device setting variable containing query result. Forces treating Read Query and Write Query fields as expressions resolve to actual SQL query strings.
911 .

These expressions must

Text of SQL selection query, or expression text if Expressions flag is set. Read query execution result will be accessible within AggreGate as a device setting variable.

Write Query

Text of SQL insert/update/delete query, or expression text if Expressions flag is set. If this field is non-empty, variable containing Read Query execution result will be writable (editable). Its modification will trigger execution of the Write Query.

2000-2013 Tibbo Technology Inc.

182

AggreGate Documentation

If Write Query is an expression, it may refer to the Data Table containing Read Query result. This is a default table for references 925 inside this expression.

Device Settings
Database device driver creates one device setting variable per Queries table record. Format of this variable is dynamic, depending on the result of Read Query execution. In addition, Database Statistics variable is created with the following fields: Database Name Database Version Database Driver Name Database Driver Version

Device Operations
EXECUTE QUERY
This action lets you execute an arbitrary query on the database. Both select and update queries are supported.

Device Events
No events provided by the driver.

Connection Handling
This driver makes the device Online if JBDC connection to the database was established successfully.

3.5.15 Virtual Device

Virtual Device driver is a Device Driver 129 used to create and manage virtual devices, i.e. ones that are not associated with any real hardware but are interpreted by AggreGate as such. Every virtual device is represented by a Device Context 677 and provides a number of settings (the variables of this context), operations (the functions and actions of this context) and events. A virtual device is very useful during testing, debugging and learning about the system, as it behaves similarly to any real hardware device connected to the system.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.virtual

Global Settings
None defined.

User Level Settings

None defined.

Device Settings
The virtual device provides different types of settings to help with testing Alerts 216 , Reports system features. Here is a list of available settings (variables 869 of Device Context):
241 ,

Widgets

312

and other

BASIC PROPERTIES
Setting (Variable) Name normal readonly selvals Comments

Standard string setting. Read-only string setting. String setting with selection values.

2000-2013 Tibbo Technology Inc.

AggreGate Server

183

eselvals nullable

String setting with extensible selection values. Nullable string setting.

SETTINGS OF DIFFERENT TYPES

Setting (Variable) Name string int boolean float date table Comments

String setting. Integer setting Boolean setting. Floating point setting. Date setting. Tabular setting with two fields (Integer and String) and unlimited number of records.

LOCATION
Setting (Variable) Name track Comments

GPS track in GPX format. This track will be "replayed" by the device, meaning that a new waypoint (taken from the first track found in the file) will be written into Location setting upon every synchronization. Simulated location of the device (latitude and longitude). The location is undefined if GPS track was not loaded or its "replay" was ended.

location

WAVE SETTINGS
Read-write settings in these group define how different read-only values in Waves group are generated (period, amplitude, etc.). Setting (Variable) Name sawtoothSettings triangleSettings squareSettings sineSettings randomSettings Comments

Sawtooth wave generator settings. Triangle wave generator settings. Square wave generator settings. Sine wave generator settings. Random value generator settings.

WAVES
Setting (Variable) Name sawtooth triangle square sine random Comments

Sawtooth wave generator. Triangle wave generator. Square wave generator. Sine wave generator. Random value generator.

ERROR GENERATORS

2000-2013 Tibbo Technology Inc.

184

AggreGate Documentation

Setting (Variable) Name shouldGenerateEr ror errorGenerator

Comments

Should Generate Error. This setting define whether errors occur while reading/writing the Error Generator setting. Error Generator. Read/write operations on this setting may fail depending on the value of Should Generate Error setting.
677

Here is what virtual device configuration (see Configure Client:

action in Device Context for details) looks like in AggreGate

Device Operations
GENERATE EVENT
Virtual device context has generateEvent function and corresponding Generate Event Call Function 903 action that calls this function. Format of this function has three fields: String type field, String str field, and Integer int field. This function just generates the event with name specified by type field (Event 1 or Event 2, see below). Values of fields in event data are taken from input parameters of function.

CALCULATE
calculate function and corresponding Calculate Call Function 903 action provide a test environment for performing simple operations (addition, subtraction, multiplication or division) over two arguments. Format of this function has three fields: Float leftOperand field, Float rightOperand field, and String operation field. This function returns a Data Table with a single record and Float result field.

Device Events
The virtual device context has two events 880 called event1 (its description is Device Event #1) and event2 (Device Event #2). Format of these event has two fields: String field str and Integer field int . These events and generateEvent function may be used together to test Device operations and events.

Connection Handling
A virtual device is always deemed Online.

3.5.16 WebSphere MQ
The WebSphere MQ Device Driver 129 allows AggreGate Server to perform monitoring of IBM WebSphere MQ server operability. The monitoring is performed via the native MQ communication protocol over an IP network.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.mq

2000-2013 Tibbo Technology Inc.

AggreGate Server

185

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
CONNECTION SETTINGS
Connection settings define how AggreGate Server communicates with an MQ server. These settings may be accessed using the Edit Device Properties 677 action of Device Context. The following connection properties are available: Property IP address or host name Port Channel Timeout Description Address of the MQ server. Port to connect on the MQ server (default is 1414). Name of MQ channel to connect (default is ADMIN.CONN). Operation timeout (default is 30 seconds).

Device Settings
The MQ device driver provides three tabular read-only settings: Channels. This table contains information about every channel provided by MQ server, including channel name, type, status, start time and incoming/outgoing traffic volume. Queues. This table contains information about every queue provided by MQ server, including queue name, depth, last get/put time, maximum and average message ages, counts of open inputs/outputs, and number of uncommitted messages. Listeners. This table contains information about every listener provided by MQ server, including listener name, description, status, start time, backlog, and command/session counters.

Device Operations
No operations provided by the driver.

Device Events
No events provided by the driver.

Connection Handling
This driver makes the device Online if connection with MQ server was successfully established.

Synchronization Details
Synchronization between AggreGate Server and MQ server includes the following steps: Reading the list of channels available on the MQ server and fetching information about each individual channel. Reading the list of queues available on the MQ server and fetching information about each individual queue. Reading the list of listeners available on the MQ server and fetching information about each individual listener.

2000-2013 Tibbo Technology Inc.

186

AggreGate Documentation

3.5.17 WMI (Windows Management Instrumentation)

Windows Management Instrumentation Device Driver 129 allows AggreGate Server to manage Microsoft Windows computers. Like with all other types of devices, data collected via WMI is converted into unified form to allow access from different AggreGate facilities. See Devices 113 article for more information about the "normalized" representation of devices in Tibbo AggreGate. WMI device driver allows AggreGate Server to monitor and manage WMI-enabled computers remotely from any, even non-Windows platform. All the communications are provided using Distributed COM (DCOM) technology. With AggreGate Server's WMI driver, you can: read and write properties of WMI objects fetch information using WMI Query Language (WQL) request call methods provided by WMI objects subscribe for WMI events. In order to monitor/manage a WMI computer, you should configure remote access to WMI service on that machine. See Configuring Remote Access to WMI 189 for information on this subject.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.wmi

Global Settings
None defined.

User Level Settings

None defined.

Device Properties
CONNECTION PROPERTIES
Connection settings define how AggreGate Server communicates with a certain WMI computer. These settings can be accessed using Edit Device Properties 677 action of the Device Context. Here is a list of available connection properties: Setting Address Domain User Password Namespace Asset View Description IP address or host name of a WMI computer. Windows Domain name (optional). Name of Windows User Account used to access WMI via DCOM. Password of the Windows User Account. A WMI namespace. Driver supports two types of asset view representation: Flat view, i.e. a plain list of WMI classes available at the device. Tree view representing hierarchy of WMI classes. To apply this option for an existing device, you should invoke Reset Device Driver action.

Timeout

Timeout for WMI operations.

WQL REQUESTS
The WQL Requests table defines queries that can be used to retrieve fine-grained information from WMI device: certain properties of objects or objects that meets specified conditions.

2000-2013 Tibbo Technology Inc.

AggreGate Server

187

Setting Name Description Expressions WQL Request

Description Request name. Request description. Forces treating WQL Request field as expression query string. WQL query text.
911 .

This expression must resolve to a WQL

WQL EVENT REQUESTS

The WQL Event Requests table defines queries that are used to subscribe to WMI events. Setting Name Description Expressions WQL Request Description Request name. Request description. Forces treating WQL Request field as expression query string. Text of WQL event query.
911 .

This expression must resolve to a WQL

Device Assets
For each WMI class driver creates an asset of the same name. By enabling an asset, user asks driver to fetch all the instances of a corresponding class. Most assets are disabled by default, just few often-used classes are enabled.

Some WMI classes may have thousands or even millions of instances. Enabling these classes may cause device synchronization slowdown and exceeding resource consumption. Use WQL requests to fetch data precisely.

Device Settings
WMI device driver creates Device setting variables as follows: For each enabled asset (WMI class) it creates a variable of the same name. For each query defined in WQL Requests table it creates a variable of the same name. The WMI Event variable that stores information about WMI event subscriptions is created.

Device Operations
WMI driver creates a Device context function and a corresponding action for every method provided by enabled WMI classes. These actions are grouped by class names. When invoked, WMI action requests object path and method parameters, then calls the method for the object, converts output and displays it as a result table.

Device Events
WMI driver allows to monitor WMI events. Subscription for WMI events is performed by adding WQL Event Requests in Device properties. Driver subscribes for and/or unsubscribes from event notifications when this table is changed.

Connection Handling
WMI driver makes the device Online if: connection to a DCOM server on the specified computer using user name, domain and password provided is established access to the specified WMI namespace is acquired using the DCOM connection.

Synchronization Details
WMI devices are synchronized steps:
126

with AggreGate Server like any other Devices. Synchronization includes the following

2000-2013 Tibbo Technology Inc.

188

AggreGate Documentation

Reading assets definitions (if they were not read yet or were reset). Each asset element relates to a WMI class of the same name.

Device metadata acquisition: o For each enabled asset driver fetches definition of a corresponding WMI class including its properties and methods specifications. o For each query specified in the WQL Requests table driver creates a variable that will contain results. o Adds a WMI Events variable that controls all WMI event subscriptons specified in the WQL Event Requests table. Reading/writing device settings: o Driver reads properties of all instances for classes defined by assets. o Writes changed properties of WMI objects back to managed device. o Executes all WQL requests putting fetched data in the query variables. o Manages WMI event subscription according to the WMI Event variable.

WMI Data Conversion

WMI objects are converted to AggreGate tables as follows: A table comprises data of one or several (array of) WMI objects. Each object is presented by a single data record. The table contains the Object Path field that identifies object using its path in WMI namespace. Other fields in the table reflect properties of the WMI object. The following table shows how WMI types are converted to AggreGate types 856 and vice versa: WMI Type Unsigned 8-bit integer Signed 8-bit integer Unsigned 16-bit integer Signed 16-bit integer Unsigned 32-bit integer Signed 32-bit integer Unsigned 64-bit integer Signed 64-bit integer UCS-2 string Boolean IEEE 4-byte floating-point IEEE 8-byte floating-point Datetime Reference 16-bit UCS-2 character Object Arrays AggreGate Type Integer Integer Integer Integer Integer Integer Long Long String Boolean Float Double Date String String Data Table Data Table

Class and property qualifiers (Key, Write, Abstract, etc.) are used to refine conversion.

2000-2013 Tibbo Technology Inc.

AggreGate Server

189

3.5.17.1 Configuring Remote Access to WMI

Follow the steps presented below to configure WMI for remote access.

Configure DCOM
WMI uses DCOM to handle remote calls. Therefore, DCOM should be accessible remotely for the specific user. Refer to Configuring DCOM for Remote Access 1327 for details.

WMI Namespace Access Settings

Go to Control Panel > Administrative Tools > Computer Management > Services and Applications. Right-click WMI Control and select Properties. Select the Security tab and click the Security button. Add the monitoring user account and check all the needed permissions (including the Remote Enable ). Make sure that the security settings for WMI namespaces are inherited from Root. Alternatively, you can configure security for particular namespaces.

Allow WMI through Windows Firewall

If the WMI server is running Windows Firewall, then you need to tell it to let remote WMI requests pass through. This can only be done from the command prompt:

netsh firewall set service RemoteAdmin enable

WMI Impersonation Rights

Start Group Policy Editor console by clicking Start , then Run, typing gpedit.msc, and then clicking OK. Under Local Computer Policy, expand Computer Configuration, and then expand Windows Settings. Expand Security Settings, expand Local Policies, and then select User Rights Assignment. Make sure that Impersonate a client after authentication rights is granted for SERVICE account .

Registry Permissions
Set full access permissions for the WMI monitoring user to the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet \Control\SecurePipeServers\WinReg branch. If WMI device synchronization with a Windows server fails for a with an Access Denied error, do the following on the remote machine: Run Registry Editor ('regedit.exe'). Find registry key: 'HKEY_CLASSES_ROOT\CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}'. Right-click it and select 'Permissions'. Change key owner to ' administrators' group. Give 'Full Control' permission for 'administrators' group. Change key owner back to TrustedInstaller ("NT

Service\TrustedInstaller")

Repeat the above operations for all registry keys named {76A64158-CB41-11D1-8B0200600806D9B6} (e.g. HKEY_LOCAL_MACHINE\Software\Classes\Wow6432Node\CLSID \{76A64158-CB41-11D1-8B02-00600806D9B6} and all other). Those keys can be found by searching the registry. Restart "Remote Registry" service.

Reinitializing WMI Provider to Get Access to Missing Information

In some rare cases WMI performance counters (this is known to happen with Microsoft Exchange 2003 counters) may not be available via WMI because WMI provider uses AutoDiscovery/AutoPurge (ADAP) to build its internal performance counter table. If the services providing the counters are not started when the WMI ADAP process is started, the performance counters are not transferred to WMI. To work around this problem, you can run the wmiadap.exe /f command to force the transfer of all the performance libraries. To do this, follow these steps:

2000-2013 Tibbo Technology Inc.

190

AggreGate Documentation

Click Start , click Run, type cmd, and then click OK. At the command prompt, type wmiadap.exe /f, and then press ENTER. Type exit, and then press ENTER to close the command prompt.

3.5.17.2 Mass-enabling Remote Access to WMI

When deploying AggreGate in large networks, it's often necessary to enable WMI on hundreds or even thousands of workstations. This article is a step-by-step instruction for that. There are two top-level operations to be completed: 1. Setting up Group Policies 2. Running a WMI configuration script

1. Setting Up Group Policies

The group policies are created and configured on a Domain Controller machine.

2.1 ENABLE SERVER AND REMOTE REGISTRY SERVICES

Use group policies to enable Server and Remote Registry Services.

2.2 ENABLE DCOM ACCESS

Use group policies to enable DCOM access. 2.2.1. Double click on a DCOM: Machine Access Restrictions policy, then use Edit Security button to add a user those credentials will be used for monitoring. Give this user Remote Access permissions.

2000-2013 Tibbo Technology Inc.

AggreGate Server

191

2.2.2. Double click on a DCOM: Machine Launch Restrictions policy, then use Edit Security button to add a user those credentials will be used for monitoring. Give this user Local Launch, Remote Launch , Local Activation, and Remote Activation permissions.

2000-2013 Tibbo Technology Inc.

192

AggreGate Documentation

2.2.3. Double-click Network access: Sharing and security model for local accounts policy, select Classic users authenticate as themselves from a drop-down list.

2000-2013 Tibbo Technology Inc.

AggreGate Server

193

2.3 CONFIGURE OR DISABLE WINDOWS FIREWALL

Reconfigure Widows Firewall using group policies if necessary. In some cases, Windows Firewall is configured to block the DCOM protocol. Make sure that Windows Firewall does not block DCOM protocol or is disabled.

2.4 DISABLE USER ACCOUNT CONTROL (UAC)

When User Account Control (UAC) is active, an administrator account actually has two security tokens, a normal user token, and an administrator token (which is only activated when you pass the UAC prompt). Unfortunately, remote requests that come in over the network get the normal user token for the administrator, and since there is no way to handle a UAC prompt remotely, the token can't be elevated to the true-administrator security token. Thus, UAC should be disabled via group policies to allow remote DCOM access. 2.4.1. Set User Account Control: Behaviour of the elevation prompt for administrators in Admin Approval Mode policy to Elevate without prompting

2000-2013 Tibbo Technology Inc.

194

AggreGate Documentation

2.4.2. Set User Account Control: Detect application installations and prompt for elevation policy to Disabled

2000-2013 Tibbo Technology Inc.

AggreGate Server

195

2.4.3. Set User Account Control: Run all administrators in Admin Approval Mode policy to Disabled

2000-2013 Tibbo Technology Inc.

196

AggreGate Documentation

2.5 ENABLE WMI ACCESS THROUGH WINDOWS FIREWALL

Reconfigure Windows Firewall using a group policy to pass WMI requests:

2000-2013 Tibbo Technology Inc.

AggreGate Server

197

2.6 CONFIGURE WMI IMPERSONATION

Go to Security Settings > Local Policies, then select User Rights Assignment. Make sure that Impersonate a client after authentication policy grants permissions to the SERVICE system account.

2000-2013 Tibbo Technology Inc.

198

AggreGate Documentation

2.7 CONFIGURING REGISTRY PERMISSIONS

Grant the user those credentials will be used for monitoring Full Control permissions to HKEY_LOCAL_MACHINE \SYSTEM\CurrentControlSet\Control\SecurePipeServers\WinReg registry branch.

2000-2013 Tibbo Technology Inc.

AggreGate Server

199

2. Running WMI Configuration Script

The WMI configuration script does the rest of mass WMI configuration job. Once it's finished, you can connect WMI hosts to AggreGate for monitoring. The script is written in PowerShell. Script text is available in a separate article Run instructions: 1. Save the script as wmi_config.ps1 file. 2. The script can be launched on a Windows 2008 Server or Windows 7 machine under domain administrator account. 3. Account of user running the scri[t must be included into the Local Administrators group on every workstation being configured. This can be done using group policies: go to Computer Configuration > Windows Settings > Security Settings > Restricted Groups , add Administrators group, then add domain used those privileges should be elevated to this group. Get warned that domain users that were not added to newly created group will be removed from local administrators. 4. It's necessary to execute PowerShell scripts using Set-ExecutionPolicy
200 .

RemoteSigned command.

5. Time of all workstations that are subject for WMI monitoring must be synchronized. 6. Point $ComputerListFile parameter in the script to the file listing IP addresses of hosts to configure. 7. Specify name of user account those credentials will be used for monitoring in script's $account parameter. 8. Run the script.

Find Hosts Ready for WMI Configuration

To create a file listing all hosts in your network that are ready for WMI configuration (e.g. have RPC port (135) open), use another PowerShell script 203 .

Automatic WMI Enabling

The WMI hosts scanning script and the WMI configuration script can be started periodically using Windows Task

2000-2013 Tibbo Technology Inc.

200

AggreGate Documentation

Scheduler. This will allow to auto-discover and auto-connect all new WMI hosts to AggreGate by using AggreGate's network discovery feature thereafter.

3.5.17.2.1 WMI Configuration Script

This script is used to mass-configure remote WMI access. # # # # # Usage: 1. Edit computers.txt referred by $ComputerListFile parameter 2. Set $account parameter to the name of user those credentials will be used for monitoring 3. Run the script 4. Check the log file for results

$account = "administrator@dc1" $ComputerListFile = "C:\wmi\computers.txt" $LogFile = "C:\wmi\wmi_setup.log" #--------------------------------------------function print_message($File, [string]$Text) { Write-Host $Text Add-Content $File $Text } Function for print messages to $LogFile and screen

#--------------------------------------------Function for check open DCOM port (135) ----------function check_open_port($ip, $port, $con_timeout) { $tcpclient = new-object Net.Sockets.TcpClient $Connection = $tcpclient.BeginConnect($ip, $port, $null, $null) $TimeOut = $Connection.AsyncWaitHandle.WaitOne($con_timeout,$false) if(!$TimeOut) { $TCPclient.Close() return 0 } else { try { $TCPclient.EndConnect($Connection) | out-Null $TCPclient.Close() return 1 } catch { ## Machine actively refused the connection. The port is not open but $TimeOut was still true return 0 } } }

#--------------------------------------------- Function for enable privilege to change CLSID\{76A6415 function enable-privilege { param( ## The privilege to adjust. This set is taken from ## http://msdn.microsoft.com/en-us/library/bb530716(VS.85).aspx [ValidateSet( "SeAssignPrimaryTokenPrivilege", "SeAuditPrivilege", "SeBackupPrivilege", "SeChangeNotifyPrivilege", "SeCreateGlobalPrivilege", "SeCreatePagefilePrivilege", "SeCreatePermanentPrivilege", "SeCreateSymbolicLinkPrivilege", "SeCreateTokenPrivilege", "SeDebugPrivilege", "SeEnableDelegationPrivilege", "SeImpersonatePrivilege", "SeIncreaseBasePriorityPr "SeIncreaseQuotaPrivilege", "SeIncreaseWorkingSetPrivilege", "SeLoadDriverPrivilege", "SeLockMemoryPrivilege", "SeMachineAccountPrivilege", "SeManageVolumePrivilege", "SeProfileSingleProcessPrivilege", "SeRelabelPrivilege", "SeRemoteShutdownPrivilege", "SeRestorePrivilege", "SeSecurityPrivilege", "SeShutdownPrivilege", "SeSyncAgentPrivilege", "SeSystemEnvironmentPrivilege", "SeSystemProfilePrivilege", "SeSystemtimePrivilege", "SeTakeOwnershipPrivilege", "SeTcbPrivilege", "SeTimeZonePrivilege", "SeTrustedCredManAccessPrivilege" "SeUndockPrivilege", "SeUnsolicitedInputPrivilege")] $Privilege, ## The process on which to adjust the privilege. Defaults to the current process. $ProcessId = $pid, ## Switch to disable the privilege, rather than enable it. [Switch] $Disable )

2000-2013 Tibbo Technology Inc.

AggreGate Server

201

## Taken from P/Invoke.NET with minor adjustments. $definition = @' using System; using System.Runtime.InteropServices; public class AdjPriv { [DllImport("advapi32.dll", ExactSpelling = true, SetLastError = true)] internal static extern bool AdjustTokenPrivileges(IntPtr htok, bool disall, ref TokPriv1Luid newst, int len, IntPtr prev, IntPtr relen); [DllImport("advapi32.dll", ExactSpelling = true, SetLastError = true)] internal static extern bool OpenProcessToken(IntPtr h, int acc, ref IntPtr phtok); [DllImport("advapi32.dll", SetLastError = true)] internal static extern bool LookupPrivilegeValue(string host, string name, ref long pluid); [StructLayout(LayoutKind.Sequential, Pack = 1)] internal struct TokPriv1Luid { public int Count; public long Luid; public int Attr; } internal const internal const internal const internal const public static int SE_PRIVILEGE_ENABLED = 0x00000002; int SE_PRIVILEGE_DISABLED = 0x00000000; int TOKEN_QUERY = 0x00000008; int TOKEN_ADJUST_PRIVILEGES = 0x00000020; bool EnablePrivilege(long processHandle, string privilege, bool disable)

{ bool retVal; TokPriv1Luid tp; IntPtr hproc = new IntPtr(processHandle); IntPtr htok = IntPtr.Zero; retVal = OpenProcessToken(hproc, TOKEN_ADJUST_PRIVILEGES | TOKEN_QUERY, ref htok); tp.Count = 1; tp.Luid = 0; if(disable) { tp.Attr = SE_PRIVILEGE_DISABLED; } else { tp.Attr = SE_PRIVILEGE_ENABLED; } retVal = LookupPrivilegeValue(null, privilege, ref tp.Luid); retVal = AdjustTokenPrivileges(htok, false, ref tp, 0, IntPtr.Zero, IntPtr.Zero); return retVal; } } '@ $processHandle = (Get-Process -id $ProcessId).Handle $type = Add-Type $definition -PassThru $type[0]::EnablePrivilege($processHandle, $Privilege, } #--------------------------------------------- First stage (get account sid, open file function get-sid { Param ( $DSIdentity ) $ID = new-object System.Security.Principal.NTAccount($DSIdentity) return $ID.Translate( [System.Security.Principal.SecurityIdentifier] ).toString() } $sid = get-sid $account $SDDL = "A;;CCWP;;;$sid" computers.txt,

$Disable)

2000-2013 Tibbo Technology Inc.

202

AggreGate Documentation

$DCOMSDDLDefaultLaunchPermission = "A;;CCDCLCSWRP;;;$sid" $DCOMSDDLDefaultAccessPermission = "A;;CCDCLC;;;$sid" $DefaultSDDLAccess = "O:BAG:BAD:(A;;CCDCLC;;;PS)(A;;CCDC;;;SY)(A;;CCDCLC;;;BA)" $DefaultSDDLLaunch = "O:BAG:BAD:(A;;CCDCLCSWRP;;;BA)(A;;CCDCSW;;;IU)(A;;CCDCSW;;;SY)(A;;CCDCLCSWRP;;;LA)" $computers = Get-Content $ComputerListFile $timeNow = get-date print_message $LogFile

$timeNow Main loop

#--------------------------------------------foreach ($strcomputer in $computers) { print_message $LogFile $strcomputer

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

$Port135Open = check_open_port $strcomputer "135" "1000" if ($Port135Open) { try{ $Reg = [WMIClass]"\\$strcomputer\root\default:StdRegProv" } catch { $message = "Error: " + [string]$Error[0] print_message $LogFile $message continue } } else { print_message $LogFile "Error! The RPC server is unavailable. No ping." continue } #-------------------------try{ $Win32_OS = Get-WmiObject Win32_OperatingSystem -computer $strcomputer } catch { $message = "Error: " + [string]$Error[0] print_message $LogFile $message continue } print_message $LogFile $Win32_OS.caption $str_version = [regex]::Replace($Win32_OS.version, "(\d.\d).*", '$1'); #6.1.7601 -> 6.1 $version = [decimal]$str_version print_message $LogFile "Applying group policies..." apply group policy

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

If ($version -ge 5.1) { Invoke-WmiMethod -ComputerName $strcomputer -Path win32_process -Name create -ArgumentList " } Else { Invoke-WmiMethod -ComputerName $strcomputer -Path win32_process -Name create ArgumentList } print_message $LogFile "Applying group policies completed"

#--------------------------------------- If Windows 2008 or 7 set CLSID\{76A64158-CB41-11D1-8B02If ($version -ge 6.1) { print_message $LogFile "Set CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6} permissions..." $RemoteKey = [Microsoft.Win32.RegistryKey]::OpenRemoteBaseKey([Microsoft.Win32.RegistryHive]::

enable-privilege SeTakeOwnershipPrivilege $key = $RemoteKey.OpenSubKey("CLSID\{76A64158-CB41-11D1-8B02-00600806D9B6}",[Microsoft.W # You must get a blank acl for the key b/c you do not currently have access $acl = $key.GetAccessControl([System.Security.AccessControl.AccessControlSections]::None) $me = [System.Security.Principal.NTAccount]"BUILTIN\Administrators" $acl.SetOwner($me) $key.SetAccessControl($acl) $TrustedInstaller = [System.Security.Principal.NTAccount]"NT Service\TrustedInstaller" $acl.SetOwner($TrustedInstaller)

# After you have set owner you need to get the acl with the perms so you can modify it. $acl = $key.GetAccessControl() $rule = New-Object System.Security.AccessControl.RegistryAccessRule ("BUILTIN\Administrators"

2000-2013 Tibbo Technology Inc.

AggreGate Server

203

$acl.SetAccessRule($rule) $key.SetAccessControl($acl)

$key.Close() #http://social.technet.microsoft.com/Forums/en/winserverpowershell/thread/e718a560-2908-4b91}

#--------------------------------------- Enable DCOM, Set authentication (to "Connect") and im $Result = $Reg.SetStringValue(2147483650,"software\microsoft\ole","EnableDCOM","Y") if ($Result) {print_message $LogFile "EnableDCOM -> Y"} $Result = $Reg.SetDWORDValue(2147483650,"software\microsoft\ole","LegacyAuthenticationLevel","2") if ($Result) {print_message $LogFile "LegacyAuthenticationLevel -> Connect"} $Result = $Reg.SetDWORDValue(2147483650,"software\microsoft\ole","LegacyImpersonationLevel","2") if ($Result) {print_message $LogFile "LegacyImpersonationLevel -> Identify"} #-------------------------------------- Set wmi namespace $converter = new-object system.management.ManagementClass root/CIMV2 permissions, set COM Win32_SecurityDescriptorHelper

secur

$security = Get-WmiObject -ComputerName $strcomputer -Namespace root/cimv2 -Class __SystemSecurit $binarySD = @($null) $result = $security.PsBase.InvokeMethod("GetSD",$binarySD) $outsddl = $converter.BinarySDToSDDL($binarySD[0]) $newSDDL = $outsddl.SDDL += "(" + $SDDL + ")" $WMIbinarySD = $converter.SDDLToBinarySD($newSDDL) $WMIconvertedPermissions = ,$WMIbinarySD.BinarySD $result = $security.PsBase.InvokeMethod("SetSD",$WMIconvertedPermissions) print_message $LogFile "ROOT\cimv2 permissions should be granted"

$COMAccess = $Reg.GetBinaryValue(2147483650,"software\microsoft\ole","DefaultAccessPermission").uV if ($COMAccess) { $outCOMAccessSDDL = $converter.BinarySDToSDDL($COMAccess) $newCOMAccessSDDL = $outCOMAccessSDDL.SDDL += "(" + $DCOMSDDLDefaultAccessPermission + ")" } else { $newCOMAccessSDDL = $DefaultSDDLAccess + "(" + $DCOMSDDLDefaultAccessPermission + ")" } $COMAccessbinarySD = $converter.SDDLToBinarySD($newCOMAccessSDDL) $COMAccessconvertedPermissions = ,$COMAccessbinarySD.BinarySD $result = $Reg.SetBinaryValue(2147483650,"software\microsoft\ole","DefaultAccessPermission", $COM if ($result.Returnvalue -eq 0) {print_message $LogFile "DefaultAccessPermission granted"}

$COMLaunch = $Reg.GetBinaryValue(2147483650,"software\microsoft\ole","DefaultLaunchPermission").uV if ($COMLaunch) { $outCOMLaunchSDDL = $converter.BinarySDToSDDL($COMLaunch) $newCOMLaunchSDDL = $outCOMLaunchSDDL.SDDL += "(" + $DCOMSDDLDefaultLaunchPermission + ")" } else { $newCOMLaunchSDDL = $DefaultSDDLLaunch + "(" + $DCOMSDDLDefaultLaunchPermission + ")" } $COMLaunchbinarySD = $converter.SDDLToBinarySD($newCOMLaunchSDDL) $COMLaunchconvertedPermissions = ,$COMLaunchbinarySD.BinarySD $result = $Reg.SetBinaryValue(2147483650,"software\microsoft\ole","DefaultLaunchPermission", $COM if ($result.Returnvalue -eq 0) {print_message $LogFile "DefaultLaunchPermission granted"} }

3.5.17.2.2 WMI Network Scanning

This script is used to scan a subnet, find all hosts those RPC port (135) is open, and write their list to a file. # # # # Usage: 1. Edit script, change $ip, $mask, $outpitFile, and $rewriteFile parameters 2. Start script 3. Check the output file

$ip = "192.168.1.1" $mask = "255.255.255.0" $outputFile = "C:\wmi\computers.txt" $rewriteFile = 1

2000-2013 Tibbo Technology Inc.

204

AggreGate Documentation

#--------------------------------------------function print_message($File, [string]$Text) { Write-Host $Text Add-Content $File $Text }

Function

for

print

messages

to

$LogFile

and

screen

#-------------------------------------------------------------------------------------------------------Function ConvertTo-DecimalIP { <# .Synopsis Converts a Decimal IP address into a 32-bit unsigned integer. .Description ConvertTo-DecimalIP takes a decimal IP, uses a shift-like operation on each octet and returns a sin .Parameter IPAddress An IP Address to convert. #> [CmdLetBinding()] Param( [Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True)] [Net.IPAddress]$IPAddress ) Process { $i = 3; $DecimalIP = 0; $IPAddress.GetAddressBytes() | ForEach-Object { $DecimalIP += $_ * [Math]::Pow(256, $i); $i-- } Return [UInt32]$DecimalIP } }

Function ConvertTo-DottedDecimalIP { <# .Synopsis Returns a dotted decimal IP address from either an unsigned 32-bit integer or a dotted binary strin .Description ConvertTo-DottedDecimalIP uses a regular expression match on the input string to convert to an IP a .Parameter IPAddress A string representation of an IP address from either UInt32 or dotted binary. #> [CmdLetBinding()] Param( [Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True)] [String]$IPAddress ) Process { Switch -RegEx ($IPAddress) { "([01]{8}\.){3}[01]{8}" { Return [String]::Join('.', $( $IPAddress.Split('.') | ForEach-Object { [Convert]::ToUInt32($_, 2) } "\d" { $IPAddress = [UInt32]$IPAddress $DottedIP = $( For ($i = 3; $i -gt -1; $i--) { $Remainder = $IPAddress % [Math]::Pow(256, $i) ($IPAddress - $Remainder) / [Math]::Pow(256, $i) $IPAddress = $Remainder } ) Return [String]::Join('.', $DottedIP) } default { Write-Error "Cannot convert this format" } } } } Function <# Get-NetworkAddress {

2000-2013 Tibbo Technology Inc.

AggreGate Server

205

.Synopsis Takes an IP address and subnet mask then calculates the network address for the range. .Description Get-NetworkAddress returns the network address for a subnet by performing a bitwise AND operation against the decimal forms of the IP address and subnet mask. Get-NetworkAddress expects both the IP address and subnet mask in dotted decimal format. .Parameter IPAddress Any IP address within the network range. .Parameter SubnetMask The subnet mask for the network. #> [CmdLetBinding()] Param( [Parameter(Mandatory = $True, Position = 0, ValueFromPipeline = $True)] [Net.IPAddress]$IPAddress, [Parameter(Mandatory = $True, Position = 1)] [Alias("Mask")] [Net.IPAddress]$SubnetMask ) Process { Return ConvertTo-DottedDecimalIP } } function check_open_port($ip, $port, $con_timeout) { $tcpclient = new-object Net.Sockets.TcpClient $Connection = $tcpclient.BeginConnect($ip, $port, $null, $null) $TimeOut = $Connection.AsyncWaitHandle.WaitOne($con_timeout,$false) if(!$TimeOut) { $TCPclient.Close() return 0 } else { try { $TCPclient.EndConnect($Connection) | out-Null $TCPclient.Close() return 1 } catch { ## Machine actively refused the connection. The port is not open but $TimeOut was still true return 0 } } }

((ConvertTo-DecimalIP

$IPAddress)

-BAnd

(ConvertTo-DecimalIP $Subnet

if ($rewriteFile) { Remove-Item $outputFile } $mm = "255.255.255.255" $dmm = ConvertTo-DecimalIP $mm $first = Get-NetworkAddress $ip $mask $dmask = ConvertTo-DecimalIP $mask $dfirst = [long](ConvertTo-DecimalIP $first) + 1 $n = [long]$dmm - [long]$dmask for ($i=0; $i -le ($n - 2); $i++) { $new = ConvertTo-DottedDecimalIP $dfirst $Port135Open = check_open_port $new "135" "1000" if ($Port135Open) {print_message $outputFile $new} $dfirst ++ }

2000-2013 Tibbo Technology Inc.

206

AggreGate Documentation

3.6 Event Filters

Real-time event monitoring is an important feature of most remote device management applications. It may be used for monitoring security systems or medical applications, for inspection of IT equipment failures, etc. Devices 113 usually generate many different events 880 , and when you're running a system which contains many Devices, your AggreGate Server will get many events which aren't very important, but some which might be critical. So, when you have a human operator, it is unnecessary for them to monitor all events, but some events may require attention. To filter out the less significant events and concentrate on the more important ones, use Event Filters. Filters also help monitor different system events, such as Scheduled Job 266 execution, Alert 216 escalation etc. An Event Filter is used to hide non-significant events and highlight the most important ones. It is a set of rules instructing the Event Log component in AggreGate Server User Interface (e.g. Event Log 791 in AggreGate Client) to adjust the visualization of incoming events for the needs of the user's business role. Every user
108

has his own set of event filters.

Working With Event Filters

To start using an event filter, the user must activate it by selecting it from the Filters drop-down list in the Event Log component. This is what filter selection looks like in the AggreGate Client Event Log:

The Event Log component has two sections: Real-time events, shows events as they are fired Event history
882

, for past events

Filters may be selected separately for each section. If a filter is selected in Real-time Events section, the Event Log starts listening for all categories of events listed in the Filter Rules 211 table. When a filter is selected in the Event History section, AggreGate Server loads all events satisfying Filter Rules 211 list (see below) from the database 80 and shows the first few rows, allowing the user to scroll through the whole list and sort it. The most important property of an event filter is Filter Rules 211 , defining which events to show. During filter activation every Enabled record in the Filter Rules table is processed and events satisfying the following conditions are shown in event log: Context
863

in which the event fired must match

866

the Context Mask

If Event Name is not equal to "*" (All Events), the event's name must be equal to the Event Name field. The event's level
882

must be greater of equal to the severity level specified by the Level field
207

The event must satisfy

the Filter Expression

All of these field names, in bold above, are described below. Each filter record may also define a highlighting color that will be used to highlight events of this category in Event Log. Highlighting color defined in Filter Rules record may be overridden by Custom Highlighting
210

rules.

By default, the following columns are visible in the Event Log: Server Timestamp. Date and time when this event was registered by AggreGate Server. This column cannot be hidden. Context. Description and/or path of the context where event has been occurred. This column shows descriptions of contexts by default. Context paths are shown only if the Show context paths along with their descriptions setting is enabled in Filter Info 211 . This column may be hidden by disabling the Context Name setting in Primary Visible Fields 212 . Event. Event name and/or description. This column shows events descriptions by default. Event names are shown

2000-2013 Tibbo Technology Inc.

AggreGate Server
only if the Show event names along with their descriptions setting is enabled in Filter Info be hidden by disabling the Event Name setting in Primary Visible Fields 212 .
211 .

207

This column may

212 .

Level . Event level. This column may be hidden by disabling the Event Level setting in Primary Visible Fields

Data. String representation of the Data Table associated with event. This column may show field names and values or values only, depending on the Show field names setting in Filter Info 211 . It may be hidden by disabling the Event Data setting in Primary Visible Fields 212 . Acknowledgement. Event acknowledgement setting in Primary Visible Fields 212 . See the Event Log
791 882 .

This column may be hidden by disabling the Acknowledgement

article in AggreGate Client manual for more information about event monitoring.

Administering Event Filters

Two contexts are used to administer event filters: One is the general Event Filters 687 context, which serves as a container. The other is the Event Filter 688 context, which holds the information for a single filter.

Event Filter Structure

Each event filter has several properties: Filter Info. The name and description of the filter, and some other basic settings Filter Rules. A list of events (or rather, event types, for we're not talking about specific event instances here) that are shown in the Event Log when the filter is active Primary Visible Fields. The visible properties of events shown when the filter is active Additional Visible Fields. These are additional fields, containing event-specific data. You can use this property to control which of these "additional" fields you see in the Event History for this event. For example, the login event has a username field, indicating what user logged in. This field is used only for the login event -- there's no use for it in an alert event (for example). So it's contained within the Data Table for the login event (and there's no such field in the data table for the alert event). The contents of this field depends on the event types which were selected in Filter Rules 211 . Custom Highlighting. Rules for assigning different colors to events
210

when they're shown in the Event Log.

The Filter Rules property defines which events are shown when the event filter is active, while Filter Info, Primary Visible Fields and Additional Visible Fields describe which parameters and fields are shown for every event. More information about filter properties can be found here 211 .

Filter Expressions
Filter expressions are used to fine-tune filtering and color-coding rules. See Filter Expressions
207

for more information.

Event Highlighting
Events shown in the Event Log can be color-coded according to different rules. See Event Highlighting information.
210

for more

Parameterized Filters
Some filters may require system operators to adjust filtering parameters upon filter activation or reactivation. Such filters are called parameterized filters. See Parameterized Filters 213 for details.

3.6.1 Filter Expressions

Filter expressions help fine-tune a given filter by showing only events that match a specific formula defined by an AggreGate Expression 911 , or highlighting these events in color within a broader list of events. This expression may include references 925 to the cells of an event's Data Table 854 containing event-specific data. (If you're not sure what's an event's Data Table, check out Event Data Table 881 within Events 880 ). For example, the Data Table for a login event contains a username field. So, when filtering for login events, you could use a filter expression containing a reference to this table, to further refine your filter and pass only logins of the

2000-2013 Tibbo Technology Inc.

208
user Joe.

AggreGate Documentation

It is also possible to refer the filtering environment

210

and data from various AggreGate Server contexts.

You are now entering an "advanced" section of this article. Before you can actually understand filter expressions, you'll need to have a profound understanding of references 925 and expressions 911 . These have their own chapters, under System Internals. We advise you to skip there now, read those chapters until you really understand references and expressions, and then come back here for an in-depth review of filter expressions.

HOW REFERENCES ARE USED WITHIN FILTER EXPRESSIONS

1. You can include references to the "default data table" within the Filter Expression. These are references such as firstname - no need to state an explicit context path and a variable name (such as users.admin: childInfo$firstname). AggreGate Server treats the Data Table of the event currently being filtered as the Default Data Table, and these references point there. 2. You can also refer to environment variables, such as env/level (an event's severity level, which is not included in the event's Data Table but is just a property of an event,. More about event properties can be found in the Events 880 article in the System Internals section). A full list of environment variables defined when an event is being filtered is here 210 .

FILTER EXPRESSIONS IN FILTER RULES

Every record in Filter Rules 211 table may have its own Filter Expression. This can be a bit tricky to grasp: the Filter Rules table is already a filter in itself -- it defines a mask, an event name and an event level, and only events matching these categories are shown. But the optional filter expression lets you make the filter even more granular and accurate. What if you have events that all match the mask, event name and level, and yet you only want to show some of them? That's where a filter expression comes in handy. Again, this may seem abstract for now, but you can skip down to the example and it'll all make much better sense. The filter expression must resolve to a Boolean value: TRUE of FALSE. If it resolves to FALSE, the event is filtered out and not shown in Event Log. If it resolves to TRUE, the event passes the filter and is shown. If the Parameterized flag is enabled in the Filter Rule, the Parameterizer Source Data field is used to build a Filter Expression in real-time upon filter activation. For further details, see Parameterized Filters 213 .

If a filter expression is not specified in Filter Rules record, all events that satisfy Context Mask, Event Name and Level options defined by this record will be shown. Example: Assuming that we are monitoring user logins. In Filter Rules, we have a category with the following settings:

Field
Description Context Mask Event Name Enabled Level Filter Expression Parameterized Highlighting Color

Value
User login events users login TRUE Info

FALSE <Not set>

It we double-click any login event shown in Event Log, we'll see its data in a Data Table Editor component. Here is a screenshot from the Data Table Editor 801 in AggreGate Client:

2000-2013 Tibbo Technology Inc.

AggreGate Server

209

We see that data for the Login event has two fields: Username (authenticated user contents of his permissions table 111 ).

108 )

and Permissions (current

To refer to these fields from our Filter Expression we need to use field names instead of their descriptions. Field names are shown in tooltips that appear when the mouse hovers over field description:

From this tooltip we see that the first field's name is username. This name may be used to create a Filter Expression that will let us to filter out only logins of a particular user. Let's say we want to filter only Charlie's logins. We'll use the following Filter Expression:

{username} == 'charlie'
When this expression is evaluated, the {username} reference resolves to the contents of the username field in the event's Data Table. This field is a String type, so the resolution results in a String value. This value is then compared with the String literal charlie. If they are equal, the event passes the filter and it is shown in the Event Log, otherwise it is filtered out. When we put this expression in the Filter Expression field of the Filter Rules table and activate the filter, only logins of Charlie will be visible in Event Log. The exact effect shown in this example could have also been accomplished by restricting the filter's context to users. charlie, but this example just serves to illustrate the point. It's more useful if you want to display logins from several users, for example, but not display logins from other users.

FILTER EXPRESSIONS IN CUSTOM HIGHLIGHTING

Every record in the Custom Highlighting 210 table may also contain a Filter Expression. If such an expression is set and evaluates to TRUE, custom highlighting rule is applied to this event. If a filter expression is not specified in Custom Highlighting record, all events that satisfy Context Mask, Event Name and Level options defined by this record will be highlighted. Example: Some events are critical to the functioning of the system. Such events fire at a high level 882 , such as Error or Fatal . We can highlight events that were fired at Error level in orange. Event level is indicated with a special icon in the Event Log, but custom highlighting might help system operators notice these events more easily. To highlight events coming from Devices
113 ,

we have to add a new rule to the Custom Highlighting table:

Field
Context Mask Event Name Level Filter Expression Highlighting Color

Value
users.*.deviceservers.*.devices.* event None

Orange

To match events fired at Error level, we may use the following expression:

{env/level} == 4
Alternatively, we can add a rule to highlight Fatal events in red. It will contain the following Filter Expression:

2000-2013 Tibbo Technology Inc.

210

AggreGate Documentation

{env/level} == 5
If we just want to highlight all events whose level is greater than Error (I.e, greater than level 4), we might as well just enter "4" in the Level field of the custom highlighting table of the event. We could accomplish the same thing using an expression, {env/level} > 4.

RESOLUTION ENVIRONMENT
As a baseline, you can find the formalized filter expression resolution environment below. Filter Expression and Highlighting Expression Resolution Environment Default Context
927 927 922

Context of event. Data Table containing event-specific data 0 Variable Name context event level time Value Type String String Integer Date Description Full path to the event's context. Name of the event. Event level
882 . 881 .

Default Data Table Default Row Environment Variables 930

927

Event timestamp. Event acknowledgements table Event enrichments table

883 . 883 .

acknowledge Data Table ments enrichments Data Table

3.6.2 Event Highlighting

Events can be color-coded in the Event Log. The colors are defined in the Filter Rules 211 or by Custom Highlighting 210 rules. Custom highlighting rules have higher priority, so if an event matches a custom highlighting rule, the color defined for it in Filter Rules will be ignored. The color defined by a custom highlighting rule is used to highlight an event if: The context where the event occurred matches the Context Mask defined in the rule. If Event Name is equal to "*" (All Events) or the event's name is the same as the Event Name parameter. The event's level is greater than, or equal to, the severity Level defined in the rule. The event matches the Filter Expression, if the highlighting rule specifies one. Here is what the event list looks like in the AggreGate Client Event Log:

2000-2013 Tibbo Technology Inc.

AggreGate Server

211

3.6.3 Event Filter Configuration

This section covers event filter configuration properties. All properties described here are available via Configure
904

action of an Event Filter context

688 .

3.6.3.1 Filter Properties

This defines the basic options of an event filter.

Field Description
Filter Name. Name of the event filter 688 . Should satisfy the context naming conventions 863 . It's used to refer to this filter from other parts of the system. Filter Description. Textual description of the alert. This is also the description alert context.
864

Field Name
name

of the

description

Default Filter. Indicates whether the current filter is the default filter of the owning user The default filter is auto-activated in Event Log 791 .

108 .

defaultFilter

Show Field Names in "Data" Column . Show the name of each field in the Data Table defined by Event Format 880 in the "Data" column of event log. If this setting is disabled, only the value of the field is shown. Show Context Paths Next To Their Descriptions. Show both paths and descriptions of events in "Context" column of event log. Show Event Names Next To Their Descriptions. Show both names and descriptions of events in "Event" column of event log. These may be accessed via the childInfo
689

showDataFieldNames

showServerContextN ames showServerEventNa mes

variable.

3.6.3.2 Filter Rules

This property defines a list event categories that will be shown when this filter is active.

Field Description
Description . Textual description of event category. Context Mask. Contexts to be monitored for this event. More about this in the Context Masks 865 section. Event Name. Name of event to monitor. This field may be set to "*" (All Events) to enable monitoring of all non-system events. Enabled. When this flag is disabled, the category is inactive and events specified by it are not shown. This is the same as "deleting" the category, but you're not actually deleting it (so you can still use it for reference or quickly re-enable it). Level . Events with a level
882

Field Name
description mask

event

enabled

lower than what's set in this field will not be shown.

level parameterized

Parameterized. Indicates that the filter rule is parameterized, i.e. Parameterized Source Data field should be used to build a Filter Expression during filter activation based on a number of operator-specified parameters. See Parameterized Filters 207 for details. Filter Expression. An AggreGate Expression 911 used to filter out events even more granularly. Used when Parameterized flag is disabled for this rule. Parameterizer Source Data. Used when Parameterized flag is enabled for this

expression

parameterized

2000-2013 Tibbo Technology Inc.

212

AggreGate Documentation

rule. See Parameterized Filters

207

for details. color

Highlighting Color. The color used to highlight events of this category in the event log. The color for any particular event may be overridden by Custom Highlighting 210 settings.

Important: Once you edit this property, save and then reload your filter. Doing so will update the Additional Visible Fields 212 property according to the event types you selected here, and this is important. These may be accessed via the rules
690

variable.

3.6.3.3 Primary Visible Fields

This property what columns to show in the event log when displaying a given event.

Field Description
Context Name. Show context
863

Field Name
where event has been fired. context event level
854

Event Name. Show name of event. Event Level. Show event level
882 .

Event Data. Show contents of Data Table

associated with event.

882 .

data ack enrichments

Acknowledgements . Show event acknowledgements Enrichments. Show event enrichments These may be accessed via the shownFields
883 . 690

variable.

3.6.3.4 Additional Visible Fields

As covered above, events have additional fields. These are event-specific data, such as username (in the case of a login event). This property lets you configure which of these additional fields will be shown in the event log. Once you've configured which event types your filter should pass (i.e, once you've customized the Filter Rules 211 table to your liking), you must save the table. After saving and reloading filter configuration, the Additional Visible Fields list will be updated. This list will now contain all additional fields, but only for those event types passed by the filter you're editing (and actually, even for disabled event categories). So you're going to have a whole slew of additional fields which you're going to have to choose from. Let's say you have a filter passing both login events and alert events. The Additional Visible Fields list for this filter will let you enable (make visible) all fields for both event types. So you'll have name (for Alerts, to show the Alert name in the list) and also username (for Logins, to show who logged in). If you enable username, there will be an additional username column in the filter's table when you're viewing it in the Event Log. For lines showing login events, this column will contain the username. For lines showing alert events, this column will just be blank (no value at all, because it's inapplicable). We advise you to select your fields wisely at this point - otherwise you'll end up with an extremely wide list for this filter in the Event Log, and scrolling it can be uncomfortable.

Field Description
Field Name. Name of field. Field Description. Textual description of field. Event Descriptions . Shows what events this field applies to. Visible. Indicates that the field is shown in event log.

Field Name
name description edescs shown

2000-2013 Tibbo Technology Inc.

AggreGate Server

213

Table doesn't seem to contain what you need? Try saving and then reloading the whole filter. This should always be done to make this table dynamically update to match the events configured in Filter Rules. These may be accessed via the additionalFields
691

variable.

3.6.3.5 Custom Highlighting

This table defines special highlighting
210

rules.

Field Description
Context Mask. Mask of contexts for those this highlighting rule will be applied. Event Name. Name of event to highlight. This field may be set to "*" (All Events) to enable highlighting of all events. Level . Minimal level of event to highlight. Filter Expression. Highlight only events satisfying filter expression, if it is set. Highlighting Color. Highlighting color. These may be accessed via the customHighlighting
691

Field Name
mask event

level expression color variable.

3.6.3.6 History Browser Settings

This table defines settings used to view event history
882 .

Field Description
Limit Time Frame. Flag indicating that only a certain subrange of historical events should be selected. Time Frame (in Time Units). If Limit Time Frame is enabled, this options defines the actual time frame to be selected. See example below. Time Unit . Defines the unit of measurement for the Time Frame (Month, Week, Day, Hour, Minute, etc.). Use Custom End Time. If this flag is active, event history browser will only show events which have occurred prior to the End Time. End Time. If Use Custom End Time is enabled, only historical events which have occurred prior to this time will be shown in Event Log.

Field Name
limitTimeFrame

timeFrame

timeUnit

useCustomEndTimeP oint customEndTimePoint

Example: If Time Frame is 10, and Time Unit is Day, event history browser will only show historical events matching the filter which have occurred within the last 10 days. If, at the same time, Use Custom End Time option is enabled, event history browser will show only events that have occurred within 10 days before the End Time. These may be accessed via the historySettings
691

variable.

3.6.4 Parameterized Filters

Filter parameterization is useful when you want to let an operator configure a filter at runtime. If the record in Filter Rules 211 is marked as Parameterized, filter may require user to input one or more parameters during its activation (i. e. selection from a drop-down list in Event Log).

2000-2013 Tibbo Technology Inc.

214

AggreGate Documentation

Parameterization is a complex subject, which is beyond the extent of this topic. However, to understand this section, you must have a complete understanding of the Parameterization process and engine. So, if you'd like to use Parameterized Filters and you're unfamiliar with the subject, you should now skip to Parameterization Engine 956 , read the whole topic until you're fully familiar with parameterization, and then come back here. As covered above, the Filter Rules property contains many lines (records), each describing an event type which the filter passes. Each record may contain a filter expression (which may be parameterized). Even if the Filter Rules property contains more than one such parameterized Filter Expression, all filter parameters are entered in one single dialog. The Event Filter uses an Edit Data 896 UI Procedure to prompt for filtering parameters. When the Parameterized option is enabled in the Filter Rules record, the filter processing engine uses Parameterizer Source Data to build Filter Expression in real-time based on a number of operator-specified parameters. For more information, see Parameterization Engine 956 . Here is an example of Parameterizer Source Data:

<form> <format> <![CDATA[ <<username><S><D=Username>> ]]> </format> <expression> {username} ~= '.*<e>{username}</e>.*' </expression> </form>

A filter containing this parameterized expression will ask for a Username parameter upon activation:

This filter will pass only events whose username field contains the value entered by an operator as the Username parameter, because resulting Filter Expression will be:

{username} ~= '.*<e>VALUE_OF_USERNAME_PARAMETER_ENTERED_BY_USER</e>.*'
Again, this isn't really supposed to make much sense at this point of the manual -- it's just a glimpse at the power of parameterized filters. To really understand how this works, you have to read about the Parameterization Engine 956 .

Auto-Parameterization
This function automatically generates parameterization data for event categories selected from within Filter Rules 211 . You can auto-parameterize a Filter Rules record only if it doesn't already contain a Filter Expression. The autoparameterization process flow is described here 692 . Parameterization data generated by this function defines two parameters per every field in the event's Data Table. I.e, when applying auto-parameterization to an event 880 which has only one field defined in its Event Format property, the user will be prompted to enter two values upon filter execution. "Filter by 'description_of_field (name_of_context_where_event_is_defined)'": This would be something like Filter by 'Username (users)'. It's a Boolean value (in other words, a checkbox) which enables or disables filtering by the value of this field. "description_of_field (name_of_context_where_event_is_defined)": This would be something like Filter by 'Username (users)'. It's a textbox (or another editing control, depending on the field type) in which you can enter the value you want to filter by.

2000-2013 Tibbo Technology Inc.

AggreGate Server

215

For example, if we apply auto-parameterization to the Administration Events category, parameterization data will define two parameters: Filter by 'Info (administration)' and Info (administration):

The first parameter enables filtering by the Info field of the Info event 885 (in the administration context). The second parameter contains the expected value for the field. Only events with an Info field equal to this value will pass the filter.

3.6.5 Build-In Filters

AggreGate Server distribution contains several predefined Event Filters:

All Events
All events filter shows all important system and Device events. Rules of this filter are useful for most system administrators and operators. Here is a brief overview of them: Rule Administration Events Users Events User Events Data Terminal Events Alert Events Notes Generic administrative events, such as failed user 108 login attempts and registrations of new user accounts, reports about connected External Device Servers 1012 , notifications about AggreGate Server startup and shutdown etc. Events related to all user accounts. Events related to a certain user account
108 .

Events related to a certain Data Terminal 113 , such as communication problems, synchronization issues, events received from hardware etc. Notifications about Alerts 216 . These pop up in the interface, or are emailed, even if you're not monitoring the filter. This is useful mainly for checking alert history and viewing acknowledgements. Other information about alerts, such as alert escalations 237 , notification 225 delivery problems etc., is also included in this category. Information about successful and unsuccessful execution of scheduled jobs Tracker
257 266 .

Scheduler Events Tracker Events

events, such as state changes or value calculation errors.

Server Log
This filter shows server log messages
74

that are normally written to the server-side console or log file.

Technically, the filter is set up to display Log 652 events from Administration context. Since Log events are not persistent, historical events are not available under Server Log filter. Most of messages written to the server log are system-level messages that are not intended to be analyzed by system operators. Thus, some of the messages may be non-internationalized, available in English language only.

Device Events
This filter shows only events related to Device communications and events generated by hardware devices.

Alerts
This filter shows only alert events
224 .

Actions
This filter selects action events
653 ,

i.e. lists actions

892

that were executed by system operators and components.

2000-2013 Tibbo Technology Inc.

216

AggreGate Documentation

3.6.6 Event Filters in Distributed Architecture

This section describes specifics of event filters behavior in a distributed installation
791 99

of AggreGate.

To make an event filter connected from a provider server appear in Event Log of clients connected to a consumer server, make sure that the context path of connected filter context on the consumer server matches users.*. filters.* context mask, i.e. the remote filter appears among local filters.

3.7 Alerts
An alert is a response of the system to a custom user-defined event or condition. Alerts are raised by triggers (alert conditions). A trigger can be an event, a state or a change of state of a system component/hardware device. See the triggers 216 section for details. When an alert is raised, the system responds to it: The alert owner may be immediately notified, if he is connected to the server. He may also be prompted to acknowledge 228 the alert. E-mail messages may be sent to the alert owner, to a system user The alert may be stored in the event history Some corrective actions
892 882 108 (s)

or to a custom E-mail address(es).

as a usual event.
893 .

may be executed, in interactive or non-interactive mode

216 .

The alert may change its state Every user

108

has their own set of alerts.

Administering Alerts
Two contexts are used to administer alerts: One is the general Alerts 654 context, which serves as a container. The other is the Alert 656 context, which holds the information for one alert.

Triggers
Alerts are activated by triggers. Every alert may have several triggers associated with it. Each trigger defines a condition in which the alert should be raised. There are two types of triggers, described below: Event Triggers
222 217

Variable Triggers

Trigger: an act that sets in motion some course of events.

Each alert may define zero or more triggers of every type. If no triggers are defined, the alert is never raised. If several triggers are defined, they act separately -- each trigger may raise the alert (they don't all have to exist at the same time -- just one is enough to raise the alert).

Alert Notifications
When an alert is raised by one of its triggers, AggreGate Server starts sending notifications actions 227 .
225

and executing corrective

Alert States
Alert state indicate current severity of the alert. It involves several factors, such as availability of pending alert instances, trigger activity, and escalation rules. See Alert States
233

for details.

Built-In Alerts

2000-2013 Tibbo Technology Inc.

AggreGate Server

217

DEVICE OFFLINE ALERT

Device Offline alert is built into AggreGate Server basic distribution package. It is raised when any Data Terminal disconnected from the server for longer than 10 minutes. According to its Variable Triggers active.
217 , 113

is

this alert is triggered only for Devices whose Enable Offline Alert
109 .

126

setting is

Device Offline alert is owned by default administrator

FAILOVER
Failover alert is raised once the Master Node of AggreGate Server failover cluster 87 fails and control is taken by a Failover node. An e-mail message is sent to the default administrator 109 upon this alert.

Examples
Some examples of real-world alert configurations are provided in the Alert Examples
238

section.

3.7.1 Variable Triggers

A variable trigger may raises the alert: When a variable
869

value satisfies some condition, or

When a variable value changes (no matter to what value) Selection between these two methods is performed by the Monitor State Changes property of the trigger. Other properties of the variable trigger are described here 230 . Every variable trigger periodically inspects the value of the variable in every context matching the defined by the Context Mask 865 setting. Polling period is defined in seconds, by the Check Period parameter. A Data Table 854 containing the value of the variable is retrieved from the context, and then something happens, according to the Monitor State Changes setting: If Monitor State Changes is disabled, the server evaluates the expression 911 defined by the Expression setting. This expression must evaluate to a Boolean result in this case. It may contain references 925 to the cells of the Data Table containing the variable value, but may also refer other variables and functions of AggreGate Server contexts. If the expression evaluates to TRUE and the result of the previous evaluation was FALSE (or if this is the first time the variable is inspected since AggreGate Server was started or since the properties for this alert were last changed), the trigger fires and raises an alert. If the evaluation is TRUE and was also TRUE during the last check, no action is performed. If it changes from TRUE to FALSE, no action it performed either, but subsequent change back to TRUE will fire the trigger. If Monitor State Changes is enabled, the Expression is evaluated every Check Period exactly like in the previous scenario, but its result may be of any type. The server will remember the last evaluation result. If the new evaluation result is different than the last one, the trigger fires and raises the alert. If the Context Mask parameter points to more than one context, each context is separately inspected, and the alert is raised every time the variable value satisfies the condition (or changes, depending on the Monitor State Changes setting) in any of these contexts. Example of variable trigger without "monitor state changes": Let's say we're monitoring the Current Temperature variable, coming from a temperature sensor. In this case, Expression may refer to the Celsius Temperature field of this variable and cause a trigger to fire if the temperature exceeds a certain limit. The trigger parameters may be: Context Mask Variable Expression Monitor State Changes Check Period (seconds) Delay (seconds)

users.user123.devices.temperature_sensor (This mask matches a single

Data Terminal
677

context)

currentTemperature {celsiusTemperature} > 100 disabled 10 0

2000-2013 Tibbo Technology Inc.

218

AggreGate Documentation

Alert Level

Warning

Example of variable trigger with "monitor state changes": Now let's say we're monitoring a Warning List variable, coming from a piece of medical equipment monitoring several critical parameters of a patient. The value of this variable is a Data Table with up to five records, and every record has a single String field called Warning, containing a textual warning about the state of patient. In this scenario, the Expression may aggregate all warning messages by appending them to each other, and activate the alert when any of the warnings is removed, added or changed. The parameters of may look like this: Context Mask Variable Expression Monitor State Changes Check Period (seconds) Alert Level

users.user123.deviceservers.medical12.devices.monitor1 (This mask

matches to a single Data Terminal
677

context)

warningList {warning[0]} + {warning[1]} + {warning[2]} + {warning[3]} + {warning[4]} enabled 100 Warning

Delays and Hysteresis

Variable triggers have a Delay parameter that help to set up alerts like "Warning, temperature is less than 10 degrees for over one hour". The Delay parameter is relevant only when Monitor State Changes is off. It defines the interval between time when the trigger expression becomes true and the time the alert is raised. If set to zero (the default), the alert is raised immediately when Expression evaluates to TRUE. When Delay is non-zero, the server waits for the specified number of seconds before activating trigger and raising and alert. If Expression evaluates back to FALSE before the Delay time expires, the alert is not raised and the time counter is reset. Regardless to the Delay value, trigger expression is re-evaluated only once per Check Period (which is one of the parameters of the trigger - see above). For example, if Check Period is 10 seconds and Delay is 15 seconds alert will be raised 20 seconds after the time when expression has been first evaluated to true. Variable trigger is activated if Expression is TRUE for longer than Delay time. It is deactivated if: Deactivator expression is not specified, and Expression is FALSE for longer than Deactivation Delay Deactivator expression is specified, and it is TRUE for longer than Deactivation Delay. If you think the Deactivator expression seems very similar to the Correlator expression mentioned above, that's because it is! The main difference is that a Correlator expression may lower the alert upon Correlated Event only, while a Deactivator expression is evaluated periodically. An activated trigger switches its related alert to Active state
233

and adds an Active Instance

235 .

A combination of Delay and Deactivation Delay is called hysteresis. Hysteresis is the lagging of an effect behind its cause.

The following picture shows how the variable trigger is activated/deactivated when Deactivator is not specified:

2000-2013 Tibbo Technology Inc.

AggreGate Server

219

When Deactivator is specified, activation/deactivation of trigger is performed according to the following picture:

2000-2013 Tibbo Technology Inc.

220

AggreGate Documentation

Example of variable trigger with hysteresis Let's return to the one of the above examples involving temperature monitoring. We want to set up a trigger that: Activates the alert when temperature is higher than 50 degrees for longer than 5 minutes, Deactivates the alert when it's active and temperature is lower than 35 degrees for longer than 20 minutes. The trigger parameters may be as follows: Context Mask Variable Expression Monitor State Changes

users.user123.devices.temperature_sensor (This mask matches a

single Data Terminal
677

context)

currentTemperature {celsiusTemperature} > 50 disabled

2000-2013 Tibbo Technology Inc.

AggreGate Server

221

Check Period, seconds Delay, seconds Alert Level Deactivator Deactivation Delay, seconds

10 300 Warning {celsiusTemperature} < 35 1200

Flapping Detection
Flapping is a situation where trigger Expression changes its result very rapidly constantly switching between TRUE and FALSE. This can happen for various reasons for example if the device constantly reboots, its online status will oscillate. AggreGate can detect that a variable trigger is flapping. It does so by analyzing previous Expression evaluation results, in terms of how many state changes have happened. AggreGate keeps a history of the 101 most recent checks and analyzes changes within that history. If there are no changes from TRUE to FALSE or back in the last 101 state checks (i.e. 100 state changes), the flapping percentage would be 0%. If all checks have different states, the flapping percentage would be 100%. Flapping detection is controlled by three parameters: Enable Flapping Detection Activation Threshold Deactivation Threshold The first parameter must be enabled in order to allow flapping alerts. Once it's enabled, the trigger keeps the result of Expression calculation performed in every Check Period and recalculates flapping percentage on every check. The flapping alert occurs once there are more then 11 checks (10 state changes) in the history and flapping percentage exceeds Activation Threshold. Flapping alert is processed and delivered like any other alert, its only difference is its cause and alert data. The latter provides information about flapping percentage that caused the alert. The trigger will remain in Flapping Detected state until current flapping percentage drops below Deactivation Threshold.

FLAPPING AND TRIGGER ACTIVATION

Flapping and normal trigger activation are fully independent. This means that a trigger may be in Active and Flapping Detected states simultaneously. This also means that normal alert and flapping alert may be raised by the trigger in any order. Flapping detection will not cause normal activation that occurs when Expression result remains TRUE for longer than Delay.

Trigger Message
In addition to alert's Message expression, each variable trigger has its own Trigger Message expression. This expression is resolved to a string when the alert is raised. The resulting string becomes a part of Alert Event 224 , holding any custom information about alert cause or other circumstances.

Resolution Environment
Variable Trigger Expression and Deactivator Expression Resolution Environment Default Context None.
927 922

Default Data Table 927 Default Row

927

Current value of the trigger's variable.

Environment Variables 930

Standard

931

variables only.

2000-2013 Tibbo Technology Inc.

222

AggreGate Documentation

3.7.2 Event Triggers

An Event trigger raises the alert when a certain event 880 fires in a context 863 , and conforms to a condition specified in trigger settings. This event may be generated by AggreGate Server itself or may come from a Data Terminal 113 . The event trigger's properties are described here 230 . Each trigger causes AggreGate Server to "listen" for the event specified by the Event setting in every context that matches the Context Mask setting. When such an event is detected, the server evaluates the expression 911 specified by the Expression setting. This expression usually refers to some data associated with the event, but it may also refer to any other data, such as the values of some context variables 869 . If the Expression parameter is not specified, every occurrence of the event will raise the alert.

Example of event trigger: Let's say we're running a vehicle monitoring system, which has Devices in various factory vehicles. These Devices fire various events, such as the Impact event, which fires when the vehicle bumps (or crashes...) against something. So the Context Mask would match the Device monitoring the vehicle, the event would be something like impact, and we could also have an expression, referring to the strength field of the impact event, which would cause the trigger to activate if the strength of the impact exceeds a certain value. In this case, the Event Trigger parameters may be as follows: Context Mask Event Expression

users.user123.devices.vehicle12_controller (This mask matches a

single Data Terminal
677

context - could be a wildcard matching several, too)

impact {strength} > 5.5

(Of course, impact and strength are just theoretical events coming from some made-up Device - they're not built-in AggreGate Server system events). Example of event trigger expression: contains({message}, "FAILED LOGIN") &&

{facility} == 4 && {level} == 5

This expression will trigger an alert if a message is received from Syslog server: Contains FAILED LOGIN string Has 5th level Is generated by Syslog facility with ID = 4

Multiple Events Trigger

Count and Period trigger parameters work together to allow trigger activation only if event occurred X times within last Y seconds. If Count is set to 1 (default), any event matching trigger Expression will activate the trigger and alert. If Count is 3 and Period is 10 minutes, the trigger will be activated upon an occurrence of event if two previous occurrences happened not more than 10 minutes ago and all three occurrences match an Expression . Example: let's assume we're monitoring several servers in a network. A single "Authentication Failed" event received from any server does not necessarily indicate a problem, since user may have just mistyped his password. However, multiple events received from a single server within 10 minutes should raise a security alert. Here is a proper event trigger setup for this case: Context Mask Event Expression Count Period

users.*.devgroups.servers.* authenticationFailure

20 10 Minutes

Event Correlation

2000-2013 Tibbo Technology Inc.

AggreGate Server

223

Event correlation is a technique for making sense of a large number of events and pinpointing the few events that are really important in that mass of information. In terms of AggreGate alerts, event correlation is a way to activate 235 the alert by an event trigger when one ("primary") event occurs, and deactivate the alert upon another ("correlated") event. To enable event correlation for a certain event trigger, specify the name of the Correlated event in the trigger settings. In this case: Event trigger (and the alert itself) will be activated by the event named in the Event setting (which is the "primary" event in this case). It will be deactivated if Correlated event occurs in the same context with Event, and additionally, Correlator expression evaluates to TRUE. (It can happen that the Correlated event occurs, but Correlator expression evaluates to FALSE, thus leaving the trigger active.) Once a trigger has been activated, it switches the alert to Active state
233

and adds an Active Instance

235 .

The following picture illustrates activation/deactivation of event trigger by Primary and Correlated events:

Count and Period settings also work for correlated events. For example, if Count equals to 5 and Period is 1 minute, trigger will be deactivated only if five Correlated events occur within one minute and all five will match Correlator expression. Examples of event triggers using event correlation: Sometimes we may want to view an alert in the Active Alerts 274 list when a certain device is offline (not available for AggreGate Server). Assuming that we have connection and disconnection events in the Device context 677 of this device, we may use the following event trigger settings to force an alert remain active when device is disconnected: Context Mask Event Correlated

users.user123.devices.critical_device disconnection connection

This trigger will activate alert on disconnection event and deactivate it on connection event. If there are no connection/disconnection events in the Device context, we can still use a contextStatusChanged 890 event for the same functionality. In this case we'll have a slightly more complicated trigger setup: Context Mask Event

users.user123.devices.critical_device contextStatusChanged

2000-2013 Tibbo Technology Inc.

224

AggreGate Documentation

Expression Correlated Correlator

{status} == 0 (Assuming that status 0 means "device is disconnected") contextStatusChanged {status} == 1 (Assuming that status 1 means "device is connected")

This trigger will be activated when contextStatusChanged event occurs and status field of event data equals to zero. The same event with a status of 1 deactivates the trigger.

Trigger Message
In addition to alert's Message expression, each event trigger has its own Trigger Message expression. This expression is resolved to a string when the alert is raised. The resulting string becomes a part of Alert Event 224 , holding any custom information about alert cause or other circumstances. Example of event trigger message expression: 'Device-provided custom SNMP trap

field:' + cell({variableBindings}, "myMIBDataField")

This expression can be used to insert value of a certain custom SNMP trap 174 's variable binding into an alert. The expression first refers to a nested table of SNMP Trap's event data table 881 using {variableBindings} reference, then extracts value of myMIBDataField field from the first line of this table.

Resolution Environment
Event Trigger Expression and Correlator Expression Resolution Environment Default Context
927 922

None. Data Table containing event-specific data

881

Default Data Table

927

for trigger event or correlated event.

Default Row Environment Variables 930

927

Variable Name context event level time

Value Type String String Integer Date

Description Full path to the event's context. Name of the event. Event level
882 .

Event timestamp. Event acknowledgements table Event enrichments table

883 . 883 .

acknowledge Data Table ments enrichments Data Table

3.7.3 Alert Event

When alert is raised, a special AggreGate Server event or "Alert instance", and has several uses: When this event is not acknowledged
882 , 880

is generated in the Alert context

656 .

It is called "Alert event"

it is called "pending alert instance". When an alert has pending instances,

the alert itself is put into the Active state 233 . Its icon changes to . This is similar to how an email client works -you can see your mailbox as "Unread" if it has unread messages in it. History
882

of the Alert Event helps to keep track when and why the alert was raised.

When you View Pending Alerts 656 , you are actually looking at the history of all Alert Events for a particular alert. You can only access this action if the Allow Pending Alerts setting is enabled for this alert. Format of Alert Event: Field Description

2000-2013 Tibbo Technology Inc.

AggreGate Server

225

Alert Name Alert Description Context Entity Cause Message Trigger Alert Data

Name of alert context

656 . 656 .

Description of alert context

Path of context for which the alert was raised, i.e. context where event or state change monitored by alert trigger has occurred. Event (is raised by event trigger) or variable (if raised by variable trigger) which caused the alert. Textual description of alert's cause. Alert message. This is a manually configured string, which is supposed to be a human-readable description of the alert (i.e, "The house is on fire"). See Alert Configuration 229 section. Trigger message. Additional text message provided by alert trigger. Data associated with the event causing the alert. This field is NULL (not defined) if the alert was caused by a certain variable state or by a variable value change. For a login event defined in the Users context, this data table will contain one record with two fields: Username and Permissions.

Example of Alert event:

The technical description of alert event is available in context reference section

662 .

3.7.4 Notifications
Alert notifications are used to inform alert owner and other interested parties about alert rise or escalation. Notification settings are described in the Notification Settings
231

section.

Popup Alert Notifications and Sound Alerts

The AggreGate Server user 108 owning the alert is notified if the Show Popup Notification to Owner setting is enabled and this user is logged in to a AggreGate Server User Interface. For example, in AggreGate Client, a flying popup is shown to the user:

The alert notification popup contains: Alert description The cause of the alert Alert message Message provided by the trigger Server that the alert was received from Flying alert popups will disappear automatically after a certain time that depends on the alert severity. However, an alert can be closed at any time by clicking on the close button. Alert popup also provide access the following options: Stick. Disable automatic hiding for this alert popup. Configure. Open alert configuration. Show Alert Data. Show alert details in a Data Table Editor
801 .

2000-2013 Tibbo Technology Inc.

226

AggreGate Documentation

Close All. Close all currently visible alert popups. If owner notification is enabled, you can specify a Notification sound (.WAV or .MP3 file) that will be played in AggreGate Server User Interface before the notification popup is shown.

ACKNOWLEDGING ALERTS
If the Acknowledgement Is Required parameter is enabled, the user is prompted to enter an acknowledgement text for the alert in the same popup box. Here is what it looks like in AggreGate Client:

Sending E-mail Notifications

Alert notification e-mails will be sent only if mail server settings are properly configured and mail sending is enabled. See Mail Sending Settings 63 in AggreGate Server Global Configuration for details. AggreGate Server can prepare and send an alert notification e-mail message . This message may be sent to three recipient categories: Alert Owner Other AggreGate Server user(s) Custom e-mail address(es) Sending mail to alert owner is enabled by the Send E-mail To Owner setting. E-mail Recipients table contains a list of AggreGate Server users that will receive e-mail notification. Only users whose e-mail address is specified in the user profile may be added to the recipient list.
108

It is also possible to send e-mail notifications to custom e-mail addresses. These addresses should be listed in the Additional E-mail Recipients field and separated by commas. Contents of the email: Alert description Event causing the alert Context where the event is defined Alert message Alert time Data of the event that caused the alert (if raised by Event Trigger by Variable Trigger 217 ) This is what such an email looks like:
222 )

or value of the variable that caused it (it raised

2000-2013 Tibbo Technology Inc.

AggreGate Server

227

Plain text version of alert email:

Sending SMS Notifications

Alert notification may be sent by SMS only if SMS sending settings are properly configured and SMS sending is enabled. See SMS Sending Settings 69 in AggreGate Server Global Configuration for details. AggreGate Server can send an alert notification via SMS to a number of cellular phones. Specify recipients using the SMS recipients setting located in the Notifications Settings 231 section. The sender's number is defined by Sender Number Global Configuration option. Example: For Impact Warning alert that may inform Vehicle Monitoring System operator about impact occurred to a vehicle, the following SMS notification will be sent:

Alert: Impact Warning

It is also possible to send SMS alert notifications via GSM/GPRS modem: Connect AggreGate Server to a modem using Modem device account are properly configured. Add a new Automatic Corrective Action
232 148

device driver. Make sure that both modem and its

to an alert.

Point corrective action's Context to your modem account. Change Action to Send SMS. Enter recipient's number and SMS text in the action Parameters.

3.7.5 Corrective Actions

AggreGate Server is capable of running actions 892 when an alert is raised. These are called "corrective actions" because they're intended to correct the problem automatically or by interacting with humans. Corrective actions may be also used to send non-standard notifications. For example, corrective action may launch an external application to send message to a pager or beeper (check details here 730 ). Another examples would be sending Unix syslog message or Simple Network Management protocol (SNMP) trap using special actions included into AggreGate Network Management extensions. Actions may be run in interactive or non-interactive (headless) mode 893 . In non-interactive mode, all action input is pre-defined and action output is sent to the server log 74 or written to event history 882 . This mode is also used by the scheduler 266 . In interactive mode, the action interacts with the alert owner by using UI Procedures 896 . He must be

2000-2013 Tibbo Technology Inc.

228

AggreGate Documentation

logged in to an AggreGate Server User Interface (e.g. AggreGate Client) to allow interactive actions execution. See the action execution modes 893 section for details.

Automatic Corrective Actions

Automatic (also called autonomous, headless, or non-interactive) execution of corrective actions is controlled by the Automatic Corrective Actions 232 property. This property lets you configure multiple actions to run on alert. Automatic corrective actions table has several fields: Every action will be launched from every context matching the Context Mask parameter. Action name is defined by the Action parameter. Parameters is the list of action-specific parameters (this might be confusing, but keep in mind that Parameters here is, itself, a parameter. Get it?). These parameters are used to substitute user input when the alert processing engine executes an action in non-interactive mode. For example, if a given action requires confirmation (i.e. asks user something like "Delete query?" and lets the user click OK or Cancel), this field will contain a Delete query? parameter with two possible choices: OK or Cancel. Condition is an expression
911

that, if defined and evaluated to FALSE, suppresses execution of a corrective action.

To view headless corrective actions execution history and errors reported by them during execution, use Monitor Related Events 909 action of an Alert context 656 .

Interactive Corrective Actions

Interactively executed actions are listed in a table called Interactive Corrective Actions
233 . Every action has Context Mask and Action parameters which work just like in non-interactive execution (see above). The Parameters column allows to specify some interactive execution parameters, such as window locations.

3.7.5.1 Action Parameter Processing

Input parameters 270 of a corrective action are pre-defined at the stage of alert creation and saved in the database However, it's often necessary to change/update these parameters when alert is actually raised.
80

For example, if a custom e-mail or SMS message should be sent upon an alert, its text should be composed upon actual alert occurrence and include data elements describing its cause. To configure dynamic corrective action parameters: Open any parameters table for editing. It will be possible to add/modify its bindings Add one or more bindings to the table. These bindings will be calculated when alert is raised and its corrective actions are executed. They will update value of pre-defined action parameters. See Input Parameter Bindings
893 813 .

for more information.

3.7.6 Alert Acknowledgement

Every alert raised is persistently stored as an AggreGate Server event (see Alert Event 224 for details). These events may be acknowledged exactly like all other AggreGate Server events. Acknowledging an alert is the same as acknowledging its "Alert" event. The acknowledgement is stored in the event history, just like any other event acknowledgement. Its parameters (author, time and text) may be viewed when browsing event history (for example, using the Event Log 791 in AggreGate Client).

E-MAIL ACKNOWLEDGEMENTS
AggreGate Server provides an E-mail alert acknowledgement service letting operators acknowledge events by replying to alert notification e-mail message 226 . To start using this service, enable mail receiving in Mail Settings 63 section of AggreGate Server Global Configuration and configure incoming mail server properties (POP3 server address, login and password). Make sure that Check Incoming Mail 267 scheduled job is enabled (it's disabled by default).

2000-2013 Tibbo Technology Inc.

AggreGate Server

229

E-mail alert acknowledgements will function properly only if replies to the alert notification e-mails will be delivered to the mailbox monitored by AggreGate Server. Alert notification e-mails are sent with the Reply-to header set to the address specified in Sender address for mail messages global configuration setting. Thus, AggreGate Server must receive all e-mail that were sent to this address. This will allow notification email recipients to use "Reply" function of their mail clients and enter acknowledgement text in the reply email. To acknowledge an alert by e-mail, reply to the alert notification e-mail and enter the acknowledgement text in the first line of reply. Alert acknowledgement will be added once the reply is delivered and received by AggreGate Server. AggreGate Server checks for new mail periodically, according to Incoming mail check period global configuration option. It is important to preserve the subject of original alert notification e-mail when replying. The mail client may add text (usually "Re: "), and this is fine. However, the ID pattern in the message subject should not be removed or changed.

3.7.7 Alert Configuration

This section covers alert configuration properties. All properties described here are available via Configure
904

action of an Alert context

656 .

3.7.7.1 Alert Properties

This defines the basic options for an alert.

Field Description
Alert Name. Name of the alert context 656 , required to refer to this alert from other parts of the system. It should satisfy the context naming conventions 863 . Alert Description. Textual description of the alert. This is also a description context.
864

Field Name
name

of the alert

description

Alert is Enabled. Disabling an alert deactivates all its triggers. It will never be raised.

enabled message

Message. Alert message. It will be shown in all alert notifications including visual notifications, notification e-mails, alert event etc. This is an expression 911 , so static messages should be quoted (e.g. 'Some message').

Alert Message Expression Resolution Environment Default Context Source context of the alert.
927

922

Default Data Table 927 Default Row Environment Variables 930

927

Data Table of the alert event

224 .

0 Standard
931

variables only.

Required Source Permission Level. Defines permission level 932 that the user should have in alert source context to be able to see the alert. Default value None means that user may not have access to alert source context at all, but he will still be able to see and process the alert. These may be accessed via the childInfo
657

permissions

variable.

2000-2013 Tibbo Technology Inc.

230

AggreGate Documentation

3.7.7.2 Event Triggers

This defines a list of Event Triggers
222 .

Field Description
Context Mask. This mask 865 is resolved during trigger processing. If the event specified by the Event parameter is fired in any context matching this mask, the trigger activates an alert. In most cases, this context mask points to one explicit context, being a context path, rather than a mask. Event. Name of the event to be monitored. Filter Expression. An AggreGate Expression 911 which must evaluate to TRUE to activate the trigger. May contain references 925 to the cells in the Data Table 854 associated with the Event. Alert Level. Level 880 of this alert event 224 . In addition to the fixed values, may be set to Same As Event (this is a default setting). In this case level of alert event will be same as level of event that caused the alert. Correlated. Name of the "correlated event" that will deactivate the trigger if Correlator expression will be TRUE when it occurs. Correlator. An AggreGate Expression 911 which must evaluate to TRUE to deactivate the trigger when Correlated event occur. May contain references 925 to the cells in the Data Table 854 associated with the Correlated event. Message. Trigger message is usually used to indicate the root cause of alert. This is an expression 911 so static messages should be quoted (e.g. 'Some message').

Field Name
mask

event filter

level

correlated

correlator

message

Alert Trigger Message Expression Resolution Environment Default Context Source context of the alert.
927

922

Default Data Table 927 Default Row Environment Variables 930

927

Data Table of the alert event

224 .

0 Standard
931

variables only.

These may be accessed via the eventTriggers

657

variable.

3.7.7.3 Variable Triggers

Every variable trigger periodically inspects value the variable in every context matching the mask 865 defined by the Context Mask setting. Polling period is defined in seconds, by the Check Period parameter. A Data Table 854 containing the value of the variable is retrieved from the context, and then something happens, according to the value of the Monitor State Changes setting: This property defines a list of Variable Triggers
217 .

Field Description
Context Mask. This mask 865 is resolved during trigger processing. The value the variable specified by the Variable parameter will be monitored in any context matching the mask. In most cases, this context mask points to one explicit context, being a context path, rather than a mask.

Field Name
mask

2000-2013 Tibbo Technology Inc.

AggreGate Server

231

Variable. Name of context variable to be monitored. Expression . AggreGate Expression 911 used to check the variable value. The result of this expression will be processed according of the Monitor State Changes flag. Monitor State Changes. It this setting is disabled, the trigger fires whenever the result of Expression changes from FALSE to TRUE. If it's enabled, trigger fires whenever the result of Expression changes (from one value to another, not necessarily TRUE/FALSE). This is comprehensively described above, under variable triggers 217 . Check Period (seconds). Time interval between inspections of Variable. Delay (seconds). Time interval between time when trigger expression become true and time when alert is raised. Alert Level. Level
880

variable expression

monitorStateChange

period delay

of this alert event

224 .

level deactivator deactivationDelay flapping message

Deactivator. Alert deactivation expression. Deactivation Delay. Alert deactivation delay. Flapping. Controls flapping detection
221

for this trigger.

Trigger Message. Usually used to indicate the root cause of alert.

Alert Trigger Message Expression Resolution Environment Default Context Source context of the alert.
927

922

Default Data Table 927 Default Row

927

Data Table of the alert event

224 .

Environment Variables 930

Standard

931

variables only.

These may be accessed via the variableTriggers

658

variable.

3.7.7.4 Notification Settings

This property defines alert notification rules.

Field Description
Show Popup Notification to Owner. Show a popup message to the user 108 owning this alert if he happens to be logged on to a AggreGate Server User Interfaces (such as AggreGate Client) when the alert is raised. Acknowledgement Required . Force user to acknowledge notification is shown.
228

Field Name
notifyOwner

an alert when the alert

ackRequired

Custom Notification Lifetime. Specifies for how long popup alerts will remain visible. Notification Sound . Sound that will be played to the alert owner before notification popup is shown. Send E-mail to Owner . E-mail the owner, to the address specified in his user profile. E-mail recipients. List of AggreGate Server users who will receive e-mail notifications of the alert.

lifetime sound

mailToOwner mailRecipients

2000-2013 Tibbo Technology Inc.

232

AggreGate Documentation

Additional E-mail Recipients. Comma-separated list of e-mails addresses. Alert notification will be sent to each of these addresses. SMS Recipients. List of phone numbers to those SMS notification message will be sent upon alert. This list may contain both AggreGate Server users 108 who have phone numbers in their account settings 110 and raw phone numbers. All numbers must be written in international format. These may be accessed via the notifications
658

additionalMailRecipients

smsRecipients

variable.

3.7.7.5 Escalation Settings

This property defines processing options for pending
236

alerts and alert escalation

237

rules.

Field Description
Allow pending alerts. When enabled, allows the alert to switch to "Pending" state. Disabling pending alerts also disables escalation. Number-based instances. escalation. Enables escalation due to a certain number of pending alert

Field Name
pending

numberEscalation

Number of pending alerts requited to initiate escalation. When the number of pending alert instances (of this type) exceeds this limit, alert is escalated. Time-based escalation. Enables escalation due to alert instances that are pending longer than the specified time limit. Time before escalation (minutes). If any pending alert instances are not acknowledged within this time, alert is escalated. These may be accessed via the escalation
659

numberThreshold

timeEscalation

timeThreshold

variable.

3.7.7.6 Automatic Corrective Actions

This property defines the actions 892 to be executed in non-interactive mode when the alert is raised. A good example illustrating application of this feature is execution 730 of an external application on alert.

Field Description
Context Mask. Action will be executed from every context matching this mask Action. Name of the action to be executed. Parameters. This list incudes parameters of two types: action-specific execution parameters 896 and pre-defined input for different UI Procedures 896 like Confirmation 901 , Edit Data 896 etc. Pre-defined input is required to substitute user input when alert executes action in noninteractive mode. For example, if an automatic corrective action requires confirmation (i.e. asks user something like "Delete query?" and allows to click OK or Cancel), this field will contain a "Delete query?" parameter with two possible choices: "OK" and "Cancel". Condition. An expression 911 that is evaluated before corrective action execution. If the expression returns false corrective action is skipped.
865 .

Field Name
mask action input

condition

Condition Expression Resolution Environment Default Context

927

922

Context of the alert.

Default Data Table

927

Data of alert event

224 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

233

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

Run From Source Context. If this flag is checked, corrective action will be launched from the context that the alert came from. Example: If an alert monitors memory usage of an application that has memory leaks, selecting Restart corrective action and enabling Run From Source Context will restart the application on the server that has originated the alert. Same applications on other servers will not be touched. The Context Mask parameter is ignored if Run From Source Context is on. However, it's necessary to select a Context Mask that will match one or all possible alert source contexts first, since this will allow proper selection of an Action and its Parameters. These may be accessed via the alertActions
659

runFromSource

variable.

3.7.7.7 Interactive Corrective Actions

This property defines the actions connected to the server.
892

to be executed in interactive mode when the alert is raised while its owner is

Field Description
Context Mask. Action will be executed from every context matching this mask Action. Name of the action to be executed. Parameters. Action-specific execution parameters
896 . 865 .

Field Name
mask action input runFromSource

Run From Source Context. If this flag is checked, corrective action will be launched from the context that the alert came from. Example: If an alert monitors memory usage of an application that has memory leaks, selecting Restart corrective action and enabling Run From Source Context will restart the application on the server that has originated the alert. Same applications on other servers will not be touched. The Context Mask parameter is ignored if Run From Source Context is on. However, it's necessary to select a Context Mask that will match one or all possible alert source contexts first, since this will allow proper selection of an Action and its Parameters. These may be accessed via the interactiveActions
659

variable.

3.7.8 Alert States

Alerts can be in one of the following states: Enabled ( Disabled ( Active ( ) ) ) )

Escalated (

Enabled/Disabled Alerts
The initial state for a newly created alert is Enabled. This means that all triggers are enabled and may raise the alert.

2000-2013 Tibbo Technology Inc.

234

AggreGate Documentation

You can disable the alert (put it in Disabled state, technically speaking) by switching off the Alert is enabled basic option 229 . A disabled alert is never raised and doesn't do anything, because all triggers are inactive.

Active Alerts
Alert is active if: One of its event triggers
222

is active, i.e. primary event has occurred and correlated event hasn't yet occurred
217

One of its variable triggers been satisfied thereafter One of its variable triggers There are any pending
236

is active, i.e. activation condition has been satisfied and deactivation condition hasn't is in "Flapping Detected" state

217

(non-acknowledged) alerts

The activation reason is shown in a tooltip that appears when the mouse hovers over the alert in AggreGate Server User Interfaces.

Escalated Alerts
For description of Escalated state see Alert Escalation
237 .

3.7.9 Alert Lifecycle

An alert is a quite complex object with multi-stage lifecycle. This section provides an overview of available alert states and their transitions, while subsequent articles describe the details.

Alert Trigger Instances

Each alert may have multiple triggers (of variable 217 and/or event 222 type), and each trigger has a Context Mask setting generally targeting it to a group of contexts (alert sources). Internally, an instance of each trigger is created to monitor each context matching the mask. For example, if an alert has two triggers, first of them having 10 context matching its mask, and second one having 20 events, the alert will have a total of 30 trigger instances.

Alert Raising
Each trigger instance performs the monitoring of its "peer" context in its own way, separately from the others. Variable triggers periodically evaluate a trigger Expression against its peer context's values, while event triggers simply wait for occurrences of the Event. At certain moment, a trigger may decide that trigger condition is satisfied. This process is called "alert raising". At this moment, a bunch of things goes on: An instance of Alert Event Alert notifications
225 224

is created, saved to database and sent to subscribed listeners.

are sent as e-mails and/or SMS messages.

Alert popup is shown to system operators. If Acknowledgement Required option is set, the operators are prompted to acknowledge the alert. Acknowledging an alert 228 is technically acknowledging a corresponding Alert event instance. This alert event can be later acknowledged by any other means, such as from Event Log's context menu. Corrective actions (both automatic
232

and interactive

233 )

are executed.

If system operators have an open Event Log those filter 206 is set up to monitor Alert events (e.g. Alerts or similar filter is active), the operators will also see the Alert event in Event Log. If alert's Activate alert when there are pending (non-acknowledged) instances setting is enabled, the alert will change its state 233 from Normal to Active. If Number-based escalation setting is enabled and increased number of pending (non-acknowledged) Alert event instances exceeds the Number of pending alerts required to initiate escalation threshold, the alert will switch from Active to Escalated state. The escalation notifications (e-mail and SMS) are also sent in this case. The trigger itself may activate. For variable triggers, activation will happen in any case. For event trigger, the activation will happen only if the trigger has a Correlated event set and, thus, the system knows how to deactivate it upon a "paired" event. If the trigger was activated, the alert will switch from Normal to Active state. The activated trigger will be added to alert's Active Instances The activated trigger will also be added to the Active Alerts
235

list.

875

list of the alert source context (the one those event/

2000-2013 Tibbo Technology Inc.

AggreGate Server
state has raised the alert).

235

Time-Based Escalation
If Time-based escalation setting is enabled, the alert tracks time elapsed since each of those instances was raise. If this time exceeds value of Time before escalation threshold, the alert is escalated and changes its state from Active to Escalated. The escalation notifications (e-mail and SMS) are also sent in this case.

Alert Deactivation
Every active trigger instance continues monitoring in its own way. A variable trigger will deactivate after a delay since its Expression 's (or Deactivator expression's, if it's set) result will switch to FALSE. An event trigger will deactivate if Collelated event(s) were received. Once any trigger was deactivated, the following happens: The deactivated trigger will be removed from alert's Active Instances The deactivated trigger will be removed from the Active Alerts event/state has raised the alert).
875 235

list.

list of the alert source context (the one those

236 ,

If no other triggers are active and there are no pending instances Active to Normal.

the alert state will change its state back from

Alert Acknowledgement
If any Alert event 224 was acknowledged 228 and alert's Activate alert when there are pending (nonacknowledged) instances setting is enabled, a number of things may happen: If the alert was Escalated, there are neither non-acknowledged instances that are pending for longer than Time before escalation , and the number of pending instances is below the Number of pending alerts required to initiate escalation, the alert will be de-escalated and change its state from Escalated to Active. If there are no other pending (non-acknowledged) alert instances, the alert will change its state back from Active to Normal.

3.7.10 Active Instances

Each of alert's triggers (both variable-based
217

and event-based

222 )

can be active:

An event trigger is active is primary event has occurred but correlated event has not A variable trigger is active if activation condition is true (and hysteresis time elapsed) but deactivation condition is false (or deactivation hysteresis time not yet elapsed) A variable trigger is also active if it's in "Flapping Detected" state Since trigger's context masks can be used to check multiple contexts context simultaneously.
863 ,

the trigger may be active for more than one

An alert instance is called Active if its trigger is still active for this alert's source context.

It's important to distinguish Active and Pending

236

alert instances.

Viewing Active Instances

To see active instances of a certain alert, launch View Status To see all active alerts in the system, run Active Alerts
274 910

action and check Active Instances table.

query.

Here is how a list of active alerts look like in AggreGate Client:

2000-2013 Tibbo Technology Inc.

236

AggreGate Documentation

3.7.11 Pending Instances

When an alert is raised, a special Alert event 224 is generated and persistently stored in AggreGate Server database Alert events that are not acknowledged 228 are called pending alert instances. See the events 880 topic for more information about events and event acknowledgement. It's important to distinguish Active
235 80

and Pending alert instances.

Managing Pending Alerts

The pending instances of every alert may be controlled using the Manage Pending Instances 656 action, defined in the Alert context. This action shows when and why the alert was raised, and lets you delete or acknowledge pending alerts. Alert instances that have already been acknowledged are not shown in the list. Here is what the list of pending alerts looks like (screenshot made in AggreGate Client):

When one or more unacknowledged alert events exist, the alert remains in Active state. This state is indicated in AggreGate Server User Interfaces by a special icon. The active state indicates that some attention is required to solve the problem indicated by an alert. When the problem is solved, system operator may launch the View Pending Alerts action and acknowledge all pending alert instances. Alert will be put back in the "Enabled" (normal) state, indicated by the icon.
232

Non-acknowledged instances may force alert to switch into the Active state only if the Allow pending alerts enabled.

setting is

Viewing Pending Instances

To see pending instances of a certain alert, launch View Status instances have Pending mark in the Type column. To see all pending alerts in the system, run Active Alerts
274 910

action and check Active Instances table. Pending

query.

2000-2013 Tibbo Technology Inc.

AggreGate Server

237

Disabling Pending Alerts

When configuring an alert, one of the properties 232 is called Allow Pending Alerts. If you disable this (i.e, disallow pending alerts for this particular alert you're configuring), the alert won't be shown in the Pending Alerts list even if it wasn't acknowledged. It also won't be escalated 232 .

3.7.12 Alert Escalation

Pending
236

alerts may be escalated. Escalation is usually used to draw attention to some critical conditions. In most icon, require the system operators to take quick action.

cases, escalated alerts, indicated with the

For an alert to be escalated, there has to be at least one pending (unacknowledged) instance of it, and it must satisfy at least one of the escalation rules defined by the Alert Escalation 232 property. There are two escalation types: Number-based escalation Time-based escalation With number-based escalation, an alert is escalated if the number of pending alert instances specified by the Number of pending alerts required to initiate escalation setting.
236

exceeds the limit

With time-based escalation, an alert is escalated if any pending instance (alert event) is not acknowledged within the time frame specified by its Time before escalation setting. When an alert is escalated, an Escalation Notification is emailed to all recipients defined by the Notifications setting. This notification contains the time of escalation, and the reason for it:

The reason is also shown in a tooltip that appears when the mouse hovers over the alert in AggreGate Server User Interfaces. Here is what it looks like in AggreGate Client:

To put an alert back in pending or normal state, acknowledge will not be satisfied.

228

some of its pending instances so that escalation rules

3.7.13 Alerts Security

Alert's triggers perform all checks using alert owner's permission table to those contexts that are available for alert owner.
933 .

The trigger's Context Mask is resolved only

Example: If user Joe has an alert with trigger's Context Mask set to users.*.devices.*, the trigger will be activated for all devices that are accessible with Joe's user permissions 111 . However, the same trigger added to default administrator 109 's alert will work for all devices in the system. Alert triggers retrieve diverse data from contexts matching their Context Mask (e.g. during Trigger Expression evaluation). Thus, alert owner must have sufficient permission level 932 in all these contexts. Other notes: Variable triggers Event triggers
222 217

will be activated only for variables that are readable under alert owner's permissions

will be activated only for events those definitions are accessible under alert owner's permissions

Corrective Actions Permissions

All alert corrective actions
227

are also executed with alert owner's permissions.

Example: A corrective action belonging to Joe's alert won't be able to stop or restart the AggreGate Server unless Joe has Admin permission level 932 in the Root Context 726 . However, default administrator 109 alert's can always stop/restart the server, since he has permissions to do everything.

2000-2013 Tibbo Technology Inc.

238

AggreGate Documentation

3.7.14 Alerts Performance

Alerts are "active" server components causing constant CPU load. The CPU load caused by an alert is a multiplication of several factors: Number of alert's triggers. Number of contexts checked by each trigger. For example, in a large installation a trigger targeted to users.*. devices.* context mask 865 will cause much higher load that a trigger targeted to users.john.devices.dev1. The CPU load impact
924

of alert trigger's expression.

Once an alert is raised by one of its triggers, an additional performance impact can be caused by its corrective actions 227 . Alert's don't cause significant constant memory usage. However, considerable spot memory usage can be caused by evaluation of trigger expression referring a large dataset or execution or a corrective action.

3.7.15 Alert Examples

This article provides some non-trivial alert configurations that can be used as a reference for creating your own custom alerts.

Trigger Expression Examples

Here are some real-life examples of alert trigger expressions: Expression Notes This expression will take the Default Table (that is variable's value 221 in the case Variable Trigger), find a record that has its ifIndex field equal to 1, and trigger the alert if value of ifAdminStatus field in this record equals to 2. This expression is used by Device Offline Alert 217 . It triggers the alert if connectionStatus field of the monitored variable (actually Device status 682 variable) equals to 0 (Offline), and value of offlineAlert field of genericProperties (Generic Properties 680 ) variable is true (i.e. Offline Alert is enabled for thiscnt device). This alert will be triggered if temperature goes over 27 degrees on Monday to Friday, 9AM to 6PM.

select({}, 'ifAdminStatus', 'ifIndex', 1) == 2

{connectionStatus} == 0 && {genericProperties$offlineAlert}

{temperature} > 27.00 && dayOfWeek(now()) != 0 && dayOfWeek(now()) != 6 && hour (now()) > 9 && hour(now()) < 18 contains({message}, "FAILED LOGIN") && {facility} == 4 && {level} == 5 select({.:settingsStatus}, 'duration', 'setting', 'mySqlQuery') > 500

This is an Event Trigger's expression that activates an alert when message field of the event data contains "FAILED LOGIN" substring, facility field equals to 4, and level field equals to 5. This expression analyzes last execution time of an SQL query named mySqlQuery that is periodically executed by database device driver 180 . If query execution time exceeds 500 milliseconds, an alert will raise. The same expression can be used to analyze I/O duration (i.e. read/ write time) of any device variable.

Impact Warning Alert

Let's assume that our hardware device is a forklift controller that may generate Impact event when forklift collides with some obstacle. This event contains Level field that represents impact level, higher levels indicate more severe impacts. The Impact Warning alert has a single Event Trigger 222 which fires due to the Impact event in the Data Terminal context if the Integer level field in event data is greater than 50 (i.e. alert is raised only for severe impacts) .
677

ALERT INFO

Field
Alert Name

Value
impact_warning

2000-2013 Tibbo Technology Inc.

AggreGate Server

239

Alert Description Alert is Enabled Message

Impact Warning TRUE Severe impact occurred to the vehicle

TRIGGERS ACTIVATED BY EVENTS

Context Mask users.admin.devices.forklift Event impact Filter Expression {level} > 50

ALERT NOTIFICATIONS

Field
Notify owner if connected to the server Acknowledgement is required Notification sound Send e-mail to owner E-mail recipients Additional e-mail recipients

Value
TRUE

FALSE <Not set> TRUE NONE

Several Harware Devices in Trouble

This complex example show how integration of two powerful features, alerts and queries error conditions that involve several Device.
271 ,

may be helpful to detect

Assuming that ten temperature sensors are connected to AggreGate Server and owned by user john . The Data Terminal 677 context of every sensor has a Temperature variable (variable name: temperature) whose value has an Integer field, celsius, containing the temperature in Celsius. Suppose the temperature of every individual sensor is not critical, but if three or more sensors report temperature greater than 100 degrees this may lead to problems in the future, and an alert should be raised to let the operators know there's a problem. We'll use a query that helps to find all thermometers reporting temperature over than 100 degrees:

SELECT * FROM users.john.devices.*:temperature WHERE temperature$celsius > 100

This query returns a table (Data Table
854 )

containing one record per every sensor showing high temperature.

We can execute the above query by calling the executeQuery function 878 from the Root 726 context and passing the query text to it as an input parameter. So the idea is to set up an alert with a trigger that periodically executes this query and checks the number of records in its output. If the number is greater than three, the trigger fires. Variable triggers may not be used to check function output directly, but here we must check a function's output -executeQuery is a function. As covered above, alerts can be triggered in two ways -- when an event (so-called "event triggers") happens, or according to the value of some variable ("variable trigger"). For our example, we'll use a "variable" trigger, but we'll hack it a little bit. A variable trigger always has a context , a variable and an expression. Now, expressions can actually invoke functions. So we're going to create an alert which has a meaningless context, a meaningless variable (which is still valid for that context), and a very meaningful expression. This expression won't even refer to the context and variable of the alert. We care only about the expression in this case, because it causes the query to be executed for us. The other parts (context and variable) are just placeholders. As placeholders, we'll use the "" (root) context and the version read-only variable, containing the server version. Out alert will be raised when the expression evaluates to true . To access the number of records contained in the output of the executeQuery function we will use the records property (see References 925 for details about the reference resolving process). So, the final reference that will return the number of thermometers registering a high temperature looks like this:

{:executeQuery("SELECT * FROM users.john.devices.*:temperature WHERE temperature$celsius > 100")#records}

2000-2013 Tibbo Technology Inc.

240

AggreGate Documentation

How it works: 1. The trigger periodically polls the Root context for the value of the version variable. 2. This value is discarded as it is not used in trigger expression. 3. The expression is evaluated. During evaluation, Default Reference Resolver resolves the above reference - it calls the "Execute Query" function and returns the number of rows in the result. This number is compared to the numeric constant "3". The resulting expression returns TRUE if it is greater or equal to it and FALSE otherwise. 4. If the expression returns TRUE, the trigger raises the alert and all notifications
225

are sent.

ALERT INFO

Field
Alert Name Alert Description Alert is Enabled Message

Value
temperature_warning Temperature Warning TRUE Three or more sensors show high temperature

VARIABLE TRIGGERS
Context Mask "" (empty string - Root context) Variabl Expression e version {:executeQuery("SELECT * FROM users.john.deviceservers. sensors.devices.*:temperature WHERE temperature$celsius > 100")#records} >= 3 Monitor State Changes FALSE Check Period (seconds) 10 Leve l Error

ALERT NOTIFICATIONS

Field
Notify owner if connected to the server Acknowledgement is required Notification sound Send e-mail to owner E-mail recipients Additional e-mail recipients

Value
TRUE

FALSE <Not set> TRUE NONE

Additional examples may be found in the Triggers

216

section.

3.7.16 Alerts in Distributed Architecture

This section describes specifics of alerts behavior in a distributed installation
99

of AggreGate.

To make popup notifications of an alert connected from a provider server appear in clients connected to a consumer server, make sure that the context path of connected alert context on the consumer server matches users.*. alerts.* context mask, i.e. the remote alerts appears among local alerts.

2000-2013 Tibbo Technology Inc.

AggreGate Server

241

3.8 Reports
Reports are designed to display data in a graphic, printer-friendly format. In most cases, reports are created by users similarly to alerts 216 , queries 271 and other system objects. However, some reports are pre-configured in the system distribution and can't be changed by the user. These reports are built into the the AggreGate distribution package and extension plugins 950 . Every user
108

has his own set of Reports.

Every user-defined report is characterized by two important properties: Report Template that defines generic look and feel and layout of the report Source Data Expression that is used to fetch data for filling in report template Related tutorials: Building a Device Status Report 1250 Scheduled Report Emailing
1254

Administering Reports
Two contexts are used to administer reports: One is the general Reports 719 context, which serves as a container. The other is the Report 721 context, which holds the information for one report. Pre-defined reports may not have all settings and actions that are available for custom user-created reports.

3.8.1 Source Data Expression

The Source Data Expression is an AggreGate Expression 911 that is evaluated every time when a report is launched 242 and shown to the user. This expression must evaluate to a Data Table 854 . An error condition will occur if this expression evaluates to any primitive type, such as Boolean, Integer or String. Data from the Data Table produced as a result of the expression is used to fill in the report template and prepare the report. For relative 242 reports, this expression may contain references 925 with relative context 863 paths. When the report is launched 242 , any relative references will be resolved in relation to the context from which the Launch Report 243 action has been selected. If the report is launched using the Show Report 721 action of the report context, or from the Report Editor 826 , relative references will be resolved relatively to the context specified by the report's Default Context property 245 . Example: If an absolute report is designed to show data retrieved by a query 271 , its Source Data Expression should contain a reference to the data variable defined in the query context 716 . So if a query is called traffic_stats and belongs to the admin user (this actually exists as a pre-defined query 274 ), we can get the following Source Data Expression:

{users.admin.queries.traffic_stats:data}
Example: Here is a Source Data Expression of a relative Attendance Report:

{attendance:attendanceData('{.:}')}
This source data expression refers to an attendanceData function 878 from an attendance context. During evaluation, this function is called with one parameter, the path of the context from which the Attendance Report launch action 243 has been selected (or the Default Context's 242 path, if the report is started in test mode from Report Editor 826 ). See Standard References 926 section for an explanation of why {.:} resolves to default context's path. Example: The below expression of a relative Alert History report loads historical 882 alert events 224 from the database and returns them in a table. Only a few of alert fields selected by subtable() function are included in the report.

2000-2013 Tibbo Technology Inc.

242

AggreGate Documentation

subtable({events:get('{.:}', "alert", null, null, false, null, false)}, "eCreationtime", "eLevel", "cause", "message", "trigger", "eAcknowledgements")
See Selecting and Processing Events 1270 tutorial for more information.

Default Context for a Report

Simply speaking, the default context is a report property used for resolving references in the Source Data Expression 241 when no "target" is specified on launching a relative 242 report. It is used in two cases: When launching
242

a relative report directly, without selecting a "target" context first.

826 .

When building a report in test mode from a Report Editor

When the relative report is launched using a Launch Report 243 action (the "classic" use case), relative context paths in references appearing inside the Source Data Expression 241 are resolved relatively to the path of the context from which the Launch Report action has been started. The Default Context property is not used in this case.

3.8.2 Report Template

A Report Template defines page layout and different transformations that are applied to the source data when report is run. The report template is defined in XML, and stored as a property 245 of the report. The Report Template is automatically generated 1325 during report creation. This auto-generated template is based on the data that fetched by the Source Data Expression. There are two ways to modify the template of an existing report: Directly in XML format, using the Configure Report Using the Report Editor
826 . 721

action of a report context.

722

This can be done by executing Edit Report Template

action of a report context.

Reports are compiled, filled and processed by the JasperReports engine. You can refer to Jasper Reports documentation for more information on template structure, available elements and their properties.

3.8.3 Report Types

Reports are divided into two categories: Absolute Reports Relative Reports

Absolute Reports
Absolute reports usually process data coming from just one fixed source (usually one context). For example, a AggreGate Server User Accounts report shows a system-wide list of user accounts 108 . This report should be absolute. Source Data Expression
241

of absolute report can not have relative references

925 .

Relative Reports
Relative reports are designed to process data from a certain context selected by the operator when launching 242 the report. This is useful when creating a report for data coming from one Device or system resource. Relative reports are usually activated using the Launch Report 243 action of the context whose data should be processed. For example, in a network management system you may have a Router Interface Usage Statistics relative report. To view this report, you would right-click on any Router Device in AggreGate Client and select Router Interface Usage Statistics from context menu. Relative reports will install their Launch Action only into contexts that are accessible for the report owner according to his permissions 931 .

3.8.4 Launching Reports

When a report is launched, AggreGate Server evaluates its Source Data Expression 241 , uses the data it returns to fill a report template 242 , and shows the prepared report using the Show Report 900 UI procedure. A report can be launched in one of two ways:

2000-2013 Tibbo Technology Inc.

AggreGate Server

243

Directly, using the Show Report 721 action of the Report Context. For relative 242 reports, this method evaluates the Source Data Expression 241 relatively to the context specified by Default Context report property 245 . Using the Launch Report action 892 (see below). For relative 242 reports, this method evaluate the Source Data Expression 241 relatively to the context from which the Launch Report action has been launched.

LAUNCH REPORT ACTION

This action may be found in every context for which the report's validity expression 948 is true. For example, if an Attendance Report is created for a Card Holder context (meaning, its Validity Expression is {.#type} == 'cardholder'), an action called Attendance Report will appear in the context of every cardholder. Its description is the same as that of the report itself. Actions that are used to start reports may be easily recognized by a icon. Please, check References
925

article for details on how the {.#type} reference works.

Here is what a Launch Report action looks like in a context menu within AggreGate Client:

For this action to be available, the user must have an effective permission level Report context
721

935

of User in two contexts:

of the actual report being launched

The context on which the report operates, i.e. the one where Launch Action is defined

2000-2013 Tibbo Technology Inc.

244

AggreGate Documentation

3.8.5 Viewing Reports

A report is accessed using its Show Report 721 context action. This action asks for parameters, fills the report template with data retrieved from various contexts 863 and presents the user with a prepared report:

A report may be printed or exported to a file. See the Show Report

900

UI Procedure for details.

Viewing Previously Created Reports

If the Save History 245 report option is enabled, it's possible to browse, export, print and manage the previously created instances of report. To open the list of previously created reports, run View History action of Report context
721 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

245

3.8.6 Report Configuration

This section covers report configuration properties. All properties described here are available via Configure
904

action of a Report context

721 .

3.8.6.1 Report Properties

Every report has the following basic properties:

Field Description
Name . Name of the report context, used to refer to it from other parts of the system. It should satisfy context naming conventions 863 .

Field Name
name

Description. Textual description

864

of the report context.

246 .

description parameterized expression

Parameterized. Flag indicating that report is parameterized Source Data Expression. Expression template.
911

used to fetch data for populating the report

Parameterizer Source Data. This field is used only when Parameterized flag is enabled. Parameterizer Source Data is used by parameterization engine to build a Source Data Expression at report launch time based on a number of operator-specified parameters. See Parameterized Reports 246 for details. Report Template. The report template, in XML format. Save History. If this option is enabled, the fully filled copy of the report is saved in the server database 80 each time the report is launched. To see all saved copies of the report, run View History action from a Report context 721 . Report Type. Report type
242 ,

parameterizer

template saveHistory

Relative or Absolute.

type validityExpression

Validity Expression. Determines which context(s) may be "understood" by the report. See Resource Validity 948 for more information. Validity Update Rules. A list of context masks and event names. If event specified by Event field of this table occurs in any of context matching to the mask specified by Mask field in the same record, Validity Expression will be recalculated for this context. This allows to make report valid/invalid for a certain context if some changes occur in it. Default Context. The default context to be used for evaluating the Source Data Expression. See Default Context for a Report 242 for details. These properties may be accessed through the childInfo
723

validityListeners

defaultContext

variable.

3.8.6.2 Additional Report Parameters

This table defines additional parameters that are used to fill in the report template. These parameter names must match the names of report parameters used in the reporting engine. The value of each parameter is calculated by an expression
911

entered in the Value field.

Field Description
Parameter. Name of the parameter. Value . Expression used to calculate parameter value. Additional report parameters may be accessed through the parameters
724

Field Name
parameter value variable.

Resolution Environment

2000-2013 Tibbo Technology Inc.

246

AggreGate Documentation

Resolution Environment
Default Context
927

922

used to calculate values of additional report parameters:

Context of report being launched. The result of report parameterization 246 . It means that references in the Value expression may refer to fields defined by the parameters format 956 of the parameterizer source data.

Default Data Table 927 Default Row Environment Variables 930

927

0 Standard
931

variables only.

3.8.7 Parameterized Reports

Report parameterization is useful when you want to let an operator configure a report at runtime. If the Parameterized flag is enabled in report properties 245 , the user may be prompted to input one or more parameters when launching 242 the report. An Edit Data 896 UI Procedure is used to prompt for report parameters. Parameterization is a complex subject, which is beyond the extent of this topic. However, to understand this section, you must have a complete understanding of the Parameterization process and engine. So, if you'd like to use Parameterized Reports and you're unfamiliar with the subject, you should now skip to Parameterization Engine 956 , read the whole topic until you're fully familiar with parameterization, and then come back here. When the Parameterized option is enabled in the Report Properties, the report processing engine uses Parameterizer Source Data to build Source Data Expression 241 in real-time based on a number of operatorspecified parameters. For more information, see Parameterization Engine 956 . Here is an example of Parameterizer Source Data:

<form> <format> <![CDATA[ <<startDate><D><D=Start Date><E=date>><<endDate><D><D=End Date><E=date>><B=<startDate=now()><endDat ]]> </format> <expression> {attendance:timeRecorderEvData('{.:}',"<e>{startDate}</e>", "<e>{endDate}</e>")} </expression> </form> A report containing this parameterized expression will ask for Start Date and End Date parameters upon activation:

The final Source Data Expression used to build a report will something like:

{attendance:timeRecorderEvData('{.:}',"2009-05-01 00:00:00.000")}

00:00:00.000",

"2009-05-02

3.8.8 Reports Security

Report Source Data Expression 241 is resolved using permissions data accessible for this user is used to fill the report. Relative
242 931

of user

108

that is running the report. Thus, only

reports are added only to contexts that are accessible with report owner user's permissions.

2000-2013 Tibbo Technology Inc.

AggreGate Server

247

3.8.9 Reports Performance

Alerts are "passive" server components that don't cause constant CPU load. Performance impact caused by the report generation process is defined by: Performance impact 924 of report's Source Data Expression evaluation. Reports are often build upon a large dataset, requiring considerable amount of memory. Some additional CPU time and memory required to fill in the report template. This is normally a scintilla of resource utilization required to prepare the dataset, but rare really complex templates can increase the influence of template filling process.

3.8.10 Built-in Reports

The basic AggreGate Server distribution contains several built-in reports:

User Accounts
This report contains information about all AggreGate Server user accounts report:
108

accessible by the user who is viewing the

Device Settings Summary

This report shows the summary of all single-cell (i.e. non-tabular and non-array) settings of all Devices:

2000-2013 Tibbo Technology Inc.

248

AggreGate Documentation

Alert History
This report shows the history of a certain alert, and specifically: Alert date/time Alert level Alert cause Alert message Trigger message Acknowledgements, if any This report is Relative
242 ,

it is valid for any Alert context

656 .

3.9 Groups
Groups are used to combine several similar system objects (Users, Devices etc.) to make batch operations more convenient. It is very easy to execute an operation over all objects in a group. Groups also provide an easy way to set similar settings to all group members or automatically replicate configuration changes between them. Another feature of groups is integration with the Common Data 260 facility that allows to have "master" values of group member properties. Changes of master value are automatically applied to all group members.

2000-2013 Tibbo Technology Inc.

AggreGate Server

249

Related tutorial: Using Resource and Device Templates

1263

Administering Groups
Two contexts are used to administer groups: One is the general Groups 701 context, which serves as a container for groups of a particular type. The other is the Group 702 context, which represents one group.

3.9.1 Managing Group Members

New members can be added to the group at any time. The maximum number of group members is not limited. When a group is deleted, group members are not destroyed. An object may belong to several groups. Note for advanced AggreGate administrators: group members cannot be accessed by context 863 paths such as group_context_path.member_name. Instead, the normal paths of group members should be used to access them. For example, even if we put the admin user in the usergroup1 group, we won't be able to access it using a path such as usergroups.usergroup1.admin. It may be accessed by its normal path: users.admin.

Adding Members To The Group

Group members may be added to a group in AggreGate Server User Interfaces by dragging a context 863 and dropping it on a group. If the context type is suitable for the group, it will be added. More information about the logic behind this operation may be found here 702 .

Removing Members From The Group

Every group member context has a Remove from group action 892 ( ), which may accessed through its context menu in AggreGate Client System Tree 784 or through similar facilities in other clients.

Nested Groups
Groups support unlimited nesting, i.e. one group may be a member of another group, that is, in its turn, a member of a third one, etc. Member list of a top-level group includes its "direct" members along with all members of its subgroups (nested groups) at all levels.

3.9.2 Group Types

AggreGate Server supports grouping for all types of devices and resources: user 241 groups, etc.
108

groups, Device

113

groups, report

Some types of groups, such as user groups, are global. They can be created, accessed and managed only by users with administrative permissions 931 . Other groups types, such as Device or Alert groups, belong to a specific user account and thus can be managed both by administrators and normal users (account owners).

3.9.3 Batch Member Operations

Groups provide an easy way to execute the same operation on several different devices or resources. For example, the Group Actions menu for a Device group may have a "Send Message" action, used to send a text message to a device LCD. When using such an action, the user enters the message just once and it is then sent to all Device in the group. Here is what the Group Actions menu looks like for a Device Server group (screenshot from AggreGate Client
776 ):

2000-2013 Tibbo Technology Inc.

250

AggreGate Documentation

3.9.4 Dynamic Groups

A dynamic group maintains its member list automatically by auto-adding contexts that match group's Validity Expression 949 , if the latter is specified. Contexts that do not match Validity Expression are auto-removed. See Resource Validity
948

for more information.

Dynamic groups can still have manually added members. However, there is no way to remove dynamically added members from the group.

Dynamic groups will include only members that are accessible for the group owner according to his permissions 931 .

Example: Validity Expression: startsWith({.:#type},

'device.') && {.:genericProperties$type}

== 'printer'
Update Rules: 1. Mask = users.*.devices.*, Event = infoChanged 2. Mask = users.*.devices.*, Event = updated This dynamic group will include all network printers, e.g. devices 113 those context type string (specified by .: #type reference) starts with device. and device type (specified by type field of genericProperties variable) equals to printer. Each time context type or device type changes (this will be indicated by infoChanged or updated event respectively) the device will be re-considered for the group.

3.9.5 Group Status

Any group may optionally have a status that is dynamically calculated as a function of group members' state. The status is indicated as group's node color in the System Tree 784 . For example, a group of Devices is red if at least one device has error, yellow if at least one device is offline, and green otherwise.

Group Status Calculation

The group status is calculated according to the following rules. 1. Every time when a new member is added or existing member's Member Status Variable is changed, the Member Status Expression is calculated for this member, resulting to member status string. 2. All members status strings are then looked up in the Status Table, from top to bottom. 3. The group status is set according to the highest Status Table record those Member Status Expression Result match at least one member's status string. Let's assume that we have a group with five members. Every member's expression is evaluated into a string value that is normally 100, 200, 300, 400 or 500 (these are strings constants, not numbers). Here is our Status Table: Member Status Group Status (Color)

2000-2013 Tibbo Technology Inc.

AggreGate Server

251

Expression Result 100 200 300 400 500 Green Yellow Red Magenta Blue

The below table illustrates what status will the group get in accordance with different member status string combinations and the above table: Member Status Strings 100, 200, 300, 400, 500 500, 400, 300, 200, 100 300, 300, 300, 400, 500 500, 500, 500, 500, 500 500, 500, 200, 500, 500 200, 200, 500, 200, 200 100, 200, 300, 400, 123 Group Status (Color) Green Green Red Blue Yellow Yellow Undefined

This example illustrates how device group status is calculated by default. Default group status settings of a device group are as follows: Member Status Variable: contextStatus Member Status Expression: ({status} % 10 != 2 && ({status} - {status} % 10) ==

40 ? 1 : ({status} % 10 == 1 || {status} % 10 == 2 ? 3 : 2))

Status Table: Member Status Expression Result 1 2 3 Color Description

Dark Red Dark Yellow Dark Green

Error Offline Online

The above group status configuration uses devices' context status 678 information to calculate status of device group. There are three defined statuses of a device group: Error (meaning that at least one device reports an error), Offline (meaning there are no errors but at least one device is offline or its connection state is unknown) and Online (meaning that all devices in the group are connected and report no errors). The member status expression analyzes integer status field of contextStatus variable. This status can be parsed into: Number of tens representing device synchronization status error, etc.) Number of units representing device connection status
127 128

(20 = synchronized, 40 = synchronization

(0 = offline, 1 = online, 2 = suspended, 3 =

2000-2013 Tibbo Technology Inc.

252

AggreGate Documentation

status unknown) The device group individual member's status expression result is: 1 (Error) if device is not suspended ({status} % 10 != 2) and reports a synchronization error ( ({status} - {status} % 10) == 40) 3 (Normal) if device is suspended or online ({status} % 10 == 1 || {status} % 10 == 2) 2 (Offline) otherwise See Group Status configuration
253

article for more information.

3.9.6 Member Properties Replication

Groups also let you easily copy settings between group members in manual or automatic mode. In manual mode, some or all settings may be replicated from one group member to all other members. In automatic replication mode, the group monitors all members for configuration changes, and if such changes are detected, they're copied to all other members. This feature maintains group members in sync with each other.

Manual Replication
Every Group context 702 has a Replicate to children 910 action, used to copy the settings from one group member to all other members. This action is very convenient to configure group members in the same way.

Automatic Replication
Groups also support auto-replication. Auto replication turned on by Enable Auto-replication 253 flag and controlled by the Replication Options 254 property of a group. This property is a table, containing a list of properties (variables 869 ) appearing in the group member contexts. Auto-replication may be enabled or disabled separately for every property. If the auto-replication option is enabled for a certain property, changes to its value in one of the group members are automatically applied to all other members. For example, if there are three Devices 113 (A , B and C) in a group G1 and Device B is disabled (e.g. by editing its properties in AggreGate Client), Devices A and C will be automatically dosabled as well. Auto-replication works in a single group only: if Device C is a member of two groups (G1 and G2) and was disabled during auto-replication in G1, other members of group G2 will not be disabled. This prevents unexpected 'domino' effects, whereby one change to a replicated group creates unexpected chaos. When an auto-replicated group detects changes to a property of one of the group members, it takes the value of this property (gets the Data Table 854 containing the value of the context 863 variable 869 ) and sets that value for the same property of other group members using a Data Table Smart Copy 861 operation.

3.9.7 Group Member Context Masks

If is often necessary to select all group members for some kind of processing using a context mask examples: Making an alert
216 865 .

Here are some

that applies to the group members

271

Executing a query

to fetch some data from group member contexts

206

Configuring an event filter

to show only events that was generated by Devices participating in a certain group

To construct a mask that will match 866 all group members, take group's context path and append a wildcard section (". *") in the end, e.g.: users.admin.alerts_groups.snmpAlerts.* Example: If default administrator 109 owns a device group called environment that includes all datacenter environment monitoring devices, use the following mask to match all group member Devices:

users.admin.devgroups.environment.*
This mask will be resolved to the list of member devices, e.g.:

users.admin.devices.temperature_sensor users.admin.devices.humidity_sensor users.ny_datacenter_operator.devices.smoke_sensor users.ny_datacenter_operator.devices.spill_detector

2000-2013 Tibbo Technology Inc.

AggreGate Server

253

3.9.8 Group Configuration

This section covers group configuration properties. All properties described here are available via Configure
904

action of a Group context

702 .

3.9.8.1 Group Properties

This property defines basic options of a group.

Field Description
Group Name. Name of the group context, required to refer to this group from other parts of the system. It should satisfy the context naming conventions 863 . Group Description. Textual description of the group. This is also a description group context. Enable Auto-replication. Enables auto-replication
252 864

Field Name
name

of the

description

for this group.

autoReplication hideMembers

Hide Members From Primary Location . If this flag is enabled, group member contexts are shown inside the group, but not shown under their parent context. This is a mapping feature that affects only the visual representation of the server context tree (e.g in System Tree 784 ). Components that show a real (non-mapped) context tree (e.g. Entity Selector 815 ) will show group member contexts at their real locations specified by context paths. No children will be visible under the group context in this case. Members are not hidden from primary location:

Members are hidden from primary location:

Validity Expression. Determines which context(s) may be automatically added to the group. See Dynamic Groups 250 and Resource Validity 948 for more information. Validity Update Rules. A list of context masks and event names. If event specified by Event field of this table occurs in any of context matching to the mask specified by Mask field in the same record, Validity Expression will be recalculated for this context. This feature is used for automatically adding/removing a certain context from a group if some changes occur in it. This property may be accessed via the childInfo
704

validityExpression

validityListeners

variable.

3.9.8.2 Group Status

This property defines group status
250

evaluation rules.

Field Description
Enable Custom Status. Flag that controls whether custom status is enabled for a group.

Field Name
enabled

2000-2013 Tibbo Technology Inc.

254

AggreGate Documentation

Member Status Variable. Property (variable) of group members that will be used to calculate status of each member. Member Status Expression. This expression will be evaluated for every group member to find out a status value (String) for this member. This value will be than looked up in the Status Table.

variable

expression

Member Status Expression Resolution Environment Default Context

927

922

Context of current group member.

Default Data Table

927

Current value of the Member Status Variable.

Default Row 927 Environme nt Variables

930

Standard

931

variables only.

Status Table. The lookup table used to calculate aggregate status of the group as described in the Group Status 250 article. The table has three fields: Member Status Expression Result. Result of Member Status Expression evaluation. Color. A color that will be used to mark the group with such status (there are twelve predefined group status colors). Description . Description of this status. This property may be accessed via the groupStatus
704

statuses

variable.

3.9.8.3 Replication Options

This property defines parameters of replication
252

performed by the group for every setting of its members.

Field Description
Property. Name of the variable
869

Field Name
(property) to apply the replication rule to. variable description replicate useMaster

Description . Description of the above property. Auto-replication. Use automatic replication for this variable. Use Common Table. Use a master value 255 for this property. This setting may be enabled only if Auto-replication is disabled for this property and Current Common Table with Master Value is not empty (i.e. a Common Table containing a master value exists). Current Common Table with Master Value . Description and location 261 of the Common Table that may be used as a master value of a property. This is a read-only field. Replication options may be accessed through the replication
705

master

variable.

3.9.9 Groups Security

Only members that are accessible for the group owner can be added to the group. Example: If device Dev1 is not accessible for user Joe's group Grp1 according to his permissions table even the default administrator 109 won't be able to put Dev1 into Grp1.
931 ,

2000-2013 Tibbo Technology Inc.

AggreGate Server
Groups may retrieve diverse data from its member contexts (e.g. during evaluation of Group Status Thus, group owner must have sufficient permission level 932 in all group member contexts.
250

255

expressions).

Dynamic Group Permissions

Dynamic
250

groups will include only members that are accessible by the group owner according to his permissions.

Master Values of Member Properties

Any Common Table owner.
260

used as a master value

255

of group member's properties must be accessible by the group

3.9.10 Groups Performance

Static groups are passive server components that don't cause significant CPU load or memory usage. Dynamic 250 groups may rarely cause considerable CPU load if group's Validity Expression re-evaluation is often triggered by group's Validity Update Rules. See expression performance 924 to estimate the performance impact. Example: If a dynamic group includes 100 devices and its Validity Update Rules refer device event that's triggered by every device as 10 Hz rate, the Validity Expression will be evaluated 1000 times per second.

3.9.11 Master Values of Member Properties

Integration of groups with Common Data 260 facility allows to have "master" values of group member properties. When this master value is changed, changes are automatically applied by the group to all its members that have this property. To create a master value for a certain property: First, create a common table to contain the master value, using the Create New Table From Variable 666 action of any Common Data context. The source variable for common table creation should be a variable of one of the group members. Its value will be copied to all other group member when the "master value" feature is enabled for it. The common table must be located in the User Common Data container 261 under the group owner, or in the Global Common Data container. Then, enable the Use Common Table setting in the Replication Options 254 for the record you want to replicate. If the Common Table was properly created in the previous step, the Current Common Table with Master Value setting will show the description and location of the master value:

If Common Tables that can be used as a master value for a property were created in both Global and User Common Data containers, the user's container will be used. Example: Let's say your Device is a time recorder that has "Bell Table" setting, defining several daily alarms. You can drag the time recorder and drop it on the Global Common Data 666 in AggreGate Client, launching a Create New Table From Variable action. You'll now be prompted to select the variable to be used as a source for the new common table. Select "Bell Table":

Once the variable has been selected, a new common table is created in the global container. It contains the list of alarms that were defined in the dropped Device:

2000-2013 Tibbo Technology Inc.

256

AggreGate Documentation

You'll now create a new Device group and populate it with some time recorders:

Next, launch the Group Properties Replication Options look like:

702

action to configure the group. The group settings dialog will open. Here is what the

The Use Common Table setting can be enabled for Bell Table because a corresponding master value is found in the Global Common Data container. Let's enable it and save changes. Now our group monitors changes to the Bell Table located in the common data. If someone edits the table, updated bell times will be saved to all time recorders in the group.

3.9.12 Groups in Distributed Architecture

This section describes specifics of groups behavior in a distributed installation
99

of AggreGate.

If a group from a provider server is connected to a context tree on a consumer server, consumer server users may add this group as a subgroup to other consumer server groups. If a local consumer server group has custom status 250 calculated upon statuses of its members, including members of nested subgroups, the logic of status calculation will differ for local and remote subgroups: For a local subgroup, each subgroup's member is directly processed by a top level group. The top level group calculates Member Status Expression for local subgroup's members and put their individual statuses to its member status 705 table. For a remote subgroup, only aggregated subgroup status received from a provider server is processed. Members of a remote subgroup are not processed individually. The aggregated subgroup's status is added to top level group's member status table and considered during its status evaluation.

The above rules effectively mean that if remote groups are put into local groups with dynamic status, status evaluation rules of local and remote groups should match to avoid errors on consumer server.

2000-2013 Tibbo Technology Inc.

AggreGate Server

257

3.10 Trackers

Trackers help watch mission-critical server data in real-time. All trackers are shown togethe table (e.g. Trackers 824 window in AggreGate Client) to enable efficient monitoring. Trackers use highlighting to indicate their state .
Here is what the trackers table looks like in AggreGate Client:

The basis of a tracker is a tracked expression written in AggreGate Expression Language 911 . This expression may refer to some server data or to data originated from hardware Data Terminals 113 . A simple tracked expression may be used to monitor some value directly, while more complicated ones help track combinations of several values. For example, a tracker can be easily set up to watch dew point temperature calculated by temperature and absolute humidity measurements coming from different sensors. Every user
108

has his own set of Trackers.

The value of each active tracker expression is recalculated periodically, as specified by the Check Period the tracker.

258

property of

Administering Trackers
Two contexts are used to administer trackers: One is the general Trackers 750 context, which serves as a container. The other is the Tracker 753 context, which holds the information for one tracker.

3.10.1 Tracker Status

Tracker status lets system operators quickly check the state of a tracker by highlighting it in the trackers list. Statuses can help detect trackers that indicate warning and critical conditions of the monitored values. It is possible to associate an unlimited number of user-defined states with every tracker. The Status Table 258 property is used to determine current tracker status. Tracker status is determined once per Check Period 258 , immediately after calculation of tracked expression. Tracker Status Table is browsed line by line, starting from the first one. The Expression specified in the current line of the status table is evaluated. Tracker status expression should contain a special {tracker/} reference 925 pointing to the value of tracked expression. If the result is TRUE, tracker status is changed to the one defined by the currently processed line of status table. When the result is FALSE, processing skips to the next record in the table. If the status table is empty, or no expressions evaluate to TRUE, the status is considered as undefined . When tracker status changes, its Description appears in the trackers list and it is highlighted with the Color contained in the status table record (if any). State Change 755 event is generated at the same time. History 882 of this event can be used to view the past state changes with the Monitor Related Events 909 action of the Tracker context 753 . Here is what the status table for a simple temperature tracker looks like (screenshot made in AggreGate Client):

2000-2013 Tibbo Technology Inc.

258

AggreGate Documentation

According to this table, tracker status will be Extremely Low if temperature is lower than 15 degrees, Very Low if temperature is between 15 and 19 degrees etc.

3.10.2 Tracker Configuration

This section covers tracker configuration properties. All properties described here are available via Configure
904

action of a Tracker context

753 .

3.10.2.1 Tracker Properties

This property defines the basic options for a tracker.

Field Description
Tracker Name. Name of the tracker context. It should satisfy context naming conventions 863 . Name is required to refer to this tracker from other parts of the system. Tracker Description. Textual description of the tracker. This is also a description of the tracker context. Tracked Expression. The expression to be tracked.
864

Field Name
name

description

expression enabled

Enabled. If the tracker is not enabled, no calculations of its value and status are performed periodically. Check Period. Defines how often tracker value and status is recalculated. Hide If Status Undefined. If a tracker currently has no custom status 258 (i.e. no status expressions were resolved to TRUE), it will be hidden from the trackers list if this flag is set. History Storage Time . Sets the period of raw tracker history expiration. Technically, this is how long are the changes of Tracker variable stored in the database. An alternative method of keeping tracker history is using Tracker Statistics 259 .

period hideIfNoStatus

historyStorageTime

These properties may be accessed through the childInfo

754

variable.

3.10.2.2 Status Table

This property defines tracker status
257

calculation rules, and the characteristics of every status.

Field Description

Field Name

2000-2013 Tibbo Technology Inc.

AggreGate Server

259

Description . Textual description of tracker status. Expression . Expression that must be true to activate status. Color. Color used to highlight the tracker when this status is active. Level of status change event. Severity when status is changed to this one.
882

description expression color event that is generated level

of Status Change

755

Status table may be accessed through the statusTable

754

variable.

3.10.3 Tracker Statistics

Trackers support statistical channels values.
936

that help to maintain long-term history for trackers that represent numeric

If a new channel is added to the tracker's Statistical Channels table, this channel will be pre-configured to convert tracker value to a number and collect its stats.

Viewing Tracker Statistics

To view brief statistics of the tracker, run View Status
910

) action and switch to Statistics tab.

Here is how brief tracker statistics look like in AggreGate Client:

Viewing Detailed Statistics

To view detailed tracker statistics, use global View Statistics
729

action.

3.10.4 Trackers Security

The tracker's Tracked Expression is evaluated with tracker owner's permissions data that is accessible by its owner.
931 .

Thus, tracker may refer only

If you create a copy of a certain tracker under another user account 108 , the copy may not function properly if new tracker's owner has no permissions to access data referred by the Tracked Expression of the cloned tracker.

3.10.5 Trackers Performance

CPU load and memory usage caused by a tracker is completely defined by CPU and memory impact Expression and Status expressions.
924

of its Tracked

Trackers should be used only for calculating values that are supposed to be constantly monitored by system operators. Using trackers to pre-calculate some values to later display them on widgets 312 or dashboards 617 is generally a bad idea since the tracker value will be periodically recalculated even when this value isn't being displayed, causing performance overhead. To avoid this, get rid of trackers by using one of the following techniques: For non-reused trackers, just copy tracker's tracked expression to a widget binding expression previously referred tracker value
606

what has

2000-2013 Tibbo Technology Inc.

260

AggreGate Documentation
309

For reused trackers, define a model 303 with several functions functions from your widget binding expressions

that perform necessary calculations and refer those

3.10.6 Tracker Examples

This article describes some simple tracker expressions.

Calculating Devices
Tracked Expression: aggregate("users.*.devices.*", "{env/previous} + ({.:

status$connectionStatus} == 1 ? 1 : 0)", 0)
This expressions uses aggregate() function to screen all device contexts (i.e. all context matching users.*. devices.* mask 865 ) and calculate those having connectionStatus field of the status variable equal to 1 (i.e. "online"). It will return number of online devices available to the user who owns the tracker. Thus, if executed with default administrator 109 's permissions, it will return total number of online devices in the system.

Calculating AggreGate Server Memory Usage

Tracked Expression: round(({:status$totalMemory} - {:status$freeMemory}) * 100 / {:

status$maxMemory})
First, amount of memory currently used by the Java VM is calculated by taking current allocation size and subtracting its free part. Second, the above number is divided by the maximum memory size that the JVM is allowed to allocate. This gives the relative memory usage that is multiplied by 100 to calculate the percentage.

3.10.7 Built-In Trackers

Several trackers are built into AggreGate Server and appear under default administrator's Total Users. Shows the number of user accounts Total Devices . Shows the number of Devices
113 108 109

user account:

in the system.

in the system.

Online Devices. Shows the number of Devices currently online. Offline Devices. Shows the number of Devices currently offline. Suspended Devices. Shows the number of Devices currently suspended. AggreGate Server Memory Usage. Shows the memory used by AggreGate Server as a percentage of the total memory available for it according to the Java Virtual Machine (JVM) startup configuration. The usage tend to follow a "sawtooth pattern" since it grows during normal server activities and instantly drops during a garbage collection that occurs in the JVM. Garbage collection is a form of automatic memory management. The garbage collector periodically attempts to reclaim garbage, or memory occupied by objects that are no longer in use by the program.

3.10.8 Trackers in Distributed Architecture

This section describes specifics of trackers behavior in a distributed installation
99

of AggreGate.

To make a tracker connected from a provider server appear in Trackers table of clients connected to a consumer server, make sure that the context path of connected tracker context on the consumer server matches users.*. trackers.* context mask, i.e. the remote tracker appears among local trackers.

3.11 Common Data

Common Data is a custom data storage facility that may be used by various AggreGate Server components and plugins 950 to perform specific operations, such as data replication, data sharing and configuration management. See Uses Of Common Data 261 for details. The Common Data container
261

is like a database, built of tables, supporting the following operations:

2000-2013 Tibbo Technology Inc.

AggreGate Server

261

Creating tables. The Common Data container supports creating a number of tables. The only restriction is that all the tables inside a Common Data must have a unique names. Every table has both a name and a description, but the description doesn't have to be unique. Removing tables: A table inside a Common Data node may be removed, along with all data it contains. Defining and modifying table structure : The user (or a specific plugin) may dynamically change the structure of a table in a way suitable for a task being performed. Viewing and editing data: Users can view and modify the contents of a Common Data table. A common table is a Data Table 854 of a user-defined format which is administered using the Common Data context, and which may be accessed by different users or Devices.

Common Data Containers

Every Common Data container is represented by a Common Data context 666 . Containers are owned by AggreGate Server users. Every uses has his own Common Data context with a path like users.USER_NAME.common. A user can use his Common Data Container to store data that should be shared between his Data Terminals or Groups 248 , such as a logo file that all Devices should display. See Uses of Common Data 261 for details.

Administering Common Data

Two types of contexts are used to administer common data (and the tables containing it): one is the Common Data 666 context, which serves as a container for several common tables. The other is the Common Data Table 668 context, which holds the information for one common table.

3.11.1 Uses of Common Data

Common data tables are used in several different scenarios. See the below articles for details: Custom Data Storage Custom Properties
261 262 263 261

Master Properties of Devices

Master Properties of Group Members

3.11.1.1 Custom Data Storage

Common tables can be created by the system administrator manually, from scratch, to contain some custom data that is not automatically generated or used by AggreGate Server components. This can be, for example, an inventory of equipment belonging to the company. This table may contain the description and location of each piece of equipment, person responsible to it etc. The administrator could allow users to view or edit it. It can be later referred from different parts of the system. For example, you could create a query 271 showing how many pieces of equipment are under the responsibility of every system user 108 .

3.11.1.2 Custom Properties

It's possible to "attach" a common table to one or more contexts 863 in the form of a Custom Property. This method allows AggreGate administrators to add new properties to different system objects and later refer to these properties from all parts of the system. For example, it's possible to extend all devices with a Location property containing the building, floor, and room number where this piece of hardware is physically located. After that, it will be very easy to view locations of all equipment using a query 271 , or make a report. For this use, only format of common table is shared between different contexts, while each of them has its own data (custom property value). Related tutorial: Adding Custom Properties
1258

2000-2013 Tibbo Technology Inc.

262

AggreGate Documentation

Custom property will be added only into contexts that are accessible for the common table owner according to his permissions 931 . To be able to read this property, the user must have an effective permission level contexts: Common table context
668 935

of Observer in two

of the common table that servers as the base for this custom property

The context to that the property is added To be able to write this property, the user must have an effective permission level same contexts.
935

of Manager in the

Edit Custom Properties Action

The Configure 904 action called Edit Custom Properties is used to edit values of custom properties It's added to a context when it has at least one custom property. Action Icon:
261

of a context.

3.11.1.3 Master Properties of Devices

A common table may contain a master value for a certain property of several Data Terminals 113 . AggreGate Server monitors changes in the common table and when these changes are detected it takes the "master" common table and copies it to several Devices. Just like in the Master Properties of Group Members 263 use case, the common table is created based on the value of a context variable, but here we're using a Data Terminal context 677 variable. Same rules apply to the name and format of common table. More information on this feature can be found here
120 .

Real-World Example
For example, let's say our Devices have a "Checklist Table" setting, containing a list of things that should be checked by the Device operator after device startup. This Checklist Table should be same (or almost the same) for all Devices in the facility. Thus, we can create a Common Table that will contain "master" Checklist Table. The creation process is quite simple. Note that this is a hypothetical example -- you might not have Devices with this exact setting. It's here just to give you a general idea of what the process looks like. This is how you would do it in AggreGate Client 776 , had you had Devices with such a table: 1. Drag any Device node ( ) in System Tree
784

and drop it on the Common Data node (

).

2. Select Checklist Table from the drop down list:

3. A new Common Table will be created and shown in the System Tree:

4. Run the Edit Device Properties

677

action for your Devices, go to the Device Settings Synchronization Options

2000-2013 Tibbo Technology Inc.

AggreGate Server

263

tab and change Synchronization Mode for Checklist Table to Use Server-Side Master Value. After that, select your new common table in the Master Value field:

5. Now, a new master Checklist Table will be written to all Devices. You could open the settings of any Device and see that its Checklist Table setting is not editable anymore. Instead, a button fills the row, with a label saying "Using common data table":

6. You can click this button to see what data was written from Common Table to the Device:

If it is necessary to exclude particular checklist items from some Devices, see the Record Permissions figure out how to do this.

265

section to

3.11.1.4 Master Properties of Group Members

A common table may contains a master value for a certain property of all group 248 members. The group monitors the common table for changes, and when changes are detected, the group rewrites a certain property 869 for all group members according to the contents of the common table. This is easy, because the various property values of a context 863 are represented by a Data Table 854 , just like the common table 263 . In this scenario, the common table isn't created from scratch by adding fields and records. Rather, it has to be created using the Create New Table from Variable 668 action, which takes the value of a user-specified context variable and creates a new common table with the same format and contents. The common table's Format 263 must match (or extend) the format 855 of the property whose whose master value it contains. So it must contain all fields defined for that property, but may also contain additional fields. The common table's name must be be the same as the name of the linked property -- this allows the group to find this common table and propose it to be used. More info on this feature can be found here
255 .

3.11.2 Common Table Contents

Every common table is actually a single Data Table 854 . Its format 855 is specified by its fields 264 property, and can be changed using Configure Common Table 668 action. The number of records is limited by the minimum and maximum values defined in the table properties 264 . Records in the table can be reordered. When the table format (format of table field(s), to be precise) is changed while the table already contains some data, AggreGate Server does its best to preserve existing data and convert it to the new format. In most cases data in the table is not changed. For example, if an Integer field was converted to String, values in this fields are converted to strings. But if a String field was converted to Integer, not every string value of field may be converted to integer number and some data may be lost. This is why you should avoid changing table structure if it contains important data. The only exception to the above rule is field renaming. Field renaming is supported only it the table is empty (doesn't contain any data). Changes in table format that may affect table data: Changing field type (values that cannot be converted to a new type will be set to default value for this field). Switching field from Nullable to non-Nullable (NULL values will be changed to default). Removing some items from Selection Values if Extendable Selection Values is disabled for this field (the cells that used to contain the values that were removed will be set to default).

2000-2013 Tibbo Technology Inc.

264

AggreGate Documentation

Disabling Extendable Selection Values (cells that contain values that doesn't appear in Selection Values will be set to default). When the Minimal number of records is set to a value greater than the current number of records in the table, empty records with default values are created to "fill the table up". When the Maximal number of records is set to a value lesser than the current number of records in the table, any 'extra' records are trimmed off the end of the table (removed). The common table's data is stored in AggreGate Server database viewed and edited using the Edit Data 668 action.
80

along with all other context properties. It can be

When changes are made to the format or contents of a table, they're detected by other system components. For details, see Uses of Common Data 261 (specifically, Integration with Groups and Integration with Data Terminals). Contents of a Common Table (screenshot from AggreGate Client):

3.11.3 Common Table Configuration

This section covers common table configuration properties. All properties described here are available via Configure
904

action of a Common Table context

668 .

3.11.3.1 Common Table Properties

This property defines the basic options of a common table.

Field Description
Table Name. Name of the common table 668 context. It should conform to context naming conventions 863 . This name is used to refer to this table from other parts of the system. Table Description. Textual description of the table. This is also a description Common Table context. Minimal number of records. Maximal number of records. Enable per-record permissions. Per-record permissions let you control which contexts access each and every record in the table (as opposed to controlling access to the whole table). These may be accessed via the childInfo
669 863 864

Field Name
name

of the

description

minRecords maxRecords recordPermissions

variable.

3.11.3.2 Common Table Fields

This multi-record property defines the fields of a common table.

Field Description
Name . Unique name of the field. Type . One of the types supported by the Data Table Format
856 .

Field Name
name type

2000-2013 Tibbo Technology Inc.

AggreGate Server

265

Description . Textual description of the field. Default. Default value of the field. Read-only . Indicates that field is read-only. Nullable. Indicates the field may contain NULL ("Not Set") values. Key. Indicates that field is a key field
856 .

description default readonly nullable key selvals extselvals

Selection Values. List of possible values for this field. Extendable Selection Values. Indicates that the field may contain values that are not listed in Selection Values. Help. Additional info about the field. Editor/Viewer . Defines how the value of the field is edited. For example, Data Block 857 fields may be edited using Image Editor, Sound Editor of generic File Editor. More info about field properties can be found here
855 .

help editor

These may be accessed via the fields

669

variable.

3.11.3.3 Custom Properties

This property defines how the common table is used as a custom property
261 .

Field Description
Use common table as custom property . When enabled, this common table is added as a custom property to the contexts according to Validity Expression. Validity Expression. Determines which context(s) the custom property will be added to. See Resource Validity 948 for more information. Validity Update Rules. A list of context masks and event names. If event specified by Event field of this table occurs in any of context matching to the mask specified by Mask field in the same record, Validity Expression will be recalculated for this context. This allows add/remove custom property from a certain context if some changes occur in it. These may be accessed via the customProperties
670

Field Name
enabled

validityExpression

validityListeners

variable.

3.11.4 Common Table Record Permissions

There is a method to associate a set of permissions with every record in the common table. This feature is called "Perrecord permissions" is may be enabled or disabled for a particular table by editing basic properties 264 of a table. Record permissions define which AggreGate Server contexts 863 have access to this record. This feature is used in Master Properties of Group Members 263 and Master Properties of Devices 262 use cases. When a group 248 or Data Terminal 113 context retrieves the contents of a common table, it only gets records to which it has permissions. Example: Let's say that the common table contains a checklist of actions to be performed with certain hardware devices on startup. This list is written to every device using the Integration with Data Terminals feature, causing the device's operator to complete all checkup items during device startup. Obviously, not all device types need the same items in the checklist. Sure, most of them may need an item such as "Swipe your ID card" (for a vehicle control system), but only some would need an item such as "Verify there are no leaks in hydraulics system". In a scenario like this, per-record permissions come in handy. For every record in the this hypothetical Checklist table, we may specify a list of Devices (Device contexts, to be precise) to which it applies. We can even specify them as groups 248 (see below). A given checkup item (record) will be written only to the Devices which are allowed to access it per this table.

2000-2013 Tibbo Technology Inc.

266

AggreGate Documentation

Common table per-record permissions differ from user 108 's permission tables 933 . A user's permissions define which contexts he may access, and which operations he may execute in every such context. In contrast, common table record permissions define which contexts may access a given record. Currently, this is only useful in the following scenarios: For Integration with Groups, the permission list may contain only Group contexts in the list will write this record for their members.
702 .

Only groups specified

For Integration with Data Terminals, the permission list may contain Data Terminal contexts 677 and Group contexts 702 of Data Terminal groups. In the former case, the record will be accessible by a certain Data Terminal. In the latter case, it will be accessible by all Data Terminals in a group. If you're trying to keep a table secure, you'd better control who can edit the table itself -- don't just set perrecord permissions. When per-record permissions are enabled, every record in table contains two additional fields: Access to record Permissions

The Access to record field has three possible values: Enabled, Disabled and Determined by permissions. When access is Enabled, per-record permissions are switched off for this record, and every group or Data Terminal has access to it. When access is Disabled, no groups and Devices will receive this record when retrieving the table's contents. And when the field it set to Determined by permissions, you can set a list of groups or Devices which will have access to this record. If a user is allowed to edit the table itself, he may modify per-record permissions. When the Integration with Devices feature is used to work with a common table, the permission list may contain not only ordinary Data Terminal contexts, but also Data Terminal groups . When a Data Terminal group is added to the permissions list of a specific common table record, all of its members will have access to this record.

3.11.5 Common Data Performance

Common tables require as much memory as needed to store the whole table data. Note, that if a table is used as a custom property 261 multiple instances of table are created, requiring more memory. Tables used as custom properties may in very rare cases cause considerable CPU load if table's Validity Expression reevaluation is often triggered by table's Validity Update Rules. See expression performance 924 to estimate the performance impact.

3.12 Scheduled Jobs

The primary purpose of the Scheduler is automatic non-interactive execution of actions time schedule. To run, a scheduled job requires the following: Context mask
865 892

according to a user-defined

that matches the contexts from which the action will be executed

Name of an action to execute Any input parameter(s) required for the action At least one trigger to determine when the action is executed The scheduler stores its internal state persistently. This means that when the server is restarted, the scheduler can detect if any scheduled jobs were missed (not launched) while the server was down. The Scheduler executes actions in headless (non-interactive) mode execution cannot be scheduled. Basic properties of a scheduled job are described here
270 . 893 .

Actions that don't support non-interactive

2000-2013 Tibbo Technology Inc.

AggreGate Server

267

Every user

108

has his own set of Scheduled Jobs.

Related tutorials: Scheduled Report Emailing

1254 1269

Scheduling Device Downtime

Tracking Execution History

Use Monitor Related Events Execution history of a job Errors reported by the executed action
909

action of the Job context

744

for viewing:

Administering Scheduler
Two contexts are used to administer scheduled jobs: One is the general Scheduled Jobs 742 context, which serves as a container. The other is the Scheduled Job 744 context, which holds the information for one scheduled action.

Built-In Scheduled Jobs

Several scheduled jobs are built into AggreGate Server: Check Incoming Mail . This scheduled job is used by AggreGate Server to fetch mail from incoming mail server. It is necessary for acknowledging alerts by email 228 . Remove Expired Events. This scheduled job is responsible for periodic removal of expired events from event history 882 . It's not recommended to delete or reconfigure it. Scheduled Server Restarts . This job restarts AggreGate Server when a restart operation was scheduled by administartor. Scheduled Server Shutdowns . This job stops AggreGate Server when a shutdown operation was scheduled by administartor.

3.12.1 Job Triggers

The scheduled job can be activated by either of two types of triggers. Trigger - an act that sets in motion some course of events.

Simple Triggers
According to a single simple schedule trigger, action is executed predefined number of times with a fixed period. It is also possible specify start and end of time interval when the execution may take place. It is possible to define more then one trigger of this type. When execution is finished (this may happen because repeat count or end time is reached), the corresponding trigger is automatically removed from schedule. Properties of simple triggers are described here 270 .

Advanced Triggers
Advanced schedule triggers allow complex execution patterns like "execute every minute starting at 2pm and ending at 2:59pm, every day" or "execute at 10:15am on every last Friday of every month during the years 2009, 2010, 2011 and 2012". There can be more than one such trigger. Triggers are automatically removed from the schedule when no executions should happen in the future, but in practice this happens only if the Year option is set to some finite range of years. Properties of advanced triggers are described here 270 .

2000-2013 Tibbo Technology Inc.

268

AggreGate Documentation

Execution may not be scheduled for any combination of Day of Month and Day of Week at the same time. If execution pattern for any Day of Month is set to a non-Never value, patterns for every Day of Week must be set to Never and vice versa.

EXAMPLES OF ADVANCED TRIGGERS

Day of Month Month Day of Week Year Time Start Date/Time End Date/Time Execution Pattern Day of Month Month Day of Week Year Time Start Date/Time End Date/Time Execution Pattern Day of Month Month Day of Week Year Time Start Date/Time End Date/Time Execution Pattern Day of Month Month Day of Week Year Time Start Date/Time End Date/Time Execution Pattern Day of Month Month Day of Week 05:15:00 <Not set> <Not set> At 5:15am every Monday, Tuesday, Wednesday, Thursday and Friday. 15th: Always, other days : Never All months : Enabled All days : Never 17:55:00 <Not set> <Not set> At 5:55pm every Wednesday in the month of March. All days : Never All months : Enabled Mon - Fri : Always, other days : Never 09:00:00 <Not set> <Not set> At 9:00am every day. All days : Always All months : Enabled All days : Never 2005 09:00:00 <Not set> <Not set> At 9:00am every day during the year 2005. All days : Never Mar : Enabled, others months: Disabled Wed : Always, other days : Never All days : Always (execute on every day of month) All months : Enabled All days : Never (disabled, Day of Month is used in this pattern)

2000-2013 Tibbo Technology Inc.

AggreGate Server

269

Year Time Start Date/Time End Date/Time Execution Pattern Day of Month Month Day of Week Year Time Start Date/Time End Date/Time Execution Pattern Day of Month Month Day of Week Year Time Start Date/Time End Date/Time Execution Pattern 09:00:00 <Not set> <Not set> At 9:00am on the last Friday of every month. All days : Never Jan - Mar : Enabled, other months : Disabled Fri: Last, other days : Never 2006 - 2008 09:00:00 <Not set> <Not set> At 9:00am on the last Friday of every January, February and March during years 2006, 2007 and 2008. All days : Always All months : Enabled All days : Never 09:00:00 <Not set> <Not set> At 9:00am on the 15th day of every month. All days : Never All months : Enabled Fri: Last, other days : Never

Day of Month Month Day of Week Year Time Start Date/Time End Date/Time Execution Pattern

09:00:00 01.07.2007 00:00:00 01.08.2008 00:00:00 At 9:00am every day, first execution at 01.07.2007 09:00:00, last execution at 31.07.2007 09:00:00.

3.12.2 Action Parameter Processing

Input parameters 270 of an action being scheduled are pre-defined at the stage of scheduled job creation and saved in the database 80 . However, it's often necessary to change/update these parameters at the time of scheduled job execution. To implement this: Open any parameters table for editing. It will be possible to add/modify its bindings Add one or more bindings to the table. These bindings will be calculated at the time of job execution. They will update value of pre-defined action parameters. See Input Parameter Bindings
893 813 .

for more information.

2000-2013 Tibbo Technology Inc.

270

AggreGate Documentation

3.12.3 Job Configuration

This section covers scheduled job configuration properties. All properties described here are available via Configure
904

action of a Job context

744 .

3.12.3.1 Job Properties

This property defines basic options of a scheduled job.

Field Description
Job Name. Name of the scheduled job context. It should satisfy the context naming conventions 863 . Name is required to refer to this job from other parts of the system. Job Description . Textual description of the job. This is also a description Scheduled Job context.
864

Field Name
name

of the

description

Job is Enabled. All triggers of enabled jobs are active and job is executed. When job is re-enabled after being disabled for some time all misfired triggers are executed. Context Mask. Context mask 865 defines a number of contexts to call the scheduled action from. When scheduled job is launched, selected action is launched in consecutive order from every context that matches to the mask. Action. Name of the action to be launched. Parameters. Action-specific parameters. These parameters are used to substitute user input when scheduler job executes action in non-interactive mode. For example, if scheduled action requires confirmation (i.e. asks user something like "Delete query?" and allows to click OK or Cancel), this field will contain a "Delete query?" parameter with two possible choices: "OK" and "Cancel". These properties may be accessed through the jobDetailsView
745

enabled

mask

action input

variable.

3.12.3.2 Simple Schedule

This property defines one or more simple triggers for a scheduled job. It has multi-line format.

Field Description
Start Date/Time. Time before that execution is not allowed according to this trigger. Default value is <Not set>, so execution starts immediately after the trigger is created. End Date/Time. Time after that execution is not allowed according to this trigger. Execution ends and trigger is deleted when this time comes. Default value is <Not set>, so execution is ended when Repeat Count is reached or continues endlessly is Repeat Count is set to 0. Repeat Count. Number of executions. Execution ends and trigger is deleted when job is executed Repeat Count times according to this trigger. Default value is 0 what means "execute unlimited number of times". If this option is set to zero, execution may end only when End Date/Time comes if is defined. Repeat Interval. Specified in seconds. Simple schedule may be accessed through the triggersView
745

Field Name
startTime

endTime

repeatCount

repeatInterval variable.

3.12.3.3 Advanced Schedule

This property defines one or more advanced triggers for a scheduled job. It has multi-line format.

Field Description

Field Name

2000-2013 Tibbo Technology Inc.

AggreGate Server

271

Day of Month. Specifies execution pattern for every day of month: always, nearest weekday of never. Month . Defines for which months execution is enabled. Day of Week. Specifies execution pattern for every day of week: always, first, second, third, last or never. Year. Specifies a range of years for those execution is allowed. It is a combination of comma separated years or year ranges, i.e. "2003, 2004, 2006-2008". Empty value causes endless execution every year. Time. Execution time. Job is executed at that time every day for which execution is allowed by other trigger options. The only way to specify more then one execution time is to create several triggers. Start Date/Time. Time before that execution is not allowed according to this trigger. Default value is <Not set>, so execution starts immediately when combination of other options will allow it. End Date/Time. Time after that execution is not allowed according to this trigger. Trigger is deleted automatically when this time comes. Advanced schedule may be accessed through the cronTriggersView
746

dayOfMonth

month dayOfWeek

year

time

startTime

endTime

variable.

3.12.4 Jobs Security

Any scheduled job is executed with its owner's permissions accessible for its owning user account 108 .
931 .

Thus, the job may check and process only data that

Example: A job belonging to Joe's user account won't be able to stop or restart the AggreGate Server unless Joe has Admin permission level 932 in the Root Context 726 . However, default administrator 109 's job can always stop/restart the server, since he has permissions to do everything.

3.12.5 Jobs Performance

Jobs are active server components that may cause surges of CPU and memory load on each execution. The amount of resource consumption is completely defined by an action triggered by a job, ranging from almost nothing (e.g. for "Send SMS" action) to considerable or high load (e.g. for removal of expired events from the database).

3.13 Queries
SQL (Structured Query Language) is a powerful language for extracting and processing data. Tibbo AggreGate Server natively supports SQL, making it easy to access its internal data, as well as data collected from hardware devices. The specific SQL dialect supported by AggreGate Server is called AggreGate Query Language. AggreGate Query Language is highly integrated into AggreGate Server. Since all AggreGate Server internal data is maintained as Data Tables, it's easy to use SQL queries to modify the properties (settings, variables) of various system objects. Data Tables contain actual data, as well as data validation rules, detailed information each field, etc. This section of the manual is not a tutorial of the SQL language itself. Rather, it assumes you already know SQL and SQL syntax. This isn't because we want to make your life hard -- it's just because SQL is an extensive topic, and great minds have already wrote excellent books and tutorials on the topic. So, if you're unfamiliar with SQL, please read a bit about the subject generally. Once you understand SQL as a wider subject, come back to this chapter and learn how we've implemented it in AggreGate. We've listed some places where you can learn more about SQL in the SQL References 274 section.

Purpose Of The Query Language

AggreGate Query Language has two primary uses: 1. Obtaining data from server objects or hardware devices, filtering, sorting and grouping it and presenting it to the user in a convenient form (as a table). 2. Modifying the properties of various contexts (so as to configure various hardware devices, for example) by entering values for settings in the table.

2000-2013 Tibbo Technology Inc.

272

AggreGate Documentation

The first task is performed using a normal data selection ("SELECT") query, creating a Data Table viewable through a AggreGate Server User Interface (such as AggreGate Client). For example, you can write a query that shows the traffic for all Device Servers sortable table:
1003

in the system in a single convenient

Queries can also present editable results, allowing users to enter data, for example to configure several instances of the same device. So you can use a query to access the settings of all Device Servers 1003 in the system and edit them in a single table:

Queries can be also used in different AggreGate Server facilities. For example, you can set up an alert that will be raised if a query result satisfies some condition (see Hardware Devices in Trouble 239 example in Alerts 216 chapter for details). Query results may be converted into a printable report when they're browsed (e.g. using the Generate Report feature of Data Table Editor 801 in AggreGate Client). Widgets 312 may also be used to present data previously aggregated and filtered by a query.

How AggreGate Query Language Compares to Normal SQL

There are two primary differences between "normal" SQL used by most modern Database Engines (like MySQL or Oracle) and AggreGate Query Language.

FIRST DIFFERENCE: TABLES VS. CONTEXTS

Normal SQL uses tables as the primary data source. Every SELECT statement refers to one or more tables from which data is selected. These references appear in the FROM clause. AggreGate Query Language works with data stored within AggreGate Server contexts 863 . This data may be accessed by getting context variables 869 (properties) or calling context functions 878 . The value of every context variable is represented by a Data Table 854 , a data structure that has fields, records and cells. These Data Tables are used by the Query Language engine as the tables from which data is selected. The same method may be used to refer to tables containing the output values of context functions. When a SELECT statement refers to such a table (containing output values of a function), the reference should also include the input parameters for that function. When the query is executed, the function is called with these parameters. That function then generates a data table containing its output, which in turn will be used by the query. In the Query Language Syntax 299 article, these references to context variables or functions are called contextReference 299 . Every contextReference may have an alias (tableAlias) that is used to refer to it from other parts of the query. Just like normal SQL, AggreGate Query Language supports nested SELECT statements, where the FROM section of a SELECT statement contains another SELECT statement.

SECOND DIFFERENCE: FIELD REFERENCES IN 'FROM' CLAUSE

The second difference concerns referring to the fields of tables mentioned in the FROM clause. In normal SQL, a reference to a table field includes two parts: tableAlias.fieldName. The first part is table's name, an alias given to it in the FROM clause or an alias given to the nested SELECT query. The second part is the field's name. In AggreGate, a reference to a table field consists of three parts. It looks like this: tableAlias.fieldAlias. tableAlias

2000-2013 Tibbo Technology Inc.

AggreGate Server

273

is the alias assigned to the table generated from context's data (see First Difference 272 , above). fieldAlias is in the form entityName$fieldName. entityName is the name of a context variable or function (such as childInfo , which is the "user information" variable of the user context). fieldName is a specific field of that variable or function output (such as firstname , the user's first name, for the childInfo context). People familiar with classic SQL language may use the following analogy to understand the AggreGate Query Language quickly: a query in AggreGate is exactly like a normal SQL query with some exceptions: 1. Table names used in normal SQL are substituted by Context References 274 . However, every Context Reference is used to build a table before the query is executed. So the AggreGate Query Language processor deals with tables, just like a normal database engine. 2. Field names used in normal SQL are substituted by Field References 277 . But these Field References behave exactly like normal field names in the classic SQL query. They just have a slightly different syntax, allowing a user to refer to the fields of "virtual" tables generated from Context References. To see the exact differences in the syntax, and the logic behind them, please read about Field References 277 . 3. When an SQL query is executed, you get a "dumb" table, containing just values of data. However, when an AggreGate Query is executed, you get something we call a "Data Table 854 ", which is smarter than "just" a table -- it contains data validation rules, field types, and other such metadata.

Query Execution Flow

This section describes the step-by-step process of how a query text is used to generate query results. 1. At first stage, the query processing engine finds all Context References 274 in the FROM clause of the query text. These references are then used to build ad-hoc tables, filled with data from the actual contexts, on which the query will later be executed. This process is described here 274 . 2. A Classic SQL query is executed using the tables that were created at the previous step. The query produces a table, built according to the query syntax. 3. This table is now converted to a Data Table 854 . This makes it simpler to understand: the final Data Table contains all field descriptions, formatting and validation rules and any other metadata that may be fetched from the Data Tables on which the query was executed. So, for all intents and purposes. AggreGate uses a query to generate a Data Table. The only reason we mentioned the previous step (2) is to give you a glimpse at the internals of the system. 4. The query result is shown to the user. If the results are editable, the user can now make changes to the data presented. 5. If the user saves the modified results, the query processing engine writes all modified data back to the context variables from which it came. As stated in the previous chapter, the difference between AggreGate query and a normal SQL query is that it is executed on "virtual" tables generated from context data rather than on "plain" tables.

Query Syntax Overview

The only operation supported in AggreGate Query Language is the data selection operation which is performed with the SELECT keyword. SELECT retrieves data from a specified table, or from multiple related tables, that are created ad hoc when the Context References 274 in the query are processed. Each query has several clauses: The primary SELECT clause, defining which fields of the original tables should be included in the query result. The FROM clause, indicating the source table or tables from which the data is to be retrieved. The FROM clause can include optional JOIN clauses, joining related tables with each other based on user-specified criteria. The WHERE clause includes a conditional expression, which is used to filter data returned by the query. The WHERE clause is applied before the GROUP BY clause. Technically speaking, the WHERE clause eliminates all rows from the result set where the conditional expression does not evaluate to True. The GROUP BY clause is used to combine, or group, rows with related values. GROUP BY is often used to calculate statistics (total, average, etc) of similar rows or to eliminate duplicate rows from a result set. The HAVING clause includes a conditional expression used to eliminate rows after the GROUP BY clause is applied to the result set. The UNION clause allows to combine the results of two or more SELECT statements into a single result. The ORDER BY clause is used to designate the columns used to sort resulting data, and whether they should be ascending or descending. The order of rows returned by an SQL query is never guaranteed unless an ORDER BY clause is specified. The LIMIT clause restricts the final result to a predefined range of rows. This is just a numeric range -- for example, if you have a query resulting in 100 records, but you just want 10 arbitrary records (the first ten, last ten, ten records

2000-2013 Tibbo Technology Inc.

274

AggreGate Documentation

starting from the 15th record, etc.), you can use a LIMIT clause to get just as many records as you want. AggreGate Query Language supports most features of SQL standard selection queries. It has support for nested SELECT queries, SQL aggregation functions used to perform calculations on various data values (COUNT, MIN, MAX, SUM, AVG, etc), and built-in functions 300 (numerical, string, date/time and system). For a detailed description of AggreGate Query Language syntax, click here
299 .

Administering Queries
Two contexts are used to administer queries: One is the general Queries 714 context, which serves as a container. The other is the Query 716 context, which holds the information for a single query. See descriptions below.

Every user

108

has his own set of Queries.

Built-In Queries
Several queries are built into AggreGate Server and appear under default administrator's All Users . This query allows viewing and editing the settings of all user accounts
108 109

user account:

in a single table.

Device Status Summary. Shows connection and synchronization status of every Device. Offline Devices. Shows offline Device summary. Active Alerts . Shows pending and escalated alerts These queries are described in the Query Examples
284 216

summary.

chapter.

SQL References
For more information on SQL language check the following links: http://en.wikipedia.org/wiki/SQL http://www.w3schools.com/sql/sql_select.asp http://sqlzoo.net/ http://www.fluffycat.com/SQL/ http://www.baycongroup.com/tocsql.htm

3.13.1 Context References

A Context Reference looks like this:

contextMask { :contextEntityReference [: ...] }

contextMask is a mask 865 of contexts whose entities (variables or functions) will be used to build tables on which the query will be executed. This mask can be a plain context name (without any wildcards) or resolve to several contexts. contextEntityReference may point to a context variable, a group of variables or function. It looks like:

{ contextVariableName | contextVariableGroupName.* | contextFunctionName ( contextFunctionParameters ) }

The pipe marks above denote alternatives -- they're not actually included in the contextEntityReference. Here is the simplest example of a context reference: users.admin:childInfo this reference points to the value of the childInfo variable from the users.admin context. The colon (:) mark is used to separate the context mask from the entity. An "entity" is a fancy name for a variable or a function. So, once you specify a mask (i.e, "where" you want to go), you then put a colon and specify the entity (i.e, "what" you want to find out when you get to where you're going). You can even use a wildcard after the colon, to refer to a group of variables (such as user.charlie.devices.sensor:remote.*, which will give you all settings (variables) in

2000-2013 Tibbo Technology Inc.

AggreGate Server
the group remote of the sensor Device which belongs to the user charlie). Every Context Reference may combine context masks and several entity references (even of different types): users.*:childInfo:variableGroup.*:status()

275

This reference points to the value of the childInfo variable, all variables that belong to the variableGroup group and to the output of the status function called without parameters. Values are fetched from all contexts corresponding to the mask users.*, i.e. to the context of all users in the system that are visible with the permission level of the user who executes this query.

Building Source Tables from Context References

When a query is executed, the first thing which happens is that every Context Reference is used to build a single table, on which the query will be performed. Building of this table is a complex process which includes several steps: 1. The context mask is resolved to the list of contexts that correspond to it, and are accessible to the user executing the query (according to his permissions 931 ). 2. The query processing engine now retrieves and caches the values of the variables that the context reference points to. It also calls all referred functions with the parameters specified in the query text and caches the output of these functions. 3. Now a list of fields for the resulting table is generated, according to several rules. If the context reference refers to just one variable or function, the resulting table will have exactly the same fields as that variable or function output. If the context reference refers to several variables or functions, the format of the resulting table will include all of the fields that appear in the format of these variables or in the function output. The only exception occurs when a value or a function output contains more than one record. In this case, the resulting table will have just one field for this variable/function. That field will contain a nested table with the value of the variable or the function output. 4. The table is filled with data. Usually, one record is created for every context that corresponds to the context reference mask. But if just one variable/function is referred and its value/output contains several records, all these records are put in the resulting table (i.e, you won't have a table containing just one record, that record being another nested table. That wouldn't make much sense). Click here
299

to see where the Context References may appear in Query Language Syntax.

SPECIFYING FUNCTION PARAMETERS

When a context function is called during Context Reference resolution, it usually has to get some input values. These values are specified in a list containing string parameters 299 . The parameters are all in one long string, and are sepearated by commas (","). See details on how comma-separated parameter list is converted to a Data Table here according to the function input format 855 .
862 .

The Data Table is built

SPECIAL FIELDS
Every table build from a Context Reference contains three additional fields: CONTEXT_ID, PARENT_ID and RECORD_INDEX. These fields are implicitly added by query processing engine. CONTEXT_ID field contains full name of context that originated the particular record. PARENT_ID field is the full name of context that is parent to context that originated the record. RECORD_INDEX is the number of record in Data Table from that the particular record was taken. The special fields may be referred by the WHERE clause. However, these fields are hidden. They are not visible in the query results. These special fields may be referred in any query. See using joins
293

for an example of how to do that.

Note that names of special fields must be explicitly specified in the SELECT clause when using editable query results 280 . See write-back fields 281 for more information.

Examples of Field References

Let's assume you have two contexts, path.name and path.name2. The path.* context mask matches both. path.name has two variables: var1: stringField

2000-2013 Tibbo Technology Inc.

276

AggreGate Documentation

"test string" var2: integerField 123 booleanField TRUE

This context also defines the func1 function, which returns the following value: floatField 45.6 78.9 integerField 456 789

path.name2 has the same variable names, but with different values: var1: stringField "string in 2nd context" var2: integerField 555 booleanField FALSE

This context also defines a func1 function which returns the following value: floatField 11.1 22.2 33.3 Example 1 Context Reference: path.name:var2 Table built from this simple context reference will be exactly the same as value of var2: var2$integerField 123 var2$booleanField TRUE Note that names of fields in the resulting table include the variables from which each field was taken (var2 above). This helps to refer to these fields using Field References 277 . Example 2 Context Reference: path.name:var1:var2 This reference will resolve to a table with three fields, one from the value of var1 and two from the value of var2. There's just one line, because both variables come from the same context. var1$stringField "test string" Example 3 Context Reference: path.*:var1:var2 This reference points to a context mask, so it will result to the table with three fields, like in the previous example, but with two records, one per every context: var2$integerField 123 var2$booleanField TRUE integerField 666 777 888

2000-2013 Tibbo Technology Inc.

AggreGate Server

277

var1$stringField "test string" "string in 2nd context" Example 4 Context Reference: path.*:func1

var2$integerField 123 555

var2$booleanField TRUE FALSE

This reference points to a single entity (function) with a value containing multiple records, so the resulting table will have the same fields as the function output. The total number of records in the table is five, since two records are provided by the value of func1 in path.name and three records by the value of func1 in path.name2 func1$floatField 45.6 78.9 11.1 22.2 33.3 Example 5 Context Reference: path.*:var1:func1 Since several entities ( var1 variable and func1 function) are referred here, the multi-line values of func1 will be put in nested tables. Fields in these nested tables can not be referred using Field References 277 . var1$stringField "test string" "string in 2nd context" func1 [Nested table with the value of "func1" in "path.name"] [Nested table with the value of "func1" in "path.name2"] func1$integerField 456 789 666 777 888

3.13.2 Field References

The Context References 274 section describes how context references are used to build the tables on which queries are executed. These tables contain multiple fields that may be referred in different parts of the query, i.e. in the WHERE clause. Field references may comprise of two or three parts: 1. When a query has just one context reference in the FROM clause, fields in the table that was built from this reference may be referred with a two-part Field References:

contextEntityName$dataTableFieldName
In this Field Reference, contextEntityName is the name of the context variable or function that was used by the single Context Reference in the query. dataTableFieldName is the name of the field in the Table Format 855 of the Data Table containing the value of that entity. Example:

SELECT childInfo$firstname FROM users.*:childInfo

In this example, the Field Reference childInfo$firstname refers to the firstname field of a Data Table containing the value of the childInfo variable in all contexts corresponding to the users.* mask. 2. If a query has more then one Context Reference, each reference must have an alias so you'd be able to refer to the fields of the table that was built from it. The alias is assigned using the AS keyword:

contextReference AS tableAlias
Example:

users.*:childInfo as ui

2000-2013 Tibbo Technology Inc.

278

AggreGate Documentation

Here we give a table built from the users.*:childInfo Context Reference an alias named ui . Now we can refer to the fields of this table using the alias. The generic form of a Field Reference that includes an alias is:

tableAlias.contextEntityName$dataTableFieldName
Example:

SELECT ui.childInfo$firstname FROM users.*:childInfo as ui

This query works exactly as the query from previous example, but here field in the table build from "users.*: childInfo " is referred by an alias. You can see another example of using an alias below, in Example 6 292 . Click here
300

to see where Field References may appear in Query Language Syntax.

At first look it may seem that a reference to a field should include only two components: tableAlias and fieldName. But AggreGate Query Language lets you generate one source table (a table on which the query will be run) from the values of several context variables or from the output of several context functions. That is why we need an additional entityName. It points to the name of a context variable or a function which contains the fieldName field.

3.13.3 Query Configuration

Here is a list of query properties:

Field Description
Name. Name of the query context. It should satisfy the context naming conventions Name is required to refer to this query from other parts of the system. Description. Textual description of the query. This is also a description context.
864 863 .

Field Name
name

of the Query

description

Parameterized. Indicates that query is parameterized. If this flag is set, Query Text should contain parameterized query in XML format, not just the query in plain text. Query Text. Text of the query. Edited in a text area editor. Parameterizer Source Data. This field is used only when Parameterized flag is enabled. Parameterizer Source Data is used by parameterization engine to build a Query Text at query execution time based on a number of operator-specified parameters. See Parameterized Queries 282 for details. Field Descriptions. This is the table of custom descriptions assigned to the fields of query result. There are two fields: Field that is name of field as it appears in the query result table, and Description that is a custom description for this field. Disable Editable Result. Enables/disables editable results These properties may be accessed through the childInfo
717 280

parameterized

query parameterizer

fields

for this query.

disableEditableResult

variable.

3.13.4 Debugging Queries

Some queries may execute without errors but return unpredictable or unexpected results. Such behaviour may be caused by non-critical errors that occur during query execution. The Query debugging feature helps view these errors. To run a query in debug mode, use the Debug Query 716 action defined in the Query Context. This action lets you browse a query debug report before showing execution result. The debug report has the following fields: Message. Debug message. Context (optional). Server context
863

processing the data which caused the error.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Exception (optional). Text of the error generated by the context when the query accessed its variables or functions.

279

Stack Trace (optional). Stack trace of exception generated by AggreGate Server. May be requested by AggreGate technical support team during resolving of complex problems. A stack trace is just computer-generated debug information -- it's not supposed to be very human-readable. Here is an example of debug report (screenshot made in AggreGate Client):

Query Performance Debugging

Query execution report also shows time taken by different stages of the execution process. This information is crucial for query performance assessment.

2000-2013 Tibbo Technology Inc.

280

AggreGate Documentation

3.13.5 Query Executor Widget

Default AggreGate Server distribution includes a Query Executor widget and click Execute to view query results:
312

for debugging queries. Type query text

3.13.6 Editable Query Results

Results of execution of some queries are editable. This is a unique feature of AggreGate Query Language, that helps collect properties of different objects or settings of hardware devices in a single table (including only the necessary fields, sorted, grouped etc) and edit these properties using a convenient form. A field in a query result is editable if several conditions are met: 1. The field must belong to some context variable, not a function output. This is obvious, since you can write a new value for a variable back to the context from which it came, but there is no way to "write back" a function output. 2. This field must not be defined as read-only in the format of the variable from which it was taken. 3. The value of this field must not be calculated (using simple or aggregation functions or some query language expressions). 4. The field must not come from a table that was built using nested SELECT statement. 5. All fields of a source table should be selected in the SELECT clause using * or tableAlias.* (this can be avoided by using write-back 281 fields). Example 1:

SELECT * FROM users.*:childInfo

Most fields in the result of this query will be editable, because: They came directly from the value of the childInfo variable, They are writable in the the format of this variable, They are not converted using any function or expression in the query result, They are selected using *, without using Field References
277

2000-2013 Tibbo Technology Inc.

AggreGate Server

281

Some fields (i.e. "Username" field) will not be editable, because they are not defined as editable in the format of the childInfo variable. Example 2:

SELECT childInfo$firstname, childInfo$lastname FROM users.*:childInfo

The result of this query will have no editable fields, because fields to be selected are listed explicitly in the SELECT clause and write-back fields are not defined in the query text.

WRITE-BACK FIELDS
There is a special way to select a pre-defined number of fields by explicitly listing them in the SELECT clause and still make these fields editable. To do this, you have to add three so-called "write-back" fields to the list of Field References listed in the SELECT clause. These fields help the query processing engine figure out where the information contained in the editable query results should be stored when the modified result is saved. The format of these write-back field references is as follows:

tableAlias.CONTEXT_ID,

tableAlias.PARENT_ID,

tableAlias.RECORD_INDEX

where tableAlias is name of alias given to the Context Reference 274 in the FROM clause, CONTEXT_ID, PARENT_ID and RECORD_INDEX are predefined constants. Just put them in the query text as-is, without modifying anything. These write-back fields must be always used all together. Example: Assuming we have a query that shows statistics of traffic generated by all Device Servers executing it:
1003

accessible by the user

SELECT info.deviceServerInfo$owner, info.deviceServerInfo$name, info.deviceServerInfo$description, info.deviceServerInfo$blocked, info.status$servertods, info.status$dstoserver, FROM users.*.deviceservers.*:status:deviceServerInfo as info
Result of this query is not editable, because selected fields are explicitly listed in the SELECT clause:

To make it editable, we should add write-back fields to SELECT clause:

SELECT info.deviceServerInfo$owner, info.deviceServerInfo$name, info.deviceServerInfo$description, info.deviceServerInfo$blocked, info.status$servertods, info.status$dstoserver,

2000-2013 Tibbo Technology Inc.

282

AggreGate Documentation

info.CONTEXT_ID, info.PARENT_ID, info.RECORD_INDEX FROM users.*.deviceservers.*:status:deviceServerInfo as info

This correction will make Device Server description and its "blocked" status editable in the query result. Other fields will remain read-only, since they are defined as read-only in the format of the deviceServerInfo ("Device Server Info") and status ("Device Server Status") variables:

If some columns are not editable due to the absence of write-back fields, this is indicated in the query debug report

278 :

3.13.7 Parameterized Queries

Parameterized queries are used to specify some parameters during query execution. Source data for the parameterization engine is written XML format, rather than in AggreGate Query Language. When the Parameterized option is enabled in the query settings, the query engine considers the query text as parameterization data. See Parameterization Engine 956 for more info. Here is an example of parameterization data: Query Text:

<form> <format> <![CDATA[ <<byusername><B><D=Filter by User Name>> <<username><S><D=User Name>> ]]> </format> <expression> SELECT * FROM users.*:childInfo <p enabled="{byusername}">WHERE childInfo$username LIKE '%<e>{username}</e>%'</p> </expression> </form>
This query will ask for two parameters upon execution:

2000-2013 Tibbo Technology Inc.

AggreGate Server

283

If the user checks "Filter by User Name", final parameterized query text will be

SELECT * FROM users.*:childInfo WHERE childInfo$username LIKE '% text_entered_in_User_Name_field%'

i.e. only users whose usernames include the specified text will be shown. If "Filter by User Name" is not checked, all users will be shown because parameterized query text will be

SELECT * FROM users.*:childInfo

Example 1: Selecting a Subrange of Variable History

This parameterized query allows operator to select start and end date/time and shows historical values of batteryChargeCurrent variable that were collected within the selected time range.

<form> <format> <![CDATA[ <<startDate><D><D=Start Date>><<endDate><D><D=End Date>><B=<startDate=now() ><endDate=now()>> ]]> </format> <expression> SELECT * FROM utilities:variableHistory(users.admin.devices.site1, batteryChargeCurrent, <e> {startDate}</e>, <e>{endDate}</e>) </expression> </form>

3.13.8 Queries Performance

Query execution time and resource consumption depends on several factors: Number and size of virtual tables defined by query's context references 274 . For example, in a 1000-devices installation CPU and memory load implicated by users.*.devices.*:temperature context reference will be 1000 times higher than one of users.admin.devices.meter1:temperature reference. Nature of variables 869 or functions 878 of server contexts and functions performance 880 for more information.
863

referred by the query. See variables performance etc.)

878

Complexity of the the query (i.e. usage of JOINs, functions Debugging a query
278

300 ,

is the way to find out what stages of the query execution process are slow.

2000-2013 Tibbo Technology Inc.

284

AggreGate Documentation

3.13.9 Query Examples

This article comprehensively describes some real-world query examples.

Example 1: Viewing/Editing User Accounts

Viewing or changing various settings of User Accounts 108 is a common administrative task. The query language may help AggreGate Server administrators to perform bulk changes to several user accounts, or view certain settings for multiple user accounts in a single ordered table.

SELECTING SINGLE USER'S INFO

To access the basic User Account settings we'll use a variable called "childInfo" ("User Information") defined in the User 759 context. The value of this variable has a single record with several fields containing user's first/last name, country etc. Here is a typical view of the User Info variable:

Now let's use one of the simplest possible queries to get the value of this variable from just one context. Query Text:

SELECT * FROM users.admin:childInfo

Result of this query is a table showing the value of the childInfo variable defined in the users.admin context. When viewing or editing the properties of some system object or hardware device, its context name is usually shown in the window header:

This query contains two clauses: SELECT and FROM. The SELECT clauses says that we should select all fields ("*"). The

2000-2013 Tibbo Technology Inc.

AggreGate Server

285

FROM clause contains a single Context Reference 274 ("users.admin:childInfo") used to build a table on which the query will be executed. The contents and format of this table will match the value of the childInfo variable exactly. All fields in the result of this query will be editable childInfo variable.
280

except for the fields that are defined as read-only in the format of

When viewing or editing the properties of some context (such as the User context), you usually see variable descriptions rather than variable names . But we must use variable names in query text: Variable names are usually shown in the tooltips that appear when mouse hovers over some variable description:

Query Result:

SELECTING ALL USERS' INFO

Now let's select the properties of all users in the system: Query Text:

SELECT * FROM users.*:childInfo

The Context Reference (users.*:childInfo) contained in the text of this query is actually a mask 865 of contexts. During query execution this mask will resolve to the list of all user contexts accessible by the user executing the query. See Context References 274 chapter for more info. This query results in a table with the values of the childInfo variable of every user account accessible by the user who is executing the query. It will probably contain multiple records, one per every user account. The result of this query will also be editable. This query is built-in to the AggreGate Server distribution. It is called All Users . Query Result:

2000-2013 Tibbo Technology Inc.

286

AggreGate Documentation

For example, you can now change the first name and last name of some user and save the changes:

Changes will be immediately visible in other parts of the system:

SORTING USER LIST

Now let's sort the table. Query Text:

SELECT * FROM users.*:childInfo order by childInfo$name desc

This query outputs almost the same table as the previous one, but the rows in this table are sorted by Username (name field in the format of the childInfo variable) in descending order. The query contains a two-component Field Reference 277 (childInfo$name ), used to refer to a field within the table built when resolving the Context Reference users.*: childInfo . When we examine value of "childInfo" variable in AggreGate Client or other AggreGate Server User Interface, field descriptions are shown in the table header instead of field names . But we must use field name in order to refer to it in query text. Field names are usually shown in tooltips that appear when mouse hovers over the field header:

Query Result:

2000-2013 Tibbo Technology Inc.

AggreGate Server

287

USING TABLE ALIASES

We can edit the query and assign an alias, info, to our Context Reference, and then use a three-component Field Reference that includes this alias:

SELECT * FROM users.*:childInfo as ORDER BY info.childInfo$name desc info

The result of this query is exactly like the previous one.

RESTRICTING SELECTED FIELDS

Now let's select just a limited number of fields by further modifying the same query. Query Text:

SELECT childInfo$name, FROM users.*:childInfo ORDER BY childInfo$name desc

This query contains a number of Field References in the SELECT clause. Since the fields are specified explicitly, the query result will be not editable, unless we add the write-back 281 fields. We'll add them to this query in one of the next examples. The result of this query will contain just three columns. Query Result:

childInfo$firstname,

childInfo$lastname

ADDING EXPRESSIONS
Let's now use a Query Language expression to show the first and last name of users in a single column, to make browsing more convenient. We'll also add a new column to the query result, user's country.

2000-2013 Tibbo Technology Inc.

288

AggreGate Documentation

Query Text:

SELECT childInfo$name, || CASEWHEN((childInfo$firstname CASEWHEN((childInfo$lastname childInfo$country FROM users.*:childInfo ORDER BY childInfo$name desc
This query selects three fields from the source table. The first and third fields contain the user's username and country respectively. The value of the second field is calculated using an expression. This expression gets a user's first name and appends a space and the user's last name to it. The double pipe marks (||) used are just a standard SQL operator, used for concatenating the strings. The first and last names are transformed using the CASEWHEN built-in function 300 to make sure that an empty string is shown if value of the first or last name is NULL ("<Not set>"). Note that the name for the second column is generated automatically. Query Result:

IS NULL), '', childInfo$firstname) || IS NULL), '', childInfo$lastname),

'

'

USING FIELD ALIASES

Now let's assign a custom name ("label") to the second column to make the result more readable. Query Text:

SELECT childInfo$name, CASEWHEN((childInfo$firstname IS NULL), '', childInfo$firstname) ((childInfo$lastname IS NULL), '', childInfo$lastname) as name, childInfo$country FROM users.*:childInfo ORDER BY childInfo$name desc
Second column is now called "name" in query result. Query Result:

|| ' ' || CASEWHEN

ENABLING EDITABLE RESULTS

2000-2013 Tibbo Technology Inc.

AggreGate Server

289

Now let's make it possible to change the users' countries -- add write-back 281 fields to make the result editable. To add them we should assign an alias to the Context Reference ("table alias"), because write-back fields (CONTEXT_ID, PARENT_ID and RECORD_INDEX) have to be specified for a given context reference. To specify which reference should be written back, you have to use an alias. Carefully read the example below to figure it all out. Query Text:

SELECT info.childInfo$name, CASEWHEN((info.childInfo$firstname IS NULL), '', info.childInfo$firstname) || ' ' || CASEWHEN((info.childInfo$lastname IS NULL), '', info.childInfo$lastname) as name, info.childInfo$country, info.CONTEXT_ID, info.PARENT_ID, info.RECORD_INDEX FROM users.*:childInfo as info ORDER BY info.childInfo$name desc
In the result of this query, Country column will be editable. Username column is still read-only because it is read-only in the source variable ("childInfo"). Name column is read-only because it is calculated using an expression. Query Result:

FILTERING USER LIST

Now let's add some filtering rules to the query. As an example, let's select only users whose usernames doesn't contain word "test". Query Text:

SELECT info.childInfo$name, CASEWHEN((info.childInfo$firstname IS NULL), '', info.childInfo$firstname) || ' ' || CASEWHEN((info.childInfo$lastname IS NULL), '', info.childInfo$lastname) as name, info.childInfo$country, info.CONTEXT_ID, info.PARENT_ID, info.RECORD_INDEX FROM users.*:childInfo as info WHERE info.childInfo$name ORDER BY NOT LIKE '%test%'

2000-2013 Tibbo Technology Inc.

290

AggreGate Documentation

info.childInfo$name desc
This query contains an additional WHERE clause, specifying which records should be included in the result. Query Result:

LIMITING THE OUTPUT

The last line of the next example shows the LIMIT clause, used to restrict query result to a specified range of rows. Query Text:

SELECT info.childInfo$name, CASEWHEN((info.childInfo$firstname IS NULL), '', info.childInfo$firstname) || ' ' || CASEWHEN((info.childInfo$lastname IS NULL), '', info.childInfo$lastname) as name, info.childInfo$country, info.CONTEXT_ID, info.PARENT_ID, info.RECORD_INDEX FROM users.*:childInfo as info WHERE info.childInfo$name NOT LIKE '%test%' ORDER BY info.childInfo$name desc LIMIT 2 OFFSET 1
Result of this query includes just two (LIMIT 2) records (2nd and 3rd) from the result of previous one. We use OFFSET 1 here. This means we're going to get 2 records (LIMIT 2) starting from the second record (OFFSET 1). The OFFSET clause tells AggreGate to start taking record from the second record onwards (the first record's offset is 0). Query Result:

Example 2: Viewing/Editing Device Server Accounts

This example is similar to selecting the basic properties of all users as described in the previous example, but here we use the deviceServerInfo variable ("Device Server Information") defined in Device Server 1018 context. Query Text:

SELECT * FROM users.*.deviceservers.*:deviceServerInfo

The text of this query includes a single Context Reference (users.*.deviceservers.*:deviceServerInfo) with a context mask that expands to all Device Server contexts which are accessible with the permissions 931 of the user executing the query. The results of this query are editable, except for the fields that are read-only in the definition of the deviceServerInfo variable.

2000-2013 Tibbo Technology Inc.

AggreGate Server
This query is built-in to the AggreGate Server distribution. It is called "All Device Servers". Query Result:

291

Example 3: Viewing Device Server Traffic Statistics

This example shows the usage of Context References that include multiple variables/fields. Query Text:

SELECT info.deviceServerInfo$owner, info.deviceServerInfo$name, info.status$servertods, info.status$dstoserver FROM users.*.deviceservers.*:status:deviceServerInfo as info ORDER BY info.deviceServerInfo$owner, info.deviceServerInfo$name
Context Reference in this query ("users.*.deviceservers.*:status:deviceServerInfo") refers two variables defined in Device Server 1018 context: "deviceServerInfo" mentioned in previous example and "status" ("Device Server Status") that contains some real-time values related to Device Server functioning. The values of both variables contain just one record, so the table that will be built after resolving this context reference will contain all fields that appear in the values of both variables and one record per every Device Server accessible by the user executing query. From this table we select four columns: two that appear in the value of deviceServerInfo (Owner and name of Device Server) and two from status (Incoming and outgoing traffic). The table is sorted by two fields: first by Device Server owner, then by Device Server name (because some Device Servers may have the same owner). This query is built-in to the AggreGate Server distribution. It is called "Device Server Traffic Statistics". Query Result:

Example 4: Buzzing Device Servers

2000-2013 Tibbo Technology Inc.

292

AggreGate Documentation

This example shows how context functions may be used in the query. Query Text:

SELECT * FROM external_device_servers.*:buzz()

This query is very interesting because it doesn't produce any output, but causes a side-effect on the server. It includes one Context Reference ("external_device_servers.*:buzz()") that involves the buzz() function ("Buzz Device Server") defined in the External Device Server 1027 context. This function is called without parameters, as specified by the empty parenthesis. The buzz function causes Device Server to blink its LEDs, helping to locate visually. Thus, this query helps to locate all Device Server that are visible by the AggreGate Server in the local network segment. It it very important to run the Discover Device Server action before executing this query. This action forces AggreGate Server to find all local Device Servers by sending broadcast network commands. See External Device Servers 1012 for more info. If discovery was not performed, the External Device Servers 1030 context will not have any children, the external_device_servers.*context mask will not resolve to any context and no action will be performed on query execution. The output of buzz() function contains no fields of records, so this query doesn't return any data. But its execution causes all External Device Server to buzz helping to locate them. This query is built-in to the AggreGate Server distribution. It is called "Buzz All External Device Servers".

Example 5: Calculating Total Traffic of All Device Servers

This example shows how aggregation functions can be used. Query Text:

SELECT SUM(status$servertods) as server_to_ds, SUM(status$dstoserver) as ds_to_server FROM users.*.deviceservers.*:status

In one of the previous examples we've mentioned the status variable ("Device Server Status") that is defined in the Device Server 1018 context and contains statistics of traffic between AggreGate Server and the Device Server. This query calculates how many bytes were sent to all currently visible Device Server and how many bytes were received from them. The query result contain one record, because the SUM aggregation function is used. Query Result:

Since the query result contains just one row, it is shown using a "vertical" two-column layout, where field names are shown in the first column and field values in the second.

This example could be easily modified to use other aggregation functions: AVG will help to calculate an average traffic of Device Server MIN and MAX may be used to calculate minimum and maximum traffic respectively COUNT may be used to find the number of Device Server (although this example is not the best one for doing that)

Example 6: Executing Query on Multiple Tables

This example shows how to execute queries on multiple tables (built from multiple Context References). Query Text:

SELECT d.deviceServerInfo$owner || '.' || d.deviceServerInfo$name as device_server,

2000-2013 Tibbo Technology Inc.

AggreGate Server d.deviceServerInfo$blocked, u.childInfo$city, u.childInfo$country FROM users.*:childInfo as u, users.*.deviceservers.*:deviceServerInfo as d WHERE u.childInfo$name = d.deviceServerInfo$owner

293

This query has two Context References in the FROM clause. The first one is used to build a table containing all basic settings of all users, and the second one results in a table of all basic settings of all Device Server. These tables are then joined together based on the formula contained in WHERE clause ("u.childInfo$name = d. deviceServerInfo$owner"). The query result has four fields: first contains full Device Server name in the form "Owner Name"."Device Server Name". Second shows "Blocked" status of the Device Server. Two other columns show city and country of the user who owns the Device Server (which are probably the city and country where Device Server is located). Query Result:

Example 7: Using JOINs

This example shows how to use SQL JOIN and hidden fields different context references 274 .
275

to combine data from two tables generated from two

When AggreGate is used for network management, AggreGate Server operates with devices using SNMP protocol. Every SNMP device has a so-called Interface Table (ifTable variable of device context) containing statistics of device's network interfaces. The below query finds all network interface of all SNMP devices those status is down (i.e. ifOperStatus field equals to 2). The query joins description of device context (i.e. device name) to the description of network interface to show them in one table.

SELECT info.info$description, ift.ifTable$ifDescr, ift.ifTable$ifOperStatus FROM users.*.devices.*:ifTable as ift LEFT OUTER JOIN users.*.devices.*:info as info ON ift$CONTEXT_ID = info$CONTEXT_ID WHERE ift.ifTable$ifOperStatus = 2
Query Result:

2000-2013 Tibbo Technology Inc.

294

AggreGate Documentation

More Real World Examples

GETTING LOGIN EVENTS OF A USER
This query calls get
695 ()

function from events context and filters resulting table by username.

SELECT * FROM events:get("users", "login") as logins WHERE logins.get$username = 'operator'

Note, that same results may be obtained by passing filter expression into the get() function call:

SELECT * FROM events:get("users", "login", "{username} == 'operator'") as logins

FINDING NETWORK DEVICES WITH HIGH RESPONSE TIME
This query finds all network devices those response time is over 500 ms and shows their names along with current response time.

SELECT info.info$description AS device, ping.ping$averageTime AS average_round_trip_time FROM users.*.devices.*:info AS info RIGHT OUTER JOIN users.*.devices.*:ping AS ping ON ping$CONTEXT_ID = info$CONTEXT_ID WHERE ping.ping$averageTime > 500 ORDER BY ping.ping$averageTime DESC
FINDING NETWORK DEVICE WITH HIGH CPU LOAD
This query finds all network (SNMP-enabled) devices that have an average load of all their processors higher than 90%. It works perfectly for multi-processor devices.

SELECT

2000-2013 Tibbo Technology Inc.

AggreGate Server info.info$description AS device,

295

avg(processors.hrProcessorTable$hrProcessorLoad) AS processor_utilization_percentage FROM users.*.devices.*:hrProcessorTable AS processors LEFT OUTER JOIN users.*.devices.*:info as info ON processors$CONTEXT_ID = info$CONTEXT_ID GROUP BY device HAVING avg(processors.hrProcessorTable$hrProcessorLoad) > 90 ORDER BY processor_utilization_percentage DESC
GROUPING SNMP DEVICES BY TYPE
This query calculates number of SNMP devices of every type (type is specified by sysObjectID variable provided by device itself) and shows summary table. Note, that descriptions of every device type are taken from common table 260 called deviceTypes.

SELECT coalesce(types.value$description, snmp.sysObjectID$sysObjectID) AS device_type, COUNT(*) AS device_count FROM users.*.devices.*:status:sysObjectID AS snmp LEFT JOIN common.deviceTypes:value AS types ON snmp.sysObjectID$sysObjectID = types.value$type WHERE snmp.status$driver = 'com.tibbo.linkserver.plugin.device.snmp' GROUP BY device_type ORDER BY device_count DESC
GETTING DEVICE SETTING STATISTICS
This query uses statistics 767 function defined in Utilities 763 context to extract last values of a statistical channel channel is configured to count network device's interface errors that occurred every hour/day/month.
936 .

The

The query groups all device's interface tables into one and use it as a base (FROM users.*.devices.*:ifTable AS interfaces). Then it LEFT OUTER JOIN's last hour's data from two statistical channels named "ifInOctets" and "ifOutOctets" (LEFT OUTER JOIN utilities:statistics("users.*.devices.*", "ifInErrors", null, "hour") AS in_errors). And finally it LEFT OUTER JOIN's generic device information (LEFT OUTER JOIN users.*.devices.*:info AS info). The query also features filtering, sorting and results row limit.

SELECT info.info$description AS device, interfaces.ifTable$ifDescr AS interface, in_errors.statistics$average * 3600 AS incoming_errors,

2000-2013 Tibbo Technology Inc.

296

AggreGate Documentation

out_errors.statistics$average * 3600 AS outgoing_errors FROM users.*.devices.*:ifTable AS interfaces LEFT OUTER JOIN utilities:statistics("users.*.devices.*", "ifInErrors", null, "hour") AS in_errors ON interfaces.ifTable$ifIndex = in_errors.statistics$key AND interfaces$CONTEXT_ID = in_errors.statistics$context LEFT OUTER JOIN utilities:statistics("users.*.devices.*", "ifOutErrors", null, "hour") AS out_errors ON interfaces.ifTable$ifIndex = out_errors.statistics$key AND interfaces$CONTEXT_ID = out_errors.statistics$context LEFT OUTER JOIN users.*.devices.*:info AS info ON info$CONTEXT_ID = interfaces$CONTEXT_ID WHERE length(interfaces.ifTable$ifDescr) > 1 ORDER BY incoming_errors + outgoing_errors DESC LIMIT 10
LISTING CARDHOLDERS BY DIVISIONS
In the AggreGate Time and Attendance, the system processes attendance data for cardholders forming a complex hierarchy that includes organizations, divisions, and possibly departments. Since context path of every cardholder starts with context path of the division he belongs to, we can build a query that lists cardholders by divisions:

SELECT divisions.childInfo$name, cardholders.childInfo$name FROM organizations.Organization1.divisions.*.cardholders.*:childInfo as cardholders, organizations.Organization1.divisions.*:childInfo as divisions WHERE substring(cardholders.CONTEXT_ID, 1, length(divisions.CONTEXT_ID)) = divisions. CONTEXT_ID
GETTING ALERTS ACTIVE FOR MULTIPLE DEVICES
In the below example, each device has custom_childContext tabular custom property 261 that lists all devices dependent to it. This property has contextPath field that contains paths of dependent devices. The query checks triggers listed in activeInstances tables of all alerts. Only triggers those source field equals to context path of selected device (i.CONTEXT_ID) or listed in custom_childContext table of selected device will be selected.

2000-2013 Tibbo Technology Inc.

AggreGate Server

297

Thus, the query will return alert triggers that are active either for current device ( dev1) or to its dependent devices.

SELECT * FROM users.*.alerts.*:activeInstances AS at WHERE at.activeInstances$source IN ( SELECT i.CONTEXT_ID FROM users.admin.devices.dev1:info AS i UNION SELECT c.custom_childContexts$contextPath FROM users.admin.devices.dev1:custom_childContexts AS c )
JOINING HISTORICAL VALUES OF MULTIPLE VARIABLES
The variableHistory 764 function can load historical values of any context variable. This is suitable to show those values in a report, on a dashboard, etc. But what is you want to show values of multiple variables in a single table? For example, you're measuring temperature and history, and want the measurements to be presented as a single table. Here is a solution. The below query loads 10-days history of two separate variables in two virtual tables and JOINs those tables by putting together values those timestamps are equal with one second precision.

SELECT sineTimeString, sineTime, FROM ( SELECT TO_CHAR(sine.variableHistory$vUpdateTime, 'DD.MM.YYYY H:MI:SS') as sineTimeString, sine.variableHistory$vUpdateTime as sineTime, sine.variableHistory$value as sineValue FROM utilities:variableHistory("users.admin.devices.demoVirtualDevice", "sine", 'dateAdd(now(), -10, \"m\")') as sine ) JOIN ( SELECT TO_CHAR(triangle.variableHistory$vUpdateTime, 'DD.MM.YYYY H:MI:SS') as triangleTimeString, triangle.variableHistory$vUpdateTime as triangleTime, triangle. variableHistory$value as triangleValue FROM utilities:variableHistory("users.admin.devices.demoVirtualDevice", "triangle", 'dateAdd(now(), -10, \"m\")') as triangle ) ON sineTimeString = triangleTimeString
UNIFYING RESULTS OF SEVERAL SUB-QUERIES

sineValue, triangleTime, triangleValue

2000-2013 Tibbo Technology Inc.

298

AggreGate Documentation

The below query refers three other queries by listing their data variables in the FROM clauses of primary and nested SELECT statements. The three query result sets are glued together using UNION operators.

SELECT hpux.data$icon AS icon, hpux.data$device AS device, hpux.data$context AS context, hpux.data$cpu AS cpu, hpux.data$max_threshold as max_threshold, hpux.data$min_threshold as min_threshold, hpux.data$max_threshold - hpux.data$cpu as margin, CASEWHEN(hpux.data$max_threshold - hpux.data$cpu < 0, 2, CASEWHEN(hpux.data$max_threshold - hpux.data$cpu < 10, 1, 0) ) as condition FROM users.admin.queries.cpu_HPUX:data as hpux UNION ALL (SELECT standard.data$icon AS icon, standard.data$device AS device, standard.data$context AS context, standard.data$cpu AS cpu, standard.data$max_threshold as max_threshold, standard.data$min_threshold as min_threshold, standard.data$max_threshold - standard.data$cpu as margin, CASEWHEN(standard.data$max_threshold - standard.data$cpu < 0, 2, CASEWHEN(standard.data$max_threshold - standard.data$cpu < 10, 1, 0) ) as condition FROM users.admin.queries.cpu_standard:data as standard UNION ALL (SELECT sun.data$icon AS icon, sun.data$device AS device, sun.data$context AS context, sun.data$cpu AS cpu, sun.data$max_threshold as max_threshold, sun.data$min_threshold as min_threshold, sun.data$max_threshold - sun.data$cpu as margin, CASEWHEN(sun.data$max_threshold - sun.data$cpu < 0, 2, CASEWHEN(sun.data$max_threshold - sun.data$cpu < 10, 1, 0) ) as condition FROM

2000-2013 Tibbo Technology Inc.

AggreGate Server users.admin.queries.cpu_Sun:data as sun)) ORDER BY margin

299

3.13.10 Query Language Syntax

This article explains nothing. It merely shows what SQL constructs and functions may be used within <%AG % >. Actually training the reader in SQL is very much beyond the scope of this manual. If you're not fully conversant in SQL, we highly recommend the reference texts 274 listed in the Queries 271 article. Every query in AggreGate Query Language has the following syntax: selectStatement

SELECT [ALL | DISTINCT] { selectExpression | tableAlias.fieldReference | tableAlias.* | * } [, ...] FROM tableList [WHERE expression] [GROUP BY expression [, ...]] [HAVING expression] [{ UNION [ALL] | MINUS | INTERSECT } selectStatement] [ORDER BY orderExpression) [, ...]] [LIMIT <limit> [OFFSET <offset>]]
The LIMIT clause may be used only if all Context References "SELECT ... FROM context_reference AS alias LIMIT n, m") tableList
274

listed in FROM clause have aliases. (I.e.

table [joinedTables] [, ...]

joinedTables

joinedTable [joinedTable] [...]

joinedTable

{CROSS | INNER | LEFT OUTER | RIGHT OUTER | FULL OUTER} JOIN table ON expression
table

{ (selectStatement) [AS tableAlias] | contextReference [AS tableAlias]}

contextReference See context references
274 .

contextMask { :contextEntityReference [: ...] }

contextEntityReference

{ contextVariableName | contextVariableGroupName.* | contextFunctionName ( contextFunctionParameters ) }

contextFunctionParameters

{ null | 'value' | "value"} [, ...]

orderExpression

{ [tableAlias.]fieldReference | selectExpression } [ASC | DESC]

selectExpression

{ expression | COUNT(*) | { expression) } [[AS] label]

expression

COUNT | MIN | MAX | SUM | AVG }

([ALL | DISTINCT]

2000-2013 Tibbo Technology Inc.

300

AggreGate Documentation

[NOT] condition [{ OR | AND } condition]

condition

{ value [|| value] | value { = | < | <= | > | >= | <> | != } value | value IS [NOT] NULL | EXISTS(selectStatement) | value BETWEEN value AND value | value [NOT] IN ( {value [, ...] | selectStatement } ) | value [NOT] LIKE value [ESCAPE] value }
value

[+ | -] { literal [{ + | - | * | / | || } literal] | ( condition ) | function ( [parameter] [,...] ) | selectStatement giving one value | {ANY|ALL} (selectStatement giving single column)
fieldReference See field references
277 .

{ { contextVariableName | contextFunctionName} $ dataTableFieldName | writebackFieldName }

writebackFieldName

"CONTEXT_ID" | "PARENT_ID" | "RECORD_INDEX"

Literals
AggreGate Query Language defines several types of literals: Null Literal: NULL Boolean Literals: TRUE of FALSE Decimal Literals (0, 1, 123, -1234567890, ...) Hexadecimal Literals (X'0A', X'FFFF', ...) Binary Literals (B'01', B'00110011') Floating Point Literals (3.1 , -44.5, 1.3E12, ...) String Literals ('This is a String', 'test', ...)

3.13.11 Query Language Functions

Numerical Built-In Functions
Function ABS(Number d) ACOS(Number d) ASIN(Number d) ATAN(Number d) Description Returns the absolute value of d. Returns the arc cosine of an angle. Returns the arc sine of an angle. Returns the arc tangent of an angle.

ATAN2(Number a, Number Returns the tangent of a /b.

2000-2013 Tibbo Technology Inc.

AggreGate Server

301

b) BITAND(Number a, Number b) BITNOT(Number a) BITOR(Number a, Number b) BITXOR(Number a, Number b) CEILING(Number d) COS(Number d) COT(Number d) DEGREES(Number d) EXP(Number d) FLOOR(Number d) LOG(Number d) LOG10(Number d) MOD(Number a, Number b) PI() POWER(Number a, Number b) RADIANS(Number d) RAND() ROUND(Number a, Number b) ROUNDMAGIC(Number d) SIGN(Number d) SIN(Number d) SQRT(Number d) TAN(Number a) TRUNCATE(Number a, Number b) Return a & b. Return !a . Returns a | b. Returns a ^ b. Returns the smallest integer that is not less than d. Returns the cosine of an angle. Returns the cotangent of an angle. Converts radians to degrees. Returns e (2.718...) raised to the power of d. Returns the largest integer that is not greater than d. Returns the natural logarithm (base e). Returns the logarithm (base 10). Returns a modulo b. Returns pi (3.1415...). Returns a raised to the power of b. Converts degrees to radians. Returns a random number x bigger or equal to 0.0 and smaller than 1.0. Rounds a to b digits after the decimal point. Solves rounding problems such as 3.11-3.1-0.01. Returns -1 if d is smaller than 0, 0 if d equals to 0, and 1 if d is bigger than 0. Returns the sine of an angle. Returns the square root. Returns the trigonometric tangent of an angle. Truncates a to b digits after the decimal point.

String Built-In Functions

Function ASCII(String s) BIT_LENGTH(String s) CHAR(Integer c) CONCAT(String s1, String s2) DIFFERENCE(String s1, String s2) HEXTORAW(String s) INSERT(String s, Integer start, Integer length, String replacement) Description Returns the ASCII code of the leftmost character of s. Returns the length of the string in bits. Returns a character that has the ASCII code c. Returns s1 + s2. Returns the difference between the sound of s1 and s2. Returns translated string. Returns a string where length number of characters beginning at start has been replaced by replacement .

2000-2013 Tibbo Technology Inc.

302

AggreGate Documentation

LEFT(String s, Integer count) LENGTH(String s) LOCATE(String search, String s[, Integer start]) LOWER(String s) LPAD(String s1, Integer length[, String s2])

Returns a character string consisting of the first count characters of s. Returns the number of characters in s. Returns the first index (1=left, 0=not found) where search is found in s, starting at start. Converts s to lower case. Returns a character string with the length of length characters. The string contains the characters of s1 padded to the left with spaces. If length is smaller than the length of the s1 argument, the argument is truncated. If the optional string s2 is specified, this string is used for padding, instead of spaces. Removes all leading blanks in s. Returns the length of the string in bytes (twice the number of characters). Returns translated string. Returns true if the s matches the regex as a whole. The regex is defined according to regular expression rules 1318 . Returns the first region in the s that matches the regex. The regex is defined according to regular expression rules 1318 . Returns s repeated count times. Replaces all occurrences of replace in s with s2. Returns a character string based on s with characters in the reverse order. Returns a character string consisting of the last count characters of s. Returns a character string with the length of length characters. The string contains the characters of s1 padded to the right with spaces. If length is smaller than the length of the s1 argument, the argument is truncated. If the optional string s2 is specified, this string is used for padding, instead of spaces. Removes all trailing spaces. Returns a four character code representing the sound of s. Returns a string consisting of count spaces. Returns the substring starting at start (1=left) with length len .

LTRIM(String s) OCTET_LENGTH(String str) RAWTOHEX(String s1) REGEXP_MATCHES(String s, String regex) REGEXP_SUBSTRING (String s, String regex) REPEAT(String s, Integer count) REPLACE(String s, String replace, String s2) REVERSE(String s) RIGHT(String s, Integer count) RPAD(String s1, Integer length[, String s2])

RTRIM(String s) SOUNDEX(String s) SPACE(Integer count) SUBSTRING(String s, Integer start[, Integer len]) UPPER(String s)

Converts s to upper case.

Date/Time Built-In Functions

Function CURDATE() CURTIME() DATEADD(String string, Integer number, Date datetime) DATEDIFF(String string, Date datetime1, Date datetime2) DAYNAME(Date date) DAYOFMONTH(Date date) Description Returns the current date. Returns the current time. Adds a number of string units to datetime. The string indicates the unit of time and can have the following values 'ms'='millisecond', 'ss'='second','mi'='minute','hh'='hour', 'dd'='day', 'mm'='month', 'yy' = 'year'. Both the long and short form of the strings can be used. Returns the count of units of time elapsed from datetime1 to datetime2. The string indicates the unit of time and can have the following values 'ms'='millisecond', 'ss'='second','mi'='minute','hh'='hour', 'dd'='day', 'mm'='month', 'yy' = 'year'. Both the long and short form of the strings can be used. Returns the name of the day. Returns the day of the month (1-31).

2000-2013 Tibbo Technology Inc.

AggreGate Server

303

DAYOFWEEK(Date date) DAYOFYEAR(Date date) HOUR(Date time) MINUTE(Date time) MONTH(Date date) MONTHNAME(Date date) NOW() QUARTER(Date date) SECOND(Date time) SECONDS_SINCE_MIDNI GHT(Date time) TIMESTAMP(Object value)

Returns the day of the week (1 means Sunday). Returns the day of the year (1-366). Return the hour (0-23). Returns the minute (0-59). Returns the month (1-12). Returns the name of the month. Returns the current date and time as a timestamp. Returns the quarter (1-4). Returns the second (0-59). Returns an integer in the range of 0 - 86399 indicating number of seconds elapsed since midnight. This function translates the arguments into a timestamp. When the single argument is a numeric value, it is interpreted as a Unix timestamp in seconds. When the argument is a string, it's parsed to a timestamp. Formats a date into a string of format given in the second argument. The format string is described here 1321 . Parses datetime to a timestamp using the format. The format string is described here Returns the number of seconds since 1970-01-01 (the Epoc). Returns the week of this year (1-53). Returns the year.
1321.

TO_CHAR(Date date, String format) TO_TIMESTAMP(String value, String format) UNIX_TIMESTAMP(Date date) WEEK(Date date) YEAR(Date date)

System Built-In Functions

Function CONVERT(Object exp, String type) Description Converts exp to another data type. Supported data types: Integer types: SQL_TINYINT, SQL_SMALLINT, SQL_INTEGER, SQL_BIGINT, SQL_NUMERIC, SQL_DECIMAL, SQL_BOOLEAN Floating point types: SQL_REAL, SQL_FLOAT, SQL_DOUBLE String types: SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR Date/time types: SQL_DATE, SQL_TIME, SQL_TIMESTAMP Example: CONVERT(10, CASEWHEN(Object exp, Object v1, Object v2)

SQL_STRING)

If exp is true, v1 is returned, else v2.

COALESCE(Object exp1, If exp1 is not null then it is returned else exp2 is evaluated and if not null it is returned Object exp2, Object exp3, and so on. ...) NULLIF(Object v1, Object v2) If v1 equals v2 return null, otherwise v1.

3.14 Models
Models are used to simulate different business objects or processes. The models range from simple, defining several properties and a few business rules, to really complicated ones, e.g. representing a whole industrial plant. Models may act on its own or get attached to lower-level objects, such as devices. In the second case multiple instances of a model are created, each of them using object it's attached to as its primary data source. Each model comprises:

2000-2013 Tibbo Technology Inc.

304

AggreGate Documentation

Definitions of variables (properties) representing model values Definitions of functions (operations) that instruct the model to perform some processing or calculation Definitions of events the model can produce Definitions of bindings that tie model's properties, operations and events together allowing it to react to other objects' events or states Sets of business rules for decision making according to a machine-readable knowledge base Example of a simple real life model Simple monitoring and control systems allow direct visualization of values that were collected from devices. However, devices from different manufacturers use differing approaches for providing values with the same physical meaning. For example, network management products are used to track CPU load of network nodes. This simple metric is available in many different forms: Windows-based computers expose "spot" values of CPU load via SNMP Same Windows machines can provide WMI
186 -based 173 .

CPU load readings if SNMP is not available.

Cisco routers provide pre-calculated CPU utilization data as 5-minute and 1-hour averages. HP-UX servers have counter-type values showing how many seconds the CPU was busy since server startup. These counters require complex processing to calculate the current load. However, a Network Device dashboard 617 should have a "CPU Load" chart looking equally for all device types. A "High CPU Load" alert is also expected to behave similarly. In addition, we'd like to build a "CPU Load Overview" report showing current utilization for all devices in out network. The right way to ensure the above requirements is having a numeric "CPU Load" metric in every device that provides CPU data. This metric should have common format, but its calculation and update policy will differ between device types. That's where a model can help. The "CPU Load" model attaches to every network device and employs a set of business rules to calculate current CPU load. The rules calculation is triggered by a periodic binding. The business rule set calculation result is written into CPU Load variable that is declared by the same model. Models are a little bit similar to widgets 312 . A model may be interpreted as a widget that runs inside the server and has no user interface. However, both models and widgets have binding 951 engines that make them "life" by activating certain behaviour upon system events and state changes. Every user
108

has their own set of models.

Administering Models
Two contexts are used to administer models: One is the general Models 708 context, which serves as a container. The other is the Model 709 context, which holds the information for one model.

3.14.1 Model Types

There are two types of models: Absolute Models Relative Models

Absolute Models
Absolute model doesn't have a changeable data source. It uses absolute references to pull data from different parts of the system. All variables, functions and events declared by an absolute model are added to the model's own context 709 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

305

For example, a model simulating technological process should take data from multiple specific controllers and perform complex mathematical processing over them. Results of calculations should be visible as model properties. Such model should be absolute. Absolute model's bindings
311

and rule expressions

305

cannot include relative references

925 .

Relative Models
Relative models are designed to process data from a certain source context a relative model is created for each context it's attached to.
863

and its children. A separate instance of

For example, a model calculating CPU load of a network device with respect to its type and communication should attach to every network device, apply a rule set to its properties, and add "generic" CPU Load property to each device. Such model should be relative. Absolute model's bindings
311

and rule expressions

305

can include relative references

925 .

3.14.2 Model Lifecycle

Once a new model is created or a model is reinitialized after server startup, it goes through a fixed lifecycle: First, "valid" data source contexts
863

are found in accordance with model type

304 :

o If the model is absolute, its data source the model context itself. o If the model is relative, system calculates its validity expression for every context in the system to define whether it's "compatible" with the model. Second, a separate model instance is created for each of them. Third, model adds definitions of its variables, functions and events to every valid context. Fourth, model also adds functions referring model's rule sets
305

to all valid contexts.

Fifth, the model initializes its bindings 307 ' activators so that events and changes in source contexts will cause triggering of model binding processing.

Normal Model Operation

Once initial startup in completed, the model switches to wait mode. The following can cause its further activities: Periodic model bindings are processed upon schedule, causing the model process corresponding bindings Some server context events of variable value updates can also cause activation of certain model bindings Other system components read/write model properties and execute model functions

3.14.3 Model Rules

Each model may include multiple sets of business rules that comprise a machine-readable knowledge base helping the system to make decisions and perform complex calculations during autonomous functioning. All rule sets are fully independent from each other. Each set includes one or more rules that work in certain order (see Rule Set Types 306 ). Each rule set may take certain parameters, and its processing always results to a single object (of any type, e.g. number, string, or date).

Rule Components
Each rule in a set consist of target, expression, and condition. Each rule either returns result of the whole rule set or (re-)defines a single environment variable that is valid until the end of rule set processing.

RULE TARGET
Target defines how to treat the outcome of this rule set. If rule target is Final Rule Set Result, this rule stops rule set processing and returns a result of the whole rule set. In other cases target defines a name of environment variable that will be defined once rule processing is over. This variable can be referred from other rules' expressions and conditions.

RULE EXPRESSION

2000-2013 Tibbo Technology Inc.

306

AggreGate Documentation
911

Rule expression is an AggreGate expression

that returns result of any type. This result is:

Returned as the result of the whole rule set if rule Target is Final Rule Set Result. Stored as rule set's internal environment variable rewriting value of this variable if was already defined by other rules. This environment variable will be valid during the current rule set processing cycle. Rule expressions may refer to results of other rules from this set via {env/rule_target_variable_name} references.

RULE CONDITION
Rule Condition is an AggreGate expression 911 that should result to a Boolean value. If this value is false, the rule processing will be skipped and other rules will be processed according to the rule set type 306 . Rule conditions may refer to results of other rules from this set via {env/rule_target_variable_name} references. The rule condition is optional.

Using Rule Sets

To process a rule set from model's own binding 311 or any external system component, call a rule set context function. See referring rule sets 307 for more information.

Rule Set Example

This example describes a simple sequential type and operating system.
306

rule set that calculates CPU load of a network host regardless of the host
927

The model is relative 304 , it's attached to every network host and, thus, the default context condition is the context of a network device it's attached to. Target Final Rule Set Result Final Rule Set Result Final Rule Set Result Expression

of rule expression and

Condition

aggregate({.:hrProcessorTable}, '{env/previous} + {hrProcessorLoad}', 0) / records({.: hrProcessorTable}) aggregate({.:cpmCPUTotalTable}, '{env/previous} + {cpmCPUTotal5min}', 0) / records({.: cpmCPUTotalTable}) null

hasVariable({.:}, 'hrProcessorTable') hasVariable({.:}, 'cpmCPUTotalTable')

The first rule is used when device context has hrProcessorTable variable. It goes through the list of processor cores and calculates an average. The second rule, similarly, is used when device context has cpmCPUTotalTable variable. And finally, if no suitable rules are found CPU load is deemed undefined according to the third unconditional rule.

3.14.3.1 Rule Set Types

Models support two types of business rules sets: Sequential rule sets Dependent rule sets
306 307

3.14.3.1.1 Sequential Rule Sets

Rules in sequential rule sets are processed one-by-one from top to bottom of the rule list. Rules those conditions are defined and return false are skipped. The first processed rule targeted to Final Rule Set Result will stop rule set processing and return result of its Expression as the result of whole rule set. If no rules targeted to Final Rule Set Result are found or all such rules were skipped due to false Condition, the rule set processing will fail with Result Undefined error.

2000-2013 Tibbo Technology Inc.

AggreGate Server

307

3.14.3.1.2 Dependent Rule Sets

Rules in dependent rule set are processed our of their order they appear in the rule list. Processing starts by selecting all rules that point to Final Rule Set Result. Conditions of such rule(s) are calculated first, and the list of active final result rules (i.e. rules that have no condition or have true condition) is formed: If obtained final result rule list has more than one rule, rule set processing fails with Found multiple active rules to calculate the final result error. If obtained final result rule list has no rules, rule set processing fails with Found no active rules to calculate the final result error. If a single active final result rule is found, its Expression is calculated.

Dependent Rule Processing

If any rule Expression refers one or more environment variables, it is said to depend to other rules. To get result of those rule(s), the system founds all active (i.e. no/true condition) rules those target points to this variable. Rule set processing fails if zero or more than one rule is found (see above). If a single rule is found, it's Expression is calculated. This expression may recursively refer to the result of other rules.

3.14.3.2 Referring Rule Sets

Each rule set defined by a model is represented as a separate context function 878 . This function accepts a Data Table 854 of any format as its input and wraps its result into another Data Table to return it as function output. Name of the rule set context function matches the name of rule set itself. The rule set function is defined in the model context (or each context the relative model is attached to). Since context functions always return Data Tables any scalar value returned by the rule expression will be wrapped into a single-cell Data Table. For example, if rule set's expression targeted to Rule Set Result has returned a integer number, the rule set context function will return a single-cell Data Table with an Integer column and one row containing this integer. To if this function is referred from an expression, it will be necessary to use cell() expression language function extract the integer result from the function output table.
914

to

3.14.4 Model Bindings

The engine of a model is constructed of server context bindings 952 . Those bindings make the model truly dynamic by forcing it to react to the server context events 880 and changes of server context variables 869 . Those bindings may define: Relations between model data items (i.e. model's own variables
308 ,

functions
869 ,

309

and events
878

309 ). 880 ).

Relations between server context data items (i.e. server context variables Relations between server data items and models data items Every binding is evaluated at different points during model operation. See server context bindings
952

functions

and events

for more information.

3.14.5 Model Configuration

This section covers model configuration properties. All properties described here are available via Configure
904

action of a Model context

709 .

3.14.5.1 Model Properties

This defines the basic options for a model.

Field Description

Field Name

2000-2013 Tibbo Technology Inc.

308

AggreGate Documentation

Name . Name of the model context. It should satisfy context naming conventions name is required to refer to this model from other parts of the system. Description . Textual description Type . Model type
304 , 864

863 .

The

name

of the Model context.

description type validityExpression

Relative or Absolute.

Validity Expression. Determines which context(s) should the relative model attach to. See Resource Validity 948 for more information. Validity Update Rules. A list of context masks and event names. If event specified by Event field of this table occurs in any of context matching to the mask specified by Mask field in the same record, Validity Expression will be recalculated for this context. This allows to make model valid/invalid for a certain context if some changes occur in it. Enabled. If this flag unchecked, the model is deactivated and doesn't perform any active binding processing. However, all variables/function/event definitions added by this model remain available if the model is disabled. Normal Concurrent Bindings. Defines the core size of model's thread pool, i.e. base number of bindings that will be processed simultaneously. Maximum Concurrent Bindings. Defines the maximum size of model's thread pool, i.e. the number of concurrently processed bindings allowed in case of binding queue overflow. Maximum Unprocessed Binding Queue Length . Defines how many unprocessed binding operations can be queued before model's thread pool size grows over its core size towards maximum size. These properties may be accessed through the childInfo
710

validityListeners

enabled

normalConcurrentBi ndings maximumConcurrent Bindings maximumBindingQu eueLength

variable.

3.14.5.2 Model Variables

The model variables table contains properties of variables that are declared by the model.

Field Description
Name . Name of the variable. Description . Variable description. Format. Format of the variable. See format for details.
855

Field Name
name description section format

Writable. Flag indicating that variable is writable. Help. Detailed variable description. Group. Variable group, or NULL if variable does not belong to any group. Read Permissions . Permission level 932 in the model context (or a context the relative model is attached to) required to read the variable. Write Permissions. Permission level 932 in the model context (or a context the relative model is attached to) required to write the variable. Storage Mode. Defines whether variable's value is persistent ( Database storage type) or transient ( Memory storage type).

writable help group

readPermissions

writePermissions

storageMode

2000-2013 Tibbo Technology Inc.

AggreGate Server

309

History Storage Time . Defines how long historical values of this variable are stored.

updateHistoryStorageTime

These properties may be accessed through the modelVariables Read more about variable definition properties under Variables

710 869 .

variable.

3.14.5.2.1 Model Variable Statistics

Model variables support statistical channels numeric values.
936

that help to maintain long-term history for variable fields that represent

Viewing Statistics
To view brief statistics of a model variable, run View Status
910

) action and switch to Statistics tab.

Viewing Detailed Statistics

To view detailed model variable statistics, use global View Statistics
729

action.

3.14.5.3 Model Functions

The model functions table contains properties of functions that are declared by the model.

Field Description
Name . Name of the function. Description . Description of the function. Input Format. Input format of the function. See format
855

Field Name
name description section for details.
855

inputformat outputformat help group permissions

Output Format. Output format of the function. See format Help. Detailed description of variable. Group. Variable group
870 ,

section for details.

or NULL if variable does not belong to any group.

Permissions. Permission level 932 in the model context (or a context the relative model is attached to) required to execute the function. Implementation. Source code of Java class that implements the function body, i.e. does something the function is supposed to do. See defining and implementing functions 994 for details. Plugin. ID of server plugin 950 that defines the model. Required if function implementation should access plugin's internal Java classes. These properties may be accessed through the modelFunctions Read more about function definition fields under Functions
878 . 711

implementation

plugin

variable.

3.14.5.4 Model Events

The model events table contains properties of event types that are declared by the model.

Field Description
Name . Name of the event. Description . Description of the event.

Field Name
name description

2000-2013 Tibbo Technology Inc.

310

AggreGate Documentation

Format. Format of the event data. See format Help. Detailed description of the event. Level . Default level of the event.

855

section for details.

format help level group permissions

Group. Event group, or NULL if event does not belong to any group. Permissions. Permission level 932 in the model context (or a context the relative model is attached to) required to subscribe to this event type. Fire Permissions. Permission level 932 in the model context (or a context the relative model is attached to) required to generate an instance of this event type. These properties may be accessed through the modelEvents Read more about event definition fields under Events
880 . 711

firePermissions

variable.

3.14.5.5 Rule Sets

The rule sets table defines sets of business rules
305

used by the model.

Field Description
Name . Name of a rule set. User to refer this set from other components of the system. Since each set is represented by a function 878 , its name may contain only letters, numbers and underscore. Description . Human-readable description of the rule set. Type . Rule set type: Sequential Processing
306

Field Name
name

description
307 .

or Dependency Tracking

type rules

Rules. The list of rules. See descriptions of rule fields below These properties may be accessed through the ruleSets
712

variable.

Rule Fields
Each rule in a rule set has the following properties:

Field Description
Target. Can be either the Final Rule Set Result (i.e. result of the whole rule set) or name of any rule set environment variable. Expression . An expression
911

Field Name
target

that calculates rule result.

expression

Rule Expression Resolution Environment Default Context

927

922

Context of the absolute model or a context the relative model is attached to. Data that was passed to a rule set function
307 .

Default Data Table 927 Default Row Environment Variables 930

927

0 Any variable that was defined by the previously executed rules of the same rule set. condition

Condition. An optional expression 911 that should result to a Boolean value. Rule evaluation is skipped if the condition expression results to false.

2000-2013 Tibbo Technology Inc.

AggreGate Server

311

Rule Condition Resolution Environment Default Context

927

922

Context of the absolute model or a context the relative model is attached to. Data that was passed to a rule set function
307 .

Default Data Table 927 Default Row Environment Variables 930

927

0 Any environment variable that was defined by the previously executed rules of the same rule set. comment

Comment. Any notes about rule's purpose.

3.14.5.6 Bindings
The bindings table defines model bindings.

Field Description.
Target. Binding target is a special type of reference 925 that points to where the evaluation result of binding expression will be written when the binding is processed. Expression . This is an expression 911 that is evaluated every time a binding is processed. The evaluation result is stored in the binding target. Activator. This is a reference that points to some event or property of the model that will trigger the processing of the binding. The Activator parameter is available only when On event parameter is enabled. Condition. Condition is an expression 911 that is evaluated first after binding activation. If this expression results to false, the binding execution is skipped. On Startup. When this parameter is enabled, the binding is processed every time a model instance is created. On Event. When this parameter is enabled and an Activator is specified, the binding is processed whenever there's a changes in the property the activator refers to. If the Activator refers to an event, the binding will be processed when the event fires. If On event is enabled and an Activator is not specified, the binding will be automatically processed: The binding's Expression includes references, pointing to one or more variables. A change in any of these variables will cause the binding to run. Periodically. If this parameter is enabled, the binding will be processed periodically. Period. Interval between binding processing sessions. This parameter may be changed only if Periodically is turned on. These properties may be accessed through the bindings
712

Field Name
target

expression

activator

condition

onstartup

onevent

periodically period

variable.

3.14.6 Models Security

All model bindings
307

are processed with model owner's permissions

931 .

It effectively means that:

Binding expressions are calculated with the model owner's permissions The binding target is also written with the model owner's permissions Thus, the model may access only data that is accessible by its owner.

2000-2013 Tibbo Technology Inc.

312

AggreGate Documentation

If you create a copy of a certain model under another user account 108 , the copy may not function properly if new model's owner has no permissions to access data referred by the bindings of the cloned model.

Model Modification
Only users that have Administrator effective permission level 932 in the model context may modify model configuration. This ensures maximum security for the potentially dangerous model operations.

Custom Model Functions Security

Model functions 309 that have custom implementations can potentially access any server data. Thus, system administrators developing function implementation code should always respect security model and use only the instance of CallerController object that has been passed to the FunctionImplementation.execute().

3.14.7 Models Performance

Models are complex active server resources that may have significant performance impact. An "engine" of a model is its bindings 307 and rules. Model's performance impact is a multiplication of the following: Number of model's instances. An absolute 304 model has just on instance, while a new instance of a relative 304 model is created for every resource it's attached to. Thus, a single relative model can have thousands of instances. Number of model's bindings. Frequency of model binding processing. It may either be explicitly specified in the binding options (for Periodic bindings) or implicitly defined by the frequency of events or state changes that trigger binding execution (for On Event bindings). Frequency of model variable reads/writes, model function calls and model events generation performed by other active system components (such as alerts 216 , trackers 257 or widgets 312 ). Complexity and impact of binding expressions and model rule more information.
305

expressions. See expressions performance

924

for

Impact of writing binding targets. Writing a binding target is in most cases writing a context variable or calling a context function. See variables performance 878 and functions performance 880 for more information. Impact of custom Java code implementing model's functions.

3.15 Widgets

A Widget is a special "sub-application" with graphical a user interface (GUI) defined by a number of widget components 322 and their layout 318 . Widgets are good for building custom forms and Human Machine Interfaces (HMI). These forms and interfaces may be used to control, configure and different hardware devices or system components.
Before you begin: Widgets let you manipulate and view AggreGate data in various forms. To be effective in creating them, you should be familiar with References 925 , Expressions 911 and finally, Data Bindings 951 . Please read these three topic before continuing. Once you understand these topics, you can read all about the specific ways in which bindings apply to widgets in Widget Bindings 604 . Widgets are created in GUI Builder 827 , which is a part of AggreGate Client. The core of a widget is its template 314 -text in XML format, containing the layout and properties of its internal components along with relations between these components and the data model, i.e. data that comes from AggreGate Server contexts 863 . These relations exist in the form of Widget Bindings 604 and Widget Scripts 610 . Every widget may be launched in different AggreGate Server User Interfaces, e.g. in AggreGate Client 776 . Its appearance will depend on the specific User Interface in which it runs, but its overall structure and behaviour will be similar. Here is what a running widget may look like in AggreGate Client:

2000-2013 Tibbo Technology Inc.

AggreGate Server

313

Related tutorials: Creating a Widget to Monitor a Device

1217

Monitoring Device Parameters Using a Chart 1239 Building Complex Chart 1244 Keeping History of Object Changes Manipulating SVG Images
1224 1267

Administering Widgets
Two contexts are used to administer widgets: One is the general Widgets 770 context, which serves as a container. The other is the Widget 774 context, which holds the information for one widget.

Moving Widgets between Servers

It's often necessary to transfer one or more widgets from one AggreGate Server installation This can be the case of moving to a production server from a development one, or just parti replication of configuration during distributed installation 99 setup. There are three basic ways to transfer widgets between servers:

1. Copy/move the whole database 80 from one server to another. If the database server was runni on a standalone machine and the old AggreGate Server won't be longer used, it's possible stop the old server and re-configure the new one to connect to the same database. Moving whole database will transfer all widgets, along with the full server configuration. 2. For bulk transfer of widgets, Export use 907 /Import 908 actions of Widgets moving all or selected widgets of a certain user 108 at once.
774

context. This will allow

3. In fact, the widget itself is its XML template plus several minor options (such as name, des andtype 314 ). Therefore, t's i also possible to open the XML template of a widget and send it to another server (e.g. via e-mail). On the target server, it will be necessary to create a new set up its name/description and other options, and insert the XML template copied from th server.

Built-In Widgets
Several widgets are built into AggreGate Server and appear under default administrator's Query Executor. This widget allows you to test and debug queries
271 . 109

user account:

2000-2013 Tibbo Technology Inc.

314

AggreGate Documentation

Daily Alert. Contains a bar diagram displaying daily alert count and a table that lists alert instances once a certain bar is clicked on a diagram.

3.15.1 Creating Widgets

Widgets may be created only in AggreGate Client analogs of a GUI Builder 827 .
776 .

Other AggreGate Server User Interfaces have no

New widgets are created using the Create New Widget 770 action of the Widgets context. This is a Drag and Drop 895 action that accepts any context type. The action assumes that one context (the "accepted context") is selected before it starts. This accepted context has one simple use during widget creation: its type 864 will be used as the type of context for which the new widget will be available. The Launch Widget 316 action will be installed in all contexts of this type once the widget is created. Example: "accepted" every User description If a User 759 context is dragged and dropped on the Widgets 770 context (i.e. selected as an context for a Create New Widget action), the newly created widget will be suitable for use with context in AggreGate Server. Each User context will have a new Launch Widget action with a matching that of the widget. See Launch Widget Action 316 for details.

Once the context type is selected, a GUI Builder 827 starts which is used to build a widget by editing its template 314 in a visual editor. You will now create the layout 318 for the new widget, by adding some components 322 to it and configuring their properties. This is also a good time to define some bindings 604 , i.e. relations between widget components and the different variables 869 or functions 878 of AggreGate Server contexts. You can stop editing the widget template in GUI Builder by clicking on Done or Cancel in the GUI Builder toolbar. If Cancel is clicked, action is terminated and no widget is created. If Done, the user is prompted 896 to specify properties 315 for the new widget. Most properties are already set by this point, but you still have to provide a name and a description for the new widget. After that, AggreGate Server actually creates Widget 774 context representing new widget. Then it finds all context of the same type as type of "accepted" context for this action and installs a Launch Widget 316 action to them. Widget creation is now finished. You can now launch the widget action from the contexts for which it was installed.

3.15.2 Widget Template

The core of a widget is its template. The template is written in XML and stored as a property context. It defines a widget's structure, and has two primary parts: Layout
318 315

of the Widget

774

, defining the internal components

604

322

of a widget, their properties and relative positions

Data bindings

that define the relations between widget components and data provided by AggreGate Server

In most cases, the widget template is edited in GUI Builder 827 and editing is initiated by Edit Template 774 action of a Widget context. But in some rare cases, the template may be manually changed (or replaced) by editing its raw text. GUI Builder 827 also lets you export and import templates from external XML files.

Template Backups
It is possible to force the server to keep history of widget template modifications. For more information, see Keeping History of Object Changes 1267 tutorial.

3.15.3 Widget Types

There are two types of widgets: Absolute Widgets Relative Widgets

Absolute Widgets
Absolute widgets usually process and integrate data coming from different source contexts.

2000-2013 Tibbo Technology Inc.

AggreGate Server

315

For example, a complex Human-Machine Interface widget in a process control application shows data coming from different sensors and has buttons or other active components for sending commands to the actuators. Such a widget should be absolute. Absolute widget bindings
604

cannot include relative references

925 .

Relative Widgets
Relative widgets are designed to process data from a certain context 863 and its children. This is useful when creating a form or a custom interface for representing data coming from one Device or system resource. Relative widgets are usually activated using the Launch Widget 316 action of the context whose data should be processed. For example, in a network management system you may have a relative widget called CPU Load Chart. You could right-click a Mail Server Device in AggreGate Client and select CPU Load Chart from context menu.

3.15.4 Widget Default Context

The term default context applies to a widget in two different cases: During widget creation
314

or editing

During widget execution

317

During widget creation: When the widget template is being edited in GUI Builder, new bindings 604 are created to bind widget components 322 with data from contexts. When a new widget is created or edited, context paths in newly created bindings which refer to contexts below the default context are constructed relatively to the default context. During widget execution: The default context is also defined during widget execution. This is the context from which the Launch Widget action 316 was launched. This default context is used to resolve relative references during widget execution. {.deviceservers:children#records} - this is a ref resolving to number of user's DS if widget is created for user context. Is uses context path relative to default context. The widget normally gets data from its default context, but may exchange data with any other AggreGate Server contexts. See widget bindings
604

for more information.

314

Note: default context for any absolute

widget is a root context of AggreGate Server context tree.

3.15.5 Widget Configuration

Widget properties are viewed and edited using the Configure Widget
774

action of the Widget context.

Field Description
Widget Name. Name of the widget context. It should satisfy context naming conventions The name is required to refer to this widget from other parts of the system. Widget Description. Textual description
864 863 .

Field Name
name

of the Widget context.

314

description template type validityExpression

Widget Template. Text of the widget template Widget Type. Widget type
314 ,

in XML format.

Relative or Absolute.

Validity Expression. Determines which context(s) may be "understood" by the widget. See Resource Validity 948 for more information. Validity Update Rules. A list of context masks and event names. If event specified by Event field of this table occurs in any of context matching to the mask specified by Mask field in the same record, Validity Expression will be recalculated for this context. This allows to make widget valid/invalid for a certain context if some changes occur in it. Default Context. The default context to be used when editing the template
314

validityListeners

of a relative

defaultContext

2000-2013 Tibbo Technology Inc.

316

AggreGate Documentation

314 widget in GUI Builder or launching it directly, without using a Launch Widget action of a Device or a system resource. Its value is automatically set to the path of the context for which that widget was created 314 . There's usually no need to edit it, except if this context is deleted. See Default Context for a Widget 315 for details.

Default Location. Widget Window Location 955 to be used when widget is launched manually, i.e. without using Auto Run 625 , Favourite 626 or other facility. When Launch Widget 774 action is added to Auto Run of Favourites, it's execution parameters 896 allow to override the Default Location and open widget window on a custom dashboard/position. These properties may be accessed through the childInfo
775

defaultLocation

variable.

3.15.6 Launching Widgets

There are several ways to launch a widget: From the GUI Builder
827 .

This method is mostly used when testing a new widget.

Using the Launch Widget 774 action of the Widget Context. For relative 314 widgets, this method will launch the widget and have it process data from the context specified by the Default Context widget property 315 . Using a Launch Widget action
892

(see below) to start a relative

314

widget for a certain Device or system resource.

Launch Widget Action

This action may be found in every context for those widget's validity expression 948 is true. When the Launch Widget action is started in some context, this context becomes a default context 315 for the running widget. For example, if a Custom User Info Form widget is created for a User 759 context (e.g. has Validity Expression {.#type} == 'user'), an action called Custom User Info Form will appear in the context of every AggreGate Server user. Its description is the same as that of the widget itself. Actions that are used to start widgets may be easily recognized by a icon. Here is what a Launch Widget action looks like in a context menu within AggreGate Client:

Relative widgets will install their Launch Widget Action only into contexts that are accessible for the widget owner according to his permissions 931 . To be able to launch this action, the user must have an effective permission level contexts: Widget context
774 935

of Observer in two

of the actual widget being launched

The context on which the widget operates, i.e. the one where Launch Action is defined

Widget Window

2000-2013 Tibbo Technology Inc.

AggreGate Server
In addition to the standard window toolbar buttons
781 ,

317

widget window has several additional buttons:

827 .

Edit. Stops current widget and opens it for editing in GUI Builder Event Log. Opens widget event log
613 .

Standalone Widget Player

It's often necessary to run a widget as a standalone application, without starting AggreGate Client or other AggreGate Server user interface. For example, the widget may be displayed on a touch screen panel of embedded PC that provides instant control/monitoring for some equipment. To run a widget in standalone mode, use Widget Player
614

application that is a part of AggreGate Client.

3.15.6.1 Widget Input Parameters

When a widget is being started, it receives a special Data Table Parameters Table.
854

on its input. This Data Table is called Widget Input

Passing Parameters to a Widget

If a widget is started directly from a AggreGate Client (by manually executing its Launch Action pass any parameters to it.
316 ),

there is no way to

However, widgets can be launched from inside another widgets. When a widget wants to launch another widget, it executes a binding 604 those target 605 is set to Launch Widget action 953 of the widget to start. This binding's expression 606 should result to a Data Table, and this table will be passed to a newly opening widget as its Widget Input Parameters Table. So, to recap, here is the necessary sequence for passing parameters between widgets: In originating widget, create a binding those target points to a launch action of another widget, e.g. action/users. admin.widgets.voltageChart:launch. Make sure that expression of the above binding creates/fetches and returns a Data Table object.

Processing Input Parameters in a Widget

Accessing input parameters from within a widget is very easy. The Widget Input Parameters Table is always a default table 927 during widget binding expression evaluation. Thus, if this table has field called mode, this parameter can be referred from any binding's expression by using {mode} reference.

3.15.6.2 Widget Execution

When a widget is started in a AggreGate Server User Interface, a new window is created for it. The widget engine renders the contents of the widget's root panel in this window. The window's size may be defined by the Width and Height parameters of the root panel (in pixels), or calculated automatically based on the optimal sizes of the widget's internal components if Width or Height of the root panel are not specified (i.e. set to zero). An optimal size is whatever size a component has to be so it could display all of its information without hiding any or requiring the user to scroll to see it. For a label, the optimal size is however big the label has to be to show all text. For a slider, it's however long the slider has to be to fit in all ticks, etc. If only the width or the height is specified, the other dimension is optimally sized. If a widget window is resized, its internal components are moved and resized according to their individual constraints and sizes. A widget's layout may also change on execution, when components properties are modified by bindings 604 according to user input or changes in context data.
318

Bindings Processing
When a widget starts up, the widget engine processes any bindings within it which are scheduled for processing on startup. Usually, bindings executed on startup are used to read certain context values and initialize the widget components. While working, the widget monitors changes in contexts and component properties, and processes the bindings again when such changes are detected. Also, some bindings can be configured for periodic processing. Every processed binding may change server data, properties of widget components, or execute widget script See the bindings
604 610 .

article for more information.

2000-2013 Tibbo Technology Inc.

318

AggreGate Documentation

3.15.7 Widget Layout

Every widget consists of several graphical components Normal components Containers The primary difference between containers and normal components is that containers may hold other components and containers inside them. Each container has one or more panes in which child components may be placed. For example, a Panel 378 container has a single pane that is always visible and has no decoration. A Tabbed Panel 379 container may have any number of panes (tabs) containing child components. Every pane has a separate layout and may contain any number of child components or containers. The basic component of a widget is its root panel 376 . This component is a container for all other components of a widget. When a widget is running, its root panel occupies all available space within the widget's window.
322 .

These can be divided into two large groups:

Pane Layout Types

Every pane in a container has its own layout of child components. There are two layout types: Grid
318

Layout
322

Absolute

Layout
376

The layout may be changed by modifying Layout

property of a pane.

Component Constraints
The constraints of a widget component define its position and size within its parent container. Constraints also define how components change size and position when the widget window is resized. Every layout provides its own constraints for each widget component excluding root pane.

3.15.7.1 Grid Layout

This layout is a grid of rows and columns, allowing certain components to span multiple rows or columns. Rows can have different heights. Similarly, columns may have different widths. This grid may be toggled (shown or hidden) when editing the widget template in GUI Builder 827 , but it is never shown when the widget is running. Only the actual components are visible. Don't mix grid layout with absolute layout's snapping grid
842 .

Here is an example widget with five Button

334

components in its root panel:

The layout grid for this widget has three rows and three columns. The button in the second row spans all columns, and the button in the third row spans the two right columns:

2000-2013 Tibbo Technology Inc.

AggreGate Server

319

If you enlarge the widget window as shown in the following figure, you will notice that the bottom row, which contains Button 5, gets all the new vertical space. The new horizontal space is evenly split between all columns. This resizing behavior is based on weights assigned to individual components in the panel layout. You will also notice that each component takes up all available horizontal space but not (as you can see with button 5) all available vertical space. This behavior is also specified by component weights.

Grid Layout Constraints

Constraints that characterize the position of components in a grid layout are:

ROW, COLUMN
Specify the row and column of the top-left part of the component. The leftmost column is column 0 and the top row is row 0. Property names: gridx, gridy

ROW SPAN, COLUMN SPAN

Specify the number of columns or rows occupied by the component in the layout grid of its parent container. These constraints specify the number of cells the component occupies, not the number of pixels or any other unit. The default value is 1. Property names: gridWidth, gridHeight

ANCHOR
Used when the component is smaller than its display area to determine where (within the area) to place the component. Valid values are: Center North East South West North-West North-East South-East South-West So if you have a big area and a small component, the Anchor position lets you determine where the component sits

2000-2013 Tibbo Technology Inc.

320

AggreGate Documentation

within the abundance of space it has available to it. Property name: anchor

FILL
Used when the component's display area is larger than the component's requested size to determine whether and how to resize the component. Valid values include None (the default), Horizontal (make the component wide enough to fill its display area horizontally, but leave its height as-is), Vertical (make the component tall enough to fill its display area vertically, but leave its width as-is), and Both (make the component completely fill its display area). Property name: fill

TOP MARGIN, BOTTOM MARGIN, LEFT MARGIN, RIGHT MARGIN

Specifies the external padding of the component -- the minimum amount of space between the component and the edges of its display area. The display area is the amount of space the current layout provides for the component. By default, each component has no external padding (i.e. all margins are set to zero). Property names: insetsTop, insetsBottom, insetsLeft, insetsRight

WEIGHT X, WEIGHT Y
Specifying weights can have a significant impact on the appearance of the components in the layout grid. Weights are used to determine how to distribute space among columns (Weight X) and among rows (Weight Y); this is important for specifying resizing behavior. For each column, the weight is related to the highest Weight X specified for a component within that column (the same goes for each row's weight and the highest Weight Y for a component within that row). Unless you specify at least one non-zero value for Weight X or Weight Y, all components clump together in the center of their container . This is because when the weight is 0.0 (the default), any extra space is put between the grid of cells and the edges of the container. Usually, weights are specified with 0.0 and 1.0 as the extremes. Larger numbers within this range indicate that the component's row or column should get more space. Extra space tends to go toward the rightmost column and bottom row. Here is how components look like if their weights are 1.0:

Setting weights of the same components to 0.0 produces the following result:

Property names: weightx, weighty

CONSTRAINTS EXAMPLE
Let's return to our example widget with five buttons:

2000-2013 Tibbo Technology Inc.

AggreGate Server

321

Here are constraints for these buttons (only non-default values are shown here): Button 1: Row: 0 Column: 0 Weight X: 1.0 Fill: Horizontal Button 2: Row: 0 Column: 1 Weight X: 1.0 Fill: Horizontal Button 3: Row: 0 Column: 2 Weight X: 1.0 Fill: Horizontal Button 4: Row: 1 Column: 0 Column Span: 3 Weight X: 1.0 Fill: Horizontal Button 5: Row: 2 Column: 1 Column Span: 2 Anchor: Center Top Margin: 20 Weight X: 1.0 Weight Y: 1.0 Fill: Horizontal To find out how to build the actual layout, see the editing widget layout
836

section in the description of GUI Builder.

2000-2013 Tibbo Technology Inc.

322

AggreGate Documentation

3.15.7.2 Absolute Layout

This layout allow to specify absolute position for every component. This may be very convenient for putting different gauges, meters and similar components over an image or animated vector graphics. Components in absolute layout may easily overlap each other. Here is an example of what an absolute layout may look like (two components are located at absolute positions in root panel 376 ):

Absolute Layout Constraints

Constraints that characterize position of component in an absolute layout are:

X COORDINATE, Y COORDINATE
These are absolute horizontal and vertical coordinates of the component. Horizontal (X) coordinates increment from left to right, vertical (Y) coordinates increment from top to bottom, so top left corner of the frame has coordinates X=0, Y=0.

Z-ORDER
Z-order determines how "high" is the component located in the parent container and, thus, which components will be overlapped by it. Higher Z-order number means that component is higher than the other components and will overlap them.

3.15.8 Components
Widget components are divided into several categories: Normal components Containers Charts
384 376 322

Normal components are used to present data or interact with the user. Containers may hold normal components or other containers. However, some containers may also interact with the user. For example, the Tabbed Panel 379 container monitors mouse clicks on its tabs (to display the tab that was clicked). Some additional information on widget components may be found in the widget layout
318

section.

Component have a slightly different appearance under different AggreGate Server User Interfaces. For example, a simple Button 334 may appear different in AggreGate Client 776 , Web Admin 632 and in the forthcoming web interface for mobile phones and communicators. A component's appearance and behaviour in a certain AggreGate Server User Interface is defined by a component renderer.

Normal Components
Normal components may not have child components (as opposed to containers supported by the widget engine: Label
323 376 ).

Here is a list of normal components

Text Field

325

2000-2013 Tibbo Technology Inc.

AggreGate Server

323

Password Field

326

Formatted Text Field List

331

328

Text Area HTML Area Button

334

332

334

Toggle Button Radio Button Check Box Combo Box

337

339

340

340

Date Time Picker Data Table Editor Event Log Slider

347 345

341

344

Spinner

348

Progress Bar Image

350

349

Vector Drawing

352

Gauge

558

Arc Gauge Meter

360

563

Compass Map
364

362

Device

367

3.15.8.1 Label
A label is a display area for a short text string, which doesn't react to input events and thus may not get keyboard focus. This is what labels looks like:

2000-2013 Tibbo Technology Inc.

324

AggreGate Documentation

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
TEXT (Default Property
Text of label message. Property name: text Property type: String In addition to HTML area 334 component, label may also show simple HTML text that must start with <html> tag, for example: <html><font color="red">Red</font> and <b>bold</b> text.</html>
586 )

ALIGNMENT
Horizontal alignment of text within label display area. Possible values: Description Left Center Right Value 2 0 4

Property name: horizontalAlignment Property type: Integer

VERTICAL ALIGNMENT
Vertical alignment of text within label display area. Top, Center or Bottom. Possible values: Description Top Center Bottom Value 1 0 3

Property name: verticalAlignment Property type: Integer

ICON
Image shown on the label. If NULL, no image will be displayed.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: icon Property type: Data Block

325

ICON TEXT GAP

Defines the space between the text and the icon. Property name: iconTextGap Property type: Integer

DISABLED ICON
The image shown on the label when the label is disabled. If NULL, the Disabled Icon will be auto-generated from a normal Icon. Property name: disabledIcon Property type: Data Block

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.2 Text Field

Text Field is a component that allows editing a single line of text. Here is what a text field looks like:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
TEXT (Default Property
586 )

Default text in the text field. Property name: text Property type: String

EDITABLE
This flag indicates that text in the text field can be changed. The primary difference between non-editable and nonenabled 586 components is that text in a non-editable component is not grayed out and may be selected using the mouse. Property name: editable Property type: Boolean

ONSCREEN KEYBOARD
Defines whether this component should support onscreen keyboard for text input. See touchscreen support details. Possible choices are:
616

for

2000-2013 Tibbo Technology Inc.

326

AggreGate Documentation

None - don't use onscreen keyboard Single Click - show the keyboard upon any click in the component area Double Click - show the keyboard only if component is double-clicked Property name: onscreenKeyboard Property type: Integer

ALIGNMENT
Horizontal alignment of text within label display area. Possible values: Description Left Center Right Value 2 0 4

Property name: horizontalAlignment Property type: Integer

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

Custom Events
CARET UPDATE
This event fires each time when a caret is moved or any text is entered in the component. Event name: caretUpdate Event fields: Field ID Dot Mark Name id dot mark Type Integer Integer Integer Description Event type ID. The location of the caret. The location of other end of a logical selection. If there is no selection, this will be the same as dot.

3.15.8.3 Password Field

Password Field is a component that allows editing a single line of masked (hidden from view) text. This is what a password field looks like:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

2000-2013 Tibbo Technology Inc.

AggreGate Server

327

Custom Properties
ONSCREEN KEYBOARD
Defines whether this component should support onscreen keyboard for text input. See touchscreen support details. Possible choices are: None - don't use onscreen keyboard Single Click - show the keyboard upon any click in the component area Double Click - show the keyboard only if component is double-clicked Property name: onscreenKeyboard Property type: Integer
616

for

ALIGNMENT
Horizontal alignment of text within label display area. Possible values: Description Left Center Right Value 2 0 4

Property name: horizontalAlignment Property type: Integer

PASSWORD (Default Property

586 )

Default password in the password field. Should usually be left blank. Property name: password Property type: String

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

Custom Events
CARET UPDATE
This event fires each time when a caret is moved or any text is entered in the component. Event name: caretUpdate Event fields: Field ID Dot Mark Name id dot mark Type Integer Integer Integer Description Event type ID. The location of the caret. The location of other end of a logical selection. If there is no selection, this will be the same as dot.

2000-2013 Tibbo Technology Inc.

328

AggreGate Documentation

3.15.8.4 Formatted Text Field

Formatted Text Field is a component that allows editing a single line of text and supports formatting arbitrary values. Here is what a formatted text field looks like:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
TEXT (Default Property
586 )

Default text in the text field. Property name: text Property type: String

EDITABLE
This flag indicates that text in the text field can be changed. The primary difference between non-editable and nonenabled 586 components is that text in a non-editable component is not grayed out and may be selected using the mouse. Property name: editable Property type: Boolean

ONSCREEN KEYBOARD
Defines whether this component should support onscreen keyboard for text input. See touchscreen support details. Possible choices are: None - don't use onscreen keyboard Single Click - show the keyboard upon any click in the component area Double Click - show the keyboard only if component is double-clicked Property name: onscreenKeyboard Property type: Integer
616

for

ALIGNMENT
Horizontal alignment of text within label display area. Possible values: Description Left Center Right Value 2 0 4

Property name: horizontalAlignment Property type: Integer

2000-2013 Tibbo Technology Inc.

AggreGate Server

329

VALIDATION MODE
Select regular expression or mask field validation. Possible values: Description Mask Regular Expression Value 0 1

Property name: validationMode Property type: Integer

Mask, Valid Characters, Invalid Characters, Placeholder and Placeholder enabled when Validation Mode is Mask.

Character are only

Regular Expression in only enabled when Validation Mode is Regular Expression.

MASK
Mask validation pattern. This parameter specifies the set of characters that can be typed at each position in the field. The following characters can be specified: Character # ' U L A ? * H Description Any number. Escape character, used to escape any of the special formatting characters. Any character. All lowercase letters are mapped to upper case. Any character. All upper case letters are mapped to lower case. Any character or number. Any character. Anything. Any hex character (0-9, a-f or A-F).

Mask property works together with Valid Characters and Invalid Characters (see below): Only symbols appearing in Valid Characters will be allowed in any position of final value. Any symbol appearing in Invalid Characters will not be allowed in any position of final value. Property name: mask Property type: String

VALID CHARACTERS
A list of characters that will be valid in any position of final value. Thus, if Valid Characters is non-null, symbol will be valid if it appears inside Valid Characters string and matches the mask. Property name: validCharacters Property type: String

INVALID CHARACTERS
A list of characters that will not be valid in any position of final value independently to the Mask. Property name: invalidCharacters Property type: String

PLACEHOLDER
The string to use if the value does not completely fill in the mask. A NULL value implies the Placeholder Character

2000-2013 Tibbo Technology Inc.

330

AggreGate Documentation

should be used. When initially formatting a value if the length of the string is less than the length of the mask, two things can happen. Either the Placeholder string will be used, or the Placeholder Character will be used. Precedence is given to the placeholder string. The placeholder String is only used on the initial format, on subsequent formats only the placeholder character will be used. Property name: placeholder Property type: String

PLACEHOLDER CHARACTER
The character to use in place of characters that are not present in the value, i.e. the user must fill them in. The default value is a space. This is only applicable if the Placeholder string has not been specified, or does not completely fill in the mask. Property name: placeholderCharacter Property type: String

REGULAR EXPRESSION
The regular expression pattern Property name: regEx Property type: String
1318

to use for value validation if Validation Mode is set to Regular Expression.

OVERWRITES TEXT
Configures the behavior when inserting characters. If this parameter is true, new characters overwrite existing characters in the field. Property name: overwritesText Property type: Boolean

FOCUS LOST BEHAVIOUR

Controls what happens when formatted text field loses focus. Description Commit Commit Or Revert Revert Persist Value Notes 0 1 2 3 Commit the value. If the value being edited isn't considered a legal value then the value will not change, and then edited value will persist. Similar to Commit, but if the value isn't legal, behave like Revert. Revert the display to match that the default, possibly losing the current edit. Do nothing, i.e. don't update the value.

Property name: focusLostBehaviour Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

Custom Events
CARET UPDATE
This event fires each time when a caret is moved or any text is entered in the component. Event name: caretUpdate Event fields:

2000-2013 Tibbo Technology Inc.

AggreGate Server

331

Field ID Dot Mark

Name id dot mark

Type Integer Integer Integer

Description Event type ID. The location of the caret. The location of other end of a logical selection. If there is no selection, this will be the same as dot.

3.15.8.5 List
A component that allows the user to select one or more values from a list. This is what a list looks like:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
SELECTION MODE
Selection mode for list items. One of Single Selection, Single Interval Selection or Multiple Intervals Selection. Property name: selectionMode Property type: Integer

LAYOUT ORIENTATION
Defines how list cells are laid out. A list with four cells can be laid out in one of the following ways: Vertical:

0 1 2 3
Vertical Wrap:

0 2

1 3

Horizontal Wrap:

0 1

2 3

Property name: layoutOrientation Property type: Integer

LIST ITEMS
A table that defines all items in the list. Property name: listItems

2000-2013 Tibbo Technology Inc.

332

AggreGate Documentation

Property type: Data Table It is possible to fill a List with selection values 856 of a certain Data Table field using a binding 604 . For example, binding that will fill a List with the countries available in the Country field of User Information variable defined in the User context of user admin will look as follows: Target: form/list1:listItems Expression: {users.admin:childInfo$country#options} This binding is created automatically when dragging a variable field to a List in GUI Builder here 845 .
827 .

760

Check details

SELECTED ITEMS (Default Property

List of items that are initially selected. Property name: selectedItems Property type: Data Table

586 )

SELECTED ITEM
List of item that are initially selected (convenient method to set/get just one selected item in Selected Items property). Property name: selectedItem Property type: dynamic

VISIBLE ROW COUNT

Sets the preferred number of rows in the list that can be displayed without a scrollbar if there is enough space in the layout of the parent container. This property may be set to Auto. In this case, the list will occupy all available space in the layout grid of the parent container. Property name: visibleRowCount Property type: Integer

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

Custom Events
LIST SELECTION
This event fires when a user selects or de-selects some list items. Event name: listSelection

3.15.8.6 Text Area

A Text Area is a component that displays multiple editable lines of text. This is what a text area looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

333

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
TEXT (Default Property
586 )

Default text contained in the text area. Property name: text Property type: String

EDITABLE
This flag indicates that text in the text field can be changed. The primary difference between non-editable and nonenabled 586 components is that text in a non-editable component is not grayed out and may be selected using the mouse. Property name: editable Property type: Boolean

LINE WRAP
Sets the line-wrapping policy of the text area. If enabled, lines will be wrapped if they are too long to fit the allocated width. If disabled, the lines will always be unwrapped. Property name: lineWrap Property type: Boolean

WRAP ON WORD BOUNDS

Sets the style of wrapping used if line wrap is enabled. If enabled, the lines will be wrapped at word boundaries (whitespace) if they are too long to fit within the allocated width. If disabled, the lines will be wrapped at character boundaries (i.e, broken mid-word). Property name: wrapStyleWord Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

Custom Events
CARET UPDATE
This event fires each time when a caret is moved or any text is entered in the component. Event name: caretUpdate Event fields: Field ID Dot Mark Name id dot mark Type Integer Integer Integer Description Event type ID. The location of the caret. The location of other end of a logical selection. If there is no selection, this will be the same as dot.

2000-2013 Tibbo Technology Inc.

334

AggreGate Documentation

3.15.8.7 HTML Area

An HTML Area is a component that displays text formatted using HTML markup language. Enclosing <html></html> tags are not required. This is what an HTML area looks like:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
TEXT (Default Property
586 )

Default text contained in the HTML area. Property name: text Property type: String

EDITABLE
This flag indicates that text in the text field can be changed. The primary difference between non-editable and nonenabled 586 components is that text in a non-editable component is not grayed out and may be selected using the mouse.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.8 Button
A regular button. This is what a button looks like:

Example: see Opening a New Widget upon Button Click upon button click, e.g. open another widget.

608

example to learn how to execute an action

892

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 587 , Tooltip 587 , Popup Menu 588
586 ,

Visible

587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Font

587 ,

Cursor

Custom Properties

2000-2013 Tibbo Technology Inc.

AggreGate Server

335

TEXT (Default Property

Text of button label.

586 )

Buttons support rich multi-line HTML texts with formatting. To enable HTML start value Text property with <html> tag: <html>Line <b>1</b><br>Line <b>2</b> Property name: text Property type: String

ALIGNMENT
Horizontal alignment of text within button display area. Possible values: Description Left Center Right Value 2 0 4

Property name: horizontalAlignment Property type: Integer

VERTICAL ALIGNMENT
Vertical alignment of text within button display area. Possible values: Description Top Center Bottom Value 1 0 3

Property name: verticalAlignment Property type: Integer

MARGINS
Space between the border and the label at each of its edges. Margins value has the following fields: Field Top Left Bottom Right Name top left bottom right Type Integer Integer Integer Integer

Property name: margins Property type: DataTable

OPERATIONS
List of widget actions caused by button activation. This list may contain zero or more of the following operations: Submit. This action triggers submit Reset. This action triggers reset
378 378

event of a root panel.

event of a root panel.

2000-2013 Tibbo Technology Inc.

336

AggreGate Documentation

Close. Stops widget execution and closes its window. Property name: operations Property type: Data Table

ICON
Image shown on the button. If NULL, no image will be shown. Property name: icon Property type: Data Block

ICON TEXT GAP

Defines the space between the text and the icon. Property name: iconTextGap Property type: Integer

PRESSED ICON
Image shown on the button when the button is pressed. If NULL, the default image will be shown. Property name: pressedIcon Property type: Data Block

DISABLED ICON
Image shown on the button when the button is disabled. If NULL, the Disabled Icon will be auto-generated from normal Icon. Property name: disabledIcon Property type: Data Block

ROLLOVER ICON
Image shown on the button when a mouse hovered over the button. If NULL, the default image will be shown. Property name: rolloverIcon Property type: Data Block

FOCUS PAINTED
Flag that controls drawing of a dotted-stroke rectangle inside the button when it has focus. This option should be disabled to make icon-only buttons look better.

Property name: focusPainted Property type: Boolean

CONTENT AREA FILLED

Flag that controls filling of button content area. This option should be disabled to make icon-only buttons look better.

Property name: contentAreaFilled Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

AggreGate Server

337

Custom Events
CLICK
This event fires when a user clicks the button. Event name: click

3.15.8.9 Toggle Button

An two-state button. Toggle buttons may be used within Button Groups which only one button at a time can be selected. This is what a toggle button looks like:
375

to create a group of buttons in

If a toggle button is a member of a Button Group, it can be released only by pressing another button in the same group.

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 587 , Tooltip 587 , Popup Menu 588
586 ,

Visible

587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Font

587 ,

Cursor

Custom Properties
TEXT (Default Property
Text of button label. Property name: text Property type: String
586 )

SELECTED
Flag indicating that toggle button is selected (pressed). Property name: selected Property type: Boolean

ALIGNMENT
Horizontal alignment of text within button display area. Possible values: Description Left Center Right Value 2 0 4

Property name: horizontalAlignment Property type: Integer

VERTICAL ALIGNMENT

2000-2013 Tibbo Technology Inc.

338

AggreGate Documentation

Vertical alignment of text within button display area. Possible values: Description Top Center Bottom Value 1 0 3

Property name: verticalAlignment Property type: Integer

MARGINS
Space between the border and the label at each of its edges. Margins value has the following fields: Field Top Left Bottom Right Name top left bottom right Type Integer Integer Integer Integer

Property name: margins Property type: DataTable

BUTTON GROUP
Button group
375

to which the button belongs.

Property name: buttonGroupID Property type: String

VALUE
Value associated with the toggle button. Property name: value Property type: String

ICON
Image shown on the button. If NULL, no image will be shown. Property name: icon Property type: Data Block

ICON TEXT GAP

Defines the space between the text and the icon. Property name: iconTextGap Property type: Integer

PRESSED ICON
Image shown on the button when the button is pressed. If NULL, the default image will be shown. Property name: pressedIcon Property type: Data Block

DISABLED ICON
Image shown on the button when the button is disabled. If NULL, the Disabled Icon will be auto-generated from normal

2000-2013 Tibbo Technology Inc.

AggreGate Server
Icon. Property name: disabledIcon Property type: Data Block

339

SELECTED ICON
Image shown on the button when the button is selected. If NULL, the default image will be shown. Property name: selectedIcon Property type: Data Block

ROLLOVER ICON
Image shown on the button when a mouse hovered over the button. If NULL, the default image will be shown. Property name: rolloverIcon Property type: Data Block

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.10 Radio Button

An item that can be selected or deselected, and which displays its state to the user. Radio buttons are used within Button Groups 375 to create a group of buttons in which only one button at a time can be selected. This is what a label looks like:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
TEXT (Default Property
586 )

Text of radio button label. Property name: text Property type: String

BUTTON GROUP
Button group
375

to which the button belongs.

Property name: buttonGroupID Property type: String

VALUE
Value associated with the radio button. Property name: value Property type: String

2000-2013 Tibbo Technology Inc.

340

AggreGate Documentation

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.11 Check Box

An item can be selected or deselected, and its state is displayed to the user. This is what a check box looks:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
TEXT (Default Property
Text of check box label. Property name: text Property type: String
586 )

SELECTED
Flag indicating that check box is selected (checked). Property name: selected Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.12 Combo Box

A component that combines an editable field and a drop-down list. The user can select a value from the drop-down list. If you make the combo box editable, then the combo box includes an editable field into which the user can type a value. This is what a combo box looks like:

The Type 586 of Selected Item 341 property and the type of data in the Value column of the Selection Values 341 tabular property is dynamic. It cannot be manually changed from the GUI Builder, but it is changed by the binding 604 whose target points to the Selection Values 341 property of Combo Box. This binding rewrites the Selection Values table. The binding is automatically created when dragging a field that has selection values to a combo box 845 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

341

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
MAXIMUM DISPLAYED ROW COUNT
Sets the maximum number of rows the Combo Box displays. If the number of items greater than count, the combo box uses a scrollbar. Property name: maximumRowCount Property type: Integer

SELECTION VALUES
List of items available in the combo box. Property name: options Property type: Data Table It is possible to fill a Combo Box with selection values 856 of a certain Data Table field using a binding example, binding that will fill a Combo Box with the countries available in the Country field of User Information 760 variable defined in the User context of user admin will look as follows: Target: form/comboBox1:options Expression: {users.admin:childInfo$country#options} This binding is created automatically when dragging a variable field to a Combo Box in GUI Builder details here 845 .
827 . 604 .

For

Check

SELECTED ITEM (Default Property

Item selected by default. Property name: selectedItem Property type: dynamic

586 )

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.13 Date/Time Picker

A component that is used to choose a date, using a drop-down popup. It combines an editable field and a popup. Here is what a Date Time Picker looks like:

2000-2013 Tibbo Technology Inc.

342

AggreGate Documentation

The component supports a keyboard-only environment: Key ALT + DOWN ESC LEFT RIGHT UP DOWN HOME END PAGE_UP PAGE_DOWN CTRL + PAGE_UP CTRL+ PAGE_DOWN ENTER Action Bring up the popup Hide the popup without changing the selection Previous day of the selected day Next day of the selected day Same day of the last week Same day of the next week First day of this month Last day of this month Same day of the last month Same day of the next month Same day of the last year Same day of the next year Select the highlighted date and hide popup

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
DATE (Default Property
Picked date. Property name: date Property type: Date
586 )

EDITABLE
Determines if the text field is editable. When it is set to false, the date can only be chosen from a popup but not entered by a keyboard. Property name: editable Property type: Boolean

2000-2013 Tibbo Technology Inc.

AggreGate Server

343

FORMAT
Date/time format 1321 for a value presented in the field. Property name: format Property type: String

MINIMUM DATE
Minimum allowed date. Property name: minDate Property type: Date

MAXIMUM DATE
Maximum allowed date. Property name: maxDate Property type: Date

TIME DISPLAYED
Determines if a time edit field is displayed in the date chooser popup. Enabling it gives the ability to specify the time as well as the date. Property name: timeDisplayed Property type: Boolean

TIME FORMAT
Defines the format of time
1321

displayed in the popup.

Property name: timeFormat Property type: String

SHOW TODAY BUTTON

Controls the Today button visibility. Property name: showTodayButton Property type: Boolean

SHOW NONE BUTTON

Controls the None button visibility. None button allows to select NULL date value. Property name: showNoneButton Property type: Boolean

SHOW OK BUTTON
Controls the OK button visibility. Property name: showOKButton Property type: Boolean

SHOW WEEK NUMBERS

Determines whether week numbers are visible in the picker panel. Property name: editable Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

344
597

AggreGate Documentation
597 ,

, Focus Gained

Focus Lost

597

3.15.8.14 Data Table Editor

Data Table Editor component is designed to view and edit tabular data (Data Tables More information on what this component looks like and behaves may be found here This is what a Data Table Editor looks like:
854 ). 801 .

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Border

587

Custom Properties
TOOLBAR
Controls whether or not to show the toolbar of the Data Table Editor. Property name: toolbar Property type: Boolean

FIXED FORMAT
Defines whether the Data Table Editor should accept only tables of pre-defined format. If this option is enabled, it's possible to edit the Format property (see below) and, after defining table format, fill the table with pre-defined data by editing Data Table property (also described below). At the moment when this flag is enabled, data in the Data Table property will be converted to match current value of Format. Property name: fixedFormat Property type: Boolean

FORMAT
Allows to specify a fixed format of table to be viewed/edited in the Data Table Editor. See description of format options and individual field options in Data Table format 855 section. At the moment when the Format is changed, data in the Data Table property will be converted to match the new format. Property name: format Property type: Data Table

DATA TABLE (Default Property

586 )

Default data table shown and edited by this component. When this option's value is changed to a new Data Table, the system will convert this table to match the Format property (this happens only if Fixed Format flag is set).

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: dataTable Property type: Data Table

345

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.15 Event Log

Event Log component is designed to view and manage AggreGate events
880 . 791 .

More information on what this component looks like and behaves may be found here This is what an Event Log looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Visible

587 ,

Border

587

Custom Properties
MODE
The event log component can work in two principal modes: Event List. In this mode, it shows only events specified by Events property. Primary visible columns are defined by Event Log component properties (see below). No additional fields are shown, and no filtering/highlighting is performed. Event Filter. In this mode Event Log activates a server-side event filter 206 specified by Event Filter setting and uses this filter to select and highlight events. Column model is also built according to the filter configuration. Property name: mode Property type: Integer

EVENTS
This tabular setting defines what events should be shown. There are two columns:

2000-2013 Tibbo Technology Inc.

346

AggreGate Documentation
865

Context Mask. Only events occurred in contexts matching this mask Event. Name of the event. Property name: eventList Property type: Data Table

are shown.

EVENT FILTER
Context path of the event filter
206

to use.

If this setting is NULL, Event Log component will allow to select a filter from a drop-down list. Note that different filters may be selected for Current Events and Event History sections. Property name: filter Property type: String

SECTIONS
Defines what sections to show: Current Events, Event History, or Both Sections. Property name: sections Property type: Integer

PRELOAD EVENT HISTORY

Whether to load event history on widget startup. Property name: preloadHistory Property type: Boolean

SHOW CONTEXT NAMES

Flag defining the visibility of Context column. Property name: showContexts Property type: Boolean

SHOW EVENT NAMES

Flag defining the visibility of Event Name column. Property name: showNames Property type: Boolean

SHOW EVENT LEVELS

Flag defining the visibility of Level column. Property name: showLevels Property type: Boolean

SHOW EVENT DATA

Flag defining the visibility of Data column. Property name: showData Property type: Boolean

SHOW EVENT ACKNOWLEDGEMENTS

Flag defining the visibility of Acknowledgements column. Property name: showAcknowledgements Property type: Boolean

SHOW EVENT ENRICHMENTS

2000-2013 Tibbo Technology Inc.

AggreGate Server
Flag defining the visibility of Enrichments column. Property name: showEnrichments Property type: Boolean

347

FILTER PARAMETERS
Parameters table to use for a parameterized filter 213 . This property is normally written during run-time by a binding that reads filter's parameters table using getParameters() 692 function of an Event Filter context and fills this table onthe-fly (e.g. by set() expression language function 920 ). Property name: filterParameters Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.16 Slider
Lets the user graphically select a value by sliding a knob within a bounded interval. The slider can show both major tick marks and minor tick marks between them. The number of values between tick marks is controlled by Major Tick Spacing and Minor Tick Spacing properties. This is what a slider looks like:

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
VALUE (Default Property
Default value of a slider. Property name: value Property type: Integer
586 )

ORIENTATION
Orientation of slider: Horizontal or Vertical . Property name: orientation Property type: Integer

MINIMUM
Minimum value of a slider. Property name: minimum Property type: Integer

MAXIMUM

2000-2013 Tibbo Technology Inc.

348

AggreGate Documentation

Maximum value of a slider. Property name: maximum Property type: Integer

MINOR TICK SPACING

This is the distance, measured in values, between each minor tick mark. If you have a slider with a range from 0 to 50 and the minor tick spacing is set to 10, you will get minor ticks next to 0, 10, 20, 30, 40, and 50. Property name: minorTickSpacing Property type: Integer

MAJOR TICK SPACING

This is the distance, measured in values, between each major tick mark. If you have a slider with a range from 0 to 50 and the major tick spacing is set to 10, you will get major ticks next to 0, 10, 20, 30, 40, and 50. Property name: majorTickSpacing Property type: Integer

PAINT TRACK
Determines whether the track is painted on the slider. Property name: paintTrack Property type: Boolean

PAINT TICKS
Determines whether tick marks are painted on the slider. Property name: paintTicks Property type: Boolean

PAINT LABELS
Determines whether labels are painted on the slider. Property name: paintLabels Property type: Boolean

CUSTOM LABELS
Table that contains custom labels for the slider. Each label is characterized by slider value at that it is painted and label description. Property name: customLabels Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.17 Spinner
A single line input field that lets the user select a number or value from an ordered sequence. Spinners provide two tiny arrow buttons for stepping through the elements of the sequence. The keyboard up/down arrow keys also cycle through the elements. The user may also type a (legal) value directly into the spinner. This is what a spinner looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

349

Common Properties
Width 586 , Height 586 , Bindings 586 , Enabled 586 , Visible 587 , Cursor 587 , Tooltip 587 , Popup Menu 588
587 ,

Foreground

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Font

Custom Properties
VALUE (Default Property
Default value of a spinner. Property name: value Property type: Integer
586 )

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.18 Progress Bar

A component that, by default, displays an integer value within a bounded interval. A progress bar typically communicates the progress of some work by displaying its percentage of completion. This is what a progress bar looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

587 ,

Popup Menu

588

Custom Properties
VALUE (Default Property
586 )

Default value for the progress bar. Property name: value Property type: Integer

ORIENTATION
Orientation of the progress bar: Horizontal or Vertical . Property name: orientation Property type: Integer

MINIMUM
Minimum value for the progress bar. Property name: minimum

2000-2013 Tibbo Technology Inc.

350

AggreGate Documentation

Property type: Integer

MAXIMUM
Maximum value for the progress bar. Property name: maximum Property type: Integer

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.19 Image
This component displays an image. This is what an image component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

587 ,

Popup Menu

588

Custom Properties
ALIGNMENT
Horizontal alignment of text within label display area. Possible values: Description Left Center Right Value 2 0 4

Property name: horizontalAlignment Property type: Integer

VERTICAL ALIGNMENT
Vertical alignment of text within label display area. Possible values: Description Top Center Value 1 0

2000-2013 Tibbo Technology Inc.

AggreGate Server

351

Bottom

Property name: verticalAlignment Property type: Integer

IMAGE TABLE
This is a tabular property with two columns: Image ID and Image Data . See Image Expression information. Field Image ID Image Data Type String Data Block Description Unique ID of the image in this table. Image data.
351

for more

Property name: imageTable Property type: Data Table Example: To show the photo of user
108

admin in the image component, create the following binding

604 :

Target: form/image1:imageTable$imageData[0] Expression: {users.admin:photo$photo}

IMAGE EXPRESSION
When image expression
350

is set to a non-empty value, it is evaluated:

351

If expression evaluates to a String, image with ID matching this string is selected from Image Table by this component.

and displayed

If it evaluates to an Image, it is immediately displayed by this component. See variable definition properties 929 and context properties 928 in References article for more information about how an expression may resolve to an image. Property name: expression Property type: String Since image expression is not a part of widget binding 604 , it will not be recalculated when properties and components referred by it are changed. It will be recalculated in the following cases only: Upon widget startup When the Image Expression property itself is changed by a widget binding Thus, if you want the image contents to be changed upon certain event, do the following: Create a widget binding those target
605

points to the Image Expression, e.g.: form/image1:

expression
Make binding expression 606 what constructs another expression (Image Expression). The latter will be used to find an Image Table entry to display. For example, to select an image according to the value selected in the Combo Box, use the following binding expression: "'" + {form/comboBox1:selectedItem} + "'". This binding expression will construct Image Expression strings, such as 'image1'. To make an animated image, add two pictures to the image table and create the following periodic binding Target: form/image1:expression Expression: {form/image1:expression}=="'image1'"?"'image2'":"'image1'" This binding will switch the image every time it's executed.
604 :

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

352

AggreGate Documentation

3.15.8.20 Vector Drawing

This component displays a Scalable Vector Graphics (SVG) drawing. This is what a vector drawing component can look like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

Custom Properties
SVG FILE (Default Property
SVG file to display. Property name: drawing Property type: Data Block
586 )

ENABLE INTERACTIONS
When interactions are enabled it is possible to manipulate vector drawing in the widget window using the following keyboard/mouse shortcuts: Shortcut Meaning

2000-2013 Tibbo Technology Inc.

AggreGate Server

353

Ctrl key + Mouse button 1

Magnify (zoom region)

Shift key + Mouse button Zoom 2 Shift key + Mouse button Pan 1 Ctrl key + Mouse button 2 Ctrl key + Shift key + Mouse button 2
QUADRANT ROTATION
Rotates the drawing to fixed angles: 0, 90, 180, 270. The value is the number of 90 arcs to rotate by. If Preserve Aspect Ratio is enabled and the drawing is in Absolute Layout 322 rotating to 90 or 270 flips component's bounding box width/height. Property name: quadrantRotation Property type: Integer When quadrant rotation differs from 0 the Rotation property is disabled and ignored. Rotate Reset transformations

FLIP HORIZONTAL
Flips the drawing around horizontal axis. Property name: flipHorizontal Property type: Boolean

FLIP VERTICAL
Flips the drawing around vertical axis. Property name: flipVertical Property type: Boolean

SCALE
Scaling index. Value of 1.0 is used to disable scaling. If scaled and rotated drawing doesn't fit the component's box, it will be cropped.

Property name: scale Property type: Float

ROTATION
Scaling angle, in degrees. If scaled and rotated drawing doesn't fit the component's box, it will be cropped.

Property name: rotation Property type: Float

PRESERVE ASPECT RATIO

Enables/disables preserving the drawing's aspect ratio. If preserving is disabled, the drawing stretches to occupy the whole component's space. When preserving is enabled and the drawing is in Absolute Layout 322 , component's borders resize proportionally.

2000-2013 Tibbo Technology Inc.

354

AggreGate Documentation

Property name: preserveAspectRatio Property type: Boolean When preserving aspect ratio is disabled, Horizontal/Vertical Alignment properties are also disabled.

Ignoring aspect ratio is useful when you need non-proportional scaling, for example when constructing pipelines consisting of different pipe segments.

HORIZONTAL ALIGNMENT
Defines the drawing horizontal alignment when the component's area is wider then the drawing: Left, Center, Right. Property name: horizontalAlignment Property type: String

VERTICAL ALIGNMENT
Defines the drawing vertical alignment when the component's area is higher then the drawing: Top, Center, Bottom. Property name: verticalAlignment Property type: String

MAXIMIZE
Enables automatic magnification of the drawing so that its margins (i.e. empty space around the image) are discarded. When Maximize is checked, X/Y Margin Percent properties are enabled. Setting small X/Y margins can be used to prevent edges clipping when the drawing size is automatically detected. Property name: maximize Property type: Boolean

X MARGIN PERCENT
X margin as a percentage of drawing width. Enabled when the Stretch To Fit is checked. Property name: xMarginPercent Property type: Float

Y MARGIN PERCENT
Y margin as a percentage of drawing height. Enabled when the Stretch To Fit is checked. Property name: yMarginPercent Property type: Float

CUSTOM SVG PROPERTIES

SVG images included into some AggreGate distribution bundles are enhanced to support custom properties. These properties are defined as special extensions of SVG files. However, Vector Drawing component decodes these properties from SVG files and exposes them as "normal" component's properties, allow to edit them inside GUI Builder 827 , manipulate them by widget bindings 604 , and more. The custom properties are visible in a separate SVG Properties group. The typical custom SVG properties are: Fill color (e.g. element colors) Stroke width and color (e.g. outline strokes) Rotation angle (e.g. gauge arrows) Animation trigger (e.g. fan start/stop switches) Element positions (e.g. tanks levels, damper positions) And many more (pushbutton positions, etc.)

2000-2013 Tibbo Technology Inc.

AggreGate Server

355

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.20.1 Creating Dynamic Vector Images

AggreGate platform provides an elegant way to allow static SVG images became alive and interactive. You can add custom parameters to an image. When SVG image with custom parameters is loaded into a Vector Drawing 352 component, parameters are shown as component properties in a special tab of the GUI Builder 827 's Properties Editor 835 . Modifying them can dynamically alter various drawing's aspects: color, lines thickness, rotation angle, tank levels, turn animation on/off etc. Custom parameters is declared by special tags in SVG document. They define rules of changing SVG document elements when a certain parameter gets a new value. The vector drawing is dynamically updated on every SVG document change.

XML namespace
All custom tags use a separate namespace: agg. So it must be declared in SVG document header to keep the document well formed:

<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xl

XML tags
The structure of custom parameters declaration is the following: There must be a single <agg:params> root node holding all other declarations. The root <agg:params> element can hold multiple <agg:param> elements. Each <agg:param> element can hold multiple <agg:state> elements with <agg:param> elements.

AGG:PARAMS
This is simply a root container for all custom declarations. Only a single <agg:params> tag must present in a document.

AGG:PARAM
It has attributes that: hold information about a component property, define rules for applying a property value to SVG document elements. When the tag is located in <agg:params> root node it is treated as a component property: both the component property information and the rule is used. When the tag is located in <agg:state> node then only the rule data is used and no component property is created (see AGG:STATES 356 ). Attributes used to define component property: Attribute: name description type Type: String String String Description: Component property name. Component property description in properties editor. Text code for property type. The following types are supported: I (Integer), F (Float), S (String), C (Color), state, level. Minimum limit for property value when used with number types or lower limit for parameter value when used with level type. Maximum limit for property value when used with number types or upper limit for parameter value when used with level type.

min max

Float Float

Level type implies that component property is an Integer number limited by a [0..100] range. Every property value within this range is proportionally translated to [min..max] range when applying to a document. min and max

2000-2013 Tibbo Technology Inc.

356

AggreGate Documentation

numbers are defined by appropriate parameter attributes. Note, that min value can be greater then max value. State type is for applying fixed modifications to a document (see AGG:STATES Attributes that define SVG modification rules: Attribute: ids classes attributes cssAttributes pattern Type: String String String String String Description: Comma-separated SVG document elements identifiers list. Elements with given identifiers is affected by parameter changes. Comma-separated CSS classes list. Elements with given CSS classes is affected by parameter changes. Comma-separated attributes list. Document element attributes that values are overwritten by a new value on parameter change. Comma-separated CSS attributes list. CSS attributes that values are overwritten by a new value on parameter change. A string pattern containing "{0}". It is used to transform property value to a document string by replacing the {0} token with the value. This flag controls SVG drawing repaint policy on parameter changes. When set to false the drawing repaints partially, based on changed regions detection (fast). When set to true the drawing repaints completely on each parameter change (slow). In certain cases the SVG drawing engine can't properly handle dynamic document changes (e.g. changing clipping masks) so the drawing must be repainted completely. Force repaint slows down SVG dynamic performance. The default value is false. animation * value * "play/ stop" String Plays or stops animation for elements with given identifiers and classes. Sets the value for attribute with given identifiers and classes.
356 ).

forceRepaint

Boolean

Animation and value attributes used only when <agg:param> defines a state. Value holds a constant string value that applies to document when an appropriate state of the component parameter is set. Animation begins/stops playing an animation with given id when the appropriate state is set.

AGG:STATE
States are used to apply some predefined modifications (states) to a document. For example it can be used to turn on/ off a fan rotation. State parameter is non scalar and displayed in Properties Editor 835 as a combo box with predefined options. It is used to set multiple values to multiple DOM elements when the state is applied. The idea of defining a state is simple: create an <agg:param> with "state" type and enumerate states within it by <agg:state>. Each <agg: state> tag can have multiple <agg:param/> tags that define how the DOM should change when the state is applied. It has parameters: Attribute: name description Type: String String Description: State name. State description in properties editor.

Examples
STYLE
You can control styling of SVG document elements by modifying their CSS attributes. To change the color for different drawing parts the following parameter declaration can be used:

<agg:params> <agg:param name="color" description="Color" type="C" cssAttributes="fill" classes="mainColor"/> </agg:params>

When the drawing is loaded in GUI Builder
827

it will have the Color component property. Every time the Color gets a

2000-2013 Tibbo Technology Inc.

AggreGate Server

357

new value the drawing engine will find all document elements where class is mainColor and set a new color value to their fill CSS attribute. This will change the drawing parts color. To make SVG more flexible, faster to download and easier to maintain you can use CSS (Cascading Style Sheets) right in the same file. Read Styling with CSS section in W3C SVG Specificaton.

ROTATION
Suppose that a SVG document have an element representing a knob with ID knob. Applying a rotation transformation at point (61.542, 61.792) forces the knob to rotate. To create a parameter for rotation to a certain angle you can write the following:

<agg:params> <agg:parameter name="angle" description="Angle" type="I" ids="knob" attributes="translation" pattern="rotate({0} 61.542 61.792)"/> </agg:params>
This declares a single SVG parameter Angle with Integer type that will be shown as component property. If the parameter is set to 45 then the translation attribute of the knob DOM element will be set to rotate(45 61.542 61.792) and the knob will turn by 45 degrees.

LEVEL
Let the fluid level in SVG image document of a reactor depends on y attribute value of a <clipPath id="clipPathId"...> tag: when y is 66.9 the reactor is full, when y is 660 the reactor is empty. So, to control the level we must create a parameter with level type:

<agg:params> <agg:param name="level" description="Level" type="level" attributes="y" min="660" max="66" ids="clipPathId" forceRepaint="true"/> </agg:params>
This parameter creates a component property with Integer type having 0 to 100 limits. Attributes min="660" and max="66" define the range of y attribute. Every time a component property gets a new value it is proportionally translated from [0, 100] range to [600, 66] range and the y attribute of the clipPathId element is set to this translated value. If the Level property of Vector Drawing is set to 0 then the y will be set to 660. If the Level property is set to 50 then the y will be set to 297. If the Level property is set to 100 then the y will be set to 66. The forceRepaint flag is used to completely repaint the drawing on every Level change. Because dynamic clip mask modifications are not supported and you might see unexpected results without repainting the whole image.

STATES
To manage drawing states like "the box is opened" or "the switch is turned on", you can use a state parameter. To create a dynamic left-right flip switch for example, you can create an SVG document with two groups of elements. One for the left switch state and another for the right state. Now to control a flip switch state you must control groups visibility. The parameter for switching the state can be defined like this:

<agg:params> <agg:param name="state" description="State" type="state"> <agg:state name="left" description="Left"> <agg:param attributes="visibility" ids="switch-left" value="visible"/ > <agg:param attributes="visibility" ids="switch-right" value="hidden"/ > </agg:state> <agg:state name="right" description="Right"> <agg:param attributes="visibility" ids="switch-left" value="hidden"/> <agg:param attributes="visibility" ids="switch-right" value="visible"/> </agg:state>

2000-2013 Tibbo Technology Inc.

358

AggreGate Documentation </agg:param>

</agg:params>
This defines a State component property with two values: Left and Right. When the State is set to Left then the visibility attribute of the switch-left DOM element gets visible value, and the visibility attribute of the switch-right DOM element gets "hidden" value. When the State is set to Right the switch-left becomes hidden and the switch-right becomes visible.

ANIMATION
Suppose you have a fan drawing and it animated with:

<animateTransform id="rotate" attributeName="transform" attributeType="XML" type="rotate" from="0 45 45" to="360 45 45" begin="indefinite" dur="10s" repeatCount="indefinite"/>
To control animation you can define the following state parameter:

<agg:params> <agg:param name="state" description="State" type="state"> <agg:state name="on" description="On"> <agg:param animation="play" ids="rotate"/> </agg:state> <agg:state name="off" description="Off"> <agg:param animation="stop" ids="rotate"/> </agg:state> </agg:param> </agg:params>
This defines a State component property with two values: On and Off. When it gets the On value then the rotate animation is started. When the value is set to Off the rotate animation is stoped. You can see more examples of using custom SVG parameters in the Symbol Library
1165 .

3.15.8.21 Video Player

Video Player component is used to display MJPEG video stream or JPEG still images streamed by a network camera or video server. This is what a video player looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

359

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

587 ,

Popup Menu

588

Custom Properties
URL (Default Property
586 )

The URL of a video stream or JPEG image to show. Property name: url Property type: String

VIDEO MODE
Format of the video: MJPEG stream or JPEG still images. Property name: videoMode Property type: Integer

REFRESH RATE
Period of image refresh (if using JPEG Stills Video Mode). Property name: refresh Property type: Long

SCALE VIDEO
If enabled, video frame will be downscaled to fit component size. If disabled, video frame will be truncated if it's larger than the component size. Property name: scaleVideo Property type: Boolean

SHOW STATUS
Defines whether or not to show frame rate and some other details on the video. Property name: showStatus Property type: Boolean

USERNAME
Username to use for authenticating when accessing a password-protected URL. Property name: username Property type: String

PASSWORD
Password to use for authenticating when accessing a password-protected URL. Property name: password Property type: String

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

360

AggreGate Documentation

3.15.8.22 Meter
This component displays a meter that is best used for indicating temperature, pressure and similar values. The meter has three subranges, shown in different colors. This is what a gauge component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

Custom Properties
VALUE (Default Property
586 )

Data value indicated by meter. Property name: value Property type: Float

PLOT
A configuration of meter plot, i.e. "graphical part" of a meter. Fields of meter plot: Field Lower Bound Upper Bound Axis Location Background Alpha Background Paint Bulb Radius Column Radius Follow Data In Subranges Gap Insets Mercury Paint Type Float Float Integer Float Data Table Integer Integer Boolean Integer Data Table Data Table Description Lower bound for the meter. Upper bound for the meter. The axis can be displayed at the left or right of the meter, or not displayed at all. The alpha transparency value used when coloring the plots background. Paint
590

used to draw the background of the plot area.

Radius of the meter bulb. Radius of the main column of the meter. Flag that controls whether or not the axis range automatically changes to show only the subrange within which the current data value falls. Gap between the outlines used to represent the meter. The amount of space to leave around the outside of the plot. Default mercury Paint
590

used when value is outside of all subranges.

2000-2013 Tibbo Technology Inc.

AggreGate Server

361

Outline Paint Outline Stroke Outline Visible Padding Meter Paint Meter Stroke Units Use Subrange Paint Value Font Value Location

Data Table Data Table Boolean Data Table Data Table Data Table Integer Boolean Data Table Integer

Paint

590

used to draw an outline around the plot area. used to draw an outline around the plot area.

Stroke

593

Flag that controls whether or not the outline is drawn. Padding (top, left, bottom, right) around the outside of the meter. Paint
590

used to draw the outline of the meter. used to draw the outline of the meter.

Stroke

593

Unit type. Can be set to Fahrenheit, Celsius or Kelvin degrees is meter is used to represent the temperature, or to No units displayed otherwise. Flag that controls whether or not the sub-range colors are used for the mercury in the meter. Font
590

used to display the value label, if it is visible.

Location at which the current value will be displayed (None, Right, Left, or Bulb). Note that the default Value Paint color is white, so if you change the location you should also change the color so that the label remains visible. Paint
590

Value Paint

Data Table

used to display the value label, if it is visible.

Property name: plot Property type: Data Table

AXIS
Configuration of meter axis. Fields of meter axis: Field Label Label Angle Label Font Label Insets Label Paint Tick Label Font Tick Label Insets Tick Label Paint Tick Labels Visible Type String Float Data Table Data Table Data Table Data Table Data Table Data Table Boolean Description The axis label typically describes what an axis is measuring. The angle of rotation for the axis label. The font
590

for the axis label.

The space to leave around the outside of the axis label. The paint
590

for the axis label.

The font for the tick labels. The space to leave around the outside of the tick labels. The paint
590

for the tick labels.

A flag controlling the visibility of tick labels. The amount by which the tick marks extend into the plot area The amount by which the tick marks extend outside the plot The paint
590

Tick Mark Inside Float Length Tick Mark Outside Length Tick Mark Paint Tick Mark Stroke Tick Marks Visible Visible Float Data Table Data Table Boolean Boolean

used to draw the tick marks. used to draw the tick marks.

The stroke

593

A flag controlling the visibility of tick marks. A flag that controls whether or not the axis is visible.

Property name: axis Property type: Data Table

2000-2013 Tibbo Technology Inc.

362

AggreGate Documentation

SUBRANGES
Table of meter subranges used to indicate normal, warning and critical values. Fields of a subrange: Field Subrange Lower Bound Upper Bound Display Low Type String Float Float Float Description Subrange name, read-only. Lower bound for the subrange. Upper bound for the subrange. Lower display bound. The display bounds are only used if the meter axis range is automatically adjusted to display the current sub-range (i.e. Follow Data In Subranges flag of Meter Plot is enabled). Upper display bound. Mercury paint
590

Display High Paint

Float Data Table

used to display values within the subrange.

Property name: subranges Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.23 Compass
This component displays a compass with one or more needles. This is what a compass component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

Custom Properties
DATA VALUES (Default Property
586 ) 586 .

A list of data values that will be indicated by the compass. This is an indexed property Property name: datasets Property type: Data Table

PLOT
A configuration of compass plot.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Properties of meter plot: Field Background Alpha Background Paint Draw Background Insets Revolution Distance Rose Center Paint Rose Highlight Paint Rose Paint Type Float Data Table Boolean Data Table Float Data Table Data Table Data Table Description The alpha transparency value used when coloring the plots background. The paint
590

363

used to draw the background of the plot area.

Flag that determines whether or not the background is drawn. The amount of space to leave around the outside of the plot. The length of a full revolution for the compass. The default value is 360.0, because the compass displays degree values. The paint The paint The paint
590

used to fill the interior of the compass dial. used to draw the edges of the outer border of the compass dial. used to fill the outer border of the compass dial.

590

590

Property name: plot Property type: Data Table

NEEDLES
A list of compass needles. Each needle indicates one Data Value Properties of a needle: Field Needle Type Outline Paint Outline Stroke Paint Needle types: Type Integer Data Table Data Table Data Table Description Type of the needle. The paint
590 362

with matching index.

used to draw needle outline. used to draw needle outline.

The stroke The paint

593

590

used to fill the needle.

2000-2013 Tibbo Technology Inc.

364

AggreGate Documentation

Property name: needles Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.24 Map
This component displays and dynamically updates geographical map, road map, terrain map, or satellite image. It uses Google Maps as data source. The map may show markers indicating current location of devices providing GPS data, along with their track paths. This is what a map component looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

365

Zooming and Panning

The map can me panned by clicking a certain point and dropping it over another map location. This will move map center accordingly. Zooming into/from current mouse location is enabled by using mouse wheel.

Datum
This map component uses WGS84 datum. Any device that provides location data for AggreGate must be set up to use WGS84 datum in order to be properly displayed on the map.

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Visible

587 ,

Border

587 ,

Tooltip

587 ,

Popup Menu

588

Custom Properties
AUTO-DETECT ZOOM LEVEL
Instructs map renderer to set zoom level automatically so that map center, all markers and paths will be visible without additional panning. Property name: detectZoom Property type: Boolean

ZOOM LEVEL
Zoom Level defines the resolution of the current view. Zoom levels between 0 (the lowest zoom level, in which the entire world can be seen on one map) to 21+ (down to individual buildings) are possible. Each succeeding zoom level doubles the precision in both horizontal and vertical dimensions. Not all zoom levels appear at all locations on the earth. Zoom levels vary depending on location, as data in some parts of the globe is more granular than in other locations. If no data is available for the current location and selected zoom level, the map will display blank image instead. Property name: zoom Property type: Integer

2000-2013 Tibbo Technology Inc.

366

AggreGate Documentation

MAP TYPE
Four map types are supported: Roadmap (default) specifies a standard road map image. Satellite specifies a satellite image. Terrain specifies a physical relief map image, showing terrain and vegetation. Hybrid specifies a hybrid of the satellite and roadmap image, showing a transparent layer of major streets and place names on the satellite image. Property name: mapType Property type: String

TRACKED DEVICES
This setting is a context mask 865 . All Devices be shown on the map as markers. The mask may resolve to: An individual Device All Devices in the system All Devices of a certain user Device group
248 108 113

providing their location data those context paths match this mask will

Property name: deviceMask Property type: String

DISPLAYABLE TRACK LENGTH

A number of Device track waypoints to show on the map. An attempt to show too many waypoints may cause Google Maps API usage rules violation. In this case, an empty map will be displayed. Decrease this settings to avoid the problem.

Device setting history storage 116 must be enabled for Location (location) setting of a Device in order to keep historical track information and display it on the map. Property name: trackLength Property type: Integer

Location Properties
TYPE
This setting allows to specify how the map is centered: Automatic. The map is centered to fit all devices and track waypoints. This option may be combined with Auto-detect Zoom Level 365 to ensure that map displays all available data. Geolocation. Allows to center map using a geocode, i.e. city name, street address, or zip code. Latitute/Longitude . Manual specification of map center coordinates (latitude and longitude). Property name: locationType Property type: Integer

GEOLOCATION
This option is enabled if Location Type Property name: geoLocation Property type: String
366

is Geolocation. It specifies map center's geocode, e.g. Berkeley,CA.

2000-2013 Tibbo Technology Inc.

AggreGate Server

367

LATITUDE
This option is enabled if Location Type Property name: latitude Property type: Float
366

is Latitude/Longitude. It specifies latitude of the fixed map center.

LONGITUDE
This option is enabled if Location Type Property name: longitude Property type: Float
366

is Latitude/Longitude. It specifies longitude of the fixed map center.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.25 Device
This component displays an image of some hardware device and renders some dynamically generated device status messages near or over it. This is what a device component looks like:

Common Properties
Width 586 , Height Menu 588
586

, Bindings

586 ,

Visible

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

587 ,

Popup

Custom Properties
SOURCE
Path of context
863

to get data from. In most cases, this path will point to a Device Context

677 .

Property name: source Property type: String

IMAGE
Device image (both raster and vector images are supported). Property name: image Property type: Data Block

LABELS
Configuration of dynamic labels indicating current device state. Properties of a label:

2000-2013 Tibbo Technology Inc.

368

AggreGate Documentation

Field Expression

Type String

Description Label text expression 911 . This expression will be calculated every Period. Its result will be converted to string and displayed on the label.

Label Expression Resolution Environment Default Context

927

922

Context specified by the Source property of this device component. If Source is not specified, default context 315 of the currently running widget. Widget parameters
317

Default Data Table 927 Default Row 927 Environm ent Variables
930

table.

Standard

931

variables only.

Vertical Alignment Horizontal Alignment Font Foreground Period

Integer Integer Data Table Color Long

Label vertical alignment. Label horizontal alignment. Label font

590 .

Label color. Label text update period, i.e. period of Expression re-evaluation.

Property name: labels Property type: Data Table

STATUS
Numeric value of component status. Status is used to find a proper color for the device image according to the Status Table . If status is not NULL, device image is colored per the corresponding line in the Status Table. If status is NULL, device image is left untouched. Property name: status Property type: Integer

STATUS TABLE
Table containing a color value for every Status used by this device component. Fields of the Status Table: Field Status Color Type Integer Color Description Value of the Status property. Device image color corresponding to the this status.

Property name: statusTable Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

AggreGate Server

369

3.15.8.26 Graph
This component displays and dynamically updates a graph of any kind, e.g. a network topology graph. This is what a graph component looks like:

Opening Nodes
Graph nodes can be right-clicked to open related objects (for example, dashboards of corresponding devices).

Node Color Coding

The color of graph vertices indicates the state of underlying objects. Example: on a network topology graph green node indicates that network device is online and has no problems. Red nodes are offline devices and devices with problems.

Node Labels
Each graph nodes has a label describing an underlying object. Example: on a network topology map node labels show device context descriptions.

Edge Width and Color Coding

Width of graph edges may vary depending on the type of the underlying link. Example: on a network topology map narrower edges match low speed connections (e.g. 100 Mbps links), while wide edges represent high speed links (e.g. Gigabit Ethernet). Edge colors indicates node-to-node link statuses. Example: on a network topology map each edge may be colored differently on its opposite sides. Green edge side indicates that network interface corresponding to this link is online, and red side points to offline interface.

2000-2013 Tibbo Technology Inc.

370

AggreGate Documentation

Zooming and Panning Graph

The graph can me panned by clicking a certain point and dropping it over another map location. This will move graph center accordingly. Panning works only when the graph is in Transforming mode.

If graph is in Picking mode, it's possible to Ctrl-click on a node to center graph on this node.

Zooming into/from current mouse location is enabled by using mouse wheel.

Rotating and Shearing Graph

Shift, left mouse click and drag in the graph window allows you to rotate the graph. Control, left mouse click and drag in the graph window allows you to shear the graph. Rotating and shearing work only when the graph is in Transforming mode.

Picking and Moving Nodes

If a graph is in Picking mode, it nodes can be picked and moved by dragging them with the mouse. Multiple nodes can be selected: By clicking outside of any node and dragging mouse to select a certain graph area that includes several nodes By shift-clicking on several nodes

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Visible

587 ,

Background

587 ,

Border

587 ,

Tooltip

587

Custom Properties
PROVIDER
Selects the graph data provider type. The list of available types may vary in different AggreGate installations. For example, available types may include: Network (Network topology of all types) Level 2 (OSI model layer 2 topology) Level 3 (OSI model layer 3 topology) Property name: provider Property type: String

VERTEX MASK
The mask 865 of contexts to get topology data from. In most cases, each context matching this mask will appear as a separate graph node (vertex). Property name: vertexMask Property type: String

VERTEX MASK
The mask 865 of contexts to get topology data from. In most cases, each context matching this mask will appear as a separate graph node (vertex). Property name: vertexMask

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: String

371

MODE
Graph mode: Transforming or Picking. In transforming mode, the graph can be zoomed, panned, rotated and sheared. In picking mode, graph nodes can be moved individually. It's possible to change graph mode using a binding widget. Property name: mode Property type: Integer
604 ,

for example by adding mode selector Combo Box

340

to a

UPDATE PERIOD
The period of re-reading topology information from the server and refreshing the graph. Property name: updatePeriod Property type: Long

EDGE SHAPE
Defines the visual look of graph edges. Possible choices are: 1. Line 2. Wedge

3. Quad Curve

4. Cubic Curve.

2000-2013 Tibbo Technology Inc.

372

AggreGate Documentation

Property name: edgeShape Property type: Integer

Layout Properties
LAYOUT
Graph layout type. Supported layouts are: 1. Kamada-Kawai 2. Fruchterman-Reingold

3. Circle

4. Meyer's self-organizing

2000-2013 Tibbo Technology Inc.

AggreGate Server

373

Property name: layout Property type: Integer

ATTRACTION
Attraction factor for Fruchterman-Reingold layout. Property name: attraction Property type: Double

REPULSION
Repulsion factor for Fruchterman-Reingold layout. Property name: repulsion Property type: Double

ADJUST FOR GRAVITY

Adjust for gravity flag, used by Kamada-Kawai layout. Property name: adjustForGravity Property type: Boolean

DISCONNECTED DISTANCE MULTIPLIER

Disconnected distance multiplier for Kamada-Kawai layout. Property name: disconnectedDistanceMultiplier Property type: Double

EXCHANGE VERTICES
Exchange vertices flag for Kamada-Kawai layout. Property name: exchangeVertices Property type: Boolean

LENGTH FACTOR
Length factor for Kamada-Kawai layout. Property name: lengthFactor Property type: Double

2000-2013 Tibbo Technology Inc.

374

AggreGate Documentation

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.27 LED Display

This component displays a string or number by emulating a bar or LED indicators. This is what a LED display looks like:

Common Properties
Width 586 , Height Menu 588
586

, Bindings

586 ,

Visible

587 ,

Foreground

587 ,

Background

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

587 ,

Popup

Custom Properties
TEXT (Default Property
586 )

Text displayed by LED component. Note that not all symbols are supported. Unsupported symbols are displayed as question marks. Property name: text Property type: String

ALIGNMENT
Horizontal alignment of text inside the LED display: Center, Left or Right. Property name: horizontalAlignment Property type: Integer

VERTICAL ALIGNMENT
Vertical alignment of text inside the LED display: Center, Top or Bottom. Property name: verticalAlignment Property type: Integer

DOT OFF COLOR

Color of disabled LCD dots. Property name: dotOffColor Property type: Color

DOT WIDTH
Width of a single dot. Property name: dotWidth Property type: Integer

DOT HEIGHT

2000-2013 Tibbo Technology Inc.

AggreGate Server
Height of a single dot. Property name: dotHeight Property type: Integer

375

HORIZONTAL GAP
Horizontal gap between dots. Property name: horizontalGap Property type: Integer

VERTICAL GAP
Vertical gap between dots. Property name: verticalGap Property type: Integer

PADDING
Number of dots that will never lit at the left, right, top and bottom sides of display. Property name: padding Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.8.28 Button Group

Button Group is a special non-renderable component that logically join several Radio Buttons in order to bind them to a single value in the data model (e.g the field of a variable 869 ). A button group is a special type of component -- It's not visually shown in the widget layout. Button Groups are used for logical grouping, rather than visual. To create a visual group of radio buttons, you should still create a Panel 378 or a similar container to hold several radio buttons and set it off from the surrounding components with a border. Click here
845 339

or Toggle Buttons

337

to see how to create bindings

604

for button groups.

Button Group Properties

BINDINGS
This property shows a list of bindings related to the button group. Additional info can be found here Property name: bindings Property type: Data Table
586 .

NAME OF SELECTED COMPONENT

Name of the Radio Button or Toggle Button that is selected (pressed). Property name: selectedButton Property type: String

2000-2013 Tibbo Technology Inc.

376

AggreGate Documentation

3.15.9 Containers
Containers may may hold other components Panel
378 322 .

Here is a list of containers supported by widget engine:

Layered Panel Tabbed Panel Split Panel

381

382

379

Common Properties Of Containers

This chapter describes properties that are supported by most containers. The description for every container includes a list of supported common container properties.

LAYOUT
This property defines the layout type Property name: layout Property type: Integer
318

of the container.

SCROLLING
This property defines when scrolling is enabled in the container's panels. It has the following options: None. Both horizontal and vertical scrolling are disabled. Vertical . Vertical scrolling is enabled, horizontal is disabled. Horizontal. Horizontal scrolling is enabled, vertical is disabled. Both. Both horizontal and vertical scrolling are enabled. Property name: scrolling Property type: Integer

SMART SCROLLBAR POLICY

This property is available only when scrolling 376 is set to Vertical , Horizontal or Both. It defines when scrollbars appear in the container. If this option is enabled, scrollbars appear only when the container contents does not fit its display area and actual scrolling may be required. If disabled, scrollbars are always visible. Property name: scrollingAuto Property type: Boolean

3.15.9.1 Root Panel

Root panel is a special type of Panel
378

container that has several additional properties

586

and events

595 .

Custom Properties
This section describes properties of the root panel
376

of the widget.

IGNORE BINDING ERRORS

If this option is enabled, any binding 604 errors that occur during widget execution are not shown to the user in error dialog. Instead, they are just written to the log file or console (see logging 848 topic for more information). If this option is disabled (this is a default), bindings errors are both logged and shown to the user. Property name: ignoreBindingErrors Property type: Boolean

ALL BINDINGS

2000-2013 Tibbo Technology Inc.

AggreGate Server
This property contains a list of all bindings available in the widget template. See the bindings information about bindings and their parameters. Property name: allBindings Property type: Data Table
604

377

article for more

SCRIPTS
This property contains the table of widget scripts
610 .

There are two columns: Name and Code .

604 .

Name is the script name. It it used to refer to this script from widget bindings

Code contains text of a class implementing WidgetScript interface, i.e. script code. When a new script is added to the scripts table, a new binding used to launch it is automatically added to the All Bindings 376 list. However, initial properties 952 of this binding do not define any script launch conditions. It's necessary to modify these properties to make the script start on widget startup, some event or just periodically. Property name: scripts Property type: Data Table

NORMAL CONCURRENT BINDINGS

Defines the core size of widget's thread pool, i.e. base number of bindings that will be processed simultaneously. Zero value disables parallel bindings processing. Property name: normalConcurrentBindings Property type: Integer

MAXIMUM CONCURRENT BINDINGS

Defines the maximum size of widget's thread pool, i.e. the number of concurrently processed bindings allowed in case of binding queue overflow. Zero value disables parallel bindings processing. Property name: maximumConcurrentBindings Property type: Integer

MAXIMUM UNPROCESSED BINDING QUEUE LENGTH

Defines how many unprocessed binding operations can be queued before widget's thread pool size grows over its core size towards maximum size. Property name: maximumBindingQueueLength Property type: Integer

STARTUP BINDINGS CONCURRENCY

Defines whether startup bindings can be executed in parallel threads. Enabling this option causes startup bindings to be processed in random order.

Property name: startupBindingsConcurrency Property type: Boolean

Touchscreen
Settings in this group are related to touch panel support
616 .

EMBEDDED ONSCREEN KEYBOARD FONT SIZE

Defines what font is used to label native onscreen keyboard's buttons. Property name: embeddedOnscreenKeyboardFontSize

2000-2013 Tibbo Technology Inc.

378

AggreGate Documentation

Property type: Integer

NATIVE ONSCREEN KEYBOARD COMMAND

The path of native onscreen keyboard application's executable file to launch when keyboard input is requested. There are several pre-defined selections (despite any other file can be referred): None (forces use of AggreGate's own embedded onscreen keyboard) Windows Onscreen Keyoboard ( C:\Windows/system32/osk.exe) GNOME Onboard (onboard) KDE Kvkbd (kvkbd) Mac OS Onscreen Keyboard (open -a KeyboardViewerServer) Property name: nativeOnscreenKeyboardCommand Property type: String

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

Custom Events
SUBMIT
This event may be triggered by a button having a Submit action in its actions list Event name: submit
335 .

RESET
This event may be triggered by a button having a Reset action in its actions list Event name: reset
335 .

CLOSE
This event may be triggered by a button having a Close action in its actions list Event name: close
335 .

3.15.9.2 Panel
A panel is a generic container. It provides a simple grid layout 318 with no additional decorations. Panel may be put to the cell of parent container's layout grid to form complex interfaces. This is what an opaque panel with a blue background, holding a single text field
325 ,

looks like:

By default, a panel is non-opaque, i.e. draws no background, so that any components underneath show through. Opaque panels are filled with background color. Borders can be also added to panels.

Common Properties
A Panel supports the following common widget properties:

2000-2013 Tibbo Technology Inc.

AggreGate Server
Width 586 , Height Menu 588
586

379
Popup

, Bindings

586 ,

Visible

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

587 ,

And the following common container properties: Layout

376

, Scrolling

376 ,

Smart Scrollbar Policy

376

Custom Properties
The panel has no custom properties.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.9.3 Tabbed Panel

A Tabbed Panel lets the user switch between a group of components by clicking on a tab with a given title. Every tab contains a separate pane of any layout 318 that may hold other components or containers. This is what a tabbed panel with two empty tabs looks like:

Common Properties
A Tabbed Panel supports the following common widget properties: Width 586 , Height 587 , Popup Menu
586 588

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

And the following common container properties: Scrolling

376

, Smart Scrollbar Policy

376

Custom Properties
ACTIVE TAB
Name of active tab. Property name: activeTab Property type: String

TAB PLACEMENT
Placement of tab headers: Top, Left, Bottom or Right. Property name: tabPlatement Property type: Integer

TAB LAYOUT POLICY

Specifies how to place tabs if they don't fit a single row: Wrap Tabs. Create multiple rows of tabs. Scroll Tabs . Add scroll buttons to the tabbed pane header.

2000-2013 Tibbo Technology Inc.

380

AggreGate Documentation

Property name: tabLayoutPolicy Property type: Integer

Adding New Tabs

New tabs can be added to the tabbed panel by using the Add Tab context menu item of the Resources Tree for the Tabbed Panel.
833

node

Tab Properties
Common properties: Layout
376 ,

Bindings

586

ORDER NUMBER
Order number of the tab. Tabs are shown according to their order numbers in ascending order. Property name: index Property type: Integer

TITLE
Title of the tab. Property name: title Property type: String

ICON
Image shown next to the tab's title. If NULL, no image is displayed. Property name: icon Property type: Data Block

ENABLED
Flag indicating whether tab can be activated. Property name: enabled Property type: Boolean

FOREGROUND
Tab header font color. Property name: foreground Property type: Color

BACKGROUND
Tab background color. Property name: background Property type: Color

TOOLTIP
Text of tab tooltip. Property name: toolTipText Property type: String

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

AggreGate Server

381

3.15.9.4 Split Panel

A Split Panel is used to divide two (and only two) other components or containers that are called frames. These components are displayed either side by side or one on top of the other. Space available for each of these components may be interactively re-distributed by the user. This is what a split panel with horizontal orientation holding two labels
323

looks like:

It's possible to divide space among three or more components by putting split panes inside of other split panes.

Common Properties
A Split Panel supports the following common widget properties: Width 586 , Height 587 , Popup Menu
586 588

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

And the following common container properties: Scrolling

376

, Smart Scrollbar Policy

376

Custom Properties
ORIENTATION
Horizontal or vertical. A split panel with horizontal orientation has a left frame and a right frame, while a vertically oriented split panel has a top frame and a bottom frame. Property name: orientaton Property type: Integer

DIVIDER LOCATION
Divider location in pixels from the left or top side of split panel. Property name: dividerLocation Property type: Integer

DIVIDER SIZE
Divider size in pixels. Property name: dividerSize Property type: Integer

Frame Properties
Common properties: Layout
376 ,

Bindings

586

ORDER NUMBER
Order number of the frame. A frame with lower number is located in the left part (or in the top part -- for a Split Panel with vertical layout) or the Split Panel. Property name: index Property type: Integer

2000-2013 Tibbo Technology Inc.

382

AggreGate Documentation

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.9.5 Layered Panel

A Layered Panel has several panes that are rendered one over another. Each pane has a separate layout 318 . This is what a layered panel with two layers containing a text area
332

and a label

323

looks like:

Common Properties
A Layered Panel supports the following common widget properties: Width 586 , Height Menu 588
586

, Bindings

586 ,

Visible

587 ,

Background

587 ,

Opaque

587 ,

Border

587 ,

Cursor

587 ,

Tooltip

587 ,

Popup

And the following common container properties: Scrolling

376

, Smart Scrollbar Policy

376

Custom Properties
A Layered panel has no custom properties.

Adding New Layers

New layers can be added to the layered panel by using Add Layer context menu item of the Resources Tree for the Layered Panel.
833

node

Layer Properties
Common properties: Layout
376 ,

Bindings

586

DEPTH
Depth of the layer, that is also called z-order. Layers with lower depth are rendered over the layers with higher depth. Property name: depth Property type: Integer

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.9.6 Subwidget
Subwidget component is used to display a widget inside another widget. The appearance of subwidget component is fully configurable, since a subwidget is, indeed, a usual widget that's just inserted into another widget. This is what a subwidget component may look like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

383

The nested widget, represented by a subwidget component, can interact with its host widget: First, a widget that will act as a subwidget is created. Second, some custom properties 588 are added to the root panel "bridge" between a host widget and the subwidget.
376

of this widget. These properties will be used as a

Example: The root panel of "Conveyor" subwidget (pictured above) has boolean Processing property that starts/stop the conveyor belt. Third, the above custom properties are bound example, in the "Conveyor" subwidget to some component properties inside the "nested" widget. For

604

Example: The Processing property of the "Conveyor" subwidget is bound to Operate properties of several Vector Drawing 352 components that constitute the conveyor belt inside the nested widget. Fourth, the host widget is created and a Subwidget component is added to it. The Subwidget component's Reference property is set up to point the "nested" widget. The Processing property of the nested widget will than appear as a regular property of Subwidget component inside the host widget. Fifth, "inherited" properties of a subwidget are bound building the widget-to-subwidget interactions.
604

to some component properties of a host widget. This finalizes

Example: The Processing property of the "Conveyor" subwidget is bound Enabled property of "Main Switch" toggle button inside the host widget. Thus clicking this button to start/stop the whole bottling line will also start/stop the conveyor belt.

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Visible

587 ,

Border

587 ,

Tooltip

587

Custom Properties
REFERENCE
Path of a widget context
774

matching the widget to load and display inside this subwidget component.

Property name: reference Property type: String

SUBWIDGET PROPERTIES
The subwidget component exposes custom properties of referred widget's root panel interaction between the host widget and a the subwidget.
376

as its own properties to allow

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

384

AggreGate Documentation

3.15.10 Charts
Charts are used for graphical representation of data. The following chart types are supported:

CATEGORY CHARTS
Line Chart Area Chart Bar Chart
397

401

404

Interval Bar Chart Statistical Chart Gantt Chart

419 417

415

Mixed Category Chart

422

Combined Domain Category Chart Combined Range Category Chart

425

427

XY CHARTS
XY Line Chart XY Area Chart XY Bar Chart
429

436

440

Interval Chart Error Chart

450

449

Deviation Chart Vector Chart Bubble Chart

455

453

457

Financial Chart Block Chart

463

459

Mixed XY Chart

469

Combined Domain XY Chart Combined Range XY Chart

472

475

OTHER CHARTS
Spider Chart Polar Chart Pie Chart
478

481

485

Ring Chart

486

2000-2013 Tibbo Technology Inc.

AggreGate Server

385

Chart Zooming
The chart component supports zooming via the popup menu or via a mouse drag on the displayed chart.

Chart Context Menu

The popup menu of a chart provides support for: On-the-fly chart property fine-tuning Exporting charts to images files Printing charts Copying chart data to clipboard Different zooming options Viewing chart source data in Data Table Editor
801

Chart Structure
Most chart consist of the following basic parts: Dataset Plot
509 385

build from the server-side data

where the data items are drawn

542

Renderer Axes
490

that performs drawing on the plot (optional, some plots perform data rendering themselves)

of chart-specific types (optional, some charts have no axes)

Numerous other chart elements are supported: Titles Legends Frames Annotations Gridlines Crosshairs Data Item Labels And more

3.15.10.1 Building Chart Dataset

Charts provide several generic ways of fetching tabular data from AggreGate Server context tree to build chart's dataset.
863

and using this data

This section covers chart properties that are related to fetching source data and building chart's dataset.

Data-related Chart Properties

DATA SOURCE TYPE
This basic parameter defines what kind of data should be used to build a chart. There can be four options: Custom Data Event
392 388

. Use custom tabular data to build a chart.

880

. Use data from event

history and new event occurrences to build and dynamically update the chart.
869

Variable 393 . Use data from variable update the chart. Trending
395

changes history and real-time variable changes to build and dynamically

. Use other chart's dataset to build a trend, such as moving average, liner/power regression, etc.

Custom Data is used in all charts. Event and Variable data types are available in XY Line Chart 429 , XY Area Chart 436 and XY Bar Chart 440 . And Trending is available for the same three charts if they are a part of Mixed XY Chart 469 .

2000-2013 Tibbo Technology Inc.

386

AggreGate Documentation

Property name: source Property type: Integer

SOURCE EVENTS
This property defines what is used to build an event-based 392 chart. It has a tabular format. Every line in the table defines one data series to be shown on the chart. Thus, a single chart may show changes of different values, and even values calculated from the data of different events. Each data series has the following properties: Proper ty Name Context Event Type String String String Description Name of data series indicated on the chart. Server context Event
880 863

defining event to take the data from.

from which to take the data.

925

Expressi String on

Expression 911 used to calculate data values. In most cases it should include references cells of event Data Table 881 .

to the

Variable Series Expression Resolution Environment Default Context Specified by series Context setting.
927

922

Default Data Table

927

Value of variable specified by series Event setting.

Default Row 927 Environmen t Variables

930

Standard

931

variables only.

Date String Expressi on

Expression 911 used to calculate value timestamps (i.e. domain axis values). If this expression is not defined (this is a default behaviour), chart represents values at timestamps when their modification was registered by the server. The Date Expression is useful when variable value Data Tables 854 received from a device (e.g. a real-time controller) contain both timestamps and values. In this case each data sample contains both domain-axis value (the timestamp) and range-axis value (the number), precisely positioning a chart data item.

Variable Series Date Expression Resolution Environment Default Context Specified by series Context setting.
927

922

Default Data Table

927

Value of variable specified by series Event setting.

Default Row 927 Environmen t Variables

930

Standard

931

variables only.

Aggrega Integer tion

Tells what to do if several data values exist for a specific time range. Possible choices are calculate an average, take minimal or maximal value, calculate a sum of all values, or take first/ last value for the period.

Property name: eventSeries

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: Data Table

387

SOURCE VARIABLES
This property defines what data is used to build a variable-based 393 chart. It is formatted as a table. Every line in the table defines one data series to be shown on the chart. Thus, a single chart may show changes of different values, and even values calculated from data of different variables. Each data series has the following properties: Proper ty Name Context Type String String Description Name of data series indicated on the chart. Series name can be an expression constant. Server context Variable
869 863 911

or just a string

defining event to take the data from.

Variable String Expressi String on

from which to take the data.

925

Expression 911 used to calculate data values. In most cases it should include references variable value.

to the

Variable Series Expression Resolution Environment Default Context Specified by series Context setting.
927

922

Default Data Table

927

Value of variable specified by series Variable setting.

Default Row 927 Environmen t Variables

930

0 (or dynamic if series propagation

393

is enabled)

Standard

931

variables only.

Propaga Boolean Create a separate data series for every record of source variable. See series propagation te details. Aggrega Integer tion Type Integer

393

for

Tells what to do if several data values exist for a specific time range. Possible choices are calculate an average, take minimal or maximal value, calculate a sum of all values, or take first/ last value for the period. Data series type
393 .

Property name: variableSeries Property type: Data Table

TIME UNIT
Time unit defines resolution for event-based 392 and variable-based 393 charts. Only one data value per time unit is shown on the chart. For example, if time unit for Event chart is Day and several events occurred during a certain day, data for only one event for this day (the latest one) is shown on the chart. Available Time Units: Year, Quarter, Month , Week, Day , Hour, Minute and Second . Property name: timeUnit Property type: Integer

INCLUDE HISTORICAL DATA

This property specifies whether an event-based 392 or variable-based and variable value changes that occurred before the chart was built.
393

chart will include historical data, i.e. events

Estimate memory consumption that may be caused by loading historical data according to Limit Time Range and Time Range options. Loading a huge amount of historical data may cause server failure or degraded performance.

2000-2013 Tibbo Technology Inc.

388

AggreGate Documentation

Property name: includeHistory Property type: Boolean

INCLUDE REAL-TIME DATA

This property specifies whether event-based 392 and variable-based 393 charts include real-time data, i.e. data for changes that occur after the chart is built. If this option is enabled, the chart is updated every time a new event is registered or a variable's value is changed. Property name: includeRealtime Property type: Boolean

LIMIT TIME RANGE

This property is relevant for event-based 392 and variable-based 393 charts. If it is enabled, chart data will include only events and variable value changes that have occurred only within a certain time before the chart is built, as specified by the Time Range property.

Disabling limited time range will force the server to load all available event/variable history from database into memory in order to prepare chart dataset. This may cause very high memory consumption and lead to server failure of degraded performance!
Property name: enableTimeRange Property type: Boolean

TIME RANGE (IN TIME UNITS)

This option is available only if Limit Time Range setting is enabled. It specifies a number of Time Units time range for a chart.
387

defining

Setting a long time range will force the server to load a sufficient part of event/ variable history from database into memory in order to prepare chart dataset. This may cause very high memory consumption and lead to server failure of degraded performance!
Property name: timeRange Property type: Integer

SOURCE DATA
The source data table used for building custom-data-based Property name: sourceData Property type: Data Table
388

charts.

SOURCE DATA BINDINGS

A set of expressions used to retrieve data from Source Data table records and build the resulting chart dataset. This property is also valid only for charts based on custom data 388 . Property name: chartBindings Property type: Data Table

3.15.10.1.1 Custom Data

This data source type is supported by all charts. When it's enabled chart's dataset is build in two stages by: Reading tabular chart source data (usually from the server) using a binding Data property Analyzing Source Data table row by row and filling the chart dataset Building chart dataset in AggreGate is very similar to Microsoft Excel: At first step any tabular data is read from the server and put into Source Data property. This property closely resembles Excel sheet filled with numbers and strings, as it may actually contain any data.
604

and putting this data into Source

2000-2013 Tibbo Technology Inc.

AggreGate Server

389

At second step data from this "sheet" is used to fill the resulting dataset using AggreGate expressions 911 that are similar to Excel formulas. For example, if talking about a Pie chart, one expression ("formula") is used to calculate Category name (pie section name) and another expression gives the Value (width of a pie section).

Reading Source Data

First, a widget binding 604 must be used to set value of Source Data 388 chart tabular property. This binding's expression 606 must return a Data Table 854 , e.g. by reading value of context variable or executing context function. Source Data binding may be used to refresh chart periodically or upon server-side data changes. See binding On event and Periodically binding properties 952 for more information. Example of Source Data binding:

See Debugging Charts

397

to learn how to fill Source Data with "real" values from inside the GUI Builder

827 .

Building The Dataset

Once Source Data property is filled or refilled by the binding, chart starts rebuilding its internal dataset and refreshing. This is done by processing Source Data table record-by-record and using Chart Bindings 388 for fetching different dataset values (such as X, Y, or Category) from it. Here is a step-bystep description of this process: 1. Chart renderer takes first record of Source Data Bindings table. 2. Every record of Source Data table is used to add one chart dataset entry. Expressions contained in every field of current Source Data Bindings record are used to retrieve different values from current Source Data record and fill in the dataset entry. 3. The process is repeated for the remaining Source Data Bindings records, if there are more than one.
See Debugging Charts
397

to learn how to test the chart using "live" values.

Examples
Since the above concepts may seem complicated at first glance, let's illustrate them with several examples.

PIE CHART
This simple example shows how to build a Pie Chart management system. First, we set up the binding that executes a query table (field names are shown in bold): interface_type (Interface Type) Tunnel Ethernet
271 485

depicting stats of network interfaces types in a network

and fills Source Data table with its results. Here is a source data

interface_count (Interface Count) 18 11

2000-2013 Tibbo Technology Inc.

390

AggreGate Documentation

Wireless (IEEE 802.11) Other PPP Loopback

3 2 2 1

The Source Data Bindings table of our chart will look as follows: Key {interface_type} Value {interface_count}

This means, that we'll use values from Interface Type column to fill dataset keys ("pie piece names") and values from Interface Count column to fill dataset values ("pie piece sizes"). Here is how resulting chart will look like:

BAR CHART
This example shows how values for different data series may be take from different columns of Source Data table. It's a Bar Chart 404 indicating current incoming and outgoing traffic for top ten most active network interfaces in a network management system. Below is the Source Data table for this chart. It was also set by binding upon widget startup. device ( Device) interface (Interface) interfacesInterfacetrafficI interfacesInterfacetraffic ncomingtraffic Outgoingtraffic (Incoming Traffic, bps (Outgoing Traffic, ) bps) admin.lh (Network Host) admin.lh (Network Host) admin.lh (Network Host) admin.lh (Network Host) admin.lh (Network Host) Intel(R) Wireless WiFi Link 4965AGNNative WiFi Filter Driver-0000 Intel(R) Wireless WiFi Link 4965AGNQoS Packet Scheduler-0000 Intel(R) Wireless WiFi Link 4965AGN 801 747

801

747

801

747

Microsoft Windows Mobile Remote Adapter Teredo Tunneling Pseudo-Interface

11

64

15

2000-2013 Tibbo Technology Inc.

AggreGate Server

391

admin.lh (Network Host) admin.lh (Network Host) admin.lh (Network Host) admin.lh (Network Host) admin.lh (Network Host)

Intel(R) 82566MM Gigabit Platform-QoS Packet Scheduler-0000 WAN-QoS Packet Scheduler-0000

NULL

NULL

NULL

NULL

WAN (IP)-QoS Packet Scheduler-0000

NULL

NULL

WAN (IPv6)-QoS Packet Scheduler0000 isatap.{1CD346AE-0620-4276-9D418C5FB87CCAAB}

NULL

NULL

NULL

NULL

We need to take incoming traffic values from the third column and outgoing traffic values. Therefore, we'll need two Source Data Bindings records: Series Key 'Incoming Traffic, bps' 'Outgoing Traffic, bps' Category {device} + ' - ' + {interface} {device} + ' - ' + {interface} Value {interfacesInterfacetrafficIncomingtraf fic} {interfacesInterfacetrafficOutgoingtraf fic}

This table indicates that there will be two series in the chart. During the processing of first Source Data Bindings record all added dataset entries will belong to a series with fixed name Incoming Traffic, bps (it's quoted as a string literal, since all Source Data Bindings table cells contain expressions). During processing of second record, all dataset entries will belong to Outgoing Traffic, bps series. The resulting chart:

BUBBLE CHART
Note that every type of chart contains a default Source Data table and default Source Data Bindings that greatly help understanding chart functionality. This example uses the default data and bindings of a Bubble Chart 457 to illustrate its dataset creation.

2000-2013 Tibbo Technology Inc.

392

AggreGate Documentation

Chart Source Data: key (Key) Series 1 Series 1 Series 1 Series 2 Series 3 Chart Source Data Bindings: Key {key} X {x} Y {y} Z {z} x (X) 4 6 9 5 8 y (Y) 4 6 9 12 2 z (Z) 4 5 8 5 4

These bindings are very straightforward: value of every dataset item is takes from the Source Data field with the same name. Note that Z is the size of bubbles, while X and Y are their coordinates. Here is the resulting chart:

3.15.10.1.2 Events-based Charts

A chart may be based on server events 880 data. Depending on the chart component properties, it may use real-time events and/or event history 882 as source data. When real-time events are used, the chart will update dynamically. Event-based mode is supported for the following charts: XY Line Chart XY Area Chart XY Bar Chart
429 436

440

A chart based on event data is called a Time Chart . It shows the changes in a certain value over time. The value is calculated using an expression 911 that contains references to event data 881 . The domain axis of an events-based chart must be of Date Axis type.

See source events

386

for more information.

2000-2013 Tibbo Technology Inc.

AggreGate Server

393

3.15.10.1.3 Variables-based Charts

A chart may be based on server variable 869 values. Depending on the chart component properties, it may show the history of variable value changes or monitor variable changes in real-time. In this case, the chart will update dynamically. Variable-based mode is supported for the following charts: XY Line Chart XY Area Chart XY Bar Chart
429 436

440

A chart based on variable values is called a Time Chart . It shows the changes in a certain value over time. The value is calculated using an expression 911 that contains references to the Data Table 854 containing variable value. The domain axis of a variables-based chart must be of Date Axis type.

Variable Series Properties

See source variables
387

for more information about properties of variable-based data series.

3.15.10.1.3.1 Variable Series Propagation

A variable series has Propagate flag allowing to create a separate data sub-series for every record found in the source variable. Here is how it affects series processing.

Propagation Disabled
This is a default setting. Only one data series will be created, even if the source variable has multiple rows. Series Name expression and data Expression will be evaluated having row number zero as default row 927 . It's of course possible to refer other rows using references of format {field[row]}.

Propagation Enabled
A separate sub-series is created for every row found in the current value of series variable. Series Name should be an expression 911 . This expression is evaluated for every row found in the current value of series variable (i.e. default row 927 is current row). The current row is also defined as the "active" row for the sub-series, so that when series primary Expression will be evaluated for historical and future values, its default row 927 will be the same. Series propagation will work properly only in two cases: Series is based on statistics
394 ,

OR

The order of rows in the variable's value never changes If series Name expression was evaluated to NULL, no series will be created for the current record. This is very convenient to skip some series. Here is an example of propagated series' Name expression that skips series creation for records those {ifInOctets} and {ifOutOcters} fields are both zeros:

({ifInOctets} > 0 && {ifOutOctets} > 0) ? 'Interface ' + {ifDescr} + ' incoming traffic, Kbit/s' : null

3.15.10.1.3.2 Variable Series Types

Series Type setting completely change the style of how "raw" source values are converted to chart data points. There are four series types: Gauge Counter Derive

2000-2013 Tibbo Technology Inc.

394
Absolute

AggreGate Documentation

If the series is based on statistics

394 ,

its type must match the type of statistical channel

936

it's based on.

Gauge
The source value is kept as-is, without any conversion. This is a default setting that is suitable for most cases. This type is suitable for simple metering like temperature, number of people in the room or stock price.

Counter
Suitable for continuous incrementing counters. The Counter-type data source assumes that the counter never decreases, except when a counter overflows. The series takes the overflow into account. The counter is stored as a persecond rate. When the counter overflows, series checks if the overflow happened at the 32bit or 64bit border and acts accordingly by adding an appropriate value to the result. Simply speaking, Counter will look at the difference between the previous value and the current value (the delta). An example would be an odometer. The chart data point is computed as: delta(counter) divided by delta(time).

Derive
Derive-type series will store the derivative of the line going from the last to the current value of the data source. This can be useful for gauges, for example, to measure the rate of people entering or leaving a room. Internally, derive works exactly like Counter but without overflow checks. So if your counter does not reset at 32 or 64 bit you might want to use Derive and combine it with a Minimum Value of 0. Derive is similar to Counter, but now it can also go back. An example could be something monitoring a bidirectional pump. The resulting rate can be negative as well as positive.

Absolute
Absolute series are used for counters which get reset upon reading. This is used for fast counters which tend to overflow. So instead of reading them normally you reset them after every read to make sure you have a maximum time available before the next overflow. Another usage is for things you count like number of messages since the last update. Absolute series is also similar to the odometer, but here the counter is reset every time it is read. Chart data point computed as: value divided by delta(time).

3.15.10.1.3.3 Statistics-Based Series

In most cases, variable series are based on "raw" historical values of the series variable. These values are stored in the server database. However, it's possible to build a chart those historical data points are based on a statistical channel To build such a chart: Make sure that a statistical channel exists for the series variable Use a special statistics reference within series Expression
936 .

Statistics Reference
The statistics reference ("key")}.
925

has one of the following formats: {statistics/channel} or {statistics/channel

Once statistics reference is used inside series Expression , chart builder takes historical data from the channel named channel. This channel should be based on the series source variable. If a key is specified, the statistical Dataset matching this key
942

will be used as a source.

The following series parameters affect fetching statistical data:

2000-2013 Tibbo Technology Inc.

AggreGate Server
Aggregation. Series aggregation setting match statistical aggregation function Type . Series type must match statistical channel's type
942 . 940

395

those results will be used.

Series expression may include only one statistics reference. Referring multiple channels not possible.

Referring Other Fields from Statistics-Based Series Expression

Statistics-based series expression may also refer other fields of the source variable. However, such references have some important nuances: Statistical channel doesn't keep the original historical values of the variable. Therefore, any reference to the cells of source variable is resolved using current value of this variable. If real-time history is enabled for a statistics-based series, the chart builder will merge statistical channel's expression and series' expression to generate new expression for building real-time data points.

3.15.10.1.4 Trending
A chart may show trends based on data from other chart's dataset. There are four types of trends: Linear Regression Exponential Regression Moving Average Percentile Trending involves two charts to present: the source chart (its data is used to calculate the trend) and the trend chart itself. Thus, trends can be plotted by the following charts only when they are a part of Mixed XY Chart 469 : XY Line Chart XY Area Chart XY Bar Chart
429 436

440

Setting Up Trends
To configure new trend for a chart, perform the following: 1. Create a Mixed XY Chart 2. Add
489 469

a "simple" XY Chart to this mixed chart.

3. Configure the data source for the simple XY chart and ensure that it shows correct data. 4. Add
489

another XY chart to the mixed chart. The second XY chart will show trend(s) of first XY chart's source data.
385

5. Change the Data Source Type

of second XY chart to Trending.

6. Since trend chart and source chart share the same address space and axes, you can now remove trend chart's "original" axes from the parent mixed chart. This step is optional. 7. Open Trending properties of the second XY chart and change Source Chart Name to the name of widget component matching the "source" XY chart, e.g. xyLineChart1. 8. Select trend type and configure other trend properties. 9. Run the widget and test the trends.

Trending Properties
The trending properties are available only for XY Line, Area and Bar charts when they are added as sub-charts to a Mixed XY Chart 469 .

SOURCE CHART
Name of sub-chart component those data will be used to build trend curves. It must be the a sub-chart of the same Mixed XY Chart with this trending sub-chart. Property name: sourceDataPlotID

2000-2013 Tibbo Technology Inc.

396

AggreGate Documentation

Property type: String

TRENDING TYPE
Type of trend(s) to build: Linear, Exponential, Moving Average, or Percentile. Property name: trendingType Property type: Integer

FORECAST FACTOR
Length of "future" trend in time comparing to the time frame of the source data, for example: Value of 0.0 means that the trend is build exactly for the time frame covered by source data. Value of 0.5 means that the trend goes into the future for half of source data's time frame. E.g. if the source data covers the whole year 2012, the trend will cover 2012 and first two quoters of 2013. Value of 1.0 means that the trend goes into the future full source data's time frame. E.g. if the source data covers the whole year 2012, the trend will cover 2012 and 2013. Value of 3.0 means that the trend goes into the future three source time frames, etc. Property name: forecastFactor

Property type: Float

Linear And Exponential Trend Options

POINT COUNT
Number of data items in the trend curve. Zero value means that point count will match the number of data items in the source series. This option is valid for Linear and Exponential trends only. Property name: pointCount Property type: Float

Moving Average Trend Options

PERIOD
The averaging period for Moving Average calculation (in chart's data space). Property name: period Property type: Float

SKIP PERIOD
The length of the initial skip period for the Moving Average calculation (in chart's data space). Property name: skipPeriod Property type: Float

Percentile Trend Options

PERCENTILE
The base for Percentile trend, in percents. The default is value is 95%, making percentile trend appear so that 95% of source values will stay below the trend line. Property name: percentile Property type: Float

2000-2013 Tibbo Technology Inc.

AggreGate Server

397

3.15.10.2 Debugging Charts

When a new chart is created in the GUI Builder 827 , it contains a pre-defined Source Data 388 table and pre-defined Source Data Bindings 388 that refer this default source data. Together they provide a kind of "demo chart", illustrating its common appearance. Once you've started to customize your chart, you change its Source Data Bindings to refer your server-side data model. During normal widget operation and in the editor preview mode, the Source Data table is changed by a binding, and than chart's dataset is correctly build upon this data. However, when working in the editor, the system never gets data from the server. Therefore, once you have modified Source Data Bindings the system is no longer unable to build the chart since default Source Data table doesn't match the "real" bindings. To solve this issue, the chart's context menu in the GUI Builder contains Load Real Source Data item. This operation causes the system to find widget binding 604 pointing to current chart's Source Data, resolve its expression getting server data, and write this data into "editor-mode" Source Data table. After that you will be able to configure chart that uses real data. To reset Source Data back to its original demo value, use Reset Source Data context menu item.

3.15.10.3 Category Charts

The common feature of all category charts is their Domain Axis that displays discrete textual categories, while analog Range Axis displays numeric values. All category charts are based on: Category Plot
511 548

Category Renderer

3.15.10.3.1 Line Chart

A category line chart simply connects each (category, value) data item using straight lines. The line chart is based on Category Plot
511

and Category Line Renderer

552 .

It inherits all their properties.

This is what category line chart looks like:

2000-2013 Tibbo Technology Inc.

398

AggreGate Documentation

Category line chart supports four renderers.

LINE RENDERER
A renderer that displays data items by drawing a shape at each data point and/or connecting data points with straight lines.

LINE 3D RENDERER
A line renderer that uses a "pseudo-3D" effect to draw line charts.

LEVEL RENDERER
A renderer that draws horizontal lines to represent items.

2000-2013 Tibbo Technology Inc.

AggreGate Server

399

STEP RENDERER
A renderer that draws a stepped line (or stepped lines) connecting the data items.

Dataset
The category line chart supports Custom Data It has the following Source Data Bindings: Binding Series Category Value Expected Value Type String String Number Description Textual name of the data series. Data series is represented by a single line (or set of shapes) on the chart. Name of category. Categories are displayed along the domain axis. Numeric value to display for the above series/category. Values are displayed along the range axis.
388

model only.

2000-2013 Tibbo Technology Inc.

400

AggreGate Documentation

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

511 .

388

properties.

All properties of a Category Plot

All properties of a Category Line Renderer

552 .

All properties defined directly by Category Line Renderer 552 (and not the base Category Renderer) are valid only for Line and Line 3D renderers. These properties has no effect on Level and Step renderers.

Custom Properties
ITEM MARGIN
Item margin as a percentage of the overall length of the category axis (the default is 0.20, or twenty percent). This controls the amount of space that is allocated to the gaps between items within the same category. This property is valid for Level renderer. Property name: itemMargin Property type: Float

MAXIMUM ITEM WIDTH

Maximum item width as a percentage of the axis length. For example, setting this to 0.05 will ensure that the items never exceed five percent of the length of the axis. This can improve the appearance of charts where there is a possibility that only one or two items will be displayed. This property is valid for Level renderer. Property name: maximumItemWidth Property type: Float

X OFFSET
X-offset for the 3D effect. This property is valid for Line 3D renderer. Property name: XOffset Property type: Float

Y OFFSET
Y-offset for the 3D effect. This property is valid for Line 3D renderer. Property name: YOffset Property type: Float

WALL PAINT
Paint
590

used to color the "sides" (or "walls") of the plot background area.

This property is valid for Line 3D renderer. Property name: wallPaint Property type: Data Table

Common Events

2000-2013 Tibbo Technology Inc.

AggreGate Server
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

401

Mouse Key Released

Additional Examples
A line chart with item labels showing. The orientation of the plot has been changed to horizontal:

A line chart where each series is displayed with a different combination of lines and/or shapes:

3.15.10.3.2 Area Chart

A category area chart represents the items using polygons that fill the area between the domain axis and the data points. The area chart is based on Category Plot
511

and Category Renderer

548 .

It inherits all their properties.

This is what category area chart looks like:

2000-2013 Tibbo Technology Inc.

402

AggreGate Documentation

Category area chart supports two renderers.

AREA RENDERER
A renderer that draws different data series one over another. Since different series overlap each other, they are rendered semi-transparently. The transparency is controlled by Foreground Alpha property of the chart plot 511 .

STACKED RENDERER
A renderer that "stacks" different data series one over another.

2000-2013 Tibbo Technology Inc.

AggreGate Server

403

Dataset
The category area chart supports Custom Data It has the following Source Data Bindings: Binding Series Category Value Expected Value Type String String Number Description Textual name of the data series. Name of category. Categories are displayed along the domain axis. Numeric value to display for the above series/category. Values are displayed along the range axis.
388

model only.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

511 . 548 .

388

properties.

All properties of a Category Plot

All properties of a Category Renderer

Custom Properties
END TYPE
Controls how the end points are drawn on the area chart. There are three options: Taper: Taper down to zero. Truncate: Truncates at the first and last values. Level : Fill to the edges of the chart level with the first and last data values. Property name: endType Property type: String

RENDER AS PERCENTAGES
Flag that controls whether the renderer displays each item value as a percentage (so that the stacked areas add to 100%). This property is valid for Stacked Renderer. Property name: renderAsPercentages

2000-2013 Tibbo Technology Inc.

404

AggreGate Documentation

Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

3.15.10.3.3 Bar Chart

A category bar chart represents data items as rectangular bars. The bar chart is based on Category Plot
511

and Category Bar Renderer

549 .

It inherits all their properties.

This is what category bar chart looks like:

Category bar chart supports six renderers.

BAR RENDERER
A classic bar renderer that draws bars for every series/category pair as a separate "bar group".

2000-2013 Tibbo Technology Inc.

AggreGate Server

405

STACKED RENDERER
A renderer that "stacks" bars from different series in every category.

BAR 3D RENDERER
A renderer that draws items using bars with a 3D effect.

2000-2013 Tibbo Technology Inc.

406

AggreGate Documentation

STACKED 3D RENDERER
A renderer that draws stacked bars with a 3D effect.

LAYERED BAR RENDERER

A renderer that draws bars for every series/category pair one over another.

2000-2013 Tibbo Technology Inc.

AggreGate Server

407

WATERFALL BAR RENDERER

A renderer for drawing "waterfall" charts. A waterfall chart highlights the difference between two values and the components that make up that difference. The value in the last category of the dataset should be (redundantly) specified as the sum of the items in the preceding categories - otherwise the final bar in the plot will be incorrectly plotted.

Bar colors for this renderer are defined using special properties. Related properties inherited from the base renderer are ignored.

Dataset
The category bar chart supports Custom Data It has the following Source Data Bindings: Binding Series Category Value Expected Value Type String String Number Description Textual name of the data series. Name of category. Categories are displayed along the domain axis. Numeric value to display for the above series/category. Values are displayed along the
388

model only.

2000-2013 Tibbo Technology Inc.

408

AggreGate Documentation

range axis.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

511 .

388

properties.

All properties of a Category Plot

All properties of a Category Bar Renderer

549 .

Custom Properties
RENDER AS PERCENTAGES
Flag that controls whether the renderer displays each item value as a percentage (so that the stacked bars add to 100%). Example of a stacked bar chart that displays values as percentages:

This property is valid for Stacked Renderer and Stacked 3D Renderer. Property name: renderAsPercentages

Property type: Boolean

X OFFSET
X-offset for the 3D effect. This property is valid for Bar 3D Renderer and Stacked 3D Renderer. Property name: XOffset Property type: Float

Y OFFSET
Y-offset for the 3D effect. This property is valid for Bar 3D Renderer and Stacked 3D Renderer. Property name: YOffset Property type: Float

WALL PAINT

2000-2013 Tibbo Technology Inc.

AggreGate Server
Paint
590

409

used to color the "sides" (or "walls") of the plot background area.

This property is valid for Bar 3D Renderer and Stacked 3D Renderer. Property name: wallPaint Property type: Data Table

FIRST BAR PAINT

Paint
590

used for the first bar (i.e. first category).

Property name: firstBarPaint Property type: Data Table

LAST BAR PAINT

Paint
590

used for the last bar (i.e. last category).

Property name: lastBarPaint Property type: Data Table

POSITIVE BAR PAINT

Paint
590

used for the intermediate bars representing positive values.

Property name: positiveBarPaint Property type: Data Table

NEGATIVE BAR PAINT

Paint
590

used for the intermediate bars representing negative values.

Property name: negativeBarPaint Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
Horizontally-oriented bar chart:

2000-2013 Tibbo Technology Inc.

410

AggreGate Documentation

A bar chart with the customized Default Item Label Position. A range marker has been added to the chart to indicate a target range for the data values:

A bar chart with items labels displayed for just one series:

Another labels customization:

2000-2013 Tibbo Technology Inc.

AggreGate Server

411

A 3D bar chart with multiple series:

A 3D bar chart with horizontal orientation:

A bar chart with customized Series Paints:

2000-2013 Tibbo Technology Inc.

412

AggreGate Documentation

A layered bar chart with horizontal orientation:

Stacked bar chart with negative values:

A stacked bar chart with a horizontal orientation and Render As Percentages enabled. A completely transparent color

2000-2013 Tibbo Technology Inc.

AggreGate Server
is used for the middle series, so that it leaves a gap in the chart:

413

A stacked bar chart that uses a Date Axis for the range axis:

A stacked bar chart with 3D effect and interval marker:

2000-2013 Tibbo Technology Inc.

414

AggreGate Documentation

A stacked bar chart with 3D effect and vertical orientation:

A stacked bar chart with 3D effect and negative values:

A bar chart with two range axes:

2000-2013 Tibbo Technology Inc.

AggreGate Server

415

3.15.10.3.4 Interval Bar Chart

An interval bar chart shows an interval (that is, a start value and an end value) for each series/category value pair in the dataset. The area chart is based on Category Plot This is what interval bar chart looks like:
511

and Category Bar Renderer

549 .

It inherits all their properties.

Dataset
The interval bar chart supports Custom Data It has the following Source Data Bindings: Binding Expected Description
388

model only.

2000-2013 Tibbo Technology Inc.

416

AggreGate Documentation

Value Type Series Category Start End String String Number Number Textual name of the data series. Name of category. Categories are displayed along the domain axis. Interval start value for the above series/category. Values are displayed along the range axis. Interval end value for the above series/category.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

511 .

388

properties.

All properties of a Category Plot

All properties of a Category Bar Renderer

549 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
Bar chart that displays different intervals along the date X-axis:

Another example of an interval bar chart:

2000-2013 Tibbo Technology Inc.

AggreGate Server

417

3.15.10.3.5 Statistical Chart

A statistical chart shows a mean and a standard deviation for each series/category value pair in the dataset. The statistical chart is based on Category Plot
511 . 552

Its renderers are based on Category Line Renderer This is what statistical chart looks like:

and Category Bar Renderer

549 .

It inherits all their properties.

Statistical chart supports two renderers.

LINE RENDERER
A renderer that draws lines and/or shapes for each data value and then overlays a standard deviation indicator.

2000-2013 Tibbo Technology Inc.

418

AggreGate Documentation

BAR RENDERER
A renderer that draws bars for each data value and then overlays a standard deviation indicator.

Dataset
The statistical chart supports Custom Data It has the following Source Data Bindings: Binding Series Category Mean Deviation Expected Value Type String String Number Number Description Textual name of the data series. Name of category. Categories are displayed along the domain axis. Mean value for the above series/category. Values are displayed along the range axis. Standard deviation value for the above series/category.
388

model only.

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Visible

587 ,

Background

587 ,

Border

587

All properties of a Category Plot

511 .

2000-2013 Tibbo Technology Inc.

AggreGate Server
Source Data
388

419

and Source Data Bindings

388 552 549

properties. (valid if renderer type is Line Renderer). (valid if renderer type is Bar Renderer).

All properties of a Category Line Renderer All properties of a Category Bar Renderer

Custom Properties
ERROR INDICATOR PAINT
Paint 590 used to display the deviation (error) indicator for each item. If this is null then the item paint is used instead (that is, the error indicator will use the same color as the Line/Shape/Bar Outline for the item). Property name: errorIndicatorPaint

Property type: Data Table

ERROR INDICATOR STROKE

Stroke 593 used to draw the deviation (error) indicator for each item. If this property is null, the item Outline Stroke will be used instead. Property name: errorIndicatorStroke

Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

3.15.10.3.6 Gantt Chart

A gantt chart is used to draw simple Gantt diagrams.

A Gantt chart is a type of bar chart that illustrates a project schedule. Gantt charts illustrate the start and finish dates of the individual tasks within a project. The gantt chart is based on Category Plot This is what gantt chart looks like: and Category Bar Renderer
549 .

511

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

420

AggreGate Documentation

Dataset
The gantt chart supports Custom Data
388

model only.

It has the following Source Data Bindings: Binding Series Description Start Date End Date Percent Complete Expected Value Type String String Date or Number Date or Number Number Description Textual name of the data series. Series are usually used to indicate project names in the multi-project charts. Description of the task. Tasks are displayed along the domain axis. Task start timestamp. Numeric values are converted to dates by treating them as number of milliseconds since the January 1, 1970. Task end timestamp. Task completion percentage.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

511 .

388

properties.

All properties of a Category Plot

All properties of a Category Bar Renderer

549 .

Custom Properties
COMPLETE PAINT
Paint
590

used to draw the portion of the task that is completed.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: completePaint Property type: Data Table

421

INCOMPLETE PAINT
Paint
590

used to draw the portion of the task that is not yet completed.

Property name: incompletePaint Property type: Data Table

START PERCENT
Start position for the "percentage complete" indicator as a percentage of the width of the task bar (for example, 0.30 is thirty percent). Property name: startPercent Property type: Float

END PERCENT
End position for the "percentage complete" indicator as a percentage of the width of the task bar (for example, 0.30 is thirty percent). Property name: endPercent Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A simple Gantt chart showing actual vs. scheduled progress:

A simple Gantt chart showing progress-to-date on a set of tasks:

2000-2013 Tibbo Technology Inc.

422

AggreGate Documentation

3.15.10.3.7 Mixed Category Chart

A mixed category chart is a composite chart 488 designed to combine two or more "simple" category charts 397 within a single plot. These sub-charts share the plot and axes, but each of them has its own dataset and renderer. This is what mixed category chart looks like:

When a "simple" category chart is added as a sub-chart to a mixed category chart, is has the following differences from its "standalone" version: Axes of the sub-chart are added to the axes list of the container chart. The sub-chart has no own axes. Instead, it has references to the parent chart's axes to use for displaying the data. By default, the axes moved from sub-chart to its parent are referenced. The sub-chart has no plot
509 -related

properties, since its data will be rendered on the parent's plot.

489 ,

The sub-chart has no chart common properties

the parent mixed chart has its own set of chart common

2000-2013 Tibbo Technology Inc.

AggreGate Server
properties. The sub-chart has no widget component default properties rendered separately.
586 ,

423

except for the Bindings property, since it is not

Custom Properties of Sub-charts

Every "simple" category chart added as a sub-chart to a mixed category chart has several additional properties:

DOMAIN AXIS INDEX

The index of parent mixed chart's domain axis to use. First axis in the parent's domain axes table has index 1. Property name: domainAxisIndex Property type: Integer

RANGE AXIS INDEX

The index of parent mixed chart's range axis to use. First axis in the parent's range axes table has index 1. Property name: rangeAxisIndex Property type: Integer

Z-ORDER
Z-index of the sub-chart in the parent's plot. Charts with lower order numbers overlap chart's with higher order numbers. Property name: index Property type: Integer

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties

All properties of a Category Plot

511 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A mixed category chart with line
397

and bar

404

sub-charts using different range axes:

2000-2013 Tibbo Technology Inc.

424

AggreGate Documentation

Almost same as above, but with 3D renderers:

Almost same as above, but with horizontal orientation:

A mixed chart with a bar

404

sub-chart and a line

397

sub-chart using Level renderer:

2000-2013 Tibbo Technology Inc.

AggreGate Server

425

3.15.10.3.8 Combined Domain Category Chart

A combined domain category chart is a composite chart 397 share a single domain axis. This is what combined domain category chart looks like:
488

allowing two or more "simple" category charts

When a "simple" category chart is added as a sub-chart to a combined domain category chart, is has the following differences from its "standalone" version: No Domain Axes chart. No Orientation
517 513

and Fixed Domain Axis Space

514

properties, since Domain Axis is a part of parent combined

property, since it inherits the orientation of parent combined chart.

489 ,

No chart common properties

since the parent combined chart has its own set of chart common properties.
586 ,

No widget component default properties

except for the Bindings property, since it is not rendered separately.

2000-2013 Tibbo Technology Inc.

426

AggreGate Documentation

Custom Properties of Sub-charts

Every "simple" category chart added as a sub-chart to a combined domain category chart has several additional properties:

WEIGHT
The weight determines how much of the parent chart's area is assigned to this sub-chart. For example, if parent has three sub-charts with weights of 1, 2 and 4, the relative amount of space assigned to each sub-chart is 1/7, 2/7 and 4/7 (where the 7 is the sum of the individual weights). Property name: weight Property type: Integer

Z-ORDER
Sub-charts with higher order numbers are placed closer to the shared axis. Property name: index Property type: Integer

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Domain Axes

513

property.
514

Fixed Domain Axis Space

property.

Custom Properties
ORIENTATION
Chart orientation (Vertical or Horizontal). This orientation is used for all sub-charts. Property name: orientation Property type: String

GAP
The gap between sub-charts. Property name: gap Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A demo showing two sub-charts that share a single domain axis:

2000-2013 Tibbo Technology Inc.

AggreGate Server

427

3.15.10.3.9 Combined Range Category Chart

A combined range category chart is a composite chart 397 share a single range axis. This is what combined range category chart looks like:
488

allowing two or more "simple" category charts

When a "simple" category chart is added as a sub-chart to a combined range category chart, is has the following differences from its "standalone" version: No Range Axes No Orientation
514 517

and Fixed Range Axis Space

514

properties, since Range Axis is a part of parent combined chart.

property, since it inherits the orientation of parent combined chart.

489 ,

No chart common properties

since the parent combined chart has its own set of chart common properties.
586 ,

No widget component default properties

except for the Bindings property, since it is not rendered separately.

2000-2013 Tibbo Technology Inc.

428

AggreGate Documentation

Custom Properties of Sub-charts

Every "simple" category chart added as a sub-chart to a combined range category chart has several additional properties:

WEIGHT
The weight determines how much of the parent chart's area is assigned to this sub-chart. For example, if parent has three sub-charts with weights of 1, 2 and 4, the relative amount of space assigned to each sub-chart is 1/7, 2/7 and 4/7 (where the 7 is the sum of the individual weights). Property name: weight Property type: Integer

Z-ORDER
Sub-charts with higher order numbers are placed closer to the shared axis. Property name: index Property type: Integer

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Range Axes

514

property.
514

Fixed Range Axis Space

property.

Custom Properties
ORIENTATION
Chart orientation (Vertical or Horizontal). This orientation is used for all sub-charts. Property name: orientation Property type: String

GAP
The gap between sub-charts. Property name: gap Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A demo showing two horizontally oriented sub-charts that share a single range axis:

2000-2013 Tibbo Technology Inc.

AggreGate Server

429

3.15.10.4 XY Charts
XY charts display values on a continuous 2D space. Both domain and range axes are analog. All XY charts are based on: XY Plot
521 554

XY Renderer

3.15.10.4.1 XY Line Chart

An XY line chart simply connects each (X, Y) data item using straight lines. The line chart is based on XY Plot
521

and XY Line Renderer

556 .

It inherits all their properties.

This is what XY line chart looks like:

2000-2013 Tibbo Technology Inc.

430

AggreGate Documentation

XY line chart supports four renderers:

LINE RENDERER
A renderer that displays items by drawing a line between each (x, y) point and overlaying a shape at each (x, y) point.

LINE 3D RENDERER
A line renderer that uses a "pseudo-3D" effect to draw line charts.

2000-2013 Tibbo Technology Inc.

AggreGate Server

431

SPLINE RENDERER
This renderer connects data points using spline curves. This results in a smooth line passing through all the data points.

STEP RENDERER
This renderer draws items using "stepped" lines to connect each (x, y) point.

2000-2013 Tibbo Technology Inc.

432

AggreGate Documentation

Dataset
The XY line chart supports several data models: Custom Data
388 392 393

Event-based Data

Variable-based Data

It has the following Source Data Bindings: Binding Series X Y Expected Value Type String Number Number Description Textual name of the data series. Data series is represented by a single line (or set of shapes) on the chart. Numeric value to display along the domain (X) axis. Numeric value to display along the range (Y) axis.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 556 .

All properties of a XY Plot

All properties of a XY Line Renderer

Custom Properties
X OFFSET
X-offset for the 3D effect. This property is valid for Line 3D renderer. Property name: XOffset Property type: Float

Y OFFSET
Y-offset for the 3D effect. This property is valid for Line 3D renderer.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: YOffset Property type: Float

433

WALL PAINT
Paint
590

used to color the "sides" (or "walls") of the plot background area.

This property is valid for Line 3D renderer. Property name: wallPaint Property type: Data Table

PRECISION
Number of line segments used to approximate the curve between data points. This property is valid for Spline renderer. Property name: precision Property type: Integer

STEP POINT
Fraction of the domain position between two points on which the step is drawn. The default is 1.0, which means the step is drawn at the domain position of the second point. If the Step Point is 0.5 the step is drawn at half between the two points. This property is valid for Step renderer. Property name: stepPoint Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A line chart with many series. A shape is displayed at each data point to help to differentiate the series:

A line chart where each series is displayed with a different combination of lines and/or shapes:

2000-2013 Tibbo Technology Inc.

434

AggreGate Documentation

A "step" chart with item labels:

A line chart with two range axes:

A line chart with multiple range axes:

2000-2013 Tibbo Technology Inc.

AggreGate Server

435

An XY line chart with four data series and pointer annotations

532 :

A scatter plot that displays multiple data series. It uses Line renderer with Default Lines Visibility disabled:

2000-2013 Tibbo Technology Inc.

436

AggreGate Documentation

3.15.10.4.2 XY Area Chart

An XY area chart represents the items using polygons that fill the area between the domain axis and the (X, Y) data points. The XY area chart is based on XY Plot This is what XY area chart looks like:
521

and XY Renderer

554 .

It inherits all their properties.

XY area chart supports four renderers:

AREA RENDERER
A renderer draws each item in an (X, Y) dataset using a polygon that fills the area between the x-axis and the data point. The below example uses Date Axis
495

as an x-axis.

STACKED RENDERER

2000-2013 Tibbo Technology Inc.

AggreGate Server
A renderer that fills the area under a series, and stacks each series on top of the other.

437

STEP RENDERER
A renderer that displays data from an (X, Y) Dataset in a step format with the area under the steps filled.

DIFFERENCE RENDERER
A renderer that highlights the difference between the items in two series by filling in the area between the lines for each series. The fill color alternates between a "positive" color (used when series 1 is greater than series 2) and a "negative" color (used when series 1 is less than series 2). The below example uses Date Axis
495

as an x-axis.

2000-2013 Tibbo Technology Inc.

438

AggreGate Documentation

Dataset
The XY area chart supports several data models: Custom Data
388 392 393

Event-based Data

Variable-based Data

It has the following Source Data Bindings: Binding Series X Y Expected Value Type String Number Number Description Textual name of the data series. Numeric value to display along the domain (X) axis. Numeric value to display along the range (Y) axis.

Additional dataset properties:

AUTO SORT
Flag that controls whether the items in the series are automatically sorted into ascending order by x-value. Property name: autoSort Property type: Boolean

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 554 .

All properties of a XY Plot

All properties of a XY Renderer

Custom Properties
OUTLINE
Flag that controls whether or not outlines are drawn. This property is valid for Area and Step renderers. Property name: outline

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: Boolean

439

AREA RENDERER MODE

Area renderer can work in several different modes: Area (normal mode) Area and Shapes (date item shapes are visible) Shapes and Lines (only date item shapes and item-to-item lines are visible, areas not filled; chart is similar to XY Line Chart 429 ) Lines (only item-to-item lines are visible, areas not filled; chart is similar to XY Line Chart
429 ) 429 )

Shapes (only date item shapes are visible, areas not filled; chart is similar to XY Line Chart Example of Area and Shapes mode:

This property is valid for Area renderer. Property name: XYAreaRendererMode Property type: Integer

ROUND X COORDINATES
Flag that controls whether or not the x-coordinates (in drawing space) are rounded. This property is valid for Stacked and Difference renderers. Property name: roundXCoordinates Property type: Boolean

PLOT AREA
Flag that controls whether or not the area beneath the steps is filled. This property is valid for Step renderer. Property name: plotArea Property type: Boolean

SHAPES VISIBLE
Flag that controls whether or not shapes are drawn at each data point. This property is valid for Step renderer. Property name: shapesVisible Property type: Boolean

2000-2013 Tibbo Technology Inc.

440

AggreGate Documentation

SHAPES FILLED
Flag that controls whether or not shapes (if visible) are filled. This property is valid for Step renderer. Property name: shapesFilled Property type: Boolean

RANGE BASE
Base value for the renderer. The default value is 0.0. This property is valid for Step renderer. Property name: rangeBase Property type: Float

POSITIVE PAINT
Paint used to fill the area between series 1 and series 2 when the difference is positive. This property is valid for Difference renderer. Property name: positivePaint Property type: Data Table

NEGATIVE PAINT
Paint used to fill the area between series 1 and series 2 when the difference is negative. This property is valid for Difference renderer. Property name: negativePaint Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

3.15.10.4.3 XY Bar Chart

An XY bar chart represents (X, Y) data items as rectangular bars. The line chart is based on XY Plot
521

and XY Renderer

554 .

It inherits all their properties.

This is what XY bar chart looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

441

XY bar chart supports three renderers:

SIMPLE RENDERER
A "classic" bar renderer.

The below example uses Date Axis

495

as an x-axis.

STACKED RENDERER
A renderer for drawing stacked bar charts on an XY Plot. All series must share the same set of x-values to allow values to be stacked.

2000-2013 Tibbo Technology Inc.

442

AggreGate Documentation

CLUSTERED RENDERER
This render slightly differs from the Simple Renderer, in that it adjusts the position and width of each of the bars, making the assumption that the bars for all the series should be clustered within the same x-interval. The below example uses Date Axis
495

as an x-axis.

Dataset
The XY bar chart supports several data models: Custom Data
388 392 393

Event-based Data

Variable-based Data

It has the following Source Data Bindings: Binding Series X Expected Value Type String Number Description Textual name of the data series. Data series is represented by a single line (or set of shapes) on the chart. Bar position anchor along the domain (X) axis. It is unused if Bar Alignment Factor is negative. See Bar Alignment Factor 445 for details.

2000-2013 Tibbo Technology Inc.

AggreGate Server

443

X Low X High Y Low Y High

Number Number Number Number

The lower margin of the bar along the domain (X) axis or a part of bar's width. See Bar Alignment Factor 445 for details. The upper margin of the bar along the domain (X) axis or a part of bar's width. See Bar Alignment Factor 445 for details. The beginning of a bar at the range (Y) axis. Unused if Use Y Interval The end of a bar at the range (Y) axis.
445

is disabled.

Additional dataset properties:

AUTO SORT
Flag that controls whether the items in the series are automatically sorted into ascending order by x-value. Property name: autoSort Property type: Boolean

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 554 .

All properties of a XY Plot

All properties of a XY Renderer

Bar Shadows
SHADOWS VISIBLE
Flag that controls whether or not shadows are drawn for the bars. Property name: shadowsVisible Property type: Boolean

SHADOW PAINT
Paint
590

used to fill the bar shadows.

Property name: shadowPaint Property type: Data Table

SHADOW X OFFSET
X-offset for the bar shadows. Property name: shadowXOffset Property type: Float

SHADOW Y OFFSET
Y-offset for the bar shadows. Property name: shadowYOffset Property type: Float

Item Labels
Due to the rectangular nature of the bars, the renderer calculates anchor points that are arranged as shown in figure below. Note that the numbers correspond (roughly) to the position of the hours on a clock face.

2000-2013 Tibbo Technology Inc.

444

AggreGate Documentation

When an item label is displayed inside a bar, the renderer will calculate if the bar is large enough to contain the text. If not, the renderer will check to see if a "fallback" label position has been specified. If there is a fallback position, the label is displayed there, and if there is no fallback position the label is not displayed at all. Two fallback positions can be specified, one for positive values and one for negative values (this covers the standard case where positive value labels that don't fit within a bar should be displayed above the bar, and negative value labels that don't fit within a bar should be displayed below the bar).

ITEM LABEL POSITION FALLBACK

This property includes two values: Positive Item Label Position 499 : fallback position for positive item labels. Set the value to null if you prefer labels to be hidden if they don't fit within the bar. Negative Item Label Position: fallback position for negative item labels. Set the value to null if you prefer labels to be hidden if they don't fit within the bar. Property name: itemLabelPositionFallback Property type: Data Table

Other Properties
MARGIN
Margin for the renderer. The margin is specified as a percentage of the bar width (for example, 0.10 is ten percent) and is the amount that is trimmed from the bar width before the bar is displayed. Property name: margin Property type: Float

DRAW BAR OUTLINE

Flag that controls whether or not an outline is drawn around each bar. The paint and stroke used for the bar outline are specified using properties of a base chart renderer. Property name: drawBarOutline Property type: Boolean

BASE
Base value for the bars. By default, the renderer draws a bar between zero (the base value) and the data value of the item to be displayed. Some specialized bar charts require a non-zero base value.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: base Property type: Float

445

USE Y INTERVAL
Flag that controls how the length of the bars is determined. If true, the y-interval from the dataset is used. If false, the y-value from the dataset determines one end of the bar, and the Base property determines the other end of the bar. Property name: useYInterval Property type: Boolean

BAR ALIGNMENT FACTOR

Bar alignment factor. If the alignment factor is in the range 0.0 to 1.0, then the bar width is determined by the x-interval from the dataset, while the bar position is adjusted so that the x-value from the dataset falls at the specified relative position within the bar (for example, 0.0 places the bar so that the x-value is at the left side of the bar, 0.5 places the bar so that the x-value is at the center of the bar, and 1.0 places the bar so that the x-value is at the right side of the bar). If the alignment factor is outside the range 0.0 to 1.0, no alignment will be performed by the renderer (in this case the bar position is determined by the x- interval in the dataset only, and the x-value is ignored). Property name: barAlignmentFactor Property type: Float

BAR PAINTER
Bar Painter takes care of the actual drawing of individual bars. It has the following properties: Property Type Name type Type Description

Intege Painter type: Standard or Gradient: r Standard bar painter uses a single Paint

590

(current series paint) to fill the bars.

Gradient bar painter applies the effect over several ranges to give the bars an interesting look. G1 G2 G3 g1 g2 g3 Float Float Float The division point between the first and second gradient regions (greater than 0.0). The division point between the second and third gradient regions (greater than G1). The division point between the third and fourth gradient regions (greater than G2 and less than 1.0).

Property name: barPainter Property type: Data Table

LEGEND BAR
Shape
594

used to represent a bar in each legend item.

Property name: legendBar Property type: Data Table

Other Properties
RENDER AS PERCENTAGES
Flag that controls whether the renderer displays the values as percentage of the total across all series. Example of chart that renders percent values:

2000-2013 Tibbo Technology Inc.

446

AggreGate Documentation

This property is valid for Stacked renderer. Property name: renderAsPercentages

Property type: Boolean

CENTER BAR AT START VALUE

Flag that controls whether or not the cluster of bars is shifted so that it centers around the starting x-value returned by the dataset. Property name: centerBarAtStartValue

Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A bar chart created using range axis of Date type. The chart uses a subtitle to cite the data source:

2000-2013 Tibbo Technology Inc.

AggreGate Server

447

A stacked XY bar chart based on a date domain axis:

A chart that shows varying bar widths. The Bar Alignment Factor is negative, and X coordinates of bar's left and rights sides are based on X Low and X High values from the dataset:

2000-2013 Tibbo Technology Inc.

448

AggreGate Documentation

A chart with "floating" bars. The Bar Alignment Factor is negative, and X coordinates of bar's left and rights sides are based on X Low and X High values from the dataset. Use Y Interval is enabled, so bars are drawn from Y Low to Y High dataset values:

A simple histogram with two data series built using an XY bar chart:

2000-2013 Tibbo Technology Inc.

AggreGate Server

449

3.15.10.4.4 Interval Chart

An interval chart displays lines indicating a y-interval corresponding to each x-value. The interval chart is based on XY Plot This is what interval chart looks like:
521

and XY Renderer

554 .

It inherits all their properties.

Dataset
The interval chart supports Custom Data
388

model only.

It has the following Source Data Bindings: Binding Series X Y Low Y High Expected Value Type String Number Number Number Description Textual name of the data series. Numeric value to display along the domain (X) axis. Y-interval lower bound. Y-interval upper bound.

Additional dataset properties:

AUTO SORT
Flag that controls whether the items in the series are automatically sorted into ascending order by x-value. Property name: autoSort Property type: Boolean

ALLOW DUPLICATE X VALUES

Flag that controls whether two or more items in the series can have the same x-value. Property name: allowDuplicateXValues Property type: Boolean

2000-2013 Tibbo Technology Inc.

450

AggreGate Documentation

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 554 .

All properties of a XY Plot

All properties of a XY Renderer

Custom Properties
ADDITIONAL ITEM LABEL GENERATOR
An additional item label generator 530 . If this is non-null, the item label generated will be displayed near the lower yvalue at the Negative Item Label Position. Property name: lowItemLabelGenerator

Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A simple interval chart with one data series:

3.15.10.4.5 Error Chart

An error chart display error bars next to each data item. The error chart is based on XY Plot This is what error chart looks like:
521

and XY Line Renderer

556 .

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

AggreGate Server

451

Dataset
The error chart supports Custom Data
388

model only.

It has the following Source Data Bindings: Binding Series X X Low X High Y Y Low Y High Expected Value Type String Number Number Number Number Number Number Description Textual name of the data series. Numeric value to display along the domain (X) axis. X-error interval lower bound. X-error interval upper bound. Numeric value to display along the range (Y) axis. Y-error interval lower bound. Y-error interval upper bound.

Additional dataset properties:

AUTO SORT
Flag that controls whether the items in the series are automatically sorted into ascending order by x-value. Property name: autoSort Property type: Boolean

ALLOW DUPLICATE X VALUES

Flag that controls whether two or more items in the series can have the same x-value. Property name: allowDuplicateXValues Property type: Boolean

Common Properties

2000-2013 Tibbo Technology Inc.

452
Width
586

AggreGate Documentation
, Height
586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 556 .

All properties of a XY Plot

All properties of a XY Line Renderer

Custom Properties
DRAW X-ERROR
Flag that controls whether or not error bars are drawn for the x-values in the dataset. Property name: drawXError Property type: Boolean

DRAW Y-ERROR
Flag that controls whether or not error bars are drawn for the y-values in the dataset. Property name: drawYError Property type: Boolean

CAP LENGTH
Length of the caps at each end of the error bar for each data value. Property name: capLength Property type: Float

ERROR PAINT
Paint
590

used to draw the error bars. If disabled, the renderer will use the series paint.

Property name: errorPaint Property type: Data Table

ERROR STROKE
Stroke
593

used to draw the error bars. If disabled, the renderer will use the series stoke.

Property name: errorStroke Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
An error chart with Draw X-error disabled and Default Lines Visibility enabled:

2000-2013 Tibbo Technology Inc.

AggreGate Server

453

Almost same as above, but with different settings:

3.15.10.4.6 Deviation Chart

A deviation chart highlights a range of y-values in the background of a series that is typically rendered as a line. The deviation chart is based on XY Plot This is what deviation chart looks like:
521

and XY Line Renderer

556 .

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

454

AggreGate Documentation

Dataset
The deviation chart supports Custom Data It has the following Source Data Bindings: Binding Series X Y Y Low Y High Expected Value Type String Number Number Number Number Description Textual name of the data series. Numeric value to display along the domain (X) axis. Numeric value to display along the range (Y) axis. Y-interval lower bound. Y-interval upper bound.
388

model only.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 556 .

All properties of a XY Plot

All properties of a XY Line Renderer

Custom Properties
ALPHA
Alpha transparency for the interval shading. Property name: alpha Property type: Float

2000-2013 Tibbo Technology Inc.

AggreGate Server

455

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A deviation chart with two data series:

3.15.10.4.7 Vector Chart

A vector chart displays series of vectors in 2D space. Each vector is described by Delta X and Delta Y values. The vector chart is based on XY Plot This is what vector chart looks like:
521

and XY Renderer

554 .

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

456

AggreGate Documentation

Dataset
The vector chart supports Custom Data
388

model only.

It has the following Source Data Bindings: Binding Series X Y Delta X Delta Y Expected Value Type String Number Number Number Number Description Textual name of the data series. Vector base at the domain (X) axis. Vector base at the range (Y) axis. Length of vector projection to the X axis. Length of vector projection to the Y axis.

Additional dataset properties:

AUTO SORT
Flag that controls whether the items in the series are automatically sorted into ascending order by x-value. Property name: autoSort Property type: Boolean

ALLOW DUPLICATE X VALUES

Flag that controls whether two or more items in the series can have the same x-value. Property name: allowDuplicateXValues Property type: Boolean

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties

2000-2013 Tibbo Technology Inc.

AggreGate Server
All Data-related
385

457

properties.
521 . 554 .

All properties of a XY Plot

All properties of a XY Renderer

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A vector chart demo with a large dataset:

3.15.10.4.8 Bubble Chart

A bubble chart draws bubbles of different sizes (diameters) in 2D space. The bubble chart is based on XY Plot This is what bubble chart looks like:
521

and XY Renderer

554 .

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

458

AggreGate Documentation

Dataset
The bubble chart supports Custom Data
388

model only.

It has the following Source Data Bindings: Binding Series X Y Z Expected Value Type String Number Number Number Description Textual name of the data series. X (domain) coordinate of the bubble center. Y (range) coordinate of the bubble center. Z-value, that may be bubble diameter, its length along the X-axis or its length along the Y-axis. These depends on the Scale Type property.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 554 .

All properties of a XY Plot

All properties of a XY Renderer

Custom Properties
SCALE TYPE
Method used to determine the size of the bubbles drawn by this renderer: Scale On Both Axes : bubbles are drawn as ellipses where the width and height of the ellipse is determined by the zvalue scaled against both axes; Scale On Domain Axis : bubbles are drawn as circles where the diameter of the circle is determined by the z-value scaled against the domain axis;

2000-2013 Tibbo Technology Inc.

AggreGate Server

459

Scale On Range Axis: bubbles are drawn as circles where the diameter of the circle is determined by the z-value scaled against the range axis. Property name: scaleType Property type: Integer

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A simple demo bubble chart with one data series:

A bubble chart with item labels and Scale Type set to Scale On Both Axes:

3.15.10.4.9 Financial Chart

A financial chart is used to build Open-High-Low-Close (OHLC) diagrams. The financial chart is based on XY Plot
521

and XY Renderer

554 .

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

460

AggreGate Documentation

This is what financial chart looks like:

Financial chart supports two renderers:

CANDLESTICK RENDERER
A candlestick renderer draws each item from an OHLC dataset as a box with lines extending from the top and bottom. Candlestick charts are typically used to display financial data. The box represents the open and closing prices, while the lines indicate the high and low prices for a trading period (often one day). See example of candlestick renderer on the above image.

HIGH LOW RENDERER

A high-low renderer draws each item in an OHLC Dataset using lines to mark the "high-low" range for a trading period, plus small marks to indicate the "open" and "close" values.

Dataset

2000-2013 Tibbo Technology Inc.

AggreGate Server
The interval chart supports Custom Data
388

461

model only.

It has the following Source Data Bindings: Binding Series Date Open High Low Close Expected Value Type String Data Number Number Number Number Description Textual name of the data series. Date Open value for the date. High value for the date. Low value for the date. Close value for the date.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 554 .

All properties of a XY Plot

All properties of a XY Renderer

Candle Width Calculation

If the Candle Width attribute is negative, the renderer will automatically determine the candle width at drawing time. After the candle width is calculated according to the Auto Width Method, it is then subject to three adjustments. First, the Auto Width Gap is subtracted, then the width is multiplied by the Auto Width Factor, and finally the width is capped according to the Max Candle Width In Milliseconds.

AUTO WIDTH METHOD

Type of candle auto width calculation: Average: bases the width on the default gap between consecutive x-values in the dataset Smallest: bases the width on the smallest gap between consecutive x-values in the dataset This property is valid for Candlestick renderer. Property name: autoWidthMethod Property type: Integer

AUTO WIDTH FACTOR

Factor by which the candle width is multiplied during the auto-width calculation. This property is valid for Candlestick renderer. Property name: autoWidthFactor Property type: Float

AUTO WIDTH GAP

Amount of space to leave on each side of every candle. This property is valid for Candlestick renderer. Property name: autoWidthGap Property type: Float

CANDLE WIDTH
Width of each candle. If the value is negative, then the renderer will automatically determine a width each time the

2000-2013 Tibbo Technology Inc.

462

AggreGate Documentation

chart is redrawn. This property is valid for Candlestick renderer. Property name: candleWidth Property type: Float

MAX CANDLE WIDTH IN MILLISECONDS

Maximum candle width in milliseconds. The default value is equivalent to 20 hours, which is a reasonable value for displaying daily data. This property is valid for Candlestick renderer. Property name: maxCandleWidthInMilliseconds

Property type: Float

Other Properties
UP PAINT
Paint 590 used to fill candles where the closing price is higher than the opening price (that is, where the price has gone up). If this is disabled (null), the renderer will will the candle using the regular series paint. This property is valid for Candlestick renderer. Property name: upPaint Property type: Data Table

DOWN PAINT
Paint 590 used to fill candles where the closing price is lower than the opening price (that is, where the price has gone down). If this is disabled (null), the renderer will will the candle using the regular series paint. This property is valid for Candlestick renderer. Property name: downPaint Property type: Data Table

USE OUTLINE PAINT

This renderer can draw the outline of the candles using either the regular series paint or the series outline paint. Use Outline Paint flag controls whether the renderer uses the series outline paint. This property is valid for Candlestick renderer. Property name: useOutlinePaint Property type: Boolean

DRAW OPEN TICKS

Flag that controls whether or not the open tick is drawn for each data value. This property is valid for High Low renderer. Property name: drawOpenTicks Property type: Boolean

DRAW CLOSE TICKS

Flag that controls whether or not the close tick is drawn for each data value. This property is valid for High Low renderer. Property name: drawCloseTicks Property type: Boolean

OPEN TICK PAINT

Paint
590

used to draw the open tick mark for each data value. If this is disabled (null) then the renderer's series paint is

2000-2013 Tibbo Technology Inc.

AggreGate Server
used instead. This property is valid for High Low renderer. Property name: openTickPaint Property type: Data Table

463

CLOSE TICK PAINT

Paint 590 used to draw the close tick mark for each data value. If this is disabled (null) then the renderer's series paint is used instead. This property is valid for High Low renderer. Property name: closeTickPaint Property type: Data Table

TICK LENGTH
The length of the open and close tick marks. This property is valid for High Low renderer. Property name: tickLength Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

3.15.10.4.10 Block Chart

A block chart draws colored or gray-scale blocks in the 2D space to represent the z-values of the XYZ dataset. The z-values are converted to colors. The block chart is based on XY Plot This is what block chart looks like:
521

and XY Renderer

554 .

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

464

AggreGate Documentation

Block chart supports two renderers:

BLOCK RENDERER
This renderer uses colored rectangular blocks to represent the data items.

SHAPE RENDERER
This renderer uses colored shapes
594

to represent the data items.

2000-2013 Tibbo Technology Inc.

AggreGate Server

465

Dataset
The interval chart supports Custom Data
388

model only.

It has the following Source Data Bindings:

Binding Series X Y Z

Expected Value Type String Number Number Number

Description Textual name of the data series. Data series is represented by a single line (or set of shapes) on the chart. Block position along the domain (X) axis. Block position along the range (Y) axis. Z-value used to calculate the color of block/shape drawn at (X, Y) point.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All Data-related

385

properties.
521 . 554 .

All properties of a XY Plot

All properties of a XY Renderer

Custom Properties
PAINT SCALE
Paint scale is used to convert values within a certain range to colors (Paints There are two types of paint scales: Grayscale paint scale specifies shades of gray to represent the values in a range. For values at the lower end of the range, the scale will return dark grey or black, and for values at the upper end of the range, the scale will return light grey or white. It is also possible to specify the alpha transparency for the returned colors. Paint scale properties: Property Type Lower Bound Name type Type Description
590 ).

Intege Scale type: Grayscale or Lookup. r Lower bound of meaningful values for the scale.

lowerBoun Float d

2000-2013 Tibbo Technology Inc.

466

AggreGate Documentation

Upper Bound Alpha Default Paint Lookup Table

upperBou nd alpha defaultPai nt

Float Float Data Table

Upper bound of meaningful values for the scale. Transparency value for colors generated by Grayscale scale, from 0 (fully transparent) to 255 (fully opaque). Default paint
590

for Lookup scale.

lookupTab Data le Table

Table matching values to colors used by Lookup scale. Contains two fields: Value : z-value; Paint: paint
590

to use for the blocks.

Property name: paintScale Property type: Data Table

PAINT SCALE LEGENDS

The table containing special chart legends (usually just one) displaying the Paint Scales. Properties of a paint scale legend: Property Visible Width Height Margins Padding Frame Position Horizontal Alignment Vertical Alignment Axis Axis Location Axis Offset Strip Width Strip Outline Visible Strip Outline Paint Strip Outline Stroke Background Paint Subdivision Count Property name: Name visible width height margins padding frame position horizontalAlig nment Type Boole an Float Float Data Table Data Table Data Table String String Description Flag that indicates whether or not this legend should be displayed. Preferred width of the legend. Preferred height of the legend. Margin around the outside of the legend's frame. See Rectangle Insets Area of whitespace inside the legend's frame. See Rectangle Insets Border that will be drawn around the legend. See Block Frame
498 . 506 . 506 .

Position of the legend within the chart (Top, Bottom, Left, or Right). Horizontal alignment for the legend. Usually used if Position is Top or Bottom. Vertical alignment for the legend. Usually used if Position is Left or Right. Value axis
493

verticalAlignm String ent axis axisLocation axisOffset stripWidth Data Table String Float Float

that shows the numerical range of the paint scale.

Location of the axis relative to the legend. Offset between the color strip and the axis. See Rectangle Insets Width of the color strip. Flag that controls whether or not an outline is drawn for the color strip. Paint
590 506 .

stripOutlineVis Boole ible an stripOutlinePai Data nt Table stripOutlineStr Data oke Table backgroundPa Data int Table subdivisionCo unt

used to draw the outline for the color strip (if the outline is visible). used to draw the outline for the color strip (if the outline is visible).
590

Stroke

593

Background paint

for the legend.

Intege Number of subdivisions to use when drawing the paint scale. r

paintScaleLegends

Property type: Data Table

2000-2013 Tibbo Technology Inc.

AggreGate Server

467

BLOCK WIDTH
Block width in data units (that is, measured against the domain axis). The default value is 1.0. This property is valid for Block renderer. Property name: blockWidth Property type: Float

BLOCK HEIGHT
Block height in data units (that is, measured against the range axis). The default value is 1.0. This property is valid for Block renderer. Property name: blockHeight Property type: Float

BLOCK ANCHOR
Anchor point on the block that will be aligned to the (x, y) location on the plot. Available anchor values are Center, Top, Bottom, Left, Right, Top Left, Top Right, Bottom Left, and Bottom Right. This property is valid for Block renderer. Property name: blockAnchor Property type: String

DRAW OUTLINES
Flag that controls whether or not the renderer draws outlines for the shapes. This property is valid for Shape renderer. Property name: drawOutlines Property type: Boolean

USE OUTLINE PAINT

Flag that controls whether or not the Outline Paint attribute is used for drawing shape outlines. If this flag is set to false, the regular series paint is used for drawing the outlines. This property is valid for Shape renderer. Property name: useOutlinePaint Property type: Boolean

USE FILL PAINT

Flag that controls whether the regular paint or the fill paint in the renderer is used for filling shapes. This property is valid for Shape renderer. Property name: useFillPaint Property type: Boolean

GUIDE LINES VISIBLE

Flag that controls whether or not guide lines are drawn. This property is valid for Shape renderer. Property name: guideLinesVisible Property type: Boolean

GUIDE LINE PAINT

Paint
590

used to draw the guide lines.

This property is valid for Shape renderer. Property name: guideLinePaint

2000-2013 Tibbo Technology Inc.

468

AggreGate Documentation

Property type: Data Table

GUIDE LINE STROKE

Stroke
593

used to draw the guide lines.

This property is valid for Shape renderer. Property name: guideLineStroke Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A block chart using Date range axis:

Another block chart example:

2000-2013 Tibbo Technology Inc.

AggreGate Server

469

3.15.10.4.11 Mixed XY Chart

A mixed XY chart is a composite chart 488 designed to combine two or more "simple" XY charts 429 within a single plot. These sub-charts share the plot and axes, but each of them has its own dataset and renderer. This is what mixed XY chart looks like:

When a "simple" XY chart is added as a sub-chart to a mixed XY chart, is has the following differences from its "standalone" version: Axes of the sub-chart are added to the axes list of the container chart. The sub-chart has no own axes. Instead, it has references to the parent chart's axes to use for displaying the data. By default, the axes moved from sub-chart to its parent are referenced. The sub-chart has no plot
509 -related

properties, since its data will be rendered on the parent's plot.

489 ,

The sub-chart has no chart common properties properties.

the parent mixed chart has its own set of chart common
586 ,

The sub-chart has no widget component default properties rendered separately.

except for the Bindings property, since it is not

Custom Properties of Sub-charts

Every "simple" XY chart added as a sub-chart to a mixed XY chart supports all trending properties additional properties:
395

and has several

DOMAIN AXIS INDEX

The index of parent mixed chart's domain axis to use. First axis in the parent's domain axes table has index 1. Property name: domainAxisIndex Property type: Integer

RANGE AXIS INDEX

The index of parent mixed chart's range axis to use. First axis in the parent's range axes table has index 1. Property name: rangeAxisIndex Property type: Integer

2000-2013 Tibbo Technology Inc.

470

AggreGate Documentation

Z-ORDER
Z-index of the sub-chart in the parent's plot. Charts with lower order numbers overlap chart's with higher order numbers. Property name: index Property type: Integer

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties All properties of a XY Plot

521 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A mixed chart with a financial sub-chart
459

and a moving average trend

395

sub-chart:

A mixed chart with a line sub-chart

429

and a moving average trend

395

sub-chart:

2000-2013 Tibbo Technology Inc.

AggreGate Server

471

A mixed chart with line

429

and bar

440

sub-charts:

A mixed chart with financial

459

and bar

440

sub-charts:

2000-2013 Tibbo Technology Inc.

472

AggreGate Documentation
397

Another mixed chart with line

and bar

404

sub-charts using different range axes:

A mixed chart with a line sub-chart trend 395 sub-chart:

429

using shape-only rendering (i.e. Default Lines Visible is disabled) and a linear

3.15.10.4.12 Combined Domain XY Chart

A combined domain XY chart is a composite chart single domain axis. This is what combined domain XY chart looks like:
488

allowing two or more "simple" XY charts

429

share a

2000-2013 Tibbo Technology Inc.

AggreGate Server

473

When a "simple" XY chart is added as a sub-chart to a combined domain XY chart, is has the following differences from its "standalone" version: No Domain Axes No Orientation
528 523

and Fixed Domain Axis Space

525

properties, since Domain Axis is a part of parent XY chart.

property, since it inherits the orientation of parent combined chart.

489 ,

No chart common properties

since the parent XY chart has its own set of chart common properties.
586 ,

No widget component default properties

except for the Bindings property, since it is not rendered separately.

Custom Properties of Sub-charts

Every "simple" XY chart added as a sub-chart to a combined domain XY chart has several additional properties:

WEIGHT
The weight determines how much of the parent chart's area is assigned to this sub-chart. For example, if parent has three sub-charts with weights of 1, 2 and 4, the relative amount of space assigned to each sub-chart is 1/7, 2/7 and 4/7 (where the 7 is the sum of the individual weights). Property name: weight Property type: Integer

Z-ORDER
Sub-charts with higher order numbers are placed closer to the shared axis. Property name: index Property type: Integer

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Domain Axes

523

property.
525

Fixed Domain Axis Space

property.

2000-2013 Tibbo Technology Inc.

474

AggreGate Documentation

Custom Properties
ORIENTATION
Chart orientation (Vertical or Horizontal). This orientation is used for all sub-charts. Property name: orientation Property type: String

GAP
The gap between sub-charts. Property name: gap Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A demo showing two sub-charts sharing a common domain axis:

A demo showing two sub-charts that share a common domain axis. Notice also that the top plot has two range axes and a Text Annotation 534 :

2000-2013 Tibbo Technology Inc.

AggreGate Server

475

3.15.10.4.13 Combined Range XY Chart

A combined range XY chart is a composite chart single range axis. This is what combined range XY chart looks like:
488

allowing two or more "simple" XY charts

429

share a

When a "simple" XY chart is added as a sub-chart to a combined range XY chart, is has the following differences from its "standalone" version: No Range Axes No Orientation
524 528

and Fixed Range Axis Space

525

properties, since Range Axis is a part of parent combined chart.

property, since it inherits the orientation of parent combined chart.

489 ,

No chart common properties

since the parent combined chart has its own set of chart common properties.
586 ,

No widget component default properties

except for the Bindings property, since it is not rendered separately.

2000-2013 Tibbo Technology Inc.

476

AggreGate Documentation

Custom Properties of Sub-charts

Every "simple" XY chart added as a sub-chart to a combined range XY chart has several additional properties:

WEIGHT
The weight determines how much of the parent chart's area is assigned to this sub-chart. For example, if parent has three sub-charts with weights of 1, 2 and 4, the relative amount of space assigned to each sub-chart is 1/7, 2/7 and 4/7 (where the 7 is the sum of the individual weights). Property name: weight Property type: Integer

Z-ORDER
Sub-charts with higher order numbers are placed closer to the shared axis. Property name: index Property type: Integer

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Range Axes

524

property.
525

Fixed Range Axis Space

property.

Custom Properties
ORIENTATION
Chart orientation (Vertical or Horizontal). This orientation is used for all sub-charts. Property name: orientation Property type: String

GAP
The gap between sub-charts. Property name: gap Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A demo showing two sub-charts that share a common Date range axis:

2000-2013 Tibbo Technology Inc.

AggreGate Server

477

A demo showing two sub-charts that share a common Value range axis:

A demo showing three plots that share a common Date range axis:

2000-2013 Tibbo Technology Inc.

478

AggreGate Documentation

3.15.10.5 Other Charts

This section describes charts that use non-standard plots
509 .

3.15.10.5.1 Spider Chart

A spider chart displays (Category, Value) data items in a format that resembles a spider web. The spider chart is based on standard Plot Spider chart has no renderer.
509 .

It inherits all its properties.

This is what spider chart looks like:

Dataset
The category line chart supports Custom Data It has the following Source Data Bindings: Binding Series Category Value Expected Value Type String String Number Description Textual name of the data series. Data series is represented by a single-color area (or set of lines) on the chart. Name of category. Each category is represented by a radial line. Numeric value to display for the above series/category. Values are displayed along the radial lines.
388

model only.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties

2000-2013 Tibbo Technology Inc.

AggreGate Server
Source Data
388

479

and Source Data Bindings

509 .

388

properties.

All properties of a Plot

Custom Properties
WEB FILLED
Flag that controls whether the interior of the polygon defined by the data points for each series is filled. Property name: webFilled Property type: Boolean

HEAD PERCENT
Size of the shapes drawn at each data point. This is a percentage of width and height of the plot area. The default value is 0.01 (one percent). Property name: headPercent Property type: Float

START ANGLE
Angle of the first category, in degrees, relative to a radial line extending from the center of the plot horizontally to the right (that is, 3 o'clock on a clock face), in an anti-clockwise direction. The default value is 90.0 which draws the first category at the top of the plot (that is, 12 o'clock). Property name: startAngle Property type: Float

MAX VALUE
Maximum value for display on the axes. Property name: maxValue Property type: Float

DIRECTION
Direction in which the categories are added to the plot: Clockwise or Anticlockwise. The default is Clockwise. Property name: direction Property type: String

INTERIOR GAP
Percentage between 0.0 and 0.40 (forty percent) indicating the amount of whitespace to leave around the plot (some of which is used for the labels). The default value is 0.25. Property name: interiorGap Property type: Float

AXIS LABEL GAP

Gap between the end of each "radial" axis and the corresponding label, expressed as a percentage of the axis length. The default value is 0.10 (ten percent). Property name: axisLabelGap Property type: Float

AXIS LINE PAINT

Paint
590

used to draw the radial axes lines.

Property name: axisLinePaint Property type: Data Table

AXIS LINE STROKE

2000-2013 Tibbo Technology Inc.

480
Stroke
593

AggreGate Documentation
used to draw the radial axes lines.

Property name: axisLineStroke Property type: Data Table

DEFAULT SERIES PAINT

Default series paint
590

that is used if there is no custom setting for a series.

Property name: baseSeriesPaint Property type: Data Table

DEFAULT SERIES OUTLINE PAINT

Default series outline paint 590 is used to draw the outline of the shape at each data point. It is valid if there is no custom setting for a series. Property name: baseSeriesOutlinePaint

Property type: Data Table

DEFAULT SERIES OUTLINE STROKE

Default series outline stroke custom setting for a series.
593

is used to draw the outline of the shape at each data point. It is valid if there is no

Property name: baseSeriesOutlineStroke Property type: Data Table

LEGEND ITEM SHAPE

Shape
594

used for each legend item.

Property name: legendItemShape Property type: Data Table

LABEL FONT
Font
590

used to display category labels.

Property name: labelFont Property type: Data Table

LABEL PAINT
Paint
590

used to display category labels.

Property name: labelPaint Property type: Data Table

SERIES PAINT
The table defining paints for individual data series. Property Index Series Paint Name index Type Description

Intege Series index. r Paint

590

seriesPain Data t Table

to use for the series.

Property name: seriesPaint Property type: Data Table

SERIES OUTLINE PAINT

The table defining outline paints for individual data series.

2000-2013 Tibbo Technology Inc.

AggreGate Server

481

Property Index Series Outline Paint

Name index

Type

Description

Intege Series index. r Outline paint

590

seriesOutli Data nePaint Table

to use for the series shapes.

Property name: seriesOutlinePaint Property type: Data Table

SERIES OUTLINE STROKE

The table defining outline strokes for individual data series. Property Index Series Outline Stroke Property name: Name index Type Integ er Description Series index. Outline stroke
593

seriesOutlin Data eStroke Table

to use for the series shapes.

seriesOutlineStroke

Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

Additional Examples
A spider chart with three data series:

3.15.10.5.2 Polar Chart

A polar chart displays (X, Y) data items using polar coordinates. The polar chart is based on standard Plot This is what polar chart looks like:
509

and standard Renderer

542 .

It inherits all their properties.

2000-2013 Tibbo Technology Inc.

482

AggreGate Documentation

Dataset
The category line chart supports Custom Data It has the following Source Data Bindings: Binding Series Theta Radius Expected Value Type String Number Number Description Textual name of the data series. Data series is represented by a single-color line on the chart. Data item angle in degrees. Data item radius (distance from plot center) for the above series/angle.
388

model only.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

509 . 542 .

388

properties.

All properties of a Plot

All properties of a Renderer

Custom Properties
AXIS
Value axis 493 that provides the value scale for the plot. The axis will extend from the center of the plot towards the right hand side of the chart. Property name: axis Property type: Data Table

Common Events

2000-2013 Tibbo Technology Inc.

AggreGate Server
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

483

Mouse Key Released

Angle Gridlines
The "angle gridlines" are the optional lines radiating out from the center of the chart.

ANGLE GRIDLINES VISIBLE

Flag that controls whether or not the angle gridlines are displayed. Property name: angleGridlinesVisible

Property type: Boolean

ANGLE TICK UNIT

Angle between two radial axes in degrees. Tick unit that controls the spacing between the angular grid lines. Property name: angleTickUnit Property type: Float

ANGLE GRIDLINE STROKE

Stroke
593

used to display the angle gridlines. angleGridlineStroke

Property name: Property type:

ANGLE GRIDLINE PAINT

Paint
590

used to display the angle gridlines.

Property name: angleGridlinePaint Property type: Data Table

ANGLE LABELS VISIBLE

Flag that controls whether or not the angle labels are visible. Property name: angleLabelsVisible Property type: Boolean

ANGLE LABEL FONT

Font
590

for the angle labels.

Property name: angleLabelFont Property type: Data Table

ANGLE LABEL PAINT

Paint
590

for the angle labels.

Property name: angleLabelPaint Property type: Data Table

Radius Gridlines
The "radius gridlines" are drawn as circles at a regular interval that is controlled by the size of the tick unit on the plot's axis.

RADIUS GRIDLINES VISIBLE

Flag that controls whether or not the radius gridlines are visible.

2000-2013 Tibbo Technology Inc.

484

AggreGate Documentation
radiusGridlinesVisible

Property name:

Property type: Boolean

RADIUS GRIDLINE STROKE

Stroke
593

used to draw the radius gridlines. radiusGridlineStroke

Property name:

Property type: Data Table

RADIUS GRIDLINE PAINT

Paint
590

used to draw the radius gridlines.

Property name: radiusGridlinePaint Property type: Data Table

Corner Text Items

Plot provides an option to add one or more short text items (called "corner text items") to the lower right corner of the plot.

CORNER TEXT ITEMS

A list of text string to display in the lower right corner. Property name: cornerTextItems Property type: Data Table

SERIES FILLED
The table defining whether or not each series is drawn as a "filled" polygon: Property Index Series Filled Name index seriesFille d Type Description

Intege Series index. r Boole an Flag indicating whether or not the area "inside" the series should be filled.

Property name: seriesFilled Property type: Data Table

Additional Examples
A polar chart with two data series:

2000-2013 Tibbo Technology Inc.

AggreGate Server

485

3.15.10.5.3 Pie Chart

A pie chart is a circular chart divided into sectors, illustrating proportion. The arc length of each sector (and consequently its central angle and area), is proportional to the value it represents. The pie chart is based on Pie Plot
536 .

It inherits all its properties.

Pie chart has no renderer.

This is what pie chart looks like:

Dataset
The pie chart supports Custom Data
388

model only.

It has the following Source Data Bindings: Binding Series Value Expected Value Type String Number Description Textual name of the data series. Data series is represented by individual pie section. The value for the series, i.e. pie section size. There is no need to normalize the values and make their sum equal to 1 or 100%, this is done automatically by the chart.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

536 .

388

properties.

All properties of a Pie Plot

Custom Properties

2000-2013 Tibbo Technology Inc.

486

AggreGate Documentation

3D
Flag that control whether or not the chart is rendered in 3D mode. Example of 3D pie chart:

3D pie chart does not support exploded sections.

Property name: chart3D Property type: Boolean

DEPTH FACTOR
Depth factor specifies the size of the 3D effect as a percentage of the height of the plot area. The default value is 0.12 (twelve percent). This property is valid for 3D mode only. Property name: depthFactor Property type: Float

DARKER SIDES
Flag that controls whether or not the sides of the pie plot are drawn using a darker color. This property is valid for 3D mode only. Property name: darkerSides Property type: Boolean

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

3.15.10.5.4 Ring Chart

A ring chart is an adaptation of a pie chart The ring chart is based on Pie Plot
536 . 485 ,

where a hole is left in the middle of the "pie".

It inherits all its properties.

2000-2013 Tibbo Technology Inc.

AggreGate Server

487

Ring chart has no renderer.

This is what ring chart looks like:

Dataset
The ring chart supports Custom Data
388

model only.

It has the following Source Data Bindings: Binding Series Value Expected Value Type String Number Description Textual name of the data series. Data series is represented by individual ring section. The value for the series, i.e. ring section size. There is no need to normalize the values and make their sum equal to 1 or 100%, this is done automatically by the chart.

Common Properties
Width
586

, Height

586

, Bindings

586 , 489 .

Visible

587 ,

Background

587 ,

Border

587

All Common Chart Properties Source Data

388

and Source Data Bindings

536 .

388

properties.

All properties of a Pie Plot

Custom Properties
SEPARATORS VISIBLE
Flag that controls whether or not the separators between sections are visible. Property name: separatorsVisible

Property type: Boolean

2000-2013 Tibbo Technology Inc.

488

AggreGate Documentation

SEPARATOR STROKE
Stroke
593

used to draw the separator lines. separatorStroke

Property name:

Property type: Data Table

SEPARATOR PAINT
Paint
590

used to draw the separator lines.

Property name: separatorPaint Property type: Data Table

INNER SEPARATOR EXTENSION

Length of the separator line drawn inside the ring for each section. The value is a percentage of the ring depth (the default is 0.20, or 20%). Property name: innerSeparatorExtension

Property type: Float

OUTER SEPARATOR EXTENSION

Length of the separator line drawn outside the ring for each section. The value is a percentage of the ring depth (the default is 0.20, or 20%). Property name: outerSeparatorExtension

Property type: Float

SECTION DEPTH
Section depth as a percentage of the plot's radius. The default value is 0.20 (twenty percent). Property name: sectionDepth Property type: Float

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597 All relevant chart events
507 . 596 , 597 ,

Mouse Key Released

3.15.10.6 Composite Charts

Composite charts were designed for combining other ("simple") charts together. There are two types of composite charts: Mixed charts, allowing several simple charts to share a single plot and axes, while each of them has its own dataset and renderer . Combined charts, designed to share a single common axis between several simple charts having separate plots , datasets and renderers.

Mixed Charts
There are two types of mixed charts: Mixed Category Chart Mixed XY Chart
469 422 ,

joining several Category Charts

429

397

, joining several XY Charts

Combined Charts
There are four types of combined charts: Combined Domain Category Chart
425 ,

allowing several Category Charts

397

to share a single domain axis

2000-2013 Tibbo Technology Inc.

AggreGate Server
Combined Range Category Chart Combined Domain XY Chart Combined Range XY Chart
472 , 427 ,

489

allowing several Category Charts

429

397

to share a single range axis

allowing several XY Charts

to share a single domain axis

475 ,

allowing several XY Charts

429

to share a single range axis

Adding Sub-charts To Composite Charts

Technically, composite chart act as a container component
376

for its sub-charts.

To add new sub-chart to a composite chart in a GUI Builder 827 , drag a chart of proper type from the Component Palette 834 and drop it over the composite chart. A new sub-chart will be added.

Editing and Deleting Sub-charts

Properties of a sub-chart may be accessed at any time by selecting this sub-chart in the Resources Window To delete a sub-chart in a GUI Builder, select it in the Resources Window the context menu.
833 833 .

and press Delete, or select Delete from

3.15.10.7 Chart Common Properties

This section describes properties that are supported by all charts.

Chart Border
A border can be drawn around the outside of a chart, if required. By default, no border is drawn, since in many cases component's default border 587 can be used instead.

CHART BORDER VISIBLE

A flag that controls whether or not an "internal" single-line border is drawn around the outside of the chart. Property name: borderVisible Property type: Integer

CHART BORDER PAINT

The paint
590

used to draw the chart's "internal" border.

Property name: borderPaint Property type: Data Table

CHART BORDER STROKE

The stroke
593

used to draw the chart's "internal" border.

Property name: borderStroke Property type: Data Table

Other Properties
PADDING
The padding between the chart border and the chart drawing area. See Rectangle Insets Property name: padding Property type: Data Table
506 .

TITLE
The chart's title
506

Property name: title Property type: Data Table

SUBTITLES

2000-2013 Tibbo Technology Inc.

490

AggreGate Documentation
506 .

The list of chart's subtitles

Property name: textSubtitles Property type: Data Table

LEGENDS
The list of chart's legends
500 .

Property name: legendSubtitles Property type: Data Table

SUBTITLE IMAGES
The list of chart's subtitle images Property name: imageSubtitles Property type: Data Table
498 .

ANTI-ALIAS
The use of a technique called anti-aliasing can improve the appearance of the chart by "smoothing" the edges of lines and shapes. Using anti-aliasing for drawing operations is usually slower, but the results often look better. Property name: antiAlias Property type: Boolean

3.15.10.7.1 Axis
This section covers basic properties of any chart axis. The base axis features: Axis Label: The axis label typically describes what an axis is measuring (for example, "Sales in US$"). Axis Line: The axis draws a line along the edge of the plot's data area. Tick Marks: small marks at regular intervals to show the scale of values displayed by the axis. Tick Labels : textual descriptions for the tick marks. Note that the category plot 511 and XY plot 521 classes also draw an outline around the data area. The outline is drawn before (under) the axis line(s). The plot outline stroke and paint are described in the Plot Border 510 section.

Axis Properties
Property Visible Label Label Font Label Paint Label Insets Label Angle Axis Line Visible Axis Line Paint Name visible label labelFont labelPaint labelInsets labelAngle axisLineVisible axisLinePaint Type Boole an Description Flag that controls whether or not the axis is visible.

String The axis label typically describes what an axis is measuring (for example, "Sales in US$"). If value is NULL, no label is displayed. Data Table Data Table Data Table Float Boole an Data Table Font Paint
590

used to display the axis label. used to display the axis label. for the axis label.

590

Insets

506

Angle of rotation for the axis label (in degrees). Flag that controls whether or not a line is drawn along the edge of the data area by the axis. Paint
590

used to draw the axis line.

2000-2013 Tibbo Technology Inc.

AggreGate Server

491

Axis Line Stroke Tick Labels Visible Tick Label Font Tick Label Paint Tick Label Insets Tick Marks Visible Tick Mark Paint

axisLineStroke tickLabelsVisibl e tickLabelFont tickLabelPaint tickLabelInsets

Data Table Boole an Data Table Data Table Data Table

Stroke

593

used to draw the axis line.

Flag that controls whether or not the tick labels are visible. Tick label font
590 .

Tick label paint

590 .

Blank space around each tick label. See Rectangle Insets Flag that controls whether or not tick marks are visible. Paint
590

506 .

tickMarksVisible Boole an tickMarkPaint Data Table Data Table Float

used to draw the tick marks. used to draw the tick marks.

Tick Mark Stroke tickMarkStroke Tick Mark Inside Length Tick Mark Outside Length tickMarkInsideL ength

Stroke

593

Length of the tick mark on the inside of the data area. Length of the tick mark on the outside of the data area. A flag that indicates whether or not minor tick marks are visible for the axis. The number of minor ticks per major tick unit. This is an override field, if the value is > 0 it is used, otherwise the axis refers to the Minor Tick Count in the current Tick Unit. Length of the minor tick mark inside the data area (zero permitted). Length of the minor tick mark outside the data area (zero permitted).

tickMarkOutside Float Length

Minor Tick Marks minorTickMarks Boole Visible Visible an Minor Tick Count minorTickCount Integ er Minor Tick Mark Inside Length Minor Tick Mark Outside Length minorTickMarkI nsideLength minorTickMark OutsideLength Float Float

3.15.10.7.1.1 Category Axis

A category axis is used as the domain axis in a category plot 511 . Categories are displayed at regular intervals along the axis, with a gap before the first category (the lower margin), a gap after the last category (the upper margin) and a gap between each category (the category margin).

Properties
See Axis
490

for the list of generic axis properties.

Category axis has the following additional properties: Property Type Lower Margin Name type lowerMargin Type Intege r Float Description Axis type: Category Axis or Extended Category Axis. Lower margin for the axis, as a percentage of the total axis length.

2000-2013 Tibbo Technology Inc.

492

AggreGate Documentation

The default value is 0.05 (five percent). Upper Margin Category Margin upperMargin categoryMargin Float Float Upper margin for the axis, as a percentage of the total axis length. The default value is 0.05 (five percent). Category margin for the axis. The margin is a percentage of the axis length (for example, 0.20 for a twenty percent margin). The overall margin is distributed over N-1 gaps where N is the number of categories displayed on the axis. Maximum Category Label Lines Maximum Category Label Width Ratio Category Label Position Offset Category Label Positions Category Label Properties maximumCategory Intege LabelLines r By default category labels are displayed on a single line and truncated if necessary. However, multi-line labels are supported. This option specifies the maximum number of lines for displaying category labels. A ratio that is multiplied by the width of one category to determine the maximum label width. Zero (0.0) or negative value deactivates this setting. Offset between the axis and the category label. A tabular property that controls the position, alignment and rotation of the category labels along the axis. See Category Label Positions 492 . A tabular property that controls font, paint and tooltips of individual category labels. See Category Label Properties 493 .

maximumCategory Float LabelWidthRation categoryLabelPositi Intege onOffset r categoryLabelPositi Data ons Table categoryLabelProp erties Data Table

Category Label Positions

When the axis needs to determine where it is going to draw the category labels, it will select one of those instances depending on the current location of the axis (at the top, bottom, left or right of the plot). It is the attributes of the Category Label Position record that ultimately determine where the labels are drawn. The first attribute is an anchor point relative to a notional category rectangle that is computed by the axis. Within this rectangle, an anchor point is specified.

The second attribute is a text anchor, which defines a point on the category label which is aligned with the anchor point on within the category rectangle mentioned previously. This is specified using the Text Block Anchor class. Two additional attributes define a rotation anchor point and a rotation angle. These are applied once the label text has been positioned using the previous two attributes. A width ratio and width ratio type control the maximum width of the category labels.

CATEGORY LABEL POSITION PROPERTIES

Property Anchor Name anchor Type Description

String Used to determine the point on the axis against which the category label is aligned. This is specified relative to a rectangular area that the Category Axis allocates for the category. String Determines the point on the category label that is aligned with the category anchor. String Point on the category label about which the label is rotated (note that there may be no rotation). Float Angle of the rotation, specified in degrees.

Label Anchor Rotation Anchor Angle

labelAnchor rotationAnch or angle

2000-2013 Tibbo Technology Inc.

AggreGate Server

493

Width Type

widthType

String Controls whether the maximum width for the labels is relative to the width of the category label rectangle (Category) or the length of the range axis (Range). The last option is useful when labels are rotated so that they are perpendicular to the category axis. Float Maximum category label width ratio, measured as a percentage of either the category label rectangle or the length of the range axis (see the previous setting).

Width Ratio widthRatio

Category Label Properties

This setting defines how individual category labels are drawn on an axis. Property Category Key Font Paint Tooltip Name key font paint tooltip Type Description

String Category to apply label settings for. Data Table Data Table Font Paint
590

for the specified category's label. for the specified category's label.

590

String Tooltip for the specified category's label.

Extended Category Axis is a subtype of the category axis Additional properties of an extended category axis: Property Sub Labels Sub Label Font Sub Label Paint Name subLabels Type Data Table Description

493

that allows sub-labels to be displayed with the categories.

A table of sub-labels, each of them having a Category Key and Label text. Font Paint
590

subLabelFont Data Table subLabelPain Data t Table

used to display the sub-labels. used to display the sub-labels.

590

3.15.10.7.1.2 Value Axis

An axis that displays numbers or dates (internally represented as numeric values). Usage: In a Category Plot In an XY Plot
521 511 ,

the default range axis is a Value Axis.

, both the domain and range axes are of Value Axis type by default.

The Axis Range

The axis range defines the highest and lowest values that will be displayed on axis. On a chart, it is typically the case that data values outside the axis range are clipped, and therefore not visible on the chart.

AUTOMATIC BOUNDS CALCULATION

By default, the axis is configured to automatically calculate ranges so that all of the data in your dataset is visible. It does this by determining the highest and lowest values in your dataset, adding a small margin (to prevent the data being plotted right up to the edge of a chart), and setting the axis range. To control whether or not the axis range is automatically adjusted to fit the available data, use Auto Range parameter.

Properties
See Axis
490

for the list of generic axis properties.

2000-2013 Tibbo Technology Inc.

494

AggreGate Documentation

Value axis has the following additional properties: Property Type Inverted Vertical Tick Labels Lower Margin Name type inverted verticalTickLa bels lowerMargin Type Integ er Boole an Boole an Float Description Axis type: Number Axis, Date Axis, Period Axis, Logarithmic Axis, or Symbol Axis . Flag that controls whether or not the axis scale is inverted. Flag that controls whether or not the tick labels are rotated by 90 degrees. It is usually set to fit more labels in. Lower margin for the axis, as a percentage of the total axis length. The default value is 0.05 (five percent). Note that the margin is only applied when the axis bounds are automatically calculated. If you set the axis bounds manually then the margins are ignored. Upper Margin upperMargin Float Upper margin for the axis, as a percentage of the total axis length. The default value is 0.05 (five percent). Note that the margin is only applied when the axis bounds are automatically calculated. If you set the axis bounds manually then the margins are ignored. Positive Arrow Visible Negative Arrow Visible Up Arrow Down Arrow Left Arrow Right Arrow Auto Tick Unit Selection Auto Range Fixed Auto Range Auto Range Minimum Size positiveArrow Visible negativeArro wVisible upArrow downArrow leftArrow rightArrow autoTickUnitS election autoRange fixedAutoRan ge Boole an Boole an Data Table Data Table Data Table Data Table Boole an Boole an Float Flag that controls whether or not an arrow is drawn at the positive end of the scale. Flag that controls whether or not an arrow is drawn at the negative end of the scale. Shape Shape Shape Shape
594

used to draw an arrow at the end of an axis pointing upwards. used to draw an arrow at the end of an axis pointing downwards. used to draw an arrow at the end of an axis pointing leftwards. used to draw an arrow at the end of an axis pointing rightwards.

594

594

594

Flag controlling whether or not the tick units are selected automatically. Flag that controls whether or not the axis range is automatically adjusted to fit the available data values. If specified (non-zero), the auto-range is calculated by subtracting this value from the maximum domain value in the dataset. The smallest axis range allowed when it is automatically calculated.

autoRangeMin Float imumSize

PERIOD AXIS LABEL INFO

The axis supports one or more "bands" of labels, where each band is defined by the following properties: Property Period Padding Date Format Label Font Label Paint Draw Dividers Name periodClass padding dateFormat labelFont labelPaint drawDividers Type Description

String Time period type: Year, Month, Day, Hour, Minute, Second, or Millisecond. Data Table Padding that controls the minimum space between labels. See Rectangle Insets 506 .
1321

String A date/time formatting pattern Data Table Data Table Boole an Font
590

for the labels on the band.

used to display labels for each time period.

Paint 590 that is used as the foreground color when displaying labels for each time period. Flag that determines whether or not dividers are drawn between time periods.

2000-2013 Tibbo Technology Inc.

AggreGate Server

495

Divider Stroke dividerStroke Divider Paint dividerPaint

Data Table Data Table

Stroke Paint

593

used to draw dividers between time periods.

590

used to draw dividers between time periods.

Number Axis is a subtype of the value axis Additional properties of a number axis: Property Name Type Integ er Data Table

493

that displays numerical data along a linear scale.

Description The type for auto-selected tick units: Integer or Float. This option allows to configure tick units if Auto Tick Unit Selection is disabled. There are two fields: Size. A floating point number specifying the distance between two tick marks. Minor Tick Count. An integer count of minor tick marks between two major tick marks.

Auto Tick Units numberTickU nits Tick Unit numberTickU nit

Tick Unit Format Override Range Type Range Default Auto Range Auto Range Includes Zero

numberForma String A number formatting pattern tOverride rangeType

1322

for the tick labels on the axis.

String This setting is used to restrict the axis to display only positive values, or only negative values. Possible values are Full , Positive and Negative. A manually set axis range. Specified as Lower Bound and Upper Bound float values. This setting is available if Auto Range is disabled. An axis range to use if the dataset has no data. Specified as Lower Bound and Upper Bound float values. If Auto Range flag to true (so that the axis range automatically adjusts to fit the current data), you may also want to set this flag to ensure that the axis range always includes zero. Note that some renderers (for example, Bar Renderer) have a flag to control the inclusion of some "base" value in the axis range -since the base value often defaults to zero, you may need to set the flag in the renderer also, to get the required range for the axis.

numberRange Data Table defaultNumbe Data rAutoRange Table autoRangeInc ludesZero Boole an

Auto Range Sticky Zero

autoRangeSti ckyZero

Boole an

Flag that controls whether or not the axis margin is truncated if the zero value falls within the margin.

Date Axis is a subtype of the value axis 493 that displays date/time values. It is designed to be flexible about the range of dates/times that it can display -- anything from a few milliseconds to several centuries can be handled. Although the axis displays dates for tick labels, at the lowest level it is still working with floating point numbers obtained from the plot's dataset. The values are interpreted as the number of milliseconds since 1 January 1970. Additional properties of a date axis: Property Tick Unit Name dateTickUnit Type Data Table Description This option allows to configure tick units if Auto Tick Unit Selection is disabled. There are four fields: Unit Type. Year, Month, Day, Hour, Minute, Second, or Millisecond. Multiple . Unit multiple, i.e. the number of units between two adjacent tick marks. Tick Unit dateFormatO String A date/time formatting pattern
1321

for the tick labels on the axis.

2000-2013 Tibbo Technology Inc.

496

AggreGate Documentation

Format Override Range Default Auto Range Tick Mark Position Time Zone

verride dateRange defaultDateA utoRange Data Table Data Table A manually set axis range. Specified as Lower Bound and Upper Bound timestamps. This setting is available if Auto Range is disabled. An axis range to use if the dataset has no data. Specified as Lower Bound and Upper Bound timestamps. Tick mark position: Start , Middle or End of the time period. Time zone for the axis, which affects the conversion of date values to string labels.

tickMarkPositi String on timeZone String

Period Axis is a subtype of the value axis

493

that displays date/time values and has the following features:

Multiple label bands, where each band is divided up into time periods; Automatic range calculation based on (whole unit) time periods; A user specified time zone.

In the above example, there are three bands. The first band is split into 1 day time periods, the second into 1 month periods, and the third into 1 year periods. Additional properties of a period axis: Property Time Zone Locale Auto Range Time Period Major Tick Time Period Minor Tick Time Period Minor Tick Mark Stroke Minor Tick Mark Paint Name timeZone locale autoRangeTi mePeriodClas s majorTickTim ePeriodClass minorTickTim ePeriodClass minorTickMar kStroke minorTickMar kPaint Type Description

String Time Zone that is used to "peg" time periods to the absolute time line. String Locale used to format timestamps into tick label strings. String Time period used when the axis range is calculated automatically: Year, Month, Day, Hour, Minute, Second, or Millisecond. The axis range will always be a whole number of periods. String Time period used to determine the spacing of the major tick marks: Year, Month, Day, Hour, Minute, Second, or Millisecond. String Time period used to determine the spacing of the minor tick marks: Year, Month, Day, Hour, Minute, Second, or Millisecond. Data Table Data Table Stroke Paint
593

used to draw the minor tick marks.

590

used to draw the minor tick marks.

2000-2013 Tibbo Technology Inc.

AggreGate Server

497

Label Info

labelInfo

Data Table

Label band definitions, see below.

Logarithmic Axis is a subtype of the value axis display positive values. Additional properties of a logarithmic axis: Property Base Name base Type Float

493

that displays values using a logarithmic scale. This axis can only

Description base for the logarithm calculation Returns the smallest (positive) value that will be displayed on the axis. The default value is 1E-100. This option allows to configure tick units if Auto Tick Unit Selection is disabled. There are two fields: Size. A floating point number specifying the distance between two tick marks. Minor Tick Count. An integer count of minor tick marks between two major tick marks.

Smallest Value smallestValue Float Tick Unit tickUnit Data Table

Override Format Base Label Power Label Show Base Exponent Format

overrideForm at baseLabel powerLabel showBase exponentFor matOverride

Boole an

Enables custom tick label formatting.

String Logarithm base label. String Logarithm power label. Boole an Flag indicating whether or not to print logarithm base on the labels.
1322 .

String Logarithm exponent format

Symbol Axis is a subtype of the value axis Additional properties of a symbol axis: Property Symbols Name symbols Type Data Table

493

that maps integer values (starting at zero) to symbols (strings).

Description A table with value labels, that has two fields: Value to mark with a label (Integer) Symbol , i.e. text of a label (String)

Grid Bands Visible Grid Band Paint

gridBandsVisi ble gridBandPaint

Boole an Data Table Data Table

Flag that controls whether or not grid bands are painted for alternate tick values. Paint Paint
590

used to color alternate bands within the plot area. used to all alternate bands within the plot area.

Grid Band gridBandAlter Alternate Paint natePaint A line

397

590

chart where the range axis is a Symbol Axis:

2000-2013 Tibbo Technology Inc.

498

AggreGate Documentation

3.15.10.7.2 Block Frame

A simple border that can be assigned to different chart blocks, such as title.

Properties
Property Type Insets Paint Stroke Name type insets paint stroke Type Description

Intege Frame type: Line Border or Block Border. r Data Table Data Table Data Table Available drawing space for the border. See Rectangle Insets Paint
590 506 .

that is used to draw the border. that is used to draw the border.

Stroke

593

3.15.10.7.3 Image Subtitle

A chart image subtitle displays an image. This is typically used to display a logo or other image on a chart.

Image Subtitle Properties

Property Visible Image Auto Size Width Height Margins Padding Name visible image autoSize width height margins padding Type Boole an Data Block Boole an Float Float Data Table Data Table Description Flag that indicates whether or not this title should be displayed. Image for this subtitle. Use size of image itself instead of Width/Height parameters. Preferred width of the title. Preferred height of the title. Margin around the outside of the title's frame. See Rectangle Insets Area of whitespace inside the title's frame. See Rectangle Insets
506 .

506 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

499

Frame Position Horizontal Alignment Vertical Alignment

frame position horizontalAlig nment

Data Table String String

Border that will be drawn around the title. See Block Frame

498 .

Position of the title within the chart (Top, Left, Bottom, or Right). Horizontal alignment for the title. Usually used if Position is Top or Bottom. Vertical alignment for the title. Usually used if Position is Left or Right.

verticalAlignm String ent

3.15.10.7.4 Item Label Position

Item Label Position is used to specify the position of item labels on a chart. Four properties are used to specify the position.

Properties
Property Name Typ Description e An item label anchor is used by a renderer to calculate a fixed point (the item label anchor point) relative to a data item on a chart. This point becomes a reference point that an item label can be aligned to. There are 25 anchors available. The numbers 1 to 12 are used and roughly correspond to the positions of the hours on a clock face. In addition, positions are defined relative to an "inside" ring and an "outside" ring - see the below image for an illustration. With 12 points on the inside circle, 12 points on the outside circle, plus a "center" anchor point, in all there are 25 possible anchor points. For some renderers (e.g. Bar Renderer), the circular arrangement of anchor points doesn't make sense, so the renderer is free to modify the anchor positions.

Item Label itemLab Stri Anchor elAnchor ng

Text Anchor

textAnch Stri or ng

A point relative to the item label text which will be aligned with the item label anchor point above. Available anchor values are Center, Center Left, Center Right, Top Center, Top Left, Top Right, Bottom Center, Bottom Left, Bottom Right, Baseline Center, Baseline Left, Baseline Right, Half Ascent Center, Half Ascent Left, Half Ascent Right.

Rotation Anchor

rotation Anchor

Stri ng

Another point somewhere on the item label about which the text will be rotated (if there is a rotation). Available anchor values are Center, Center Left, Center Right, Top Center, Top Left, Top Right, Bottom Center, Bottom Left, Bottom Right, Baseline Center, Baseline Left, Baseline Right, Half Ascent Center, Half Ascent Left, Half Ascent Right.

2000-2013 Tibbo Technology Inc.

500

AggreGate Documentation

Angle

angle

Floa Specifies the amount of rotation about the rotation point. t

3.15.10.7.5 Legend
A legend displays labels for the series in a chart, usually along with a small graphic item that identifies the series (by color and/or style). It is even possible to add more than one legend to a chart. The legend will typically contain one legend item for each series displayed in a chart. The item has a small graphic that identifies the series in the chart, and a label that corresponds to the series name.

Legend Properties
Property Visible Width Height Margins Padding Frame Position Horizontal Alignment Vertical Alignment Background Paint Item Font Item Label Padding Item Paint Legend Item Graphic Anchor Name visible width height margins padding frame position horizontalAlig nment Type Boole an Float Float Data Table Data Table Data Table String String Description Flag that indicates whether or not this legend should be displayed. Preferred width of the legend. Preferred height of the legend. Margin around the outside of the legend's frame. See Rectangle Insets Area of whitespace inside the legend's frame. See Rectangle Insets Border that will be drawn around the legend. See Block Frame
498 . 506 . 506 .

Position of the legend within the chart (Top, Bottom, Left, or Right). Horizontal alignment for the legend. Usually used if Position is Top or Bottom. Vertical alignment for the legend. Usually used if Position is Left or Right. Background paint Font
590 590

verticalAlignm String ent backgroundPa Data int Table itemFont itemLabelPad ding itemPaint legendItemGr aphicAnchor Data Table Data Table Data Table String

for the legend.

for the legend item labels.

506 .

Padding for the item labels. See Rectangle Insets Legend item paint
590 .

The location of the item graphic within its rectangle is determined by two attributes, the anchor point and the location. The anchor point is a point on the item graphic that can be aligned with the location point. Available anchor values are Center, Top, Bottom, Left, Right, Top Left, Top Right, Bottom Left, and Bottom Right.

Legend Item Graphic Edge Legend Item Graphic Location Legend Item Graphic Padding

legendItemGr aphicEdge legendItemGr aphicLocation

String String

Location of the item graphic relative to its text (Top, Bottom, Left, or Right). Location of item graphic, relative to the bounding box of the legend item. Available location values are Center, Top, Bottom, Left, Right, Top Left, Top Right, Bottom Left, and Bottom Right.

legendItemGr aphicPadding

Data Table

Padding around the legend item graphic. See Rectangle Insets

506 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

501

3.15.10.7.5.1 Legend Item

A Legend Item records the attributes of an item that should appear in a chart legend Legend item consist of: Item shape (e.g. rectangle or star) Item line those look usually matches the line used to render series data Item label used to represent series name
500 .

Properties
Property Series Key Label Label Font Label Paint Tool Tip Text Shape Visible Shape Shape Filled Fill Paint Shape Outline Visible Outline Paint Outline Stroke Line Visible Line Line Stroke Line Paint Name seriesKey label labelFont labelPaint toolTipText shapeVisible shape shapeFilled fillPaint Type String String Data Table Data Table String Description Key for the series that this legend item represents. Legend item label. Font Paint
590

used to draw the item label. used to draw the item label.

590

Tool tip text for the legend item.

Boolean Flag that controls whether or not the legend item shape should be displayed. Data Table Shape
594

to display as the graphic for this legend item.

Boolean Flag that controls whether or not the legend item shape should be filled. Data Table Paint
590

used to draw the marker.

shapeOutlineVi Boolean Flag that controls whether or not the legend item shape should have its sible outline drawn. outlinePaint outlineStroke lineVisible line lineStroke linePaint Data Table Data Table Paint
590

used to draw the marker outline. used to draw the marker outline.

Stroke

593

Boolean Flag that controls whether or not a line is drawn as part of the legend item graphic. Data Table Data Table Data Table Line, if any, to be drawn for the legend item graphic. See Shape Stroke Paint
593 594 .

used to draw the line for the legend item graphic.

590

used to draw the line for the legend item graphic.

3.15.10.7.6 Marker
Markers are used to highlight particular values or value ranges against either the domain or range axes. Markers can be displayed with or without labels. The following image below illustrates marker usage:

2000-2013 Tibbo Technology Inc.

502

AggreGate Documentation

LABEL POSITION
The image below illustrates how the marker label anchor position is calculated relative to the marker's bounds. One of the nine potential anchors is selected via the Label Anchor property, and the margin between the marker's bounds and the potential anchor points is determined by the Label Offset and Label Offset Type methods. Label Offset Type is Contract:

Label Offset Type is Expand:

2000-2013 Tibbo Technology Inc.

AggreGate Server

503

Properties
These properties apply to all types of markers. Every specific type of markers has additional properties, at least ones defining its location (e.g. category, value, etc.). Property Name Paint Stroke paint stroke Type Data Table Data Table Data Table Data Table Float String Data Table Data Table String Description Paint
590

used to draw the marker.

Stroke 593 used to draw the marker, if it is drawn as a line. If the marker is a rectangular region, the outline is drawn using Outline Stroke, so this attribute is not used in that case. Paint 590 paint used to draw the marker outline. This field is not used when the marker is drawn as a line. Stroke 593 used to draw the marker outline. This field is not used when the marker is drawn as a line. Alpha transparency that should be used to draw the marker. This is a value in the range 0.0f (completely transparent) to 1.0f (completely opaque). Label text (which may be null). If the label string is null (the default), the marker will be drawn without a label. Paint Paint
590

Outline Paint Outline Stroke Alpha Label

outlinePai nt outlineStr oke alpha label

Label Font labelFont Label Paint Label Anchor labelPaint labelAnch or

used to draw the marker. used to draw the label.

590

Point on the marker bounds that is used for alignment of the label. This anchor (after being adjusted by the label offsets) determines a fixed point on the chart that the marker label can be aligned to. Available anchor values are Center, Top, Bottom, Left, Right, Top Left, Top Right, Bottom Left, and Bottom Right.

Label Text Anchor Label Offset

labelText Anchor

String

Point on the label that is aligned to the fixed point on the chart determined by the Label Anchor property. Offset between the marker's bounds and the label anchor points. The default value is (3.0, 3.0, 3.0, 3.0), that is, the anchor points lie on a rectangle three units inside

labelOffse Data t Table

2000-2013 Tibbo Technology Inc.

504

AggreGate Documentation

(or outside) the marker's bounding rectangle. See Rectangle Insets Label Offset Type Type labelOffse String tType type Integer

506 .

Label offset type: No Change , Expand or Contract. This controls how the insets returned by Label Offset are applied to calculate the label anchor position. Marker type: Category 504 , Value 505 , or Interval if only one marker type is applicable.
505 .

This field may be unavailable

3.15.10.7.6.1 Category Marker

A category marker that can be used to highlight a category in a category plot. The category marker can be drawn as a line or as a rectangle. Line mode:

Rectangle mode:

Properties
See Marker
501

for the list of generic marker properties.

Category markers have the following additional properties:

2000-2013 Tibbo Technology Inc.

AggreGate Server

505

Property Name Category Key Draw As Line key

Type String

Description Category to mark. Flag that controls whether the marker is drawn as a line or a rectangle.

drawAsLin Boolean e

3.15.10.7.6.2 Value Marker

A value marker is used to indicate a constant value against the domain or range axis for a category plot plot 521 .
511

or an XY

The marker is most often drawn as a line, but in a chart with a 3D-effect the marker will be drawn as a polygon. For this reason, the marker has both Paint and Outline Paint attributes, and Stroke and Outline Stroke attributes. The image showing a chart having several value markers and a pointer annotation:

Properties
See Marker
501

for the list of generic marker properties.

Value markers have the following additional property: Property Name Value value Type Float Description Value to mark.

3.15.10.7.6.3 Interval Marker

An Interval Marker is used to highlight a fixed range of values against the domain or range axis for a category plot or an XY plot 521 . The below image shows a chart with an interval marker used to highlight a range of values on the domain axis:
511

2000-2013 Tibbo Technology Inc.

506

AggreGate Documentation

Properties
See Marker
501

for the list of generic marker properties.

Interval markers have the following additional properties: Property Name Start Value Type Description The lower bound of the interval to be highlighted. The upper bound of the interval to be highlighted.

startValue Float Float

End Value endValue

3.15.10.7.7 Rectangle Insets

This class is used to specify left, right, top and bottom insets relative to an arbitrary rectangle. The space can be specified in absolute terms (pixels) or relative terms (a percentage of the height or width of the rectangle).

Properties
Property Top Left Bottom Right Unit Type Name top left bottom right unitType Type Float Float Float Float Description The top value of the insets. The left value of the insets. The bottom value of the insets. The right value of the insets.

Intege Absolute or Relative. r

3.15.10.7.8 Title
A chart text title or subtitle displays a text string. Long titles automatically wrap to the next line, and you can also specify line breaks by inserting a newline character in the title's text.

Title Properties
Property Name Type Description

2000-2013 Tibbo Technology Inc.

AggreGate Server

507

Visible Text Tool Tip Text Font Width Height Margins Padding Frame Position Horizontal Alignment Vertical Alignment Background Paint Paint Text Alignment

visible text toolTipText font width height margins padding frame position horizontalAlig nment

Boole an String String Data Table Float Float Data Table Data Table Data Table String String

Flag that indicates whether or not this title should be displayed. Text for the title. Text that will be displayed as the tool tip for this title. The value can be null, which means that no tool tip will be displayed for the title. Font
590

for the title.

Preferred width of the title. Preferred height of the title. Margin around the outside of the title's frame. See Rectangle Insets Area of whitespace inside the title's frame. See Rectangle Insets Border that will be drawn around the title. See Block Frame
498 . 506 .

506 .

Position of the title within the chart (Top, Left, Bottom, or Right). Horizontal alignment for the title. Usually used if Position is Top or Bottom. Vertical alignment for the title. Usually used if Position is Left or Right. Paint Paint
590

verticalAlignm String ent backgroundPa Data int Table paint textAlignment Data Table String

used to fill the background area within the title's bounds. used to display the title text.

590

Alignment of the text within the title bounds (Left, Center, or Right). This controls how the text is aligned within the title's bounds, whereas the title's horizontal alignment controls how the title's bounding rectangle is aligned within the drawing space. Flag that controls whether or not the title bounds expand to match the available space.

Expand To Fit Space Maximum Lines To Display

expandToFitS pace maximumLine sToDisplay

Boole an

Intege Maximum number of lines to display. r

3.15.10.8 Chart Common Events

This section describes events that are supported by all charts.

CHART CLICK
This event is fired when a certain chart section (outside of its plot, axes, legend and titles that hava their own click events) is clicked. Event name: chartClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Name toolTipText area Type String Description Contains a tooltip of the clicked section of a chart.
594 598 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape

for details.

PLOT CLICK
This event is fired when chart's plot is clicked. Event name: plotClick

2000-2013 Tibbo Technology Inc.

508

AggreGate Documentation
598 .

Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Name toolTipText area Type String Description

Additionally, it defines the following fields:

Contains a tooltip of the clicked section of a chart.

594

Data Table A shape of a clicked chart area. See Shape

for details.

LEGEND ITEM CLICK

This event is fired when a chart's legend item is clicked. Event name: legendItemClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Dataset Index Series Key Name toolTipText area Type String Description Contains a tooltip of the clicked section of a chart.
594 598 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape

for details.

datasetIndex Integer seriesKey String

Index of a dataset the legend item corresponds to. Key of a series the legend item corresponds to.

TITLE CLICK
This event is fired when a chart's title is clicked. Event name: titleClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Name toolTipText area Type String Description Contains a tooltip of the clicked section of a chart.
594 598 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape

for details.

AXIS CLICK
This event is fired when a chart's axis is clicked. Event name: axisClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Domain Axis Index Range Axis Index Name toolTipText area domainAxisI ndex rangeAxisIn dex Type String Description Contains a tooltip of the clicked section of a chart.
594 598 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape Integer Integer

for details.

Index of the clicked domain axis or null if a range axis was clicked. Index of the clicked range axis or null if a domain axis was clicked.

CATEGORY LABEL CLICK

This event is fired when a category chart's item label is clicked. It is only available for category charts Event name: categoryLabelClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Name toolTipText area Type String Description Contains a tooltip of the clicked section of a chart.
594 598 . 397 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape

for details.

2000-2013 Tibbo Technology Inc.

AggreGate Server

509

Key

key

String

Dataset key of the clicked category.

CATEGORY ITEM CLICK

This event is fired when a category chart's item is clicked. It is only available for category charts Event name: categoryItemClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Dataset Index Row Key Column Key Name toolTipText area Type String Description Contains a tooltip of the clicked section of a chart.
594 598 . 397 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape

for details.

datasetIndex Integer rowKey columnKey String String

Index of the dataset the clicked item belongs to. Dataset key of the clicked row. Dataset key of the clicked column.

XY ITEM CLICK
This event is fired when an XY chart's item is clicked. It is only available for XY charts Event name: xyItemClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Dataset Index Series Item Name toolTipText area Type String Description Contains a tooltip of the clicked section of a chart.
594 598 . 429 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape

for details.

datasetIndex Integer series item Integer Integer

Index of the dataset the clicked item belongs to. Index of the series the clicked item belongs to. Index of the clicked item.

PIE SECTION CLICK

This event is fired when an pie chart's section is clicked. It is only available for pie charts Event name: pieSectionClick Event fields: this event has all fields of a regular mouse event Field Tooltip Text Area Pie Index Section Index Section Key Name toolTipText area pieIndex sectionIndex sectionKey Type String Description Contains a tooltip of the clicked section of a chart.
594 598 . 485 .

Additionally, it defines the following fields:

Data Table A shape of a clicked chart area. See Shape Integer Integer String Index of the pie the clicked item belongs to. Index of the clicked section. Key of the clicked section.

for details.

3.15.10.9 Chart Plots

A plot controls the visual representation of data in a chart. This section describes properties that are supported by all chart plots.

2000-2013 Tibbo Technology Inc.

510

AggreGate Documentation

The Plot Border

A border is drawn around the outside of most plot types. It's possible to change the appearance of the border by modifying the paint and stroke used to draw it. An outline is drawn around all four sides of the data area. Note that each of the plot's axes may also draw a line along the edge of the data area. See the Axis Line Visible attribute of the axis.

OUTLINE VISIBLE
Flag that controls visibility of the plot outline. Property name: outlineVisible Property type: Boolean

OUTLINE PAINT
The paint
590

used to draw an outline around the plot area.

Property name: outlinePaint Property type: Data Table

OUTLINE STROKE
The stroke
593

used to draw an outline around the plot area.

Property name: outlineStroke Property type: Data Table

The Plot Background

The background area for a plot is the area inside the plot's axes (if the plot has axes). It does not include the chart titles, the legend or the axis labels.

BACKGROUND PAINT
Paint
590

used to fill the plot's background.

Property name: backgroundPaint Property type: Data Table

BACKGROUND ALPHA
Alpha transparency for the plot's background. The range of values permitted is 0.0f (fully transparent) through to 1.0f (fully opaque). Property name: backgroundAlpha Property type: Float

BACKGROUND IMAGE
Background image for the plot. Property name: backgroundImage Property type: Data Block

BACKGROUND IMAGE ALIGNMENT

Alignment type for the background image. Allowed values are: Non-scaling: Center, Top, Bottom, Left, Right, Top Left, Top Right, Bottom Left, and Bottom Right Scaling: Fit Vertical, Fit Horizontal, and Fit (stretch to fill the entire area) Property name: backgroundImageAlignment

Property type: Integer

BACKGROUND IMAGE ALPHA

2000-2013 Tibbo Technology Inc.

AggreGate Server
Alpha transparency for drawing the background image. Property name: backgroundImageAlpha

511

Property type: Float

The "No Data" Message

Some plots will display a message when no data is available for plotting. The message itself is a simple string, controlled by the following properties:

NO DATA MESSAGE
A string shown when there is no data to display. Property name: noDataMessage Property type: String

NO DATA MESSAGE FONT

The font
590

used to display the "no data" message.

Property name: noDataMessageFont Property type: Data Table

NO DATA MESSAGE PAINT

The paint
590

used to display the "no data" message.

Property name: noDataMessagePaint Property type: Data Table

Other Properties
INSETS
The amount of space to leave around the outside of the plot. See Rectangle Insets Property name: insets Property type: Data Table
506 .

FOREGROUND ALPHA
Alpha transparency used to draw items in the plot's foreground. Property name: foregroundAlpha Property type: Float

3.15.10.9.1 Category Plot

A category plot is most commonly used to display bar charts, but also supports line charts, area charts, stacked area charts and more. The category plot has: One or more domain axes showing string category names. These are Category One or more range axes showing numeric values. These are Value Category plots can be drawn with one of two orientations: Horizontal orientation: the domain (category) axis will appear at the left or right of the chart, and the range (value) axis will appear at the top or bottom of the chart; Vertical orientation: the domain (category) axis will appear at the top or bottom of the chart and the range (value) axis will appear at the left or right of the chart. Category plot with horizontal orientation:
493 491

axes.

axes.

2000-2013 Tibbo Technology Inc.

512

AggreGate Documentation

The colors used for the series within the chart are controlled by the plot's renderer. The plot supports panning and zooming along the range axis. This section describes properties of a category plot. See Chart Plot
509

for the descriptions of generic plot properties.

Item Rendering Order

Within each dataset, the data items are rendered by column then by row, in ascending order (by default). In some cases, you might need to change the order in which the items are rendered (it only matters when the renderer draws items in such a way that they can overlap with other items, for example the bars drawn by a 3D Bar Renderer):

COLUMN RENDERING ORDER

Column rendering order. Property name: columnRenderingOrder Property type: String

ROW RENDERING ORDER

Row rendering order. Property name: rowRenderingOrder Property type: String

Plot Annotations
Annotations can be added to a plot to highlight data items of interest. The following standard annotation types are available: Line Annotation Text Annotation
517 518 519

Pointer Annotation

ANNOTATIONS
The list of annotations. Property name: annotations Property type: Data Table

Markers
Markers are used to highlight different categories (domain markers) or values (range markers). Each marker may be put on one of two layers:

2000-2013 Tibbo Technology Inc.

AggreGate Server
Foreground layer: the marker will be drawn over series data

513

Background layer: the marker will be drawn below series data

DOMAIN MARKERS
A table containing category markers Property name: domainMarkers Property type: Data Table
504

and their layers.

RANGE MARKERS
A table containing range markers Property name: rangeMarkers Property type: Data Table
501

and their layers.

Axes Properties
A category plot usually has a single domain axis and a single range axis. However, additional axes may be added.

AXIS OFFSET
The axes can be offset slightly from the edges of the plot area, if required. This property controls the offset between the plot area and the axes. See Rectangle Insets 506 . Axis offset usage illustration:

Property name: axisOffset Property type: Data Table

DOMAIN AXES
The table containing chart's domain (category) axes There are four domain axis location options: Top or Left: top side if plot orientation is vertical and left side if plot orientation is horizontal Top or Right: top side if plot orientation is vertical and right side if plot orientation is horizontal Bottom or Left: bottom side if plot orientation is vertical and left side if plot orientation is horizontal Bottom or Right : bottom side if plot orientation is vertical and right side if plot orientation is horizontal Property name: domainAxes Property type: Data Table
491

and their positions.

2000-2013 Tibbo Technology Inc.

514

AggreGate Documentation

RANGE AXES
The table containing chart's range (value) axes There are four range axis location options: Top or Left: top side if plot orientation is horizontal and left side if plot orientation is vertical Top or Right: top side if plot orientation is horizontal and right side if plot orientation is vertical Bottom or Left: bottom side if plot orientation is horizontal and left side if plot orientation is vertical Bottom or Right : bottom side if plot orientation is horizontal and right side if plot orientation is vertical Property name: rangeAxes Property type: Data Table
493

and their positions.

RANGE ZERO BASELINE VISIBLE

Flag that controls whether or not the zero baseline against the range axis is visible. Range Zero Baseline is a base line against the range axis at the zero value. Property name: rangeZeroBaselineVisible

Property type: Data Table

RANGE ZERO BASELINE STROKE

Stroke
593

used for the zero baseline against the range axis. rangeZeroBaselineStroke

Property name:

Property type: Data Table

RANGE ZERO BASELINE PAINT

Paint
590

used for the zero baseline against the range axis. rangeZeroBaselinePaint

Property name:

Property type: Data Table

Fixed Axis Dimensions

The width and height of the axes are normally determined automatically to allow just the required amount of space, no more and no less. Occasionally, you may want to override this behaviour and specify a fixed amount of space to allocate to each axis. As an example, this can make it easier to align the contents of multiple charts. The fixed axis space table contains four values (Top, Bottom, Left and Right) that define the space allocated for axes located at the top, bottom, left, and right part of a plot respectively. Since the plot may contain many axes these values are used to collate the space requirements for all the axes.

FIXED DOMAIN AXIS SPACE

Specifies a fixed amount of space to allocate to the domain axis. Property name: fixedDomainAxisSpace

Property type: Data Table

FIXED RANGE AXIS SPACE

Specifies a fixed amount of space to allocate to the range axis. Property name: fixedRangeAxisSpace

Property type: Data Table

Crosshairs
Category plot has support for crosshairs against the primary domain and range axes.

2000-2013 Tibbo Technology Inc.

AggreGate Server

515

Crosshairs may be set up by clicking on a chart within a working widget.

DOMAIN CROSSHAIR VISIBLE

Flag that controls the visibility of the domain crosshair. Property name: domainCrosshairVisible

Property type: Boolean

DOMAIN CROSSHAIR CATEGORY

Category key for the domain crosshair point. Property name: domainCrosshairColumnKey

Property type: String

DOMAIN CROSSHAIR SERIES

Series key for the domain crosshair point. This property is supported by Line
397

and Gantt

419

charts only.

Property name: domainCrosshairRowKey Property type: String

DOMAIN CROSSHAIR STROKE

Stroke
593

used to draw the domain crosshair if it is visible. domainCrosshairStroke

Property name:

Property type: Data Table

DOMAIN CROSSHAIR PAINT

Paint
590

used to draw the domain crosshair if it is visible. domainCrosshairPaint

Property name:

Property type: Data Table

RANGE CROSSHAIR VISIBLE

Flag that controls whether or not a range crosshair is drawn. Property name: rangeCrosshairVisible

Property type: Boolean

RANGE CROSSHAIR VALUE

Value for the range crosshair point. Property name: rangeCrosshairValue

Property type: Float

RANGE CROSSHAIR STROKE

Stroke
593

used to draw the range crosshair if it is visible. rangeCrosshairStroke

Property name:

Property type: Data Table

RANGE CROSSHAIR PAINT

Paint
590

used to draw the range crosshair if it is visible.

2000-2013 Tibbo Technology Inc.

516

AggreGate Documentation
rangeCrosshairPaint

Property name:

Property type: Data Table

RANGE CROSSHAIR LOCKED ON DATA

Flag that controls whether or not the range crosshair point locks onto the nearest data value when it is set up by clicking on a chart. Property name: rangeCrosshairLockedOnData

Property type: Boolean

Gridlines
By default, the Category Plot will display gridlines against the primary range axis, but not the domain axis. Normal Gridlines are drawn every axis' Tick Mark, and Minor Gridlines are drawn on every axis' Minor Tick Mark. Note that the domain and range gridlines are controlled independently.

DOMAIN GRIDLINES VISIBLE

Flag that controls whether gridlines are drawn against the domain axis. Property name: domainGridlinesVisible

Property type: Boolean

DOMAIN GRIDLINE POSITION

The position of the gridlines against the domain axis: Start , Middle , or End of every category. Property name: domainGridlinePosition

Property type: String

DOMAIN GRIDLINE STROKE

Stroke
593

used to draw the domain gridlines. domainGridlineStroke

Property name:

Property type: Data Table

DOMAIN GRIDLINE PAINT

Paint
590

used to draw the domain gridlines.

Property name: domainGridlinePaint Property type: Data Table

RANGE GRIDLINES VISIBLE

Flag that controls whether gridlines are drawn against the range axis. Property name: rangeGridlinesVisible

Property type: Boolean

RANGE GRIDLINE STROKE

Stroke
593

used to draw the range gridlines. rangeGridlineStroke

Property name:

Property type: Data Table

RANGE GRIDLINE PAINT

Paint
590

used to draw the range gridlines.

Property name: rangeGridlinePaint Property type: Data Table

2000-2013 Tibbo Technology Inc.

AggreGate Server

517

RANGE MINOR GRIDLINES VISIBLE

Flag that controls whether or not gridlines are shown for the minor tick values on the primary range axis. Property name: rangeMinorGridlinesVisible

Property type: Boolean

RANGE MINOR GRIDLINE STROKE

Stroke
593

used to draw the range minor gridlines. rangeMinorGridlineStroke

Property name:

Property type: Data Table

RANGE MINOR GRIDLINE PAINT

Paint
590

used to draw the range minor gridlines. rangeMinorGridlinePaint

Property name:

Property type: Data Table

Other Properties
ORIENTATION
Plot orientation (Vertical or Horizontal). Default is Vertical. Property name: orientation Property type: String

RANGE PANNABLE
Flag that controls whether or not the plot is pannable along the range axis. Property name: rangePannable Property type: Boolean

FIXED LEGEND ITEMS

A collection of legend items
501

for the plot, used to override the auto-generated set of legend items if non-empty.

Property name: fixedLegendItems Property type: Data Table

3.15.10.9.1.1 Line Annotation

An annotation that draws a line between two points on a category plot (starting at Category 1, Value 1 and ending at Category 2, Value 2).

Properties
Property Category 1 Category 2 Value 1 Value 2 Paint Stroke Name category1 category2 value1 value2 paint stroke Type String String Float Float Data Table Data Table Description Category for the start of the line. Category for the end of the line. Value for the start of the line. Value for the end of the line. Paint
590

used to draw the line used to draw the line.

Stroke

593

2000-2013 Tibbo Technology Inc.

518

AggreGate Documentation

3.15.10.9.1.2 Text Annotation

An annotation that can be used to display an item of text at some location (defined by a Category, Value pair) on a category plot. Text annotations example:

Properties
Property Category Category Anchor Font Paint Rotation Anchor Rotation Angle Text Text Anchor Value Name category Type String Description Category key for the annotation. Category anchor point, which helps to determine the position of the alignment point for the annotation Font Paint
590

categoryA String nchor font paint Data Table Data Table

used to display the text. used to draw the text.

590

rorationAn String chor rorationAn Float gle text textAncho r value String String Float

Text anchor point about which any rotation is performed. Rotation angle (in degrees). Text displayed by the annotation. Anchor point for the text. This will be aligned to the Category, Value point on the chart. Value that determines the alignment point for the annotation.

2000-2013 Tibbo Technology Inc.

AggreGate Server

519

3.15.10.9.1.3 Pointer Annotation

An annotation for a category plot that displays a text item and an arrow pointing towards a point on a chart defined by a Category, Value pair. Example of a pointer annotation:

Properties
Property Category Category Anchor Font Paint Rotation Anchor Rotation Angle Text Text Anchor Value Angle Arrow Length Arrow Paint Arrow Stroke Arrow Width Base Radius Name category Type String Description Category key for the annotation. Category anchor point, which helps to determine the position of the alignment point for the annotation Font Paint
590

categoryA String nchor font paint Data Table Data Table

used to display the text. used to draw the text.

590

rorationAn String chor rorationAn Float gle text textAncho r value angle String String Float Float

Text anchor point about which any rotation is performed. Rotation angle (in degrees). Text displayed by the annotation. Anchor point for the text. This will be aligned to the Category, Value point on the chart. Value that determines the alignment point for the annotation. Angle of the pointer (in degrees). Length of the arrow head. Paint
590

arrowLeng Float th arrowPain t arrowStro ke arrowWidt h Data Table Data Table Float

used to draw the arrow. used to draw the arrow.

Stroke

593

Width of the arrow head. Distance from the anchor point to the base of the arrow. The difference between the Base Radius and the Tip Radius is the overall length of the arrow.

baseRadiu Float s

2000-2013 Tibbo Technology Inc.

520

AggreGate Documentation

Label Offset

labelOffse t

Float Float

Offset from the base of the arrow to the label. Distance from the anchor point to the tip of the arrow. Since the tip of the arrow is pointing towards the anchor point, this should be a lower value than the Base Radius.

Tip Radius tipRadius

3.15.10.9.1.4 Item Label Generator

A Category Item Label Generator assumes responsibility for creating the text strings that will be used for item labels in a category chart.

Properties
Property Label Format Name labelForm at Type String Description Format string that may contain the following tokens: {0} - the series name {1} - the category {2} - the string representation of item value Formatter Type Number Format Percent Format Date Format formatTyp Intege Number Formatter or Date Formatter . e r numberFo rmat percentFo rmat dateForm at String String String Number format Number format
1322

pattern (for Number Formatter only). pattern used for percentage values (for Number Formatter only).

1322

Date/time format 1321 pattern (for Date Formatter only).

3.15.10.9.1.5 Tool Tip Generator

A Category Tool Tip Generator assumes responsibility for creating the text strings that will be used for tool tips in a category chart.

Properties
Property Label Format Name labelForm at Type String Description Format string that may contain the following tokens: {0} - the series name {1} - the category {2} - the string representation of item value Formatter Type Number Format Percent Format Date Format formatTyp Intege Number Formatter or Date Formatter . e r numberFo rmat percentFo rmat dateForm at String String String Number format Number format
1322

pattern (for Number Formatter only). pattern used for percentage values (for Number Formatter only).

1322

Date/time format 1321 pattern (for Date Formatter only).

2000-2013 Tibbo Technology Inc.

AggreGate Server

521

3.15.10.9.2 XY Plot
XY Plot draws a visual representation of (X, Y) value pairs, where the domain axis measures the X-values and the range axis measures the T-values. This plot supports panning and zooming along both axes. XY plot is typically displayed using a vertical orientation, but it is possible to change to a horizontal orientation which can be useful for certain applications.

PLOT LAYOUT
Axes are laid out at the left and bottom of the drawing area. The space allocated for the axes is determined automatically. The following diagram shows how this area is divided:

Determining the dimensions of these regions is an awkward problem. The plot area can be resized arbitrarily, but the vertical axis and horizontal axis sizes are more difficult. Note that the height of the vertical axis is related to the height of the horizontal axis, and, likewise, the width of the vertical axis is related to the width of the horizontal axis. This results in a "chicken and egg" problem, because changing the width of an axis can affect its height (especially if the tick units change with the resize) and changing its height can affect the width (for the same reason).

Quadrants
The XY Plot provides an optional facility to specify a background color for each quadrant in the plot.

QUADRANT ORIGIN
The quadrant origin, in chart data space, specified by X and Y coodrdinates. By default, the origin is (0, 0). Property name: quadrantOrigin Property type: Data Table

QUADRANTS PAINT
Property Quadrant Name quadrant Type Description

Intege Quadrant specification. There are four quadrants: r Negative domain, positive range Positive domain, positive range Negative domain, negative range Positive domain, negative range

Paint

paint

Data Table

Paint

590

used to fill the quadrant. If null, quadrant it not filled.

Property name: quadrantsPaint Property type: Data Table

2000-2013 Tibbo Technology Inc.

522

AggreGate Documentation

Markers
Markers are used to highlight different X-values (domain markers) or Y-values (range markers). Each marker may be put on one of two layers: Foreground layer: the marker will be drawn over series data

Background layer: the marker will be drawn below series data

DOMAIN MARKERS
A table containing X-value markers Property name: domainMarkers Property type: Data Table
501

and their layers.

RANGE MARKERS
A table containing Y-value markers Property name: rangeMarkers Property type: Data Table
501

and their layers.

Plot Annotations
Annotations can be added to a plot to highlight data items of interest. The following standard annotation types are available: Box Annotation
528 529

Data Image Annotation Image Annotation Legend Annotation Line Annotation

531 532 533 529 530

Pointer Annotation

Polygon Annotation Shape Annotation Text Annotation Title Annotation

534

534 535

Renderer Annotations have several advantages over plot's annotations.

ANNOTATIONS
The list of annotations. Property name: annotations Property type: Data Table

Tick Bands
The XY Plot can color alternate bands between the tick marks on the plot's axes. Tick bands example:

2000-2013 Tibbo Technology Inc.

AggreGate Server

523

Tick bands are controlled by two properties:

DOMAIN TICK BAND PAINT

Paint
590

used to fill alternate bands between the tick values on the domain axis. If paint is null, no bands will be filled.

Property name: domainTickBandPaint Property type: Data Table

RANGE TICK BAND PAINT

Paint
590

used to fill alternate bands between the tick values on the range axis. If paint is null, no bands will be filled.

Property name: rangeTickBandPaint Property type: Data Table

Axes Properties
An XY plot usually has a single domain axis and a single range axis. However, additional axes may be added. The plot's axes can appear at the top, bottom, left or right of the plot area. The location for an axis combines two possible options. Option which is actually used depends on the orientation (horizontal or vertical) of the plot. For "vertical" plots (the usual default), the domain axis will appear at the top or bottom of the plot area, and the range axis will appear at the left or right of the plot area. For "horizontal" plots, the domain axis will appear at the left or right of the plot area, and the range axis will appear at the top or bottom of the plot area.

AXIS OFFSET
The axes can be offset slightly from the edges of the plot area, if required. This property controls the offset between the plot area and the axes. See Rectangle Insets 506 . Property name: axisOffset Property type: Data Table

DOMAIN AXES
The table containing chart's domain (X-value) axes There are four domain axis location options: Top or Left: top side if plot orientation is vertical and left side if plot orientation is horizontal Top or Right: top side if plot orientation is vertical and right side if plot orientation is horizontal Bottom or Left: bottom side if plot orientation is vertical and left side if plot orientation is horizontal Bottom or Right : bottom side if plot orientation is vertical and right side if plot orientation is horizontal Property name: domainAxes Property type: Data Table
493

and their positions.

2000-2013 Tibbo Technology Inc.

524

AggreGate Documentation

RANGE AXES
The table containing chart's range (Y-value) axes There are four range axis location options: Top or Left: top side if plot orientation is horizontal and left side if plot orientation is vertical Top or Right: top side if plot orientation is horizontal and right side if plot orientation is vertical Bottom or Left: bottom side if plot orientation is horizontal and left side if plot orientation is vertical Bottom or Right : bottom side if plot orientation is horizontal and right side if plot orientation is vertical Property name: rangeAxes Property type: Data Table
493

and their positions.

DOMAIN ZERO BASELINE VISIBLE

Flag that controls whether or not the zero baseline against the domain axis is visible. Domain Zero Baseline is a base line against the domain axis at the zero value. Property name: domainZeroBaselineVisible

Property type: Data Table

DOMAIN ZERO BASELINE STROKE

Stroke
593

used for the zero baseline against the domain axis. domainZeroBaselineStroke

Property name:

Property type: Data Table

DOMAIN ZERO BASELINE PAINT

Paint
590

used for the zero baseline against the domain axis. domainZeroBaselinePaint

Property name:

Property type: Data Table

RANGE ZERO BASELINE VISIBLE

Flag that controls whether or not the zero baseline against the range axis is visible. Range Zero Baseline is a base line against the range axis at the zero value. Property name: rangeZeroBaselineVisible

Property type: Data Table

RANGE ZERO BASELINE STROKE

Stroke
593

used for the zero baseline against the range axis. rangeZeroBaselineStroke

Property name:

Property type: Data Table

RANGE ZERO BASELINE PAINT

Paint
590

used for the zero baseline against the range axis. rangeZeroBaselinePaint

Property name:

Property type: Data Table

Fixed Axis Dimensions

The width and height of the axes are normally determined automatically to allow just the required amount of space, no more and no less. Occasionally, you may want to override this behaviour and specify a fixed amount of space to allocate to each axis. As an example, this can make it easier to align the contents of multiple charts. The fixed axis space table contains four values (Top, Bottom, Left and Right) that define the space allocated for axes located at the top, bottom, left, and right part of a plot respectively. Since the plot may contain many axes these values

2000-2013 Tibbo Technology Inc.

AggreGate Server
are used to collate the space requirements for all the axes.

525

FIXED DOMAIN AXIS SPACE

Specifies a fixed amount of space to allocate to the domain axis. Property name: fixedDomainAxisSpace

Property type: Data Table

FIXED RANGE AXIS SPACE

Specifies a fixed amount of space to allocate to the range axis. Property name: fixedRangeAxisSpace

Property type: Data Table

Crosshairs
Category plot has support for crosshairs against the primary domain and range axes. Crosshairs may be set up by clicking on a chart within a working widget.

Example chart with both domain and range crosshairs:

DOMAIN CROSSHAIR VISIBLE

Flag that controls the visibility of the domain crosshair. Property name: domainCrosshairVisible

Property type: Boolean

DOMAIN CROSSHAIR VALUE

Value for the domain crosshair point. Property name: domainCrosshairValue

Property type: Float

DOMAIN CROSSHAIR STROKE

Stroke
593

used to draw the domain crosshair if it is visible. domainCrosshairStroke

Property name:

Property type: Data Table

2000-2013 Tibbo Technology Inc.

526

AggreGate Documentation

DOMAIN CROSSHAIR PAINT

Paint
590

used to draw the domain crosshair if it is visible. domainCrosshairPaint

Property name:

Property type: Data Table

DOMAIN CROSSHAIR LOCKED ON DATA

Flag that controls whether or not the domain crosshair point locks onto the nearest data value when it is set up by clicking on a chart. Property name: domainCrosshairLockedOnData

Property type: Boolean

RANGE CROSSHAIR VISIBLE

Flag that controls whether or not a range crosshair is drawn. Property name: rangeCrosshairVisible

Property type: Boolean

RANGE CROSSHAIR VALUE

Value for the range crosshair point. Property name: rangeCrosshairValue

Property type: Float

RANGE CROSSHAIR STROKE

Stroke
593

used to draw the range crosshair if it is visible. rangeCrosshairStroke

Property name:

Property type: Data Table

RANGE CROSSHAIR PAINT

Paint
590

used to draw the range crosshair if it is visible. rangeCrosshairPaint

Property name:

Property type: Data Table

RANGE CROSSHAIR LOCKED ON DATA

Flag that controls whether or not the range crosshair point locks onto the nearest data value when it is set up by clicking on a chart. Property name: rangeCrosshairLockedOnData

Property type: Boolean

Gridlines
The XY Plot provides support for drawing gridlines against the primary domain axis and the primary range axis. For each axis, there is a flag that controls whether or not the gridlines are visible. For visible gridlines, you can customize the line style (Stroke) and color (Paint).

DOMAIN GRIDLINES VISIBLE

Flag that controls whether gridlines are drawn against the domain axis. Property name: domainGridlinesVisible

Property type: Boolean

DOMAIN GRIDLINE STROKE

Stroke
593

used to draw the domain gridlines. domainGridlineStroke

Property name:

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: Data Table

527

DOMAIN GRIDLINE PAINT

Paint
590

used to draw the domain gridlines.

Property name: domainGridlinePaint Property type: Data Table

RANGE GRIDLINES VISIBLE

Flag that controls whether gridlines are drawn against the range axis. Property name: rangeGridlinesVisible

Property type: Boolean

RANGE GRIDLINE STROKE

Stroke
593

used to draw the range gridlines. rangeGridlineStroke

Property name:

Property type: Data Table

RANGE GRIDLINE PAINT

Paint
590

used to draw the range gridlines.

Property name: rangeGridlinePaint Property type: Data Table

DOMAIN MINOR GRIDLINES VISIBLE

Flag that controls whether or not gridlines are shown for the minor tick values on the primary domain axis. Property name: domainMinorGridlinesVisible

Property type: Boolean

DOMAIN MINOR GRIDLINE STROKE

Stroke
593

used to draw the domain minor gridlines. domainMinorGridlineStroke

Property name:

Property type: Data Table

DOMAIN MINOR GRIDLINE PAINT

Paint
590

used to draw the domain minor gridlines. domainMinorGridlinePaint

Property name:

Property type: Data Table

RANGE MINOR GRIDLINES VISIBLE

Flag that controls whether or not gridlines are shown for the minor tick values on the primary range axis. Property name: rangeMinorGridlinesVisible

Property type: Boolean

RANGE MINOR GRIDLINE STROKE

Stroke
593

used to draw the range minor gridlines. rangeMinorGridlineStroke

Property name:

Property type: Data Table

RANGE MINOR GRIDLINE PAINT

Paint
590

used to draw the range minor gridlines.

2000-2013 Tibbo Technology Inc.

528

AggreGate Documentation
rangeMinorGridlinePaint

Property name:

Property type: Data Table

Other Properties
ORIENTATION
Plot orientation (Vertical or Horizontal). Default is Vertical. Property name: orientation Property type: String

DOMAIN PANNABLE
A flag that controls whether or not panning is enabled for the domain axis/axes. Property name: domainPannable Property type: Boolean

RANGE PANNABLE
A flag that controls whether or not panning is enabled for the range axis/axes. Property name: rangePannable Property type: Boolean

FIXED LEGEND ITEMS

A collection of legend items
501

for the plot, used to override the auto-generated set of legend items if non-empty.

Property name: fixedLegendItems Property type: Data Table

3.15.10.9.2.1 Box Annotation

An annotation that highlights a rectangular region within the data area. The annotation will only be visible if it falls within the current bounds of the plot's axes. It's possible to use this annotation with Date axes. Just specify the relevant coordinates in terms of milliseconds since 1-Jan-1970. Box annotation example:

2000-2013 Tibbo Technology Inc.

AggreGate Server

529

Properties
Property X Y Width Height Fill Paint Stroke Outline Paint Tool Tip Text Name x y w h fillPaint stroke outlinePai nt Type Float Float Float Float Data Table Data Table Data Table Description Lower x-coordinate of the box. Lower y-coordinate of the box. Width of the box. Height of the box Paint
590

used to fill the box. used to draw the box outline.

Stroke Paint

593

590

used to draw the box outline.

toolTipTex String t

The tool tip text for this annotation.

3.15.10.9.2.2 Data Image Annotation

An annotation that enables an image to be drawn (scaled) on an XY Plot within a rectangle that is defined in data coordinates. A potential application for this is to support basic geographical plotting by displaying maps in the background of charts.

Properties
Property X Y Width Height Image Include In Data Bounds Tool Tip Text Name x y w h image Type Description Float Float Float Float Lower x-coordinate of the box. Lower y-coordinate of the box. Width of the image, in chart data units. Height of the image, in chart data units.

Data The image to display. Block

includeInDat Boole Flag indicating whether or not the annotation should contribute to the data range aBounds an for a plot/renderer. toolTipText Strin g The tool tip text for this annotation.

3.15.10.9.2.3 Image Annotation

An annotation that allows an image to be displayed at an arbitrary (x, y) location.

Properties
Property X Y Anchor Image Name x y anchor image Type Description Float Float Strin g Data Lower x-coordinate of the box. Lower y-coordinate of the box. Image anchor, which will be aligned to the (x, y) location on the chart when the image annotation is displayed. The image to display.

2000-2013 Tibbo Technology Inc.

530

AggreGate Documentation

Block Tool Tip Text toolTipText Strin g The tool tip text for this annotation.

3.15.10.9.2.4 Item Label Generator

An XY Item Label Generator assumes responsibility for creating the text strings that will be used for item labels in an XY chart.

Properties
Property Format String Name formatString Type String Description Format string that may contain the following tokens: {0} - the series name {1} - the string representation of X-value {2} - the string representation of Y-value X Value Formatter Type X Value Format X Value Formatter Type X Value Format xFormatType Intege Formater to use for X-values: Number Formatter or Date Formatter . r String X-values format pattern: Number format 1322 pattern for Number Formatter, or Date/time format 1321 pattern for Date Formatter.

xFormat yFormatType

Intege Formater to use for T-values: Number Formatter or Date Formatter . r String Y-values format pattern: Number format 1322 pattern for Number Formatter, or Date/time format 1321 pattern for Date Formatter.

yFormat

3.15.10.9.2.5 Legend Annotation

An annotation that can place a Legend Example of legend annotation:
500

within a chart.

Properties

2000-2013 Tibbo Technology Inc.

AggreGate Server

531

Property X Y Max Width Max Height Legend Anchor Tool Tip Text

Name x y maxWidth maxHeight legend anchor toolTipText

Type Description Float Float Float Float Data Table Strin g Strin g X coordinate of the title in the range from 0.0 to 1.0. Y coordinate of the title in the range from 0.0 to 1.0. Maximum width for the annotation (specified as a percentage of the plot width, i. e. 0.05 is 5%). Maximum height for the annotation (specified as a percentage of the plot width, i. e. 0.05 is 5%). Legend
500

to display.

Title anchor, which will be aligned to the (x, y) location on the chart when the annotation is displayed. The tool tip text for this annotation.

3.15.10.9.2.6 Line Annotation

A simple annotation that draws a line between a starting point (x0, y0) and an ending point (x1, y1).

Properties
Property X Y Width Height Paint Stroke Tool Tip Text Name x y w h paint stroke Type Float Float Float Float Data Table Data Table Description Lower x-coordinate of the line. Lower y-coordinate of the line. Length of line along the X axis, i.e. X1 - X0. Length of line along the Y axis, i.e. Y1 - Y0. Paint
590

used to draw the line. used to draw the line.

Stroke

593

toolTipTex String t

The tool tip text for this annotation.

2000-2013 Tibbo Technology Inc.

532

AggreGate Documentation

3.15.10.9.2.7 Pointer Annotation

An annotation that displays an arrow pointing towards a specific (x, y) location. The arrow can have a label at one end. Examples of pointer annotations:

Properties
Property X Y Text Font Text Anchor Paint Backgrou nd Paint Rotation Anchor Name x y text font textAncho r paint Type Float Float String Data Table String Data Table Description X-value for the annotation. Y-value for the annotation. Text displayed by the annotation. Font
590

used to display the text.

Anchor point for the text. This will be aligned to the Category, Value point on the chart. Paint
590

used to draw the text.

backgroun Data dPaint Table rorationAn String chor

The background paint if the label (or null to disable filling the label background). Text anchor point about which any rotation is performed.

2000-2013 Tibbo Technology Inc.

AggreGate Server

533

Rotation Angle Outline Visible Outline Paint Outline Stroke Angle Arrow Length Arrow Paint Arrow Stroke Arrow Width Base Radius Label Offset

rorationAn Float gle outlineVisi ble outlinePai nt outlinePai nt angle Boole an Data Table Data Table Float

Rotation angle (in degrees). Flag that controls the visibility of the label outline. Outline paint
590

for the label. for the label.

Outline stroke

593

Angle of the pointer (in degrees). Length of the arrow head. Paint
590

arrowLeng Float th arrowPain t arrowStro ke arrowWidt h Data Table Data Table Float

used to draw the arrow. used to draw the arrow.

Stroke

593

Width of the arrow head. Distance from the anchor point to the base of the arrow. The difference between the Base Radius and the Tip Radius is the overall length of the arrow. Offset from the base of the arrow to the label. Distance from the anchor point to the tip of the arrow. Since the tip of the arrow is pointing towards the anchor point, this should be a lower value than the Base Radius. The tool tip text for this annotation.

baseRadiu Float s labelOffse t Float Float

Tip Radius tipRadius Tool Tip Text

toolTipTex String t

3.15.10.9.2.8 Polygon Annotation

A simple annotation that draws a polygon on an XY Plot. The polygon's coordinates are specified in data space (that is, the coordinate system defined by the plot's axes). Example of polygon annotation:

Properties
Property Fill Paint Name fillPaint Type Data Table Description Paint
590

used to fill the polygon.

2000-2013 Tibbo Technology Inc.

534

AggreGate Documentation

Stroke Outline Paint Polygon Tool Tip Text

stroke outlinePai nt polygon

Data Table Data Table Data Table

Stroke Paint

593

used to draw the polygon outline.

590

used to draw the polygon outline.

The list of (X, Y) points specifying polygon vertices. The tool tip text for this annotation.

toolTipTex String t

3.15.10.9.2.9 Shape Annotation

A simple annotation that draws a shape on an XY Plot. The shape's coordinates are specified in "data space" (that is, the coordinate system defined by the plot's axes).

Properties
Property Stroke Shape Fill Paint Tool Tip Text Name stroke shape fillPaint Type Data Table Data Table Data Table Description Stroke Shape Paint
593

used to draw the shape outline. to draw. Vertex coordinates are defined in the "data space".

594

590

used to fill the shape.

toolTipTex String t

The tool tip text for this annotation.

3.15.10.9.2.10 Text Annotation

A text annotation that draws a small text label at some (x, y) location on a chart. Text annotations example:

Properties
Property Name Type Description

2000-2013 Tibbo Technology Inc.

AggreGate Server

535

X Y Paint Backgrou nd Paint Outline Paint Text Font Text Anchor Rotation Anchor Rotation Angle Outline Visible Outline Stroke Tool Tip Text

x y paint

Float Float Data Table

X-value for the annotation. Y-value for the annotation. Paint Paint Paint
590

used to draw the text. used to fill the annotation background. used to draw the annotation outline.

backgroun Data dPaint Table outlinePai nt text font textAncho r Data Table String Data Table String

590

590

Text displayed by the annotation. Font

590

used to display the text.

Anchor point for the text. This will be aligned to the (X, Y) point on the chart. Text anchor point about which any rotation is performed. Rotation angle (in degrees). Flag controlling visibility of the annotation outline. Outline stroke
593

rorationAn String chor rorationAn Float gle outlineVisi ble outlineStr oke Data Table Data Table

for the annotation.

toolTipTex String t

The tool tip text for this annotation.

3.15.10.9.2.11 Title Annotation

An annotation that can place a Title
506

within a chart.

Properties
Property X Y Max Width Max Height Title Anchor Tool Tip Text Name x y maxWidth maxHeight title anchor toolTipText Type Description Float Float Float Float Data Table Strin g Strin g X coordinate of the title in the range from 0.0 to 1.0. Y coordinate of the title in the range from 0.0 to 1.0. Maximum width for the annotation (specified as a percentage of the plot width, i. e. 0.05 is 5%). Maximum height for the annotation (specified as a percentage of the plot width, i. e. 0.05 is 5%). Title
506

to display.

Title anchor, which will be aligned to the (x, y) location on the chart when the annotation is displayed. The tool tip text for this annotation.

3.15.10.9.2.12 Tool Tip Generator

An XY Tool Tip Generator assumes responsibility for creating the text strings that will be used for tool tips in an XY chart.

Properties

2000-2013 Tibbo Technology Inc.

536

AggreGate Documentation

Property Format String

Name formatString

Type String

Description Format string that may contain the following tokens: {0} - the series name {1} - the string representation of X-value {2} - the string representation of Y-value

X Value Formatter Type X Value Format Y Value Formatter Type Y Value Format

xFormatType

Intege Formater to use for X-values: Number Formatter or Date Formatter . r String X-values format pattern: Number format 1322 pattern for Number Formatter, or Date/time format 1321 pattern for Date Formatter.

xFormat yFormatType

Intege Formater to use for Y-values: Number Formatter or Date Formatter . r String Y-values format pattern: Number format 1322 pattern for Number Formatter, or Date/time format 1321 pattern for Date Formatter.

yFormat

3.15.10.9.3 Pie Plot

This plot is used by Pie Chart
485

and Ring Chart

486 .

General Properties
START ANGLE
Angle (in degrees) at which the first pie section starts. Zero is at 3 o'clock, and as the angle increases it proceeds anticlockwise around the chart (so that 90 degrees, the current default, is at 12 o'clock). Property name: startAngle Property type: Float

DIRECTION
Direction of the sections in the chart: Clockwise (the default) or Anticlockwise. Property name: direction Property type: String

INTERIOR GAP
Gap around the interior of the pie plot (the region where the labels are drawn) as a percentage of the plot width and height. The default value is 0.08 (8%). Property name: interiorGap Property type: Float

CIRCULAR
Flag that controls whether the pie chart is circular or elliptical in shape. Property name: circular Property type: Boolean

Handling Null and Zero Values

A dataset can contain null, zero or negative values which are awkward or impossible to display in a pie chart. Some special handling is built into the Pie Plot for these. If a zero or null value is found in the dataset, the Pie Plot, by default, will place a label at the position where the pie section would be displayed if it had a positive value and will also add an item to the chart's legend. If you prefer zero and null values to be ignored, use the following properties:

IGNORE NULL VALUES

Flag that controls whether or not null values in the dataset are ignored.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: ignoreNullValues Property type: Boolean

537

IGNORE ZERO VALUES

Flag that controls whether or not zero values in the dataset are ignored. Property name: ignoreZeroValues

Property type: Boolean

Shadow Effect
The plot will draw a "shadow" effect controlled by several properties:

SHADOW PAINT
Paint
590

used to draw the "shadow" effect. If disabled, no shadow effect will be drawn.

Property name: shadowPaint Property type: Data Table

SHADOW X OFFSET
X-offset for the shadow effect. Property name: shadowXOffset Property type: Float

SHADOW Y OFFSET
Y-offset for the shadow effect. Property name: shadowXOffset Property type: Float

Section Labels and Tooltips

LABEL GENERATOR
Section labels are generated according to the following properties: Property Disabled Label Format Name isNull labelForm at Type Boole an String Description Flag that enables/disabled item labels. Format string that may contain the following tokens: {0} - the series name {1} - the string representation of value {2} - the string representation of value in percents {3} - the sum of all values Number Format Percent Format numberFo rmat percentFo rmat String String Number format Number format
1322

pattern. pattern used for percentage values.

1322

Property name: labelGenerator Property type: Data Table

TOOL TIP GENERATOR

Section tooltips are generated according to the following properties:

2000-2013 Tibbo Technology Inc.

538

AggreGate Documentation

Property Disabled Label Format

Name isNull labelForm at

Type Boole an String

Description Flag that enables/disabled item tooltips. Format string that may contain the following tokens: {0} - the series name {1} - the string representation of value {2} - the string representation of value in percents {3} - the sum of all values

Number Format Percent Format

numberFo rmat percentFo rmat

String String

Number format Number format

1322

pattern. pattern used for percentage values.

1322

Property name: toolTipGenerator Property type: Data Table

Exploded Sections
The Pie Plot supports the display of "exploded" sections, in which a pie section is offset from the center of the chart to highlight it. Here is an example:

To make space for the sections that are offset from the center of the pie chart, the radius of the main pie is reduced, so a pie chart with exploded sections will appear smaller than a pie chart with no exploded sections.

EXPLODED PERCENTS
Table that controls "exploding" of individual pie sections: Property Series Percents Name series Type String Description Name of series to explode. Amount by which a specific section of the pie plot is offset, expressed as a percentage of the radius of the pie.

explodePe Float rcents

Property name: explodedPercents Property type: Data Table

Section Paints

2000-2013 Tibbo Technology Inc.

AggreGate Server
The paint used to fill each section in the pie chart is, by default, auto-populated (auto-assigned).

539

DEFAULT SECTION PAINT

Default section paint
590 ,

to be used if there is no custom setting for a series.

Property name: baseSectionPaint Property type: Data Table

AUTO POPULATE SECTION PAINTS

Flag that controls whether or not the different pre-defined section paints should be used. Property name: autoPopulateSectionPaints

Property type: Boolean

SECTION PAINTS
The table defining paints for individual sections. Property Series Paint Name series paint Type String Data Table Description Series name. Paint
590

to use for the series (section).

Property name: sectionPaints Property type: Data Table

Section Outlines
Section outlines are drawn, by default, as a thin grey line around each pie section. The Pie Plot provides options to: Switch off the outlines completely; Change the outlines for all sections by changing the default value; Control the outline for particular pie sections independently.

SECTION OUTLINES VISIBLE

Flag that controls whether or not section outlines are drawn. Property name: sectionOutlinesVisible Property type: Boolean

DEFAULT SECTION OUTLINE PAINT

Default section outline paint Property name:
590 ,

to be used if there is no custom setting for a series.

baseSectionOutlinePaint

Property type: Data Table

AUTO POPULATE SECTION OUTLINE PAINTS

Flag that controls whether or not the different pre-defined section outline paints should be used. Property name: autoPopulateSectionOutlinePaints

Property type: Boolean

SECTION OUTLINE PAINTS

The table defining outline paints for individual sections. Property Series Paint Name series paint Type String Data Description Series name. Outline paint
590

to use for the series (section).

2000-2013 Tibbo Technology Inc.

540

AggreGate Documentation

Table Property name: sectionOutlinePaints Property type: Data Table

DEFAULT SECTION OUTLINE STROKE

Default section outline stroke Property name:
593 ,

to be used if there is no custom setting for a series.

baseSectionOutlineStroke

Property type: Data Table

AUTO POPULATE SECTION OUTLINE STROKES

Flag that controls whether or not the different pre-defined section outline strokes should be used. Property name: autoPopulateSectionOutlineStrokes

Property type: Boolean

SECTION OUTLINE STROKES

The table defining outline strokes for individual sections. Property Series Stroke Name series stroke Type String Data Table Description Series name. Outline stroke
593

to use for the series (section).

Property name:

sectionOutlineStrokes

Property type: Data Table

Section Labels
LABEL FONT
Font
590

used to display the section labels.

Property name: labelFont Property type: Data Table

LABEL PAINT
Paint
590

used to display the section labels.

Property name: labelPaint Property type: Data Table

LABEL BACKGROUND PAINT

Paint 590 used to fill the section label boxes. If disabled, the label boxes will be transparent (the plot background color will show through). Property name: labelBackgroundPaint

Property type: Data Table

LABEL OUTLINE PAINT

Paint
590

used to draw the outline around the section labels. If disabled, the label boxes will not have an outline drawn.

Property name: labelOutlinePaint Property type: Data Table

LABEL OUTLINE STROKE

Stroke
593

used to draw outlines around the section labels. If disabled, no outlines will be drawn.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: labelOutlineStroke Property type: Data Table

541

LABEL SHADOW PAINT

Paint
590

used to draw the shadows beneath the section label boxes. If disabled, no shadow is drawn.

Property name: labelShadowPaint Property type: Data Table

LABEL PADDING
Label padding, i.e. the whitespace around the text and inside the outline. See Rectangle Insets Property name: labelPadding Property type: Data Table
506 .

Label Links
With regular (non-simple, see below) section labels, a linking line is drawn to connect the pie section with its corresponding section label. These links have several properties:

LABEL LINKS VISIBLE

Flag that controls whether or not the section label linking lines are visible. Property name: labelLinksVisible Property type: Boolean

LABEL LINK STYLE

The style of label links: Standard, Quad or Cubic. Property name: labelLinkStyle Property type: String

LABEL LINK MARGIN

Label linking line has a bend or "elbow" at a point slightly outside of the pie chart. The distance of the point from the edge of the pie chart is expressed as a percentage of the pie radius, and is referred to as the Label Link Margin. The default value is 0.025 (two-and-a-half percent). Property name: labelLinkMargin Property type: Float

LABEL LINK PAINT

Paint
590

used for the lines connecting the pie sections to their corresponding labels.

Property name: labelLinkPaint Property type: Data Table

LABEL LINK STROKE

Stroke
593

used for the lines connecting the pie sections to their corresponding labels.

Property name: labelLinkStroke Property type: Data Table

LABEL GAP
Gap between the edge of the pie and the label areas at the left and right side of the pie, as a percentage of the overall plot width. The default value is 0.025 (2.5%). Property name: labelGap Property type: Float

MAXIMUM LABEL WIDTH

2000-2013 Tibbo Technology Inc.

542

AggreGate Documentation

Maximum label width as a percentage of the plot width. The default value is 0.14 (fourteen percent). Property name: maximumLabelWidth Property type: Float

Simple Labels
A "simple" labelling option ensures that the labels are drawn roughly in the center of each pie section. No attempt is made to avoid overlapping labels in the case that several small pie sections are displayed alongside each other, so use this option only for cases where that is not a concern.

SIMPLE LABELS
Flag that controls whether the pie plot shows section labels in the "simple" format. Property name: simpleLabels Property type: Boolean

SIMPLE LABEL OFFSET

Insets
506

used to calculate the simple label anchor points relative to the pie plot's bounding rectangle.

Property name: simpleLabelOffset Property type: Data Table

Other Properties
MINIMUM ARC ANGLE TO DRAW
Minimum angle for drawing the arc segment for a pie section. Property name: minimumArcAngleToDraw

Property type: Float

LEGEND ITEM SHAPE

Shape
594

displayed with each legend item.

Property name: legendItemShape Property type: Data Table

3.15.10.10 Chart Renderers

Chart renderer is responsible for representing individual dataset items on chart's plot All chart renderer types provide support for the following common features: 1) Colors, line styles and shapes for each series: a) Paint b) Fill paint c) Outline paint d) Stroke e) Outline stroke f) Shape 2) Series visibility 3) Series in legend visibility 4) Item labels a) Visibility
509 .

2000-2013 Tibbo Technology Inc.

AggreGate Server
b) Font c) Paint d) Positive item label positions e) Negative item label positions

543

Per Series Property Mechanism

Many renderer properties need to have a value defined for each series in the dataset that is assigned to the renderer. In addition to the per-series properties, typically there is a default (or "base") property value, that will be used in the event that no property value is defined for a particular series.

SETTING SERIES COLORS

Renderers are responsible for drawing the data items within a plot, so they provide properties for controlling the colors that will be used. Colors are typically defined on a "per series" basis, and stored in a lookup table. There is a default mechanism to automatically populate the lookup table with default colors. However, you can manually update the the list at any time.

Basic Properties
RENDERER TYPE
Type of renderer to use for the chart. Property name: rendererType

Property type: Integer

Default Series Properties

DEFAULT SERIES VISIBILITY
The default visibility for all series. Property name: baseSeriesVisible

Property type: Boolean

DEFAULT SERIES VISIBILITY IN LEGEND

The default legend visibility for all series. Property name: baseSeriesVisibleInLegend

Property type: Boolean

DEFAULT PAINT
The default Paint
590

that is used if there is no custom setting for a series.

Property name: basePaint Property type: Data Table

DEFAULT STROKE
The default Stroke
593

that is used if there is no custom setting for a series.

Property name: baseStroke Property type: Data Table

DEFAULT SHAPE
The default Shape
594

that is used if there is no custom setting for a series.

Property name: baseShape Property type: Data Table

DEFAULT FILL PAINT

2000-2013 Tibbo Technology Inc.

544

AggreGate Documentation
590

The default fill paint

that is used if there is no custom setting for a series.

Property name: baseFillPaint Property type: Data Table

DEFAULT OUTLINE PAINT

The default outline paint
590

that is used if there is no custom setting for a series.

Property name: baseOutlinePaint Property type: Data Table

DEFAULT ITEM LABELS VISIBILITY

The default visibility for all item labels. Property name: baseItemLabelsVisible

Property type: Boolean

DEFAULT ITEM LABEL FONT

The default item label font Property name:
590

that is used if there is no custom setting for a series.

baseItemLabelFont

Property type: Data Table

DEFAULT ITEM LABEL PAINT

The default item label paint
590

that is used if there is no custom setting for a series.

Property name: baseItemLabelPaint Property type: Data Table

DEFAULT ITEM LABEL POSITION

This property includes two values: Positive Item Label Position 499 : the default setting for the positive item label position attribute is used when no per series or override setting is specified; Negative Item Label Position: the default setting for the negative item label position attribute is used when no per series or override setting is specified. Example of a category bar chart 404 that has the item labels for positive data values are displayed inside the bars, while the item labels for the negative data value are displayed underneath the bar:

The above chart also has a category marker Property name: baseItemLabelPosition

504 .

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: Data Table

545

ITEM LABEL ANCHOR OFFSET

The item label anchor offset allows some control over the position of item labels, by controlling how far the anchor point is shifted from its natural position. Property name: itemLabelAnchorOffset

Property type: Float

DEFAULT LEGEND SHAPE

The default shape
594

to use in chart legend(s)

500 .

Property name: baseLegendShape Property type: Data Table

DEFAULT LEGEND TEXT FONT

The default font Property name:
590

to use in chart legend(s)

500 .

baseLegendTextFont

Property type: Data Table

DEFAULT LEGEND TEXT PAINT

The default paint Property name:
590

to use in chart legend(s)

500 .

baseLegendTextPaint

Property type: Data Table

DEFAULT OUTLINE STROKE

The default outline stroke
593 ,

to be used when no other stroke is available for the series.

Property name: baseOutlineStroke Property type: Data Table

Per Series Properties

SERIES VISIBILITY
The table defining visibility for individual data series. Property Index Series Visible Name index seriesVisi ble Type Description

Intege Series index. r Boole an Flag indicating whether or not the series is visible.

Property name: seriesVisible Property type: Data Table

AUTO POPULATE SERIES PAINTS

Flag indicating that different pre-defined series colors should be used instead of Default Paint. Property name: autoPopulateSeriesPaints

Property type: Boolean

SERIES PAINTS
The table defining paints for individual data series. Property Name Type Description

2000-2013 Tibbo Technology Inc.

546

AggreGate Documentation

Index Series Paint

index

Intege Series index. r Paint

590

seriesPain Data t Table

to use for the series.

Property name: seriesPaints Property type: Data Table

AUTO POPULATE SERIES STROKES

Flag indicating that different pre-defined series strokes should be used instead of Default Stroke. Property name: autoPopulateSeriesStrokes

Property type: Boolean

SERIES STROKES
The table defining strokes for individual data series. Property Index Series Stroke Name index seriesStro ke Type Description

Intege Series index. r Data Table Stroke

593

to use for the series.

Property name: seriesStrokes Property type: Data Table

AUTO POPULATE SERIES SHAPES

Flag indicating that different pre-defined series shapes should be used instead of Default Shape. Property name: autoPopulateSeriesShapes

Property type: Boolean

SERIES SHAPES
The table defining shapes for individual data series. Property Index Series Shape Name index seriesSha pe Type Description

Intege Series index. r Data Table Shape

594

to use for the series.

Property name: seriesShapes Property type: Data Table

AUTO POPULATE SERIES FILL PAINTS

Flag indicating that different pre-defined series fill paints should be used instead of Default Fill Paint. Property name: autoPopulateSeriesFillPaints

Property type: Boolean

SERIES FILL PAINTS

The table defining fill paints for individual data series. Property Index Name index Type Description

Intege Series index. r

2000-2013 Tibbo Technology Inc.

AggreGate Server

547

Series Fill Paint

seriesFillP aint

Data Table

Fill paint

590

to use for the series.

Property name: seriesFillPaints Property type: Data Table

AUTO POPULATE SERIES OUTLINE PAINTS

Flag indicating that different pre-defined series outline paints should be used instead of Default Outline Paint. Property name: autoPopulateSeriesOutlinePaints

Property type: Boolean

SERIES OUTLINE PAINTS

The table defining outline paints for individual data series. Property Index Series Outline Paint Name index Type Description

Intege Series index. r Outline paint

590

seriesOutli Data nePaint Table

to use for the series.

Property name: seriesOutlinePaints Property type: Data Table

AUTO POPULATE SERIES OUTLINE STROKE

Flag indicating that different pre-defined series outline strokes should be used instead of Default Outline Stroke. Property name: autoPopulateSeriesOutlineStrokes

Property type: Boolean

SERIES OUTLINE STROKE

The table defining outline strokes for individual data series. Property Index Series Outline Stroke Property name: Name index Type Integ er Description Series index. Outline stroke
593

seriesOutlin Data eStroke Table

to use for the series.

seriesOutlineStrokes

Property type: Data Table

SERIES VISIBILITY IN LEGEND

The table defining legend visibility for individual data series. Property Index Series Visible In Legend Property name: Name index seriesVisibl eInLegend Type Integ er Description Series index.

Boole Flag indicating whether or not the series is visible in legend. an

seriesVisibleInLegend

Property type: Data Table

LEGEND PROPERTIES

2000-2013 Tibbo Technology Inc.

548

AggreGate Documentation

The table defining the representation of individual series in the legend. Property Index Shape Text Paint Text Font Property name: Name index shape paint font Type Integ er Data Table Data Table Data Table Description Series index. Shape Paint Font
594

used to represent series in the legend.

590

used to represent series in the legend. used to represent series in the legend.

590

legendProperties

Property type: Data Table

SERIES ITEM LABEL PROPERTIES

The table defining the representation of item labels for individual series. Property Index Visible Font Paint Positive Items Position Negative Items Position Property name: Name index visible font paint positiveIte msPosition negativeIte msPosition Type Integ er Description Series index.

Boole Item labels visibility flag. an Data Table Data Table Data Table Data Table Font Paint
590

used to print items labels. used to print items labels.

499

590

Item Label Position

for positive items in this series.

Item Label Position

499

for negative items in this series.

seriesItemLabelProperties

Property type: Data Table

3.15.10.10.1 Category Renderer

Category Renderer is a base renderer for data items on a Category Plot and adds its own properties.
511 .

It inherits base renderer

542 's

properties

Properties
DEFAULT ITEM LABEL GENERATOR
The default Category Item Label Generator series. Property name:
520

used to create item labels when no custom generator is set for the

baseItemLabelGenerator

Property type: Data Table

DEFAULT ITEM TOOL TIP GENERATOR

The default Category Tool Tip Generator series. Property name:
520

used to create tool tips when there is no custom generator set for the

baseToolTipGenerator

Property type: Data Table

2000-2013 Tibbo Technology Inc.

AggreGate Server

549

LEGEND ITEM LABEL GENERATOR

The generator for the series name in the legend. Format string that may contain the {0} token to represent series name. Property name: legentItemLabelGenerator

Property type: Data Table

LEGEND ITEM TOOL TIP GENERATOR

The generator of the tool tips for the legend items. Format string that may contain the {0} token to represent series name. Property name: legentItemToolTipGenerator

Property type: Data Table

SERIES ITEM LABEL GENERATORS

The table defining item label generators for individual data series. Property Index Series Item Label Generator Property name: Name index seriesItemLa belGenerator Type Description

Intege Series index. r Data Table An item label generator

520

for the series.

seriesItemLabelGenerators

Property type: Data Table

SERIES TOOL TIP GENERATORS

The table defining item tool tip generators for individual data series. Property Index Series Item Tool Tip Generator Property name: Name index seriesToolTip Generator Type Description

Intege Series index. r Data Table An tool tip generator

520

for the series.

seriesToolTipGenerators

Property type: Data Table

3.15.10.10.1.1 Category Bar Renderer

This renderer is a subtype of Category Renderer 548 used in conjunction with a Category Plot inherits all Category Renderer's properties and has its own properties.
511

to create bar charts. It

Controlling the Width of Bars

The renderer automatically calculates the width of the bars to fit the available space for the plot, so you cannot directly control how wide the bars are. However, the bar width is a function of the following properties:

ITEM MARGIN
Item margin as a percentage of the overall length of the category axis (the default is 0.20, or twenty percent). This controls the amount of space that is allocated to the gaps between bars within the same category. Property name: itemMargin Property type: Float

2000-2013 Tibbo Technology Inc.

550

AggreGate Documentation

MAXIMUM BAR WIDTH

Maximum bar width as a percentage of the axis length. For example, setting this to 0.05 will ensure that the bars never exceed five percent of the length of the axis. This can improve the appearance of charts where there is a possibility that only one or two bars will be displayed. Example of a chart with limited maximum bar width:

Property name: maximumBarWidth Property type: Float

The Base Value

By default, the renderer draws a bar between zero (the base value) and the data value of the item to be displayed. Some specialized bar charts require a non-zero base value.

BASE
Base value for the bars. Property name: base Property type: Float

INCLUDE BASE IN RANGE

Flag that controls whether or not the base value is included in the auto range calculation for the range axis. Property name: includeBaseInRange Property type: Boolean

Item Labels
Due to the rectangular nature of the bars, the renderer calculates anchor points that are arranged as shown in figure below. Note that the numbers correspond (roughly) to the position of the hours on a clock face.

2000-2013 Tibbo Technology Inc.

AggreGate Server

551

When an item label is displayed inside a bar, the renderer will calculate if the bar is large enough to contain the text. If not, the renderer will check to see if a "fallback" label position has been specified. If there is a fallback position, the label is displayed there, and if there is no fallback position the label is not displayed at all. Two fallback positions can be specified, one for positive values and one for negative values (this covers the standard case where positive value labels that don't fit within a bar should be displayed above the bar, and negative value labels that don't fit within a bar should be displayed below the bar).

ITEM LABEL POSITION FALLBACK

This property includes two values: Positive Item Label Position 499 : fallback position for positive item labels. Set the value to null if you prefer labels to be hidden if they don't fit within the bar. Negative Item Label Position: fallback position for negative item labels. Set the value to null if you prefer labels to be hidden if they don't fit within the bar. Property name: itemLabelPositionFallback Property type: Data Table

Bar Shadows
SHADOWS VISIBLE
Flag that controls whether or not shadows are drawn for the bars. Property name: shadowsVisible Property type: Boolean

SHADOW PAINT
Paint
590

used to fill the bar shadows.

Property name: shadowPaint Property type: Data Table

SHADOW X OFFSET
X-offset for the bar shadows. Property name: shadowXOffset Property type: Float

2000-2013 Tibbo Technology Inc.

552

AggreGate Documentation

SHADOW Y OFFSET
Y-offset for the bar shadows. Property name: shadowYOffset Property type: Float

Other Properties
BAR PAINTER
Bar Painter takes care of the actual drawing of individual bars. It has the following properties: Property Type Name type Type Description

Intege Painter type: Standard or Gradient: r Standard bar painter uses a single Paint

590

(current series paint) to fill the bars.

Gradient bar painter applies the effect over several ranges to give the bars an interesting look. G1 G2 G3 g1 g2 g3 Float Float Float The division point between the first and second gradient regions (greater than 0.0). The division point between the second and third gradient regions (greater than G1). The division point between the third and fourth gradient regions (greater than G2 and less than 1.0).

Property name: barPainter Property type: Data Table

DRAW BAR OUTLINE

Flag that controls whether or not an outline is drawn around each bar. The paint and stroke used for the bar outline are specified using properties of a base chart renderer. Property name: drawBarOutline Property type: Boolean

MINIMUM BAR LENGTH

Sets the minimum length that will be used for a bar. You can set this to a small value (e.g. 1.0) to ensure that very short bars do not disappear. Property name: minimumBarLength Property type: Float

3.15.10.10.1.2 Category Line Renderer

This renderer is a subtype of Category Renderer 548 used in conjunction with a Category Plot 511 to create line charts. It displays data items by drawing a shape at each data point and/or connecting data points with straight lines.

Properties
SERIES LINES VISIBLE
The table defining item-to-item line visibility for individual data series. Property Index Series Lines Visible Name index seriesLine sVisible Type Description

Intege Series index. r Boole an Flag controlling visibility of item-to-item lines for the series.

Property name:

seriesLinesVisible

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: Data Table

553

SERIES SHAPES VISIBLE

The table defining item shape visibility for individual data series. Property Index Series Shapes Visible Name index seriesSha pesVisible Type Description

Intege Series index. r Boole an Flag controlling visibility of item shapes for the series.

Property name:

seriesShapesVisible

Property type: Data Table

SERIES SHAPES FILLED

The table controlling item shape filling for individual data series. Property Index Series Shapes Filled Name index seriesSha pesFilled Type Description

Intege Series index. r Boole an Flag controlling filling of item shapes for the series.

Property name:

seriesShapesFilled

Property type: Data Table

DEFAULT LINES VISIBLE

Default value for visibility of lines between data items. Property name: baseLinesVisible Property type: Boolean

DEFAULT SHAPES VISIBLE

Default value for item shape visibility. Property name: baseShapesVisible

Property type: Boolean

DEFAULT SHAPES FILL

Default setting for filling item shapes. Property name: baseShapesFilled

Property type: Boolean

DRAW OUTLINES
Flag that controls whether or not outlines are drawn around item shapes. Property name: drawOutlines Property type: Boolean

USE FILL PAINT

Flag that controls whether the series fill paint or the regular series paint is used to fill item shapes. Property name: useFillPaint Property type: Boolean

2000-2013 Tibbo Technology Inc.

554

AggreGate Documentation

USE OUTLINE PAINT

Flag that controls which paint is used for the shape outlines. The renderer uses one of two possible colors for the shape outlines The outline paint for the current series, or The regular paint for the current series. This property is valid for Line and Line 3D renderers. Property name: useOutlinePaint Property type: Boolean

USE SERIES OFFSET

Flag that controls whether or not the stepped lines for the series are offset from one another. Property name: useSeriesOffset Property type: Boolean

3.15.10.10.2 XY Renderer
XY Renderer is a base renderer for data items on an XY Plot own properties.
521 .

It inherits base renderer

542 's

properties and adds its

Properties
BASE ITEM LABEL GENERATOR
The default XY Item Label Generator Property name:
530

used to create item labels when no custom generator is set for the series.

baseItemLabelGenerator

Property type: Data Table

BASE ITEM TOOL TIP GENERATOR

The default XY Tool Tip Generator Property name:
535

used to create tool tips when there is no custom generator set for the series.

baseToolTipGenerator

Property type: Data Table

LEGEND ITEM LABEL GENERATOR

The generator for the series name in the legend. Format string that may contain the {0} token to represent series name. Property name: legentItemLabelGenerator

Property type: Data Table

LEGEND ITEM TOOL TIP GENERATOR

The generator of the tool tips for the legend items. Format string that may contain the {0} token to represent series name. Property name: legentItemToolTipGenerator

Property type: Data Table

SERIES ITEM LABEL GENERATORS

The table defining item label generators for individual data series. Property Index Name index Type Description

Intege Series index. r

2000-2013 Tibbo Technology Inc.

AggreGate Server

555

Series Item Label Generator Property name:

seriesItemLa belGenerator

Data Table

An item label generator

520

for the series.

seriesItemLabelGenerators

Property type: Data Table

SERIES TOOL TIP GENERATORS

The table defining item tool tip generators for individual data series. Property Index Series Item Tool Tip Generator Property name: Name index seriesToolTip Generator Type Description

Intege Series index. r Data Table An tool tip generator

520

for the series.

seriesToolTipGenerators

Property type: Data Table

SERIES RENDERING ORDER

Rendering order for the series in the dataset: Forward of Reverse . Series are, by default, rendered in reverse order (so that the first series in each dataset appears in front of all the other series in that dataset). Property name: seriesRenderingOrder

Property type: String

RENDERER ANNOTATIONS
Renderer annotations have two differences from plot annotations
522 :

1. It's possible to specify a Layer for every annotation, making it appear under of over the data. 2. When an XY chart is added as a subchart to a Mixed XY Chart 469 , plot's annotations are defined within a parent chart and bind to its primary axes, while sub-chart's renderer annotations are bind to the axes used by a sub-chart. Render annotation properties: Property Annotatio n Name Type Description Annotation type and properties table. The following standard annotation types are available: Box Annotation
528 529

annotation Data Table

Data Image Annotation Image Annotation Legend Annotation Line Annotation

531 532 533 529 530

Pointer Annotation Polygon Annotation Shape Annotation Text Annotation Title Annotation Layer layer String

534

534 535

Layer to put the annotation on: Foreground or Background .

Property name:

rendererAnnotations

Property type: Data Table

2000-2013 Tibbo Technology Inc.

556

AggreGate Documentation

3.15.10.10.2.1 XY Line Renderer

This renderer is a subtype of XY Renderer 554 used in conjunction with an XY Plot 521 to create line charts. It displays data items by drawing a shape at each data point and/or connecting data points with straight lines.

Properties
SERIES LINES VISIBLE
The table defining item-to-item line visibility for individual data series. Property Index Series Lines Visible Name index seriesLine sVisible Type Description

Intege Series index. r Boole an Flag controlling visibility of item-to-item lines for the series.

Property name:

seriesLinesVisible

Property type: Data Table

SERIES SHAPES VISIBLE

The table defining item shape visibility for individual data series. Property Index Series Shapes Visible Name index seriesSha pesVisible Type Description

Intege Series index. r Boole an Flag controlling visibility of item shapes for the series.

Property name:

seriesShapesVisible

Property type: Data Table

SERIES SHAPES FILLED

The table controlling item shape filling for individual data series. Property Index Series Shapes Filled Name index seriesSha pesFilled Type Description

Intege Series index. r Boole an Flag controlling filling of item shapes for the series.

Property name:

seriesShapesFilled

Property type: Data Table

BASE LINES VISIBLE

Default value for visibility of lines between data items. Property name: baseLinesVisible Property type: Boolean

BASE SHAPES VISIBLE

Default value for item shape visibility.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: baseShapesVisible

557

Property type: Boolean

BASE SHAPES FILLED

Default setting for filling item shapes. Property name: baseShapesFilled

Property type: Boolean

LEGEND LINE
This renderer allows a simple customization of the legend display where you can specify the shape but any shape is permitted) that will represent each series in the legend. Property name: legendLine Property type: Data Table
594

(typically a line,

DRAW OUTLINES
Flag that controls whether or not outlines are drawn around item shapes. Property name: drawOutlines Property type: Boolean

DRAW SERIES LINE AS PATH

It is common to used a dashed stroke to draw the connecting lines between items within a series. An issue arises when the items within a series are close together on the chart, because by default the renderer will draw the connecting line individually for each data item (connecting the current item to the previous item). The stroke pattern for the line is reset for each segment, which can result in the stroke pattern not being visible for the series. A workaround is available, in which the connecting lines for the entire series are drawn as a single line. Draw Series Line As Path flag that controls whether the connecting lines between the data items are drawn as a path, or individually. Property name: drawSeriesLineAsPath

Property type: Boolean

USE FILL PAINT

Flag that controls whether the series fill paint or the regular series paint is used to fill item shapes. Property name: useFillPaint Property type: Boolean

USE OUTLINE PAINT

Flag that controls which paint is used for the shape outlines. The renderer uses one of two possible colors for the shape outlines The outline paint for the current series, or The regular paint for the current series. Property name: useOutlinePaint Property type: Boolean

3.15.11 Gauges
Gauges ensure easily readable visualization of numeric values. The following gauge types are supported: Simple Gauge
558

Simple Arc Gauge Radial Gauge

563

2000-2013 Tibbo Technology Inc.

558

AggreGate Documentation

Radial Bargraph Gauge Arc Gauge Half-Round Gauge Quarter-Round Gauge Linear Gauge Linear Bargraph Gauge Counter Gauge

3.15.11.1 Simple Gauge

This component displays a simple gauge with one or more pointers and scales. This is what a simple gauge component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

Custom Properties
DATA VALUES (Default Property
586 ) 586 .

A list of data values that will be indicated by the gauge. This is an indexed property Property name: datasets Property type: Data Table

BACKGROUND
Gauge background (may be a solid color, linear/radial gradient or texture). Fields of gauge background: Field Visible Paint Type Boolean Data Table Description Flag that determines whether or not the background is drawn. Paint
590

used to fill the background.

Property name: gaugeBackground Property type: Data Table

2000-2013 Tibbo Technology Inc.

AggreGate Server

559

FRAME
Properties of Circle-type frame. Fields of gauge frame: Field Visible Background Paint Foreground Paint Radius Stroke Type Boolean Data Table Data Table Float Data Table Description Flag that determines whether or not the frame is drawn. Paint 590 used to fill the space between the double lines around the outer edge of the frame circle. Paint
590

used to draw the double lines around the outside of the gauge.

Radius, expressed as a percentage relative to the framing rectangle. Stroke

593

used to draw the frame outline.

Property name: frame Property type: Data Table

VIEW
The dimensions of the dial plot are calculated relative to a framing rectangle, but in some cases it is required only a subset of the dial to be presented in the plot area. The View parameter allows it by setting the viewing rectangle relative to the plots framing rectangle. Fields of view: Field X Y Width Height Type Float Float Float Float Description The relative position of the viewing rectangles x-coordinate with reference to the framing rectangle. The value can be in the range 0.0 to 1.0. The relative position of the viewing rectangles y-coordinate with reference to the framing rectangle. The value can be in the range 0.0 to 1.0. The relative width of the viewing rectangle with reference to the framing rectangle. The value can be in the range 0.0 to 1.0. The relative height of the viewing rectangle with reference to the framing rectangle. The value can be in the range 0.0 to 1.0.

Property name: view Property type: Data Table

CAP
Gauge cap. This is the circle in the middle of the gauge (to which the needles connect). Fields of gauge cap: Field Visible Fill Paint Outline Paint Outline Stroke Radius Type Boolean Data Table Data Table Data Table Float Description Flag that determines whether or not the cap is drawn. Paint Paint
590 590

used to fill the cap. used to draw the cap outline. used to draw the caps outline.

Stroke

593

Radius for the cap, as a percentage of the size of the gauges framing rectangle.

Property name: cap Property type: Data Table

SCALES
A table of gauge scales and their associations with Data Values defines which data value will be indicated on the scale.
558 .

Every record has a Data Value Index field that

2000-2013 Tibbo Technology Inc.

560

AggreGate Documentation

The scale can display major and minor tick marks at user-specified intervals, and numerical labels for the major tick marks. To control the arc through which the scale is drawn on the gauge, you can specify the starting angle and the extent (in degrees). Fields of the scales table: Field Data Value Index Scale Type Integer Data Table Description Index of the data value indicated on the scale. Scale properties.

Fields of gauge scale: Field Visible Lower Bound Upper Bound Start Angle Extent Tick Radius Description Flag that determines whether or not the scale is drawn. Lower bound for the scale. Upper bound for the scale. Angle (in degrees) for the starting point of the scale. Extent (in degrees) for the scale. The tick radius determines how far out on the gauge the tick marks are drawn (typically they will appear near the outer edge of the gauge, but for a gauge that shows more than one scale you might want to show a scale closer to the center). The tick radius defines the reference point for the major and minor tick marks, as well as the labels for the major tick marks. It is specified as a percentage of the gauges framing rectangle. Interval between major tick marks. Length of the major tick marks, expressed as an amount to be subtracted from the tick radius. Paint
590

Major Tick Increment Major Tick Length Major Tick Paint Major Tick Stroke Minor Tick Count Minor Tick Length Minor Tick Paint Minor Tick Stroke Tick Label Font Tick Label Formatter Tick Label Offset Tick Label Paint Tick Labels Visible First Tick Label Visible

used to draw the major tick marks. used to draw the major tick marks.

Stroke

593

Number of minor tick marks to display between each pair of major tick marks. Length of minor tick marks, as a radius specified as a percentage of the gauges framing rectangle. Paint
590

used to draw the minor tick marks. used to draw the minor tick marks.

Stroke Font
590

593

used to display the tick labels.

Number formatter 1322 used to convert the tick label values to strings. The anchor point for each label is determined using the tick radius adjusted by an offset value. Once the anchor point is determined, the value label is centered on the anchor point. Paint
590

used to display the tick labels.

Flag that controls whether or not the tick labels are visible. Flag that controls whether or not the first tick label is visible.

Property name: scales Property type: Data Table

RANGES
Gauge ranges. Every range is painted as a color arc. It is used to highlight a range of values, e.g. normal, high and extreme. The range is primarily defined by its lower and upper bounds. The range highlights are drawn at a specified radius within the gauge. Fields of gauge range:

2000-2013 Tibbo Technology Inc.

AggreGate Server

561

Field Visible Scale Index Lower Bound Upper Bound Inner Radius Outer Radius Paint

Type Boolean Integer Float Float Float Float Data Table

Description Flag that determines whether or not the range is drawn. Range is measured relatively to a scale with specific index. Lower bound for the range, in data units. Upper bound for the range, in data units. Radius for the inner highlight of the range, as a percentage of the size of the gauges framing rectangle. Radius for the outer highlight of the range, as a percentage of the size of the gauges framing rectangle. Paint
590

used to highlight the range.

Property name: ranges Property type: Data Table

NORMAL POINTERS
A list of normal pointers, drawn as long triangular shapes. Pointers are used for indicating the current value on the gauge. Fields of normal pointer: Field Data Value Index Visible Fill Paint Outline Paint Radius Width Radius Type Integer Boolean Data Table Data Table Float Float Description Index of data value
558

indicated by the pointer.

Flag that determines whether or not the pointer is drawn. Paint Paint
590 590

used to fill the pointer. used to draw the outline of the pointer.

Length of the pointer, as a percentage of the size of the gauges framing rectangle. The width of the base of the pointer is specified as a radius, in percentage terms relative to the size of the gauges framing rectangle.

Property name: normalPointers Property type: Data Table

PIN POINTERS
A list of pin pointers. A pin pointer that is drawn as a thin straight line. Pointers are used for indicating the current value on the gauge. Fields of pin pointer: Field Data Value Index Visible Paint Radius Stroke Type Integer Boolean Data Table Float Data Table Description Index of data value
558

indicated by the pointer.

Flag that determines whether or not the pointer is drawn. Paint

590

used to draw the pointer.

Length of the pointer, as a percentage of the size of the gauges framing rectangle. Stroke
593

used to draw the pointer.

Property name: pinPointers Property type: Data Table

VALUE INDICATORS

2000-2013 Tibbo Technology Inc.

562

AggreGate Documentation
558 .

A list of value indicators showing current data values Fields of value indicator: Field Data Value Index Visible Angle Radius Font Frame Anchor Type Integer Boolean Float Float Data Table String Description

Index of data value

558

shown by the indicator.

Flag that determines whether or not the indicator is drawn. The anchor point for positioning the indicator is specified in terms of an angle and a radius. This property is the angle, in degrees, for calculating the anchor point. Radius, relative to the gauges framing rectangle. Font
590

used to display the indicator value.

The value indicator is displayed as a text item in a frame. The frame anchor specifies the point on this frame that will be aligned to the anchor point (which is calculated from the angle and radius). Insets (top, left, bottom, right) which determine the white-space around the indicator value. Number formatter 1322 used to format the value. Paint
590

Insets Number Format Outline Paint Outline Stroke Paint Background Paint Template Value

Data Table String Data Table Data Table Data Table Data Table Float

used to draw the outline around the indicator. used to draw the outline around the indicator.

Stroke Paint Paint

593

590 590

used to display the indicator value. used to fill the background of the indicator.

To ensure that the value indicator has a fixed width regardless of the current value in the dataset, a template value is used to calculate the dimensions of the indicator. This template value will be formatted using the current number formatter, then the dimensions of the string will be used to determine the dimensions of the value indicator. The value anchor determines the point to which the value text will be aligned. Point on the text that is aligned to the value anchor.

Value Anchor Text Anchor

String String

Property name: indicators Property type: Data Table

TEXT ANNOTATIONS
A list of text annotations. Text annotation is a text string displayed at an arbitrary location on a gauge. Fields of text annotation: Field Label Visible Angle Radius Anchor Paint Font Type String Boolean Float Float String Data Table Data Table Description Text displayed by the annotation. Flag that determines whether or not the annotation is drawn. The anchor point for the text label is defined by an angle and a radius. This property is the angle (in degrees) that determines the text anchor point. Radius used to determine text anchor point, as a percentage relative to the gauges framing rectangle. Anchor specifies how text is aligned to its anchor point. Paint Font
590 590

used to display the label. used to display the label.

Property name: annotations Property type: Data Table

2000-2013 Tibbo Technology Inc.

AggreGate Server

563

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.2 Simple Arc Gauge

This component displays a simple arc gauge with one or more pointers and scales. This is what a simple arc gauge component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 ,

Enabled

586 ,

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

Custom Properties
DATA VALUES (Default Property
586 ) 586 .

A list of data values that will be indicated by the gauge. This is an indexed property Property name: datasets Property type: Data Table

BACKGROUND
Gauge background (may be a solid color, linear/radial gradient or texture). Fields of gauge background: Field Visible Paint Type Boolean Data Table Description Flag that determines whether or not the background is drawn. Paint
590

used to fill the background.

Property name: gaugeBackground Property type: Data Table

FRAME
Fields of gauge frame:

2000-2013 Tibbo Technology Inc.

564

AggreGate Documentation

Field Visible Foreground Paint Start Angle Extent Inner Radius Outer Radius Stroke

Type Boolean Data Table Float Float Float Float Data Table

Description Flag that determines whether or not the frame is drawn. Paint
590

used to draw the double lines around the outside of the gauge.

Arc start angle, in degrees. Arc extent angle, in degrees. Arc inner radius, expressed as a percentage relative to the framing rectangle. Arc outer radius, expressed as a percentage relative to the framing rectangle. Stroke
593

used to draw the frame outline.

Property name: arcFrame Property type: Data Table

VIEW
The dimensions of the dial plot are calculated relative to a framing rectangle, but in some cases it is required only a subset of the dial to be presented in the plot area. The View parameter allows it by setting the viewing rectangle relative to the plots framing rectangle. Fields of view: Field X Y Width Height Type Float Float Float Float Description The relative position of the viewing rectangles x-coordinate with reference to the framing rectangle. The value can be in the range 0.0 to 1.0. The relative position of the viewing rectangles y-coordinate with reference to the framing rectangle. The value can be in the range 0.0 to 1.0. The relative width of the viewing rectangle with reference to the framing rectangle. The value can be in the range 0.0 to 1.0. The relative height of the viewing rectangle with reference to the framing rectangle. The value can be in the range 0.0 to 1.0.

Property name: view Property type: Data Table

CAP
Gauge cap. This is the circle in the middle of the gauge (to which the needles connect). Fields of gauge cap: Field Visible Fill Paint Outline Paint Outline Stroke Radius Type Boolean Data Table Data Table Data Table Float Description Flag that determines whether or not the cap is drawn. Paint Paint
590 590

used to fill the cap. used to draw the cap outline. used to draw the caps outline.

Stroke

593

Radius for the cap, as a percentage of the size of the gauges framing rectangle.

Property name: cap Property type: Data Table

SCALES
A table of gauge scales and their associations with Data Values defines which data value will be indicated on the scale.
558 .

Every record has a Data Value Index field that

The scale can display major and minor tick marks at user-specified intervals, and numerical labels for the major tick marks. To control the arc through which the scale is drawn on the gauge, you can specify the starting angle and the extent (in degrees).

2000-2013 Tibbo Technology Inc.

AggreGate Server
Fields of the scales table: Field Data Value Index Scale Type Integer Data Table Description Index of the data value indicated on the scale. Scale properties.

565

Fields of gauge scale: Field Visible Lower Bound Upper Bound Start Angle Extent Tick Radius Description Flag that determines whether or not the scale is drawn. Lower bound for the scale. Upper bound for the scale. Angle (in degrees) for the starting point of the scale. Extent (in degrees) for the scale. The tick radius determines how far out on the gauge the tick marks are drawn (typically they will appear near the outer edge of the gauge, but for a gauge that shows more than one scale you might want to show a scale closer to the center). The tick radius defines the reference point for the major and minor tick marks, as well as the labels for the major tick marks. It is specified as a percentage of the gauges framing rectangle. Interval between major tick marks. Length of the major tick marks, expressed as an amount to be subtracted from the tick radius. Paint
590

Major Tick Increment Major Tick Length Major Tick Paint Major Tick Stroke Minor Tick Count Minor Tick Length Minor Tick Paint Minor Tick Stroke Tick Label Font Tick Label Formatter Tick Label Offset Tick Label Paint Tick Labels Visible First Tick Label Visible

used to draw the major tick marks. used to draw the major tick marks.

Stroke

593

Number of minor tick marks to display between each pair of major tick marks. Length of minor tick marks, as a radius specified as a percentage of the gauges framing rectangle. Paint
590

used to draw the minor tick marks. used to draw the minor tick marks.

Stroke Font
590

593

used to display the tick labels.

Number formatter 1322 used to convert the tick label values to strings. The anchor point for each label is determined using the tick radius adjusted by an offset value. Once the anchor point is determined, the value label is centered on the anchor point. Paint
590

used to display the tick labels.

Flag that controls whether or not the tick labels are visible. Flag that controls whether or not the first tick label is visible.

Property name: scales Property type: Data Table

RANGES
Gauge ranges. Every range is painted as a color arc. It is used to highlight a range of values, e.g. normal, high and extreme. The range is primarily defined by its lower and upper bounds. The range highlights are drawn at a specified radius within the gauge. Fields of gauge range: Field Visible Type Boolean Description Flag that determines whether or not the range is drawn.

2000-2013 Tibbo Technology Inc.

566

AggreGate Documentation

Scale Index Lower Bound Upper Bound Inner Radius Outer Radius Paint

Integer Float Float Float Float Data Table

Range is measured relatively to a scale with specific index. Lower bound for the range, in data units. Upper bound for the range, in data units. Radius for the inner highlight of the range, as a percentage of the size of the gauges framing rectangle. Radius for the outer highlight of the range, as a percentage of the size of the gauges framing rectangle. Paint
590

used to highlight the range.

Property name: ranges Property type: Data Table

NORMAL POINTERS
A list of normal pointers, drawn as long triangular shapes. Pointers are used for indicating the current value on the gauge. Fields of normal pointer: Field Data Value Index Visible Fill Paint Outline Paint Radius Width Radius Type Integer Boolean Data Table Data Table Float Float Description Index of data value
558

indicated by the pointer.

Flag that determines whether or not the pointer is drawn. Paint Paint
590 590

used to fill the pointer. used to draw the outline of the pointer.

Length of the pointer, as a percentage of the size of the gauges framing rectangle. The width of the base of the pointer is specified as a radius, in percentage terms relative to the size of the gauges framing rectangle.

Property name: normalPointers Property type: Data Table

PIN POINTERS
A list of pin pointers. A pin pointer that is drawn as a thin straight line. Pointers are used for indicating the current value on the gauge. Fields of pin pointer: Field Data Value Index Visible Paint Radius Stroke Type Integer Boolean Data Table Float Data Table Description Index of data value
558

indicated by the pointer.

Flag that determines whether or not the pointer is drawn. Paint

590

used to draw the pointer.

Length of the pointer, as a percentage of the size of the gauges framing rectangle. Stroke
593

used to draw the pointer.

Property name: pinPointers Property type: Data Table

VALUE INDICATORS
A list of value indicators showing current data values Fields of value indicator:
558 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

567

Field Data Value Index Visible Angle Radius Font Frame Anchor

Type Integer Boolean Float Float Data Table String

Description Index of data value

558

shown by the indicator.

Flag that determines whether or not the indicator is drawn. The anchor point for positioning the indicator is specified in terms of an angle and a radius. This property is the angle, in degrees, for calculating the anchor point. Radius, relative to the gauges framing rectangle. Font
590

used to display the indicator value.

The value indicator is displayed as a text item in a frame. The frame anchor specifies the point on this frame that will be aligned to the anchor point (which is calculated from the angle and radius). Insets (top, left, bottom, right) which determine the white-space around the indicator value. Number formatter 1322 used to format the value. Paint
590

Insets Number Format Outline Paint Outline Stroke Paint Background Paint Template Value

Data Table String Data Table Data Table Data Table Data Table Float

used to draw the outline around the indicator. used to draw the outline around the indicator.

Stroke Paint Paint

593

590 590

used to display the indicator value. used to fill the background of the indicator.

To ensure that the value indicator has a fixed width regardless of the current value in the dataset, a template value is used to calculate the dimensions of the indicator. This template value will be formatted using the current number formatter, then the dimensions of the string will be used to determine the dimensions of the value indicator. The value anchor determines the point to which the value text will be aligned. Point on the text that is aligned to the value anchor.

Value Anchor Text Anchor

String String

Property name: indicators Property type: Data Table

TEXT ANNOTATIONS
A list of text annotations. Text annotation is a text string displayed at an arbitrary location on a gauge. Fields of text annotation: Field Label Visible Angle Radius Anchor Paint Font Type String Boolean Float Float String Data Table Data Table Description Text displayed by the annotation. Flag that determines whether or not the annotation is drawn. The anchor point for the text label is defined by an angle and a radius. This property is the angle (in degrees) that determines the text anchor point. Radius used to determine text anchor point, as a percentage relative to the gauges framing rectangle. Anchor specifies how text is aligned to its anchor point. Paint Font
590 590

used to display the label. used to display the label.

Property name: annotations Property type: Data Table

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

568
597

AggreGate Documentation
597 ,

, Focus Gained

Focus Lost

597

3.15.11.3 Radial Gauge

This component displays a highly-configurable radial gauge. This is what a radial gauge component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

All Common Radial Gauge Properties

584 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.4 Radial Bargraph Gauge

This component displays a highly-configurable radial bargraph gauge. This is what a radial bargraph gauge component looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

569

Common Properties
Width
586

, Height

586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

All Common Radial Gauge Properties

584 .

Custom Properties
BAR GRAPH COLOR
Color or the bar graph (one of the pre-defined values). Property name: barGraphColor Property type: Color

PEAK VALUE VISIBLE

Controls the visibility of the peak value which is the last measured value. Property name: peakValueVisible Property type: Boolean

PEAK VALUE
The peak value of the gauge. Used in the bargraph gauges to visualize the last displayed value. Property name: peakValue Property type: Double

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.5 Arc Gauge

This component displays a highly-configurable arc gauge. This is what an arc gauge component looks like:

Common Properties

2000-2013 Tibbo Technology Inc.

570
Width
586

AggreGate Documentation
, Height
586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

All Common Radial Gauge Properties

584 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.6 Half-Round Gauge

This component displays a highly-configurable half-round gauge. This is what a half-round gauge component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

All Common Radial Gauge Properties

584 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.7 Quarter-Round Gauge

This component displays a highly-configurable quarter-round gauge. This is what a quarter-round gauge component looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

571

Common Properties
Width
586

, Height

586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

All Common Radial Gauge Properties

584 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.8 Linear Gauge

This component displays a highly-configurable linear gauge. This is what a linear gauge component looks like:

2000-2013 Tibbo Technology Inc.

572

AggreGate Documentation

Common Properties
Width
586

, Height

586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.9 Linear Bargraph Gauge

This component displays a highly-configurable linear bargraph gauge. This is what a linear bargraph gauge component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

2000-2013 Tibbo Technology Inc.

AggreGate Server

573

3.15.11.10 Counter Gauge

This component displays a highly-configurable counter gauge. This is what a counter gauge component looks like:

Common Properties
Width
586

, Height

586

, Bindings

586 , 573 .

Visible

587 ,

Border

587 ,

Cursor

587 ,

Popup Menu

588

All Common Gauge Properties

All Common Radial Gauge Properties

584 .

Custom Properties
None defined.

Common Events
Hidden 595 , Shown 595 , Moved 596 , Resized 596 , Mouse Clicked 596 , Mouse Pressed 596 , Mouse Released Entered 596 , Mouse Exited 596 , Mouse Moved 596 , Mouse Wheel Moved 597 , Key Typed 597 , Key Pressed 597 , Focus Gained 597 , Focus Lost 597
596 , 597 ,

Mouse Key Released

3.15.11.11 Gauge Common Properties

This article describes properties that are available in all gauge types.

Basic Properties
BACKGROUND VISIBLE
Defines whether the background image is visible and will be painted. Property name: backgroundVisible Property type: Boolean

BACKGROUND COLOR
The background color of the gauge (one of the pre-defined values). Property name: backgroundColor Property type: String

CUSTOM BACKGROUND

2000-2013 Tibbo Technology Inc.

574

AggreGate Documentation
590 .

Custom frame design paint

This will be used if the Background Color property is set to Custom .

Property name: customBackground Property type: Data Table

FOREGROUND VISIBLE
Enables/disables the visibility of the glass effect foreground image. If enabled the foreground image will be painted. Property name: foregroundVisible Property type: Boolean

ORIENTATION
The orientation of the gauge. Property name: orientation Property type: String

VALUE COUPLED
Enables/disables automatic setting of gauge's LCD value when gauge primary value is changed. Property name: valueCouples Property type: Boolean

AUTO RESET TO ZERO

Enables/disables the mode where the gauge will return to zero after a value was set. Means if you set a value the pointer will move to this value and after it reached the given value it will return back to zero. Property name: autoResetToZero Property type: Boolean

STANDARD TIME TO VALUE

The time in milliseconds that the pointer/bar/led needs to move from the minimum value of the gauge to the maximum of the gauge in standard mode. The minimum time is 250 ms and the maximum time is 5000 ms. Property name: stdTimeToValue Property type: Long

TIME BACK TO ZERO

The time in milliseconds that the pointer/bar/led needs back from the value to zero in autoreturn to zero mode. The minimum time is 250 ms and the maximum time is 5000 ms. Property name: rtzTimeBackToZero

Property type: Long

TIME TO VALUE
The time in milliseconds that the pointer/bar/led needs to move from the minimum value of the gauge to the maximum of the gauge in autoreturn to zero mode. The minimum time is 250 ms and the maximum time is 5000 ms. Property name: rtzTimeToValue Property type: Long

MIN MEASURED VALUE VISIBLE

The visibility of the Minimal Measured Value indicator. Property name: minMeasuredValueVisible

Property type: Boolean

MAX MEASURED VALUE VISIBLE

The visibility of the Maximal Measured Value indicator.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: maxMeasuredValueVisible

575

Property type: Boolean

VALUE
Value to display on the gauge. Same value will be displayed in the gauge's LCD if Value Coupling option is enabled. Property name: value Property type: Double

MAX VALUE
Sets the maximum value of the measurement range of this gauge. This value defines the maximum value the gauge could display. Property name: maxValue Property type: Double

MIN VALUE
Sets the minimum value of the measurement range of this gauge. This value defines the minimum value the gauge could display. Property name: minValue Property type: Double

Frame Properties
This section describes properties of gauge frame.

FRAME VISIBLE
Enables/disables the visibility of the frame. Property name: frameVisible Property type: Boolean

FRAME DESIGN
The frame design of the gauge (one of the pre-defined values). The frame design is some kind of a color scheme for the frame of the component. Property name: frameDesign Property type: String

FRAME EFFECT
The pseudo 3D effect of the frame. Property name: frameEffect Property type: String

FRAME BASE COLOR ENABLED

Enables/disables usage of the Frame Base Color to colorize the Shiny Metal Frame Design. Property name: frameBaseColorEnabled

Property type: Boolean

FRAME BASE COLOR

The color that will be used to colorize the Shiny Metal Frame Design. Property name: frameBaseColor Property type: Color

CUSTOM FRAME DESIGN

2000-2013 Tibbo Technology Inc.

576

AggreGate Documentation
590

The custom paint Property name:

that will be used if Frame Design property is set to Custom.

customFrameDesign

Property type: Data Table

Glow Properties
This section describes properties of gauge glow effect.

GLOW VISIBLE
Enables/disables the glow indicator. Property name: glowVisible Property type: Boolean

GLOW PULSATING
Enables/disables the pulsating of the glow effect. Property name: glowPulsating Property type: Boolean

GLOWING
Enables/disables glowing of the glow indicator. Property name: glowing Property type: Boolean

GLOW COLOR
The color that will be used for the glow indicator. Property name: glowColor Property type: Color

Led Properties
This section describes properties of gauge LEDs. Each gauge may have up to two LEDs: a threshold LED and a usercontrolled LED.

LED VISIBLE
Enables/disables visibility of the threshold LED (one of the pre-defined values). Property name: ledVisible Property type: Boolean

LED COLOR
The color of the threshold LED. Property name: ledColor Property type: String

USER LED VISIBLE

Controls the visibility of the user LED. Property name: userLedVisible Property type: Boolean

USER LED ON
Switches the user LED on or off. Property name: userLedOn

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: Boolean

577

USER LED BLINKING

Enables/disables blinking of the user LED. Property name: userLedBlinking Property type: Boolean

USER LED COLOR

The color of the user LED (one of the pre-defined values). Property name: userLedColor Property type: String

LED POSITION
The position of the gauge threshold LED defined as (X, Y) values. The X and Y should be in range 0...1 as they indicate LED position within the gauge space. Property name: ledPosition Property type: Data Table

USER LED POSITION

The position of the gauge threshold LED defined as (X, Y) values. The X and Y should be in range 0...1 as they indicate LED position within the gauge space. Property name: userLedPosition Property type: Data Table

Scale Properties
This section describes properties of gauge scale.

TICK MARKS VISIBLE

Enables or disables the visibility of the tickmarks. Property name: tickmarksVisible Property type: Boolean

TICK MARK SECTIONS VISIBLE

Controls the visibility of the tickmark sections. Property name: tickmarkSectionsVisible

Property type: Boolean

TICK MARK SECTIONS

A list of tickmark sections. The sections are defined by a start value, a stop value, a color, and highlight color. This might be a useful feature if you need to have exactly defined areas that you would like to visualize by by colored tickmarks. Property name: tickmarkSections

Property type: Data Table

TICK MARK COLOR FROM THEME ENABLED

Enables/disables usage of a separate color for the tickmarks. Property name: tickmarkColorFromThemeEnabled

Property type: Boolean

TICK MARK COLOR

The color of the tickmarks and their labels.

2000-2013 Tibbo Technology Inc.

578

AggreGate Documentation

Property name: tickmarkColor Property type: Color

TICK LABELS VISIBLE

Enables or disables the visibility of the tickmark labels. Property name: ticklabelsVisible Property type: Boolean

LABEL NUMBER FORMAT

The number format that will be used to display the labels of the tickmarks. The following formats are available: Auto, Standard, Fractional and Scientific. Property name: labelNumberFormat

Property type: String

MINOR TICKMARK VISIBLE

Enables/disables the visibility of the minor tickmarks. Property name: minorTickmarkVisible

Property type: Boolean

MINOR TICKMARK TYPE

The current type of tickmark that is used for minor tickmarks. Value could be Line (default), Circle, Triangle or Square. Property name: minorTickmarkType

Property type: String

MINOR TICK SPACING

The spacing between the minor tickmarks if the Nice Scale property is disabled. Property name: minorTickSpacing Property type: Double

MAJOR TICKMARK VISIBLE

Enables/disables visibility of the major tickmarks. Property name: majorTickmarkVisible

Property type: Boolean

MAJOR TICKMARK TYPE

The current type of tickmark that is used for major tickmarks. Value could be Line (default), Circle, Triangle or Square. Property name: majorTickmarkType

Property type: String

MAJOR TICK SPACING

The spacing between the major tickmarks if the Nice Scale property is disabled Property name: majorTickSpacing

Property type: Double

NICE SCALE
Enables/disables the calculation of nice values for the min and max values of the scale. Property name: niceScale Property type: Boolean

LOG SCALE

2000-2013 Tibbo Technology Inc.

AggreGate Server
Enables/disables logarithmic scaling for the axis. Property name: logScale Property type: Boolean

579

MAX NUMBER OF MINOR TICKS

Maximum number of minor tickmarks. Property name: maxNoOfMinorTicks Property type: Integer

MAX NUMBER OF MAJOR TICKS

Maximum number of major tickmarks. Property name: maxNoOfMajorTicks Property type: Integer

Track Properties
Track is an area that could be defined by a start value, a section value, and a stop value. This area will be painted with a gradient that uses two or three given colors. E.g. a critical area of a thermometer could be defined between 30 and 100 degrees celsius and could have a gradient from green over yellow to red. In this case the start value would be 30, the stop value would be 100 and the section could be somewhere between 30 and 100 degrees. The track can be used in addition to gauge Areas and Sections.

TRACK VISIBLE
Controls visibility of the track. Property name: trackVisible Property type: Boolean

TRACK START
Value where the track will start. Property name: trackStart Property type: Double

TRACK START COLOR

Color of the point where the track starts. Property name: trackStartColor Property type: Color

TRACK SECTION
Value of the middle point between Track Start and Track Stop. Property name: trackSection Property type: Double

TRACK SECTION COLOR

Color of the track section (middle) point. Property name: trackSectionColor

Property type: Color

TRACK STOP
Value where the track will end. Property name: trackStop

2000-2013 Tibbo Technology Inc.

580

AggreGate Documentation

Property type: Double

TRACK STOP COLOR

Color of the point where the track ends. Property name: trackStopColor Property type: Color

Title Properties
This section describes properties of gauge title and unit labels.

TITLE AND UNIT FONT ENABLED

Enables and disables the usage of a custom title and unit label font. Property name: titleAndUnitFontEnabled

Property type: Boolean

TITLE
The title of the gauge, e.g. "Temperature". Property name: title Property type: String

TITLE AND UNIT FONT

Font
590

that will be used for the title and unit labels.

Property name: titleAndUnitFont Property type: Data Table

UNIT STRING
Unit string of the gauge, e.g. "[cm]". Property name: unitString Property type: String

LABEL COLOR FROM THEME ENABLED

Enables/disables usage of a separate color for the title and unit labels. Property name: labelColorFromThemeEnabled

Property type: Boolean

LABEL COLOR
Color of the title and unit labels. Property name: labelColor Property type: Color

Threshold Properties
This section describes properties of gauge's threshold indicator.

THRESHOLD VISIBLE
Controls visibility of the threshold indicator. Property name: thresholdVisible Property type: Boolean

THRESHOLD

2000-2013 Tibbo Technology Inc.

AggreGate Server
Value at that the threshold indicator is displayed. Property name: threshold Property type: Double

581

THRESHOLD TYPE
Type of the threshold indicator (Arrow or Triangle). Property name: thresholdType Property type: String

THRESHOLD COLOR
Color of the threshold indicator (one of the pre-defined values). Property name: thresholdColor Property type: String

THRESHOLD BEHAVIOUR INVERTED

Enables/disables inversion of the threshold behaviour. Property name: thresholdBehaviourInverted

Property type: Boolean

Area Properties
Areas are visual pie sections of a gauge that visualize certain value ranges. Areas can be used in addition to gauge Track and Sections.

AREAS VISIBLE
Sets the visibility of the areas. Property name: areasVisible Property type: Boolean

AREAS
List of the areas. Each ares is defined by a start value, a stop value, and a color. Property name: areas Property type: Data Table

HIGHLIGHT AREA
Enables/disables highlighting of the area that contains the current value. Property name: highlightArea Property type: Boolean

AREAS 3D EFFECT VISIBLE

Controls 3D-like appearance of areas. Property name: areas3DEffectVisible

Property type: Boolean

TRANSPARENT AREAS ENABLED

Enables / disables the usage of a transparent color for filling areas. Property name: transparentAreasEnabled

Property type: Boolean

Section Properties

2000-2013 Tibbo Technology Inc.

582

AggreGate Documentation

Sections are colorized parts of gauge's scale. Sections can be used in addition to gauge Track and Areas.

SECTIONS VISIBLE
Controls visibility of the sections. Property name: sectionsVisible Property type: Boolean

SECTIONS
List of the sections. Each section is defined by a start value, a stop value, a color, and a highlight color. Property name: sections Property type: Data Table

SECTION TICK MARKS ONLY

Controls whether only tickmarks of the sections are visible. Property name: sectionTickmarksOnly

Property type: Boolean

HIGHLIGHT SECTION
Enables/disables highlighting of the section that contains current value. Property name: highlightSection Property type: Boolean

SECTION 3D EFFECT VISIBLE

Controls 3D-like appearance of sections. Property name: section3DEffectVisible

Property type: Boolean

TRANSPARENT SECTIONS ENABLED

Enables/disables the usage of a transparent color for filling sections. Property name: transparentSectionsEnabled

Property type: Boolean

LCD Properties
Each gauge may display an LCD-like display with numeric presentation of gauge value. This section describes LCD display properties.

LCD VISIBLE
Enables or disables visibility of the LCD display. Property name: lcdVisible Property type: Boolean

USER LCD VALUE

If gauge's Value Coupling flag is disabled, LCD will display separate numeric value defined by this property. Property name: lcdValue Property type: Double

COLOR
Background color of the LCD display. Property name: lcdColor

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: String

583

DECIMALS
Number of decimal digits that will be used to visualize values in the LCD display. Property name: lcdDecimals Property type: Integer

INFO STRING
Arbitrary text displayed on the top of LCD display. Property name: lcdInfoString Property type: String

INFO FONT
Font
590

used to display the Info String.

Property name: lcdInfoFont Property type: Data Table

NUMBER SYSTEM
Number system that will be used to display the current LCD value (Decimal, Hexadecimal, or Octal). Property name: lcdNumberSystem Property type: String

SCIENTIFIC FORMAT
Enables/disables the scientific format of LCD value. Property name: lcdScientificFormat

Property type: Boolean

THRESHOLD VISIBLE
Enables/disables visibility of the LCD threshold indicator. Property name: lcdThresholdVisible

Property type: Boolean

THRESHOLD
Value of the LCD indicator's threshold. Property name: lcdThreshold Property type: Double

THRESHOLD BEHAVIOUR INVERTED

Enables/disables inversion of the LCD threshold behaviour. Property name: lcdthresholdBehaviourInverted

Property type: Boolean

UNIT STRING VISIBLE

Enables/disables visibility of the unit string in the LCD display. Property name: lcdUnitStringVisible Property type: Boolean

VALUE FONT
Font
590

that will be used to visualize the value on the LCD display.

2000-2013 Tibbo Technology Inc.

584

AggreGate Documentation

Property name: lcdValueFont Property type: Data Table

UNIT STRING
Text of unit label displayed on the LCD. Property name: lcdUnitString Property type: String

UNIT FONT
Font
590

that will be used to visualize the unit label on the LCD display.

Property name: lcdUnitFont Property type: Data Table

DIGITAL FONT
Enables/disables usage of the digital font in the LCD display. Property name: digitalFont Property type: Boolean

3.15.11.11.1 Radial Gauge Common Properties

POINTER COLOR
Color of the pointer. Property name: pointerColor Property type: String

CUSTOM POINTER COLOR

Color from which the custom pointer color will be calculated. Property name: customPointerColor Property type: Color

POINTER TYPE
Type of the pointer (one of the pre-defined types). Property name: pointerType Property type: String

FOREGROUND TYPE
The type of foreground that will be used for the radial gauge (one of the pre-defined values). Property name: foregroundType

Property type: String

GAUGE TYPE
The type of the gauge: Type 1 - a quarter gauge (90 degrees) Type 2 - a two quarter gauge (180 degrees) Type 3 - a three quarter gauge (270 degrees) Type 4 - a four quarter gauge (300 degrees)

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property name: gaugeType Property type: String

585

POINTER SHADOW VISIBLE

Enables/disables the pointer shadow. Property name: pointerShadowVisible Property type: Boolean

RANGE OF MEASURED VALUES VISIBLE

Enables/disables the visibility of the arc that represents the range of measured values. Property name: rangeOfMeasuredValuesVisible

Property type: Boolean

Knob Properties
This section describes properties of the center knob of a radial gauge.

KNOB TYPE
The type of the knob (one of the pre-defined values). Property name: knowType Property type: String

KNOB STYLE
The the style of the knob (one of the pre-defined values). Property name: knowStyle Property type: String

Frame Properties
FRAME TYPE
Defines the type of frame that will be used for the radial gauge. It could be round our square. Property name: frameType Property type: String

Scale Properties
DIRECTION
The direction of the tickmark label counting (Clockwise or Counter Clockwise). Property name: tickmarkDirection Property type: String

ORIENTATION
The orientation of the tickmark labels (Normal, Horizontal or Tangent). Property name: ticklabelOrientation

Property type: String

Section Properties
EXPANDED SECTIONS ENABLED
Enables/disables the use of wider sections.

2000-2013 Tibbo Technology Inc.

586

AggreGate Documentation
expandedSectionsEnabled

Property name:

Property type: Boolean

3.15.12 Component Properties

Each component has several properties. These may be referred in bindings 604 that "route" data to and from components (e.g. settings of hardware devices). Some properties are common 586 to all widget components. Other properties are component-specific, and are thus described in the articles concerning these components.

Property Types
Description of each widget component property includes property type. Property type is the type of value returned by a component property reference 606 appearing in widget binding (String, Boolean, Integer, etc.).

Indexed Properties
Indexed property is a property that has several elements, i.e. that is represented by array or list. Elements of indexed properties must be referred from bindings 604 by adding zero-based element index into a binding target 605 .

Default Property
Default property is a component's property which is targeted by an automatically created binding 604 . For example, when you drag some server variable and drop in on a Label 323 , the binding created by this operation will change label's text, since Text is the default property of a Label component.

Common Properties Of Components

This section describes properties that are supported by most widget components. The individual description for each component includes a list of supported common properties.

WIDTH
The preferred width of the component, in pixels. If there is not enough space to display a component, this setting may be ignored and the component's actual width will be smaller. If set to zero, the component's width is calculated automatically based on its contents and the display area available to it within the widget layout. Property name: width Property type: Integer

HEIGHT
Preferred height of a component, in pixels. If there is not enough space to display a component, this setting may be ignored and the component's actual height will be smaller. If set to zero, the component's height is calculated automatically based on its contents and the display area available to it within the widget layout. Property name: height Property type: Integer

BINDINGS
This property contains a table of all bindings 604 related to this component (meaning, bindings with an expression target 605 or activator 607 referring to the component's properties). Property name: bindings Property type: Data Table
606 ,

ENABLED
This flag indicates a component is active. Disabled components do not respond to user input, and on most interfaces are rendered as grayed-out:

Property name: enabled

2000-2013 Tibbo Technology Inc.

AggreGate Server
Property type: Boolean

587

VISIBLE
This flag indicates a component is visible. Property name: visible Property type: Boolean

FOREGROUND
This property defines a component's foreground color. The exact elements rendered in the foreground color are component-specific. Property name: foreground Property type: Color

BACKGROUND
This property defines a component's background color. The exact elements rendered in the background color are component-specific. Property name: background Property type: Color

OPAQUE
Indicates that component is opaque. It is a Boolean value - can be "True" (Opaque) or "False" (Transparent). A transparent component's background is not rendered -- the background color 587 property is ignored. Property name: opaque Property type: Boolean

BORDER
See Border
588

article for details on border settings.

Property name: border Property type: Data Table

FONT
Defines which font is used by the component. This property is relevant for components using labels or other text elements (e.g, Text Field 325 ). Properties of font are described here 590 . Property name: font Property type: Data Table

CURSOR
Defines what mouse cursor should be used when mouse hovers over the component. Available cursors: Default Crosshair Text Wait Resize (N, S, E, W, NE, NW, SE, SW) Hand Move Property name: cursor Property type: Integer

TOOLTIP

2000-2013 Tibbo Technology Inc.

588

AggreGate Documentation

Text for the component's tooltip. Tooltips usually appear when the mouse hovers over the component:

Property name: tooltip Property type: String

POPUP MENU
The property configures component's context menu that is shown upon right mouse click on the component. The menu items table contains the following fields: Field Name Description Icon Name name Type String Description Name of menu item used to refer this item from any binding activator Textual description of the item, i.e. the text that will appear in menu. Item icon image.
607 .

description String icon Data Block

Property name: popupMenu Property type: Data Table

3.15.12.1 Custom Properties

In addition to standard component properties, it's possible to define your own custom properties . These properties may be used for keeping widget internal state, e.g intermediate result of some calculation. Custom properties may be added to any widget component, however, they don't affect component's behaviour or visual presentation. Instead, custom properties may be referred by widget bindings 604 .

Managing Custom Properties

Custom properties are managed via context menu of GUI Builder pertinent menu items:
827 's

component properties dialog

835 .

There are three

Add Custom Property. Adds new custom property to the component those properties are being edited. Edit Custom Property. Allows to edit parameters of selected custom property. Remove Custom Property. Removes custom property definition from the component.

Custom Property Parameters

Parameters of custom property may be specified during its creation and edited later on. A custom property is a Data Table 854 by its nature. Property name is used to refer it by widget bindings
604 . 855

Parameters of custom property are comprehensively described in Data Table Format

section.

3.15.12.2 Border
Every component comprises an inner and an outer border. Properties are specified separately for each.

Border Properties
Field Position Type Top Name pos type top Type String String Integer Description Inner or Outer, read-only field. One of None, Empty, Line, Lowered, Raised or Etched. Thickness of border at the top side of component. Applicable to Empty and Line borders.

2000-2013 Tibbo Technology Inc.

AggreGate Server

589

Left Bottom Right Primary Color Secondary Color Title Title Color Title Justification

left bottom right color scolor title tcolor justification

Integer Integer Integer Color Color String Color Integer

Thickness of border at the left side of component. Applicable to Empty and Line borders. Thickness of border at the bottom side of component. Applicable to Empty and Line borders. Thickness of border at the right side of component. Applicable to Empty and Line borders. Color of the border, or color of the main part of the border for two-color borders. Applicable to Line, Lowered, Raised and Etched borders. Color of the border's shadow or other decorations. Applicable to Lowered, Raised and Etched borders. Text for the border's title. Color of border's title. Justification of border title - Left, Center or Right.

Border Examples
An empty border is not visible, but may be used to add a title to the element:

A green border with a centered title in red:

A blue border with a different line thickness for each side:

Lowered border:

Raised border:

Etched border:

2000-2013 Tibbo Technology Inc.

590

AggreGate Documentation

3.15.12.3 Font
This section describes font properties. Different fonts are used by widget components to display text strings.

Font Properties
Field Name Type Boolean String Description Enable this parameter to allow a custom font for the component. Name of the typeface to be used. If you pick a custom font, it might not be available on all clients running this widget. In this case, the default font will be used. Use well-known fonts like Verdana, Times New Roman, etc. Size Bold Italic size bold italic Integer Boolean Boolean Font size, in points. Make font bold. Make font italic.

Use Custom Font custom Name name

3.15.12.4 Paint
Paints are used by widget components to fill different areas, draw lines and other shapes. There are four basic types of paints: Color
590 590 591

Linear Gradient Radial Gradient Texture

592

Color
This paint uses a single solid color for drawing and filling.

Linear Gradient
The linear gradient provides a way to fill a shape with a linear color gradient pattern. The user may specify two or more gradient colors, and this paint will provide an interpolation between each color. The user also specifies start and end points which define where in user-space the color gradient should begin and end. The user must provide an array of floating point numbers specifying how to distribute the colors along the gradient. These values should range from 0.0 to 1.0 and act like keyframes along the gradient (they mark where the gradient should be exactly a particular color). In the event that the user does not set the first keyframe value to 0 and/or the last keyframe value to 1, keyframes will be created at these positions and the first and last colors will be replicated there. So, if a user specifies the following values to construct a gradient: Relative Location 0.3 0.7 Color Blue Red

this will be converted to a gradient with the following keyframes: Relative Location 0.0 0.3 Color Blue Blue

2000-2013 Tibbo Technology Inc.

AggreGate Server

591

0.7 1.0

Red Red

The user may also select what action the gradient paint should take when filling color outside the start and end points. If no cycle method is specified, Disabled will be chosen by default, which means the endpoint colors will be used to fill the remaining area. The image below demonstrates each of the three cycle methods applied for a linear gradient with the following parameters: Start X, Start Y: 0.0 End X, End Y: 50.0 Colors: Relative Location 0.0 0.2 1.0 Color Red White Blue

Radial Gradient
The radial gradient paint provides a way to fill a shape with a circular radial color gradient pattern. The user may specify 2 or more gradient colors, and this paint will provide an interpolation between each color. The user must specify the circle controlling the gradient pattern, which is described by a center point and a radius. The user can also specify a separate focus point within that circle, which controls the location of the first color of the gradient. By default the focus is set to be the center of the circle. This paint will map the first color of the gradient to the focus point, and the last color to the perimeter of the circle, interpolating smoothly for any in-between colors specified by the user. Any line drawn from the focus point to the circumference will thus span all the gradient colors. Specifying a focus point outside of the circle's radius will result in the focus being set to the intersection point of the focus-center line and the perimeter of the circle. The user must provide an array of floats specifying how to distribute the colors along the gradient. These values should range from 0.0 to 1.0 and act like keyframes along the gradient (they mark where the gradient should be exactly a particular color). In the event that the user does not set the first keyframe value to 0 and/or the last keyframe value to 1, keyframes will be created at these positions and the first and last colors will be replicated there. So, if a user specifies the following values to construct a gradient: Relative Location 0.3 0.7 Color Blue Red

this will be converted to a gradient with the following keyframes: Relative Location 0.0 0.3 Color Blue Blue

2000-2013 Tibbo Technology Inc.

592

AggreGate Documentation

0.7 1.0

Red Red

The user may also select what action the radial gradient paint should take when filling color outside the bounds of the circle's radius. If no cycle method is specified, Disabled will be chosen by default, which means the the last keyframe color will be used to fill the remaining area. The image below demonstrates each of the three cycle methods applied for a radial gradient with the following parameters: Start X, Start Y: 50.0 Radius: 25.0 Focus X, Focus Y: 50.0 Colors: Relative Location 0.0 0.2 1.0 Color Red White Blue

Another image demonstrates each of the three cycle methods applied for a radial gradient with the same parameters, but with non-centered focus point (Focus X, Focus Y: 40.0):

Texture
The texture paint provides a way to fill a shape with an image texture. Texture image is resized to the rectangle specified by Start X, Start Y, End X and End Y parameters. This rectangle is replicated infinitely in all directions of the space of filled shape.

Paint Properties
Field Type Color Start X Start Y End X End Y Radius Name type color startx starty endx endy radius Type Integer Color Float Float Float Float Float

2000-2013 Tibbo Technology Inc.

AggreGate Server

593

Focus X Focus Y Colors Cycle Texture

focusx focusy colors cycle texture

Float Float Data Table Integer Data Block

3.15.12.5 Stroke
The stroke defines a basic set of rendering attributes for different parts of widget components. The rendering attributes defined by the stroke describe the shape of the mark made by a pen drawn along the outline of some shape and the decorations applied at the ends and joins of path segments of the shape. These rendering attributes include:

Line Width
The pen width, measured perpendicularly to the pen trajectory.

End Cap
The decoration applied to the ends of unclosed subpaths and dash segments. The three different decorations are: None, Round , and Square.

Line Join
The decoration applied at the intersection of two path segments. The three different decorations are: Bevel, Miter, and Round .

Miter Limit
The limit to trim a line join that has a Miter decoration. A line join is trimmed when the ratio of miter length to stroke width is greater than the Miter Limit value. The miter length is the diagonal length of the miter, which is the distance between the inside corner and the outside corner of the intersection. The smaller the angle formed by two line segments, the longer the miter length and the sharper the angle of intersection. The default Miter Limit value of 10.0 causes all angles less than 11 degrees to be trimmed. Trimming miters converts the decoration of the line join to bevel.

Dash Array
Dash Array and Dash Phase attributes define how to make a dash pattern by alternating between opaque and transparent sections. Dash Array is a number of values representing the lengths of the dash segments. Alternate entries in the array represent the user space lengths of the opaque and transparent segments of the dashes. As the pen moves along the outline of the shape to be stroked, the user-space distance that the pen travels is accumulated. The distance value is used to index into the dash array. The pen is opaque when its current cumulative distance maps to an even element of the dash array and transparent otherwise.

2000-2013 Tibbo Technology Inc.

594

AggreGate Documentation

Dash Phase
The dash phase is a distance that represents an offset into the dashing pattern. In other words, the dash phase defines the point in the dashing pattern that will correspond to the beginning of the stroke. The image below illustrates how strokes with different dash arrays and phase look like:

Stroke Properties
Field Line Width End Cap Line Join Miter Limit Dash Array Dash Phase Name lineWidth endCap lineJoin miterLimit dashArray dashPhase Type Float Integer Integer Float Data Table Float

3.15.12.6 Shape
The shape represent a geometric primitive, such as rectangle of star. The following types of shapes are supported: Rectangle Rounded Rectangle Ellipse/Circle Arc Line Polygon Star

Shape Properties
Field Type X Coordinat e Y Coordinat e Width Name type x Type Description

Intege Shape type. r Float The leftmost point of a Rectangle, Rounded Rectangle , Ellipse/Circle , Arc, Line or Star . The topmost point of a Rectangle, Rounded Rectangle , Ellipse/Circle , Arc, Line or Star . The width point of a Rectangle, Rounded Rectangle , Ellipse/Circle , or Arc;

Float

width

Float

2000-2013 Tibbo Technology Inc.

AggreGate Server

595

End X - Start X distance for a Line. Height height Float The height point of a Rectangle, Rounded Rectangle , Ellipse/Circle , or Arc; End Y - Start Y distance for a Line. Arc Width arcWidth Float Float Float Float Width of Rounded Rectangle 's corner arc. Height of Rounded Rectangle 's corner arc. Start of an Arc shape (in degrees). Extent of an Arc shape (in degrees).

Arc Height arcHeight Start Extent Arc Type start extent arcType

Intege Arc type: r Open: arc with no path segments connecting the two ends of the arc segment Chord: arc closed by drawing a straight line segment from the start of the arc segment to the end of the arc segment Pie: arc closed by drawing straight line segments from the start of the arc segment to the center of the full ellipse and from that point to the end of the arc segment

Points Inner Radius Outer Radius Branch Count

points innerRadi us outerRadi us branches Count

Data Table Float Float

Polygon points, i.e. an array of (X, Y) points. By default, polygons point array specifies a cross shape. Inner radius of a Star . Outer radius of a Star .

Intege Number of branches of a Star . r

3.15.13 Component Events

Widget components may generate events when the user interacts with them. For example, a button has an action event which fires when the user clicks it. An event may be specified as the binding activator 607 for a binding. An "activator" causes the binding to do just that -act, and thus write data from a widget to a context on the server, read data from a context and use it as a widget's content, or perform some other data processing. Let's say we have a Name text field which is bound to a field in some server context's variable (i.e, the First Name of a user). Its binding also specifies an activator event -- the action event of the Save button, which is right next to it. When the user clicks this button, the following sequence of events occurs: 1) All bindings of the widget are scanned, looking for their specified Activator events. 2) The system sees that the binding for the Name text field has this action event defined as its "activator". 3) The binding is then executed, along with any other bindings which have this event as their activator (such as Last Name , if there is one). In simple words, the data in the text fields is now written into the database.

Common Events Of Components

This section describes events that are supported by most widget components. The individual description for each component includes a list of supported common events.

HIDDEN
This event is fired when a component is hidden. Event name: hidden Event fields: Field ID Name id Type Integer Description Event type ID.

SHOWN

2000-2013 Tibbo Technology Inc.

596

AggreGate Documentation

This event is fired when a component is shown. Event name: shown Event fields: Field ID Name id Type Integer Description Event type ID.

MOVED
This event is fired when a component is moved within its parent container. Event name: moved Event fields: Field ID Name id Type Integer Description Event type ID.

RESIZED
This event is fired when a component is resized. Event name: resized Event fields: Field ID Name id Type Integer Description Event type ID.

MOUSE CLICKED
This event is fired when a mouse button is clicked over the component. Event name: mouseClicked Parameters: see mouse event
598 .

MOUSE PRESSED
This event is fired when a mouse button is pressed over the component. Event name: mousePressed Parameters: see mouse event
598 .

MOUSE RELEASED
This event is fired when a mouse button is released over the component. Event name: mouseReleased Parameters: see mouse event
598 .

MOUSE ENTERED
This event is fired when a mouse cursor enters the component area. Event name: mouseEntered Parameters: see mouse event
598 .

MOUSE EXITED
This event is fired when a mouse cursor leaves the component area. Event name: mouseExited Parameters: see mouse event
598 .

MOUSE MOVED

2000-2013 Tibbo Technology Inc.

AggreGate Server
This event is fired every time when a mouse cursor moves over the component area. Event name: mouseMoved Parameters: see mouse event
598 .

597

MOUSE WHEEL MOVED

This event is fired when a mouse wheel is activated over the component. Event name: mouseWheelMoved Event fields: The mouse wheel moved event has all fields of a regular mouse event following fields: Field Scroll Amount Scroll Type Name Type Description The number of units that should be scrolled per click of mouse wheel rotation. Only valid if Scroll Type is "unit scroll". Scroll type: 0 - representing scrolling by "units" (like scrolling with the arrow keys) 1 - Constant representing scrolling by a "block" (like scrolling with pageup, page-down keys) Wheel Rotation wheelRotatio Integer n The number of "clicks" the mouse wheel was rotated. Negative values if the mouse wheel was rotated up/away from the user, and positive values if the mouse wheel was rotated down/towards the user.
598 .

Additionally, it defines the

scrollAmount Integer scrollType Integer

KEY TYPED
This event is fired when a keyboard key is typed while the component is in focus. Event name: keyTyped Parameters: see keyboard event
599 .

KEY PRESSED
This event is fired when a keyboard key is pressed while the component is in focus. Event name: keyPressed Parameters: see keyboard event
599 .

KEY RELEASED
This event is fired when a keyboard key is released while the component is in focus. Event name: keyReleased Parameters: see keyboard event
599 .

FOCUS GAINED
This event is fired when the component gets input focus. Event name: focusGained Event fields: Field ID Temporary Name id temporary Type Integer Boolean Description Event type ID. Identifies the focus change event as temporary or permanent.

FOCUS LOST
This event is fired when the component loses input focus. Event name: focusLost Event fields:

2000-2013 Tibbo Technology Inc.

598

AggreGate Documentation

Field ID Temporary

Name id temporary

Type Integer Boolean

Description Event type ID. Identifies the focus change event as temporary or permanent.

3.15.13.1 Mouse Event

This table described all fields of mouse-related component events. Field ID When Modifiers Name id when modifiers Type Integer Date Integer Description Event type ID. Event timestamp. The modifier mask for this event. Modifiers represent the state of all modal keys, such as ALT, CTRL, META, just after the event occurred. This value is a bitwise OR of the following constants: 1 - Shift key 2 - Control key 4 - Meta key 8 - Alt key 32 - Alt Graph key Alt Down Alt Graph Down Control Down Shift Down Meta Down X Y X on Screen altDown altGraphDow n controlDown shiftDown metaDown x y xOnScreen Boolean Boolean Boolean Boolean Boolean Integer Integer Integer True if Alt key was down when an event occurred. True if Alt Graph key was down when an event occurred. True if Control key was down when an event occurred. True if Shift key was down when an event occurred. True if Meta key was down when an event occurred. The horizontal x position of the event relative to the source component. The horizontal y position of the event relative to the source component. The absolute horizontal x position of the event. In a virtual device multiscreen environment in which the desktop area could span multiple physical screen devices, this coordinate is relative to the virtual coordinate system. The absolute horizontal y position of the event. See note above. Defines which of the mouse buttons has changed state: 0 - no buttons 1 - button #1 2 - button #2 3 - button #3 Click Count Extended Modifiers clickCount modifiersEx Integer Integer The number of mouse clicks associated with this event. The extended modifier mask for this event. Extended modifiers represent the state of all modal keys, such as ALT, CTRL, META, and the mouse buttons just after the event occurred. This value is a bitwise OR of the following constants: 64 - Shift key 128 - Ctrl key 256 - Meta key 512 - Alt key 1024 - Mouse button 1 2048 - Mouse button 2

Y on Screen Button

yOnScreen button

Integer Integer

2000-2013 Tibbo Technology Inc.

AggreGate Server

599

4096 - Mouse button 3 Popup Trigger popupTrigger Integer Defines whether or not this mouse event is the popup menu trigger event for the platform.

3.15.13.2 Keyboard Event

This table described all fields of keyboard-related component events. Field ID When Modifiers Name id when modifiers Type Integer Date Integer Description Event type ID. Event timestamp. The modifier mask for this event. Modifiers represent the state of all modal keys, such as ALT, CTRL, META, just after the event occurred. This value is a bitwise OR of the following constants: 1 - Shift key 2 - Control key 4 - Meta key 8 - Alt key 32 - Alt Graph key Alt Down Alt Graph Down Control Down Shift Down Meta Down Action Key Key Character altDown Boolean True if Alt key was down when an event occurred. True if Alt Graph key was down when an event occurred. True if Control key was down when an event occurred. True if Shift key was down when an event occurred. True if Meta key was down when an event occurred. Defines whether the key in this event is an "action" key. Typically an action key does not fire a Unicode character and is not a modifier key. Returns the character associated with the key in this event. For example, the Key Typed event for shift + "a" returns the value for "A". Key Pressed and Key Released events are not intended for reporting of character input. Therefore, the values returned by this method are guaranteed to be meaningful only for Key Types events. Key Code Key Location keyCode keyLocation Integer Integer The integer key code associated with the key in this event. Returns the location of the key that originated this key event. Some keys occur more than once on a keyboard, e.g. the left and right shift keys. Additionally, some keys occur on the numeric keypad. This provides a way of distinguishing such keys. Available locations: 0 - unknown 1 - standard 2 - left 3 - right 4 - numpad

altGraphDow Boolean n controlDown shiftDown metaDown actionKey keyChar Boolean Boolean Boolean Boolean String

Key Codes
Key VK_0 Key Code 48

2000-2013 Tibbo Technology Inc.

600

AggreGate Documentation

VK_1 VK_2 VK_3 VK_4 VK_5 VK_6 VK_7 VK_8 VK_9 VK_A VK_ACCEPT VK_ADD VK_AGAIN VK_ALL_CANDIDATES VK_ALPHANUMERIC VK_ALT VK_ALT_GRAPH VK_AMPERSAND VK_ASTERISK VK_AT VK_B VK_BACK_QUOTE VK_BACK_SLASH VK_BACK_SPACE VK_BEGIN VK_BRACELEFT VK_BRACERIGHT VK_C VK_CANCEL VK_CAPS_LOCK VK_CIRCUMFLEX VK_CLEAR VK_CLOSE_BRACKET VK_CODE_INPUT VK_COLON VK_COMMA VK_COMPOSE VK_CONTEXT_MENU VK_CONTROL VK_CONVERT VK_COPY VK_CUT

49 50 51 52 53 54 55 56 57 65 30 107 65481 256 240 18 65406 150 151 512 66 192 92 8 65368 161 162 67 3 20 514 12 93 258 513 44 65312 525 17 28 65485 65489

2000-2013 Tibbo Technology Inc.

AggreGate Server

601

VK_D VK_DEAD_ABOVEDOT VK_DEAD_ABOVERING VK_DEAD_ACUTE VK_DEAD_BREVE VK_DEAD_CARON VK_DEAD_CEDILLA VK_DEAD_CIRCUMFLEX VK_DEAD_DIAERESIS VK_DEAD_DOUBLEACUTE VK_DEAD_GRAVE VK_DEAD_IOTA VK_DEAD_MACRON VK_DEAD_OGONEK VK_DEAD_SEMIVOICED_SOUND VK_DEAD_TILDE VK_DEAD_VOICED_SOUND VK_DECIMAL VK_DELETE VK_DIVIDE VK_DOLLAR VK_DOWN VK_E VK_END VK_ENTER VK_EQUALS VK_ESCAPE VK_EURO_SIGN VK_EXCLAMATION_MARK VK_F VK_F1 VK_F10 VK_F11 VK_F12 VK_F13 VK_F14 VK_F15 VK_F16 VK_F17 VK_F18 VK_F19 VK_F2

68 134 136 129 133 138 139 130 135 137 128 141 132 140 143 131 142 110 127 111 515 40 69 35 10 61 27 516 517 70 112 121 122 123 61440 61441 61442 61443 61444 61445 61446 113

2000-2013 Tibbo Technology Inc.

602

AggreGate Documentation

VK_F20 VK_F21 VK_F22 VK_F23 VK_F24 VK_F3 VK_F4 VK_F5 VK_F6 VK_F7 VK_F8 VK_F9 VK_FINAL VK_FIND VK_FULL_WIDTH VK_G VK_GREATER VK_H VK_HALF_WIDTH VK_HELP VK_HIRAGANA VK_HOME VK_I VK_INPUT_METHOD_ON_OFF VK_INSERT

61447 61448 61449 61450 61451 114 115 116 117 118 119 120 24 65488 243 71 160 72 244 156 242 36 73 263 155

VK_INVERTED_EXCLAMATION_M 518 ARK VK_J VK_JAPANESE_HIRAGANA VK_JAPANESE_KATAKANA VK_JAPANESE_ROMAN VK_K VK_KANA VK_KANA_LOCK VK_KANJI VK_KATAKANA VK_KP_DOWN VK_KP_LEFT VK_KP_RIGHT VK_KP_UP VK_L VK_LEFT 74 260 259 261 75 21 262 25 241 225 226 227 224 76 37

2000-2013 Tibbo Technology Inc.

AggreGate Server

603

VK_LEFT_PARENTHESIS VK_LESS VK_M VK_META VK_MINUS VK_MODECHANGE VK_MULTIPLY VK_N VK_NONCONVERT VK_NUM_LOCK VK_NUMBER_SIGN VK_NUMPAD0 VK_NUMPAD1 VK_NUMPAD2 VK_NUMPAD3 VK_NUMPAD4 VK_NUMPAD5 VK_NUMPAD6 VK_NUMPAD7 VK_NUMPAD8 VK_NUMPAD9 VK_O VK_OPEN_BRACKET VK_P VK_PAGE_DOWN VK_PAGE_UP VK_PASTE VK_PAUSE VK_PERIOD VK_PLUS VK_PREVIOUS_CANDIDATE VK_PRINTSCREEN VK_PROPS VK_Q VK_QUOTE VK_QUOTEDBL VK_R VK_RIGHT VK_RIGHT_PARENTHESIS VK_ROMAN_CHARACTERS VK_S VK_SCROLL_LOCK

519 153 77 157 45 31 106 78 29 144 520 96 97 98 99 100 101 102 103 104 105 79 91 80 34 33 65487 19 46 521 257 154 65482 81 222 152 82 39 522 245 83 145

2000-2013 Tibbo Technology Inc.

604

AggreGate Documentation

VK_SEMICOLON VK_SEPARATER VK_SEPARATOR VK_SHIFT VK_SLASH VK_SPACE VK_STOP VK_SUBTRACT VK_T VK_TAB VK_U VK_UNDEFINED VK_UNDERSCORE VK_UNDO VK_UP VK_V VK_W VK_WINDOWS VK_X VK_Y VK_Z

59 108 108 16 47 32 65480 109 84 9 85 0 523 65483 38 86 87 524 88 89 90

3.15.14 Bindings
If widget components 322 form the "body" of the widget, then its "engine" is constructed of bindings. Bindings define relations between widget components and data from server contexts, such as their variables 869 and functions 878 . Every binding is evaluated at different points during widget execution. Evaluation results are used to modify widget components or context data. Widget bindings extend server bindings 952 . While server binding define relations of server-side objects, widget bindings can also define relations between server objects and visual components. However, widget bindings use the same syntax. Widget bindings may be viewed, created or edited: By editing the Bindings 586 property of any widget component in GUI Builder component includes only bindings involving this component. By editing the All Bindings widget.
376 827 .

The bindings table for a particular

property of the root panel

376 .

This bindings table include all bindings available for the

GUI Builder greatly simplifies creation of bindings. Most bindings may be created using intuitive Drag and Drop operations. Details of this procedure are described here 842 .

3.15.14.1 Binding Properties

Every binding defined in the widget template Target
314

has the following parameters:

Binding target is a special type of reference 925 that points to where the evaluation result of binding expression will be written when the binding is processed. Check the binding target 605 section for details.

2000-2013 Tibbo Technology Inc.

AggreGate Server

605

Expression Activator

This is an AggreGate Expression 911 that is evaluated every time a binding is processed. The evaluation result is stored in the binding target. See Binding Expression 606 for details. This is a reference that points to some event or property of the widget that will trigger the processing of the binding. The Activator parameter is available only when On event parameter is enabled. See Binding Activator 607 for details. Condition is an AggreGate Expression 911 that is evaluated first after binding activation. If this expression results to false, the binding execution is skipped. When this parameter is enabled, the binding is processed every time the widget is launched. When this parameter is enabled and an Activator is specified, the binding is processed whenever there's a changes in the property the activator refers to. If the Activator refers to an event, the binding will be processed when the event fires. If On event is enabled and an Activator is not specified, the binding will be automatically processed: The binding's Expression includes references, pointing to one or more variables. A change in any of these variables will cause the binding to run. For example, let's take the following binding, and say that no Activator was specified for it: Target: users.admin.deviceservers.ds1.devices.thermostat:

Condition On Startup On Event

temperature$temperature Expression: {form/temperatureField:text} + {form/ temparatureAdjustmentField:text}

This binding has an expression which takes the value from a form field called temperatureField, and adds it to the value of the temperatueAdjustmentField form field. The end result is then written to the Target. Now, since this binding doesn't have an Activator but On event is enabled for it, the binding is processed whenever the user changes one of the form fields specified in the Expression. Periodically Period If this parameter is enabled, the binding will be processed periodically. Interval between binding processing sessions. This parameter may be changed only if Periodically is turned on.

3.15.14.2 Binding Target

The binding target is an object affected by the binding. It can either be a widget component or some data within a AggreGate Server context. To affect a widget component, the binding target has to point to one of its properties. To modify context data, the binding target has to point to a context variable, field of a variable or the input field of a context function (see server binding target 952 ). In fact, the binding target is a special type of reference 925 . Two types of binding targets are supported: one with no schema 926 (and thus, no prefix), which points to context data, and another, which uses the form schema and prefix ( form/) and points to the widget component properties. Widget binding targets support all syntax variants of server binding targets The following additional syntax variants are supported:
952 .

1. Component Property
form/component:property
This binding target points to a specific property of a widget component. Binding target that refers cell of the tabular property within the specific row and field has the following format:

form/component:property$field[row]
Example: form/textField1 A binding with this target will write its result to the default property of the textField1 component. If textField1 is a text field 325 , its text property will be changed. Example: form/image1:imageTable$imageData[0] This binding target changes a binary image in the first row of Image component's Image Table
351 .

2000-2013 Tibbo Technology Inc.

606

AggreGate Documentation

Example: form/gauge:datasets[1] This binding target changes the value of a second dataset (with index=1) of a gauge
558

component.

2. Widget Script
form/script()
This type of binding target is used to launch the widget script 610 named script upon processing the binding, passing the binding evaluation result to the script as its parameter. Bindings with such targets are created automatically upon adding new scripts to the widget template. However, initial properties 952 of such binding does define any script launch conditions. It's necessary to modify these properties to make the script start on widget startup, some event or just periodically. Example: form/refreshChart() This binding launches the refreshChart widget script displaying the most recent data.
610

that may refresh a chart

384

component to make it

3.15.14.3 Binding Expression

Widget binding expressions are very similar to server binding expressions may include two types of references: Standard references that point to context
322 953 .

However, binding expressions in widgets their fields or properties, and

variables

869

or functions

878 ,

Component

references that point to properties of widget components

322 .

Component References
A component reference points to a property of a widget component (e.g. the text of a Label format:
323 ).

It has the following

form/component:property form is the name of the schema

926 used to identify component references. It tells the expression language processor to use a resolver 926 that understands component references and knows what to do with them. You always have to start component references with form/.

component is the name of the widget component

Resource Window Builder.
833

322 you want to work with. The component name is shown in and in the title of the Component Properties Window 835 when the component is selected in GUI

property is the name of a specific property within the component. Property names can be found in the description of
properties of every widget component. Property part of a component reference is optional. If it is omitted, the reference points to the default property 586 of the component. Type of property 586 , i.e. type of value returned by a component property reference, may be found in the description of this property in the components reference 322 .

COMPONENT PROPERTY REFERENCE EXAMPLES

{form/userNameField:} {form/userNameField:text}
Both of these two references resolve to the text currently contained in userNameField (assuming that's a text field 325 ). The first variant points to the default property 586 of component, which is text, and the second one names it explicitly (:text).

Widget Binding Expression Example

{form/slider1:value} * 100
This expression will resolve to a number that equals to the value property (which is a default property and thus is not explicitly specified) of the Slider 347 component called slider1, multiplied by 100.

2000-2013 Tibbo Technology Inc.

AggreGate Server

607

3.15.14.4 Binding Activator

A binding activator is a special reference A property
586 925

that points to:

or event

595

of a widget component
954 )

A property (variable) or event of a server context (see server binding activator An item of widget component's context menu

A change of the widget/server variable, an occurrence of the widget/server event, or a selection of context menu item force this binding's processing. Widget binding activators support all syntax variants of server binding activators The following additional syntax variants are supported:
954 .

1. Property of a widget component

form/component:property
If the property of component is changed, the activator will run. Example: form/setpoint:text This activator will run when text in the test field
325

named setpoint is edited.

2. Event of a widget component

form/component:event@
If component has an event called event, the activator will run when this event fires. Example: form/button1:click@ This activator will run when the button1 button
334

is pressed.

3. Popup Menu Item

menu/component:item
This activation will trigger a binding once a menu item named item is selected from component's context menu
588 .

3.15.14.5 Binding Condition

Widget binding conditions are very similar to server binding conditions include two types of references: Standard references that point to context
322 954 .

However, binding conditions in widgets may

878 ,

variables

869

or functions

their fields or properties, and

Component

references that point to properties of widget components

606

322 .

See widget binding expressions

for more information about widget component references.

Widget Binding Condition Example

{value/altDown} && ({value/keyCode} == 'A') - this expression will trigger a binding those activator is key
typed event
595

only if Alt-A key combination was pressed.

3.15.14.6 Binding Performance

Bindings are normally processed one by one. For example, if you have a widget displaying 20 different metrics of a device and each reading metric from a remote server takes 1 second, widget loading will take 20 seconds. To increase widget loading speed enable Startup Bindings Concurrency flag of a root panel 376 . In this case each binding will be processed in separate thread. In the above example, this will cause all metric requests to be executed simultaneously, so the widget will load in 1 second (20 times faster).

2000-2013 Tibbo Technology Inc.

608

AggreGate Documentation

Root panel has another performance-related setting: Maximum Concurrent Bindings. It defines how many threads can be created for widget binding processing and, thus, how many bindings can be processed simultaneously.

3.15.14.7 Binding Examples

Example 1. Opening a New Widget upon Button Click
This example shows how to execute a server-side action 892 upon a Button click. The most typical of using this binging type is opening a new widget when a button is clicked any other widget. First of all, put a Button binding as follows:
334

component on your widget. Second, add a binding

607 ,

604

to the button, and configure this

Set button's Click event as binding Activator

i.e. set Activator to form/button1:click@

Specify it's Launch Widget 774 action as binding Target 605 , i.e. set Target to action/users.admin.widgets. bindingsDemo:launch, where users.admin.widgets.bindingsDemo is context path of widget to launch. Leave binding Expression empty.
Binding configuration: Target Expres sion Activat form/button1:click@ or Conditi on Option s

action/users.admin.widgets.bindingsDemo:launch

On Event

It's also possible to close current widget (one with the Button) before the action execution. To configure this: Open Operations property of the Button Add a record with Close operation

Example 2: Binding Panel Color to Status of a Controller

This binding will make a status panel be green.
378

red if a voltage alert is reported by the controller. In other cases the panel will

Note that the expression and the target reference use relative context paths (".") to make the widget compatible with multiple similar controllers. The widget should be relative 314 and valid for all "voltage controller" devices. Target Expres sion Activat or Conditi on Option s

form/voltageAlertPanel:background {.:voltageAlert$voltageAlert} ? color(255, 0, 0) : color(0, 255, 0)

On Startup, On Event

It's possible to modify the above binding to make the panel red if temperature reading is over 50 degrees:

({.:voltage$voltage} > 50) ? color(255, 0, 0) : color(0, 255, 0)

Example 3: Binding Slider Component to Setpoint of a Controller

This pair of bindings will change setpoint of a controller (e.g. temperature controller) once a slider
347

is moved.

2000-2013 Tibbo Technology Inc.

AggreGate Server
First binding is used to read current setpoint value from the controller and initialize the slider: Target Expres sion Activat or Conditi on Option s

609

form/slider1:value {.:currentTemperature$temperatureCelsius}

On Startup

Second binding writes new setpoint to the controller once the slider is moved: Target Expres sion Activat or Conditi on Option s

.:currentTemperature$temperatureCelsius {form/slider1:value}

On Event

Example 3: Binding Table Editor to Query Results

This binding executes a server query 271 those text is contained in the text field queryText and puts query results into the Data Table Editor 344 component named results. The query is executed by calling executeQuery of the root server context execute button 334 click.
726 .

The operation is performed upon

Note that first parameter of executeQuery function is single-quoted to make the system processing it as expression. Target Expres sion

form/result:dataTable {:executeQuery('{form/queryText:text}')}

Activat form/execute:click@ or Conditi on Option s

On Event

It's possible to use alternative syntax for the above binding's expression:

callFunction("", "executeQuery", {form/query:text})

This expression works exactly as the above one. However, it employes callFunction() expression language function to call the server context function by explicitely specifying context path, function name and its parameters.

Example 4: Calling Device Function

This example explains how to perform device or server function 878 call from a widget. Assuming we have a device supporting multiply operation with two numeric arguments. We'd like to call this operation upon calculate button click by supplying numbers entered in two text fields (argument1 and argument2).

METHOD ONE: CALLING FUNCTION FROM A WIDGET BINDING TARGET

In this case our binding's target will point to the function and its expression will return a pre-build parameters data table:

2000-2013 Tibbo Technology Inc.

610

AggreGate Documentation

Target Expres sion

.:multiply() table(functionInputFormat(), {form/argument1:text}, {form/argument1:text})

Activat form/calculate:click@ or Conditi on Option s

On Event

Note that we're using relative context path (" .") in the target to make calculation widget compatible with many calculation agents. To use it with just one agent, specify absolute path, e.g. users.my_user.devices.my_agent. In this example calculation result returned by multiply operation will be discarded. But what is we want to put it into another widget component (such as a label 323 )? Here is the solution:

METHOD TWO: CALLING FUNCTION FROM A WIDGET BINDING EXPRESSION

In this case our binding expression will call the function and return its output (a Data Table 854 ). The actual calculation result (numeric result field) is extracted from this table using cell() function. This result is written into result label: Target Expres sion

form/result:text cell(callFunction(dc(), "multiply", {form/argument1:text}, {form/argument1: text}), "result")

Activat form/calculate:click@ or Conditi on Option s

On Event

Note that relative device context path (returned by dc() function) is used. To use absolute context path change dc() to full device path, e.g. users.my_user.devices.my_agent. There is another (more compact) style of writing the above binding expression to obtain exactly the same result. This style uses a function reference
927

instead of callFunction() expression language function:

{.:multiply('{form/argument1:text}',

'{form/argument2:text}')$result}

3.15.15 Widget Scripts

Widget scripts allow performing custom operations with widget components and server data. Scripts are written in Java. Every script is executed in the Java Virtual Machine (JVM) that executes the widget (this may be the JVM running AggreGate Client, or the AggreGate Server JVM if the widget is executed in the web interface). Thus, the scrip has access to all in-memory objects and structures of the widget. Scripts are very powerful, and provide the ability to fully control the widget. Script permissions are not restricted in any way. A single unintentional error in a script, or some malicious code, may cause the AggreGate server or client to function improperly, hang, get 100% CPU time, corrupt its data or even corrupt data on the machine running it!

Triggering Script Execution

Widget script is executed in two cases: When a binding
604

whose target points to this script

606

606

is processed;
914 .

When a binding expression

calls script() function

Scripts are executed in bindings processing thread, so script those execution takes a long time may hand processing of other widget bindings. It's recommended to create new threads for executing time-consuming tasks from widget scripts.

2000-2013 Tibbo Technology Inc.

AggreGate Server

611

Managing Scripts
Scripts are created and managed by editing the Scripts
377

property of widget root panel.

Script Interface
Every script is a single Java class that must implement a WidgetScript interface: public interface WidgetScript { public void execute(WidgetScriptExecutionEnvironment }

environment,

Object...

parameters);

This interface declares a single execute() method that is called when the script is executed. Result of binding expression's evaluation is passed to the widget script as parameter object.

Script Execution Environment

Every script has access to an object implementing WidgetScriptExecutionEnvironment interface that is passed as an argument to execute() method. Here is what WidgetScriptExecutionEnvironment look like: public interface WidgetScript { public void execute(WidgetScriptExecutionEnvironment }

environment,

Object

parameter);

Instance of WidgetScriptExecutionEnvironment provides access to an object implementing GUIEngine interface (it is obtained by calling getEngine() method). GUIEngine provides access to objects responsible for widget execution.

getCause() method returns reference

925 (object of type Reference) that caused processing of binding that gave rise to script execution. This reference may point to some server data or property of widget component.

Script Template
When a new script is created, its text is not empty. It contains an auto-generated stub of a class implementing WidgetScript interface with an empty execute() method. Here is the default script text: import com.tibbo.platform.guibuilder.*; public class users_admin_widgets_scripts_refresh implements WidgetScript { public void execute(WidgetScriptExecutionEnvironment environment, Object { } }

parameter)

Developing Scripts
See Programming Guidelines
980

section for common practices of developing AggreGate widget scripts.

WRITING SCRIPTS
Basically, scripts should do several things: Read/write properties of widget components Generate widget component events Read/write server context variables (i.e. hardware device settings and server resource properties) Call server and device operations (functions) In most cases, all activities should be performed via Context interface. To obtain a Context matching any server-side object, use the following code:

2000-2013 Tibbo Technology Inc.

612

AggreGate Documentation

WidgetEngine engine = environment.getEngine(); ContextManager contextManager = engine.getServerContextManager(); Context serverContext = contextManager.get("server.context.path"); To obtain a Context matching a certain widget component, write the following code: Context componentContext = environment.getComponentContext("widget_component_name");

Once an instance of Context is retrieved, you can read/write variables using getVariable() and setVariable() methods. For widget component contexts, most variables directly match component properties (e.g. Font, Width, Color, etc.)

Example 1: Processing Property of a Component

For example, to apply custom processing to a Data Table stored in the Data Table Editor following code:
344

component, use the

Context dataTableEditorContext = environment.getComponentContext("dataTableEditor1"); DataTable dataTable = dataTableEditorContext.getVariable("dataTable"); // Process the data here

Example 2: Closing Another Widget

This example illustrates how a widget can close another widget, e.g. upon a button click. The script calls ClientUtils.removeFrame() static method and passed the key (name) of frame to close. The widget's frame key is constructed by ClientUtils.createWidgetFrameKey() method that accepts path of widget context and path of its default context 315 (or root context path, i.e. empty string, in the case of absolute 314 widget). import import import com.tibbo.aggregate.common.script.*; com.tibbo.aggregate.common.widget.*; com.tibbo.aggregate.client.util.*;

public class %ScriptClassNamePattern% implements WidgetScript { public Object execute(WidgetScriptExecutionEnvironment environment, Object... parameters) { ClientUtils.removeFrame(ClientUtils.createWidgetFrameKey("users.admin.widgets.test", "")); return null; } }

Example 3: Opening an URL in Browser

This example illustrates how to open a certain website in browser. The below script can be launched upon button click, it accepts an URL as an only parameter. import import import java.awt.*; java.net.*; com.tibbo.aggregate.common.widget.*;

public class %ScriptClassNamePattern% implements WidgetScript { public Object execute(WidgetScriptExecutionEnvironment environment, Object... parameters) { try { Desktop.getDesktop().browse(new URI(parameters[0].toString())); } catch (Exception ex) { throw new IllegalStateException("Error opening url '" + parameters[0].toString() + "'", ex); } return null;

2000-2013 Tibbo Technology Inc.

AggreGate Server

613

} }

3.15.16 Widget Event Log

When a widget is loading and running, it produces several types of events. These events may be viewed in Event Log 791 : In GUI Builder
827

, the Event Log is opened automatically when the widget is started icon in the widget window toolbar

During normal operation, the log may be opened by clicking on

Widget Events
The following event types are shown in the widget event log:

LOAD ERROR
This event occurs if component's property or the whole component cannot be properly decoded from XML-based widget template.

Event Name Records: Record Format

Field Name component property
855

loadError

1 :
Field Type String String Notes Name of component that cannot be loaded. Property name, or NULL if the whole component cannot be decoded from template. Error message.

error

String

BINDING ERROR
This error event is fired when a binding be properly written into binding target.
604

error occurs, i.e. binding expression cannot be evaluated or its result cannot

Event Name Records: Record Format

Field Name target expression activator execution error stack
855

bindingError

1 :
Field Type String String String String String Data Table Notes Binding target
605 .

Binding expression Binding activator

606 .

607 .

Binding execution mode: on startup, on event, or periodical. Error text. Stack trace of error source.

2000-2013 Tibbo Technology Inc.

614

AggreGate Documentation

3.15.17 Widgets Security

Once a widget is launched, all operations performed by it inherit permissions of the user that has started it. For example, if user Joe starts a widget owned by the default administrator 109 , the widget will have Joe's limited permissions. However, if the administrator starts any of Joe's widgets, the widget will have unrestricted permissions, introducing potential security risk if Joe is not a trusted user. Unlike many old generation automation and control systems, AggreGate doesn't provide any UI-level access control settings to avoid non-secure client-side access checks. However, it's possible to make behaviour of the widget UI dependent to the permissions of the current user. Use expression language functions 914 to check whether certain contexts 863 and their variables/functions/events are available for the current user and modify UI behaviour accordingly (e.g. hide/disable buttons, etc.): Use available() function to check whether a certain server context exists and is available for the current user Use hasVariable(), hasFunction() and hasEvent() to determine whether a corresponding variable/function/ event exists in the specified context and is available

3.15.18 Widgets Performance

Widgets are active resources that may have significant performance impact. An "engine" of a widget is its bindings
604 .

A widget running inside AggreGate Client may cause considerable CPU load and memory usage on AggreGate Client itself, AggreGate Server, or both. Widget's CPU load impact is a multiplication of the following: Number of widget instances launched by system operators. Number of widget's bindings. Frequency of widget binding processing. It may either be explicitly specified in the binding options (for Periodic bindings) or implicitly defined by the frequency of events or state changes that trigger binding execution (for On Event bindings). Complexity and impact of binding expressions. See expressions performance
924

for more information.

Impact of writing binding targets. Writing a binding target is in most cases writing a context variable or calling a context function. See variables performance 878 and functions performance 880 for more information. Impact of custom widgets scripts
610

Java code.

Templates 314 of the widgets are cached in the server memory to ensure quick widget startup. A large number of complex widget can cause noticeable constant server memory usage. Running widgets that have hundreds of complex dynamic components (such as tables 344 , event logs graphs 369 or dynamic vector images 352 ) may cause considerable constant client-side memory load.
345 ,

maps

616 ,

Running widgets may also cause additional short memory usage bursts in case if large datasets (e.g. lots of historical events 882 ) are loaded by widget bindings or charts 384 .

3.15.19 Widget Examples

AggreGate Platform and derived vertical market products contain thousands of out-of-box widgets that can be easily reverse-engineered in the GUI Builder, offering a huge database of widget examples.

3.15.20 Widget Player

Widget Player is an utility used for running a widget
312

as a standalone application. It is useful for:

launching widget inside a touch panel connected to an industrial or home automation controller; starting some important monitoring widget without running AggreGate Client itself.

Parameters Dialog
If widget player is started without command line parameters, it shows a dialog allowing to specify connection/ authorization settings, path of widget to start, and path of it default context 315 :

2000-2013 Tibbo Technology Inc.

AggreGate Server

615

Command Line Options

Widget Player is launched by running widget_player executable file (its extension is OS-dependent) with the following parameters:

widget_player [server_address server_port username password] widget_context_path [other_options]

server_address is IP or host name of the AggreGate Server (e.g. localhost); server_port is AggreGate Server port accepting client connections (6460 by default); username is the name of AggreGate Server user account password is AggreGate Server user account password; widget_context_path is full path of context of the widget to be launched, e.g. users.admin.widgets. myCustomWidget; If Widget Player can't connect to the AggreGate Server with specified command line parameters (or command line parameters are not set) it displays an authorization dialog prompting to enter Widget Player options.
108

to use for logging in to the server;

OTHER OPTIONS

-c Specifis full path of the default context 315 that will be used during widget operation, e.g. users. default_contex admin.devices.myDevice. This parameter is relevant only for relative 314 widgets. t_path -f -h
Enable full-screen mode. Displays command line parameters help.

Full Screen Mode

Any widget may be expanded to full screen by pressing F11 key. Full screen mode is disabled by pressing ESC or F11.

3.15.21 Web Widget Player

Web Widget Player is a browser-based web application that can run widgets even on systems that have no support for Java Standard Edition (Java SE). This includes: Android OS Apple iOS Windows Phone OS Any other operating systems that have Javascript-enabled browsers

2000-2013 Tibbo Technology Inc.

616

AggreGate Documentation

Currently, the Web Widget Player is in BETA-testing stage. Please contact Tibbo if you experience some troubles with the player. To access widgets in a production environment, please use Widget Player application. To access the web widget player: Open Web Control Center
631 614

desktop

and select Web Widget Player from main menu, OR

Navigate your browser to https://server.address:8443/widget or http://server.address:8080/widget. Check your web application settings 59 if you've problems accessing both pages. Enter your AggreGate Server username and password Enter full context path 863 of your widget context default context 315 (only if your widget it relative
651

(e.g. users.admin.widgets.my_widget) and widget's

314 )

Click on Log In. The widget will open in the browser window.

3.15.22 Device Maps

Device map is a widget used to represent the dynamically updated status of several Devices and any additional information on a graphical map. Here are some examples illustrating the use of device maps: Network map for network management solutions. Such a map would show the status and availability of servers, workstations, routers, switches, and other network equipment. Facility/floor map for access control, security, and video surveillance solutions. A map like this would provide quick access to access control panels, time/attendance terminals, cameras, and other building security/automation devices. Region/city/area map for fleet management solutions. Such a map would show the geographical location of any vehicles being monitored. In terms of AggreGate, a device map is a regular widget consisting of: Layered panel Image
350 382

component with background (lower) and device (upper) layers.

component in the background. This image (raster or vector) contains the maps itself.

Several device 367 components that represent monitored hardware. Every device component is colored depending on device status and supplemented with labels showing device status. Buttons
334

and links opening detailed maps.

344 ,

Any other components showing overall statistics and any additional data: tables

charts

384 ,

labels

323 ,

etc.

Working With Device Maps

Device maps are created using Create Device Map be edited in GUI Builder 827 like any other widget.
770

action of Widgets context. Once the map widget is created, it can

834

New devices are added to the map by dragging a Device Context from Entity Selector container in the Work Form 830 (see details here 846 ).

and dropping it to any

3.15.23 Touchscreen Support

AggreGate widgets are often launched inside industrial PCs equipped with touch panels instead of regular keyboards. However, those widgets may still require minor keyboard input, e.g. entering passwords or diverse numbers. This input is enabled via on-screen keyboard support. Some of widget components (e.g. Text Field 325 , Formatted Text Field 328 , or Password Field 326 ) can show on-screen keyboard upon click or double-click, allowing touchscreen operators to type any text that will be inserted into component. There are two possible choices of onscreen keyboard: 1. AggreGate native keyboard that works under any operating system

2000-2013 Tibbo Technology Inc.

AggreGate Server

617

2. Operating system's onscreen keyboard application or any third-party onscreen keyboard application

Type and style of on-screen keyboard are selected in widget's Root panel settings

377 .

Each component that should show an onscreen keyboard when it's clicked in a touch panel should have its Onscreen Keyboard setting configured to either Single Click or Double Click.

3.16 Dashboards
Dashboards are designed to built interactive data presentation views for system operators. A dashboard displays multiple dynamic components together on separate display within AggreGate Server User Interface (e.g. AggreGate Client 776 ). In many cases, a dashboard contains multiple Widgets 312 . Each widget represents a solid data processing/presentation unit (such as chart), while dashboard is used to group multiple units to show multiple aspects of a monitored device/ resource at once. However, dashboards may contain other modules, such as Event Logs
791

or Query

271

results (i.e. Data Tables

854 ).

Administering Dashboards
Two contexts are used to administer dashboards: One is the general Dashboards 672 context, which serves as a container. The other is the Dashboard 673 context, which holds the information for a single dashboard.

Every user

108

has his own set of Dashboards.

2000-2013 Tibbo Technology Inc.

618

AggreGate Documentation

3.16.1 Dashboard Layouts

There are two dashboard layouts available: Dockable Layout Scrollable Layout Each dashboard element's window location
955

is interpreted differently for dockable and scrollable dashboards.

Dockable Layout
In the dockable layout, all dashboard's windows are placed on one screen and possibly grouped into tabs. These dockable windows can be managed (closed, moved, re-docked, floated, etc.) as described in Customizing Dockable Windows 781 article. For dockable layout, all properties of each element's location are interpreted exactly as described in window location section.
955

Scrollable Layout
Scrollable dashboards place windows one under another, in several columns. If all windows do not fit into the screen, a vertical scroll bar appears. For scrollable layout, State and Side parameters specified in window location 955 are ignored. Index parameter defines the zero-based index of column to which the window will be added. In each column, windows appear in the same order as in the Dashboard Elements 619 table.

2000-2013 Tibbo Technology Inc.

AggreGate Server

619

3.16.2 Dashboard Types

Dashboards subdivide in two types: Absolute Relative

Absolute Dashboards
Absolute dashboards are most used to display data coming from multiple different sources, e.g. several devices. In some cases, an absolute dashboard may display or control a pre-defined device or resource those name is hardcoded into dashboard elements' 619 parameters. Absolute dashboards are opened by right-clicking on a dashboard context 621 .
673

) and selecting open dashboard action

Relative Dashboards
Relative dashboards show status of a single device/resource that is not hard-coded into dashboard's configuration. A relative dashboard is opened for a certain device/resource by right-clicking on it and selecting launch dashboard action those name match dashboard description (this action's icon is always ).

3.16.3 Dashboard Elements

Every dashboard consist of elements. Each element is opened in a separate sub-window within dashboard window. Element properties 624 include: Title and location of element's window Type and properties of the element itself

2000-2013 Tibbo Technology Inc.

620

AggreGate Documentation
619

Validity expression that allows to exclude certain elements if target context (i.e. context for that a relative dashboard is opened) doesn't match specific criteria

Element Types
The following dashboard element types are supported: Widget Data Table Properties Event Log System Tree Report

WIDGET
This element opens a widget being opened. Element properties: Widget. The path of widget context
774 . 312 .

If the widget is relative

314 ,

it's started for the same context for those the dashboard is

DATA TABLE
This element evaluates an expression that should evaluate to a Data Table Table Editor 801 as a part of the dashboard. Data Table element is ideal for showing query Element properties: Icon ID. ID of the icon to show in the title of element's window. Help ID. ID of the help article that the element should refer to. Expression . Expression to be evaluated. Refresh Period. Period of expression re-evaluation, i.e. data refresh rate.
271 854 .

The Data Table's data is shown in a Data

results within a dashboard.

PROPERTIES
Shows a Properties Editor Element properties: Context. Context
863 795

inside a dashboard.

those properties to show.

Group. Group of properties to show, or NULL to show manually specified properties. Properties. List of properties to show if Group is NULL. Simple Mode. Use Properties Editor's simple mode
796 .

Initially Read-Only. Lock the editor upon startup. It will be necessary to click Unlock toolbar button to start editing.

EVENT LOG
Shows an Event Log Element properties: Event Filter. Context path of event filter
206 791

inside a dashboard.

to use.

Events. List of specific events to show in the log, specified by "Context Path - Event Name" pairs. This option is active if no filter is specified. Current Events. Flag indicating whether or not to show Current Events section of the log. Event History. Flag indicating whether or not to show Event History section of the log. Preload Event History. Enables/disables loading event history upon Event Log startup. Show Context Names. Controls visibility of Context column.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Show Event Names. Controls visibility of Event column. Show Event Levels. Controls visibility of Level column. Show Event Data. Controls visibility of Data column. Show Event Acknowledgements. Controls visibility of Acknowledgements column.

621

SYSTEM TREE
Shows a custom-rooted System Tree Element properties: Root. Path of the tree's root context. Related Actions. Flag that controls visibility of Related Actions pane.
784

component inside a dashboard.

REPORT
Shows a report viewer Element properties: Report . Path of a report context.
814

inside a dashboard.

3.16.4 Opening Dashboards

There are several ways to open a dashboard: Using the Open Dashboard 673 action of a Dashboard Context. This method should be used for absolute 619 dashboards. For relative 619 dashboards, this method will open the dashboard for the AggreGate Server root context, causing wrong behaviour in most cases. Using an Open Dashboard action resource.
892

(see below) to start a relative

314

dashboard for a certain Device or system

Open Dashboard Action

This action may be found in every context for those relative dashboard's validity expression 948 is true. When the Open Dashboard action is started in some context, this context becomes a default context 315 for the opening dashboard. For example, if a User Overview dashboard is created for a User 759 context (e.g. has Validity Expression {.#type} == 'user'), an action called User Overview will appear in the context of every AggreGate Server user. Its description is the same as that of the dashboard itself. Actions that are used to open dashboards may be easily recognized by a icon. Here is what an Open Dashboard action looks like in a context menu within AggreGate Client:

2000-2013 Tibbo Technology Inc.

622

AggreGate Documentation

Relative dashboards will install their Open Dashboard Action only into contexts that are accessible for the dashboard owner according to his permissions 931 . To be able to launch this action, the user must have an effective permission level contexts: Dashboard context
673 935

of Observer in two

of the actual dashboard being launched

The context on which the dashboard operates, i.e. the one where Launch Action is defined

Dashboard Window
The dashboard is opened in a separate tabbed window in any AggreGate Server User Interface. When dashboard window is closed, all dashboards components are stopped (e.g. if it were running widgets 312 ) and hidden. Here is how a dashboard look like in AggreGate Client:

2000-2013 Tibbo Technology Inc.

AggreGate Server

623

3.16.5 Dashboard Configuration

This section covers dashboard configuration properties. All properties described here are available via Configure
904

action of a Dashboard context

673 .

3.16.5.1 Dashboard Properties

This property defines basic options of a dashboard.

Field Description
Dashboard Name. Name of the dashboard context, required to refer to this dashboard from other parts of the system. It should satisfy the context naming conventions 863 . Dashboard Description. Textual description of the dashboard. This is also the description 864 of the dashboard context. Title Expression . Dashboard title that appears on the top of dashboard window. If title is not specified, its Description used instead. Title can be a plain string or an expression 911 . If it's an expression, it's evaluated into string to allow titles of relative 619 dashboards display values from contexts those data is displayed on dashboard. Example: Assuming we are creating a dashboard that shows device power status, we may set Title Expression to 'Power Status: ' + {.#description}. It will include description of device context, e.g. "Power Status: Device213". Title Expression Resolution Environment
922

Field Name
name

description

title

2000-2013 Tibbo Technology Inc.

624

AggreGate Documentation

Default Context

927 927

Context for that a relative dashboard is opened. None. 0

930

Default Data Table Default Row

927

Environment Variables

Standard
618 ,

931

variables only. layout columns type validityExpression

Layout. Dashboard layout

dockable or scrollable.

Column Count . Number of columns, relevant for scrollable dashboards only. Type . Type
619

of the dashboard: Absolute or Relative.

Validity Expression. Determines which context(s) may be "understood" by the dashboard. See Resource Validity 948 for more information. Validity Update Rules. A list of context masks and event names. If event specified by Event field of this table occurs in any of context matching to the mask specified by Mask field in the same record, Validity Expression will be recalculated for this context. This allows to make dashboard valid/invalid for a certain context if some changes occur in it. This property may be accessed via the childInfo
674

validityListeners

variable.

3.16.5.2 Dashboard Elements

The elements
619

of a dashboard are defined by the following properties:

Field Description
Title. This is the header odf element's window. Type . Element type, see elements
619

Field Name
title type location

article for details.

Window Location. Location of element's window within dashboard window. See details here 955 . Parameters. Settings of the element. The settings define what data will be shown and how to present it. List of settings depend to element's Type . Validity Expression. An expression 911 that defines whether the element should be skipped during dashboard rendering. It it evaluates to FALSE, the element will be skipped. Validity Expression Resolution Environment Default Context
927 927 922

parameters

validityExpression

Context for that dashboard is opened. None. 0

930

Default Data Table Default Row

927

Environment Variables

Standard

931

variables only. variable.

These may be accessed via the elements

674

3.16.6 Dashboards Security

Once a dashboard is opened by a system user 108 , all its elements are started under launching user's permissions. The permissions of dashboard owner user and users owning particular dashboard elements (e.g. widgets 312 ) are ignored. For example, if user Joe opens a dashboard owned by the default administrator 109 , dashboard elements will have Joe's limited permissions. However, if the administrator opens any of Joe's dashboards, the dashboard and its elements will have unrestricted permissions, introducing potential security risk if Joe is not a trusted user.

2000-2013 Tibbo Technology Inc.

AggreGate Server

625

3.17 Auto Run

The Auto Run feature allows actions 892 to be executed automatically when a user logs into a AggreGate Server User Interface, such as AggreGate Client. Auto Run actions are very useful for creating "dashboards", which are sets of widgets 312 , queries 271 , and reports 241 which are automatically displayed in pre-set positions as soon as a user launches AggreGate Client. Another use would be to automatically display the status of a particular mission critical Device 113 . Actions are launched in the same order as they appear under the Auto Run context. Children of this context may be reordered. AggreGate Client users may use reordering feature 788 of the System Tree for that, while other AggreGate Server User Interfaces provide similar facilities. Unlike actions launched "directly" (e.g. from the System Tree facility may use custom execution parameters 896 . Every user
108 784

of AggreGate Client), actions started using Auto-Run

has his own set of Auto Run Actions.

Related tutorial: Creating a Dashboard to Monitor Your Devices in Real-Time

1233

Reordering Auto Run Actions

It's possible to change the order of auto-started actions execution using the System Tree Open Auto Run node under Users => Your_Username Drag one of the actions and drop it in between two other actions (or in the beginning/end of the list) See Node Reordering
788 784

of AggreGate Client:

section for details.

It's not possible to reorder actions using the Auto Run container located right under the Server node of System Tree because this container mixes auto run actions that belong to different system users 108 .

Administering Auto Run

Two contexts 863 are used to administer the automatically started actions: One is the general Auto Run 662 context, which serves as a container. The other is the Auto Run Action 664 context, which holds the information for one auto-started action.

Launching Widgets, Reports and Dashboards via Auto Run

Widgets 312 , reports 241 , dashboards 617 and several other system objects can be absolute and relative. While an absolute object is launched per se, relative objects are started over a certain context 863 that serves as a data source. Thus, adding relative object's launch action to auto run directly won't let the system know what context should it be started for. Instead, object's launch action located in the target context should be added to auto run. Example: Assuming there is a Traffic Chart relative widget that is valid for all network devices add traffic chart of a certain device to auto run. To do that: Drag selected device and drop it to the Auto Run node Choose Traffic Chart in the action selection dialog
113 .

You can

2000-2013 Tibbo Technology Inc.

626

AggreGate Documentation

3.17.1 Auto-Run Action Configuration

Every auto-run action has several properties: Field Description Description . A textual description of the automatically started action. This is also a description 864 of the Auto Run Action context. Context Mask 865 . This defines the scope of the Auto Run action. The action will be launched from all contexts matching this mask. Action. The action which will be launched when Auto Run is activated. Enabled. The Auto Run action can also be enabled or disabled (without deleting the action itself). Parameters. Action execution parameters
896 . 665

Field Name description mask action enabled executionParameters variable.

These properties may be accessed through the childInfo

3.17.2 Auto Run in Distributed Architecture

This section describes specifics of auto run actions behavior in a distributed installation
99

of AggreGate.

To make an auto run action connected from a provider server launched by clients connected to a consumer server, make sure that the context path of connected auto run action context on the consumer server matches users.*. autorun.* context mask, i.e. the remote auto run action appears among local actions.

3.18 Favourites
The AggreGate interface is rich in functionality, and the context tree navigation easier, Favourites have been implemented.
863

can get quite deep and complex. To make

Favourites allow AggreGate users to execute commonly-used actions 892 with a single mouse click. You don't have to "dig" in the context tree -- you can have instant access to whatever you use the most via the Favourites, which work like "shortcuts" or "quick links" leading to various contexts. The Favourites are easy to locate in all AggreGate user interfaces. For example, this is what they look like in AggreGate Client:

The following columns are displayed in the table: Number: This is the line number of the favourite in the table. Description: This is a textual description of the action which will be executed (can be changed by the user). Server: This is the server on which the favourite is configured. Context Mask: This is the context mask 865 to which the favourite applies or description of the context resolves to a single context (i.e, does not contain any wildcards).
863 ,

if the mask

Action: This is the description of the Action which will be executed on the context mask when the favourite is launched. Every line in the table functions as a link. When the line is clicked, the Favourite is launched. You can click any column. In the AggreGate Client, when a workspace 779 contains several server connections, the resulting favourites table includes all favorites that are available under all accounts. In effect, the favourites are collected from all AggreGate Server connections and displayed in one unified table in the AggreGate Client. This lets you use just one Favourites table to navigate all over your "AggreGate Universe". Unlike actions launched "directly" (e.g. from the System Tree facility may use custom execution parameters 896 . Every user
108 784

of AggreGate Client), actions started using Favourites

has his own set of Favourites.

2000-2013 Tibbo Technology Inc.

AggreGate Server

627

Related tutorial: Performing an Action With Multiple Devices

1211

Administering Favourites
Two contexts 863 are used to administer the automatically started actions: One is the general Favourites 697 context, which serves as a container. The other is the Favourite 699 context, which holds the information for one particular favourite item.

Launching Widgets, Reports and Dashboards via Favourites

Widgets 312 , reports 241 , dashboards 617 and several other system objects can be absolute and relative. While an absolute object is launched per se, relative objects are started over a certain context 863 that serves as a data source. Thus, adding relative object's launch action to favourites directly won't let the system know what context should it be started for when a favourite is clicked. Instead, object's launch action located in a target context should be added to favourites. Example: Assuming there is a Traffic Chart relative widget that is valid for all network devices add traffic chart of a certain device to favourites. To do that: Drag selected device and drop it to the Favourites node Choose Traffic Chart in the action selection dialog
113 .

You can

3.18.1 Favourite Configuration

Every favourite action is characterized by several properties:

Field Description Description. Textual description of the favourite. This is also a description
Favourite context.
864

Field Name
of the description

Context Mask

865 . This defines the scope of the favourite. When executed, the favourite action will be launched from all contexts which correspond to this mask.

mask

Action. Name of the action to be launched. Enabled. The favourite can also be disabled (hidden from favourites list). Parameters. Action execution parameters
896 . 700

action enabled executionParameters variable.

These properties may be accessed through the childInfo

3.18.2 Favourites in Distributed Architecture

This section describes specifics of trackers behavior in a distributed installation
99

of AggreGate.

To make a favourite connected from a provider server appear in Favourites table of clients connected to a consumer server, make sure that the context path of connected favourite context on the consumer server matches users.*. favourites.* context mask, i.e. the remote favourite appears among local favourites.

2000-2013 Tibbo Technology Inc.

628

AggreGate Documentation

3.19 Scripts
Scripts allow AggreGate Server administrators and privileged users to execute custom pure-Java code within a Java Virtual Machine (JVM) that runs AggreGate Server. Every script is executed inside server core and has access to all inmemory objects and structures of the server. Thus, scripts are very powerful tool that provide an ability for a full realtime control of the server. Scripts are executed in server JVM and their permissions are not restricted in any way. See Script Security for more information.
631

Script Interface
Scripts are written in Java. Every script is a single Java class that must implement a Script interface: public interface Script { public DataTable execute(ScriptExecutionEnvironment }

environment,

DataTable

parameters)

throws

ScriptExc

This interface declares a single execute() method that is called by AggreGate Server when script is executed. There are two ways to launch a script: Manual execution by calling the execute 748 action of a Script be of any format) will be directly passed to the script.
748

context. The function input Data Table

854

(that may

Automatic execution on AggreGate Server startup. The script is executed by the server automatically during startup if the Launch Automatically Upon Server Startup flag is enabled in stript properties 629 . In this case, no input will be passed to a script. The script may return some data in the form of Java DataTable object. This table is returned by the execute 750 function of the Script context. If script returns NULL, a single-cell table with nullable string field is returned by the execute function.

Execution Environment
Every script has access to an object implementing ScriptExecutionEnvironment interface that is passed as an argument to execute() method. Here is what ScriptExecutionEnvironment interface look like: public interface ScriptExecutionEnvironment { public abstract CallerController getCallerController(); } Instance of ScriptExecutionEnvironment provides access to an object implementing CallerController interface (it is obtained by calling getCallerController() method). This object incorporates permissions of a user that initiated script execution. CallerController object is passed as an argument to most of context 863 -related operations (Get Context, Get/Set Variable, Call Function, Add/Remove Event Listener etc.) When a script is launched automatically during server startup, its execution environment contains a system CallerController that suppresses all permission checking.

Developing Scripts
See Programming Guidelines
980

section for common practices of developing AggreGate server scripts.

Script Template
When a new script is created, its text is not empty. It contains an auto-generated stub of a class implementing Script interface with an empty execute() method. Here is the default script text: import import import import com.tibbo.aggregate.common.context.*; com.tibbo.aggregate.common.datatable.*; com.tibbo.aggregate.common.script.*; com.tibbo.linkserver.*;

2000-2013 Tibbo Technology Inc.

AggreGate Server

629

import import

com.tibbo.linkserver.context.*; com.tibbo.linkserver.script.*;

public class %ScriptClassNamePattern% implements Script { public DataTable execute(ScriptExecutionEnvironment environment, { } }

DataTable

parameters)

throws

ScriptExc

Note, that %ScriptClassNamePattern% will be replaced by an auto-generated Java class name during compilation. Do not change this part of the script to avoid compilation problems. After you've put some meaningful code inside the body of execute() method, you may try to execute a script. Note, that script is re-compiled by Java compiler upon every execution. Any compilation errors are reported to the user. See description of Execute 748 action for more information.

Administering Scripts
Two contexts 863 are used to administer the scripts: One is the general Scripts 747 context, which serves as a container. The other is the Script 748 context, which holds information for one particular script.

Every user

108

has his own set of scripts.

Built-In Scripts
Currently, just one pre-defined script is bundled into the core AggreGate Server distribution. This script is called SLA Breakdown Date Calculator , and it's described in Predicting SLA Breakdowns 1276 tutorial.

3.19.1 Script Configuration

Every script is characterized by several properties:

Field Description
Script Name . Name of the script context 748 , required to refer to this script from other parts of the system. It should satisfy the context naming conventions 863 . Script Description. Textual description of the script. This is also a description the Script context. Script Text. Script source in Java programming language. Launch Automatically Upon Server Startup. Flag that forces server to launch script during startup. These properties may be accessed through the childInfo
749 864

Field Name
name

of

description

text autorun

variable.

2000-2013 Tibbo Technology Inc.

630

AggreGate Documentation

3.19.2 Using Scripts In Expressions

It is possible to call a script from an expression 911 by inserting a reference 925 to the execute 748 function of the Script context. Function parameters specified 927 in the reference will be passed to the script. The Execute Script function returns a value that may be referred from the other parts of expression. Example. Here is the expression referring calculator script and passing some input to it:

{users.admin.scripts.calculator:execute("123", "456", "789")}

The script will receive three strings "123", "456" and "789" as an input (see specifying context function input parameters in the reference 927 for details). It may convert these strings to numbers, perform necessary calculations on them and return the result.

3.19.3 Script Examples

Here is an example of script that changes IP address of a hardware Device Server import import import import import import com.tibbo.aggregate.common.context.*; com.tibbo.aggregate.common.datatable.*; com.tibbo.aggregate.common.script.*; com.tibbo.linkserver.*; com.tibbo.linkserver.context.*; com.tibbo.linkserver.script.*;
1003 :

public class %ScriptClassNamePattern% implements Script { public DataTable execute(ScriptExecutionEnvironment environment, DataTable parameters) throws ScriptExc { try { // Getting context of a Device Server Context con = LinkServer.getContextManager().get("users.admin.deviceservers.c1", environme if (con == null) { throw new }

ScriptException("Device

Server

not

available");

// Getting IP address variable DataTable val = con.getVariable("IP_setting", environment.getCallerController()); // Changing IP address val.rec().setValue("IP_setting", "192.168.1.235"); // Writing new value of variable con.setVariable("IP_setting", environment.getCallerController(), val); // Rebooting Device Server con.callFunction("reboot", environment.getCallerController()); return null; } catch { (ScriptException ex)

throw ex; } catch (Exception ex) { throw new ScriptException(ex); } } }

2000-2013 Tibbo Technology Inc.

AggreGate Server

631

3.19.4 Scripts Security

Scripts are executed in server JVM and their permissions are not restricted in any way. Thereby a single unintentional error in a script, or some malicious code, may cause the server to function improperly, hang, get 100% CPU time, corrupt its database or even corrupt data on the machine running it. By default, only the default administrator 109 may modify and execute scripts. Give only trusted users permissions to execute scripts. If a script can be substituted by an expression 911 , it's always advised to go for this substitution, since expression security 924 mechanism ensures that calling party's permissions are inherited by all expression's operations.

Script Execution
To let another user execute scripts, set his permission level execute all scripts in this context.
932

in Scripts

747

context to Admin. This will allow the user to

748

To allow execution of a single script, set the user's permission level in that Script

context to Admin.

Script Modification
Only users that have Administrator effective permission level 932 in the Script context may modify script configuration and code. This ensures maximum security for script operations.

3.20 Web Control Center

The AggreGate Server Control Center is web portal used to access different web-based interfaces of AggreGate Server. To access the Control Center, type the following URL in a browser: https://a.b.c.d:8443/. In this URL, a.b.c.d is the IP address of AggreGate Server machine. If Enable non-secure access to web applications 60 global configuration option is turned on, it's also possible to access the Control Center via the following URL: http://a.b.c.d:8080/. The port numbers (8443 and 8080) are configurable in the Web Applications If the above URLs are not accessible: Check that you've specified correct server address Check server configuration file
52 59

section of global configuration options.

to find out the port numbers

108

Try opening the Control Center via system tray menu

Control Center Instructions

Here is what the Control Center main page looks like:

Once the Control Center is open, you can select one of the following options: Install and launch AggreGate Client. Installs and immediately launches AggreGate Client in the Java Web Start mode 776 .

2000-2013 Tibbo Technology Inc.

632

AggreGate Documentation
776 .

Open AggreGate Client in the Browser. Immediately starts AggreGate Client in the browser window Open Web Desktop (beta version). Allows to access the Web Desktop Desktop is enabled 59 .
632 .

This item is visible only if Web

976 .

Open Web Services Admin Console. Opens administration console for Web Services

3.21 Web Desktop

AggreGate Web Desktop is a web-interface that gives remote control capabilities to AggreGate Server. It provides the same functionality as desktop AggreGate Client 776 , with the following exceptions: Web Desktop is used to control a single instance of AggreGate Server only, while desktop AggreGate Client may access several servers at once Web Desktop has no Report Editor Web Desktop has no GUI Builder
826

827

Otherwise, Web Desktop provides full configuration, control and monitoring functionality for AggreGate Server, all its resources (alerts, user accounts, trackers, etc.) and all connected devices. Currently, the Web Desktop is in BETA-testing stage. The current Web Desktop version will not let you access several vital options. To access AggreGate Server in a production environment, please use AggreGate Client desktop application.
776

Embedded Web Server

Since Web Desktop is an AJAX-based Rich Internet Application (an application that can be accessed using a standard web browser) it needs a web server to run. This web server is built into the AggreGate Server and tightly integrated with its functions. It starts automatically each time the AggreGate Server is launched and shuts down when the AggreGate Server is stopped. Check Web Applications server configuration.
59

section of AggreGate Server Global Configuration to find out details of embedded web

3.21.1 Accessing Web Desktop

To access AggreGate Server Web Desktop, you need to enable it in AggreGate Server Global Configuration by setting Enable Web Desktop 59 option to true . Before accessing the Web Desktop, make sure that AggreGate Server is successfully started and running. Startup procedure is described under Startup and Shutdown 44 .

Accessing Web Desktop Via Tray Icon

This method is only valid for opening Web Desktop from the same machine that runs AggreGate Server: Locate AggreGate Server icon in the system tray Right-click on the icon. Select Open Web Desktop in Browser item.
108 .

Direct Access to Web Desktop

This method allows to access AggreGate Server Web Desktop from any remote PC: Open a web browser, such as Internet Explorer or Mozilla Firefox. In the address bar, type https://xxx.xxx.xxx.xxx:8443/wd, where xxx.xxx.xxx.xxx is the IP address of the server (if you're actually working locally on the server, this would be 127.0.0.1). In the login dialog that will appear, enter the username and password of your user account
108 .

If Enable non-secure access to web applications 60 global configuration setting is active, it is also possible to access the Web Desktop via a non-secure connection using this URL:

http://xxx.xxx.xxx.xxx:8080/wd

2000-2013 Tibbo Technology Inc.

AggreGate Server

633

If AggreGate Server uses non-standard port numbers (secure 60 and/or non-secure 60 ) to accept web connections, the connection to Web Desktop using the above URLs will fail. In this case: Check current port numbers in AggreGate Server configuration file 52 or by connecting to AggreGate Server using AggreGate Client 776 and browsing global configuration Substitute port number in one of the above URLs and try accessing the server again

Connection Troubles
If you still cannot access the Web Desktop after verifying that it's active and you are using correct URL, try the following: Check AggreGate Server log file
74

for Web Desktop startup errors

If it doesn't give you a hint, send the log file to Tibbo for analysis

3.21.2 Login and Logout

Once you've accessed the Web Desktop in the browser window, you need to log in using your AggreGate Server user account 108 name and password. The login dialog is shown below:

Enter your username and password in the auth dialog and click Login to get authenticated and start using Web Desktop. Help link opens the most recent online version of AggreGate documentation. Register link allows to create a new AggreGate Server user account global configuration option is enabled.
108

if Enable user self-registration

54

2000-2013 Tibbo Technology Inc.

634

AggreGate Documentation

Self-registration
Once you've clicked Register link in the auto dialog, you will be redirected to a self-registration page:

Enter your desired username, password and other information in the form and click on Register to create a new user account. You will be redirected to the login form again.

Logout
To log out from the Web Desktop, click on the Log Out button on the main window toolbar before closing browser window.

3.21.3 User Interface

The layout of Web Desktop is very similar to layout of AggreGate Client Web Desktop layout comprises toolbar dashboard called Main Dashboard.
635 780 .

and dashboards with different windows. By default, there is only one

2000-2013 Tibbo Technology Inc.

AggreGate Server
Default layout of the main dashboard includes the following parts: A System Tree
636 637

635

One or more Event Log's Favourites Trackers

651

window

651

window
640 ,

Other windows, such as Properties Editor use.

Widget

312 ,

or Data Table Editor

643

windows, may be added during normal

3.21.3.1 Toolbar
The Web Desktop toolbar includes several buttons: Close/Open System Tree. Toggles visibility of System Tree Close/Open Close/Open Favourites. Toggles visibility of Favourites Trackers. Toggles visibility of Trackers
651 . 636 . 633 . 651 . 636 .

Close/Open Event Log. Toggles visibility of System Tree

Log out. Finishes Web Desktop work session and de-authenticates current user. Redirects to the login form

2000-2013 Tibbo Technology Inc.

636

AggreGate Documentation

3.21.4 System Tree

The System Tree is used to browse and administer various server resources and devices.

Every tree node represents a server context Click here tree.

868

863

(and may have sub-contexts under it).

to check the difference between context tree visible in System Tree and real server context

3.21.4.1 Context Menu

When you right-click a System Tree node, a context menu is shown. The context menu options are node-specific. These are actions 892 defined in the AggreGate Server context corresponding to the current node. The action usually interacts with the user by executing different UI Procedures 896 . Menu item corresponding to a default action
893

(i.e. action started upon double-click on a node) is highlighted in bold.

For some nodes, the context menu also contains a "Group Actions" submenu. It contains action you can apply on every child of the current node. See action grouping 894 for more info. Here's what the System Tree context menu for a Device node looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Server

637

3.21.5 Event Log

The Event Log component is intended for viewing and managing server events provides access to event history 882 and allows to acknowledge 882 events. Event Log consist of two main parts: Current Events and Event History:
880

in the real-time mode. It also

Both parts have a toolbar that helps to access frequently used functions. In the left part of both toolbars the is a drop down box that allows to select an Event Filter. Initially, these the selected filter is <Empty Filter> what means that no events are shown. In some cases Event Log component shows a predefined set of event types. In this case list of Event Filters and related buttons ("Reactivate Filter", "Configure Filter") are not available. It is possible to sort events. To enable sorting, click on the column header. Subsequent clicks will change sorting order for this column between ascending and descending. Clicking on a button in the Data column next to any event opens Data Table 643 .
854

associated with it in a Data Table Editor

Event Log uses Date Pattern , Time Pattern and Timezone settings specified in User Account Properties to properly convert and render different timestamps. All date/time values are shown in active user's timezone.

110

3.21.5.1 Current Events

Current Events table shows events happening on the server in the real time. Events are filtered according to the currently selected Event Filter 206 or by the custom filtering rules specified by the server during execution of Show Event Log 898 UI Procedure.

Current Events Toolbar

2000-2013 Tibbo Technology Inc.

638

AggreGate Documentation
206

The drop-down box selects Event Filter

that will be used to filter events that will be shown in the log.

Reactivate Current Filter. This operation allows to re-enter filter parameters. Configure Current Filter. Edit settings of currently selected filter.

View Severity Statistics. Shows the number of events of each level Export . Exports
640

882

in the Current Events window.

events currently shown in the Current Events window to a file.

Clear Current Events . Clearing the current events table doesn't remove these events from the server and doesn't prevent new events from appearing in the table.

3.21.5.2 Event History

Event History displays events that happened in the past and were saved by the server. Events are filtered according to the currently selected Event Filter 206 or by the custom filtering rules specified by the server during execution of Show Event Log 898 UI Procedure. Not all events are persistently saved in the history. Thus, event that has appeared in the Current Events section is not guaranteed to appear in Event History.

Event History Toolbar

Event Filter
206

selected in the drop-down box is used to filter out events that will be shown.

Reactivate Current Filter. This operation allows to re-enter filter parameters. Configure Current Filter. Edit settings of currently selected filter.

View Severity Statistics. Shows the number of events of each level history. Export . Exports
640

882

in the currently loaded event

events currently shown in the Event History window to a file.

Only events shown in the currently selected range will be exported. To export larger number of events, increase value in Events combo box (see below). Refresh. Refreshes event history. This operation causes the server to reload the history according to the current filter. The actual visible events may change after this operation. First. Scrolls history list to the first page. Previous . Loads previous page of the history list. Next. Loads next page of the history list. Last. Scrolls history list to the last page. The Events combo box in the middle of toolbar defines how many events are shown at once. The total number of events corresponding to the filter and range of currently shown events is indicated in the right part of toolbar.

3.21.5.3 Context Menu

Context menu is available upon right click on one of the events in the Event Log. It includes the following items: Show Event Data. Opens Data Table
854

associated with the event in the Data Table Editor

643 .

Acknowledge Event. Allows user to set event acknowledgement. This operation is available only for persistent events.

2000-2013 Tibbo Technology Inc.

AggreGate Server
View Acknowledgements . View event acknowledgements in the Data Table Editor
643 .

639

Delete Event. Permanently delete event from event history. This operation is available only for persistent events. Event context menu also contains a Related Actions submenu with list of actions event was occurred or related to the event 895 itself.
892

related to the context

863

where

For example, for a Device-related event, "Reboot Device", "Configure Device" and other operations may be shown. Event context menu example:

3.21.5.4 Acknowledging Events

Event acknowledgement 882 function is available for persistent events only. When Acknowledge Event menu item is activated, user is prompted to enter acknowledgement text:

When acknowledgement is set, its time, author and text appear in the Acknowledgements column of the events table:

2000-2013 Tibbo Technology Inc.

640

AggreGate Documentation

3.21.5.5 Exporting Events

Export functionality of Event Log in Web Desktop is similar to AggreGate Client's Event Log export
795 .

3.21.6 Properties Editor

The Properties Editor is used to change the properties of different contexts Server itself and Devices are edited in a Properties Editor.
863 .

For example, settings for AggreGate

Technically, the Properties Editor allows changing the values of one of more variables 869 (properties) of a context. When the editor starts up for a given context, it loads the value of every variable for the context, and then allows the user to edit these values and writes them back to the context. Every property (variable) is edited in a separate Data Table Editor single Data Table 854 . The Properties Editor consist of a Toolbar and a Properties Pane:
643

component, because a property is actually a

Toolbar
Reload. Reloads values of all properties from the source context. Values that were recently changed in the editor are lost. Save . Saves values of changed properties to the source context. Saved values are marked as unchanged. Import properties. Import Export properties. Export
800

values of properties from the file. values of properties to the file.

800

If Properties Editor is shown on a separate page, it has OK and Cancel buttons. The OK button saves the values of any properties which were modified, and closes the dialog. The Cancel button aborts the operation without saving. Most elements of the Properties Editor, as well as the actual properties, often have tooltips. These appear when the mouse cursor hovers over the element for some time.

2000-2013 Tibbo Technology Inc.

AggreGate Server

641

Context Menu
The context menu is shown when right-clicking one of the properties in the Properties Editor. It contains a list of Variable-Related Actions 895 that "know" what to do with the selected variable. The number and types of available Variable-Related actions depend on the type of variable for which the context menu is shown.

Properties Editor Modes

The Properties Editor may work in two modes: Normal mode Read-only mode Read-only mode doesn't allow properties to be edited or saved. There are also two representation modes of Properties Editor: Simple Mode Expanded Mode

Property Representation Modes

SIMPLE MODE
In Simple Mode, every Data Table Editor representing the value of a single property occupies a separate tab. On the below picture, a Data Table Editor containing the value for a single property is marked with a red rectangle:

The property's name and detailed description are shown in a tooltip of its tab:

2000-2013 Tibbo Technology Inc.

642

AggreGate Documentation

EXPANDED MODE
In Expanded Mode, properties are grouped according to their variable group a separate tab. Group names are shown as tab headers.
870 .

Properties of each group are shown in

Properties of every group are represented as a table with two or three columns. The first column is optional, and may contain a status icon for the property. The properties editor constantly monitors the status of every variable and updates the status icon with every change. Hovering the mouse over the icon pops up a tooltip with the status details:

The Property column contains property descriptions. Cell tooltips provide information about each property's name and its detailed description:

The Value column's contents changes according to the variable definition 869 of the context being edited. If the Data Table 854 representing the value of a property always has just a single field with a single record, the Data Table Editor 643 is shown directly in the third column. In other cases, the third column will contain a [...] button, which would open a Data Table Editor on a separate page. A Data Table Editor that is embedded into the table is marked in red on the picture below:

Importing and Exporting Properties

2000-2013 Tibbo Technology Inc.

AggreGate Server

643

Properties can be exported to and imported from external files. By default, property files have a .prs extension. Properties are imported by name: if the Properties Editor contains a property with the same name as one saved in the file, their values are merged by a Data Table Smart Copy 861 operation. Properties import procedure cannot just override values contained in the editor with ones read from a file because they may have different format 855 . But in any case the best efforts are made to import as much data as possible.

3.21.7 Data Table Editor

The Data Table Editor (DTE) is a component used to edit or view a single Data Table By the Properties Editor By the Event Log By the Edit Data
637 896 640 854 .

It is used:

to edit context

863

variables

869 880

to view Data Tables associated with events UI Procedure to edit function

878

input parameters and view its output, etc.

And in many other system facilities.

Most elements of the Data Table Editor, such as column headers and data cells, usually have tooltips which pop up when the mouse hovers over the element. The tooltip for the column header contains the field type and help string specified in the table's format
855 ,

if any.

The tooltip for a cell contains a string representation of the cell's value, and the type of field used for this cell. For example, it may be useful: If a cell's value too long to fit into the cell itself, If the cell editor has selection values box.
856

and you want to see the value itself, not its description from the drop-down

If cell tooltip provides some important extended information, the cell is marked with a small blue triangle:

2000-2013 Tibbo Technology Inc.

644

AggreGate Documentation

Data Table Editor uses Date Pattern , Time Pattern and Timezone settings specified in User profile properly convert and render different timestamps. All date/time values are shown in active user's timezone.

110

to

Data Table Editor Modes

Data Table Editor may work in two modes: Normal mode Read-only mode In the read-only mode editing is disabled. There are also two data presentation modes: Multiple records mode Single record mode In multiple records mode, the table header shows the description for every column, and every row represents one Data Table record:

Single record mode is used by the DTE when the table being edited contains just one record, and no extra records may be added. This mode features a two-column layout: the left column shows field names, and the right one contains values:

Toolbar
The Data Table Editor toolbar provides access to the operations that may be performed with the data table Add Row
854 .

Insert a new row before the currently selected one. If no row is selected, a new row is added to the end of table. This button is disabled or hidden if rows may not be added to the table.

2000-2013 Tibbo Technology Inc.

AggreGate Server

645

Remove Selected Rows Move Row Up

Remove the currently selected row(s). This button is disabled or hidden if rows may not be removed. Move current row up. This button is not shown if rows may not be reordered. It changes actual data in the table (in contrast to the sorting operation, which merely changes how the data is shown.) Move currently row down. This button is not shown if rows may not be reordered. It changes actual data in the table (in contrast to the sorting operation, which merely changes how the data is shown.) Undo all changes that were made to the table. This button is enabled only after a change is made. Imports Exports
649

Move Row Down

Reset Changes Import Data Table Export Data Table Make Report

data from a file. data to a file.

649

649

Generate a report

based on the table being edited or viewed.

Some (or even all) toolbar buttons may be hidden or disabled if their respective operations are not available in the editor. A button is hidden if the operation is not applicable to the current table at all. If an operation is simply not available at the moment (e.g. the Remove Selected Rows is disabled when no rows are selected), its button is disabled.

Processing Data Bindings

The Data Table Editor handles bindings 860 contained in the format 855 definition of the Data Table being edited. When the editor loads, it reads the list of bindings for the table and processes them in the background. Bindings are evaluated and used to change cells in the table being edited. Binding expressions used by Data Table Editor may contain relative links to the cells of the table being edited, along with links to data from various contexts 863 . To find out how to create these links, learn more about data bindings here 854 .

3.21.7.1 Editing Data

If the Data Table Editor is in the editable mode, the values within the table may be changed. Renderer and editor used to display and modify value in each cell depends on several factors. Field type Editor/Renderer specified in field declaration Availability of Selection Values Whether the field value is NULL
856 856

(that is a part of Table Format)

declared for this field in Table Format

Special Renderers/Editors
There are some special cases when non-standard editors are used:

NULL VALUE RENDERER

If the field is declared as Nullable and its value is NULL , it is shown as <Not Set> in DTE. Click the cell to start editing and set a non-null default value for it. You can reset the value back to NULL using the Remove value operation in the cell context menu.

SELECTION VALUES EDITOR

If a field format contains selection values
856 ,

editing is performed using a drop-down box:

2000-2013 Tibbo Technology Inc.

646

AggreGate Documentation

If Extendable Selection Values 856 flag is set in Field Format, any custom value can be typed in the text field next to the combo box if Other option is selected in it:

Standard Renderers/Editor
STRING/INTEGER/LONG/FLOAT FIELDS
Integer, Long, String and Float values are edited in a normal text field:

BOOLEAN FIELDS
Boolean values are edited using checkboxes and are represented by Yes (for TRUE) or No (for FALSE) in read-only mode:

DATE FIELDS
Date and Date/Time values are edited using a Date Picker:

COLOR FIELDS
Colors are selected using a Color Picker:

2000-2013 Tibbo Technology Inc.

AggreGate Server

647

DATA TABLE FIELDS

Data Table fields (i.e. fields whose values are actually entire data tables) are edited by a nested Data Table Editor that appears on a separate page. The page opens when you click [...] button in the cell containing the embedded Data Table:

DATA BLOCK FIELDS

Default Data Block editor allows to choose and save a file of any type from/to AggreGate Client's local file system:

Additional Renderers/Editors
DATE-ONLY EDITOR
Date-only editor allows to specify a date using Date Picker, but time specification is not allowed:

TIME-ONLY EDITOR
Time-only editor allows to specify a time in string form, but date cannot be selected:

BAR RENDERER
Bar renderer shows Integer , Long , Float and String values as percentages of maximum defined by Editor Options:

String values are converted to numbers on the best effort basis.

PERIOD EDITOR
Period editor allows to specify a time period as a certain number of selected time units:

2000-2013 Tibbo Technology Inc.

648

AggreGate Documentation

PASSWORD EDITOR
Password editor is very similar to the usual text area, but types characters are now shown:

Values cannot be copied from cells that use this editor.

REFERENCE RENDERER
Reference editor displays clickable references in blue underlined font:

Clicking on a reference initiates a server action.

TEXT AREA
Long String values can be alternatively viewed and edited in a Text Area editor:

CONTEXT AND CONTEXT MASK EDITORS

String values corresponding to Context 863 paths and context masks component. It looks like a usual text field with a button on the right:
865

are specified using a Context Mask Selector

Pressing the [...] button opens an Entity Selector

649

component to allow building the mask by pointing and clicking.

SOUND/IMAGE/FILE EDITORS
Data Block fields may contain images, sounds or generic files. Files, sound and images are inserted into the cells using a File Selector:

Images contained into the Data Table are displayed as a thumbnail (see previous screenshot). Clicking on a thumbnail opens a full-size image view.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Sounds can be played back by clicking on the Play button.

649

3.21.7.2 Context Menu

The context menu in the Data Table Editor contains several operations: Remove Value Undo Cell Changes Resets cell value to NULL (<Not set>). This operation is only applicable if current field is nullable, i.e. supports NULL values. Reset the cell value to the one it contained when the Data Table Editor was opened. If the cell didn't exist when the editor was opened (i.e. the cell belongs to a newly created row) this operation will reset its value to default (see below). Reset the cell value to the default for this column (usually defined on the server, as part of the table format description). Copy value from the selected cell to all other cells of current column. Resets all changes made to the table since it was opened. Shows format
855

Reset Cell To Default Fill Column With Cell Value Reset Table View Table Format

of current table.

When the Data Table Editor is being used to modify the value of a context variable 869 (as opposed to raw data coming from another source), the context menu within the editor contains additional actions related to this variable 895 .

3.21.7.3 Sorting and Filtering

Sorting and filtering functionality of Data Table Editor in Web Desktop is similar to the same functions in AggreGate Client's Data Table Editor 809 .

3.21.7.4 Data Export/Import

Export and import functionality of Data Table Editor in Web Desktop is similar to the same functions in AggreGate Client's Data Table Editor 810 .

3.21.7.5 Report Creation

Report creation functionality of Data Table Editor in Web Desktop is similar to the same functions in AggreGate Client's Data Table Editor 812 .

3.21.8 Entity Selector

The Entity Selector component is used to select AggreGate Server contexts and even specific fields within these. Click here tree.
868 863 ,

variables

869 ,

functions

878 ,

events

880

to check the difference between context tree visible in Entity Selector and real server context

Content can be filtered so that only certain entity types are shown for selection. Here is what the Entity Selector looks like when used to select a single context:

2000-2013 Tibbo Technology Inc.

650

AggreGate Documentation

Uses Of Entity Selector

1. The Entity Selector is used by the Select Entities
902

UI Procedure to select different contexts and their elements.

2. The Entity Selector is used to select contexts and context masks when editing context path/mask fields in a Data Table Editor 643 .

Icons Used In Entity Selector

If custom icons are defined for different contexts and their parts, these icons are shown in the Entity Selector's tree. In all other cases the following icons are used: "Closed" Context (for context nodes which are currently collapsed). "Open" Context (for context nodes which have been expanded). Variable (Property). Function (note that these are different from Actions Event. Input field (for entering values for variables, events and functions). Description and type of field are shown. Output field (used by functions). Description and type of field are shown.
892 ).

2000-2013 Tibbo Technology Inc.

AggreGate Server

651

3.21.9 Favourites
The Favourites window displays a list of Favourites
626 .

Clicking on a favourite launches a corresponding action.

Favourites component is based on Data Table Editor functionality.

651

and, thus, provides the same toolbar, context menu, and other

Context menu of the favourites table has two additional items: Configure. Starts Configure Favourite Delete. Starts Delete Favourite
905 904

action.

action.

3.21.10 Trackers
The Trackers window displays a list of Trackers
257 .

Color of the tracker indicate its state.

Trackers component is based on Data Table Editor functionality.

643

and, thus, provides the same toolbar, context menu, and other

Context menu of the trackers table has two additional items: Configure. Starts Configure Tracker Delete. Starts Delete Tracker
905 904

action.

action.

3.22 Context Reference

This chapter contains in-depth documentation of all contexts Description of every context includes the following parts: Overview Unique Actions Common Actions Context Information Context States and Icons Public Variables (Properties) General information about the context. These are actions These are actions
854 892 863

that are available in AggreGate Server.

which apply to this context only. which apply to many different contexts in AggreGate Server.

Advanced information about the context. Available context states Context variables
869 865

and their visual representation.

that may be directly used by users.

2000-2013 Tibbo Technology Inc.

652

AggreGate Documentation

Public Functions Public Events

Context functions Context events

880

878

that may be directly used by users.

that may be directly used by users.

3.22.1 Administration
This context is a system context that provides access to different data related to the overall operation of AggreGate Server. It is not shown in the visible context tree.

Advanced Information
Context Information
Context Type Context Name
864

: administration : administration
864

863

Context Description Context Path Context Mask

863

: Administration

: administration : administration
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. No access allowed. No access allowed. No access allowed. No access allowed. All operations.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions Public Events

[?

878 ]

This context has no public functions. [?

880 ]

Common Events: info (Information)

885

LOG

Fired when some message is added to a server event log Event Name Permissions:
Expiration Period: log

74

at info or higher level

79

Accessible at Administrator permission level Non-persistent 1

855

932

Records: Record Format :

2000-2013 Tibbo Technology Inc.

AggreGate Server

653

Field Name level message cause thread location

Field Type String String String String String

Notes Message level. Message text. Message cause (exception stack trace). Server thread that produced the message. File and line number of the message source.

ACTION

Fired when a system operator 108 executes an action 892 , or an action is automatically executed by one of the server components (e.g. upon schedule 266 or alert 216 ). Event Name Permissions:
Expiration Period: action

Accessible at Administrator permission level 100 days 1

855

932

Records: Record Format

Field Name user mode

:
Field Type String Integer Notes Username of system operator Execution mode. The following modes are distinguished: Normal. The execution was initiated by a human operator. Redirect . This action was started by some other action. Batch. Multiple actions were started at once. Headless . Generic automatic execution mode, i.e. when an action is executed under control of a server plugin 950 . Alert. Alert's corrective action mode. Scheduler. Scheduled job mode.

context name description

String String String

Path of context

863

that the action was executed from.

Name of the action. Description of the action.

EMAIL

Fired when AggreGate Server receives an incoming email message. Event Name Permissions:
Expiration Period: email

Accessible at Administrator permission level 100 days 1

855

932

Records: Record Format :

2000-2013 Tibbo Technology Inc.

654

AggreGate Documentation

Field Name sender subject text

Field Type String String String

Notes Sender's address. Message subject. Message text.

FAILOVER

This event is fired when failover cluster Event Name Permissions:

Expiration Period: failover

87

's slave node starts due to the failure of primary node.

Accessible at Administrator permission level 100 days 1

855

932

Records: Record Format

: none.

3.22.2 Alerts
This context
863

is a container, holding all alerts [?

651 ]

216

for a particular user.

Unique Actions

CREATE ALERT (Default Action

893

)
229

This action is used to create new alert. It allows the user to specify the basic properties configure it immediately after creation.

for the new alert, and

Action Type: Permissions:

Create

905 932

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Variable-Related Actions [?
CREATE ALERT

895 ]

This action creates a new alert with a single Variable State Trigger 217 . User is prompted to select which variable fields will be checked by the trigger expression and specify comparison operators for them.

Action Name: Non-Interactive Mode 893 : Permissions:

createForVariable Not Supported Accessible at Manager permission level

895 ] 932

Event-Related Actions [?
CREATE ALERT

This action creates new alert with a single Event Trigger 222 that raises the alert if an event of this type occurs. User is prompted to select which event fields will be checked by the trigger expression and specify comparison operators for

2000-2013 Tibbo Technology Inc.

AggreGate Server
them. If no fields were selected, any event occurrence will trigger the alert.

655

Action Name: Non-Interactive Mode 893 : Permissions:

createForEvent Not Supported Accessible at Manager permission level

932

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: alerts : alerts
864 :

863

Context Description Context Path Context Mask

863

Alerts

: users.USER_NAME.alerts : users.*.alerts
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Alert creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new alert.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as childInfo
657

variable in Alert

656

context.

Output Records: Output Format

855 : 880 ]

0
none

Public Events [?

2000-2013 Tibbo Technology Inc.

656

AggreGate Documentation

Common Events: info (Information)

885

3.22.3 Alert
This context
863

lets you access and manage a single alert

[?
651 ]

216

Unique Actions

CONFIGURE ALERT (Default Action

893 ) 229

This action is used to edit properties

of alert.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure

904

MANAGE PENDING INSTANCES

This shows a list of pending 236 alerts using Show Event Log 898 UI Procedure. This action is normally used to acknowledge 228 the pending alert instances in order to deactivate them.
Action Name: Non-Interactive Mode 893 : Permissions: pendingAlerts Not Supported Accessible at Observer permission level [?
651 ] 909 , 932

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 2 3 State Alert is enabled Alert is disabled Alert is active
234 237

Alert is escalated

Advanced Information
Context Information
Context Type Context Name
864

: alert : provided by user

864 :

863

Context Description Context Path Context Mask

863

provided by user

: users.USER_NAME.common.ALERT_NAME : users.*.alerts.*
865

865

Context Permissions [?

2000-2013 Tibbo Technology Inc.

AggreGate Server

657

Level None Observer

Description No access allowed. Receiving the alert. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Alert configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

ALERT PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name name description enabled message expressions
855

229

childInfo

1 Readable at Observer permission level :

Notes 1-50 characters 1-50 characters
932

, writable at Manager permission level

Field Type String String Boolean String Boolean

Nullable

TRIGGERS ACTIVATED BY EVENTS

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name
855

230

eventTriggers

0...unlimited Readable at Observer permission level :

Field Type String String Notes
932

, writable at Manager permission level

mask event

2000-2013 Tibbo Technology Inc.

658

AggreGate Documentation

filter level correlated correlator message

String Integer String String String

TRIGGERS ACTIVATED BY VARIABLE STATE

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name mask variable filter monitorStateChange period delay level deactivator deactivationDelay message
855

230

variableTriggers

0...unlimited Readable at Observer permission level :

Field Type String String String Boolean Long Long Integer String Long String Measured in milliseconds Measured in milliseconds Measured in milliseconds Notes
932

, writable at Manager permission level

ALERT NOTIFICATIONS

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name notifyOwner ackRequired
855

231

notifications

1 Readable at Observer permission level :

Field Type Boolean Boolean Notes
932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

AggreGate Server

659

sound mailToOwner mailRecipients additionalMailRecipien ts smsRecipients

Data Block Boolean Data Table String

Edited by Sound Editor

Data Table

ALERT ESCALATION

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name pending numberEscalation numberThreshold timeEscalation timeThreshold
855

232

escalation

1 Readable at Observer permission level :

Field Type Boolean Boolean Integer Boolean Integer Notes
932

, writable at Manager permission level

AUTOMATIC CORRECTIVE ACTIONS

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name mask action input condition runFromSource
855

232

alertActions

0...unlimited Readable at Observer permission level :

Field Type String String Data Table String Boolean Notes
932

, writable at Manager permission level

INTERACTIVE CORRECTIVE ACTIONS

See description of the variable and its fields here

233

2000-2013 Tibbo Technology Inc.

660

AggreGate Documentation

Variable Name: Records: Permissions: Record Format

Field Name mask action parameters runFromSourc e
855

interactiveActions

0...unlimited Readable at Observer permission level :

Notes
932

, writable at Manager permission level

Field Type String String Data Table Boolean

ALERT STATUS

The variable contains different run-time alert parameters, such as number of pending alert instances. The variable is shown by View Status 910 action. Variable Name: Records: Permissions: Record Format
Field Name
855

status

1 Readable at Observer permission level :

Field Type Boolean Integer Long Boolean String Notes
932

enabled pendingInstanceCount maxPendingTime escalated escalationReason

Indicates whether alert is enabled. Number of pending (non-acknowledged) alert instances. Life time of the oldest pending alert instance. Indicates whether alert is escalated. Escalation reason(s).

ACTIVE INSTANCES

This is a list of active Variable Name: Records: Permissions: Record Format

Field Name event type
855

235

and pending

236

alert instances.

activeInstances

0...unlimited Readable at Observer permission level :

Notes ID of alert event
224 932

Field Type Long Integer

(hidden field).
235

Instance type: Active

and Pending

236

2000-2013 Tibbo Technology Inc.

AggreGate Server

661

time level source message trigger cause data

Date Integer String String String String Data Table

Alert raise time. Alert level. Alert source context, i.e. context those event/state has originated the alert. Alert message. Alert trigger message. Alert cause. Alert data.

EVENT TRIGGER STATUS

Table indicating statuses of individual event triggers action. Variable Name: Records: Permissions: Record Format
Field Name trigger active details
855

222

. The variable is shown by View Status

910

eventTriggerStatus

0...unlimited Readable at Observer permission level :

Notes Zero-based trigger index in the Triggers Activated by Events table. Indicates whether trigger is active and fording alert to remain in active state. Contains details of trigger sub-status for each context matching trigger mask: Context path and description. Flag indicating whether trigger is active for the above context. Number of events registered within the last trigger Period (if trigger is activated by more than one event).
932

Field Type Integer Boolean Data Table

VARIABLE TRIGGER STATUS

Table indicating statuses of individual variable triggers action. Variable Name: Records: Permissions: Record Format
Field Name trigger active details
855

217

. The variable is shown by View Status

910

variableTriggerStatus

0...unlimited Readable at Observer permission level :

Notes Zero-based trigger index in the Triggers Activated by Variable State table. Indicates whether trigger is active and fording alert to remain in active state. Contains details of trigger sub-status for each context matching trigger mask: Context path and description.
932

Field Type Integer Boolean Data Table

2000-2013 Tibbo Technology Inc.

662

AggreGate Documentation

Flag indicating whether trigger is active for the above context. Time elapsed since the registration of activating condition (if inactive) or deactivating condition (if active). Once this time exceeds Period (or Deactivation Period), trigger will activate (deactivate). Flag indicating whether flapping is detected for the above context.

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

, contextStatusChanged (Status Changed)

890

ALERT

See description of the event and its fields here Event Name Permissions:
Expiration Period: alert

224

Accessible at Observer permission level 10 years 1

855

932

Records: Record Format

Field Name name description context entity

:
Notes

Field Type

String String String String

Alert name. Alert description. Context defining event/variable that has triggered an alert. Name of variable if alert was triggered by variable state/state change or name of event if alert was triggered by event Alert cause. Alert message. Alert trigger message. Alert data.

cause message trigger data

String String String Data Table

3.22.4 Auto Run

This context
863

is a container, holding all Auto Run

[?
651 ]

625

actions for a particular user.

Unique Actions

Add Action to Auto Run

Other unique actions:

664

(Default Action

893

INITIATE AUTO RUN

2000-2013 Tibbo Technology Inc.

AggreGate Server Launches all Auto Run actions that are defined by the children of this context exactly like they're launched on startup. Useful for testing.
Action Name: Non-Interactive Mode 893 : Permissions: autorun Not Supported Accessible at Observer permission level [?
651 ] 932

663

Common Actions
Create From Template
905

, Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions 906 , Monitor Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: autorunActions : autorun
864

863

Context Description Context Path Context Mask

863

: Auto Run

: users.USER_NAME.autorun : users.*.autorun
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Auto run action creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new Auto Run action.

Function Name: Permissions: Input Records:

create Accessible at Manager permission level

932

2000-2013 Tibbo Technology Inc.

664

AggreGate Documentation
855

Input Format

Same as format of childInfo 0

none
880 ]

665

variable in Auto Run Action

664

context.

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

3.22.4.1 Action: Add Action to Auto Run

ADD ACTION TO AUTO RUN (Default Action
893

)
895

This action adds a new action that will be automatically launched on startup. This Drag and Drop action accepts contexts of any type. Action Flow: 1) Select a context as described in Drag and Drop Actions 2) Specify
896 895

which Action will be launched.

3) A new Auto Run Action context is created with the parameters specified in (1) and (2).
Action Type: Action Icon: Action Name: Non-Interactive Mode 893 : Permissions: add Not Supported Accessible at Manager permission level
932

Drag and Drop

895

3.22.5 Auto Run Action

This context
863

lets you access and manage a single Auto Run [?

651 ]

625

action.

Unique Actions

CONFIGURE (Default Action

893

)
626

This action is used to edit Auto-Run Action properties

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure

904

LAUNCH ACTION

This action starts Auto-Run Action immediately, for testing.

Action Name: Non-Interactive Mode 893 : Permissions: launch Not Supported Accessible at Observer permission level
932

2000-2013 Tibbo Technology Inc.

AggreGate Server

665

Common Actions
Delete
Status
905

[?
908

651 ]

, Make Copy

, Replicate

909

, Edit Context Permissions

906

, Monitor Related Events

909 ,

View

910

Context States and Icons

Icon Code 0 1 State Auto Run Action is enabled Auto Run Action is disabled

Advanced Information
Context Information
Context Type Context Name
864

: autorunAction : provided by user

864

863

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.autorun.AUTORUN_ACTION_NAME : users.*.autorun.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Auto run action execution. You should also have enough permissions to access the action that the auto-run item points to.

Basic event monitoring. Status browsing. Operator Manager Engineer Administrat or Same as Observer. Auto run action configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

AUTOMATICALLY LAUNCHED ACTION PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
855

626

childInfo 1 Readable at Observer permission level

932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

666

AggreGate Documentation

Field Name name description mask action enabled executionParamete rs

Field Type String String String String Boolean Data Table

Notes 1 - 50 characters 1 - 100 characters

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

, contextStatusChanged (Status Changed)

890

3.22.6 Common Data

This context
863

is a container, holding all common tables [?

651 ] 668

668

for a particular user.

Unique Actions

Create Common Table from Variable Other unique actions:

CREATE COMMON TABLE (Default Action

893

)
264

This action is used to create new Common Table. It allows user to specify basic properties table and configure it immediately after creation.
Action Type: Permissions: Create
905 932

of a new

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: commonData : common
864

863

Context Description

: Common Data

2000-2013 Tibbo Technology Inc.

AggreGate Server Context Path Context Mask

863

667

: users.USER_NAME.common : users.*.common
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Common table creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions [?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new common table.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
:

Same as format of childInfo 0

none

669

variable in Common Data Table

668

context.

Output Records: Output Format

855 :

CREATE FROM VARIABLE

Creates new common table from a value of context variable.

Function Name: Permissions: Input Records:

Input Format
855

createFromVariable Accessible at Manager permission level

932

1
: Name Type Description

context variable

String String

Name of the context to get variable from. Name of the variable.

Output Records: Output Format

855 :

0 None
880 ]

Public Events

[?

2000-2013 Tibbo Technology Inc.

668

AggreGate Documentation

Common Events: info (Information)

885

3.22.6.1 Action: Create Common Table from Variable

This action allows to create new common table those fields and contents (data itself) will be taken from the value of context variable 869 . Action Flow: 1) Select an "accepted" context as described in Drag-and-Drop actions 2) Specify
896 895

article.

variable (for the given context) to be used to create a common table.

3) A new Common Table is created. Action Type: Action Name: Non-Interactive Mode 893 : Permissions: Drag and Drop
895

createFromVariable Not Supported Accessible at Manager permission level

932

3.22.7 Common Data Table

This context
863

lets you access and manage a single common table

[?
651 ]

260

Unique Actions

CONFIGURE COMMON TABLE

This action is used to edit the configuration

264

of a common table.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
893 )

904

EDIT DATA (Default Action

This action is used to access the contents

Action Type: Action Name:

263

of a common table.

Configure
editData [?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type
864

: commonDataTable

2000-2013 Tibbo Technology Inc.

AggreGate Server Context Name

863

669

: provided by user
864

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.common.COMMON_TABLE_NAME : users.*.common.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing. Common table contents browsing.

Operator Manager

Common table contents editing. Common table fields and properties configuration. Common table removal.

Engineer Administrat or

Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

validity (Validity)

876 ,

activeAlerts (Active Alerts)

875

TABLE PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name name description minRecords maxRecords recordPermissions
FIELDS
855

264

childInfo

1 Readable at Observer permission level : Field Type String String Integer Integer Boolean Notes
1-50 characters 1-50 characters
932

, writable at Manager permission level

0...unlimited 0...unlimited, should be greater of equal to minRecords

See description of the variable and its fields here Variable Name: Records:
fields

264

0...unlimited

2000-2013 Tibbo Technology Inc.

670

AggreGate Documentation

Permissions: Record Format

Field Name name type description default readonly nullable key selvals extselvals help editor
855

Readable at Observer permission level :

Notes

932

, writable at Manager permission level

Field Type String String String String Boolean Boolean Boolean Data Table Boolean String String

Key field, value may contain only letters, numbers and underscore.

CUSTOM PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name enabled validityExpressi on validityListeners
855

265

customProperties

1 Readable at Observer permission level :

Field Type Boolean String Notes
932

, writable at Manager permission level

Data Table

COMMON TABLE

This variable is used to access and change data of the common table. Variable Name: Records: Permissions: Record Format
TABLE STATUS
855

value

Depends on minRecords and maxRecords fields of Table Info Readable at Observer permission level : dynamic, depends on the value of Fields
932 669

669

variable.

, writable at Operator permission level variable.

2000-2013 Tibbo Technology Inc.

AggreGate Server This variable some common table status metrics. Variable Name: Records: Permissions: Record Format
Field Name modified
855

671

status

1 Readable at Observer permission level :

Notes Date/time of the last modification of common table format and/or data.
878 ] 932

, writable at Manager permission level

Field Type Date [?

Public Functions

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

3.22.8 Config
This context is a system context that provides access to AggreGate Server global configuration is not shown in the visible context tree.
53

. It

Advanced Information
Context Information
Context Type Context Name
864

: config : config
864

863

Context Description Context Path Context Mask

863

: Config

: config : config
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. No access allowed. No access allowed. No access allowed. No access allowed. All operations.

Public Variables (Properties)

[?

869 ]

This context defines one public variable per every setting group described in Global Configuration Options 53 . Please, see this section for more information about format of these variables and descriptions of their fields.

Public Functions

[?

878 ]

2000-2013 Tibbo Technology Inc.

672

AggreGate Documentation

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

3.22.9 Dashboards
This context
863

is a container, holding all dashboards

[?
651 ]

617

for a particular user.

Unique Actions

CREATE DASHBOARD (Default Action

893

)
623

This action is used for creating new dashboards. It allows user to specify basic properties new dashboard and configure it immediately after creation.
Action Type: Permissions: Create
905 932

of the

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: dashboards

863

: dashboards
864 :

Context Description Context Path Context Mask

863

Dashboards

: users.USER_NAME.dashboards : users.*.dashboards
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Dashboard creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

2000-2013 Tibbo Technology Inc.

AggreGate Server

673

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new dashboard.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
674

variable in Dashboard

673

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.10 Dashboard
This context
863

lets you access and manage a single dashboard

651 ] 893

617

Unique Actions [?

OPEN DASHBOARD (Default Action

This action opens Action Name: Permissions:
621

a dashboard. open Accessible at Observer permission level

932

CONFIGURE

This action is used to edit Dashboard properties

623

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State This dashboard is relative. This dashboard is absolute.

Advanced Information
Context Information

2000-2013 Tibbo Technology Inc.

674

AggreGate Documentation
864

Context Type Context Name

: dashboard : provided by user

864

863

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.dashboards.DASHBOARD_NAME : users.*.dashboards.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Opening the dashboard. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Dashboard configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

validity (Validity)

876 ,

activeAlerts (Active Alerts)

875

PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name
name description title type validityExpression validityListeners
855

623

childInfo 1 Readable at Observer permission level

932

, writable at Manager permission level

: Field Type
String String String Integer String Data Table

Notes
1 - 50 characters 1 - 50 characters Nullable

ELEMENTS

See description of the variable and its fields here Variable Name: Records:
elements

624

0...unlimited

2000-2013 Tibbo Technology Inc.

AggreGate Server Permissions: Record Format

Field Name
855

675

Readable at Observer permission level :

Field Type String Integer Data Table Data Table String Notes

932

, writable at Manager permission level

title type location parameters validityExpressi on

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

3.22.11 Devices
Thiscontext
863

is a container forDevices all

[?
651 ]

113

of a certain user

108

Unique Actions

ADD DEVICE (Default Action

893

This action is used to add a new Device to the system. It consists of several steps:

1. User is prompted to specify 896 Device name (i.e. name of Device Context Device Driver 129 that will communicate with Device). 2. A new Device Context
677

677

) and type (type of

is created on the server.

897

2. The user configures the connection properties for the new Device using an Edit Properties Procedure.
Action Name: Action Icon: Permissions: Accessible at Manager permission level
932

UI

create

TUTORIAL: CONFIGURE A DEVICE

This action starts configure it.

902

an Interactive Guide to help connect a new Device to AggreGate Server and

This context may provide some other unique actions, depending on the Device Driver 129 managing it. For example, if it is managed by an AggreGate Agent 130 driver, it will contain a Configure Agent action, to configure an Agent 848 application. Action Name: Action Icon: guide

2000-2013 Tibbo Technology Inc.

676

AggreGate Documentation

Non-Interactive Mode 893 : Permissions:

Not Supported Accessible at Observer permission level [?

651 ] 932

Common Actions

Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor Related Events

909 ,

Search/Filter

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: devices : devices
864

863

Context Description Context Path Context Mask

863

: Devices

: users.USER_NAME.devices : users.*.devices
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Device creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

ADD DEVICE
Creates new device account.

Function Name: Permissions: Input Records:

Input Format
855

add Accessible at Manager permission level

932

1
: Name Type Description

2000-2013 Tibbo Technology Inc.

AggreGate Server

677

driver
name

String
String

ID of device driver plugin

Name of account.

129

description
Output Records: Output Format
855 :

String

Account description.

0 None
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.12 Device
This context
863

lets you access and manage a single Device [?

651 ]

113 .

Unique Actions

Some actions of this context depend on the type of Device represented by it. AggreGate Server creates one Call Function 903 action in this context per every operation provided by Device. Actions corresponding to the Device operations are accessible at Operator permission level 932 .

EDIT DEVICE PROPERTIES

This action helps to set parameters of communications between AggreGate Server and Device. This action provides access to several groups of properties: Connection properties specific to a particular Device type (e.g host name and port number for networked devices) Generic Device Properties
123 115

Device Settings Synchronization Options

Groups of settings, operations and events that should be synchronized and made available within AggreGate Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type: Action Name: Action Icon: Permissions:

Configure setup

904

Accessible at Manager permission level

893

932

MANAGE DEVICE (Default Action

Opens all dashboards Device 677 action.
617

)
for the device. If no relevant dashboards are found, simply starts Configure

that are valid

948

Action Name: Action Icon: Non-Interactive Mode 893 : Permissions:

manage

Not Supported Accessible at Observer permission level

932

CONFIGURE DEVICE
This action is used to edit the settings of a hardware Device. New setting values are stored in the server cache during editing and written to the actual Device on next synchronization. See description of the Device Driver 129 that manages

2000-2013 Tibbo Technology Inc.

678

AggreGate Documentation

Device for more information. This context may provide some other unique actions, depending on the Device Driver 129 managing it. For example, if it is managed by an AggreGate Agent 130 driver, it will contain Device-specific actions.

Action Type:

Configure

904

CONFIGURE DEVICE DYNAMICALLY

This action has just one difference from the above: when Device settings are open for editing, and their values are modified in the server cache (e.g by an ordinary synchronization or other system operators), these changes are immediately reflected in the editor. This may greatly help to monitor state of device with frequently changed read-only settings (e.g. sensor readings). However, this editing mode is not convenient for changing Device settings, as modifications made in the editor may be overwritten by third-party modifications made to the server cache. Action Type: Action Name:

Configure

904

configureDynamically

SYNCHRONIZE
This action immediately starts synchronization between AggreGate Server and Device. Action Type: Action Name: Action Icon: Permissions: Accessible at Operator permission level
932

Call Function synchronize

903

RESET DEVICE DRIVER

This action clears Device settings cache 115 , deletes all other information about Device remembered by AggreGate Server. Then starts synchronization 126 as if AggreGate Server were just connected to AggreGate Server for the first time. Action Type: Action Name: Action Icon: Permissions Accessible at Manager permission level [?
651 ] 906 , 932

Call Function reset

903

Common Actions
Delete
905

, Replicate

909 ,

Edit Context Permissions

895 ]

Monitor Related Events

909 ,

View Status

910

Variable-Related Actions [?

EDIT SYNCHRONIZATION OPTIONS

This action allows to edit synchronization options variables "coming" from device side.
115

of a certain device-provided setting. It is available only for

Action Name: Non-Interactive Mode 893 : Permissions:

editVariableSyncOptions Not Supported Accessible at Manager permission level

932

Context States and Icons

Information about Device statuses is available here
127 .

2000-2013 Tibbo Technology Inc.

AggreGate Server

679

Icon

Code 20 21 22 23 30 31 32 33 40 41 42 43 50 51 52 53 70 71 72 73 80 81 82 83 90 91 92 93

State Offline, synchronized Online, synchronized Suspended, synchronized Connection status unknown, synchronized Offline, waiting for synchronization Online, waiting for synchronization Suspended, waiting for synchronization Connection status unknown, waiting for synchronization Offline, synchronization error Online, synchronization error Suspended, synchronization error Connection status unknown, synchronization error Offline, not synchronized or synchronization in progress Online, not synchronized or synchronization in progress Suspended, not synchronized or synchronization in progress Connection status unknown, not synchronized or synchronization in progress Offline, connecting (extended status only) Online, connecting (extended status only, reconnection has been requested by AggreGate Server) Suspended, connecting (extended status only, means that Device has been suspended during connection attempt) Connection status unknown, connecting (extended status only) Offline, reading metadata (extended status only, means that connection has been lost during metadata reading and synchronization is being interrupted) Online, reading metadata (extended status only) Suspended, reading metadata (extended status only, means that Device has been suspended during metadata reading) Connection status unknown, reading metadata (never occurs in practice) Offline, synchronizing settings (extended status only, means that connection has been lost during settings synchronization and it is being interrupted) Online, synchronizing settings (extended status only) Suspended, synchronizing settings (extended status only, means that Device has been suspended during settings synchronization) Connection status unknown, synchronizing settings (never occurs in practice)

Advanced Information
Context Information
Context Type Context Name
864

: device.DEVICE_TYPE : provided by Device Driver

864 129 129

863

Context Description

: provided by Device Driver

2000-2013 Tibbo Technology Inc.

680

AggreGate Documentation
863

Context Path Context Mask

: users.USER_NAME.devices.NAME_OF_THIS_CONTEXT : users.*.devices.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Device settings browsing. Basic event monitoring. Status browsing.

Operator

Device settings editing. Executing device operations. Device event monitoring. Explicit device synchronization requesting.

Manager

Device account properties configuration. Device removal. Device driver resetting. Viewing statistical data.

Engineer Administrat or

Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Some public variables of this context depend on the type of Device represented by it. AggreGate Server creates one public variable in this context per every Device setting. Variables corresponding to the Device settings are readable at the Observer permission level 932 and writable at Operator permission level. Common Variables: groupMembership (Group Membership)
875 ,

activeAlerts (Active Alerts)

875

GENERIC DEVICE PROPERTIES

Contains Generic Properties Variable Name: Records: Permissions: Record Format

Field Name name description type syncPeriod interruptOnError suspend
855

123

of the Device.

genericProperties

1 Readable at Observer permission level :

Field Type String String String Long Boolean Boolean Measured in milliseconds Notes
932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

AggreGate Server

681

extendedStatus dependency offlineAlert

Boolean String Boolean

STATISTICS CHANNELS

This variable allows to manage statistics channels Variable Name: Records: Permissions: Record Format
Field Name name variable properties
855

117

of this Device.

statisticsProperties

0...unlimited Readable at Observer permission level :

Field Type String String Data Table Notes Name of the channel. Name of variable the channel is based on. Properties
938 932

, writable at Manager permission level

of the channel.

DEVICE SETTINGS SYNCHRONIZATION OPTIONS

Contains Per-Setting Synchronization Options Variable Name: Records: Permissions: Record Format
Field Name name description mode updateHistoryStor ageTime syncPeriod filter master
855

115

of the Device.

settingSyncOptions

0...unlimited Readable at Observer permission level :

Field Type String String Integer Long Measured in milliseconds Notes
932

, writable at Manager permission level

Long String String

Measured in milliseconds Nullable

ASSETS

This variable allows to manage assets Variable Name: Records:

assets

113

provided by Device.

0...unlimited

2000-2013 Tibbo Technology Inc.

682

AggreGate Documentation

Permissions: Record Format

Field Name id description enabled
855

Readable at Observer permission level :

Field Type String String Boolean Notes Asset unique ID.

932

, writable at Manager permission level

Human-readable description of the asset. Flag indicating whether asset is enabled and its members (settings, operations and events) are available within AggreGate. List of nested assets. It has the same format as this variable.

children

Data Table

STATUS

Returns status of the Device. Variable Name: Records: Permissions: Record Format
Field Name
855

status

1 Readable at Observer permission level :

Field Type Notes
932

status

String

Custom textual device status. Calculated by the Status Expression 125 , which is a setting of device account. Custom device status color. Calculated by the Color Expression , which is a setting of device account. Device Driver Date/time of last synchronization between AggreGate Server and Device. Device connection status.
125

color

Color

driver syncTime

String Date

connectionStat us syncStatus syncDetails

Integer

Integer String

Device synchronization status. Current synchronization progress.

SETTINGS SYNCHRONIZATION STATUS

Returns synchronization status information Variable Name: Records: Permissions: Record Format
Field Name
855

128

for Device settings.

settingsStatus

0...unlimited Readable at Observer permission level :

Field Type Notes
932

2000-2013 Tibbo Technology Inc.

AggreGate Server

683

name setting serverTime duration

String String Date Long

Name of setting variable

869

. This field is hidden.

Setting description, i.e. description of setting variable. Date/time of last synchronization. Duration of last synchronization, i.e. time elapsed by device driver for reading/writing settings value from the hardware. Updated on Server flag that is true if setting value was updated in the server cache and new value is not yet written to the hardware. Textual description of current setting synchronization status.

updated

Boolean

syncStatus
STATISTICS

String

This variable is a view of device statistics, i.e. aggregated data collected by device's statistical channels 117 . Variable Name: Records: Permissions: Record Format
Field Name name variable statistics
855

statistics

0...unlimited Readable at Observer permission level :

Field Type String String Data Table Notes Name of the channel. Name of variable the channel is based on. Brief statistical data.
932

LOCATION

Returns current location of the device. See Tracking Device Location Variable Name: Records: Permissions: Record Format
Field Name
855

128

for details.

location

1 Readable at Observer permission level :

Field Type Notes
932

latitude longitude

Float Float

Current device latitude in floating point number format. Current device longitude in floating point number format.

VARIABLE STATUSES

Returns additional status information about Device settings. Variable Name:

variableStatuses

2000-2013 Tibbo Technology Inc.

684

AggreGate Documentation

Records: Permissions: Record Format

Field Name
855

0...unlimited Readable at Observer permission level :

Field Type Notes
932

name status comment

String String String

[?
878 ]

Name of variable Unique string ID of the status Human-readable description of status

Public Functions

Some public functions of this context depend on the type of Device represented by it. AggreGate Server creates one public function in this context per every operation provided by Device. Functions corresponding to the Device operations are accessible at Operator permission level 932 .

SYNCHRONIZE
Starts synchronization between Device and AggreGate Server. See Synchronize action
678

for details.

Function Name: Permissions: Input Records:

Input Format
855

synchronize Accessible at Operator permission level

932

0
: None

Output Records: Output Format

855 :

0
none

RESET DEVICE DRIVER

Causes AggreGate Server to purge all information about Device and start synchronization. See Reset Device Driver action 678 for details.

Function Name: Permissions: Input Records:

Input Format
855

reset Accessible at Manager permission level

932

0
: None

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Public events of this context depend on the type of Device represented by it. AggreGate Server creates one public event in this context per every type of event that may be generated by Device. Common Events: info (Information)
885

, contextStatusChanged (Status Changed)

890

2000-2013 Tibbo Technology Inc.

AggreGate Server

685

3.22.13 Drivers/Plugins Configuration

This context 863 is a container, holding all Driver/Plugin Configuration 129 at a certain level 130 .
686

contexts that are responsible for Device Driver

Unique Actions

[?

651 ]

ACTIVATE/DEACTIVATE PLUGINS (Default Action

This action is used to edit Active Plugins context. Action Type:
74

893

)
130

global configuration property. It is available only in global settings

Configure
[?
651 ]

904

Common Actions
Edit Context Permissions child contexts.

906 ,

Monitor Related Events

909 ,

Search/Filter

909 ,

various Grouped Actions

894

according to

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: "pluginsGlobalConfig" for global settings, "pluginsUserConfig" for user settings : plugins

864

863

Context Description for user settings Context Path Context Mask

863

: "Drivers/Plugins" for global settings, "Drivers/Plugins Per-account Configuration"

: "plugins" for global settings, "users.USER_NAME.plugins" for user settings : "plugins" for global settings, "users.*.plugins" for user settings
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Description

No access allowed. No access allowed. No access allowed. No access allowed. No access allowed - for global settings. All operations - for user settings.

Administrat or

All operations.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

2000-2013 Tibbo Technology Inc.

686

AggreGate Documentation

Common Events: info (Information)

885

3.22.14 Driver/Plugin Configuration

This context
863

lets you access and manage the configuration of a Device Driver

[?
651 ]

129

at certain level

130

Unique Actions

EDIT PLUGIN PROPERTIES (Default Action

893

This action is used to edit properties of the plugin. See description of plugin for the information about its properties. In contrast to a standard Configure action, the Edit Plugin Properties action prompts to reboot the server when editing is finished. Rebooting is required to activate plugin configuration changes. Action Type:

Configure
[?
651 ]

904

Common Actions
Edit Context Permissions

906 ,

Monitor Related Events

909

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: pluginConfig : plugin-dependent
864

863

Context Description

: equals to the description of plugin

Context Path 863 : "plugins.NAME_OF_THIS_CONTEXT" for global settings, "users.USER_NAME.plugins. NAME_OF_THIS_CONTEXT" for user settings Context Mask 865 : "plugins.NAME_OF_THIS_CONTEXT" for global settings, "users.*.plugins. NAME_OF_THIS_CONTEXT" for user settings

Context Permissions [?
Level None Observer Operator Manager Engineer Description

865

No access allowed. No access allowed. No access allowed. No access allowed. No access allowed - for global settings. All operations - for user settings.

Administrat or

All operations.

Public Variables (Properties)

[?

869 ]

Every device driver defines its own public variables in this context.

Public Functions

[?

878 ]

This context has no public functions.

2000-2013 Tibbo Technology Inc.

AggreGate Server

687

Public Events

[?

880 ]

Common Events: info (Information)

885

3.22.15 Event Filters

This context
863

is a container, holding all event filters

[?
651 ]

206

for a particular user.

Unique Actions

CREATE EVENT FILTER (Default Action

893

)
211

This Create 905 is used to create a new filter. It allows the user to specify basic properties new filter and configure it immediately after creation.
Action Type: Permissions: Create
905 932

for the

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Variable-Related Actions [?

895 ]

CREATE CHANGE EVENTS FILTER

This action creates an Event Filter
206

for viewing variable change history.

Action Name: Non-Interactive Mode 893 : Permissions:

filterForVariable Not Supported Accessible at Manager permission level

895 ] 932

Event-Related Actions [?
CREATE EVENT FILTER
This action creates new single-rule

211

Event Filter for viewing events of the selected type.

User is prompted to select which event fields will be checked by filter expression and specify comparison operators for them. If no fields were selected, any event occurrence will pass the filter. Action Name: Non-Interactive Mode 893 : Permissions: filterForEvent Not Supported Accessible at Manager permission level
932

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
864

: eventFilters

2000-2013 Tibbo Technology Inc.

688

AggreGate Documentation
863

Context Name

: filters
864

Context Description Context Path Context Mask

863

: Event Filters

: users.USER_NAME.filters : users.*.filters
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Filter creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new event filter.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
:

Same as format of childInfo 0

none
880 ]

689

variable in Event Filter

688

context.

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

3.22.16 Event Filter

This context
863

lets you access and manage a single event filter

[?
651 ]

206

Unique Actions
Parameterize
692

Other unique actions:

CONFIGURE FILTER

This action is used to edit the properties

211

of an event filter.

2000-2013 Tibbo Technology Inc.

AggreGate Server

689

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State This filter is a normal filter This filter is the default (auto-activated) filter of the owning user

Advanced Information
Context Information
Context Type Context Name
864

: eventFilter : provided by user

864

863

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.filters.FILTER_NAME : users.*.filters.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Filter activation. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Filter configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

FILTER PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions:
childInfo

211

1 Readable at Observer permission level

932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

690

AggreGate Documentation
855

Record Format
Field Name name description defaultFilter

:
Field Type String String Boolean Boolean Notes 1-50 characters 1-50 characters

showDataFieldNa mes showServerConte xtNames showServerEvent Names

Boolean

Boolean

FILTER RULES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name description mask event enabled level expression parameterized color
855

211

rules

0...unlimited Readable at Observer permission level :

Field Type String String String Boolean Integer String Boolean Color Notes
932

, writable at Manager permission level

PRIMARY VISIBLE FIELDS

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name
855

212

shownFields

1 Readable at Observer permission level :

Notes
932

, writable at Manager permission level

Field Type

2000-2013 Tibbo Technology Inc.

AggreGate Server

691

context event level data ack enrichments

Boolean Boolean Boolean Boolean Boolean Boolean

ADDITIONAL VISIBLE FIELDS

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name name description edescs shown
855

212

additionalFields

0...unlimited Readable at Observer permission level :

Field Type String String String Boolean Notes Read-only Read-only Read-only
932

, writable at Manager permission level

CUSTOM HIGHLIGHTING

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name mask event level expression color
855

210

customHighlighting

0...unlimited Readable at Observer permission level :

Notes
932

, writable at Manager permission level

Field Type String String Integer String Color

HISTORY BROWSER SETTINGS

See description of the variable and its fields here

213

2000-2013 Tibbo Technology Inc.

692

AggreGate Documentation

Variable Name: Records: Permissions: Record Format

Field Name limitTimeFrame timeFrame timeUnit
855

historySettings

0...unlimited Readable at Observer permission level :

Field Type Boolean Integer Integer Boolean Date Notes
932

, writable at Manager permission level

useCustomEndTimePoint customEndTimePoint

Public Functions
GET PARAMETERS

[?

878 ]

Returns an initial (non-filled) parameters table that can be filled and used for activating a parameterized filter

213 .

Function Name: Permissions: Input Records:

Input Format
855

getParameters Accessible at Observer permission level

932

1
: Name realtime Type Boolean Description Indicates whether a parameters table suitable for real-time (if true) or historical (if false) section of the Event Log should be returned.

Output Records: Output Format

855 :

0...unlimited Dynamic
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.16.1 Action: Parameterize

This action is used to parameterize Action Flow: 1. The server prepares a list of event categories that are suitable for parameterization. 2. The user is prompted to select
896 214

event filter.

event categories to be parameterized.

3. The server generates parameterization data and stores it in filter properties. 4. A parameterized filter is opened for editing using the Edit Properties
Action Name: parameterize
897

UI Procedure.

2000-2013 Tibbo Technology Inc.

AggreGate Server

693

Non-Interactive Mode 893 : Permissions:

Not Supported Accessible at Observer permission level

932

3.22.17 Events
This context is a system context that provides access to different data and operations related to event 880 management. It is not shown in the visible context tree.

Unique Actions

[?

651 ]

REMOVE EXPIRED EVENTS

Removes expired events from event history. Action Type: Action Name: Permissions: Call Function
903

removeExpired Accessible at Engineer permission level

932

Advanced Information
Context Information
Context Type Context Name
864

: events : events
864

863

Context Description Context Path Context Mask

863

: Events

: events : events
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Description

No access allowed. Accessing event history. Acknowledging events. Deleting events. Mass-deleting events. Explicitly removing expired events.

Administrat or

All operations.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

ACKNOWLEDGE EVENT
Adds a new acknowledgement
882

to the event.

2000-2013 Tibbo Technology Inc.

694

AggreGate Documentation
acknowledge Accessible at Operator permission level
932

Function Name: Permissions: Input Records:

Input Format
855

1
: Name Type Description

context name id ack author

String String Long String String

Context of the event to acknowledge. Name of the event to acknowledge. ID of event to acknowledge. Acknowledgement text. Acknowledgement author (optional field, username of the active user is used if author was not specified). This is just a plain text field; it is not actually linked to a system user, and thus should not be considered auditable (always accurate).

Output Records: Output Format

855 :

0 None

ENRICH EVENT
Adds a new enrichment
883

to the event.

Function Name: Permissions: Input Records:

Input Format
855

enrich Accessible at Engineer permission level

932

1
: Name Type Description

context name id enrichmentN ame enrichmentV alue

String String Long String

Context of the event to acknowledge. Name of the event to acknowledge. ID of event to acknowledge. Enrichment name. It can contain only English letters, numbers, and underscores. Enrichment value string. Numbers, dates and other types of enrichments should be encoded into strings using any method preferred by tools that are supposed to analyze this enrichment later.

String

Output Records: Output Format

855 :

0 None

DELETE EVENT
Permanently deletes event from event history.

2000-2013 Tibbo Technology Inc.

AggreGate Server

695

Function Name: Permissions: Input Records:

Input Format
855

delete Accessible at Manager permission level

932

0...unlimited
: Name Type Description

context event id
Output Records: Output Format
855 :

String String Long

Path of context event was occurred in. Name of event. Event ID.

0 None

REMOVE EXPIRED EVENTS

Removes all expired events from event history. Note, that normally all expired events are removed automatically by AggreGate Server by periodic execution of this function.

Function Name: Permissions: Input Records:

Input Format
855

removeExpired Accessible at Engineer permission level

932

0
:

None 0 None

Output Records: Output Format

855 :

GET EVENT HISTORY

Returns history of a specified event. See View Event History
728

action for more information.

Function Name: Permissions: Input Records:

Input Format
855

get Accessible at Observer permission level

932

0
: Name Type Description

mask

String

Context mask defining a number of context to select events from. Event type name. Text of expression 911 to use for event filtering or NULL to disable filtering.
Timestamp used to select only events which occurred after a certain date. If it is NULL, all oldest events will be selected. Timestamp used to select only events which occurred before a certain date. If it is NULL, all recent events will be selected.

event filter

String String

fromDate

Date

toDate

Date

2000-2013 Tibbo Technology Inc.

696

AggreGate Documentation

dataAsTable

Boolean

This is a hidden field. If false (default), each event data table's field is put to a separate field of function output. If true, each event's data table is put to a single field (DataTable-type) or function output.

sortField

String

This is a hidden field. It defines event sort order: context - sort by source context path name - sort by event type name creationtime - sort by creation time expirationtime - sort by expiration time level - sort by level count - sort by duplicate events count

sortAscendin g limit

Boolean

This is a hidden field. It defines whether ascending sort order should be used. This is a hidden field. It defines maximum number of events to load or NULL to load all available events. This option is not compatible with filtering.

Integer

Output Records: Output Format

855 :

0...unlimited

Dynamic:
Name Type Description

eId eCreationtim e eExpirationti me eContext eName eLevel eCount

Long Date

Event ID (hidden field). Event creation time.

Date

Event expiration time.

String String Integer Integer

Event source context path. Event type name. Event level. Number of events (if similar events were suppressed by deduplication. Event acknowledgements

eAcknowledg ements eData

Data Table Data Table

Event-specific data. This field will be included into output only if dataAsTable input setting is enabled. Remaining fields will be added only if dataAsTable input setting is disabled. Number, names, types and other parameters of fields will match ones declared in event definition.

2000-2013 Tibbo Technology Inc.

AggreGate Server

697

DELETE EVENTS
Deletes events from event history.

Function Name: Permissions: Input Records:

Input Format
855

massDelete Accessible at Engineer permission level

932

1
: Name Type Description

mask

String

Context mask defining a number of context to delete events from. Event name. Nullable. If specified, only events occurred after startDate are deleted. Nullable. If specified, only events occurred before endDate are deleted.

event startDate

String Date

endDate

Date

Output Records: Output Format

855 :

0 None
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.18 Favourites
This context
863

is a container, holding all favourites

[?
651 ]

626

for a particular user.

Unique Actions
Add to Favourites

698

(Default Action
[?
651 ]

893

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: favourites : favourites
864

863

Context Description Context Path Context Mask

863

: Favourites

: users.USER_NAME.favourites : users.*.favourites

865

2000-2013 Tibbo Technology Inc.

698

AggreGate Documentation
865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Favourite creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new favourite.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
:

Same as format of childInfo 0

None
880 ]

700

variable in Favourite

699

context.

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

3.22.18.1 Action: Add Action to Favourites

This action adds a Favourite to the Favourites table. It is implemented as a Drag-and-Drop action 895 that accepts contexts of any type. When you drag a System Tree node and drop it over the Favourites node, a new Favourite is created for whatever was dragged. Newly created favourites may be launched by running the default "Launch Action" in the new Favourite context (for example double clicking on it in the Client 776 ). Action Flow: 1. Select a context as described in Drag-and-Drop actions 895 article. For example, in the Drag-andDrop selection method, click a System Tree node you wish to apply this action to. Keep the left mouse button pressed and drag it onto the Favourites node. 2. At this point, you will have to specify the Favourite is invoked.
896

which Action (for the given context) will be executed when

3. Once you've specified the action, a new Favourite is created.

Action Type:

Drag and Drop

895

2000-2013 Tibbo Technology Inc.

AggreGate Server

699

Action Icon: Action Name: Non-Interactive Mode 893 : Permissions: add Not Supported Accessible at Manager permission level
932

3.22.19 Favourite
This context
863

lets you access and manage a single favourite

[?
651 ]

626

action.

Unique Actions

LAUNCH ACTION (Default Action

893

This action launches the target of the favourite.

Action Name: Non-Interactive Mode 893 : Permissions: launch Not Supported Accessible at Observer permission level
932

CONFIGURE

This action is used to edit Favourite properties

627

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State Favourite is enabled Favourite is disabled

Advanced Information
Context Information
Context Type
Context Name
864

: favourite

863

: provided by user
864 :

Context Description Context Path Context Mask

863

provided by user

: users.USER_NAME.favourites.FAVOURITE_NAME : users.*.favourites.*

865

2000-2013 Tibbo Technology Inc.

700

AggreGate Documentation
865

Context Permissions [?
Level None Observer Description

No access allowed. Access to favourite. You should also have enough permissions to access the action that the favourite points to.

Basic event monitoring. Status browsing. Operator Manager Engineer Administrat or Same as Observer. Favourite configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

FAVOURITE ACTION PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name
name description mask action enabled executionParameters
855

627

childInfo 1 Readable at Observer permission level

932

, writable at Manager permission level

: Field Type
String String String String Boolean Data Table

Notes
1 - 50 characters 1 - 100 characters

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

2000-2013 Tibbo Technology Inc.

AggreGate Server

701

3.22.20 Groups
This context
863

is a container, holding all groups

[?
651 ]

248

of a particular type

249

Unique Actions

CREATE GROUP (Default Action

893

)
253

This action is used for creating new groups. It allows the user to specify basic properties group and configure it immediately after creation.
Action Type: Permissions: Create
905 932

of a new

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
864

: groups
108

Context Name 863 : name of primary container context + "_groups" (e.g. "user_groups" for user groups); "devgroups" for container of Device 113 groups Context Description
864

: "User Groups" for container user

108

groups, etc.

Context Path 863 : "users.USER_NAME.container_groups" where container is the primary container name (e.g. "users.admin.user_groups" for user 108 groups container); "users.USER_NAME.devgroups" for container of Device 113 groups Context Mask 865 : "users.*.container_groups" where container is the primary container name (e.g. "users.*.user_groups" for all user 108 groups containers); "users.*.devgroups" for container of Device groups
113

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

865

No access allowed. Basic event monitoring. Same as Observer. Group creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

2000-2013 Tibbo Technology Inc.

702

AggreGate Documentation

Common Functions: delete (Delete)

880

CREATE
Creates new group.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
:

Same as format of childInfo 0

none
880 ]

704

variable in Group

702

context.

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

3.22.21 Group
This context
863

lets you access and manage a single group

[?
651 ]

248

Unique Actions

Create Group Status Tracker Other unique actions:

707

CONFIGURE GROUP (Default Action

893

)
253

This action is used to edit Group properties

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure

904

CREATE IN GROUP
This action is used to create new object and add it to group immediately after creation. Object type matches group type, e.g. Alert for Alert Group, etc. Action flow: 1. Start Create Alert Group.
905

action from "container" context matching the group, e.g. Admin

109 's

Alerts context for Admin's

2. Add newly created object to the group. Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not supported Accessible at Observer permission level
932

create

REPLICATE OF ADD TO GROUP

This is a Drag-and-Drop action 895 that accepts contexts of the same type as group members, i.e. User contexts 759 for the User groups etc. The Logic of this action is completely different in two cases:

2000-2013 Tibbo Technology Inc.

AggreGate Server When accepted context is not member of this group When accepted context is already member of the group

703

In the first case accepted context is just added to the list of group members. No interaction of the used it performed in this case. In the second case this action behaves as the Replicate member's configuration to all other group members.
909

action, i.e. performs replication of a group

This action is very convenient to add new members to the group. New members are added by just dragging them and dropping on the Group context.
Action Type: Action Name: Non-Interactive Mode 893 : Permissions:

Drag and Drop

replicateOrAdd Not Supported

895

Accessible at Operator permission level

932

CONVERT DYNAMIC GROUP TO STATIC

This action adds every child of a dynamic 250 group as a static child to the same group so that it can be later removed individually. When done, group's validity expression is emptied so that it has no more dynamic children. It's easy to create a group of objects matching specific criteria: Create new group and specify its validity expression to auto-add objects that match it; Convert group to static; Add or remove certain objects to fine-tune your group.

Action Name: Non-Interactive Mode 893 : Permissions:

convertToStatic Not Supported Accessible at Engineer permission level [?

651 ] 906 , 932

Common Actions
Delete
905

, Edit Context Permissions

Monitor Related Events

909 ,

Search/Filter

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State Normal group Group that performs automatic replication
252

Advanced Information
Context Information
Context Type Context Name
864

: group : provided by user

864

863

Context Description

: provided by user
108

Context Path 863 : "usergroups.GROUP_NAME" for user GROUP_NAME" for Device 113 group Context Mask
865

group, "users.USER_NAME.devgroups.
113

: "usergroups.*" for user

108

groups, "users.*.devgroups.*" for Device

groups

2000-2013 Tibbo Technology Inc.

704

AggreGate Documentation
865

Context Permissions [?
Level None Observer Description

No access allowed. Group member list browsing. Access to group member list does not mean access to the group members themselves. See Group Member Permissions 934 for details. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Group member management. Group configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

validity (Validity)

876 ,

activeAlerts (Active Alerts)

875

GROUP PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name
name description autoReplication hideMembers validityExpression validityListeners
855

253

childInfo 1 Readable at Observer permission level level

932

, writable at Manager permission

: Field Type
String String Boolean Boolean String Data Table

Notes
1 - 50 characters 1 - 50 characters

GROUP STATUS

See description of the variable and its fields here Variable Name: Records: Permissions: groupStatus 1

253

Readable at Observer permission level level

932

, writable at Manager permission

2000-2013 Tibbo Technology Inc.

AggreGate Server Record Format Field Name

enabled variable expression statuses
855

705

: Field Type
Boolean String String Data Table

Notes

REPLICATION OPTIONS

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name variable description replicate useMaster master
STATIC MEMBERS
855

254

replication 0...unlimited Readable at Observer permission level level

932

, writable at Manager permission

: Field Type String String Boolean Boolean String Notes

This variable lists group members that were manually added by devices operators. The list includes only members that are accessible to the party that reads this variable. Note that certain static group members can also appear in the Validity list (e.g. match dynamic group expression).
250 's

validity

Variable Name: Records: Permissions: Record Format Field Name context

MEMBER STATUS
855

staticMembers

0...unlimited Readable at None permission level : Field Type String Notes

The path of static member context.
932

This variable lists individual status of all group members. Those individual statuses are used to calculate aggregated group status 250 .

2000-2013 Tibbo Technology Inc.

706

AggreGate Documentation

Variable Name: Records: Permissions: Record Format Field Name

context status
855

memberStatus 0...unlimited Readable at Observer permission level

932

: Field Type
String String

Notes
Member context path. Member status string.

Public Functions
ADD MEMBER

[?

878 ]

Adds new member context to the group.

Function Name: Permissions: Input Records:

Input Format
855

add Accessible at Operator permission level

932

1
: Name context Type String Description Path of context to add.

Output Records: Output Format

855 :

0 None

REMOVE MEMBER
Removes member context from the group.

Function Name: Permissions: Input Records:

Input Format
855

remove Accessible at Operator permission level

932

1
: Name context Type String Description Path of context to remove.

Output Records: Output Format

855 :

0 None

CALL FUNCTION FOR GROUP MEMBERS

Calls the same context function from every member context.

Function Name: Permissions: Input Records:

call Accessible at Operator permission level

932

2000-2013 Tibbo Technology Inc.

AggreGate Server
Input Format
855

707

: Name Type Description

function parameters

String String

Name of function to call. Function input parameters.

Output Records: Output Format

855 :

0...unlimited Name Type Description

context successful error

String Boolean String

Context path. Indicates whither execution was successful. Text of error message, if execution has failed. Function output, if execution was successful.

return

Data Table

Public Events

[?

880 ]

Common Events: info (Information)

885

, contextStatusChanged (Status Changed)

890

3.22.21.1 Action: Create Group Status Tracker

This action lets you create a tracker 257 that will indicate the group's status, i.e. the aggregated status of all group members. Group status is calculated using two parameters: Expression and Initial Value. Group status Expression is evaluated for every group member context. It should involve two references: {env/previous}, a reference that refers to the result of previous calculation A reference to the data in current context, such as {.:status$connectionStatus} During the first evaluation, {env/previous} will resolve to the Initial Value. Action Flow: 1. The user is prompted 896 to enter the expression to be calculated for every group member, and an initial value for a group status. 2. Group status expression is constructed based on the above data and a new tracker is created. 3. A notification
Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Manager permission level
932 899

indicating the name of the new tracker is shown.

createStatusTracker

2000-2013 Tibbo Technology Inc.

708

AggreGate Documentation

3.22.22 Models
This context
863

is a container, holding all models [?

651 ]

303

for a particular user.

Unique Actions

CREATE (Default Action

893

)
307

This action is used to create new model. It allows the user to specify the basic properties configure it immediately after creation.

for the new model and

Action Type: Permissions:

Create

905 932

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: models : models
864 :

863

Context Description Context Path Context Mask

863

Models

: users.USER_NAME.models : users.*.models
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Model creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new model.

Function Name:

create

2000-2013 Tibbo Technology Inc.

AggreGate Server Permissions: Input Records:

Input Format
855

709

Accessible at Manager permission level

932

1
:

Same as format of childInfo 0

none
880 ]

710

variable in Model

709

context.

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

3.22.23 Model
This context
863

lets you access and manage a single model

[?
651 ]

303

Unique Actions
CONFIGURE

This Configure

904

action is used to edit the properties

307

of the model.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State This model is relative. This model is absolute.

Advanced Information
Context Information
Context Type Context Name
864

: model : provided by user

864 :

863

Context Description Context Path Context Mask

863

provided by user

: users.USER_NAME.models.MODEL_NAME : users.*.models.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Model configuration browsing. Basic event monitoring.

2000-2013 Tibbo Technology Inc.

710

AggreGate Documentation

Status browsing. Operator Manager Engineer Administrat or Same as Observer. Model configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Absolute 304 models add variables they declare to their own context. Thus, one variable is created per each record in the model's Variables 308 table. Common Variables: groupMembership (Group Membership)
875 ,

validity (Validity)

876 ,

activeAlerts (Active Alerts)

875

PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name name description template type validityExpressio n validityListeners
855

307

childInfo

1 Readable at Observer permission level :

Field Type String String String String String Notes 1 - 50 characters 1 - 50 characters
932

, writable at Manager permission level

Data Table

VARIABLES
This variable contains definitions of model variables
308 .

Variable Name: Records: Permissions: Record Format Field Name

name description format
855

modelVariables

0...unlimited Readable at Observer permission level :

Field Type String String Data Table Notes
932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

AggreGate Server

711

writable help group readPermissions writePermissions updateHistorySto rageTime

Boolean String String String String Long Nullable Nullable

FUNCTIONS
This variable contains definitions of model functions
309 .

Variable Name: Records: Permissions: Record Format Field Name

name description inputformat outputformat help group permissions implementation plugin
855

modelFunctions

0...unlimited Readable at Observer permission level :

Field Type String String Data Table Data Table String String String String String Nullable Nullable Nullable Notes
932

, writable at Manager permission level

EVENTS
This variable contains definitions of model events
309 .

Variable Name: Records: Permissions: Record Format Field Name

name description
855

modelEvents

0...unlimited Readable at Observer permission level :

Field Type String String Notes
932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

712

AggreGate Documentation

format help level group permissions firePermissions

Data Table String Integer String String String Nullable Nullable

RULE SETS
This variable contains model's rule sets
305 .

Variable Name: Records: Permissions: Record Format Field Name

name description type rules
855

ruleSets

0...unlimited Readable at Observer permission level :

Field Type String String Integer Data Table Notes
932

, writable at Manager permission level

BINDINGS
This variable contains model bindings
311 .

Variable Name: Records: Permissions: Record Format Field Name

target expression activator condition onstartup onevent periodically period
855

bindings

0...unlimited Readable at Observer permission level :

Field Type String String String String Boolean Boolean Boolean Long Notes
932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

AggreGate Server

713

THREAD POOL STATISTICS

Returns statistical information about model's threa pool. Variable Name: Records: Permissions: Record Format
Field Name
855

threadPoolStatus

0...unlimited Readable at Observer permission level :

Field Type Notes
932

activeCount completedCoun t totalCount coreSize largestSize maximumSize queueLength

STATISTICS

Integer Long

Number of active tasks. Number of completed tasks.

Long Integer Integer Integer Integer

Total number of tasks. Pool core size. Pool largest (peak) size. Pool maximum allowed size. Task queue length.

This variable is a view of model variable statistics, i.e. aggregated data collected by model variables' statistical channels 309 . Variable Name: Records: Permissions: Record Format
Field Name name variable statistics
855

statistics

0...unlimited Readable at Observer permission level :

Field Type String String Data Table Notes Name of the channel. Name of variable the channel is based on. Brief statistical data.
932

Public Functions

[?

878 ]

Absolute 304 models add functions they declare to their own context. Thus, one function is created per each record in the model's Functions 309 table. Additionally one function is created per each record in model's Rule Sets 310 table.

Public Events

[?

880 ]

Absolute 304 models add events they declare to their own context. Thus, one event is created per each record in the model's Events 309 table.

2000-2013 Tibbo Technology Inc.

714

AggreGate Documentation

Common Events: info (Information)

885

3.22.24 Queries
This context
863

is a container, holding all queries

[?
651 ] 716

271

for a particular user.

Unique Actions

Execute Native Query Other unique actions:

CREATE QUERY (Default Action

893

)
278

This action is used for creating new queries. It allows user to specify basic properties query and configure it immediately after creation.
Action Type: Permissions: Create
905 932

of the new

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Variable-Related Actions [?
CREATE QUERY

895 ]

This action creates a new query that selects: Value of this variable from multiple contexts, or History of this variable, or Statistics
936

of this variable

Action workflow: 1. Select what the query should be based on: current values of the variable, variable history, or variable statistics. This will form the FROM clause of the query. 2. If variable history was selected at step 1, select a time frame to extract the historical data for: all time or specific time frame. 3. If specific time frame was selected at step 2, define a range of historical/statistical data to include in the query results. 4. If variable statistics was selected at step 1, select a statistical channel those data will be included in the query results. The query creation will be finished at this point. 5. Select a resource or mask of resources that the query should select data from. This resource/mask will be included in the FROM clause. 6. If a single-row variable initially selected to build the query, choose between building a query over a single variable or multiple variables. The variables will be listed in the FROM clause of the query. 7. If multiple variables were selected at step 6, select some other single-row variables to include in the query results. 8. Select what variable fields to include in the query results: all fields of selected variables or selected fields only. The fields will be listed in the SELECT clause of the query. 9. If selected fields option was chosen at step 8, check one or more fields to include in the query results. 10.Add one or more conditions to the WHERE clause of the query. Each condition is defined by a variable, a comparison operation, a string-encoded value to compare the variable to, and an OR/AND operation applied to the other conditions. 11.The query is created at this point and its configuration is opened for editing.

2000-2013 Tibbo Technology Inc.

AggreGate Server

715

Action Name: Non-Interactive Mode 893 : Permissions:

queryForVariable Not Supported Accessible at Manager permission level

932

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: queries

863

: queries
864 :

Context Description Context Path Context Mask

863

Queries

: users.USER_NAME.queries : users.*.queries
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Query creation, export and import. Same as Manager. Native query execution.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new query.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
717

variable in Query

716

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

2000-2013 Tibbo Technology Inc.

716

AggreGate Documentation

3.22.24.1 Action: Execute Native Query

This Call Function 903 action is used to execute a native SQL query over a AggreGate Server database Execute Native Query 740 function from the root context.
80

. It calls the

This query affects the underlying AggreGate Server database directly, bypassing the AggreGate Server Query Language 271 engine and AggreGate Server permission checking 931 . Incorrect queries may corrupt the data and make AggreGate Server installation non-operative.
Action Type: Action Name: Permissions: Call Function
903

executeNativeQuery Accessible at Administrator permission level

932

3.22.25 Query
This context
863

lets you access and manage a single query

651 ] 893

271

Unique Actions [?
Execute Query
718

(Default Action

Other unique actions:

DEBUG QUERY

This action is used to execute query in debug mode 278 . Its has only one difference from the Execute Query 718 action: if query produces any debug output, debug report is shown to the user immediately after query execution using Edit Data 896 UI Procedure in read-only mode. When user closes debug report, query result is shown.
Action Name: Non-Interactive Mode 893 : Permissions: debug Not Supported Accessible at Observer permission level
932

CONFIGURE

This action is used to edit Query properties

278

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information

2000-2013 Tibbo Technology Inc.

AggreGate Server

717

Context Information
Context Type Context Name
864

: query : provided by user

864

863

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.queries.QUERY_NAME : users.*.queries.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Query execution. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Query configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

QUERY PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name
name description query parameterized fields disableEditableResult
855

278

childInfo 1 Readable at Observer permission level

932

, writable at Manager permission level

: Field Type
String String String Boolean Data Table Boolean

Notes
1 - 50 characters 1 - 50 characters

QUERY RESULTS

This variable is used to execute query and get its result. Variable Name: data

2000-2013 Tibbo Technology Inc.

718

AggreGate Documentation

Records: Permissions: Record Format 855 :

0...unlimited Readable/writable at Observer permission level Dynamic

932

Public Functions
EXECUTE QUERY

[?

878 ]

Executes the query and returns its result set.

Function Name: Permissions: Input Records:

Input Format
855

execute Accessible at None permission level

932

1
: Dynamic, may change when query properties
278

are edited.

If the query is not parameterized 282 , the input format is empty, i.e. it's possible to execute a query without specifying any input. If the query is parameterized, the input format of this function matches format defined in query parameterizer. Output Records: Output Format
855 :

0...unlimited
Dynamic
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.25.1 Action: Execute Query

This action executes the query and shows its result to the user. Its flow differs for simple and parameterized 282 queries. For simple (non-parameterized) query: 1. Query is executed 2. Query result is shown to the user using Edit Properties 897 UI Procedure. If query result contains some editable fields, user can edit them and save changes. All changed data will be saved back to the contexts 863 from which it originally came. For parameterized query: 1. User is prompted
896

to enter query parameters

2. Parameters entered on step 1 are used to produce final query text according to the text of parameterized query 3. Query is executed 4. Query result is shown to the user using Edit Properties 897 UI Procedure. If query result contains some editable fields, user can edit them and save changes. All changed data will be saved back to the contexts 863 from which it originally came.
If query is Parameterized or Disable Editable Result flag is enabled in query properties is shown using Edit Data 896 UI Procedure instead of Edit Properties.
278 ,

query result

If some errors occur during query execution or parameterization, they are shown to the user using Show Error 899 UI Procedure.

2000-2013 Tibbo Technology Inc.

AggreGate Server

719

Action Name: Non-Interactive Mode 893 : Permissions: Execution Parameters

896

execute Not Supported Accessible at Observer permission level Query Result Window Location :
955 932

3.22.26 Reports
This context
863

is a container, holding all reports [?

651 ]

241

for a particular user.

Unique Actions

CREATE NEW REPORT (Default Action

893

This action is used for creating new reports. Action Flow: 1. Specify 2. Set up
896

basic properties

245

of a new report.

896

different properties of report template 1325 .

721

3. Report template is generated 1325 by the server and a new report context 4. Decide
901

is created.

whether you want to modify report template right now.

826

5. [Optional] Edit report template in Report Editor .

Action Icon: Action Name: Non-Interactive Mode 893 : Permissions: create Not Supported

. This step is supported only in AggreGate Client

776

Accessible at Manager permission level [?

651 ]

932

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Variable-Related Actions [?
CREATE REPORT

895 ]

This action creates new report that displays value of the variable. Action workflow: Select what the report should be based on: variable history table or current value of the tabular variable. Create a new report with a Source Data Expression
241

pointing to the variable value or its history.

Prompt user to specify report template properties 1325 . Obtain the variable's value and generate
1325

a Report Template

242

according to its format.

Action Name: Non-Interactive

reportForVariable Not Supported

2000-2013 Tibbo Technology Inc.

720

AggreGate Documentation

Mode

893

: Accessible at Manager permission level

895 ] 932

Permissions:

Event-Related Actions [?
CREATE REPORT

This action creates new report that displays event history. Action workflow: Prompt user to specify Period and Maximum Event Count . Prompt user to specify report template properties 1325 . Create a new report with a Source Data Expression context.
241

pointing to the Get Event History

1325

695

function of Events according to its format.

Obtain the a small part ("sample") of event history and generate

a Report Template

242

Action Name: Non-Interactive Mode 893 : Permissions:

reportForEvent Not Supported Accessible at Manager permission level

932

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: reports

863

: reports
864 :

Context Description Context Path Context Mask

863

Reports

: users.USER_NAME.reports : users.*.reports
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Report creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

2000-2013 Tibbo Technology Inc.

AggreGate Server

721

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new report.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
723

variable in Report

721

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.27 Report
This context
863

lets you access and manage a single report

[?
651 ]

241

Unique Actions

Preview Source Data Schedule Report

725

725

Send Report by E-mail

Other unique actions:

725

SHOW REPORT (Default Action

893

This action is used to build and view the report. Action Flow: 1. [Optional] User is prompted to enter report parameters using an Edit Data 2. A report template is compiled on the server and filled with data. 3. The report is shown to the user using Show Report
Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Execution Parameters
896 900 896

UI Procedure.

UI Procedure.

show

Not Supported Accessible at Observer permission level Report Window Location

955 932

CONFIGURE

This action is used to edit Report properties

245

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

2000-2013 Tibbo Technology Inc.

722

AggreGate Documentation

Action Type:

Configure

904

EDIT REPORT TEMPLATE

This action is supported in AggreGate Client the report template.

Action Name: Non-Interactive Mode 893 : Permissions: editTemplate Not Supported

776

only. Is starts the Report Editor

826

and allows to edit

Accessible at Manager permission level

932

VIEW HISTORY

This action is used to see all versions database.

Action Type: Action Name: Permissions: Configure
904

723

of this report that were filled earlier and saved in the

viewHistory Accessible at Manager permission level

932

EXPORT TO SERVER FILE

This Call Function Action 903 saves filled report to a file on AggreGate Server machine. Report is filled with data at the moment of execution of this action and, thus, always contains up-to-date data. Reports may be saved in one of the following formats: Printable Document Format (PDF) Microsoft Excel (XLS) Rich Text Format (RTF) Character Separated Values (CSV) Extensible Markup Language (XML) Open Office (ODT) Action Type: Action Name: Permissions: Call Function export Accessible at Manager permission level [?
651 ] 909 , 932 903

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State This report is relative. This report is absolute.

Advanced Information
Context Information
Context Type Context Name
864

: report : pre-defined, different for every report

863

2000-2013 Tibbo Technology Inc.

AggreGate Server Context Description Context Path Context Mask

863 864

723

: pre-defined, different for every report

: users.USER_NAME.reports.REPORT_NAME : users.*.reports.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Report launching. Report source data viewing. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Report configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

validity (Validity)

876 ,

activeAlerts (Active Alerts)

875

REPORT PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name
name description expression template type validityExpression validityListeners defaultContext
855

245

childInfo 1 Readable at Observer permission level

932

, writable at Manager permission level

: Field Type
String String String String Integer String Data Table String

Notes
1 - 50 characters 1 - 100 characters

REPORT HISTORY

Provides access to the instances of this report that were filled earlier and saved in the database. A new record in this table is created every time the report is filled, but only when a Save History 245 flag of the report is enabled.

2000-2013 Tibbo Technology Inc.

724

AggreGate Documentation

System operators can delete historical reports by simply removing necessary records from this table and saving changes to the server. Variable Name: Records: Permissions: Record Format Field Name
date user report
855

history 0...unlimited Readable at Observer permission level

932

, writable at Manager permission level

: Field Type
Date String Data Block

Notes
Report creation date. System user
108

who has filled the report.

814 .

Report data. Can be opened in the Report Viewer

ADDITIONAL REPORT PARAMETERS

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name parameter value
855

245

parameters 0...unlimited Readable at Observer permission level level

932

, writable at Manager permission

: Field Type String String

[?
878 ]

Notes

Public Functions

EXPORT TO SERVER FILE

Saves report to a file located on AggreGate Server. The file will be located in AggreGate Server installation directory unless specified path is absolute.

Function Name: Permissions: Input Records:

Input Format
855

export Accessible at Manager permission level

932

1
: Name Type String Description

file

Path of resulting file (absolute or relative, with or without extension). Report format.

format
Output Records: Output Format
855 :

Integer

0 None

2000-2013 Tibbo Technology Inc.

AggreGate Server

725

SEND REPORT BY EMAIL

Fills report with data and sends it by email
725 .

Function Name: Permissions: Input Records:

Input Format
855

sendByMail Accessible at Manager permission level

932

1
: Name Type String Description

recipients format
Output Records: Output Format
855 :

Comma-separated list of email recipients. Report format.

Integer

0 None
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.27.1 Action: Preview Source Data

This action fetches data referenced by Source Data Expression 241 and presents this data to the user using Edit Data UI Procedure. It is very useful for debugging a report because it shows the raw data used to fill in report template.
896

Action Name: Non-Interactive Mode 893 : Permissions:

viewData Not Supported Accessible at Observer permission level

932

3.22.27.2 Action: Schedule Report

This Call Function Action defined format.
903

creates a new scheduled job

725

266

for periodic sending of filled report by e-mail in a user-

See Send Report by E-mail Action Name: Action Icon: Permissions:

for details.

schedule

Accessible at Manager permission level

932

3.22.27.3 Action: Send Report by E-mail

This Call Function Action 903 sends report by e-mail to the recipients specified as a comma-separated list of e-mail addresses. Report is filled with data at the moment of execution of this action and, thus, always contains up-to-date data. Repots may be sent in one of the following formats: Printable Document Format (PDF)

2000-2013 Tibbo Technology Inc.

726

AggreGate Documentation

Microsoft Excel (XLS) Rich Text Format (RTF) Character Separated Values (CSV) Extensible Markup Language (XML) Open Office (ODT) It may be very convenient to schedule report by e-mail.
266

this action to enable periodic (e.g. daily or weekly) sending of

Action Type: Action Name: Permissions:

Call Function sendByMail

903

Accessible at Manager permission level

932

3.22.28 Root Context

This context server.
863

is the root of AggreGate Server's context tree. It has some basic actions

892

that are used to control the

Unique Actions

[?

651 ]

CONFIGURE SERVER

This action is used to view or edit the global configuration options 53 of AggreGate Server. Its only difference from a standard Configure 904 action is that prompts 901 the user to reboot the server once the new settings are saved (a reboot is needed to apply the changes). Additional information about server configuration may be found here 51 .
Action Type: Action Name: Action Icon: Permissions: Accessible at Administrator permission level
932

Configure

904

configureServer

VIEW SERVER INFORMATION

This action shows 897 information about AggreGate Server runtime environment. It may be useful for debugging and troubleshooting the server as well as resolving some performance issues. There are two sections available: Server Status. Different information about server real-time operational status, such as startup time or memory usage. Context Statistics. List of all contexts and the number of variables, functions, events and actions in every context. License Information . Information about AggreGate license. Active Plugins. Information about plugins
950

being currently used by AggreGate Server.

Active Client Connections. The list of currently connected clients including remote address and connection type/ time. Threads . List of server threads along with their state and stack trace. This information is may be requested by AggreGate support team. Thread Pool Statistics. The list of active and completed tasks for every server thread pool. This information may be helpful for analyzing server CPU load. Server Environment. Information about Java Runtime environment and machine/operating system it's running on. Configure
904

Action Type:

(read-only mode)

2000-2013 Tibbo Technology Inc.

AggreGate Server

727

Action Name: Action Icon: Permissions:

viewServerInfo

Accessible at Administrator permission level

932

CREATE RESOURCES
This action is used to create pre-build resources (alerts, reports, widgets, etc.) that are included in AggreGate distribution. See Managing Pre-Built Resources 107 for details.

Action Name: Action Icon: Permissions:

createResources

Accessible at Manager permission level

932

DELETE RESOURCES
This action is used to delete pre-build resources (alerts, reports, widgets, etc.) that are included in AggreGate distribution. See Managing Pre-Built Resources 107 for details.

Action Name: Action Icon: Permissions:

deleteResources

Accessible at Manager permission level

932

STOP SERVER
This action allows to stop AggreGate Server. There are two options: immediate and delayed shutdown. In case of delayed shutdown all active operators are informed about the shutdown time and reason. This helps them to set current jobs aside and save all changes before the shutdown. Action Type: Action Name: Action Icon: Permissions: Accessible at Administrator permission level
932

Call Function stop

903

RESTART SERVER
This action allows to restart AggreGate Server. There are two options: immediate and delayed restart. In case of delayed restart all active operators are informed about the restart time and reason. This helps them to set current jobs aside and save all changes before the restart. Automatic restart is possible only when AggreGate Server is running in service mode server must be stopped and started again manually.
46

. In other cases

Action Type: Action Name: Action Icon: Permissions:

Call Function restart

903

Accessible at Administrator permission level

932

CHANGE PASSWORD
This Call Function Action Type: Action Name: Permissions:
903

action is used to change the password of the currently authenticated user. Call Function
903

changePassword Accessible at Operator permission level

932

VIEW VARIABLE HISTORY

2000-2013 Tibbo Technology Inc.

728

AggreGate Documentation
869 .

This Call Function 903 action is used to access and view the update history of a certain variable specify 896 the following options: Context where variable is defined; Name of variable; From Date to track update history backwards up to a certain date only.

It prompts user to

This action outputs variable update history in the form of table. Every field of monitored variable's format 855 is shown in a separate field of resulting table. If variable value contains several rows, only data of the first row is shown. Action Type: Action Name: Action Icon: Permissions: Accessible at Administrator permission level
932

Call Function

903

variableHistory

VIEW EVENT HISTORY

This Call Function 903 action is used to select and view certain events from event history 896 event selection and presentation criteria: Mask
865 882 .

It prompts user to specify

of contexts to select events from;

Name of event; Event filtering expression

911 ;

From Date to select only events which occurred after a certain date. Here is an example of output (selecting user Expression = ""):
108

login events, Context Mask = users , Event Name = login , Filter

Action Type: Action Name: Action Icon: Permissions:

Call Function eventHistory

903

Accessible at Administrator permission level

932

DELETE EVENT HISTORY

This Call Function 903 action is used to delete certain events from event history event selection criteria: Mask
865 882 .

It prompts the user to specify

896

of contexts to delete events from;

Name of event; Start Date to delete only events which occurred after a certain date (optional); End Date to delete only events which occurred before a certain date (optional).

2000-2013 Tibbo Technology Inc.

AggreGate Server

729

Action Type: Action Name: Permissions:

Call Function deleteEvents

903

Accessible at Administrator permission level

932

VIEW CHANNEL STATISTICS

This Call Function 903 action is used to view statistics channel properties: Mask of contexts where channel is defined; Name of channel; Key of statistics dataset; Grouping period (hour, day, etc.); Aggregation types (average, maximum, etc.) This action outputs channel statistics in the tabular form. Action Type: Action Name: Action Icon: Permissions: Accessible at Administrator permission level
932 936

for a certain statistical channel. It prompts user to specify

896

Call Function viewStatistics

903

VIEW RAW CHANNEL STATISTICS

This Call Function 903 action is used to view raw (full) statistics specify 896 channel properties: Mask of contexts where channel is defined; Name of channel. This action outputs channel statistics in the tabular form. Action Type: Action Name: Action Icon: Permissions: Accessible at Administrator permission level
932 936

for a certain statistical channel. It prompts user to

Call Function

903

viewRawStatistics

PURGE STATISTICS CHANNEL

This Call Function 903 action is used to delete all data collected by a certain statistical channel. It prompts user to specify 896 channel properties: Mask of contexts where channel is defined; Name of channel. This action outputs channel statistics in the form of table. Action Type: Action Name: Permissions: Call Function
903

deleteStatistics Accessible at Administrator permission level

932

IMPORT

Used to import generic data into the system using a script. Action Flow: 1. Select 2. Select
902 896

a script to be used for processing the imported data. a file to be imported.

2000-2013 Tibbo Technology Inc.

730

AggreGate Documentation
896

3. [Optional] Specify

import options, if any options are available for the format of the selected file.

4. At this point, data is read from the file and converted to a Data Table. 5. Review
896

the data to be imported.

6. At this point, the import script is launched and imported Data Table is passed to its input. The script should process table data record by record and make necessary modifications to the system (e.g. create/modify resources).
Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Administrator permission level
932

import

SEND EMAIL

This Call Function

Action Type: Action Name: Action Group:

903

instructs AggreGate Server to send an email message.

Call Function sendMail Advanced Actions
903

SEND SMS

This Call Function

Action Type: Action Name: Action Group:

903

instructs AggreGate Server to send an SMS message.

Call Function sendSms Advanced Actions
903

EXECUTE APPLICATION

This Call Function 903 action is used to launch an external application by calling execute 765 function of this context. It may be used, for example, to launch some program in response to the raised alert (see Executing Non-Interactive Actions On Alert 227 for more information).
Action Type: Action Name: Permissions Action Group: Call Function execute Accessible at Administrator permission level Advanced Actions
932 903

VIEW DATABASE STATISTICS

This action shows number of events and properties in all tables of AggreGate Server database counts are grouped by database table, context path and event/property name. Action Type: Action Name: Permissions: Action Group: Edit Properties
897 80

. Event/property

viewDatabaseStatistics Accessible at Admin permission level Advanced Actions

932

CHECK INCOMING MAIL

This Call Function

Action Type:

903

forces AggreGate Server to fetch mail from an incoming mail server.

Call Function
903

2000-2013 Tibbo Technology Inc.

AggreGate Server

731

Action Name: Permissions: Action Group:

checkMail Accessible at Engineer permission level Advanced Actions

932

UPDATE HOST

This Call Function update.

Action Type: Action Name: Permissions: Action Group:

903

instructs AggreGate Server add or remove host from a DNS using a dynamic DNS

Call Function updateHost

903

Accessible at Admin permission level Advanced Actions [?

651 ]

932

Common Actions
Edit Context Permissions

906 ,

Monitor Related Events

909

Context States and Icons

This context has no states 865 . It is usually represented by the this context depends on the connection state. See details here icon. In AggreGate Client
789 . 776 ,

the icon representing

Advanced Information
Context Information
Context Type Context Name
864

: root : "" (Empty string)

864 :

863

Context Description Context Path Context Mask

863

"" (Empty string)

: "" (Empty string) : "" (Empty string)

865

865

Context Permissions [?
Level None Description Users login.

Users self-registration. Observer Operator Manager Engineer Administrat or Executing plain text AggreGate queries. User password self-changing. Creating bundled resources
107 .

Requests for checking and processing incoming mail. Viewing server information. Server stopping and restarting. Executing plain text native queries. Executing external applications. Accessing variable/event history and statistics. Viewing database statistics. Sending E-mail and SMS messages.

Public Variables (Properties)

[?

869 ]

2000-2013 Tibbo Technology Inc.

732

AggreGate Documentation

SERVER VERSION

Returns version of AggreGate Server. Variable Name: Records: Permissions: Record Format
Field Name
855

version

1 Readable at Observer permission level :

Field Type Notes
932

version
SERVER STATUS

String

Server version string.

Returns run-time information about AggreGate Server. Variable Name: Records: Permissions: Record Format
Field Name
855

status

1 Readable at Observer permission level :

Field Type Notes
932

name version startTime uptime freeMemory

String String Date Long Long

Server instance description. Server version. Server startup timestamp. Server uptime. Free memory in the currently allocated Java Virtual Machine (JVM) heap.
Maximum allowed size of JVM heap. Controlled by -Xmx parameter Current size of JVM heap. Server context event dispatcher queue length.
46

maxMemory totalMemory eventQueueLengt h

Long Long Integer

DATABASE STATISTICS

Returns statistical overview of AggreGate Server database. Variable Name: Records: Permissions: Record Format
855

database

1 Readable at Observer permission level :

932

2000-2013 Tibbo Technology Inc.

AggreGate Server

733

Field Name

Field Type

Notes

queries transactions
loaded

Long Long Long

Number of queries executed since server startup. Number of transactions completed since server startup. Number of objects fetched from the database since server startup. Number of objects updated in the database since server startup. Number of objects inserted into the database since server startup. Number of objects deleted from the database since server startup. Maximum execution time of all database queries performed since server startup.

updated inserted

Long Long

deleted

Long

maxQueryTime

Long

DATABASE TABLE STATISTICS

Returns detailed statistics of AggreGate Server database tables. Variable Name: Records: Permissions: Record Format
Field Name
855

tables

0...unlimited Readable at Observer permission level :

Field Type Notes
932

table
loaded updated inserted deleted

String Long Long Long Long

Table name. Number of objects fetched from the table since server startup. Number of objects updated in the table since server startup. Number of objects inserted into the table since server startup. Number of objects deleted from the table since server startup.

CONTEXT STATISTICS

Returns statistical information AggreGate Server contexts, variables, functions, events, and actions. Variable Name: Records: Permissions: Record Format
Field Name
855

sysinfo

0...unlimited Readable at Observer permission level :

Field Type Notes
932

2000-2013 Tibbo Technology Inc.

734

AggreGate Documentation

context variableCount
function Count eventCount actionCount variablesRead

Integer Integer Integer Integer Integer Long

Name and description of the AggreGate Server context. Total number of variable definitions in the context. Total number of function definitions in the context. Total number of event definitions in the context. Total number of action definitions in the context. Number of variable read operations performed since server startup. Number of variable write operations performed since server startup. Number of function call operations performed since server startup. Number of events fired since server startup.

variablesWritten

Long

functionsCalled

Long

eventsFired

Long

LICENSE INFORMATION

Returns information about active AggreGate Server license. Variable Name: Records: Permissions: Record Format
Field Name
855

license

1 Readable at Observer permission level :

Field Type Notes
932

issueDate holder version

trialPeriod trialRemaining maxDevices curDevices activationKey

Data String String Integer Integer Integer Integer

String

License issue date. License holder. Server version pattern. Trial period (days), or NULL for non-trial license. Remaining trial period (days), or NULL for non-trial license. Maximum number of devices allowed by the license. Current number of registered devices.
Server activation key.

ACTIVE PLUGINS

Returns information active AggreGate Server plugins Variable Name:

plugins

950

2000-2013 Tibbo Technology Inc.

AggreGate Server Records: Permissions: Record Format

Field Name
855

735

0...unlimited Readable at Observer permission level :

Field Type Notes
932

id type
name

String String String

Plugin ID. Plugin type.

Plugin description.

ACTIVE CLIENT CONNECTIONS

Returns information active client connections. Variable Name: Records: Permissions: Record Format
Field Name
855

connections

0...unlimited Readable at Observer permission level :

Field Type Notes
932

user type
date address

String String Date

String

Username of authenticated user

108

Connection type (Client, Web Desktop, Web Service, etc.)

Connection time. Client's IP address.

CLUSTER STATUS

Returns failover cluster Variable Name: Records: Permissions: Record Format

Field Name
855

87

node status information.

cluster

0...unlimited Readable at Observer permission level :

Field Type Notes
932

id role
time

String Integer Long

Cluster node ID. Cluster node role.

Time elapsed since node live status confirmation.

THREADS

Returns comprehensive list of server threads.

2000-2013 Tibbo Technology Inc.

736

AggreGate Documentation
threads

Variable Name: Records: Permissions: Record Format

Field Name
855

0...unlimited Readable at Observer permission level :

Field Type Notes
932

id name group priority state daemon interrupted stack

Long String String Integer String Boolean Boolean Data Table

Thread unique ID. Thread name. Thread group name. Thread priority. Thread state. True if thread is a daemon thread. True if thread has been interrupted. Thread stack track with the following fields: Class name Method name File name Line number

THREAD POOL STATISTICS

Returns statistical information about server thread pools. Variable Name: Records: Permissions: Record Format
Field Name
855

pools

0...unlimited Readable at Observer permission level :

Field Type Notes
932

poolName activeCount completedCoun t totalCount coreSize largestSize

String Integer Long

Pool name. Number of active tasks. Number of completed tasks.

Long Integer Integer

Total number of tasks. Pool core size. Pool largest (peak) size.

2000-2013 Tibbo Technology Inc.

AggreGate Server

737

maximumSize queueLength

Integer Integer

Pool maximum allowed size. Task queue length.

SERVER ENVIRONMENT

Returns information about Java Virtual Machine that is running AggreGate Server and server/PC that it is running on. Variable Name: Records: Permissions: Record Format
Field Name
855

environment

0...unlimited Readable at Observer permission level :

Field Type Notes
932

property value

String String

Name of property. Property value.

EVENT PROCESSING RULES STATISTICS

Returns statistical information collected by event processing rules is reset upon server restarts. Variable Name: Records: Permissions: Record Format
Field Name
855

70

. Note, that event rules statistics

eventRuleStatistics

0...unlimited Readable at Admin permission level :

Field Type Notes
932

context event filtered stored

String String Long Long

Context path. Event name. Number of events that were suppressed by this rule. Number of events that passed the rules and were saved in the server database.

EVENT STATISTICS

Returns counts of events name. Variable Name: Records: Permissions: Record Format
855

880

grouped by AggreGate Server database

80

table, context path and event

eventStatistics

0...unlimited Readable at Admin permission level :

932

2000-2013 Tibbo Technology Inc.

738

AggreGate Documentation

Field Name

Field Type

Notes

table context event count

String String String Long

Database table name. Context path. Event name. Number of events of the above type that occurred in the above context. Note, that all events of a certain type that occurred in a single context are always stored in a single table.

VARIABLE STATISTICS

Returns how many variables Variable Name: Records: Permissions: Record Format
Field Name
855

869

values are stored in the database for each AggreGate Server context.

variableStatistics

0...unlimited Readable at Admin permission level :

Field Type Notes
932

context count

String Long

Context path. Number of context variable's values that are currently stored in the database. Note, that default variable values are not saved to the database, and, thus, counts may be very low right after server installation.

Public Functions

[?

878 ]

REGISTER NEW USER ACCOUNT

Registers new user account
108 .

Function Name: Permissions: Input Records:

Input Format
855

register Accessible at None permission level

932

1
: Name username Type String Description Name of account.

password passwordre permissions

Output Records:

String String String

Account password. Account password.

Permission level 932 for a new user. Used only if registration is performed by administrator.

2000-2013 Tibbo Technology Inc.

AggreGate Server
Output Format
855 :

739

None

LOGIN
Pass authentication/authorization and continue session with access permissions of a certain user
108 .

Function Name: Permissions: Input Records:

Input Format
855

login Accessible at None permission level

932

1
: Name username password Type String String Description Username of user to authenticate as. User account password.

Output Records: Output Format

855 :

0 None

LOGOUT
Log out to continue session with None user permissions.

Function Name: Permissions: Input Records:

Input Format
855

logout Accessible at None permission level

932

0
: None

Output Records: Output Format

855 :

0
none

CHANGE PASSWORD
Changes password of a currently authenticated user account.

Function Name: Permissions: Input Records:

Input Format
855

changePassword Accessible at Operator permission level

932

1
: Name oldPassword newPassword repeatPasswor d Type String String String Description Old password for the account. New password. Must match the new password.

Output Records: Output Format

855 :

0 None

EXECUTE QUERY
Executes a custom Query
271

with permissions of current user.

Function Name:

executeQuery

2000-2013 Tibbo Technology Inc.

740

AggreGate Documentation
Accessible at Observer permission level
932

Permissions: Input Records:

Input Format
855

1
: Name query Type String Description Query text.

Output Records: Output Format

855 :

0...unlimited Dynamic

EXECUTE NATIVE QUERY

Executes a native query over AggreGate Server database. More information is available here
716 .

Function Name: Permissions: Input Records:

Input Format
855

executeNativeQuery Accessible at Administrator permission level

932

1
: Name query update Type String Boolean Description Query text. Flag indicating that query is an update query (DELETE, INSERT, UPDATE, etc.).

Output Records: Output Format

855 :

0...unlimited Dynamic

RESTART SERVER
Restarts AggreGate Server.

Function Name: Permissions: Input Records:

Input Format
855

restart Accessible at Administrator permission level

932

1
: Name instantly Type Boolean Description Allows to choice between immediate and delayed restart. Delay before scheduled restart. Reason of scheduled restart.

delay reason Output Records: Output Format

855 :

Long String

0
none

STOP SERVER
Stops AggreGate Server.

Function Name: Permissions: Input Records:

stop Accessible at Administrator permission level

932

2000-2013 Tibbo Technology Inc.

AggreGate Server
Input Format
855

741

: Name instantly Type Boolean Description Allows to choice between immediate and delayed shutdown. Delay before scheduled shutdown. Reason of scheduled shutdown.

delay reason Output Records: Output Format

855 :

Long String

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

CONTEXT ADDED

Fires when a new context of any type is added to the server context tree. This event may fire multiple times for the same context, e.g. during each server startup. Event Name Permissions:
Expiration Period: contextAdded

Accessible at Administrator permission level Non-persistent 1

855

932

Records: Record Format

Field Name context

:
Field Type String Notes Path of context.

CONTEXT REMOVED

Fires when a new context of any type is removed from the server context tree. This event may fire multiple times for the same context, e.g. during each server shutdown. Event Name Permissions:
Expiration Period: contextRemoved

Accessible at Administrator permission level Non-persistent 1

855

932

Records: Record Format

Field Name context

:
Field Type String Notes Path of context.

CONTEXT CREATED

Fires when a new resource context (e.g. alert 216 , widget 312 or device 113 ) is created. In contrast to contextAdded event this event fires only once for every resource upon its initial creation. It will not fire again on server startup. Event Name
contextCreated

2000-2013 Tibbo Technology Inc.

742

AggreGate Documentation

Permissions:
Expiration Period:

Accessible at Administrator permission level Non-persistent 1

855

932

Records: Record Format

Field Name context

:
Field Type String Notes Path of context.

CONTEXT DESTROYED

Fires when a resource context (e.g. alert 216 , widget 312 or device 113 ) is permanently destroyed. In contrast to contextRemoved event this event fires only once when the resource is being deleted. It does not fire during server shutdown. Event Name Permissions:
Expiration Period: contextDestroyed

Accessible at Administrator permission level Non-persistent 1

855

932

Records: Record Format

Field Name context

:
Field Type String Notes Path of context.

FEEDBACK

Server generates this event to report its activity related to a currently logged user Event Name Permissions:
Expiration Period: feedback

108

Accessible at Observer permission level Non-persistent 1

855

932

Records: Record Format

Field Name message

:
Field Type String Notes Server message.

3.22.29 Scheduled Jobs

This context
863

is a container, holding all scheduled jobs [?

651 ]

266

for a particular user.

Unique Actions

CREATE (Default Action

893

)
270

This action used for scheduling new jobs. It allows user to specify basic properties configure it immediately after creation.

of new job and

2000-2013 Tibbo Technology Inc.

AggreGate Server

743

Action Type: Permissions:

Create

905 932

Accessible at Manager permission level

SCHEDULE NEW JOB

This action also adds a new scheduled job. It is implemented as a Drag-and-Drop action 895 that accepts contexts of any type. The user is prompted to select an action to schedule from the context that was dropped onto the Scheduled Jobs context.
Action Type: Action Name: Non-Interactive Mode 893 : Permissions:

Drag and Drop createByDnD

Not Supported

895

Accessible at Manager permission level [?

651 ]

932

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: jobs : jobs
864 :

863

Context Description Context Path Context Mask

863

Scheduled Jobs

: users.USER_NAME.jobs : users.*.jobs
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Job creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

2000-2013 Tibbo Technology Inc.

744

AggreGate Documentation

CREATE
Creates new scheduled job.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
:

Same as format of jobDetailsView 0

none
880 ]

745

variable in Scheduled Job

744

context.

Output Records: Output Format

855 :

Public Events [?

Common Events: info (Information)

885

3.22.30 Scheduled Job

This context
863

lets you access and manage a single scheduled job

[?
651 ]

266

Unique Actions

CONFIGURE SCHEDULED JOB

This action is used to edit Scheduled Job properties
270 .

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure

904

EXECUTE SCHEDULER JOB

This forces AggreGate Server to perform immediate single execution of a scheduled job in non-interactive mode. Action Type: Action Name: Permissions: Call Function execute Accessible at Manager permission level [?
651 ] 909 , 932 903

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State Job is enabled Job is disabled

Advanced Information
Context Information
Context Type
864

: job

2000-2013 Tibbo Technology Inc.

AggreGate Server
Context Name
863

745

: provided by user
864 :

Context Description Context Path Context Mask

863

provided by user

: users.USER_NAME.jobs.SCHEDULED_JOB_NAME : users.*.jobs.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing.

Operator Manager

Same as Observer. Job configuration and removal. Forced job execution.

Engineer Administrat or

Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

SCHEDULED JOB PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name name description enabled mask action input
855

270

jobDetailsView

1 Readable at Observer permission level :

Field Type String String Boolean String String Data Table Notes 1 - 50 characters 1 - 50 characters
932

, writable at Manager permission level

SIMPLE SCHEDULE

See description of the variable and its fields here Variable Name: Records: Permissions:
triggersView

270

0...unlimited Readable at Observer permission level

932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

746

AggreGate Documentation
855

Record Format
Field Name startTime endTime repeatCount repeatInterval

:
Field Type Date Date Integer Long Notes

ADVANCED SCHEDULE

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name dayOfMonth month dayOfWeek year time startTime endTime
855

270

cronTriggersView

0...unlimited Readable at Observer permission level :

Field Type Data Table Data Table Data Table String Date Date Date Time-only editor is used Notes
932

, writable at Manager permission level

JOB STATUS

The variable provides scheduled job status data. It is shown by View Status Variable Name: Records: Permissions: Record Format
Field Name
855

910

action.

status

1 Readable at Observer permission level :

Field Type Date Date [?
878 ] 932

Notes

previousFireTime nextFireTime

Time elapsed since previous job execution or NULL if it was not executed yet. Time to next job execution or NULL if the job won't execute anymore.

Public Functions

This context has no public functions.

2000-2013 Tibbo Technology Inc.

AggreGate Server

747

EXECUTE
This forces AggreGate Server to perform immediate single execution of a scheduled job in non-interactive mode. The function is synchronous, i.e. it won't exit until the job has finished execution.

Function Name: Permissions: Input Records:

Input Format
855

execute Accessible at Manager permission level

932

0
:

None. 0
None.
880 ]

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

, contextStatusChanged (Status Changed)

890

3.22.31 Scripts
This context
863

is a container, holding all scripts

[?
651 ]

628

for a particular user.

Unique Actions

CREATE NEW SCRIPT (Default Action

893

)
629

This action used for creating new scripts. It allows user to specify basic properties
Action Type: Permissions: Create
905 932

of a new script.

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: scripts

863

: scripts
864 :

Context Description Context Path Context Mask

863

Scripts

: users.USER_NAME.scripts : users.*.scripts
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring.

2000-2013 Tibbo Technology Inc.

748

AggreGate Documentation

Operator Manager Engineer Administrat or

Same as Observer. Script creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new script.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo hidden.
749

variable in Script

748

context, except that text field is

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.32 Script
This context
863

lets you access and manage a single script

651 ]

628

Unique Actions [?

EXECUTE SCRIPT (Default Action

893

This action causes the server to compile and launch the script. If any errors occur during compilation or are produced by the script itself, they are reported to the user using the Show Error 899 UI Procedure.
Action Name: Non-Interactive Mode 893 : Permissions: execute Not Supported Accessible at Engineer permission level
932

CONFIGURE

This action is used to edit Script properties

context is required to change script text.

629

. Note, that Administrator permission level

932

in the Script

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

2000-2013 Tibbo Technology Inc.

AggreGate Server

749

Action Type:

Configure

904

EDIT SOURCE

This action starts the built-in text editor (with syntax highlighting) and allows the user to edit the script source. The text editor available in AggreGate Client 776 is described here 819 .
Action Name: Non-Interactive Mode 893 : Permissions: editSource Not Supported Accessible at Administrator permission level [?
651 ] 909 , 932

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: script : provided by user

864

863

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.scripts.SCRIPT_NAME : users.*.scripts.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Script configuration and removal. Script execution. Script source editing.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

SCRIPT PROPERTIES

See description of the variable and its fields here Variable Name: Records: childInfo 1

629

2000-2013 Tibbo Technology Inc.

750

AggreGate Documentation

Permissions: Record Format Field Name

name description text autorun
855

Readable at Observer permission level level : Field Type

String String String Boolean

932

, writable at Manager permission

Notes
1 - 50 characters 1 - 50 characters Text can only be changed under Administrator permission level.

Public Functions
EXECUTE SCRIPT

[?

878 ]

Executes the script and returns the data it generates. A list of parameter objects passed to the script as input is constructed from the function input Data Table by taking the values of its cells field-by-field, starting from the first row. If the script returns a Data Table object, this function will return it unchanged. If the script returns another value type that is supported by the Data Table format 856 , this object is wrapped into a single-cell table with a field of a corresponding format. If script returns a value of a type that is not supported by the Data Table format, this value is converted to a string (by calling Java Object.toString() method) and wrapped into a single-cell Data Table with a string field.

Function Name: Permissions: Input Records:

Input Format
855

execute Accessible at Engineer permission level 0...unlimited

932

Dynamic 0...unlimited Dynamic

880 ]

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

3.22.33 Trackers
This context
863

is a container, holding all trackers

[?
651 ]

257

for a particular user.

Unique Actions
Build Tracker
752

Other unique actions:

CREATE TRACKER (Default Action

893

)
258

This action is used for creating new trackers. It allows the user to specify the basic properties new tracker and configure it immediately after creation.
Action Type: Permissions: Create

of a

905 932

Accessible at Manager permission level

895 ]

Variable-Related Actions [?

2000-2013 Tibbo Technology Inc.

AggreGate Server

751

CREATE TRACKER
This action creates a new tracker that tracks the value of a variable. If variable has more than one field, user is prompted to select which field will be displayed by the tracker. If the variable belongs to a Device Context 677 (e.g. it is a Device setting), the user is prompted 901 to create an Offline status 257 for the newly created tracker. Tracker in Offline state is indicated by gray color (this is a default color -- it may be changed). This state is activated when the Device is disconnected from the server.

Action Name: Non-Interactive Mode 893 : Permissions:

trackerForVariable Not Supported Accessible at Manager permission level [?

651 ] 906 , 932

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: trackers

863

: trackers
864 :

Context Description Context Path Context Mask

863

Trackers

: users.USER_NAME.trackers : users.*.trackers
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Tracker creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new tracker.

Function Name:

create

2000-2013 Tibbo Technology Inc.

752

AggreGate Documentation
Accessible at Manager permission level
932

Permissions: Input Records:

Input Format
855

1
: Same as format of childInfo
754

variable in Tracker

753

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

TRACK

This event is fired when tracker value and state is re-evaluated. Event Name Permissions:
Expiration Period: track

Accessible at Observer permission level Non-persistent 1

855

932

Records: Record Format

Field Name name value status color

:
Notes

Field Type

String String String Color

Tracker name. String representation of tracker value. Description of tracker status. Color associated with tracker status.

3.22.33.1 Action: Build Tracker

This is a step-by-step wizard for creating a tracker.

Action Flow: 1. Select a context as described in Drag-and-Drop actions 895 article. For example, in the Drag-andDrop selection method, click a System Tree node you wish to apply this action to. Keep the left mouse button pressed and drag it onto the Favourites node. 1. Select 2. Select
896 896

a variable those state will be tracked. a tracked field of the above variable.

3. At this point, new Tracker will be created. 4. Edit

897

properties of the newly created tracker, e.g. add some statuses. Drag and Drop
build Not Supported Accessible at Manager permission level
932

Action Type: Action Name: Non-Interactive Mode 893 : Permissions:

895

2000-2013 Tibbo Technology Inc.

AggreGate Server

753

3.22.34 Tracker
This context
863

lets you access and manage a single tracker

651 ]

257

Unique Actions [?

CONFIGURE TRACKER (Default Action

893

)
258

This action is used to edit Tracker properties

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State Tracker is enabled Tracker is disabled

Advanced Information
Context Information
Context Type Context Name
864

: tracker : provided by user

864

863

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.trackers.TRACKER_NAME : users.*.trackers.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Tracker monitoring. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Tracker configuration and removal. Same as Manager. Same as Manager.

2000-2013 Tibbo Technology Inc.

754

AggreGate Documentation

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

TRACKER PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name
name description expression enabled period
855

258

childInfo 1 Readable at Observer permission level

932

, writable at Manager permission level

: Field Type
String String String Boolean Long Measured in milliseconds

Notes
1 - 50 characters 1 - 50 characters

STATUS TABLE

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format Field Name description expression color level
STATISTICS CHANNELS
855

258

replication 0...unlimited Readable at Observer permission level

932

, writable at Manager permission level

: Field Type String String Color Integer

Nullable.

Notes
One or more characters.

This variable allows to manage statistics channels Variable Name: Records: Permissions: Record Format
855

259

of this tracker.

statisticsProperties

0...unlimited Readable at Observer permission level :

932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

AggreGate Server

755

Field Name name variable properties

Field Type String String Data Table

Notes Name of the channel. Name of variable the channel is based on. Properties
938

of the channel.

TRACKER

This variable provides access to the current tracker value. If a non-zero History Storage Time is set in the tracker settings 258 , changes of this variable are persisted in the database and may be used for building charts etc. Variable Name: Records: Permissions: Record Format Field Name value
STATISTICS
855

tracker 1 Readable at Observer permission level

932

: Field Type String Notes

Current value of the tracker converted to a string.

This variable is a view of tracker statistics, i.e. aggregated data collected by tracker's statistical channels 259 . Variable Name: Records: Permissions: Record Format
Field Name name variable statistics
855

statistics

0...unlimited Readable at Observer permission level :

Field Type String String Data Table [?
878 ] 932

Notes Name of the channel. Name of variable the channel is based on. Brief statistical data.

Public Functions

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

STATUS CHANGE

This event is fired when tracker state has been changed. Event Name
statusChange

2000-2013 Tibbo Technology Inc.

756

AggreGate Documentation

Permissions:
Expiration Period:

Accessible at Observer permission level 100 days 1

855

932

Records: Record Format

Field Name value status

:
Notes

Field Type

String String

String representation of current tracker value. Description of new tracker status.

3.22.35 Users
This context
863

is a container, holding all User contexts

[?
759 651 ]

759

(user accounts

108

).

Unique Actions
New User Account

(Default Action
759

893

View User Summary

Other unique actions:

TUTORIAL: CREATE NEW USER ACCOUNT

This action starts

Action Name: Action Icon: Non-Interactive Mode 893 : Permissions:

902

an Interactive Guide for helping with registering new user account

guide

108

Not Supported Accessible at Administrator permission level [?

651 ] 906 , 932

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

Monitor

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: users : users
864 :

863

Context Description Context Path Context Mask

863

Users

: users : users
865

865

Context Permissions [?

2000-2013 Tibbo Technology Inc.

AggreGate Server

757

Level None Observer Operator Manager Engineer Administrat or

Description No access allowed. No access allowed. No access allowed. No access allowed. No access allowed. All operations.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions
USER LIST

[?

878 ]

This function returns information about all User Accounts that are accessible with current permissions. Account properties are described here 110 .

Function Name: Permissions: Input Records:

Input Format
855

list Accessible at Observer permission level

932

0
:

None
0...unlimited Name Type Description

Output Records: Output Format

855 :

name firstname lastname password country region zip city address1 address2 comments company department

String String String String Integer String String String String String String String String Nullable Nullable Nullable Nullable Nullable Nullable Nullable Nullable Nullable Nullable

2000-2013 Tibbo Technology Inc.

758

AggreGate Documentation

email phone fax timezone locale datepattern timepattern dsautoregist ration

String String String String String String String Boolean

Nullable Nullable Nullable

Public Events

[?

880 ]

Common Events: info (Information)

885

LOGIN

This event is generated upon successful user Event Name Permissions:

Expiration Period: login

108

authentication.

Accessible at Administrator permission level 100 days 1

855

932

Records: Record Format

Field Name username type address permissions

:
Field Type String String String String Notes Name of authenticated user. Connection type (desktop, web, web service, etc.) Client's IP address or host name. User's permissions at the moment of authentication.

LOGOUT

This event is generated when a user Event Name Permissions:

Expiration Period: logout

108

logs out from the system.

Accessible at Administrator permission level 100 days 1

855

932

Records: Record Format

Field Name

:
Field Type Notes

2000-2013 Tibbo Technology Inc.

AggreGate Server

759

username

String

Name of user who performed the logout.

3.22.35.1 Action: New User Account

This Call Function Username Password Permission level See the users
108 932 903

action is used to create a new user account. The following parameters should be specified:

section for more information about the default settings for a new account.

Action Type: Action Name: Action Icon:

Call Function create

903

3.22.35.2 Action: View User Summary

This action shows executing it.
Action Type: Action Name:
896

the basic properties

110

of all user accounts that are accessible by the user

Call Function list

903

3.22.36 User
This context
863

lets you access and manage a single user account

[?
651 ]

108

Unique Actions

CONFIGURE (Default Action

893

)
110 .

This action is used to edit account properties

Action Type:

Configure

904

DELETE ACCOUNT
This is a standard Delete Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Supported Accessible at Administrator permission level [?
651 ] 906 , 932 905

action that is used to remove user account.

delete

Common Actions
Replicate
909

, Edit Context Permissions

Monitor Related Events

909 ,

View Status

910

Context States and Icons

2000-2013 Tibbo Technology Inc.

760

AggreGate Documentation

This context has no states

865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: user : provided by user

864 :

863

Context Description Context Path Context Mask

863

provided by user; contains username, first name and last name of a user

: users.USER_NAME : users.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing.

Operator Manager

Same as Observer. User profile browsing. User photo editing.

Engineer Administrat or

Same as Manager. User profile editing. User permissions editing. User removal.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

USER INFORMATION

Returns properties Variable Name: Records: Permissions: Record Format

855

110

of a User Account.
childInfo

1 Readable at Observer permission level :

932

Name

Type

Description

name firstname lastname password country

String String String String Integer Nullable Nullable

2000-2013 Tibbo Technology Inc.

AggreGate Server

761

region zip city address1 address2 comments company department email phone fax timezone locale datepattern timepattern dsautoregistratio n
PERMISSIONS

String String String String String String String String String String String String String String String Boolean

Nullable Nullable Nullable Nullable Nullable Nullable Nullable Nullable Nullable Nullable Nullable

Returns permissions Variable Name: Records: Permissions: Record Format

855

111

of a User Account.

permissions

0...unlimited Readable at Observer permission level level 932 :

932

, writable at Administrator permission

Field Name

Field Type

Notes

mask type
ACCOUNT SETTINGS

String String

Context mask for that permission level is applied. Permission level.

User account settings Variable Name:

111

settings

2000-2013 Tibbo Technology Inc.

762

AggreGate Documentation

Records: Permissions: Record Format

855

1 Readable/writable at Administrator permission level :

932

Field Name

Field Type

Notes User login is not allowed if this flag is disabled. If not NULL, user is not allowed to log in until this time. If not NULL, user is not allowed to log in after this time.

enabled activationTime expirationTime

RESOURCES

Boolean Date Date

User's available resources Variable Name: Records: Permissions: Record Format

855

111

table.

resources

0...unlimited Readable/writable at Administrator permission level :

932

Field Name

Field Type

Notes Resource type description. Flag indicating whether user's account will have a container node for resources of this type.

description available

String Boolean

USER PHOTO

User's photo

111

.
photo

Variable Name: Records: Permissions: Record Format

855

1 Readable/writable at Manager permission level :

932

Field Name

Field Type

Notes

photo
USER STATUS

Data Block

Returns status

112

of a User Account.
status

Variable Name: Records: Permissions: Record Format

855

1 Readable at Observer permission level :

932

2000-2013 Tibbo Technology Inc.

AggreGate Server

763

Field Name

Field Type

Notes

creationtime updatetime logintime

Date Date Date

[?
878 ]

Account creation time. Last account modification time. Last login time, or NULL if the user has never logged in.

Public Functions

DELETE USER ACCOUNT

Permanently destroys User Account and all related data.

Function Name: Permissions: Input Records:

Input Format
855

delete Accessible at Administrator permission level

932

0
: None

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

3.22.37 Utilities
This context is a system context that provides miscellaneous operations. It is not shown in the visible context tree.

Unique Actions
SHOW DATA

[?

651 ]

This action fetches some data from the system by calculating an expression 911 , shows it to the user using Edit Data UI procedure, and enables automatic re-retrieving and auto-refreshing of the shown data. Action Name: Non-Interactive Mode 893 : Permissions: Execution Parameters
896

896

showData Not Supported Accessible at None permission level 1. Data Acquisition: : Expression to calculate Refresh period 2. Data Presentation: Title of the data window Help, the text to show in the data window Icon, the icon ID string of the data window icon 3. Location
955 932

of the data window

Variable-Related Actions [?

895 ]

2000-2013 Tibbo Technology Inc.

764

AggreGate Documentation

VIEW CHANGE HISTORY

This action shows historical changes of variable's value. It outputs the variable update history in the form of table. Every field of the monitored variable's format 855 is shown in a separate field of the resulting table. If the variable value contains several rows, only the first row is shown.

VIEW VARIABLE INFORMATION

This action shows
896

variable definition
895 ]

870

properties and its format.

Event-Related Actions [?

VIEW EVENT INFORMATION

This action shows
896

event definition

870

properties and its format.

Advanced Information
Context Information
Context Type Context Name
864

: utilities : utilities
864

863

Context Description Context Path Context Mask

863

: Utilities

: utilities : utilities
865

865

Context Permissions [?
Level None Observer Description

Basic system internal operations. Accessing and deleting variable/event history. Accessing and deleting variable statistics. Accessing device topology.

Operator Manager Engineer Administrat or

Sending E-mail and SMS messages. Same as Operator. Requests for incoming mail checking. External application execution.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

GET VARIABLE HISTORY

Returns update history of a specified variable. See View Variable History
727

action for more information.

Function Name: Permissions: Input Records:

Input Format
855

variableHistory Accessible at Observer permission level

932

1
: Name Type Description

2000-2013 Tibbo Technology Inc.

AggreGate Server

765

context variable fromDate

String String Date

Context where variable is defined. Variable name.

Timestamp used to select only variable updates which occurred after a certain date. If it is NULL, all oldest events will be included. Timestamp used to select only variable updates which occurred before a certain date. If it is NULL, all newest events will be included. If disabled (default behaviour), the resulting table will contain one additional field per every field of variable those history is retrieved. In this case, only first rows of historical values will be added to the resulting table, other rows will be discarded. Thus, this mode is suitable for single-row variables only. If enabled, the historical values will be contained in a separate tabular field called vValue.

toDate

Date

dataAsTable

Boolean

limit sortAscendin g
Output Records: Output Format
855 :

Integer Boolean

Maximum number of historical values to retrieve. Flag switching between ascending and descending sorting of historical values.

0...unlimited Dynamic, has at least vUpdateTime field that contains timestamps of historical values.

EXECUTE EXTERNAL APPLICATION

This function executes an external application referred by input arguments, waits for its termination and returns its output.

Function Name: Permissions: Input Records:

Input Format
855

execute Accessible at Administrator permission level

932

1
: Name command directory Type String String Description Command fully qualified name with arguments. Working directory, may be omitted.

Output Records: Output Format

855 :

1
Name exitCode output errors Type Integer String String Description Command exit code. Capture of command output. Capture of command error output.

CHECK MAIL
Instructs AggreGate Server to fetch and process incoming e-mail messages.

2000-2013 Tibbo Technology Inc.

766

AggreGate Documentation
checkMail Accessible at Engineer permission level
932

Function Name: Permissions: Input Records:

Input Format
855

0
: None

Output Records: Output Format

855 :

0
none

SEND EMAIL
Sends an email. This function will work properly only if mail sending
63

is properly set up in server global configuration.

Function Name: Permissions: Input Records:

Input Format
855

sendMail Accessible at Operator permission level

932

1
: Name Type Description

recipients subject message html

Output Records: Output Format
855 :

String String String Boolean

Comma-separated list of email recipients. Message subject.

Message text. Indicates that message text is in HTML format.

0 None

SEND SMS
Sends an SMS message. This function will work properly only if SMS sending configuration.
69

is properly set up in server global

Function Name: Permissions: Input Records:

Input Format
855

sendSms Accessible at Operator permission level

932

1
: Name Type Description

recipient

String

Phone number of SMS recipient in international format. Message text.

message
Output Records: Output Format
855 :

String

0 None

UPDATE HOST
Updates host in a dynamic DNS.

Function Name: Permissions: Input Records:

updateHost Accessible at Operator permission level

932

2000-2013 Tibbo Technology Inc.

AggreGate Server
Input Format
855

767

: Name Type Description

host

String

Host name to update. DNS zone to be updated is configured in Dynamic DNS global settings. IP address of the host.

61

ip remove

String Boolean

Unregister host from DNS zone if false, or register it if true.

Output Records: Output Format

855 :

0 None

LIST VARIABLES
This function returns a list of values of all single-cell (i.e. non-tabular and non-array) variables in all contexts matching to a certain mask and belonging to a certain group.

Function Name: Permissions: Input Records:

Input Format
855

listVariables Accessible at Observer permission level

932

1
: Name mask group Type String String Description Mask of context to list variables from. Variable's group.

Output Records: Output Format

855 :

0...unlimited
Name context variable value Type String String String Description Context description. Variable description. String representation of variable's value.

STATISTICS
This function returns last values for a statistical channel
936

(e.g. last month's average, last day's minimum, etc.)

Function Name: Permissions: Input Records:

Input Format
855

statistics Accessible at Observer permission level

932

1
: Name mask channel key Type String String String Description Mask of context to fetch statistical data from. Name of channel. Dataset key or NULL to use default dataset.

2000-2013 Tibbo Technology Inc.

768

AggreGate Documentation

period

String

Time period to show last values for. If NULL, the data will be fetched for all periods. Period names: millisecond or ms for Milliseconds second, sec or s for Seconds minute, min or m for Minutes hour, hr or h for Hours day or d for Days week or w for Weeks month for Months (Note, that month is zero-based , i.e. value for January is 0.) year or y for Years

full

Boolean

If true, all statistical values are returned according to the above period (e.g. all hourly averages). If false, only last collected values are returned (e.g. last full hour averages). Show average value for the last period of selected type. Default is true. Show minimum value for the last period of selected type. Default is false. Show maximum value for the last period of selected type. Default is false. Show total value for the last period of selected type. Default is false. Show first value for the last period of selected type. Default is false. Show last value for the last period of selected type. Default is false.

average

Boolean

minimum

Boolean

maximum

Boolean

sum

Boolean

first

Boolean

last

Boolean

Output Records: Output Format

855 :

0...unlimited
Name context start end key average minimum maximum sum first Type String Date Date String Float Float Float Float Float Description Name of context that originated data. Start of time period. End of time period. Dataset key or NULL if default dataset was used. Average value for the time period. Minimum value for the time period. Maximum value for the time period. Total value for the time period. First value for the time period.

2000-2013 Tibbo Technology Inc.

AggreGate Server

769

last

Float

Last value for the time period.

RAW STATISTICS
This function returns raw statistical data for a statistical channel
936 .

Function Name: Permissions: Input Records:

Input Format
855

rawStatistics Accessible at Observer permission level

932

1
: Name context name Type String String Description Name of context to fetch statistics from. Name of channel to fetch statistics from.

Output Records: Output Format

855 :

0...unlimited
Dynamic

DELETE STATISTICS
This function is used to purge all data collected by a statistical channel
936 .

Function Name: Permissions: Input Records:

Input Format
855

deleteStatistics Accessible at Observer permission level

932

1
: Name mask channel Type String String Description Mask of contexts to look for statistical channels. Name of channel to purge data from.

Output Records: Output Format

855 :

0
None

SELECTION VALUES
This function returns a data table suitable to be used as selection values of another data table's field. It's most often used in an expression of a data table binding 860 that's targeted to choices 860 property of the field. The function first constructs an intermediate data table by evaluating an expression. It then goes through this table rowby-row and evaluates two other expressions for each row. First one returns the selection values itself and second one returns its description.

Function Name: Permissions: Input Records:

Input Format
855

selectopnValues Accessible at Observer permission level

932

1
: Name tableExpressio n valueExpressio Type String Description Expression that should return a table those records will be used to construct selection values list. Expression that's calculated over each record of the

String

2000-2013 Tibbo Technology Inc.

770

AggreGate Documentation

above table and should return a string representation of a selection value. String Expression that's calculated over the same record and should return a description of the selection value.

descriptionExpr esssion

Output Records: Output Format

855 :

0...unlimited
Name value description Type String String Description String representation of a selection value. Description of the selection value.

Public Events

[?

880 ]

Common Events: info (Information)

885

3.22.38 Widgets
This context
863

is a container, holding all widgets [?

651 ]

312

for a particular user.

Unique Actions

CREATE NEW WIDGET (Default Action

893

)
314

This Drag and Drop

Action Type: Action Icon: Action Name: Non-Interactive Mode 893 : Permissions:

895

action is used to create a new widget. It is described here Drag and Drop
895

create Not Supported Accessible at Manager permission level

932

CREATE DEVICE MAP

This action is used to create a Device Map widget.

Action Flow: 1. Specify 2. Select

896

map properties (name, description, background image, size of device images, etc.). the Device to show on the map.
827

902

3. Edit the new map in GUI Builder

Action Name: Non-Interactive Mode 893 : Permissions: createMap Not Supported

Accessible at Manager permission level [?

651 ]

932

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Variable-Related Actions [?

895 ]

2000-2013 Tibbo Technology Inc.

AggreGate Server

771

CREATE CHART
This action creates a new widget with a chart 384 component and several other components for controlling chart parameters on-the-fly. These components form a toolbar. Chart is configured to show historical changes of variable's values. At first step, the following parameters should be specified: Chart type (line, area, or bar) Toolbar (enabled/disabled) One of the two pre-defined validity expressions only or with all contexts of the same type.
948 ,

that allow this chart to later used with the current context

At next step, one or more named chart trends should be created. Each trend is defined an expression that may refer one or more variable fields.

Action Name: Non-Interactive Mode 893 : Permissions:

chartForVariable Not Supported Accessible at Manager permission level

932

CREATE WIDGET
This action generates new widget that may be used to edited value variable. Newly created widget may be customized immediately after creation to form a good-looking custom editor for this type of variable. Widget template 314 produced by this action is best suit for editing values of complex variables those format defines multiple fields but single row. Template consist of main panel with two columns and and button panel in the bottom. Left column of main panel displays field names using widget labels 323 . Right column contains different components used to view/edit field values. In the button there are two buttons: Submit button causing widget to commit changes and exit, and Close button that stops widget without saving changes. Here is how an auto-generated widget looks like for User Account Properties 110 variable of User context:

2000-2013 Tibbo Technology Inc.

772

AggreGate Documentation

Action Name: Non-Interactive Mode 893 : Permissions:

widgetForVariable Not Supported Accessible at Manager permission level

895 ] 932

Event-Related Actions [?
CREATE CHART

This action creates a new widget with a chart 384 component and several other components for controlling chart parameters on-the-fly. These components form a toolbar. Chart is configured to show data value taken from history of current event. At first step, the following parameters should be specified: Chart type (line, area, or bar) Toolbar (enabled/disabled) One of the two pre-defined validity expressions only or with all contexts of the same type.
948 ,

that allow this chart to later used with the current context

At next step, one or more named chart trends should be created. Each trend is defined an expression that may refer one or more event fields.

Action Name: Non-Interactive Mode 893 :

chartForEvent Not Supported

2000-2013 Tibbo Technology Inc.

AggreGate Server

773

Permissions:

Accessible at Manager permission level

932

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: widgets : widgets
864 :

863

Context Description Context Path Context Mask

863

Widgets

: users.USER_NAME.widgets : users.*.widgets
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Widget creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new widget.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
:

Same as format of childInfo 0

none
880 ]

775

variable in Widget

774

context.

Output Records: Output Format

855 :

Public Events

[?

Common Events: info (Information)

885

2000-2013 Tibbo Technology Inc.

774

AggreGate Documentation

3.22.39 Widget
This context
863

lets you access and manage a single widget

[?
651 ]

312

Unique Actions

CONFIGURE WIDGET

This Configure

904

action is used to edit the properties

315

of the widget.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure

904

EDIT TEMPLATE (Default Action

893

for Relative

314

widgets)
776

This action is supported only in AggreGate Client widget template 314 .

Action Name: Non-Interactive Mode 893 : Permissions: editTemplate Not Supported

. Is starts the GUI Builder

827

and allows to edit the

Accessible at Manager permission level

893

932

LAUNCH WIDGET (Default Action

for Absolute
316

314

widgets)

This action starts a widget. See Launching Widgets

for more information.

Action Name: Non-Interactive Mode 893 : Permissions: Execution Parameters

896

launch Not Supported Accessible at Observer permission level Widget Window Location : [?
651 ] 909 , 955 932

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

Icon Code 0 1 State This widget is relative. This widget is absolute.

Advanced Information
Context Information
Context Type Context Name
864

: widget : provided by user

864 :

863

Context Description Context Path

863

provided by user

: users.USER_NAME.widgets.WIDGET_NAME

2000-2013 Tibbo Technology Inc.

AggreGate Server
Context Mask
865

775

: users.*.widgets.*
865

Context Permissions [?
Level None Observer Description

No access allowed. Widget launching. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Widget configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

validity (Validity)

876 ,

activeAlerts (Active Alerts)

875

WIDGET PROPERTIES

See description of the variable and its fields here Variable Name: Records: Permissions: Record Format
Field Name name description template type validityExpressio n validityListeners defaultContext
855

315

childInfo

1 Readable at Observer permission level :

Field Type String String String String String Notes 1 - 50 characters 1 - 50 characters
932

, writable at Manager permission level

Data Table String

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

2000-2013 Tibbo Technology Inc.

776

AggreGate Documentation

4 AggreGate Client
AggreGate Client is a software product using a Graphical User Interface (GUI) to access a AggreGate Server installation. It can be used for: 1. Server configuration and administration 2. Management and configuration of Devices 3. Event monitoring and receiving alert notifications In short, it can be used for just about anything having to do with AggreGate Server. The AggreGate Client is your "window" into AggreGate Server. This is where the average user spends most of his time. AggreGate Client the uses AggreGate Communications Protocol 1303 to communicate with AggreGate Server.
40

4.1 Operation Modes

There are several ways to install and launch AggreGate Client: Unified Operations Console mode Java Web Start mode Browser mode

UNIFIED OPERATIONS CONSOLE

AggreGate Client can be installed as a standalone cross-platform application for Windows, Linux/Unix and Mac OS. In this case AggreGate Client acts as a Unified Operations Console since it can establish multiple simultaneous server connections and aggregate data collected by a distributed AggreGate installation. When running as a Unified Operations Console, AggreGate Client allows to create workspaces 779 that comprise server connections 779 . Thus, every operator that uses AggreGate Client on a certain machine logs in to his workspace first, and the workspace auto-connects him to one or more servers.

BROWSER MODE
AggreGate Client can run in any web browser. To launch AggreGate Client in a browser window, open AggreGate Server Control Center 631 and select Open AggreGate Client in the Browser. Use tray menu
108

to connect to a server running on the localhost.

When running in Browser mode, AggreGate Client doesn't allow to create workspaces and server connections Instead, it is connected to a single server only.

779 .

JAVA WEB START MODE

Java Web Start technology allows to install and immediately run AggreGate Client on your machine without downloading the installer file and executing it. It also provides a seamless method for ensuring that your installation is always up to date. To install and launch AggreGate Client via Java Web Start, open AggreGate Server Control Center Install and Launch AggreGate Client. Use tray menu
108 631

and select

to install and launch AggreGate Client from a server running on the localhost.

Once AggreGate Client has been installed via Java Web Start, a desktop icon will be created, allowing to re-launch it later without navigating through the web pages. AggreGate Client will be auto-updated to match version of the server it was installed from upon every startup. Note that AggreGate Client will update to the same version as the server it was installed from. It's not the latest version available on Tibbo website! To update the whole installation to the latest version offered by Tibbo, perform the server upgrade first, and all AggreGate Clients launched via Java Web Start will be updated upon the next startup.

2000-2013 Tibbo Technology Inc.

AggreGate Client

777

4.2 Requirements and Installation

AggreGate Client is a Java-based application, so it can run on any Java-enabled OS. AggreGate Client installer is bundled with a Java 6 Virtual Machine, so it is not necessary to have Java installed on your PC. Installation is only necessary to operate AggreGate Client in unified operations console
776

mode.

Tibbo supplies pre-packaged installation files for the following operating systems: Windows 98, NT, 2000, XP, 2003 Server, Vista, 2008 Server, and 7 (compatible with Windows Embedded) Different versions of Linux (compatible with embedded Linux) Mac OS X Installers for the other Java-enabled operating systems (FreeBSD and other *nix, Solaris, etc.) are available on demand. To install the product, just run the installer executable file and follow the instructions. On some systems, you need to make the installation package 'executable' before running it.

System Requirements
Operating System: Any Java-enabled OS, including embedded environments (e.g. ARM Linux) RAM: 256MB minimum HDD: 200MB of free space Recommended screen resolution: 1280x1024 or more

4.3 Command Line Parameters

The AggreGate Client can be run with any of the following command line options: Parameter Description Activate admin mode
779 . 779

-a -c -l <context>:< action>

Automatically create workspace

if it does not exists.

Automatically start action <action> from context <context>. This option allows to open necessary information upon AggreGate Client startup. For example, if a device was clicked in a third-party system (e.g. billing system), the latter may start AggreGate Client executable and immediately show dashboard of a clicked device to the operator.

-u <username> -p <password> -s

Name of workspace

779

to load on startup.

Workspace password. Launches client in simple mode

784 .

If both -u and -p options are specified, the authorization dialog is not shown and workspace selected by -u option is loaded automatically. This combination should be used only in secure environments - it grants instant access to your AggreGate Server installation. You can also use -u and -p to run the AggreGate Client and instantly show several widgets 312 (by using Auto Run 662 feature) with monitoring information for some contexts (such as in a monitoring station on a factory floor). I.e, you can have AggreGate Client run from a desktop shortcut (or automatically when the computer is started), and show various gauges and bars on a screen in a factory floor, to help determine the status of various machines.

2000-2013 Tibbo Technology Inc.

778

AggreGate Documentation

4.4 Uninstallation
AggreGate Client is uninstalled by running uninstall executable file from AggreGate Client installation directory. It's necessary to close the application before uninstallation. AggreGate Client uninstaller does not remove files created or modified by the AggreGate Client itself during its operation (workspaces, logs, etc.). To completely wipe out all AggreGate Client data, delete its installation directory with all contents when uninstaller has finished working. This may be necessary to perform a "clean" reinstallation.

4.5 Startup and Shutdown

This article explains how to start/stop AggreGate Client that is installed in unified operations console
776

mode.

The AggreGate Client is started by a special Launcher created during the installation process. Launcher type depends on the operating system: Under Unix , it's the ag_client shell script, while under Windows it is a small exe file accessible through the Start menu (Start > Programs > AggreGate > Client) or as a desktop shortcut:

User interface language, memory usage, and some other parameters of AggreGate Client may be configured using the Launcher Properties File (ag_client.vmoptions) those format is the same as AggreGate Server's Launcher Properties File 45 .

Workspace Login
Once AggreGate Client is launched, you need to login to the workspace in the dialog:
779 .

Select a workspace and enter its password

If you are using AggreGate Client for the first time, just enter any desired workspace name and password to create a new workspace. If a workspace with the given name does not exist, you will be prompted to create a new one:

2000-2013 Tibbo Technology Inc.

AggreGate Client

779

4.5.1 Admin Mode

AggreGate Client may work in two run-time modes: Normal mode Admin mode Admin mode is activated by specifying the -a command line option 777 . It allows AggreGate administrators to access advanced functions. The Admin mode does not require any special privileges in itself: The advanced functions simply won't be available if the user doesn't have sufficient access rights on the server. Currently, the advanced mode unlocks the following functions: Interactive Guide Editor ("Macro Recorder"). It is available in Main Menu 780 > View > Start Macro Recorder. This doesn't require any server permissions in itself, but any changes made will only apply to the local AggreGate Client installation. Server operation won't be effected in any way. Open Server Log and Open Device Browser actions in the AggreGate Server node
789

of the System Tree.

4.6 Workspaces and Server Connections

There are two important terms that can be easily mixed up: Workspace and Server Connection. Both terms are widely used in this manual. Workspaces are used only if AggreGate Client operates in unified operations console server connections are also managed manually.
776

mode. In this mode

In all other modes AggreGate Client has no workspaces and a single server connection to the server it's launched from. A Workspace is just a special directory on the AggreGate Client installation that stores the data used by a single AggreGate Client user. Note that this is the AggreGate Client user - a person who actually uses this specific installation of AggreGate Client to control one or more AggreGate Servers. It is not the same as user account 108 on the AggreGate Server. Even though every AggreGate Client user usually has an AggreGate Server user account, it's important to keep the distinction. A AggreGate Client user may have more than one AggreGate Server user account, and theoretically, you could also have someone run the AggreGate Client without having any valid AggreGate Server user account to work with (to test it, etc). The AggreGate Client itself would still work (you couldn't do much with it, but it would work...). A Workspace: Contains definitions of zero or more server connections, Contains a window layout (windows size, position, docked/floating status, etc.), Is stored in the AggreGate Client installation folder, Is encrypted (the workspace password unlocks it), Is never transferred to the server completely or partially. A server connection: Is stored within the workspace (securely encrypted), Includes server address, port, name of user account on the server and password to this account, Is just a local configuration definition - AggreGate Client will attempt to connect to the AggreGate Server installation using these credentials. If they're correct (i.e, the server is where it's supposed to be, and an account which matches the credentials), it will work.

Workspaces
Workspaces are stored in the /workspaces folder of the AggreGate Client directory, i.e. /workspaces/test/*.* contains the test workspace. Workspaces can be transferred between the AggreGate Client installations, but workspaces saved in older AggreGate Client versions may not load correctly on newer versions.

2000-2013 Tibbo Technology Inc.

780

AggreGate Documentation

4.7 Main Window

The main AggreGate Client frame consists of Main Menu 780 , Dashboards with different windows, and a Status Bar. By default, there is only one dashboard window called Main Dashboard. Default layout of the main dashboard includes the following windows: A System Tree
784 791

One or more Event Log's Favourites Trackers

824

window

824

window
795 ,

Other windows, such as Properties Editor use.

Widget

312 ,

or Report Viewer

814

windows, may be added during normal

The System Tree, Properties Editor, Trackers, Event Log and other windows are dockable

781 .

4.7.1 Main Menu

There are three menus in AggreGate Client Main Menu: File, View and Help.

File Menu
Save Workspace . Saves current workspace immediately, without waiting until shutdown. Switch Workspace . Saves and closes current workspace
779

and allows another one to be loaded. (Alt+R)

Exit . Save current workspace and exit AggreGate Client. (Alt+X)

2000-2013 Tibbo Technology Inc.

AggreGate Client

781

View Menu
Reset layout. Set sizes and positions of all windows and components to default. System Tree. Show/hide System Tree Favourites. Show/hide Favourites Trackers. Show/hide Trackers
824 . 824 . 784 .

When the System Tree is shown, this item has a check mark next to it.

When the favourites are shown, this item has a check mark next to it.

When the trackers are shown, this item has a check mark next to it.
225 .

Alerts . Disable this checkbox menu item to suppress popup alert notifications and sounds always enabled by default, its state is not saved in the workspace.

This menu item is

Auto Run. Disable this checkbox to prevent auto run 625 actions execution for all server accounts. The auto run actions won't be launched when this workspace will be opened next time(s). Value of this item is always enabled by default, its state is saved in the workspace. Show all Event Logs. Shows Event Log for every active server connection. Hide all Event Logs. Hides all Event Logs.

Help Menu
Open Help. Open AggreGate manual in a browser window (HTML). Open Interactive Guide. Starts the Interactive Guide About . Shows software version and copyright.
847 .

4.7.2 Status Bar

The Status Bar contains an animated progress bar with a description. The bar shows the current state of AggreGate Client: Idle. Indicates that there are no commands in progress and no network I/O is performed. Loading. Indicates that AggreGate Client is currently executing operations with one or more servers, and data transfer is in progress. Some operations may report progress or current status by posting messages to the status bar. For example, AutoDiscovery of External Device Servers 1013 reports its status as follows:

- Auto-Discovery started - Found admin.c1 at 0.1.2.3.4.5 (192.168.1.100) - Found admin.c2 at 0.1.2.3.4.6 (192.168.1.101) ...

4.7.3 Customizing Dockable Windows

Every window in AggreGate Client has a title bar that provides some information about the window, and can be docked or floating. The bar has several buttons: Help. Opens documentation for the component displayed in the dockable window. Maximize Window. Maximized window occupies the whole AggreGate Client frame. Restore Window . Restores window back from its maximized size. Enable Pane Floating . Undocks a window and makes it floating above the AggreGate Client frame. Disable Pane Floating. Docks a floating window back to its previous location in AggreGate Client frame. Enable/Disable Side Bar Mode . With a window is located in a side bar, it is reduced to an icon on one of the edges of the main AggreGate Client frame. Hovering over this icon will display the window. Hide Active Side Bar Window. Hides a visible Side Bar window back to the Side Bar. Close Window. Closes a dockable window. Some windows may not have all these operations available.

2000-2013 Tibbo Technology Inc.

782

AggreGate Documentation

Many operations allow to specify location their data window(s) as a parameter and store it on the server. See details in Window Location 955 section.

Window Operations
Every window can be dragged by its title bar and dropped in any of the following positions: As a dockable window that is docked to other windows As a floating window that "floats" over other windows As a side bar window that normally appears as an icon in the corner of the client frame, but can be expanded when the icon is clicked (or on mouse-over). As a new tab for a tabbed windows. This happens when you drop a window directly on top of another window. And of course, many windows (like the System Tree 784 window, or Event Log (closed) and later restored using the corresponding Main Menu 780 items. The window's default appearance is similar to this:
791

windows) may be also hidden

This is what it looks like when the windows have been undocked and dropped onto one another, to create a floating tabbed pane. Note the tabs at the bottom:

2000-2013 Tibbo Technology Inc.

AggreGate Client

783

And this is what it looks like when the windows have been undocked and are used as floating mini-windows in cascaded form:

2000-2013 Tibbo Technology Inc.

784

AggreGate Documentation

If you've played around too much and now your layout is messy, you can always reset it using the main menu

780 .

4.7.4 Simple Mode

AggreGate operators often do not need any of the AggreGate Client standard components (such as System Tree 784 and Event Log 791 ) to perform their everyday duties. They use only custom-developed widgets 312 grouped into dashboards 617 to perform regulated monitoring and control tasks, such as supervising a network segment of controlling a manufacturing process. Such operators may start AggreGate Client in so-called Simple Mode. In this mode, no windows open automatically upon startup. However, connections to all servers registered in the workspace 779 are established. Once connected to a server, AggreGate Client launches all auto-run actions 625 from the server in normal mode. These actions should open necessary dashboards that provide access to everyday operations. Simple Mode is activated by -s command line switch
47

4.8 System Tree

The System Tree is probably the most important component of AggreGate Client. It is used to: Manage AggreGate Server connections. Provide access to workspace configuration. Browse and administer various server resources and devices (i.e. server contexts
863 ).

2000-2013 Tibbo Technology Inc.

AggreGate Client

785

The System Tree consists of a toolbar, the tree itself and a context-sensitive list of related actions . Every tree node represents a context 863 (and may have sub-contexts under it). Click here tree.
868

to check the difference between context tree visible in System Tree and server-side context

System Tree Toolbar

The toolbar provides an easy way to access frequently used operations: Refresh Node Refreshes the currently selected node and all sub-nodes.

2000-2013 Tibbo Technology Inc.

786

AggreGate Documentation

If used for a Server Node the server. Expand Node Recursively Collapse Node Recursively Search/Filter Text Field

789 ,

this button forces AggreGate Client to reconnect to

Expands the selected node and all its children recursively. This button is disabled if selected node is a leaf (i.e. has no children). Collapses the selected node and all its children recursively. This button is disabled if selected node is a leaf. Enables node searching/filtering
789 .

There are two types of node expansion and collapse: normal and recursive. Normal expansion and collapse are performed when you click on a [+] or [-] icon next to the node. Recursive expand and collapse operations are activated using node context menu or System Tree toolbar. Normal mode expands only the node itself, and any children-nodes which can be expanded remain collapsed. Recursive mode expands a given node as well as all of its child nodes which can be expanded. The same applies to collapse operations. The toolbar is also used to search and filter
789

nodes.

Related Actions
The related actions list is the same as the bottom part (after the horizontal separator) of the context menu currently selected node(s). You can use it to launch an action with a single click.
786

for the

Tooltips for the action list items show action names , rather than descriptions. These action names are needed for referring to these actions in many components of the system.

4.8.1 Context Menu

When you right-click a System Tree node, a context menu is shown. The context menu of every node includes several items: Refresh Node Expand Node Recursively Collapse Node Recursively Other options are node-specific. Operations which appear before the horizontal separator are specific to the current System Tree node and defined in the AggreGate Client itself (so, these are not AggreGate Server actions 892 ). Operations that appear after the horizontal separator launch an action 892 from the AggreGate Server context 863 corresponding to the System Tree node. The action usually interacts with the user by executing different UI Procedures 896 . Menu item corresponding to a default action
893

(i.e. action started upon double-click on a node) is highlighted in bold.

2000-2013 Tibbo Technology Inc.

AggreGate Client

787

For some nodes, the context menu also contains a "Group Actions" submenu. It contains action you can apply on every child of the current node. See action grouping 894 for more info. Here's what the System Tree context menu for a AggreGate Server node
789

looks like:

Working With Multiple Nodes

To select a range of nodes, click a node, hold down the Shift key and click another node. The two nodes, and all nodes in-between, will be selected. To select multiple nodes which are not in a single range (i.e, with unselected nodes inbetween) hold down the Ctrl key and click the nodes you wish to select. If you right-click a selected node, you'll get a context menu with operations that are related to all selected nodes. For more information on which actions appear in the context menu when several nodes are selected and how they behave, see action grouping 894 .

4.8.2 Drag and Drop Operations

The System Tree supports Drag and Drop. To initiate a Drag and Drop operation, left-click a node, hold it, and drag it on top of another node (This is dragging). Now release the mouse button, and "drop" the node onto its target. You can't always drop the node - sometimes it makes no sense (like dropping a Device on an Alert node - what is AggreGate Client supposed to do now?). If you can drop the node, the mouse cursor will change. If the node you're trying to drop onto (your target) is currently "inside" some other collapsed node, just hold your cursor over the parent node for some time, and it will expand. If the target node supports several Drag and Drop Actions select a single action using a context menu:
895

that for the dropped context, the user will be prompted to

It's convenient to add multiple objects to a group 248 by opening the group in a separate System Tree using Search/Filter 909 action and drag-and-droping objects from the "main" System Tree to the group node in group's System Tree.

2000-2013 Tibbo Technology Inc.

788

AggreGate Documentation

4.8.3 Copy and Paste Operations

The Copy and Paste context menu commands work exactly like Drag and Drop 787 operations between nodes. Copying node A and pasting it on node B is just like dragging node A and dropping it on node B . If a System Tree node is associated with a AggreGate Server context 863 (as most are), copying it and then pasting in any text field will insert the full path for the context within the server. For example, if you go to Queries > All Users, right-click that node and select copy, your clipboard will now contain the full path to this context - users.admin.queries.all_users. This can be useful to specify a context name when creating new alert 216 , or wherever you need the full path for a context.

4.8.4 Node Reordering

Some nodes support manual sorting, or "reordering", of their children. For these nodes, you can drag a child node and drop it between other child nodes when the "put-in-between" mark (a short horizontal line) is visible:

This feature helps to: Reorder server accounts Change launch sequence of Auto-Run Actions Reorder Trackers
257 625

and Group

248

members

2000-2013 Tibbo Technology Inc.

AggreGate Client

789

4.8.5 Node Searching and Filtering

Note searching/filtering is activated by typing some text in the filter text field located inside the System Tree toolbar Drop-down menu of filter text field allows to specify the following filter options: Capital letter processing: case sensitive or case insensitive Filter mode: normal , wild cards, or regular expressions 1318
785 .

Pattern matching mode: match from start, match exactly or match anywhere Match leaf nodes only Hide nodes without children Keep children if any of their ancestors match

4.8.6 Custom Nodes

Some nodes in the System Tree do not directly correspond to AggreGate Server contexts. These nodes are used by the AggreGate Client itself: Workspace Configuration Servers Server
791 789

789

4.8.6.1 Workspace Configuration Node

This is a node within the System Tree
784 ,

letting you configure your Workspace.

Custom Actions
CONFIGURE WORKSPACE (default action)
This lets you edit the configuration for the currently open workspace. Currently, there is only one workspace configuration parameter: workspace password. This is the password used to encrypt the passwords for the server connections 779 contained in the workspace.

4.8.6.2 Server Node

The Server System Tree 784 node is the root of all nodes associated with a particular AggreGate Server. It provides access to basic server control operations.

This node has three states: Connected ( Disconnected ( Disabled ( ) ) )

Connection with the server is automatically established when the node is added or AggreGate Client is launched. If connection or login fails for some reason (server not available, invalid password etc.), the node is shown in Disconnected state. If login fails, you will be prompted to register a new user account on the server:

2000-2013 Tibbo Technology Inc.

790

AggreGate Documentation

Registering a new account is possible only if "Users self-registration" global configuration option 53 is enabled in AggreGate Server global configuration. You'll get the prompt even if this option is disabled on the server, because AggreGate Client has no way of telling whether or not it's enabled. AggreGate Client constantly monitors the connection with every AggreGate Server. Is the server becomes unavailable at any time, the node is shown as Disconnected . If a Server node is in the Disconnected state, AggreGate Client will periodically attempt to connect to it. To manually initiate a connection attempt, double-click the node.

Custom Actions
EDIT SERVER CONNECTION PARAMETERS
This is a default action when connection with the server is established. If not, double clicking on a node causes AggreGate Client to try connecting to the AggreGate Server. This action is used to change the settings for the current Server Connection IP Address or Host Name. Address of the server. Port Number. Port used for AggreGate Client connections. Username. Name of user account
108 779 :

on the server.

Password. User account password. Description . Server name or other textual description of account. Disabled. Flag that indicates that the account is disabled. AggreGate Client does not attempt to establish a connection using disabled accounts. Connection Timeout. Specifies how long will the client wait until a non-responding server will be considered unavailable. This parameter should be increased for remote servers available via slow or unreliable connections. Command Timeout. Specifies maximum execution time for a single command. This parameter should be increased in rare cases when the server has some extremely slow operations, e.g. building of a report may take several hours.

REMOVE SERVER CONNECTION

Permanently removes the Server Connection from the workspace.

OPEN SERVER LOG

Opens an Event Log 791 that shows events from the server log 74 . Only Info-level This action is available only if AggreGate Client is running in admin 779 mode.
79

events (or higher) are shown.

OPEN DEVICE BROWSER

Opens a Device Browser 825 component for the current server. This action is available only if AggreGate Client is running in admin 779 mode.

VIEW CONNECTION STATISTICS

Shows statistical information related to this server connection: Connection duration Number of commands executed via connection Average server response time Incoming and outgoing traffic Number of failed (non-replied) commands This action is available only if AggreGate Client is running in admin
779

mode.

2000-2013 Tibbo Technology Inc.

AggreGate Client

791

4.8.6.3 Servers Node

Provides access to the list of Server Accounts
779

registered under the currently open workspace.

Server accounts located under the Servers node may be reordered using Drag and Drop.

Custom Actions
NEW SERVER CONNECTION (default action)
Registers a new Server Connection
779

under the current workspace:

IP Address or Host Name. Default address is 'localhost', it is used when AggreGate Server is installed on the same machine as AggreGate Client. Port Number. AggreGate Server port used for AggreGate Client connections. Default is 6460. Username. Name of user account
108

on the server.

Password. User account password.

4.8.7 Local Server Auto-connection

If no server connections are configured upon AggreGate Client startup (i.e. there are no Server 789 nodes under Servers 791 node), AggreGate Client tries to connect to a AggreGate Server running on the default port of the local machine. If the connection is successful and AggreGate Client is able to login to the server as default administrator (with default login/password), it proposes to create a new Server Connection automatically:
109

This feature makes it easier for users new to the system to get access to the AggreGate Server for testing purposes and initial system set-up.

4.9 Event Log

The Event Log component is intended for viewing and managing server events provides access to event history 882 and allows to acknowledge 882 events.
880

in the real-time mode. It also

To allow using Event Filters 206 , AggreGate Client creates one Event Log component per every server connection 779 when it is active (established). Event Log component is automatically closed when connection to the corresponding server is broken. Event Log window consist of two main parts: Current Events and Event History:

2000-2013 Tibbo Technology Inc.

792

AggreGate Documentation

Both parts have a toolbar that helps to access frequently used functions. In the left part of both toolbars the is a drop down box that allows to select an Event Filter. Initially, these the selected filter is <Empty Filter> what means that no events are shown. In some cases Event Log component shows a predefined set of event types. In this case list of Event Filters and related buttons ("Reactivate Filter", "Configure Filter") are not available. Columns of event tables can be resized and reordered. To resize a column click on its margin and drag the mouse to left or right. To change column order, drag column header and drop it to a new location. Column size and order is applied to the current filter only. It is stored in the workspace and reused when AggreGate Client is restarted. It is also possible to sort events. To enable sorting, click on the column header. Subsequent clicks will change sorting order for this column between ascending and descending. Double-clicking the separator between headers of two columns will auto-fit the left-hand's column width (i.e, resize it to fit everything in it). It is important to note that sorting of event history is performed on the server, so it may take considerable time. Double clicking on any event opens Data Table
854

associated with it in a Data Table Editor

801 .

Event Log uses Date Pattern , Time Pattern and Timezone settings specified in User Account Properties to properly convert and render different timestamps. All date/time values are shown in active user's timezone.

110

Event Level Indication

Event Level column uses a set of icons to indicate level Icon Event Level None (event level not defined) Notice Info Warning Error Fatal
882

of events:

2000-2013 Tibbo Technology Inc.

AggreGate Client

793

4.9.1 Current Events

Current Events table shows events happening on the server in the real time. Events are filtered according to the currently selected Event Filter 206 or by the custom filtering rules specified by the server during execution of Show Event Log 898 UI Procedure. In order to minimize the amount of transferred data, filtering is performed on the server.

Current Events Toolbar

The drop-down box selects Event Filter
206

that will be used to filter events that will be shown in the log.

Reactivate Current Filter. This operation allows to re-enter filter parameters. Configure Current Filter. Edit settings of currently selected filter. Enable/Disable Horizontal Scrolling. If disabled, width of all columns is adjusted automatically to fit the width of Event Log window. If enabled, Event Log has a horizontal scrollbar and width of all columns is adjusted to fit their contents. This option is disabled by default. View Severity Statistics. Shows the number of events of each level Export . Exports
795 882

in the Current Events window.

events currently shown in the Current Events window to a file.

Clear Current Events . Clearing the current events table doesn't remove these events from the server and doesn't prevent new events from appearing in the table.

4.9.2 Event History

Event History displays events that happened in the past and were saved by the server. Events are filtered according to the currently selected Event Filter 206 or by the custom filtering rules specified by the server during execution of Show Event Log 898 UI Procedure. Not all events are persistently saved in the history. Thus, event that has appeared in the Current Events section is not guaranteed to appear in Event History.

Event History Toolbar

Event Filter
206

selected in the drop-down box is used to filter out events that will be shown.

Reactivate Current Filter. This operation allows to re-enter filter parameters. Configure Current Filter. Edit settings of currently selected filter. Enable/Disable Horizontal Scrolling. If disabled, width of all columns is adjusted automatically to fit the width of Event Log window. If enabled, Event Log has a horizontal scrollbar and width of all columns is adjusted to fit their contents. This option is disabled by default. View Severity Statistics. Shows the number of events of each level history. Export . Exports
795 882

in the currently loaded event

events currently shown in the Event History window to a file.

Only events shown in the currently selected range will be exported. To export larger number of events, increase value in Events combo box (see below). Refresh. Refreshes event history. This operation causes the server to reload the history according to the current filter. The actual visible events may change after this operation. First. Scrolls history list to the first page. Previous . Loads previous page of the history list. Next. Loads next page of the history list.

2000-2013 Tibbo Technology Inc.

794

AggreGate Documentation

Last. Scrolls history list to the last page. The Events combo box in the middle of toolbar defines how many events are shown at once. The total number of events corresponding to the filter and range of currently shown events is indicated in the right part of toolbar.

4.9.3 Context Menu

Context menu is available upon right click on one of the events in the Event Log. It includes the following items: Show Event Data. Opens Data Table
854

associated with the event in the Data Table Editor

801 .

Acknowledge Event. Allows user to set event acknowledgement. This operation is available only for persistent events. View Acknowledgements . Shows event acknowledgements available only for persistent events. View Enrichments. Shows event enrichments persistent events.
883 882

in the Data Table Editor

801 .

801 .

This operation is

in the Data Table Editor

This operation is available only for

Delete Event. Permanently deletes event from event history. This operation is available only for persistent events.

Event-sensitive Menu Items

Event context menu also contains a Related Actions submenu with list of actions event was occurred or related to the event 895 itself.
892

related to the context

863

where

For example, for a Device-related event, "Reboot Device", "Configure Device" and other operations may be shown. Event context menu example:

4.9.4 Acknowledging Events

Event acknowledgement operation function is available for persistent events only. When Acknowledge Event menu item is activated, user is prompted to enter acknowledgement text:

When acknowledgement is set, its time, author and text appear in the Acknowledgements column of the events table:

2000-2013 Tibbo Technology Inc.

AggreGate Client

795

4.9.5 Exporting Events

Event Log has support for event exporting to a number of well-known file formats. When events are exported, a Data Table 854 containing events data is prepared first. This table contains the following fields: Event Time Events Context Event Name Event Level Event Data (contents of event's Data Table encoded into a string) One additional field per every field declared in event format Here is a list of supported export formats: Extension Description TBL XML HTML CSV XLS AggreGate Native Format Extensible Markup Language Hypertext Markup Language Character Separated Values Microsoft Excel User may specify a number of CSV encoding/decoding settings before export/ import takes place. Notes Data Table is encoded according to Data Table Encoding written to a file.
1306

standard and
1312

Data Table is encoded according to Data Tables XML Encoding and written to a file.

standard

4.10 Properties Editor

The Properties Editor is used to change the properties of different contexts Server itself and Devices are edited in a Properties Editor.
863 .

For example, settings for AggreGate

Technically, the Properties Editor allows changing the values of one of more variables 869 (properties) of a context. When the editor starts up for a given context, it loads the value of every variable for the context, and then allows the user to edit these values and writes them back to the context. Every property (variable) is edited in a separate Data Table Editor single Data Table 854 . The Properties Editor consist of a Toolbar and a Properties Pane:
801

component, because a property is actually a

2000-2013 Tibbo Technology Inc.

796

AggreGate Documentation

Toolbar
Reload. Reloads values of all properties from the source context. Values that were recently changed in the editor are lost. Save . Saves values of changed properties to the source context. Saved values are marked as unchanged. Enable/Disable Tabbed Layout. Switches Properties Editor from tabbed layout to single page layout and back. Toggle Read-only. Temporarily switches editor to and from the read-only mode Import properties. Import Export properties. Export
800 796 .

values of properties from the file. values of properties to the file.

800

Help. Shows documentation for the properties being edited. If Properties Editor is shown inside a dialog window, it has OK and Cancel buttons. The OK button saves the values of any properties which were modified, and closes the dialog. The Cancel button aborts the operation without saving. Most elements of the Properties Editor, as well as the actual properties, often have tooltips. These appear when the mouse cursor hovers over the element for some time.

Context Menu
The context menu is shown when right-clicking one of the properties in the Properties Editor. It contains a list of Variable-Related Actions 895 that "know" what to do with the selected variable. The number and types of available Variable-Related actions depend on the type of variable for which the context menu is shown.

Properties Editor Modes

The Properties Editor may work in two modes: Normal mode Read-only mode Read-only mode doesn't allow properties to be edited or saved. There are also two representation modes of Properties Editor: Simple Mode Expanded Mode

2000-2013 Tibbo Technology Inc.

AggreGate Client

797

Property Representation Modes

SIMPLE MODE
In Simple Mode, every Data Table Editor representing the value of a single property is shown directly in the Properties Pane. It is not opened in a separate window. On the below picture, a Data Table Editor containing the value for a single property is marked with a red rectangle:

If tabbed layout is enabled, the value of every property is shown in a separate tab. The property's name and detailed description are shown in a tooltip of its tab:

If tabbed layout is disabled, all properties are shown on a single page. The value of each property is shown in a separate collapsible pane. This pane may be collapsed and expanded by clicking on it. The property's name and detailed description are shown in a tooltip of its collapsible pane:

2000-2013 Tibbo Technology Inc.

798

AggreGate Documentation

EXPANDED MODE
In Expanded Mode, properties are grouped according to their variable group 870 . Properties of every group are represented as a table with two or three columns. The first column is optional, and may contain a status icon for the property. The properties editor constantly monitors the status of every variable and updates the status icon with every change. Hovering the mouse over the icon pops up a tooltip with the status details:

The Property column contains property descriptions. Cell tooltips provide information about each property's name and its detailed description:

The third column's contents changes according to the variable definition 869 of the context being edited. If the Data Table 854 representing the value of a property always has just a single field with a single record, the Data Table Editor 801 is shown directly in the third column. In other cases, the third column will contain a [Click to open...] button, which would open a Data Table Editor in a new window. A Data Table Editor that is embedded into the table is marked in red on the picture below:

2000-2013 Tibbo Technology Inc.

AggreGate Client

799

If tabbed layout is enabled, the properties of each group are shown in a separate tab. Group names are shown as tab headers:

If tabbed layout is disabled, all properties are shown on a single page. The properties of every group are shown in a separate collapsible pane. This pane may be collapsed and expanded by clicking on it. Group names are shown as headers of collapsible panes:

2000-2013 Tibbo Technology Inc.

800

AggreGate Documentation

In expanded mode, the background color of modified properties changes from gray to dark gray:

Importing and Exporting Properties

Properties can be exported to and imported from external files. By default, property files have a .prs extension. Properties are imported by name: if the Properties Editor contains a property with the same name as one saved in the file, their values are merged by a Data Table Smart Copy 861 operation. Properties import procedure cannot just override values contained in the editor with ones read from a file because they may have different format 855 . But in any case the best efforts are made to import as much data as possible.

Keyboard Navigation
Alt-L Als-S Reload properties Save properties

2000-2013 Tibbo Technology Inc.

AggreGate Client

801

4.11 Data Table Editor

The Data Table Editor (DTE) is a component used to edit or view a single Data Table 854 . It is used by the Properties Editor 795 to edit context 863 variables 869 , by the Event Log 791 to view Data Tables associated with events 880 , by the Edit Data 896 UI Procedure to edit function 878 input parameters and view its output, etc.

Most elements of the Data Table Editor, such as column headers and data cells, usually have tooltips which pop up when the mouse hovers over the element. The tooltip for the column header contains the field type and help string specified in the table's format
855 ,

if any.

The tooltip for a cell contains a string representation of the cell's value, and the type of field used for this cell. For example, it may be useful: If a cell's value too long to fit into the cell itself, If the cell editor has selection values box.
856

and you want to see the value itself, not its description from the drop-down

If cell tooltip provides some important extended information, the cell is marked with a small blue triangle:

Table columns can be resized and reordered. To resize a column click on its margin and drag the mouse to left or right. To change column order, drag the column header and drop it in a new location. Double-clicking the separator between headers of two columns will auto-fit the left-hand's column width (i.e, resize it to fit everything in it). Data Table Editor uses Date Pattern , Time Pattern and Timezone settings specified in User Account Properties 110 to properly convert and render different timestamps. All date/time values are shown in active user's timezone.

Data Table Editor Modes

Data Table Editor may work in two modes: Normal mode Read-only mode In the read-only mode editing is disabled.

2000-2013 Tibbo Technology Inc.

802

AggreGate Documentation

There are also two data presentation modes: Multiple records mode Single record mode In multiple records mode, the table header shows the description for every column, and every row represents one Data Table record:

Single record mode is used by the DTE when the table being edited contains just one record, and no extra records may be added. This mode features a two-column layout: the left column shows field names, and the right one contains values:

Toolbar
The Data Table Editor toolbar provides access to the operations that may be performed with the data table Add Row
854 .

Insert a new row before the currently selected one. If no row is selected, a new row is added to the end of table. This button is disabled or hidden if rows may not be added to the table. Remove the currently selected row(s). This button is disabled or hidden if rows may not be removed. Move current row up. This button is not shown if rows may not be reordered. It changes actual data in the table (in contrast to the sorting operation, which merely changes how the data is shown.) Move currently row down. This button is not shown if rows may not be reordered. It changes actual data in the table (in contrast to the sorting operation, which merely changes how the data is shown.) Undo all changes that were made to the table. This button is enabled only after a change is made. If horizontal scrolling is disabled, width of all columns is adjusted automatically to fit the width of Data Table Editor window. If scrolling is enabled, Data Table Editor has a horizontal scrollbar and width of all columns is adjusted to fit their contents. This option is disabled by default. Imports Exports
810

Remove Selected Rows Move Row Up

Move Row Down

Reset Changes Enable/Disable Horizontal Scrolling

Import Data Table Export Data Table Make Report Help

data from a file. data to a file.

812

810

Generate a report

based on the table being edited or viewed.

Open documentation article related to the data being edited/viewed.

Some (or even all) toolbar buttons may be hidden or disabled if their respective operations are not available in the editor. A button is hidden if the operation is not applicable to the current table at all. If an operation is simply not available at the moment (e.g. the Remove Selected Rows is disabled when no rows are selected), its button is disabled.

2000-2013 Tibbo Technology Inc.

AggreGate Client

803

Processing Data Bindings

The Data Table Editor handles bindings 860 contained in the format 855 definition of the Data Table being edited. When the editor loads, it reads the list of bindings for the table and processes them in the background. Bindings are evaluated and used to change cells in the table being edited. Binding expressions used by Data Table Editor may contain relative links to the cells of the table being edited, along with links to data from various contexts 863 . To find out how to create these links, learn more about data bindings here 854 .

4.11.1 Editing Data

If the Data Table Editor is in the editable mode, the values within the table may be changed. Renderer and editor used to display and modify value in each cell depends on several factors. Field type Editor/Renderer specified in field declaration Availability of Selection Values Whether the field value is NULL
856 856

(that is a part of Table Format)

declared for this field in Table Format

Special Renderers/Editors
There are some special cases when non-standard editors are used:

NULL VALUE RENDERER

If the field is declared as Nullable and its value is NULL , it is shown as <Not Set> in DTE. Click the cell to start editing and set a non-null default value for it. You can reset the value back to NULL using the Remove value operation in the cell context menu.

SELECTION VALUES EDITOR

If a field format contains selection values
856 ,

editing is performed using a drop-down box:

If Extendable Selection Values

856

flag is set in Field Format, any custom value can be typed inside the combo box:

Standard Renderers/Editor
STRING/INTEGER/LONG/FLOAT FIELDS
Integer, Long, String and Float values are edited in a normal text field:

BOOLEAN FIELDS
Boolean values are edited using checkboxes and are represented by Yes (for TRUE) or No (for FALSE) in read-only mode:

2000-2013 Tibbo Technology Inc.

804

AggreGate Documentation

DATE FIELDS
Date and Date/Time values are edited using a Date Picker:

COLOR FIELDS
Colors are selected using a Color Picker:

DATA TABLE FIELDS

Data Table fields (i.e. fields whose values are actually entire data tables) are edited by a nested Data Table Editor that appears in a separate dialog. The dialog pops up when you click in the cell containing the embedded Data Table:

2000-2013 Tibbo Technology Inc.

AggreGate Client

805

DATA BLOCK FIELDS

Default Data Block editor allows to choose and save a file of any type from/to AggreGate Client's local file system:

Additional Renderers/Editors
DATE-ONLY EDITOR
Date-only editor allows to specify a date using Date Picker, but time specification is not allowed:

TIME-ONLY EDITOR
Time-only editor allows to specify a time in string form, but date cannot be selected:

BAR RENDERER
Bar renderer shows Integer , Long , Float and String values as percentages of maximum defined by Editor Options:

2000-2013 Tibbo Technology Inc.

806

AggreGate Documentation

String values are converted to numbers on the best effort basis.

PERIOD EDITOR
Period editor allows to specify a time period as a certain number of selected time units:

PASSWORD EDITOR
Password editor is very similar to the usual text area, but types characters are now shown:

Values cannot be copied from cells that use this editor.

REFERENCE RENDERER
Reference editor displays clickable references (links) in blue underlined font:

Clicking on a reference initiates a server-side action. Right-clicking on a link brings a context menu of object that the link points to.

TEXT AREA
String values can be alternatively viewed and edited in a Text Area editor that is shown in a separate window:

TEXT EDITOR
Another option for editing String values is the more advanced Text Editor code, XML document or other text data suitable for syntax highlighting.
819 .

It is used when a String field contains Java

CODE EDITOR
Yet another option for editing Strings is Code Editor 820 . It's used when a string contains some Java source code, i.e. Java class representing a server script 628 or widget script 610 .

2000-2013 Tibbo Technology Inc.

AggreGate Client

807

CONTEXT AND CONTEXT MASK EDITORS

String values corresponding to Context 863 paths and context masks component. It looks like a usual text field with a button on the right:
865

are specified using a Context Mask Selector

When editing the path/mask, you can press Space to get list of contexts that may be appended to the currently edited mask. Choose a context from the drop down list to append it to the current mask:

Pressing the [...] button opens an Entity Selector

815

component to allow building the mask by pointing and clicking.

EXPRESSION EDITOR
Expressions 911 are edited in a text field with a [...] button that opens an Expression Builder validating an expression in point-and-click mode.
817

to allow creating and

SOUND/IMAGE/FILE EDITORS
Data Block fields may contain images, sounds or generic files. Files, sound and images are inserted into the cells using a File Selector:

Images contained into the Data Table are displayed as a thumbnail (see previous screenshot). Clicking on a thumbnail opens a full-size image view.

2000-2013 Tibbo Technology Inc.

808

AggreGate Documentation

Vector images (in SVG format) can be also opened for editing in the Text Editor highlighting. Sounds can be played back directly from the table cell:

819

with XML syntax

BINARY DATA EDITOR

Custom binary data is modified in a special editor allowing to specify bytes in both HEX and ACSII form:

4.11.2 Context Menu

The Data Table Editor provides two different context menus: Cell context menu for manipulating table data Header context menu for controlling row/column visibility and grouping

Cell Context Menu

The context menu of Data Table Editor cells contains the following operations: Copy Paste Copy the value of a cell. Paste a value from the clipboard into a cell. If the value in the clipboard has another format than the cell value, AggreGate Client will attempt to convert it. If the value cannot be converted, it will not be pasted. Resets cell value to NULL (<Not set>). This operation is only applicable if current field is nullable, i.e. supports NULL values. Reset the cell value to the one it contained when the Data Table Editor was opened. If the cell didn't exist when the editor was opened (i.e. the cell belongs to a newly created row) this operation will reset its value to default (see below). Reset the cell value to the default for this column (usually defined on the server, as part of the table format description). Copy value from the selected cell to all other cells of current column. Creates a copy of current record. Resets all changes made to the table since it was opened. Shows format
855

Remove Value Undo Cell Changes

Reset Cell To Default Fill Column With Cell Value Duplicate Record Reset Table View Table Format

of current table.

VARIABLE RELATED ACTIONS

When the Data Table Editor is being used to modify the value of a context variable 869 (as opposed to raw data coming from another source), the context menu within the editor contains additional actions related to this variable 895 .

Header Context Menu

2000-2013 Tibbo Technology Inc.

AggreGate Client
The context menu of Data Table Editor header provides access to the following features: Auto Resize This Column Auto Resize All Columns Group This Column (soft ascending) Group This Column (soft descending) Expand All Collapse All Hide This Column Show All Hidden Columns Reset Columns To Default More... Select All Cells Clear Selection Auto-adjust size of clicked column to fit all data. Auto-adjust size of all columns to maximize the amount of visible data.

809

Enables row grouping by the values of current column's cells, with ascending sorting. Enables row grouping by the values of current column's cells, with descending sorting. Expand all row groups. Collapse all row groups. Hides current column. Shows all currently invisible columns. Resets columns widths. Opens a popup dialog allowing to select visible columns. Selects the whole table. Clears cell selection.

In addition, header context menu contains checkable menu items allowing to show/hide individual columns.

4.11.3 Sorting and Filtering

Sorting and filtering do not change or reorder the actual data in the table, but only its visible presentation.

Sorting Rows
You can sort the rows of a Data Table being edited or viewed. To enable sorting, click the column header. Clicking a header already used for sorting will reverse the sorting order.

Filtering Rows
Another convenient feature is data filtering. To enable filtering, enter some text in filter text field located in Data Table Editor toolbar (and indicated by a looking glass icon). Table contents will be filtered to show only rows matching to the filter. Context menu of the filter bar contains the following operations: Column Selection Case Sensitive Case Insensitive Use Wild Cards Use Regular Expressions Match From Start Match Exactly Match Anywhere Allows to perform searching in all columns or selected columns only. Enables case sensitive searching. Disables case sensitive searching. Enables/disables wildcard search mode. Wild cards may include * or ? characters that match any characters or any character, respectively. Enables/disables regular expression
1318

search mode.

Filter text must appear in the beginning of cell text. Filter text must exactly match cell text. Filter text may appear anywhere in the cell text.

2000-2013 Tibbo Technology Inc.

810

AggreGate Documentation

4.11.4 Row Grouping

The header context menu 808 of the Data Table Editor allows to group rows according to values of certain selected row (s). Here is an example of how a grouped table looks like:

Grouping is very handy for screening long tables.

4.11.5 Data Export/Import

Data Table Editor has embedded support for data exporting/importing from a number of well-known file formats. Here is a list of supported formats: Extens ion TBL XML HTML CSV XLS Description AggreGate Native Format Extensible Markup Language Hypertext Markup Language Character Separated Values Microsoft Excel Export Supported Yes Yes Yes Yes Yes Import Supported Yes Yes No Yes No Notes Data Table is encoded according to Data Table Encoding 1306 standard and written to a file. Data Table is encoded according to Data Tables XML Encoding 1312 standard and written to a file. See example below. User may specify a number of CSV encoding/decoding settings before export/import takes place.

During import operation, data read from a file is not inserted into Data Table Editor as is. Instead, it is merged with the data currently contained in the Data Table Editor using a Data Table Smart Copy 861 operation.

2000-2013 Tibbo Technology Inc.

AggreGate Client

811

Properties import procedure cannot just override values contained in the editor with ones read from a Excel file because they may have different format 855 . But in any case the best efforts are made to import as much data as possible. When importing data, it is possible to choose what fields will be imported. You can only import fields that exist both in the imported Data Table and Data Table currently being edited, and are writable in the table being edited:

If you are exporting to or importing from a Character Separated Values (CSV) file, you will be prompted to specify CSV encoding/decoding options 1325 .

Examples
Original Data Table:

The same table exported to CSV format (Header Record contains field descriptions, screenshot taken in a text editor):

The same table exported to HTML format (as shown in a web browser):

2000-2013 Tibbo Technology Inc.

812

AggreGate Documentation

The same table exported to XLS format (as shown in Microsoft Excel):

4.11.6 Report Creation

When the Data Table Editor is in Multiple Records Mode you can generate a report, based on the data being viewed or edited. Click the Make Report button on the toolbar and specify options 1325 for the report:

When you click OK, AggreGate Client generates 1325 a report design, fills it with the data from the editor, and opens the generated report in a Report Viewer 814 . You can then print it, or export it to PDF, HTML, CSV etc. This is what such a report looks like:

2000-2013 Tibbo Technology Inc.

AggreGate Client

813

4.11.7 Editing Bindings

In certain cases Data Table Editor allows to add, edit or remove bindings 860 of a table being edited. For example, this mode is enabled when the table will be used as an input parameter for a headless action 893 (i.e. action executed upon alert 216 of by the scheduler 266 ). If bindings editing is enabled, the top section of the Data Table Editor contains an expandable bindings pane:

Bindings are edited in a nested Data Table Editor that has two fields: Target. Defines the field (and optional row number) to write the expression result into. Expression . Defines binding expression
911

that will be calculated when table bindings are processed.

The Apply button instructs Data Table Editor to save new/modified bindings inside the "primary" table and recalculate table data according to new bindings.

2000-2013 Tibbo Technology Inc.

814

AggreGate Documentation

4.12 Report Viewer

The Report Viewer is used to view, print and save reports Viewer looks like:
241

generated by AggreGate Server. Here is what Report

The Report Viewer's main window consists of toolbar and the report itself. Toolbar provides access to the number of operations: Save Report. Export the report to a file. Print Report. Reload Report. First Page. Go to the first page. Previous Page. Go to the previous page.

2000-2013 Tibbo Technology Inc.

AggreGate Client

815

Next Page. Go to the next page. Last Page. Go to the last page. Go To Page. Go to a specific page. Actual Size. Zoom to the actual size. Fit Page. Zoom to fit a complete page in window. Fit Width. Zoom to fit page width in window. Zoom In. Increate zoom ratio. Zoom Out. Decrease zoom ratio. Zoom Ratio. Change zoom ratio. The Report Viewer can print reports, and also export to several file formats: PDF (Adobe Acrobat) RTF (Rich Text Format) XLS (Microsoft Excel, single or multiple sheets) HTML (Hypertext Markup Language) CSV (Character Separated Values, may be imported into many different applications) XML (Extensible Markup Language) To export a report, click the Save button. The Save File dialog is shown:

4.13 Entity Selector

The Entity Selector component is used to select AggreGate Server contexts and even specific fields within these. Click here tree.
868 863 ,

variables

869 ,

functions

878 ,

events

880

to check the difference between context tree visible in Entity Selector and server-side context

Content can be filtered so that only certain entity types are shown for selection. Here is what the Entity Selector looks like when used to select a single context:

2000-2013 Tibbo Technology Inc.

816

AggreGate Documentation

Here is what it looks like in GUI Builder

827

when selection of all types of entities is allowed:

Uses Of Entity Selector

1. The Entity Selector is used by the Select Entities
902

UI Procedure to select different contexts and their elements.

2. In GUI Builder 827 , the Entity Selector can be used to drag various entities and drop them on various components ("widgets") in the main window. 3. In Expression Builder 817 , a double-click on the Entity Selector's tree node adds new a Reference Expression 911 being edited.
925

to the

4. Finally, the Entity Selector is used to select contexts and context masks when editing context path/mask fields in a Data Table Editor 801 .

Icons Used In Entity Selector

If custom icons are defined for different contexts and their parts, these icons are shown in the Entity Selector's tree. In all other cases the following icons are used:

2000-2013 Tibbo Technology Inc.

AggreGate Client

817

"Closed" Context (for context nodes which are currently collapsed). This icon is shown if context doesn't provide a custom icon. "Open" Context (for context nodes which have been expanded). This icon is shown if context doesn't provide a custom icon. Group of variables, functions or events. Variable. This icon is shown if variable definition doesn't provide a custom icon. Function. This icon is shown if function definition doesn't provide a custom icon. Event. This icon is shown if event definition doesn't provide a custom icon. Action. This icon is shown if action definition doesn't provide a custom icon. Input field (for entering values for variables, events and functions). Description and type of field are shown. Output field (used by functions). Description and type of field are shown.

Searching/Filtering Nodes
Entity selector window has a filter field in the top. If something is typed in this field, only nodes those names contain typed text are shown.

4.14 Expression Builder

The Expression Builder component was designed to simplify writing of expressions in Expression Language component is used to edit expression text in a Data Table Editor 801 . Here is what the Expression Builder window looks like:
911 .

This

Expression Builder window consists of the following parts:

2000-2013 Tibbo Technology Inc.

818

AggreGate Documentation

Expression Text Area in the top that is used for directly editing expression text. Button Bar with two groups of buttons. Buttons on the left are used for inserting different operators and other Expression Language elements into the current caret position in expression area. Buttons on the right are used to validate expression syntax (Validate button) and calculate the expression result in the current environment ( Evaluate button). There is also a Functions combo box, for quick insertion of functions 914 . A Server Data area that contains an Entity Selector 815 component. Double-clicking on any entity inserts its Reference 925 into the current caret position in the expression area. A Components area that contains another Entity Selector allowing to insert references to widget component properties. This section is available only when editing widget binding expressions 606 . A Relative References list (not visible on the above screenshot) that shows relative references available in the current environment. If no relative references are available, this part is not visible. Double-clicking on a reference inserts its textual representation into the current caret position in expression area. Relative references are references with relative context part or with no context /entity specification at all. See References 925 article for details. A Reference Editor used to edit the reference that is currently selected in the expression area. Any part of a reference may be changed independently. When changes are made, expression text is updated. The Resolve button allows to calculate current value pointed by the edited reference. Evaluate button allowing to calculate expression output. The button image changes from the green checkmark ( to red cross ( ) if syntax of the whole expression (or its selected part, if any) is incorrect. Functions button that brings up the function selector, allowing to insert a function
914 :

Evaluating Expressions in the Builder

Expression Builder allows to validate syntax of absolutely any expression. In most cases it's also possible to calculate the result that the expression will produce. This can be done since Expression Builder knows about the evaluation environment 922 of current expression. However, the evaluation environment is not always complete, and in some cases

2000-2013 Tibbo Technology Inc.

AggreGate Client
it's not possible to evaluate the expression correctly from the Expression Builder. Here are some examples: If editing event filter
206

819

expression, there is no specific event that provides data for the expression.

Same applies for alert 216 's event trigger 222 expression - there is no event to test it with, and, thus, no "real" default data table in the expression evaluation environment.

4.15 Text Editor

Text editor component allows to edit text data in different formats (Java code, XML documents, SNMP MIB files, etc.). Text editor supports different syntax highlighting rules for different types of text documents.

Keyboard Shortcuts
This is a list of keyboard shortcuts supported by the text editor component. Shortcut Ctrl-A Ctrl-D Ctrl-I Ctrl-J Ctrl-C Ctrl-X Ctrl-V Ctrl-Z Ctrl-E, Ctrl-Z Ctrl-ShiftBackspace Description Select all Delete line Indent lines Join lines Copy Cut Paste Undo Redo Delete to line start

2000-2013 Tibbo Technology Inc.

820

AggreGate Documentation

Ctrl-Shift-Delete Ctrl-Left Ctrl-Right Ctrl-Up Ctrl-Down Ctrl-Shift-Left Ctrl-Shift-Right Shift-Left Shift-Right Shift-Home Shift-End Shift-Up Shift-Down Shift-Page Up Shift-Page Down Ctrl-Shift-Up Ctrl-Shift-Down Ctrl-Shift-Home Ctrl-Shift-End Ctrl-Backspace Ctrl-Delete Ctrl-Home Ctrl-End Ctrl-[ Ctrl-] Ctrl-E, Ctrl-[ Ctrl-E, Ctrl-] Ctrl-' Ctrl-/ Alt-' Alt-/ Ctrl-E, Ctrl-A Ctrl-E, Ctrl-U Ctrl-E, Ctrl-J Ctrl-E, Ctrl-N

Delete to line end Go to previous word Go to next word Go to previous paragraph Go to next paragraph Extend selection back by one word Extend selection by one word Extend selection back by one character Extend selection by one character Extend selection to line start Extend selection to line end Extend selection back by one line Extend selection by one line Extend selection back by one page Extend selection by one page Extend selection back by one paragraph Extend selection by one paragraph Extend selection to document start Extend selection to document end Delete character before caret Delete character after caret Go to document start Go to document end Select code block Go to matching bracket Go to previous bracket Go to next bracket Scroll up one line Scroll down one line Scroll up one page Scroll down one page Append selected text to clipboard, leaving it in the editor Append selected text to clipboard, removing it from the editor Scroll to current line Center caret on screen

4.16 Code Editor

Code editor component allows to edit code written in Java programming language, such as AggreGate Server scripts or widget scripts 610 . The code editor supports: Java syntax highlighting Find and replace
628

2000-2013 Tibbo Technology Inc.

AggreGate Client
Bracket matching Code folding Auto indent

821

Keyboard Shordcuts
The below table lists default keyboard shortcuts available in Code Editor. To edit them, click on Configure Keyboard Shortcuts label in the Code Editor's status bar. Name Shortcut Key Description

BASIC EDITING
Backspace Delete to Word Start Delete Delete to Word End Delete Current Line Insert Line Break Split Line Start New Line BACK_SPACE Control BACK_SPACE DELETE Control DELETE Control Y ENTER Control ENTER Shift ENTER Delete the previous char at the caret position. Delete previous chars until it see a non-word char. Delete the next char at the caret position. Delete next chars until it see a non-word char. Delete current line. Insert a line break at the caret position. Insert a line break at the caret position and keep current caret position. Start a new line next to the caret line and put caret at the beginning of the new line.

2000-2013 Tibbo Technology Inc.

822

AggreGate Documentation

Indent Selection Unindent Selection Join Lines Toggle Insert/ Overwrite Toggle Rectangular Selection

TAB Shift TAB Control Shift J INSERT Control BACK_SLASH Alt Shift INSERT Control Shift U

Indent the caret line if no selection and all selected lines if there is selection. Indent the caret line if no selection and all selected lines if there is selection. Join the next line with caret line if no selection, or join all selected lines as one line if there is selection. Toggle the override/insert status. Toggle from regular selection to rectangular selection.

Toggle Case

Toggle the case of the selection.

CHANGE CARET POSITION AND SELECTION

Select All Move Caret to Line Start Move Caret to Line End Select to Line Start Select to Line End Move Caret to Document Start Move Caret to Document End Select to Document Start Select to Document End Page Up Page Down Select to Previous Page Select to Next Page Move Caret to Previous Char Move Caret to Next Char Select Previous Char Select Next Char Move Caret to Previous Word Move Caret to Next Word Select Previous Word Select Next Word Control A HOME END Shift HOME Shift END Control HOME Control END Control Shift HOME Control Shift END PAGE_UP PAGE_DOWN Shift PAGE_UP Shift PAGE_DOWN LEFT RIGHT Shift LEFT Shift RIGHT Control LEFT Control RIGHT Control Shift LEFT Control Shift RIGHT Select all the text in the editor. Move caret to the start of the current line. Move caret to the end of the current line. Select from the current caret position all the way to the line start. Select from the current caret position all the way to the line end. Moves caret to the start of the code editor. Moves caret to the end of the code editor. Select from the current caret position all the way to the document start. Select from the current caret position all the way to the document end. Move caret one page up. Move caret one page down. Select from the current caret position up by one page. Select from the current caret position down by one page. Move caret one char left. Move caret one char right. Select the previous char of the current caret position. Select the current char of the current caret position. Move caret to the previous word the first space char before the current caret position. Move caret to the next word the first space char after the current caret position. Select the current caret position to the first space char before it. Select the current caret position to the first space char after it.

2000-2013 Tibbo Technology Inc.

AggreGate Client

823

Move Caret to Previous Line Move Caret to Next Line Select Previous Line Select Next Line Goto Line Select Word at Caret Select to Matching Bracket Duplication Selection Line Comments Block Comments

UP DOWN Shift UP Shift DOWN Control G Control W Control B

Move caret up by one line. Move caret down by one line. Select from the caret position up by one line. Select from the caret position down by one line. Prompt a dialog to let user type in a line index and scroll to it. Select the current word. Select the current block that starts and ends with two matching brackets.

Control D Control SLASH Control Shift SLASH

Duplication the selection. If no selection, the caret line will be duplicated. Using line style comment for comment a line or several lines. Using block style comment a line or several lines.

UNDO/REDO
Undo Redo Control Z Control Shift Z Undo the last editing operation. Redo the last undone editing operation.

CLIPBOARD OPERATIONS
Clipboard Cut Control X Shift DELETE Clipboard Copy Control C Control INSERT Clipboard Paste Control V Shift INSERT Clipboard Paste with Dialog Control Shift V Control Shift INSERT Prompt a dialog to allow user to select one of the previous clipboards and paste it. Paste whatever on the clipboard to the current caret position. Copy the currently selected text. If nothing is select, copy the current line. Cut the currently selected text. If nothing is selected, cut the current line.

FIND AND REPLACE

Find Find Next Occurrence Find Previous Occurrence Replace Quick Search Control F F3 Shift F3 Control R Alt F3 Prompt a dialog to allow user to type in a text to search for. Find the next occurrence of the searching text. Find the previous occurrence of the searching text. Prompt a dialog to allow user to type in a text to replace with another text. Using the Searchable feature to show a popup where user can type in a text without using a dialog.

FOLDING OPERATIONS
Fold Selection Expand Folding Collapse Folding Control PERIOD Control EQUALS Control MINUS Create a folding which contains the currently selected text. Expand the current folding. Collapse the current folding.

2000-2013 Tibbo Technology Inc.

824

AggreGate Documentation

Expand All Collapse All

Control Shift EQUALS Control Shift MINUS

Expand all the foldings. Collapse all the foldings.

4.17 Favourites
The Favourites window displays a list of Favourites 626 . It combines favourites obtained from all server connections that are configured in AggreGate Client. Clicking on a favourite launches a corresponding server-side action.
779

The table includes Favourites even from servers with which AggreGate Client does not have an active connection at the moment. Upon first connecting to a new server, AggreGate Client obtains the list of Favourites and retains it locally from this point onwards. Favourites component is based on Data Table Editor functionality.
801

and, thus, provides the same toolbar, context menu, and other

Context Menu
Context menu of the favourites table has two additional items: Configure. Starts Configure Favourite Delete. Starts Delete Favourite
905 904

action.

action.

Drag and Drop Operations

Drag any System Tree 784 node and drop it over the Favourites table to start the Add to Favourites creating new Favourite that runs a selected action from the context matching dropped node.
698

action. It will help

4.18 Trackers
The Trackers window displays a list of Trackers 257 . It combines trackers obtained from all server connections are configured in AggreGate Client. Color of the tracker indicate its state.
779

that

Trackers component is based on Data Table Editor functionality.

801

and, thus, provides the same toolbar, context menu, and other

Context Menu
Context menu of the trackers table has two additional items: Configure. Starts Configure Tracker Delete. Starts Delete Tracker
905 904

action.

action.

2000-2013 Tibbo Technology Inc.

AggreGate Client

825

Drag and Drop Operations

Drag any System Tree 784 node and drop it over the Trackers table to start the Build Tracker 752 action. It will help creating new Tracker that watches a selected variable from the context matching dropped node.

4.19 Device Browser

The Device Browser is used to browse the AggreGate Server context tree 863 , view and modify values for context variables 869 , call functions 878 and view events 880 using Event Log 791 components. The Device Browser component is provided for debugging and troubleshooting purposes only. It shouldn't be used during normal operation. Improper use of this component may damage the server database or otherwise destabilize the server. The Device Browser consists of two primary parts: the Context Tree and the Browsing Pane.

There are four types of Context Tree nodes: Context nodes that can be expanded Variable nodes, shown using normal font Function nodes, shown in bold Event nodes, shown in bold italics Expanding a context node forces the Device Browser to request the server for info about the node's children. Clicking on a context node shows information about that context's variables, functions and events. Double-clicking on a variable node shows its current value in a Data Table Editor
801 .

Double-clicking on a function node allows to enter function parameters using Data Table Editor. Then function is called and its output shown in Data Table Editor.

2000-2013 Tibbo Technology Inc.

826

AggreGate Documentation
791

Double-clicking on an event node opens Event Log

that starts monitoring this event.

4.20 Report Editor

Report Editor is a part of AggreGate Client 776 that is used to edit Report Templates 242 . It is used to change report layout, modify report sections (title, summary, page header/footer, column header/footer and details) and edit data expressions used to calculate data values shown in the report. The Report Editor window consists of several main parts: Main Menu for supervising operations Main Toolbar providing quick access to commonly used operations (such as undo/redo). Workspace used to view and access the report template, view/edit the XML source of template, and preview the final report. Report Window Toolbar allowing to access properties of selected elements (such as element alignment and font) Document Structure Pane containing report fields, parameters, bands (sections) and elements in a hierarchical tree. Output Console shows all messages related to compiling reports, filling them with data and the overall functioning of the Report Editor. Properties Pane used to view and edit properties of currently selected element(s). Palette Pane allowing to add new components to the report. Styles Library Pane provides access to commonly used element styles.

Editing Report Templates

When Report Editor is launched, it automatically opens a report template for editing. You can make any changes to it and save it at any time. To finish editing: Click File > Quit and decide whether you want to save your changes (if any):

2000-2013 Tibbo Technology Inc.

AggreGate Client

827

OR click the "Close Window" icon in the top-right corner to discard your changes and exit report editor immediately.

Previewing Your Report

It is possible to compile the report template and preview your report at any time. To preview the report, click on a Preview button in report window toolbar:

All reports are shown in Report Viewer 814 by default. However, it is possible to select a different destination using the Preview menu (located in main menu). Reports can be directly exported into PDF, HTML or TXT format.

Report Editor Manual

AggreGate uses the iReport Designer copyrighted by Jaspersoft Corporation for editing report templates. See iReport documentation for more information on how to modify report templates and use the different features of reporting engine, such as charts, sub-reports, expressions, and scriptlets.

Manual Report Editor Installation

Certain AggreGate Client bundles do not include Report Editor (iReport). To install iReport manually and connect it to existing AggreGate Client installation perform the following steps: Download iReport from its official website and install it to any directory Copy contents of iReport installation folder to the /reports subfolder of AggreGate Client installation folder Restart AggreGate Client You should be able to execute Edit Template action after manual iReport installation.

4.21 GUI Builder

GUI Builder is the part AggreGate of Client widgets from scratch.
776

that is used to edit widget

312

templates

314

or build

Main Window
GUI Builder always opens in a separate window:

2000-2013 Tibbo Technology Inc.

828

AggreGate Documentation

The main window has several primary components: Main Menu Toolbar
829 830 833 828

Work Form

Resources Window Entity Selector

834

Component Palette

834 835

Component Properties Window

Most components in GUI Builder are implemented as dockable panes and may be removed, resized, docked/undocked, put into tabs etc. For more information, see Customizing Dockable Panes 781 . Properties Editor 795 article has more information on using the Properties Editor. Component properties are described in the component reference 322 .

4.21.1 Main Menu

There are two menus in GUI Builder: File and View.

FILE MENU
New Template. Clears the template of the widget currently being edited. Open Template . Loads a new widget template from file. The template currently being edited will be lost.

2000-2013 Tibbo Technology Inc.

AggreGate Client
Save Template to File. Saves the currently edited template to file.

829

VIEW MENU
Items in this menu may be enabled or disabled. They are used to show or hide different parts of GUI Builder. Resource Window. Toggles Resource Window Palette Window . Toggles Component Palette
833 .

834 . 835 .

Properties Window. Toggles Component Properties Window Entity Selector Window . Toggles Entity Selector
834 .

HELP MENU
Open GUI Builder help. Opens GUI Builder documentation in browser. Open Widgets help. Opens widgets documentation in browser.

4.21.2 Toolbar
Provides quick access to commonly used operations: Done. Finishes editing of widget template and saves changes to the AggreGate Server. Cancel. Stops editing and abandons any changes. Toggle Decorations. Enables or disables decorations of panel layout grid cells. See cell decorations details.
831

for

Save Template. Stores currently edited template on the server by updating template field in the widget properties 315 . Editing is not interrupted. Undo. Discards previous operation. This function has global keyboard shortcut: Ctrl-Z. Redo. Repeats previously undone operation. This function has global keyboard shortcut: Ctrl-Y . Run Widget. Runs the widget currently being edited, for testing. This function has global keyboard shortcut: F5. Fill Horizontal. Toggles horizontal fill 320 of currently selected component. Available for components that are located in container with Grid Layout 318 . Fill Vertical. Toggles vertical fill in container with Grid Layout 318 .
320

of currently selected component. Available for components that are located

Set anchor: Center. Set anchor 319 of currently selected component to Center. Available for components that are located in container with Grid Layout 318 . Set anchor: North. Set anchor 319 of currently selected component to North. Available for components that are located in container with Grid Layout 318 . Set anchor: East. Set anchor 319 of currently selected component to East. Available for components that are located in container with Grid Layout 318 . Set anchor: South . Set anchor 319 of currently selected component to South. Available for components that are located in container with Grid Layout 318 . Set anchor: West. Set anchor 319 of currently selected component to West. Available for components that are located in container with Grid Layout 318 . Set anchor: North-West. Set anchor 319 of currently selected component to North-West. Available for components that are located in container with Grid Layout 318 . Set anchor: North-East. Set anchor 319 of currently selected component to North-East. Available for components that are located in container with Grid Layout 318 . Set anchor: South-East. Set anchor 319 of currently selected component to South-East. Available for components that are located in container with Grid Layout 318 . Set anchor: South-West. Set anchor 319 of currently selected component to South-West. Available for components that are located in container with Grid Layout 318 . Align Top. Align selected components by their top edge. Available for components that are located in container with Absolute Layout 322 .

2000-2013 Tibbo Technology Inc.

830

AggreGate Documentation

Align Bottom. Align selected components by their bottom edge. Available for components that are located in container with Absolute Layout 322 . Align Left. Align selected components by their left edge. Available for components that are located in container with Absolute Layout 322 . Align Right. Align selected components by their right edge. Available for components that are located in container with Absolute Layout 322 . Align Horizontal Axis. Align selected components to horizontal axis by their center. Available for components that are located in container with Absolute Layout 322 . Align Vertical Axis. Align selected components to vertical axis by their center. Available for components that are located in container with Absolute Layout 322 . Make Same Width (by minimal). Set width of all selected components equal to the minimal width of them all. Make Same Width (by maximal). Set width of all selected components equal to the maximal width of them all. Make Same Height (by minimal). Set height of all selected components equal to the minimal height of them all. Make Same Height (by maximal). Set height of all selected components equal to the maximal height of them all. Distribute by Centers Horizontal. Align components so that the distance between their centers along the horizontal axis will be equal. The leftmost and rightmost components are not moved. This button is available when three or more components are selected. Distribute by Spacing Horizontal. Align components so that the distance between edges of adjacent components along the horizontal axis will be equal. The leftmost and rightmost components are not moved. This button is available when three or more components are selected. Distribute by Centers Vertical . Align components so that the distance between their centers along the vertical axis will be equal. The topmost and bottommost components are not moved. This button is available when three or more components are selected. Distribute by Spacing Vertical. Align components so that the distance between edges of adjacent components along the vertical axis will be equal. The leftmost and rightmost components are not moved. This button is available when three or more components are selected.

4.21.3 Work Form

The work form is used to preview widget layout Builder window.
318

during construction and editing. This is the main part of the GUI

The work form always displays the core container of a widget - its root panel. If is contains any child components or containers, the entire hierarchy is shown in the work form. In other words, when cell decorations 831 are disabled, the widget in the work form closely resembles what it'll look like when actually running in AggreGate Client 776 . You can put new components on the work form, move components within current container or to other containers, resize components and change their margins 320 , create new bindings 842 etc. See editing widget layout 836 for details. Here is what the work form looks like when editing a widget template
314 :

2000-2013 Tibbo Technology Inc.

AggreGate Client

831

Components in GUI Builder look similar to what they'll look like when the widget is executed in AggreGate Client, with some differences: 1. Most user input is ignored (e.g. buttons are not visually "pressed" when user clicks on them). 2. If Toggle Decorations button (see below) is pressed all containers have borders showing their titles:

3. Empty cells in a Grid Layout

318

are visually represented by white bordered rectangles.

The borders of these rectangles are used for resizing GUI components and defining their borders. For further details on how to use the borders, see Editing Widget Layout 836 .

Cell Decorations
When a cell of a Grid Layout 318 is shown in a work form, it may have additional decorations. These decoration make it easier to edit the layout, but make the widget appear different then what it looks like during normal execution 317 . You can toggle them using the Toggle Decorations button in GUI Builder toolbar 829 . Additional visible elements shown when decorations are enabled: 1. Empty cells of Grid Layout are shown as white rectangles. 2. Every cell of Grid Layout has a border, to help find separate and joined cells. 3. Containers 376 have title borders showing their names. If a container has multiple panes, each pane also gets a title border with its name. Here is what the same panel with grid layout looks like, with and without decorations:

2000-2013 Tibbo Technology Inc.

832

AggreGate Documentation

Without decorations:

With decorations:

In the Absolute Layout

322 ,

every component is decorated by a border helping to view its margins:

Context Menu
Right-click on a component within the work form will bring up the same context menu that appears inside Resources Window. See descriptions of menu items here 833 .

2000-2013 Tibbo Technology Inc.

AggreGate Client

833

4.21.4 Resources Window

The resources window contains a tree of widget components and other objects (i.e. Button Groups 334 ). The root panel 376 forms the root node of the tree. Normal components and containers are shown as nodes with different icons. Components held by a container or a pane (i.e. in the case of a Layered Panel 382 ) are shown as its child nodes.

The resource tree may be used for selecting components and panes of multi-pane containers. When a component or pane is selected in the resource window, it is also selected in the work form. Its properties are shown in the Component Properties Window 835 . Invisible components (with Visible property set to FALSE) are shown in grey.

Node Icons
Root panel Container Regular
376 376

of the widget component.

322

component.
604

Regular component that has at least one binding

(either incoming or outgoing).

Context Menu of a Resource Tree Node

The context menu for a resource has the following operations: Edit Bindings. Open bindings
604

related to this component for editing.

Rename. This is the way to change the name of a component, container or pane. Delete. Permanently delete the selected node (container, component or pane). The context menu for a node may also contain some component-specific operations. For example, the context menu for a Tabbed Panel node contains an Add Tab item. Similarly, the Button Groups 375 node has an Add Button Group operation. Clone. Make a copy of the component. If selected node is a container component in this container.
376 ,

its context menu also has a Create submenu used to create a new widget

The same menu appears when right-clicking a component in a Work Form

830 .

Renaming Components
Component's name is used to refer it by bindings is how renaming looks like:
604 .

The component may be renamed using Rename menu item. Here

2000-2013 Tibbo Technology Inc.

834

AggreGate Documentation

If the renamed component had any bindings, these bindings will be shown in the popup window to allow adjusting them to reflect component name change.

Searching/Filtering Components
Use the filter field in the top of resources window to display only components those names/types contain specified string.

Drag-and-Drop Operations
The resource tree supports the following Drag-and-Drop operations: If a component is dragged from a component palette 834 and dropped on a container's node with Grid Layout 318 , a new component is placed on the first free cell in the component's grid. If the container has no free cells, a new cell is created. If a component is dragged from a component palette a new component is placed at position X=0, Y=0. If a component is dragged from the work form tree, they exchange places.
830 834

and dropped on a container's node with Absolute Layout

322 ,

and dropped on another component in the work form or resources

4.21.5 Entity Selector

The entity selector 815 window lets you browse the AggreGate Server context 863 tree and see all available variables 869 and functions 878 with their fields. The default context 315 defined during widget editing and all its children are marked in bold.

The entity selector is mostly used for creating new bindings

604 .

See creating bindings

842

for details.

4.21.6 Component Palette

The component palette is used to add new components to the widget layout by dragging and dropping them on the work form 830 or on a container in the resource window 833 . The palette has several tabs: Components. Contains all normal components
322 .

2000-2013 Tibbo Technology Inc.

AggreGate Client
Containers . Contains all containers
376 . 397 .

835

Category Charts. Contains all category charts XY Charts. Contains all XY charts
429 . 478 .

Other Charts. Contains all other charts

See the editing widget layout to the widget layout.

836

section for more information on how to use component palette to add new components

4.21.7 Component Properties

This window contains a properties editor
795

used to change the properties of the currently selected component.

Note that properties marked with icon have bindings property context menu (see below).

312

associated with them. These bindings may be accessed via

When properties are changed, changes are saved immediately. There's usually no need to click the Save button in the Properties Editor toolbar. If a new property value cannot be automatically saved (e.g. because it was filled with an invalid value, such as a negative width, for example), the status of this property is set to "Modified" in the Properties Editor. Modified properties are highlighted in dark grey, and you have to correct them and then click the Save button in the toolbar to save them. If such explicit saving fails, an Error Dialog 846 pops up, describing the problem.

Context Menu
The context menu of Component Properties Editor allow to manage bindings component. It contains the following menu items:
604

and custom properties

588

of a
605 .

Bind Property. Create a new binding that will change current property, i.e. have this property as a target prompted to specify other binding properties 952 first.

User is

Edit Bindings. Opens a dialog allowing to configure all bindings associated with current property, i.e. having it as a target 605 , an activator 607 , or appearing inside binding expression 606 .

2000-2013 Tibbo Technology Inc.

836

AggreGate Documentation
870

View Property Information. Shows detailed information

about the property including its format

855 .

Add Custom Property. Allows to create new custom property for current component. Edit Custom Property. Opens parameters of selected custom property for editing. Remove Custom Property. Removes selected custom property.

4.21.8 Editing Widget Layout

Widget can contain multiple nested containers, and each of them has its own layout 318 . Layout types may be combined, e.g. root panel with absolute layout may have child tabbed panel 379 those tabs use grid layout, and one of tab's cells may have nested panel 378 with absolute layout, etc. Layout of each container is edited independently. However, it's possible to move components between containers. Editing layout comprises: Adding new components to the widget by dragging them from palette Moving components from one container to another Moving components between two locations within one container Resizing components Cloning components Editing component constraints
319 834

and dropping into the work form

830

(margins, anchor, etc.)

318

Before reading this section make sure that you read and understood how widget layout

is organized.

The effect of all operations described in this section may be obtained by manually editing the constraints widget components.

318

of

It's possible to clone component by moving it to another location with the mouse when Ctrl key is pressed.

4.21.8.1 Editing Grid Layout

You can use Drag-and-Drop to add new components from the component palette already laid out on the work form 830 . A component may be dragged... 1. From the component palette 2. From the work form
830 , 833 . 834 834

or to move and resize components

(to create a new component of selected type),

3. From the resources window

A component may be dropped... 1. On an empty cell in the layout grid, 2. Over an existing component, 3. On a drop zone, causing automatic creation of new row and/or column in the panel layout grid, or 4. On a drop zone leading to the implicit creation of a new Panel
378 .

It's possible to drag and drop individual components and event component sub-trees between different widgets, each of them being edited in a separate instance of GUI Builder.

1. DROPPING ON AN EMPTY CELL

2000-2013 Tibbo Technology Inc.

AggreGate Client

837

When a component is dragged onto the work form and the mouse hovers over an empty cell (one marked with a white background, if decorations 831 are enabled), the cell is highlighted in blue:

Dropped here, the component will occupy the empty cell.

2. DROPPING OVER AN EXISTING COMPONENT

You can drag an existing component from its location on the form and drop it onto another component. This will allow to replicate properties from the dragged component to a dropped one. This obviously doesn't work with new components dragged from the palette.

2 AND 3. DROPPING INTO SPECIAL LOCATIONS

The third and fourth aforementioned methods work similarly. The component being dragged is dropped inside a cell already occupied by some component, but not directly over the component. Each cell occupied by some component ( label1 in the following picture) has 16 available drop locations:

2000-2013 Tibbo Technology Inc.

838

AggreGate Documentation

Dropping the component over one of the first eight locations (illustrated in yellow in the example above) puts it into a new row and/or column of the layout grid. More on this in the description for method 3, below. Dropping the component over locations 9-16 (green, above), creates a new Panel 378 container in the cell occupied by label1. This panel will now hold two components: label1 and the component that was dropped. More on this below, in the description of method 4.

3. DROPPING ON LOCATIONS 1-8

If the component is dropped on the locations 1-8 (shown in the image above), it will be put in the layout grid of label1's container (the root panel, in our example). A new row and/or column will be created in the layout grid to hold the dropped component. When the mouse hovers over the 1-8 drop locations, "ghost" frames are shown to help visualize where the new row and/or column will be located. Here is what it looks like when the mouse is held over location 5:

If we now drop the new component, a new column will be created to the right of label1:

2000-2013 Tibbo Technology Inc.

AggreGate Client

839

Hovering over location 8 shows the following "ghost" frames:

In the above case, the new component will be placed on a new row and column created to the bottom and to the right of label1. As a side-effect, two empty cells will be created:

This is what the "ghost" frames look like in a more complicated layout:

This is what this layout looks like once the component is dropped:

2000-2013 Tibbo Technology Inc.

840

AggreGate Documentation

4. DROPPING ON LOCATIONS 9-16

Dropping on these locations creates new a Panel 378 in the cell. This panel will then contain two components: label1 and the component dropped. Their relative positions in the new panel will depend on where the new component is dropped. "Ghost" frames are also shown when the mouse hovers over these locations while dragging. Here is the "ghost" frame for location 13:

If the component is dropped on this location, a new panel will be created, containing two cells in one row:

For location 16, "ghost" frames show that the new panel will contain four cells. label1 will be placed in row 1, column 1, while the dropped component will be placed in row 2, column 2:

2000-2013 Tibbo Technology Inc.

AggreGate Client

841

Here is what the new panel will look like:

RESIZING COMPONENTS AND EDITING THEIR MARGINS

When a component is selected in the work form, it has a blue dashed border with blue and green dots used to resize it or edit its Grid Layout margins 320 :

To resize the component, drag the blue dots. To change its margins, drag the green dots. When margins are set to nonzero values, they are drawn as green dashed rectangles around the component:

Holding Shift key during component resize will cause it to preserve its proportions. Holding Alt key during resize will resize component relatively to its center instead of its top-left point. The Root panel never has margins (it must occupy all available space in the widget window).

376

2000-2013 Tibbo Technology Inc.

842

AggreGate Documentation

4.21.8.2 Editing Absolute Layout

Editing an absolute layout is much easier than editing grid layout. Move the components using the mouse, and their X and Y Coordinates will be updated properly. Use keyboard arrow keys for precision moving. To resize a component drag it for one of its corners. Simultaneous moving/resizing of multiple selected components is also supported.

Snapping Grid
It's often very convenient to preserve regular component spacing within absolute layout. The widget will look better if components are properly aligned to each other. Despite GUI Builder's toolbar 829 provides many component alignment tools, one of the best ways to ensure proper alignment is using snapping grid. Don't mix absolute layout's snapping grid with the grid layot
318 .

Snapping grid may be visible only if a widget is being edited in GUI Builder. It has two steps: primary step that may be optionally used to snap components during drag and drop operations, and secondary step which is always ten times larger than primary step.

The snapping grid can be controlled separately in each container using absolute layout. There are three component properties 322 controlling snapping grid demeanor: Show Grid . Enables/disables snapping grid visibility. Grid Step. The primary step of snapping grid in pixels. Snap to Grid . If enabled, all component's corners are always attached to grid nodes during drag and drop operations 844 . Despite snapping grid controls are visible in properties window and saved into widget template like any other properties, they do not somehow influence the behavior of running widgets. The only objective of snapping grid is component placement facilitation in GUI Builder.

4.21.9 Managing Bindings

GUI Builder helps create widget bindings manage the bindings: Creation via drag-and-drop Modification of component bindings via component's context menu Modification of property bindings via property context menu
604

using intuitive visual operations. There are several ways to create and

Drag and Drop Binding Creation

2000-2013 Tibbo Technology Inc.

AggreGate Client
You can drag a node from the Entity Selector Window 833 .
834

843

onto a component or container in the Work Form

830

or in the Resource

PREVIEW OF BINDINGS BEFORE CREATION

When a node is dragged from the entity selector onto the work form and the mouse is held over a form component, bindings that will be created if the component is dropped are shown in a red tooltip. The left part of the binding (before the "=" character) is binding target 605 , while the right part is the binding expression 606 :

If the node is then dropped onto the component, the new bindings are created. Newly created bindings are shown in the popup window and may be adjusted.

Editing All Widget Bindings at Once

To view or edit all widget bindings in a single dialog: Open properties of Root panel
376

in the Component Properties

835

window

Open All Bindings tabular property and edit it Click OK to save the changes

Similarly to all other tables, All Bindings table support sorting and filtering of the bindings list.

Modification of Component Bindings

To manage all bindings related to a certain component, right click on it in the Resources Window and select Edit Bindings. The component bindings window will pop up. Alternatively, you can edit Bindings table in the Component Properties all bindings related to the current component.
835 833

or Work Form

830

window. It also provides access to

Binding a Property
To create a new binding targeting 605 a certain component property, right click on the name of this property in the Component Properties 835 window and select Bind Property. The binding settings dialog will pop up, allowing to set up

2000-2013 Tibbo Technology Inc.

844

AggreGate Documentation

binding expression, activator, and execution options.

Modification of Property Bindings

To manage all bindings related to a single component property, right click on the name of this property in the Component Properties 835 window and select Edit Bindings. The property bindings window will pop up.

Editing a Binding
Different parts of a binding can be edited in different visual editors. Binding Target
605

is edited in the Binding Target Editor:

Binding Expression Binding Activator

606

is edited in the Expression Builder

817

607

is edited in the Binding Activator Editor:

4.21.10 Drag and Drop Operations

This section covers mouse drag-and-drop operations that greatly simplify binding component properties to data model items and to each other.

Drag and Drop Operations Between Entity Selector and Work Form
1. DRAGGING A VARIABLE FIELD AND DROPPING IT ON A COMPONENT
In this case, two bindings are created: A binding that reads the variable field on startup and reset component's default property 586 .
378

event of the root panel and writes it to the

378

A bindings that writes the value of the component's default property back to the context variable upon the submit event of the root panel.

2000-2013 Tibbo Technology Inc.

AggreGate Client

845

2. DRAGGING A FUNCTION INPUT FIELD AND DROPPING IT ON A COMPONENT

This operation creates one binding. Its target 605 is a function's input field. Its expression is a reference to the default property of widget component. Its activator 607 is the root panel's submit 378 event.

3. DRAGGING A FUNCTION OUTPUT FIELD AND DROPPING IT ON A COMPONENT

This operation also creates a single binding with a target pointing to a property of the component. The binding expression is a reference pointing to the output field of the function. Activator 607 of this binding is submit 378 event of the root panel.

4. DRAGGING A VARIABLE TO THE DATA TABLE EDITOR

This operation creates three bindings:

344

COMPONENT

A binding that reads the variable value on widget startup and writes it to the default property of the Data Table Editor, i.e. the table this editor operates on. A binding that writes the table contained in the Data Table Editor back to the context upon the submit root panel.
378

event of the

A binding that sets the Enabled 586 property of the Data Table Editor according to the Writable property of the variable definition, to make sure that value of read-only variables can't be edited.

5. DRAGGING A FUNCTION TO A BUTTON

334

COMPONENT

This operation does not actually create new bindings. Instead, it finds all widget bindings: Whose target points to the input field of this function, or Whose expression contains references to the output fields of this function and sets their activators to the action 337 event of the button component. This makes them working together within one bindings processing session 607 that is started upon button click (when action event is fired). If a widget has no bindings related to the input or output fields of the dragged function, this drag and drop operation won't be allowed.

6. DRAGGING A VARIABLE FIELD TO A BUTTON GROUP

375

This operation creates three bindings, which let you use the buttons in the group to change the field's value:

If the field has selection values 856 , this operation also changes the Value 339 property of all radio buttons that belong to the group to the available selection values. If you have 5 selection values (for example) yet only 3 radio buttons, only the first 3 values will be used - no error will be shown.

7. DRAGGING A VARIABLE FIELD TO COMBO BOX

This creates the same bindings as in 1 above
844

340

OR LIST

331

(Dragging A Variable Field And Dropping It On A Component), but

2000-2013 Tibbo Technology Inc.

846

AggreGate Documentation
856

adds an extra binding whose purpose is to display the selection values or list.

defined by the field format in the combo box

8. DRAGGING A DEVICE CONTEXT AND DROPPING IT TO ANY CONTAINER

This drag and drop operation created a new Device component 367 in the target container. The new component will have labels showing basic status of the dropped Device. It will also have a pre-defined Status Table configured to indicate current device connection status (Online, Offline or Suspended). A binding linking server-side device status to the Status parameter of device component is also created.

4.22 Error Dialogs

An Error Dialog generally looks like this:

It has three buttons: The More Info button shows detailed information about the error message. Advanced users can use this for troubleshooting.

The Send Report button submits the error details to Tibbo. The email contains the text shown when you click More Info. No additional information is transferred. The PC where AggreGate Client is installed must have Internet access for the report to be sent. Error report is sent using HTTP protocol to the Tibbo server. The Close button just closes the dialog. If logging details) in the log.
848

is enabled, you can later find the error message (along with its

2000-2013 Tibbo Technology Inc.

AggreGate Client

847

4.23 Interactive Guide

AggreGate is an easy-to-use system, but it's quite robust, too. There are several simple operations you have to do to get up and running. To ease your way into using the AggreGate Client, we have authored a series of Interactive Guides - one for each of these actions. These guides will help you quickly get up and running with AggreGate. The following guides are available, and should be done in sequence by any new AggreGate Server administrator: Guide 1: Create new Server Connection Guide 2: Create a User Account Guide 2: Connect a Device Guide 3: Connect a Device Server We call these guides "interactive" because the Guide window tracks what you do with the client, and tells you what to do next. Think of it as a personal coach watching over your shoulder as you get up to speed with AggreGate. It's just readand-click, all the way through:

SHOWING THE TUTORIAL WINDOW

By default, the tutorial window is shown automatically on starting up the client. However, if you need to manually show the guide window, use Main Menu 780 > Help > Open Interactive Guide.

PITFALLS AND BUGS (TRICKING THE GUIDE)

We have attempted to make the tutorial as fool-proof as possible. The Next button is only enabled once you've performed the action called for. However, it is possible to 'trick' the tutorial by clicking the Cancel button for various dialogs, etc. Our purpose was not necessarily to predict all of the countless incorrect actions which can be done, but to mark a 'safe trail' through setting up the program. If you carefully follow the tutorial, you'll get where you're trying to go.

2000-2013 Tibbo Technology Inc.

848

AggreGate Documentation

4.24 Logging
Similarly to the AggreGate Server, AggreGate Client uses Apache Log4J logging library for log output of its own internal events. It is highly customizable and allows multiple levels and sources of logging information along with numerous log destinations. Logging output can be redirected to: Console Text files XML files Windows event logs UNIX syslog Database Remote network server E-mail messages Java Message Service (JMS) And many other destinations.. Logging of AggreGate Client is configured and managed exactly in the same way as the logging of AggreGate Server. In effect, this means you're most likely to use the default configuration. If you want to change anything, you're going to have to directly edit AggreGate Client logging configuration file, which is logging-client.xml, in the installation directory. The structure of this file is briefly described in logging configuration file 74 section. More info on logging: Configuring Logging
74

of AggreGate Server
74

Logging Configuration File Logging Levels

79

Logging Framework Documentation Sources

80

This may seem like a bit of a terse explanation, but it's just because logging is a complex topic, and is only used for troubleshooting. If we were to delve into logging in detail, we would effectively be writing another manual for Log4J. We opted for using a third-party logging tool because it is robust, flexible, and very well documented.

5 AggreGate Agent
The AggreGate Agent is one of the most complex and versatile concepts in the AggreGate universe. In this part of the manual, we will attempt to explain its purpose, function, and importance. The term Agent bears defining. The inspiration for this term comes from the following sense of the word: Agent: somebody representing another; somebody who officially represents somebody else in business. [Microsoft Encarta 2006. 1993-2005 Microsoft Corporation.] In this documentation, Agent means one of the following, depending on the context: 1. A special application that intercommunicates with AggreGate Server server using AggreGate communication protocol 1303 . This application converts data collected from hardware into AggreGate format and/or converts third-party communication protocols into AggreGate protocol. It can be implemented in virtually any programming language, while Tibbo provides reference implementations in Tibbo BASIC, Java (including Android version) and .NET (including .NET Compact). 2. An external hardware device (programmable controller or computer) that runs a Agent application.

Agent And Dedicated Device Drivers

The AggreGate Server can communicate with a device in one of two principal ways: 1. Via a dedicated Device Driver 129 : Using this method, the AggreGate Server communicates with a Device via its native communication protocol. The driver allows the AggreGate Server to correctly parse and 'understand' the data from this specific device, and thus make it accessible via the various AggreGate Server facilities (events, reports, context trees, etc.). This driver is a Java software component running on the server side. The drivers are 'one-off' -meaning, to connect a different device to AggreGate Server using this method, you would need a different driver which 'understands' the protocol used by the new device. Writing such a driver requires extensive familiarity with

2000-2013 Tibbo Technology Inc.

AggreGate Agent
AggreGate Server internals and Java programming.

849

2. Via an Agent : The Agent is a separate hardware device (controller, module, or PC) running a special-purpose application. This hardware/software combination acts as a mediator between the actual hardware device (connected to Agent using serial, Wi-Fi, GPRS or other link) and the AggreGate Server. Connection between AggreGate Server and Agent is established over IP network. Agent application may be also integrated into device design and executed by the device's main CPU. Alternatively, a communication coprocessor running Agent application may interact with the main CPU responsible for device "business logic" via SPI interface. Let's discuss this second modus operandi a bit further: When using an Agent, data conversion is done in hardware. The device running the Agent application receives a stream of data from the hardware device using the device's own native protocol. It then converts this stream into a AggreGate Server generic protocol, and sends it to the AggreGate Server. When receiving instructions from the AggreGate Server, the Agent converts them back into the device-specific protocol and sends them to the device. In effect, the Agent application is composed of two primary parts: 1. Device-Specific side: This part of the code is written specifically for the particular hardware device connected to the Agent hardware platform. This is the only part which has to be modified to make AggreGate work with any new hardware device. 2. Network side: This part of the code handles all AggreGate Server communications. This is a generic part. In effect, it communicates with AggreGate Server using the AggreGate Communications Protocol 1303 . This part never has to be changed to make AggreGate work with a new device. You may think of the AggreGate as a hardware-based driver or protocol converter. If you have a hardware device you wish to plug into AggreGate so it would exploit all of the power and benefits of the system, all you have to do is just include an open-source Agent library to your firmware/software, and voila - you've got complete AggreGate connectivity for your device! Agent application provides AggreGate operators several methods to control, monitor and configure hardware devices connected to it: It exposes the internal settings of your device to AggreGate Server, so that settings such as Number of Records to Keep (for a time clock) or Maximum Permitted Speed (for a forklift) will be seamlessly displayed and edited in any AggreGate Server User Interface (such as AggreGate Client 776 ). It allows to execute different operations with the device, such as Perform Self Test or Send Message To Device LCD. Operators may specify input parameters for every operation and view their execution results. It helps to monitor events generated by a device, such as User has entered the area or User has exited the area for the Access Control Terminal. AggreGate Server stores all device events persistently and provides access to their history for system operators. In addition, one Agent hardware platform can be connected to several different devices. For example, you could use a 4-port DS1000 Programmable Controller manufactured by Tibbo as your hardware platform, and connect it to 4 serial devices (time clocks, for example). Your Agent application will allow access to each of these time clocks as if it were individually connected to the network.

Agent Device Driver

Agent has a counterpart on AggreGate Server -- Device Driver all communications between AggreGate Server and Agent.
129

called Agent Driver

130 .

This driver is responsible for

Using Agent As a Core Hardware Component

Since Tibbo provides full portfolio of powerful programmable modules and controllers along with the free IDE, another option would be to build your system around a Tibbo processor running the Agent application. In such a case, you could hook the peripheral components of your system (LCD, keypad, etc.) directly to the Tibbo processor and use it as the main CPU for your system. You would then code your device logic in Tibbo BASIC, as part of the Agent application. This would provide your new device with native AggreGate functionality.

Customizing Agent For Your Devices

The Agent application may be customized to connect any existing or newly created device to AggreGate. You just have to include Agent library into your software/firmware and provide: Definitions for device settings, operations and events, Code that implements reading and writing device settings, Code for forwarding operation requests to devices, Code for polling the device for events or receiving events asynchronously and sending them to the server.

2000-2013 Tibbo Technology Inc.

850

AggreGate Documentation

Agent SDK
For information about implementing Agent as a part of a PC-based application based on Java or .NET technology, see Agent SDK 972 section.

5.1 Generic Information About Agent

The Agent application may be used: To represent one or more hardware devices for AggreGate (e.g. PC-based vending machine running a .NET application that uses Agent library to communicate with AggreGate Server for providing supply stats and remote service operation handling). To communicate with one or more external hardware devices via serial, Wi-Fi, GPRS or other links to make them available for AggreGate (e.g. programmable module collecting data from temperature, humidity and pressure sensors and making this data available within AggreGate).

PRIOR KNOWLEDGE
In order to proceed with connecting your devices to AggreGate with Agent, you should be familiar with different concepts of the system, such as representing of devices as contexts containing a set of variables, functions and events. We suggest reading the following basic topics before starting the customization: Introduction
27 31

AggreGating Your Devices System Components Data Terminals

113 35

AggreGate Agent Introduction Agent Device Driver

130

848

It is also highly recommended to learn about the internal representation of device data in the system: Contexts Variables Functions Events
880 854 863 869 878

Data Tables

Also, you may want to take a look on two articles about communications between AggreGate Server and Agent: AggreGate Communications Protocol 1303 Data Table Encoding
1306

5.2 Agent Core Concepts

The most important concepts implemented in the Agent application and its corresponding AggreGate Server driver
130 :

The Agent application maps data provided by hardware into variables, functions, and events of a single context 863 (Agent's context). AggreGate Server creates a Device context Agent application.
677

that mimics variables, functions and events of context provided by

126 ).

All variables (settings) provided by Agent are read and cached on the server side (see synchronization

All control requests (function calls) to AggreGate Server's Device context are directly forwarded to Agent for execution. Replies are sent back to AggreGate Server. AggreGate Server receives and persistently stores all events received from Agent.

Agent Startup
1. When a programmable controller running AggreGate powers up or PC-based Agent application is started, it tries to

2000-2013 Tibbo Technology Inc.

AggreGate Agent
establish a connection with AggreGate Server.

851

2. If a connection is established, it completes the login sequence by sending some commands to the server and checking the replies. This involves checking the validity of AggreGate password stored in server-side Device account. 3. After that, the AggreGate Server starts a full synchronization 131 . It reads information about context provided by Agent along with the definitions of its variables, functions and events, synchronizes Agent's real-time clock with the server time and then switches to "normal operation". During normal operation AggreGate Server: Periodically synchronizes variable values between the server and agent contexts; Forward operation requests to Agent and receives execution results; Receives device events from Agent and processes/stores them.

Normal AggreGate Server Communication Mode

In this mode, Agent receives commands from AggreGate and processes them. It may also generate some events asynchronously and send them to the server. Supported elements of AggreGate Communications Protocol: Incoming Messages (from server): Start Message . Processed automatically by AggreGate Server intercommunication module. Operation Message. Parsed and processed by AggreGate Server intercommunication module. Outgoing Messages (to server): Event Message. Send to the server asynchronously by AggreGate Server intercommunication module when devicespecific code decides to generate and event. Replies: Success Denied Error All replies are automatically generated by the AggreGate Server intercommunication module. The Denied reply may be returned only if version of Agent is not compatible with AggreGate Server. In such a case Agent will not be able to communicate with the server. Operations: Get Variable. Set Variable. Call Function. These are automatically handled by the AggreGate Server intercommunication module. If an operation is related to a variable or function defined by the AggreGate Server intercommunication module itself (e.g. synchronization of realtime clock between server and Agent), the corresponding command is automatically processed by this module. Otherwise, command processing is delegated to the device-specific module, which may: Fetch data from a connected device, EEPROM, flash disk, memory or other source and send it to the server (as described below) for a Get Variable operation. Send data to equipment or store it internally in the for a Set Variable operation. Perform data processing or send commands to the connected equipment in for a Call Function operation.

5.3 Representation Of Devices In Agent

Device data is represented in Agent like it's represented within AggreGate Server itself. Agent provides a "normalized" representation of every device to the other parts of AggreGate. This representation is called a context 863 . Every context has variables 869 (device settings), functions 878 (operations valid for current device), and events 880 that can be produced by device. Variable values, function input/output parameters and data associated with event instances are also represented in the "normalized" form, as Data Tables 854 . Every Data Table has a format defining the allowed number of records in the table, and the name, type and other parameters of each column, as well as some other data.

2000-2013 Tibbo Technology Inc.

852

AggreGate Documentation

Every context (i.e. device) should provide definitions for its variables, functions and events. A definition contains the metadata for the variable, function or event, such as description, format and some other information.

5.4 Event Generation

Most hardware devices generate various events . These events usually reflect changes in device status or operating conditions. The Agent application maybe used to poll events from external hardware as well as generate them internally. These events are represented as context events 880 in context provided by Agent.

Event Confirmation
Some Agents require reliable event delivery. Such Agents should declare a confirmEvent() 853 function that will be called by the server each time it has received and successfully processed an non-system event from an Agent.

Asynchronous Updates Of Server Cache

Sometimes is may be necessary to "push" new value of some changed Agent variable to the AggreGate Server and update settings cache 115 without waiting for a regular synchronization cycle 126 . If such case, Agent should generate and Updated 890 event for the changed variable. Updated event contains name and new value of the variable. AggreGate Server will put new value to the server cache upon receiving Updated event if synchronization options for this variable does not block device-to-server synchronization.

5.5 Agent Contexts

This section describes Agent-specific variables Agent.
869 ,

functions

878

and events

880

that are available in context provided by

Public Variables (Properties)

DATE
This variable should be manually declared in an Agent context if AggreGate Server should perform real-time clock synchronization with the Agent. If an Agent declared the Date variable, the server writes it with its current date/time in the beginning of every synchronization cycle.

Variable Name: Records: Availability: Record Format Field Name

date
855

date

1 Root context :
Field Type Notes

Field Description

Value of the real-time clock onboard the programmable controller or PC running Agent.

Date

MODTIME
This variable contains timestamps for the latest modification time of every "device setting" variable in Agent's device contexts. These modification times are usually stored in EEPROM to assure correct synchronization after restarts. After each synchronization of device settings between AggreGate Server and Agent, the server updates variable modification times stored in the Agent by setting this variable. When a device setting is modified internally (e.g. using the device's keypad and LCD screen), Agent must properly update its modification time to keep the new values from being overwritten by the old ones, stored in the server cache, during the next synchronization. In some cases, Agent may not support modification times for some or all device setting variables. The modtime variable should not contain records for such variables. Even if it does, their modification timestamps must be set to NULL.

2000-2013 Tibbo Technology Inc.

AggreGate Agent Variable Name: Records: Availability: Record Format Field Name
variable modtime
855

853

date

0...unlimited Device contexts :

Field Type Notes

Field Description

Name of device setting variable. Date/time of the last modification of this variable's value. [?
878 ]

String Date Nullable

Public Functions
SYNCHRONIZED

AggreGate Server calls this function to instruct Agent that synchronization is finished and the latter may start sending events 852 .

Function Name: Input Records:

Input Format
855

synchronized

0
: None

Output Records: Output Format

855 :

0
none

CONFIRM EVENT
If this function is defined by an Agent, AggreGate Server calls it every time it receives and successfully processes a non-system event.

Function Name: Input Records:

Input Format
855

confirmEvent

1
: Name id Type Long Description ID of an Agent-generated event that was successfully received, stored and processed by the server

Output Records: Output Format

855 :

0 None

5.6 Communications Between Agent and AggreGate Serv

This article describes how Agent communicates with AggreGate Server using AggreGate Communications Protocol 1303. Communication takes place when Agent establishes a connection with AggreGate Server and logs in. At this point, control of the Agent is passed to the AggreGate Agent 130 driver. AggreGate Server then starts sending commands using AggreGate Communications Protocol to find out what data is provided by the Agent.

Command-By-Command Structure of Communications

A. LEARNING ABOUT THE CONTEXT OF AGENT

2000-2013 Tibbo Technology Inc.

854

AggreGate Documentation

First, AggreGate Server gets information about context declared by the Agent. The following commands are sent: 1. Get Variable 1305 info 2. Get Variable children
871 872 872 873

3. Get Variable variables 4. Get Variable functions 5. Get Variable events

873

B. SYNCHRONIZING REAL-TIME CLOCK

1. Set Variable 1305 date
852

of the Agent context to the current time in the Agent's Device Account timezone

124 .

C. SYNCHRONIZING DEVICE SETTINGS (VALUES OF VARIABLES OF DEVICE CONTEXTS)

AggreGate Server now synchronizes the values of all device setting variables between its cache and Agent. More information about synchronization and device settings caching may be found in the AggreGate Agent 131 driver article 1. Get Variable modtime 852 . Server gets modification times of all device settings variables to detect the proper direction of synchronization (Device-to-Server or Server-to-Device) for each of them. 2. For each device setting variable, either a Get Variable or a Set Variable command is executed, depending on the direction of synchronization. These commands are used to update value of variable in the Agent's device context (for Server-To-Device synchronization) or in the server cache (for Device-To-Server synchronization). 3. Set Variable modtime
852 .

The server updates device modification times stored in Agent.

D. FINISHING SYNCHRONIZATION
1. Call function synchronized
853

from Agent context

Commands Initiated By Agent

When Agent is connected to the AggreGate Server, it may send event are generated 852 .
1305

commands to the server whenever events

AggreGate Server never explicitly starts or stops listening for Agent's events by sending Add Event Listener 1306 or Remove Event Listener 1306 commands of AggreGate Communication Protocol. It listens for events implicitly, without notifying Agent about that it has started listening. Therefore, Agent may start sending events of any defined type to the server immediately after synchronization is complete, i.e. after the server has called the synchronized 853 function from Agent's root context.

6 System Internals
This chapter discovers the details of AggreGate internal components and concepts.

6.1 Data Tables

A Data Table may contain zero or more records (lines) and zero or more fields (columns), and thus (records * columns) cells filled with data. The records (lines) for a given table are described by a Table Format 855 . All records in a Data Table are always of the same format. The Table Format describes every field in the table and contains several other options.

2000-2013 Tibbo Technology Inc.

System Internals

855

Even the most simple variables, containing just a single string or number, are represented by a Data Table with just one record and one field. This may seem strange at first glance, but the concept of Data Tables significantly simplifies complex operations.

Uses of Data Tables

Data Tables are widely used in AggreGate. They have three primary uses: Variable values. The value of each variable 869 in every AggreGate Server context Table. Its format 855 is specified by a variable definition 870 .
863

is represented by a Data

Function input and output values. Input and output values for each function 878 in every AggreGate Server context is represented by a Data Table. Its format 855 is specified by function definition 878 . Event data. Every AggreGate Server context event 880 has a separate Data Table associated with it. This Data Table contains event-specific data. Its format 855 is specified by event definition 880 .

6.1.1 Table Format

The Table Format contains complete information about a table. It may exist independently from a Data Table. You can create several Data Tables using the same Table Format. When you add a new (empty) record to such a table, every field in it will initially contain a default value, as specified by the Table Format. If the field is defined as "nullable", the value can also be NULL (i.e, no value). The table format is most commonly used in the following cases: To define the format for a context variable
869 ,

2000-2013 Tibbo Technology Inc.

856

AggreGate Documentation
878 ,

To define the format for the input and output values of context functions To define the format for a Data Table associated with an event Table format defines the following table properties: Property Minimal and maximal record count Reorderable Record Validators Table Validators Bindings Naming Expression Description
880 .

The number of records should be within this range, otherwise the table will be treated as invalid. This flag indicates that records in this table may be swapped (re-ordered) during table processing Rules for validating every record in a table. These are used internally and are not userconfigurable. Rules for validating the whole table. These are used internally and are not userconfigurable. A list of data bindings 860 that define how the values in the table are changed when other table cells, or environment variables, are changed during table processing. An Expression
911

that defines how the table is presented to the users in the interface.

Field Format
The Table Format consists of several Field Format descriptors describing each field. Most of these descriptors are never configured by the user (or administrator). They're internal settings, and are only covered here for reference. Field properties: Property Name Description Help Default Value Nullable Non-Replicatable Key Field Selection Values Extendable Selection Values Validators Editor/Renderer Options Icon Group Description Field name. Textual field description. Detailed description of a field. Default value of the field. You can omit this only if the field is nullable (see below). Flag indicating that field can contain NULL ("Undefined") values. Flag that indicating that field should be skipped during Data Table Smart Copy
861

operation. operation

Flag designating field as a key field. Key fields force the Data Table Smart Copy to employ a special copy algorithm. List of values that can be selected for the field, along with textual descriptions.

861

Flag indicating the field may be set to any value, including ones not listed in Selection Values. List of validators used to check if value is suitable for the field. AggreGate Server features several pre-configured validators, internally used by the system to verify user input. This parameter defines how the field is shown and modified in the user interface. Allowed editor/renderer codes are listed and described here 857 . Editor/renderer options that allow fine-tuning rendering of field values in the UI. Syntax of option strings for different editor/renderer types are described here 857 . String ID of field icon. Human-friendly field group description.

Field Types
There are several predefined field types that may appear in Data Tables: Field Type Integer field Desctiption Contains a 32-bit signed integer number.

2000-2013 Tibbo Technology Inc.

System Internals

857

Long field String field Boolean field Float field Double field Date field Data Table field Color field Data Block field

Contains a 64-bit signed integer number. Long fields are often used to hold time periods expressed in milliseconds. Contains a string (unlimited length). A "flag" field with two possible values: TRUE or FALSE. Contains a 32-bit floating point number. Contains a 64-bit floating point number. In most cases, Double should not be used in favor of Float. Contains a millisecond-precision timestamp. It may be treated as date, time, or a timestamp (date + time). Contains a nested Data Table. Contains a color definition (RGBA). Contains binary data that may be treated as a generic file, image, sound etc.

6.1.2 Editors/Renderers
This section lists all Data Table field editors and renderers renderer options.
856

that are supported by AggreGate. It also describes editor/

Suitab le Field Types All Field Types

Editor/ Description Render er Code list List Editor. Renders field that have Selection Values as a list of radio buttons instead of usual combo box. This editor will not work properly for fields that have Extendable Selection Values flag enabled. Date Editor . Allows to specify only date for Date fields. Time specification is not allowed. Time Editor. Allows to specify only time for Date fields. Date specification is not allowed. Spinner. Renders a spinner next to the numeric text box allowing to increase/decrease values using a mouse.

Options

None allowed.

Date

date

None allowed.

Date

time

None allowed.

Intege r

spinner

None allowed.

Intege r, Long, Float, String

bar

Progress Bar Renderer. Displays a Options string will be interpreted a numeric integer progress bar indicating current field maximum value for a bar, i.e. its high limit. The low limit is value. The highest value of the bar is always zero. specified by Editor Options. If no options are defined, the maximum value is assumed to be 100. Example: 10000. This options string will force the bar to render values in range from 0 to 10000.

Intege r, Long, Float, String

bytes

Bytes Renderer. Interprets the field Options string will be interpreted a Boolean value. If value value as byte count or byte rate and is false the field will be rendered as byte count (this is a renders it as: default mode). If value is true, the field will be rendered as byte rate. number of bytes, kilobytes, megabytes of gigabytes, OR Example: 0. This options string will force field values to be rendered as Bytes, KBytes, etc. number of bytes, kilobytes, megabytes of gigabytes per Example: 1. This options string will force field values to be second rendered as Bytes/s, KBytes/s, etc. Time Period Editor. Allows to Options string must have the following form: MIN_UNIT

Long

period

2000-2013 Tibbo Technology Inc.

858

AggreGate Documentation

specify a time period as a combination of a Time Unit (from milliseconds to year) and the number of Time Units entered as a number. The resulting field value is number of milliseconds.

MAX_UNIT. MIN_UNIT and MAX_UNIT are minimal and

maximal integer unit types to be used when rendering or editing the period:

0 - Millisecond 1 - Second 2 - Minute 3 - Hour 4 - Day 6 - Month 8 - Year

Example: 1 3. This options string will allow using only seconds, minutes and hours for rendering/selecting the period. Milliseconds will be omitted. Values greater than one hour will still be rendered in hours.

String

expressi Expression Editor. Allows to enter on an AggreGate expression 911 using Expression Editor. passwor Password Editor. Password editor d is a text field that substitutes all characters with "*". text Text Editor. Uses fully-functional text editor with syntax highlighting support for editing text strings.

Reserved for internal use.

String

None allowed.

String

Options string will be interpreted as a syntax highlighting mode, one of the following:

aggregate - AggreGate Expression html - HTML markup java - Java code shellscript - Unix shell script smi-mib - SNMP MIB file syntax sql - SQL query xml - XML markup

String

html

HTML Renderer. Renders cell text as HTML markup.

Options string will be interpreted a numeric integer number of characters to show in the main table (i.e. until the text opens in a separate dialog). By default, 30 characters are shown. Example: 100. This options string will cause first 100 characters of the string to be shown in the table.

String

textarea Text Area Editor. Uses text area opening in a separate dialog for editing text strings. It provides more space for editing longer values and has scrolling capabilities.

Options string will be interpreted a numeric integer number of characters to show in the main table (i.e. until the text opens in a separate dialog). By default, 30 characters are shown. Example: 100. This options string will cause first 100 characters of the string to be shown in the table. Options string will be interpreted a numeric integer maximum number of characters to show in every line of text area. If the text is longer, more lines will be added to the text area. Default number is 20. Example: 50. This options string will cause rendering of text area having width enough to display 50 characters and height enough to fit the whole text.

String

etextare Embedded Text Area Renderer . a Uses text area component appearing inside the table cell to render multiline text values.

String

context

Context Editor. Allows user to specify context path.

Options string must have the following form:

CONTEXT_TYPE_1 CONTEXT_TYPE_2 ... . If the

options are specified, context editor will allow selecting only contexts of the specified types 864 .

2000-2013 Tibbo Technology Inc.

System Internals

859

Example: widget. This options string will allow selecting only Widget Contexts 774 . String String context mask Context Mask Editor. Allows user to specify context mask. Same as above. Syntax of options string must match syntax of a Reference 925 of the following form:

referenc Reference Renderer. Allows user e to initiate an action by clicking on the reference. Action to execute and its parameters are specified via renderer options.

action/contextPath:actionName (parameter_list)$icon
The editor options of a Reference Editor define: What action 892 to call upon a click on the reference link, and from which context 863 What parameters will be passed to the action (parameters are specified as parameter_list, see References 925 article to discover the syntax) What icon should be shown next to the link text If parameter list includes expressions 911 , the following resolution environment will be used to resolve them: Expression Parameters Resolution Environment Default Context
927 922

Default context of the current editor. Data Table being viewed/edited in the editor. Row containing the clicked reference. Standard
931

Default Data Table

927

Default Row Environment Variables 930

927

variables only.

Example: action/users.admin.widgets.chart1: launch('{field2}', '{field3}'). This options string will cause launching widget users.admin. widgets.chart1 and passing values of fields field2 and field3 from current record to this widget. String font Font Editor. Allows to select a font from the list of fonts installed on the machine where AggreGate Client runs. IP Address Editor. Allows to enter an IP address. Host names are not allowed. None allowed.

String

ip

None allowed.

Color

box

Box Renderer. Normally, color None allowed. values are rendered as small colored rectangles along with numeric RGB valuess of a color. Box renderer does not show numeric RGB values and displays a large colored rectangle instead. Data Block Text Editor. Same editor as above, but used to edit a Data Block field as text. Image Editor. Allows to insert images into Data Block fields an view them. Sound Editor. Allows to insert sounds into Data Block fields an play them. Hex Editor . Allows to view/edit Reserved for internal use.

Data Block Data Block Data Block Data

dtext

image

Reserved for internal use.

sound

Reserved for internal use.

hex

None allowed.

2000-2013 Tibbo Technology Inc.

860

AggreGate Documentation

Block

individual bytes of a data block in the hex format. When editing a data block, it's also possible to change size of the block by entering new size (in bytes) inside a text field.

6.1.3 Data Table Bindings

The Data Table Format may also define one or more bindings 951 . Data Table bindings are similar to formulas in electronic spreadsheets (like Microsoft Excel). They define relationships between cells in the table. If the value of an "input" cell changes, the values in other cells that are bound to it are recalculated. A data binding points to an output cell in the data table (i.e, the "left" part of the binding expression, or "binding target"), and derives its value from an input expression 911 (which can contain references 925 to one or more data sources or table cells). When such a data source (used as an input for the binding expression) changes, the binding is automatically re-evaluated, and a new value is posted to the output cell.

Creating Bindings
In most cases, bindings are added to the table format programmatically, e.g. when creating a device driver writing a server script 628 . See Working with Data Tables 983 for details.
129

or

However, in some cases bindings are created by system operators using the Data Table Editor 813 . These bindings are then used to modify tables on-the-fly without operator intervention, e.g. during a headless action 892 execution.

Binding Target
variable$field[row]#property
All elements of the binding target are optional, except for field. It indicates the field in the table to which changes should be applied. If a variable is specified, we've just created a cross-table binding. This is a binding in which values stored in one Data Table are copied into another Data Table. Such a binding will work only if the values of both variables are being edited within a single Edit Properties 897 UI Procedure. If row is not specified, the binding will be applied to every row in the table. If property is not specified, the evaluation result is written to field. Properties are used to modify the behaviour of a given field when it's being edited. You can use them to conditionally enabled/disable the field, or to make a field into a drop-down list. Supported properties: Property enabled Explanation Binding expression should resolve to a Boolean value in this case. If this value is TRUE, editing of the cell specified by the binding target will be enabled, otherwise this cell will be switched to read-only mode. Binding expression should also resolve to a Boolean. If it is TRUE, the table field specified by the binding target will be hidden in all rows and its editing will not be allowed. Note, that it is not possible to hide a single cell (i.e. field in a certain row). Binding expression should resolve to a Data Table containing list of Selection Values available for the cell pointed by binding target. Binding expression should resolve to a String that represents new editor options
856 856

hidden

choices options

that will be

for the field.

Binding Expression
The binding expression may contain only standard references 926 . If a reference points to a cell within the table being edited, it will resolve to the value currently contained in the cell (which may be edited by a user, or written by other binding). In all other cases value will be retrieved from the server context, as described in standard references 926 section.

Data Table Bindings Resolution Environment Default Context

927

922

May vary, see individual Data Table bindings processing cases for details.

2000-2013 Tibbo Technology Inc.

System Internals

861

Default Data Table

927

Current table, i.e. the table on that the bindings are evaluated.

Default Row

927

Current row, if the binding does not refer a specific row and is evaluated for each table row individually. Zero otherwise. May vary, see individual Data Table bindings processing cases for details.

Environment Variables 930

Example
recipient#enabled = {mailSendingEnabled}
When this binding is processed, editing of the recipient field (probably, e-mail recipient) is enabled for a user only if the Boolean field "mailSendingEnabled" contains a TRUE value (i.e. mail sending is enabled). If a Data Table has several records, this binding will apply to every record separately.

6.1.4 Data Tables Smart Copy

The Data Table Smart Copy operation is used to merge data from one (source) Data Table 854 with the data in another ( target) data table. It's called "Smart" for a reason - it's not just a fancy name: Let's say you have a property (let's say, "Clients Allowed") on a given context (such as "AccessControl", to use a fictional context). For this specific context, the variable is of a binary type - can be either Yes (allow clients) or No (don't allow). Now, let's say you have another context, such as OfficePrinter (again, just saying). This context also has a property called ClientsAllowed. Only this time, it's an integer describing the number of clients which may connect to this printer or poll it. It's not a binary value. But it has the same name! (As can often happen in a diverse, open system.) So, if the default AggreGate Server copy operation just took properties and copied them around based on name only, trouble would soon ensue. We needed a "smart" way of copying property values around without breaking the system, and thus Data Table Smart Copy was developed. Generally speaking, the Data Table Copy operation does its best to copy as much data as possible from the source table to the target table, but always ensures that the target table keeps its original format. For example, if the format definition of the target table specifies that maximum number of records is 5, the table will contain 5 records after the copy operation, even it there were 100 records in the source table. Another example: if both the source and target table contain a field called "value", but it's a String type in the source table and an Integer type in the target table, the copy operation will not change the field type in the target table. Instead, it will try to convert all strings from the source field to integers and write them to the target table. The copy operation is not aborted if errors when copying some record or field. Instead, the operation continues and does its best to copy as much data as it can. Any errors are reported upon completion. The copy process selects one of the following methods: Copy with Key Fields
861 862

Copy without Key Fields

A key field is a field or set of fields of a table which together form a unique identifier for a record (a table entry). The aggregate of these fields is usually referred to simply as "the key". The first method is selected if the format 855 of the target Data Table defines a non-zero number of key fields. When there's no key field, the second method is used. With both methods, the system ensures that the number of records in the target table does not exceed minimum and maximum values (defined by the format of Variable Definition 869 ).

Copy with Key Fields

If the Destination table has Key Fields which aren't defined as Key Fields in the Source table, operation falls back to the copy without key fields 862 method. The copy operation is divided into three stages. Every stage operates with the records that have identical values in all Key Fields in both tables (the combined value of all key fields can be referred to as a "key"). 1. All records in the target table that contain keys not appearing in the source table are deleted. 2. Data from every record of the source table is copied
862

into the record of the target table with the same key, if one

2000-2013 Tibbo Technology Inc.

862
exist.

AggreGate Documentation

3. For every remaining record of the source table, a new record is created in the target table and data from the source record is copied 862 into the new record.

Copy without Key Fields

This method also has three stages. 1. If number of records in the target table is greater then in the source table, last records from the target table are deleted to make the number of records equal. 2. Every record of source table is copied
862

to the record of the target table with the same number.

3. If number of records in the Source table is greater than in the Target table, new records are created in the Target table to make the number equal. Data from the Source record is copied 862 into the new record with the same number.

Data Record Copy Algorithm

When copying a source record (a single row in a table) to a destination record, each field in the row is tested to see if it can be copied: 1. If field is declared as read-only in the format of target record, it is skipped 2. If field is declared as non-replicatable in the format of source of target record, it is skipped 3. If field has the same type in the source and target records, its value is copied directly 4. If field has different types in source and target records, AggreGate Server does its best to convert the value. For example, all types of values can be converted to String, String values can sometimes be converted to Integers, etc.

6.1.5 Building a Data Table From a Parameters List

It may be necessary to build a Data Table from a string-encoded comma-separated list of parameters, e.g. "param1", 'param2', null. For example, this method is used for calling a function from a reference 926 or a query 271 . AggreGate uses a common algorithm to construct a Data Table from a string-encoded parameter list. This algorithm uses field types defined in format 855 to convert string parameters into the proper field values for putting into the various cells within the Data Table. This format may be, for example, input format of the function those input Data Table is being constructed. Simply speaking, the system knows format of table that is being built, takes string values from the source list one-byone, converts them into proper types and fills table cells. Parameters in the list must be separated by commas (","), and it may contain the following types of values: Value Non-quoted string, Single-quoted string Example Description Quotes are trimmed from the string, if it's quoted. The resulting value is treated as an expression 911 that is evaluated and evaluation result is used as the value of a cell in the function's input parameters table. If you're not sure what an expression is, you can think of it like a spreadsheet formula for now (1+1, for example). The chapter AggreGate Expression Language 911 explains all about it. Quotes are trimmed from the string. The resulting value is not treated as an expression -- rather, it is converted to whatever data type the function expects for this argument. Conversion is done on a "best effort" basis -- you can't always convert any data type to any other data type.
1309 .

'{nested_refere nce} + 1' {nested_referen ce} + 1

Double-quoted "123" string

Rules for encoding/decoding values of different types to/from strings may be found here

Each cell in the table gets its value from the corresponding argument in the argument list (i.e. the value of the first cell is the value of the first argument in the list). If a Data Table to be constructed has dynamic (unspecified) format, the system constructs a single-row Data Table with all string fields. Every source parameter is put in a separate field.

Very rarely, a function might expect more than one row of fields (i.e, more than one "record") as its input. If the function's input format defines N fields, the first N arguments are used for filling the first row, second N arguments for the second row etc.

2000-2013 Tibbo Technology Inc.

System Internals

863

Example: Let's say you have a function, func1 (just an arbitrary name), which expects the following input Data Table with two fields and two rows: string_field "abc" "xxx" integer_field 123 456

You would then call it from a reference 926 or a query 271 like this: func1("abc", "123", "xxx", "456"). So, since you have two parameters per row, the first two parameters are used to fill the first row. The next two parameters are used to fill the second row, etc. Note that although the integer values above have double quotes, func1("abc", 123, "xxx", 456) will give the same result. The difference is that integers will be treated as expressions (which consist of simple integer literals) and processing may be slightly slower.

6.1.6 Naming Expression Resolution Environment

The below table describes resolution environment for Data Table's Naming Expression
856 .

Data Table Naming Expression Resolution Environment Default Context None.

927

922

Default Data Table 927 Default Row

927

The table whose naming expression is being evaluated.

Environment Variables 930

Standard

931

variables only.

6.2 Contexts
One of the key concepts introduced in this manual is the context. A context is a logical "container" for data related to some object or hardware device. It also provides methods for manipulating this data and monitoring the object's state. For example, AggreGate Server internally works with contexts that correspond to Devices 113 . It creates a "Device context", and this context is used to monitor and change Device settings, view its events etc.

Context Tree
Almost all data managed by AggreGate Server is represented by contexts. Contexts are organized into a hierarchical structure called a context tree. Every installation of AggreGate Server contains a single context tree. This tree is dynamic, so contexts can be added and removed from it during normal server operation. All contexts available in AggreGate Server are described in Context Reference
651 .

Context Naming
Every context has a name. This is a string that may contain only letters, numbers and underscore character ("_"). For example, the context for the admin user is called "admin". Some context names are pre-defined and built into the system. In other cases the user can specify the name of the context. For example, when creating a new Device account, the name of the Device Account is used as the context name. As mentioned above, the context tree is hierarchical, and every context in the tree may be addressed using its context path. The context path may also referred as the context's full name. The path consists of one or more context names separated by dot (".") characters.

2000-2013 Tibbo Technology Inc.

864

AggreGate Documentation

Example 1: the users context corresponds to all users in the system. It provides some generic user-related data and operations like "New User Account Registration" operation etc.

Example 2: the users.admin.devices.dev1 context (shown here in its full name) corresponds to a Device called dev1 registered under the admin user. This context provides access to the settings of Device and related operations, e.g. "Configure Device" etc. The context tree "grows" from a so-called root context. The root context is unique in that its name is "" (empty string).

One more term related to contexts in the tree is parent-child relationship. Every context in a tree except for the root context has a parent context. Also, every context may have zero or more children. For example, users.admin is a child context for users (which makes users a parent context, obviously...).

Context Path Types

Context paths may be absolute (i.e. resolved from the context tree root) or relative (i.e. resolved from some other context). Relative paths start with a dot (".") character.

Context Descriptions
A "Description" is a user-friendly name for a context. It is used to refer to this context all throughout the user interface. For example, the context description of the context plugins is "Drivers/Plugins Per-account Configuration". Sometimes the user may specify the description manually, such as when creating a new Favourite. In this case, the user-specified description will be used to refer to the favourite in the user interface. Having separate properties for the name and the description allows AggreGate to maintain one name for a context internally, while allowing maximum user friendliness by using a simple description. In addition, changing the description for an object will smoothly alter its appearance in the GUI without "breaking" it (because internally, it will still have the same name).

Context Types

2000-2013 Tibbo Technology Inc.

System Internals

865

The "Context Type" property of a context helps AggreGate decide if the same operations may be applied to different contexts, such as properties between them. For example, you can copy the properties of a Device to another Device, but it would be meaningless to try and copy the properties of that Device to an Alert 216 context. Therefore, AggreGate only allows copying context properties between contexts (also known as "replication the context type is identical between two contexts. Context type is a string that may contain only letters, numbers and underscore character ("_").
866 ")

when

Context Entities
Every context contains a number of so-called entities . There are three types of entities: Variables Functions Events
880 869 878

(Properties) that allow to view or change some data associated with a context. used to execute some actions associated with a context.

helping to see if something happens in a context.

Context States and Icons

Every context has an icon that is used for its visual representation in AggreGate Server user interfaces (like AggreGate Client). Some contexts may have different states. For example, the context for a hardware device may have two states: "online" and "offline". Every state has a different icon associated with it.

Context Permissions
When a user 108 tries to access a context or some of its entities, it does that under his current effective permission level 932 for this context. The latter is defined by user's permissions table 933 . The effective permission level defined what a user can do with the context, for example: Can not access the context at all Can execute only read-only operations and see values Can execute control operations and edit values Etc. The Context Reference
651

section describes what each effective permission level means for every context type.

Higher permission levels always include all permissions allowed by lower permission levels, so this is not explicitly reflected in the Context Reference.

6.2.1 Context Masks

A context mask is a string that corresponds to one or more contexts. A mask name is similar to a context path 863 , but its segments (parts, separated by dots) may include wildcard ("*") characters instead of context names. They are quite similar to the filename masks (like " *.txt") which are often used in computing. Context masks may be resolved to a number of context paths that match to a context mask. Here's an example of a context mask: users.*.deviceservers.*.devices.* Groups 248 provide special context mask syntax to access all group members. See Group Member Context Masks 252 for details.

Resolving Masks
The context mask can be resolved to a list of context paths. For example, the mask users.* may be resolved to the following list of context paths: users.admin users.user1 users.user2 etc.

2000-2013 Tibbo Technology Inc.

866

AggreGate Documentation

And the mask users.*.deviceservers.* may be resolved to users.admin.deviceservers.c1 users.admin.deviceservers.c2 users.admin.deviceservers.c3 users.user1.deviceservers.ds1 users.user1.deviceservers.ds2 users.user2.deviceservers.plc The mask resolution process always involves permission checking 931 . For example, the users.* mask is resolved to the list of user contexts 759 accessible with the permissions of the user 108 that requested the operation. It will be resolved to the list of all users in the system only if the user originating the operation has permissions to access all user accounts.

Matching to Masks
A context path may match to a context mask. Also, context mask may extend a context path, or context path may extend a context mask. To match a context mask, context path must contain the same number of segments (parts between ".") at mask. Also, if any context mask segment is not a wildcard ("*") segment, it should be equal to the correspondent segment of context path. If a path extends a mask, the leading segments of the path must match the mask, but the path may contain any number of additional segments. Similarly, if a mask extends a path, its beginning should match the path, but it will contain additional mask segments.

EXAMPLES
Path users.admin matches mask users.* Path users.admin doesn't match the external_device_servers.* mask Path users.admin.deviceservers.c1 extends mask users.* (i.e, it's longer than that mask - matches the beginning and adds additional segments) Path users.admin.deviceservers.c1 doesn't extend mask users.*.alerts (because the mask don't match to the three leading segments of the path) Mask users.*.deviceservers.* extends path users.admin (because it adds additional information to it) Mask users.*.deviceservers.* doesn't extend path reports.impacts_report (because it doesn't match)

6.2.2 Context Copy Operations

Copy Configuration Operation
Context Copy operation is sometimes referred as Replication in this manual.

The Copy configuration operation is used to configure one context similarly to another. It can be a User account 108 , a Device 113 , an Event Filter 206 , an Alert 216 , etc. This operation can be initiated through the AggreGate Client User Interface, for example, by dragging one System Tree 784 node and dropping it on another node of the same type. Internally, this operation modifies the values of the variables 869 (properties) of the target context 863 (the copy destination) according to the values of the variables in the source. A given value is copied from the source context only if the variable supposed to contain it (i.e, a variable with the same name) already exists on the destination context. The replication operation flows like this: If a variable is not readable in the source context, operation with this variable is aborted If a variable is not writable in the target context, operation is aborted too The server reads the variable value from the source context into the Data Table Then it reads the variable value from the target context into the Data Table B Data from the Data Table A is copied into the Data Table B using Data Table Smart Copy The server rewrites value of the variable in the target context by the Data Table B
861 854

operation

2000-2013 Tibbo Technology Inc.

System Internals

867

If an error occurs on any step, operation with the current variable is aborted. The copy process proceeds to the next variable. Just before the operation begins, users may select 896 variables to be copied. It is also possible to prevent certain fields from being replicated. In addition, new value of every variable may be corrected:

The copy operation returns a report in the following format: Variable description Copy successful (yes or no) Here's what a report looks like: List of errors encountered during copy if this variable

Copy Configuration to Children Operation

The Copy to children operation is similar to the normal context copy 866 operation, but it copies variable values from the source context to every child of the target context, not to the target context itself. This operation can be initiated, for example, by dragging a System Tree 784 node representing some context, and dropping it on a node representing a group of contexts of the same type. In this case all contexts in the group will be configured like the object that was dropped. Copy to children operation outputs a report in the following format:

2000-2013 Tibbo Technology Inc.

868

AggreGate Documentation

Target context

Variable name

Copy successful (yes or no)

List of errors encountered during copy if this variable

Here's a sample report:

6.2.3 Visible and Real Context Trees

This section covers the difference between visible Context Tree and server-side Context Tree. It is very important to know, that structure of context tree visible in the System Tree 784 and similar components (such as Entity Selector 815 ) does not exactly match real structure of AggreGate Server contexts 863 tree. For user convenience, nodes corresponding to a single server-side context may appear in two, three or even more locations of the System Tree. For example, a single Device Context
677

representing hardware device may simultaneously appear:

Under Devices node showing Devices of the active user (those context path is users.username.devices) Under Devices node combining all Devices in the system (those context path is just devices) And under one or more Device Group nodes (with context path like users.username.devgroups.group1)

The nodes indicated by arrows on the above picture all correspond to a single server-side context. Its absolute server path may be found out by holding mouse over System Tree node and checking its tooltip:

This difference may cause unexpected results when checking paths of contexts visible in the tree. Here is an example:

2000-2013 Tibbo Technology Inc.

System Internals

869

the tree may show a Device ABC context under Root > Devices. However, the real server path of this context is users.Owner_Name.devices.deviceABC where Owner_Name is the AggreGate Server user 108 owning the device. The server-side Devices context has no real children at all, as it is a so-called mapped context.

Container Paths
New AggreGate users often mix "real" and "mapped" container contexts. Most contexts in the root of System Tree are mapped. For example, if we hover a mouse over Devices node, we'll see that its context path is devices:

If we expand this node and check a path of device context located right under it, we'll see that its path is users. admin.devices.virtual:

It actually means that the real container of our device named virtual is users.admin.devices. It belongs to a system user 108 called admin. We can find this real container by going to Users => admin (Administrator) => Devices (note the third arrow on the below image):

6.3 Variables
Variables contain context 863 -related data. For example, the users.admin context has the childInfo variable (property) that contains a username, password, e-mail and some other properties of a given user. In AggreGate Server, value of every variable is actually a Data Table 854 . Even simple numeric and string values are represented by one-cell Data Tables. This helps to a use a generic approach for the processing of variable values. All variables can be processed using the routines for handling tables (such as smart data table copy 861 ), even if they contain just a single number or string. Context variables are sometimes referred as properties. These two words are interchangeable in AggreGate jargon. They're one and the same.

2000-2013 Tibbo Technology Inc.

870

AggreGate Documentation

Value of every context variable is a Data Table

854

Variable Definition
Every variable is defined using a Variable Definition which contains several options: Variable Name. The name is unique within context where variable is defined. This is a string that may contain only letters, numbers and underscore character ("_"). Variable Format. Table Format 855 of the Data Table 854 for the variable. This actually defines what the variable can look like - minimum and maximum rows, field types, possible field values, validation rules, etc. Readable. Flag indicating that it is possible to get value of the variable from the context. This can be useful for sending messages to a device without getting a reply, such as when sending out a string to be displayed on an attached LCD screen. Writable. Flag indicating that it is possible to change value of the variable to a new one. Description . Description of the variable. Help. Detailed description of the variable. Group. Shows that variable belongs to a variable group. The group may be not defined, i.e, there can be variables which do not belong to any group. Groups help to select a number of variables for processing. For example, a Device context may have a Configure action 892 for configuring the Device Account, and another action for configuring the hardware DS. Each action will operate with all variables of a separate group. Group name may be pre-defined on the AggreGate Server or come from some hardware device, but it cannot be changed by the user. Read Permissions . Permission level Write Permissions. Permission level
932 932

required to get value of this variable. required to change value of this variable.

AggreGate Server processes variables in various ways. If you pass a Data Table as the value of a variable, you won't necessarily get the same exact table back when you try and retrieve the value of the variable. Internally, variables are divided into several types: In-memory structures that are not saved when AggreGate Server is stopped. Persistent settings that are stored in the database
854 .

Settings of Devices that are read/written from a remote device and cached by the server.

2000-2013 Tibbo Technology Inc.

System Internals
"Virtual" variables. The value of virtual variables is generated on-the-fly, and they're not permanently stored.

871

If there are problems in setting or getting variable values, an exception may be thrown. In the case of "get variable" operation, no value is returned. "Set variable" might throw an exception even though variable value was indeed set, due to some other reason. The exception contains a textual description of the problem.

Variable Status
Variables of AggreGate contexts may also have custom status. Variable status is a combination of a status code and human-readable status description. Variables statuses are displayed in the leftmost column of Properties Editor 795 . However, there are some other ways to see variable statuses. For example, statuses of device setting variables are shown in the Device Status 910 dialog.

Examples
In the User 759 context there is a variable called childInfo ("User Information"). Its value always contains one record (as specified by Variable Format) with several fields that store the user's first name, last name, phone number etc. In the Event Filter 688 context there is a variable called rules ("Filter Rules"). Its value may include numerous records ("lines"), each of describing an event type to be shown when the event filter 206 is activated.

6.3.1 Common Variables

This section describes variables that are common for most AggreGate contexts
863 .

6.3.1.1 info (Context Information)

This variable contains basic information about the context.

Variable Name: Records: Permissions: Record Format Field Name

description
855

info

1 Readable/writable at None permission level :

Field Type Notes
932

Field Description

Description 864 of the context, i.e. textual information about its purpose. Type
864

String

type group icon

of the context.
848 .

String String String Nullable Nullable

Context group. Should be NULL in AggreGate Agent

Context icon ID. Used for visual representation of context in the user interface. Should be NULL in Agent 848 . Used within the distributed architecture 99 . Path of the mount point's root in the local (consumer server) context tree. Used within the distributed architecture 99 . Path of mount point's root in the remote (provider server) context tree. If null, this context is local (i.e. not a proxy from any remote provider server). Used within the distributed architecture 99 . Path of this context in the remote (provider server) context tree. Returns true if context's children are mapped (e.g. for group and aggregation contexts).

localRoot

String

remoteRoot

String

Nullable

remotePath

String

mapped

Boolean

2000-2013 Tibbo Technology Inc.

872

AggreGate Documentation

6.3.1.2 children (Context Children)

This variable contains a list of the context's child contexts, one record per child. When you get this variable, you see only children that are accessible at your current permission level 932 , not necessarily all existing children.

Variable Name: Records: Permissions: Record Format Field Name

name
855

children

0...unlimited Readable/writable at None permission level :

Field Type Notes
932

Field Description

Name of child context.

String

6.3.1.3 variables (Context Variables)

This variable contains basic information about variables that are available in the context. When you get this variable, you see only variable definitions that are accessible at your current permission level 932 , not necessarily all existing variables. Read more about variable definition fields under Variables 869 .

Variable Name: Records: Permissions: Record Format Field Name

name format
855

variables

0...unlimited Readable/writable at None permission level :

Field Type Notes
932

Field Description

Name of the variable. Format of variable encoded 1307 into String. If this field is NULL, the variable has a dynamic format -- it may return data of any format. Variable description. Flag indicating that variable is readable at your permission level. Flag indicating that variable is writable at your permission level. Detailed variable description. Variable group, or NULL if variable does not belong to any group. ID of icon used to represent the variable (for internal use). ID of documentation article describing the variable (for internal use).

String String Nullable

description readable

String Boolean

writable

Boolean

help group

String String

Nullable Nullable

iconId helpId

String String

Nullable Nullable

2000-2013 Tibbo Technology Inc.

System Internals

873

6.3.1.4 functions (Context Functions)

This variable contains basic information about functions available in the context. When you get this variable, you see only function definitions that are accessible at your current permission level 932 , not necessarily all existing functions. Read more about function definition fields under Functions 878 .

Variable Name: Records: Permissions: Record Format Field Name

name inputformat
855

functions

0...unlimited Readable/writable at None permission level :

Field Type Notes
932

Field Description

Name of the function. Format of function input encoded 1307 into String. If this field is NULL, the function has a dynamic input format -- it may accept data of any format. Format of function output encoded 1307 into String. If this field is NULL, the function has a dynamic output format -- it may return data of any format. Description of the function. Detailed description of variable. Variable group group.
870 ,

String String Nullable

outputform at

String

Nullable

description help group

String String String Nullable Nullable

or NULL if variable does not belong to any

6.3.1.5 events (Context Events)

This variable contains basic information about events that are available in the context. When you get this variable, you see only event definitions that are accessible at your current permission level 932 , not necessarily all existing events. Read more about event definition fields under Events 880 .

Variable Name: Records: Permissions: Record Format Field Name

name format
855

events

0...unlimited Readable/writable at None permission level :

Field Type Notes
932

Field Description

Name of the event. Format of event data encoded 1307 into String. If this field is NULL, the event has a dynamic format -- it may contain data of any format. Description of the event.

String String Nullable

descriptio

String

2000-2013 Tibbo Technology Inc.

874

AggreGate Documentation

n help level group Detailed description of the event. Default level of the event. Event group group.
881 ,

String Integer String

Nullable

or NULL if event does not belong to any

Nullable

6.3.1.6 actions (Context Actions)

This variable contains basic information about actions 892 available in the context. When you get this variable, you see only action definitions that are accessible at your current permission level 932 , not necessarily all existing actions.

Variable Name: Records: Permissions: Record Format Field Name

name description help accelerator dropSource s hidden enabled iconId group executionG roup default
855

actions

0...unlimited Readable/writable at None permission level :

Field Type Notes
932

Field Description

Name of the action. Description of the action. Detailed description of the action. Action hotkey. Drag-and-drop activation rules.

String String String String Data Table Nullable Nullable Nullable Nullable

Action visibility flag. Action availability flag. Action icon ID. Action group. Action execution group.

Boolean Boolean String String String Nullable Nullable Nullable

Flag defining whether this action is a default one in its context.

Boolean

6.3.1.7 contextStatus (Context Status)

This variable contains information about context status. To track context status changes, subscribe to contextStatusChanged 890 event.

Variable Name:

contextStatus

2000-2013 Tibbo Technology Inc.

System Internals Records: Permissions: Record Format Field Name

status comment
855

875

1 Readable/writable at None permission level :

Field Type Notes
932

Field Description

Numeric context-specific status code. Textual description of context status.

Integer String

Nullable Nullable

6.3.1.8 activeAlerts (Active Alerts)

This variable provides information about alert
216

instances that are currently active for the context.

Variable Name: Records: Permissions: Record Format Field Name

location
855

activeAlerts

0...unlimited Readable/writable at None permission level :

Field Type Notes
932

Field Description

Defines location of the alert within a distributed installation 99 . Local means that the alert active for this context is defined on the consumer server while Remote indicates that the alert is defined on the remote provider server. ID of alert event
224 . 656 .

Integer

event alert type time level message trigger cause data

Long String

Hidden field.

Path of alert context

Instance type: Active Alert raise time. Alert level. Alert message. Alert trigger message. Alert cause. Alert data.

235

and Pending

236

Integer Date Integer String String String Data Table

6.3.1.9 groupMembership (Group Membership)

This variable provides information about groups
248

that current context participates in.

Variable Name: Records: Permissions: Record Format

855

groupMembership

0...unlimited Readable at None permission level :

932

2000-2013 Tibbo Technology Inc.

876

AggreGate Documentation

Field Name
location

Field Description

Field Type

Notes

Defines location of the group within a distributed installation 99 . Local means this context is a member of the group defined on the consumer server while Remote indicates that this context is added to a group located on the remote provider server. Full path of group context
702

Integer

group

that holds current context.

String

6.3.1.10 validity (Validity)

This variable lists contexts that the current context is valid
948

for.

Variable Name: Records: Permissions: Record Format Field Name

context
855

validity

0...unlimited Readable at None permission level :

Field Type Notes
932

Field Description

Full path of context

702

that current context is valid for.

String

6.3.2 Processing Historical Values

Context variable values are frequently updated. The values can be manually modified by human operators or changed by autonomous system components (such as scheduled jobs 266 ). In the simplest case, new values are received from hardware devices during synchronization 126 . Once value of a context variable has been changed, AggreGate Server can optionally keep its old value to allow tracking historical changes of the variable. The historical values can be later used for: Displaying historical trends on charts Building reports
241 384

(such as last day temperature chart)

(such as monthly fuel consumption report)

Exporting them to third-party systems

Raw History vs Statistics

AggreGate Server provides two ways to preserve historical values: Storing "raw history" in a classic relational database (see server database
80

Storing aggregated history in a round-robin database (see statistics module Each of these methods has its own pros and cons.

936 )

RAW HISTORY
In the "raw history" storage mode, every historical value of a variable is stored as a separate record in one of the tables of server database 80 . Pros of this method:

2000-2013 Tibbo Technology Inc.

System Internals
Full precision of old values, regardless to the sampling rate Cons of this method: Large volume of historical data Slow storage Slow retrieval of historical values, especially if loading samples collected during a long time frame

877

STATISTICS
When variable history is stored in the statistical process control 936 database, its old values are not kept "as is". Instead, server calculates a numeric "aggregate" of every value and uses it to calculate hourly/daily/weekly/monthly/yearly averages, minimums and maximums. Pros of this method: Compact file-based storage of historical data Size of preserved historical values does not increase with time Fast storage Extremely fast access to historical values, regardless of the time frame length Cons of this method: Only aggregated historical values are available, the original "raw" values as not saved Precision of calculated aggregates decreases with time

Enabling Variable History Storage

To enable storing raw history of a device setting variable, open device setting synchronization options zero Update History Storage Time. Also, set History Mode properly. To enable storing aggregated statistics of a device setting variable, open device settings statistics new statistical channel. Point it to the necessary variable and configure other options.
117 115

and set not-

and create a

Accessing Variable History

There are several methods to access historical values of a variable. The suitable method depends on the type of processing.

BUILDING A CHART
To build a chart values):
384

that displays historical trend of a variable (this method is valid for graphing both raw and statistical
312

Create a widget

and add an XY Line Chart

429 ,

XY Area Chart

436

or XY Bar Chart

440

to it.

Set chart's Data Source Type to Variable. Edit Source Variables table and add new series Point the series to the necessary variable. Write series expression that refers fields of the variable or statistical channel that is based on this variable. Make sure that Include Historical Data option of a chart is enabled.
393 .

ACCESSING VARIABLE HISTORY AS A TABLE

In most cases, variable history should be accessed in the form of table similar to that: Timestamp Value

This table is suitable for: Building a query

271

over historical values

241

Building a variable history report

2000-2013 Tibbo Technology Inc.

878

AggreGate Documentation

Exporting data to third-party systems To obtain such a table of "raw" historical values, use variableHistory 764 function of Utilities context. This function loads a certain subrange of raw historical values and returns it them as a table. Here is an example of expression devices.meter:
911

that returns history of variable temperature defined in device users.admin.

{utilities:variableHistory("users.admin.devices.meter", 12:00:00.000", "2012-05-04 12:00:00.000")}

"temperature",

"2012-05-03

If the raw history of your variable is not being saved, but there is a statistical channel that aggregates its historical values, you can use statistics 767 function of Utilities context to get the table of the following format: Period Start Period End Aggregated Numeric Value (Average, Minimum or Maximum)

Here is an example of expression 911 that returns hourly averages, minimums and maximums for a statistical channel named temperature that is defined for device users.admin.devices.meter:

{utilities:statistics("users.admin.devices.meter", "temperature", null, "hour", true, true, true, true)}

6.3.3 Variables Performance

The performance of a variable read and write operations dramatically depends on "nature" of the variable and underlying algorithms. Here are some examples: Retrieving value of a cached 115 device setting variable is very fast, even millions of read operations per second will have no significant CPU load impact. Same applies for writing new value of the variable, since the actual device I/O will be delayed and the call returns asynchronously. Retrieving properties of widget components Reading data 283 .
717 322

is also very fast.

variable from a Query context triggers query execution, involving associated CPU and memory load

If value of any remote variable was requested (e.g. an AggreGate Client has requested it from an AggreGate Server or a consumer server has requested it from a provider server in a distributed environment 99 ), additional time will be required to send a corresponding request to the remote server and get the response. This time is generally equal to the round-trip time reported by ping command.

6.4 Functions
Functions are operations that can be executed on a context 863 . For example, the users.admin.devices.dev1 context may contain a reboot function that reboots the admin.dev1 Device . Every function has an input and output value. Both values are actually Data Tables 854 . Each of these Data Table may have many lines and fields and even contain nested Data Tables in its cells, so the number of possible input and output parameters of a function is virtually unlimited. The input and output values of every context function is a Data Table
854 .

Function Definition
Every function is defined using a Function Definition. The Definition contains several options: Function Name. The name is unique within the context in which the function is defined. This is a string that may contain only letters, numbers and underscore character ("_"). Input Format. Table Format
855

of the Data Table

854

used to specify the input value of the function.

Output Format. Table Format of a Data Table used to output the result of the function. Description . Description of the function. Help. Detailed description of the function. Permissions. Permission level
932

required to access this function.

2000-2013 Tibbo Technology Inc.

System Internals

879

Group. Shows that function belongs to a function group. Groups help join several similar functions together during different operations.

If a function is unable to finish its job, it will throw an exception containing a a textual description of the problem.

EXAMPLES
The Users 756 context has a function called list ("List Users") that returns a list of all User Accounts that are accessible for the user calling it. The Scheduled Jobs specified parameters.
742 108

on the server
266

context has a function called create ("Schedule New Job") that creates a new job

with the

Note that functions are non-interactive in themselves. These are internal server operations - they happen "behind the scenes". To provide input for a function (or to view its output), UI Procedures 896 are used. When a function is used with interactive UI Procedures, it is called an Action 892 .

6.4.1 Common Functions

This section describes functions that are common for most AggreGate contexts
863 .

6.4.1.1 makeCopy (Make Copy)

This function is used to clone a system object, e.g. an Alert context, i.e. context where it is defined.
216 .

It creates a copy of specified context under the current

Function Name: Permissions: Input Records:

Input format :
855

makeCopy

Accessible at Manager permission level

932

Name context

Type Strin g

Description Path of a context copy of that will be created under current context.

Output Records: 0...unlimited Output format 855 : Name variable Type Strin g Boole an Strin g Description Name of variable those value was replicated.

successful

Replication status, successful or not.

errors

Replication error list.

2000-2013 Tibbo Technology Inc.

880

AggreGate Documentation

6.4.1.2 delete (Delete)

This function is used to permanently destroy a child of the current context.

Function Name: Permissions: Input Records:

Input format 855 :

delete

Accessible at Manager permission level

932

Name name

Type Strin g

Description Name of a child context to delete.

Output Records: Output format 855 :

0
none

6.4.2 Functions Performance

The performance of a function call dramatically depends on "nature" of the function and underlying algorithm. Here are some examples: Synchronize
678

function of a Device context is very fast as it just schedules a synchronization

126

and returns.

Execute query 739 function will generally have noticeable performance effect which depends on query complexity and size of its source dataset. Calling a function that matches a device operation takes time required for device I/O but don't cause server-side CPU load. If a remote function was called (e.g. an AggreGate Client has called it from an AggreGate Server or a consumer server has called it from a provider server in a distributed environment 99 ), additional time will be required to send a corresponding request to the remote server and get the response. This time is generally equal to the round-trip time reported by ping command.

6.5 Events
An Event for a given context 863 is fired if something happens in that context. For example, the login event defined in the users context indicates that a new user has been logged in to the AggreGate Server. An event in a Device context may occur if it is initiated by the hardware device. Every event in AggreGate Server has a special structure called Data Table 854 associated with it. This Data Table contains event-specific data. For example, the login event may contain one record with a username field containing the user name of the newly logged user. Event-specific data is formatted as a Data Table
854 .

Event Definition
Every event is defined in its context using an Event Definition. An Event Definition contains several options: Event Name. The name is unique within the context where the event is defined. This is a string that may contain only letters, numbers and underscore character ("_"). Event Format. The Table Format
855

of a Data Table

881

representing event-specific data.

Description . Description of the event. Help. Detailed description of the event. Expiration Period. Defines how long persistent event is stored in the event history
882 .

2000-2013 Tibbo Technology Inc.

System Internals

881

Level . Severity of the event. This is the default level for this event, but the actual event fired in the context may have another severity level. The levels are listed below 882 . Permissions. Permission level
932

required to receive events of this type.

Group. Shows that event belongs to a event group. Groups help join similar event instances together during different operations.

Examples
The Alert
656

context has an alert ("Alert") event which fires when an alert

726

216

is triggered.

The AggreGate Server Root context

has a login ("User Login") event which fires when a user logs in to the server.

6.5.1 Event Parameters

Every event has the following parameters: Unique event ID Context
863

where the event was fired

Creation time Expiration time Event level Event-specific data in the form of Data Table Acknowledgements Enrichments
883 882 854

(see Event Data Table below)

(for persistent events only)

(for persistent events only)

Event Data Table

Every event has an Data Table attached to it. This Data Table is different for every event type, and contains relevant information for this event type. You might say it's "notes" or "particulars" for this specific event type. For example, the login event has a username field, indicating what user logged in. This field is used only for the login event -- there's no use for it in an alert event (for example). So it's contained within the Data Table for the login event (and there's no such field in the data table for the alert event).

2000-2013 Tibbo Technology Inc.

882

AggreGate Documentation

6.5.2 Event Levels

Levels describe the severity of an event. When an event is fired, its level may be either assigned by the component firing it or set to some default value specified in the Event Definition. There are several predefined event levels: None (undefined severity) Notice (the least severe) Info Warning Error Fatal (the most severe) Numeric values of event levels (may be used in different expressions Level None Notice Info Warning Error Fatal Value 0 1 2 3 4 5
911 ,

e.g. during event filtering

207 ):

6.5.3 Event Listeners

If an AggreGate Server component "wants" to know what's going on in a particular context, it starts to listen for events in that context. For this, it has to register a special context event listener . This listener receives a notification whenever the selected event is fired in the context. For example, the Event Log 791 component in AggreGate Client registers event listeners in the contexts defined by the active Event Filter 206 . When these events are fired, the Event Log receives notifications. It uses these to display new events. Event listeners may be dynamically added and removed during server operation.

6.5.4 Event History

Persistent events are stored in the event history. The event history is a special database 80 table that contains all persistent events that were generated by the various AggreGate Server components. Other components may access the event history through the events context. For example, the Event Log component in AggreGate Client uses this context to display event history. Each event stored in the history has an expiration period. When an event expires, it is automatically removed from the history. The default expiration period is 10 days, but it can be changed by editing Event Expiration Times 70 table in AggreGate Server Global Configuration options.

6.5.5 Event Acknowledgement

Every persistent event may be acknowledged one or more times. An acknowledgement is a text string which may be entered and viewed using the Event Log 791 component of AggreGate Client. A user can also enter the acknowledgement text when an alert 216 pops up in the AggreGate Client. If the alert requires an acknowledgement, the popup will prompt the user to enter the acknowledgement text. The acknowledgement comprises of a timestamp, username (who acknowledged the event) and the acknowledgement text.

2000-2013 Tibbo Technology Inc.

System Internals

883

Example: Server Failure event can be acknowledged by a system operator who added "Replaced defective memory stick." message. Acknowledgements are usually generated by humans. They're useful for accountability - you can be certain that a human operator saw the event, and can also tell which operator it was, when they saw it and what they had to say about it.

Event Acknowledgements Table

Event acknowledgements table can be referred from diverse event filtering expressions
911 .

It has the following format:

Field Name
author time text

Field Type
String Date String

Notes
Username of acknowledgement creator. Acknowledgement timestamp. Acknowledgement text.

6.5.6 Event Enrichment

is the process of adding important attributes originated from AggreGate internal resources or external systems to an event. Each event may have unlimited number of enrichments each of those is described by a name string and a value string.
Event enrichment In contrast to event acknowledgements, enrichments are usually generated by AggreGate components and external systems, not by humans. Example: AggreGate is often integrated with Service Desk systems so that a trouble ticket is created in the Service Desk upon AggreGate alert 216 . An external Service Desk system may enrich alert event 224 instances with numbers of those trouble tickets so that AggreGate operators will be able to quickly identify a ticket associated with an alert.

Event enrichments are associated with a certain instance of event, not its type. Each event instance can be enriched immediately after its creation or later at any time.
The enrichments can be browsed in Event Log
791 : 206

Enable Enrichments column in the event filter

setting to see enrichments of all events.

Right-click on an event and select View Enrichments to browse detailed information about enrichments of a particular event. Newly created event instances can be automatically enriched by AggreGate Server. See Enrichments Event Processing Rules article for more information.
71

section in

Event Enrichments Table

Event ennrichments table can be referred from diverse event filtering expressions
911 .

It has the following format:

Field Name
name

Field Type
String

Notes
Enrichment name. The name can contain only English letters, numbers, and underscores. Enrichment content. Enrichment timestamp. Username of enrichment creator.

value date author

String Date String

2000-2013 Tibbo Technology Inc.

884

AggreGate Documentation

6.5.7 Event Management

Event management is a technology for making sense of a large number of events and pinpointing a few ones that are really important. This section describes how events received from diverse sources and generated within the system can be managed by AggreGate operators and administrators. Event management is a complex task involving multiple stages: Event filtering 884 . At this stage, events that don't match specific criteria (source, severity, domain-specific rules) are being filtered out from processing chains and business views. Event aggregation 884 . Aggregation, also called event deduplication or reduction, allows the system to minimize the overall number of processed events by joining instances that have matching deduplication IDs. Event masking deemed failed.
884

. Masking means ignoring events that come from sources that depend on system elements that are

Event correlation 885 . Correlation engine finds simple relations between similar events, usually one of them marking an outset of a certain process or state, and the second marking its termination. Root cause analysis 885 . This is the most complex stage of event management process. It involves analyzing relations between events and their environment followed by finding a cause of each event.

6.5.7.1 Event Filtering

Event filtering consists in discarding events that are deemed to be irrelevant. For instance, a number of bottom-of-therange devices may be difficult to configure and occasionally send events of no interest to AggreGate (e.g., printer P needs A4 paper in tray 1). There are several ways to filter unnecessary events in AggreGate Server: 1. Many device drivers 129 and plugins 950 that are capable of receiving events from diverse hardware provide different mechanisms of skipping certain events or downgrading their severity. For example, Syslog plugin has a special Severity Conversion Table allowing to fine-tune level of AggreGate events that are generated upon Syslog messages reception. 2. Certain events may be suppressed from any processing, storage and routing chains by configuring a Pre-filter in Event Processing Rules 70 . 3. It's also possible to filter our certain events at the presentation level. First, Event Filters 206 allow to see only relevant events during real-time event monitoring and event history browsing. Second, most system facilities that are involved in event mining allow to specify different filtering criteria, from simple (such as start/end timestamps and minimal levels) to flexible (expression 911 -based).

6.5.7.2 Event Aggregation

Event aggregation (also known as event deduplication or reduction) consists in merging duplicates of the same event. Such duplicates may be caused by transport network instability (e.g., the same event is sent twice by the event source because the first instance was not acknowledged sufficiently quickly, but both instances eventually reach the event destination). Another example is temporal aggregation, when the same event is sent over and over again by the event source until the problem is solved. AggreGate Server event processing rules 70 allow to specify a Deduplication ID Expression that will be used to find event duplicates by matching events' Deduplication IDs . Such duplicate events will be merged, and the aggregated event will preserve total number of duplicate along with timestamp of the most recent duplicate. Another event aggregation facility is provided by Alert's Event Triggers 222 . These triggers allow creating an aggregated event (Alert Event 224 ) only if originating event occurred more than N times within a certain time frame.

6.5.7.3 Event Masking

Event masking (also known as topological masking) consists in ignoring events pertaining to systems that are downstream of a failed system. For example, network servers that are downstream of a crashed router will fail availability polling. In AggreGate, every Device 113 has a Dependency Expression 124 that prevents its synchronization and polling by suspending it when this expression resolved to FALSE. Thus, you can set your devices to be dependent to other device (s) or resource(s), preventing any event to be originated from any device auto-disabled according to its dependencies.

2000-2013 Tibbo Technology Inc.

System Internals

885

6.5.7.4 Event Correlation

Event correlation allows AggreGate Server to find simple relations between two similar events, one of them being an originator of a certain process (or state), and the second one terminating this process. Event correlation is performed by alert's Event Triggers 222 . Every trigger activates an alert upon receiving first event (called primary event) and deactivates it upon another event (correlated event). Both events are pre-processed according to trigger expression 911 , allowing to activate and deactivate alert upon events of the same type having differing parameters.

6.5.7.5 Root Cause Analysis

Root cause analysis is the last and most complex step of event management. It consists of analyzing dependencies between events, based for instance on a model of the environment and dependency graphs, to detect whether some events can be explained by others. For example, if database D runs on server S and this server gets durably overloaded (CPU used at 100% for a long time), the event the SLA for database D is no longer fulfilled can be explained by the event Server S is durably overloaded. AggreGate's approach for a root cause analysis is implemented by setting up advanced Alerts 216 . An alert, that is an event by itself 224 , is always caused by certain event (if using Event Triggers 222 ) or state (if using Variable Triggers 217 ). This cause is associated with the alert event and persistently stored, allowing to find out the root cause of any problem during real-time event monitoring or when analyzing event history.

6.5.8 Event Lifecycle

This article describes the lifecycle of a server event. Events generated in Agents simpler lifecycles with less stages.
848

and AggreGate Clients

776

have

1. Some system component wants to fire an event during its operation. For example, the component responsible for communications with a particular Device (it is called a Device Driver ) fires an info event in the this Device's context when the connection with the Device is broken. 2. Permissions 931 of the event generator are checked. If its permissions does not allowing firing this type of event in this particular context, event generation fails. 3. If Prefilter Expression
70

is defined, it is now evaluated. If it returns false, event generation is omitted.

4. If Deduplication ID Expression 70 is defined, it is now evaluated. That the system tries to find another event with the same deduplication ID, and if it's found current event it dropped but occurrence counter of the previous one is increased. 5. Event is enriched
883

with additional user-defined data.

6. If the event is defined as persistent, it is saved to the event history. You cannot make an event permanent if it's not already defined as such (most events are permanent). You can, however, change the "time to live" of an event (its expiration time). This is done by changing the Event Expiration Times 70 table in AggreGate Server Global Configuration (See Event History 882 section). 7. Every registered listener receives a notification.

6.5.9 Common Events

This section describes events that are common for most AggreGate contexts
863 .

6.5.9.1 info (Information)

This event fires when something happens within a context which might be useful for human users to know about. This covers things such as a problem with synchronizing the settings between a hardware device and the AggreGate Server database (for a Data Terminal 677 context). The Format 855 for this event is a single String field called "info", containing a human-readable description of the event. The info event is defined in all AggreGate Server contexts. It is persistent, i.e. stored in event history
882 .

Event Name Permissions:

info

Accessible at context's permission level

932

2000-2013 Tibbo Technology Inc.

886

AggreGate Documentation

Expiration Period:

1 week 1
855

Records: Record Format Field Name

info

: Notes

Field Type

String

Text of informational message.

6.5.9.2 childAdded (Child Added)

This event fires when a new child context is added to the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

childAdded

Accessible at context's permission level

Non-persistent

932

Records: Record Format Field Name

child
855

1 : Notes

Field Type

String

Name of child.

6.5.9.3 childRemoved (Child Removed)

This event fires when a child context is removed from the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

childRemoved

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format Field Name

child

: Notes

Field Type

String

Name of child.

2000-2013 Tibbo Technology Inc.

System Internals

887

6.5.9.4 variableAdded (Variable Added)

This event fires when a new variable definition is added to the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

variableAdded

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format

: matches format of variables

872

variable.

6.5.9.5 variableRemoved (Variable Removed)

This event fires when a variable definition is removed from the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

variableRemoved

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format Field Name

name

: Notes

Field Type

String

Name of the variable.

6.5.9.6 functionAdded (Function Added)

This event fires when a new function definition is added to the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

functionAdded

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format

: matches format of functions

873

variable.

2000-2013 Tibbo Technology Inc.

888

AggreGate Documentation

6.5.9.7 functionRemoved (Function Removed)

This event fires when a function definition is removed from the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

functionRemoved

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format Field Name

name

: Notes

Field Type

String

Name of the function.

6.5.9.8 eventAdded (Event Added)

This event fires when a new event definition is added to the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

eventAdded

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format

: matches format of events

873

variable.

6.5.9.9 eventRemoved (Event Removed)

This event fires when an event definition is removed from the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

eventRemoved

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format Field Name

name

: Notes

Field Type

String

Name of the event.

2000-2013 Tibbo Technology Inc.

System Internals

889

6.5.9.10 actionAdded (Action Added)

This event fires when a new action definition is added to the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

actionAdded

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format

: matches format of actions

874

variable.

6.5.9.11 actionRemoved (Action Removed)

This event fires when an action definition is removed from the context. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

actionRemoved

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format Field Name

name

: Notes

Field Type

String

Name of the action.

6.5.9.12 actionStateChanged (Action State Changed)

This event fires when context action's state is changed. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

actionStateChanged

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format

: matches format of actions

874

variable.

2000-2013 Tibbo Technology Inc.

890

AggreGate Documentation

6.5.9.13 infoChanged (Info Changed)

This event fires when basic context information is changed. This event is defined in all AggreGate Server contexts. It is non-persistent, i.e. not stored in event history
882 .

Event Name Permissions:

Expiration Period:

infoChanged

Accessible at context's permission level Non-persistent 1

855

932

Records: Record Format

: matches format of info

871

variable.

6.5.9.14 contextStatusChanged (Status Changed)

This event fires in a context when the context changes its status (also known as state 865 ). For example, in a Device context this event fires when the Device is connected and its context changes its status from "Offline" to "Online". The format
855 675

for this event defines two fields:

status: an Integer number indicating the new state for the context comment: a String containing a human-readable description for the new state This event is defined in all AggreGate Server contexts that have different states history 882 .
865 .

It is persistent, i.e. stored in event

Event Name Permissions:

Expiration Period:

contextStatusChanged

Accessible at context's permission level 1 week for Group Context 1 week for Alert Context
702

932

656 753

1 day for Tracker Context

Non-persistent in all other cases Records: Record Format Field Name

status commen t oldStatu s
855

1 : Notes

Field Type

Integer String

New context status. Description of current context status.

Integer

Previous context status.

6.5.9.15 updated (Variable Updated)

This event is fired when value of the some variable Event Name Permissions:
updated
869

defined in this context is modified.

Accessible at Observer permission level

932

2000-2013 Tibbo Technology Inc.

System Internals

891

Expiration Period:

Non-persistent (see Change 1

855

891

event for variable update persistence)

Records: Record Format :

Field Name Field Type

variable value String Data Table

Notes
Name of changed variable. New value of the variable.

6.5.9.16 change (Variable Changed)

This is a "system-level" counterpart of updated 890 event. The "change" event is fired when value of the some variable 869 defined in this context is modified. In contrast to the "updated" event that is designed to deliver property changes to other system modules, the "change" event is used to persistently store historical property values. The history of this event is internally used by different system components to retrieve property history. Event Name Permissions:
Expiration Period: change

Accessible at Observer permission level

932

Dynamic, depends on a type of the variable those value was updated. 1

855

Records: Record Format :

Field Name Field Type

variable value data String Data Table String

Notes
Name of changed variable. New value of the variable. Value of the variable encoded into string, without format. This field is filled only when "value" field is NULL.

6.5.10 Events Performance

AggreGate Server is capable of processing millions of events per second. However, all events are different, and while one event occur without any consequences others got saved to the server database 80 and delivered to remove listeners, causing CPU load and network I/O. In plus, local listeners can perform complex event processing, causing additional CPU and memory load. Here are some notes on events performance: If an event is not persistent (e.g. database storage is disabled for its type) and not listened by any system components (such as model 307 or widget bindings 604 ), it's occurrence doesn't cause any noticeable CPU or memory utilization Saving an event to the database causes disk and CPU load on the server database machine. The maximum database storage rate is practically limited by several thousand of events per second. This is a limit implied by the underlying database engine. Events triggering server-side operations (such as validity re-evaluation 948 or model binding processing 307 ) cause additional performance impact defined by those operations. See corresponding performance articles for more information. Events that are delivered to remote listeners (such as bindings 604 of widgets running inside AggreGate Client) can cause considerable network bandwidth utilization if occur too often.

2000-2013 Tibbo Technology Inc.

892

AggreGate Documentation

6.6 Actions
Actions are human-executable operations that are associated with a context for example, in the context menu for a System Tree 784 node.
863 .

A list of available actions may appear,

There is a key difference between context actions and context functions 878 : Unlike functions, actions may interact with a user by generating some output or requesting data input. Not all actions are interactive, but most involve several steps that require user attention. Actions interact with the user using UI Procedures 896 . Every action is a combination of UI Procedures and server-side data operations, such as function 878 calls, changing or analyzing variable 869 values, etc. For more information, see the UI Procedures 896 chapter. The sequence of server-side data processing operations and UI procedures performed by an action is called action flow.

Just for contrast, here are some Actions: The Data Terminal 677 context has a Configure action that interacts with the user and lets them change the settings for a Data Terminal 113 The Alerts 654 context has a Create New Alert action that prompts for the basic settings of a new Alert 216 , creates it (by calling the "Create new alert" function ) and then interacts with the user again, allowing him to configure the newly

2000-2013 Tibbo Technology Inc.

System Internals
created alert. And here are some Functions: The Root context The Users
756 726

893

of the AggreGate Server has a Stop Server ("stop") function that stops the server.

context has a Delete User Account ("delete") function that removes a given user account.

As you can see, functions are "machine" operations, while actions actually require user intervention and input.

Default Action
Most contexts have a so-called default action. This action is executed when user double-clicks the context in the AggreGate Client System Tree 784 , for example. Here are two examples of default actions: The default action for the Event Filters The default action for the Query its output to the user.
716 687

context is "Create New Filter".

271

context is "Execute Query", which executes the query

clicked on and displays

Tracking Action Execution

Every time an action is execution by an operator or a system component, an action 652 event is created stored in Administration context. Preserving action execution history is important for keeping audit trails and ensuring system security. AggreGate distribution includes Actions event filter real time.
206

allowing to browse action history and track action execution in

6.6.1 Action Execution Modes

Actions may be executed in two different modes: Interactive Headless
893

Mode

893

(Non-Interactive) Mode

6.6.1.1 Interactive Actions

Interactive mode is the normal execution mode supported by every action. In this mode, every UI Procedure executed during the action flow performs some operator interaction using AggreGate Server user interface. For example, it may show messages or ask the user to edit some data.

6.6.1.2 Headless Actions

Headless (non-interactive) mode is supported only by actions that may execute "off-line", without interaction with an operator. Headless execution is supported by Alerts 227 and Scheduled Jobs 266 . In this mode, the result of every UI procedure is predefined when the action is configured for non-interactive execution. These pre-defined results are configured during the headless action execution setup, e.g. when configuring an alert or a scheduler job. All action output is redirected into server log
74

and/or converted into context events

880 .

Input Parameter Bindings

When editing pre-defined parameters of a headless action in the Data Table Editor, it's possible to configure 813 table bindings 860 . When a headless action is executed by the server, the latter evaluates all bindings contained in its predefined parameters, filling them with the some actual or context-sensitive information. Example: It's possible to schedule Export Report to Server File 722 action of a Recent Alerts report and use bindings to generate a different file name each time the report is being exported. In this case, the following binding should be added to the Input: Export to Server File table:

2000-2013 Tibbo Technology Inc.

894

AggreGate Documentation

Target: File Path (file), String Expression: "alerts_report_" + year(now()) + "_" + month(now()) + "_" + day(now ()) + ".pdf"
Example: We can execute an external application upon alert by adding Execute Application 730 action to the list of alert's corrective actions 227 . However, it's often necessary to pass alert message and other alert parameters to this application. In this case, the following and similar bindings should be added to the Input: Execute Application or Operating System Command table:

Target: Command (command), String Expression: "\"" + cell({env/parameters}, "message") + "\""

This expression refers parameters environmenal variable alert event 224 .
930

those value is a Data Table associated with

Example: To send an e-mail message upon an alert with custom text that describes alert cause, add Send Email automatic corrective action to the alert, open its input parameters, get inside Input: Send E-Mail table:

Target: Message (message), String Expression: "An alert was raised, it is caused by value of custom field: " + cell(cell({env/parameters},'data'),'customField')
This expression refers parameters environmenal variable 930 those value is a Data Table associated with alert event 224 . It then uses first (inner) cell() function to extract data table that corresponds to value of variable (or data of an event) that has caused the alert. Another (outer) cell() function extracts custom field out of this data table. The field value is appended to e-mail message text.

INPUT PARAMETER BINDINGS EVALUATION

The execution environment of action parameter bindings allow accessing: Data from any server context
863

Initial parameters of an action being executed

Input Parameter Bindings Resolution Environment Default Context

927

922

Context the action is executed from. Current table, i.e. the table on that the bindings are evaluated.

Default Data Table

927

Default Row

927

Current row, if the binding does not refer a specific row and is evaluated for each table row individually. Zero otherwise.

Environment Variables 930

Variable Name parameters

Value Type Data Table

Description Action initial parameters: Alert event

224 's

Data Table if action is executed upon alert

Not defined if action is executed by scheduler

6.6.2 Action Grouping

AggreGate supports grouping of actions several contexts 863 .
892 .

Action grouping is the aggregated execution of the same action from

Some types of actions change their behaviour drastically when launched in a grouped mode. For example, when Configure 904 action is grouped for several contexts, properties are being read from the first context in the group, but changed settings are written to all contexts in the group, allowing to configure multiple objects at the same time. Other actions support grouping at the level of UI Procedures 896 . For example, when the Call Function Action 903 is invoked for a group of contexts, it allows the user to apply one confirmation to all actions in the group (i.e, the user has to confirm only once). The input parameters for the function being called can be also provided once for all actions. A

2000-2013 Tibbo Technology Inc.

System Internals

895

single window is then used to provide feedback from the execution of all actions, rather than a separate popup for every action.

6.6.3 Drag and Drop Actions

Some actions are activated by Drag and Drop operations in the AggreGate Server User Interface. For example, in AggreGate Client you can drag one System Tree 784 node and drop it onto another node. This will trigger an action. In the terms of a Drag And Drop action, the context that was dropped onto the node is called "accepted context". Drag-and-Drop actions may be also activated without actually dragging and dropping with the mouse. For example, you can launch them from the Related Actions 786 list appearing under the System Tree in AggreGate Client, or from the context menu for a node in the System Tree. In this case, the user will be prompted to select an "accepted" context using a Select Entities 902 UI Procedure. Every Drag and Drop action may accept contexts of one or more types others will accept just contexts of a certain type.
864 .

Some actions may accept any context,

6.6.4 Variable-Related Actions

Some actions are activated by selecting a context variable 869 in AggreGate Server User Interface and then running an action for this variable. Such actions receive the name of the selected variable and the path for the context 863 in which it is defined on startup. Their workflow is tightly related to this variable, which is why they are called Variable-Related Actions. For example, we may select a variable indicating current temperature defined in the Device 677 Context of a thermometer device and start a Create Chart 771 variable-related action for this variable. Create Chart action will create a widget 312 containing chart component 384 for displaying a history of temperature changes. Variable-Related Actions are similar to Event-Related Actions their input.
895

that have a reference to context event

880

on

In AggreGate Client 776 Variable-Related actions are launched by right-clicking on a variable in Properties Editor selecting an action to run from context menu.

795

and

Here is what variable-related actions may be available for a hardware Device setting variable (screenshot made in AggreGate Client):

6.6.5 Event-Related Actions

Some actions are activated by selecting a context event 880 in AggreGate Server User Interface and then running an action for this event. Such actions receive the name of the selected event and the path of context 863 in which it is defined on startup. Their workflow is tightly related to this event, which is why they are called Event-Related Actions. For example, we may select an event indicating that a certain Device 677 was disconnected from the server and start a Create Alert event-related action for this event. The action will create an alert 216 that will be raised upon next disconnection of this Device. Event-Related Actions are similar to Variable-Related Actions on their input.
895

that have a reference to context variable

869

In AggreGate Client 776 Event-Related actions are launched by right-clicking on an event in Event Log an action to run from Related Actions menu.

791

and selecting

2000-2013 Tibbo Technology Inc.

896

AggreGate Documentation

6.6.6 Execution Parameters

Many actions have execution parameters allowing to pre-customize the action flow. For example, the Call Function 903 action has a Results Window Location parameter that specifies where the execution result window should be shown. When the user initiates a "normal" action execution (for example using a context menu of AggreGate Client's System Tree 784 ), the action is launched with default execution parameters. Custom parameters may be specified in the following cases: When adding action to Auto-Run When creating a Favourite
626 625

action

6.6.7 UI Procedures
When AggreGate Server wants to talk to a human user, it can pop up a message, show a data table editor, or possibly show a list with checkboxes to let the user select one or several options. When you think about it, just a handful of interaction types are enough to fully interact with a user. There's no need to pop up a special, custom dialog whenever the user has to interact with the software. Standardizing user interaction in this way lets a user quickly gain familiarity with the system. The learning curve is less steep, because you only have to figure out the data shown in the dialog - not the dialog itself. User Interface Procedures (UI Procedures) are the basic building blocks of actions 892 . These UI Procedures are used for showing alerts, confirming actions, editing properties, etc. Every action is a combination of server-side operations and UI Procedures. Depending on action logic and the runtime environment, an action may invoke UI Procedures in various combinations. For example, the Call Function Action 903 lets a user edit the input parameters of a called function using an Edit Data 896 UI Procedure, then calls the function, and then decides what UI Procedure will be started: Show Error 899 if function execution has been failed, Edit Data 896 in read-only mode if function has returned some output or just Show Message 899 to indicate that function has been successfully executed. Another key advantage of using UI Procedures comes to light when considering AggreGate as a multi-platform system. When using a web interface or a Smartphone to interact with the AggreGate system, obviously the actual GUI controls shown to the user are somewhat different. However, the GUI controls always derive from the same UI procedures. I.e, even on a Smartphone, you will have some way to show an error message, or allow a user to perform a multipleselection. So an action can run on any platform -- you won't have an action that can run only in the GUI AggreGate Client. Here too, this reduces the learning curve and improves consistency.

6.6.7.1 Edit Data

This UI Procedure 896 allows editing or viewing the content of a single Data Table specify the input parameters of a function 878 or view its output.
854 .

It may be used, for example, to

Data can be displayed in editable mode or just as read-only data. The dialog itself may have scrolling enabled or disabled, and it can also be shown in a separate window or as a part of the main window of the UI. All of these are configurable parameters for this UI Procedure. In AggreGate Client, editing is performed using the Data Table Editor component:

801

Grouping Support
This UI Procedure supports action grouping
894 .

In AggreGate Client, the Data Table Editor will contain additional All button in this case (shown as the middle button below, between OK and Cancel). It is used to apply the data being edited to all actions that are executed in the group:

2000-2013 Tibbo Technology Inc.

System Internals

897

6.6.7.2 Edit Properties

This UI Procedure 896 is used to edit or view the values of one or more context variables 869 . It is employed, for example, by the Configure 904 action 902 during the configuration of Data Terminals, Alerts and other objects. It allows properties to be saved to external files, or reloaded. It can also export and import property values from the AggreGate native to third-party formats. In some cases, properties are available in read-only mode. On the surface, this UI Procedure may seem similar to the Edit Data 896 UI Procedure. But the main difference is that while Edit Data lets the user edit any arbitrary data in a table (such as providing parameters for some function, etc), the Edit Properties function is used only for editing properties (or "variables", to use another name) of various contexts. This is because editing properties requires more options than editing general data. For instance, with this procedure, you can apply your changes and keep editing (i.e, you don't necessarily have to close the dialog to apply the changes). The Edit Properties UI Procedure provides more choices than the Edit Data UI Procedure. They may appear similar in some clients, but they are actually different. The difference can be likened to the difference between a Print dialog in any software (asking the user to fill in how many copies he wants, what pages to print, etc) and a Properties Editor in Visual BASIC (asking the user to edit the properties of a certain GUI component). The first (Print dialog) is similar to our Edit Data UI Procedure - you do enter data, but it does not apply as properties to one object. Rather, you data is used as arguments, driving an operation of the system. Conversely, the Properties Editor in VB is similar to the Edit Properties UI Procedure - it is used for systematically going over the properties of an object and modifying them. In AggreGate Client, editing is performed using the Properties Editor
795

component:

Grouping Support
This UI Procedure supports action grouping
894 .

In AggreGate Client, the Properties Editor will contain only properties and their fields that are common to all contexts whose properties are being edited. The list of these contexts is shown in the header of the Properties Editor window:

2000-2013 Tibbo Technology Inc.

898

AggreGate Documentation

Note, that data shown in the Properties Editor is actually read from the first context of the list (so-called Master Context ). However, all changes made in the Properties Editor will be applied to Master Context and all other edited contexts ( Slave Contexts).

6.6.7.3 Edit Text

This UI Procedure
896

prompts user to edit some text in a syntax-highlighted text editor.

819

In AggreGate Client, this UI Procedure shows a Text Editor

component:

6.6.7.4 Show Event Log

This UI Procedure 896 is used to to view events 880 or access their history. It may be used to display the flow of events in real-time, as they occur, or to review events which already happened (i.e, event history 882 ). This operation also defines which columns are shown in the event list. In some cases, only the timestamp and event name are shown. In other cases, other event properties are also visible, such as the context 863 in which it was occurred, acknowledgements 882 given by operators, the event level 882 (severity), etc. In AggreGate Client, this UI Procedure launches an Event Log
791

component:

2000-2013 Tibbo Technology Inc.

System Internals

899

6.6.7.5 Show Message

This simple UI Procedure
896

just shows a custom message to the user and waits for a reaction.

In AggreGate Client, this UI Procedure shows a popup dialog with a single "OK" button:

Grouping Support
This UI Procedure supports action grouping 894 . With action grouping, messages provided for the UI Procedure by different actions in a group are shown together. In AggreGate Client, a single popup window is used in this case:

6.6.7.6 Show Error

This UI Procedure 896 is activated when error conditions occur during the execution of an action message and details and lets the user send an error report. In AggreGate Client, this UI Procedure shows an Error Dialog
846 : 902 .

It displays an error

2000-2013 Tibbo Technology Inc.

900

AggreGate Documentation

6.6.7.7 Show Report

This UI Procedure
896

allow users to view, print or export reports

241

to different formats.
814

In AggreGate Client, this UI Procedure shows report in a Report Viewer

component:

6.6.7.8 Show System Tree

This UI procedure is used to show a subtree of a server's context tree 863 and allow the user to manipulate contexts included in this subtree. It shows a System Tree component in a separate window. See details: System Tree System Tree
784 636

in AggreGate Client in Web Desktop

Here is how System Tree look like in AggreGate Client:

2000-2013 Tibbo Technology Inc.

System Internals

901

6.6.7.9 Confirm
This simple UI Procedure 896 is used to obtain user confirmation for various operations. In AggreGate Client, it shows a popup dialog with "OK" and "Cancel" buttons:

Grouping Support
This UI Procedure supports action grouping 894 . With action grouping, the user is able to choose an "Apply to all" option to apply his positive or negative choice to all actions in the group. In AggreGate Client, an Apply to all checkbox is shown in the confirmation dialog:

2000-2013 Tibbo Technology Inc.

902

AggreGate Documentation

6.6.7.10 Browse
This UI Procedure 896 opens a web page in browser. It is used to view AggreGate documentation, access Device Servers 1003 that work through HTTP Proxy 1011 etc.

6.6.7.11 Select Entities

This UI Procedure 896 allows users to select contexts 863 , variables 869 , functions 878 and events 880 using a convenient tree-like graphical component. For example, it is used by Drag and Drop 895 actions that are launched without actually dragging and dropping -- it lets the user select a context to be used as "dropped" one. In AggreGate Client, selection is performed using the Entities Selector
815

component:

Grouping Support
This UI Procedure supports action grouping all actions in the group.
894 .

With action grouping, it is possible to apply the same entity selection to

In AggreGate Client, the Entities Selector dialog contains an additional All button in this case:

6.6.7.12 Start Interactive Tutorial

This UI Procedure AggreGate.
896

starts an interactive tutorial. Interactive tutorials teach users how to use different components of
847

For details, see the Interactive Guide

chapter.

6.6.8 Common Actions

Actions 892 are used to manipulate contexts configuring 904 it.
863

in various ways. For example, deleting

905

a context is an action. So is

Some contexts have actions which apply only to them. For example, the Initiate Auto-Run action would not make

2000-2013 Tibbo Technology Inc.

System Internals
much sense in the Device context. It only makes sense for the Auto Run
662

903

context. Right? Thus, it is a unique action.

However, other actions can apply to many different contexts. The configure 904 action, for example, lets you configure a Device, an Auto Run entry, or an alert without much difference. It applies to all of these contexts in a similar manner. Thus, it is called a common action. Below are all common actions supported by AggreGate Server.

6.6.8.1 Call Function

This it one of the basic action types used in AggreGate Server. The primary objective of this action is to allow a user to perform an operation with the hardware device or system object by calling a single function 878 from the corresponding context 863 . Non-Interactive Mode 893 : Permissions: Execution Parameters
896

Supported Accessible at Observer permission level Location

955 932

of function output window

Action Flow
1. [Optional] User is prompted to confirm the execution using the Confirm
878 901

UI Procedure.

2. [Optional] User is prompted to edit input parameters of a function to be called using an Edit Data 896 UI Procedure. If the user cancels this UI Procedure (i.e. by clicking Cancel in the Data Table Editor 801 dialog), the action is aborted. 3. The function specified by the Call action is now invoked, and the server performs all necessary operations (like creating a new Alert, or reading a list of all <%DS%s and returning it as its output). If function input parameters were not specified on step 2, the function is called using its default parameters. 4. If the function returns an error, it is shown to the user using a Show Error 899 UI Procedure. If the user was prompted for input parameters on step 2, the flow now returns back to step 2 so that the user could specify different parameters. 5. [Optional] If the function returned any data, it may be shown to the user using an Edit Data only mode.
896

UI Procedure in read-

6. [Optional] In some cases, a "Successfully Completed" or other message may be shown to the user using a Show Message 899 UI Procedure to indicate that the function has been successfully called.

Grouping Support
This action supports action grouping
894 .

If confirmation is required, it may be applied to all actions in the group. The same input parameters may be applied to all actions in the group. All "Successfully Completed" messages for the actions in the group are shown in a single window.

Examples:
Connect Device Server to AggreGate Server in External Device Server context has "Successfully completed" message)
1027

(prompts for input parameters,

2000-2013 Tibbo Technology Inc.

904

AggreGate Documentation
756

View Users Summary in Users context

(doesn't prompt for input, shows output)

Delete Query in Query context

716

(doesn't prompt for input and output, requires confirmation)

Buzz in Device Server context 1018 (no user interaction at all, just performs the requested operation)

6.6.8.2 Configure
This action allows users to change the settings for various hardware devices (such as Data Terminals for system objects (such as Alerts 216 ). This action may also run in read-only mode, allowing the user to only view the property values. Action Name: Action Icon: Keyboard Shortcut Non-Interactive Mode 893 : Permissions: Execution Parameters
896 113 )

or properties

configure (may differ in some cases) (may differ in some cases) F2 Not Supported Accessible at Observer permission level Properties Editor Window Location :
955 932

2000-2013 Tibbo Technology Inc.

System Internals

905

Action Flow
1. Check if the context has any variables which can be configured. If it doesn't, pop up an error message for the user. This can also mean the context is not currently available for configuration, such as when trying to configure a Device 113 which is currently offline. 2. Change values of context variables by using an Edit Properties
897

UI Procedure

Grouping Support
This action supports action grouping
894 .

If the action is called for a group of contexts, it uses an Edit Properties UI Procedure to open the settings for the first context in the group. However, upon saving those settings, the modified settings (properties) will be written to all contexts in the group.

6.6.8.3 Create
This action is used to create new objects like Alerts Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Supported Accessible at Observer permission level
932 216 ,

Event Filters

206

etc.

create

Action Flow
1. Pop up a dialog (or some sort of data entry form) using the Edit Data settings for the context to be created. 2. Create the new context
863 896

UI Procedure, and let the user enter basic

on the server.

3. Use the Edit Data 896 UI Procedure again to let the user configure the newly created context. The user can now access more properties.

6.6.8.4 Create From Template

This action is used to create some system object, like a Widget or a Device Account, by cloning another object of the same type. It is a Drag-and-Drop action 895 , allowing user to activate it by Drag-and-Drop operation or by selecting a "template" object first. Then a copy of the object's context is created in the holder context from which Create From Template action was executed. In this way you could take an alert from one user account and create a copy of it in another user account. Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Manager permission level
932

createFromTemplate

Action Flow
Once a template object is selected, the flow of this action is the same as Make Copy
908

action's flow.

6.6.8.5 Delete
This common action is used to permanently delete various contexts, such as Event Filters, Widgets, Favourites etc. Deleting a context stops its functioning (for example prevents all future executions of a Scheduled Job or raising of an Alert), removes all associated settings (including permanent properties stored in the AggreGate Server database 80 ) and removes context from the Children List of its parent context. Delete Action is based on a Call Function require confirmation.
903

Action. It doesn't ask for parameters or show any output, but it does

2000-2013 Tibbo Technology Inc.

906

AggreGate Documentation

Action Name: Action Icon: Keyboard Shortcut Non-Interactive Mode 893 : Permissions:

delete

Delete Supported Accessible at Manager permission level

932

6.6.8.6 Edit Context Permissions

Edit Context Permissions is a Configure 904 action that is used to define which AggreGate Server users to a given context. The context permissions table has two fields: User Permissions Name and description of user account The permission level
932 108

have access

the user has for the current context

The table is not permanently stored on the server. It is generated on-the-fly when the Edit Context Permissions action is executed. To generate this table, AggreGate Server reads the permission tables 933 of all users in the system. If the permission level of a particular user for the current context is greater than None, a new record is added to the context permissions table, with the fields specified above (user and permissions ). The current user (whose username and password you are using to access this action) is not shown in the context permissions table, because a user may not modify his own permissions. You can add new records to the context permissions table while editing it, thus allowing new users to access this context. When the context permissions table is saved, it is not stored "as is" on the server. Instead, the server modifies the permission tables of individual users according to the permissions defined in the table being saved. Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Administrator permission level
932

perms

EXAMPLE
Let's say the initial user permissions table for the user john looks like this:

Next we execute the Edit Context Permissions Action from users.admin.alerts.water_level_warning (this context represents a "Water Level Warning" alert that is registered under the admin account). We'll see a permissions table similar to this:

This particular table shows two users with access to this alert: the newadmin user has administrative access and and test user has normal level of access. The admin user also has some permissions but we don't see them here because that's the account we're using right now. Next we'll add a new record to context permissions table. Select john in the User field and Manager in Permissions field. The table should look like this:

2000-2013 Tibbo Technology Inc.

System Internals

907

Next we'll save the changes and open the user permissions table for john again. We see that the table was modified so that he now has access to the "Water Level Warning" alert:

Now john has access to the "Water Level Warning" alert. He can see, configure and use it, for example, using the System Tree 784 of AggreGate Client:

See Security and Permissions

931

for more info.

6.6.8.7 Export
The Export action is used to save selected properties of devices or resources to a file. It helps to select certain data fields from the children contexts of the context in that it is defined.
Example: If you launch Export action from Cardholders context located under a certain Department context, you will be able export names, emails, addresses, and other details of cardholders belonging to this department. This example came from AggreGate Time and Attendance solution.

Action Flow: 1. Select 896 export type: all variables (ideal for further reporting) or writable variables only (convenient for future data re-import). 2. Check one or more resources to retrieve export data from. 1. Select
896

what variables/fields should be exported.

271

2. The system will generate a query

returning selected fields as a single table.

898

3. User is prompted to review and fine-tune the generated query using Edit Text 4. At this point the selection query is executed. 5. Data retrieved by a query is presented to the user using Edit Data mode).
896

UI procedure.

UI procedure (in read-only

6. User may sort, filter and export data using controls and toolbar buttons of the Data Table Editor. It it is also possible to build a printable report based on the selected data.
Action Name: export

2000-2013 Tibbo Technology Inc.

908

AggreGate Documentation

Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Manager permission level
932

6.6.8.8 Import
The Import action is used to create several resources and apply parameters read from a file. Action Flow: 1. Select
896

a file to be imported.
896

2. [Optional] Specify

import options, if any options are available for the format of the selected file.

3. Data is now read from the file and converted to a Data Table. 4. Review
896

the data to be imported.

911

5. Map 896 properties of resources to be created to the fields of imported Data Table (file). The Source/Expression field can contain a field selected from the list or manually entered expression referring to one or more fields and/or making necessary type/value conversions.

The system does its best to figure out the suitable mappings based on field names and descriptions. In most cases, only some of the mappings would need to be specified manually.

Example 1: To convert a phone field into international format during import, you may specify the following Source/Expression (for US phone numbers): "+1" + {phone} Example 2: You may want to use a comments field of the created resources to note the date of import. In this case Source/Expression will not contain any references to the imported data fields, but will be simply something like: format(now(), "d MMM yyyy HH:mm:ss")

6. The system starts processing every record of an imported Data Table (file). A new resource is created first, with the name specified by the Name field mapping. After that, all mappings are processed and properties of the newly created resource are updated. 7. A status report is shown 896 to the user. It contains a list of the created objects along with any errors which occurred during the import process.
Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Manager permission level
932

import

6.6.8.9 Make Copy

This action is used to clone some system object, like Alert or Widget. It creates a new object first, and then copies properties from the source object to a newly created one using context copy operation 866 . There is no Move action. To move an object, copy it and then delete it.

Action Name: Action Icon: Non-Interactive

makeCopy

Not Supported

2000-2013 Tibbo Technology Inc.

System Internals

909

Mode

893

: Accessible at Manager permission level

932

Permissions:

Action Flow
1. A new context is created, of the same type as context being copied. Its name is auto-generated by appending "_copy" to the name of the copied context. Its description is also auto-generated by appending the word "Copy" to the Description of the original context. 2. User is prompted
896

to change the name and description of a context to be created.

3. All settings are copied from the original context to the newly created one. Read-only variables and fields are not copied. For more information about the logic behind copy operations, see Context Copy Operations 866 for more info.

6.6.8.10 Monitor Related Events

This action helps detect and analyze activity performed by any hardware device or system object. This is done by monitoring events 880 that are fired in this context. When this action is launched, AggreGate Server finds all events in this context that may be useful for human users and starts an Event Log using Show Event Log 898 UI Procedure. Now the user can monitor all events in real time, view their history acknowledge 882 events etc. Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Execution Parameters
896 882 ,

filter and sort them, view associated data,

monitor

Not Supported Accessible at Observer permission level Event Log Window Location
955 932

Examples of Related Events

In the Favourites are deleted.
697

context, "info
677

885 "

("Information") event is fired when new favourite is created of some favourites

In the Data Terminal hardware device

context, "event" ("Data Terminal Event") event is fired when new event is received from the

6.6.8.11 Search/Filter
This action opens subtree of the server context tree with the current context as a root, using the Show System Tree UI Procedure. The opened System Tree has a Filter toolbar for filtering or finding contexts. Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Observer permission level
932 900

filter

6.6.8.12 Replicate
This is a Drag-and-Drop 895 action that is used to copy properties from a given context to another one of a similar type. It lets you copy the values of one, several or all properties of this context (like User Account 759 or Device Account 677 ) from the "accepted" context. For more information, see Context Copy Operations 866 . As a Drag-and-Drop 895 action, Replicate action accepts contexts of the same type as type of context in that it is defined. Thus, properties may be replicated only between the contexts of the same type. Action Name: replicate

2000-2013 Tibbo Technology Inc.

910

AggreGate Documentation

Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Manager permission level
932

Action Flow
1. An Edit Data 896 UI Procedure allows the user to select variables and their fields to replicate. It's also possible to correct variable values on-the-fly. 2. AggreGate Server performs the replication. 3. A Replication Status Report is shown to the user using the Edit Data 896 UI Procedure in read-only mode. It includes one record per every replicated variable. This record shows the replication status (Successful/Unsuccessful) and a any errors which occurred during replication of this variable.

6.6.8.13 Replicate To Children

This is a Drag and Drop 895 action that is usually defined in "container" contexts (like Alerts 654 or Queries 271 ). It copies settings of an "accepted" context to all its children. This helps to configure one, several or all properties of the child contexts in the same way as corresponding property of "acccepted" contexts. For example, it may replicate settings of an "accepted" Alert 656 context to all Alert contexts defined under the Alerts context defining this action. See Context Copy Operations 866 for more info. As a Drag-and-Drop 895 action, Replicate To Children action accepts contexts of the same type as type of all children of context in that it is defined. Thus, properties may be replicated only between the contexts of the same type. Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Manager permission level
932

replicate

Action Flow
1. An Edit Data 896 UI Procedure allows the user to select variables and their fields to replicate. It's also possible to correct variable values on-the-fly. 2. Server performs the replication. 3. A Replication Status Report is shown to the user using the Edit Data 896 UI Procedure in read-only mode. It includes one record per every replicated variable. This record shows the replication status (Successful/Unsuccessful) and a any errors which occurred during replication of this variable.

6.6.8.14 View Status

Allows to view status of the system resource by showing all its status variable. For most contexts, the only status variables are Group Membership 875 and Active Alerts 875 . Other status variables are context-dependent. For example, for a device this action shows its online status, synchronization status, time of last synchronization, synchronization progress, and individual settings synchronization statuses 117 . Action Type: Action Name: Action Icon:

Configure
status

904

(read-only mode)

2000-2013 Tibbo Technology Inc.

System Internals

911

6.7 Expression Language

An expression is like a "sentence", or a line of text, which you let AggreGate process and come some result. For example, if someone were to tell you "All apples are blue", you would think a very brief moment and would then conclude that it'sFALSE wrong , in (or computing jargon). You just processed an expression, on your very own.
In AggreGate, an expression is a combination of values, also known as literals, ("True", "False", "5", "John"), operators (like +, -, * etc, a full list is below) and references (such as users.admin.deviceservers.ds1:buzz() ). You mix all these together in a particular way, and end up with a line of text (an expression) that AggreGate can understand, and thus evaluate. When AggreGate evaluates an expression, it processes it. It systematically goes through the expression, executing the operations it calls for (getting variable values, running functions included in it and getting their results, etc) until it finishes evaluating and winds up with some result. This is the value of the expression -- its result. In AggreGate, expressions are used widely throughout the system. They're always written the same way, like in a language. This language (or "way of composing references") is called AggreGate Expression Language. Here are some examples of expressions usage: Expressions that evaluate to a Boolean result are used in Event Filters filter. Expressions that evaluate to a Boolean determine when an Alert condition).
216 206

to decide if an event should pass through a

should be triggered (upon a certain event or

Widgets 312 are based on expressions that define relations between widget components and data coming from various contexts within the server. Every argument of an expression is also an expression in itself, and thus, expressions may be nested. Once an expression is evaluated, it gives a certain value (result). This value can be an integer, a string, a Boolean variable or any other date type defined in AggreGate Server. The value type is dependant on whatever is being evaluated: An expression such as 1 + 1 will return an integer (2), while an expression such as "the" + " dog" will return a string ("the dog"). If the expression contains a reference (such as {username} + 1), you can't really know for sure what the value type will be, because it depends on the data type of whatever is being referenced.

Side Effects
Evaluation of an expression may have side effects. For example, if an expression contains a reference to the Buzz function of a Device Server context 1018 , its evaluation will cause a hardware Device Server to blink its LEDs. This is what is called side effect.

6.7.1 Data Types and Type Conversion

The expression language internally deals with the following types (and returns values of these types): Type Null Object Number Description Null value means "no value". This value may be written to the Data Table cell only if field is nullable
856 .

This is a super-type of all types. If some function is declared to return an Object, it may return value of any type, depending on the input parameters. This is a super-type of all numeric types. If some function is declared to accept a number, it may accept Integer, Long, Float or Double. In addition, all other objects will be converted to numbers on a best effort basis. 32-bit signed integer number. 64-bit signed integer number. A floating point number. A double-precision floating point number. String of any length. Strings may also contain binary data. TRUE or FALSE An 8-bit RGB color value. A timestamp that includes both date and time parts. May be consumed by date/time processing functions 916 .

Integer Long Float Double String Boolean Color Date

2000-2013 Tibbo Technology Inc.

912

AggreGate Documentation

Data Table

A Data Table

854 . 856 .

All types have their analogs among Data Table field types

Type Conversion
The expression language processing engine does its best to perform all necessary type conversion and evaluate an expression to get some result. For example, if a numeric argument is passed to a function that accepts strings, the number is auto-converted to its string representation. Another example: if floating point number is added to an integer number the resulting value is also floating point number. This helps avoid rounding errors. If proper type conversion is not possible, the evaluation of an expression fails with error. The explicit type conversion is performed by using type conversion functions
920 .

6.7.2 Expression Syntax

Every expression may consist of the following elements: Literals
912 913 914 921 922

Operators Functions

References Comments

6.7.2.1 Literals
A literal is a constant. It is "taken literally" by AggreGate - the system just takes it as it is, and uses it as a basis for calculations etc. It is a constant value. AggreGate Expression Language defines several types of literals: Null Literal: null Boolean Literals: true of false Decimal Literals (0, 1, 123, -1234567890, ...) Hexadecimal Literals (0x0A , 0xFFFF, ...) Binary Literals (0b01, 0b00110011) Octal Literals (00 , 055, 01234567 , ...) Floating Point Literals (3.1 , -44.5, 1.3E12, ...) String Literals ("This is a String", 'test', ...)

STRING ESCAPING
Backslashes (" \ ") that appear within strings must be escaped using another backslash (i.e. \ becomes \\).1 Quotes must be also escaped using backslash character (\" , \') if the same type of quotes was used to quote the string. Examples: "There are double quotes \"inside\" this string" 'There are single quotes \'inside\' this string'

2000-2013 Tibbo Technology Inc.

System Internals

913

6.7.2.2 Operators
An operator is a symbol which applies to certain data (such as numbers or strings) and tells the system what it should do with it. Once the system executes the operator on the data (i.e, once the operator "operates"), you always get some result, or value. Common operators include + (addition, as in 1+1), - (subtraction, such as 2-1), etc. A single expression may contain many operators, such as 1 + 2 * 3. The operators are evaluated in a certain sequence -- not as they're written in the line (from left to write). For example, 1 + 2 * 3 evaluates to 7 and not to 9, because the multiplication operator has a higher precedence than addition operator. The following table also shows operator precedence - the topmost operators are the first to be evaluated when the system evaluates an expression.

Operators Precedence
Description Parenthesis Bitwise NOT operator Logical NOT operator Multiplicative operators Additive operators Syntax () ~ ! * + / < >= <= % Example (1 + 2) * 3 ~{a} !{x} > 0 {d} * 3 {b} + {c} {a} >= 123 {name} == "test" Argument Types Any Numeric Boolean Numeric Numeric (or Strings for "+") Numeric Any (Strings only for "!=") Result Type Any Numeric Boolean Numeric Numeric (or String for "+") Boolean Boolean

Relational operators > Equality operators and regular expression 1318 match operator Bitwise AND operator Bitwise XOR operator Bitwise OR operator Logical AND operator Logical OR operator ==

!=

~=

& ^ | && ||

{z} & 0xFFFF {y} ^ 0x1A {x} | 0xFF {z} = 1 && {x} > 0 {x} > 5 || {y} < 1 {y} > 5 ? 1 : 0

Numeric Numeric Numeric Boolean Boolean Boolean for first argument, any type for other arguments

Numeric Numeric Numeric Boolean Boolean Any

Conditional operator ? :

PARENTHESIS
Expressions may also include parenthesis that change operators precedence. Example:

1 + 2 * 3
but

evaluates to 7

(1 + 2) * 3
CONDITIONAL OPERATOR

evaluates to 9

The conditional operator, ?:, can be used to conditionally evaluate expressions. It has three agruments: The first argument should evaluate to a Boolean value. If it evaluates to TRUE, the operator result is the second argument. If the first argument is FALSE, the operator result is the third argument.

condition ? value_if_true : value_if_false

2000-2013 Tibbo Technology Inc.

914

AggreGate Documentation

Example:

2 * 2 == 4 ? "Yes" : "No"
Resolves to a String, "Yes".

REGULAR EXPRESSION MATCH OPERATOR

Both arguments are strings. Evaluates to true is first string matches to the regular expression argument. Example: "abXXXX" ~= "^abc.*" resolves to Boolean false.
1318

defined by the second

ADDITIVE OPERATOR
If at least one of arguments is String, second argument is converted to its string representation. In this case evaluation result is result of concatenation of these strings. Example:

"test" + 123
resolves to String "test123".

6.7.2.3 Functions
Expression language functions perform some processing of their input parameters and return some value. Several functions (such as random ) do not have input parameters at all. It is important to keep the distinction between expression language functions and context functions may appear inside references 921 .
878

that

NUMBER PROCESSING FUNCTIONS

Function abs(Float value) Description Returns the absolute value of a value. If the argument is not negative, the argument is returned. If the argument is negative, the negation of the argument is returned. If argument type is Integer or Long, return value is Long. acos(Float value) asin(Float value) atan(Float value) cbrt(Float value) ceil(Float value) cos(Float value) cosh(Float value) e() eq(Long first, Long second) exp(Float value) floor(Float value) formatNumber Returns the arc cosine of an angle, in the range of 0.0 through pi. Returns the arc sine of an angle, in the range of -pi/2 through pi/2. Returns the arc tangent of an angle, in the range of -pi/2 through pi/2. Returns the cube root of a value. Returns the smallest (closest to negative infinity) value that is greater than or equal to the argument and is equal to a mathematical integer. Returns the trigonometric cosine of an angle. Angle is measured in radians. Returns the hyperbolic cosine of a value. Returns the base of the natural logarithms. Returns true if first argument is equal to the second argument (same as == operator). Returns Euler's number e raised to the power of a value. Returns the largest (closest to positive infinity) value that is less than or equal to the argument and is equal to a mathematical integer. Formats Number value to a String. Number formatting patterns are described Float Float Float Float Float Float Float Float Boolean Float Float String Result Type Float

2000-2013 Tibbo Technology Inc.

System Internals

915

(Number number, String pattern) ge(Long first, Long second) gt(Long first, Long second) le(Long first, Long second) log(Float value) log10(Float value) lt(Long first, Long second) min(Float first, Float second) max(Float first, Float second) ne(Long first, Long second) pi() pow(Float base, Float power) random()

here

1322 .

Returns true if first argument is greater or equal than second argument (same as >= operator). Returns true if first argument is greater than second argument (same as > operator). Returns true if first argument is less or equal than second argument (same as <= operator). Returns the natural logarithm (base e) of a value. Returns the base 10 logarithm of a value.

Boolean Boolean Boolean Float Float

Returns true if first argument is less than second argument (same as < operator). Boolean Returns the smaller of two values. If argument types are Integer or Long, return value is Long. Returns the greater of two values. If argument types are Integer or Long, return value is Long. Returns true if first argument is not equal to the second argument (same as != operator). Returns the ratio of the circumference of a circle to its diameter. Returns the value of the first argument raised to the power of the second argument. Returns a value with a positive sign, greater than or equal to 0.0 and less than 1.0. Returned values are chosen pseudorandomly with (approximately) uniform distribution from that range. Returns the closest integer to the argument. Returns the signum function of the argument; zero if the argument is zero, 1.0 if the argument is greater than zero, -1.0 if the argument is less than zero. If argument type is Integer or Long, return value is Long. Boolean Float Float Float Float Float

round(Float value) signum(Float value)

Long Float

sin(Float value) sinh(Float value) sqrt(Float value) tan(Float value) tanh(Float value)

Returns the trigonometric sine of an angle. Angle is measured in radians. Returns the hyperbolic sine of a value. Returns the correctly rounded positive square root of a value. Returns the trigonometric tangent of an angle. Angle is measured in radians. Returns the hyperbolic tangent of a value.

Float Float Float Float Float

STRING PROCESSING FUNCTIONS

Function contains(String string, String substring) endsWith(String string, String suffix) index(String string, String substring) index(String string, String substring, Integer fromIndex) lastIndex(String string, String substring) lastIndex(String string, String Description Returns true if and only if string contains the specified substring. Returns true if string ends with the specified suffix. Note that the result will be true if the suffix is the empty string or is equal to the string argument. Returns the zero-based index within string of the first occurrence of the specified substring or -1 if not found. Returns the zero-based index within string of the first occurrence of the specified substring, starting at the specified fromIndex. If substring is not found, -1 is returned. Returns the zero-based index within string of the rightmost occurrence of the specified substring or -1 if not found. Returns the zero-based index within string of the rightmost occurrence of Result Type Boolean Boolean

Integer Integer

Integer Integer

2000-2013 Tibbo Technology Inc.

916

AggreGate Documentation

substring, Integer fromIndex) length(String string) replace(String string, String target, String replacement)

the specified substring, searching backward starting at the specified fromIndex. If substring is not found, -1 is returned. Returns the length of the string . Replaces each substring of the string that matches the target substring with the specified replacement string. The replacement proceeds from the beginning of the string to the end, for example, replacing "aa" with "b" in the string "aaa" will result in "ba" rather than "ab". Returns true if string starts with the specified prefix. Note also that true will be returned if the prefix is an empty string or is equal to the string . Returns a new string that is a substring of the string . The substring begins with the character at the specified beginIndex and extends to the end of the string. Examples: Integer String

startsWith(String string, String prefix) substring(String string, Integer beginIndex)

Boolean String

substring("unhappy", 2) returns "happy" substring("Harbison", 3) returns "bison" substring("emptiness", 9) returns "" (an empty string)
substring(String string, Integer beginIndex, Integer endIndex) Returns a new string that is a substring of the string. The substring begins at the specified beginIndex (inclusively) and extends to the character at index endIndex - 1 . Thus the length of the substring is endIndex beginIndex. Examples: String

substring("hamburger", 4, 8) returns "urge" substring("smiles", 1, 5) returns "mile"

lower(String string) upper(String string) trim(String string) Converts all of the characters in the string to lower case. Converts all of the characters in the string to upper case. Returns a copy of the string , with leading and trailing whitespace omitted. String String String

DATE/TIME PROCESSING FUNCTIONS

Function now() year(Date date) month(Date date) day(Date date) hour(Date date) minute(Date date) second(Date date) millisecond(Date date) dayOfYeah(Date date) dayOfWeek(Date date) time(Date date) date(Integer year, Integer month, Integer day, Integer hour, Integer minute, Integer second [, String timezone]) Description Returns current date/time. Returns year of the specified timestamp. Returns month of the specified timestamp (0 for January ). Returns day of the specified timestamp. Returns hour of the specified timestamp. Returns minute of the specified timestamp. Returns second of the specified timestamp. Returns millisecond of the specified timestamp. Returns day of year of the specified timestamp. Result Type Date Integer Integer Integer Integer Integer Integer Integer Integer

Returns day of week of the specified timestamp (0 for Sunday Integer ). Returns number of milliseconds since Epoch for the specified timestamp. Constructs date by the specified year, month, day, hour, minute, and second values. Note, that month is zero-based, i.e. value for January is 0. The default time zone used to construct timestamps is UTC. Custom time zones can be specified in the string form, e.g.: GMT-8 Long Date

2000-2013 Tibbo Technology Inc.

System Internals

917

GMT-08:00 America/Los_Angeles dateDiff(Date first, Date second, String unit) Calculates time passed since first date till second date, measured in named unit(s). Unit names: millisecond or ms for Milliseconds second, sec or s for Seconds minute, min or m for Minutes hour, hr or h for Hours day or d for Days week or w for Weeks month for Months (Note, that month is zero-based, i.e. value for January is 0.) year or y for Years dateAdd(Date date, Integer count, String unit) formatDate(Date date, String pattern) Adds count periods of time specified by named unit(s) to the date, and returns the result. See unit names above. Formats Date value to a String. Date formatting patterns are described here 1321 . To format a date to string suitable for reconstructing a Data Table from string parameter list 862 , use the following pattern: yyyy-MM-dd HH:mm:ss.SSS. printPeriod(Long period) Intelligently formats a time period (expressed in milliseconds) as a string in form: X days X hours X minutes X seconds. String Date String Long

COLOR PROCESSING FUNCTIONS

Function color(Integer red, Integer green, Integer blue) red(Color color) green(Color color) blue(Color color) brighter(Color color) darker(Color color) Description Constructs a color by three RGB values. Each component may must be in 0..255 range. Returns red component of a color (0...255). Returns green component of a color (0...255). Returns blue component of a color (0...255). Applies an arbitrary scale factor to each of the three RGB components of color argument to create a brighter version of this color. Applies an arbitrary scale factor to each of the three RGB components of color argument to create a darker version of this color. Result Type Color Integer Integer Integer Color Color

DATA TABLE PROCESSING FUNCTIONS

Function addColumns(DataTable table, String format1, String expression1, String format2, String expression2, ...) Description Result Type

Adds one or more columns to the table. Format of the first added DataTable column is specified by format1 argument, its value is defined by expression1, etc. Format is encoded into string as specified by format encoding 1307 section (visible separators are used). Value for this field is calculated by evaluating the expression that may contain references 925 to the other cells of this table. If row is not specified in the reference, it defaults to the current row (i.e. one for that new field's value is calculated). Example: addColumns({.:hrStorageTable},

2000-2013 Tibbo Technology Inc.

918

AggreGate Documentation

"<usage><S>", "{hrStorageUsed} * 100 / {hrStorageSize} + ' %') returns a copy of original table with
one new column named usage of type String. Values for this column are calculated using {hrStorageUsed} * 100 / {hrStorageSize} + ' %' expression that references two other columns of the same table. aggregate(Object source, String expression, Object initialValue) Calculates some "aggregate value" for a Data Table (if source Object argument is a Data Table) or a number of contexts (if source argument is a String representing context mask). If the first argument is a Data Table, goes through every record of it and calculates an expression for it, making source Data Table a default table 927 , and current row a default row 927 . If source is a context mask, expression is calculated for every context which matches the mask, making it a default context 927 . The expression usually operates over two values: the value of the previous calculation that may be referred using {env/previous} reference (see Environment References 931 ) and value(s) from the current context/record referred by standard references 926 . During the first calculation, {env/previous} returns the value of initialValue argument. Example 1: aggregate("users.*.devices.*",

"{env/ previous} + ({.:status$connectionStatus} == 1 ? 1 : 0)", 0)

This expression will calculate the number of online ({.: status$connectionStatus} == 1) devices in the system by going over all device contexts (users.*.devices.* mask) and adding 1 to the "aggregate" value if the device is online. The initial value is zero. Example 2: aggregate({}, '{env/previous} ||

({prtCoverStatus} == "open")', false)

In this case, the result is calculated default Data Table (returned by {} value is Boolean value false. The prtCoverStatus field is equal to false otherwise. Example 3: aggregate({}, by going over the records of the reference). The initial "aggregate" final result will be true if open in at least one record, and

max({env/previous},

{field}), 0)
The above expression will return maximum value found in the field column. Example 4: ({env/previous} * {#row} + {num}) /

({#row} + 1)
The above expression will calculate an average value of a table column. cell(DataTable table [, String field [, Integer row [, Boolean description]]]) Returns value contained in the cell of Data Table passed in the first argument. Cell is specified by field and row parameters. If row is not specified, value of field in the first row is returned. If field is a number, it is considered to be field index instead of its name. If description parameter is specified and is true, the function returns description of cell value instead of the value itself (only if field format specifies selection values 856 ). If field is unspecified, this function returns content of the first cell of the table (e.g. from first field and first row). Example: cell({users:list()}, "firstname", 5) will return firstname field from 6th row (index = 5) of table containing a list of user accounts (obtained by calling list 759 () context function 878 from Users 756 context). clear(DataTable table) Removes all records from the table. If minimal record count allowed by the table's format is greater than zero, removes records starting from the end of the table until the minimal record count is reached. Converts table to the format specified by format argument. Format is DataTable Object

convert(DataTable table, String

DataTable

2000-2013 Tibbo Technology Inc.

System Internals

919

format)

encoded into string as specified by format encoding 1307 section (visible separators are used). After a new empty table of the specified format is created, the function does its best to copy all data from table to a new table using Data Table smart copy 861 operation. Example: convert({}, '<<f1><S><A=123>> <<f2><B>>') expression will create a table with String field f1 and Boolean field f2 and copy all data from default table 927 to the newly created table. If default table has field f1 of type Integer, field type will be converted, but all data will be preserved.

copy(DataTable source, DataTable target)

Copies as much data as possible from the source table to the target table and returns the target table. Adds/removes records from the target table to match the number of records in the source table (if target table's format allows this). Converts value types wherever necessary.

DataTable

describe(DataTable table, String field1, String description1, String field2, String description2, ...)

Changes description of field named field1 to description1, etc. Returns DataTable resulting table. Example: describe({.:ifTable},

"ifDescr", "Name", "ifAdminStatus", "Status", "ifType", "Type", "ifSpeed", "Speed") returns a copy of original table where
descriptions of ifDescr, ifAdminStatus, ifType , and ifSpeed fields are changed to Name, Status, Type, and Speed respectively.

description(DataTable table) filter(DataTable table, String filterExpression)

Returns description of the table, i.e. result of its Naming Expression 856 evaluation. Returns a table that contains only those rows of source table that match filterExpression. Example: filter({users:list()}, "contains ({firstname}, 'John')") will return only users whose first names contain John string.

String DataTable

hasField(DataTable table, String field) print(DataTable table, String expression, String separator)

Returns true if table has field named field and false otherwise. Calculates expression for every record of the table and appends output to a resulting string separating results by separator. Example: print({users:list()}, "{firstname}", ", ") will return of user's first names, e.g. Amanda, Michelle, John, Donald, Paul.

Boolean String

records(DataTable table) removeColumns(DataTable String column1, String column2, ...) table,

Returns number of records (rows) in the table. Removes several columns from the table.

Integer DataTable

select(DataTable table, String fieldToSelect, String fieldToCheck, Object value)

Scans table row-by-row and checks if value of fieldToCheck is equal to value . If true, returns value of fieldToSelect from current record. If no matching records found in the table, this function returns NULL. Example: select({users:list()}, "firstname", "username", "john") will return first name of user with username john, selected from the user stats table (see example above).

Object

set(DataTable table, String field, Integer row, Object value)

Changes value table's cell located pointed by field and row to value and returns the changed table.

DataTable

2000-2013 Tibbo Technology Inc.

920

AggreGate Documentation

sort(DataTable table, String field, boolean ascending)

Sorts table's records according to the natural order of field values. Value of ascending flag specifies sort order.

DataTable

subtable(DataTable table, String field1, String field2, ...)

Accepts a table as an argument and returns another table that contains only fields whose names are specified by fields argument. Format and content arn preserved in the returned subtable. Example: subtable({users:list()}, "firstname", "lastname") will return a table with two columns containing first and last names of all AggreGate Server users.

DataTable

table(String format, Object field1, Object field2, ...)

Creates a new table using format encoded into string using visible separators 1307 and an array of parameters. Rules used to fill table with data are covered here 862 . Example: table("<<from><I>><<to><I>>", 2, 5, 3, 7) will return a table with two Integer columns and two rows. First row will have from field equal to 2 and to field equal to 5. Second row's values will be from=3 and to=7.

DataTable

TYPE CONVERSION FUNCTIONS

Function string(Object value) boolean(Object value) integer(Object value [, Integer radix]) Description Converts argument to a String. Converts argument to a Boolean. Converts argument to an Integer number. If a radix is specified, this function converts value to a string and parses it as a signed integer in this radix. In this case characters in the string must all be digits of the specified radix, except that the first character may be an ASCII minus sign ('-') to indicate a negative value. long(Object value [, Integer radix]) Converts argument to a Long number. If a radix is specified, this function converts value to a string and parses it as a signed long in this radix. In this case characters in the string must all be digits of the specified radix, except that the first character may be an ASCII minus sign ('-') to indicate a negative value. float(Object value) timestamp(Object value) Converts argument to a Float number. Float Long Result Type String Boolean Integer

Converts arguments to a Date. The value argument is first Date converted to an integer number. This number is then interpreted as a Unix timestamp, i.e. number of milliseconds since Epoch.

CONTEXT-RELATED FUNCTIONS

Function available(String context) callFunction(String context, String function, Object parameter1, Object parameter2, ...) dc()

Description Returns true if context with path context exists and is available to the caller. Calls a function 878 named function of a context with path context and returns its output. Function's input Data Table 854 is constructed from array of parameters ( parameter1 , parameter2 , ...). Rules used to fill table with data are covered here 862 . Returns path of default context evaluation.
927

Result Type Boolean DataTable

defined during expression

String

2000-2013 Tibbo Technology Inc.

System Internals

921

Another way to get path of default context is using {.:} reference 926 . dr() dt() Returns default row
927 927

defined during expression evaluation. defined during expression evaluation.

926 .

Integer DataTable

Returns default table

Another way to get default table is using {} reference

getVariable(String context, String variable)

Gets a variable 869 named variable from a context with path context and returns its value.

DataTable Boolean Boolean Boolean String

hasVariable(String context, String Returns true if context with path specified by context argument has variable) variable specified by variable argument. hasFunction(String context, String Returns true if context with path specified by context argument has function) function specified by function argument. hasEvent(String context, String event) variableFormat(String context, String variable) functionInputFormat(String context, String function) functionOutputFormat(String context, String function) eventFormat(String context, String event) Returns true if context with path specified by context argument has variable specified by event argument. Returns string representation of variable format or null if context/ variable is not available or variable's format is dynamic.

Returns string representation of function input format or null if context String /function is not available or function 's input format is dynamic. Returns string representation of function output format or null if context/function is not available or function 's output format is dynamic. Returns string representation of event format or null if context/event is not available or event's format is dynamic. String

String

OTHER FUNCTIONS
Function evaluate(String expression) script(String name, Object parameter1, Object parameter2, ...) Description Evaluates its string argument as an AggreGate expression returns the result.
911

Result Type and Object Object

Calls a widget script 610 called name and passes several parameters to it. Returns script output object. This function is available only inside widget binding expressions 606 .

sleep(Integer milliseconds) trace(Object value, String message)

Causes the thread processing this expression to pause execution for the specified number of milliseconds. Logs the value accompanied by the message as a system event to enable expression debugging 923 . Returns the unchanged value .

Null Object

6.7.2.4 References
References are used to access external data values from an expression. See the references description of references and their syntax.
925

chapter for a detailed

References must be enclosed into curly brackets when inserted into expressions. They're resolved when the expression is evaluated. It looks like this: {temperature} <= 100. In this case, temperature is a reference.

2000-2013 Tibbo Technology Inc.

922

AggreGate Documentation

6.7.2.5 Comments
Comments
Expressions may include single-line and multi-line comments. A single-line comment starts with a // character sequence and continues to the end of current line. Here is an example of a single-line comment:

{temperature} > 10 // Low threshold && {temperature} < 30 // High threshold

A multi-line comments starts with a /* character sequence and ends with a */ sequence. Here is an example of a multi-line comment:

{temperature} > 10 /* Low threshold */ && {temperature} < 30 /* High threshold */

6.7.3 Expression Evaluation Environment

When an expression is evaluated in AggreGate, there are a number of parameters that may affect the result. The whole set of these parameters is called "evaluation environment". Most of these parameters affect the resolution of references 921 that may appear inside the expression. Evaluation environment includes: Default Context Default Data Table Default Row Environment Variables The default context references 926 .
927

that is used to resolve relative context paths that may appear in standard

The default data table 927 that is used to resolve standard references that do not explicitly point to variable/function of a certain context. The default row 927 that is used to determine what data table row should be accessed when resolving standard references that do not explicitly specify a row. Any environment variables that may be retrieved by using environment references expression.
930

inside the

6.7.4 Expression Examples

Expressions that are used in Event Filter 206 and Alert 216 definitions must produce a Boolean result. This allows AggreGate Server to decide if an event may pass through a filter or if an alert should be raised upon a certain event. Expression Evaluation Result true 5 "Red Line" true if reference speed resolves to Integer that is greater the 5. true if reference name resolves to String admin. true if reference failed[3] resolves to Boolean value "false". true if reference env/context resolves to String that matches regular expression "^abc.*", i.e. starts with " Result Type Boolean Integer String Boolean Boolean Boolean Boolean

5 + 5 > 7 3 + 2 "Red" + " " + "Line" {speed}>5 {name} == "admin" {failed[3]} == false {env/context} ~= "^abc.*"

2000-2013 Tibbo Technology Inc.

System Internals

923

abc".

{int[1]} == {int[2]}

true if both references resolve to values that may be compared to each other (i.e. two numbers, or two strings) and these values are equal. true or false, depending on the values of resolved references, that must resolve to numbers. "mile" Value of pressure reference if it is greater than 100 or 100 otherwise.

Boolean

({field} + 5) * ({field2} - 1) / 2 == {field[1]} + 1 substring("smiles", 1, 5) max(100, {pressure})

Boolean String Number

Calculating Distance Between Points

Let's assume we own a small car rental company and don't want our cars to drive far from a base station. For monitoring purposes, every car is equipped with smart controller that reads car location from GPS receiver and sends it to AggreGate server via cellular network using GPRS. In our system, we have the coordinates of two points: car and base station. We can calculate the distance between them using an expression, or create an expression that triggers an alert 216 when distance is greater than certain limit. If our coordinates are expressed in radians, we can use the following formula to trigger an alert if distance between car and base station is more than 500 kilometers:

acos(sin({car_latitude}) * sin({base_latitude}) + cos({car_latitude}) * cos ({base_latitude}) * cos({car_longitude} - {base_longitude})) * 6371 > 500

6371 is Earth's radius in kilometers 500 is maximum allowed distance between car and base station in kilometers

If coordinates are expressed in degrees (that is more likely in the case of GPS receiver data), we just convert degrees to radians, e.g. by writing

{car_latitude} / 180 * 2 * 3.1415926

instead of

{car_latitude}

6.7.5 Expression Debugging

In many cases expressions are evaluated in autonomous environment that seriously complicates their testing. For example, when a system administrator creates an expression for alert's event trigger 222 , he cannot correctly test it from inside the Expression Builder 817 since there are no at hand instances of triggering event that could provide "real" data. In other words, the default table 927 will not be defined in the Resolution Environment 922 , and the expression will not produce a correct result when calculated inside the visual editor.

Using Trace Function

The AggreGate expression language includes a very handy trace() function that was designed for expression debugging. This function takes any value, logs it (to make its viewable in Event Log 791 ), and returns it unchanged, resulting to any other side effects. Methods of viewing values logged by trace function differ: If an expression is calculated inside an AggreGate Server, values can be viewed by activating Expression event filter 206 (which is a part of AggreGate core installation bundle) If an expression is calculated inside a widget, valued can be viewed in widget event log In other cases, values will be logged to the standard logging facility
74 345 .

Tracing

(and can be accessed from console, file, etc.)

2000-2013 Tibbo Technology Inc.

924

AggreGate Documentation

Example: Let's assume that we want to create an alert that will be triggered if pressure is under 20 units and temperature is above 50 units. Our initial variable trigger 217 's expression will look like this:

{pressure} < 20 && {temperature} > 50

However, if the alert does not raise, it's hard to find out whether the "pressure part" of expression is false or its "temperature part" is. To enable easy debugging, we can modify our expression as follows:

track({pressure}, "Pressure") < 20 && track({temperature}, "Temperature") > 50

Once this is done, we'll see the following output in Event Log every time our alert's performs the check:

Pressure: 25.3 Temperature: 52.7

This helps to quickly find out current values and see why alert setup is incorrect. Another option is to track the state of individual parts of the expression instead of the "raw" metric values:

track({pressure} < 20, "Pressure Condition") && track({temperature} > 50, "Temperature Condition")
The output will be as follows:

Pressure Condition: false Temperature Condition: true

6.7.6 Expressions Security

Expression processing always inherits permissions 931 of the calling party. For example, if an alert 216 trigger tries to execute a query 271 over a group of devices 113 , the trigger expression will use alert owner's permissions and pass them to the Execute Query function, effectively allowing it to access only devices available to him. Calling party permissions are used for: Resolving references
926

to context variables and functions

920

Executing context-related functions

of the expression language itself

6.7.7 Expressions Performance

Since AggreGate is heavily based on expressions, estimation of their performance impact is crucial for planning performance of the whole AggreGate installation.

CPU Load Impact

Some overall notes on expression performance: If an expression refers variables or functions or contexts located on the local server, its evaluation time will depend only to time required for the local server to complete the operation. It can differ thousand times depending on the nature of variable getter algorithm and function implementation code. Reading a local context variable or calling a local context function may also cause significant CPU load on the local server. Once an expression refers variables 869 or functions 878 of remote contexts 863 (e.g. contexts on remote servers), its evaluation takes significant time and can cause remote server's CPU load. Time required to evaluate the expression that includes a remote context reference 925 is a sum of: o Network round-trip time required to send a command (e.g. get/set variable or call function command) to the remote server and get a reply (generally equal the result of ping command) o Time required for the remote server to process the command. In all other cases expression processing is generally very fast and don't have noticeable CPU load impact. Millions of evaluations per second can be easily handled by any server. Following table helps to estimate the impact of different expression elements: Element Basic operations Performance Very high. Performance (CPU load) impact can be noticed if an expression is calculated millions of

2000-2013 Tibbo Technology Inc.

System Internals

925

(arithmetic, comparison, logical, conditional, etc.) Default table 927 references (e.g. {field} or

times per second.

Very high, millions of operations per second won't cause performance degradation.

{temperature [2]})
Context references (e.g. Very high to low, depending on the context location (local or remote) and nature of referred context variable/function.

{.: temperature$c Resolution performance of server-side variable/function references depends on: elsius} or {: Time required to send a corresponding request to the server and get the response. This is not executeQuery relevant for expressions calculated inside the server (e.g. in models bindings 307 ), but relevant ("SELECT * for remote access (e.g. for widget binding 604 expressions) from users.*: info")}) Time and resources (CPU time, memory, database I/O) required to obtain value of referred
variable or function output. See variables performance
878

and functions performance

880

for more information.

Widget component High, tens of thousands of operations per second won't cause performance degradation. references (e.g.

{form/ textField1: text})

Mathematical functions

Very high, millions of operations per second won't cause performance degradation. Very high to high. Minor performance impact is only noticeable when performing operations on very long strings (millions of characters). Very high, millions of operations per second won't cause performance degradation.

String processing functions Date/time processing functions Color processing functions Data Table processing functions Type conversion functions Context related functions

Very high, millions of operations per second won't cause performance degradation. Very high to medium, only operations on very large tables (thousands of records) can generally cause noticeable CPU load impact. Very high, millions of operations per second won't cause performance degradation. Very high to low, depending on the context location (local or remote) and nature of referred context variable/function. See variables performance
878

and functions performance

880

for more information.

Memory Usage Impact

Expressions don't cause constant memory usage. However, evaluation of an expression can cause significant spot memory load if it refers some context variables or functions those underlying "implementation" code load or generate a lot of temporary data (e.g. load a long list of historical events 882 from server database or execute a query 271 over ten thousand devices).

6.8 References

References are used to indicate the location of data. Depending on the context, the referenc used to read data (i.e, data will be fetched from wherever the reference points to) or to writ (data will be saved to wherever the reference points to).
References may refer to any value that represents AggreGate internal data. The generic syntax of a reference is:

schema/server^context:entity(parameter_list)$field[row]#property
All parts of a reference except for field are optional.

2000-2013 Tibbo Technology Inc.

926

AggreGate Documentation

Reference Schema
A reference schema defines how the system resolves the rest of the reference. It helps the system "figure out" the meaning of the rest of the reference. Schemas are widely used in computing. For example, in the address http:// www.google.com, the http:// part is the schema. It tells your browser that this is an HTTP link, and that it should treat the rest of the line like this. An FTP link can have a different structure, such as ftp://joeuser:xxx@gmail. com. Here again, the ftp:// part defines the schema, and now your program knows how to handle the rest of the link. In AggreGate, Schemas are used to refer to various parts of the system:

env/ schema is used to refer to environment variables 930 (which are properties immediately concerning the current operation being executed), form/ schema is used in GUI Builder to refer to the properties of graphical components of
that widget is composed. A schema is optional: you don't necessarily have to include it in your reference. It just tells the system that your reference points to an environment variable (env/) or a graphical component (form/). If your reference points to the data coming from a context variable, a function or a cell of a Data Table, etc., you just omit the schema, and write your reference in the default format, which is described in the very next section (Resolving References). For example, a reference like form/TextField1#text uses the form/ schema, and refers to the "text" property of a widget component called "TextField1". A reference like users.admin:childInfo$firstname includes no schema, and refers to the first name of user "admin" (which is a field of the childInfo variable.

REFERENCE SCHEMAS USED IN AGGREGATE

Schema Not specified action/ env/ form/ menu/ previous/ Description Indicates that reference is a Standard Reference Used to launch an action
892 , 926 .

e.g. from a widget

930 .

312

binding

604

target

605 .

Points to an Environment Reference Widget component reference User inside a widget

312 606 .

Such reference are used in widget activator

607

312

binding expressions.
588

binding

604

to react to a context menu

item selection.

Used in chart dataset expressions (see Event-based Data 392 and Variable-based Data 393 properties of the Chart component). These use the same format as used for the Standard Reference 926 . However, Default Data Table 927 pointed by such reference is a Data Table containing the value for the previous data point (i.e. event data or value of changed variable). See this example 931 to find out how previous/ reference may be used to calculate the difference between two data points.

statistics/ table/ value/

Used to refer statistical

936

data from chart's dataset

394 .

When used as a data table binding 860 target, instructs the system to replace the whole table those binding is being processed by the one returned by current binding's expression. Used inside a widget 312 binding 604 condition 607 to refer fields of event that caused binding activation (or fields of variable those change caused the activation).

Resolving References
Resolving a reference is the process of getting the current value stored at the location the reference points to. Resolving algorithm depends on the reference schema. If the reference does not specify a schema, it is resolved as a standard reference
926 .

6.8.1 Standard References

Standard references may point to: Data Tables
854

representing values of context variables, input/output of context functions or just some relevant data.

Individual cells of the above tables. Properties of context variable/function/event definitions (e.g. their descriptions or readable/writable flags). Properties of data table fields (e.g. their descriptions and help texts).

2000-2013 Tibbo Technology Inc.

System Internals
The full syntax of a standard reference: context:entity(parameter_list)$field[row]#property

927

"Classic" Data Table Cell References

In the most common use case, standard references resolve to a Data Table cell value. This Data Table may be a variable value, function output, or just a certain table defined in current environment (see Default Data Table 927 ). Full syntax: context:entity(parameter_list)$field[row]. Resolved to a value of Data Table cell pointed by field and row. Data Table is a value of variable entity (or function entity if parameter_list is specified) in context context . Value from Default Context
927 :

entity(parameter_list)$field[row] field[row]

Value from Default Data Table

927 :

Default Row
If row is not specified, value is taken: From current row, if Data Table is processed row-by-row in the current environment; From row 0 (first row in a Data Table) in all other cases. Full syntax: context:entity(parameter_list)$field Value from Default Context
927 :

entity(parameter_list)$field field

Value from Default Data Table

927 :

Default Context
If context is specified in the reference, data is fetched from this context. If context is not specified, data is retrieved from a default context. The default context is automatically defined according to whatever you're doing. For example, when filtering events, the default context is the context in which a given event (the one we're working on) was fired. You might say that the default context is the "current context". Example: When working with widgets
315 ,

the default context is one from which the widget was launched.

Relative

864

context paths (e.g. .devices.device1) are resolved starting from this default context.

Example: childInfo$firstname refers to the default context, while users.admin: childInfo$firstname explicitly refers to a specific context.

{.:} reference will return path of default context. dc() function will also return this path.

Default Data Table

Just like you can omit the context part of the reference and still end up with a valid reference, you can also omit the entity part. When you omit the entity part, it is assumed you're referring to the so-called "default" Data Table, which can also be called "current Data Table". For example, when filtering events, the default Data Table is the table for the event being currently filtered. An example using the Default Data Table would be a reference such as firstname. That's the whole reference -- just firstname. When you write it, you assume the system would "know what you mean" -- i.e, that it would apply to the firstname field of the Data Table for event currently being filtered, in the case of filtering events.

{} (empty) reference will return the whole default Data Table (that can be used, for example, by Data Table processing functions 917 ). dt() function will also return this table.

Resolving Entity

2000-2013 Tibbo Technology Inc.

928

AggreGate Documentation

The entity part specified in the reference is the name of a variable or function existing in the context you're referring to. It is considered to be a function if the reference contains a parameter_list in parenthesis, and as a variable otherwise. So users.admin:childInfo refers to a variable, while users.admin:delete() refers to a function. If the entity you're referring to (such as delete()) does not exist, resolution will fail. A variable (such as childInfo) may actually be a table containing some fields (such as firstname). To refer to a field of some variable, you have to follow the variable name with a $ sign, followed by the field's name. So, to make the entity part refer to the firstname field of the childInfo variable, you would have to write it as childInfo$firstname. If reference points to a function, and it is called with parameters specified by the parameter_list during resolution. Example: Resolution of reference :register("charlie", "12345", "12345") will cause execution of register function from the root context.

FUNCTION PARAMETER LIST

The parameter_list is then used to create a Data Table according to the function's input format as described here
862 .

ERROR HANDLING
If an error occurs when getting variable value of calling function, reference resolution fails.

Data Table References

Resolved Data Table references return a whole Data Table. Data Table returned by such references is often used as an input parameter of Data Table processing functions 917 . If neither field nor property is specified, reference is resolved: to Data Table representing entity value, if entity is specified; to Default Data Table, if entity is not specified. Variable value reference syntax: context:variable Function output reference syntax: context:function(parameter_list) The above items mean that empty reference ("") is resolved to a Default Data Table. Here is how to insert reference to a Default Data Table into an expression: {}

Resolving Properties
Sometimes, you might want to specify a property to find out a certain property of context, variable, function, data table, or data table field. You might be wondering what is the difference between a field and a property. Well, a field contains actual data, while a property contains "meta-data" -- data about data. Let's say we're working with the version variable of the server context (its path is server:version). The variable contains a field (also called version) with actual data, such as "4.01.00" (this is the server version). You can refer to this field as server:version$version. This same variable also has a description property, containing data about the variable. In this case, the property would contain a string, "Server Version". The property is not stored within the variable's Data Table -- rather, it "concerns" the variable definition (rather than its value). You can refer to this property as server:version#description. So, when referring to a field you use the $ sign, and when referring to a property you use the pound sign ( #). This is important because fields often have properties (i.e, a field has a description). More on this below.

CONTEXT PROPERTIES
Context property reference syntax: context:#property Property Type Description

2000-2013 Tibbo Technology Inc.

System Internals

929

name description type icon

String String String Image

Name of the context. Description of the context. Type

864

of the context.
350

Context icon. May be used by Image

component of a Widget

312 .

VARIABLE DEFINITION PROPERTIES

Variable definition property reference syntax: context:variable#property Property description icon readable writable Type String Image Boolean Boolean Description Description of the variable. Property-specific icon. May be used by Image True if variable is readable for current user. True if variable is writable for current user.
350

component of a Widget

312 .

FUNCTION DEFINITION PROPERTIES

Function definition property reference syntax: context:function(parameter_list)#property Property description Type String Description Description of a function.

DATA TABLE PROPERTIES

Data Table property reference syntax: context:entity(parameter_list)#property Property records Type Integer Description Number of records in the table. This can be useful for figuring out how many records were returned in response to your reference. For example, users:list()#records calls the function listing all users in the system and returns the number of records in the result (i.e, how many users your permissions allow you to see in the system).

DATA TABLE FIELD PROPERTIES

Data Table field property reference syntax: context:entity(parameter_list)$field#property Property description help svdesc Type String String String Description Field description Field help (detailed description) Selection value description, i.e. string that is used to represent current field value in the user interface.

For example, users.admin:childInfo$firstname will return something like "John" (which is the value of the field), while users.admin:childInfo$firstname#description will return something like "User's first name" (which is the field's description property).

PROPERTY-ONLY REFERENCES
If reference consist of a property only (e.g. #property), it is resolved to one of the following properties: Property row Type Integer Description This property resolves to the current row of the Data Table being processed. For example, when widget chart 384 is based on custom data 388 , its Source Data table is processed line by line. For every line Source Data Bindings expressions are calculated. Thus, we may use {#row} in any Source Data Bindings expression to create consecutive series or category names (0, 1, 2, ... ).

2000-2013 Tibbo Technology Inc.

930

AggreGate Documentation

Examples
Reference Text Comments This reference returns the value of the recipient field in the default ("current") data table. It's useful, for example, when working with event filter 206 expressions. Same as above, but the value is taken from the fourth row. Resolves to the value of the email field in the Data Table containing the value for the childInfo variable in the user.admin context. Will contain the system administrator's email address in this case. This example starts with a colon. So it refers to the "" (empty string) context, which is the name of the root context. So it returns the description field of the info variable within the root context. Note that while "description" is also the name of a property, you can still have a "description" field as well. The difference is whether you use the # or the $ sign to refer to it. Resolves to the description property of the DS_setting field in the default data table. Resolves to the Data Table returned by "buzz" function in context users.test.deviceservers. To get a data table, the buzz function must be called, thereby causing the ds1 Device Server to blink its lights in the "real world". Resolves to the value of the firstname field in in the childInfo variable of the default ("current") context. This reference use a relative context path ("."). You might as well not put anything before the colon, but a dot works the same. You'll get a string with the user's first name ("Joe").

recipient

recipient[3] users.admin:childInfo$email

:info$description

DS_setting#description users.test.deviceservers.ds1:buzz()

.:childInfo$firstname

.:childInfo$country#svdesc

Returns name of user's country (that is the description of the selection value of country field). Note that .: childInfo$country will return the system internal numeric country code. This reference points to the status output field of the selfTest function defined in the context users. admin.deviceservers.ds1.devices.1. This function is called with one parameter. This reference will resolve to a Data Table returned by dailyActivityData function defined in attendance context. This function will be called with two parameters: Result of evaluating expression {.:}, that is a path of default context ("."). Result of evaluating expression {date}, that is value of date field in first row of default data table

users.admin.deviceservers.ds1.devices.1: selfTest("quick")$status

attendance:dailyActivityData ('{.:}','{date}')

users.admin#icon

Resolves to an icon of user context (

).

6.8.2 Environment References

Environment references point to special environment variables defined during the evaluation of an expression. For example, environment references may be used in event filter expression 207 : there are context environment variable pointing to the context when the event occurred, and level variable containing its severity (details are here 210 ). Environment variables are provided by the system. There is no way to define new environment variables or change their values.

2000-2013 Tibbo Technology Inc.

System Internals
References to environment variables are formatted like this:

931

env/xxx: env is a predefined string (don't change it). You put it there to indicate the schema you're using (i.e, environment variables) and thus invoke the environment variable resolver. xxx is the name of the variable. An
environment variable isn't the same as a context variable operation -- you just write its name. Example:
869 ,

so it never has a path. It refers to the currently running

env/level
This environment variable contains the severity level of the current event being processed. This example may not seem very useful at this point: to make it really useful, you have to put it in an AggreGate Expression, which we'll discuss in the next chapter.

STANDARD ENVIRONMENT VARIABLES

Some environment variables are defined in any environment: Variable Name count Description Number of calculations performed in the current environment. Equals to zero during the first calculation, and increments by one on each calculation. For example, if your expression referring {env/count} is used to calculate the data value for a chart, you may want to write something like {env/count} > 0 ? {value} {previous/value} : null to suppress calculation of the first data value (because {previous/value} is not defined yet. previous time Result of the previous calculation in the current environment. Used in chart dataset expressions (see Event-based Data 392 and Variable-based Data 393 properties of the Chart component). Returns timestamp of the currently processed data point (time when event occurred of variable change time). time and previousTime environment variables may be used to create time charts of values these are increased on each measurement. For example, if {incomingBytes} reference returns number of bytes that were received by the device since its startup, you can create a traffic chart by using the following expression:

{previousTime} != null ? ({incomingBytes} - {previous/ incomingBytes}) / ({env/time} - {env/previousTime}) : null

previousTi me Also used in chart dataset expressions. Returns timestamp of the previous data point or NULL for the first data point.

6.9 Security and Permissions

Resources having associated permission levels include: Contexts Variables Functions Events Actions
880 892 933 863 869 878

Tibbo AggreGate has a flexible and highly customizable security architecture. Most system r have an associated permission level 932 . A permission level describes who may access the resource.

Every user account 108 has a permissions table specified by context masks 865 .

that defines a user's permission levels for groups of contexts

863

Access Denied Window

If user's permissions are not sufficient to perform a requested operation, it will fail with the following error:

2000-2013 Tibbo Technology Inc.

932

AggreGate Documentation

6.9.1 Permission Levels

A Permission level defines if access to some resource is allowed. It works like this: if the permission level of a user requesting access includes the permission level of the requested resource, access is granted. Otherwise, it is denied. AggreGate Server operates with the following permission levels: Permission Includes Level None None Comments No permissions assigned. This permission level is assigned to any user who tries to access the system without a prior login. Very few operations may be executed with this permission level, such as the login operation, registration of new user account (if the Enable users self-registration global configuration option 53 is enabled) etc. The minimal permission level possible. Basically, this level allows to view most information, but no data modification is possible. It can be also useful to give someone "demo" permissions to view certain objects. Observers may view device settings and events, but cannot configure devices and execute operations provided by hardware. This is the permission level most everyday users should have. It allows viewing most non-system data and performing some basic data modification operations. Operators may configure hardware devices and execute device-provided operations, but cannot create/delete devices or edit device communication and data processing settings. This permission level allows all data browsing and editing activities like managing hardware devices, editing reports templates, creating and managing alerts, etc. The level that allows all operations with non-system data, including potentially dangerous operations, like running scripts. This permission levels should be assigned to system engineers. This permission level allows the execution of administrative actions: make changes to AggreGate Server global configuration, stop/restart the server, manage user accounts, etc. Basically, if a user has Administrator permission level within a context, they can do everything with this context.

Observer

None, Observer

Operator

None, Observer, Operator

Manager

None, Observer, Operator, Manager None, Observer, Operator, Manager, Engineer

Engineer

Administrato None, Observer, r Operator, Manager, Engineer, Administrator

If you wish to check what permission level is required to access a particular context, variable, function, event or action, please see Context Reference 651 . It may seem counter-intuitive that Events have permission levels. After all, an event just happens , whether you like it or not. A Device disconnects from the system -- that's an event. It's a fact of life, you might say. But you can select whether you want someone to be able to view the event or monitor it -- and this is what event permissions do. They let you determine who may see the event in the Event Log, create Alerts 216 for this event, etc. Advanced information: To understand what we mean when we say a permission includes another permission, you're going to have to think about permissions as binary bitmasks. If you're not sure what a bitmask is, please see http://en.wikipedia.org/wiki/Bitmask. A permission level is internally expressed as a bitmask. For example, the internal bitmask for None is 00000000, while for Observer it is 00000001, and for Administrator is 00011111. So, as you see, the Administrator mask (it's a mask - not just a number) includes the Observer and None masks, because it has a 1 in every position where the other masks have 1. This method is used because it is more versatile and powerful than just a numeric scale (i.e, None is 0, Observer is 1, etc).

Example 1

2000-2013 Tibbo Technology Inc.

System Internals

933

If the permission level of a user requesting access to a certain resource is Manager and the required permission level for the resource is Admin, access will be denied because Manager level does not include Admin.

Example 2
If the permission level of a user requesting access to a certain resource is Manager and required the permission level for the resource is Manager, access will be granted because Manager level includes Manager.

6.9.2 Default Context Permission Level

Every context has a default permission level . In order to be able to execute some operations with this context, a user must have this permission level or a higher one for it. Specific variables, functions, events or actions may require other permission levels than the default level. The default permission level defined for almost all context in the AggreGate Server is Observer. Here is a list of all exceptions (contexts whose default permission level differs from Observer): Context Administration Root
726 756 652

Default Permission Level Administrator None Administrator

Users

Example 1
The default permission level of the Root Context 726 of AggreGate Server is None. It means that even nonauthenticated users may execute some actions with this context. But the Restart Server and Stop Server actions that are defined in this context require Administrator permission level in this context. Thus, only users whose permissions table defines Administrator permission level for the Root context will be able to stop or restart the server.

Example 2
The default permission level of the User 759 context is Observer. But the Delete action defined in this context has an Administrator permission level. Thus, a user having the Observer permission level for this context will be able to view account status, but will not be able to delete it. The Administrator permission level is required for that.

6.9.3 Permissions Table

Every user account has a permissions table 111 property. This table is used to determine the permission level effective for a given context. This is the permission level 932 with which attempts to gain access to that context. If the effective permission level of a user includes the permission level of a resource, access will be granted. The permissions table has two columns: Context Mask and Permission Level. When a user tries to access some resource, AggreGate Server uses the permissions table to decide whether access should be granted or not. See permission checking 935 for details. The context mask and permission level are similar to the "Security Domain " and "User Role" concepts that are widely used to describe the architecture of many security systems. The last line of the permissions table must define permission level for all contexts, i.e. contain the "*" Context Mask.

2000-2013 Tibbo Technology Inc.

934

AggreGate Documentation

Every resource (variable, function, event, action) of a context has its own permission level, but there is no way to give users a dedicated permission level to a certain context resource. It's only possible to set a user's permission level for the context as a whole. This means that the system provides pre-defined scenarios of interaction with a context, and permission levels for context resources are assigned to avoid access conflicts in these scenarios. For example, if a certain context action changes some variables of this context, the action's permission level must include the permission levels of any accessed variables, otherwise the action may internally fail with Access Denied error even though the user was allowed to execute it.

Group Member Permissions

Permissions table allows to give an operator access to all members of a group context mask consisting of group context path and .* suffix, for example:
248 .

To give such permissions, use

users.admin.devgroups.my_device_group.*
Such permissions table record will allow access to all members of the my_device_group group at permission level specified in Permissions field.
932

Allowing access to all group members in the way described above creates a potential security risk! Group contents can be changed by operators or even automatically 250 , exposing newly added members for the user having permissions to access all group members. Grant group member permissions to operators only in case of absolute necessity.

6.9.4 Default Permissions Table

When a new user account is created, AggreGate Server builds a default permissions table for it. The contents of this table depends on the account name, and on the contents of two AggreGate Server global properties: Additional Permissions For New Users 73 and Default User Permissions 73 .

Last Records
Last three records of the new user's permissions table have special meaning. Here is an example: Context Mask users.NAME_OF_USER users.* * Permissions Manager None Manager

The first record declares Manager-level access to all contexts that are defined under the user's own User 759 context (e.g. users.NAME_OF_USER.alerts etc.). This level will be used if no dedicated permission level is assigned to a user's resource by the prior records. The second line denies access to contexts of all other AggreGate Server users by setting None-level permissions for them. Thus, the effective permission level for the context users.user123.widgets will be None (Unless, of course, the new account happens to be user123). The third line defines Manager-level to all other contexts that are not related to user accounts. This prevents a new user from executing administrative actions. For example, a new user will not be able to view administrative events because the Default Permission Level 933 of the Administration 652 context is Administrator . They would also not be able to stop or restart the AggreGate Server, because the Stop server and Restart server actions (defined in the Root Context 726 ) require Administrator -level access to this context.

Default User Permissions

For every record of Default User Permissions 73 table, a new record is added to the top of new user's permissions table. If Default User Permissions record is disabled, user is assigned None permission level to the resource specified by Default User Permissions record. Otherwise, the default level specified during user registration is used for the resource. Here is an example of new user's permissions table: Context Mask users.NAME_OF_USER.dsgroups Permissions None

2000-2013 Tibbo Technology Inc.

System Internals

935

users.NAME_OF_USER.devgroups users.NAME_OF_USER.filters users.NAME_OF_USER.alerts users.NAME_OF_USER.common users.NAME_OF_USER.jobs users.NAME_OF_USER.queries users.NAME_OF_USER.widgets users.NAME_OF_USER.autorun users.NAME_OF_USER.favourites common users.NAME_OF_USER users.* *

None None Manager None None None Manager None None None Manager None Manager

In the above example, only Alerts and Widgets records were enabled in Default User Permissions during user creation.

Additional Permissions For New Users

All records from the Additional Permissions For New Users 73 table are added to the very top of the permissions table and thus have highest priority. For example, let's assume we have two records in the Additional Permissions table: Context Mask (use % for user name) users.%.widgets external_device_servers Permissions Administrator Administrator

Assuming all items in Default User Permissions are enabled, we'll get the following permissions table for a new user: Context Mask users.NAME_OF_USER.widgets external_device_servers users.NAME_OF_USER users.* * Permissions Administrator Administrator User None User

6.9.5 Permission Checking

When a user tries to access a resource, AggreGate Server browses his permissions table line by line, starting from the first (topmost) one. If the context path 863 of the resource being accessed matches 866 or extends 865 the context mask defined in the current line of the permissions table, the permission level defined in this line will be used as the effective permission level for this path. Once a matching line is found, no other lines are matched. So, for example, if you start the table with the * context (i.e, that's the first line in the table) no other lines will ever be checked, because that line matches all contexts. That's why * is always the last line in the table. The effective permission level determined at the previous step is then compared with the permission level required by the resource being accessed. If the effective permission level includes 932 the permission level required by the resource, access is granted. Otherwise, it is denied. If the context path of the accessed resource doesn't match or extend any mask defined all throughout the table, the effective permission level for the resource being accessed is defined by the last line in the permissions table, because it always defines the permission level for all contexts (* Context Mask).

EXAMPLE 1
Supposing that the permissions table of the user john looks like this:

2000-2013 Tibbo Technology Inc.

936

AggreGate Documentation

Line Context Mask 1 2 3 users.test users.* *

Permissions Manager None Manager

1. John tries to access user.abc.alerts. The permission level required to access that resource is Manager. The first line in the table, users.test, doesn't match or extend the users.abc.alerts mask, so we move on to the second line, users.* and see that it does extend users.test. This second line specifies None as the permission level, and so access will be denied. 2. John tries to access event_filters.filter1, requiring a Manager permission level. John's effective permission for event_filters.filter1 will be defined by the third line in the table, and thus access will be granted. 3. John tries to access users.test.queries, requiring an Administrator permission level. His effective permission level for that context is defined by the first line in the table. It will be Manager (lower than Administrator ), and thus John will be denied access to users.test.queries.

EXAMPLE 2
Permissions table of the default administrator Line 1 Context Mask *
109 :

Permissions Admin

The effective permission level of the default administrator for any context is Admin, because all context paths extend the * mask. So the administrator may execute any operation in any context.

Temporarily Disabling Access To Some Objects

When a user's permission table is adjusted so as to keep them from accessing some of their own resources, the resources are not actually destroyed or affected in any way. In fact, some other user may have access to these resources even if their owner has no access to them.

EXAMPLE
John, the guy from the last example, has an Alerts 654 context, users.john.alerts. This path always exists. Initially John can access his Alerts, because Default User Permissions let him do so. He logs onto AggreGate Server and creates an alert, alert1. Then, the administrator adjusts John's permissions table so that John can no longer see his Alerts context (for example, by adding a record with Context Mask users.john.alerts and Permissions None to the beginning of the table). This does not destroy alert1. It doesn't even stop it from working. Some other AggreGate Server users may still have access to this alert, and be able to configure and monitor it. Once the administrator lets John access his alerts again, alert1 will show up under his Alerts context.

6.10 Statistics
AggreGate platform can store long-term time series data in a Round-Robin Database (RRD). The module responsible for collecting, storing and processing time-series data is called Statistical Process Control module, or simply Statistics. Round Robin Database (RRD) aims to handle time-series data like network bandwidth, temperatures, CPU load etc. The data are stored in an circular buffer, thus the system storage footprint remains constant over time. See RRD Technology 945 article for more information. The RRD database has two important benefits for storing long term statistical data: Small and constant database size Extremely fast access to the historical data for any time period

Statistics Channels
In AggreGate, RRD-based statistical data is presented by named Statistics Channels. Each channel processes value of one context variable 869 . However, since channel Primary Data Points 945 are calculated by expressions 911 , channel source values may be based upon any data flowing inside the system. Each channel defines: Expression used to determine values of Primary Data Points

2000-2013 Tibbo Technology Inc.

System Internals
Storage type (file or memory) Channel type
942

937

(gauge, counter, etc.)

Active aggregation functions (average, minimum, etc.) Storage periods for different aggregation intervals (hourly, daily, etc.) And other options
938

Use of Statistics
Currently, the following AggreGate data processing facilities allow to use statistics: Devices
113

. One or more channels may be created to keep history of every device setting variable. . Each tracker has a pre-created statistical channel to keep changes history.

Trackers

257

For more information see: Device Setting Statistics Tracker Statistics

259 117

Channel Elements
Each statistical channel consists of the following elements: Datasets. Datasets allow to store multiple sets of statistics for one context variable. Simple variables match one dataset, while each row in a tabular variable may be identified by a unique key to form a named Dataset. See Working With Keys 942 for details. Archives. Each dataset includes several Archives that contain data aggregated by different time periods. For example, the dataset may include one Archive with monthly averages, another one with hourly maximums, etc. The available Archive types are Minutely, Hourly, Daily, Weekly, Monthly, and Yearly.

2000-2013 Tibbo Technology Inc.

938

AggreGate Documentation

6.10.1 Statistics Channel Properties

This article cover properties of a single statistical channel.

Source Data

2000-2013 Tibbo Technology Inc.

System Internals

939

EXPRESSION
The Expression property defines what data is the base of statistics. It is evaluated on every change of variable that the channel is built upon. The expression must evaluate to a number (integer of floating point). If the expression evaluates to any other data type, the system tries to convert it to a number and skips the value if conversion fails. If the expression evaluates to NULL, the system applies NULL Value Handling method to it (see below). Statistics Channel Expression Resolution Environment Default Context
927 927 922

Context that the channel is defined in. Current value of the variable that the channel is based on. 0 if Use Key Field property is disabled. Number of currently processed row if Use Key Field is enabled.

Default Data Table Default Row

927

Environment Variables 930

Standard

931

variables only.

Key Fields
A channel may include one or more Datasets for a single context variable. Multiple Datasets can be created for tabular variables. In this case each row in the variable is identified by unique string key (Dataset name). See Working With Key 942 section for further explanation.

Values Post-Processing
Statistics channel provides several options for post-processing values returned by channel Expression : NULL Value Processing Out Of Range Values Processing Minimal Value Maximal Value

NULL VALUE PROCESSING

This setting defines that should the channel do when its Expression was evaluated to NULL. There are two options: Discard. Value will be silently dropped. If no other values were received for a certain period, channel overall value becomes UNDEFINED for this period. Treat As Zero. NULLs values will be converted to zeros.

OUT OF RANGE VALUE PROCESSING

Specifies how to process the values that are less than Minimum Value or greater than Maximum Value. The following choices are available: Do Nothing. Simply disables minimum/maximum values for the channel. Discard. Drops values that are less than minimum or greater than maximum. If no other values were received for a certain period, channel overall value becomes UNDEFINED for this period. Normalize. Values less than minimum and greater than maximum are converted to the minimum and maximum values respectively.

MINIMAL VALUE AND MAXIMAL VALUE

These numbers define discarding/normalization thresholds, as specified by Out Of Range Value Processing option. When enabled for the counting-type 942 channels (Counter, Derive and Absolute), these numbers define minimal and maximal per-second rates .

Minimal and Maximal Value settings are very useful to handle counter resets and erroneous decreases. If you've a counter that can reset to zero or decrease at any time (e.g. during device reboot), AggreGate Server has no way to detect whether the counter has been reset or overflowed. However in case of counter reset or

2000-2013 Tibbo Technology Inc.

940

AggreGate Documentation

decrease calculated per-second rate will be very high. For example, if counter value measured at 18:00:00 was 100 000 and the next reading at 18:01:00 resulted to 1000, statistics module will suppose that the counter was increased up to 2^32 (4.2 billion), overflowed, and increased to 100 during this minute. Thus, calculated per-second rate will be definitely higher than 1 000 000. To exclude such high rates caused by counter resets from your statistics, just set Maximal Value to something definitely higher than your maximum expected per-second rate but lower than abnormal "counter reset rate". For example, if your maximum expected per-second rate is 10 000, set Maximum Value to 100 000 to throw incorrect rates away and avoid statistics cluttering.

Statistics Storage
Basically, statistical data may be stored in files and memory. File-based storage is persistent, while data of memorybased channels is discarded when server is restarted.

STORAGE
Storage property defines statistics storage type. There are three options: Standard file (Lower memory usage, slower) Mapped file (Higher memory usage, faster) Memory Memory based storage guarantees maximum performance, but it doesn't preserve data between server restarts and, therefore, has very limited uses. Here are some guidelines for making a choice between standard files and memory-mapped files: Memory-mapped file caches channel data in memory (borrowed not from JVM, but directly from the underlying operating system), while regular file's data is kept on the disk. Both file-based storage's performance dramatically depend to the operating system, so in most cases it's necessary to perform some tests to finally select one of them.

Channel Type
The channel Type setting defines how are subsequent source values processed to form Primary Data Points channel. See Channel Types 942 for details.
945

for the

Data Aggregation
Statistics module use Aggregation Functions (AF) to convert Primary Data Points into Consolidated Data Points (see RRD Technology 945 for details). There are siz aggregation functions that may be individually enabled/disabled for a channel: Average Minimum Maximum Total First Last Data aggregation functions are applied to all Archives 937 enabled for the channel. For example, if Average aggregation function is enabled, the system keeps Minutely, Hourly and other averages.

AVERAGE
This function calculates an average of Primary Data Points to form a Consolidated Data Point. This is an average of values themselves (for Gauge 943 channel) or value change rates (for Counter 943 and other channel types).

MINIMUM
This function takes finds minimal Primary Data Point to use as a Consolidated Data Point. This is minimal value itself (for Gauge 943 channel) or minimal value change rate (for Counter 943 and other channel types).

MAXIMUM
Similar to Minimum.

2000-2013 Tibbo Technology Inc.

System Internals

941

TOTAL
This function sums all Primary Data Points to form a Consolidated Data Point. This is a sum of values themselves (for Gauge 943 channel) or value change rates (for Counter 943 and other channel types).

FIRST
This function takes first Primary Data Point as the value for a Consolidated Data Point.

LAST
This function takes last Primary Data Point as the value for a Consolidated Data Point.

Archives
Each channel can have all or some of the following Archives Minutely Hourly Daily (fixed 24 hours period, see note below) Weekly Monthly (fixed period, see note below) Yearly (fixed period, see note below)
937

enabled:

Important note: the RRD database and statistics module are always dealing with fixed length time periods. This leads to the following consequences: 1. Daily archives are set up for the 24-hour days. This will produce incorrect daily results for days when switching from DST (summer time) to normal time and back occurs. 2. Monthly archives are set up for an average month length during any four consequent years (three normal years and one leap year), which is around 30.43 days. This affects the precision when calculating per-month and per-year statistical values for all months/years. To get more precise monthly and yearly results, you need to base your statistics on daily samples and use additional aggregation on the later steps of processing, e.g. chart's internal data aggregation that will group daily samples by "real" months/ years. To get results with highest possible precision level, base your calculations on hourly statistical samples and use higher-level aggregation to group results by days, weeks, months or years.
Length of each archive, i.e. number of Consolidated Data Points in it, is configurable. To completely disable an archive set its length to NULL (<Not set>).

System administrators define length of archive in "human" time units, while number of Consolidated Data Points is calculated automatically. For example, if length of Minutely archive is set to 1 day, it will contain 1440 CDPs (i.e. 1440 Averages, 1440 Minimums, 1440 Maximums and 1440 Totals, having all that aggregation functions enabled).

Step
Granularity interval for the channel, see RRD Techology Changing Step will reset channel statistics.
945

for details. The Step should not be changed in most cases.

2000-2013 Tibbo Technology Inc.

942

AggreGate Documentation

Since the default step is 60 seconds, the Average, Minimal and Maximal statistical values for the Last Minute period will be equal.

XFiles Factor
The XFiles Factor defines what part of a consolidation interval may be made up from "Unknown" Data Points while the consolidated value is still regarded as known. It is given as the ratio of allowed "Unknown" Primary Data Points to the number of PDPs in the interval. Thus, it ranges from 0 to 1 (exclusive). Changing XFiles Factor will reset channel statistics.

The default value is 0.9, meaning that 90% of initial samples may be missing. To ensure more reliable statistical values, decrease this value. The typical setting is 0.5.

Show In Status
Defines whether this channel's brief statistics should be shown in the status of container (i.e. device or tracker).

6.10.1.1 Working With Keys

If channel source variable is tabular, the channel may work in two modes by creating either one or multiple RRD Datasets for a single source variable. These modes are switched by Use Key Field flag. See Statistics Configuration Examples 944 to learn how to use both modes.

USE KEY FIELD

The channel may work in two modes: If Use Key Field is disabled (the default setting), a single Dataset channel.
937

(i.e. set of statistical data) is created for this

If Use Key Field is enabled, one Dataset is created for every record in the source variable's value. This option does, of course, have sense only for channels based on tabular variables. The name of dataset is defined by the unique record key that is constructed according to Key Field property. Here is what action is taken by the system when channel source variable is updated: 1)When Use Key Field is disabled, the channel Expression is evaluated only once, having row number zero as the default row 927 during evaluation. The result of evaluation is converted to a number and the only dataset (that is untitled) is updated with this number. 2)When Use Key Field is enabled, the channel Expression is evaluated once for every row found in the source table. For each row: a) First, the system determines what dataset does current row correspond to. This is performed by either taking value of Key Field or value of first field that is marked as key 856 in variable format. b) Second, channel Expression is evaluated having current row set as the default row c) Third, the dataset those named was determined at step (a) is updated.
927 .

KEY FIELD
This property defines what field of channel source variable is used to determine RRD dataset names when Use Key Field is enabled. Here is how the dataset name is constructed from the Data Table record: If Key Field is non-NULL, value of this field will be used as dataset name; If Key Field is NULL, the value of first key field
856

defined in table format will be used as dataset name;

If Key Field is NULL and no key fields are defined in table format, dataset name will match current record's number.

6.10.1.2 Channel Types

Channel Type setting completely change the style of how raw values are processed to calculate channel's Primary Data Points 945 . There are four channel types: Gauge

2000-2013 Tibbo Technology Inc.

System Internals
Counter Derive Absolute

943

Gauge
Value of Primary Data Point equals to the channel Expression evaluation result, i.e. the only conversion is application of NULL Value Processing and Out Of Range Value Processing rules. This type is suitable for simple metering like temperature, number of people in the room or stock price.

Counter
Suitable for continuous incrementing counters. The Counter data source assumes that the counter never decreases, except when a counter overflows. The statistics update function takes the overflow into account. The counter is stored as a per-second rate. When the counter overflows, channel checks if the overflow happened at the 32bit or 64bit border and acts accordingly by adding an appropriate value to the result. Simply speaking, Counter will look at the difference between the previous value and the current value (the delta). An example would be an odometer. The Primary Data Point is computed as: delta(counter) divided by delta(time). Examples of counters: - Vehicle travel distance (number of meters passed by the vehicle) - Error count (number of errors occurred since device startup) - Interface traffic (number of ingress/egress bytes on the interface since network device power up). - CPU load caused by a process (number of milliseconds of CPU time consumed by the process since its startup)

Derive
Derive-type channel can measure both increments and decrements. This can be useful for gauges, for example, to measure the rate of people entering or leaving a room. Internally, derive works exactly like Counter but without overflow checks. So if your counter does not reset at 32 or 64 bit you might want to use Derive and combine it with a Minimum Value of 0. Derive is really similar to Counter, but now it can also go back. An example could be something monitoring a bidirectional pump. The resulting pumping rate can be negative as well as positive.

Absolute
Absolute channels are used for counters which get reset upon reading. This is used for fast counters which tend to overflow. So instead of reading them normally you reset them after every read to make sure you have a maximum time available before the next overflow. Another usage is for things you count like number of messages since the last update. Absolute channel is also similar to the odometer, but here the counter is reset every time it is read. Primary Data Point computed as: value divided by delta(time).

6.10.2 Data Processing Sequence

This article describes the complete sequence of steps taken by a statistical channel to convert values of AggreGate Server variable 869 's fields into statistical data points. This sequence is followed each time when variable change was detected. 1. First, channel Expression is calculated. 2. NULL Values Processing rule is applied to discard NULL value or convert it to zero. 3. The resulting non-NULL value is converted to a number on a best-effort basis. Values that cannot be converted to numbers are discarded. 4. Out Of Range Values Processing rule is applied to ensure that numeric value is within a valid range and discard/ normalize it if appropriate.

2000-2013 Tibbo Technology Inc.

944

AggreGate Documentation

5. The value is processed according to the channel Type to form new channel's Primary Data Point. If Type is Gauge, value is left as-is. For Counter, the resulting value will represent the source value's per-second change rate. 6. Primary Data Point value is used to update channel's Consolidated Data Point(s) according to enabled aggregation functions (Average, Minimum, etc.). This is performed for every Archive (Minutely, Hourly, etc.) 7. Consolidated Data Point value(s) are saved in file/memory Storage.

6.10.3 Charting Statistical Data

Statistics module is designed to work in close cooperation with charts data in the same way as raw historical values.
384 .

It is possible to graph statistical time series and use a special {statistics/} reference

To build a chart upon variable statistics, create a Variable-based Chart within data series expression to refer statistical data. See Statistics-Based Series
394

393

for more information.

6.10.4 Statistics Configuration Examples

This section provides several examples of configuring statistics channels to solve everyday tasks.

Example 1: Temperature
Assuming we've a simple variable that represents current temperature in degrees (Celsius). The variable has only one record with a single field called temp . However, we want our statistics to be based on Fahrenheit-scale metering. Here is how the channel properties
938

should be set up for this case:

The channel Expression should be {temp} * 9 / 5 + 32. This will ensure temperature conversion. Since the channel is based on a simple (non-tabular) variable, Use Key Field setting should be disabled.

Example 2: Disk Usage

This example illustrates how to track disk usage for the case when multiple disks stats is located in a single table. Assuming we have a variable with the following value: Label (Key Field) 00DFFF 45CABC CBBC99 Disk C: D: E: Used 150 500 10 To tal 30 0 70 0 30

Label field is a key field according to the above table's format. Here is how the channel properties
938

should be set up for this case:

Our channel Expression will be {Used} Since we need to create a single RRD dataset for every tracked disk, the Use Key Field flag should be enabled If we leave Key Field Name property at default (NULL), the system will use value of Label field (i.e. disk labels) as dataset names. This will happen since Label is a key field. However, this is not convenient, so we set Key Field to Disk. This forces disk names to be used for naming RRD datasets.

2000-2013 Tibbo Technology Inc.

System Internals

945

6.10.5 RRD Technology

RRD assumes time-variable data in intervals of a certain length. This interval is named step . Because data may not always be available at just the right time, RRD will automatically interpolate any submitted data to fit its internal timesteps. The value for a specific step, that has been interpolated, is named a primary data point (PDP). Multiple PDPs may be consolidated according to a aggregation function (AG) to form a consolidated data point (CDP). Typical consolidation functions are average , minimum, maximum, and total. After the data have been consolidated, the resulting CDP is stored in a round-robin archive (RRA). A round-robin archive stores a fixed amount of CDPs and specifies how many PDPs should be consolidated into one CDP and which AF to use. The total time covered by an RRA can be calculated as follows: Time Covered = (#CDPs stored) * (#PDPs per CDP) * step After this time the archive will "wrap around": the next insertion will overwrite the oldest entry. This behavior is sometimes referred to as "round-robin" and is the reason for the technology name.

How RRD Differs from Classic Database

1. In case of linear databases, new data gets appended at the bottom of the database table. Thus its size keeps on increasing, whereas the size of an RRD database is determined at creation time. Imagine an RRD database as the perimeter of a circle. Data is added along the perimeter. When new data reaches the starting point, it overwrites existing data. This way, the size of an RRD database always remains constant. 2. Other databases store the values as supplied. RRD can be configured to calculate the rate of change from the previous to the current value and store this information instead. 3. Other databases get updated when values are supplied. The RRD database is structured in such a way that it needs data at predefined time intervals. If it does not get a new value during the interval, it stores an UNKNOWN value for that interval.

6.10.5.1 Rates, normalization and consolidation

Statistics module stores rates during time intervals. These time intervals are on well defined boundaries in time. However, your input is not always a rate and will most likely not be on such boundaries. This means your input needs to be modified. This section explains how it works. A couple of different stages should be recognized: transforming to a rate normalizing the interval consolidating intervals into a larger one This does not get in your way, it is not doing bad things to your data. It is how SPC module works, by design. All stages apply for all input, no exceptions. There is no short circuit. After transforming your input into a rate, normalization occurs. After normalization, consolidation occurs. All three stages can be a no-op if you carefully setup your database, but making one stage a no-op does not mean the other stages are skipped. If you use Gauge 942 , the input is already a rate, but it is still subject to normalization. If you enter the data exactly at the boundaries normalization is looking for, your input is still subject to consolidation.

Transforming to a Rate
Everything is processed as a rate. This doesn't mean you cannot work with temperatures, just remember it is processed as if it was a rate as well. There are several ways for SPC module to get a rate from its input (depending on the channel type Gauge: Keep it "as is". The input is already a rate. An example would be a speedometer. This is also the type used for keeping track of temperature and such. Keep it "as-is" does not mean normalization and consolidation are skipped! Only this step is. Counter: Look at the difference between the previous value and the current value (the delta). An example would be an odometer. The rate is computed as: delta(counter) divided by delta(time). Absolute:
942 ):

2000-2013 Tibbo Technology Inc.

946

AggreGate Documentation

As the odometer, but now the counter is reset every time it is read. Computed as: value divided by delta(time). Derive: As counter, but now it can also go back. An example could be something monitoring a bidirectional pump. The resulting rate can be negative as well as positive. In each of these four cases, the result is a rate. This rate is valid between the previous update of statistical channel and the current one. SPC module does not need to know anything about the input anymore, it has start, end and rate. This concludes step 1. The data is now a rate, no matter what data source type you use. From this moment on, SPC module doesn't know nor care what kind of data source type you use.

About Rate and Time

If you transfer something at 60 bytes per second during 1 second, you could transfer the same amount of data at 30 bytes per second during 2 seconds, or at 20 bytes per second during 3 seconds, or at 15 bytes per second during 4 seconds, et cetera.

These numbers are all different yet they have one thing in common: rate multiplied by time is a constant. In this picture, it is the surface that is important, not its width nor its height. This is because we look at the amount of data, not at its rate nor its time. Why this is important follows later.

Normalizing Intervals
The input is now a rate but it is not yet on well defined boundaries in time. This is where normalization kicks in. Suppose you are looking at a counter every minute. What do you know? You know counter values at HH:MM:SS. You don't know if the counter incremented at a high rate during a small amount of time (1 second at 60 bytes per second) or during a long time at a small rate (60 seconds at 1 byte per second). Look at the picture above again, each HH:MM:SS will be somewhere in the white areas. This means that the rate you think you know isn't the real rate at all! In this example, you only know that you transfered 60 bytes in 60 seconds, somewhere between MM:SS and the next MM:SS. Its computed rate will be 1 byte per second during each interval of 60 seconds. Let me emphasize that: you do not know a real rate, only an approximation.

Now look at the next image, showing some measured intervals and rates. The samples are taken at 30 seconds past the minute, each colored area represents another measurement. There are four measured intervals, the last one has a rate of zero but it is known (i.e. the last update occurred at 04:30). One expected update, the one at 02:30, did not happen. SPC module can cope with this perfectly well if you let it. The update just happens at 03:30 and is valid from 01:30. The bottom part of the image is the result after normalization. It shows that each interval uses a bit of each input interval. The first interval is built from the blue interval (which started before 00:00) and the red interval (measured between 00:30 and 01:30). Only the blue part that falls inside the 00:00 to 01:00 interval is used, only the red part that falls inside the 00:00 to 01:00 interval is used. Similar for the other intervals. Notice that it are areas that are important here. A well defined part of the blue area is used (in this example exactly half) and a well defined part of the red area is used (dito). Both represent bytes transferred during an interval. In this example we use half of each interval thus we get half of the amount of bytes transferred. The new interval, the one created in the normalization process, has a surface that is exactly the sum of those two amounts. Its time is known, this is a fixed amount of time, the step size you specified for your database. Its rate is its area divided by this amount of time. If you think it isn't right to shift data around like this, think again. Look at the red interval. You know something has happened between 00:30 and 01:30. You know the amount of data transferred but you do not know when . It could be that all of it was transferred in the first half of that interval. It could also be that all of it was transferred in the last half of that interval. In both cases the real rate would be twice as high as you measured! It is perfectly reasonable to divide

2000-2013 Tibbo Technology Inc.

System Internals

947

the transfer like we did. You still don't know if it is true or not. On the long term it doesn't make a difference, the data is transferred and we know about it. The rates are now normalized. It are these rates that statistics module works with. Notice that the second and fourth normalized rate (mixture of red and green, mixture of green and white) are lower than the green rate. This is important when you look at maximum rates seen. But as both the red and green rates are averages themselves, the mixture is as valid as its sources. Each normalized rate is valid during a fixed amount of time. Together these are called Primary Data Points (PDPs). Each PDP is valid during the step size. SPC module doesn't know nor care about the input you gave it. This concludes step 2. From now on, SPC module forgets all original input. Even if normalization is a no-op (if you made sure your timestamps are already on well defined boundaries) consolidation still applies.

Consolidating Intervals
Suppose you are going to present your data as an image. You want to see ten days of data in one graph. If each PDP is one minute wide, you need 10*24*60 PDPs (10 days of 24 hours of 60 minutes). 14400 PDPs is a lot, especially if your image is only going to be 360 pixels wide. There's one way to show your data and that is to take several PDPs together and display them as one pixel-column. In this case you need 40 PDPs at a time, for each of the 360 columns, to get a total of ten days. How to combine those 40 PDPs into one is called consolidation and it can be done in several ways: Average: Compute the average of each rate (of those 40) Minimum: Take the lowest rate seen (of those 40) Maximum: Take the highest rate seen (of those 40) Sum: Take the sum of those 40 rates First: Take the first rate seen (of those 40) Last: Take the last rate seen (of those 40) Which function you are going to use depends on your goal. Sometimes you would like to see averages, so you can use it to look at the amount of data transferred. Sometimes you want to see maxima, to spot periods of congestion, et cetera. Whichever function you use, it is going to take time to compute the results. 40 times 360 is not a lot but consider what's going to happen if you look at larger amounts of time (such as several years). It would mean you have to wait for the image to be generated. This is also covered by SPC module but it requires some planning ahead. In this example, you are going to use 40 PDPs at a time. Other examples would use other amounts of PDPs each time but you can know up front what those amounts are going to be. Instead of doing the calculations at use-time, SPC module can do the computations at monitoring time. Each time a series of 40 PDPs is known, it consolidates them and stores them as a Consolidated Data Point (CDP). It are these CPDs that are stored in the database. Even if no consolidation is required, you are going to "consolidate" one PDP into one CDP.

6.10.6 Server-side vs Device-side Aggregation

Many devices that are connected to AggreGate (via Agents 848 or device drivers 129 ) provide different gauge-type or counter-type values, such as temperature readings, odometers, or fuel consumption counters. These values are normally grouped by time periods (aggregated) to allow use consolidated values (averages, minimums and maximums) inside reports 241 , charts 384 and other data processing tools. Developers of device monitoring and control systems often face a necessity to choose between aggregating data inside a device and passing raw values into AggreGate Server. This article explains pros and cons of each method.

Aggregating Data Inside Device

In this case device calculates consolidated values (such as daily averages or monthly minimums) by itself. It then provides the pre-calculated table of values to the server in the form of tabular variable, such as:

2000-2013 Tibbo Technology Inc.

948

AggreGate Documentation

Month Jun 2012 Jul 2012 Aug 2012 Pros of this method:

Average Fuel Consumption 124 131 119

Device can continue data aggregation even if connection to the server is not available for long time (however some protocols, such as AggreGate protocol, allow device-side buffering) Aggregated statistics is available inside device, e.g. for displaying on the device LCD or internal web interface Cons of this method: Implementation of data aggregation inside the device is quite complicated Aggregated statistics will occupy device-side storage space If many aggregation types are required (e.g. for charting), such as minutely/hourly/daily/weekly/monthly/yearly averages/minimums/maximums, the device must provide multiple aggregation tables for single counter Aggregation tables will fully be re-read from the server during any update, partial reading is not possible Aggregation data will be duplicated in the device and in the server database Charts won't be able to auto-switch between different aggregation types (e.g. from daily to monthly samples)

Aggregating Data on the Server Using Statistics Channels

In this case device provides raw values to the server in the form of variables. Server polls these variables and uses statistical channels 936 to calculate and store aggregated data points. Pros of this method: Only raw values are sent to the server and, therefore, device-to-server traffic is minimized Device resources are not consumed for calculating, storing and exposing aggregated data Server provides centralized control for aggregation parameters Aggregated data points from multiple devices can be easily combined within server reports of charts Cons of this method: Unless buffering is used, server will not receive raw values from offline devices, what can cause gaps in highgranularity statistics (minitely, hourly) and degradation of precision in low-granularity statistics (daily, monthly, yearly) Device itself won't be able to profit from consolidated data, e.g. display it in its web interface

Using Both Methods

In some systems it may be reasonable to combine both methods, i.e aggregate data on both device and server sides. In this case some server-side data analysis tools will use pre-build device-side consolidation tables, and others will refers to server statistical channels.

6.11 Resource Validity

Resource validity is a technology that allows AggreGate Server to detect that a certain resource is "compatible" with some other resources. The validity is relevant for the following types of resources: Widgets
312

. If a relative

314

widget is valid for a certain context, it can use this context as its primary data source.
619

Dashboards 617 . If a relative data from this context.

dashboard is valid for a certain context, it can be opened so that its elements take

Reports 241 . If a relative 242 report is valid for a certain context, it may take data from this context to fill in the template when report is being created. Groups
248

. If a certain context is valid for a dynamic group

250 ,

it will be automatically added to this group.

261 ,

Common Tables 260 . If a certain context is valid for a common table that is used as a custom property custom property will be added to this context.

this

2000-2013 Tibbo Technology Inc.

System Internals

949

Models 303 . If a relative model is valid for a context, a dedicated copy of this model will be created and attached to this context in order to interact with it.

Configuring Validity
The validity is configured using two options: Validity Expression Validity Update Rules

Validity Expression
Validity Expression helps AggreGate Server to determine what contexts 863 a resource can work with. It is written using the built-in Expression Language 911 . When a new resource is created, or the validity expression itself is updated, AggreGate Server evaluates this expression for every context in the system. If the expression evaluates to true , the server considers that the resource "understands" the data of this context, and: For widgets
312

, installs a Launch Widget

617

316

action into this context

621

For dashboards For reports For groups

241 248

, installs a Open Dashboard

243

action into this context

, installs a Launch Report

action into this context

, adds this context into the group

260 ,

For common tables For models

303

registers this common table as a custom property of this context

, attaches a separate copy of the model to this context

Example 1: The Validity Expression is often used to check the type 864 of context. This is very useful for creating widgets that work with certain types of Devices or system resources. For example, to make a widget 312 work with every SNMP (Simple Network Management Protocol) device in the system, set the Validity Expression to {.#type} == 'device.snmp'. This expression will resolve to TRUE when the type property for the context being checked (indicated by "." relative context path) equals device.snmp. Example 2: Dynamic groups 250 use Validity Expression for consolidating devices of a certain type. For example, to make a group containing all printer devices in the system, set the Validity Expression to startsWith({.#type}, 'device') && {.:genericProperties$type} == 'printer'. This expression will resolve to TRUE when the type property for the context being checked (indicated by "." relative context path) starts with device word and type field of genericProperties variable (that contains a user-selected type for a device) equals to printer. Validity Expression Resolution Environment Default Context
927 927 922

Context those validity is verified. None. 0

930

Default Data Table Default Row

927

Environment Variables

Standard

931

variables only.

VALIDITY EXPRESSION RECALCULATION

The Validity Expression is calculated in the following cases: On server startup, to initially associate the resource with all existing valid contexts When a new context is created, to associate the resource with it if it's valid When a Validity Expression itself is modified it's recalculated for all context in the system because new set of contexts will become valid while others may be no longer valid When an event pointed by any Validity Update Rule
949

occurs

Validity Update Rules

Validity Update Rules instructs AggreGate Server when it should re-calculate Validity Expression for a certain context to check whether is become valid for a resource. Every Validity Update Rule consist of: Mask of contexts to monitor events in Name of Event to listen for

2000-2013 Tibbo Technology Inc.

950

AggreGate Documentation

Target Expression that, if specified, points to a context those validity should be checked. If Target Expression is not specified (what is suitable in most cases), the system checks validity of context in that Event has occurred. Example 1: Assuming we want to make a Report 241 that is valid for all device contexts has Collector_ prefix. We may use the following Validity Expression:
677

those description

startsWith({info$type}, "device.") && startsWith({info$description}, "Collector_")

This Validity Expression checks type and description fields of info 871 variable what is available in all contexts. The context type never changes, but its description may be edited at any time. If we want our report to be added to any context right after its description has been changed to one starting with Collector_, we need to add the following Validity Update Rule:

Mask: users.*.devices.* Event: infoChanged Target Expression: <Not Set>

This rule will be activated every time when an infoChanged event occurs in any device context. This actually happens when info variable is changed, e.g. when context description change occurs. The rule will cause Validity Expression recalculation for the device context those description was changed and, if the new description starts with Collector_, the Launch Report 243 action will be added to the device. Example 2: We need to make a dashboard 617 that can be opened only for devices that belong to a certain group 248 . We have to use the following Validity Expression:

aggregate({users.admin.devgroups.test:visibleChildren}, ({path} == '" + dc() + "' ? 1 : 0)", 0) > 0

"{env/previous}

This Validity Expression uses aggregate() function to list all rows in visibleChildren table of every context. If path field in current row is equal to the path of context those validity is being checked (returned by dc() function), this context is deemed found among group members, and thus, valid. In this case aggregate() function will return 1 (and 0 otherwise). If we want our dashboard to be registered in context menu of devices right after we add them to test group, we need to add the following Validity Update Rule:

Mask: users.admin.devgroups.test Event: visibleChildAdded Target Expression: {path}

Once a new member was added to the group, visibleChildAdded event will occur in the group context 702 . Target Expression refers path field of this event, and thus, the Validity Expression will be recalculated for newly added member (pointed by path field of the event). Since it will always return true, the dashboard's Open Dashboard Action 621 will be added to the device. To ensure that dashboard is no longer valid when devices are removed from the group, we need to add another Validity Update Rule:

Mask: users.admin.devgroups.test Event: visibleChildRemoved Target Expression: {path}

The only difference is that at the time of visibleChildRemoved event the Validity Expression will already return false for context pointed by path field of event data. So the dashboard will de-register itself from any device that was excluded from the group.

6.12 Plugins
Some functions of AggreGate Server are implemented using plugins. AggreGate Server supports several types of plugins for communicating with different Devices 113 , adding new contexts 863 to a server context tree, building custom reports, localizing and customizing textual and graphical resources etc.

NEW TERM: A Plugin is a computer program that interacts with a main application (a web browser or an
email program, for example) to provide a certain, usually very specific, function on-demand.

2000-2013 Tibbo Technology Inc.

System Internals

951

All plugins are loaded by the server at startup. They are located in the /plugins subfolder of the AggreGate Server installation folder. To install new plugin, simply copy plugin archive into the corresponding subfolder of /plugins and restart AggreGate Server. When installing new version of existing plugin received from Tibbo, overwrite the old plugin archive with a new one.

Setting Levels
Every plugin has up to two levels of settings: Global Settings. These affect the default behaviour of plugins. Global settings may be edited only by users with sufficient permissions. User-level Settings . These affect the behaviour of a plugin only when its actions are related to a certain user account 108 . Many plugins have global settings only or no settings at all.

Administering Plugins
Two contexts are used to administer plugins: One is the general Drivers/Plugins Configuration 685 context, which serves as a container. The other is the Driver/ Plugin Configuration 686 context, which holds the configuration for one plugin. There are two types of plugin configuration containers: global container for global settings and user's personal container for storing plugins settings related to a certain user account 108 .

Enabling/Disabling Plugins
Individual plugins may be enabled or disabled using Active Plugins
74

server global configuration option.

6.13 Bindings
What's in a name? Bindings are called this way because they bind various data to each other. When you bind something in the real world (such as a package to the roof of a car) you actually tie it tightly. That's the core meaning here -- tying something tightly. With data bindings, you tie data tightly to other data. For example, you can have a textbox in a dialog which is grayed-out. You can't write anything in it. This textbox can have a checkbox next to it, saying something like "Enable this setting?". Once the checkbox is checked, the textbox magically becomes white (enabled) and you can write in it. This is done via data bindings -- the value of the checkbox (Enabled or Disabled) is bound to the state of the textbox (Enabled or Disabled). AggreGate data bindings let you do such nice interface tricks using widgets 312 - this is just one example of their power. Every binding consists of two parts:

reference = expression
If you're not sure what a reference 925 or an expression 911 is, you really should check out the previous two articles. Without a thorough understanding of references and expressions, bindings won't make much sense.

reference defines the binding target. This is where the result of the expression will be written to, once the binding is
processed. depending on the processing environment, reference may refer to a Data Table Interface component etc. See references 925 chapter for more info on references.
854

cell, property of User

expression is an AggreGate expression

is processed.

911

that defines the value to be written to the binding target when the binding

See the following chapters for more info on using bindings: Bindings in Data Tables Bindings in Widgets Bindings in Models
604 860

311

2000-2013 Tibbo Technology Inc.

952

AggreGate Documentation

6.13.1 Server Bindings

The engine of AggreGate widgets 312 and models 303 is constructed of server context bindings. Those bindings define relations between data items (such as variables 869 , functions 878 and events 880 ) of different server contexts 863 . Every binding is evaluated at different points during widget execution or model operation. Evaluation results are used to modify context data. Bindings are generally described in general under Bindings 951 section. Please read that topic and the topics it refers to. Only once you've understood the bindings overview, references and expressions will you easily understand this topic. Every binding has three parts: Binding Activator 954 and Condition 954 , defining WHEN a binding is processed. Processing may occur on widget startup, button click, changes in data model or properties of widget components etc. Binding Expression 953 , defining WHAT is the result of binding processing. A binding expression may refer to different properties of the widget component or to various data from server contexts. It's written in AggreGate Expression Language 911 . Binding Target 952 , defining WHERE to result of evaluation of binding expression will be written, i.e. which property of the GUI component or what context data will be changed. It is a Reference 925 .

6.13.1.1 Binding Target

Binding target is an object affected by the binding. The binding target points to a context variable, field of a variable, context function, or context event. In fact, the binding target is a special type of reference There are several supported types of binding targets:
925 .

1. Server Context Variable

context:variable
This binding target points to the value of a context variable. Since a variable is always a Data Table 854 , the binding expression must resolve to a Data Table in order to allow bindings processor to use this table as new value of variable. Example: users.admin:childInfo$firstname This binging target will modify the firstname field of the childInfo variable for users.admin.

2. Field of Server Context Variable

context:variable$field
This binding target points to a specific field within a server context variable.

3. Context Function
context:function()
This type of target points to the function of a context . When a binding with such target is processed, that function is called. The binding expression should return a Data Table 854 that will be used as the function input.

4. Context Event
context:event@
This target type causes the binding to fire an event of type event in context . The binding expression should return a Data Table those value will be treated as event data 881 . This binding target will have effect only if the binding is running inside AggreGate Server (e.g. in a model 303 ). If the binding is running remotely (e.g. in a widget 312 running inside AggreGate Client), this target will generate a "local" event that will be received by the listeners inside the same AggreGate Client installation. This event will not be forwarded to the AggreGate Server and other clients.

2000-2013 Tibbo Technology Inc.

System Internals

953

5. Context Action
action/context:action
This target starts interactive execution of action action from context context . Binding evaluation result is passed to the action as an input value. It should have Data Table 854 type. Action execution is not available inside widget bindings (outside of AggreGate Client).
604

if the widget is running as a standalone application

Example: action/cardholders:import Starts cardholders import action (Cardholders module is a part of Time and Attendance and Access Control solutions), that is an action named import in context with path cardholders.

LAUNCHING RELATIVE WIDGETS, REPORTS AND DASHBOARDS

Widgets 312 , reports 241 , dashboards 617 and several other system objects can be absolute and relative. While an absolute object is launched per se, relative objects are started for a certain context 863 that serves as a data source. Thus, launching relative widget, report or dashboard via binding target directly won't let the system know what context should it be started for when a binding is executed. Instead, object's launch action located in the target context should be specified in binding target. Example: Assuming there is a Traffic Chart relative widget that is valid for all network devices open traffic chart of a certain device using binding activator. To do that: Find the source device in the binding target editor Choose Traffic Chart in the action selector
113 .

You can

6. Empty Target
If binding target is empty string, the binding will just discard value returned by Expression . However, such binding may still be usable, since expression will still be evaluated and it may have useful side effects (i.e. can perform function calls that do some stuff).

6.13.1.2 Binding Expression

The binding expression is written in AggreGate Expression Language will be resolved when the expression is evaluated. Binding Expression Resolution Environment Default Context
927 911 .

This means it may include references

925

which

922

Default Context
927

315

for a widget.
317

Default Data Table Default Row

927

Widget input parameters 0

930

table.

Environment Variables

Standard

931

variables only.
880 ,

If the binding was activated by an event environment: Variable Name context event level time acknowledgements enrichments Value Type String String Integer Date Data Table Data Table

the following event properties can also be accessed v

Description Full path to the event's context. Name of the event. Event level
882 .

Event timestamp. Event acknowledgements table Event enrichments table

883 . 883 .

2000-2013 Tibbo Technology Inc.

954

AggreGate Documentation

value

Data Table

Data Table

854

containing event-specific data.

References
Binding expressions in context bindings may include references and their fields or properties.
925

that point to context

322

variables

869 ,

functions

878 ,

More information about standard reference format and resolving algorithm may be found in the Standard References section.

926

Server Binding Expression Example

"User: " + {users.admin:childInfo$firstname}
This expression includes a reference (enclosed in curly brackets), and evaluates to a string which results from concatenating the "User: " string literal and the string which is contained within the firstname field in the childInfo variable of the admin user's context (the path of this context is users.admin). If the Administrator's first name is Charlie, this expression will evaluate to User: Charlie.

6.13.1.3 Binding Activator

A binding activator is a special reference 925 that points to a server context variable, a server context event, a field of server context variable. A change of the above variable or an occurrence of the above event force this binding's processing. Here is a list of supported activator syntax variations:

1. Server context variable

context:variable
This activator will trigger a binging once the variable named variable of the server context named context is changed. Example: users.admin.devices.dev1:voltage This activator will run upon the change of voltage property in server-side users.admin.devices.dev1 context.

2. Server context event

context:event@
This activator will trigger a binging once event named event will occur in server context named context. Example: users.admin.devices.access_control_terminal:cardRead This activator will run upon the occurrence of cardRead event in users.admin.devices. access_control_terminal context.

6.13.1.4 Binding Condition

The binding condition is written in AggreGate Expression Language this expression results to false, binding execution will be skipped. Binding Expression Resolution Environment Default Context
927 911 .

It's evaluated first when a binding is activated. If

922

Default Context

315

for a widget.
317

Default Data Table

927

Widget input parameters

table.

Default Row

927

2000-2013 Tibbo Technology Inc.

System Internals

955

Environment Variables 930

Standard

931

variables only.
880 ,

If the binding was activated by an event environment: Variable Name context event level time acknowledgements enrichments value Value Type String String Integer Date Data Table Data Table Data Table

the following event properties can also be accessed via

Description Full path to the event's context. Name of the event. Event level
882 .

Event timestamp. Event acknowledgements table Event enrichments table Data Table
854 883 . 883 .

containing event-specific data.

References
Binding conditions may include the same types of references as binding expressions
954 .

6.14 Window Location

Window Location settings allows to specify where a window is located in the user interface. Window location comprises the following information: Dashboard name and description Dock state (Docked, Floating, Side Bar Icon, Side Bar) Dock side (Top, Left, Bottom, Right) Dock index Width and height Position control flags System operators can move/dock/resize windows and their state/location is stored within the AggreGate Client workspace. Thus, if a certain window is opening for the second time, it will in most cases preserve the previous location parameters.

Dashboard
If Dashboard Name and Dashboard Description parameters are specified, window will be located in a non-default dashboard 617 . Dashboards are used to group multiple windows together. If dashboard with a given name does not exist, it will be created.

State, Side and Index

Combination of State, Side and Index parameters specify window location within the dashboard. The following table shows how do these parameters work together for a dockable dashboard State Docked Side Bar Floating Side Index Comments Frames with same mode, same side, and same index will form a single tabbed pane. Frames with same side and same index will form a group on the side bar. Frames with same mode and same index will form a tabbed pane and lie in the same floating window.
618 :

Top, Left, Bottom, Any integer Right greater than 0 Top, Left, Bottom, Any integer Right greater than 0 N/A
618 ,

Any integer greater than 0

For a scrollable dashboard

State and Side parameters are ignored, while Index parameter defines the zero-based

2000-2013 Tibbo Technology Inc.

956

AggreGate Documentation

index of column to add the window to.

Width and Height

If Width and/or Height are specified, they are processed as follows: If window is docked, the docking window manager does its best to match preferred sizes of all windows. The window will not have exactly the size specified by Width/Height parameters. If window is located in the side bar, it will adhere the Width if put to a left/right size bar, and it will adhere the Height if put to a top/bottom size bar. If window is floating, it will have size specified by Width/Height parameters.

Position Control Flags

Window location includes the following additional position/size control flags: Resizing Allowed Closing Allowed Docking Allowed Floating Allowed Maximizing Allowed Side Bar Docking Allowed

6.15 Parameterization Engine

Parameterization is the process of building a query 271 , an event filter 206 expression or report's source data expression 241 which will prompt the user for various parameters when it is run. Once you've done this process, you get a simple string -- a piece of text you can use as the text for a query or an event filter expression. The source data for parameterization engine has XML format. It defines a number of parameters that must be entered during parameterization process. Normal use is like this: administrators create parameterization source data (XML) and put into a parameterized query or event filter. Users then specify parameters on-the-fly, when executing the query or filter. Here is the generic syntax for the parameterization engine's source data:

<form> <format> <![CDATA[ PARAMETERS_FORMAT ]]> </format> <expression> EXPRESSION_TO_PARAMETERIZE </expression> </form>

Parameters Format
PARAMETERS_FORMAT is the format 855 of the Data Table 854 that will be created and shown to the user in editable mode so he could change its fields. The values of these fields will be then converted to strings and inserted into EXPRESSION_TO_PARAMETERIZE. The data table constructed from PARAMETERS_FORMAT always contains just a single record. This table allows the user to interactively define parameter values which will then be used within EXPRESSION_TO_PARAMETERIZE. PARAMETERS_FORMAT is the Table Format 855 encoded to a string using "visible" characters. More information on encoding can be found in the appendix, under Encoding Data Tables 1306 . The minimum and maximum number of records specified by the Table Format are ignored, because there's just a single record. The PARAMETERS_FORMAT string is nested into a CDATA block. CDATA is an element of XML language which allows

2000-2013 Tibbo Technology Inc.

System Internals
using normal XML markup characters ("<", ">" etc.) without escaping them. This is needed because the PARAMETERS_FORMAT string employs such characters. Here's an example of a PARAMETERS_FORMAT string:

957

<<byusername><B><D=Filter by User Name>> <<username><S><D=User Name>>

This example defines two fields: A boolean field called "byusername" (with a "user-friendly" description, "Filter by User Name") and a string field called "username" ("User Name"). The first parameter may be used, for example, to enable filtering by a specific user in a query 271 , and the second parameter will be name of user. The user will then be prompted to enter these parameters (screenshot made in AggreGate Client):

Here is a much more complex PARAMETERS_FORMAT, which even includes bindings

860 .

<<bydate><B><D=Filter by Date>> <<startdate><D><D= <<enddate><D><D= Start Date>> End Date>>

<<byusername><B><D=Filter by User Name>> <<username><S><D= User Name>>

<<byuserid><B><D=Filter by User ID>> <<userid><S><D= User ID>>

<<bymachine><B><D=Filter by Machine>> <<machine><I><D= Machine Number>>

<<bytype><B><D=Filter by Event Type>> <<type_impact><B><D= <<type_login><B><D= <<type_speed><B><D= <<type_oil><B><D= Show Impact Events>> Show Log On/Off/Auto Events>> Show Speed Events>> Show Oil Warn/Temp Over Events>> Show Maintenance Events>> Show Checklist Events>>

<<type_maintenance><B><D= <<type_checklist><B><D= <B=

<startdate#enabled={bydate}> <enddate#enabled={bydate}> <username#enabled={byusername}> <userid#enabled={byuserid}> <machine#enabled={bymachine}> <type_impact#enabled={bytype}> <type_login#enabled={bytype}> <type_speed#enabled={bytype}> <type_oil#enabled={bytype}> <type_maintenance#enabled={bytype}> <type_checklist#enabled={bytype}>

2000-2013 Tibbo Technology Inc.

958 >

AggreGate Documentation

This format defines many fields and some relations between them that are controlled by bindings ("<B=...>"). For example, the binding "username#enabled={byusername}" makes it so that a user can only fill in the "User Name" ("username") parameter if filtering by user names is enabled (i.e, the "byusername" field is set to TRUE). To learn more about what <B>, <D>, <S>, <I>, <D> etc, see Encoding Data Tables 1306 . When running a filter using this format, the user is prompted to enter parameters using the following dialog (screenshot made in AggreGate Client):

Expression To Parameterize
EXPRESSION_TO_PARAMETERIZE is just the text used to build a query 271 or an AggreGate Expression used by an event filter 206 or a report 241 . This text may contain two special constructs that depend on the values of parameters specified by fields of PARAMETERS_FORMAT. As EXPRESSION_TO_PARAMETERIZE contains XML tags (see below) it cannot be written inside the CDATA block like PARAMETERS_FORMAT. Therefore characters used by XML syntax must be escaped. For example, if & character must appear in the resulting expression, it must be written as &amp; inside the EXPRESSION_TO_PARAMETERIZE.

CONDITIONAL PARAGRAPHS
A conditional paragraph defines a block of text that will be inserted into the parameterized expression only if the expression defined in its header is TRUE. This expression may contain references to various fields within PARAMETERS_FORMAT. Syntax:

<p

enabled="ENABLING_CONDITION_EXPRESSION">TEXT_OF_CONDITIONAL_PARAGRAPH</p>

ENABLING_CONDITION_EXPRESSION is an AggreGate expression 911 that may contain references to the cells of the Data Table built from PARAMETERS_FORMAT. Format of references is {FIELD_NAME} where FIELD_NAME is the name of the field defined by PARAMETERS_FORMAT. More information about references can be found here 925 . Example ENABLING_CONDITION_EXPRESSION:

{filterByName} && {filterByValue}

With this ENABLING_CONDITION_EXPRESSION, the text of conditional paragraph will be inserted to the parameterized expression only if the values of two Boolean fields filterByName and filterByValue are TRUE. These fields must be defined in PARAMETERS_FORMAT. Example of EXPRESSION_TO_PARAMETERIZE with a conditional paragraph:

SELECT * FROM users.*:childInfo <p enabled="{showOnlyUsersWithPhones}">WHERE childInfo$phone IS NOT NULL</p>

2000-2013 Tibbo Technology Inc.

System Internals

959

In this example, childInfo$phone refers to the "phone number" field within a user information record (You can learn more about this under Queries 271 .) ENABLING_CONDITION_EXPRESSION refers to the Boolean field showOnlyUsersWithPhones defined in PARAMETERS_FORMAT (for example, like this: " <<showOnlyUsersWithPhones><B><D=Show only users that have phone numbers>>"). If this field is set to FALSE by the user during parameterization process, the resulting parameterized expression will be "SELECT * FROM users.*:childInfo". If the field is set to TRUE, the resulting expression will be "SELECT * FROM users. *:childInfo WHERE childInfo$phone IS NOT NULL", i.e. TEXT_OF_CONDITIONAL_PARAGRAPH is included in the result. The conditional paragraph doesn't necessarily have to be at the end of the query/filter string. In the following example, it's in the middle of the expression (right before the ORDER BY clause):

SELECT * FROM users.*:childInfo <p enabled="{showOnlyUsersWithPhones}">WHERE childInfo$phone IS NOT NULL</p> ORDER BY childInfo$name DESC
EXPRESSIONS

As covered above, Expression_to_parameterize is just a string. It's not an AggreGate Expression in itself. However, it may include AggreGate Expressions. Such AggreGate expressions may contain references to the cells of the Data Table built from PARAMETERS_FORMAT. The expression is evaluated, and the result of the evaluation is converted to a string and inserted into the final parameterization result (the AggreGate query or filter expression which is the product of the parameterization process). Syntax:

<e>EXPRESSION</e>
This expression may contain references to the cells of Data Table built from PARAMETERS_FORMAT, exactly like ENABLING_CONDITION_EXPRESSION of conditional paragraph (see above). Example:

SELECT * FROM users.*:childInfo WHERE childInfo$phone = '<e>{phone}</e>'

The ' marks above are necessary - they're used to escape the SQL string literal. This example assumes a "phone" field exists in PARAMETERS_FORMAT. For example, if a user has entered phone "123-45-67" during the parameterization process, the result of parameterization will be "SELECT * FROM users.*:childInfo WHERE childInfo$phone = '123-45-67'".

THE DIFFERENCE
1) Conditional paragraphs let you add/remove various pieces of your final expression based on a yes/no (Boolean) result of some expression. 2) Expressions let you insert specific values, deriving from their evaluation, into your final parameterization result.

Parameterization Process Flow

1. Parameterization data is parsed and validated. 2. The user is prompted to enter the parameters specified by PARAMETERS_FORMAT. 3. The resulting Data Table with parameters filled by the operator is preserved and made available for use, for example as a default table for additional report parameter values calculation 245 . 4. EXPRESSION_TO_PARAMETERIZE is now modified, using parameters from step (2): text of conditional paragraphs is inserted or removed, expressions are evaluated and the evaluation result is inserted into the final string. 5. The resulting final string is used as the query or filter expression.

6.16 Enabling Serial Communications

Java Virtual Machine that runs AggreGate Server needs a special Java Communication API driver to be able to communicate with Serial devices (RS-232, RS-482, etc.). This driver is automatically installed by the AggreGate Server Installer for Microsoft Windows operating system. For other operating systems, the Java Communication API driver has to be manually installed to get access to Serial devices. If the Java Commmunication API driver is not properly installed, Serial device's Connection Settings will not contain the list of serial ports available in the system. To install the Java Communication API for your operating system, follow these instructions:

2000-2013 Tibbo Technology Inc.

960

AggreGate Documentation

1. Download the Java Communication API for your operating system from Sun Java website. At the time of this writing, it is available at http://java.sun.com/products/javacomm/. 2. Follow the instructions contained in driver distribution package. By default, the Java Virtual Machine that executes AggreGate Server is located in the /jre subdirectory of AggreGate Server installation.

Linux Note
If your server is installed on Linux machine, only ports that follow the standard naming conventions (/dev/ttyS*) will be visible in AggreGate. If your port has the name that doesn't satisfy this, create a symbolic link for it:

# ln -s /dev/tty200 /dev/ttyS200 # updatedb

Don't forget to restart the server after creating the synlink.

7 Development and Integration

This chapter covers integration of the AggreGate into the enterprise infrastructure and its intercommunication with the third-party applications.

7.1 AggreGate SDK

The open-source AggreGate Software Development Kit (SDK) provides the ability to extend AggreGate Platform and integrate it with the other enterprise systems. AggreGate SDK is a set of open-source modules that provide compatibility with different operating systems. The modules are implemented in Java programming language. There are two different version of AggreGate Java SDK available: AggreGate Java SDK for Java SE AggreGate Java SDK for Android (Dalvik JVM) AggreGate SDK includes the following components: AggreGate Server Application Programming Interface (API) 961 for managing AggreGate Server and connected hardware from the other applications via secure network connection AggreGate Server Driver Development Kit (DDK) custom Device Drivers 129 AggreGate Server Plugin SDK modules Agent SDK
972 969 963

for connecting new hardware devices to the system using

for extending AggreGate Server with new data processing and presentation
848

for implementing Agents

running on PC-based controllers

Driver vs Agent We're often asked what is the difference between Device Driver brief explanation:
129

and Java-based Agent

848 ,

so here is the

Device Driver's Java code is a part of AggreGate Server, it is executed inside servers Java Virtual Machine (JVM). Agent is a standalone Java application that runs on a separate PC. Device Driver uses native protocol (usually based on IP or serial communications) to interact with devices, while Agents communicate with AggreGate Server using AggreGate Protocol 1303 .

AggreGate SDK Distribution Package

The AggreGate SDK is available as a ZIP archive that contains: Source code (/src folder) Examples (/src/examples folder) Unit tests (/test folder) Functional tests (/test folder)

2000-2013 Tibbo Technology Inc.

Development and Integration

Javadocs ( /docs folder) Pre-built Java Archive (JAR) with SDK classes (aggregate-api.jar) Necessary third-party libraries (aggregate-api-libs.jar)

961

Using AggreGate SDK

To use the AggreGate SDK, you have to add the following java archives (JARs) to the classpath of your Java application: aggregate-api.jar aggregate-api-libs.jar The first archive contains AggreGate-specific code, while the second one contains the third-party libraries used by the SDK.

JAVADOCS AND SOURCES

This section of the manual provides only top-level functional documentation and step-by-step guides for using different aspects of AggreGate SDK. For detailed information on specific classes and interfaces included in the SDK refer to: Javadocs located in the /docs folder of SDK distribution package Source code located in the /src folder of SDK distribution package

7.1.1 AggreGate Server API

The AggreGate Server open-source Application Programming Interface for Java (AggreGate Server Java API) lets you control, configure and monitor AggreGate Server and all hardware devices that are working within a single AggreGate installation remotely from any application written in the Java programming language. Using this API, you can: Access server resources and connected devices; Modify server and device configuration; Execute server and device operations; Acquire server and device events; Technically, the Java API provides the following functionality: Full access to the server contexts
863

through a so-called proxy context tree;

863

Getting and setting values of context Calling context functions

878 ; 880 ;

variables

869 ;

Listening for context events

Creating and manipulating Data Tables Executing context actions

892

854 ;

All communications with AggreGate Server are performed over IP, through a single SSL-secured TCP connection using AggreGate Communications Protocol 1303 .

Using AggreGate Server API

This section provides step-by-step instructions for establishing connection with a remote AggreGate Server from a Java application.

CREATING SERVER CONNECTION

Start with creating a RemoteServer object:

RemoteServer rls = new RemoteServer("localhost", RemoteServer.DEFAULT_PORT, "admin", "admin");

You need to specify the following parameters in RemoteServer's constructor: IP address of host name of remote AggreGate Server Port number to connect to (6460 by default)

2000-2013 Tibbo Technology Inc.

962

AggreGate Documentation
108

Name of user account

to use for authentication (username)

Password for the user account Next, create a RemoteServerController. It will be used for managing server connection:

RemoteServerController rlc = new RemoteServerController(rls, true);

Establish a connection with the server by calling connect() method:

rlc.connect();
Connection will fail if: Server is not running; Server remote API is disabled; Address/port are not correct; Versions of AggreGate Server and API libraries are not compatible. At this point, your application has established TCP connection, completed SSL handshake and exchanged basic information 1304 with the AggreGate Server. To perform some valuable operations, you need to authorize on the server to obtain a certain permission level. This is carried out by calling login() method of the server controller:

rlc.login();
The call will fail if login/password specified in the RemoteServer constructor are incorrect.

ACCESSING CONTEXT MANAGER

Now it's possible to get an instance of ContextManager from the controller. This is proxy context tree those structure and operation mimics remote AggreGate Server's context tree:

ContextManager cm = rlc.getContextManager();
WORKING WITH CONTEXTS
All further essential AggreGate Server data management operations are performed by calling variable/function/eventrelated methods of different proxy contexts provided by proxy context manager. See Working With Contexts
986

for details.

DISCONNECTING FROM SERVER

Call disconnect() method of the AggreGate Server controller to close the connection.

Related Examples
Example Description This simple example illustrates how to connect to a AggreGate Server remotely using AggreGate Server API and get version of the server. This example shows how to: List available user accounts
108

/src/examples/api/ GetServerVersion. java /src/examples/api/ ManageUsers.java

and view their information

Create, update and delete user accounts

/src/examples/api/ ManageDevices.java

This example illustrates: Listing available Device accounts

113

and viewing/modifying their properties

Creating and destroying Device accounts Viewing Device status and awaiting while Device comes into a certain state Listing, reading and writing Device settings Executing Device operations Receiving and processing Device events

/src/examples/api/ ExecuteAction.java

This is an advanced example that shows how to execute a server action simulating input of a human operator.

892

by

2000-2013 Tibbo Technology Inc.

Development and Integration

963

7.1.2 Error Reporting

The easiest way of reporting any message or error from inside an AggreGate driver or plugin is using a standard logging facility 74 . AggreGate uses Log4j library for logging. Logging a messages requires just one line of Java code:

Logger.getLogger("ag.core").info("A
or

message");

Logger.getLogger("ag.device.acme").error("Unexpected

error",

exception);

The Log4j library documentation offers comprehensive documentation for all aspects of logging configuration and implementation. The Log class provides pre-defined loggers for common AggreGate logging categories. Here is a usage example:

Log.CORE.info("A message");

Error Reporting Via AggreGate Events

Messages and errors reported through the logging facility are not visible to system operators. Only system administrators having access to machine running AggreGate Server or AggreGate Client will be able to check the log files. Redirecting logging output to other destinations will still hardly make it available to the operators. To make any message or problem visible to one or more system operators, report it by firing an AggreGate event Info 885 type:
880

or

Retrieve an instance of a relevant Context via ContextManager.get(). This could be a device context 677 (if reporting an issue from a driver), an administration context 652 (if reporting a system-wide issue, such as a plugin startup problem), or any other AggreGate Server context. Call Context.fireEvent() to generate a new context event. The event will be stored in the server database 80 and routed to subscribed listeners (e.g. Event Logs 791 ), making it accessible by system operators and administrators. The below example illustrates how to report an internal recoverable error from a device driver: Context deviceContext = getDeviceContext(); "Something happened inside the driver");

deviceContext.fireEvent(AbstractContext.E_INFO,

7.1.3 Driver Development Kit (DDK)

AggreGate Server Driver Development Kit (DDK) is a part of AggreGate SDK that allows to implement custom AggreGate Server Device Drivers 129 in Java programming language. AggreGate Server Device Driver is a special type of AggreGate Server plugin mandatory components:
950 .

Technically, the driver has two

Driver Java class that implements DeviceDriver interface. Most implementations extend AbstractDeviceDriver class to avoid implementing irrelevant methods and preserve their default functionality. Driver plugin descriptor
971

that defines driver plugin properties and its place in AggreGate Server plugins hierarchy.

Device Server SDK bundle includes an open-source example of AggreGate Server Device Driver implementation called Demo Device Driver. It is located in examples.driver package and comprises three files: DemoDeviceDriver.java - source code of the driver plugin.xml - driver plugin descriptor build.xml - Ant build file with a single task building driver's JAR archive To try the driver:

Run build.xml using Ant to build demo.jar

Copy demo.jar to %AggreGate Server Installation Folder/plugins/device when AggreGate Server is not running Start AggreGate Server Create new Device account and specify Demo Device as driver type

2000-2013 Tibbo Technology Inc.

964

AggreGate Documentation

Modifying Plugin Descriptor

To create a plugin descriptor it:
971

for your driver, make a copy of demo driver's plugin.xml file and edit the following in

Change the last word in id attribute of the <plugin> tag to the ID of new plugin. The ID should contain only lowecase letters, digits and underscores. For example, if your desired plugin ID is xyz, set ID attribute to com. tibbo.linkserver.plugin.device.xyz. Change class attribute of <plugin> tag to full name of driver's java class. Enter driver description in the body <doc-text> tag. Change id attribute of the <extension> tag to the new plugin ID.

Building and Deploying Plugin Archive

Make a copy of demo driver's Ant build file (build.xml) Change project name and name of destination file (plugin archive) Run built.xml using Ant to build plugin Java archive Copy the JAR file to %AggreGate Server Installation Folder/plugins/device when AggreGate Server is not running Start AggreGate Server Create new Device account and select new driver as driver type

Device Driver Instance Creation

Developers of device drivers should be aware of the policy used by AggreGate Server to create driver objects, i.e. instances of Java class inherited from AbstractDeviceDriver: One instance of driver class is created during server startup. This instance is responsible for plugin's global and peruser initialization/deinitialization. Thus, server calls the following methods of this instance: globalInit(), globalDeinit(), globalStart(), globalStop(). It also calls several methods once per every user 108 account in the system: userInit(), userDeinit(). One instance of driver class is created for every device account 113 that uses this type of driver. This instance performs the actual communications with the hardware or data source and interacts with a certain DeviceContext. Also, instances of driver class may be created during the new device creation action (at device connection properties specification stage). The only method that will be called from those instances is createConnectionPropertiesFormat().

7.1.3.1 Implementing a Driver

To create a new device driver from scratch, create a new Java class inherited from AbstractDeviceDriver. You will need to override at least some of the methods to provide driver functionality.

Global and Per-account Configuration

Certain plugins may have global and per-user
108 -account

configuration settings

130 .

To add global and per-user settings, implement globalInit() and userInit() methods respectively. Their implementations should call createGlobalConfigContext() and createUserConfigContext() and provide VariableDefinition's of global and per-user settings. These settings will be exposed to system administrators, their values get persisted in the database. The variables must belong to "default" group, available as ContextUtils. GROUP_DEFAULT constant. To access setting values from any method of the plugin, retrieve global or per-user config contexts using getGlobalConfigContext() or getUserConfigContext(), then call Context.getVariable() to fetch instances of DataTable representing setting values.

Setting Up Device Context

2000-2013 Tibbo Technology Inc.

Development and Integration

965

AggreGate Server calls the setupDeviceContext() method of the driver when a new device account is created or the server is started. The method receives an instance of DeviceContext interface that is a Device Context 677 representing this device account. Call super.setupDeviceContext() to store its reference inside AbstractDeviceDriver. It will be available via getDeviceContext() method. The main purpose of setupDeviceContext() is adding device-specific communication settings. They are added in the form of context variables belonging to ContextUtils.GROUP_ACCESS variable group. System operator is prompted to edit these settings upon device account creation, and they can be later accessed using Edit Device Properties 677 action. Communication setting variables should be added to device context using Context.addVariableDefinition() method. The actual user-specified values can be later fetched from DeviceContext using Context.getVariable(), e.g. from DeviceDriver.startSynchronization() or DeviceDriver.connect().

Starting and Finishing Synchronization

Device driver has two methods that are called in the beginning and in the end of synchronization respectively: startSynchronization() and endSynchronization(). These methods may be used to initialize and clear some driver's internal caches or other data structures.

Handling Connections and Disconnections

DeviceDriver.connect() method should establish a connection with the hardware device. It usually uses
communication settings described in Setting Up Device Context (see above). In most cases, connection includes several steps: Fetch device communication properties by calling getDeviceContext.getVariable(). Use getDeviceContext().getCallerController() as a caller controller in these calls to ensure proper permission level. Bringing up a link (opening TCP socket, serial port, etc.) Sending authentication/authorization credentials to the device and processing its reply Switching the device to "configuration mode", if applicable The connect() method should throw an exception if connection has failed at any phase. Otherwise, if should call super.connect() method of AbstractDeviceDriver in the end of method body to mark device as connected. AbstractDeviceDriver will then provide a correct result of isConnected() method.

DeviceDriver.disconnect() should correctly shutdown the link to hardware. It's called on server shutdown,
account removal, or when reconnection to the device is requested by the system. To force reconnection during driver testing/debugging, use Reset Device Driver
678

action.

Reading Device Metadata

There are three methods that are called by the AggreGate Server core during full synchronization
126 :

readVariableDefinitions() that should examine available device settings (or communication properties if the device protocol does not support self-documentation) and create a VariableDefinition object for every available device setting. depending on the communication protocol, device settings may be also called I/O channels, tags , configuration items , etc. See variable definition 870 for details. readFunctionDefinitions() that should provide one FunctionDefinition object per every operation provided by the hardware. In different communication standards, device operations may be also called device methods, functions, actions, procedures, etc. See function definition 878 for details. readEventDefinitions() that provides one EventDefinition object for every type of event that can be generated by hardware. In some device protocols, events may be also called messages, notifications, etc. See event definition 880 for details. Definitions of variables, functions and events provided by the driver are added to the Device context and cached The driver may not be asked to re-read them until the next full synchronization even if the server was restarted. To force re-reading of device metadata during driver testing/debugging, use Reset Device Driver
678 115 .

action.

2000-2013 Tibbo Technology Inc.

966

AggreGate Documentation

Reading/Writing Device Settings

If the driver has provided a non-empty list of device settings from readVariableDefinitions() method, server core will call readVariableValue() and writeVariableValue() methods of the driver. readVariableValue () should read up-to-date setting value from the hardware and convert it to the form of DataTable matching format defined in its VariableDefinition. On the contrary, writeVariableDefinition() takes value encoded as a DataTable, converts it to the device native format and writes to the hardware. Setting is being read from the hardware: During first synchronization, and During any other synchronization if there are no server-side changes of its value Setting is being written to the hardware during synchronization if it's writable according to the definition and there were some server-side changes of its value. Setting values will be cached inside the Device context. The driver may not be asked to re-read them until the next full synchronization even if the server was restarted. To force re-reading of device settings during driver testing/debugging, use Synchronize
678

action.

Executing Device Operations

If the driver has provided a non-empty list of device settings from readFuncitonDefinitions() method, AggreGate Server will add a Call Function 903 action per every device operation. Being executed by system operator, this action prompts to specify input data (according to function input format, and only if it's not "empty"), then calls executeFunction() method of device driver and shows its output to the operator (also only if it's not "empty"). Thus, driver-specific implementation of executeFunction() method should basically: Convert input Data Table to the device native format Send input data to the hardware Trigger device-side operation Read operation output from the device Convert device-side output to the Data Table and return it

Working With Device Events

When dealing with events, device driver: Returns the list of event definitions from readEventDefinitions() method. The list should include every type of event that may be produced by the hardware. Asynchronously calls DeviceContext.fireEvent() method when new event instance is received from the hardware. Device driver can start firing context events only after the end of first synchronization, i.e. after its finishSynchronization() method was called at least once. When firing an event, the driver must ensure that format of event's Data Table containing event-specific data matches format stored in corresponding Event Definition. Any event provided by device driver is persistent. It will be stored in event history 116 is defined for it.
882

if non-zero history storage time

Advanced Features
See javadocs of DeviceDriver, DeviceContext and parent interfaces for description of all their methods.

2000-2013 Tibbo Technology Inc.

Development and Integration

967

7.1.3.2 Working with Device Assets

Some device drivers support assets Some examples of asset usage: JMX device driver returns one asset per every MBean class. Each asset has one sub-asset per MBean instance. OPC device driver provides asset tree that matches hierarchy of OPC server branches. BACnet device driver provides an asset for every BACnet object type. Each asset has one sub-asset for every BACnet object instance. Similarly, WMI device driver creates an asset for every WMI object type.
113

to provide a hierarchical logical grouping of settings, operations and events.

Implementing Asset Support in Driver

Drivers that support assets must return TRUE from isUsesAssets() method. If certain driver declares asset support, AggreGate Server core calls its readAssetDefinitions() method right after establishing or confirming device connection. This method should return a list of DeviceAssetDefinition objects. Each asset definition has a unique ID, human-readable description, and a list of nested definitions (sub-assets). AggreGate Server reads asset definitions from the driver just once at the device creation stage and caches them the database. To force server to re-read asset definitions from the driver, use Reset Device Driver 678 operation. Every asset may be enabled/disabled by system operators using Edit Device Properties
677

action.

If driver supports assets, AggreGate Server calls the following methods to obtain device metadata:

readVariableDefinitions(List<DeviceAssetDefinition>) readFunctionDefinitions(List<DeviceAssetDefinition>) readEventDefinitions(List<DeviceAssetDefinition>)

The driver must return only definitions that belong to enabled assets (i.e. DeviceAssetDefinition. isEnabled() returns true). Definitions of settings, operations and events that belong to disabled assets won't be available within AggreGate.

7.1.3.3 Synchronization Sequence

This section describes the sequence of calls to different DeviceDriver methods by the server core during synchronization 126 of the device with the server. 1. If device is suspended
124 ,

synchronization is skipped.
124

2. If device dependency expression connection status.

evaluates to false, synchronization is skipped and device switches to Offline

3. Driver's should shouldSynchronize() method is called. If it returns false (e.g. if device communication settings were not yet defined), synchronization is skipped. 4. If extended status
124

is enabled, device's synchronization status

128

switches to Connecting.

5. If isUsesConnections() method of the driver returns true: 5.1. If isConnected() returns false or system core requests reconnection to the hardware (e.g. because previous sync has failed and Interrupt Synchronization On Error 124 is enabled), the system calls disconnect() (only if isConnected() is true) and then connect(). 5.2. If connect() doesn't throw an exception, device switches to Online connection status. 6. Certain synchronization tasks called "connect-only" tasks may end at this point. 7. If extended status
124

is enabled, device's synchronization status

128

switches to Reading Metadata.

8. startSynchronization() is called. 9. If synchronization parameters request metadata reading (i.e. "full" synchronization is performed): 9.1. If driver supports groups (i.e. isUsesGroups() returns true) and groups has not yet been read from device (or driver was reset), readGroupDefinitions() method is called. 9.2. readVariableDefinitions() is called, new and changed definitions are added to the device context and

2000-2013 Tibbo Technology Inc.

968

AggreGate Documentation

cached in database. If driver supports groups, readVariableDefinitions(List<GroupDefinition>) method is called instead. 9.3. If synchronization settings 115 of some newly added variable definitions have custom synchronization period, persetting synchronization tasks are scheduled. 9.4. readFunctionDefinitions() is called, new and changed definitions are added to the device context and cached. If driver supports groups, readFunctionDefinitions(List<GroupDefinition>) method is called instead. 9.5. Corresponding Call Function
903

action is added to device context for every new function definition.

9.6. readEventDefinitions() is called, new and changed definitions are added to the device context and cached. If driver supports groups, readEventDefinitions(List<GroupDefinition>) method is called instead. 9.7. If any of the above read methods throw a DisconnectionException, the error is logged, device switches to Offline connection status, driver's disconnect() method is called, and synchronization is terminated. 10. If extended status
124

is enabled, device's synchronization status

128

switches to Synchronizing Settings.

11. All device settings (or settings specified in the synchronization parameters) are synchronized with the server. Synchronization algorithm depends on the setting's synchronization mode 115 . Server may call the following driver's methods at that point: 11.1. getVariableModificationTime() to get device-side modification timestamp for a setting. If modification timestamps are not supported by the hardware, this method should return null. In this case server will write setting value to the device if it was modified in the server cache and read it from the device otherwise. 11.2. readVariableValue() to read device-side value of a setting. 11.3. writeVariableValue() to write server-side value to the device. 11.4. updateVariableModificationTime() to store new modification timestamp in the device. 11.5. If any of the above methods throw a DisconnectionException, it is logged, device goes to Offline connection state, driver's disconnect() method is called, and synchronization is terminated. 11.6. If any of the above methods throw some other exception, it is logged, setting synchronization status Error, and synchronization is terminated if Interrupt Synchronization On Error 124 is enabled. 12. finishSynchronization() is called. 13. Device online and synchronization statuses are reevaluated.
117

is set to

7.1.3.4 Handling Asynchronous Variable Updates

Some communication protocols allow devices to asynchronously inform the server about variable value updates. This often happens in two cases: If a communication protocol is optimized to avoid polling through low-speed, low-bandwidth or unreliable connections If a device runs real-time operating system (RTOS) and the communication protocol allows it to send values updates at fixed rate If a driver is internally designed to receive asynchronous value updates, it should perform the following actions if such an update is received: Create a new DataTable representing variable value and fill it with data Call DeviceContext.asyncVariableUpdate(String

variable, DataTable value)

AggreGate Server will process new value, save it to the history, and deliver to update listeners once asyncVariableUpdate() is called.

7.1.3.5 Managing Incoming Device Connections

AggreGate Server normally establishes outgoing TCP/UDP connections to networked devices, authenticating itself with credentials contained inside the device account. However, certain devices connect to server themselves. These are mostly M2M devices connected to IP network via GPRS/3G modems. Such devices do not have static IP addresses and host names and, thus, cannot be accessed by a server. Device drivers servicing incoming device connections require special design approach: 1. The globalInit() method of a device driver should call createGlobalConfigContext(Context rootContext, VariableDefinition... properties) method. Its parameters should include definition of

2000-2013 Tibbo Technology Inc.

Development and Integration

969

variable that contains global connection settings of the driver, i.e. at least port number to listen for incoming device connections. 2. globalStart() method of the driver should open a listening socket and start a separate thread that accepts and services incoming device connections. This method can access global configuration properties of the driver by getting global properties context via getGlobalConfigContext() and retrieving value of global configuration variable from this context. It's possible (hence not necessary) to create a class inherited from SocketServerThread (for normal sockets) or SslSocketServerThread (for SSL-secured sockets) and use this class as a listening socket thread. 3. The aforementioned server socket thread should be interrupted from globalStop() method of the driver. 4. The server socket thread should accept incoming connections and create a new thread (connection controller thread) to service each connection. For example, a non-abstract implementation of SocketServerThread or SslSocketServerThread should include createConnectionThread() method that creates an incoming connection controller thread each time a new device connects to the server. 5. Each device account should in most cases define some unique device ID (such as mobile device's IMEI code) and device password used to authenticate and authorize incoming device connections. A variable containing this information should be added to device account by implementation of setupDeviceContext() method. 6. The connection controller thread should first authenticate and authorize the device by using device's native protocol to retrieve the unique device ID, finding a device account that matches this ID, and checking that device password matches password specified in the device account settings. 7. Once the device is authenticated and matching server-side device account (context) is identified, the device controller thread should: 7.1. Get per-device instance of driver/plugin class by calling deviceContext.getDriver(). 7.2. Register current device controller inside the driver instance to establish temporary relationship between the device account/driver and current incoming connection operated by controller. 7.3. Call deviceContext.requestSynchronization() to order a normal synchronization sequence
967 .

8. All "classic" methods of the driver should perform device I/O through the instance of device controller registered by the incoming connection controller thread. However, incoming connections add several peculiarities to this process: 8.1. shouldSynchronize() method of the driver should return true if an incoming connection controller is currently registered within the driver instance and false otherwise. 8.2. connect() method of the driver should send some test commands to the device to make sure that the incoming connection is still alive. If the TCP/UDP connection is dead or device didn't reply, the connect method should throw an exception to prevent further synchronization. 8.3. disconnect() method of the driver should shutdown incoming connection controller and close its incoming connection if it's alive.

7.1.4 Plugin SDK

AggreGate Platform has a rich set of build in data processing tools, such as alerts 216 , event filters 206 , widgets 312 , or trackers 257 . AggreGate Plugin SDK is designed for creating customized instances of existing tools (e.g. building widgets on-the-fly based on current state of the system) and creating completely new tools (e.g. Access Policies for the physical access control industry). These tools are added to the AggreGate Server core in the form of plugins 950 . Use scripts
628

instead of new AggreGate Server plugins to solve simple data processing tasks.

Technically speaking, AggreGate Server plugin can: Add new contexts

863

to the AggreGate Server context tree.

880

Add new variables 869 , functions 878 , events may be implemented by custom code.

and actions

892

to existing contexts. The functionality of these objects

Start any asynchronous code (listening server sockets, threads, etc.) that interacts with existing or custom contexts by changing values of their variables, executing their functions, or generating events in them. Some examples of AggreGate Server plugins: Asset Management plugin that creates a number of common tables associates them with the hardware devices
260

containing asset-specific information and

2000-2013 Tibbo Technology Inc.

970

AggreGate Documentation

Syslog Server plugin that receives messages from the servers via network and converts them to AggreGate events for storage and future processing Industrial I/O plugin that generates widgets for monitoring status of programmable controllers Device Server SDK bundle includes an open-source example of AggreGate Server Plugin implementation called Demo Plugin . It is located in examples.plugin package and comprises three files: DemoServerPlugin.java - source code of the plugin plugin.xml - plugin descriptor build.xml - Ant build file with a single task building plugin's JAR archive To try the plugin:

Run build.xml using Ant to build demo.jar Copy demo.jar to %AggreGate Server Installation Folder/plugins/context when
AggreGate Server is not running

Start AggreGate Server

Structure of AggreGate Server Plugin

AggreGate Server plugin has two mandatory components: Plugin Java class that implements ContextPlugin interface. Most implementations extend AbstractContextPlugin class to avoid implementing irrelevant methods and preserve their default functionality. Plugin descriptor
971

that defines plugin properties and its place in AggreGate Server's plugin hierarchy.

These components must be packed in the Java Archive (JAR). Plugin descriptor (plugin.xml) must be located in the root folder of the archive.

Implementing New AggreGate Server Plugin

To create new AggreGate Server plugin from scratch, create new Java class inherited from AbstractContextPlugin. You will need to override at least some of the methods to provide plugin functionality. To suppress permission checking and ensure full access to all server contexts, pass an instance of UncheckedCallerController to all calls that accept arguments of CallerController type.

GLOBAL CONFIGURATION
Certain plugins may have global configuration settings. To add global implement globalInit() method. Its implementations should call createGlobalConfigContext () and provide VariableDefinition's of global settings. These settings will be exposed to system administrators, their values get persisted in the database. To access setting values from any method of the plugin, retrieve global config context using getGlobalConfigContext(), then call Context.getVariable() to fetch instances of DataTable representing setting values.

HOOKING UP TO THE SERVER CONTEXT TREE

ContextPlugin interface provides several groups of methods to attach some new elements to the AggreGate Server
context tree 863 . Every group has two methods: one "startup" method called at server startup or context creation and one "shutdown" method called at server shutdown or context destruction. 1. Plugin initialization/deininialization When a new context plugin is created, server calls its initialize() method that may contain some generic initialization code. When the plugin going to be destroyed, server calls its deinitialize() method. 2. Context-based setup Every time when new context is created or re-created on server startup, server calls install(Context method of the plugin. Its implementation may:

context)

2000-2013 Tibbo Technology Inc.

Development and Integration

Add some variable/function/event/action definitions to the context and optionally provide their "custom code" (variable getters/setters, function implementations) Add event listeners to the context

971

Please avoid accessing other server contexts from the install(Context context) method. Since server context tree creation is concurrent, certain server contexts may be available at the time of debugging and become unavailable in production environment, causing unpredictable behaviour. To access the whole context tree, add your code to install(ContextManager launch() methods. 3. Context tree-based setup The install(ContextManager contextManager) method is called once right after server context tree finishes loading and all contexts were created. Its implementation may retrieve certain server contexts using ContextManager.get() method and add variable/function/event/action definitions and/or event listeners to them. 4. Plugin launch

contextManager) or

launch() method of the plugin is called in the very end of server startup, when all server contexts and facilities are up
and running. It should be implemented only if some code fails to work properly from any of the methods described above.

MODIFYING PLUGIN DESCRIPTOR

To create a plugin descriptor it:
971

for your plugin, make a copy of demo plugin's plugin.xml file and edit the following in

Change the last word in id attribute of the <plugin> tag to the ID of new plugin. The ID should contain only lowecase letters, digits and underscores. For example, if your desired plugin ID is xyz, set ID attribute to com. tibbo.linkserver.plugin.context.xyz. Change class attribute of <plugin> tag to full name of plugin's java class. Enter plugin description in the body <doc-text> tag. Change id attribute of the <extension> tag to the new plugin ID.

BUILDING AND DEPLOYING PLUGIN ARCHIVE

Make a copy of demo plugin's Ant build file (build.xml) Change project name and name of destination file (plugin archive) Run built.xml using Ant (http://ant.apache.org/) to build plugin Java archive Copy the JAR file to %AggreGate Server Installation Folder/plugins/context when AggreGate Server is not running Start AggreGate Server

7.1.4.1 Plugin Descriptor

AggreGate Server Plugin Descriptor is an XML file describing a single AggreGate Server plugin the server plugin hierarchy. Here is an example of plugin descriptor:
950

and its place in

<?xml version="1.0" ?> <!DOCTYPE plugin PUBLIC "-//JPF//Java Plug-in Manifest 0.4" "http://jpf.sourceforge.net/plugin_0_4.dtd"> <plugin id="com.tibbo.linkserver.plugin.context.access-control" version="0.0.1" class="com.tibbo.links <doc> <doc-text>Access Control</doc-text> </doc> <requires> <import plugin-id="com.tibbo.aggregate.common.plugin.extensions"/> <import plugin-id="com.tibbo.linkserver.plugin.context.cardholders"/> </requires> <runtime> <library id="tibbo" path="/" type="code"> <export prefix="*"/> </library> </runtime>

2000-2013 Tibbo Technology Inc.

972

AggreGate Documentation

<extension </plugin>

plugin-id="com.tibbo.aggregate.common.plugin.extensions"

point-id="context"

id="access-contr

7.1.5 Agent SDK

Agent SDK is a Java library that allows to implement Agent 848 in the form of Java application running on a PC or mobile device. That application mimics Agent based on a hardware controller by connecting to AggreGate Server via secure network connection and providing a number of settings (variables), operations (functions) and events. In contast to a Java application that uses AggreGate Server API 961 , application written using Agent SDK connects to AggreGate Server in "device mode". It emulates or implements a hardware device connected to AggreGate. Agent can be also implemented using .NET API
974 .

Java-based Agents are ideal for connecting PC-based equipment to AggreGate for monitoring and management. Some examples of devices that can run PC-based Agent: Vending Machines Self Service Kiosks ATMs Remote Data Collection Stations etc. Device Server SDK bundle includes an open-source example of Java-based Agent. It is a runnable Java class DemoAgent located in examples.agent package. To try the demo agent, change server address/port/login/password in the constructor of RemoteServer class run DemoAgent class. It should connect to the server and auto-register a new Device account 113 .

Structure of Java-based Agent

Technically, Java-based Agent is a Java application or part of application that: Creates an instance of Agent class Retrieves the implementation of Agent's Context using Agent.getContext() method Configures the context by adding definitions of variables, functions and events. These are settings, operations and events "provided by the hardware device" in terms of AggreGate. Provides custom VariableGetter and VariableSetter for every Agent setting. These classes implement custom logic of reading and writing setting values. Provides custom FunctionImplementation for every Agent operation. These classes implement the logic of operations, i.e. processing the input and generating the output. Connects to the AggreGate Server on startup or at any desired time and starts processing server commands. These commands will trigger variable reads/writes and function execution. Asynchronously fires events in the Agent context using Context.fireEvent() method after server connection has been established.

7.1.5.1 Implementing a Java Agent

To implement your own Agent, add the following basic code to your java application: 1. Create an instance of RemoteServer and specify AggreGate Server address/port, name of user account to use for registration and Agent's password.

2000-2013 Tibbo Technology Inc.

Development and Integration

973

In AggreGate Server API server user account 108 .

961 ,

the password field of RemoteServer object is used as a password for the

113 .

However, Agent class uses password field as the password for the Agent's server-side Device account doesn't match the password of Agent owner's user account.

It

If Agent account with the name specified in Agent class constructor already exists and passwords of Agent account and Agent application do not match, Agent won't be able to log in to the server. 2. Create an instance of Agent and specify name of Agent's Device account
113

in the constructor.

3. Get an instance of Context using Agent.getContext() and add definitions/implementations of variables, functions, and events using addVariableDefinition(), addFunctionDefinition() and addEventDefinition() methods. 4. Call Agent.connect() to make your Agent connect to the AggreGate Server and authenticate/authorize. This call may fail for many reasons, including server unavailability, wrong server address/port, missing or disabled server-side Agent driver, incompatible Java libraries versions, missing user account, and incorrect Agent's device account password. 5. Start periodically calling Agent.run() method. It will server a single server command and return, so it should be basically called from a separate thread. At this point, your custom VariableGetter, VariableSetter and FunctionImplementation will be called. If run() method throws a DisconnectionException, server communication has failed for some reason and connection should be re-established. 6. Once Agent.getContext().isSynchronized() method will return true, your application may start generating Agent events using Agent.getContext().fireEvent() method. 7. To disconnect from the server and stop the Agent, call Agent.disconnect(). If some events are generated when Agent is not connected to the server or not yet synchronized, these events should be stored locally (in memory or some persistent storage) and sent to AggreGate Server upon first opportunity.

Informing Server About Variable Updates

An agent can notify the server that value of a certain variable has been changed. Such notification will cause out-oforder server cache update that may occur between synchronizations 126 . To send a variable update notification, use updated DataTable newTemperatureValue = new
890

event (example for Java-based Agent):

DataTable(agent.getContext().getVariableDefinition("temperature").getFor "temperature", newTemperatureValue);

agent.getContext().fireEvent(AbstractContext.E_UPDATED,

The updated event will-be auto-generated if you call agent.getContext().setVariable

("temperature",

newTemperatureValue);

Server-Initiated Disconnections
In certain cases (e.g. if server-side agent device account settings were changed) the server may forcibly close TCP connection with Agent. The latter should be able to detect such situation and reconnect to the server again.

Event Confirmation
The AgentContext class defines an eventConfirmed event that is generated each time an AggreGate Server has confirmed an Agent-generated event successful delivery and processing by calling Agent's confirmEvent() 853 function. It's possible to add a listener for eventConfirmed event and react to event delivery confirmations, e.g. by removing delivered Agent events from Agent's internal database.

2000-2013 Tibbo Technology Inc.

974

AggreGate Documentation

7.2 .NET API

The AggreGate Server open-source Application Programming Interface for .NET and .NET Compact (AggreGate Server . NET API) is a convenient library for accessing AggreGate Server from any .NET-based application using Web Service 976 or AggreGate Communication Protocol 1303 .

An Application Programming Interface (API) is an interface that a program or library provides for other computer programs, to let them make requests to it.
.NET Compact API is not available for direct download on AggreGate website. Please contact Tibbo to obtain . NET Compact API package.

Features of .NET API

Using this API, you can: Access server resources and connected devices; Modify server and device configuration; Execute server and device operations; Acquire server and device events; Connect to AggreGate Server in "device mode", i.e. write .NET code that emulates or implements a hardware device connected to AggreGate. Technically, the .NET API provides the following functionality: Full access to the server contexts
863

through a so-called proxy context tree;

863

Getting and setting values of context Calling context functions

878 ; 880

variables

869 ;

Listening for context events

(only when using AggreGate Protocol);

854 ;

Creating and manipulating Data Tables Emulating Agent

848 .

.NET API Distribution Package

The AggreGate .NET API is available as a ZIP archive that contains: Source code Examples Microsoft Visual Studio solution

Essential Classes and Interfaces of the .NET API

Class Name Description A container server connection parameters (address, port, username and password). An instance of this class is passed to the constructor of RemoteLinkServerController.

RemoteLinkServer

RemoteLinkServerContro This class is used to establish and control connection with the AggreGate Server. It ller provides access to a ContextManager interface which, in turns, lets you access the
server's context tree.

ContextManager

Interface that provides access to the context tree. An instance of the class implementing this interface may be retrieved from the RemoteLinkServerController through the getContextManager() method. Interface letting you work with a single context. Instances of classes implementing this interface are returned by different methods of ContextManager. Implementation of a Data Table 854 . It provides access to the format and records of the table. Instances of this class are returned by getVariable() and

Context DataTable

2000-2013 Tibbo Technology Inc.

Development and Integration

975

callFunction() methods of Context. DataRecord TableFormat FieldFormat

Implementation of a single Data Table record. Class implementing format of fields.
855

of a Data Table. It includes table properties and a list

Class implementing format 856 of a single Data Table field. Defines name, type and other parameters of the field, including validators, selection values etc.

Accessing AggreGate Server From .NET Application via Web Service

To access AggreGate Server from a .NET application using Web Service, create a LinkServerClient object in your application by calling its constructor with the Web Service address 976 and AggreGate Server user name 108 /password. Following is the LinkServerClient constructor's signature:

public LinkServerClient(String username, String password, String url)

Example: creating a AggreGate Server client object in C#: String webServiceAddress = "https://localhost:8443/ws/services/ServerWebService"; String userName = "admin"; String userPassword = "admin"; LinkServerClient lsc = new LinkServerClient(userName, userPassword, webServiceAddress);

To access the Web Service via HTTPS, it is necessary to set up a certificate policy first. For example (in C#): System.Net.ServicePointManager.CertificatePolicy = new TrustAllCertificatePolicy();

public class TrustAllCertificatePolicy : System.Net.ICertificatePolicy { public TrustAllCertificatePolicy() { } public bool CheckValidationResult(ServicePoint sp, X509Certificate cert, WebRequest req, int { return true; } }

The LinkServerClient object implements all methods defined

977

by the AggreGate Server Web Service:

getXML setXML callXML setByStringArray callByStringArray get set call

getXML, setXML, callXML, setByStringArray and callByStringArray methods are comprehensively described in Web Service 976 article. In most cases it is more convenient to use get, set and call methods that represent Data Tables as objects of type DataTable that is defined in AggreGate namespace. Here are signatures of all methods provided by LinkServerClient:

2000-2013 Tibbo Technology Inc.

976

AggreGate Documentation

METHODS THAT USE XML ENCODING OF DATA TABLES

public String getXML(String context, String variable) public void setXML(String context, String variable, String value) public String callXML(String context, String variable, String parameters)

METHODS THAT REPRESENT DATA TABLES AS STRING ARRAYS

public void setByStringArray(String context, String variable, String[] values) public DataTable callByStringArray(String context, String variable, String[] values)

METHODS THAT PROCESS DATA TABLES AS OBJECTS

public DataTable get(String context, String variable) public void set(String context, String variable, DataTable value) public DataTable call(String context, String variable, DataTable parameters)

7.3 Web Service

AggreGate Server supports Web a Services technology for integration with third-party ERP, CRM an other software systems. It supports the SOAP protocol, used for sending XML-encoded data secure HTTP connections.
Web Services is a set of protocols for generic data exchange between different systems.

AggreGate Servers Web Service allows total control of the server. It is possible to stop/restart the server, manage users, configure and control Devices, view Device events and their status etc. Technically, the Web Service provides methods for getting and setting values of context 863 variables 869 and calling context functions 878 . Real-time listening to context events 880 is not supported, but it's possible to access event history.

7.3.1 Accessing Web Service

AggreGate Server Web Service is available at the following addresses: https://server_host_name:server_ssl_port/ws/services/ServerWebService (for secure SHTTPbased connections) http://server_host_name:server_non_ssl_port/ws/services/ServerWebService (for non-secure HTTP connections)

server_host_name is the IP address or host name of the server. It may match one of the aliases defined in the host
name aliases list
60

Global Configuration Setting.

60

server_ssl_port is the port number on which AggreGate Server accepts incoming secure HTTP (HTTPS)
connections. Default value is 8443. This port is defined by Port number to listen for HTTPS (secure) connections Global Configuration Setting. value is 8080. This port is defined by Port number to listen for HTTP (non-secure) connections Setting.
60

server_non_ssl_port is the port number on that AggreGate Server accepts incoming HTTP connections. Default
Global Configuration

Non-secure HTTP access to the Web Service is disabled by default. It can be enabled by turning on Enable non-secure access to web applications 60 Global Configuration Setting.

2000-2013 Tibbo Technology Inc.

Development and Integration

977

Example: If AggreGate Server is running on the local host and all settings are set to their defaults, you can access the Web Service using the following URL:

https://localhost:8443/ws/services/ServerWebService

7.3.2 Web Service Functions

This article lists all functions that are exposed via Web Service.

Functions that Use XML Encoding of Data Tables

1. GETXML
The getXML Web Service function is used to retrieve values of AggreGate Server context Function parameters: Name username password context variable Type String String String String Description Name of AggreGate Server user account 108 that will be used to log in to the server. The Get variable operation will be executed with this user's permissions 931 . Password for the user account. Context path for the variable. Name of variable.
863

variables

869 .

Return value: this function returns a String that is a Data Table 854 containing the value of requested variable. This value is encoded in XML format. See Data Table XML Encoding 1312 for more information. The resulting XML string is encoded once again according to the URL encoding standard specified by RFC 1738 (Uniform Resource Locators). This is to ensure that the resulting string doesn't contain characters unsafe for SOAP protocol.

2. SETXML
The setXML function allows to change the value for a AggreGate Server context Function parameters: Name username password context variable value Type String String String String String Description Name of AggreGate Server user account 108 that will be used to log in to the server. The Set variable operation will be executed with the this user's permissions 931 . Password for the user account. Path of context to set variable in. Name of variable. New value of the variable encoded in XML format. See Data Table XML Encoding 1312 for more information. The resulting XML document is encoded once again according to URL encoding standard specified by RFC 1738 (Uniform Resource Locators). This is to ensure that the resulting string doesn't contain characters unsafe for SOAP protocol.
863

variable

869 .

Return value: none. In most cases, the value argument passed to this function is a Data Table that was previously retrieved by the getXML function.

3. CALLXML
The callXML function is used to execute AggreGate Server context an XML-encoded Data Table. Function parameters: Name Type Description
863

functions

878 ,

by passing function arguments in

2000-2013 Tibbo Technology Inc.

978

AggreGate Documentation

username password context variable value

String String String String String

Name of AggreGate Server user account 108 that will be used to log in to the server. The Call function operation will be executed with this user's permissions 931 . Password for the user account. Path of context from which the function is to be called. Name of function. Data Table containing function input parameters. This table is encoded in XML format. See Data Table XML Encoding 1312 for more information. The resulting XML document is encoded once again according to URL encoding standard specified by RFC 1738 (Uniform Resource Locators). This is to ensure that the resulting string doesn't contain characters unsafe for SOAP protocol.
854

Return value: this Web Service function returns a String that is a Data Table value is encoded just like the value input parameter above.

returned by the function executed. This

Functions that Represent Data Tables as String Arrays

1. SETBYSTRINGARRAY
The setByStringArray function is used to change values of AggreGate Server context Data Table containing the new value are passed to it as an array of String arguments. Function parameters: Name username password context variable values Type String String String String String[] Description Name of AggreGate Server user account 108 that will be used to log in to the server. The Set variable operation will be executed with this user's permissions 931 . Password for the user account. Path of context where the variable is located. Name of variable. An array of Strings, used to fill Data Table with the new variable value as described here
862 . 863

variables

869 .

Cells of the

Return value: none.

2. CALLBYSTRINGARRAY
The callByStringArray function allows to execute AggreGate Server context as a String array. Function parameters: Name username password context function parameter s Type String String String String String[] Description Name of AggreGate Server user account 108 that will be used to log in to the server. The Call function operation will be executed with this user's permissions 931 . Password for the user account. Path of context to call function from. Name of function. Array of Strings that are used to fill Data Table representing function input value as described here 862 .
863

function

878

by passing its arguments

Return value: this Web Service function returns a String that is a Data Table 854 returned by the function executed. This value is encoded in XML format. See Data Table XML Encoding 1312 for more information. The resulting XML string is encoded once again according to the URL encoding standard specified by RFC 1738 (Uniform Resource Locators). This is to ensure that the resulting string doesn't contain characters unsafe for SOAP protocol.

3. ADDRECORDBYSTRINGSRRAY
The addRecordByStringSrray function is used to new record(s) to a tabular context Data Table record are passed to it as an array of String arguments.
863

variable

869 .

Fields of a new

Technically, the function reads variable value, adds new record to it, and writes new value back to the context. Function parameters:

2000-2013 Tibbo Technology Inc.

Development and Integration

979

Name username password context variable values

Type String String String String String[]

Description Name of AggreGate Server user account 108 that will be used to log in to the server. The Get variable/Set variable operations will be executed with this user's permissions 931 . Password for the user account. Path of context where the variable is located. Name of variable. An array of Strings, used to fill new Data Table record with the values as described here
862 .

Return value: none.

4. SETVARIABLEFIELD
The setVariableField function is used to change a single cell (specified by field name and row number) of context variable 869 . The new cell value is passed as a String argument. Technically, the function reads variable value, changes a single cell of this value (that is a Data Table (sets) new value back to the context. Function parameters: Name username password context variable field row value Type String String String String String int String Description Name of AggreGate Server user account 108 that will be used to log in to the server. The Get variable/Set variable operations will be executed with this user's permissions 931 . Password for the user account. Path of context where the variable is located. Name of variable. Name of field. Row number. New cell value in the String form.
854 ), 863

and writes

Return value: none.

Functions that Use Native Encoding of Data Tables

There are three Web Service functions that use native Data Table encoding get set call These functions are used to get/set values of AggreGate Server context variables and call context functions respectively.
1306 :

7.3.3 Web Service Examples

Example 1: Accessing AggreGate Server Web Service From a PHP Script
This example shows how to get the value of a AggreGate Server context variable from a PHP script using the Web Service. The complete source code of this example is available in the Downloads section of the AggreGate website.

<?php // Creating SOAP client for the server running on localhost $client = new SoapClient("https://localhost:8443/ws/?wsdl"); $username = "admin";

2000-2013 Tibbo Technology Inc.

980

AggreGate Documentation

$password = "admin"; $context = "users.admin"; $variable = "childInfo"; try { // Calling getXML Web Service function and decoding its output by URL decoder $childInfoXML = urldecode($client->getXML($username, $password, $context, $variable)); } catch { (SoapFault $fault) occurred while calling remote function: ".$fault->faultcode."

echo "Error exit(); } if {

(".$fault->faultstring."

(is_soap_fault($childInfoXML)) echo "Error exit(); occurred while calling remote function: ".$fault->faultcode."

(".$fault->faultstring."

} // Creating DOM document from XML $xml = new DomDocument; $xml->loadXML( $childInfoXML ); // Loading XSLT transformation $xsl = new DomDocument; $xsl->load( 'resources/xslt/dataTable.xslt' // Creating XSLT processor $proc = new xsltprocessor; $proc->importStyleSheet( $xsl

);

);

// Processing out XML document and and showing the output echo $proc->transformToXML( $xml ); ?>

Example 2: Calling a Context Function

This example shows how to create a new AggreGate Server user account 108 by calling the register function of the root context 726 . Creation of SOAP client and error checking are omitted in this example. $params[0]="phpuser"; // Username (value for record 0, field 0 of function input Data Table) $params[1]="test"; // Password (value for record 0, field 1) $params[2]="test"; // Repeat Password (value for record 0, field 2) urldecode($client->callByStringArray("admin", "admin", "", "register", $params)); // Calling function

via

7.4 Programming Guide

This section covers common Java programming techniques helpful for mastering AggreGate SDK are useful for: Server-side development (plugins
969 , 960 .

This techniques

device drivers
610 )

963 ,

server scripts

628 )

Client-side development (widget scripts

Third party application development (AggreGate Server API

961 ,

Agents

972 )

7.4.1 Basic Concepts

AggreGate SDK indoctrinates a generic approach to managing any type of data flowing inside the system, both raw data coming from devices and pre-processed data provided by different system facilities, such as alerts 216 or trackers 257 . This approach also applies to any of the pre-built vertical market solution, such as AggreGate Network Manager, AggreGate SCADA/HMI, AggreGate Access Control, and other.

2000-2013 Tibbo Technology Inc.

Development and Integration

981

Data Table Operations

The elementary unit of all data flowing inside the system is Data Table 854 . Even simple scalar values (integers, strings, booleans) are represented by single-cell Data Tables for the sake of uniformity. The java representation of Data Table is DataTable class. If includes zero of more DataRecord instances representing individual records. Format 855 of DataTable is represented by TableFormat class. It refers zero or more FieldFormat instances defining format of individual table fields.

Working Via Contexts

Generally, all data should be accessed through different server contexts 863 . Contexts are organized as a hierarchical context tree 863 . The SDK includes Context interface for handling different context operations. Context instances may be retrieved from the ContextManager by their paths (full names). The Context interface also has a series of methods to access its parent and children.

Accessing Context Variables, Functions and Events

Every context provides access to its variables 869 , functions 878 and events 880 . There are several methods to get their definitions: getVariableDefinition(), getVariableDefinitions(), getFuncitonDefinition(), getFuncitonDefinitions(), getEventDefinition(), getEventDefinitions(). Classes representing the definitions are VariableDefinition, FunctionDefinition and EventDefinition respectively. Context interface provide a way to read/write values of variables: getVariable() and setVariable(). Value of every variable is an instance of DataTable. Context also provides a method for calling its functions: callFunction(). Both input and output of function are instances of DataTable. Events are handled by adding and removing event listeners using addEventListner() and removeEventListener() methods. Event listener must implement ContextEventListerner interface, but the real implementations will extend DefaultContextEventListener in most cases. Listeners working inside server plugins and drivers should pass an instance of UncheckedCallerController to the constructor of DefaultContextEventListener to ensure proper permissions.

getVariable() method returns a clone of variable value's DataTable even in the case of server-side code (plugins, drivers). To apply new value of the variable to the context, call setVariable() after making
modifications to the data table. Modifications of DataTable returned by getVariable() won't affect the context until setVariable() call is made.

7.4.2 Essential Classes and Interfaces

The below table briefly describes the most important classes and interfaces of AggreGate SDK. Class Name Description A container for server connection parameters (address, port, username and password). An instance of this class is passed to the constructor of RemoteServerController. This class is used to establish and control a connection with the AggreGate Server. It provides access to a ContextManager interface which, in turns, lets you access the server's context tree. An interface that provides access to the context tree. An instance of the class implementing this interface may be retrieved from the RemoteServerController through the getContextManager() method. An interface letting you work with a single context. Instances of classes implementing this interface are returned by different methods of ContextManager. Definition of the context variable Definition of the context function implementation. Definition of the context event
869 .

RemoteServer RemoteServerCo ntroller ContextManager

Context VariableDefini tion FunctionDefini tion EventDefinitio n

Provides access to its properties, format, getter and setter. Provides access to its properties, input/output formats and

878 .

880 .

Provides access to its properties and format.

2000-2013 Tibbo Technology Inc.

982

AggreGate Documentation

VariableGetter VariableSetter FunctionImplem entation ContextEventLi stener DefaultContext EventListener DataTable

Implementations of this interface should provide custom variable value reading logic. Implementations of this interface should provide custom variable value writing logic. Implementations of this interface should provide custom function execution logic, i.e. processing of input and generation of output. A base interface for context event listeners. The listener's handle() method is called when event is fired in the context to that the listener was added. Default implementation of ContextEventListener. Generally, most listeners should extend this class. Implementation of a Data Table 854 . It provides access to the format and records of the table. Instances of this class are returned by getVariable() and callFunction() methods of Context. Implementation of a single Data Table record. Class implementing the format fields.
855

DataRecord TableFormat FieldFormat CallerControll er UncheckedCalle rController Permissions ServerPermissi onChecker

of a Data Table. It includes table properties and a list of

Class implementing the format 856 of a single Data Table field. Defines name, type and other parameters of the field, including validators, selection values etc. The instance of this class is passed to many context operations. It incorporates permissions of the calling side. A special type of caller controller that suppress any permission checking, giving full access to the calling side. Should be used for system calls. A list of permissions (Permission objects) what must be satisfied when accessing a certain server resource. This class provides a set of static methods for getting Permissions to assign for newly added variable/function/event definitions.

7.4.3 Finding and Accessing Arbitrary Data

This section explains how to find, read or modify any data flowing inside the AggreGate installation.

1. Finding the Proper Context

First step is locating the context that exposes the necessary setting, operation or event. There are several ways to achieve that: Check server core context reference documentation)
651

and/or vertical-solution-specific context references (that are also part of this

776

Find necessary context in the System Tree of AggreGate Client

or Web Desktop

632

2. Finding Name of Necessary Variable/Function/Event

If the context containing necessary data was found in the context reference, check Public Variables, Public Functions or Public Events section of the corresponding article for name of variable/funciton/event providing necessary data If using AggreGate Server UI to locate the data, consider the following: o Tooltips of rows and cells of the Properties Editor component show names of variables; o Tooltips of events in Event Log component show event source context and name; o Function names may be tracked down using Entity Selector component; o Properties Editor provides View Variable Information operation in its context menu, while Event Log has View Event Definition context operation. These operations show all properties of the definitions, their formats, etc.

3. Determining Field Names and Types

Since every value is a Data Table, it's necessary to find out what fields does its format have. That includes field names and types. If the necessary definition is found in context reference, its description contain a format table describing field names, types, and purposes.

2000-2013 Tibbo Technology Inc.

Development and Integration

If using the UI, consider the following:

983

o Values of variables, events data, or functions input/output are always opened in the Data Table Editor component. Column, row and cell tooltips in the Data Table Editor show field names and types; o View Variable Information and View Event Definition operations (see above) provide comprehensive information about all field propeties, including their defaults, selection values, etc.

4. Accessing the Data Programmatically

After locating the necessary context, variable/function/event, and their fields, you can access them programmatically, both from server plugins or using remote API: Get the necessary Context object using ContextManager.get(), Context.getChild() or Context. getParent() methods. To programmatically construct server context names/paths use static helper methods defined in ContextUtils class and constants defined in Contexts class. Example: String

alertContextPath = ContextUtils.alertContextPath("admin",

"myAlert");
Get/set variable, call function, of add event listeners using getVariable(), setVariable(), callFunction(), addEventListner() methods. To construct new value of variable of function input value from scratch, use the following code: new DataTable (VariableDefinition.getFormat()) or new DataTable(FunctionDefinition.getInputFormat()) . When processing a DataTable, you can get a certain DataRecord using getRecord() method. The shortcut for getting first record is rec() method. DataRecord provides generic getValue() and setValue() methods for reading/writing field values. However, there is a set of methods for getting field value casted to a certain type: getInt(), getString(), getBoolean (), etc. To refer named server variables/functions/events/actions and their fields use constants defined in members of com.tibbo.aggregate.common.server package. Example: String

serverVersion = rootContext.getVariable(RootContextConstants. V_VERSION).rec().getString(RootContextConstants.VF_VERSION_VERSION);

7.4.4 Logging
AggreGate libraries report their activities via logging 74 . To enable and configure logging in the Java application that uses AggreGate Server API 961 or Agent SDK 960 , call Log.start() method and pass the URL of logging configuration file 74 to it. You can copy this file from AggreGate Server or AggreGate Client installation directory. Edit this file by changing logging level in certain categories 76 for debugging purposes. It's also possible to use logging in server or widget scripts. Logging produced by server scripts will be appended to server log file (server.log). Widget script logging will be appended to AggreGate Client log file (client.log) or java applet console (if using Web Desktop 632 ). By default, all categories in the logging configuration files are set up to pass messages at INFO and higher levels. Thus, to write a certain string to a log file, you can use the following code: Logger.getLogger("ag.mycategory").info("Hello world!");

7.4.5 Working with Data Tables

This section helps to master programmatic management of Data Tables Creation
984 854 .

It's divided into the following parts:

of Data Tables (defining format, adding records, setting cell values, etc.)
985

Manipulation

of Data Tables (iterating records, accessing cell values, cloning tables, etc.)

2000-2013 Tibbo Technology Inc.

984

AggreGate Documentation

7.4.5.1 Creation
Data tables are represented by instances of DataTable class. To create a DataTable it's necessary to define its format by creating an instance of TableFormat class: TableFormat tf = new TableFormat(); // For multi-row tables TableFormat tf = new TableFormat(1, 1); // For single-row tables

ADDING FIELDS
After that, it's necessary to add field descriptors to a table format. Each field is represented by a FieldFormat instance. There are many ways to create a field format descriptor:

FieldFormat ff = FieldFormat.create("fieldName", FieldFormat.STRING_FIELD); // The simplest method to crea ff.setDescription("Field Description"); ff.setDefault("Default Value"); ff.setNullable(true);

FieldFormat ff = FieldFormat.create("fieldName", FieldFormat.STRING_FIELD, "Field Description", "Default Va FieldFormat ff = FieldFormat.create("<fieldName><S><D=Field Description><A=Default value><F=N>"); // Same

// After field format is created, we can fine-tune it ff.addSelectionValue("v1", "First option"); ff.addSelectionValue("v2", "Second option"); ff.addValidator(new LimitsValidator(10, 100)); ff.setKeyField(true); //Now we can add our field descriptor to field format: TableFormat tf = new TableFormat(); tf.addField(ff); It's also possible to avoid explicit creation of FieldFormat and pass field options to TableFormat.addField(): TableFormat tf = new TableFormat(); tf.addField("fieldName", FieldFormat.STRING_FIELD, "Field Description", "Default Value", true);

SETTING FORMAT OPTIONS

When all fields were added, we can fine-tune out table format and add some bindings tf.setReorderable(true); tf.addBinding("field2", tf.addTableValidator(new "{field1} * 2");
860

and validators to it:

TableKeyFieldsValidator());

CREATING TABLE
When our table format is ready, we can base a table on it: TableFormat tf = new TableFormat(1, 1, FieldFormat.create("fieldName", FieldFormat.STRING_FIELD));

DataTable table = new DataTable(tf);

Once TableFormat instance has been used to create a table, it becomes immutable and cannot be modified. To modify format of an existing table: Clone format of the table: TableFormat cloned = table.getFormat().clone(); The cloned format will be mutable. Make necessary modifications to it. Create a new table using cloned format: DataTable newTable = new DataTable(cloned); Copy
861

data from old table to a new one using static helper methods of DataTableReplication class:

DataTableReplication.copy(table,

newTable);

2000-2013 Tibbo Technology Inc.

Development and Integration

985

ADDING RECORDS
There are several ways to create a record. First method - setting field values explicitly: DataRecord rec = table.addRecord(); rec.setValue("firstField", "Value of first field"); // First field is a string-type field rec.setValue("secondField", true); // First field is a boolean-type field rec.setValue("thirdField", 12345); // First field is an integer-type field Second method - passing field values to addRecord(): DataRecord rec = table.addRecord("Value of first field", true, 12345); Third method - adding values one by one: DataRecord rec = table.addRecord(); rec.addString("Value of first field"); rec.addBoolean(true); rec.addInt(12345); // Explicit type specification is not necessary DataRecord rec = table.addRecord(); rec.addValue("Value of first field"); rec.addValue(true); rec.addValue(12345);

7.4.5.2 Manipulation
It possible to add/remove records from existing table and modify cell values. However, it's not possible to change format of existing table. To access cell data, obtain a DataRecord first: DataRecord rec = table.getRecord(5); // Records are zero-based, so this will return 6th record DataRecord rec = table.rec(); // This returns first record (with zero index) Now you can use methods that return proper value types to get cell values: String Boolean Integer s1 b1 i1 = = = rec.getString("firstField"); rec.getBoolean("secondField"); rec.getInt("thirdField");

ITERATING RECORDS
It's very often necessary to process all table's records. DataTable implements Iterable interface making this very easy: for(DataRecord rec : table) { // Process the record }

CLONING TABLES AND TABLE ELEMENTS

All data table elements support cloning. Therefore, it's always possible to clone a whole table and all its parts: DataTable clonedTable = table.clone();

2000-2013 Tibbo Technology Inc.

986

AggreGate Documentation

DataRecord

clonedRecord

table.rec().clone();

ENCODING AND DECODING TABLES

Any data table can be encoded into string and restored without data loss. To encode and decode a table use the following code: String encodedTable = table.encode(false); // Don't use visible separators DataTable restored = new DataTable(encodedTable);

SELECTING TABLE CELLS

To find the first record having value of Integer field field1 is equal to 123 use the below code: DataRecord rec = table.select("field1", 123);

If such record is not found, this method will return null.

SORTING TABLES
To sort the table according to values of field field1, use this code: table.sort("field1", true); // Ascending sort order

7.4.6 Working with Contexts

An initial object providing access to a context tree to obtain a context manager.
863

implements ContextManager interface. There are several ways

Obtaining Context Manager

The method of getting an instance of ContextManager depends on the current environment: If developing an application using AggreGate Server API 961 , use RemoteServerController. getContextManager() to get context tree manager of remote server If developing a Device Driver manager If developing a plugin
963 ,

use DeviceContext.getContextManager() to get server context tree

969 , the context manager is passed as a parameter to install(ContextManager cm) and deinstall(ContextManager cm) methods. If inside install(ServerContext context) and deinstall (ServerContext context) methods, use ServerContext.getContextManager().

When developing a Java-based Agent 972 , remember that your Agent has just a single context. However, its context manager can be accessed via Agent.getContext().getContextManager(). When writing a server script 628 , call ScriptExecutionEnvironment.getScriptContext(). getContextManager() to access server context manager. When writing a widget script
610 , call WidgetScriptExecutionEnvironment.getEngine(). getServerContextManager() to access remote server's context manager. Alternatively, you can call WidgetScriptExecutionEnvironment.getComponentContext("componentName"). getContextManager() to access context manager of widget components' context tree.

Respecting Access Permissions

An instance of CallerController object incorporating current user's permissions must be passed to most contextrelated calls if you're writing code that will work inside the AggreGate Server JVM (e.g. if developing a server script or plugin). Failure to do so will result to null results of different access denied exceptions. See Dealing with Access Permissions
997

for details.

Retrieving Individual Contexts

You can call ContextManager.get(String

path) method to retrieve a context with the specified path

863 .

2000-2013 Tibbo Technology Inc.

Development and Integration

987

Context

deviceContext

contextManager.get("users.admin.devices.device1");

The get() method will return null if requested context does not exist or is no available with current permissions. Calls to ContextManager.get() and ContextManager.getRoot() will return instances of Context interface: Context rootContext = contextManager.getRoot();

Constants defined in Contexts class and static methods of ContextUtils class provide convenient ways to construct paths of different server contexts, such as Alert or Device contexts. Example: Context

alertContext = contextManager.get(ContextUtils.alertContextPath ("admin", "myalert"));

When working with a specific context, use Context.getParent() and Context.getChild(String access its parent and named child contexts respectively.

name) to

PROCESSING CHILDREN LISTS

To get the list of certain context's children contexts, call Context.getChildren(). 1. Server-side call to getChildren(CallerController caller) will return only children that are accessible to the calling user (represented by CallerController). 2. Call to getChildren() of a proxy context (e.g. when using remote API or developing an Agent) will return only children accessible to the user that is authenticated in the current server connection.

Getting Context Information

The Context interface has several of methods for getting basic information about a context:

getName() getPath() getDescription() getType() getGroup()

7.4.6.1 Manipulating Variables

This section explains how to programmatically manipulate context variables
869 .

Finding Out Available Variables

There are several ways to get a list of variables from a Context: getVariableDefinitions() - this method will return the list of all variables in a context getVariableDefinitions(CallerController caller) - this method will return the list of variables accessible by the caller (either for reading or for writing) getVariableDefinitions(String certain group or its subgroups

group) - this method will return the list of variables belonging to the group) - this method will return the list

getVariableDefinitions(CallerController caller, String of variables belonging to the certain group and accessible by the caller List<VariableDefinition> variables =

context.getVariableDefinitions(ContextUtils.GROUP_REMOTE);

//

Finding

To retrieve a single variable definition by its name call getVariableDefinition(String name) method. The method getVariableDefinition(String name, CallerController caller) will return a definition or null if variable is not accessible by caller .

Reading and Writing Variables

2000-2013 Tibbo Technology Inc.

988

AggreGate Documentation

The Context interface has two primary methods for manipulating variable values:

getVariable() setVariable()
This methods allow to read and write context variable values respectively.

READING VARIABLES
The getVariable() method reads variable value and returns a DataTable representing this value. It accepts one or two arguments: name of variable to read and optional instance of CallerController that incorporates permissions of calling side (see Dealing with Access Permissions 997 for details). Once the variable value table is obtained, you can access its data. See Manipulating Data Tables Here is an example of how to read variable value: DataTable variableValue = context.getVariable("tabularVariable");
985

for details.

WRITING VARIABLES
There are two primary ways to set a variable: By supplying a pre-built DataTable object. This object can be programmatically created from scratch or obtained via getVariable() call and modified. By supplying individual cell values. Example 1 - setting variable value using a pre-built data table: DataTable variableValue = new DataTable(context.getVariableDefinition("tabularVariable").getFormat()); // // // Adding Adding Setting a record another one variable value //

variableValue.addRecord().addString("str1").addInt(111); variableValue.addRecord().addString("str2").addInt(222); context.setVariable("tabularVariable", variableValue);

Example 2 - modifying previous variable value: DataTable variableValue = context.getVariable("tabularVariable"); // // // Adding Adding Setting a record another one variable value

variableValue.addRecord().addString("str1").addInt(111); variableValue.addRecord().addString("str2").addInt(222); context.setVariable("tabularVariable", variableValue);

Example 3 - setting variable value using a list of cell values: context.setVariable("tabularVariable", "str1", 111); // Supplying cell values for the first record of new

If you want to change just a single cell or record of variable value, it's not enough to read its value and modify the obtained DataTable. It's necessary to write modified value back to the source context by calling setVariable(). Simply speaking, any modification of variable requires setVariable() call.

Accessing Variable History

There are two ways to access database-stored historical values of a variable: By calling variableHistory 764 function from Utilities drivers/plugins) and remotely (via server API).
763

context. This method will work both locally (inside server

By calling ServerContextUtils.getVariableHistory() static Java method. This way is slightly faster than previous one, but it will work inside server JVM only (e.g. in drivers/plugins).

CALLING VARIABLEHISTORY FUNCTION

The variableHistory function of Utilities context returns a Data Table historical value of the variable. See its description here 764 .
854

each row of that contains timestamp and

2000-2013 Tibbo Technology Inc.

Development and Integration

989

DataTable

history

utilsContext.callFunction(UtilitiesContextConstants.F_VARIABLE_HISTORY,

getCallerControl

for (DataRecord rec : history) { // Process historical values }

USING SERVER CONTEXT UTILITIES CLASS

Static method of ServerContextUtils class that returns historical values of a variable has the following signature:

public static Map<Date, DataTable> getVariableHistory(CallerController caller, String context, String vari throws DaoException, ContextException, DataTableException It returns the map of timestamps indicating time when values were saved and the values themselves.

7.4.6.2 Calling Functions

This section explains how to programmatically list and call context functions
878 .

Finding Out Available Functions

There are several ways to get a list of functions from a Context: getFunctionDefinitions() - this method will return the list of all functions in a context getFunctionDefinitions(CallerController accessible by the caller getFunctionDefinitions(String certain group of its subgroups

caller) - this method will return the list of functions

group) - this method will return the list of functions belonging to the group) - this method will return the list

getFunctionDefinitions(CallerController caller, String of functions belonging to the certain group and accessible by the caller List<FunctionDefinition> functions =

context.getFunctionDefinitions(ContextUtils.GROUP_REMOTE);

//

Finding

To retrieve a single function definition by its name call getFunctionDefinition(String name) method. The method getFunctionDefinition(String name, CallerController caller) will return a definition or null if function is not accessible by caller .

Executing Functions
To call a function, use Context.callFunction() method. It accepts the following arguments: name of function to call, optional instance of CallerController that incorporates permissions of calling side (see Dealing with Access Permissions 997 for details), and optional function parameters. There are two ways to specify function input parameters: By supplying a pre-built DataTable object. This object can be programmatically created from scratch using format obtainable via FunctionDefinition.getInputFormat(). By supplying individual cell values of function input data table. The callFunction() method returns a DataTable representing function output. Example 1 - calling function by supplying a pre-built data table: DataTable input = new DataTable(context.getFunctionDefinition("sendSms").getInputFormat());

input.addRecord().addString("+12345678900").addInt("First message"); // Adding a record input.addRecord().addString("+98765432100").addInt("Second message"); // Adding another one DataTable output = context.callFunction("sendSms", input); // Calling function

Example 2 - calling function by supplying a list of input table cell values:

DataTable output = context.callFunction("sendSms", "12345678900", "First message"); // Supplying cell value

2000-2013 Tibbo Technology Inc.

990

AggreGate Documentation

7.4.6.3 Listening and Processing Events

This section explains how to programmatically list, subscribe to, and process context events
880 .

Finding Out Available Events

There are several ways to get a list of events from a Context: getEventDefinitions() - this method will return the list of all events in a context getEventDefinitions(CallerController the caller getEventDefinitions(String group of its subgroups

caller) - this method will return the list of events accessible by

group) - this method will return the list of events belonging to the certain group) - this method will return the list of

getEventDefinitions(CallerController caller, String events belonging to the certain group and accessible by the caller List<EventDefinition> events =

context.getEventDefinitions(ContextUtils.GROUP_REMOTE);

//

Finding

all

even

To retrieve a single event definition by its name call getEventDefinition(String name) method. The method getEventDefinition(String name, CallerController caller) will return a definition or null if event is not accessible by caller .

Firing Events
Once a certain system component (e.g. a device driver) detects that something has happened, it may fire a context event. The event may be fired asynchronously from any thread. Note, that there is no generic way to fire any event remotely (from AggreGate Client or when using AggreGate Server API). To fire an event, call Context.fireEvent() method. This method accepts the following parameters: Event name Event level Event parameters (in form of pre-built DataTable or list of its cell values) Example 1 - firing event by supplying event DataTable: DataTable eventData = new DataTable(context.getEventDefinition("myEvent").getFormat()); // Adding a record // Creating empty

eventData.addRecord().addString("str1").addInt(111); context.fireEvent("myEvent", EventLevel.INFO,

eventData);

Example 2: firing event by supplying event table cell value: context.fireEvent("randomValue", EventLevel.INFO, new Float(Math.random() * 1000000));

Subscribing To Events
Server modules may subscribe to context events in order to receive and process their instances. In most cases, this functionality is required when implementing custom server plugins 950 . To subscribe to an event: Create an instance of class implementing ContextEventListener interface Pass this instance to Context.addEventListener() method

ContextEventListener interface has a lot of methods, and in most cases it's more reasonable to inherit your event
listener from an existing implementation: If writing server-side code (e.g. a plugin), inherit your event listener from ServerEventListener to ensure its correct permission level. In other cases, use DefaultContextEventListener as a base.

2000-2013 Tibbo Technology Inc.

Development and Integration

991

Using DefaultContextEventListener from code running inside the server JVM will lead to no events being received. This happens because default listener does not incorporate proper permissions.

Processing Events
Once you've subscribed to an event by adding a listener, the system will call listener's handle() method each time when an event occurs. Thus, all processing logic should be added to the implementation of this method: DefaultContextEventListener listener = new DefaultContextEventListener() { @Override public void handle(Event event) throws EventHandlingException { // Handling event here int level = event.getLevel(); List<Acknowledgement> acknowledgements = event.getAcknowledgements(); // Accessing event data DataTable eventData = event.getData(); } }; context.addEventListener("eventName", listener);

Accessing Historical Events

There are two ways to access historical events stored in the server database: By calling get 695 function from Events and remotely (via server API).
693

context. This method will work both locally (inside server drivers/plugins)

By calling Server.getDaoFactory().getEventDao().getEvents() Java method. This way is slightly faster than previous one, but it will work inside server JVM only (e.g. in drivers/plugins).

CALLING GET FUNCTION

The get function of Events context returns a Data Table event. See its description here 695 . DataTable history =
854

each row of that contains information about one historic

eventsContext.callFunction(EventsContextConstants.F_GET,

getCallerController(),

con.ge

for (DataRecord rec : history) { // Process historical events }

USING DIRECT DATABASE ACCESS

Method of EventDao class that performs loading of events from the database has the following signature:

public List<Event> getEvents(CallerController caller, EntityList eventList, EventsFilter filter, Date from Criterion... additionalCriteria) throws DaoException This method accept list of event types to load, pre-filter (additionalCriteria) and post-filter (filter), start/end dates of loaded events occurrence period, maximum number of events to load, and sort options. fromDate, toDate and maxResults parameters can be set to null to disable time range and count limit. It returns the list of Event objects representing historical events. Usage example: EntityList List<Event> events events = = new EntityList("users.admin.devices.my_device", "my_device_event"); entities, null, null, null,

Server.getDaoFactory().getEventDao().getEvents(caller,

2000-2013 Tibbo Technology Inc.

992

AggreGate Documentation

for (Event ev : events) { Date eventTime = ev.getCreationtime(); DataTable eventData = ev.getData(); // Processing }

7.4.7 Declaring Variables, Functions, Events and Actions

Server plugins 969 and drivers 963 , along with Java-based Agents 972 , usually create their own definitions of variables, functions and events. These definitions are added to the contexts using addVariableDefinition(), addFunctionDefinition() and addEventDefinition() methods. There are also corresponding removal methods: removeVariableDefinition(), removeFunctionDefinition() and removeEventDefinition (). There is no generic way to remotely manage/modify server-side context tree structure and variable/function/ event definitions. Thus, addChild(), removeChild(), addVariableDefinition(), removeVariableDefinition (), addFunctionDefinition(), removeFunctionDefinition(), addEventDefinition(), removeEventDefinition(), and similar methods called on a proxy context (e.g. via AggreGate Server API) will not affect server-side context tree.

7.4.7.1 Defining and Implementing Variables

When defining your own device/agent/server context variables, it's necessary to specify properties of their definitions 870 , i.e. name, description, format, readable/writable flags, permission level, help text, and group. To declare new variable, create an instance of VariableDefinition object and set its properties. Here is an example: // Creating String field format FieldFormat ff = FieldFormat.create("demoSettingField", // Creating single-cell (scalar) setting TableFormat format = new TableFormat(1, 1, ff); // Creating variable (setting) definition. Note that variable group should not be changed. VariableDefinition vd = new VariableDefinition("demoSetting", format, true, true, "Demo Setting", // Setting permission level vd.setPermissions(ServerPermissionChecker.getManagerPermissions()); Once done, add the variable definition to a context: Device driver context's variables matching device access settings should be added by calling Context. addVariableDefinition() from inside the DeviceDriver.setupDeviceContext() method. Definitions of device driver context's variables matching device properties (device settings variables) should be returned by overridden DeviceDriver.readVariableDefinitions() method. Server plugins
950

FieldFormat.STRING_FIELD);

Contex

should add variables from inside install() and start() methods.

Java-based Agents should add variables after Agent object creation via Agent.getContext(). addVariableDefinition(). Finally, scripts (both server and widget scripts) should not normally add any variables. For server-side variables, it's might be also necessary to specify read/write permission level // Setting permission level vd.setPermissions(ServerPermissionChecker.getManagerPermissions());
997 :

2000-2013 Tibbo Technology Inc.

Development and Integration

993

Device setting variables provided by a device driver 129 , along with Agent variables, must belong to a group remote. I be grouped into tabs, append tab description to a group name using "|" as a separator, e.g. remote|Power Managem It's also possible to use nested groups, e.g. remote|Power Management Settings|Auto Power-off. Variable group is specified by calling VariableDefinition.setGroup(). You can use the following syntax: vd.setGroup(ContextUtils.createGroup(ContextUtils.GROUP_REMOTE, "Power Management Settings",

"Auto

Manually added variables (except for device setting variables) should also have a non-null getter implementing VariableGetter interface. The purpose of getter is providing custom variable reading code. Writable variables should also have a non-null setter implementing VariableSetter interface. The setter should somehow store new variable value modified by system operators or different server facilities. Format of data table returned by variable getter must match format contained in its definition. Failure to follow this rule may result in data loss since the system will try convert the data table to definition-provided format preserving as much data as it can.

Variable Value Getting Implementation

This section comprehensively describes how a Context builds and returns a DataTable representing variable value once someone has called the getVariable() method. All logic described here is implemented in the AbstractContext class that is included into the open-source SDK. To returns a resulting DataTable from the getVariable() method, an AbstractContext does the following: 1. Obtains variable read lock to prevent concurrent read operations. If any other thread reads the variable, current thread will block until the previous read operation is finished. 2. Checks whether the calling party (identified by the CallerController object) has sufficient effective permission level 932 in the current context to read this variable. 3. Searches current context (using Java reflection technology) for existence of the "getter method" with the following signature:

public DataTable getVvariable(VariableDefinition def, CallerController caller, RequestController request) throws ContextException
The variable is the name of variable being read. If a method with such a signature is found it will be called. This method must return a DataTable representing value of the variable. 4. If a "getter method" was not found, existence of VariableGetter is checked by calling VariableDefinition. getGetter(). If VariableGetter is defined (not null), VariableGetter.get() method is called. The getter must return a DataTable representing value of the variable. 5. If variable getter is not defined (i.e. VariableDefinition.getGetter() returns null), the AbstractContext calls getVariableImpl() method. This method may be overridden in the subclasses of AbstractContext. If the overriding implementation "understands" the variable (i.e. "knows" its name), it should return a DataTable representing value of the variable. In other cases, the getVariableImpl() method should return null. 6. If getVariableImpl() method has returned null, the AbstractContext calls executeDefaultGetter() method. The default getter returns value of the variable that was stored in the database (for server-side code) or cached in memory (for all other cases). 7. If variable value was not previously cached, executeDefaultGetter() method checks whether default value of the variable is defined (non-null) by calling VariableDefinition.getDefaultValue(). This value should be set via VariableDefinition.setDefaultValue(DataTable value) earlier. 8. And finally, if default value is not defined in the VariableDefinition, the default getter constructs and returns a default value by calling new DataTable(variableDefinition.getFormat(), true). 9. DataTable obtained from "getter method", VariableGetter, getVariableImpl() method, or default getter is not immediately returned from getVariable(). It's first checked for accordance with variable format (available via VariableDefinition.getFormat(), this step is skipped if it returns null). If format of the data table matches format provided by the definition (or extends it by adding some fields), this table is returned as is. If format of table does not match or extend format of definition, AbstractContext does its best to convert the table to "proper" format and preserve as much data as possible. This is done by calling DataTableReplication.copy() method.

2000-2013 Tibbo Technology Inc.

994

AggreGate Documentation

If code implementing "getter method", VariableGetter or getVariableImpl() needs to access database-stored or memory-stored value of the variable, this code should call executeDefaultGetter() method directly.

Variable Value Setting Implementation

This section comprehensively describes how a Context processes a DataTable representing new variable value once someone has called the setVariable() method. All logic described here is implemented in the AbstractContext class that is included into the open-source SDK. To process a DataTable representing new value of the variable when the setVariable() method is called, an AbstractContext does the following: 1. Obtains variable write lock to prevent concurrent write operations. If any other thread writes the variable, current thread will block until the previous write operation is finished. 2. Checks whether the calling party (identified by the CallerController object) has sufficient effective permission level 932 in the current context to write this variable. 3. DataTable representing new value of the variable is first checked for accordance with variable format (available via VariableDefinition.getFormat(), this step is skipped if it returns null). If format of the value data table matches format provided by the definition (or extends it by adding some fields), this table is left intact. If format of value table does not match or extend format of definition, AbstractContext does its best to convert the table to "proper" format and preserve as much data as possible. This is done by calling DataTableReplication.copy() method. 4. If the calling party has permission checking enabled (i.e. represents a normal system user 108 ), the system ensures that values of all read-only fields in the new table are equal to values of corresponding fields in the old (current) table that is internally retrieved by getVariable() call. Values of all changed read-only fields are reset to the ones taken from old (current) table. 5. Current context is then searched (using Java reflection technology) for existence of the "setter method" with the following signature:

public void setVvariable(VariableDefinition def, CallerController caller, RequestController request, DataTable value) throws ContextException
The variable is the name of variable being written. If a method with such a signature is found it will be called. This method must process the DataTable representing new value of the variable. 6. If a "setter method" was not found, existence of VariableSetter is checked by VariableDefinition. getSetter(). If VariableSetter is defined (not null), VariableSetter.set() method is called. The setter must process the DataTable representing new value of the variable. 7. If variable setter is not defined (i.e. VariableDefinition.getSetter() returns null), or the setter has returned false, the AbstractContext calls setVariableImpl() method. This method may be overridden in the subclasses of AbstractContext. If the overriding implementation "understands" the variable (i.e. "knows" its name), it should process a DataTable representing new value of the variable and return true. Otherwise, the setVariableImpl() method should return false. 8. If setVariableImpl() method has returned false, the AbstractContext calls executeDefaultSetter() method. The default setter stores new value of the variable in the database (for server-side code) or memory cache (for all other cases). If code implementing "setter method", VariableSetter or setVariableImpl() needs to store new variable value in the database or memory, this code should call executeDefaultSetter() method directly.

7.4.7.2 Defining and Implementing Functions

When defining your own device/agent/server context functions, it's necessary to specify properties of their definitions 878 , i.e. name, description, input and output format, permission level, help text, and group. To declare new function, create an instance of FunctionDefinition object and set its properties. Here is an example: // Creating function input format (scalar, integer) FieldFormat iff = FieldFormat.create("demoOperationInputField", TableFormat inputFormat = new TableFormat(1, 1, iff);

FieldFormat.INTEGER_FIELD);

2000-2013 Tibbo Technology Inc.

Development and Integration

995

// Creating function output format (scalar, string) FieldFormat off = FieldFormat.create("demoOperationOutputField", TableFormat outputFormat = new TableFormat(1, 1, off);

FieldFormat.STRING_FIELD);

// Creating function (operation) definition. Note that function group should not be changed. FunctionDefinition fd = new FunctionDefinition("demoOperation", inputFormat, outputFormat, "Demo Once done, add the function definition to a context: Definitions of device driver context's functions matching device operations should be returned by overridden DeviceDriver.readFunctionDefinitions() method. Server will add function definitions to the device context and create action 892 definitions for them. Server plugins
950

Operati

should add functions from inside install() and start() methods.

Java-based Agents should add functions after Agent object creation via Agent.getContext(). addFunctionDefinition(). Finally, scripts (both server and widget scripts) should not normally add any functions. For server-side functions, it's might be also necessary to specify permission level
997 :

// Setting permission level fd.setPermissions(ServerPermissionChecker.getManagerPermissions());

Device operation functions provided by a device driver 129 , along with Agent functions, must belong to a group remote you want them to be grouped logically (and put into nested context menus), append group description to a group name using "|" as a separator, e.g. remote|Maintenance Operations. It's also possible to use nested groups, e.g. remote|Maintenance Operations|Daily. Function group is specified by calling FunctionDefinition.setGroup(). You can use the following syntax: fd.setGroup(ContextUtils.createGroup(ContextUtils.GROUP_REMOTE, "Maintenance Operations",

"Daily"

Manually added functions must have a non-null implementation that is a derived from FunctionImplementation interface. The implementation should analyze function input, process it, and generate the output. Format of data table returned by function implementation method must match output format contained in its definition. Failure to follow this rule may result in data loss since the system will try convert the data table to definition-provided format preserving as much data as it can.

7.4.7.3 Defining and Implementing Events

When defining your own device/agent/server context events, it's necessary to specify properties of their definitions i.e. name, description, format, help text, permission level, and group. To declare new event, create an instance of EventDefinition object and set its properties. Here is an example: // Creating event data format (scalar, string) FieldFormat ff = FieldFormat.create("demoEventField", TableFormat format = new TableFormat(1, 1, ff); // Creating event definition EventDefinition ed = new EventDefinition("demoEvent", Once done, add the event definition to a context: Definitions of device driver context's events matching device events should be returned by overridden DeviceDriver.readEventDefinitions() method. Server plugins
950 880 ,

FieldFormat.STRING_FIELD);

format,

"Demo

Event",

ContextUtils.GROUP_DEFAULT);

should add events from inside install() and start() methods.

Java-based Agents should add events after Agent object creation via Agent.getContext(). addEventDefinition(). Finally, scripts (both server and widget scripts) should not normally add any events. For server-side events, it's might be also necessary to specify their expiration period and permission level
997 :

2000-2013 Tibbo Technology Inc.

996

AggreGate Documentation

// Setting permission level ed.setPermissions(ServerPermissionChecker.getManagerPermissions()); along with Agent events, must belong to a group remote.

Device events provided by a device driver

129 ,

Event group is specified by calling EventDefinition.setGroup(). You can use the following syntax: ed.setGroup(ContextUtils.GROUP_REMOTE);

Event Generation
Plugins, drivers and Agents may generate context events using fireEvent() method of Context interface. Here is an example: context.fireEvent("eventName", EventLevel.INFO, new Float(Math.random() * 1000000));

Format of data table passed to fireEvent() method must match format contained in event definition. Failure to follow this rule may result in data loss since the system will try convert the data table to definitionprovided format preserving as much data as it can.

7.4.7.4 Defining and Implementing Actions

When defining your own server context actions, it's necessary to specify properties of their definitions, i.e. name, description, format, permission level, help text, and group. To declare new action, create an instance of ServerActionDefinition object and set its properties. Here is an example: // Creating the definition and providing action implementation class ServerActionDefinition ad = new ServerActionDefinition("configurationWizard", // Setting action description ad.setDescription("Configuration

ActionImplementationClass.c

Wizard");

// Setting permission level ad.setPermissions(ServerPermissionChecker.getManagerPermissions()); Once done, add the action definition to a context by calling Context.addActionDefinition() method. Server plugins 950 and drivers 129 should add actions from inside install() and start() methods.

Action Implementation
Action implementation is the class extending ServerAction class. It must override execute() method that performs the actual action, i.e. the combination of server-side operations and interactions with a human operator. Once an action is launched by an operator (or in headless mode), a new instance of action implementation object is created and its execute() method is called. Here is an example of simple action implementation: public class ShowReportAction extends ServerAction { @Override public ActionResult execute(ServerActionInput parameters) throws ContextException { DataTable deviceStatusTable = getDefiningContext().getVariable("status", getCallerController()); String status = deviceStatusTable.rec().getString("statusMessage"); getProcessor().showMessage("Current Device Status", "Device Status: " + status); } }

Interaction with Operator

When an action is running, it may, at its discretion, decide to "talk" to a human operator that has launched it. These interactions are called UI procedures 896 .

2000-2013 Tibbo Technology Inc.

Development and Integration

All UI procedures are initiated by calling diverse methods of ServerActionCommandProcessor object that is accessible from within an action via getProcessor() method. Here is a non-complete list of available UI procedure calls: Method of ServerActionCommandPr ocessor editData() editProperties() editText() showEventLog() showMessage() showError() showReport() showSystemTree() confirm() browse() selectEntities() showGuide() UI Procedure

997

Edit Data

896 897

Edit Properties Edit Text

898

Show Event Log Show Message Show Error

899 900

898

899

Show Report

Show System Tree Confirm Browse

901 902 902

900

Select Entities

Start Interactive Tutorial

902

7.4.8 Dealing with Access Permissions

This section covers programmating handling of AggreGate Server security and permissions
931

issues.

Accessing Context Data

Many methods of the Context and ContextManager interfaces accept a parameter of type CallerController. Caller controller is an object that incorporates effective permissions of the calling side. There are two generic rules for using caller controllers: Any server-side code (device drivers 963 and plugins 969 ) must pass an instance of CallerController to every method that accepts it. Failure to do so will result to the None effective permission level of the calling side, thus making most calls fail with an error or return null values. Any remote code (applications using AggreGate Server API 961 or Java-based Agents 972 ) should use methods that do not accept caller controller or pass null as its value. This will perfectly work since client-side code does not perform permission checking, while the requested remote server-side operation will anyway incorporate permission level obtained during authorization (call to login() function of the root context).

Obtaining Caller Controller

Server-side code may obtain caller controllers in several ways: Create an instance of UncheckedCallerController to suppress any permission checking and get full access. This should be done only by some system code that is not assumed to execute operations with permissions of a certain system user. Get a caller controller by calling ServerContext.getCallerController() (or DeviceContext. getCallerController()). This controller will incorporate permission of system user 108 owning the device account 113 . This way of getting caller controllers mostly applies to Device Driver 963 code.

Extending Contexts
When device driver of server plugin adds definitions of variables, functions or events to a server context, it may assign custom permission levels to them using VariableDefinition.setReadPermissions(), VariableDefinition.setWritePermissions(), FunctionDefinition.setPermissions(), and EventDefinition.setPermissions() methods. If permission level of the definition is null, it will match permission level of the parent context. Note, setting definition's permission levels lower or equal to context's permission level is meaningless.

2000-2013 Tibbo Technology Inc.

998

AggreGate Documentation

To get predefined values of different permission levels, use the following code: Permission Level None Observer Operator Manager Engineer Administrator Code

ServerPermissionChecker.getNullPermissions() ServerPermissionChecker.getObserverPermissions() ServerPermissionChecker.getOperatorPermissions() ServerPermissionChecker.getManagerPermissions() ServerPermissionChecker.getEngineerPermissions() ServerPermissionChecker.getAdminPermissions()

8 Device Server Management

This section covers management of Device Servers.

8.1 HTTP Proxy Service

Let's say you have hundreds of Device Servers with embedded web servers, with each such Device Server providing access to a number of web pages. It is very easy to access every embedded Web Server when all of them have real static IP addresses. However, in real life, most Device Servers are installed in local networks protected by firewalls, and static IP addresses cost money. In this case, there is no way to access these Device Servers directly. The HTTP Proxy service solves this problem by providing a generic way to access all embedded web servers through AggreGate Server. It works like this: A Device Server with an embedded web server connects to the AggreGate Server. Its account 1003 should be configured to use HTTP Proxy mode. Someone wants to see the web pages from this particular Device Server, so they start a web browser and surf to a URL such as http://server.bigcompany.com/dev/admin/dev1/data.html The HTTP request sent by a browser is received and processed by the AggreGate Server AggreGate Server redirects the HTTP request to the admin.dev1 Device Server, to which it is currently connected. The Device Server processes the request and sends the data.html page to the AggreGate Server. AggreGate Server forwards this page to the browser.

For more information, see the HTTP Proxy 1011 chapter within the Device Drivers

129

section.

2000-2013 Tibbo Technology Inc.

Device Server Management

999

8.2 Dynamic DNS Service

The downside of the AggreGate Server 1000 is that it is slower than direct connection, because all the data must go through the AggreGate Server. This isn't critical for systems that do not produce a lot of traffic per each node. Still, there are times where you might want to create a direct connection to a device (for the sake of speed), but the IP address of this device changes from time to time (as is the case with most ADSL connections). You need a way to track the device down -- a way to overcome this and connect to one 'stable' address. You need to know that this address belongs to the Device Server you want, and be able to rely on it. This is where the dDNS Service comes in. With dDNS Service each of your Device Servers gets a "host name", which looks something like dev1.abccorp.dev.srv1.com (in this example the domain name of your server is srv1.com). You can always connect to your device using this hostname. This URL stays the same even when the IP address of the Device Server changes.

Since the actual connection is established directly to the Device Server you would have to be able to reach it -- i.e, if it has a firewall protecting it, the firewall must be appropriately configured. Configuration would be more complex than with the Link Service 1000 , but you would gain an increase in communications speed. In Dynamic DNS mode, Device Servers connect to the AggreGate Server on startup only, after obtaining IP address from DHCP server. After their registration in DNS they break connection with the AggreGate Server and act exactly as "normal" Device Servers, having no relations with AggreGate Server and other parts of AggreGate. In contrast to Link Service 1000 mode, no connection between Device Server and AggreGate Server is maintained. No data is transferred through the server.

Implementation Details
On the Device Server side, dDNS is enabled through dDNS registration (DD) setting. When this setting is at 1 (enabled) the DS registers on the dDNS Service as soon as it is powered up. During registration, the AggreGate Server creates two DNS entries: one for the external IP-address of the DS, and another one for its "internal" IP address. Example of two DNS entries for the same Device Server: For external IP address: dev1.abccorp.dev.srv1.com For internal IP address: dev1.abccorp.int.srv1.com

Dev1 is the device name, it comes from the Device Name (DN) setting of the DS. Abccorp is the owner name , it comes from the Owner Name (ON) setting of the DS.
Resulting host names are no different from any other host name (or URL) that you have ever used. Input such a name as a destination in any software that can connect to your Device Server and this name will be automatically resolved into current IP-address of this Device Server! This functionality is based on an industry-standard DNS protocol, so no special drivers or software are required for this to work. Device Servers are registered on the external DNS server, like BIND for *nix or Windows DNS Server.

2000-2013 Tibbo Technology Inc.

1000

AggreGate Documentation

Only those Device Servers that are registered 1003 at the AggreGate Server can connect to the dDNS Service. Each DS is identified by the AggreGate Server through a combination of data in its Device Name (DN) , Owner Name (ON), and Password (PW)settings.

DNS Server Compatibility

Dynamic DNS service is compatible with all DNS servers supporting dynamic updates, including Bind, Windows 2003 DNS Server, and more.

The Difference between Internal and External Addresses

The difference between the two types of addresses is rather simple. Usually the DS connects to a WAN through a router (firewall) which, in effect, "masks" the IP of the DS. So the DS can be, for instance, at 192.168.2.100 within its network segment (this is its "internal" IP), but the outside world sees it under a different IP address. This is the "external" IP of the DS. So, to recap: The "internal" IP is the actual IP address of the DS itself, such as 192.168.1.40. It is used within its own specific network segment. The "external" IP is the IP of the router which is set to forward the data to the DS on the inside. (Once more, this router will have to be set to do so -- this is not an automatic procedure, and is quite in addition to registering the Device Server in dDNS). To reach a DS from outside of its network segment you would need to use the external IP address. However, if you connecting from the same network segment you will need to know the device's "internal" IP address. This is why the AggreGate Server employs two types of dDNS records.

8.3 Link Service

Under normal circumstances, on a WAN, communicating with another node (host) on the network can be difficult due to the following factors:

Scarcity of Static IP Addresses

IP addresses on many networks (especially, the Internet) are now in short supply. This gave rise to several technologies that allow you to use available IP addresses more economically. Some examples of these technologies include: Dynamic IP addresses, whereby IP addresses of the hosts change from time to time, NAT (Network Address Translation) whereby several hosts communicate with the outside world through a single "external" IP address on a gateway. These technologies allow for each host to make outgoing connections (for example, to visit a website). However, it may be difficult (or actually impossible) to establish an incoming connection to such a host -- you either don't know its current address (because it's dynamic), or it doesn't even have an external address of its own.

2000-2013 Tibbo Technology Inc.

Device Server Management

1001

The only standard solution to this problem is to assign a static IP address to each host you need to connect to. These static IP addresses have to be obtained first. For example, you might need to lease them from your ISP. A single IP-address wouldn't cost much but when a given system is to have many nodes you end up spending considerable amounts of money. Even when the WAN is private and IP addresses are free, there are administration costs related to allocation of static IP addresses.

Firewalls blocking inbound traffic

Even assuming one has obtained necessary number of static IP addresses, there is still one more challenge: you have to actually connect to the Device Server. This may mean passing through firewalls. Firewalls usually restrict inbound traffic, so you will need to arrange opening ports, etc. This requires more work and increases the chances for possible security breaches (the more internal IP addresses or ports accessible from the outside, the greater the risk).

One possible solution to this is to configure all of the Device Servers for outbound connections, and have them connect to one specific network host. This could save leasing multiple IP addresses, so you would just need a single IP address for this host. Unfortunately, this also means that just this single host would be able to communicate with your Device Servers, as it would be configured as their destination. As you can see, this solution, too, is not an ideal one. So, what is the best way to interconnect Device Servers and their "client" hosts, when they are on different network segments, located behind firewalls, and have no static IP addresses? It is called Link Service.

Link Service
It is usually much easier for a network host to connect out than to accept an incoming connection. Unfortunately, with a normal link, at least one side must accept an incoming connection. Tibbo AggreGate Server provides a workaround for this problem by letting both sides of the link to communicate through a "middle-man" (Link Service), to which they both can establish outbound connections. When you and your friend use ICQ or MSN, you both connect to a central server. Neither of you typically has a static IP address, but the server has a static IP -- and this is what lets the "magic" happen. Both parties make outbound connections, so no firewalls have to be configured and neither side needs a static IP.

The Link Service is a very similar solution, only it is tailor-made for Tibbo Device Servers! Your Device Servers in the field connect to the Link Service (make outbound connections). Hosts that wish to communicate with Device Servers also connect to the AggreGate Server using outbound connections. Both sides meet 'at' the AggreGate Server and can thereby communicate through it.

Link Service: Implementation Details

2000-2013 Tibbo Technology Inc.

1002

AggreGate Documentation

Each Device Server that needs to use the Link Service has to be registered on the AggreGate Server first, i.e. have a Device Server Account 1003 . The AggreGate Server recognizes Device Servers through a combination of data in the following settings: Device Name (DN) , Owner Name (ON) and Password (PW). Each registered Device Server is assigned a unique port number during the registration. This is a port on the AggreGate Server to which any client wishing to communicate with this particular Device Server should connect.

The Device Server logs on to the AggreGate Server using its device name, owner name and password. Typically, the DS is preset to do so immediately when it boots (starts up). The AggreGate Server has a single port for Device Server logins -- 6450 by default. Because Device Servers are uniquely identified by their device name, owner name and password, a single login port for all Device Servers is sufficient. A "client" host who wishes to communicate with a particular Device Server establishes a connection to the AggreGate Server, to the specific port that was assigned to this Device Server during registration. The link is thus created and both sides may exchange data. A client host does not need any special login procedure to create this connection to the Device Server via the AggreGate Server. Instead of connecting to the IP address and port of the DS directly, it connects to the IP address of the AggreGate Server and to the port associated with a particular DS -- the difference is in parameter values only. Link Service feature is implemented through a Transparent Data Routing (Link Service) article for further details.
1010

Device Driver

129 .

See this

8.4 Device Servers, Device Server Accounts and External

Below we will cover the difference between hardware Device Servers, Device Server Accounts and External Device Servers. These terms are widely used throughout the manual, and it's important to form a clear distinction between them at this point. So, once more, AggreGate operates with three different types of "things": Hardware Device Servers Device Server Accounts
1003

External Device Server Accounts 1012 The first term refers to a piece of hardware. The latter two terms refer to logical parts of AggreGate Server software. It's important to understand that a single hardware Device Server may be treated by AggreGate as a normal Device Server (i.e, one with a Device Server Account) and also as external (i.e. one with an External Device Server Account) at the same time. A hardware Device Server may be configured to work with AggreGate Server as a normal Device Server, and log in to the server on power-up, but if AggreGate Server detects it while broadcasting 1013 for External Device Servers, an External Device Server Account is automatically created for it.

Hardware Device Servers

A Hardware Device Server is referred as a "Device Server" in most parts of this manual. It is a hardware device that

2000-2013 Tibbo Technology Inc.

Device Server Management

1003

is used to connect Devices 113 to the AggreGate Server. A hardware Device Server may be physically implemented as a separate device, or embedded into the design of a Device and placed on its printed circuit board (PCB). When the Device Server is a dedicated hardware device, it is usually connected to a Device using an RS-232, ZigBee or WiFi link. When the Device Server is embedded, communication between Device Server IC and main IC of the Device is performed by a serial interface. In an Agent 848 , the Device Server and Device are unified, both physically and logically. In this case, Device Server the logic is implemented by a custom application that runs in the programmable IC. Another part of the same application implements logic of the Device itself. When a hardware Device Server connects to AggreGate Server and tries to log in, the server checks if a corresponding Device Server Account exists and is not blocked.

Device Server Accounts

A Device Server Account is a special AggreGate Server context 863 that contains information about a single hardware Device Server that may connect to AggreGate Server. This account defines the password that should be used the by the hardware Device Server to log in, the Device Driver 129 that will process data received from the hardware Device Server and some other options. It is technically possible to create a Device Server Account that does not match any hardware Device Server. Such accounts may be used for testing, debugging, etc. In contrast to External Device Server Accounts, normal Device Server Accounts are used to "accept" connections of hardware Device Servers. Every hardware Device Server that is supposed to connect to the AggreGate Server and exchange data with it should have a corresponding Device Server Account.

External Device Server Accounts

The primary purpose of External Device Server Accounts is to allow AggreGate Server to access hardware Device Servers that are not configured to connect to the AggreGate Server themselves. In most cases, this is necessary during initial configuration of new hardware Device Servers that were just plugged in to the network and powered up. The difference between account types is that External Device Server Accounts are used by AggreGate Server to initiate outgoing connections to any local hardware Device Servers, while normal accounts allow AggreGate Server to accept incoming connections from "known" hardware Device Servers. Every External Device Server Account contains information about the IP or MAC address of a corresponding Device Server, the communication method used to access it and some other connection-related information. During day-to-day use of AggreGate Server, External Device Server Accounts are used to perform initial configuration of hardware Device Server so they'd work with AggreGate Server (i.e, connect to it on startup). When a hardware Device Server is properly configured and connected to the AggreGate Server, a normal Device Server account should be used to manage it. To simplify things, External Device Server Accounts are referred simply as "External Device Servers" in this manual.

8.5 Device Servers

A Device Server is a hardware device acting as a "bridge" between one or more Devices It has several important purposes: Network-enabling one or more Devices Allowing AggreGate Server to discover Devices Connecting and logging in to the AggreGate Server on power-up and routing data between AggreGate Server and Device(s) In AggreGate, every Device must be logically connected to the AggreGate Server through a Device Server. Physically, the Device Server may be implemented in several different ways: As a separate hardware device. In this case, the Device may be connected to it using an RS-232, WiFi or ZigBee link. As an embedded ethernet module, built into the Device, hooked up to its existing components. As a part of a programmable integrated circuit (IC) serving as the a main IC of a Device. In this case, Device Server logic is implemented by a special Agent 848 application running on this IC.
113

and the AggreGate Server.

2000-2013 Tibbo Technology Inc.

1004

AggreGate Documentation

It is important to remember that while a Device Server and a Device may be joined physically, AggreGate always treats them as two separate logical units. For a Device Server to connect to AggreGate Server and log in, you have to create a Device Server Account for it. A Device Server Account is a persistent record in the AggreGate Server database 80 that says something like: Device Server named "device1" (same as Device Name setting of the Device Server) is owned by AggreGate Server user " user1" (corresponds to the Owner Name setting of the Device Server) and is permitted to login to AggreGate Server using the password "pass1". Two terms are widely used in this article: hardware Device Server and Device Server Account. The difference between them is further described in a separate article 1002 . A Device Server Account also includes other settings that define how AggreGate Server treats data received from the Device Server and what type of data (i.e, whether to send commands or just a data stream, etc) it sends the Device Server. These settings are explained later on, in Device Server Properties 1006 . A Device Server Account may or may not correspond to an existing hardware Device Server. Simply put, you can create an account even for a Device Server which doesn't exist. If several Device Servers will to login using a the credentials for the same account, only one will be able to stay connected simultaneously. Every hardware Device Server should have a dedicated Device Server account. Device Server Accounts always belong to AggreGate Server users and are therefore registered under user accounts Every user has his own set of Device Server Accounts. By default, every user can manage his own Device Server Accounts. Users with enough permissions default administrator) can also manage Device Server accounts belonging to other users.
931 108 .

(including the

All operations with Device Servers are affected by the Timeouts for Device Server Operations settings of the Device Server plugin.

1009

global

HOW DEVICE SERVERS INTERACT WITH AGGREGATE SERVER

After being powered-up, every hardware Device Server that is properly configured to work with AggreGate initiates a connection to AggreGate Server and completes a login sequence 1005 . When this sequence is complete, AggreGate Server passes control of this AggreGate Server to the Device Driver 129 configured for it in its account. This driver determines what data is to be sent to the Device Server, and how to process data received from it. When a Device Server is logged on to the AggreGate Server, you can: Configure its internal settings Buzz 1008 or reboot
1008 1006 .

it.

Monitor data 1008 flowing to and from the Device Server Control, configure and monitor Devices
113

connected through it.

CREATION OF DEVICE SERVER ACCOUNTS

There are three different ways to create Device Server Accounts: Manual registration. This method is suitable if the Device Server was configured to work with AggreGate Server manually 1015 , and automatic registration 1005 of Device Server Accounts is disabled. In this case, the hardware Device Server will not be able to log in to the AggreGate Server until a corresponding account is created for it, using the New Device Server 1024 action of a Device Servers context. The Owner name setting of a hardware Device Server must match the name of the user owning this account, the Device name setting must be the same as the account name, and the passwords specified in the settings of the hardware Device Server and its account must also match. The Device Server's network settings should be configured so that it connects to the AggreGate Server on power-up. Then it will successfully log on. Automatic registration. If the hardware Device Server was manually configured 1015 to connect to AggreGate Server, and automatic registration 1005 of Device Server Accounts is enabled, and a user 108 exists whose name matches the Owner name setting of this hardware Device Server, a new Device Server Account will be automatically created when the hardware Device Server tries to log in to the AggreGate Server. See login sequence 1005 for details. Registration using the "Connect External Device Server to AggreGate Server" procedure . When an external Device Server (one which isn't registered) is being configured to connect to the AggreGate Server on startup by the AggreGate Server itself, the corresponding Device Server Account is registered automatically during this operation. See this section 1013 for more information. This is the recommended procedure. It ensures that

2000-2013 Tibbo Technology Inc.

Device Server Management

properties 1006 of the Device Server Account match to the settings easiest to perform.
1006

1005

of the hardware Device Server, and it's the

Administering Device Servers

Two contexts are used to administer Device Servers: One is the general Device Servers 1024 context that acts as a container of all Device Server Accounts belonging to a particular user. The other is the Device Server 1018 context, corresponding to a single Device Server Account. There is one additional context that may used to manage Device Servers: All Device Servers context that is located under the Root 726 context. This context provide access to all Device Servers in the system and grouped actions 894 for them. It is visible only if current user has effective permission level 931 Admin in the Root context.

Login Sequence
This is how a hardware Device Server logs in to the AggreGate Server: 1. On power-up, the hardware Device Server establishes a TCP connection with the AggreGate Server. The address and port of the AggreGate Server are defined by the Destination IP and Destination Port settings of the hardware Device Server. If some problems occur during the connection, the Device Server plays an error pattern 1018 using its green and red status LEDs. 2. When the connection is established, the hardware Device Server starts exchanging commands with the AggreGate Server. 3. AggreGate Server verifies that the Device Server firmware is capable of working with it. If not, the connection process is aborted. 4. AggreGate Server inspects the Owner Name setting of the hardware Device Server. If a user account whose name matches this setting does not exist, the connection is aborted. 5. A similar inspection is performed for the value of the Device Name setting. If a Device Server Account with this name does not exist under the user account determined on the previous step, the connection is aborted. However, if both Enable Automatic Registration of Device Servers in Device Servers Plugin user-level configuration 1009 and AggreGate Server Auto-registration in the settings of the hardware Device Server are enabled, a new Device Server Account is now created. See Auto-registration of Device Server Accounts 1005 for more information. 6. If the Device Server account exists but is blocked, the connection is also aborted. 7. If the password defined in the settings of the hardware Device Server does not match the password defined in Device Server Account properties, the connection is aborted. 8. The Device Server is registered in DNS
999

if this option is enabled in account properties

1006

9. If Device Driver setting is set to Auto Detect, AggreGate Server asks Device Server which Device Driver 129 is desired for it. When Device Server provides type of driver, it is stored in the settings of Device Server account and will be used during subsequent logins. If Device Server is unable to provide driver type, Dynamic DNS 1010 driver will be used for this account. 10. The Device Driver 129 defined in the settings of the Device Server Account starts processing data received from the hardware Device Server and the Device(s) connected to it.

Auto-Registration Of Device Server Accounts

This feature allows Device Servers which are unknown to the AggreGate Server (i.e. which have no corresponding Device Server Account) to register automatically on the server. For this to work, several conditions have to be true: 1. The hardware Device Server must be property configured
1015

to connect to the AggreGate Server on power up,

2. The AggreGate Server Auto-registration (AR) setting of the hardware Device Server that is supposed to autoregister itself has to be enabled, 3. The Enable Automatic Registration of Device Servers parameter must be also enabled in the in Device Servers Plugin user-level configuration 1009 or user those name matches the Owner name of the hardware Device Server Once these conditions are met, and the Device Server tries to log in to the AggreGate Server when it is not yet registered (i.e. has no Device Server Account), AggreGate Server creates a new Device Server account with the default settings for it. After auto-registration takes place, hardware Device Server disconnects from the server and reconnects within several seconds. It now has an account, and should be able to log in.

2000-2013 Tibbo Technology Inc.

1006

AggreGate Documentation

See the login sequence 1005 for more information.

Auto-registration should be disabled in production systems for security reasons. It is suggested to enable it for a limited time only to speed up deployment of the AggreGate in your facility.

Device Server Account Properties

These properties may be accessed using the Edit Device Server Properties Owner Name Device Server Name Password Description Register in DNS Blocked Inband commands allowed for client
1018

action from any Device Server context.

Username for the Device Server owner. Corresponds to the Owner Name setting of the Device Server. Read-only property. Name of Device Server Account (also, name of the Device Server 1018 context). Corresponds to the Device Name setting of the Device Server. Read-only property. Account password. Device Server must use the same password during its login sequence Comments about the account or hardware Device Server. Defines if the Device Server should be registered in DNS Server.
999 1005.

during its login to AggreGate

Device Server is not allowed to log in if its account is blocked. Indicates that the Device Driver 129 associated with this account may send commands to Device Server. Most device drivers do not send commands on their own, but some of drivers forward commands received from the third-party client application that controls the hardware Device Server. For these commands to transfer to the Device Server reliably, this setting must be enabled. The word "inband" here merely refers to the fact that the commands are embedded within the TCP data stream going from the AggreGate Server to the Device Server. All commands are "inband" in AggreGate Server - this is just a legacy designation, from a time when Device Servers were normally controlled over UDP (outside of the TCP data stream, and thus, "out of band"). This option should be disabled in most cases, unless you know it should be used with your device driver. If the device driver sends or forwards inband commands to the Device Server while this option is disabled, the Device Server won't be expecting the commands and won't "understand" them. Thus, the stream of data arriving to it will be considered "corrupted".

Time Zone Device Driver

Time zone where this Device Server and all connected Devices 113 are located. More information on this can be found under Dealing with Time Zones 108 . Defines which Device Driver Server.
129

is used by AggreGate Server to work with this Device

Auto Detect value causes AggreGate Server to ask Device Server about the desired driver type during its first login. Auto-detected driver type will be stored in account properties and used during future logins of this Device Server.

Editing Settings Of Hardware Device Server

You can change the settings of hardware Device Servers when they're online (connected to the AggreGate Server). This feature was previously implemented in the DS Manager software shipped by Tibbo. Device Server settings are accessible using the Configure Device Server 1018 action from any Device Server 1018 context. Once the new settings are saved, the user is prompted to reboot the Device Server. Changing some settings (such as Network Settings) of the hardware Device Server may prevent it from connecting to the AggreGate Server after reboot. In this case it may become completely unavailable for AggreGate, especially if it is located in a remote local area network protected by firewall or other methods. Be careful when editing settings of the hardware Device Server. Here is what a Device Server settings dialog looks like in AggreGate Client:

2000-2013 Tibbo Technology Inc.

Device Server Management

1007

Device Server Status

You can use the View Device Server Status
1019

action of any Device Server context to see what's going on with it:

Account status includes the following: Online Device Driver status Bytes transferred from Device Server to AggreGate Server Bytes transferred from AggreGate Server to Device Server Creation Time Last Update Time Last Login IP Indicates that Device Server is online (connected to the AggreGate Server and logged in). Status of the Device Driver driver-dependent.
129 .

Reported by the driver itself and thus is

Amount of data sent to Device Server. Amount of data received from Device Server. Read-only property, showing when account was created. Read-only property, showing when account properties were last updated. IP address from which Device Server last logged in. This is an "external" address, i.e. an address on which the Device Server is visible to the

2000-2013 Tibbo Technology Inc.

1008

AggreGate Documentation

AggreGate Server. Last Login Port Last Login Time Internal IP Port number from which Device Server logged in last time. Time when Device Server logged in last time. The internal IP that was set in Device Server when it last logged in. This is the Device Server's address in its local network. It the IP Address setting on the Device Server. It may or may not be the same as the "external" address (Last Login IP, above).

Other Device Server Operations

Two other operations can be executed on Device Servers: Reboot Buzz These may be accessed through any Device Server 1018 context.

BUZZING
Buzz lets you to visually match a Device Server Account to an actual physical Device Server. It makes the hardware AggreGate Serverplay a fast-blinking pattern on its red and green status LEDs. This way you can easily identify which AggreGate Server a particular account corresponds to.

REBOOTING
This operation reboots the hardware Device Server. Rebooting may be required when settings of Device Server were changed in order to activate them.

Data Flow Monitoring

This lets you monitor the raw data being sent and received from a hardware Device Server in real-time, and view a log of the data routed earlier. You can use the View Data Flow 1019 action of any Device Server context to access this function. This action starts Event Log that monitors two event types: Device Server to AggreGate Server (in) AggreGate Server to Device Server (out) You can view both real-time occurrences and the history of these events. Open a particular event to view if there's not enough space to show it in the Event Log itself. Here is what monitoring the data flow looks like in AggreGate Client:
896 898

an

all its data

2000-2013 Tibbo Technology Inc.

Device Server Management

1009

8.6 Device Server Plugins

Device Server Plugin is a type of plugin 950 that defines how AggreGate Server interacts with the stream of data received from a given Device Server. This usually means interacting with hardware devices connected to AggreGate using these Device Servers.

Setting Levels
Every Device Server plugin has up to three levels of settings: Global Settings. These affect the overall behaviour of plugin. Global settings may be edited only by users with sufficient permissions. User-level Settings . These affect the behaviour of a plugin only if it is assigned to a Device Server that belongs to a certain user account 108 . When the pugin is processing data from a particular Device Server, it uses the user settings stored in the owner's account. Device Server-level Settings . These settings affect the behaviour of the driver assigned to a certain Device Server Account 1003 . When the driver is processing data from a particular Device Server, it uses the Device Server settings that are stored in the Device Server's account. Most Device Server plugins do not use all three setting levels. New Device Server Accounts use the Device Server Plugin defined by the Default Device Server Plugin 53 global configuration setting. The plugin type may be later changed by editing settings of Device Server Account.

Administering Device Server Plugins

Two context types are used to administer Device Server Plugins: first is the general Drivers/ Plugins Configuration 685 context, which serves as a container. The other is the Driver/Plugin Configuration 686 context, which holds the configuration for a single plugin. These appear in two places: Under the Root Under the User
726 759

context, where they contain global settings context, where they contain user-level settings

If a given plugin doesn't contain settings on one of these levels, the corresponding configuration context will not be created (i.e, won't exist in the System Tree). Device Server Level settings for a driver may be accessed using the Configure Device Driver 1019 action of a Device Server 1018 context.

Device Servers Plugin

Device Servers Plugin is a plugin 950 that handles all generic Device Server communications and data handling. It interacts with the individual Device Server-specific plugins that are responsible for processing data from certain Device Servers. The Device Servers Plugin has the following global settings: Port number to listen for Device Server connections (0 to disable). This option defines the port number for Device Server logins, i.e. the port to which Device Servers should establish connections. If set to zero, non-secure Device Server connections are not allowed. Default Device Driver. This options defines which Device Driver 129 is used for processing data by a newly created Device Server 1003 context. This is the ID of the default driver, not its name. This option is normally edited through a GUI (such as AggreGate Client), which includes all needed IDs. Finding the correct driver ID for manually entering it in the configuration file is beyond the scope of this manual. This option defaults to a Dynamic DNS 1010 driver. If this options is set to Auto Detect, AggreGate Server will set Device Driver option in the settings of newly created Device Server account 1003 to Auto Detect. The actual driver to be used will be provided by the Device Server during its first login and stored in the settings of Device Server account. Timeout for ordinary commands . This option specifies the timeout for normal Device Server operations (login, configuration of external Device Servers etc.) Timeout for inband commands (seconds). This option specifies the timeout for commands that are sent to Device Server while it stays connected to the AggreGate Server. This applies to all Device Servers that through normal Device Server Accounts and to the External Device Servers 1012 that are configured using TCP inband commands. Timeout for broadcast commands (seconds). This option specifies the timeout for commands that are sent in broadcast mode, for example during auto-discovery of External Device Servers 1012 .

2000-2013 Tibbo Technology Inc.

1010

AggreGate Documentation

The Device Servers Plugin has one user-level setting: Enable Automatic Registration of Device Servers. Defines that Device Server Accounts 1003 should be automatically created for Device Servers that try to log in and have auto-registration on AggreGate Server setting enabled. See Auto-registration 1005 in Device Servers chapter for details.

8.6.1 Transparent Data Routing (Link Service)

Transparent Data Routing Device Server plugin implements Link Service 1000 functionality. When this driver is enabled in the Account Properties 1006 for a given Device Server, as soon as that Device Server becomes connected, AggreGate Server starts to listen for TCP connections on a dedicated "client port" which is specified in the driver settings. If some hardware (such as another Device Server), or software (some PC application) client connects to this port, AggreGate Server starts acting as a "pipe": It transparently routs data between this client and the hardware device connected to the Device Server. It forwards all data received from the Device Server (actually, from the hardware device "behind" the Device Server) to the Client. All data received from this Client is forwarded back to the Device Server (and the Device Server forwards it to its "other" side, i.e. hardware device). See Link Service 1000 for more information.

Plugin Information
Plugin ID: com.tibbo.linkserver.plugin.device.transparentlink

Global Settings
Lowest number of port assigned to Device Servers. Default is 50000. Highest number of port assigned to Device Servers. Default is 60000. These two options define a range of ports that can be assigned for Client connections in the Device Server settings of this driver. This range can be overridden in User-level Settings. Comma-separated list of ports never assigned to Device Servers. Exceptions from the above range. This ports cannot be assigned to Clients neither automatically nor manually.

User Level Settings

Lowest port number that can be assigned to Device Servers under this account. Highest port number that can be assigned to Device Servers under this account. These options override the Client port range defined in the Global Settings.

Device Server Level Settings

Port number for client connections (zero for auto-assignment). Default is zero. This port is used by clients to connect and send data to this particular Device Server and Device. The driver listens on this port only after Device Server connects and logs in to AggreGate Server. Only one client can connect at the same time, other connections will be rejected. If this setting is set to zero, the driver will find a free port (one which is not assigned to any other Device Server) in the port range specified by Global or User Settings and set a new value to this setting. Port autoassignment is performed during the the Device Server's first login, and in future logins this Device Server always gets the same port number because its internal setting was changed. You can check which port was assigned to the Device Server by viewing 686 driver settings after Device Server has been logged in. Device Server control. Possible values are None and DTR line indicates Client connection status. In the second case, Device Server's DTR line is raised by sending an inband command to it when new Client connects to the client port of the Device Server. DTS line is dropped upon Client disconnection. Client control. Possible values are None and Drop Client on DSR pulse . In the second case, existing Client connect is terminated if two subsequent DSR line state change notifications are received from a Device Server within short period of time.

8.6.2 Dynamic DNS

Dynamic DNS Device Server plugin is enabled for newly created Device Server accounts 1003 , as specified by the default value of the Default Device Server Plugin 53 global configuration setting. This driver simply discards any data received from the Device Server and never tries to send anything to it. It is called Dynamic DNS because it allows Device Server to login to AggreGate Server, get registered in DNS 999 and then disconnect. It can be also used to test Device Server connections.

2000-2013 Tibbo Technology Inc.

Device Server Management

1011

Despite the name of this driver, Dynamic DNS functionality is built-in to the AggreGate Server core. Dynamic DNS driver just helps Device Servers to stay connected after logging in. It acts like a "stub" that does nothing with a connected Device Server. It other words, it maintains an active connection without any actual data transfer. While the connection is active, a user can check a Device Server's status, configure, reboot or buzz it etc. See more info in the Device Servers 1003 chapter. To ensure that Device Server will be registered in DNS upon login to AggreGate Server, check that: Dynamic DNS is enabled and properly configured in AggreGate Server global settings Register in DNS setting is enabled in Device Server account settings 1006 See Dynamic DNS Service
999 61

for more information.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.stub

Global Settings
None defined.

User Level Settings

None defined.

Device Server Level Settings

None defined.

8.6.3 HTTP Proxy

HTTP Proxy Device Server plugin allows you to access the embedded Web Servers of Device Servers 1003 currently connected to AggreGate Server which are located in private networks or have no static IP addresses. This is done using HTTP. When AggreGate Server is started, this driver installs a special web application into the AggreGate Server's embedded Web Server. This application turns AggreGate Server into the HTTP proxy server allowing to access web pages contained in the Device Servers connected to it and working through the HTTP Proxy driver.

NEW TERM: A proxy server is software which lets clients make indirect network connections to other
network locations. The client connects to the proxy server, requests a connection, file, or other resource available on a different server, and the proxy accesses the resource for the client and relays it to the client. More information about the HTTP Proxy service may be found under HTTP Proxy Service section.
998

in the System Basics

30

When the driver is running, the following URLs may be used to access web page provided by the Web Server embedded into the Device Server connected to AggreGate Server:

https://server_address/dev/device_server_owner/device_server_name/page_path/page_name http://server_address/dev/device_server_owner/device_server_name/page_path/page_name
The first example uses a secure HTTPS connection between the Web Browser and AggreGate Server. The second example shows a non-secure HTTP connection.

server_address is the IP of the AggreGate Server or one of the DNS addresses defined in the Host Name Aliases
. If a DNS address is used, it should also be properly configured in DNS (i.e, you also have to configure your DNS server and make sure you can indeed reach the AggreGate Server's IP via this DNS address).

60

device_server_owner is the name of the user account

108

under which the Device Server is registered

device_server_name is the name of Device Server Account 1003 page_path and page_name should point to the requested page in the Device Server's embedded Web Server.

2000-2013 Tibbo Technology Inc.

1012

AggreGate Documentation

Example:

https://ls.nuclear-sub.com/dev/admin/thermometer/gui/view_temperature.html
This URL will provide access to the page /gui/view_temperature.html contained in the Web Server embedded into the Device Server admin.thermometer when it is connected to AggreGate Server. It assumes AggreGate Server is accessible via the ls.nuclear-sub.com address. The requested page will be viewed through a secure connection, even if connection between AggreGate Server and Device Server is not secure. HTTP Internal Server Error (Error 500) is shown by the HTTP Proxy Web Application in the following cases: User specified in the URL does not exist Device Server specified in the URL does not exist Device Server is offline Device Server is not working through the HTTP Proxy driver See HTTP Proxy Service
998

for more information.

Driver Information
Driver Plugin
129

ID:

com.tibbo.linkserver.plugin.device.httpproxy

Global Settings
Enable HTTP Proxy web application. Enables/disables access to HTTP Proxy.

User Level Settings

None defined.

Device Server Level Settings

None defined.

8.7 External Device Servers

External Device Servers, or External Device Server Accounts, let AggreGate Server access hardware Device Servers that are not able to initiate a connection to the server. This feature is often used when setting up new hardware Device Servers that are not yet configured to log into AggreGate Server automatically on startup. External Device Server Accounts can also come in handy when troubleshooting hardware Device Servers that have problems connecting to the AggreGate Server. The difference between hardware Device Servers, Device Server Accounts and External Device Server Accounts is covered here 1002 . External Device Server Accounts are used to store the parameters used by AggreGate Server to access hardware Device Servers by their IP or MAC address. If AggreGate Server cannot access a hardware Device Server (e.g. it is located in a remote Local Area Network, protected by firewall), there is no way to access it using the External Device Server facility. There are several ways to overcome this and make a hardware Device Server connect to AggreGate Server on startup: Temporarily plug it into another network segment that AggreGate Server can access, and then access it as an external Device Server. Once the Device Server is configured and ready to establish a link with AggreGate Server on startup, you can plug it back into its original network and it'll initiate an outgoing connection to the AggreGate Server. Temporarily reconfigure the firewall, router or other network equipment to allow AggreGate Server access hardware Device Servers as an External Device Servers. Once all hardware Device Servers are configured and ready to initiate a connection to the AggreGate Server, the original network configuration may be restored. Use DS Manager software from a PC that resides in the same network segment with the hardware Device Server (or can otherwise access it). Device Server Manager software is part of the Device Server Toolkit package provided by Tibbo.

2000-2013 Tibbo Technology Inc.

Device Server Management

1013

The basic concept of External Device Server Accounts is that they are used to access and configure new hardware Device Servers only. This facility should not be used for working with Device Servers which are already configured to connect to AggreGate Server.

Administering External Device Servers

Two contexts are used to administer External Device Servers: One is the general External Device Servers 1030 context, for actions related all External Device Servers. The other is the External Device Server 1027 context, corresponding to a single External Device Server Account.

Device Server Discovery

Device Server Discovery is the process of locating all hardware Device Servers in the local network segment and automatically creating External Device Server Accounts for them. A local network segment means there are only network hubs (no routers, bridges, firewalls, etc.) between the PC and all other devices on that segment. Hardware Device Servers which are located behind a router (i.e, you have the computer running AggreGate Server, and to actually get to the Device Server its packets need to go via a router) cannot be auto-discovered by AggreGate Server because the broadcast UDP datagrams used to find them on the network are not forwarded by the router. However, it is still sometimes possible 1014 to use the External Device Servers facility to connect such Device Servers to the AggreGate Server, if they can be accessed by their IP addresses. Each discovered Device Server is uniquely identified by its MAC-address, which is different for every Device Server manufactured. Discovery will detect all local Device Servers even if some of them have the same IP-address or an IPaddress which is invalid or unreachable. A correctly configured IP-address is not required for the AggreGate Server to be able to access AggreGate Server in the discovery mode. During the discovery process, AggreGate Server creates a new External Device Server 1027 context (account) for every hardware Device Server detected. All External Device Server contexts that were created during previous executions of discovery are destroyed before creation of new contexts. There's no way to "manually" create an External Device Server Account, only using the discovery process. If automatic discovery of Device Servers is disabled and it was not launched manually, External Device Servers context does not contain any Device Server accounts.
1030

AUTOMATIC DISCOVERY OF DEVICE SERVERS

AggreGate Server can discover Device Servers automatically. Automatic discovery is performed by Discover and Connect External Device Servers 1017 scheduled job. It's possible to turn off auto-discovery by disabling this job, or change discovery schedule by editing it's triggers. If Try to auto-connect Device Servers to AggreGate Server option of the job is enabled, AggreGate Server tries to auto-connect 1014 each discovered Device Server.

Connecting External Device Servers to the AggreGate Server

Connecting an External Device Server to AggreGate Server is the process of reconfiguring a hardware Device Server to make it connect to the AggreGate Server immediately after startup. There are several ways to do this: 1. Connecting a previously discovered 1013 Device Server using its account
1027 .

2. Automatically connecting all discovered Device Servers to AggreGate Server without user interaction. 3. Manually configuring discovered a Device Server that was not successfully connected by the above functions. 4. Manually connecting a Device Server that was not detected by the discovery process but may be accessed by AggreGate Server.

CONNECTING A PREVIOUSLY DISCOVERED DEVICE SERVER TO AGGREGATE SERVER

This procedure is initiated by the Connect Device Server to AggreGate Server 1027 context. The user must specify
896 1027

action of the External Device Server

several parameters before connection process is started:

2000-2013 Tibbo Technology Inc.

1014

AggreGate Documentation

Connection Type. "Permanent (Work with AggreGate Server)" or "Dynamic DNS only (disconnect immediately after registration in DNS)". See Connection Modes 1014 for details. Login Password. Required if a password is defined in the settings of the hardware Device Server. This password will be used by AggreGate Server to access the settings of the hardware Device Server. Owner Name. Name of the AggreGate Server user 108 who will own (or already owns) a Device Server Account 1003 that will be used to authenticate this hardware Device Server during its login to AggreGate Server. The "Owner name" setting of the hardware Device Server will be set to this value. Device Server Name. Name of the above Device Server Account Server will be set to this value.
1003 .

Device name setting of the hardware Device

Force connection even if Device Server is already configured for AggreGate Server or has incompatible firmware. By default, the connection procedure fails with an error message if the Device Server is already configured to connect to the AggreGate Server or has an outdated firmware version (one that doesn't fully support automated configuration for AggreGate Server). This option disables checking of the Device Server setting values and its version number. The forced connection operation will complete successfully, but Device Server may not be able to actually connect to the AggreGate Server or log in. If the Device Server does not login to the AggreGate Server within several seconds after the forced connection procedure has been completed, proceed to the manual configuration 1015 section. The connection sequence is described here
1015 .

AUTOMATIC CONNECTION OF DISCOVERED DEVICE SERVERS TO AGGREGATE SERVER

If the Try to auto-connect Device Servers to AggreGate Server option of Discover External Device Server 1013 scheduled job option is turned on, AggreGate Server automatically executes the Connect discovered Device Server to the AggreGate Server 1013 procedure for every Device Server detected during the discovery 1013 process. This option is disabled by default, for security reasons. It useful for quickly connecting multiple Device Servers that are plugged into the local network segment. Automatic connection fails if: The Device Server requires a password to access its settings, or The Device Server is already configured for connection with the AggreGate Server on startup, or The Device Server's firmware does not support auto-connection.

CONNECTING A DEVICE SERVER THAT WAS NOT DISCOVERED BUT IS ACCESSIBLE BY AGGREGATE SERVER
This procedure should be used to connect a hardware Device Server to AggreGate Server that wasn't discovered, but can still be accessed by AggreGate Server. This is suitable, for example, if the Device Server is not located in the same local network segment as the AggreGate Server, but its IP address is accessible to the server. All connection parameters required to access the Device Server should be specified manually for this procedure. Is is initiated by the Connect Device Server to AggreGate Server 1030 action of the External Device Servers 1030 context. To connect a non-discovered Device Server you need to specify the following options: Connection Type. Permanent (Work with AggreGate Server) or Dynamic DNS only (disconnect immediately after registration in DNS). See Connection Modes 1014 for details. Access method . One of Broadcast (UDP), Out-of-band (UDP), Inband (TCP) or Telnet (TCP). MAC address. Should be specified in the case of broadcast access. IP address. Should be specified if access method is not broadcast. Port Number. If specified, this port will be used to contact the Device Server instead of the default port for the selected access method. Owner Name. See description above. Device Server Name. See description above. Force connection even if Device Server is already configured for AggreGate Server of has incompatible firmware. See description above. Connection sequence is described here
1015 .

CONNECTION MODES
A hardware AggreGate Server may be configured to work with AggreGate Server in two different modes: Normal mode Dynamic DNS only mode

2000-2013 Tibbo Technology Inc.

Device Server Management

1015

Normal mode assumes that the Device Server connects to the AggreGate Server on startup and stays connected for an unlimited period of time. All data that is sent or received from it is processed by the Device Drivers 129 defined in the Device Server 1003 Account. In most cases Device Servers should be connected to the AggreGate Server in normal mode. Dynamic DNS only mode forces the Device Server to disconnect from AggreGate Server immediately after connection. The only thing performed by the server when the Device Server connects is to register it in the Domain Name System (DNS). After disconnecting from AggreGate Server, the Device Server acts as a normal ethernet-to-serial bridge. It does not interact with AggreGate anymore until next power-up. See Dynamic DNS (dDNS) Service 999 for more information on how this mode may be used.

CONNECTION SEQUENCE
The procedure of configuring a hardware Device Server to connect to AggreGate Server on startup involves several steps: 1. If neither a MAC nor IP address is not specified in connection settings, connection process fails with an error 2. If the access method is set to Inband (TCP) or Telnet, AggreGate Server tries to establish an outgoing TCP connection with the Device Server. 3. AggreGate Server tries to detect the proper value for the Destination IP setting of a hardware Device Server (i.e, where should the hardware Device Server connect to). If the Server IP Address 54 global configuration setting of AggreGate Server is defined, the Destination IP is set to its value. Otherwise, AggreGate Server sends a special command, "Tell me my IP address ", to the Device Server. The Device Server inspects the command packet and sends back the IP address from which the command was sent. This way, the server "knows" what IP address is visible for it on the Device Server side (i.e, where the Device Server "thinks" the server is at). If hardware Device Server in moved to another network segment after "Connect to the AggreGate Server" procedure, it may be necessary to change its "Destination IP" setting to the IP address at which the AggreGate Server is available from its new network location. 4. AggreGate Server tries to log in to the Device Server and access its configuration. The password defined in the parameters of "Connect to AggreGate Server" operation is used. 5. If Force connection even if Device Server is already configured for AggreGate Server or has incompatible firmware setting is disabled, the version of Device Server is checked to be compatible with the AggreGate Server. If it is too old, connection procedure fails. 6. If Force connection is disabled, AggreGate Server tries to detect if the Device Server is already configured to connect to this specific AggreGate Server on startup and stops the connection process if this check succeeds. Alternatively, if this setting is enabled, AggreGate Server will overwrite Device Server settings anyway, to make a best-effort attempt to make it connect to AggreGate Server. 7. At this point AggreGate Server decides which user 108 and Device Server 1003 accounts should be used by the connected hardware Device Server If the Owner name and Device name parameters are specified, they are used as the user and Device Server account respectively. If not, AggreGate Server reads Owner name and Device name settings from the hardware Device Server and uses these values as names of user and Device Server accounts. 8. If the user account determined at the previous step does not exist or is inaccessible by the user initiating the connection procedure, the procedure fails with an error. 9. The hardware Device Server settings are now changed to make it to connect to the AggreGate Server on startup. To learn what settings are changed and their new values, see Manual Configuration for AggreGate Server 1015. 10. If a Device Server Account 1003 with the name determined at step 7 exists, its settings are updated let let the new hardware Device Server connect. Otherwise, a new Device Server Account is registered automatically. 11. The hardware Device Server is rebooted. After the above steps Device Server should connect and log in to the AggreGate Server within several seconds. If this doesn't happen, check the Device Server status LEDs 1018 to find out what's going on with the Device Server. You can then use manual configuration (see immediately below) to troubleshoot the connection.

MANUALLY CONFIGURING DEVICE SERVERS TO CONNECT TO THE AGGREGATE SERVER

These are settings of a hardware Device Server that must be properly configured for it to connect and login to the AggreGate Server. These settings may be accessed using the Configure Device Server 1028 action of any External Device Server 1027 context. Setting Owner name Device name Value Name of user
108

owning Device Server

1003

Account

Name of Device Server Account

2000-2013 Tibbo Technology Inc.

1016

AggreGate Documentation

MAC-address IP-address Registration at dDNS Server Auto-registration on AggreGate Server PPPoE mode Gateway IP-address Subnet mask Connection timeout Transport protocol Link Service login Routing Mode Connection mode Destination IP-address Destination port

Must be set to any valid MAC address that is unique within the local network segment. Default value is suitable in most cases. Must be properly configured for the local network environment. Disabled Enabled Disabled Must be properly configured for the local network environment. Must be properly configured for the local network environment. Disabled (0 minutes) TCP Enabled Client only Immediately (on powerup) IP address of the AggreGate Server Must be equal to the value of the Port number to listen for normal Device Server connections 1009 global AggreGate Server configuration setting.
1014 ,

When the hardware Device Server is configured to work in Dynamic DNS only mode settings should be configured differently: Link Service login: disabled Registration at dDNS Server: enabled dDNS Server IP-address: IP address of the AggreGate Server

some of these

dDNS Server port: Must be equal to the value of Port number to listen for normal Device Server connections 1009 global configuration setting of Device Servers plugin. If the hardware Device Server does not connect to AggreGate Server within seconds after rebooting, see troubleshooting information here 1018 .

Other External Device Server Operations

BUZZING
The buzz feature allows you to visually match an External Device Server Account to a hardware Device Server. It causes the hardware Device Server play a fast-blinking pattern using its red and green status LEDs. This way you can easily identify which Device Server a particular account corresponds to.

REBOOTING
This operation reboots the hardware Device Server. Rebooting may be required after changing Device Server settings.

INITIALIZING
This operation resets a hardware Device Server to factory defaults. It requires confirmation, and cannot be undone. Default values may prevent a Device Server from being discovered by AggreGate Server. Use this feature carefully.

Icons for External Device Servers

External Device Server Accounts are represented by different icons in AggreGate Server User Interfaces (such as AggreGate Client): Normal hardware Device Server running a fixed-function firmware. A Device Server that is implemented as a logical part of Agent programmable module.
848

Tibbo BASIC application running on a

2000-2013 Tibbo Technology Inc.

Device Server Management

1017

Configuring External Device Servers

AggreGate Server provides way to change the internal settings of hardware Device Servers. This function was previously implemented in Tibbo DS Manager software. Device Server settings are accessed using the Configure Device Server 1028 action of any External Device Server 1027 context. Here is an example of a Device Server settings dialog (in AggreGate Client):

8.8 Tools
There are several tools facilitating Device Server management. Device Server Queries
271 : 1003

All Device Servers. This query allows viewing and editing the settings of all Device Server accounts table.

in a single

Buzz All External Device Servers. Helps detect what Device Servers are currently visible by AggreGate Server by buzzing them all simultaneously. Note that Device Servers discovery must be executed before running this query to allow AggreGate Server to detect Device Servers in the local network segment. See External Device Servers 1012 for more info. Device Server Traffic Statistics. Shows how much data was sent to and from every Device Server. Device Server Scheduled Job
266 :

Discover And Connect External Device Servers. This job runs a periodic External 1013 Device Servers discovery 1013 and optional auto-connection 1014 . It may be disabled if there no Device Servers 1003 are available in current AggreGate installation. Device Server Event Filter
206 :

Device Server Events. This filter shows events related to Device Servers, such login attempts of Device Servers which don't have a Device Server account, registrations of new Device Server accounts, connection problems, successful logins etc.

2000-2013 Tibbo Technology Inc.

1018

AggreGate Documentation

8.9 Troubleshooting Device Server Connections

Here is a list of Device Server 1003 LED error patterns that you might encounter if there is a problem with your setup: IP address not obtained. This has nothing to do with Dynamic DNS itself. It just means that your Device Server is configured to obtain its IP from the DHCP server and for some reason this is not working properly. The Device Server will only attempt to register at AggreGate Server after it has successfully configured of its own IP. Sending ARP. You have specified an incorrect Gateway IP-address/NetMask or your network router is not setup correctly. TCP connection is being opened. You have entered incorrect Destination IPaddress or dDNS Server IP-address or your network router is not setup correctly. TCP connection reset by the network host . You have specified incorrect Destination IP-address/Destination Port or dDNS Server Port/dDNS Server IPaddress. Login failed. AggreGate Server has rejected login from your Device Server. Make sure that Owner Name, Device Server Name and Device Server Password are equal in the Device Server Account properties and Device Server itself. See also: LED Signaling Emulator

8.10 Setting Definition Files

Some Device Servers 1003 are unable to provide AggreGate Server with information about their internal settings. To make configuration of these Device Servers possible, AggreGate Server uses Setting Definition Files (SDF files). Each SDF file contains a list of settings supported by Device Servers with a particular firmware version. SDF files are shipped as part of the AggreGate Server distribution package and installed into the /sdf subfolder of the AggreGate Server installation. All SDF files are loaded in memory during startup. If some changes are made to one of the existing files or new files are added, it is necessary to restart server to activate them. When a user upgrades the firmware for old Device Servers, they may need to receive a new SDF file(s) from Tibbo and put it in the /sdf folder. This will allow them to access settings available in newer Device Server firmware versions. The average AggreGate Server user (or even administrator) will never have any actual contact with the SDF files. You can consider this topic as an "in-depth" topic, for extending your understanding of AggreGate Server internals.

8.11 Contexts
This section described contexts
863

related to Device Server management.

8.11.1 Device Server

This context
863

is used to access and manage a single Device Server [?

651 ]

1003 .

Unique Actions

EDIT DEVICE SERVER PROPERTIES (Default Action

893 )

This action is used to edit properties 1006 of Device Server Account.

Action Type: Action Name: Action Icon:

Configure

904

editProperties

CONFIGURE DEVICE SERVER

2000-2013 Tibbo Technology Inc.

Device Server Management

This action is used to edit settings of hardware Device Server. Its differences from a standard Configure action is that Device Server is rebooted when new settings are saved. Action Name: Action Icon: configure No icon

1019
904

CONFIGURE DEVICE DRIVER

This action is used to edit Device Server-level 130 properties of a Device Driver 129 associated with Device Server Account. Driver type is defined in the basic properties 1006 of the Device Server Account. See the driver description for information about available properties.
Action Type: Action Name: Action Icon:

Configure

904

configureDevicePlugin

VIEW DEVICE SERVERS SUMMARY

Shows Device Servers summary. Action Type: Action Name: Call Function list
903

VIEW DEVICE SERVERS STATUS

This action shows

Action Type: Action Name: Action Icon:

897

status 1007 of Device Server Account. Configure

status
904

(read-only mode)

BUZZ
This action buzzes Action Type: Action Name:
1016

a hardware Device Server. Call Function buzz

903

REBOOT
This Call Function Action Type: Action Name: Non-Interactive Mode 893 :
903

action reboots

1016

a hardware Device Server.

Call Function reboot Supported

903

VIEW DATA FLOW

This action is used to monitor data routed between hardware Device Server and AggreGate Server. See details here . Action Name: Non-Interactive Mode 893 : Permissions: dataFlow Not Supported Accessible at Observer permission level [?
651 ] 932 1008

Common Actions

2000-2013 Tibbo Technology Inc.

1020
Delete
905

AggreGate Documentation
, Replicate
909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909

Context States and Icons

Device Server if offline Device Server is online (connected to the AggreGate Server) Device Server Account is blocked, login attempts will be denied Some Device Drivers
129

may affect the state and icon of this context. For example, the Transparent Data

Routing (Link Service) 1010 driver sets context icon to and status to Client connected when some third-party software is connected to the AggreGate Server using a dedicated port specified in the driver settings for this Device Server Account and exchanges data with current Device Server. In other words, you see this icon when the AggreGate Server is used as a transparent "pipe" between a Device Server and some other software.

Advanced Information
Context Information
Context Type Context Name
864

: deviceServer : provided by user

864

863

Context Description Context Path Context Mask

863

: provided by user

: users.USER_NAME.deviceservers.DEVICE_SERVER_ACCOUNT_NAME : users.*.deviceservers.*
865

865

Context Permissions

: Observer
[?
869 ]

Public Variables (Properties)

DEVICE SERVER INFORMATION

Returns properties 1006 of a Device Server Account. Variable Name: Records: Permissions: Record Format
Name owner
855

deviceServerInfo

1 Readable at Observer permission level :

Type String Description
932

name password description registerindns blocked inbandpassthrough

String String String Boolean Boolean Boolean

2000-2013 Tibbo Technology Inc.

Device Server Management

1021

timezone deviceplugin

String String

DEVICE SERVER STATUS

Returns status 1007 of a Device Server Account. Variable Name: Records: Permissions: Record Format
855

status

1 Readable at Observer permission level :

932

Field Name

Field Type

Notes

name online pluginStatu s dsToServer serverToDs creationtim e updatetime realip realport logintime internalip

String Boolean String

Long Long Date

Date String Integer Date String

[?
878 ]

Nullable Nullable Nullable Nullable

Public Functions
SEND COMMANDS

This function sends several commands to a hardware Device Server and returns its replies.

Function Name: Permissions: Input Records:

Input Format
855

commands Accessible at Observer permission level

932

1...unlimited
: Name command Type String Description Command text.

2000-2013 Tibbo Technology Inc.

1022

AggreGate Documentation 1...unlimited

Name successful Type Boolean Description True is command was successfully sent and replied by Device Server.

Output Records: Output Format

855 :

errortext

String

Text of error message if some I/O error occurred while sending command. Text of reply received from a Device Server if command was successfully replied.

reply

String

SEND NON-REPLIED COMMANDS

This function sends several commands to a hardware Device Server but doesn't expect to get any replies from it.

Function Name: Permissions: Input Records:

Input Format
855

nonRepliedCommands Accessible at Observer permission level

932

1...unlimited
: Name command Type String Description Command text.

Output Records: Output Format

855 :

1...unlimited
Name successful Type Boolean Description True is command was successfully sent to Device Server.

Successful sending a non-replied command via UDP does not mean that is was received and processed by Device Server. errortext String Text of error message if some I/O error occurred while sending command.

BUZZ
Buzzes 1008 Device Server.

Function Name: Permissions: Input Records:

Input Format
855

buzz Accessible at Observer permission level

932

0
: None

Output Records: Output Format

855 :

0
none

REBOOT
Reboots 1008 Device Server.

2000-2013 Tibbo Technology Inc.

Device Server Management Function Name: Permissions: Input Records:

Input Format
855

1023

reboot Accessible at Observer permission level

932

0
: None

Output Records: Output Format

855 :

0
none

DISCONNECT
Causes server to close TCP connection with a hardware Device Server. It will attempt to reconnect to the Device Server in several seconds.

Function Name: Permissions: Input Records:

Input Format
855

disconnect Accessible at Observer permission level

932

0
: None

Output Records: Output Format

855 :

0
none

REMOVE
Permanently destroys Device Server Account.

Function Name: Permissions: Input Records:

Input Format
855

remove Accessible at Observer permission level

932

0
: None

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

, contextStatusChanged (Status Changed)

890

CONNECTION

This event is fired upon device server connection and successful login. Event Name Permissions: Records:
DISCONNECTION
connection

Accessible at Observer permission level 0

932

This event is fired upon device server disconnection. Event Name Permissions: Records:
INBAND
disconnection

Accessible at Observer permission level 0

932

2000-2013 Tibbo Technology Inc.

1024

AggreGate Documentation

This event is generated when an inband notification (i.e. command that is not a reply to any other command) is received from a Device Server. Such inbands are handled by AggreGate Server only if
Inband commands allowed for client
1006

option if disabled in Device Server account settings.

Event Name Permissions: Records: Record Format

Field Name text
855

inband

Accessible at Observer permission level 1 :

Notes

932

Field Type

String

Text of received inband.

8.11.2 Device Servers

Thiscontext
863

is a container forDevice all Server Accounts

[?
651 ]

1003

of a particular user.

Unique Actions

NEW DEVICE SERVER (Default Action

893

This action is used to create a new Device Server account. It prompts the user to enter some basic properties for the new account: Name Password Description Register Device Server in DNS Blocked See descriptions of these properties here Action Type: Action Name: Action Icon: Call Function add
903 1006 .

VIEW DEVICE SERVERS SUMMARY

This action shows 896 the basic properties of all Device Server Accounts registered in this container in a single read-only table.
Action Type: Action Name:

Configure
list

904

(read-only mode)

VIEW DEVICE SERVERS STATUS

This actions shows 897 the status 1007 of all Device Server Accounts registered in this container in a single read-only table.
Action Type: Action Name: Action Icon:

Configure
status

904

(read-only mode)

2000-2013 Tibbo Technology Inc.

Device Server Management

1025

Common Actions

[?

651 ] 906 ,

Replicate To Children 910 , Edit Context Permissions according to child contexts.

Monitor Related Events

909 ,

various Grouped Actions

894

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: deviceServers : deviceservers
864

863

Context Description Context Path Context Mask

863

: Device Servers

: users.USER_NAME.deviceservers : users.*.deviceservers
865

865

Context Permissions

: Observer
[?
869 ]

Public Variables (Properties)

DEVICE SERVERS STATUS

Returns status of all Device Servers under the current account. More information about Device Server status may be found here 1007 . Variable Name: Records: Permissions: Record Format
855

status 0...unlimited

Readable at Observer permission level :

932

Field Name

Field Type

Notes

name online pluginStatus dsToServer serverToDs creationtime updatetime realip realport logintime

String Boolean String Long Long Date Date String Integer Date Nullable Nullable Nullable

2000-2013 Tibbo Technology Inc.

1026

AggreGate Documentation

internalip

String
[?
878 ]

Nullable

Public Functions

LIST DEVICE SERVERS

This function returns information about all Device Server Accounts available under current user account. Account properties are described here 1006 .

Function Name: Permissions: Input Records:

Input Format
855

list Accessible at Observer permission level

932

0
:

None
0...unlimited Name owner Type String Description

Output Records: Output Format

855 :

name password description registerindns blocked inbandpassth rough timezone deviceplugin

LIST ALL DEVICE SERVERS

String String String Boolean Boolean Boolean

String String

This function returns information about all Device Server Accounts in the system that are accessible with current permission level. Account properties are described here 1006 .

Function Name: Permissions: Input Records:

Input Format
855

listAll Accessible at Observer permission level

932

0
:

None
0...unlimited Name owner Type String Description

Output Records: Output Format

855 :

name

String

2000-2013 Tibbo Technology Inc.

Device Server Management

1027

password description registerindns blocked inbandpassth rough timezone deviceplugin

REGISTER NEW DEVICE SERVER

String String Boolean Boolean Boolean

String String

Creates new Device Server Account. Account properties are described here

1006 .

Function Name: Permissions: Input Records:

Input Format
855

add Accessible at Observer permission level

932

1
: Name Type Description

name password description registerindns blocked

Output Records: Output Format
855 :

String String String Boolean Boolean

0 None
880 ]

Public Events

[?

Common Events: info (Information)

885

8.11.3 External Device Server

This context
863

lets you access and manage a single External Device Server

[?
651 ]

1012

Unique Actions

CONNECT DEVICE SERVER TO AGGREGATE SERVER (Default Action

893 )

This action is used to connect this Device Server to AggreGate Server. Check details here 1013.
Action Type: Call Function
903

2000-2013 Tibbo Technology Inc.

1028

AggreGate Documentation

Action Name:

connect

CONFIGURE DEVICE SERVER

This action is used to edit the settings of the hardware Device Server. It has two differences from a standard Configure 904 action: it prompts 896 for the Device Server password in the beginning (if the Device Server has one), and reboots the Device Server once the new settings are saved.

Action Name:

configure

BUZZ
This action buzzes Action Type: Action Name:
1016

the Device Server. Call Function buzz

903

REBOOT
This action reboots Action Type: Action Name:
1016

the Device Server. Call Function reboot

903

INITIALIZE
This action initializes 1016 the Device Server. Action Type: Action Name: Call Function initialize
903

TUTORIAL: CONNECT DEVICE SERVER TO AGGREGATE SERVER

This action starts 902 an Interactive Guide to help the user discover Device Servers and connect them to the AggreGate Server.
Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Observer permission level [?
651 ] 906 , 932

guide

Common Actions
Replicate
909

, Edit Context Permissions

Monitor Related Events

909

Context States and Icons

Fixed-function Device Server Agent
848

See this 1016 section for details.

Advanced Information
Context Information
Context Type
864

: externalDeviceServer

2000-2013 Tibbo Technology Inc.

Device Server Management Context Name

863

1029

: generated automatically
864

Context Description Context Path Context Mask

863

: generated automatically

: external_device_servers.NAME_OF_THIS_CONTEXT : external_device_servers.*
865

865

Context Permissions

: Observer
[?
869 ]

Public Variables (Properties)

This context provides one public variable per every setting of the hardware Device Server when it is connected to the server. When one of these variables is being read or written, AggreGate Server sends Get Setting or Set Setting commands to a hardware Device Server.

Public Functions

[?

878 ]

CONNECT DEVICE SERVER TO AGGREGATE SERVER

Causes AggreGate Server to connect
1013

an External Device Server.

Function Name: Permissions: Input Records:

Input Format
855

connect Accessible at Observer permission level

932

1
: Name Type Description

dnsOnly password owner name force

Output Records: Output Format
855 :

String String String String Boolean Nullable Nullable

0 None

TRY TO AUTO-CONNECT DEVICE SERVER TO AGGREGATE SERVER

Causes AggreGate Server to try auto-connecting 1014 an External Device Server.

Function Name: Permissions: Input Records:

Input Format
855

autoConnect Accessible at Observer permission level

932

0
:

None 0 None

Output Records: Output Format

855 :

BUZZ
Buzzes 1016 External Device Server.

2000-2013 Tibbo Technology Inc.

1030

AggreGate Documentation
buzz Accessible at Observer permission level
932

Function Name: Permissions: Input Records:

Input Format
855

0
: None

Output Records: Output Format

855 :

0
none

INITIALIZE
Initializes
1016

External Device Server.

Function Name: Permissions: Input Records:

Input Format
855

initialize Accessible at Observer permission level

932

0
: None

Output Records: Output Format

855 :

0
none

REBOOT
Reboots 1016 External Device Server.

Function Name: Permissions: Input Records:

Input Format
855

reboot Accessible at Observer permission level

932

0
: None

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

8.11.4 External Device Servers

Thiscontext 863 is a container forExternal all Device Server Accounts 1012 , providing actions used to manage External Device Servers.

Unique Actions

[?

651 ]

DISCOVER DEVICE SERVERS (Default Action

893

)
1013

This action i nstructs AggreGate Server to initiate Device Server discovery process Action Type: Action Name: Call Function discover
903

CONNECT DEVICE SERVER TO AGGREGATE SERVER

This action allows connecting a Device Server that was not detected by the discovery process
1013

to the

AggreGate Server. See details here 1014 .

2000-2013 Tibbo Technology Inc.

Device Server Management

1031

Action Type: Action Name:

Call Function connect

903

TUTORIAL: CONNECT DEVICE SERVER TO AGGREGATE SERVER

Starts 902 an Interactive Guide to help the user discover Device Servers and connect them to the AggreGate Server.
Action Name: Action Icon: Non-Interactive Mode 893 : Permissions: Not Supported Accessible at Observer permission level [?
651 ] 906 , 932

guide

Common Actions

Replicate To Children 910 , Edit Context Permissions according to child contexts.

Monitor Related Events

909 ,

various Grouped Actions

894

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: externalDeviceServers : external_device_servers
864

863

Context Description Context Path Context Mask

863

: External Device Servers

: external_device_servers : external_device_servers
865

865

Context Permissions

: Observer
[?
869 ]

Public Variables (Properties)

This context has no public variables (properties).

Public Functions

[?

878 ]

DISCOVER LOCAL DEVICE SERVERS BY BROADCAST

Causes server to discover Device Servers.
1013

Device Servers available in a local network segment and returns a list of discovered

Function Name: Permissions: Input Records:

Input Format
855

discover Accessible at Observer permission level

932

0
:

None
0...unlimited Name Type Description

Output Records: Output Format

855 :

2000-2013 Tibbo Technology Inc.

1032

AggreGate Documentation

mac ip port owner name accessMeth od

String String Integer String String Integer

Nullable

Nullable Nullable Nullable

CONNECT DEVICE SERVER TO AGGREGATE SERVER

Causes AggreGate Server to connect
1014

an External Device Server.

Function Name: Permissions: Input Records:

Input Format
855

connect Accessible at Observer permission level

932

1
: Name Type Description

dnsOnly accessMeth od mac ip port password owner name force

Output Records: Output Format
855 :

String Integer

String String Integer String String String Boolean Nullable Nullable

1
Name Type Description

owner name

String String

Public Events

[?

880 ]

Common Events: info (Information)

885

2000-2013 Tibbo Technology Inc.

Device Server Management

1033

9 Network Management and Monitoring

This section covers AggreGate Network Manager, an enterprise network management and monitoring solution based on AggreGate Platform. Go to Overview 1033 to proceed.

9.1 Overview

AggreGate Network Manager is an enterprise-grade IP network management, monitoring and supervision system based on the AggreGate Platform. It may be combined with other AggreGate extensions (SCADA/HMI, Building Automation, Time and Attendance, Access Control, Fleet Management, etc.) to create an integrated building control center. AggreGate Network Manager provides common network monitoring facilities and tools along with comprehensive capabilities to customize, modify and extend them. The Network Manager is built as a platform-independent cross-database system. Tibbo provides bundles for Windows, Linux/Unix and Mac OS version.

Primary Features of AggreGate Network Manager

AggreGate Network Manager provides high-end monitoring and management facilities for large and complex enterpriseclass networks: Advanced network discovery 1055 providing automatically finding, registering and configuring devices and services for management and monitoring. Network Mapping 1066 for visual dynamically updated representation of network infrastructure, topology and state. Powerful alerting 1145 , reporting
1149 ,

charting

1151

and visualizing 1154 facilities. Integrated GUI Builder and Report Editor.

A variety of built-in availability/operability 1044 and performance 1045 analysis tools for all major network management and monitoring domains including SNMP management, server/router/switch monitoring, database monitoring, network traffic and bandwidth monitoring, virtualized environment monitoring, etc. Smart application, service and process monitoring. Support for standard protocols and technologies along with industrys leading data processing capabilities for nonstandard network equipment. Advanced consolidation of SNMP traps, Syslog messages and Windows Event Log notifications. WMI support: fetching classes, class instances and their metadata; performing WQL requests; receiving and processing WMI events; executing methods of WMI objects. Enterprise-level capabilities for customization, extending and scaling the network management system; integration with third-party systems via open protocols.

9.2 Getting Started

The initial steps to use AggreGate Network Manager for managing and monitoring your network and its components are: Install 1034 AggreGate Network Manager software. Discover 1055 your network. Configure 1034 the network items you want to manage/monitor.

2000-2013 Tibbo Technology Inc.

1034
Monitor

AggreGate Documentation
1035

using available tools.

Control 1036 your managed items.

9.2.1 AggreGate Network Manager Installation

AggreGate Network Manager distribution includes two separate installers: Server and Client . AggreGate Network Manager Server is responsible for data collection and processing. Client part of AggreGate Network Manager is a desktop software for operator workstations.

Installation and Startup

Refer to Quick Start Guide
28

for detailed instructions on downloading, installing and starting AggreGate.

If you are installing AggreGate Network Manager from a generic AggreGate Platform bundle, make sure that you have selected Network Management Extensions during installation of AggreGate Server.

Quick Start Widget

Once logged in to the AggreGate Network Manager, you'll see the Network Manager Quick Start widget provides access to the most important operations:
312

that

To disable automatic launch of this widget: Find Auto Run ( ) node in the System Tree
784

Right-click on Network Manager Quick Start auto-run action Select Configure ( ) from context menu

Uncheck Enabled and click on OK

9.2.2 Configuring
Network management technology implies presence of two sides: managing (AggreGate Network Manager in our case) and managed (i.e. network devices, and services/applications they run). Both sides should be properly configured.

Configuring AggreGate Network Manager

System configuration is covered in Configuring AggreGate Network Manager check the following tasks:
1047

section. If you are new to the product,

1050

Register devices for management and monitoring. You can do it either manually

or automatically

1052

(using

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1035

discovery). It's a good idea to configure first several devices manually, as this will help you to better understand various aspects of this task. As the next step, when you need to manage and monitor more devices you'll master automatic discovering procedures. The task of manual registering devices is tightly coupled with the task of their configuration, i.e. adjusting parameters 1050 for them. You should master this task really well as it is literally crucial one for successful network management and monitoring. Setup monitoring tools (e.g. alerts, charts or reports) for registered devices. Refer to the monitoring familiarize yourself with available tools and types of monitoring they provide.
1035

section to

Configure Environment
The task of configuring managed side cannot be fully covered, since there is a vast amount of different hardware and software products that can be managed or monitored. If you are not familiar with configuration issues of your devices, services and applications, leave their default settings at this stage. With gaining more experience and skills you'll get back to this subject and customize your managed items for better interaction with AggreGate Network Manager. Refer to Configuring Environment
1053

section to get information about some commonly experienced issues.

9.2.3 Monitoring
The aim of network monitoring is to understand what is going on with your network and its components. First of all, this involves collecting, storing and processing data from managed network items. This task is partly fulfilled by configuring monitoring system 1034 . Collecting data is only the very first step of monitoring task. The collected data must be processed, i.e. analyzed in order to: Detect network problems Reveal their root causes Understand how they can be fixed Make corrective decisions and implement them. One of the most significant tasks of this analysis is data visualization. It doesn't mean only building various charts but, more generally, any kind of presenting data in the form convenient to Understand current situation and trends Reveal inner relations between parameters Find events of interest. AggreGate Network Manager provides a rich set of tools facilitating data visualization and analysis. The below table represent basic AggreGate Network Manager monitoring facilities categorized by type of monitored object and type of monitoring (metric). Monitoring Object Generic IP Network Host Specific Type of Device Database Server File System Operability
1044

Monitorin g Subject Availability

1044

Monitoring Facilities and Tools Ping is used to detect Online/Offline status of a generic IP host. You can monitor this using Device Offline alert 1145 .

References

JDBC-compliant relational databases are supported by SQL Database driver 180 . Filesystem on the computer that runs AggreGate AggreGate Server may be monitored by checking the existence of files and folders, their contents, sizes, attributes, checksums, and so on.

Database Monitoring

1103

Operability
1044

Local Folder Monitoring 1104 Local File Monitoring

1104

Printer

Operability
1044

Printer Information widget and alerts Printer State Printer Marker 1120 , Printer Cover Status 1120 and Critical Printer Event SNMP Trap 1108 .
1120

216 :

1120 ,

Printer Monitoring
1119

VMware

Operability 1044 and Performanc e 1045

Individual virtual machines can be monitored using VMware Information Widget 1118 ; Virtual Machine State 1115 , Memory Utilization (Volume) 1115 , Memory Utilization (Percentage) 1115 , CPU Load 1115 , HDD Read 1115 , HDD Write 1116 alerts; CPU

VMware Server Monitoring 1114

2000-2013 Tibbo Technology Inc.

1036

AggreGate Documentation

Utilization 1117 , Disk Performance Performance 1117 charts. Wireless Device Resources CPU Storage Operability
1044

1117 ,

Memory Usage

1117 ,

Network Wireless Device Monitoring 1121

Wireless Information Widget

1121 .

Performanc CPU Load charts 1152 and CPU Load reports/queries e 1045

1150 .

Performance Monitoring 1092 Storage Monitoring

1093

Performanc Storage Space 1146 alerts, Storage Usage 1152 charts, Memory e 1045 Usage 1150 , Disk Volumes Utilization 1150 and Disk Volumes Free Space 1150 reports.

Network Routers and Switches Availability and Operability

1044

Availability/operability of particular network interfaces can be tracked using Network Interface Down 1098 and Network Interface Administrative Shutdown 1098 alerts.

Availability Monitoring 1091

Traffic

Performanc Interface Traffic 1097 , Interface Errors 1098 , Interface Discards 1098, e 1045 Network Interface Utilization 1098 charts, Interface Traffic Summary 1099 , Interface Traffic Top 10 and Interface Traffic Top 50 1099 , Interface Bandwidth Utilization Over 50% and Interface Bandwidth Utilization Over 90% 1099 , Interface Bandwidth Utilization Top 10 and Interface Bandwidth Utilization Top 50 1099 reports. Alternatively, NetFlow
1100

Network Traffic and Bandwidth Monitoring 1096

can be used to analyze network traffic. Application/Service Monitoring 1108 Network Mapping
1066

Services and Applications Network Infrastructure Overview

Operability
1044

There is a bunch of services and applications whose operability and other characteristics can be natively monitored. You can use maps 1066 to visualize geometry/topology and state of IT infrastructure you manage/monitor.

Availability
1044

9.2.4 Managing
AggreGate Network Manager provides a set of operations you can use to manage your devices: Various SNMP-compliant devices can be configured or made to perform certain actions using SNMP Computers running Windows operating system can be controlled via WMI If a host supports SSH, remote script execution
1144 1144 . 1144 .

can be used to manipulate it.

There are many network management actions 1144 provided by AggreGate Network Manager. These actions can be invoked interactively or automatically (as alert's corrective action 227 or scheduled job 266 ).

9.3 AggreGate Network Manager Basics

Network monitoring is a complex and sophisticated problem, involving a manifold of interrelated tasks. While AggreGate Network Manager can be treated simply as a set of helpful tools for those tasks, it is actually more than that. The system brings together and implements essential network management principles and approaches. AggreGate Network Manager was designed to tightly cover basic management requirements while preserving highly customizable and extendable nature inherited from AggreGate Platform. Therein AggreGate Network Manager can be viewed as a platform or framework for building highly customized network management solutions. This section covers theoretical aspects of AggreGate Network Manager operation. It can be easily skipped in favor of solving practical tasks described in the subsequent sections.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1037

9.3.1 Network Management Concepts

Network management as a term got diverse meanings at present, and hence needs a review to establish some basics to be used later in the manual. The major domain of AggreGate Network Manager is an operational aspect of network management, i.e. "keeping the network and the services it provides up and running smoothly". Essential network management terms, concepts, principles and various other aspects are discussed further in this section.

9.3.1.1 Management Subjects

AggreGate Network Manager deals with networks, end systems and applications, thus, covering the following three network management areas: Narrower network management: management of communication networks and the resources in the network that are required to establish end-to-end communications. For example, this may involve monitoring of routers and switches, and making sure that the configurations of routers and switches across the network are properly coordinated. System management: management of end systems that are connected to networks. As an example we can mention monitoring of storage volumes available on corporate servers, and notifying users when memory utilization is too high, or free space on hard disks runs out. Application management: management of services and applications that are deployed on systems that are interconnected over a network. Examples would be monitoring and controlling of Email servers, various TCP/UDP services, databases, and so on.

9.3.1.2 Management Tasks

Functionality of AggreGate Network Manager can be classified into several categories:

Monitoring
To monitor means to be aware of the state of a system. To be able to manage a system one should first of all understand everything that matters about the system: its current state, behavior, causes and trends. And network monitoring is with no doubt a central part of network management. AggreGate Network Manager helps to be aware of what is going on with network. For example, it allows to spot problems like outages, failing/slow components as soon as possible, ideally before users are affected. The network manager provides that by: collecting management information from devices, services and applications, and their associated resources (CPU, storage, network bandwidth etc.) storing, processing, and automatically analyzing the collected management information producing various quantitative characteristics like availability, operability, system and network performance metrics; revealing and handling variety of events generated by managed network items, or triggered by AggreGate itself as a result of management information processing and analysis; representing the collected data and detected events for users in a convenient visual/printable form. These basic functionality is supplemented with extremely rich facilities for customizing and extending the monitoring algorithms and tools used. Furthermore, to provide more full-fledged problem-management solution AggreGate Network Manager can be integrated with virtually any helpdesk or trouble ticketing system (see Helpdesk / Trouble Ticketing System Integration 1156 section).

Control
When an actual or potential network problem is detected and diagnosed, it should be fixed or prevented accordingly. Such corrective actions can be performed automatically or manually by applying suitable controlling operations to managed devices, services and/or applications. This can involve, for example, changing configuration parameters of an network item or invoking a command on a remote device making it perform specific operations. In whole, AggreGate Network Manager provides an extendable and customizable set of corrective control actions.

Administering Management Infrastructure

AggreGate Network Manager provides a variety of configuration facilities allowing users to form a specific monitoring infrastructure for their needs. This can be done by discovering, adding and setting up devices to be monitored,

2000-2013 Tibbo Technology Inc.

1038

AggreGate Documentation

customizing monitoring tools or creating new ones, tuning AggreGate Network Manager for better performance, etc.

Asset Management
IT asset management is another typical network management task. Asset Management plugin 950 provides facilities to organize asset management for hardware and software elements in network environment. Refer to Asset Management 1156 section for details.

9.3.1.3 Management Participants

There are two major parties involved into management "game": Managed party -- a network to be managed, consisting of a multitude of interconnected devices, services and applications (network elements/items/nodes). A device is a network element with assigned IP address. Another term that can be used as a synonym is network or IP host . Device provides functionality in terms of services/applications it is running. Manageable device can be any type of device, including, but not limited to, routers, access servers, switches, bridges, hubs, IP telephones, IP video cameras, computer hosts, printers. Examples of services and applications are Web services, e-mail services, database management systems, etc. One of the most important services, we expect to be provided by network device, is ICMP ping. Another important type of service a device can provide for manager is SNMP 1068 support. AggreGate Network Manager supports many other types of services and applications as covered in Application/Service Monitoring 1108 section. Managing party -- people performing the management, and tools (management system) used to accomplish management tasks. AggreGate Network Manager is an example of such a management system. There is another part that can't be easily classified here: common media providing communication between the two parties. Ironically, the media conforms to both definitions above: as a part of network it is subjected to management and hence is a managed party; but, on the other hand, as a facility providing execution of management tasks it can be treated as a part of managing party. We don't go deeper into the speculations here and confine ourself by stating the fact that a distinct classification here could be somewhat sophisticated. The subsequent reasoning if left for our readers. Extending the management terminology here, we introduce terms Manager and Agent.

Manager
Manager can be any kind of management system that performs its duties by tracking and controlling activities of network items. The variety of possible functionality that manager can provide and architecture it can be built with is endless. Manager role can be played by a simple network utility, a very specific application or a huge and sophisticated network management system. Therefore it's impossible to provide any reasonable description for structure or functionality of manager here.

Agent
Management agent represents a separate network element that is a network device, service or application. As a network element, agent has some essential functionality referred here as its core logic. Additionally agent provides some kind of management interface that makes it available for management and provides information about network element that can be consumed by managers. Thus, an agent can be represented as a three-part component: core logic, management interface, management information base (MIB).

CORE LOGIC
Here we use the term Core Logic to refer to essential functionality of network item. This may include operations the item provides, algorithms, parts it comprises and relations between them, etc.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1039

MANAGEMENT INTERFACE
Management Interface provides interaction between agent and manager, providing execution of manager requests and commands, sending back the data requested, and altering the element configuration if needed. Management interface can be implemented as a dedicated interface existing exclusively for and performing only management tasks. Examples are ICMP and SNMP services. But other types of interfaces can be also used to monitor and control certain aspects of a network element. For example, availability and operability of many services and applications can be monitored by accessing and using their core functionality. Say, we can check an e-mail system operability by connecting and communicating with the service via a certain protocol (POP3/IMAP/SMTP). Furthermore, we can ensure that the e-mail system operates properly in whole by sending a test message and checking its delivery to recipient.

MANAGEMENT INFORMATION BASE

Management Information Base (MIB) presents pieces of management information about network item, offering an abstraction of the manageable item used for management purposes. All the management information concerning a particular network item can be regarded as a (virtual) data store that comprises description of all the entity's physical and logical aspects. The data may cover monitoring information, for example, hardware configuration (e.g. available ports and line cards), current state and characteristics; as well as configuration settings that allow manager to control item activity. The MIBs are not real databases; they just reflect information from network item's core. Note, that often MIBs present snapshots of data obtained from core at some instant, and MIB contents is refreshed periodically. The update periods and communication delays should be taken into account by management operations. There are plenty ways management information can be represented and exchanged between agents and managers. One of the most common standards for that, and the one supported out-of-box by AggreGate Network Manager, is SNMP . Refer to SNMP Management 1068 section for details about SNMP, what for and how it can be used in AggreGate Network Manager.

9.3.1.4 Management Interactons

Network management, just like any other type of management, is all about communication and interaction. Manager 1038 interact with agents 1038 to monitor and control their activities. There are two basic approaches to organization of interactions between them. They correspond to the two possible answers to the question "Who initiates the interaction?": the interaction can be initiated either by manager, or by agent. The former is called polling, and the management is in turn polling-based (passive), while for the latter it is event-based (active). AggreGate Network Manager supports both approaches.

POLLING-BASED MANAGEMENT
Polling refers here to the manager-agent conversation initiated by manager. The interaction itself is based on a requestresponse cycle: 1. Manager makes a request (to retrieve a piece of management information, or to change a configuration setting, or to cause it to perform an operation). 2. The agent then receives the request, process it, and sends back a response including a result for the request or a success/error indicator/description. Manager decides when to start the conversation: at certain moments of time with the predefined intervals, or on certain events (when a user requests update of management information for example).

2000-2013 Tibbo Technology Inc.

1040

AggreGate Documentation

AggreGate Network Manager does not initiate polling every time when management information of network elements is requested by operators. Instead, it caches 115 the information and uses cached data upon requests, refreshing it when necessary. Consequently, the management information is requested (and the polling is initiated) under the following circumstances: when a management application initially takes management ownership of a device, storing the information in the AggreGate Network Manager's cache for the first time; when an information in the cache is considered outdated: e.g., if it is too old (with respect to the device management settings), or when a certain corresponding notification was received, or when a user directly requests a cache update. There's a delay between the moment an event occurs at the agent side (e.g. some value has changed) and the moment it was observed by the manager. The delay depends on the frequency of polling requests. On the other hand, excessively often requests abuse both network and management system. AggreGate Network Manager provides means to adjust the polling frequency for particular pieces of management information according to the certain user needs. Request granularity is another polling-based management concern. AggreGate Network Manager supports both bulk requests and incremental operations, and automatically uses an appropriate method in different situations. Besides, AggreGate Network Manager supports collecting historical information, making it available for processing and analyzing.

EVENT-BASED MANAGEMENT
Event-based communication in many ways can be considered an opposite technique to polling. Contrary to a response that is sent after a request, the agent determines on its own when it needs to send an event message, without waiting to be asked first. The agent initiates communication and sends the manager a message, notifying it about some type of occurrence or event that has occurred. This can be, for example, an alarm that indicates that paper has been jammed on a printer, or a warning about CPU overheating on a device, or someone tried to unsuccessfully log on to a device several times in a row as a possible indication of suspicious activity, and so on. Agent should be properly configured to send event notifications to a specific manager. This can be done either using the management application (called subscription to events), or using external (device-specific) tools.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1041

Manager decides independently, when and how it reacts to the events it receive. It can react immediately with some kind of control action, or do it with a delay, or send some kind of clarification request, or simply ignore the event. In AggreGate Network Manager event-based management is implemented, for example, as SNMP traps reception, Syslog messages processing, and NetFlow data collection.

2000-2013 Tibbo Technology Inc.

1042

AggreGate Documentation

9.3.2 AggreGate Network Manager Architecture

Technically, AggreGate Network Manager is implemented as a set of plugins Platform.
950

and drivers

129

extending AggreGate

Some features provided by the Network Manager are just inherited from the core of AggreGate Platform. At the same time AggreGate Network Manager comprises a number of plugins and drivers that extend the basic AggreGate functionality and provide components for managing and monitoring network devices, services and applications. These components are listed below. Covering nearly all the standard network management requirements, AggreGate Network Manager remains a highly customizable and extendable system, inheriting these merits from AggreGate Platform and its architecture.

Network Host Device Driver

Network Host Device driver 150 is used as a basis for management and monitoring of servers, applications, and services located in IP network of any type (wired or wireless, local or global, etc.). This driver includes support for Simple Network Management Protocol 1068 (SNMP).

Database Device Drirver

Database Device Driver
180

is designed for monitoring database servers and executing arbitrary SQL queries.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1043

Network Management Plugin

Network Management plugin provides network-management configuration and monitoring tools like alerts 1145, queries and reports 1149 , charts 1151 , widgets 1154 that support availability 1091 , system performance 1092 and network performance 1096 monitoring for IP hosts, SNMP-compliant devices, databases, printers, VMware ESX servers, wireless devices, a variety of web services and applications.

Discovery Plugin
Discovery plugin provides support for network discovery
1055 .

Syslog Plugin
Syslog plugin provides Syslog 1105 messages monitoring and consolidation
1105 .

NetFlow Plugin
NetFlow plugin supports network traffic monitoring, decomposition, and analysis 1100 using NetFlow protocol .

Local File Driver

Local File driver provides monitoring for files located on AggreGate server. Refer to Local File Monitoring details.
1104

for

Local Folder Driver

Local Folder driver provides monitoring for folders located on on AggreGate server. Refer to Local Folder Monitoring 1104 for details.

9.3.3 Metrics
Monitoring essentially means gathering information from managed network items and calculating operation characteristics (indicators) for them. It is convenient to classify logically connected individual indicators together in metrics. Thus, each metric characterizes a particular aspect of monitored item's operation. For example, Network Host Availability metric can be defined as one included device online status (a boolean value indicating reachability of the host), response time (time from transmission to reception) and packet loss rate indicators available using ping. Additionally, a detailed traceroute data can be added to the metric. There are many types of network metrics that could be used to monitor networks. AggreGate Network Manager provides several pre-defined commonly used metrics. Moreover, AggreGate platform offers rich facilities to calculate other metrics if you need them. There are two basic methods to calculating metrics for monitored item's behaviour: Current-value monitoring: item's characteristics are obtained for particular moments of time. Statistical monitoring: one or several separate instant characteristics are accumulated and used to calculate an aggregated indicator. AggreGate supports both methods. Monitoring can be configured to periodically poll monitored objects and calculate individual indicators to obtain current values and store them. The stored historical data then can be aggregated to obtain statistical representation of the indicator. By pinging a network host we can get its availability status at particular instants of time. Configuring a device for periodical ping with history enabled produces enough information to calculate statistical availability, i.e. a proportion of time the device was in a functioning condition. This can be an aggregated value for some fixed time intervals or availability for overall monitoring period. Metrics and indicators are used by AggreGate Network Manager tools. First of all, availability indicators are used to present device and service statuses. These and other indicators are also used in various alerts, reports, charts, widgets.

2000-2013 Tibbo Technology Inc.

1044

AggreGate Documentation

9.3.3.1 Availability And Operability Metrics

Network item availability and operability help to answer the following: If the item is working at all, i.e. is it available? This aspect is reflected by Availability metric. If the item is fully functional, i.e. does it operate as expected? This aspect is covered by Operability metric. Availability metric characterizes basic operation status of a monitored item.

Operability metric describes the ability of a monitored item to perform its essential functions.

In AggreGate Network Manager availability is checked using simple standard procedures, like pinging a network device, or connecting to a service at specified port. The task is to ensure that a managed item is "alive" at all. Operability monitoring is in contrast more complex and "in-depth" verification ensuring the managed item not "just works", but "works properly". Since the meaning of the term "works properly" differs for different monitored items, operability is usually much more complicated and very often a customizable procedure, like executing a remote script, sending and receiving email messages, etc. In this respect operability monitoring can be characterized as a smart monitoring. Operability checking procedures often provides more then just status of a monitored item, but acquire more detailed data from device. Though the difference between these two metrics can seem somewhat subtle, relative and even subjective, it is still important to distinct these two metrics. Operability can be viewed as an advanced availability metric. For example, availability is only defined for individual services, but not for a whole network device. Availability/operability check procedure depends on the type of monitored items: The basic IP network device availability is based on ping 153 and, optionally, on traceroute 161 services. In other words, availability in this case is defined as IP host reachability: the device is considered available if network packets can be delivered to and from this device. If an IP network device provides other services its availability is calculated as conjunction (logical "AND" operation) of all enabled service availability/operability statuses. Therefore the basic availability mentioned earlier is just an instance of more general procedure described here. Availability of standard IP host services is actually superseded by operability check. By default most services are configured for simpler availability check, but user can configure them service for in-depth operability testing if needed. See Network Host 150 device driver chapter and it subsections describing particular services for some more details. For example, SSH service 163 by default has an empty script and therefore performs only connection, authentication and disconnection operations. This can be considered a basic availability check procedure. User can customize service by specifying a script. Script execution provides rich capabilities for advanced analysis of monitored device and therefore can be classified as operability check. Note, that the operability check includes all the steps executed by basic availability procedure. Hence successful operability check automatically mean service is also available. Resource (CPU, storage, processes, network etc.) availability can be checked via SNMP
1068 ,

WMI

1088

or JMX

1124.

For example, operational state of a network interface can be obtained using ifOperStatus field in ifTAble. Alternatively, corresponding SNMP traps can be used to detect the state changes. Availability/operability of some SNMP-compliant devices can be accomplished using SNMP See Printer
1119 , 1068 .

Wireless Device

1121 ,

and/or VMWare

1114

monitoring sections as examples.

Monitoring, including availability and operability monitoring, of other device types can require to implement a custom device driver. SQL database device driver 180 was introduced for relational databases. It provides both availability and operability monitoring for JDBC-compliant database management systems. AggreGate Network Manager provides both current availability and statistical availability calculations.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

See also Availability Monitoring 1091 section.

1045

9.3.3.2 Performance Metrics

Performance is another important concern for network administrators. Performance metrics include indicators for network as a whole (e.g traffic, latencies, error) as well as characteristics of particular network elements implying utilization and availability of CPU, storage (memory and disks), communication, software, virtualization resources, various applications/services activity indicators, etc. Refer to Network Monitoring 1096 and Performance Monitoring 1092 sections for details about how metrics of this kind are implemented in AggreGate Network Manager.

9.3.4 Data Processing

Functionally, monitoring is a process of collecting and analyzing data. The raw data collected from monitored devices should be processed for the purpose of extracting quantitative characteristics we can analyze. This section contains a brief overview of data-processing types used in AggreGate Network Manager and issues they are concerned with.

Raw Data
In some cases, quantitative characteristics you want to monitor can be directly fetched from device and used "as is" in monitoring tasks without additional pre-processing. As an example hrProcessorLoad SNMP variable can be mentioned, which indicates "the average, over the last minute, of the percentage of time that this processor was not idle" [RFC1514 - Host Resources MIB]. This value characterizes current CPU utilization and can be use "as is", for example, in charts, or alerts.

Differentiation
But not all the values we want to track could be expressed as raw data 1045 . Often collected values must be processed in a certain way to be useful for monitoring. One of the most common processing operations is differentiation. Here it means calculating difference between current and previous samples.

Differences can be useful per se in some cases, but one of the most frequent and important utilization for this metric is time differentiation 1046 as described below.

2000-2013 Tibbo Technology Inc.

1046

AggreGate Documentation

One important issue must be discussed here. Values we use for monitoring are refreshed periodically at a device side with a certain interval. AggreGate Network Manager reads those values during synchronization 126 routine at different moments in time (with respect to its own synchronization period 116 ). Therefore providing too small synchronization period (smaller than refreshing interval at device side) can give irrelevant result: successive samples would be equal (as device had no enough time to refresh the value), and result difference would be zero.

Synchronization period of SNMP variables used in differental metrics should not be smaller then refreshing interval at device side. Refer to specific device documentation to find out how often the device refreshes its indicators and how to customize this. Alternatively, you can just determine it by experiment using AggreGate tools. Knowing the refreshing interval at device side you can adjust synchronization period 116 (at AggreGate server side) accordingly.

Derivation
Derivation is a good and most common example of differentiation
1045

"in action".

Some of the values to be monitored are actually derivatives of the values AggreGate can immediately access. For example, generic SNMP devices provide only total number of bytes received on an interface. So, to get the interface input traffic, which is (averaged) number of bytes received at a unit of time, we have to estimate changes of total received bytes over time, i.e. apply time differentiation. This kind of metrics we'll call time derivatives. The simplest way to calculate a time derivative is to get current and previous values and calculate ratio between their difference and their distance in time. Therefore their implementation is based on differential metrics and is accompanied by the same issue 1046 : derivative values can be zero when synchronization period is too small.

9.3.5 Protocols And Technologies

This section contains a brief list of protocols and technologies supported and used by AggreGate Network Manager: Basic protocols Internet Protocol (IP) Transmission Control Protocol (TCP )

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1047

User Datagram Protocol (UDP) Network management protocols, standards and technologies Simple Network Management Protocol (SNMP ) Windows Management Instrumentation ( WMI) Internet Control Message Protocol (ICMP) Syslog NetFlow Java Management Extensions (JMX) E-mail protocols Post Office Protocol (POP) Internet Message Access Protocol (IMAP) Simple Mail Transfer Protocol (SMTP) Other application protocols File Transfer Protocol (FTP) Hypertext Transfer Protocol ( HTTP), Hypertext Transfer Protocol Secure ( HTTPS) Secure Shell (SSH), Secure Copy Protocol ( SCP) Lightweight Directory Access Protocol ( LDAP) Domain Name System (DNS) protocol Dynamic Host Configuration Protocol (DHCP) Remote Authentication Dial In User Service (RADIUS) Database technologies Java Database Connectivity (JDBC ), Open Database Connectivity ( ODBC)

9.3.6 Network Management Tools

Network Manager uses both standard AggreGate data processing tools and special network management-oriented components, including: Plugins and drivers 1042 Alerts 1145 Charts 1151 Reports and queries 1149 Widgets 1154 Dashboards 1151 . These tools and components cover most of the commonly encountered network management tasks. Many specific problems and tasks can be met by customizing/modifying these elements, or by creating custom alerts, charts, reports, queries. All tools can be customized or used as templates for creating new tools.

9.4 Configuring AggreGate Network Manager

This chapter covers configuring your network management system. It involves configuring of both sides taking part in management and monitoring: managed items (agents), that should provide information and accept control operations, and manager components, ought to be tuned up and customized. See Configuring Environment monitoring.
1053

section for more information about configuring your network environment for
1048

As for AggreGate Network Manager components, there are two subsections describing global system settings configuration of managed devices/services 1049 and tools 1052 .

and

2000-2013 Tibbo Technology Inc.

1048

AggreGate Documentation

9.4.1 Configuring Drivers and Plugins

This section concerns global configuration options of network management-related drivers and plugins. These options are used to specify AggreGate Network Manager behaviour at global system level as opposite to configurations of particular managed devices/services 1049 and tools 1052 . See the below articles for configuration details: Network Host Driver Discovery Plugin 1048 Syslog Plugin
1048 1048

NetFlow Plugin 1049 .

9.4.1.1 SNMP Configuration

This sections covers global settings of SNMP device driver. Most of these settings are reused by Network Host device driver's SNMP service.

MIB Files Directory

MIB files 178 describe SNMP data AggreGate Network Manager can use. AggreGate Network Manager is distributed with more than two hundred of MIB files that are essential for SNMP monitoring and therefore are bundled with AggreGate Server distribution. You can customize this set by adding MIB files for specific devices/services you use, removing unused files to save memory and improve server performance, refreshing old versions with newer ones and so on.

SNMP Trap Monitoring

SNMP Trap Monitoring options 178 specify whether and how AggreGate Network Manager listens for SNMP traps assure your AggreGate Network Manager configuration conforms to configuration of your SNMP devices.
1085.

Just

SNMP Trap Sources Automatic Discovery

Automatic Discovery of SNMP Trap Sources 178 enables AggreGate Network Manager to automatically start discovery for the network items that send SNMP traps to your server. See also Automatic Discovery 1063 section.
1055

Additional Information
See SNMP Global Settings
178

section for more information about SNMP driver settings.

9.4.1.2 Discovery Configuration

Discovery 1055 is an automatic or semi-automatic action of finding new network devices, detecting services and applications running on them, adding and configuring the found items for monitoring and management. Discovery is implemented by Discovery plugin 1043 . Discovery settings 1063 specify options for full interactive 1062 and headless 1062 discovery, single-device discovery and automatic discovery 1063 . Refer to Service Selection and Setup 1056 section for details.
1062,

The Discovery plugin configuration is available in Network Device Discovery node under Drivers/Plugins item in System Tree. AggreGate Server should be restarted for the changes to take effect.

9.4.1.3 Syslog Configuration

Syslog 1105 support is implemented by Syslog plugin the System Tree.
1043 .

It is configured via Syslog node of Drivers/Plugin item in

The Syslog configuration includes Syslog Server Configuration and Syslog Message Sources Automatic Discovery settings described below. Note that AggreGate Server should be restarted to apply changes.

Syslog Monitoring Configuration

This table includes Syslog messages monitoring and consolidation
1105

parameters.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1049

Property Enabled Syslog Protocol Syslog Port Severity Conversion Table

Description Enables/disables syslog messages monitoring. Specifies the protocol (TCP or UDP) used for receiving Syslog messages. Specifies port to listen syslog messages at. Syslog severity level to AggreGate severity level
882

mapping. See below.

SEVERITY LEVEL CONVERSION

The Severity Conversion Table is used to calculate level of the generated %ag%> event 880 based on original Syslog message severity level. See Syslog Events Monitoring and Consolidation 1105 for details about Syslog event generation. The table maps each of the Syslog severity level values (as specified in RFC 5424) to an AggreGate severity level (see Event Levels 882 section). If a Syslog severity value is absent in the table, the resulting AggreGate event level is None (code 0). By default the table is specified as follows: Syslog Severity Level Code 7 6 5 4 3 2 1 0 Name Debug Informational Notice Warning Error Critical Alert Emergency Description Debug-level message Informational message Normal but significant condition Warning conditions Error conditions Critical conditions Action must be taken immediately System is unusable AggreGate Event Severity Code 1 2 2 3 4 4 4 5 Level Notice Info Info Warning Error Error Error Fatal

This table can be modified to provide a desired conversion procedure.

Syslog Message Sources Automatic Discovery

This flag enables or disables automatic discovery
1107

of hosts sending Syslog messages to the AggreGate server.

9.4.1.4 NetFlow Configuration

NetFlow 1100 support provided by NetFlow plugin composition data.
1043

allows AggreGate Network Manager to collect detailed network traffic

NetFlow configuration defines two aspects: how data is collected and how the collected data can be presented for users. NetFlow-collecting settings specify communication parameters used by AggreGate Network Manager to accept flow data from exporters. NetFlow Views table in the configuration describes widgets used to present accumulated NetFlow data for human analysis. Refer to NetFlow Charting Widgets section for detals.

9.4.2 Configuring/Administering Devices and Services

This section provides information and some tips for establishing and maintaining management/monitoring infrastructure by configuring initial configuration (both manual 1050 and automated 1052 ) and further administering 1052.

2000-2013 Tibbo Technology Inc.

1050

AggreGate Documentation

9.4.2.1 Manually Adding and Configuring Devices And Services

Manual configuration can be characterized as the most accurate way to add and setup a device. At the same time this can quickly become a boring, annoying and tiresome task as soon as a several dozens or more devices are to be configured. In this cases network discovery can be a better alternative. To add a new device to the system do the following: invoke Add New Device
675

action of Devices Context

specify unique Device Name, Device Description and Device Driver click OK to register the device. See also Devices
113

chapter for a more detailed description.

The newly added device should be properly configured. This involves common parameters like Host Address, Generic Device Properties and Device Settings Synchronization Options along with specific options that depends on the device type (driver used), services and applications it runs and the role it plays.

Common Configuration Parameters

HOST ADDRESS
IP Address or Host Name is required for most device types and simply specifies host address for the network device.

GENERIC DEVICE PROPERTIES

Generic Device Properties define standard device attributes like it's name, description, time zone, etc. Refer to Generic Device Properties 123 paragraph of Devices article for details. Usually most of these options should not be changed; but still check them to ensure they are correct. Pay attention to the following parameters: Device Type . This parameter specifies a role the device plays in the network environment. The roles can be used, for example, to find devices more easily by organizing them into type groups. Synchronization parameters, namely Synchronization Period, Interrupt Synchronization And Reconnect On Error, Enable Extended Status, Device Dependency Expression defines how the device information is updated. Together with Device Settings Synchronization Options 115 these settings are crucial for proper monitoring operation. Suspend Device allows to pause prevent device polling.

DEVICE SETTINGS SYNCHRONIZATION OPTIONS

Device Settings Synchronization Options 115 allows to customize synchronization (polling) options for every device setting. This provides a fine-grained control over monitoring process.

Driver-Specific Parameters
Configuration of specific device types are described in the corresponding subsections: Network Host Local File 1051 Local Folder 1051 SQL Database 1052 JMX
1052 . 1051

Monitoring Parameters
Monitor parameters are rather scattered among diverse parameter groups: Synchronization parameters 1050 , namely Synchronization Period, Interrupt Synchronization And Reconnect On Error, Enable Extended Status, Device Dependency Expression in Generic Device Properties. Device Settings Synchronization Options 1050 .

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1051

9.4.2.1.1 Network Host Device Configuration

Network Host driver provides support for a set of services that can be running on an IP network host. Refer to the Network Host 150 chapter and its sections for detailed description of the driver, services and their configuration parameters. Here we'll discuss several important services and their configuration specifics you should pay additional attention to.

Ping
Ping service 153 is essential for monitoring availability of network host. The default configuration parameters will be simply okay for most cases in practice. But for some specific circumstances you'll have to adjust timeout and possibly other settings.

SNMP
SNMP monitoring is the most universal and widely used way to collect detailed information about particular devices, services and applications in your network. For a particular SNMP-compliant device you should specify polling parameters. They are described in the SNMP Polling Settings 176 section.

BASIC CONFIGURATION
Network devices are often customized by administrators to meet security and other real-life requirements. Therefore you have to ensure that transport protocol, port, SNMP version, read/write community strings, security parameters and PDU size at AggreGate side correspond to agent's configuration. Check also that communication parameters (command retries and timeout) conform the network conditions.

POLLING PARAMETERS
Polling parameters define: What kind of data AggreGate Network Manager will read from the device Polling period Value history storage rules Data to be read is defined by Data To Process 176 parameter. There are two options allowing to balance between data fullness/plenitude and performance penalty your system and network pay for that. If you use All values found by SNMP walk option, you'll get all the data this device provides via SNMP. It can be useful especially if you want to explore new type of device, reveal all the data it exports via SNMP, and add necessary MIBs to the system. But for many cases this will just pollute your system with excessive information, borrow additional memory and other resources resulting in performance degradation. Thus, All available values in MIB directory is the best choice for most cases. Another important aspect of polling configuration is synchronization options. They define how often AggreGate Network Manager poll the device and particular SNMP variables the device provides. Again you have to find a good tradeoff between performance and information accuracy. Use synchronization options for the whole device (a part of Generic Properties) 123 and for particular SNMP variables 115 to configure polling according to your requirements.

Other Services
Refer to particular service articles presented in Network Host configuration.
150

chapter for details about their operation and

9.4.2.1.2 Local File Configuration

Local File driver 143 provides monitoring for files 1104 located on the AggreGate server. The configuration is simple and straightforward: just specify path to the file to be monitored and operations you want to perform using driver's properties 143 .

9.4.2.1.3 Local Folder Configuration

Local Folder driver 144 provides monitoring for folders 1104 located on the AggreGate server. To configure this type of device, simply provide path to monitored folder, enable or disable reading operation and specify how it should be performed (if enabled) using driver's properties 144 .

2000-2013 Tibbo Technology Inc.

1052

AggreGate Documentation

9.4.2.1.4 SQL Database Configuration

The SQL Database device 180 driver provides monitoring of relational databases 1103 . To configure this kind of devices, you should provide correct driver setting for the database management system you want to monitor, connection parameters including database URL , username and password . If you want in-depth monitoring you can specify one or several queries to be executed on the database. See also detailed SQL Database device configuration properties 181 description.

9.4.2.1.5 JMX Configuration

The JMX device driver is designed monitoring Java-based application servers and applications. See JMX device driver 140 for details on JMX monitoring configuration.

9.4.2.2 Discovering Devices and Services

Network Discovery 1055 is an action allowing to automatically or semi-automatically find network devices, create device accounts and configure service monitoring. It allows to setup monitoring infrastructure for large networks when manual operations 1050 become too tedious. Refer to Network Discovery
1055

chapter for detailed descriptions and usage instructions.

9.4.2.3 Administering Devices and Services

AggreGate Network Manager provides facilities to administer management/monitoring infrastructure. This may involve managing devices by: Varying their common properties 1050 : renaming, altering its description, type, correcting host address, suspend etc. Altering device monitoring parameters 1050 Changing driver-specific parameters Grouping
248 1050

and regrouping devices.

9.4.3 Administering AggreGate Network Manager Tools

AggreGate Platform offers different kinds of tools to facilitate network monitoring and management: alerts, widgets, charts, queries and reports, dashboards, etc. Some of these tools are ready to use out of the box; others should be properly configured beforehand. Examples of preconfigured tools are: Device Offline
1145 ,

High Packet Loss Rate 1145 , High Packet Loss Rate 1145 alerts;
1151 , 1118 ,

Ping Response Time IP Host 1154 , VMware

Ping Packet Loss Printer

1120 ,

1152

charts;

Wireless 1121 and other dashboards;

Reports and queries 1149 . Some other tools should be parameterized with concrete values to become available for usage. Many of them can be instantiated and configured for a particular device using Setup Monitoring Profile 1052 action. Another example is NetFlow charting widgets that are build from NetFlow views. AggreGate Network Manager is an extendible system. It provides great facilities to modify existing tools and create new ones to specialize system for your own specific needs and requirements. Don't hesitate to use provided tools as basements or examples for creating your own toolset that better conforms with the tasks you solve.

9.4.4 Setup Monitoring Profile Action

Setup Monitoring Profile action 892 provides user interface for adding and configuring network monitoring tools including alerts 1145 , charts 1151 and trackers 1154 . All the tools available for a device are classified into several groups according to the type of monitoring they provide:

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

Device Availability (see Availability
1091 )

1053

Processes (see Process Monitoring 1094 ) CPU (CPU Performance Monitoring 1092 ) Network Interfaces (see Network Traffic and Bandwidth Monitoring Storage Volumes (see Storage Monitoring
1093 ) 1096 )

VMware (see VMware Server Monitoring 1114 ) Apache (see Apache Web Server Monitoring Printer (see Printer Monitoring 1119 ) Performance (for tracking performance of various services) E-mail (to monitor E-mail 1112 servers) HTTP (to monitor Web 1109 servers) FTP (to monitor FTP
1112 1109 )

servers)

DNS (to monitor DNS 1113 servers) LDAP (to monitor Active Directory 1113 servers) SSH (to monitor SSH servers
1113 ) 161

Path Tracing (to monitor Traceroute

service)
1113

Generic TCP and UDP Services (to monitor TCP

and UDP

1113

services)

Monitoring groups available for a particular device depend on device type and data it provides. For example: Printer monitoring tools are supported only if the device has prtGeneralTable SNMP variable; Presence of VMware group depends on vmTable variable; Tools from Device Availabilty group can be used for any (IP-based) network device. To generate monitoring tools for a device: 1. Select Setup Monitoring Profile item in the device context menu. 2. Select groups of tools to create. 3. A separate configuration window will appear for each selected option. Add and configure one or more tools for this group.

9.4.5 Configuring Environment

This section is dedicated to questions of configuring managed network items for communication with AggreGate Network Manager. The following topics are relevant: Configuring SNMP devices
1053

Configuring WMI devices 1054 Configuring Windows to provide Windows Event Log monitoring Configuring Remote Access to WMI
189 1054

using SNMP traps

TCP/IP configuration issues 1054 in Windows operating systems Enable ICMP for availability monitoring using Ping and Traceroute.

9.4.5.1 Configuring SNMP Devices

SNMP-compliant devices should be properly configured to provide data communication. Configuring SNMP Agents 1071 section provides instructions on configuring Windows, Linux, Solaris systems, Cisco Devices, Microsoft SQL, Lotus Domino and Oracle Servers.

2000-2013 Tibbo Technology Inc.

1054

AggreGate Documentation

9.4.5.2 Configuring WMI Devices

In order to use WMI for managing a remote Windows computer, you should configure WMI service on that machine. See Configuring Remote Access to WMI 189 for details.

9.4.5.3 Receiving Windows Log Events

Windows Event Log is targeted to provide detailed information on functioning of Windows operational system and applications running under it. Windows Event Log messages should be converted to SNMP traps to be received by AggreGate Network Manager. Refer to the SNMP traps 1085 for details on receiving and processing the traps. This section presents instructions for configuring Windows machine to send SNMP traps when certain messages are added to the Windows Event Log. The SNMP Agent should be installed and properly configured to send traps to the host AggreGate Server is running on. Refer to SNMP Setup on Windows Systems 1072 (and particularly Steps to Configure SNMP Traps 1074 section) for the details.

Defining and Exporting Event Mappings

Microsoft evntwin utility is used to select events and prepare necessary data. It provides a graphical UI for selecting, configuring and exporting event log messages to be translated to SNMP Traps: 1. Start the evntwin utility from the Start (Run) menu or from a command window. 2. The Event to Trap Translator window will appear. 3. Select Custom option under Configuration type group. 4. Click Edit. The Event sources list should appear. 5. Select the events to be translated to traps (the Find button can be used to search in the list) in and click Add. 6. The Properties window should appear. The trap generation conditions can be customized here. 7. Repeat steps 5-6 for every event you are interested in (alternatively you can select several events to add using Ctrl or Shift multiple selection) 8. lick Apply button. 9. Highlight all the items in the Events to be translated to traps list and the Export... button. Choose a location and filename to save the event-to-trap mapping definitions. The exported mapping file should be a text file with one or more lines in the following format:

#pragma add <LogName> "<SourceName>" <EventID> <EventCount> <TimeInterval>

Configuring SNMP Traps

Microsoft evntcmd utility is used to configure the translation of events to traps based on information in the configuration file. To do it just run evntcmd, giving it the name of exported mappings file. If User Access Control (UAC) is used on a Windows machine, command interpreter (cmd) should be started in the 'As an Administrator' mode in order to access the evntcmd utility.

9.4.5.4 TCP/IP limitations of desktop versions of Windows

All desktop versions of Microsoft Windows, starting from Windows XP with Service Pack 2 (SP2), limit the number of half-open connections (SYN) to a maximum of 10 per second. This can negatively affect the network monitoring functionality of AggreGate Network Manager.

Network monitoring process can be significantly slowed down. If the above limit is reached, the following record can be found in Windows Event Log:

Product: Windows Operating System

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1055

ID: 4226 Source: TCPIP Symbolic Name: EVENT_TCPIP_TCP_CONNECT_LIMIT_REACHED Message: TCP/IP has reached the security limit imposed on the number of concurrent (incomplete) TCP connect attempts
Therefore it is not recommended to install AggreGate Network Manager on desktop versions of Microsoft Windows (Windows XP, Windows Vista, Windows 7) for production use in large environments. Server versions of Windows (Windows 2000, 2003 Server, or 2008 Server) do not have this limitations, and should be used instead.

9.5 Network Devices Discovery

Discovery is the act of detecting something new. In the network management industry, discovery designates a process of finding new network devices, detecting services and applications running on them, adding and configuring them for monitoring and management. Particularly, a procedure of discovery is described in Discovery Process
1055

section.

From a practical point of view, discovery supplements, extends and automates tedious task of manual (one-by-one) device addition and configuration 1050 . It helps to form a basis of monitoring infrastructure, and then maintain it in a relevant state. More specifically, device discovery can be used to accomplish several network management tasks: Interactive multiple-device discovery
1062

for initially configuring the monitoring of large network segments.

Single-device discovery 1062 that can be useful when there's a single device you want to add and configure for monitoring. Headless multiple- and single-device discovery 1062 for fully automated discovery operation (e.g., scheduling it to be invoking periodically, or in response to some events). Rediscovering services 1063 running on a particular device that was added earlier. Automatically discover and add 1063 devices that uncover themselves by sending notifications of some kind (e.g. Syslog message, or SNMP traps) to AggreGate server. In AggreGate Network Manager discovery is available via Network Device Discovery and Discover Single Device actions 892 in Devices (users.admin.devices) context, and can be invoked through certain userinterface tools and hooks (like context menus, jobs, favourite items, etc.) as described in Using Discovery 1061 section.

9.5.1 Discovery Process

In general, discovery procedure includes two major stages, each consisting of several smaller steps: I. Search 1056 : Find online devices and services they run according to the search parameters 1056 provided. The stage is divided into four steps, presenting search parameters specification 1056 (preparation part) and scanning 1060 : 1. Services Selection and Setup 1056 . Specify a list of services to look for during the discovery. The service list is a part of search parameters 1056 . 2. Host Addresses Specification parameters 1056 for details). 3. Discovery Tuning
1059 . 1058 .

Select addresses to be scanned during the discovery (see search

Configure how the search will be performed (accuracy, speed, time limits etc.).

4. Scanning 1060 . The actual network discovery is performed at this step. The system iterates through the list of specified IP addresses and checks the availability of the selected services. II. Result Processing 1060 : Add some or all or the discovered device and configure corresponding services. The stage includes the following steps: 5. Discovery results review 1060 . Select devices to add/update and services to be monitored. 6. Applying the results 1061 . Device accounts are created/updated at this step. Monitored services configuration is updated in the device account settings. 7. Mapping (optional step). If discovery is running in interactive mode, the user is prompted to create a network map 1066 for the discovered devices. 8. Discovery Status Report 1061 . Final discovery results are shown to the user. This includes the list of scanned/ created/updated devices, discovery errors, and single-host scanning tasks 1060 statuses.

2000-2013 Tibbo Technology Inc.

1056

AggreGate Documentation

9.5.1.1 Search Stage of Discovery

Search is the first stage of Discovery Process 1055 . Its objective is to find available network hosts and detect the services/applications they're currently running. This is achieved by scanning 1060 IP addresses for specified services, i.e. trying to communicate with each of the services assigned for discovery at a particular IP address. How the scan is actually accomplished is determined by discovery search parameters. Search parameters specify what to search for, where to search, and how to search:
1056

What to scan for? This question is answered at Service Selection are specified along with scan options for each. Where to scan? Host Addresses Specification How to scan? Discovery Tuning accuracy.
1059 1058

step with a list of services to be discovered

step allows to build the list of IP addresses to be scanned.

step tells how to go about the scanning process concurrency, time limits, and

The way how parameters are set depends on the discovery mode: In a full interactive 1062 mode a wizard drives a user through the procedure of specifying discovery parameters. In single-device interactive
1062

and automatic

1063

modes default discovery settings

270 .

1063

are used.

Parameters of a headless 1062 discovery are specified in job properties

Thus, we can say the Search stage is divided into two parts: parameters 1060 itself i.e. search itself with respect to the parameters provided.

specification

1056

and scanning process

9.5.1.1.1 Service Selection and Setup

Answering "What to discover?" 1056 question, the Service Selection and Setup step specifies a list of services to detect along with parameters to be used for detecting service availability. Ping Service is the only mandatory service to be checked during discovery, as it is used to determine if a host at specific address is alive (online) during scanning 1060 procedure. Other services AggreGate Network Manager are optional. Service parameters are comprised of the following fields:

Discover flag denotes service as taking part in discovery (checked) or excluded (unchecked). Timeout specifies a period of time alloted for a single attempt to detect the service during scanning Retries sets a number of attempts to detect the service as available. Service-Specific Options defines service detection parameters used by scan procedure
1060 . 1060 .

The following table provides a list of services AggreGate Network Manager is able to discover, along with associated service-specific options and a short description of discovery procedure. Service Name Ping Discovery Options Discovering Activity

Packet Data Size

(see also Ping Properties
153 )

Check whether the host properly answers to Ping (ICMP echo) requests. Check whether SNMP agent is running on the host. This is performed by sending SNMP GETNEXT request (considering the options provided). If the device responds with a correct SNMP value, the service is considered "alive".

SNMP

Protocol Port SNMP Protocol Version Read Community Maximum PDU Size Security Level Username Authentication Protocol Authentication Password Privacy (Encryption) Protocol

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1057

Privacy (Encryption) Password

(see also SNMP Connection Properties 176 ) TCP Services

Port Timeout
(see also TCP Service Properties 154 )

Check whether device listens the specified TCP ports by attempting to establish a TCP connection within a given Timeout. Only ports that AggreGate Network Manager has successfully connected to will be configured for future monitoring. The Discovery Timeout setting is ignored by this service. No data is send to the host during discovery.

UDP Services

Port Timeout Data To Send

(see also UDP Service Properties 155 )

Check whether the host replies when user-defined data is sent to its remote port as an UDP datagram. The port is considered "available" if AggreGate Network Manager has received any reply to its datagram. Only ports that AggreGate Network Manager has received replies from will be configured for future monitoring. The Discovery Timeout setting is ignored by this service.

HTTP

Port URL Request Type

(see also HTTP Properties)

Check whether a web server is available on the given Port by sending GET or POST request with the specified URL to the remote host and reading the reply.

FTP

Port
(see also FTP Properties
160 )

Check if the device accepts FTP connection at the port specified. Check whether the device answers to a predefined DNS lookup request sent to the Port via the specified Protocol (UDP or TCP). If the device correctly answers the request, we deem DNS service "alive". Check whether the device accepts a connection at the specified Port and replies with some data. If the connection is successfully established and a non-empty reply is received, the service is deemed as "alive". Check whether the device accepts a connection at the specified Port. If the connection is successfully established and a nonempty reply is received, we consider the service to be "alive". Check whether the device correctly answers HELO command of Simple Mail Transfer Protocol (according to RFC 821). If the device responds with OK reply (reply code 250), SMTP service is considered available. Check whether the device accepts an SSH connection (via SSH2 protocol ) at the specified Port. If the connection can be established, the service is deemed as "alive". Check whether the device replies to DHCP requests. AggreGate Network Manager sends a DHCP discovery request and waits for a reply. If the reply is received within the discovery timeout period, the service is denoted as available. Check whether the device accepts LDAP connections with the specified parameters. We deem LDAP service "alive", if the connection was successfully established and LDAP auth didn't fail.
165 )

DNS

Port Protocol
(see also DNS Properties
156 )

IMAP

Port
(see also IMAP Properties
158 )

POP3

Port
(see also POP3 Properties
157 )

SMTP

Port
(see also SMTP Properties
159 )

SSH

Port
(see also SSH Properties
163 )

DHCP

MAC Address
(see also DHCP Properties
164 )

LDAP

Port Username Password

(see also LDAP Properties

Radius

Authentication Port Username Password

Check whether the device accepts Radius authenticate requests . If the device returns an Access Accept (see RFC 2138) response, the service is considered available.

2000-2013 Tibbo Technology Inc.

1058

AggreGate Documentation

Radius Secret
(see also Radius Properties WMI
166 )

Domain Username Password Namespace

(see also WMI device driver
186 )

Check whether the device accepts WMI connections.

Parameter Variants
All the services excluding TCP Services, UDP Services and Ping, support multiple parameter variants to be used during scanning. The variants are provided as multiple records in service discovery options table. AggreGate Network Manager tries to find a service using each variant specified. The server stops iterating serice parameter variants when the first "working" variant is found.

Centralized Storage of Discovery Options

When a new discovery process is started, all service discovery options are loaded from the Network Device Discovery Plugin global configuration 951 .

9.5.1.1.2 Host Addresses Specification

Host Address Specification step specifies answers "What to scan?" IP addresses and/or host names to be scanned 1060 .
1056

question. The definitive answer is a list of

The discovery is often performed in large network segments including hundreds or even thousands of addresses. Manual creation of IP lists by adding individual addresses one by one is a very tedious task in these circumstances. Therefore AggreGate Network Manager allows to specify ranges of addresses making its users' life a bit easier. Nevertheless the problem is not solved yet, as network administrators often deal with a big numbers of sub-networks, segments and address ranges, which are still exhausting to type in. Fortunately in most cases there's no need to specify the ranges by hand, as the information is already stored in networking devices, such as routers and switches. AggreGate Network Manager acquire network specifications via SNMP, and uses them to facilitate address specification procedure. Thus the list of addresses to be scanned can be formed in three steps: 1) Specify Seed Router Addresses. Seed router is an SNMP-enabled router or switch that can be used to obtain information about IP subnets available in your network. Each of the specified seed routers is requested for network interfaces it supports, and then the interface addresses every network interface is associated with. As far as an interface address represents a network segment (or a subnet), AggreGate Network Manager gets all the subnets the router aware of. They are included in the IP ranges and subnets list at the next step. Seed routers to be used are specified by IP Address or Host Name values together with SNMP Connection Properties used to acquire the required data from the router/switch. 2) Specify IP Ranges. There are two ways to specify an IP range: a) By an IP address and network mask b) By a pair (start and finish) of IP addresses. All IP addresses belonging to the specified ranges will be added to the list of individual IP addresses to be edited at the following step. 3) Specify individual IP Addresses and Host Names. The user can edit a list of addresses by modifying, removing or adding a particular address. Considering that it's often unnecessary and even pointless to edit large list of addresses (e.g. automatically generated from IP ranges), system offers to skip this step if there are more than a thousand of addresses in the list.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1059

9.5.1.1.3 Discovery Tuning

The Discovery Tuning step determines how long the discovery will last, how many computational resources will be consumed, and how accurate the result will be, effectively answering the "How to discover?" 1056 question. The following parameters are introduced to provide control over the discovery process.

Concurrency (Thread Count)

Scanning 1060 comprises many individual tasks for detecting particular services running on individual devices. Since each of these tasks usually involves relatively long delays (from hundreds milliseconds to several seconds), executing them sequentially can take a while. Instead, they can be executed concurrently for a significantly reduced total discovery time. Concurrent scan is executed by several simultaneously running threads. The total number of the parallel threads is determined by Concurrency (Thread Count) parameter. Having too many threads would also defeat the purpose. Your processor will be struggling to keep up with the multiple threads (for example, 2000 threads on a dual-core system) and discovery performance will degrade. For choosing the thread count you should consider number of hosts to be scanned, along with available resources and system limits. This is case-specific parameters, and it's impossible to recommend a concrete algorithm for determining thread count "in general". The following rules of thumb can be recommended here: The thread count should be selected with respect to the system limits and recommendations (e.g. few hundreds on desktop Windows OS). Respecting mentioned limitations, the thread count can be selected close to the number of hosts to be scanned, but not exceeding it. If other processes are running on your system, you may have to reduce the number of threads. Consider what else is consuming system resources beyond AggreGate.

THREAD COUNT SUGGESTIONS

Threads 10 100 1000 Discovery Performance

Slow discovery with minimal overhead, suitable for small networks. Optimal value for most networks, average overhead. Large overhead and heavy CPU load (up to 100%). Suitable for large networks.

Maximum Total Discovery Time

As in some circumstances discovery can take a very long time, it can be explicitly limited by Maximum Total Discovery Time parameter. As soon as discovery time exceeds this threshold, the scan process will be compulsory finished. In this case the scan result will include all devices and services discovered by the time.

Maximum Single Host Discovery Time

Time limits can be applied not only to overall discovery process, but also to single-host scanning tasks 1060. If the scanning of a particular host is not finished within the Maximum Single Host Discovery Time period, it is stopped and denoted as unfinished. The discovered services will be kept for result processing 1060 stage.

Discover Ping-Failed Devices

Being potentially a very long process, full scanning 1060 of services is preceded by online status detection 1060 for each of the specified hosts. By filtering out "dead" (offline) addresses, we can significantly reduce the duration of discovery process. However, this can cause inaccuracy since some existing hosts may decline ping requests. The Discover Ping-Failed Devices parameter allows to choose between speed or accuracy. If the parameter is disabled, the scan will ignore the hosts not answering ping requests in favor of speed. Otherwise, all specified hosts will be fully scanned, providing more accurate results.

Device Descriptions
It is often desirable to use descriptive host names instead of flat IP addresses where possible, i.e. automatically assign descriptions to discovered devices. AggreGate Network Manager supports three methods for this: 1. Assign directly a provided IP address (or host name) as a description for the discovered device. This is the fastest but the least descriptive method. In some cases network administrators prefer to describe device accounts with their IP addresses as they can form a well-composed system and provide uniform host-identification structure.

2000-2013 Tibbo Technology Inc.

1060

AggreGate Documentation

2. Use reverse DNS name resolution to find a fully qualified domain name for the provided IP address. Reverse lookup queries can be time-consuming, so this method can increase the overall discovery time. 3. Take advantage of SNMP data by utilizing SNMP sysName variable as device account description. It keeps "an administratively-assigned name for this managed node" (see RFC1213), and often (by convention) this is the node's fully-qualified domain name. SNMP requests are typically faster than reverse DNS lookup, so this method can improve discovery performance compared to the previous method. AggreGate Network Manager will still use reverse DNS lookup for devices that doesn't support SNMP.

9.5.1.1.4 Scanning
Scanning is the key step of discovery process that performs the actual detection of services available on network hosts. Given a particular address, AggreGate Network Manager checks availability of the services selected for the discovery. This is called an single-host scanning task. It comprises the two steps: 1. Checking Ping service 1056 . ICMP Echo Requests are used to test device availability. If the device correctly responds to the ping requests, we deem the device as available ("alive"), and continue with the next step of scanning. Otherwise, depending on the value of Discover Ping-Failed Devices 1059 parameter we either (if the Discover PingFailed Devices parameter is set to true) go to the next step, or just consider the device unavailable skipping the next step (if the Discover Ping-Failed Devices is false). 2. Checking other services. The system tries to detect the availability of every service selected for discovery. Note, that the overall scanning process is limited by Maximum Total Discovery Time are limited by Maximum Single Host Discovery Time 1059 .
1059 ,

while single-host scanning tasks

9.5.1.2 Result Processing

This is the second stage of discovery process. Having the search stage finished, we now have to process and apply the results we've just obtained. This involves: Selecting the discovered devices and services which are of interest now Reviewing and optionally changing their discovered configuration (see Discovery Results Review Applying the selected results (see Applying Discovery Results
1061 ) 1066 , 1060 )

Interactive discovery wizard also prompts user to create a network map Report 1061 , summing up all results of the discovery.

and then shows Discovery Status

9.5.1.2.1 Discovery Results Review

Once the search 1056 stage is completed, we get a list of discovered devices and services. Some of the results are useful and should be applied to renew current monitoring configuration, while others should be just discarded. This can be done in interactive mode by editing the Discovery Results: Field Create/Update Device Name Device Description Device Type Discovered Services Description Check to create a new device account of update an existing one. Name of the device account. AggreGate Network Manager proposes a default value, but the operator can override it. Device description is automatically generated according to Device Descriptions parameter, but can be edited
1059

Automatically detected device type. System operator may change it based on the type/ purpose of the real device. A selectable list of services to be monitored and their parameters: Field Use Service Service Name Service Parameters Description Check if the service should be monitored. Service name and/or description. Service-specific monitoring parameters.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1061

IP Address or Host Name

Shows address or host name of the device.

In headless mode accounts for all discovered devices will be added/updated. All discovered services will be enabled for monitoring using service-specific settings set up in job parameters 266 .

9.5.1.2.2 Applying Discovery Results

At this step, server creates/updates device accounts and enables/disables monitored services. When existing device accounts are updated, services that were not discovered on them are, however, not disabled. We might say that existing services are considered "temporary unavailable". The only exception here is SNMP service that is disabled if discovery process wasn't able to connect to an SNMP Agent running on a host. SNMP service is explicitly disabled because: SNMP monitoring consumes significant system resources (CPU time, memory, disk I/O) SNMP service is enabled by default for manually added devices

9.5.1.2.3 Discovery Status Report

Discovery Status Report sums up final results of the discovery, showing the list of involved devices and status information: Field name IP Address or Host Name Finished Status information Host selected for the discovery. Indicates status of a corresponding single-host scanning task Yes if the the host scanning was successfully finished, No if the host scanning was interrupted for some reason or not started at all. Result Summarizes the discovery results for the host, consolidating outcome of search processing 1060 stages: interruption cause for the unfinished single-host scanning tasks
1060 ; 1056 1060 :

and result

basic information for the newly created device accounts, including their description and type; notes for the updated existing device accounts; enabled/disables services. Empty value in the field means (depending on the value of Finished field): if Finished value is No, an empty Result value shows, that the scan of the corresponding device were not started (due to discovery process interruption, e.g. because of Maximum Total Discovery Time limit exceeded); if Finished value is Yes, an empty Result value shows, that nothing changed for the device (caused by either no alive service was detected, or discovery result was ignored as not selected to be applied).

9.5.2 Using Discovery

Practically, discovery use cases can be divided in two groups: in some cases we want to scan several hosts detecting the alive ones and finding services they offer; in other cases there's essentially a single host we want to examine and find services running on it. Thus, AggreGate Network Manager offers two discovery actions: multiple-device discovery and single-device discovery.

2000-2013 Tibbo Technology Inc.

1062

AggreGate Documentation

Just as any AggreGate action 892 , discovery can be started in one of two modes 893 : either interactive, or headless. The latter allows to automatically repeat discovery with specified parameters (for example scheduling 266 it), while the former provides a better control over the process being supported supported by a wizard that allows to control discovery process 1055 by specifying parameters for every discovery step, or, alternatively, allowing to cancel the discovery. In general, discovery are implemented as Network Device Discovery and Discover Single Device actions 892 placed in Devices (users.admin.devices) context. The actions can be invoked using certain user-interface tools and hooks (like context menus, jobs, favourite items, etc.). The following table introduces types of discovery, classified into four groups:

Multiple-Device Discovery Action Interactive Mode Headless Mode Interactive Multiple-Device Discovery 1062

Single-Device Discovery Action Interactive Single-Device Discovery Rediscovering

1063 1063 1062

Headless Multiple-Device Discovery

1062

Headless Single-Device Discovery Automatic Discovery

1063

Follow the links for the details on how to use all discovery types.

9.5.2.1 Interactive Multiple-Device Discovery

Interactive Multiple-Device Discovery allows to scan large network segments, fully controlling the process at a high-grained level with an easy-to-use GUI. A user is guided through all the discovery steps 1055 by interactive wizard. The wizard allows to track the process, review and modify options for all the discovery aspects, and interrupt the process at any step. To invoke discovery in the interactive multiple-device mode you can select a Network Discovery ( a Context Menu
786

) action

892

from

or Related Actions

786

pane of Devices (
626

) context

863

in the System Tree

784 .

Use a Network Discovery Favourite

item for quick access to Full Interactive Discovery action.

9.5.2.2 Interactive Single-Device Discovery

Interactive Single-Device Discovery provides a fast way to discover services at a particular host. It just prompts for a host name or IP address to discover services on. No additional input is required as the default discovery settings 1063 are used and the results then are silently applied: Device account with the address/name provided will be created if it doesn't exists; All the discovered services will be configured for monitoring on new/existing account. The Interactive Single-Device Discovery can be invoked by selecting a Discover Single Device action Context Menu
786 892

from a

or Related Actions

786

pane of Devices (

) context

863

in the System Tree

784 .

9.5.2.3 Headless Multiple- and Single-Device Discovery

Headless mode assumes no interaction with the user, and discovery options are predefined when the action is configured for non-interactive execution: as part of alert's Automatic Corrective Actions 227 or scheduled job 266 's properties. The Network Device Discovery and Discover Single Device actions 892 are located in Devices (users.admin.devices) context. To create a scheduled discovery job: Create a new scheduler task by selecting Create Scheduled Job ( Fill-in Scheduled Job Properties: ) action from Scheduled Jobs ( ) context.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

o Select Devices (

1063

) context (under proper user account) in Context Mask field.

o Make sure selected Action is Network Discovery. o Specify the proper Discovery Click OK to create the new job. Add one or more Triggers to define discovery schedule. Parameters.

9.5.2.4 Rediscovering Device Services

Rediscover Services is a discovery action applied to an existing device account. Rediscovering for a particular device is available as a Rediscover Services action 892 in Context Menu 786 or Related Actions 786 pane of the device context . Once rediscovery wizard is started, it requests the services to be discovered (see Service Selection and Setup section), performs the scanning 1060 , presents the results for review 1060 , and finally applies 1061 them.
1056

9.5.2.5 Automatic Discovery

Automatic Discovery allows to invoke Single-Device Discovery 1062 action in a headless 1062 mode automatically in response to SNMP traps and/or SysLog messages. This helps to automate task of discovering new devices and keeping the monitoring configuration up-to-date. To enable Automatic Discovery: For SNMP traps: enable SNMP Trap Sources Automatic Discovery in Network Host plugin global settings 951 ; For Syslog messages: enable Syslog Message Sources Automatic Discovery in Syslog plugin global settings.

9.5.3 Default Discovery Settings

Default Discovery Settings provide default parameters of discovering and subsequent monitoring different services. These settings are used in single-device discovery 1062 , automatic discovery 1063 , and as default values for full interactive 1062 and headless 1062 discovery. To edit default discovery settings, access the global configuration
951

of Network Device Discovery plugin

950 .

9.6 Network Topology Monitoring

This section covers discovery and monitoring of network topology, i.e. links between individual ports and interfaces of different network devices. There are several primary aspects of topology monitoring: Topology discovery 1063 Topology editing
1064 1065

Topology browsing

9.6.1 Network Topology Discovery

AggreGate Network Manager can discover network topology at layer 2 (link layer) and layer 3 (IP network layer) of OSI network model. The topology discovery is based on analyzing information collected using diverse network protocols, primarily SNMP protocol.

Prerequisites
To allow AggreGate Network Manager successfully discover the topology links in your network, make sure that the following conditions are met: You've completed network device discovery 1055 based on scanning subnets of your IP networks. Another option is to manually create accounts for all or some of your network devices.

2000-2013 Tibbo Technology Inc.

1064

AggreGate Documentation

Only devices that have corresponding server-side device accounts

113

will be shown on the topology map.

Accounts of all devices that support SNMP, especially switches and routers, have SNMP polling enabled and SNMP community names or SNMP v3 auth credentials properly configured. Synchronization with
126

of all devices is successfully completed (in most case, fully synchronized devices are represented
784 ).

icon in the System Tree

Automatic Topology Discovery

The AggreGate Server is pre-configured to perform periodic network topology discovery every 5 minutes. The discovery is initiated by Network Topology Discovery scheduled job 266 . To disable automatic topology discovery or change its period, disable the scheduled job or change its simple schedule 270 settings respectively.

Manual Topology Discovery

To manually start the topology discovery, open context menu of the Server node ( Network Topology Discovery from Network Management submenu. ) in System Tree and select

Topology Discovery Process

In most cases the network topology discovery will be finished in mere seconds, since all required information is already contained in server-side snapshots 115 of network devices. Once the discovery is finished, it's possible to see the number of newly discovered and updated links in the status bar of AggreGate Client.

9.6.2 Editing Network Topology

The network topology information is contained inside the accounts information about incoming and/or outgoing links.
113

of network devices. Each device account contain

The link always connects two devices, but only one of their accounts will contain information about this link.

The part of topology database related to a certain device can be edited by launching Edit Device Properties from a network device context and switching to a Topology ( ) tab:

677

action

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1065

Topology Link Settings

Topology database contains the following information about each link: Status . Links in Auto-discovered status are created during topology discovery. Such links will be automatically managed (edited/deleted) during the subsequent discovery cycles. Links in User-defined status are deemed as manually added or overridden. Such links are visible on the topology maps, but never edited/deleted by the discovery process. And finally, links in Deleted status are neither shown on the maps nor edited/deleted by the discovery process. This status helps to hide links and protect them to be automatically rediscovered and created again. Type . Link type: OSI Level 2, Level 3, or generic Network link. Target. The peer of this link, which is a path
863

of device context that the link leads to.

Source Interface . Number of network interface on the source device. Target Interface. Number of network interface on the target device. Description . Custom link description.

9.6.3 Browsing Network Topology

Network topology is best of all visualizable using a graph. In AggreGate, the topology maps are enabled by widgets 312 , and particularly Graph 369 widget component. Topology graphs are really convenient for network topology and status monitoring due to support for: Zooming, panning, rotating and shearing Picking and moving individual nodes Viewing status and bandwidth of individual links and their gateway interfaces Viewing status of network devices Clicking-through to the dashboards of individual devices

Network Topology Map

The AggreGate Network Manager installation includes a Network Topology Map widget that is pre-configured for providing optimal view of the whole topology:

However, this widget is fully customizable as any other AggreGate's data management tools. It's possible to change: The subset of network devices shown on the topology map Topology graph layout type and parameters

2000-2013 Tibbo Technology Inc.

1066

AggreGate Documentation

Map type (level 2, level 3, or combined) Map update period And many other settings

9.7 Network Mapping

Network maps and diagrams are used to visualize state of monitored IT infrastructure. Network Maps are a type of Device Maps 616 , and they can depict any monitored network equipment including routers, switches, servers, workstations. Note that network maps are static. See browsing network topology network topology graphs.
1065

to find out how to build dynamic

Maps can be fully customized to depict the network in the most appropriate way: You can set up background color, texture or image. Network devices can be presented by either predefined or custom images. Device status can be represented by text labels and/or encoded by color. Maps can be nested to vary levels of detail (meaning, you can drill down and zoom in). The AggreGate Network Manager distribution includes hundreds of dynamic vector images that can be used on network maps. Here is an example illustrating just a few of them:

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1067

9.8 Event Masking and Device Dependencies

AggreGate Network Manager has a special implementation of Event Masking
884

strategy that solves the following tasks:

Disables polling of network hosts that are not available from the AggreGate Server due to failures of intermediate device(s) Suppresses alert initiation by devices that are currently unavailable due to intermediate device failures The event masking technology is based on device-to-parent relationships that are defined by Device Connectivity model 303 included into AggreGate Network Manager distribution. This model: Adds Parent Devices table and Connectivity Expression variable to every Network Host
150

device.

Sets Dependency Expression 124 property of every newly created network host device so that its connectivity check is performed in the beginning of every synchronization cycle 126 . Device synchronization (polling) is disabled if connectivity check fails. Configures connectivity check functions so that the device is deemed unavailable due to parent device failures if ping to device itself and its parents fails.

Event Masking Configuration

The basic configuration of event/alert masking and suppression is very simple: Right-click on a Network Host device Select Edit Additional Properties Switch to the Device Connectivity tab Open Parent Devices table Fill table with network device(s) that is (or could be -- in case of dynamic routing) the next hop on the network route from the device being configured to the AggreGate Network Manager server

2000-2013 Tibbo Technology Inc.

1068

AggreGate Documentation

9.9 SNMP Monitoring and Management

Simple Network Management Protocol (SNMP ) is a UDP-based network protocol, widely used to monitor and control network-attached devices, services and applications. SNMP is defined in a series of Internet Engineering Task Force (IETF) standards, covering not only the protocol itself, but also the Management Information Base (MIB) specification language (SMI and its successor SMIv2), a series of standard MIB definitions, and even the architecture of agent implementations. SNMP overview and basic concepts are introduced in SNMP Basics
1068

section.
154 .

In AggreGate Network Manager SNMP support is provided by Network Host device driver SNMP read and write operations SNMP-compliant device monitoring by:

The driver provides:

o polling (periodical reading of full of partial management information available via SNMP) o receiving and processing SNMP traps managing standard and custom SNMP devices caching management information on the server storing management information in database managing monitoring options: o synchronization periods o polling strategies: all OIDs, OIDs recognized by MIB directory, or the important ones only o running automatic actions in response to SNMP traps MIB management, including: o a set of standard MIBs o tools for adding and configuring usage of custom MIBs SNMP is used in network discovery: to find seed routers and get network topology information to discover SNMP-compliant devices to get some of their properties Various practical aspects and details of SNMP utilization in AggreGate Network Manager are covered in Using SNMP section.
1070

9.9.1 SNMP Basics

SNMP is the communication protocol between managers and managed systems. A managed system runs a software component called an agent, which reports information via SNMP to the manager. The management data is exposed in the form of variables describing the system configuration. These variables can then be queried (and sometimes set) by managing applications, e.g. AggreGate Network Manager. The communication of management information among management entities is realized through the exchange of protocol messages. A particular SNMP message is often called Protocol Data Unit (PDU). This section covers the following topics: SNMP Versions 1069 Structure of Management Information 1069 SNMP Operations SNMP Security
1070

1070 .

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1069

9.9.1.1 SNMP Versions

AggreGate Network Manager supports SNMPv1 (Simple Network Management Protocol version 1), SNMPv2c (Community-Based Simple Network Management Protocol version 2) and SNMPv3 (Simple Network Management Protocol version 3). SNMPv1 is the initial implementation of the SNMP protocol. This is still the primary SNMP implementation that many vendors support. The current state of the SNMPv1 is defined by RFC 1157, RFC 1155, RFC 1212, RFC 1213, RFC 1215. SNMPv2c, defined in RFC 1901, RFC 2578, RFC 2579, RFC 2580, RFC 3416, RFC 3417 and RFC 3418, improves version 1 in the areas of performance and manager-to-manager communications. SNMPv2 is incompatible with SNMPv1 in two key areas: message formats and protocol operations. The main issue about SNMPv1 and SNMPv2c is their poor security model
1070 .

SNMPv3 (also known as STD0062) enhances security by adding confidentiality, integrity and authentication features. This SNMP version is defined by RFC 3411 -- RFC 3418. IETF designated SNMPv3 a full Internet Standard (the highest maturity level for an RFC) and recognizes it as the current standard version of SNMP. In practice, all the mentioned SNMP versions are currently widely used. RFC 3584 describes general aspects of coexistence between these SNMP versions.

9.9.1.2 Structure of Management Information

How management information is represented and what kind of data it can contain is defined by The Structure of Management Information Version 1 (SMIv1 , RFC 1155) and The Structure of Management Information Version 2 (SMIv2 , RFC 2578). Managed systems expose their configuration in the form of managed objects or variables . The values of managed objects can then be queried and sometimes set by managing applications. Managed objects are describe by several attributes. The most important are object identifier (name), type, and encoding.

OBJECT IDENTIFIERS
Object Identifier (OID) uniquely defines a managed object. Managed objects are organized into a treelike hierarchy. Object ID represents the place of a particular object in this hierarchy as a series of integers based on the nodes in the tree, separated by dots (.). This is known as a numeric form of OID. There's also a human-readable form, that represents each OID as a series of names. Example: A textual description of a managed entity is represented by an object with numeric ID 1.3.6.1.2.1.1.1, which corresponds to a "human-readable" name iso.org.dod.internet.mgmt. mib-2.system.sysDescr.

TYPE
A type of managed object within context of SNMP is defined by a subset of Abstract Syntax Notation One (ASN.1). ASN.1 specifies a machine-independent form of data representation and transmission between managers and agents. There are several basic types defined. They can be used to to define more complex objects, containing other objects and so on, thereby composing parts of treelike hierarchy we mentioned a bit earlier. The descriptions of managed object are typically grouped together according to a specific management task, device, or vendor. These descriptions are stored in MIB files. They are used by network management system to monitor and manage network devices, services, tasks, etc. For example, AggreGate Network Manager is provided with a set of the most important MIBs out of box. Vendor- or task-specific MIBs can be added to extend functionality of <%AGNMRefer% >. to the Managing SNMP Files 1080 sections for more detailes about MIB files management in AggreGate Network Manager. In SNMP a set of related variables can be grouped together to form larger structures represented as tables. Thus, objects can contain values of two kinds: scalars or tables. Scalars have a single value. For example, the iso.org. dod.internet.mgmt.mib-2.interfaces.ifNumber (1.3.6.1.2.1.2.1) has a scalar number that represents the total number of interfaces (ports) available on a network device. Tables provide several records with the identical structure. For example, iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable (1.3.6.1.2.1.2.2) variable contain a list of interface entries, each representing details about a particular network interface, like its display string, physical address, bandwidth etc.

ENCODING
Managed objects are encoded into string of octets to be transmitted over network. The encoding and decoding algorithms used in SNMP are described by Basic Encoding Rules (BER).

2000-2013 Tibbo Technology Inc.

1070

AggreGate Documentation

9.9.1.3 SNMP Operations

SNMP standards specify a set of operations that can be invoked by manager or agent to perform their management/ monitoring tasks. All the functions agents provide are modeled by SNMP as read and write operations applied to variables agent exposes.

Read And Write Operations

There are several SNMP operations defined by standards. We'll group those operations into two main categories according to the basic management operations: read (monitoring) operations, and write (control) operations.

READ OPERATIONS
Monitoring tasks can be performed by read operations. Here are included polling operations initiated by manager and unsolicited notifications (events) sent by agents. Polling operations are implemented as various get operations (e.g. GetRequest, GetNextRequest, GetBulkRequest), while events are presented by Trap and InformRequest operations.

WRITE OPERATIONS
Control operations are implemented as alterations, i.e. write operations, of SNMP variables exposed by managed agent. Specifically, SetRequest operations are used to initiate a remote modification of agent's variables.

Confirmed And Unconfirmed Operations

The SNMP protocol has been designed to support confirmed as well as unconfirmed operations. For example, the Trap is an unconfirmed operation, while the InformRequest is a confirmed one. The confirmed operations were introduced to establish a mechanism of reliable SNMP data delivery and processing. For example, traps are not guaranteed to be delivered and processed by the manager. Even a reliable transport like TCP does not ensure that, because the management application can crash while accepting and/or processing the data. With a confirmed SNMP operation, the receiving SNMP engine acknowledges that the data was actually received. For example, the response to an InformRequest protocol operation indicates that the notification was delivered, passed the security model and processed by manager. Similarly, the response to a SetRequest indicates that the write request was actually processed by agent.

9.9.1.4 SNMP Security

SNMP security is based on so called Community Strings , which play a role of passwords. Managers and agents use the community strings to authenticate each other for performing different kinds of operations. There are three community strings controlling different kinds of activities: The read-only community string is used by agent to authenticate manager for performing read operations. The read-write community string is used by agent to authenticate manager for reading and modifying data values. The trap community string is used by manager to decide if it can trust the event notification. The main security issue of SNMPv1 and SNMPv2 is that the community strings are transmitted as clear text. This makes the managed network extremely vulnerable to snooping by packet sniffing. SNMPv3 introduces encryption of community strings, and thereby significantly enhances security of management operations. Although SNMPv3 makes your network much more secure, it is still subjected to various attacks, and security aspects should be considered thoroughly. It is recommended to consider the use of the SNMPv3 in order to provide SNMP security in your network. Specifically, the User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3) and the View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP) should be taken into account and used.

9.9.2 Using SNMP in AggreGate Network Manager

AggreGate provides monitoring of custom SNMP devices by offering facilities for: Communicating with SNMP devices using Simple Network Protocol device driver Receiving SNMP traps from network devices Editing Management Information Base directory 1080 (adding, removing, and modifying custom MIB files as needed) Processing any custom data acquired from SNMP Devices and representing it as required by AggreGate's universal facilities

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1071

AggreGate requests complete information about all available SNMP objects (OIDs) via an SNMP Walk procedure (i.e. multiple GetNextRequest calls). The required values are periodically read (see also Synchronization 126 ) and all the acquired values are cached (see also Settings Cache 115 ). The default synchronization period for SNMP devices is 24 hours. Some objects are polled with much shorter periods, e.g. network interface and processor statistics data are read every 15 minutes and every 30 seconds, respectively. SNMP is intensively used by AggreGate Network Manager for managing network items. This involves several tasks: Configuring
1071

managers and agents to make use of SNMP communications.

Monitoring 1084 network items by reading the values of their SNMP variables, and listening to management events sent as SNMP traps. Calculating characteristics of network items, representing them in a handy form, analyzing, detecting, problems, making decisions using the collected SNMP data 1086 . Controlling
1086

the configuration and state of managed items by changing values of SNMP variables they provide.
1087 .

Generating SNMP traps

Discovering devices and services, where SNMP is used to obtain data from routers and switches, and to find SNMP agents.

9.9.2.1 Configuring SNMP

How to setup SNMP monitoring and management? As there are two parts involved in the management process: manager and managed item (agent), both sides should be properly configured to communicate via SNMP. Accordingly, the two section are introduced in this chapter, covering both SNMP agents configuration 1071 , and AggreGate Network Manager setup 1079 .

9.9.2.1.1 Configuring SNMP Agents

The chapter overviews SNMP agent configuration aspects, and provides detailed instructions for configuring SNMP agents on some network systems.

Agents Configuration
Typical SNMP agent is implemented as a software component running on a network device. The software component should be properly installed and configured. The installation/configuration procedure heavily depends on the type of network system and software environment the agent will be living in. Refer to the appropriate section listed below to setup SNMP on a particular type of network system. The following information is required for configuration: Community names in your network Trap destinations for each community IP addresses and computer names for SNMP management hosts See the following chapters for detailed SNMP agent configuration instructions: Windows systems 1072 Linux systems
1075

Solaris systems 1076 Cisco Devices 1077 Microsoft SQL Servers 1078 Lotus Domino Servers 1078 Oracle Servers 1078

2000-2013 Tibbo Technology Inc.

1072

AggreGate Documentation

Common Parameters Settings

All SNMP devices share the following common configurable parameters: Parameters sysLocation sysContact sysName Read-only access community string Read-write access community string Trap community string Trap destination Description Physical location of the device being monitored. Identifies the primary contact person for the device. Should be set to the fully qualified domain name (FQDN) of the managed device. In other words, it's the hostname associated with the managed device's IP address. Read-only community string is used to get access for retrieving management information from SNMP agent. Using read-write access community string, the manager can actually change MIB variables on the network element. Trap community string will be included in the traps the device sends, and trap managers can use it to decide whether or not to process a trap received. Addresses to which traps are sent.

Devices can have variants of the access and trap parameters. For example, Cisco devices supports different community strings for different parts of the MIB to allow fine-grained access control for paticular groups of variables. Many vendors allow you to place restrictions on the hosts that are allowed to make SNMP requests, providing another level of security, additional to community strings. There is a host of configuration options you can meet while managing network systems from various vendors. Refer to your device/software manuals, or other types of documentation available, like Request for Comments (RFC).

Security Issues
Don't forget to change default community strings to the values that are hard to guess. Don't choose dictionary words, use mixed-case letters and numbers instead. Use different strings for read and write communities. A serious problem is that the read and write community strings are sent as a plain text via SNMPv1 and v2. Therefore, the community strings are potentially available to anyone with access to a packet sniffer, i.e. almost anyone on your network with a PC and widely available software. You can limit the devices that can make SNMP requests, if your agent supports this. That way, even if someone gets the community strings, he'll have to spoof the IP address of one of your management stations to do any damage. This will reduce the risk, but does not guarantee safety. A better solution is to prevent the SNMP packets from being visible outside of your management network segment by configuring your routers and firewall accordingly. Unfortunately, it is not always possible to establish a separate management network, or use it from different locations. Consider VPN solutions or some form of tunneling to make your management traffic private. Many devices can generate authentication-failure traps when someone attempts to access them using incorrect community strings. If your devices support this feature, use it to detect unsolicited access to your devices. Finally, SNMPv3 fixes most of the security problems. Particularly, it ensures that all the community strings are encrypted.

9.9.2.1.1.1 SNMP Setup on Windows Systems

To properly setup Simple Network Management Protocol (SNMP ) on your Windows system, you have to: 1. Enable 1072 SNMP Agent
1072

(if it is not yet enabled)

1074

2. Configure 1074 SNMP Agent

according to your needs

Refer to appropriate subsection to enable SNMP on: Windows Server 2008 1073 Windows Vista and Seven 1073 Windows XP, 2000, or 2003 1073

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

Windows NT 1073 Windows 98 1073 You must have administrator privileges to enable SNMP on Windows System.

1073

Install SNMP on Windows Server 2008

You can install the SNMP service in Windows Server 2008 using one of the following ways: Use the Server Manager snap-in to add the SNMP Service feature Or use the following command:

start /w ocsetup SNMP-SC

Steps to Install SNMP on Windows Vista and Seven

1. From the Control Panel, select Programs 2. Under Programs and Features, select Turn Windows features on or off 3. In the Windows features list, scroll down to SNMP feature and expand the list so that you can see WMI SNMP Provider 4. Select the check box for WMI SNMP Provider. The check box for SNMP feature is selected automatically because the provider requires SNMP 5. Click OK 6. From a command prompt or the Start menu, run Services.msc and ensure that the SNMP service is started

Steps to Install SNMP on Windows XP, 2000, or 2003

1. Click Start , point to Settings, click Control Panel, double-click Add or Remove Programs , and then click Add/ Remove Windows Components 2. Select Components, click Management and Monitoring Tools (not changing the state of its check box!), and then click Details 3. Select the Simple Network Management Protocol check box, and click OK 4. Click Next 5. Insert the CD or specify the complete path to the required files This completes the installation process. This also implements the Host Resources MIB automatically. For configuring SNMP agents to respond to SNMP requests, refer to Configuring 1074 SNMP agents 1074 .

Steps to install SNMP on Windows NT

1. Right-click the Network Neighborhood icon on the Desktop 2. Click Properties 3. Click Services 4. Click Add. The Select Network Service dialog box appears 5. In the Network Service list, click SNMP Service , and then click OK 6. Insert the CD or specify the complete path to the required files and click Continue 7. Microsoft SNMP Properties dialog box appears after the necessary files are copied This completes the installation process. This also implements the Host Resources MIB automatically. For configuring SNMP agents to respond to SNMP requests, refer to Configuring 1074 SNMP agents 1074 .

Steps to install SNMP on Windows 98

1. Insert Windows 98 CD 2. On the Network control panel, click Add. The Select Network Component Type dialog box appears 3. Double-click Service

2000-2013 Tibbo Technology Inc.

1074

AggreGate Documentation

4. Click Have Disk in the Select Network Service dialog box 5. Type the path to the tools\reskit\netadmin\snmp directory on your computer's CD drive in the Install From Disk dialog box and then click OK 6. Select Microsoft SNMP agent from the Models list in the Select Network Service dialog box and then click OK This completes the installation process. This also implements the Host Resources MIB automatically. For configuring SNMP agents to respond to SNMP requests, refer to Configuring 1074 SNMP agents 1074 .

Refer to appropriate subsection to enable SNMP on: Windows XP, 2000, Server 2003, Server 2008, Vista, and Seven Windows
1074 NT 1074 1072 1074

For details about enabling SNMP agents in Windows systems, refer to Enabling

SNMP Agent on Windows System

1072.

Configuring SNMP Agent on Windows XP, 2000, Server 2003, Server 2008, Vista, and Seven
STEPS TO CONFIGURE SNMP AGENT
1. Click Start , point to Settings, click Control Panel. 2. Under Administrative Tools, click Services.

3. In the Details pane, right-click SNMP Service and select Properties. 4. In the Security tab, select Send authentication trap if you want a trap message to be sent whenever authentication fails. 5. Under Accepted community names , click Add. 6. Under Community Rights , select a permission level for this host to process SNMP requests from the selected community. 7. In Community Name, type a (case-sensitive) community name, and then click Add. 8. Specify whether or not to accept SNMP packets from a host: To accept SNMP requests from any host on the network, regardless of identity, click Accept SNMP packets from any host. To limit acceptance of SNMP packets, click Accept SNMP packets from these hosts, click Add, type the appropriate host name, IP or IPX address, and then click Add again. 9. Click Apply to apply the changes.

STEPS TO CONFIGURE SNMP TRAPS

1. Click Start , point to Settings, click Control Panel. 2. Under Administrative Tools, click Services.

3. In the Details pane, right-click SNMP Service and select Properties. 4. In the Traps tab, under Community name, type the (case-sensitive) community name to which this computer will send trap messages, and then click Add to list. 5. Under Trap destinations, click Add. 6. In the Host name, IP or IPX address field, type host name or its IP address of the AggreGate Server server to send the trap to, and click Add. 7. Repeat steps 4 through 6 until you have added all the communities and trap destinations you want. 8. Click OK to apply the changes..

Configuring SNMP Agent on Windows NT

STEPS TO CONFIGURE SNMP AGENT
1. Click Start , point to Settings, click Control Panel. 2. Under Administrative Tools, click Services.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

3. In the details pane, right-click SNMP Service and select Properties. 4. In the Security tab, select Send authentication trap if you want a trap message to be sent whenever authentication fails. 5. Under Accepted Community Names , click Add. 6. In the Community Names box, type the community name to authenticate the SNMP requests. 7. To move the name to the Accepted Community Names list, click Add. 8. Repeat steps 5 through 7 for any additional community name.

1075

9. To specify whether to accept SNMP packets from any host or from only specified hosts, click one of two options: Accept SNMP Packets From Any Host , if no SNMP packets are to be rejected on the basis of source computer ID. Only Accept SNMP Packets From These Hosts, if SNMP packets are to be accepted only from the computers listed. To designate specific hosts, click Add, type the name or address of the host from which you will accept requests in the IP Host or IPX Address box, and then click Add (repeat this step for any additional hosts). 10. In the Agent tab, specify the appropriate information (such as comments about the user, location, and services). 11. Click OK to apply the changes.

STEPS TO CONFIGURE SNMP TRAPS

1. Click Start , point to Settings, and then click Control Panel. Double-click Administrative click Services. 2. In the details pane, click SNMP Service , then click Properties. 3. Click the Traps tab. 4. Type the (case-sensitive) community name in the Community Name box for each community to which you want this computer to send traps. 5. After typing each name, click Add to add the name to the list. 6. To specify hosts for each community you send traps to, after you have added the community and while it is still highlighted, click Add under Trap Destination. 7. Type the host name or address in the IP Host/Address or IPX Address box, and then click Add to move it to the Trap Destination list for the selected community. 8. Repeat step 7 for any additional hosts. 9. Click OK to apply the changes. Tools, and then double-

9.9.2.1.1.2 SNMP Setup on Linux Systems

To properly setup Simple Network Management Protocol (SNMP ) on your Linux system, you have to: 1. Enable 1072 SNMP Agent
1075

(if it is not enabled yet)

1074

2. Configure 1076 SNMP Agent

according to your needs

Refer to appropriate subsection to enable SNMP Agent on Linux system using one of two ways: Using RPM package
1075

Using ZIP archive 1076

Install Using RPM

1. Download the latest rpm version of SNMP from http://prdownloads.sourceforge.net/net-snmp/net-snmp-5.1.1-1.rh9.i686.rpm?download 2. Login as root user. 3. Before installing the new version of net-snmp, you need to remove the earlier versions of net-snmp in your machine. To list the versions of net-snmp installed in your machine, execute the following command:

rpm -qa | grep "net-snmp"

2000-2013 Tibbo Technology Inc.

1076

AggreGate Documentation

4. If there are already installed version in your machine, remove them using the command:

rpm -e <version of net-snmp listed as the output for previous command> --nodeps

5. If there are no previously installed versions in your machine, then execute the following command to install the new version:

rpm -i <new downloaded version of SNMP agent> --nodeps

This completes the installation process. For configuring SNMP agents to respond to SNMP requests, refer to Configuring SNMP agents 1076 .

Install Using ZIP

1. Download the zip version of SNMP from http://heanet.dl.sourceforge.net/sourceforge/net-snmp/ucd-snmp-4.2.6.tar.gz 2. Extract the file using following command: 3. Login as root user. 4. Execute the command to set the path of the C compiler:

tar -zxvf ucd-snmp-4.2.6.tar.gz

export PATH=<gcc path>:$PATH

5. Execute the following four commands from the directory where you have extracted the ucd-snmp ( directory_name is the directory to install SNMP agent; preferably choose a directory under /root, as directories /usr and /local might contain files of an older version of SNMP):

./configure --prefix=<directory_name> --with-mib-modules="host" make umask 022 make install

This completes the installation process. For configuring SNMP agents to respond to SNMP requests, refer to Configuring SNMP agents 1076 .

For details about enabling SNMP agent in Linux systems, refer to Enabling SNMP Agent on Linux System To configure SNMP Agent you have to modify snmpd.conf file: After the line: insert the line

1075.

# name incl/excl subtree mask(optional) view allview included .1.3.6

Change the line aftnr to: from to

# group context sec.model sec.level prefix read write notif access notConfigGroup "" any noauth exact systemview none none access notConfigGroup "" any noauth exact allview none none

Then restart the snmp agent using:

/etc/rc.d/init.d/snmpd restart

9.9.2.1.1.3 SNMP Setup on Solaris Systems

To properly setup Simple Network Management Protocol (SNMP ) on your Solaris system, you have to 1) Enable 1076 SNMP Agent
1076

(if it is not yet enabled)

1077

2) Configure 1077 SNMP Agent

according to your needs

To install SNMP, follow these steps: 1. Download the latest version of SNMP from http://heanet.dl.sourceforge.net/sourceforge/net-snmp/ucd-snmp-4.2.6.tar.gz 2. Extract the file using following command: 3. Login as root user.

tar -zxvf ucd-snmp-4.2.6.tar.gz

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

4. Execute the command to set the path of the C compiler:

1077

export PATH=<gcc path>:$PATH

5. Execute the following four commands from the directory where you have extracted the ucd-snmp ( directory_name is the directory to install SNMP agent; preferably choose a directory under /root, as directories /usr and /local might contain files of an older version of SNMP):

./configure --prefix=<directory_name> --with-mib-modules="host" make umask 022 make install

This completes the installation process. To configure SNMP agents respond to SNMP requests, refer to Configuring SNMP agents 1077 .

For details about enabling SNMP agents in Solaris systems, refer to Enabling SNMP Agent on Solaris System To configure SNMP Agent do the following: 1. Stop the agent if it is running already using

1076.

/etc/init.d/init.snmpdx stop

2. Make the following changes in /etc/init.d/init.snmpdx file Replace the lines

if [ -f /etc/snmp/conf/snmpdx.rsrc -a -x /usr/lib/snmp/snmpdx ]; then /usr/lib/snmp/snmpdx -y -c /etc/snmp/conf -d 3 -f 0 fi

with

<Installation
Replace the line with

Directory>/sbin/snmpd

/usr/bin/pkill -9 -x -u 0 '(snmpdx|snmpv2d|mibiisa)' /usr/bin/pkill -9 -x -u 0 '(snmpd)'

3. Restart the agent using

/etc/init.d/init.snmpdx start

9.9.2.1.1.4 SNMP Setup on Cisco Devices

To configure SNMP agents on Cisco devices, you need to log into the device and switch to privileged mode . Then you can run following commands from command prompt.

Commands To Enable SNMP

#configure terminal #snmp-server community <community_string> [ r w / r o ]
(for example: snmp-server community public ro)

#end #copy running-config startup-config

Commands To Enable Trap

#configure terminal #snmp-server enable traps snmp authentication #end #copy running-config startup-config

Commands To Set AggreGate Server As Host

#configure terminal #snmp-server host <AggreGate Server IP> <Trap community string> snmp
(for example: snmp-server host 192.168.9.58 public snmp)

#end

2000-2013 Tibbo Technology Inc.

1078

AggreGate Documentation

#copy running-config startup-config

9.9.2.1.1.5 SNMP Setup on Microsoft SQL Server

Verify whether SNMP agent is running on the server. If it is not, refer to SNMP Setup on Windows Systems Then, start the SQLSERVERAGENT service following the steps given below
1072.

Starting SQLSERVERAGENT service on Windows XP, 2003, or 2000

Click Start , point to Settings, and then click Control Panel Double-click Administrative Tools, and then double-click Computer Management

In the console tree, click Services and Applications and then click Services Right-click SQLSERVERAGENT and click Start

Starting SQLSERVERAGENT service on Windows NT

Right-click on the Network Neighborhood icon on the Desktop Click Properties Click Services Right-click SQLSERVERAGENT and click Start

9.9.2.1.1.6 SNMP Setup on Lotus Domino Server

The Domino SNMP Agent runs as a Windows Service and starts up automatically even if Domino is not running. You should take this into account when upgrading Domino: you should stop the LNSNMP and Windows SNMP services before beginning the upgrade process. Stop the LNSNMP and SNMP services using these commands:

net stop lnsnmp net stop snmp lnsnmp -Sc

Configure the Lotus Domino SNMP Agent as a service using this command: Start the SNMP and LNSNMP services using these commands:

net start snmp net start lnsnmp

9.9.2.1.1.7 SNMP Setup on Oracle Servers

Oracle services monitoring can be provided by means of Oracle Intelligent Agent, which can be configured to allow third-party systems to receive SNMP traps and gather relevant data. To accomplish that, Oracle Intelligent Agent should be configured to recognize SNMP requests from the master agent. To provide that on Windows machines do the following: 1. Once you have installed and configured the SNMP agents in your Windows machines, you have to integrate SNMP with Intelligent agent. This requires Oracle Peer SNMP Master Agent and SNMP Encapsulator Agent to be installed in the Oracle server. Note that these agents must be the same version as the Intelligent Agent and installed in the same ORACLE_HOME. After the installation completes, the Oracle SNMP Peer Encapsulator and Oracle Peer SNMP Master Agent services will be created. (If you do not install the Intelligent Agent software in the default $ORACLE_HOME, the names of all the services will begin with the following: Oracle<home name>.) 2. For SNMP master agent to communicate with both the standard SNMP service and the Intelligent Agent, the SNMP services file must be configured properly. You have to assign a free port to the encapsulated agent (Microsoft SNMP Service ). Usually Microsoft SNMP Service uses port 1161, which is specified in the SERVICES file located in the <WINDOWS>\SYSTEM32\DRIVERS\ETC directory (where <WINDOWS> designates path to windows installation). Make sure that you have the following lines in the file, changing default port (161) to another available port (1161 in this example):

snmp 1161/udp snmp snmp-trap 1162/udp snmp

3. Check that the HOSTS and LMHOSTS.SAM files in <WINDOWS>\SYSTEM32\DRIVERS\ETC (where <WINDOWS> designates path to windows installation) contain the mappings of IP addresses to host names for all computers in the SNMP setup. This will significantly improve system performance, even if you use DHCP and WINS.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1079

9.9.2.1.2 Configuring SNMP in AggreGate Network Manager

To setup AggreGate Network Manager for performing management tasks using SNMP, do the following: Configure IP Host driver 1079 . Provide and configure all the MIB files required. This is covered in the Managing MIB files Add and configure network devices for SNMP management
1081 . 1080

section.

9.9.2.1.2.1 Global SNMP Configuration

In AggreGate Network Manager SNMP is supported by Network Host driver 150 . SNMP configuration is available as Network Host driver properties. To access these properties, double-click Network Host item under Drivers/ Plugins node in the System Tree.

There are several tabs presenting various aspects of SNMP usage in AggreGate Network Manager as described below.

Global Configuration
The Global Configuration tab includes SNMP traps properties for: enabling/disabling SNMP notification processing; transport protocol used to receive notifications; port number used to receive notifications; local Engine ID to be used with SNMP version 3 notifications. See also Network Host driver's SNMP Monitoring sections
154

for details.

MIB Directory
MIB Directory tab contains the list of loaded MIB files and MIB compilation errors. This topic is covered in the
Managing MIB Files 1080 section.

SNMP User Table

SNMP User Table tab contains a list of SNMP users and their properties. This table is used to provide security options specific for SNMP version 3. See SNMP Users Table 179 described in SNMP Global Settings chapter for details.

2000-2013 Tibbo Technology Inc.

1080

AggreGate Documentation

SNMP Trap Sources Automatic Discovery

When AggreGate Network Manager receives an SNMP trap, it can automatically discover the device that sent this notification (See the SNMP Trap Sources Automatic Discovery 1086 section for details). This feature is controlled by Enable SNMP Trap Sources Automatic Discovery setting.

MIB files describe pieces of management information that agents can provide. A set of MIB files loaded and compiled AggreGate Network Manager forms a MIB configuration, used to interpret the data received from SNMP agents. If the data obtained is not properly described, manager will be unable to process it. Such data will be displayed in "raw" form. Therefore, a full and correct MIB configuration is extremely important for successful network monitoring. There are thousands of MIB files available for various network resources. They are periodically updated to add new functionality, remove ambiguities and fix defects. Full-fledged MIB configuration functionality allowing to add and use vendor-specific MIBs it essential for enterprise network management solutions.

MIB Files Directory

In AggreGate, MIB configuration is supported by Network Host driver 150 . MIB files, their statuses and associated options are represented as records in a MIB Files Directory 178 (mibDirectory) tabular variable. Users can manage MIB configuration by manipulating this variable. It can be accessed at the MIB Files Directory tab of Network Host Driver Properties window. To open the properties window, double-click Network Host node under Drivers/ Plugins item in the System Tree.

LOAD ORDER
Definitions in MIB files can reference definitions from other MIB files. Accordingly, a MIB file can be dependent on another MIB in the directory. Therefore the loading order of MIB files is important. Incorrect order can greatly slow down MIBs loading and lead to compilation errors caused by to unresolved references. AggreGate Network Manager loads MIB files in the same order as they appear in the MIB Files Directory table. If you want to change the order, move rows up or down.

ADDING MIB FILES

You can add a MIB file to the configuration by creating new record in the MIB Files Directory. Fill the description and file name fields, and select SNMP variables description method for the MIB. Alternatively you can copy one or several MIB files to the /mib subdirectory of AggreGate Server installation. In both cases the definitions from the MIB file will be available after the server restart. The status of the MIB files and load errors are available in the corresponding fields of the MIB directory record.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1081

DISABLING AND REMOVING MIB FILES

If a MIB files should be excluded from the server configuration, it can be disabled by removing the checkmark in the Enabled field. The MIB file will remain in the Directory and can be enabled again. If you want to permanently remove a MIB file from the Directory: Choose Remove MIB File item in the context menu of the Network Host node under Drivers/Plugins item in the System Tree. Select the MIB file you want to delete from both disk and MIB Directory. Right-click on a MIB File while browsing MIB Directory table. Select Remove MIB File from context menu.

EDITING MIB FILES

A MIB file from the Directory can be edited right in AggreGate Network Manager. The MIB editor supports syntax highlighting. There are two ways to start editing: Choose Edit MIB File item in the context menu of the Network Host node under Drivers/Plugins item in the System Tree. Select the MIB file you want to edit from the drop-down list. Right-click on a MIB File while browsing MIB Directory table. Select Edit MIB File from context menu.

9.9.2.1.2.2 Configuring SNMP Devices

Here are described options available and concerns should be taken into account while configuring a particular devices for SNMP management.

Enabling SNMP
Ensure SNMP is enabled on the device you are going to manage. SNMP is enabled by default for manually added devices. For discovered devices, SNMP is enabled or disabled automatically according to the service scan results. If SNMP is disabled for the discovered device, or the enabled SNMP service is "offline", try the following: 1. Ensure the IP Address or Host Name field in the Host Address tab is filled correctly. 2. Make sure that the device is actually SNMP-compliant. 3. Ensure antivirus software and/or firewalls do not hinder the SNMP communications. 4. Recheck SNMP settings you specified: transport protocol, port, community strings, etc. (see the details bellow) Being confident that all the parameters are correct, enable SNMP service if it is disabled, or invoke synchronization. Mind, that full synchronization with an SNMP device can take a significant amount of time. Alternatively, you can try to rediscover SNMP service on this device.

SNMP Device Configuration

SNMP device settings are presented by SNMP Properties variable in Network Host device contexts (refer to SNMP connection properties 176 for details).

2000-2013 Tibbo Technology Inc.

1082

AggreGate Documentation

The SNMP properties are used to establish communication with SNMP agent. Thus, both sides should be configured identically. The SNMP properties must conform the agent configuration in order to successfully communicate with it.

SELECTING TRANSPORT PROTOCOL

SNMP can work over two transport protocols: UDP (User Datagram Protocol) or TCP (Transmission Control Protocol). UDP is connectionless , i.e. try to establish end-to-end between agent and manager, and unreliable, i.e. delivery of messages is not guaranteed, and the order of messages may change. On the contrary TCP guarantees messages delivery and provides robust error-recovery; the messages are delivered in the sequence they were sent. AggreGate Network Manager supports both UDP and TCP as transport protocols for SNMP. Which one to choose for your network? SNMP over UDP has a reduced impact on network's performance, not trying to retransmit lost or broken information. UDP should be considered as default transport for SNMP; especially this is true for problematic networks. (Note, SNMP was originally designed for UDP transport.) The unreliable nature of UDP protocol can be balanced by regular requests, and/or AggreGate Network Manager ability to resend requests several times when no response was received within the specified timeout (see below). But this is not true for traps as they are basically unconfirmed operations. So, if a trap was not delivered from agent to manager for any reason, the manager will never know it was ever sent; and the agent will have no chance to be informed about that and therefore can't resend the trap. This issue should be considered when configuring SNMP management. Use Inform requests instead of traps for guaranteed delivery.

SNMP over TCP is primarily defined to support more efficient bulk transfer mechanisms. It is possible to exchange multiple SNMP request/response pairs over a single (persistent) TCP connection, even sending multiple SNMP messages to an agent before receiving responses. SNMP over TCP is intended to be used when the size of the transferred data is large. This is where TCP can be more effective then UDP. But in a whole, to be effective, using TCP as transport for SNMP polling needs a fine IP configuration considering the environment circumstances it is used in. Another concern is reliability. SNMP over TCP gives a reliable exchange of SNMP messages between SNMP engines. In particular, TCP guarantees (in the absence of security attacks) that the delivered data is not damaged, lost, duplicated, or delivered out of order. At the same time these features of TCP does not guarantee that the data sent was eventually received and processed in any way by manager. To ensure that, confirmed operations should be used. The choice between UDP or TCP does not impact security significantly, as both variants are basically vulnerable: for

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1083

example, UDP is subjected to IP spoofing attacks, while TCP may introduce vulnerabilities to denial of service attacks. In either case other security options 1070 should be considered.

PORT
By default SNMP uses port 161 for sending and receiving requests. If a device has a non-standard SNMP configuration, you can specify another port number.

SNMP VERSION
AggreGate Network Manager supports SNMPv1, SNMPv2c and SNMPv3. Select the one appropriate for the particular device.

COMMUNITY STRING
Don't forget to setup the Read Community and Write Community properties correctly to get a read and write access to the device management information via SNMPv1/SNMPv2c.

COMMAND RETRIES AND TIMEOUT

If AggreGate Network Manager's request is not responded with the specified timeout period, it repeats the request again. These settings are important especially when UDP is used as transport protocol, because it is unreliable and SNMP messages can be lost. The concrete values depend on the parameters of your network. They can be chosen empirically starting with the default values provided out of box.

MAXIMUM PDU SIZE

This is the maximum size of SNMP message the agent can receive. It is used by AggreGate Network Manager to limit the size of SNMP requests. The recommended size is 1472 octets (see, for example, Transport Mappings for the Simple Network Management Protocol). But some agents are unable to handle messages more than 484 octets in size, which is a "guaranteed" value.

DATA TO PROCESS
Many SNMP agents expose multitudes of SNMP variables. Not all of those variables are used in practice. Reading, processing and storing the variables that are not actually utilized is a waste of network, processor and memory resources. Obviously, it is a good idea not to read all the variables available, but access only those of them that are actually useful for monitoring a particular item. But what is useful may vary depending on the user tasks and aims. To meet different user requirements, AggreGate Network Manager provides two options: AggreGate Network Manager can read, process and store all the values the SNMP agent exposes. This option, for example, may be used for exploration of an unknown device. Another options is processing only the values described by loaded MIB files 178 , ignoring unrecognized ones. This can be a good choice if you want to have detailed information about the monitored device.

SECURITY OPTIONS
These options are available only for SNMPv3. A user can specify security level, username, passwords and protocols for authentication and encryption. Refer to SNMP security options description 176 for details.

Synchronization Options
AggreGate Network Manager polls monitored items periodically. The interval between adjacent requests is a very important monitoring parameter. It defines balance between monitoring data accuracy/precision and processor/ memory/network load. Furthermore, the polling interval should not be shorter than refresh period at the agent side (see Data Processing 1045 section). The polling in AggreGate Network Manager is implemented as synchronization 126 ; polling interval is represented by the Synchronization Period (refer to Generic Device Properties 123 ) and can be customized using Device Settings Synchronization Options 115 . You can specify custom synchronization period for individual SNMP variables.

2000-2013 Tibbo Technology Inc.

1084

AggreGate Documentation

The default synchronization period for SNMP devices is 24 hours. Some variables are customized with specific synchronization periods, e.g. network interface and processor statistics data are read every 15 minutes and every 30 seconds, respectively. You can specify your own periods for these and other variables.

9.9.2.2 SNMP Monitoring

AggreGate Network Manager provides monitoring for virtually any kind of SNMP-compliant network devices. Polling- and event-based monitoring approaches are supported using SNMP get operations and traps respectively. Complementing each other, these monitoring technologies are essential for a reliable monitoring strategy. SNMP polling lets you obtain all the metrics you need from the managed item. In periodic polling, information is obtained with a lag caused by the polling interval. This may reduce monitoring accuracy and response rates. Events can help to fix that: as soon as manager gets a notification about a certain event, it can request a fresh information needed to handle the event. On the other hand, event gives only a limited information about certain aspect of managed item's life. Furthermore, events implemented as SNMP traps are not guaranteed to be delivered to manager. Thus, the best strategy is to poll the values related to a certain event when a manager receives notification, and perform 'full' poll periodically. By using periodical polling and events together you can gain the needed combination of accuracy, speed, reliability and efficient utilization of network and computational resources. This chapter covers the utilization of SNMP polling 1084 and traps 1085 in context of AggreGate Network Manager, followed by a section describing how this information can be further processed and analysed 1086 .

9.9.2.2.1 SNMP Polling

SNMP polling allows you to constantly monitor values of various OIDs. AggreGate Network Manager uses SNMP polling to monitor availability, operability and performance of network interfaces, CPU, memory and disks, processes on working stations, VMware servers, wireless devices, printers, etc. There are a lot of examples in the corresponding sections of this manual. Under the hood SNMP polling is a series of get requests and responses. AggreGate Network Manager hides these communication details implementing reading operations in terms of standard synchronization process 126 . The retrieved information is injected into the core for processing and usage by various monitoring tools.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1085

9.9.2.2.2 Receiving SNMP Traps and Informs

SNMP Trap/Inform is an unsolicited message generated by management agent to notify manager about some event occurred. AggreGate Network Manager can receive and process SNMP notifications of both types: Traps and Informs. When a notification is received, it is used as a source for an internal AggreGate trap event. This allows to process SNMP notifications uniformly, just the same way as any other kind of AggreGate events 880 are processed. Example: To initiate some action in response to a particular notification, you can create an alert for the corresponding trap event and setup it's corrective action 227 accordingly. This way you can, for instance, execute a shell script on a remote Linux machine when a certain type of trap is received. See also SNMP Notifications Monitoring and Consolidation 1107 and specifically SNMP Notification Alerts
1107

sections.

Thereby AggreGate Network Manager allows one to organize event-based monitoring for virtually any custom SNMP device and combine 1084 them with SNMP polling if required.

Implementation
When AggreGate Network Manager receives an SNMP notification, it fires a trap event 880 in Administration The event data table is filled with the following properties (see RFC 1215 RFC 1157 for details): SNMP Notification Description Event Field Agent IP Address or Host Name SNMP Version Notification Type Enterprise or Trap OID Generic Trap Type ID Specific Trap Type ID Device Uptime Trap OID Variable Bindings Engine ID Address of the originator system of this SNMP notification. Version of the received notification. Type of the notification (Trap or Inform) Identifies the type of managed object that generates the trap. Indicates generic trap type, one of: coldStart (0), warmStart (1), linkDown (2), linkUp (3), authenticationFailure (4), egpNeighborLoss (5), enterpriseSpecific (6) Specific trap type. It is available if Generic Trap ID is ENTERPRISE_SPECIFIC (6). The amount of time (1/100 of second) that has elapsed between the last device reinitialization and generation of the notification. Trap identification for SNMP version 2(c) and 3 notifications. Variable bindings associated with the notification. Authoritative engine ID of the notification.
652

context.

Example: Sending SNMP Traps From Linux/Unix Workstation

To ensure that SNMP traps are correctly received by AggreGate Network Manager, you can send them using snmptrap command. For example, if your AggreGate Network Manager is configured to accept SNMP traps with public community string using UDP transport at default port 162, you can invoke the following command:

sudo snmptrap -v1 -c public udp:<AggreGate Server IP address>:162 enterprises localhost 6 5 1

This will generate an SNMP version 1 enterpriseSpecific trap with 5 as Specific Trap Type, enterprises ( 1.3.6.1.4.1) as Enterprise OID, and 1/100 as Device Uptime value. You can check that AggreGate Network Manager generates a corresponding event using Event Log's SNMP Traps filter. Double-click an event record to see its full data:

2000-2013 Tibbo Technology Inc.

1086

AggreGate Documentation

9.9.2.2.2.1 SNMP Trap Sources Automatic Discovery

You can configure AggreGate Network Manager to automatically discover senders of SNMP traps and create Device accounts 113 for them. See Network Host device driver's SNMP Trap Sources Automatic Discovery 178 global setting.

9.9.2.2.3 Using SNMP Data

SNMP data obtained from managed devices is injected into system core. The information is available in the form of Network Host 150 device settings and utilized by AggreGate Network Manager tools.

Browsing SNMP Data

All information collected from an SNMP device can be browsed as settings 176 of that device. To view the information, select the device in the System Tree and chose Configure Device item in its context menu. Alternatively you can just double-click on the device. The device configuration window will be opened. There can be a lot of variables (settings), dozens of tabs. You can enable/disable tabbed layout for more convenient presentation.

Processing SNMP Data

SNMP data obtained from a certain device is handled by various AggreGate Network Manager tools like alerts, widgets, charts, queries, etc. They analyze the data to detect type of the device and process accordingly. SNMP data can be used to obtain status, numerical characteristics and statistics of a particular monitored device. For example, a device is classified as a printer if it has a prtGeneralTable SNMP variable. This variable along with other data available for the device is used by printer monitoring tools to obtain printer-specific data: description, model, serial number, capabilities, current state. Printer alerts uses SNMP to detect possible printer problems like like paper jams, out of paper, overfull trays, lack of toner, etc. You can create your own tools to provide monitoring for specific types of SNMP devices in your network. For most cases this can be done right in the AggreGate Network Manager environment without programming. For more complex circumstances AggreGate SDK 960 can be used. It allows to create your own advanced plugins that will process SNMP data in the most appropriate way for the devices you deal with.

9.9.2.3 Managing Devices Using SNMP

Some network devices, services and applications can be controlled using SNMP. A set of available operations and methods of their invocation varies for different types of devices/services/applications.

Examples Of Control Operations

There are two kinds of control operations that can be performed via SNMP: configuration action execution. alteration and direct

CHANGING CONFIGURATION
Changeable configuration settings for a managed SNMP device/service/application are exposed as writable variables

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

(OIDs).

1087

One of the simplest examples of configuring via SNMP is setting a "standard" value, e.g. one of described in RFC 1213. Say, to alter device description you can set value of sysDescr (1.3.6.1.2.1.1.1) to the desired string value. Configuration changes can involve much more sophisticated procedures including related series of changes, table row creations, etc.

ACTION EXECUTION
There are some actions that can be performed depending on concrete types of managed items. All those actions are still performed as SNMP Set operations for certain OIDs. For example, to reload a Cisco switch you can write value 2 (representing reset operation) to a sysReset ( 1.3.6.1.4.1.9.2.9.9) variable.

How To Invoke Operations

Since all controlling operations in SNMP are actually alterations of variables (OIDs), to perform a control action a manager should set value of particular SNMP variable exposed by a managed device. The variables should be described in MIB files for the item. Refer to the documentation of device/service/application you want to control. To write new value of a particular SNMP variable to the device you can follow the standard procedure: 1. Double-click the device item in the System Tree. The Device Configuration window should appear. 2. Select the variable you want to modify at an appropriate MIB tab. Alternatively you can disable tabbed layout and find the variable in plain list of all available variables. 3. Set the desired new value and save properties. This will start synchronization process the device.
126

which will write the value to

Be careful changing parameters of real devices! Ensure you don't modify a parameter that is critical to the state of the system. You can automate the repetitious controlling operations using standard AggreGate Network Manager tools, e.g. widgets 312 , scripts 628 , alerts (their Automatic Correction Actions 227 ) etc.

9.9.2.4 Sending SNMP Traps and Informs

There are two types of SNMP notifications: Traps and Inform requests. The main difference between them is reliability. Traps are unacknowledged and thus unreliable because the sender does not know if the trap was received. SNMPv2 fixed this by introducing the Inform notifications, which can be regarded as acknowledged Traps. Inform sender can now wait for an acknowledgement from the receiver. If the acknowledgment did not arrive with a certain time interval, the notification can be resent. At the same time, Informs put additional overhead on network and computational resources: original Inform notification should be kept in sender's memory until a response is received, it needs additional processing on receiver and increase traffic when is repeated. Traps and Informs allow to find a balance between reliability and resources: for important notifications you can use Informs, while "ordinary" ones can be sent as Traps. AggreGate Network Manager can generate both types of SNMP notifications using Send SNMP Trap (sendSnmpTrap) action 892 in Root context 726 . You can invoke Send SNMP Trap action manually by activating context menu of server node ( ) in System Tree, choosing Network Management submenu and selecting Send SNMP Trap. Alternatively, you can configure traps to be sent in response to an alert -- see corrective actions 232 for details.

Input Format
The action can be configured with parameters of the following format: Name Type Description Details

2000-2013 Tibbo Technology Inc.

1088

AggreGate Documentation

trapType targetAddress port protocol timeout enterprise variableBinding s

String String Integer String Long String Data Table

Notification Type IP Address or Host Name Port Protocol Timeout Enterpised or Trap OID Variable Bindings

Notification type: Trap or Inform. Address of the trap's receiver. Port the trap will be sent to (162 by default). Transport Protocol to be used to deliver trap (UDP or TCP). Timeout before a confirmed request is resent or timed out (5 seconds by default). Trap's Enterprise for SNMP version 1, or Trap/Inform's OID for SNMP versions 2(c) and 3. Variables bindings to be associated with the trap. Bindings are defined in a table with the following format: Name variableBindingsOID variableBindingsTyp e Type String Integer Description Variable OID Variable Type Variable Value

variableBindingsValu String e snmpVersion community userName Integer String String SNMP Protocol Version Community Username SNMP version.

Community string (for notifications of SNMP versions 1 and 2) Username for version 3 notifications. Note, that system tries to find authentication and privacy passwords in SNMP Users Table 179 (using specified Username and Engine ID). Thus, a record for the user must exist in the table. Binary-encoded engine ID (for version 3 notifications). Security level for version 3 notifications.

engineId securityLevel

Data Integer

Authoritative Engine ID Security Level

Output Format
The action returns nothing for Traps. For Informs, the response is returned in the following format: Name Type Description Detials Data returned as response to Inform. Bindings are defined in a table with the following format: Name variable value errorMessage String Error Type String String Description Variable Value

variableBinding Data Table Variable s Bindings

Textual description of the success/error status.

9.10 WMI Monitoring and Management

Windows Management Instrumentation (WMI) is the infrastructure for management data and operations on Windows-based operating systems. WMI is the Microsoft implementation of Web-based Enterprise Management (WBEM), which is an industry initiative to develop a standard technology for accessing management information in an enterprise environment. WMI uses the Common Information Model (CIM) industry standard to represent systems, applications, networks, devices, and other managed components as a set of objects and relations between them.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1089

Refer to Microsoft's MSDN site for WMI architecture, availability on different operating systems, and other details.

Remote Management
WMI can be used to monitor and manage Windows computers remotely. Remote WMI connections are made through Distirbuted COM (DCOM). Remote computer should be properly configured to allow DCOM connections and execution of WMI requests. Refer to Configuring Remote Access to WMI 189 and Configuring DCOM for Remote Access 1327 sections for details.

Uniform Model for Management Information

WMI is based on the Common Information Model that abstracts and describes the "managed environment" in terms of object-oriented paradigm. This model covers virtually all managed elements of modern IT environments including devices and their components, computer systems, operating systems, networks, software, users, physical environment, performance statistics. Thus, all manageable resources can be accessed in a common way. At the same time, CIM is extensible allowing vendors to represent their specific features. WMI describes all manageable resources as objects that present element's data (readable properties) and controlling means (writable properties and methods). Every WMI object is an instance of some class. Classes define set of properties and methods their instances provide. For example, instances of Win32_Printer class present printer devices. This class defines few dozens of printer properties including its name, description, driver, capabilities, priority, status, various attributes, etc. Some of these properties are read-only, while others (like Priority, Direct, Hidden, KeepPrintedJobs, etc.) are writeable and can be used to configure printers via WMI. The Win32_Printer class also introduces several methods that allow to control printers: Pause, Resume, PrintTestPage, CancelAllJobs, etc.

Events
Events are used by manageable resource and WMI infrastructure to notify monitoring/management systems about different kinds of changes. Event consumers should subscribe for events of interest specifying a filter. The filter describes conditions under which the consumer wants to receive notifications.

WMI Query Language

The WMI Query Language (WQL) is the Microsoft implementation of CIM Query Language (CQL), a query language for the Common Object Model. It is a subset of ANSI SQL with several changes to support WBEM/WMI. WQL allows to retrieve management information and subscribe for event notifications. Refer to WQL chapters in MSDN Library for details.

WMI Device Driver

WMI support in AggreGate Network Manager is provided by WMI device driver connect to WMI running on remote computers retrieve WMI objects by WQL requests execution fetch WMI classes and their instances execute methods provided by WMI objects and vary their writable properties subscribe to WMI event notifications using WQL requests and receive events from a WMI computer run automatic actions in response to WMI events cache WMI information on the server store management information in database discover
1055 186 .

The driver allows to:

WMI-enabled computers and configure them for monitoring and management.

9.10.1 WMI Use Cases

In this section we provide some examples of how WMI can be used to monitor and manage Windows computers in your network. Feel free to explore other classes, their properties and methods that you can use to manage your system.

2000-2013 Tibbo Technology Inc.

1090

AggreGate Documentation

9.10.1.1 Controlling Windows Services

WMI represents Windows services as instances of Win32_Service class. You can add this class to device assets, or use WQL requests to fetch information and control services on remote Windows computers. Some examples are presented below.

Enumerating Inactive Services

To obtain names of inactive services and their states, you can use the following WQL request:

SELECT DisplayName,State FROM Win32_Service WHERE State <> 'Running'

To invoke it, do the following: Select a device in Context Tree Right-click it and select Edit Device Properties item Add new record in the table on the WQL Requests tab; enter the name, description and query text (as provided above) in corresponding fields Press OK The device will automatically synchronize and execute the request. The result will be available in WQL Requests table of Device Configuration.

Determining Services That Can Be Stopped

Use the following request to fetch only stoppable services:

SELECT * FROM Win32_Service WHERE AcceptStop = True

Follow the same procedure as provided above to employ it.

Start and Stop Services

To start a service on a specific computer, you can do the following: Select the corresponding device in Context Tree Right-click it and select the Win32_Service item in context menu (for Network Host devices it is located in the WMI submenu) Select the StartService method there Select or enter Object Path that identifies the service you would like to start Press OK To stop a service, perform this procedure for the StopService method.

Enumerating Service Load Order Groups

There are other classes that provide more information about Windows services. Refer to WMI documentation for further details. For example, instances of the Win32_LoadOrderGroup class represent groups of services that define execution dependencies. You can add this class to device assets or use WQL:

SELECT * FROM Win32_LoadOrderGroup

9.10.1.2 Managing Printers

The Win32_Printer WMI class represents a printing device connected to a computer running on a Microsoft Windows operating system. It allows to perform a bunch of monitoring and management tasks; some of them are presented in this section.

List of Installed Printers

To enumerate all the printers connected to a computer, you can either add Win32_Printer class to device's assets and explore contents of the Win32_Printer variable, or add the following WQL query:

SELECT * FROM Win32_Printer

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1091

Notice that if you use WQL, you can fetch only printers that satisfy some condition by adding a filter clauses to the request.

Modify Printer Properties

Some of printer's parameters are available for modification as writable properties. You just have to navigate to Device Configuration, open Win32_Printer table there and vary changeable properties for the printer of interest. Perhaps, the simplest and safest way to try this is to modify printer's comment represented by the Comment field. Refer to Win32_Printer WMI class documentation for further details on other properties and their meaning.

Rename Printer
Having Win32_Printer class enabled in device assets, you can invoke its methods to control printers. For example, to rename a printer, you can invoke RenamePrinter action available (just as all other printer actions) from Win32_Printer sub-menu in device context menu.

Enumerate Current Printer Jobs

There are other WMI classes providing useful functionality for printing devices connected to a Windows computer. For instance, Win32_PrintJob WMI class represents unit of work associated with a specific printer. To get a list of current jobs for every printer, you can perform the following query:

SELECT Description, Document, Status, JobStatus, ElapsedTime, Priority FROM Win32_PrintJob

It fetches printer descriptions, documents being printed on them along with their statuses, elapsed times and priorities. Explore documentation and WMI objects available on your real devices for more information.

9.10.1.3 Windows Event Log Monitoring via WMI

AggreGate Network Manager provides a simple way to monitor Windows Event Log via WMI. Right-click a WMI device and invoke the Edit Device Properties action. Then select the WQL Event Requests tab in the opened window and add a record to the table there. In the WQL Request field, enter a request that selects instance creation events for the Win32_NTLogEvents with required filtering parameter if needed. For example, to monitor all the events, enter the following text:

SELECT * FROM __InstanceCreationEvent WHERE TargetInstance ISA 'Win32_NTLogEvent'

You should also fill the Name and Description fields. Click OK and from now on AggreGate Network Manager will fetch fresh data from Windows Event Log every time the device is synchronized. The log objects are represented as AggreGate events. You can also set another polling period by specifying synchronization period for the wmiEvents variable. To follow and inspect Windows events, invoke the WMI Events filter in the AggreGate Event Log.

9.11 Availability Monitoring

There are two practical treatments of term availability in the context of network monitoring, fitting in two questions: "is a host/interface/service available right now?" and "how often a host/interface/service gets unavailable?". A set of indicators answering the first question we denote as current host availability indicators. An answer to the second question requires multiple measurements at different time points and therefore we refer to statistical availability metrics. The two approaches are described below. Both approaches use ICMP (basically Ping, or, additionally, Traceroute) requests. If your device does not respond to ICMP requests, you would need to find a different way to monitor its availability. Refer to Ping and Traceroute 161 services for details.

153

Current Availability
The following current availability indicators are supported by AggreGate Network Manager: Host Online/Offline Status is monitored by Ping 153 service, and can be accessed as Ping service monitoring results 153 or using these tools: Device Offline 1145 alert, Offline Devices 274 and Device Status Summary 274 queries.

2000-2013 Tibbo Technology Inc.

1092

AggreGate Documentation

Status of network interfaces on the host (tracked via SNMP). Related tools provided by AggreGate Network Manager: Interface Down 1098 and Administrative Interface Down 1098 alerts, Down Interfaces 1150 report/query. Device Response Time is monitored using Ping 153 service (accessed via Ping service monitoring results 153 ). Related tools: High Response Time 1145 alert, Ping Time 1151 and Response Time Top 10 1152 charts, and Response Time 1149 queries/reports. Packet Loss Rate is monitored with Ping 153 service (also accessed via Ping service monitoring results 153 ). See High Packet Loss Rate 1145 alert, Ping Packet Loss 1152 and Packet Loss Top 10 1152 charts, and Packet Loss Rate 1150 queries/ reports . Host Reachability can be monitoried using Traceroute network route to the host.
161

service. The service provides detailed information about

Virtual Machine availability can be monitored using VMware Server monitoring State 1115 alert.

1114

tools, namely Virtual Machine

Printer availability can be monitored using Printer monitoring tools: Printer State Cover 1120 alerts and Printer Information 1120 widget.

1120 ,

Printer Marker

1120,

Printer

Service Availability can be monitored using Service Offline alert 1145 and Services Status table. The Services Status table is accessible via Favourites 697 item and represents availability/operability 1044 statuses of all services running on all registered devices. Status of a service is presented with colors: grey if the service is disabled (i.e. not configured for monitoring), green if it is online, and red if it is offline.

Statistical Availability
Availability as a statistical value is the proportion of time a system is in a functioning condition.

Device availability is measured for a specific time interval as percentage: 100 - packetLossRate, where packetLossRate is percentage of failed ping requests. In AggreGate Network Manager the measure of statistical device availability for time intervals is represented by Availability Not 100% 1150 report.

AVAILABILITY CHART
The Network Device Overview dashboard 1151 includes an Availability Chart indicating the average availability percentages grouped by different time periods (hours, days, etc.)

9.12 Performance Monitoring

This topic comprises several aspects of internal performance of a device as a computing unit, i.e. "stand-alone" computer performance. The following computing facilities are covered here: central processing units (CPUs) -- see CPU Performance Monitoring
1092 ; 1093 ;

storage units (memory, hard disks, optical disks etc.) -- see Storage Monitoring software running on the host (processes) -- see Process Monitoring
1094 .

Network performance 1096 and application/service 1108 monitoring (often regarded as a part of performance monitoring) are described separately. Several device performance aspects, including gauges for CPU Load, Physical Memory Usage, Virtual Memory Usage can be displayed in real-time in a single window using IP Host Information widget 1154 . Another stratum of performance monitoring -- concerning virtualization technologies -- should be mentioned here. AggreGate Network Manager monitors various metrics of VMware ESX server virtual machines performance. Being described in a separate dedicated section (see VMware Server Monitoring 1114 ), virtualized infrastructure performance monitoring tools are also mentioned in the corresponding subsections below.

9.12.1 CPU Performance Monitoring

CPU Performance monitoring is accomplished via SNMP and WMI.

SNMP-based CPU Performance Monitoring

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

AggreGate Network Manager can collect CPU load data via SNMP and process it.

1093

According to RFC 1514 CPU load is the average, over the last minute, of the percentage of time that this processor was not idle. AggreGate Network Manager uses hrProcessorLoad SNMP variable to get the average CPU load. The variable is part of hrProcessorTable, providing separate data for all host's processors. The SNMP-based CPU Load monitoring tools include: CPU Load chart
1152 1152

Packet Loss Top 10 chart

CPU Load reports/queries 1150 CPU Load Top 10 Auto Run action
625

that shows 10 devices with the highest CPU load

The CPU Load chart 1152 can be created and configured using Setup Monitoring Profile action -- see CPU group in Setup Monitoring Profile Action 1052 . System administrators can create other tools (e.g. alerts, widgets, etc.) for interpreting data provided by hrProcessorTable SNMP variable. CPU utilization on VMware ESX servers by particular virtual machines can be monitored using Virtual Machine CPU Load alert 1115 and Virtual Machine CPU Utilization chart 1117 .

WMI-base CPU Performance Monitoring

AggreGate Network Manager can use WMI to obtain CPU performance data as instances of Win32_PerfFormattedData_Counters_ProcessorInformation. The WMI-based CPU performance monitoring tools include CPU Activity alert 1146 .

9.12.2 Storage Monitoring

This article refers to two distinct types of computer data storage facilities: memory (RAM, etc.) and persistent storage (hard disk drives, optical discs, etc.). Storage monitoring data is obtained using SNMP and WMI. Via SNMP , hrStorageTable SNMP table is utilized to get detailed information about logical storage volumes on the host, including their types, descriptions, total and free sizes, allocation units , etc. Via WMI, AggreGate Network Manager uses the following classes: Win32_PerfFormattedData_PerfOS_Memory to monitor memory Win32_LogicalDisk to monitor persistent storage. AggreGate Network Manager comprises the following storage monitoring tools: Storage Space (SNMP)
1146

alert

Storage Usage (SNMP) 1152 chart Memory Usage Top 10 (SNMP) Memory (WMI) 1146 alert Disk Free Space (WMI) 1146 alert Memory Usage 1150 reports/queries Disk Volumes Utiliaztion Top 10 (SNMP)
1152 1152

charts

charts

Disk Volumes Utilization 1150 reports/queries Disk Volumes Free Space

1150

reports/queries
625

Memory Usage Top 10 Auto Run action

that shows ten volumes with the highest load

2000-2013 Tibbo Technology Inc.

1094

AggreGate Documentation

The Storage Space alert 1146 and Storage Usage chart 1152 can be created and configured using Setup Monitoring Profile action -- see Storage Volumes group in Setup Monitoring Profile 1052 . Storage utilization of VMware virtual machines can be monitored using VMware Server monitoring Virtual Machine Disk Performance 1117 chart Virtual Machine Memory Usage 1117 chart Virtual Machine Absolute Memory Utilization
1115 1114

tools, namely:

alert

Virtual Machine Relative Memory Utilization 1115 alert Virtual Machine HDD Read Rate Virtual Machine HDD Write Rate
1115 1116

alert alert

9.12.3 Process Monitoring

Process monitoring corresponds to tracking metrics of software running on the host. Process activity information can be obtained via SNMP or WMI.

SNMP-based Process Monitoring

Process monitoring via SNMP is performed using hrSWRunTable and hrSWRunPerfTable tables, allowing to access information associated with each distinct process that is running or loaded into physical/virtual memory in preparation for running. This includes the host's operating system, device drivers, and applications. The monitoring data obtained via SNMP is processed and stored in AggreGate Network Manager's processList tabular variable providing the following information for every process: Value Source (SNMP variable name, or description of evaluation expression Description

Process Name

hrSWRunName

A textual description of this running piece of software, including the manufacturer, revision, and the name by which it is commonly known. A description of the location on long-term storage (e.g. a disk drive) from which this software was loaded. A description of the parameters supplied to this software when it was initially loaded. Type of this software (with numerical code): Unknown (1) Operating System (2) Device Driver (3) Application (4)

Process Path Process Parameters Process Type

hrSWRunPath hrSWRunParameters hrSWRunType

Process Status

hrSWRunStatus

The status of this running piece of software (with numerical code): Running (1) Runnable (2) -- waiting for resource (i.e., CPU, memory, IO) Not Runnable (3) -- loaded but waiting for event Invalid (4) -- not loaded

CPU Load, %

Derivative 1046 of

hrSWRunPerfCPU divided
by CPU count Memory Usage, Kilobytes

The average number of centi-seconds of the total system's CPU resources consumed by this process per second. The number of host's CPUs is provided by hrProcessorTable SNMP variable. The total amount of real system memory allocated to this process.

hrSWRunPerfMem

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1095

Memory Usage, %

hrSWRunPerfMem * 100 / hrMemorySize

The percentage of total amount of main memory on the host ( hrMemorySize) allocated to this process ( hrSWRunPerfMem).

To access host's processes information, select View Device Status item of the device's context menu, and go to Process List tab.

WMI-based Process Monitoring

WMI comprises several classes that provide information about processes and their activity. AggreGate Network Manager employs data available from Win32_Process and Win32_PerfFormattedData_PerfProc_Process classes.

Process Monitoring Alerts and Charts

AggreGate Network Manager provides a Processes alert 1146 allowing user to be notified when resources utilized by process (CPU load or memory usage) exceed the specified threshold. There is also some charts related to process monitoring: Process Count Chart .
1152

and Process Instance Count Chart

1052

1152

These alert and charts can be created for a particular device using Setup Monitoring Profile group there).

action (see Processes

9.12.3.1 Process Instance Count Chart

The Process Instance Count chart is a process-monitoring
1094

tool that diagrams number of process instances.

Process instance is identified by name, and (optionally) associated path and parameters.

While configuring chart for a host, you can select Process Name from a drop-down list of processes currently running there, or type it in. Process Path and Process Parameters fields can be optionally left unset (i.e. NULL). In this case, processes with specified name and any path/parameters are included.

2000-2013 Tibbo Technology Inc.

1096

AggreGate Documentation

Note that "unset" ("NULL") and "empty string" are different values. If you don't want to filter processes by path and/or parameters, make sure the corresponding fields are indicated as <Not set> which indicates null value. Blank field means an empty string is entered and the property will be used to filter processes out. For example, if Process Path is indicated as <Not set> and Process Parameters field is blank, the chart will count processes having no process parameters (empty string) and will ignore their paths. To set NULL value for a field you can use "Remove Value" item in the field's context menu.

9.12.4 Generic Service Performance Monitoring

Each AggreGate Network Manager device provides a Setting Synchronization Statuses 128 table that has I/O Duration field. This field reports time taken to read/write the variable during last device synchronization 126 . The I/O duration field can be analyzed by alert
216 's

trigger expression

217

in order to:
180

Measure execution time of any query provided by a database device driver Measure execution time of an SSH script
1113

executed on a remote Linux machine

139

Measure load time of web page retrieved by HTTP device driver Measure latency of any other service, such as DNS or DHCP

See description of alert trigger expression that analyzes device variable I/O duration here

238 .

9.13 Network Traffic and Bandwidth Monitoring

Monitoring network performance is a crucial point for a number of administrative tasks including: Detecting, identifying, handling and preventing network problems Finding inefficiencies and bottlenecks, performing load analysis, assure required quality of service Recognizing traffic patterns and trends, planning network capacity. AggreGate Network Manager supports two basic approaches to traffic and bandwidth usage monitoring: SNMP-based monitoring of network interfaces (see below) NetFlow-based monitoring 1100

SNMP-based Network Traffic and Bandwidth Usage Monitoring

AggreGate Network Manager can be configured to periodically poll network hosts via SNMP information about their network interfaces using ifTable SNMP variable: o total number of bytes received on and transmitted out of the interface o current bandwidth estimate (bits per second) o interface speed (maximum bandwidth) o number of packets that contained errors preventing them from being delivered o number of discarded packets. AggreGate Network Manager uses these values to estimate interface traffic and bandwidth utilization. For devices with the ifTable available an Interface Traffic (interfaceTraffic) variable is created. It contains calculated values as described in the following table: Field Name Interface Name Incoming Traffic, bps Outcoming Traffic, bps Comment Extracted from ifDescr field of ifTable. Calculated as derivation Calculated as derivation
1046 1046 1068

and obtain the following

of ifInOctets. of ifOutOctets.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1097

Incoming Bandwidth Usage, % Outgoing Bandwidth Usage, %

Calculated as a ratio between Incoming Traffic and its interface speed (ifSpeed field). Calculated as a ratio between Outgoing Traffic and its interface speed (ifSpeed field).
280 :

You can review this information for a particular device executing this query, for example, in Query Executor

SELECT * FROM users.*.devices.deviceContext:ifTable as data

(Substitute the deviceContext with the name of your device context.) The network interface monitoring data can be visualized using, for example, the following out-of-the-box charts: Interface Traffic chart
1097 1153

Interface Traffic Top 10 1152 and Bandwidth Usage Top 10 Interface Errors chart 1098 Interface Discards chart
1098 .

charts

You can also see this data in table form using reports, namely: Interface Traffic Summary
1099

report
1099

Interface Traffic Top 10 and Interface Traffic Top 50

reports
1099

Interface Bandwidth Utilization Over 50% and Interface Bandwidth Utilization Over 90% Interface Bandwidth Utilization Top 10 and Interface Bandwidth Utilization Top 50
1099

reports

reports.

Functional characteristics of individual interfaces on routers and switches can be used as to detect network problems. AggreGate Network Manager provides several alerts for that: Network Interface Utilization alert Network Interface Down alert
1098 1098 . 1098

Network Interface Administrative Shutdown alert

You can create custom tools for monitoring and analyzing activity of network interfaces.

9.13.1 Network Interface Traffic Chart

Network Interface Traffic chart shows incoming and outgoing traffic of specified network interfaces.

2000-2013 Tibbo Technology Inc.

1098

AggreGate Documentation
1151 .

The chart is available on the Network Device Overview dashboard for any device using Setup Monitoring Profile action 1052 .

Alternatively you can create a distinct widget

9.13.2 Network Interface Bandwidth Utilization

Network Interface Bandwidth Utilization chart shows incoming and outgoing bandwidth usage percentage of specified network interfaces. The chart is available on the Network Device Overview dashboard for any device using Setup Monitoring Profile action 1052 .
1151 .

Alternatively you can create a distinct widget

9.13.3 Network Interface Errors Chart

Network Interface Errors chart shows number of error packets. Error packets are inbound packets that contain errors preventing them from being deliverable to a higher-layer protocol. You can create a widget with the Interface Errors chart for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 .

9.13.4 Network Interface Discards Chart

Network Interface Discards chart shows a discarded packets for a particular Network Interface. Discarded packets are inbound packets which were chosen to be discarded even though no errors had been detected to prevent their being deliverable to a higher-layer protocol. For example, if too many packets are received, and the protocol stack does not have enough resources to properly handle the packet, it may be discarded. You can create a widget with the Interface Discards chart for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 .

9.13.5 Network Interface Utilization Alert

Network Interface Utilization alert monitors network interface bandwidth usage. The alert triggers if incoming or outgoing bandwidth usage exceeds a threshold. The interface and threshold are specified as alert's parameters. You can create Network Utilization alert by invoking Setup Monitoring Profile action 1052 .

9.13.6 Network Interface Down Alert

Network Interface Down alert monitors operational and administrative states of a network interface (available as ifOperStatus and ifAdminStatus fields in ifTable variable). The alert triggers when the operational status is down (2) and administrative status is up (1). The monitored interface is specified as alert's parameters. You can create Network Interface Down alert by invoking Setup Monitoring Profile action 1052 .

9.13.7 Network Interface Administrative Shutdown Alert

Network Interface Administrative Shutdown alert monitors desired state of interface of a network interface (available as ifAdminStatus field in ifTable variable). The alert triggers when the desired state is down (2). The monitored interface is specified as alert's parameters. You can create Network Interface Down alert by invoking Setup Monitoring Profile action 1052 .

9.13.8 Network Interface State Change Alert

Network Interface State Change alert monitors operational state of a network interface (available as ifOperStatus field in ifTable variable). The alert triggers when the operational status is changed (from Up to Down of vice versa). The monitored interface is specified as alert's parameters. You can create Network Interface State Change alert by invoking Setup Monitoring Profile action 1052 .

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1099

9.13.9 Interface Traffic Summary Report

Interface Traffic Summary report presents incoming and outgoing traffic and bandwidth information for all interfaces of all registered devices. This report includes the following fields: Field Name Device Interface Incoming Traffic, bps Outgoing Traffic, bps Incoming Bandwidth Usage, % Outgoing Bandwidth Usage, % Description Device name and type Network interface name Incoming traffic in bytes per second Outgoing traffic in bytes per second Incoming bandwidth usage ratio in percents Outgoing bandwidth usage ratio in percents

9.13.10 Interface Traffic Top 10 And 50 Reports

Interface Traffic Top 10 and Interface Traffic Top 50 reports present interfaces with the highest total (incoming and outgoing) traffic among all registered devices. These reports include the following fields: Field Name Device Interface Incoming Traffic, bps Outgoing Traffic, bps Description Device name and type Network interface name Incoming traffic in bytes per second Outgoing traffic in bytes per second

9.13.11 Interface Bandwidth Utilization Over 50% And 90% Reports

Interface Bandwidth Utilization Over 50% and Interface Bandwidth Utilization Over 90% reports present interfaces with incoming or outgoing bandwidth utilization over respective threshold. These reports include the following fields: Field Name Device Interface Incoming Bandwidth Usage, % Outgoing Bandwidth Usage, % Description Device name and type Network interface name Incoming bandwidth usage ratio in percents Outgoing bandwidth usage ratio in percents

9.13.12 Interface Bandwidth Utilization Top 10 And 50 Reports

Interface Bandwidth Utilization Top 10 and Interface Bandwidth Utilization Top 50 reports present interfaces with the highest total (incoming and outgoing) bandwidth utilization among all registered devices. These reports include the following fields: Field Name Device Interface Incoming Bandwidth Usage, % Description Device name and type Network interface name Incoming bandwidth usage ratio in percents

2000-2013 Tibbo Technology Inc.

1100

AggreGate Documentation

Outgoing Bandwidth Usage, %

Outgoing bandwidth usage ratio in percents

9.14 NetFlow-based Traffic Decomposition

NetFlow provides a powerful, flexible and effective way to collect data needed for detailed IP network performance analysis. It can be used for a number of tasks like the following: Monitoring network usage including current and historical data; finding top bandwidth consumers: users, hosts, applications, protocols, etc. Measuring actual traffic; obtaining detailed information about bandwidth utilization by particular hosts, network interfaces, applications, protocols, etc. Tracking network problems and reveal their roots; providing security, and detect threats like worms, virus attacks and other rogue and unsolicited activity. Tuning network for better performance in most common use cases specific for a particular organization. Ensuring required quality of network communication for critical applications. Network trending and capacity planning. NetFlow today is the most widely-used technology to collect statistics in large, high-traffic networks. NetFlow and its kindred technologies are supported by a number of network infrastructure vendors including Cisco, HP, Juniper, and many others.

9.14.1 NetFlow Basics

NetFlow and similar protocols are designed to deliver IP traffic information from observation points to collectors. An observation point is a location in the network where IP packets can be observed. For example, this can be an interfaces on a router. Packets entering an observation point are monitored by exporter. Exporter processes packets, accumulates traffic information and periodically sends it to a NetFlow collector. The collector receives the information, parses it and stores data for later usage by analytic tools. One collector can gather information from several exporters. Exporter don't send information about every particular packets it observes. Instead, packets are aggregated into several IP flows. Each flow accumulates data (number of packets and bytes) for packets with certain common properties. For example, a flow usually include the following traffic information: Source IP address and port number Destination IP address and port number IP protocol type Type of Service (ToS) value SNMP indices of input and output interfaces (see ifIndex in IF-MIB) Number of packets and bytes (Layer 3 octets) observed in the flow Timestamps for the moments when the first and the last packets in the flow were observed TCP flags Routing information etc. Exporter periodically sends accumulated flow data to collector. The flows to be sent are grouped together into export packets (datagrams). Export packet includes some basic information such as the NetFlow version, number of flows contained within the packet, and sequence numbering. Collector parses the export packets, extracts flow information and stores it. Now the traffic statistics can be used for analysis. AggreGate Network Manager implements flow collector service, provides a storage for netflow data, offers out-of-thebox tools for network utilization analysis. Furthermore AggreGate Network Manager allows to build custom analytic and visualization tools for your specific needs. In AggreGate Network Manager, all traffic decomposition features are supported by NetFlow plugin collector service and facilities for processing, aggregating, analyzing and visualizing IP traffic data.
950 .

It provides flow

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1101

9.14.2 Supported NetFlow Versions

Originally introduced by Cisco, NetFlow has evolved over time. There are several versions including obsolete (versions 1 and 6) ones, Cisco internal unreleased versions (versions 2, 3, and 4), relatively rare-used ones like versions 7 (geared only to switches, not routers) and 8 (offering aggregation capabilities to reduce NetFlow data volumes). The two versions that are actually widely used in practice are versions 5 and 9. NetFlow version 5 is still the most widely used NetFlow version for traffic analysis. It has all the features needed for most real-life circumstances and is supported by many routers from different brands. NetFlow version 9 (see RFC 3954 "Cisco Systems NetFlow Services Export Version 9") is the most powerful, flexible and extendible Cisco IP flow protocol version. Version 9 flow records are customizable being described by templates. This allows to collect greater number of metrics. This NetFlow version is mostly used for advanced circumstances like monitoring IPv6, MPLS, etc. NetFlow version 9 became a basis for recent IPFIX standard (RFC 3917, RFC 5101, RFC 5102, etc.). Although IPFIX (sometimes refered as NetFlow version 10) supersedes NetFlow 9 in several aspects, it is not yet widely adopted as an industry standard by network infrastructure vendors. There are also several "NetFlow-kind" protocols that provide similar features with certain variations or supported by other vendors. For example, sFlow is based on sampling and therefore is highly scalable technology applicable to high speed networks; on the other hand sampling significantly reduces accuracy.

9.14.3 System Requirements 9.14.4 Configuring Flow Exporters

Network devices and services should be correctly configured to provide statistics about the packets flowing through them. NetFlow capture and export are performed and configured independently on different network items. The configuration procedures differ significantly for various types of devices and collector services. Here we offer just few entry points for some of the most widely used types of devices and services. Refer to your device/service documentation for detailed usage and configuration instructions.

Cisco Devices
For information about configuring NetFlow on Cisco devices refer to documents you can find on official website (www. cisco.com); a good starting point is Configuring NetFlow and NetFlow Data Export.

Other Vendors
There are other vendors who produce network device supporting NetFlow including 3Com (HP Networking), Enterasys Networks, Extreme Networks, Juniper Networks and some others. Refer to a particular vendor's documentation for details of NetFlow configuration.

Software Exporters
Not all network devices support NetFlow. If none of your switches or routers support Netflow or one of its "kindred" protocols you can use a software exporters. For example, if you have a switch supporting port mirroring/SPAN, you can configure it to send a copy of network packets to a certain network location. It can be, for example, a computer running a software exporter on attached to the mirror port. Alternatively, if your switch does not allow to mirror your traffic, you can still monitor NetFlow data by using a hub (not a switch) to make your network packets reach a software exporter. For example, having a hub between your external router and your backbone equipment, all the traffic that flows through the link will be available for the software exporter attached to that hub. There is a number of proprietary and free software NetFlow exporters: fprobe: a free tool based on libpcap, a portable C/C++ library for network traffic capture; fprobe can be compiled for any POSIX-compatible OS (Linux/BSD/Unix-like). nProbe: a commercial product by nTop able to play roles of exporter and collector; there is a free version for no profit institutions and universities; available on Unix (including MacOS X and Solaris), Windows , and embedded environments. ng_netflow: implements NetFlow protocol on FreeBSD ; free. NDSAD: a free exporter for BSD and POSIX platforms (based on libpcap library), and Windows (winpcap-based).

2000-2013 Tibbo Technology Inc.

1102

AggreGate Documentation

9.14.5 Configuring Flow Processing

What to configure on the server for NetFlow Processing: -Configure NetFlow Plugin -Add NetFlow Sensor devices -Enable Flow Processing and select interfaces

9.14.5.1 Configuring NetFlow Plugin

9.14.5.2 Configuring DNS and NetBIOS Resolution

9.14.5.3 Configuring Device Accounts of NetFlow Sensors

9.14.6 Viewing NetFlow Processing Statistics 9.14.7 Flow Data Aggregation 9.14.8 Visualizing Traffic Flows
NetFlow Traffic Overview Dashboard NetFlow Sensors NetFlow Interfaces NetFlow Conversations NetFlow Applications NetFlow Countries NetFlow Endpoints NetFlow Protocols NetFlow Types of Service NetFlow Autonomous Systems Endpoint Details Dashboard

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1103

9.14.9 Optimizing NetFlow Processing Performance

Switching to On-demand Host Name Resolution Limiting Flow Collection Fine-Tuning Data Aggregation

9.15 Database Monitoring

AggreGate Network Manager provides monitoring of any JDBC-compliant Database Management System. The database monitoring is implemented by SQL Database driver 180 . The driver provides database availability monitoring by checking their connection status. Furthermore, it supports SQL insert/update/delete queries execution providing reach capabilities for in-depth monitoring of relational databases. As an example, consider the following Firebird/Interbase database monitoring task. Say, we want to check charsets and collations of string fields in tables. The corresponding SQL request is as follows:

select rf.rdb$relation_name relation, rf.rdb$field_name table_field, f.rdb$field_name field_domain, f.rdb$field_type field_type, cs.rdb$character_set_name character_set, c.rdb$collation_name collation_name from rdb$fields f, rdb$character_sets cs, rdb$collations c, rdb$relation_fields rf where cs.rdb$character_set_id = f.rdb$character_set_id and c.rdb$collation_id = f.rdb$collation_id and c.rdb$character_set_id = cs.rdb$character_set_id and f.rdb$field_name = rf.rdb$field_source and f.rdb$character_set_id is not null and rf.rdb$relation_name not starting with 'RDB$' order by 1, 2
Assume, there is a registered SQL Driver device with org.firebirdsql.jdbc.FBDriver as Database Driver, jdbc:firebirdsql:<dbHost>/3050:<dbPath> as Database URL (where <dbHost> and <dbPath> are substituted with your database host and path), and correct Database Username and Database Password values. Then the request can be added at Queries tab providing, say, charsets as Name and Charsets and Collations as Description . Once the query is configured, database monitoring results (in the Device Configuration table) will have Charsets And Collations property containing query result. Now you can identify incorrect charsets and collations according to your custom rules and add alerts or process them some other way.

9.15.1 MySQL Monitoring

2000-2013 Tibbo Technology Inc.

1104

AggreGate Documentation

9.15.2 Oracle Monitoring 9.15.3 Microsoft SQL Server Monitoring 9.15.4 PostgreSQL Monitoring

9.16 Filesystem Monitoring

AggreGate Network Manager provides functionality for monitoring filesystem on the computer that runs AggreGate AggreGate Server. This includes checking the existence of files and folders, their contents, sizes, attributes, and so on. See Local Folder Monitoring 1104 and Local File Monitoring 1104 subsections for details.

9.16.1 Local File Monitoring

Local file monitoring is provided by the Local File driver checking for the existence of a certain file. acquiring file attributes: o last modification time o size calculating file checksum (using Adler-32 algorithm) loading file contents and making them available for analysis and editing by AggreGate data processing tools (e.g. alerting if a certain pattern is found). File monitoring can be a helpful and effective tool for a number of network managements tasks, such as: Detecting events on the host being monitored by the presence or absence of a particular file. Monitoring the availability of a service or an application by tracking the last modification time and/or other attributes of a specific file. Monitoring application activity by analyzing file contents. Managing applications by changing contents of their configuration files.
143 .

It lets you monitor files located on the server by:

9.16.2 Local Folder Monitoring

Local folder monitoring is provided by Local Folder Driver providing the options to:
144 .

It allows to monitor folders located on the server by

check the existence of the folder at the specified path on the server acquire folder attributes, namely: o last modification time o file count o size, i.e. total size of files in the folder (all files of filtered set of them) load and inspect folder contents (files and subfolders) Contents of a folder can be analyzed recursively (including subfolders) or non-recursively. Besides that, the items to be processed can be filtered using wildcard or regular expression. Local Folder monitoring can be a helpful and effective tool for a number of network managements tasks, such as:

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

Tracking presence or absence of a particular folder.

1105

Monitoring availability of a service or an application by tracking last modification time and/or other attributes of a specific folder. Remotely analyzing application output or application activity by inspecting folder contents. Checking total size of application log files and warning about necessity to backup them.

9.16.3 Log File Monitoring

There are several ways to monitor log files of different applications for errors and warnings: Logs located on AggreGate Server machine may be monitored using Local File monitoring driver
1104 .

Log files located on remote machines may be accessed by Local File monitoring driver 1104 by mounting remote folders to the local filesystem via operating system facilities (Map Network Drive function on Microsoft Windows; NFS or Samba on Linux). Remote logs can be checked for errors by a custom shell script that is periodically executed via SSH such script is grep error_text /var/log/some_log_file.log | tail -n1.
1113.

Example of

9.17 Event Monitoring and Consolidation

AggreGate Network Manager can collect, process and store network event and error notifications from different sources. Generic concepts of event correlation and root cause analysis are described in the Event Management section. The following sources are supported by AggreGate Network Manager: Syslog messages SNMP traps
1107 1105 884

WMI events 1108 Windows Log Events

1108 129 .

Any other events provided by different device drivers

9.17.1 Syslog
Syslog is a standard for forwarding log messages in IP networks. This protocol is typically used for managing computer systems and performing security audits integrating log data from many different types of systems into a central repository. Syslog is a client/server protocol: the Syslog sender sends a small textual message (Syslog message) to the Syslog receiver. AggreGate Network Manager can play both roles providing abilities to monitor Syslog messages 1105 as well as to generate and send off Syslog messages 1107 . Additionally, automatic discovery of Syslog message sources 1107 is supported.

9.17.1.1 Syslog Events Monitoring and Consolidation

Providing Syslog events monitoring, Syslog plugin 1043 implements a Syslog receiver that listens to Syslog messages , collects them and converts into AggreGate events 880 . The Syslog events can be processed, stored, traced, displayed and filtered like any other conventional AggreGate events. For detailed Syslog protocol definition refer to RFC 5424. Syslog monitoring is set up by Syslog plugin configuration parameters 1048 . When a Syslog message is received it is parsed and a corresponding AggreGate event is generated. The structure and data conversion rules are presented in the following table: Event Field Source Host Event Field Name source Type String Description Message source address, i.e. address the Syslog message was received from.

2000-2013 Tibbo Technology Inc.

1106

AggreGate Documentation

Severity Facility IP Address or Host Name Message Timestamp

level facility host message timestamp

Integer Original severity level specified in the Syslog message. Refer to RFC 5424 for a list of severity values. Integer Original facility specified in the Syslog message. String String Date Host specified in the Syslog message (usually the originator of the message). Syslog message text providing information about the event. Timestamp specified in the Syslog message.

The AggreGate event is generated with severity level that is converted from original Syslog severity using conversion table 1049 specified in the Syslog plugin configuration parameters.

9.17.1.1.1 Syslog Alerts

AggreGate Network Manager provides a set of preconfigured alerts
216

for Syslog messages as described below.

Syslog alert triggers contain at most three conditions joined with logical AND (conjunction) operations. They check if the message: contains a certain string has facility equal to a certain value has severity equal to a certain value. The following table describes Syslog alerts and their trigger conditions. Name Description Trigger Condition Message contains syslogAlertFailedLogin syslogAlertKernelAlert syslogAlertKernelEmergency syslogAlertMailCritical syslogAlertMailEmergency syslogAlertSecurityOrAuthorizationAlert syslogAlertSecurityOrAuthorizationEmergen cy syslogAlertFtpLogOut syslogAlertFtpLogIn syslogAlertSuperuserLoginSuccess syslogAlertUserLoginSuccess Failed Login Kernel Alert Kernel Emergency Mail Critical Mail Emergency Security Or Authorization Alert Security or Authorization Emergency FTP Log-Out FTP Log-In Superuser Successful Login User Successful Login FTP session closed FTP LOGIN FROM opened session opened FAILED LOGIN Facility Security (4) Kernel (0) Kernel (0) Mail (2) Mail (2) Security (4) Security (4) FTP (11) FTP (11) Security (4) Security (4) Severity Notice (5) Alert (1) Emergency (0) Critical (2) Emergency (0) Alert (1) Emergency (0) Informational (6) Informational (6) Notice (5) Informational (6) Alert (1) Emergency (0) Alert (1) Emergency (0)

syslogAlertDaemonAlert syslogAlertDaemonEmergency syslogAlertUserLevelAlert syslogAlertUserLevelEmergency

Daemon Alert Daemon Emergency User-Level Alert User-Level Emergency

Daemons (3) Daemons (3) User (1) User (1)

Custom alerts for Syslog messages can be easily created by users for their specific needs using the described alerts as examples.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1107

9.17.1.1.2 Syslog Message Source Automatic Discovery

It is reasonable to consider IP hosts that originate Syslog messages as potentially manageable items. AggreGate Network Manager's Syslog plugin has an option to enable automatic discovery for Syslog message sources 1049. If it is enabled, every Syslog event generation will trigger a discovery process for the host that sent the corresponding Syslog message.

9.17.1.2 Syslog Messages Sending

AggreGate Network Manager can generate and send Syslog messages. This operation is performed by Send Syslog Message (sendSyslogMessage) action 892 in Root context 726 .

Input Format
Action can be configured with parameters of the following format: Name protocol host port message facility level sendName sendTimestam p Type String Integer String Integer Integer Integer Boolean Boolean Description Protocol Target IP Address or Host Name Port Message Facility Severity Send Local Name Send Local Timestamp Details Transport protocol to be used to deliver message (UDP or TCP ). Receiver address (127.0.0.1 by default). Port the message will be sent to (514 by default). Message text. Message facility. Refer to ... for a list of predefined values. Message level. Refer to ... for predefined values. Whether source host name should be included in the message. Whether a timestamp should be included in the message.

9.17.2 SNMP Notifications

AggreGate Network Manager receives and processes SNMP traps (check Receiving SNMP Traps 1085 for details). Received trap is converted into an internal AggreGate trap event 880 . Traps can be used to monitor important events occurring with managed items. AggreGate Network Manager includes a set of preconfigured alerts for some important SNMP trap events, see SNMP Trap Alerts 1107 subsection below. At the same time AggreGate Network Manager itself can generate and send SNMP traps allowing to notify other hosts in the network about important conditions. Refer to Sending SNMP Traps 1087 section for additional information.

9.17.2.1 SNMP Notification Alerts

AggreGate Network Manager provides a set of preconfigured alerts for SNMP notifications as described below. Alert triggers can contain two conditions: for notifications of SNMP version 1, and for version 2c and above . The following table describes SNMP trap alerts and their trigger conditions. Name Description Trigger Condition for SNMP Version 2c Traps Trap OID Authentication Failure Authentication attempt failed. The source address is included in the alert message. Router configuration changed. authenticationFailure SNMP Version 1 Traps Generi c ID 4 Specifi c ID Enterprise

Router Configuration Changed

1.3.6.1.4.1.9 or cisco

2000-2013 Tibbo Technology Inc.

1108

AggreGate Documentation

Cisco Fan Notification

One of the fans in the fan array fails.

1.3.6.1.4.1.9.9.13.3.0.4 or ciscoEnvMonFanNotification 1.3.6.1.4.1.9.9.13.3.0.1 or ciscoEnvMonShutdownNotification

Cisco Shutdown Environmental monitor detects a testpoint reaching a critical state and is about to initiate a shutdown. Cisco Temperature Notification Cisco Voltage Notification Temperature measured at a given testpoint is outside the normal range.

1.3.6.1.4.1.9.9.13.3.0.3 or ciscoEnvMonTemperatureNotification

The voltage measured at 1.3.6.1.4.1.9.9.13.3.0.2 or a given testpoint is ciscoEnvMonVoltageNotification outside the normal range. The redundant power supply failed. 1.3.6.1.4.1.9.9.13.3.0.5 or ciscoEnvMonRedundantSupplyNotificatio n 1.3.6.1.2.1.43.18.2.0.1 or printerV2Alert linkDown linkUp coldStart 2 3 0

Cisco Redundant Supply Notification Printer Alert Link Down Link Up Cold Start

A critical printer event is detected. An interface is about to enter the down state. An interface left the down state. Cold Start, i.e. reinitializing with configuration possibly altered. Warm Start, i.e. reinitializing with configuration unaltered. An EGP neighbor for which the device is an EGP peer is down and the peer relationship no longer exists.

Warm Start

warmStart

EGP Neighbor Loss

Custom alerts for SNMP traps can be easily created by users for their specific needs using the described alerts as examples.

9.17.3 WMI Events

WMI uses subscription engine to deliver notifications about important events in a managed system. AggreGate Network Manager utilizes services delivered by WMI device driver to subscribe and receive WMI events. Refer to WMI 186 chapter for details.

9.17.4 Windows Log Events

Windows NT line of operating systems provides provides a standard, centralized way for operating system itself and applications to record important software and hardware events in a a single collection called an Event Log. AggreGate Network Manager can be used to monitor activity of Windows computers by configuring their event logs to translate Windows events into SNMP traps and send them to AggreGate Network Manager server. Refer to Receiving Windows Event Log Messages 1054 section for more detailed information and configuration instructions.

9.18 Application/Service Monitoring

AggreGate Network Manager supports operability protocols.
1044

monitoring of various services and applications via TCP and UDP

To start monitoring for a particular application/service, enable corresponding monitor in the configuration of Network

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

Host device. This can be done manually, while configuring an individual device simultaneously), or automatically as part of the discovery 1055 process.
1019

1109

(also for multiple devices

1092

Availability/operability status summary for all devices/services can be monitored using Services Status table available in Favourites 626 .

9.18.1 Web Server Monitoring

AggreGate Network Manager provides many tools for web server monitoring: Web page monitoring and URL content checking 1109 by executing raw HTTP queries. This approach is independent of web server type (IIS, Apache, SunONE, etc). It is the most useful for website operability monitoring, but can be also used to organize web server functional testing -- see HTTP Monitoring 1109 section for details. Web page load time tracking 1096 and threshold alerting Comprehensive monitoring of underlying application servers and database engines
1103

Monitoring CPU load, memory, bandwidth usage and other KPIs of Web Server machine Collection of Web Server errors via Syslog 1105 Web server log file analysis
1105

Apache Monitoring
Apache web server monitoring 1109 allows to reveal some inner details (configuration, status, performance, error statistics) of Apache HTTP Server, available via SNMP in the presence of Mod-Apache-Snmp module.

9.18.1.1 Web Page Monitoring

HTTP device driver 139 and HTTP monitoring service 156 included in the Network Host device driver execute arbitrary HTTP requests and analyze URL (web page) content. To setup URL monitoring: Create an HTTP device or enable HTTP service in a Network Host device Set up HTTP/HTTPS port, monitored URL, request type (GET or POST) and parameters, optional authorization information, custom HTTP headers, user agent and timeout Open device configuration (select Configure from context menu) to see status of the HTTP service and content of the loaded web page Use any system facilities (like alerts 216 , models code, HTTP headers, response body, etc.
303 , 150

allow a user to

scripts

628 ,

etc.) for sophisticated analysis, e.g. checking reply

Built In Alerts
There are several URL monitoring alerts built into AggreGate Network Manager: Incorrect HTTP Reply
1147

alert
1147

HTTP Reply Content Changed HTTP Reply Content 1147 alert

alert

9.18.1.2 Apache Web Server Monitoring

Apache Web Server monitoring is performed via SNMP. To enable Apache monitoring: Install Mod-Apache-Snmp module into the Apache web server if it's not installed yet Make sure that APACHE2-MIB file exist in the MIB directory Manager package and loaded by default) Add a Network Host
150 178

(it's actually included to standard AggreGate Network

device via discovery 1055 or manually

113

Make sure that APACHE-MIB is checked in device assets Wait until the device synchronizes
126

(it's actually checked by default) icon)

(switches into Online, Synchronized mode indicated by

2000-2013 Tibbo Technology Inc.

1110

AggreGate Documentation

AggreGate Network Manager provides several tools for Apache web server monitoring out-of-the-box as described in the subsections below: Apache Dashboard Apache Alerts 1110
1110

9.18.1.2.1 Apache Dashboard

Apache dashboard opens upon double click on an Apache Web Server device node. It can be also selected from node's context menu. This dashboard provides the following information: Server name Server version Listened ports Uptime Total traffic Total served pages Busy and idle processes charts Graph of number of pages served per second Traffic chart HTTP error statistics chart And some other metrics

9.18.1.2.2 Apache Alerts

To create alerts for a certain Apache web server, select its host in System Tree and choose Setup Monitoring Profile menu item. Check Create Alerts item for the Apache Web Server monitoring group in the Monitoring Profile Setup window. You can create one or more alerts by adding alert records to the configuration table and specifying their type, name, description, and parameters.

APACHE REQUESTS OVERLOAD ALERT

Alert parameters include: Threshold (number of requests per second), Check Period, Delay, and Alert Level. The alert is triggered when Requests Per Second parameter (serverRequestsPerSec) exceeds the specified threshold.

APACHE TRAFFIC OVERLOAD ALERT

Alert parameters include: Threshold (kilobytes per second), Check Period, Delay, Alert Level. The alert is triggered when number of kilobytes per second transferred by an Apache server (serverKBytesPerSec) exceeds the specified threshold.

APACHE BUSY WORKERS ALERT

Alert parameters include: Threshold (number of busy processes), Check Period, Delay, Alert Level. The alert is triggered when a total number of Apache's busy processes (busyWorkers) exceeds the specified threshold.

APACHE HTTP ERROR ALERT

Alert parameters include: HTTP Error, Check Period, Delay, and Alert Level. The alert is triggered when a new error of the specified type is generated. The alert functions by monitoring value of SNMP variables representing HTTP error counts (see the table below) and raising when the count is changed. AggreGate Network Manager can monitor the following HTTP errors (see Status Code Definitions section in Hypertext Transfer Protocol -- HTTP/1.1 for details about HTTP status codes):

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1111

Status Code 400 403 404 405 500 501 505

Short Description BAD REQUEST FORBIDDEN NOT FOUND METHOD NOT ALLOWED INTERNAL SERVER ERROR NOT IMPLEMENTED VERSION NOT SUPPORTED

SNMP Variable

httpError400 httpError403 httpError404 httpError405 httpError500 httpError501 httpError505

9.18.1.3 Microsoft IIS Monitoring

9.18.2 Application Server Monitoring

9.18.2.1 JBoss Monitoring

9.18.2.2 Tomcat Monitoring

9.18.2.3 Oracle Application Server Monitoring

9.18.2.4 Lotus Domino and Lotus Notes Monitoring

9.18.2.5 Microsoft SharePoint Monitoring

9.18.3 WebSphere MQ Monitoring

IBM WebSphere MQ monitoring is enabled via WebSphere MQ Device Driver Monitoring availability and operability of MQ server Monitoring channels (status, start time, incoming/outgoing traffic) Monitoring queues (depth, last get/put operation times, maximum and average message ages, input/output counts, uncommitted message counts) Monitoring listeners (start time, backlog, command/session counters)
184 .

It provides the following functionality:

2000-2013 Tibbo Technology Inc.

1112

AggreGate Documentation

9.18.4 FTP Server Monitoring

FTP server monitoring is supported by Network Host 150 device driver. It provides FTP server operability checking by obtaining server status and reading attributes of a remote file. Furthermore FTP monitoring can be used to track remote files or directories for analyzing activity of remote applications by processing error reports, logs, etc. Refer to FTP Server Monitoring 160 section and its subsection for details about monitoring procedure, parameters used and results that can be obtained. AggreGate Network Manager includes the following tools for monitoring a particular FTP server: FTP File Size 1147 alert FTP Total File Size FTP File Changed
1147

alert alert

1147

FTP File Is Too Old 1147 alert FTP File Size 1154 chart

9.18.5 E-mail Server Monitoring

AggreGate Network Manager support for e-mail server monitoring let you ensure that your electronic mail services are working properly. Monitoring methods include: Basic operability monitoring of POP3 Monitoring end-to-end delivery 1112 .
1112 ,

IMAP

1112

and SMTP

1112

servers.

9.18.5.1 POP3 Monitoring

Availability and proper functioning of POP3 e-mail server is monitored by connecting to a mailbox, then fetching message count and total size of all messages from INBOX folder. This is implemented by the Network Host 150 device driver. Refer to POP3 Server Monitoring 157 section for description for service functioning, configuration and results. AggreGate Network Manager includes the following tools for POP3 monitoring: Too Many E-mail Messages (POP3) 1147 alert High Messages Size (POP3)
1147

alert

9.18.5.2 IMAP Monitoring

Availability and proper functioning of IMAP e-mail server is implemented by Network Host 150 device driver. The monitoring is performed by connecting to a mailbox, then fetching message count and total size of all messages from a specified folder. Refer to IMAP Monitoring 158 section and its subsections for details. AggreGate Network Manager includes the following tools for IMAP monitoring: Too Many E-mail Messages (IMAP) 1147 alert High Messages Size (IMAP)
1147

alert

9.18.5.3 SMTP Monitoring

Availability and proper functioning of SMTP e-mail server is monitored by establishing a connection with the server and passing its authorization procedure. No e-mail messages are actually sent. Refer to SMTP Server Monitoring 158 section for details.

9.18.5.4 E-mail Round-Trip Monitoring

E-mail round-trip monitoring ensures end-to-end delivery of electronic messages, checking functioning of an e-mail system as a whole. It generates specially formed test messages, send them, and then checks they are delivered to the recipient. Monitor uses SMTP to send messages, and either POP3 or IMAP to retrieve and remove them from monitored folder. The service is implemented by Network Host 150 device driver. Refer to E-mail Round-Trip Monitoring 159 section and its subsections for details.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1113

9.18.5.5 Postfix Monitoring

9.18.6 Active Directory (LDAP) Monitoring

LDAP monitoring is provided by Network Host device driver 150 . It provides ability to establish connection with LDAP server and execute search requests there. Refer to LDAP Monitoring 165 section for details. AggreGate Network Manager includes the following tools for LDAP monitoring: LDAP Request Result 1147 alert

9.18.7 SSH Server Monitoring

SSH server monitoring is provided by Network Host device driver 150 . It provides ability to connect to a network host via SSH protocol, authenticate and execute scripts on the remote host. In addition to availability/operability monitoring this allows to perform various administration tasks. Refer to SSH Server Monitoring 163 section for details. AggreGate Network Manager includes the following tools for SSH monitoring: SSH Script Result 1147 alert

9.18.8 Radius Server Monitoring

RADIUS server monitoring is supported by Network Host device driver 150 . It allows to send access requests and process responses. Refer to RADIUS Server Monitoring 166 section for details.

9.18.9 DNS Server Monitoring

Domain Name System (DNS) server monitoring is supported by Network Host device driver 150 . It allows to send DNS requests to the server and provides their results for analysis. Refer to DNS Server Monitoring 156 section for details about its operation, configuration and results. AggreGate Network Manager includes the following tools for DNS monitoring: DNS Request Result
1147

alert

9.18.10 DHCP Server Monitoring

Dynamic Host Configuration Protocol (DHCP) server monitoring is provided by by Network Host device driver 150 . It is performed by sending a DISCOVER request and listening for a corresponding answer from DHCP server. Refer to DHCP Server Monitoring 164 section for details.

9.18.11 Generic TCP Service Monitoring

Network Host 150 device driver supports availability/operability monitoring for TCP services of any kind (hence the term "generic" used here) by establishing a connection with the device via the associated port, sending some raw data and receiving replies. Several services can be configured to be monitored at a particular IP host. Refer to Generic TCP Service Monitoring section 154 for details. AggreGate Network Manager includes the following tools for generic TCP service monitoring: TCP/UDP Monitor Results
1147

alert

9.18.12 Generic UDP Service Monitoring

UDP service monitoring is supported by Network Host 150 device driver. Several UDP services can be monitored at different ports of an IP host. The monitoring procedure includes sending user-specified data and getting a reply. Refer to Generic UDP Service Monitoring section 155 for details. AggreGate Network Manager includes the following tools for generic UDP service monitoring: TCP/UDP Monitor Results
1147

alert

2000-2013 Tibbo Technology Inc.

1114

AggreGate Documentation

9.19 Active Directory Monitoring

9.19.1 Microsoft DNS Server Monitoring

9.20 VMware Monitoring

Being a leading provider of virtualization technologies, VMware provides a set of products including desktop and enterprise (server) solutions. AggreGate Network Manager provides control and monitoring for VMware ESX/ESXi servers and Guest Virtual Machines (Guest VMs). For the purposes of discussion we decompose virtual systems monitoring into several levels: server level, virtual machine level, and operating system level. In the context of this classification AggreGate Network Manager provides monitoring at all the levels with both generic and VMware-specific tools. Namely, at the server level, VMware server can be treated as a standard Linux machine and therefore can be monitored with "universal" monitoring tools (see Device Availability Monitoring 1091 , Performance Monitoring 1092 , Applications and Services Monitoring 1108). Similarly at operating system level, operating system that runs inside a Guest VM acts like any other operating system, and therefore can be monitored using the same approach. VMware-specific tools are primarily needed for monitoring at the level of particular virtual machines, as this is the place where all the "magic" actually happens. AggreGate Network Manager VMware virtual machine monitoring toolset allows to monitor particular virtual machines running on the specified VMware server. It includes VMware Information Widget 1118 along with a set of alerts 1114 and charts 1116 . The toolset can be customized if necessary, or extended by creating new tools using the existing ones as templates and/or examples. AggreGate Network Manager monitors virtual machines running on VMware servers via SNMP , using vmTable, cpuTable, memTable, vmwHBATable, and vmwNetTable variables. These variables are automatically configured for periodic polling (to provide live refreshing of the values), and historical values storage (for statistical analysis). The polling settings can be adjusted for specific tasks using Device Settings Synchronization Options 115 . Refer to VMware documentation for more information on enabling SNMP on VMware servers.

9.20.1 VMware Alerts

AggreGate Network Manager provides the following VMware alerts out of the box: Virtual Machine State 1115 Memory Utilization (Volume) 1115 Memory Utilization (Percentage) 1115 CPU Load 1115 HDD Read HDD Write
1115 1116

Refer to the appropriate section for details. To create and configure VMware alerts, use the Setup Monitoring Profile VMware alert group . Thus, to setup VMware alerts: Select the VMware server device; Chose Setup Monitoring Profile
1052 1052

action. These alerts are members of

item in context menu;

Check VMware item in Create Alert column; When Configure VMware Alerts window appears, add one or more alert and specify their settings: name, description, type , virtual machine instance an alert should apply to, and setup parameters (refer to the corresponding alert section for specific details). Note, that providing a name equal to a name of some existing alert, you do not actually create a new alert, but rather add a trigger 216 to that existing alert. If you want to create a new alert, be sure to provide a unique name.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1115

You can administer alerts and their triggers using generic AggreGate tools, as described in Alerts

216

section.

9.20.1.1 Virtual Machine State Alert

Virtual Machine State alert monitors state of a selected virtual machine. The alert is triggered if current VM state satisfies the condition specified by the alert parameters. The condition consists of a VM state (Powered On, Powered Off, or Suspended) and comparison operation (Equal, or Not Equal). Example: if the user has specified "Not Equal" as a comparison operation and "Powered On" as a state value, the alert will be triggered when virtual machine is powered off or suspended.

9.20.1.2 Virtual Machine CPU Load Alert

CPU Load alert monitors the virtual machine's CPU utilization percentage . The alert is triggered, if the current value satisfies a condition specified in the alert parameters. The conditions consists of a threshold (in percents) and comparison operation (Equal, Not Equal, Greater, Less, Less Or Equal, Greater Or Equal). Example: if the user specified 50 as a threshold, and a "Greater" as a comparison operation, the alert will be triggered when the CPU Load exceeds 50%.

9.20.1.3 Virtual Machine Absolute Memory Utilization Alert

Absolute Memory Utilization alert monitors memory volume (measured in kilobytes) used by the selected virtual machine. It triggers if the current value satisfies a condition specified by the alert parameters. The conditions consists of a threshold (in kilobytes) and comparison operation (Equal, Not Equal, Greater, Less, Less Or Equal, Greater Or Equal). Example: if the user specified 175000 as a threshold, and a "Not Equal" as a comparison operation, the alert will be triggered when the memory used by virtual machine differs from (i.e. strictly greater or strictly less than) 175000 Kbytes.

9.20.1.4 Virtual Machine Relative Memory Utilization Alert

Relative Memory Utilization alert monitors percentage of memory used by the selected virtual machine. It triggers if the current value satisfies a condition specified by the alert parameters. The condition consists of a threshold (in percents) and comparison operation (Equal, Not Equal, Greater, Less, Less Or Equal, Greater Or Equal). Example: if the user specified 50 as a threshold, and a "Greater" as a comparison operation, the alert will be triggered when the memory used is over 50% of all available for the virtual machine memory.

9.20.1.5 Virtual Machine HDD Read Rate Alert

HDD Read Rate alert monitors the selected virtual machine disk read rate. The alert is triggered, if the current value satisfies a condition specified in the alert parameters and consisting of a threshold (in Kilobytes per second) and comparison operation (Equal, Not Equal, Greater, Less, Less Or Equal, Greater Or Equal). Example: if the user specified 25000 as a threshold, and a "Less Or Equal" as a comparison operation, the alert will be triggered when the disk read rate does not exceed 25000 Kbytes/s.

2000-2013 Tibbo Technology Inc.

1116

AggreGate Documentation

9.20.1.6 Virtual Machine HDD Write Rate Alert

HDD Write Rate alert is a paired with and similar to HDD Read Rate write rate instead.
1115

but monitors the selected virtual machine disk

9.20.2 VMware Charts

AggreGate Network Manager includes a set of charts displaying virtual-machine related data.

The charts are available for creation and configuration via VMware group of Setup Monitoring Profile action CPU Utilization 1117 chart

1052:

Four Disk Performance 1117 charts: Disk Writes Number , Disk Reads Number, Disk Writes Rate and Disk Reads Rate Two (Absolute and Relative) Memory Usage
1117

charts

Four Network Performance 1117 charts: Network Packets Transmitted, Network Packets Received, Network Transfer Rate, and Network Receive Rate The VMware group is available for device contexts having vmTable SNMP variable. To setup one or several VMware charts using Setup Monitoring Profile Select the VMware server device context Choose Setup Monitoring Profile
1052 1052

action:

item in context menu

Check VMware item in Create Chart column In Configure VMware Charts window, add as many charts as you need, and configure them by specifying their types (one of the mentioned about), names, descriptions (as described in Setup Charts 1052 subsection of Setup Monitoring Profile 1052 ), and parameters. All the VMware chart types have similar parameters: just check the virtual machines those metrics should be depicted. A chart widget 312 with the specified name and description will be created. You can find it under Widgets node in System Tree 784 , or invoke from the device context menu (the menu item name will be the same as chart description provided).

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1117

9.20.2.1 Virtual Machine CPU Utilization Chart

CPU Utilization chart indicates how much of the processor's capacity is currently used by the virtual machine(s). The value diagrammed is measured as a time derivative 1046 of total time the virtual machine has been using CPU (exposed in cpuTable SNMP variable). If you customize synchronization options see also Processing Data 1046 section.
115 ,

ensure that cpuTable synchronization period is not too small --

9.20.2.2 Virtual Machine Memory Usage Charts

There are two out-of-the-box charts visualizing the virtual machine(s) memory usage: Absolute Memory Usage Relative Memory Usage. Both charts use memUtil value in memTable SNMP variable to fetch current memory utilized by certain virtual machine. Absolute Memory Usage chart diagrams memUtil as absolute value producing memory utilization in kilobytes,while Relative Memory Usage chart diagrams this value relative to amount of memory the virtual machine was configured with producing memory utilization percentage.

9.20.2.3 Virtual Machine Disk Performance Charts

These charts visualize current disk utilization by the virtual machine(s). Disk Reads Number and Disk Writes Number charts diagram disk utilization, measured as a number of disk read (write) operations performed since last synchronization. The values used are actually a differentiation 1045 of numReads (numWrites) values provided in vmwHBATable SNMP variable. Disk Read Rate and Disk Write Rate charts diagram disk read/write rates calculated as time derivatives of kbRead / kbWritten (total kilobytes read from / written to the disk per second) values in vmwHBATable SNMP variable. Mind issues concerning too small synchronization period , as mentioned in Processing Data customizing vmwHBATable synchronization options 115 .
1046

section, when

9.20.2.4 Virtual Machine Network Performance Charts

The charts depict network activity of the virtual machine(s) measured as data packets and/or kilobytes received/ transferred, based on values provided in vmwNetTable SNMP variable: Network Packets Transmitted shows a number of packets transmitted since last synchronization as differentiation of total number of packets transmitted (pktsTx). Network Packets Received shows a number of packets received since last synchronization as differentiation of total number of packets received ( pktsRx). Network Transfer Rate shows current transfer rate as derivative of total kilobytes sent (kbTx). Network Receive Rate shows current receive rate as derivative of total kilobytes received (kbRx). Mind issues concerning too small synchronization period , as mentioned in Processing Data customizing vmwNetTable synchronization options 115 .
1046

section, when

9.20.3 VMware Reports

Reports and queries for VMware virtual machines are created automatically in VMware group.

VMware Summary

2000-2013 Tibbo Technology Inc.

1118

AggreGate Documentation

VMware Summary report shows the following information for all virtual machines available on registered devices: Host device description Virtual machine display name Current state of the virtual machine Name of guest operation system associated with the virtual machine Guest OS state. The report references a VMware Summary query .

VMware Memory Utilization

VMware Memory Utilization report shows configured memory volume, and used memory volume and percentage for all virtual machines available on registered devices. The report references a VMware Memory Utilization query.

9.20.4 VMware Information Widget

VMware Information widget displays some details about virtual machines registered at a particular VMware Server

To launch widget for a VMware Server, select an appropriate context in a System Tree and choose VMware Information menu item. The widget allows you to select one of virtual machines registered at the server and shows the following information: virtual machine ID current status of the selected virtual machine operating system running on the virtual machine ("guest OS") current state of the guest OS Resources used by the virtual machine: CPU Time usage

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

Memory usage percentage HDD Read Rate HDD Write Rate The widget can be customized in GUI Builder
827

1119

(see Widgets

312 ).

The widget, and the corresponding menu item are available if vmTable SNMP variable for the VMware Service device has at least one record.

9.21 Printer Monitoring

AggreGate Network Manager printer monitoring tools include Printer Information 1120 widget and a number of alerts 216 : Printer State 1120 , Printer Marker 1120 , Printer Cover Status 1120 and Critical Printer Event SNMP Trap 1108. These tools use SNMP protocol to retrieve data from printers and support common printer monitoring tasks, like: display printer description, model, serial number, describing its capabilities, current state and other printer details detect and get notified about problems, like paper jams, out of paper, overfull trays, etc. get (beforehand) notifications about lack of resources: toner, photoconductive drum, developer, etc. At the same time it's not hard to extend these basic capabilities by creating custom printer monitoring tools for specific printer types and models with. These tools may use SNMP polling or handle printer events (by listening to SNMP Traps or Syslog messages sent by printers). Refer to RFC 3805 for reference information on printer management and monitoring.

Configuration
Printer monitoring 1119 configuration includes environment specification (printer states, synchronization options) and a set of specific tools (Printer Information widget, and a few types of alerts) along with their settings.

PRINTER STATES

Printer state is an important concept for printer monitoring, used by Printer State alert 1120 and Printer Information widget 1120 . AggreGate Network Manager detects printer state depending on the values of three SNMP variables: Device Status, Printer Status, and Printer Detected Error State. Their values are combined into a single printer state using Printer States table available in printer's Device Properties 677 . The method of their combination can be modified for a particular printer device to reflect its specific features. The the following printer states are defined by default: Non-critical Printer States Normal Printing Off-line Standby Initial Power Up Warming Up Input Tray Low Output Tray Almost Full Marker Supply Almost Empty Input Tray Missing Input Tray Empty Output Tray Missing Output Tray Full Critical Printer States Jam Cover/Door Open Input Tray Missing Input Tray Empty Output Tray Missing Output Tray Full Marker Supply Missing Marker Supply Empty

2000-2013 Tibbo Technology Inc.

1120

AggreGate Documentation

A critical state is one in which the printer is stopped and printing can not continue until the condition that caused it is eliminated. The default printer status table is automatically created for devices providing prtGeneralTable SNMP variable. It matches to the one described in Appendix E - Overall Printer Status Table of RFC 3805.

SYNCHRONIZATION OPTIONS

hrDeviceTable, hrPrinterTable, prtGeneralTable, and prtMarkerSuppliesTable SNMP variables are

used for printer monitoring. Thereafter their synchronization options
115

can be customized to better fit user's needs.

9.21.1 Printer State Alert

Printer State alerts 216 help to monitor current printer status as described in RFC 3805. Alerts of this type can be created using Setup Monitoring Profile 1052 action, and configured to be triggered when printer's status either equals to, or differs from the selected printer state 1119 value.

9.21.2 Printer Marker Alert

Printer Marker alert 216 provide monitoring of printer marker supplies (refer to RFC 3805 and, particularly, section 2.2.6. Markers there for details). The alert is configured using Marker Supplies Type and Threshold parameters. It triggers when level of the specified marker is reduced below the threshold. The values available in Marker Supplies Type field depend on the specific printer type (see PrtMarkerSuppliesTypeTC in RFC 3805). For example, Sharp MX-2300N printer reveals five marker types: Black Toner, Waste Toner , Black Photoconductive Drum, Black Developer, and Fusing Unit. In turn, the threshold units depend on the selected marker type (see PrtMarkerSuppliesSupplyUnitTC in RFC 3805). For example, Black Toner unit for Sharp MX2300N printer is percents. AggreGate Network Manager uses prtMarkerSuppliesTable SNMP variable to monitor current marker supplies values.

9.21.3 Printer Cover Status Alert

Printer Cover Status alerts 216 allow to monitor states of covers, or access panels on the printer case or enclosure. Being configurable with Setup Monitoring Profile 1052 action, alerts of this type has the only specific parameter: Triggering Cover State. The alert will be invoked, if any of printer covers is reported to be in the selected state.

9.21.4 Printer Information Widget

Printer Information widget 312 is available for all devices providing both hrDeviceTable and hrPrinterTable values. It can be activated by choosing the corresponding context menu action for a printer device. This widget is created and configured automatically, no additional customization is necessary in most circumstances. Though, it's not hard to modify 827 the widget for reflecting advanced state of a certain printer models. The widget displays the following data: General Printer Information o Name o Description (usually printer brand/model usually) o Serial Number o Physical (MAC) Address Printer State (as described in Printer State Printer Colorants Count Marker Supplies (see also Printer Marker alert 1120 section) The values are refreshed according to the Synchronization Period values for hrDeviceTable, hrPrinterTable, and prtMarkerSuppliesTable (see Synchronization Options 115 section).
1119

clause of Printer Monitoring Configuration section)

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1121

9.22 Wireless Device Monitoring

AggreGate Network Manager can monitor diverse wireless devices via SNMP. The required MIB files are included in the distribution bundle. The basic tool designed for analyzing wireless device information is Wireless Information widget. Other AggreGate tools, such as events, widgets, or charts can be created for monitoring wireless SNMP-enabled devices that use nonstandard MIBs.

Wireless Information Widget

The Wireless Information widget is available on any SNMP-compliant wireless device providing cDot11ActiveDevicesTable SNMP variable. To start the widget, select Wireless Information item in context menu of the device in System Tree 784 . The widget presents the following essential information about the selected wireless device. 1. System Name and Description. System name assigned to the managed item and its textual description are read from sysName and sysDescr SNMP variables respectively. This data is displayed in the widget header. 2. Wireless Interfaces. A list of wireless (IEEE 802.11) interfaces is obtained from ifTable SNMP variable. Those are the ones having ifType equal to ieee80211 (71) value. Advanced information for every wireless interface is retrieved from cDot11ActiveDevicesTable. The following information is presented for each wireless interface: Field Name Description Description A textual string containing information about the interface. This string should include the name of the manufacturer, the product name and the version of the interface hardware/ software. Physical (MAC-) address of the interface. The number of wireless clients currently associated with the interface. The number of bridges currently associated with the interface. Source

ifDescr in ifTable

MAC address Clients Bridges

ifPhysAddress in ifTable cDot11ActiveWirelessClients in cDot11ActiveDevicesTable cDot11ActiveBridges in cDot11ActiveDevicesTable cDot11ActiveRepeaters in cDot11ActiveDevicesTable

Repeaters

The number of repeaters currently associated with the interface.

1. Service Set Identifiers. A list of SSIDs associated with the device is obtained from cd11IfAuxSsidTable variable and presented in a table with the following fields: Field Name SSID Broadcast Max. Stations Description SSID recognized by the device. True, if the is SSID is the Broadcast SSID. There is only one Broadcast SSID per IEEE 802.11 radio interface. The maximum number of wireless stations which may be associate with this radio interface through the SSID. If the value is '0', the maximum number is limited only by IEEE 802.11 standard or hardware/firmware limitations. The default value is '0'. Source

cd11IfAuxSsid in cd11IfAuxSsidTable cd11IfAuxSsidBroadcastSsid in cd11IfAuxSsidTable cd11IfAuxSsidMaxAssocSta in cd11IfAuxSsidTable

2. Clients. This table contains configuration information, status and statistics of all client devices, including wireless clients, repeaters, and bridges, associated with the wireless device. This information is obtained from cDot11ClientConfigInfoTable and cDot11ClientStatisticTable SNMP variables: Field Name Name State Description The wireless client name. State of the authentication and association process between the client and device: Value Description Source

cDot11ClientName in cDot11ClientConfigInfoTable cDot11ClientAssociationState in cDot11ClientConfigInfoTable

2000-2013 Tibbo Technology Inc.

1122

AggreGate Documentation

initial (1)

association request received from client

authenNotAssociate authenticated but d (2) not associated assocAndAuthentica associated and ted (3) authenticated assocNotAnuthentic associated but ated (4) not authenticated

Address Role

The static or DHCP-assigned IP address of the client. This defines the type of a wireless device. Available device types are: Value ) Description

cDot11ClientIpAddress in cDot11ClientConfigInfoTable cDot11ClientRoleClassType in cDot11ClientConfigInfoTable

clientStation (0 client station repeater (1) accessPoint (2) bridgeHost (3) bridge (4) bridgeRoot (5)
repeater access point access point bridge host (WGB) bridge root bridge

ethernetClient ( Ethernet client through WGB 6)

Device

This defines the classifications of wireless client device. The devices are classified by their Ethernet connection, serial connection, and the type of radio it uses. The device classifications are: Value Description unknown Ethernet access point

cDot11ClientDevType in cDot11ClientConfigInfoTable

unknown (1) ethernetAP (76)

ethernetBridge ( Ethernet bridge 77) pc3000Client (84 client with a 3000

) radio serial port universal client Ethernet universal client client with a 5300 radio client with a 4500 radio

serialUC (85) ethernetUC (86) pc3500Client ( 101) pc4500Client ( 102)

generic80211Cli client of an unknown ent (104) radio type and nonCisco device

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1123

pc4800Client ( 109) pc3100Client ( 110) mc (111)

client with a 4800 radio client with a 3100 radio multiple client Ethernet, universal client

ethernetClient ( Ethernet client of a WGB 112) pc4800bClient ( 117)

client with a 4800b radio

wgbNoDiversity ( WGB with one antenna 123) wgb (124)

WGB with two antennas

series350Client client with 350 series (127) radio series370Client client with 370 series (128) dot11A radio c1100SeriesAP ( 129)
Cisco 1100 series AP

c1410SeriesBrid Cisco 1410 series ge (130) bridge c1200SeriesAP ( 132) mp2xClient (133) c350SeriesAP ( 134) cb21agClient ( 135)
Cisco 1200 series AP client with MP2x IEEE 802.11g radio Cisco IOS 350 series AP Cisco CB21AG/ PI21AG IEEE 802.lla/ b/g client AIR-RM21A-x-K9 and AIR-RM22A-x-K9 radio Cisco 1130 series AP

radioKodiak (136 Cisco IEEE 802.11a

)

c1130SeriesAP (137)

c1310SeriesBrid Cisco 1310 series ge (138) bridge c7920phone (139) c1240SeriesAP ( 140)
Cisco 7920 series phone Cisco 1240 series A

Associated, sec. RSSI

The time in seconds that this client has been associated with this device. This is a device-dependent measure of the signal quality of the most recently received packet from the client. The number of bytes received from this client.

cDot11ClientUpTime in cDot11ClientStatisticTable cDot11ClientSigQuality in cDot11ClientStatisticTable cDot11ClientBytesReceived in cDot11ClientStatisticTable

Received, bytes

2000-2013 Tibbo Technology Inc.

1124

AggreGate Documentation

Sent, bytes

The number of bytes sent to this client.

cDot11ClientBytesSent in cDot11ClientStatisticTable

9.23 Java Monitoring and Management

Java monitoring and management functionality of AggreGate Network Manager helps to control and monitor: Java-based applications and services Application Servers (Tomcat, JBoss, WebLogic, WebSphere, SunOne, Jetty, Oracle Application Server, and others) Java application management allows to: Access both standard and application-specific MBeans. View, log and change MBean attributes. Execute MBean operations on-demand, on schedule, or in response to alerts. Collect, store and react to MBean event notifications. Use the full range of integrated data mining tools (alerts JMX data.
216 ,

reports

241 ,

trackers

257 ,

widgets

312 ,

etc.) for processing

JMX monitoring functionality is provided by JMX device driver

140 .

Integrated Java VM and Application Monitoring Tools

AggreGate Network Manager distribution includes dashboards widespread Java applications, and application servers:
617

that help to monitor Java Virtual Machines (JVMs),

JAVA OVERVIEW DASHBOARD

This dashboard provides generic Java VM information: VM environment properties Garbage collection statistics Class statistics Thread statistics Chart of CPU load caused by the VM To access this dashboard double-click on any Java/JMX device account.

JAVA MEMORY DASHBOARD

This dashboard provides detailed JVM memory distribution statistics: Heap and Non-Heap Memory charts Detailed information about memory pools (Code Cache, Permanent Generation, Eden Space, Survivor Space, Old Generation) To access this dashboard double-click on any Java/JMX device account.

9.24 .NET Monitoring 9.25 Configuration and Change Management

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1125

9.25.1 Configuration Management Setup

Global Settings for Configuration and Change Management Setting Up Configuration Backup and Restoration for a Device

9.25.2 Configuration Backup and Restoration

Manual Configuration Downloading Manual Configuration Uploading Configuration Types Configuration Comparison

9.25.2.1 Managing Historical Configurations

9.25.2.2 Baseline Configurations

Baseline Definition Setting/Remoiving a Baseline Configuration Group Baselining

9.25.2.3 Viewing Configuration Differences

9.25.3 Scheduling Configuration Backups 9.25.4 Automatic Backups Upon Changes 9.25.5 Compliance Management
Compliance Policies Administering Compliance Policies Configuring Policies Applying Policies Policy Violation Reporting

2000-2013 Tibbo Technology Inc.

1126

AggreGate Documentation

9.25.6 Configuration and Command Scripts

Configuration and Command Script Definition Script Types Script Syntax

9.26 IP SLA Monitoring

AggreGate Network Manager offers scalable and easy-to-use Cisco IP SLA network monitoring module that is seamlessly integrated with other network monitoring components. Cisco IOS IP Service Level Agreements (SLAs) enables customers to assure new business-critical IP applications, as well as IP services that utilize data, voice, and video, in an IP network. Cisco has augmented traditional service level monitoring and advanced the IP infrastructure to become IP application-aware by measuring both end-to-end and at the IP layer. With Cisco IOS IP SLAs, users can verify service guarantees, increase network reliability by validating network performance, proactively identify network issues, and increase Return on Investment (ROI) by easing the deployment of new IP services. Cisco IOS IP SLAs uses active monitoring to generate traffic in a continuous, reliable, and predictable manner, thus enabling the measurement of network performance and health.

IP SLA Monitoring Features

Import of existing IP SLA tests from Cisco devices Batch creation of new IP SLA tests inside Cisco devices through the central monitoring server Updates and removal of tests through the central server Support for all types of IP SLA tests Support for full set of text parameters Support for monitoring all significant test metrics, including Out-of-box IP SLA infrastructure dashboards Pre-configured IP SLA violation alerts

9.26.1 IP SLA Monitoring Concepts

Functionality of IP SLA module comprises two primary operations: Initial configuration server
1129

of IP SLA tests on the side of Cisco devices and on the side of AggreGate Network Manager

Retrieval, processing, storage and visualization 1142 of IP SLA test status and performance metrics IP SLA module allows to manage and monitor hundreds of IP SLA tests without ever manually logging to Cisco devices that are actually performing those tests. This module uses SNMP protocol to import existing tests from Cisco IOS devices, upload new tests into them, and update/delete tests. SNMP is also used to read IP SLA status and performance metrics.

9.26.2 IP SLA Test Types

IP SLA module supports the following test types: ICMP Echo . Measures round trip time between nodes on your network. ICMP Path Echo . Measure round trip time to all hops leading to a node on your network. UDP Echo. Measures round trip time between nodes on your network by sending data in User Datagram Protocol.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

TCP Connect. Measures WAN quality by testing connection times between two devices using a specific port. UDP Jitter . Measures inter-packet delay variance (jitter) by sending UDP packets.

1127

ICMP Path Jitter. Measures hop-by-hop jitter, packet loss, and delay measurement statistics in an IP network. VoIP Call . Measures your network's response time for setting up a Voice over IP (VoIP) call. RTP. Measures jitter, frame loss, Mean Opinion Score for Conversational Quality (MOS-CQ), and Mean Opinion Score for Listening Quality (MOS-LQ) using Voice Gateway's DSP. DNS. Measures the difference in time from when a DNS request is sent and when the reply is received. DHCP. Measures the response time taken to discover a DHCP server and then obtain a leased IP address from it. FTP. Measures the response time between a Cisco device and an FTP server to retrieve a file. HTTP. Measures different aspects of web page load process. Custom . Allows to specify all IP SLA test settings manually.

9.26.3 Understanding IP SLA Technology

IP SLA technology enables Cisco devices to generate and analyze traffic to nodes of your network. A Cisco device sends simulated data to another Cisco device ("IP SLA Responder") or a raw network node (such as a DNS server) and analyzes how long does the response take to be received, what does it contain, etc. The core concept of IP SLA architecture is IP SLA test. A test can be set up and scheduled for execution by programming a Cisco device from console (what is manually done by system administrators) or via SNMP protocol (what AggreGate Network Manager does). The actual test execution is performed by Cisco device on a regular basis. Test results (i.e. values of measured metrics) are exposed via SNMP protocol. Those results are collected by AggreGate Network Manager, processed, stored in the database, and visualized on demand. The Network Manager can manage and monitor thousands of tests executed by multiple Cisco devices.

IP SLA Definitions
IP SLA monitoring module uses the following definitions:

SOURCE
A device that creates and inserts IP SLA packets into the network. The source is where all IP SLA operation tests are initiated.

TARGET
The final destination of the packets created and sent by the source.

TYPE
The type of test being performed on the network.

9.26.3.1 Latency
VoIP latency is a metric of the difference in time between when one caller speaks and when the other caller hears what the first has said. Excessive network latency can cause noticeable gaps and synchronization loss in transmitted conversations, particularly when VoIP is used with other types of data, as in a videoconference. If these gaps become large enough, callers may find that they will inadvertently interrupt each other while conversing. IP SLA tests measure latency by sequentially applying four different timestamps to a single test packet, as follows: 1. Timestamp T1 is applied to a test packet as it leaves the source router. 2. Timestamp T2 is applied as the test packet arrives at the target router. 3. Timestamp T3 is applied as the test packet leaves the target router to return to the source. 4. Timestamp T4 is applied when the test packet returns to the source. IP SLA tests then provide four separate measures of latency by computing differences among the four timestamps, as follows. Latency Measure Calculation

2000-2013 Tibbo Technology Inc.

1128

AggreGate Documentation

Round Trip Time Source-to-Target Latency Target Processing Latency Target-to-Source Latency

T4 T1 T2 T1 T3 T2 T4 T3

9.26.3.2 Jitter
Jitter is a measure of the variation in network latency that results in a loss of synchronization over time. In VoIP phone calls, users experience jitter as distracting noise, clicks, and pops. To ensure acceptable quality of service, network jitter should be located, isolated, and addressed.

9.26.3.3 Packet Loss

Packet loss is a quantitative metric of information loss over a given network connection. Though packet loss is inevitable in any network environment, the goal is always to identify where packets are lost in transmission so you can act to minimize information loss and maintain high QoS for your services.

9.26.3.4 Mean Opinion Score (MOS)

MOS is an industry standard measure of call quality expressed on a scale of increasing perceived quality, from 1 to 5. MOS is computed according to a standard International Telecommunications Union (ITU) algorithm involving the codec for your VoIP network and values of latency, jitter, packet loss, and MOS advantage factor. Jitter, latency, and packet loss are variable quantities that are measured in realtime. Generally, MOS reflects call quality as shown in the following table. Call Quality Very Satisfied Satisfied Some Users Satisfied Many Users Dissatisfied Nearly All Users Dissatisfied Not Recommended MOS 4.3-5.0 4.0-4.3 3.6-4.0 3.1-3.6 2.6-3.1 1.0-2.6

9.26.3.5 Test Topology

Test topology is the structure of tests selected during batch test creation process topologies:
1130 .

There are three possible test

One-to-one. A single test will be created. It's necessary to select one source Cisco device and one destination (Cisco device or raw IP/hostname). One-to-many . Multiple tests originated from a single source will be created. It's necessary to select one source Cisco device and multiple destinations (Cisco devices or raw IPs/hostnames). Many-to-many. Multiple Cisco devices should be selected. Each of those devices will perform tests to all other devices.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1129

9.26.4 Configuring IP SLA Tests

This section explains how to manage IP SLA tests. AggreGate Network Manager represents each test as a separate context 863 that is can be managed like any other contexts (e.g. alerts 216 or reports 241 ). However, in contrast to the other objects, each test has its "hardware peer", i.e. device-side configuration. Those configurations should generally remain synchronized 1130 to each other.

Administering IP SLA Tests

Two contexts are used to administer IP SLA tests: One is the general IP SLA Tests 1160 context, which serves as a container. The other is the IP SLA Test 1160 context, which holds the information for one test.

9.26.4.1 Preparing for IP SLA Monitoring

The following steps need to be completed before creation or import of IP SLA tests from a Cisco device: A device account 113 using IP Host device driver manually or by network discovery 1055 .
150

should be created for the Cisco device. This can be done either

CISCO-RTTMON-MIB should be enabled in the SNMP assets 113 of this device account. This MIB file declares OIDs related to IP SLA test management and monitoring. This MIB is normally enabled by default. Device account should remain in Online, Synchronized state indicated by state. icon. This is a normal device account

9.26.4.2 Importing Existing Tests

Importing tests is useful when you company is already operating a number of IP SLA tests that were previously configured from console of via any other network management tool. This operation loads tests definitions, properties and schedule into AggreGate Server and creates accounts for those tests. To import existing tests from a Cisco device: 1. Make sure that device account of Cisco device that the tests will be imported from is fully ready for IP SLA operations 1129 . 2. Right-click on an IP SLA node ( ) and select Import/Update Tests .

3. Select a Cisco device account to import tests from. 4. Wait while test definitions are loaded from the device. A table containing test sources, targets, numbers and types will be shown. 5. Check tests to import and click on OK. Note that if a test with certain number already exists on the server side, it will be initially unchecked. You can check it to update its server-side properties. 6. Wait while tests are imported and test accounts are created on the server. 7. Once import process is finished, a status report will be shown. This report contains a list of imported/updated tests and test import/update errors.

9.26.4.3 Updating Tests

Test batch update procedure is useful when configuration of more than one test was changed in the Cisco device, but AggreGate Network Manager already has test accounts for those tests. This operation pulls all test settings from a device and updates server-side test account configuration. For updating a single test, use test synchronization 1130 operation.

To update server-side configuration of tests, follow the sequence described in importing existing tests 1129 article. All tests that already have server-side "peer" accounts will be initially unchecked in the test selection dialog. Check them to update their server account properties.

2000-2013 Tibbo Technology Inc.

1130

AggreGate Documentation

9.26.4.4 Creating New Tests

AggreGate SCADA/HMI can create IP SLA tests directly in a Cisco device. System administrators don't need to log in to a device from console and perform any additional manual configuration. To create new tests in a Cisco device: 1. Make sure that device account of Cisco device that the tests will be imported from is fully ready for IP SLA operations 1129 . 2. Right-click on an IP SLA node ( 3. Select type of tests 1126 to create. 4. Select test topology 1128 . 5. Select one or more source Cisco devices according to selected test topology. 6. Select one or more test targets according to selected topology. A test target can be an existing Cisco device account or an arbitrary IP address or host name. 7. Specify test properties. 8. Define schedule for the newly created tests. 9. Wait while new tests are configured on selected source devices and server-side device accounts are created. 10. Once creation process is finished, a status report will be shown. This report contains a list of created tests and test import/update errors. ) and select Create Tests.

9.26.4.5 Deleting Tests

To delete IP SLA tests: Right-click on a test node ( ) and select Delete

Confirm removal of the test account from the server Separately confirm or decline removal of the test from the Cisco device

9.26.4.6 Synchronizing Tests

Test synchronization is: The process of writing changes made to server-side test account configuration into a Cisco device, or The process of reading changes made in the Cisco device and applying them to the server-side test account To synchronize test properties between AggreGate Network Manager server and Cisco device: Right-click on a test node ( ) and select Synchronize .

Select synchronization direction (From Device or To Device). Wait until the synchronization process finishes. Once synchronization process is finished, a status report will pop up. This report contains a list of synchronized tests and synchronization errors.

9.26.4.7 IP SLA Test Properties

This section describes properties of an IP SLA test. More details about those properties can be found in Cisco IP SLA references and CISCO-RTTMON-MIB file.

Basic Properties
Property
Owner

Description
A string that identifies the entity that created this table row.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1131

Tag
Type Threshold

A string which is used by a managing application to identify the RTT target. This string is inserted into trap notifications, but has no other significance to the agent. The type of IP SLA operation to be performed. An administrative threshold limit. If the RTT operation time exceeds this limit and if the conditions specified in Threshold Type (Reactions table) or Filter (History table) are satisfied, a threshold violation event is generated. Specifies the duration between initiating each RTT operation. This object cannot be set to a value which would be a shorter duration than Timeout . When the test Type is object is Path Echo, the suggested value for this object is greater than Timeout times the maximum number of expected hops to the target. When the test Type is DHCP, the minimum allowed value for this object is 10 seconds.

Frequency

Timeout

Specifies the duration to wait for a RTT operation completion. The value of this object cannot be set to a value which would specify a duration exceeding Frequency. For connection oriented protocols, this may cause the connection to be closed by the probe. Once closed, it will be assumed that the connection reestablishment will be performed. To prevent unwanted closure of connections, be sure to set this value to a realistic connection timeout.

Protocol

Specifies the protocol to be used to perform the RTT operation. When this protocol does not support the type, a 'badValue' error will be returned. A string which specifies the address of the target. A string which specifies the IP address of the source. This object is applicable to all probes except dns, dlsw and sna.

Target Address Source Address

Advanced Properties
Property
Verify Data

Description
When set to true, the resulting data in each RTT operation is compared with the expected data. This includes checking header information (if possible) and exact packet size. Any mismatch will be recorded in the rttMonStatsCollectVerifyErrors object. Some test types may not support this option. When a type does not support this option, the agent will transition this property to false. It is the management applications responsibility to check for this transition. This property is only applicable to SNA protocols. When set to true, this entry will be shown in 'show running' command and can be saved into Non-volatile memory. This object represents the number of octets to be placed into the ARR Data portion of the request message, when using SNA protocols. For non-ARR protocols' RTT request/responses, this value represents the native payload size. The ARR Header overhead is not included in this value. For echo probes the total packet size = (IP header(20) + ICMP header(8) + 8 (internal timestamps) + request size). For echo and pathEcho default request size is 28. For udp probe, default request size is 16 and for jitter probe it is 32. For dlsw probes default request size is 0. The minimum request size for echo and pathEcho is 28 bytes, for udp it is 4 and for jitter it is 16. For udp and jitter probes the maximum request size is 1500.

Non Volatile Memory

Request Size

Response Size

This object represents the number of octets to be placed into the ARR Data portion of the response message. This value is passed to the RTT Echo Server via a field in the ARR Header. For non-ARR RTT request/response (i.e. ipIcmpecho) this value will be set by the agent to match the size of Request Size, when native payloads are supported.

2000-2013 Tibbo Technology Inc.

1132

AggreGate Documentation

The ARR Header overhead is not included in this value. This object is only supported by SNA protocols. VPN Name This field is used to specify the VPN name in which the RTT operation will be used. For regular RTT operation this field should not be configured. The agent will use this field to identify the VPN routing Table for this operation. This object specifies whether the value in specified for oneway NTP sync tolerance is absolute value or percent value.

Clock Synchronization Type Value

Echo, Path Echo Tests Properties

Property
Source Port

Description
This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns. If this object is enabled then it means that the application calculates response time for a specific path. This object is applicable to echo probe only. The type of the target FEC for the RTT 'echo' and 'pathEcho' operations based on 'mplsLspPingAppl' Protocol. A string which specifies a valid 127/8 address. This address is of the form 127.x.y.z. This address is not used to route the MPLS echo packet to the destination but is used for load balancing in cases where the IP payload's destination address is used for load balancing. This object specifies the reply mode for the LSP Echo requests. This object represents the TTL setting for MPLS echo request packets. For ping operation this represents the TTL value to be set in the echo request packet. For trace operation it represent the maximum ttl value that can be set in the echo request packets starting with TTL=1.

IP Type of Service (TOS) LSR Enable

LSP FEC Type

LSP Selector

LSP Reply Mode LSP TTL

For 'echo' based on mplsLspPingAppl the default TTL will be set to 255, and for 'pathEcho' based on mplsLspPingAppl the default will be set to 30.

Note: This object cannot be set to the value of 0. The default value of 0 signifies the default TTL values to be used for 'echo' and 'pathEcho' based on 'mplsLspPingAppl'. LSP EXP Value This object represents the EXP value that needs to be put as precedence bit in the MPLS echo request IP header. This object specifies the DSCP value to be set in the IP header of the LSP echo reply packet. The value of this object will be in range of DiffServ codepoint values between 0 to 63. Note: This object cannot be set to value of 255. This default value specifies that DSCP is not set for this row. LSP Null Label This object specifies if the explicit-null label is to be added to LSP echo requests which are sent while performing RTT operation.

LSP DSCP Reply Value

UDP Echo Test Properties

Property Description

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1133

Target Port

This object represents the target's port number. This object is applicable to udpEcho, tcpConnect and jitter probes. This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns.

Source Port

Control Message

IP Type of Service (TOS)

TCP Connect Test Properties

Property
Target Port

Description
This object represents the target's port number. This object is applicable to udpEcho, tcpConnect and jitter probes. This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns.

Source Port

Control Message

IP Type of Service (TOS)

HTTP Test Properties

Property
Source Port

Description
This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns. A code that represents the specific type of HTTP or FTP operation. This object is applicable to http and ftp probe only. A string which specifies the version number of the HTTP Server. The syntax for the version string is <major number>.<minor number> An example would be 1.0, 1.1 etc.,. This object is applicable to http probe only. A string which represents the URL to which a HTTP probe should communicate with. This object is applicable to http probe only. If this object is false then it means that HTTP request should not download cached pages. This means that the request should be forwarded to the origin server. This object is applicable to http probe only.

IP Type of Service (TOS) Operation Type

HTTP Version

URL

Cache

Proxy

This string represents the proxy server information. This object is applicable to http probe only. This string stores the content of HTTP raw request. If the request cannot fit into String1 then it should be split and put in Strings 1 through 5.

Request String 1

2000-2013 Tibbo Technology Inc.

1134

AggreGate Documentation

This string stores the content of the DHCP raw option data. The raw DHCP option data must be in HEX. If an odd number of characters are specified, a 0 will be appended to the end of the string. Only DHCP option 82 (decimal) is allowed. Here is an example of a valid string: 5208010610005A6F1234 Only Request String 1 is used for dhcp, Strings 1 through 5 are not used. This object is applicable to http and dhcp probe types only. Request String 2 This string stores the content of HTTP raw request. Request Strings 1-5 are concatenated to form the HTTP raw request used in the RTT operation. This object is applicable to http probe only. This string stores the content of HTTP raw request. Request Strings 1-5 are concatenated to form the HTTP raw request used in the RTT operation. This object is applicable to http probe only. This string stores the content of HTTP raw request. Request Strings 1-5 are concatenated to form the HTTP raw request used in the RTT operation. This object is applicable to http probe only. This string stores the content of HTTP raw request. Request Strings 1-5 are concatenated to form the HTTP raw request used in the RTT operation. This object is applicable to http probe only.

Request String 3

Request String 4

Request String 5

FTP Test Properties

Property
Source Port

Description
This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns. A code that represents the specific type of HTTP or FTP operation. This object is applicable to http and ftp probe only. A code that represents the specific type of RTT operation. This object is applicable to ftp probe only.

Control Message

IP Type of Service (TOS) Operation Type

Mode

DNS Test Properties

Property
Target Address String

Description
A string which specifies the address of the target. This string can be in IP address format or a hostname. This object is applicable to dns probe only. A string which specifies the ip address of the name-server. This object is applicable to dns probe only.

Name Server

Jitter Test Properties

Property Description

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1135

Target Port

This object represents the target's port number. This object is applicable to udpEcho, tcpConnect and jitter probes. This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns. This value represents the inter-packet delay between packets and is in milliseconds. This value is currently used for Jitter probe. This object is applicable to jitter probe only.

Source Port

Control Message

IP Type of Service (TOS) Interval

Number of Packets

This value represents the number of packets that need to be transmitted. This value is currently used for Jitter probe. This object is applicable to jitter probe only.

Codec Type

Specifies the codec type to be used with jitter probe. This is applicable only for the jitter probe. If codec-type is configured the following parameters cannot be configured. Request Size Interval Number of Packets

Codec Interval

This field represents the inter-packet delay between packets and is in milliseconds. This object is applicable only to jitter probe which uses codec type. This object represents the number of octets that needs to be placed into the Data portion of the message. This value is used only for jitter probe which uses codec type. This value represents the number of packets that need to be transmitted. This value is used only for jitter probe which uses codec type. The advantage factor is dependant on the type of access and how the service is to be used. Conventional Wire-line - 0 Mobility within Building - 5 Mobility within geographic area - 10 Access to hard-to-reach location - 20 This will be used while calculating the ICPIF values. This valid only for Jitter while calculating the ICPIF value.

Codel Payload

Codec Number of Packets ICPIF Factor

Precision

This object specifies the accuracy of statistics that needs to be calculated milliseconds - The accuracy of stats will be of milliseconds microseconds - The accuracy of stats will be in microseconds. This value can be set only for jitter operation

Probe Packet Priority

This object specifies the priority that will be assigned to probe packet. This value can be set only for jitter operation. This object specifies the total clock synchronization error on source and responder that is considered acceptable for one way measurement when NTP is used as clock synchronization mechanism. The total clock synchronization error is sum of NTP offsets on source and responder. The value specified is microseconds. This value can be set only for jitter operation with precision of microsecond. This object specifies the total clock synchronization error on source and responder that is

Total Clock Synchronization Error, microseconds

Total Clock

2000-2013 Tibbo Technology Inc.

1136

AggreGate Documentation

Synchronization Error, %

considered acceptable for oneway measurement when NTP is used as clock synchronization mechanism. The total clock synchronization error is sum of NTP offsets on source and responder. The value is expressed as the percentage of actual oneway latency that is measured. This value can be set only for jitter operation with precision of microsecond.

ICMP Jitter Test Properties

Property
Target Port

Description
This object represents the target's port number. This object is applicable to udpEcho, tcpConnect and jitter probes. This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns. This value represents the inter-packet delay between packets and is in milliseconds. This value is currently used for Jitter probe. This object is applicable to jitter probe only.

Source Port

Control Message

IP Type of Service (TOS) Interval

Number of Packets

This value represents the number of packets that need to be transmitted. This value is currently used for Jitter probe. This object is applicable to jitter probe only.

Codec Type

Specifies the codec type to be used with jitter probe. This is applicable only for the jitter probe. If codec-type is configured the following parameters cannot be configured. Request Size Interval Number of Packets

Codec Interval

This field represents the inter-packet delay between packets and is in milliseconds. This object is applicable only to jitter probe which uses codec type. This object represents the number of octets that needs to be placed into the Data portion of the message. This value is used only for jitter probe which uses codec type. This value represents the number of packets that need to be transmitted. This value is used only for jitter probe which uses codec type. The advantage factor is dependant on the type of access and how the service is to be used. Conventional Wire-line - 0 Mobility within Building - 5 Mobility within geographic area - 10 Access to hard-to-reach location - 20 This will be used while calculating the ICPIF values. This valid only for Jitter while calculating the ICPIF value.

Codel Payload

Codec Number of Packets ICPIF Factor

Precision

This object specifies the accuracy of statistics that needs to be calculated milliseconds - The accuracy of stats will be of milliseconds microseconds - The accuracy of stats will be in

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1137

microseconds. This value can be set only for jitter operation Probe Packet Priority This object specifies the priority that will be assigned to probe packet. This value can be set only for jitter operation. This object specifies the total clock synchronization error on source and responder that is considered acceptable for one way measurement when NTP is used as clock synchronization mechanism. The total clock synchronization error is sum of NTP offsets on source and responder. The value specified is microseconds. This value can be set only for jitter operation with precision of microsecond. This object specifies the total clock synchronization error on source and responder that is considered acceptable for oneway measurement when NTP is used as clock synchronization mechanism. The total clock synchronization error is sum of NTP offsets on source and responder. The value is expressed as the percentage of actual oneway latency that is measured. This value can be set only for jitter operation with precision of microsecond.

Total Clock Synchronization Error, microseconds

Total Clock Synchronization Error, %

DLSW Test Properties

Property
Control Message

Description
If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns.

IP Type of Service (TOS)

DHCP Test Properties

Property
Source Port

Description
This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This string stores the content of HTTP raw request. If the request cannot fit into String1 then it should be split and put in Strings 1 through 5. This string stores the content of the DHCP raw option data. The raw DHCP option data must be in HEX. If an odd number of characters are specified, a 0 will be appended to the end of the string. Only DHCP option 82 (decimal) is allowed. Here is an example of a valid string: 5208010610005A6F1234 Only Request String 1 is used for dhcp, Strings 1 through 5 are not used. This object is applicable to http and dhcp probe types only.

Control Message

Request String 1

VoIP Calls Test Properties

Property
Source Port

Description
This object represents the source's port number. If this object is not specified, the

2000-2013 Tibbo Technology Inc.

1138

AggreGate Documentation

application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. Control Message If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns. This string stores the called number of post dial delay. This object is applicable to voip post dial delay probe only. The number will be like the one actualy the user could dial. It has the number required by the local country dial plan, plus E.164 number. The maximum length is 24 digits. Only digit (0-9) is allowed. A code that represents the detect point of post dial delay. This object is applicable to SAA post dial delay probe only. VoIP GK Registration Delay A boolean that represents VoIP GK registration delay. This object is applicable to SAA GK registration delay probe only.

IP Type of Service (TOS) Called Number

Detect Point

RTP Test Properties

Property
Source Port

Description
This object represents the source's port number. If this object is not specified, the application will get a port allocated by the system. This object is applicable to all probes except dns, dlsw and sna. If this object is enabled, then the RTR application will send control messages to a responder, residing on the target router to respond to the data request packets being sent by the source router. This object is not applicable to echo, pathEcho, dns and http probes. This object represents the type of service octet in an IP header. This object is not applicable to dhcp and dns. A string which specifies the voice-port on the source gateway. This object is applicable to RTP probe only.

Control Message

IP Type of Service (TOS) Source Voice Port

Call Duration

Duration of RTP session. This object is applicable to RTP probe only.

9.26.4.8 IP SLA Test Schedule

This section describes schedule properties of an IP SLA test. More details about those properties can be found in Cisco IP SLA references and CISCO-RTTMON-MIB file.

This table contains advanced IP SLA test properties. In most cases it should not be edited manually.

Properties
Property
Life Time, seconds (rttMonScheduleAdm inRttLife)

Description
Defines life time of a new test. The value 2147483647 has a special meaning. When this object is set to 2147483647, the Life Time object will not decrement. And thus the life time will never end.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1139

Start time, seconds

(rttMonScheduleAdm inRttStartTime) Conceptual Row Age Out (rttMonScheduleAdm inConceptRowAgeout ) Recurrence (rttMonScheduleAdm inRttRecurring)

Defines activation time of a new test. When an agent has the capability to determine date and time, the agent should store this object as DateAndTime. This allows the agent to completely reset (restart) and still be able to start conceptual RTT rows at the intended time. If the agent cannot keep date and time and the agent resets, all entries should take on one of the special value defined below. Defines when a non-active test will be auto-deleted. When this conceptual RTT control row enters an 'active' state, this timer will be reset and suspended. When this conceptual RTT control row enters a state other than 'active', the timer will be restarted. When this value is set to zero, this entry will never be aged out. When set to true, this entry will be scheduled to run automatically for the specified duration equal to the life configured, at the same time daily. This value cannot be set to true: (a) if Life Time object has value greater or equal to 86400 seconds. (b) if sum of values of Life Time and Conceptual Row Age Out is less or equal to 86400 seconds.

9.26.4.9 IP SLA Test Reactions

This section describes reaction properties of an IP SLA test. More details about those properties can be found in Cisco IP SLA references and CISCO-RTTMON-MIB file.

This table contains advanced IP SLA test properties. In most cases it should not be edited manually.

Properties
Property
Connection Enable (rttMonReactAdminC onnectionEnable)

Description
If true, a reaction is generated when a RTT operation to a Target Address (echo type) causes the test to enter Connection Lost state. Thus connections to intermediate hops will not cause this value to change.

Timeout Enable
(rttMonReactAdminT imeoutEnable)

If true, a reaction is generated when a RTT operation causes the test to enter Timeout state. When the test Type is 'pathEcho' timeouts to intermediate hops will not cause Timeout state. This object specifies the conditions under which force the test to enter threshold violation (i. e. Warning, Critical or Failure) state: NOTE: When the test Type is 'pathEcho' this objects value and all associated object values are only valid when RTT 'echo' operations are to the rttMonEchoAdminTargetAddress object address. Thus 'pathEcho' operations to intermediate hops will not cause this object to change. never - threshold violation never occurs immediate - threshold violation occurs when an operation completion time exceeds Threshold value; conversely threshold violation is deactivated when an operation completion time falls below Threshold Falling consecutive - threshold violation occurs when an operation completion time exceeds Threshold on Threshold Count, X consecutive RTT operations; conversely, threshold violation is deactivated when an operation completion time falls under the Threshold Falling for the same number of consecutive operations xOfy - threshold violation occurs when x (as specified by Threshold Count, X ) out of the last y (as specified by Threshold Count, Y) operation completion time exceeds

Threshold Type (rttMonReactAdminT hresholdType)

2000-2013 Tibbo Technology Inc.

1140

AggreGate Documentation

Threshold; conversely, it is set to false when x, out of the last y operation completion time fall below Threshold Falling NOTE: When x > y, the probe will never generate a reaction. average - threshold violation occurs when the running average of the previous Threshold Count operation completion times exceed Threshold; conversely, it is set to false when the running average falls below the Threshold Falling If this value is changed by a management station, threshold violation is reset, but no reaction is generated if threshold violation was active. Threshold Falling (rttMonReactAdminT hresholdFalling) Threshold Count, X (rttMonReactAdminT hresholdCount) Threshold Count, Y (rttMonReactAdminT hresholdCount2) Action Type (rttMonReactAdminA ctionType) Specifies what type(s), if any, of reaction(s) to generate if an operation violates one of the watched conditions: none - no reaction is generated trapOnly - a trap is generated nmvtOnly - an SNA NMVT is generated triggerOnly - all trigger actions defined for this entry are initiated trapAndNmvt - both a trap and an SNA NMVT are generated trapAndTrigger - both a trap and all trigger actions are initiated nmvtAndTrigger - both a NMVT and all trigger actions are initiated trapNmvtAndTrigger - a NMVT, trap, and all trigger actions are initiated Error Enable (rttMonReactAdminV erifyErrorEnable) If true, a reaction is generated when an RTT operation error occurs. This object defines the 'y' value of the xOfy condition specified in Threshold Type. This object defines the 'x' value of the xOfy condition specified in Threshold Type. This object defines a threshold limit. If the RTT operation time falls below this limit and if the conditions specified in Threshold Type are satisfied, an threshold is generated.

9.26.4.10 IP SLA Test Statistics

This section describes statistics properties of an IP SLA test. More details about those properties can be found in Cisco IP SLA references and CISCO-RTTMON-MIB file.

This table contains advanced IP SLA test properties. In most cases it should not be edited manually.

Properties
Property
Number of Groups (rttMonStatisticsA dminNumHourGroups)

Description
The maximum number of groups of paths to record. Specifically this is the number of hourly groups to keep before rolling over. The value of one is not advisable because the group will close and immediately be deleted before the network management station will have the opportunity to retrieve the statistics. The value used in the statistics table (rttMonStatsCaptureTable) to uniquely identify

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1141

this group is the statistics table using index ( rttMonStatsCaptureStartTimeIndex). HTTP and Jitter probes store only two hours of data. When this object is set to the value of zero all statistics table data capturing will be shut off. Number of Paths (rttMonStatisticsA dminNumPaths) When the test Type is 'pathEcho' this is the maximum number of statistics paths to record per hourly group. This value directly represents the path to a target. For all other Types this value will be forced to one by the agent. NOTE: For 'pathEcho' a source to target path will be created to to hold all errors that occur when a specific path or connection has not be found/setup. Thus, it is advised to set this value greater than one. Since this index does not rollover, only the first Number of Paths will be kept. Number of Hops (rttMonStatisticsA dminNumHops) When the test Type is 'pathEcho' this is the maximum number of statistics hops to record per path group. This value directly represents the number of hops along a path to a target, thus we can only support 30 hops. For all other Types this value will be forced to one by the agent. Since this index does not rollover, only the first Number of Hops will be kept. This object is applicable to 'pathEcho' probes only. Number of Distribution Buckets (rttMonStatisticsA dminNumDistBuckets ) Distribution Buckets Interval (rttMonStatisticsA dminDistInterval) The maximum number of statistical distribution buckets to accumulate. Since this index does not rollover, only the first Number of Distribution Buckets will be kept. The last bucket will contain all entries from its distribution interval start point to infinity. This object is not applicable to http and jitter probes. The statistical distribution buckets interval. Distribution Bucket Example: Number of Distribution Buckets = 5 buckets Distribution Buckets Interval = 10 milliseconds | Bucket 1 | Bucket 2 | Bucket 3 | Bucket 4 | Bucket 5 | | 0-9 ms | 10-19 ms | 20-29 ms | 30-39 ms | 40-Inf ms | Odd Example: Number of Distribution Buckets = 1 buckets Distribution Buckets Interval = 10 milliseconds | Bucket 1 | | 0-Inf ms | Thus, this odd example shows that the value of Distribution Buckets Interval does not apply when Number of Distribution Buckets is one. This object is not applicable to http and jitter probes.

9.26.4.11 IP SLA Test History

This section describes history properties of an IP SLA test. More details about those properties can be found in Cisco IP SLA references and CISCO-RTTMON-MIB file.

This table contains advanced IP SLA test properties. In most cases it should not be edited manually.

Properties
Property Description

2000-2013 Tibbo Technology Inc.

1142

AggreGate Documentation

Number of History Lives (rttMonHistoryAdmi nNumLives)

The maximum number of history lives to record. A life is defined by the countdown (or transition) to zero by the rttMonCtrlOperRttLife object. A new life is created when the same conceptual RTT control row is restarted via the transition of the rttMonCtrlOperRttLife object and its subsequent countdown. The value of zero will shut off all history data collection.

Number of Buckets
(rttMonHistoryAdmi nNumBuckets)

The maximum number of history buckets to record. When the test Type is 'pathEcho' this value directly represents a path to a target. For all other test Types this value should be set to the number of operations to keep per lifetime. After Number of Buckets are filled, the and the oldest entries are deleted and the most recent Number of Buckets buckets are retained. The maximum number of history samples to record per bucket. When the test Type is 'pathEcho' this value directly represents the number of hops along a path to a target, thus we can only support 30 hops. For all other test Types this value will be forced to one by the agent.

Number of Samples (rttMonHistoryAdmi nNumSamples)

Filter (rttMonHistoryAdmi nFilter)

Defines a filter for adding RTT results to the history buffer: none - no history is recorded. all - the results of all completion times and failed completions are recorded. overThreshold - the results of completion times over Threshold are recorded. failures - the results of failed operations (only) are recorded.

9.26.4.12 IP SLA Alert Thresholds

Each IP SLA test has three server side alert thresholds: Warning Threshold Critical Thershold Failure Threshold Each of these thresholds define what Round Trip Time measurement will cause alert raised at certain level.

9.26.4.13 Understanding Polling Frequency

Each of IP SLA tests has its own schedule that includes test execution frequency. Thus, statistical information collected by the test and exposed via SNMP protocol updates with the same frequency. However, the structure of SNMP data exposed by IP SLA capable devices assumes that statuses and statistics of all tests are stored in large tables. Each table contains certain piece of status information about all tests. For example, there is an rttMonLatestHTTPOperTable table that contains detailed execution status information about all HTTP tests. The architecture of AggreGate Network Manager's SNMP device driver, in its order, assumes that SNMP tables are polled as atomic values. AggreGate Server doesn't update information about each test separately, instead it reads whole test statistics tables by using GET BULK requests to optimize performance. Thus, the custom synchronization period 116 of all Cisco device account variables containing IP SLA statistics should be equal or shorter than the frequency of any test performed by this device. Failure to follow this rule will lead to loss of some IP SLA test results. Normally, IP SLA module auto-adjusts custom synchronization periods of IP SLA test result tables during test creation 1130 or import 1129 . However, system administrators should take care of matching test frequencies to the synchronization periods if some manual changes are performed to the device-side or server-side test configuration.

9.26.5 Browsing IP SLA Status and Statistics

Current metrics and statistics of network performance collected by IP SLA tests are presented in easy-to-use dashboards, tables, graphs, and charts. The following IP SLA data processing and visualization views are provided with IP SLA module: IP SLA Groups
1143

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

IP SLA Dashboards 1143 IP SLA Alerts 1143

1143

9.26.5.1 IP SLA Test Groups

The distribution bundle includes several pre-configured IP SLA test groups by type 1126 . Each group's reflects status of all member tests. If some tests are in Undefined state, the group status is Undefined, else If some tests are in Critical state, the group status is Critical, else If some tests are in Warning state, the group status is Warning, else The group status is Normal
248

that help to track status of tests grouped

9.26.5.2 IP SLA Dashboards

AggreGate Network Manager distribution bundle includes several IP SLA dashboards
617 :

IP SLA Summary. This overview dashboard lists IP SLA test groups, tests that currently run with some problems, tests that have active threshold violation alerts, and test status summary chart. IP SLA Top 10. This overview dashboard lists top 10 tests with largest Round Trip Time, top 10 TCP connection tests, top 10 DHCP tests, top 10 echo tests, top 10 FTP tests, and top 10 HTTP tests. IP SLA Test Details. This dashboard provides detailed information about a test. This includes test information table, last RTT measurement, RTT chart, test availability graph. Most specific test types has its own additional metrics on this dashboard, for example: o HTTP tests provide detailed info about DNS resolution time, TCP connection time and page load time. o VoIP tests expose latency, jitter, packet loss and MOS charts. o Path Echo tests provide hop-by-hop RTT table.

9.26.5.3 IP SLA Alerts

IP SLA module includes a set of alerts
216 : 1142.

IP SLA Violation. Raised when Round Trip Time measurement of a test exceeds one of the thresholds Disconnected. Occurs when one of the tests reports Disconnected status. Unreachable. Occurs when one of the tests reports Unreachable status. Critical . Occurs when one of the tests reports Critical status.

9.27 VoIP Monitoring 9.28 Management Operations

AggreGate Network Manager provides a wide choice of management and control operations a user can invoke interactively or automatically, say, in response to a monitoring event. Generally speaking, control operations available for different types of managed items are countless. Depending on the type of your managed device, applications it runs and services it provides you can use a variety of control operations. These can be: HTTP requests, if you HTTP service service maps certain URLs into some control operations it can execute; SQL requests to relational database management systems; SNMP traps or other types of unsolicited notifications sent to devices, if an SNMP device is configured to execute some action upon specific event arrival, etc.

2000-2013 Tibbo Technology Inc.

1144

AggreGate Documentation

This chapter covers common control operations supported by AggreGate Network Manager: SNMP management via SNMP set operations Remote shell script execution Network management actions on-LAN.
1144 1144 1144 .

using SSH. like sending SNMP traps or Syslog messages, or remotely starting PCs via Wake-

These actions can be invoked interactively or automatically as, for example, alert's corrective action or scheduled job.

9.28.1 SNMP Management

Some types of network devices and services allow to control them via SNMP. Generally, SNMP control operations are SNMP Set operations. Refer to Controlling Devices Using SNMP 1086 section for additional details and examples.

9.28.2 Control via WMI

WMI can be used to remotely control Windows computers. Refer to WMI
1088

section for details and some examples.

9.28.3 Remote Script Execution

AggreGate Network Manager may upload scripts from AggreGate AggreGate Server to remote machines over secure SSH connections. Remote script execution is one of the most powerful and flexible remote control methods. Basically, it allows to execute virtually any kind of script or application remotely on a managed host. Refer to SSH Server Monitoring
163

section for details on SSH support in AggreGate Network Manager

9.28.4 Network Management Actions

There are several management actions Right-click root (server
789 ) 892

installed in Root context

726 .

To invoke one of these actions:

node in the System Tree

Choose Network Management sub-menu Select an action to launch. A window will appear allowing you to specify input parameters for the selected action. Press OK button to proceed with selected parameters. Network management actions available in the Network Management menu are briefly described in subsections below.

9.28.4.1 Execute Remote Script

Execute script on remote server using SSH (executeRemoteScript) actions uploads a script to a remote host via secure SSH connection and executes it there. Refer to Remote Script Execution 1144 and SSH Server Monitoring
163

sections for details.

9.28.4.2 Send SNMP Trap

Send SNMP Trap (sendSnmpTrap) action allows to transmit an SNMP trap to a remote host. Refer to Sending SNMP Traps 1087 section for details.

9.28.4.3 Send Syslog Message

Send Syslog Message (sendSyslogMessage) action allows to transmit an Syslog message to a remote host. Refer to Syslog Message Sending 1107 section for details.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1145

9.28.4.4 Wake-on-LAN
Wake-on-LAN (executeWakeOnLAN) action allows to awake a computer by a network message. Wake-on-LAN (WoL) action broadcasts a special UDP packet (called a magic packet) containing MAC address of the destination computer. In order for WoL to work, network interface of the destination computer need to stay on waiting for a magic packet addressed to it and then initiates system wake-up. To invoke action you can right-click server node in the System Tree, then select Network Management menu group and there choose Wake-on-LAN. Parameters window will appear. Alternatively you can create a scheduled job 266 for this action. The action has the following parameters: Name macAddress broadcastIP Type String String Description MAC Address Broadcast IP Details MAC address of the destination computer in the form of either XX: XX:XX:XX:XX:XX or XX-XX-XX-XX-XX-XX. Broadcast IP for your network. For example, if your network IP address is 192.168.0.x and mask is 255.255.255.0 then the broadcast IP is 192.168.0.255. UDP port to send the magic packet to. Default value is 9.

udpPort

Integer

Wake-on-LAN (UDP) Port

9.29 Alerting
This section briefly describes all alerts 216 presented in AggreGate Network Manager for monitoring activity of network devices, along with trigger conditions structured by categories. Alert Name Category: Availability 1091 High Response Time High Packet Loss Rate Device Offline Average response time exceeds the specified threshold. Packet loss rate exceeds the specified threshold. Host is disconnected from the server for a certain time (10 minutes by default). A specified service is offline Availability Availability Availability
1044

Triggering Condition

Metric

Notes

Preconfigured for all network device contexts. Preconfigured for all network device contexts. Built into AggreGate Server basic distribution package (see Device Offline Built-In Alert 217 ). To create, use Availability group in Setup Monitoring Profile 1052 action.

1044

1044

Service Offline

Availability

1044

Category: Network Network Interface Down (SNMP) 1098 Operational state of a network interface is down, but it's administratively up. Availability
1044

Use Setup Monitoring Profile 1052 action, Network Interfaces group to create. Available for SNMP-compliant devices only.

Network Interface Administrative Shutdown (SNMP) 1098

Desired state of an interface is down.

Availability

1044

Use Setup Monitoring Profile 1052 action, Network Interfaces group to create. Available for SNMP-compliant devices only.

Network Interface State Change (SNMP) 1098

Network interface has changed its operation state.

Availability

1044

Use Setup Monitoring Profile 1052 action, Network Interfaces group to create. Available for SNMP-compliant devices only.

2000-2013 Tibbo Technology Inc.

1146

AggreGate Documentation

Network Interface Utilization (SNMP) 1098

Incoming or outgoing bandwidth usage exceeds specified threshold.

Performance
1045

Use Setup Monitoring Profile 1052 action, Network Interfaces group to create; available for SNMP-compliant devices only.

Category: CPU 1092 CPU Activity (WMI) CPU activity indicator satisfies a condition consisting of a threshold and comparison operation. The available indicators are percentage of time when CPU was: idle, nonidle, in user mode, handling hardware interrupts, using maximum frequency. Performance
1045

Use Setup Monitoring Profile 1052 action, CPU group to create; available for WMI-compliant devices only.

Category: Storage 1093 Storage Space (SNMP) Percentage of used space on the specified storage volume exceeds the specified threshold. Performance
1045

The alert can be created using Setup Monitoring Profile 1052 action (Storage Volumes group); available for SNMPcompliant devices only. Use Setup Monitoring Profile 1052 action, Storage Volumes group to create; available for WMI-compliant devices only. Use Setup Monitoring Profile 1052 action, Storage Volumes group to create; available for WMI-compliant devices only.

Disk Free Space (WMI)

Percentage of free disk space satisfies a condition consisting of a threshold and comparison operation .

Performance
1045

Memory (WMI)

Memory usage indicator satisfies Performance a condition consisting of a threshold 1045 and comparison operation. The following indicators are available: Available Physical Memory (bytes), File System Cache Size (bytes), Number of Cache Faults per Second, Number of Page Faults per Second, Number of Pages Read from Disk to Resolve Hard Page Faults, Number of Pages Written to Disk to Free Physical Memory, Disk Read Operations to Free Physical Memory, Disk Write Operations to Resolve Hard Page Faults.
1094

Category: Process

High Process CPU Usage (SNMP)

CPU time used by process(es) exceed the specified threshold value.

Performance
1045

The alert can be created using Setup Monitoring Profile 1052 action (Processes group); available for SNMP-compliant devices only. The alert can be created using Setup Monitoring Profile 1052 action (Processes group); available for SNMP-compliant devices only. The alert can be created using Setup Monitoring Profile 1052 action (Processes group); available for SNMP-compliant devices only. Use Setup Monitoring Profile action, Processes group to create; available for WMIcompliant devices only. Use Setup Monitoring Profile action, Processes group to create; available for WMI1052

High Process Memory Usage (SNMP)

Memory volume used by process(es) exceed the specified threshold value.

Performance
1045

Process Instance Count (SNMP)

Number of process instances exceed the specified threshold value.

Performance
1045

Process Instance Count (WMI)

Number of a specified process instances satisfies a condition consisting of a threshold and comparison operation. Activity indicator of a specified process satisfies a condition consisting of a threshold and

Performance
1045

Process Activity (WMI)

Performance
1045

1052

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1147

comparison operation. Available indicators are: percentage of CPU time used by the process, amount of physical memory the process uses, or amount of virtual address space the process uses. Category: Applications/Services Too Many E-mail Messages (IMAP) High Messages Size (IMAP) Number of messages (obtained via IMAP) exceeds a specified threshold. Total size of messages (obtained via IMAP) exceeds a specified treshold. Number of messages (obtained via POP3) exceeds a specified threshold. Total size of messages (obtained via POP3) exceeds a specified treshold. HTTP reply code received from a web site differs from a specified one. Content obtained from a web site has changed. HTTP reply obtained from a web site contains a specified string. Size of a file on an FTP server satisfies the condition consisting of a threshold (in bytes) and a comparison operation. Total size of all files monitored via FTP satisfies the condition consisting of a threshold (in bytes) and a comparison operation. Contents of a specified file obtained from an FTP server has changed. Operability
1045

compliant devices only.

To create, use E-mail group in Setup Monitoring Profile 1052 action. To create, use E-mail group in Setup Monitoring Profile 1052 action. To create, use E-mail group in Setup Monitoring Profile 1052 action. To create, use E-mail group in Setup Monitoring Profile 1052 action. To create, use HTTP group in Setup Monitoring Profile 1052 action. To create, use HTTP group in Setup Monitoring Profile 1052 action. To create, use HTTP group in Setup Monitoring Profile 1052 action. To create, use FTP group in Setup Monitoring Profile 1052 action. To create, use FTP group in Setup Monitoring Profile 1052 action. To create, use FTP group in Setup Monitoring Profile 1052 action. To create, use FTP group in Setup Monitoring Profile 1052 action. To create, use LDAP group in Setup Monitoring Profile 1052 action. To create, use SSH group in Setup Monitoring Profile 1052 action. To create, use DNS group in Setup Monitoring Profile 1052 action. To create, use Generic TCP and UDP Services group in Setup Monitoring Profile 1052 action. To create, use Path Tracing group in Setup Monitoring Profile 1052 action. To create, use Path Tracing

Operability

1045

Too Many E-mail Messages (POP3) High Messages Size (POP3)

Operability

1045

Operability

1045

Incorrect HTTP Reply

Operability

1045

HTTP Reply Content Changed

Operability

1045

HTTP Reply Content

Operability

1045

FTP File Size

Operability

1045

FTP Total Size of Files

Operability

1045

FTP File Changed

Operability

1045

FTP File Is Too Old

File on FTP server was not modified Operability in a specified time period. LDAP request result contains a specified string. SSH script output contains a specified string. Result of a specified DNS request equals to (or differs from) a string. Result of a specified TCP or UDP request contains a string. Operability

1045

LDAP Request Result

1045

SSH Script Result

Operability

1045

DNS Request Result

Operability

1045

TCP/UDP Monitor Result

Operability

1045

Host Is Not in Route

A host (specified as IP address or host name) does not appear in the trace results. Response time from a host in the

Operability

1045

Too High Host Response Time

Operability

1045

2000-2013 Tibbo Technology Inc.

1148

AggreGate Documentation

trace results exceeds a threshold (specified in milliseconds) Change in Number of Hops Number of hops in the trace has changed. Operability
1045

group in Setup Monitoring Profile 1052 action. To create, use Path Tracing group in Setup Monitoring Profile 1052 action. To create, use Path Tracing group in Setup Monitoring Profile 1052 action.

Too Many Hops

Number of hops in the trace exceeds a specified threshold.

1114

Operability

1045

Category: VMware

Virtual Machine State 1115

Virtual machine state satisfies the condition consisting of a VM state (Powered On, Powered Off, or Suspended) and comparison operation. Virtual machine's CPU utilization percentage satisfies a condition consisting of a threshold and comparison operation.

Availability

1044

Use Setup Monitoring Profile action, VMware group to create.

1052

Available for SNMP-compliant devices only. Performance

1045

Virtual Machine CPU Load 1115

Use Setup Monitoring Profile action, VMware group to create.

1052

Available for SNMP-compliant devices only. Performance

1045

Virtual Machine Absolute Memory Utilization 1115

Virtual machine's memory utilization volume satisfies a condition consisting of a threshold and comparison operation.

Use Setup Monitoring Profile action, VMware group to create.

1052

Available for SNMP-compliant devices only. Performance

1045

Virtual Machine Relative Memory Utilization 1115

Virtual machine's memory utilization percentage satisfies a condition consisting of a threshold and comparison operation.

Use Setup Monitoring Profile action, VMware group to create.

1052

Available for SNMP-compliant devices only. Performance

1045

Virtual Machine HDD Read Rate 1115

Virtual machine disk read rate satisfies a condition specified in the alert parameters and consisting of a threshold and comparison operation. Virtual machine disk write rate satisfies a condition specified in the alert parameters and consisting of a threshold and comparison operation.

Use Setup Monitoring Profile action, VMware group to create.

1052

Available for SNMP-compliant devices only. Performance

1045

Virtual Machine HDD Write Rate 1116

Use Setup Monitoring Profile action, VMware group to create.

1052

Available for SNMP-compliant devices only.

Category: Printer

1119

Printer State (SNMP)

1120

Printer status either equals to, or differs from the selected value.

Availability

1044

Use Setup Monitoring Profile action, Printer group to create.

1052

Available for SNMP-compliant devices only. Printer Marker (SNMP)

1120

Marker supply level of a particular marker type is reduced below specified threshold.

Availability

1044

Use Setup Monitoring Profile action, Printer group to create.

1052

Available for SNMP-compliant devices only. Printer Cover (SNMP) 1120 Any printer cover has a certain state. Availability
1044

Use Setup Monitoring Profile action, Printer group to create.

1052

Available for SNMP-compliant

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1149

devices only. Category: Apache 1109 Apache Requests Overload (SNMP) 1110 Requests Per Second metric of Apache web server exceeds the specified threshold. Performance
1045

Use Setup Monitoring Profile action, Apache group to create.

1052

Available for SNMP-compliant devices only. Apache Traffic Overload (SNMP) 1110 Number of kilobytes per second transferred metric of Apache web server exceeds the specified threshold. Performance
1045

Use Setup Monitoring Profile action, Apache group to create.

1052

Available for SNMP-compliant devices only. Performance

1045

Apache Busy Workers (SNMP)

1110

Total number of busy processes metric of Apache web server exceeds the specified threshold.

Use Setup Monitoring Profile action, Apache group to create.

1052

Available for SNMP-compliant devices only. Performance

1045

Apache HTTP Error (SNMP)

1110

A new HTTP error of the specified type is generated by Apache web server.

Use Setup Monitoring Profile action, Apache group to create.

1052

Available for SNMP-compliant devices only. Category: Events 1105 Syslog 1106 A syslog message received that satisfies one of preconfigured alert conditions. An SNMP trap received that satisfies one of preconfigured alert conditions. Preconfigured by AggreGate Network Manager plugin. Preconfigured by AggreGate Network Manager plugin.
216

SNMP Trap 1107

Custom alerts can be created to simplify your specific network management tasks. Refer to the Alerts pay particular attention to the examples 217 therein.

chapter, and

9.30 Reporting
One of the most important network management activities is analysis of particular devices and the whole network operation. Collecting, selecting, processing and presenting information needed for analysis is an essential task, usually addressed by a reporting system. AggreGate reporting system allows to create, design, and run custom reports 241 . To simplify the network management job the most useful reports are bundled with AggreGate Network Manager. These reports are described below. Since every report 241 depends on a corresponding query 271 which supplies the necessary data they are considered together here. Commonly, there are sets of reports and queries, handling the same types of data, just representing it in different aspects. Such reports and queries are grouped into single report class in the table below.

Report/Query Class

Name

Description

Use for: Availability Monitoring 1091 Response Time Response Time Summary Response Time Over 100 ms Response Time Over 500 ms Average round-trip time for all devices Average round-trip time for devices with round-trip time exceeding 100 ms Average round-trip time for devices with round-trip time exceeding 500 ms

2000-2013 Tibbo Technology Inc.

1150

AggreGate Documentation

Response Time Top 10 Response Time Top 50 Packet Loss Rate Packet Loss Rate Summary Packet Loss Rate Over 10% Packet Loss Over 50% Packet Loss Top 10 Packet Loss Top 50 Availability Network Assets Down Interfaces Availability Not 100% Interfaces By Type Down Interfaces
1092

Average round-trip time for top 10 devices Average round-trip time for top 50 devices Packet loss rate for all devices Devices with packet loss rate exceeding 10% Devices with packet loss rate exceeding 50% 10 devices with the highest packet loss rate 50 devices with the highest packet loss rate Statistical Availability loss rate
1092

for the devices with non-zero packet

Count of interfaces by their type Network interfaces that are in Shutdown or Administrative Shutdown states

Use for: Performance Monitoring CPU Load

CPU Load Summary CPU Load Over 50% CPU Load Over 90% CPU Load Top 10 CPU Load Top 50

CPU(s) load

1092

for all devices

Devices with CPU Load over 50% Devices with CPU Load over 90% 10 devices with the highest CPU Load 50 devices with the highest CPU Load Physical memory usage percentage for all devices Devices with memory usage percentage exceeding 75% Devices with memory usage percentage exceeding 90% 10 devices with the highest memory usage percentage 50 devices with the highest memory usage percentage Disk space usage percentage for all devices

Memory Usage

Memory Usage Summary Memory Usage Over 75% Memory Usage Over 90% Memory Usage Top 10 Memory Usage Top 50

Disk Volumes Utilization

Disk Volumes Utilization Summary

Disk Volumes Utilization Over Devices with disk space usage percentage exceeding 75% 75% Disk Volumes Utilization Over Devices with disk space usage percentage exceeding 90% 90% Disk Volumes Utilization Top 10 Disk Volumes Utilization Top 50 Disk Volumes Free Space Disk Volumes Free Space Top 10 Disk Volumes Free Space Top 50 Use for: Traffic and Bandwidth Monitoring 1096 Interface Traffic Interface Traffic Summary Interface Traffic Top 10 Interface Traffic Top 50 Interface Bandwidth Utilization Interface Bandwidth Summary Per-interface traffic summary (including incoming and outgoing traffic) for all devices 10 interfaces with maximum total traffic (sum of incoming and outgoing traffic) 50 interfaces with maximum total traffic (sum of incoming and outgoing traffic) Per-interface bandwidth summary for all devices Disk space usage percentage for top 10 devices Disk space usage percentage for top 50 devices 10 devices with the highest disk space usage percentage 50 devices with the highest disk space usage percentage

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1151

Interface Bandwidth Utilization Over 50% Interface Bandwidth Utilization Over 90% Interface Bandwidth Utilization Top 10 Interface Bandwidth Utilization Top 50 Use for: VMware Monitoring VMware
1114

Incoming and outgoing bandwidth usage percentages for devices with either of the values exceeding 50% Incoming and outgoing bandwidth usage percentages for interfaces with either of the values exceeding 90% Incoming and outgoing bandwidth usage percentages for 10 interfaces with maximal total bandwidth usage Incoming and outgoing bandwidth usage percentages for 50 interfaces with maximal total bandwidth usage

VMware Summary 1117 VMware Memory Utilization

1118

Summary information for all virtual machines Memory utilization stats for all virtual machines

9.31 Dashboards
AggreGate Network Manager includes several pre-configured dashboards
617

for viewing network status at-a-glance:

Network Overview
Network overview dashboard shows current status of your network and knows problems.

Top 10
This dashboard allows to view Top 10 lists of devices with highest CPU load, memory/disk usage, interface traffic and utilization, response time, packet loss rate and more. It also displays processes/services that consume a lot of resources.

Network Device Overview

Device dashboard shows key indicators of network device health and performance: Generic information about the device (type, operating system, memory size, uptime, etc.) Device availability graph Response time and packet loss rate charts CPU load chart Traffic and bandwidth usage chart Device network interface statistics Services status list Active device alerts table Memory and disk space usage chart Storage volumes table

9.32 Charts
Visualization of numerical characteristics for current network and device activity is a very important aspect of network monitoring and management. AggreGate Network Manager includes the following chart widgets 384 out of the box: Chart Name Description Notes

Use for: Availability Monitoring 1091 Diagrams minimum, average and/or maximum ping response (round-trip) time values. The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action

Ping Time

2000-2013 Tibbo Technology Inc.

1152

AggreGate Documentation

1052 .

Ping Packet Loss

Diagrams average packet loss rate values.

The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart is automatically created by a corresponding auto run 625 action in Top 10 group and is available at Top 10 dashboard 1151. The chart is automatically created by a corresponding auto run 625 action in Top 10 group and is available at Top 10 dashboard 1151. The chart can be created for a particular Network Host context using Setup Monitoring Profile action 1052 (Availability group).

Response Time Top 10

Presents devices with the greatest average round trip time.

Packet Loss Rate Top 10

Presents devices with the greatest packet loss rate.

Service State

Presents service state: "On" as 1, "Off" as 0

Use for: Performance Monitoring

1092

CPU Load (SNMP)

Diagrams CPU(s) load

1092 .

The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart is automatically created by a corresponding auto run 625 action in Top 10 group and is available at Top 10 dashboard 1151. The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular WMI-enabled context using Setup Monitoring Profile action 1052. The chart can be created for a particular WMI-enabled context using Setup Monitoring Profile action 1052. The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart is automatically created by a corresponding auto run 625 action in Top 10 group and is available at Top 10 dashboard 1151. The chart is automatically created by a corresponding auto run 625 action in Top 10 group and is available at Top 10 dashboard 1151.

CPU Load Top 10 (SNMP) Presents devices with the greatest CPU utilization.

Process Count (SNMP)

Diagrams total number of processes running on a certain computer or device. Data is fetched via SNMP. Diagrams instance count of a particular process. Process instance is identified by process name, path and parameters. Data is fetched via SNMP. Diagrams total number of processes running on a certain computer or device. Data is fetched via WMI. Diagrams instance count of a particular process identified by process name. Data is fetched via WMI. Diagrams usage percentage of storage areas on the host, including physical memory, virtual memory, and disk space. Presents devices with the greatest memory usage.

Process Instance Count (SNMP) 1095

Process Count (WMI)

Process Instance Count (WMI)

Memory And Disk Space Usage (SNMP)

Memory Usage Top 10 (SNMP)

Disk Volumes Utilization Top 10 (SNMP)

Presents disk volumes and corresponding devices with the greatest utilization percentage.

Use for: Traffic and Bandwidth Monitoring 1096 Network Interface Traffic (SNMP) 1097 Shows incoming and outgoing traffic of specified network interfaces. The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart is automatically created by a corresponding auto run 625 action in

Interface Traffic Top 10 (SNMP)

Presents network interfaces and corresponding devices with the greatest total (incoming and

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1153

outgoing) traffic. Interface Bandwidth Utilization Top 10 Presents network interfaces and corresponding devices with the greatest total (incoming and outgoing) bandwidth utilization percentage. Shows traffic information collected using NetFlow.

Top 10 group and is available at Top 10 dashboard 1151. The chart is automatically created by a corresponding auto run 625 action in Top 10 group and is available at Top 10 dashboard 1151. Charts of this kind can be created using NetFlow views. Refer to NetFlow Charting Widgets section for details.

NetFlow Charts

Use for: Router and Switch Monitoring Network Interface Errors (SNMP) 1098 Shows number of error packets. Error packets are inbound packets that contain errors preventing them from being deliverable to a higher-layer protocol. Diagrams number of discarded packets: inbound packets which were chosen to be discarded even though no errors had been detected to prevent their being deliverable to a higher-layer protocol. For example, if too many packets are received, and the protocol stack does not have enough resources to properly handle the packet, it may be discarded. The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 .

Network Interface Discards (SNMP) 1098

Use for: VMware Server Monitoring 1114 Virtual Machine CPU Utilization 1117 Indicates how much of the processor's capacity is currently used by the virtual machine(s). The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 .

VM Disk Writes Number

1117

Diagrams disk utilization, measured as a number of disk write operations performed since last synchronization. Diagrams disk utilization, measured as a number of disk read operations performed since last synchronization. Diagrams disk write rate in kilobytes per second.

VM Disk Reads Number

1117

VM Disk Write Rate

1117

VM Disk Read Rate 1117

Diagrams disk read rate in kilobytes per second.

VM Memory Volume 1117

Indicates current memory utilization in kilobytes.

VM Memory Percentage
1117

Indicates current memory utilization percentage, i. The chart can be created for a e. memory used relative to amount of memory the particular SNMP-enabled context virtual machine was configured with. using Setup Monitoring Profile action 1052 . Diagrams a number of packets transmitted. The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 .

VM Network Packets Transmitted 1117

VM Network Packets Received 1117

Diagrams a number of packets received.

2000-2013 Tibbo Technology Inc.

1154

AggreGate Documentation

VM Network Transfer Rate 1117

Diagrams current transfer rate.

The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 . The chart can be created for a particular SNMP-enabled context using Setup Monitoring Profile action 1052 .

VM Network Receive Rate 1117

Diagrams current receive rate.

Use for: FTP Server Monitoring 1112 FTP File Size Diagrams size of a file monitored via FTP. The chart can be created for a particular FTP-enabled device using Setup Monitoring Profile action 1052.
384

Users can easily create custom charts for graphing specific metrics. See widget charts

for details.

9.33 Trackers
AggreGate Network Manager includes the following trackers
257

out of the box:

Service Response Time tracker that watches response time of a specified service.

9.34 Widgets
AggreGate Network Manager provides a set of pre-built widgets facilitating network monitoring tasks: Widget Name IP Host Information Description Shows several network device characteristics updating them in real time: performance gauges for CPU Load, Physical Memory Usage, Virtual Memory Usage, Packet Loss Rate percentages detailed host status basic SNMP information storage volumes sizes and usage percentages information about network interfaces on the host. In general, the widget enables "at a glance" overview of essential information about an IP host. VMware Information
1118

Displays details about virtual machines registered at a particular VMware Server. Displays information about an SNMP-compliant printer. Displays essential details about a selected wireless device. Widgets providing NetFlow statistical data visualization. Visualize geometry/topology and state of monitored IT infrastructure. Special kind of widgets devoted to charting numerical characteristics of managed network items.

Printer Information
1120

Wireless Information 1121 NetFlow charting widgets Network maps

1066

Chart widgets 1151

9.35 Event Filters

AggreGate Network Manager incorporates several built-in event filters
206 :

All Events
All Events filter shows all important system and network events. See details in the corresponding section Filters chapter.
215

of Event

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1155

Service Outages
Service Outages filter shows outage events for outage events: Server Time when the event occurred. Context presenting the network host. Level of the event. Service that generated the event. Start Time of the outage. Outage Duration in seconds. Outage Reason provided by the service.
152

generated by Network Host devices. The following columns are visible

SNMP Traps
SNMP Traps filter shows events generated when an SNMP Trap 1085 is received. The following columns are presented: Server Time of the event. Agent IP Address or Host Name referencing the source of the trap. Enterprise field of trap. Trap's Generic Trap Type ID. Uptime of device that originated the trap (in 1/100 seconds). Variable Bindings associated with the trap.

Syslog
Syslog Events filter shows events corresponding to Syslog messages server. The following columns are visible here: Event Server Time. Level of the event. Syslog message Timestamp. Message text. IP Address or Host Name provided in the Syslog message. Facility specified in the Syslog message. Severity of the Syslog message.
1105

received by AggreGate Network Manager

9.36 Models
AggreGate Network Manager incorporates several built-in models
303 :

Device Type Detector

This model includes several rule sets each of those checks whether a device belongs to a specific type. The base rule set of this model defines the sequence of calling other rule sets during device type detection algorithm. Type detection rule sets are configured to work in two "modes": in one case they use SNMP data that is already available in existing device context direct SNMP operations are performed in the other case (which happens during device discovery accounts are not yet created)
1055

when device

Device Inventory
This model includes several rule sets for detecting device operating system. The model will be extended in the future AggreGate Network Manager version to discover more information about resources offered by a network host.

2000-2013 Tibbo Technology Inc.

1156

AggreGate Documentation

Device Connectivity
This model enables event masking and suppression of alerts initiated by devices that are unavailable due to failures of some intermediate network devices. See Event Masking and Device Dependencies 1067 for more information.

Interface Traffic
This model is attached to every network device. It declares per-interface in/out bytes counter table. This table is filled using 64-bit traffic counters if such counters are provided by the device, and 32-bit counters are used otherwise. All other interface traffic analysis tools (charts, reports, etc.) are based on this model.

Memory Utilization
This model is attached to every network device. It declares generic Physical Memory, Virtual Memory and Swap Space variables and a rule set that calculates their value out of available device-specific memory metrics. All other memory analysis tools (charts, reports, alerts, etc.) are based on this model.

Disk Utilization
This model is attached to every network device. It declares generic Disk Statistics variable and a rule set that calculates disk usage out of available device-specific disk metrics. All other disk utilization analysis tools (charts, reports, alerts, etc.) are based on this model.

9.37 Helpdesk / Trouble Ticketing System Integration

AggreGate Network Manager can be integrated with virtually any Helpdesk or Trouble Ticketing System. The primary target of the integration is automatic creation of trouble tickets when AggreGate alert 216 is triggered. Basically speaking, AggreGate notifies a helpdesk system by sending a message to it using alert's notification rules 225 or automatic corrective actions 227 . If operator attention is required (e.g. for confirming the notification), it's possible to use interactive corrective actions. Here are some hints for sending alert notification to a helpdesk: Sending standard action notification email
226

to an address handled by a helpdesk system

730

Sending custom email to a helpdesk using Send E-mail Send a Syslog message Send an SNMP trap Execute a script
628

corrective action

that connects to a helpdesk server using its API and injects a new ticket

9.38 Asset Management

Asset Management plugin
950

is designed to associate some asset tracking information with your network devices.

Plugin's global configuration provides the following boolean settings: Asset Information Asset Location Asset Events Enabling any of these settings instructs AggreGate Server to create a global common table 260 and attach it to all devices in the system. Format of each table may be later edited to conform the asset tracking requirements of your company. Asset tracking information associated with a certain device may be edited using Edit Custom Properties
262

action.

Asset Management plugin just provides a convenient way to enable storage of commonly used asset tracking information. You can create new asset tracking settings and tables using custom properties 261 feature.

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1157

Structure of Default Asset Tracking Information

Asset Information custom property: Serial Number (String) Manufacturer (String) Model (String) Acquired (Date, nullable) Responsible Person (String) Contact Information (String) Notes (String / Text Area editor) Photo (Data Block / Image editor) Asset Location custom property: Country (String with selection values) City (String) Building (String) Floor (String) Room (String) Asset Events tabular custom property: Date (Date / Date-only editor) Type (String) Comment (String / Text Area editor)

9.39 Network Management Context Reference

This chapter covers contexts, variables, functions, events and actions related to network management. The Network Management plugin controls two system contexts: Network Management 1160 and Discovery 1159. They are described in the corresponding articles below. Also, it adds actions, variables, functions and events to other (already existing) contexts, as described in this article.

Administration
The Network Management plugin uses Administration
853

context as a source for SNMP and Syslog events.

EVENTS

Name syslog trap

Description Syslog Event SNMP Trap

Details This event is generated when a Syslog message is received. See Syslog Events Monitoring and Consolidation 1105 for details. This event is generated when an SNMP notification (Trap or Inform) is received. See Receiving SNMP Traps and Informs 1085 for details.

Network Host Device Contexts

The Network Management plugin exploits Network Host facilitates them with specific variables and actions.
150

devices as a primary source of monitoring data and

VARIABLES
The following variables are added to contexts representing network host devices:

Name

Description

Details

2000-2013 Tibbo Technology Inc.

1158

AggreGate Documentation

processList vmCPU

Process List Virtual Machine CPU Information Virtual Machine HDD Information Printer States

Stores statistics for processes running on the host (if this information is available via SNMP). Stores statistics for CPU usage by guest virtual machines running on the host (if VMware ESX server was found there; see VMware Server Monitoring 1114 ). Stores statistics for HDD usage by guest virtual machines running on the host (if VMware ESX server was found there; see VMware Server Monitoring 1114 ). For SNMP-enabled printers stores states configuration as described in Printer Monitoring 1119 chapter.

vmHBA

printerState s

ACTIONS

Name

Description

Details Provides a wizard to configure monitoring tools 1052 for the device. When a tool is created it adds an action that helps user to invoke itself for this device. Rediscovers
1063

setupNetworkMonitoringProf Setup Monitoring ile Profile rediscoverServices Rediscover Services

services available on the device.

Root
The Network Management plugin adds several actions facilitating different administration tasks to the Root Context
726 .

ACTIONS

Name servicesStatus sendSnmpTrap sendSyslogMessa ge executeWakeOnL AN

Description Services Status Send SNMP Trap Send Syslog Message Wake-on-LAN

Details Shows statuses for all registered services. Provides an action to send an SNMP notification as described in Sending SNMP Traps and Informs 1087 . Provides an action to send Syslog messages as described in Syslog Messages Sending 1107 section. Provides an action to send Wake-on-LAN message. See Wake-on-LAN section.
1145

Widgets
ACTIONS

Name

Description

Details

createNetFlowView Create NetFlow Widget Provides a simple way to create a NetFlow View widgets based on NetFlow views. See NetFlow Charting Widgets and NetFlow Views for details.

9.39.1 Compliance Policies 9.39.2 Compliance Policy

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

1159

9.39.3 Discovery
Discovery (discovery) is a system context that provides network device discovery operations and data.

It is not shown in the visible context tree.

Unique Actions

[?

651 ]

NETWORK DEVICE DISCOVERY

This action is used to discover network devices and create their accounts in AggreGate Network Manager. See Network Discovery 1055 for details. Action Icon: Action Name: Non-Interactive Mode 893 : Permissions: networkDeviceDiscovery Not Supported Accessible at Observer permission level [?
651 ] 932

Common Actions
Edit Context Permissions

906 ,

Monitor Related Events

909 .

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: discovery : discovery
864

863

Context Description Context Path Context Mask

863

: Discovery

: discovery : discovery
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. No access allowed. No access allowed. No access allowed. No access allowed. All operations.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

This context has no public functions.

2000-2013 Tibbo Technology Inc.

1160

AggreGate Documentation
[?
880 ]

Public Events

Common Events: info (Information)

885

, contextStatusChanged (Status Changed)

890

9.39.4 IP SLA Tests 9.39.5 IP SLA Test 9.39.6 Network Management

Network Management (netmanagement) is a system context that provides access to data related to the

overall operation of Network Management extensions. It is not shown in the visible context tree.
Network Management plugin exploits SNMP communications.
173 ,

WMI

186 ,

and Network Host

150

device drivers as a basis for network

Advanced Information
Context Information
Context Type Context Name
864

: networkManagement : netmanagement
864

863

Context Description Context Path Context Mask

863

: Network Management

: netmanagement : netmanagement
865

865

Context Permissions [?
Level None Observer Operator Manager Description

No access allowed. Network topology discovery. Same as Observer. SNMP trap sending. Syslog message sending. Wake-on-LAN requests sending. Services status browsing.

Engineer Administrat or

Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions
SEND SNMP TRAP

[?

878 ]

2000-2013 Tibbo Technology Inc.

Network Management and Monitoring

Generates SNMP notifications (traps and informs) as described in Sending SNMP Traps and Informs
1087 .

1161

Function Name: Permissions: Input Records:

Input Format
855

sendSnmpTrap Accessible at Manager permission level

932

1
: see Sending SNMP Traps and Informs 0 (for Traps) or 1 (for Informs) see Sending SNMP Traps and Informs
1087 1087

Output Records: Output Format

855 :

SEND SYSLOG MESSAGE

Sends Syslog message as described in Syslog Messages Sending
1107

section.

Function Name: Permissions: Input Records:

Input Format
855

sendSyslogMessage Accessible at Manager permission level

932

1
: see Syslog Messages Sending 0 None
1107

Output Records: Output Format

855 :

WAKE-ON-LAN
Awakes a computer by sending a special message. See Wake-on-LAN
1145 .

Function Name: Permissions: Input Records:

Input Format
855

executeWakeOnLAN Accessible at Manager permission level

932

1
: see Wake-on-LAN 0 None
1145

Output Records: Output Format

855 :

GET PROCESS INFORMATION

Utility function used by process-monitoring tools
1094

to retrieve details (parameters or path string) of specific processes.

Function Name: Permissions: Input Records:

Input Format
855

getProcessInfo Accessible at Manager permission level

932

1
: Name contextName processName requestType Type String String Integer Description Name of device context. Process name.

0 to get paths of processes with the specified name filtered

by parameters;

1 to get parameters of processes with the specified name

filtered by path. processFilter Output Records: Output Format
855 :

String

Filter string to be applied to parameters or path, depending on the specified requestType.

0...unlimited
Name value Type String Description Name of device context.

2000-2013 Tibbo Technology Inc.

1162

AggreGate Documentation

description

String

Process path or parameters string.

SERVICES STATUS
Utility function used by service-monitoring tools devices.
1108

to retrieve status information from all services registered for all

Function Name: Permissions: Input Records:

Input Format
855

servicesStatus Accessible at Manager permission level

932

0
: None

Output Records: Output Format

855 :

0...unlimited
Dynamic format with the following fields: a String field named "device" (containing context path) one Color field for every registered service denoting its status

GET NETFLOW DATA

Filters and fetches NetFlow data from storage. See Fetching NetFlow Data.

Function Name: Permissions: Input Records:

Input Format
855

getNetFlowData Accessible at Manager permission level

932

0...1
: See Fetching NetFlow Data

Output Records: Output Format

855 :

0...unlimited
See Collecting NetFlow Data
880 ]

Public Events
NETFLOW

[?

The netflow event is generated when a new flow is obtained. See Collecting NetFlow Data.

Event Name Permissions: Records: Record Format

855

netflow

Accessible at context's permission level 1 : see Collecting NetFlow Data.

932

10 SCADA/HMI
This section covers AggreGate SCADA/HMI, an industrial control and automation system based on AggreGate Platform. Go to Overview 1163 to proceed.

2000-2013 Tibbo Technology Inc.

SCADA/HMI

1163

10.1 Overview

AggreGate SCADA/HMI is an industrial control and automation system based on AggreGate core. It is tightly integrated with other AggreGate solutions for intelligent device management.

AggreGate SCADA/HMI Primary Features

Cross-platform, works under Windows, Linux, MacOS and other Java-enabled operating systems Database-centric architecture, most modern DBMS can be used for data storage, including Oracle, MS SQL, MySQL, PostgreSQL, etc. Extensive protocol support: OPC, Modbus, BACnet, SNMP, SQL, DCOM, and more Open-source Driver Development Kit (DDK) Virtual devices for testing and debugging purposes Innovative patent-pending data normalization technology Advanced HMI editor and integrated Report Editor Support for grid-based and absolute HMI layouts 50+ visual components with thousands of dynamically configurable parameters Large library of dynamic automation and process control symbols Unified development/runtime environment, on-the-fly testing Comprehensive support for alerting and charting Job scheduler for periodic task execution Integration with ERP and other systems via Web Services and open-source APIs Flexible role-based user access control model Desktop and web-based user interfaces Failover clustering and distributed architecture Internationalization, localization and branding support AggreGate SCADA/HMI documentation section is quite short, since major part of SCADA/HMI functionality is a part of AggreGate Platform. Most important SCADA modules (alerts 216 , reports 241 , widgets 312 , etc.) are described in AggreGate Server 40 section.

10.2 Architecture
AggreGate SCADA/HMI is heavily based on AggreGate Platform. Most of its functions are derived from the underlying framework. Technically, the SCADA/HMI solution is a set of device drivers
129

and plugins

950

extending AggreGate Platform.

Below is the list of AggreGate Platform manual sections that are highly relevant to the SCADA/HMI solution: System Basics
30

Alerts

216 241 266

Deployment and Administration 43 Users

108

Reports

Scheduled Jobs

2000-2013 Tibbo Technology Inc.

1164

AggreGate Documentation

Devices

113 129

Widgets Scripts

312

Device Drivers Event Filters

206

628 960

Development and Integration

No Development and Runtime Environments

Unlike traditional SCADA systems, AggreGate SCADA/HMI has unified environment used for development, debugging, testing and normal operation. There are no separate "development" and "runtime" modules to install. The core of the system is AggreGate Server. The server maintains connection with the database 80 that is used for storing system configuration, HMI templates, properties of PLCs, cached channel/tag values, and historical trend data. The server communicates with controllers, sensors and actuators via dedicated device drivers 129 . While present-day controllers tend to perform the near-real-time operations according to their own logic, AggreGate SCADA/HMI allow the server to initiate some control operations that may be guided by custom scripts 628 or actions 892 .

No Projects
AggreGate SCADA/HMI does not have projects. According to its primary concept, a single "primary" server is deployed at the production facility. During the initial phase of deployment, system engineers can connect to the server locally or remotely to build HMIs, create PLC accounts, set up data storage, etc. When the initial system configuration is finished, the same server is used in normal operation mode. No migration or switching to the production environment is required. If a certain system change is required during normal operation, it's very easy to: Make temporary copies of one or more system components (e.g. HMIs or Alerts) Modify, compare and test them, and then Activate one of the temporary copies to use is instead of original The whole AggreGate SCADA/HMI database may be backed up and restored
104

at any time.

I/O Channels and Tags

In terms of AggreGate SCADA/HMI, I/O Channels (Tags) are called Device Settings (or Device Variables). These settings may be either scalar or array/tabular. Due to the data normalization technology used by AggreGate Platform's unified data model 36 , value of every I/O channel (tag), even scalar one, is represented by a so-called Data Table 854 . This technology greatly increases flexibility of AggreGate SCADA/HMI by allowing any kind of data (both raw device data and pre-processed data) to be handled by any system component. Finally, this helps to build complex multi-level data processing chains and allow external systems to access any kind of data flowing in the system.

10.3 Getting Started

This section explains what basic steps are necessary to install AggreGate SCADA/HMI and create a simple industrial automation application. 1. First, install and interconnect AggreGate Server and AggreGate Client according to the Quick Start Guide 2. Create User Accounts
108 28

for system operators.

113

3. Create Device Accounts 1165 . 4. Create HMI widgets

312

for your PLCs, sensors, actuator, and other devices as described in Connecting to PLCs
1165

to monitor and control state of your equipment. See Creating HMIs

206

for more information.

5. Configure one or more Event Filters 6. Set up Alerts

216

to get access to important and critical events.

to be triggered by certain events or I/O channel states.

241

7. Create printable Reports

if necessary.
617

8. Add your HMIs to dashboards

and configure these dashboards to auto-open

625

upon operator

login.

2000-2013 Tibbo Technology Inc.

SCADA/HMI

1165

AggreGate SCADA/HMI documentation section is quite short, since major part of SCADA/HMI functionality is a part of AggreGate Platform. Most important SCADA modules (alerts 216 , reports 241 , widgets 312 , etc.) are described in AggreGate Server 40 section.

10.4 Connecting to PLCs

AggreGate SCADA/HMI gets access to PLCs, sensors, SQL databases and other data sources via Device Accounts 113 . Every account uses a certain Device Driver 129 to connect to a physical device, read its metadata and perform data I/O. See Adding New Devices 121 for more information on how to create new device account. Once a new device account is created, full synchronization
126

of device with server will be performed. Once it's over,

device should switch into normal operation state indicated by a green tick icon: . This state means that I/O channel data and operations provided by the device are cached by the server and may be accessed by other system facilities, such as HMIs or alerts. If I/O channel value storage should be enabled, this can be now performed by changing History Storage Time in Device Setting Synchronization Options 115 dialog.

10.5 Creating HMIs

In terms of AggreGate SCADA/HMI, a Human-Machine Interface (HMI) is a standard widget characterized by: Absolute (non-grid) layout that simplify component positioning Optional background image displaying an overall view of managed industrial process Certain dynamic Image 350 components (pipes, tanks, fans, etc) placed over the background and indicating the state of corresponding equipment Labels 323 , Text Fields setpoint values
325 , 312 .

HMI widget is usually

Sliders

347

and other components

892

322

used for monitoring certain metrics and changing

Buttons for opening other HMIs via server actions

or triggering certain equipment operations

Creating New HMI

To create new HMI widget in AggreGate Client: Right-click on Widgets node ( ) in the System Tree

Select Create HMI item from context menu Enter Name and Description of the HMI. Note, that name may include only English letters, digits and underscores. Select background image for the HMI. The size of HMI widget will be auto-calculated on basis of background image size. At this point, the GUI Builder
827

application will start. You can customize your HMI, add new components to it, etc.
626

AggreGate SCADA/HMI provides Create HMI favourite

for quick access to the Create HMI action.

10.5.1 Symbol Library

AggreGate SCADA/HMI distribution includes large automation and control symbol library. The symbols are provided in well-known SVG (Scalable Vector Graphics) format. However, all images in the library are enhanced to provide easy manipulation from within HMIs: Starting/stopping animations Moving/scaling/rotating parts of images (e.g. tank level control) Showing/hiding certain parts (e.g. switch position changing) All enhancements preserve compatibility with original SVG format.

Using Symbols

2000-2013 Tibbo Technology Inc.

1166

AggreGate Documentation

To insert a symbol into an HMI widget, use Vector Drawing 352 widget component. Once a new vector drawing is added to the widget, edit its SVG File property and load one of the symbols located in the /images subfolder of AggreGate installation. The SVG file chooser shows previews to simplify image selection:

SCADA symbols are not included in AggreGate Client distribution bundles. If you'd like to build HMIs using standalone Client distribution, copy /images folder from your AggreGate Server installation to AggreGate Client installation.

Symbol Categories
Here is a list of categories available in AggreGate SCADA/HMI symbol library: Air Conditioning Arrows ASHRAE Controls & Equipment ASHRAE Ducts ASHRAE Piping Basic Shapes Blowers Boilers Chemical Containers Controllers Controls Conveyors Ducts Electrical Finishing Flexible Tubing Flow Meters Food Laboratory Machining Material Handling Mining Mixers Motors Operator Interface Panels Pipes Plant Facilities Power Process Cooling Process Heating Pulp & Paper Pumps Segmented Pipes Sensors Tanks Valves Vehicles

2000-2013 Tibbo Technology Inc.

SCADA/HMI

1167

General Heating HVAC

Water & Wastewater Wire & Cable

10.6 Trending and Charting

The task of building charts for I/O channel values comprises two steps: Enabling channel history storage (if historical values should be displayed on the trend) Creating chart widget

Enabling Channel History Storage

By default, any I/O channel in AggreGate SCADA/HMI doesn't store its historical values. To enable history storage using AggreGate Client: Right-click on a device account ( Select Edit Device Properties ( ) in the System Tree. ). ) tab and set necessary storage time for one or more

Switch to Device Settings Synchronization Options ( properties:

Click OK to save the settings. For more information on the above settings, see Device Settings Synchronization Options
115 .

Building Chart Widget

2000-2013 Tibbo Technology Inc.

1168

AggreGate Documentation
312

In AggreGate SCADA/HMI, any chart is widget chart data model, properties, and use cases.

component. See Charts

384

section for comprehensive description of

Creating a chart for displaying historical and real-time channel values is very simple: Right-click on a Device node ( Select Configure Device ( ) in the System Tree. ). The device settings (I/O channels) dialog will open.

Right-click on the I/O channel to create chart for, and select Create Chart. Follow the instructions described in Create Chart for Variable
771

section.

Alternatively, it's possible to build chart widget from scratch by creating an empty widget, adding chart component to it, and setting up its properties.

10.7 SCADA Security

Derived from AggreGate Platform, AggreGate SCADA/HMI inherits its powerful and flexible role-based security model 931 . System operators have separate user accounts 108 . These accounts may own resources (controller accounts, HMIs, alerts 216 , reports 241 , event filters 206 ). However, the system allow to share resource view/edit permissions between different accounts. See Security and Permissions 931 for more information.

HMI Security
Some SCADA systems associate permission levels and checks with every component of HMI interfaces. AggreGate SCADA/HMI uses smarter method of controlling what a certain HMI can and cannot do: HMI components have no security-related information associated with them The working HMI inherits permissions of a user who launched it Every read or write request to the server data model uses the same effective permission level (i.e. permissions of user that started the HMI widget) Permissions are checked on the server side, therefore compromising security by "hacking" the client-side widget it not possible Fine-grained permission control is performed by giving system operators different levels of access to different system resources and devices

10.8 OPC Server Discovery

AggreGate SCADA/HMI supports OPC Server Discovery. OPC discovery is the process of scanning multiple IP network hosts, finding OPC servers running on them, and creating device accounts for these servers. To perform OPC discovery: Right-click on Devices node ( ) in the System Tree and select OPC discovery ( ).

In the Discovery Services Selection and Setup dialog, specify a list of Windows login credentials that will be used to log in to the OPC server hosts. The list is available in Service Options and Credentials field. In the next steps of discovery wizard, specify IP Ranges or individual IP Addresses to be scanned. When discovery is over, the Results dialog will be shown. It's time to select OPC servers to create device accounts for them.

10.9 Maintenance
AggreGate SCADA/HMI includes a Maintenance module (plugin) hardware assets. Purposes of this module are:
950

that simplifies tracking maintenance of your

Ensuring that regular maintenance is performed on the assets and process components to avoid unnecessary downtime Ensuring that the assets have an optimal lifetime through regular maintenance

2000-2013 Tibbo Technology Inc.

SCADA/HMI

1169

Maintenance Handling Workflow

1)First of all, it's necessary to run a Schedule Maintenance action allowing to schedule job. This action is available in Scheduled Jobs
744 266

a periodic maintenance

context (

) if maintenance module is installed.

626

Schedule Maintenance action is also accessible from Favourites

table.

2)Once the Schedule Maintenance action is started, it prompts to enter parameters of a Maintenance Act to be performed, and particularly: a) Maintenance Act Name (that will match the name of maintenance job context
744 )

b)Maintenance Act Description (will match the description of maintenance job context) c) Maintenance Subject, i.e. what device or component should be serviced d)Maintenance Regulation terms 3)When a maintenance job creation is finished, it can be found in Scheduled Jobs => Scheduled Job Groups => Maintenance. It's necessary to run Configure ( ) action for this job and specify maintenance schedule. There are two types of schedules available: simple 270 (fixed-period) schedule and advanced 270 schedule. 4)Every time the maintenance job is executed, it triggers the Maintenance alert

that is stored in the database to indicate that the maintenance act should be completed. If there are some pending (unacknowledged) maintenance acts, this alert will switch to active state (indicated by icon).
216

Finally, if there are more than 5 unacknowledged maintenance acts, or at least one of them was not acknowledged for longed than one day, the maintenance alert will be escalated thresholds are configurable 232 .
237

(what is indicated by

icon). Escalation

5)Once the maintenance if physically completed, system operator should acknowledge

228 this alert instance and optionally enter some comments about maintenance progress/result. There are two ways to acknowledge a maintenance alert:

a) Run Manage Pending Instances

action from an alert context ( ), right-click on an alert instance and select Acknowledge from context menu, and enter acknowledgement text.
656

b)Activate Maintenance Acts event filter

791

(which is also a part of Maintenance module) in the historical section of Event Log . This filter shows all maintenance acts, but highlights unacknowledged acts in carrot-red color. To acknowledge any act, right-click on it and select Acknowledge from context menu, than enter acknowledgement text.
206 241

6)Finally, to see the history of past maintenance acts, use Maintenance Summary report

10.10 Demo HMIs

AggreGate SCADA/HMI distribution includes several demo HMI widgets. Some of them are quite simple, illustrating basic concepts of HMI creation (components 322 , properties 586 , bindings 604 , etc.). Other demos are much more complex -these demos are, indeed, normal HMIs that can be used to control a whole industrial process. The only difference is that these demos are not connected to any real hardware. However, AggreGate's device data normalization layer make switching such an HMI to a real hardware extemely easy. In most cases it's just necessary to correct several bindings within an HMI itself. All demo widgets are located in Widgets => Widget Groups => Demo Widgets. Here is the list of demos: Components Demo. Provides an overview of available widget components Bindings Demo. Illustrates how different parts of widget bindings tasks. Charts Demo . Contains several tabs that show available chart
384 604 322

and their properties.

can be used to solve diverse HMI animation

types and settings. component.

SVG Demo . Explains the functionality of dynamic vector drawing Scripts Demo. Outlines the usage of widget scripts
610 .

352

Filter Plant Demo . A full-scale demo HMI emulating a filter plant 1170 .

2000-2013 Tibbo Technology Inc.

1170

AggreGate Documentation
1171 .

Bottling Line Demo. A full-scale demo HMI emulating a bottling line Bottles Conveyor Demo. A subwidget demo. Should not be used separately.
382

used to implement and animate a conveyor belt within the Bottling Line

10.10.1 Filter Plant Demo

AggreGate SCADA/HMI includes Filter Plant demo HMI. This is a pretty complex HMI that can be examined, modified, launched and used for learning purposes:

Description of Filter Plant Demo

Filter Plant demo widget emulates functioning of a simple filter plant equipped by two levels of pumps, clarified, wet wells, etc. However, this demo does not depend to any real or even virtual 182 devices. The complex logic of filter plant, operation of all its components, is emulated by widget bindings 604 to illustrate their power and flexibility. The filter plant demo includes more than fifty bindings that simulate water flow, pump control, different measurements and control actions. All these bindings may be easily analyzed or corrected in GUI Builder 827 .

Floating Panel Usage

Filter plant demo illustrates another important concept of HMI widgets: usage of floating panels with grid layout 318 to build "control forms" for different pieces of equipment. These panels may be easily moved within main window that has absolute layout. However, each panel has grid layout that is much more suitable for building forms and data input interfaces. These floating panels simplify management of more than 200 filter plant HMI components by providing visual and logical grouping for them. Layout of each panel may be edited separately. - Using floating panels with grid layout to group controls

2000-2013 Tibbo Technology Inc.

SCADA/HMI

1171

10.10.2 Bottling Line

11 Time and Attendance

This section covers AggreGate Time and Attendance, a multi-user employee attendance tracking system based on AggreGate Platform. Go to Overview 1171 to proceed.

11.1 Overview

AggreGate Time and Attendance is a multi-user employee attendance tracking system based on AggreGate core. It is tightly integrated with AggreGate Access Control and other AggreGate solutions for smart building management.

Primary Features of AggreGate Time and Attendance

Process attendance events from different types of Time Recorders Advanced alerting and event processing/logging Built-in reports (attendance, punctuality, timecard, daily activity, who it in/out, and more) Scheduled report emailing Support for week and regular shifts Customizable rules for lunch/break time and overtime processing Support for large organizations with complex multi-level employee hierarchies Employee/cardholder import procedure with comprehensive mappings The industrys leading data processing capabilities for large networks of disparate time recording devices Enterprise scalability and role-based access control Integrated GUI Builder and Report Editor Integration with third party systems (payroll, access control, etc.) via open protocols Easy deployment and maintenance

11.2 Connecting Time Recorders

One of the great things about AggreGate Time and Attendance is that it's very open, letting you work with numerous types of time recorders: RFID Magnetic card Barcode Biometric Keypad

2000-2013 Tibbo Technology Inc.

1172
PC clock

AggreGate Documentation

PDA clock Web clock Native AggreGate devices: Some devices, such as GigaTMS's TR610 time recorder, are "made for AggreGate". Such devices have AggreGate settings as part of their own configuration menu, making connection very easy. Network-enabled time recorders: If you have a network-connected time recorder (or a network of several such devices) which you wish to connect to AggreGate, you may only need to create an AggreGate device driver 129 for them. This would be a software component of AggreGate, which would let you work with these devices natively. Of course, you could also write (or purchase) several different drivers to connect disparate time recorders from different makers and thus unify them into one complete system. Connecting readers directly: If you wish to have users sign in or out using a simple data acquisition device, such a magnetic stripe or a barcode reader, you could connect it using an AggreGate Agent 848 . This is a small hardware device running a dedicated Tibbo BASIC application which can "talk" to AggreGate. It does all of the heavy lifting for the simple end node: Registers it on AggreGate Server, transfers the data acquired, etc.

How to Connect a Time Recorder

The system works like this: AggreGate should be listening for incoming connections. A new device tries to connect, claiming it is owned by user a Time Recorder. AggreGate checks to see if the user account exists. Finding this user account, AggreGate creates a node (also called "device account") for the new device under the user. The user may now work with the device, get its status, change its settings, etc. So, to recap: Connections are always initiated from the device to AggreGate Server. This means that to configure your device, you're going to have to know some things about your AggreGate Server: Its IP address, What port it's listening on for new connections, Make sure it actually is configured to listen. What username the device should be listed under (must be a user which already exists on your AggreGate Server). For the IP address: You're going to have to figure out what's the IP address of your AggreGate Server yourself. You probably know how to do this ( ipconfig under Windows, ifconfig under Linux, and it can get trickier if your incoming connection is originated from outside of the local LAN). This is more of a matter of network configuration than strictly AggreGate settings. The bottom line is that you need to know what IP address your time recorder has to try to connect to, in order to get to your AggreGate Server. The other details are listed under Drivers/Plugins Configuration > AggreGate Agent. Go to this node in your system tree and double-click it (or right-click and select Edit Driver/Plugin Properties. You will get the following dialog:
108

"admin" (for example). It also tells AggreGate that it is

First, note the Port number to listen for Agents - this is 6480 by default, but your may be different. Be sure to note what it is. Then, make sure Automatically register device accounts for new Agents is checked, so that new devices would be allowed to register with the system. In the future, once you've registered all of your devices, you could disable this setting so no new devices can be registered without you (the system admin) knowing about it.

2000-2013 Tibbo Technology Inc.

Time and Attendance

1173

Another detail you'll need to include in your time recorder configuration is the user account under which the device should register. In other words, AggreGate needs the device to tell it which user "owns" it. If you have a small installation, you can leave this as admin, the default AggreGate administrator 109 . Now that you know these details, it's time to feed them into your time recorder (or Agent configuration). We're afraid we can't give you precise guidance here -- it depends on your own device. Now is the time to go to the manual for your device and figure out how to do this. Once that's done, your device should try to connect to AggreGate Server with the correct parameters (and succeed!).

What Success Looks Like

After your device registers, log in to AggreGate AggreGate Client with the username you've registered it under. Meaning, if the device told AggreGate Server that its owner is admin, you should log in as admin to see it. Next click Devices in the system tree. You should see something like this:

The highlighted node is your terminal (yours will of course have a different name; perhaps a cooler one). The checkmark next to it indicates that it is connected and in sync. Technically, it indicates the device account for your device.

WHAT THE ICON MEANS

The icon next to your time recorder indicates sync status. In the image shown above, it means "Synchronized from Device to Server". In simple terms, it means that all cards swiped (or scanned) so far have been transferred to AggreGate Server, and that any reports you generate will reflect up-to-the-minute information. There are several other sync statuses, all described under Devices
113 .

11.3 Setting Up Organization Structure

AggreGate is highly scalable. It is meant to be usable by a 10-men company and by a 30,000 strong enterprise. Thus, we have two main methods of adding employees, or cardholders in AggreGate parlance:

Flat Organization
This format is suitable for smaller organizations. If you're going to use AggreGate Time & Attendance with a 30-men company, you're probably not going to divide it up by divisions and departments. You might just want to list who you have, in the simplest way possible. This is what the Cardholders node of the System Tree is for. A "flat" organization would look something like this:

Hierarchical Organization
This option works for larger organizations. It lets you map your organization in three levels of hierarchy, so it scales up to huge enterprises.

2000-2013 Tibbo Technology Inc.

1174

AggreGate Documentation

Organization ( ): This is the highest level. It would be your whole corporation. Note that you can actually have more than one organization, so you could use this for each physical location (each campus of a multi-national enterprise, for example). Division ( ): This is the next level down. It could be something like "R&D" or "Sales". ): This is the lowest level. "Phone sales" would be a department within "Sales".

Department (

You don't have to drill all the way down. For example, you could keep things in the division level for your organization. Alternatively, if you want to keep terminology consistent with your current organizational chart and you divide by "departments" without any "divisions", you can create a single organization containing a single division, and put all of your departments within this division. The main point is that the hierarchy is fixed - a department can only be created under a division.

Adding Organizations, Divisions and Departments

To add a new organization, division or department, simply double-click the corresponding node. For example, doubleclicking Organizations would let you add a new organization (you only need to specify a name and a description for it). Once you have created this organization, you can double-click its node to add a division under it. The same goes for departments.

GROUPS
You can create groups of divisions, departments, and cardholders for use in reports and in executing various actions en masse. Groups 248 are described in their own topic.

COMMON ACTIONS
Creating, configuring and deleting contexts (context 863 is the common name for AggreGate objects such as organizations, divisions, or departments) are called common actions. There are a number of other actions you can perform on almost any context in AggreGate. These include copying the context, editing its access permissions, monitoring related events, etc. and are covered under common actions 902 . They are not generally needed for simple use of the system, so you don't have to go read up about them right now. Just know that they're there.

11.4 Managing Cardholders

To create a new cardholder, do one of the following: Double-click the root Cardholders node OR Double-click the Cardholders node within a specific department, division or organization to create the cardholder within that location. You can still drag it to a different location later. The dialog for adding a new cardholder (or editing an existing one) looks like this:

2000-2013 Tibbo Technology Inc.

Time and Attendance

1175

The details are all pretty self-explanatory (first name, last name, contact numbers, etc.). There are only a couple of notes to make here: The Name is the cardholder context name in the system. It's not necessarily the person's actual name (that's what First name and Last name are for). Thus, it needs to confirm to AggreGate's context naming conventions 863 . This sounds complicated, but it generally just means it can't have spaces in it and has to be unique within that level (you can't have two Joe contexts within the same department. One would have to be Joe1). There's one key detail you cannot feed into this dialog: The actual card number by which the cardholder signs into the system! So after adding each cardholder, you're going to have to edit its properties and add this number. You can also import 1176 cardholders from any other system which can output CSV files.

Editing Cardholders
When you double-click a cardholder (or right-click it and select Configure Cardholder) you get the following dialog:

Note the extra tabs here. When adding the cardholder, you could only access the first tab (cardholder properties). Now you get four more tabs - Cards/Badges, Photo, Voice Tag and Custom Shift. Cards/Badges: This is where you enter the cardholder's actual card information. As the name implies, each cardholder can have more than one badge associated with it. More on this under Managing Cards/Badges 1179. Photo: The cardholder's image, for use in various reports. Voice tag: This is a sound file which contains a sample of the person's voice for security purposes. Custom Shift: This lets you specify if the person works in some specific schedule (shift) different than that of the department he's in. More on this under Managing Shifts 1179 .

Moving a Cardholder or Creating One Based on an Existing Cardholder

When you drag a cardholder's node and drop it onto any other location in the organizational tree, a copy of that node is created. You can then edit it to change only a few details (such as name, badges, etc) and thus have a new cardholder based on an old one. Alternatively, you can also delete the original node and thus effectively move that cardholder onto the new location. You can also replicate
909

a cardholder (or any other context) or perform any of the Common Actions

902

on it.

Selecting Multiple Cardholders

2000-2013 Tibbo Technology Inc.

1176

AggreGate Documentation

You can select multiple cardholders (using Shift+click for contiguous selection and Ctrl+click for selecting multiple cardholders in different locations in the tree). If you then right-click your selection, you will be able to edit them all together (or delete them all, etc).

Custom Cardholder Properties

Possibly, your organization may require some cardholder properties which are not present in AggreGate by default. For example, vehicle licensing plate number, or assigned parking spot, or even a complete data table containing gear assigned to this person (if the person works in the field and checks into the system remotely). Fortunately, you can add custom properties to all cardholders. You can read all about it in the Adding Custom Properties 1258 tutorial.

11.4.1 Importing Cardholders

You may be migrating to AggreGate Time and Attendance from an existing time & attendance system. If your legacy system is capable of exporting cardholder/employee records in CSV, AggreGate could save you some time by letting you import them in bulk rather than manually create them one by one. We will be following this topic using a hands-on example. Here's a sample CSV file exported from an actual third-party time & attendance solution. You can copy it into employees.csv and follow along.

EmployeeID,LastName,FirstName,Title,TitleOfCourtesy,BirthDate,HireDate,Address,City, Region,PostalCode,Country,HomePhone,Extension,Photo,Notes,ReportsTo 1,Davolio,Nancy,Sales Representative,Ms.,12/08/48,05/01/92,507 - 20th Ave. E.\r\nApt. 2A,Seattle,WA,98122,USA,(206) 555-9857,5467,Object Type17,Education includes a BA in psychology from Colorado State University in 1970. She also completed "The Art of the Cold Call." Nancy is a member of Toastmasters International.,2 2,Fuller,Andrew,"Vice President, Sales",Dr.,02/19/52,08/14/92,908 W. Capital Way, Tacoma,WA,98401,USA,(206) 555-9482,3457,Object Type17,"Andrew received his BTS commercial in 1974 and a Ph.D. in international marketing from the University of Dallas in 1981. He is fluent in French and Italian and reads German. He joined the company as a sales representative, was promoted to sales manager in January 1992 and to vice president of sales in March 1993. Andrew is a member of the Sales Management Roundtable, the Seattle Chamber of Commerce, and the Pacific Rim Importers Association.", 3,Leverling,Janet,Sales Representative,Ms.,08/30/63,04/01/92,722 Moss Bay Blvd., Kirkland,WA,98033,USA,(206) 555-3412,3355,Object Type17,Janet has a BS degree in chemistry from Boston College (1984). She has also completed a certificate program in food retailing management. Janet was hired as a sales associate in 1991 and promoted to sales representative in February 1992.,2 4,Peacock,Margaret,Sales Representative,Mrs.,09/19/37,05/03/93,4110 Old Redmond Rd., Redmond,WA,98052,USA,(206) 555-8122,5176,Object Type17,Margaret holds a BA in English literature from Concordia College (1958) and an MA from the American Institute of Culinary Arts (1966). She was assigned to the London office temporarily from July through November 1992.,2 5,Buchanan,Steven,Sales Manager,Mr.,03/04/55,10/17/93,14 Garrett Hill,London,,SW1 8JR, UK,(71) 555-4848,3453,Object Type17,"Steven Buchanan graduated from St. Andrews University, Scotland, with a BSC degree in 1976. Upon joining the company as a sales representative in 1992, he spent 6 months in an orientation program at the Seattle office and then returned to his permanent post in London. He was promoted to sales manager in March 1993. Mr. Buchanan has completed the courses \"Successful Telemarketing\" and \"International Sales Management.\" He is fluent in French.",2 6,Suyama,Michael,Sales Representative,Mr.,07/02/63,10/17/93,Coventry House\r\nMiner Rd.,London,,EC2 7JR,UK,(71) 555-7773,428,Object Type17,"Michael is a graduate of Sussex University (MA, economics, 1983) and the University of California at Los Angeles (MBA, marketing, 1986). He has also taken the courses \"Multi-Cultural Selling\" and \"Time Management for the Sales Professional.\" He is fluent in Japanese and can read and write French, Portuguese, and Spanish.",5 7,King,Robert,Sales Representative,Mr.,05/29/60,01/02/94,Edgeham Hollow\r\nWinchester Way,London,,RG1 9SP,UK,(71) 555-5598,465,Object Type17,"Robert King served in the Peace Corps and traveled extensively before completing his degree in English at the University of Michigan in 1992, the year he joined the company. After completing a course entitled \"Selling in Europe,\" he was transferred to the London office in March 1993.",5

2000-2013 Tibbo Technology Inc.

Time and Attendance

1177

8,Callahan,Laura,Inside Sales Coordinator,Ms.,01/09/58,03/05/94,4726 - 11th Ave. N.E., Seattle,WA,98105,USA,(206) 555-1189,2344,Object Type17,Laura received a BA in psychology from the University of Washington. She has also completed a course in business French. She reads and writes French.,2 9,Dodsworth,Anne,Sales Representative,Ms.,01/27/66,11/15/94,7 Houndstooth Rd.,London,, WG2 7LT,UK,(71) 555-4444,452,Object Type17,Anne has a BA degree in English from St. Lawrence College. She is fluent in French and German.,5

Right-click the root Cardholders node (or any Cardholders node in your hierarchy, if you're using divisons, departments, etc.). Click Import. In the Select Import Data File dialog, click Choose and browse to your file. We will be using employees.csv. Click OK. Next you will see the CSV Import Options dialog. This dialog has several options which merit description: 1. Field delimiter: This is the character separating each field from the next one. The default is a semicolon (;) but in our file it's a comma (,). So if you're following along, change it. 2. Use Text Qualifier: A text qualifier is used around longer strings within the record "like this". It is usually quote marks. This option is unchecked by default, but we need it for our file. So check it. 3. Text Qualifier: This is the actual character used as the qualifier. Here we can keep the default, our file also uses quote marks. 4. Comment Character: This is for comments within the file. Things AggreGate will ignore when importing. Our file doesn't have any, but we can keep it. 5. Escape Mode: What if you want to include your text qualifier (say, double quotes) within the CSV? There are two common approaches to handle this. Some software uses a backslash as an escape char, so it looks like this: \" . Other software just repeats the qualifier twice, like this: "" . This option lets you toggle between these two modes. For our file, we need to change the default. Select Use a backslash character... 6. Header Record: Sometimes the first record is used to specify field names or descriptions. Sometimes it is just another record, and sometimes it even contains garbage and has to be ignored altogether. This setting lets you toggle between these four modes. For our file, select Field Descriptions. See CSV Import/Export Options
1325

appendix for details.

Now click OK. If you've done everything correctly, you should get a dialog like this:

Note how nicely it splits up the fields. It also specifies the field name in the header row. Our next step is to take these fields and map them onto AggreGate's field names. Click OK.

2000-2013 Tibbo Technology Inc.

1178

AggreGate Documentation

The mappings dialog lists each field in an AggreGate Cardholder record. Open the Source/Expression listbox next to each field and select the corresponding field name in your CSV. For example, First Name stays First Name (meaning, our CSV contains a field by that exact name too), while Cardholder Name would correspond to Employee ID. If you can't find a corresponding field, leave it at None. Having mapped the fields to your satisfaction, click OK. AggreGate will now create a new context for each cardholder. Voila!

11.4.2 Attendance Exceptions

Every cardholder, its parent department, division, or organization may have a custom work shift 1179 assigned to it. However, even when a certain cardholder has a "generic" working shift shared between many, it's important to keep track of his personal attendance events, such as: Vacations Sick days Days off Out-of-order workdays And other Such personal events are called attendance exceptions. Every cardholder has a personal Attendance Exceptions table allowing system operators to view and modify information about his exceptional attendance events.

Attendance Exception Properties

Most fields of the Attendance fields: Exceptions table match ones from the Shift Properties
1179 .

There are two additional

Category (sick, day off, vacation, workday, or other) Comment

Processing Attendance Exceptions

Attendance exceptions have higher priority than shifts. This means that if a cardholder has a personal exception for a certain day, this exception's properties are used to track his attendance for this day.

2000-2013 Tibbo Technology Inc.

Time and Attendance

Exception's category and comment are shown in many attendance reports.

1179

11.5 Managing Cards/Badges

In AggreGate, each cardholder may have more than one card or badge. A badge can be active or inactive. If a person loses their badge (or if you transition into a different card system) you can just add a new badge for that person, and make the old badge inactive. More than one badge can be active for a person. This means you can have multiple ways to punch in or out, all producing different output, and they would be mapped correctly by the system.

Creating Cards
Right-click the cardholder you wish to add the card for, and select Configure click the cardholder. Click the Cards/Badges tab. Click the Add row ( ) button, and fill in the various fields: cardholder. You can also just double-

Card/Badge ID: Should correspond to whatever your device passes to AggreGate Server. Can be between 1-100 chars in length, cannot contain spaces. Status: Active , Suspended, Lost, Stolen, or Destroyed. Any status differing from Active deactivates the card. Activation Date: This is the date from which the card should be active. For a card which should be active, this should be sometime in the past. Deactivation Date: This is the date on which the card ceases to be active. For a card which should be active, this should be sometime in the future (or "not set").

Removing Cards
Technically, you can can delete a row containing card info by clicking the Remove selected row ( ) button. This is generally not a good idea, as it would make all entries logged under that card disappear from any future attendance reports. That is way it's much better to deactivate the card (uncheck the Active checkbox). When you merely deactivate a card (and not delete/remove it), the system still knows it used to belong to that cardholder in the past, and thus takes it into account in all related reports.

MORE ON ACTIVATION/DEACTIVATION LOGIC

This is a bit tricky: If a card is marked as Active, the system checks to see if it is within its activation date range. If it is both Active and within date range, the system would regard it as active. If a card is not marked as Active, the system does not regard it as active and doesn't even check to see its date range. If a card is Active but the Activation Date is in the future, or the Deactivation Date is in the past, it would be regarded is inactive.

11.6 Managing Shifts

AggreGate Time and Attendance is meant to be used within two primary organization types, and has a shift arrangement suitable for each:

Office-Style Organizations - Week Shift

By "office-style" is meant your typical 9-to-5 organization, where the bulk of your workforce arrives together and leaves together. You can still have exceptions (night guards, night-shift sysadmins, etc.) but these would their own shift. Such an organization would employ at least one week shift. This shift type lets you view an entire working week and set up a week-based schedule (Monday, Tuesday, etc). We'll use a typical example to set up a Week Shift. We will include sub-headings for people who like to skim the manual -- you can read it straight through or skip to the part you like.

SHIFT PROPERTIES
Double-click the Shifts node to open the Shift Properties dialog for adding a new shift.

2000-2013 Tibbo Technology Inc.

1180

AggreGate Documentation

Enter the following details: Name: Name of the shift. Regular context naming
863

conventions apply -- no spaces allowed. Enter "NormalWeek"

Description: The description which would appear in the System Tree, etc. Enter "Normal Work Week". Type: This is where you select either a Week Shift or a Regular Shift. For this example, select Week Shift. Shift type cannot be changed after shift creation.

Overtime After End: Can employees stay longer and accrue overtime? Overtime Before Begin: Can employees punch in earlier and accrue overtime? Overtime Day Off: Can employees still show up during an official "day off" and accrue overtime for it? Overtime During Lunch: Can employees take a shorter lunch, or skip it altogether, and accrue overtime for it? Configure these as per your organizational policy, and click OK.

SCHEDULE
Now double-click the shift you created (Normal Work Week) to configure the schedule for it. Click the Schedule tab:

As you can see, each day gets a row with the following fields: Is Workday: Should the employee arrive at the office on this day? Report Time: When should they be punching in? Knock Off Time: When is the time to leave? Lunch: Type of lunch, one of the following: None - no dedicated lunch time is assumed, any work interruptions during the day will be processed as breaks. Fixed - in this case fixed Lunch Begin Hour and Lunch End Hour should be set. The system employs a special algorithm to find a single work interruption those time and duration closely matches to lunch time/duration. This work interruption is treated as lunch time, and all other work interruptions during the day are processes as breaks. Flexible - in this case Lunch Duration should be set. The first minutes of work interruptions are registered as lunch time, all work interruption time that exceeds Lunch Duration is considered as break time. See Calculating Breaks 1186 for lunch/break time processing details.

Lunch Begin Hour, Lunch Finish Hour: Margins of lunch time, used when Lunch field is set to Fixed. Lunch Duration: The maximum length of lunch time, used when Lunch field is set to Flexible. Maximum Overtime Extent (minutes): How much overtime can an employee accrue on a single one of these days? Minimum Overtime Extent (minutes): How long should an employee stay after the knock-off time for it to be considered overtime? For example, if this is 15 minutes and the employee leaves at 18:10, these ten minutes will not be counted at all! They are not overtime, but they are after the knock-off time too, so they will simply be discarded

2000-2013 Tibbo Technology Inc.

Time and Attendance

and the employee will not get any compensation for them at all. This is a crucial point to understand, because misconfiguring this setting may lead to a violation of applicable labor laws. Both of the overtime extent durations also apply to overtime before the workday begins, in case this is allowed (see Overtime Before Begin above).

1181

EXCEPTIONS
The Exceptions tab lets you configure holidays:

Start Date: When does the holiday begin? End Date: When does it end? All other fields are as above. If Is Workday is not checked for the holiday and Overtime Day Off is not checked under Shift Properties tab, employees arriving during the holiday would get no pay at all -- as if the office is closed and they are there on their own time. Make sure to check Overtime Day Off if employees on this shift are needed during the days set as exceptions.

Factory-Style Organizations - Regular Shift

Regular shifts are build as cycles of days, not as a specific workweek. For example, you can have a 3-day cycle: Two days are working days, and the third day is off. Let's configure a regular shift:

SHIFT PROPERTIES
Double-click the Shifts node and follow the same instructions given for shift properties course: Under Type be sure to select Regular Shift.
1179

above. One difference, of

SCHEDULE
Now double-click the shift you created to configure the schedule for it. Click the Schedule tab:

This is where the difference between the Week and the Regular shift becomes very clear. Whereas the Week shift gave us a pre-filled table with seven days, here we get a blank table. All properties are exactly the same as above (see Managing Shifts 1180 above), but the shift is a cycle of days. You can have a three-day cycle, a two-week cycle, etc.

2000-2013 Tibbo Technology Inc.

1182

AggreGate Documentation

EXCEPTIONS
Exceptions are configured just like for a Weekly shift above
1181 .

START DATE
When you create a Regular Shift, AggreGate configures another parameter for it which is different than a weekly shift: The Start Date. This is needed for AggreGate to later tell what day of the regular shift an employee worked on due to the cyclic nature of the regular shift. For example, if you have a regular shift which defines a three-day cycle, and an employee worked five days, day number five would correspond to day 2 of the regular shift. To figure this out, AggreGate needs to know the start date for the regular shift. You can see this setting and change it (not recommended) by re-accessing the regular shift properties once it has been created (not during the initial creation process itself).

Assigning Shifts
FOR ORGANIZATIONS
Double-click an organization within the tree, click the Shift tab and select the shift you wish to apply to that organization and all contexts it contains.

CUSTOM SHIFTS FOR DIVISIONS, DEPARTMENTS AND CARDHOLDERS

Even if you assign a shift to an entire organizations, you can still assign different shifts to divisions, departments or cardholders within that organization. Double-click a division, a department, or a cardholder. Click the Custom Shift tab and set the Custom Shift field to the shift you wish to assign for that context.

Default Shift
There is an auto-created week shift called Default Shift. It can be edited, but its removal is not allowed. It defines a "classic" Monday-to-Friday 8-hours working week.

2000-2013 Tibbo Technology Inc.

Time and Attendance

1183

11.7 Managing Raw Attendance Events

Raw attendance events are events Time Recorder Timestamp Card ID Type
880

coming in from time recorders. Each event has three fields:

This is the time, as reported from the time recording device. It may be different than the server time (due to time zone differences, etc.) This should be linkd to a specific cardholder in the system. Can be In or Out.

AggreGate adds information to each event: Server Timestamp Cardholder What was the local time at the server when this event was received. What cardholder is associated with this card.

All of this information can be viewed using the Event Log:

To View Time Recorder Events in the Event Log

If you're not sure what the event log is, you can read the Event Log assumes you have some familiarity with the log itself:
791

topic covering it in detail. The explanation below

Click the Filter listbox (top left in the screenshot above) and select Time Recorder Events - (your username) The Filter Parameters dialog appears:

Filter by Card ID: If you're looking for the events related to one specific badge or card. Note that this is a card ID not a cardholder name. Card ID: The ID you wish to filter by (if any) Filter by Event Type: Toggle this to filter by IN or OUT events. Event Type: Select IN or OUT to specify what you wish to filter by. Click OK to filter according to the parameters you selected. Not choosing any parameters would match the widest set of events. Note that you will get only events from time recorders owned by you.

Deleting and Acknowledging Events

When right-clicking an event in the event log, you get a context menu. You can: Show event data: Get more information about the event, such as card ID, etc. Acknowledge event: Enter acknowledgement (operator text) concerning this event. View acknowledgements: If there are any. Delete Event: This would completely erase the event, thus making it nonexistent for all reports as well. Related Actions: Several other operations you could do with the context which generated the event, such as reboot it.

2000-2013 Tibbo Technology Inc.

1184

AggreGate Documentation

Yes -- you may be able reboot the actual time and attendance terminal using the event context menu. It's not meant for that, but it's nice to know you have the option.

11.8 Attendance Data Processing

This topic is more of a "system internals" topic. It describes how the system figures things out, algorithmically. This is useful for troubleshooting and getting an insight for how it works -- not necessarily for day-to-day use. The main job is this section is describing the rules of processing cardholder's attendance data for building reports. It includes: - Finding cardholder's that have active cards/badges for the specified date range - Finding which shift is active for every cardholder - Finding a shift entry to be used for attendance data processing - Finding cardholder's attendance events and fixing missing events - Finally, calculating work time, lunch/break time, and overtime

How AggreGate Decides if a Card is Active

When processing card data, AggreGate needs to figure out whether to treat a certain card/badge as active or not. First, some terminology: Start date below means the start date for a given query. If you're trying to produce an attendance report for the period between 1/Jan/2009 and 1/Feb/2009, then 1/Jan/2009 would be the start date (and 1/Feb/2009 is called end date below). Now, how the system figures out what cards/badges to include in this query: 1. It gets the card/badges variable of a certain cardholder context (which contains a data table with all registered cards/ badges) 2. It now collects all records from the card/badges table for which enabled is true 3. It gets the activation date property of each record, and throws out this record if the end date is earlier than the activation date (meaning, the query is for a period of time in which the card was not yet active) 4. Next, AggreGate reads the deactivation date property for the badge. This can be null. If it's not, and is also earlier than the start date, the system throws out this record (because this would mean that the card/badge has already been deactivated by the start date). 5. Any record which made it this far with all checks valid is an active card for this cardholder for the purposes of this report.

Finding The Active Shift

AggreGate now finds the active shift for the given cardholder. It does this by checking the Custom Shift 1182 setting of the cardholder. If this is undefined, it moves up the organizational hierarchy, checking for a custom shift for the department or division. If none of these are defined, AggreGate takes the shift defined for the whole organization. Further processing is based on the time limits and overtime policies defined for this shift.

Finding Relevant Attendance Events and Normalizing Event Sequence

At this point of the process, we have a complete list of cards/badges we need information for, and a range of dates ( Start date and End date above). 1. AggreGate now searches the database for all events between the start and the end date with the card/badge IDs specified. 2. It now sorts all of the events according to their timestamp, earliest to latest. 3. For each cardholder on a given workday, it checks to see if the first event is IN. If the first IN event is missing, meaning, the first event is OUT, the system adds an IN event according to the following logic: - If the OUT event is from before the shift started: AggreGate adds an IN event with a timestamp just before that OUT event. - If the OUT event is from after the shift started: AggreGate adds an IN event at the beginning of the shift e. Report Time).
1179

(i.

2000-2013 Tibbo Technology Inc.

Time and Attendance

1185

4. AggreGate now checks the last event for the cardholder for that day, to verify that it is an OUT event. If the last event for that workday is IN (meaning, the OUT is missing), AggreGate adds an OUT event according to the following logic: - If the IN event is from before the shift ended: AggreGate adds an OUT event at the time the shift ends (i.e. Knock Off Time). - If the IN event is from after the shift ended: AggreGate adds an OUT event with a timestamp just after that IN event. 5. AggreGate now verifies the resulting event set, to ensure that there are no two IN or two OUT events one after the other. Note: The rules in points 3 and 4 are valid for any two IN or OUT events in sequence. Meaning: If AggreGate finds two contiguous IN events, it applies rule 4; if it finds two contiguous OUT events, it applies rule 3.

Finding Day Rules for a Given Event Pair

AggreGate now has a normalized event pair it has to process. Each pair of IN/OUT events marks a period of time which the cardholder spend at work. This period may fall within the bounds of a scheduled shift, or outside such a shift. It also knows what shift the employee is assigned to. So it now has to figure out what are the rules for the specific day in which the event pair occurred.

FOR A WEEKLY SHIFT

For a weekly shift, the algorithm is very simple. 1. What date did the events occur on? 2. Is that date defined as an exception? If so, take its rules. If not, move on and figure out... 3. What day of the week was it? 4. Bang -- that's it. We now know what are the overtime rules and expected schedule for that date (because the weekly shift defines a rule for every day of the week).

FOR A REGULAR SHIFT

Regular shifts are cyclic in nature, and so determining what day of the cycle an event pair falls on is a bit trickier. Let's use an example for this. 1. Let's say we have a three-day regular shift, with a start date
1182

of 21 July 2009.

2. The event pair we're working with occurred on 17 October 2009. 3. Is that date defined as an exception? If so, take its rules. If not, move on. 4. AggreGate calculates the difference between the start date and the event date. It is 88 days. 5. AggreGate now divides the difference in days (88) by the number of days in the shift (3) and calculates the remainder. In this case, it is 1. 6. AggreGate now takes the remainder and adds it to 1 because the row number for first day of the shift is 1 and not 0 (so if the remainder is 0, for example, the correct day is day 1 of the shift). In our case, the result would be 2. Therefore, the rules for the second day of the three-day cycle apply.

Calculating Time Worked and Any Overtime

1. If the time is within schedule bounds for that day of the shift, it is counted as normal working time. This is the simplest option. 2. When the time is outside of the schedule for the day, AggreGate employs a complex algorithm to decide whether to count it as overtime, regular time, or discard it. There are several possible use cases here: - The worker spent some time working before the shift started. - The worker spent some time working during the time allotted for their lunch break. - The worker kept on working after the shift ended. - The worker came in on a day which is their day off. 3. Each of these use cases has a corresponding option in Shift how long the overtime is.
1179

properties. If this option is enabled, AggreGate checks

4. AggreGate now calculates how long the entire duration of overtime is, and checks if it is greater than the Minimum Overtime Extent setting. If it is lesser than Minimum Overtime Extent, it will be set to 0.

2000-2013 Tibbo Technology Inc.

1186

AggreGate Documentation

5. The system now calculates the sum of all of the scheduled time with the overtime, and compares the result with the allotted duration of the shift. Any time above the allotted time for the shift is now counted as overtime -- again, only time which brings the total working time over the total length of the shift. So arriving 30 minutes late and staying 30 minutes late to make up for it does not qualify one for overtime.

A CONCRETE EXAMPLE
Let's say Joe Employee is supposed to work from 9:00 till 17:00. Joe comes in late one Monday, say, at 9:05. He keeps on working until 17:25 to make up for the lost time. In this case, Joe doesn't get any overtime (because the total length of his workday is still 8 hours). But you can have a problematic scenario, too: Let's say you set Minimum Overtime Extent to something like 30 minutes (not a good idea). In this case, if Joe comes in at 9:25 and stays till 17:25, the system will not count those 25 minutes because they are less than the Minimum Overtime Extent! It would seem as though Joe simply lost 25 minutes of work and could not care less (and he would not be paid for the 25 minutes he stayed -- not even normal rates). So make sure not to set Minimum Overtime Extent to more than 5 minutes or so (or Maximum Overtime Extent to a very short period).

Calculating Breaks
To calculate break time, AggreGate compiles all OUT-IN event sequences within the bounds of a given shift. It adds those periods up into a total of all breaks taken. Some reports display the time taken for the Lunch Break specifically (because the time when the employee should take the break is configurable in Shift 1179 properties). To figure out what pair of OUT-IN events within the shift denote the lunch break, AggreGate considers value of Lunch setting of employee's shift 1179 :

NONE
All pairs of OUT-IN events are considered as breaks.

FIXED
1. If there is an OUT event between the Lunch Begin Hour and the Lunch End Hour , AggreGate would take this as the beginning of the lunch break (and the IN event following it, as the end of the lunch break). 2. If there is no such event, AggreGate would take the last OUT event which precedes the lunch hour. If an employee decides to skip their lunch hour and take a lunch break later (starting after the lunch hour is already over), AggreGate would count this as a break, but it would not show up as a "lunch break" in the reports.

FLEXIBLE
Assuming the value of Lunch Duration is N minutes, the first N minutes of work interruptions during the day will be considered as lunch time, and all the rest is deemed break time.

Lunch and Break Time Processing

Lunch hour times are counted together with total break times. Meaning, the total break time for a given day would always include the time spend at lunch break. If you do not set Overtime During Lunch in your shift properties, employees will not be able to work during lunch. They might stay at their workstations and work, but the system would not count it as worktime. So if Joe Employee decides to work from 13:00-14:00 (his regular lunch time) and then take his own break from 14:30-15:30, the system would deduct two hours from his workday: The lunch time (because he was not allowed to work overtime during that period of time) and the break he actually did take. So make sure you configure this correctly!

11.9 Time and Attendance Reports

Producing Reports
You can produce a report for a single cardholder or for a group of cardholders. For a single cardholder: Right-click the cardholder and select which report to produce. For a group: Right-click the group (organization, division, department) and select which report to produce. The resulting report includes information for all cardholders within this context, as can be seen below. The columns for the reports are self explanatory, especially after you read the Attendance Data Processing
1184

topic.

2000-2013 Tibbo Technology Inc.

Time and Attendance

1187

Attendance Report
This report shows, on a daily basis, when each employee can into work, when they left, and how long they actually worked (excluding breaks).

Daily Activity Report

This report is more detailed, and includes the shift to which each employee is assigned, his entry time, length of their lunch break, leaving time, etc. The Comments field is auto-generated.

Daily Utilization Report

This report lets you compare scheduled work time vs. actual work time and spot any differences (such as Luke Skywalker not even showing up at the office, below, or Darth Vader working overtime).

2000-2013 Tibbo Technology Inc.

1188

AggreGate Documentation

Time Recorder Events Report

This report is used mainly for debugging. Since AggreGate employs internal logic 1184 to compensate for any missing events (meaning, instances where employees did not clock in or out), this report lets you isolate exactly the events received from the terminal, without any logic added by AggreGate.

Timecard Report
This report is grouped by cardholder (as opposed to by date, like Daily Activity report). It contains the same information, but lets you more easily look at each single employee rather than a single day.

2000-2013 Tibbo Technology Inc.

Time and Attendance

1189

Who Is In/Who Is Out

These reports let you see which employees are currently in the office/factory, and which are out.

11.9.1 Report Comments

Certain reports (such as Daily Activity) contain a Comments field. This field contains preset messages designed to help administrators note certain circumstances. Here's a table of all messages and their related circumstances: Missing In Event Missing Out Event Late In Early In Late Out Early Out Short Lunch Long Lunch Absent One of more IN events have been added by AggreGate internal logic because they haven't been received from the Time and Attendance Terminal. One of more OUT events have been added by AggreGate internal logic because they haven't been received from the Time and Attendance Terminal. First IN event for cardholder is later than shift start time by 15 minutes or more. First IN event for cardholder is earlier than shift start time by 15 minutes or more. Last OUT event for cardholder is later than shift end time by 15 minutes or more. Last OUT event for cardholder is earlier than shift end time by 15 minutes or more. Lunch break was shorter than time allocated for it by 15 minutes or more. Lunch break was longer than time allocated for it by 15 minutes or more. No event found for that cardholder during that day.

11.10 Context Reference

This section covers contexts, variables, functions, events, and actions related to time and attendance.

11.10.1 Attendance
This context is a system context that provides access to different data related to the overall operation of Time and Attendance extensions. It is not shown in the visible context tree.

Advanced Information

2000-2013 Tibbo Technology Inc.

1190

AggreGate Documentation

Context Information
Context Type Context Name
864

: attendance : attendance
864

863

Context Description Context Path Context Mask

863

: Attendance

: attendance : attendance
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. All operations. Same as Observer. Same as Observer. Same as Observer. Same as Observer.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions Public Events

[?

878 ]

This context has no public functions. [?

880 ]

Common Events: info (Information)

885

ATTENDANCE
The attendance event is generated upon any In or Out event produced by a Time Recorder device connected to AggreGate Server. Is provides a generic attendance data format, while different types of time recorders provide attendance events in different format. This event is hardware-independent. Any time recorder or time clock driver should convert attendance data received from hardware into attendance events. These events are processed by AggreGate Time and Attendance to build different reports. At the same time, these raw events may be accessed by third-party reporting, payroll and other software via AggreGate Server API 961 or Web Services 976 . It's also possible to collect all attendance events in a separate database table using database custom event writer Third-party systems may access this table directly to get attendance data for processing.
72

Event Name Permissions:

Expiration Period:

attendance

Accessible at context's permission level 10 years 1

855

932

Records: Record Format Field Name

timesta

: Notes

Field Type

Date

Timestamp of event registration by the time recorder (differs from server timestamp, e.g.

2000-2013 Tibbo Technology Inc.

Time and Attendance

1191

mp cardId cardhold er device type String String

time when event was received by the server) Card ID. Owner of card (path of cardholder context).

String String

Context path of time recorder context this event came from. Event type: 'in ' or 'out'

11.10.2 Cardholders
This context 863 is a container, holding cardholder contexts 1193 at some level of organization hierarchy or all cardholder contexts outside of the organization hierarchy.

Unique Actions

[?

651 ] 243

Cardholders context has several show report

actions for browsing reports on all child cardholders:

Attendance 1187 Daily Activity Report 1187

Daily Utilization Report Time Recorder Events Timecard 1188 Who Is In
1189 1187

1188

Who Is Out 1189

CREATE CARDHOLDER (Default Action

893

This action is used for creating a new cardholder. It allows user to specify basic properties of the new cardholder and configure it immediately after creation.
Action Type: Permissions: Create
905 932

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: cardholders

863

: cardholders
864 :

Context Description

Cardholders

Context Path 863 : cardholders, organizations.ORGANIZATION_NAME.cardholders, organizations.ORGANIZATION_NAME. divisions.DIVISION_NAME.cardholders, organizations.ORGANIZATION_NAME.divisions.DIVISION_NAME.departments. DEPARTMENT_NAME.cardholders

2000-2013 Tibbo Technology Inc.

1192

AggreGate Documentation

Context Mask 865 : cardholders, organizations.*.cardholders for cardholders in all organizations, organizations.*. divisions.*.cardholders for cardholders in all divisions in all organizations, organizations.*.divisions.*. departments.*.cardholders for cardholders in all departments in all divisions in all organizations

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

865

No access allowed. Basic event monitoring. Same as Observer. Cardholder creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

SHIFT

[?

869 ]

This variable is defined only for the "root" cardholders node that contains cardholders not belonging to any organization.

Variable Name: Records: Permissions: Record Format

Field Name
855

shift

1 Readable at Observer permission level :

Field Type String Notes
932

, writable at Manager permission level

shift

Shift

1182

for all children cardholders.

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates a new cardholder.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
1194

variable in Cardholder

1193

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

2000-2013 Tibbo Technology Inc.

Time and Attendance

1193

11.10.3 Cardholder
This context
863

lets you access and manage a single cardholder 1174 .

[?
651 ] 243

Unique Actions

Cardholder context has several show report

actions for viewing reports on this cardholder:

Attendance 1187 Daily Activity Report 1187

Daily Utilization Report Time Recorder Events Timecard 1188 Who Is In
1189 1187

1188

Who Is Out 1189

CONFIGURE (Default Action

893 )

This action is used to edit properties of cardholder.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: cardholder : provided by user

864 :

863

Context Description

provided by user

Context Path 863 : cardholders.CARDHOLDER_NAME for cardholders that belong cardholders context 1191 in root context, organizations.ORGANIZATION_NAME.cardholders.CARDHOLDER_NAME for cardholders that belong cardholders context in certain organization context, organizations.ORGANIZATION_NAME.divisions. DIVISION_NAME.cardholders.CARDHOLDER_NAME for cardholders that belong cardholders context in certain division context, organizations.ORGANIZATION_NAME.divisions.DIVISION_NAME.departments. DEPARTMENT_NAME.cardholders.CARDHOLDER_NAME for cardholders that belong cardholders context in certain department context Context Mask 865 : cardholders.* for all cardholders that belong cardholders context 1191 in root context, organizations.*.cardholders.* for all cardholders that belong cardholders context in all organization contexts, organizations.*.divisions.*.cardholders.* for all cardholders that belong cardholders context in all division contexts, organizations.*.divisions.*.departments.*.cardholders.* for all cardholders that belong cardholders context in all department contexts

Context Permissions [?
Level Description

865

2000-2013 Tibbo Technology Inc.

1194

AggreGate Documentation

None Observer

No access allowed. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Cardholder configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

CARDHOLDER PROPERTIES

See description of the variable and its fields here 1174 . Variable Name: Records: Permissions: Record Format
Field Name name
855

childInfo

1 Readable at Observer permission level :

Notes Cardholder Name. Name of this cardholder context, required to refer to this cardholder from other parts of the system. It should satisfy the context naming conventions 863 . Length: 1-50 characters. First Name Last Name Gender Position Country Region/State/Province/Area ZIP/Postal Code City Address 1 Address 2 E-mail Address Work Phone Home Phone Mobile Phone
932

, writable at Manager permission level

Field Type String

firstname lastname gender position country region zip city address1 address2 email workPhone homePhone mobilePhone

String String Integer String Integer Boolean String String String String String String String String

2000-2013 Tibbo Technology Inc.

Time and Attendance

1195

notes birthDate disabled emergency

String Date Boolean String

Notes Birth Date Disabled Emergency Contact Information

CARDS/BADGES

See description of the variable and its fields here 1179 . Variable Name: Records: Permissions: Record Format
Field Name
855

cards

0...unlimited Readable at Observer permission level :

Field Type String Integer Date Date Notes
932

, writable at Manager permission level

id status activationDate deactivationDat e

Card/Badge ID Status Activation Date Deactivation Date

PHOTO

Variable Name: Records: Permissions: Record Format

Field Name
855

photo

1 Readable at Observer permission level :

Field Type Data Block Notes
932

, writable at Manager permission level

photo

Uses image editor.

VOICE TAG

Variable Name: Records: Permissions: Record Format

Field Name
855

voice

1 Readable at Observer permission level :

Field Type Data Block Notes
932

, writable at Manager permission level

voice

Uses sound editor.

2000-2013 Tibbo Technology Inc.

1196

AggreGate Documentation

CUSTOM SHIFT

See description of the variable and its fields here 1182 . Variable Name: Records: Permissions: Record Format
Field Name
855

customShift

1 Readable at Observer permission level :

Field Type String Notes
932

, writable at Manager permission level

customShift

Cardholder's custom shift

1182 .

ATTENDANCE EXCEPTIONS

See description of the variable and its fields here 1178 . Variable Name: Records: Permissions: Record Format
Field Name
855

attendance

1 Readable at Observer permission level :

Field Type Date Date Boolean Date Date Boolean Date Date Long Long Integer String [?
878 ] 932

, writable at Manager permission level

Notes

startDate endDate isWorkday reportingTime knockOffTime hasLunch lunchBeginHour lunchEndHour maximumOT minimumOT category comment

Date-only editor is used. Date-only editor is used.

Time-only editor is used. Time-only editor is used.

Time-only editor is used. Time-only editor is used.

Public Functions

This context has no public functions.

Public Events

[?

880 ]

2000-2013 Tibbo Technology Inc.

Time and Attendance

1197

Common Events: info (Information)

885

11.10.4 Departments
This context
863

is a container, holding all department contexts 1198 in the corresponding division.

[?
651 ]

Unique Actions

CREATE DEPARTMENT (Default Action

893

This action is used for creating a new department 1173 . It allows user to specify basic properties of the new department and configure it immediately after creation.
Action Type: Permissions: Create
905 932

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: departments

863

: departments
864 :

Context Description Context Path Context Mask

863

Departments

: organizations.ORGANIZATION_NAME.divisions.DIVISION_NAME.departments : organizations.*.divisions.*.departments
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Department creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

2000-2013 Tibbo Technology Inc.

1198

AggreGate Documentation

CREATE
Creates new department.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
1199

variable in Department

1198

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

11.10.5 Department
This context
863

lets you access and manage a single department 1173 .

[?
651 ] 243

Unique Actions
department: Attendance 1187

Department context has several show report

actions for viewing reports on cardholders

1193

that belong to this

Daily Activity Report 1187

Daily Utilization Report Time Recorder Events Timecard 1188 Who Is In
1189 1187

1188

Who Is Out 1189

CONFIGURE (Default Action

893 )

This action is used to edit properties of department.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information

2000-2013 Tibbo Technology Inc.

Time and Attendance

Context Type Context Name
864

1199

: department : provided by user

864 :

863

Context Description Context Path Context Mask

863

provided by user

: organizations.ORGANIZATION_NAME.divisions.DIVISION_NAME.departments.DEPARTMENT_NAME : organizations.*.divisions.*.departments.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Department configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

DEPARTMENT PROPERTIES

Variable Name: Records: Permissions: Record Format

Field Name name
855

childInfo

1 Readable at Observer permission level :

Notes Department Name. Name of this department context, required to refer to this department from other parts of the system. It should satisfy the context naming conventions 863 . Length: 1-50 characters. Department Description. Length: 1-100 characters.
932

, writable at Manager permission level

Field Type String

description

String

CUSTOM SHIFT

Variable Name: Records: Permissions: Record Format

Field Name
855

customShift

1 Readable at Observer permission level :

Field Type String Notes
932

, writable at Manager permission level

customShift

Department's custom shift

1182

Public Functions

[?

878 ]

2000-2013 Tibbo Technology Inc.

1200

AggreGate Documentation

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

11.10.6 Divisions
This context
863

is a container, holding all division contexts 1201 in the corresponding organization.

[?
651 ]

Unique Actions

CREATE DIVISION (Default Action

893

This action is used for creating new division 1173 . It allows user to specify basic properties of the new division and configure it immediately after creation.
Action Type: Permissions: Create
905 932

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: divisions

863

: divisions
864 :

Context Description Context Path Context Mask

863

Divisions

: organizations.ORGANIZATION_NAME.divisions : organizations.*.divisions
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Division creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

2000-2013 Tibbo Technology Inc.

Time and Attendance

1201

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new division.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
1202

variable in Division

1201

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

11.10.7 Division
This context
863

lets you access and manage a single division 1173 .

[?
651 ] 243

Unique Actions
division: Attendance 1187

Division context has several show report

actions for viewing reports on cardholders

1193

that belong to this

Daily Activity Report 1187

Daily Utilization Report Time Recorder Events Timecard 1188 Who Is In
1189 1187

1188

Who Is Out 1189

CONFIGURE (Default Action

893 )

This action is used to edit properties of division.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

2000-2013 Tibbo Technology Inc.

1202

AggreGate Documentation

Advanced Information
Context Information
Context Type Context Name
864

: division : provided by user

864 :

863

Context Description Context Path Context Mask

863

provided by user

: organizations.ORGANIZATION_NAME.divisions.DIVISION_NAME : organizations.*.divisions.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Division configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

DIVISION PROPERTIES

Variable Name: Records: Permissions: Record Format

Field Name name
855

childInfo

1 Readable at Observer permission level :

Notes Division Name. Name of this division context, required to refer to this division from other parts of the system. It should satisfy the context naming conventions 863 . Length: 1-50 characters. Division Description. Length: 1-100 characters.
932

, writable at Manager permission level

Field Type String

description

String

CUSTOM SHIFT

Variable Name: Records: Permissions: Record Format

855

customShift

1 Readable at Observer permission level :

932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

Time and Attendance

1203

Field Name

Field Type String

Notes

customShift

Division's custom shift

1182

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

11.10.8 Organizations
This context
863

is a container, holding all organization contexts 1204 in the system.

[?
651 ]

Unique Actions

243 actions that show report containing only records with cardholders 1193 that belong to any its child organization. Such as:

Organizations context has several show report

Attendance 1187 Daily Activity Report 1187

Daily Utilization Report Time Recorder Events Timecard 1188 Who Is In
1189 1187

1188

Who Is Out 1189

CREATE ORGANIZATION (Default Action

893

This action is used for creating new organization. It allows user to specify basic properties of the new organization and configure it immediately after creation.
Action Type: Permissions: Create
905 932

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information
Context Type
Context Name
864

: organizations

863

: organizations
864 :

Context Description Context Path

863

Organizations

: organizations

2000-2013 Tibbo Technology Inc.

1204

AggreGate Documentation
865

Context Mask

: organizations
865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Organization creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new organization.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
1205

variable in Organization

1204

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

11.10.9 Organization
This context
863

lets you access and manage a single organization

[?
651 ] 243

1173

Unique Actions
organization: Attendance 1187

Organization context has several show report

actions for viewing reports on cardholders

1193

that belong to this

Daily Activity Report 1187

Daily Utilization Report Time Recorder Events Timecard 1188 Who Is In
1189 1187

1188

Who Is Out 1189

2000-2013 Tibbo Technology Inc.

Time and Attendance

1205

CONFIGURE (Default Action

893 )

This action is used to edit properties of organization.

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: organization : provided by user

864 :

863

Context Description Context Path Context Mask

863

provided by user

: organizations.ORGANIZATION_NAME : organizations.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Organization configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

ORGANIZATION PROPERTIES

Variable Name: Records: Permissions: Record Format

855

childInfo

1 Readable at Observer permission level :

932

, writable at Manager permission level

2000-2013 Tibbo Technology Inc.

1206

AggreGate Documentation

Field Name name

Field Type String

Notes Organization Name. Name of this organization context, required to refer to this organization from other parts of the system . It should satisfy the context naming conventions 863 . Length: 1-50 characters. Organization Description. Length: 1-100 characters.

description

String

SHIFT

Variable Name: Records: Permissions: Record Format

Field Name
855

shift

1 Readable at Observer permission level :

Field Type String Notes
932

, writable at Manager permission level

shift

Organization's shift

1182

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

11.10.10 Shifts
This context
863

is a container, holding all shift contexts 1207 in system.

[?
651 ]

Unique Actions

CREATE SHIFT (Default Action

893

This action is used for creating new shift. It allows user to specify basic properties of the new shift and configure it immediately after creation.
Action Type: Permissions: Create
905 932

Accessible at Manager permission level [?

651 ]

Common Actions

Create From Template 905 , Replicate To Children 910 , Import 908 , Export 907 , Edit Context Permissions Related Events 909 , Search/Filter 909 , various Grouped Actions 894 according to child contexts.

906 ,

Monitor

Context States and Icons

This context has no states
865

. It is always represented by the

icon.

Advanced Information
Context Information

2000-2013 Tibbo Technology Inc.

Time and Attendance Context Type

Context Name
864

1207

: shifts

863

: shifts
864 :

Context Description Context Path Context Mask

863

Shifts

: shifts : shifts
865

865

Context Permissions [?
Level None Observer Operator Manager Engineer Administrat or Description

No access allowed. Basic event monitoring. Same as Observer. Shift creation, export and import. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

This context has no public variables (properties).

Public Functions

[?

878 ]

Common Functions: makeCopy (Make Copy)

879 ,

delete (Delete)

880

CREATE
Creates new shift.

Function Name: Permissions: Input Records:

Input Format
855

create Accessible at Manager permission level

932

1
: Same as format of childInfo
1208

variable in Shift

1207

context.

Output Records: Output Format

855 :

0
none
880 ]

Public Events

[?

Common Events: info (Information)

885

11.10.11 Shift
This context
863

lets you access and manage a single shift 1179 .

[?
651 ]

Unique Actions

CONFIGURE (Default Action

893 )

This action is used to edit properties of shift.

2000-2013 Tibbo Technology Inc.

1208

AggreGate Documentation

Changing Name field during this operation will cause renaming of current context. This may lead to malfunctioning of other system components that use context name/path as a primary identifier.

Action Type:

Configure
[?
651 ]

904

Common Actions
Delete
905

, Make Copy

908 ,

Replicate

909 ,

Edit Context Permissions

906 ,

Monitor Related Events

909 ,

View Status

910

Context States and Icons

This context has no states
865 .

It is always represented by the

icon.

Advanced Information
Context Information
Context Type Context Name
864

: shift : provided by user

864 :

863

Context Description Context Path Context Mask

863

provided by user

: shifts.SHIFT_NAME : shifts.*
865

865

Context Permissions [?
Level None Observer Description

No access allowed. Basic event monitoring. Status browsing.

Operator Manager Engineer Administrat or

Same as Observer. Shift configuration and removal. Same as Manager. Same as Manager.

Public Variables (Properties)

[?

869 ]

Common Variables: groupMembership (Group Membership)

875 ,

activeAlerts (Active Alerts)

875

SHIFT PROPERTIES

See description of the variable and its fields is here 1179 . Variable Name: Records: Permissions: Record Format
Field Name
855

childInfo

1 Readable at Observer permission level :

Notes
932

, writable at Manager permission level

Field Type

2000-2013 Tibbo Technology Inc.

Time and Attendance

1209

name

String

Shift Name. Name of this shift context, required to refer to this shift from other parts of the system. It should satisfy the context naming conventions 863 . Length: 1-50 characters. Shift Description. Length: 1-100 characters. Type . 0(Week) or 1(Regular) Start Date. Only for regular shift type Auto Out. Overtime After End. Overtime Before Begin.

description type startDate autoOut otAfterEnd otBeforeBegi n otDayOff otDuringLunc h

String Integer Date Boolean Boolean Boolean

Boolean Boolean

Overtime Day Off. Overtime During Lunch.

SCHEDULE

See description of the variable and its fields is here 1180 . This variable has several differences for week and regular shift types. Variable Name: Records: Permissions: Record Format
Field Name
855

schedule

7 for week shift, 0...unlimited for regular shift Readable at Observer permission level :
Field Type String Boolean Date Date Boolean Date Date Integer Integer Time-only editor is used. Time-only editor is used. Time-only editor is used. Time-only editor is used. Notes
932

, writable at Manager permission level

dayOfWeek isWorkday reportingTime knockOffTime hasLunch lunchBeginHour lunchEndHour maximumOT minimumOT

Day Of Week. Regular shifts have no this field.

EXCEPTIONS

See description of the variable and its fields is here 1181 . Variable Name:
exceptions

2000-2013 Tibbo Technology Inc.

1210

AggreGate Documentation 0...unlimited Readable at Observer permission level

855 932

Records: Permissions: Record Format

Field Name

, writable at Manager permission level

:
Field Type Date Date Boolean Date Date Boolean Date Date Integer Integer Time-only editor is used. Time-only editor is used. Time-only editor is used. Time-only editor is used. Notes

startDate endDate isWorkday reportingTime knockOffTime hasLunch lunchBeginHour lunchEndHour maximumOT minimumOT

Date-only editor is used. Date-only editor is used.

Public Functions

[?

878 ]

This context has no public functions.

Public Events

[?

880 ]

Common Events: info (Information)

885

12 Tutorials
Sometimes, you don't want to learn all about the theory and internal mechanics of the system, or figure out all the algorithms AggreGate Server uses to execute a certain operation; sometimes, you just want to do something. And you want us to tell you how to do it. Hence, this Tutorials section. You won't find any in-depth explanations here, or delving into theory. Just straight-andsimple 1-2-3 style operations, to be executed in AggreGate Client 776 or other AggreGate Server User Interface. From time to time we'll add articles to this section. This will probably happen when we get too many support requests asking how to do something with the system, or how to use a particular feature.

Disclaimer
Due to the nature of this section, you need to keep several things in mind: The tutorial you're looking for might not exist yet. If so, read the complete manual topic dealing with whatever it is you're trying to do. It'll probably have the answer you need, and possibly even an example. The tutorials are written specifically for AggreGate Client. Same procedures may be executed in the similar way using other AggreGate Server User Interfaces. The articles don't involve too much theory. Don't expect to understand everything. If you need comprehensive understanding, please read the complete manual topic, and not just the tutorial. We've attempted to include many links. And most importantly: It might not work. Seriously. AggreGate Server is a complex system, and we aimed for "sane defaults" when writing the tutorials. Possibly some settings are different on your system, or your network

2000-2013 Tibbo Technology Inc.

Tutorials

1211

topology is somewhat different, and this may cause unexpected results. When this happens (you guessed it...) please read the comprehensive manual topic for the subject you're trying to resolve. If all else fails, you can always write Support. Details are in the Tibbo website.

12.1 Performing an Action With Multiple Devices

This tutorial explains how you can perform the same action with multiple Devices with just a few mouse clicks using Favourites 626 . Let's assume you have many Devices that support Self-Test operation. This operation may cause each Device to diagnose its internal state. Every device may output self-test results to its LCD or report it to AggreGate. Since system operators should initiate device self-test frequently, it must be conveniently initiated using just several mouse clicks. Moreover, it will be very convenient to self-test several devices at once. The Favourites 626 facility is ideal for that task. This article shows how to configure a self-test operation to be called from the favourites list in AggreGate Client same method may be also used to perform any other common operation with your Devices. Here is what a Self-Test action may look like in the Device context menu:
776 .

The

1. Putting Self-Test Action To Favourites

Drag a Device System Tree 784 node ( the drop-down list and click OK: ) and drop it on the Favourites node ( ). Select
896

the Self-Test action from

The newly created favourite will appear in the Favourites table:

2000-2013 Tibbo Technology Inc.

1212

AggreGate Documentation

2. Editing The Favourite action to initiate Self-Test of multiple Devices

Expand the Favourites System Tree node and right click the new "Perform Self-Test" favourite. Select Configure from the context menu:

Change Description to a new meaningful name, e.g. Self-Test My Devices. Next, modify the Context Mask so it encompasses a number of Device contexts 863 to call the Self-Test action from. Change Context Mask to users.*.deviceservers.*.devices.* to make this Favourite initiate self-test for all Device in the system. In fact, only Devices that are accessible with your user permissions
931

will be put into self-test.

To self-test only your own devices, e.g. devices that belong to your user account YOUR_USER_NAME.deviceservers.*.devices.*.

108 ,

change Context Mask to users.

3. Initiate Self-Test
To perform the self-test, just click the Self-Test My Devices favourite in the Favourites table. This will cause AggreGate Server to perform the requested procedure immediately. Depending on the Device type, test result and any failures may be reported on Device LCD, in Event Log 791 or using the Show Message 899 /Show Error 899 UI procedure.

2000-2013 Tibbo Technology Inc.

Tutorials

1213

12.2 Copying Objects Between User Accounts

This article explains how AggreGate administrators may copy objects between different user accounts AggreGate Client 776 . Such object cloning may be convenient in many cases:
108

using

When you have created some useful objects (e.g. alerts 216 , reports 241 , widgets 312 etc.) under your own account and want to share them with other users without allowing them to modify your original objects; When one user wants to use an object created by another user but you don't want to give him permissions to access that object. If you want to give one user permissions to fully access, modify and use some object that belongs to another user without making a copy of that object, see How to give one user access to the objects of another user 1215.

1. Finding the Container Node

In the System Tree
784 ,

expand the node for the user account (

) under which a copy will be created. User account

931 .

nodes are located under the Users node (

). Users node is available only if you have administrative permissions

Within the user's node, find the container node that holds objects of the same type as the copied object. For example, if you are going to make a copy of a script
628 ,

find the Scripts node (

).

Here is a screenshot showing how the Queries node for a user called test:

2. Launching Make Copy Action

Right-click the node you found at the previous step and select Make Copy :

2000-2013 Tibbo Technology Inc.

1214

AggreGate Documentation

In the Entity Selector copy of a query (

815

window, find an object you to copy. Click it, then click OK. For example, if you are making ):

), expand Users node, then the node of a user who owns the query you want to copy. Finally,

expand this user's Queries node (

A copy of the selected query will be created under the account of the user selected at step 1:

See Make Copy Action

908

article for more information about object copying.

2000-2013 Tibbo Technology Inc.

Tutorials

1215

Using Drag and Drop for cloning objects Another method to copy an object is to drag an object and drop it on the corresponding container node under another user account. This is faster but may be not convenient in some cases because nodes may be located far one from another in the System Tree and you'll need to scroll the tree while holding the mouse button pressed.

12.3 Granting One User Access to Objects of Another Use

This article explains how to give one AggreGate user 108 permissions to view, modify and use an object that belongs to another user account. This object can be a Report 241 , an Event Filter 206 , a Device 113 or any other system resource. See Security and Permissions 931 for more information about the AggreGate security system. Let's see how we can share a Temperature Monitor Widget
312

that belongs to user admin with a user called test.

1. Detecting The Context Path of The Object to be Shared

Find object that will be shared in the System Tree 784 of AggreGate Client context menu to copy its context path to the clipboard:
776 .

Right-click it and select Copy from the

You can also enter this path manually when needed, later on. To see the context path of any object, hold the mouse over it for some time and check the tooltip. In our example, the Widget context 774 path is users.admin.widgets. tmon:

2. Changing Permissions Table

Now edit the permissions table for the user who should have access to the shared resource. Find this user's node ( the System Tree (it is located under Users node, menu: ) and right-click it. Select Edit User Properties from context ) in

2000-2013 Tibbo Technology Inc.

1216

AggreGate Documentation

In the Permissions tab, select the first line in the table by clicking its number. Then click Add row ( ) to insert a new row at the beginning of the table. Right-click the Context Mask field for the new record and select Paste from the context menu. You can also press Ctrl-V or manually enter the context path noted at step 1. Finally, select Manager in the Permissions field:

We have put new permission record in the beginning of the table make sure that it won't be overridden by other records.

It is possible to user context masks 865 to share a number of resources. For example, to allow access to all widgets use context mask users.admin.widgets.* instead of users.admin.widgets.tmon.

To give all newly created users permissions for certain resources, add a permission record similar to the one described above to Additional Permissions For New Users 73 global configuration table.

3. Accessing Shared Resource

Log in as a user that should be able to access a shared resource. You should be now able to view and access this resource through the system tree. It is located under the node of its owner:

2000-2013 Tibbo Technology Inc.

Tutorials

1217

12.4 Creating a Widget to Monitor a Device

This tutorial covers the process of creating a simple widget 312 for monitoring your Device. Here we assume that our Device is a digital temperature/humidity sensor that communicates with AggreGate Server using SNMP protocol. Our widget will show the current temperature and humidity in real-time mode. Connection of the sensor to the server and its configuration is beyond the scope of this article, so we assume it is already online and visible for the system as a Device 113 .

1. Launch GUI Builder

To start creating a widget, find the Device's node in the System Tree ):
784

). Drag and drop it on the Widgets node (

This operation will show the Properties: Widget window. Set Widget Name to thmonitor and Widget Description to Temperature/Humidity Monitor. Clicking OK will open the GUI Builder 827 with an empty widget template 314 . Dragging the Device to the Widgets node means that the newly created widget will be available for every Device 677 context.

2. Adding Widget Components

2000-2013 Tibbo Technology Inc.

1218

AggreGate Documentation
836

Let's add some components to the widget. See Editing Widget Layout Drag the Label component ( form 830 mode: ) from the component palette
834

for details on manipulating widget components.

and drop it to the root panel of the widget in work

Add another label by dropping it under the current one to column 0, row 1 of the root panel:

Add one more label to column 1, row 0:

2000-2013 Tibbo Technology Inc.

Tutorials

1219

Then add a Slider component (

) to column 1, row 1:

3. Editing Component Properties

Click on label1 in the work form and change its Text property in the properties window
835

to "Temperature: ".

2000-2013 Tibbo Technology Inc.

1220

AggreGate Documentation

Change text of label2 to "Humidity: ". Then change text of label3 to 0. Then right-click label3 in resources window
833

and select Rename from context menu. Call it temperature.

Rename slider1 to humidity in a similar way. Now open Font property of label1 in properties window. Check Use Custom Font, set Name to Arial, Size to 20 and check Bold. Set the same font to label2 and temperature (former label3). Set the slider's Enabled property to false to prevent is from being moved. Select all four components one by one and set their anchor Then edit constraints
318 319

to West by clicking

button in the toolbar.

of temperature and humidity labels and set Left Margin to 15.

836

You can also edit margins using the mouse, see Editing Widget Layout

for details.

Now your widget should look like that in the work form:

2000-2013 Tibbo Technology Inc.

Tutorials

1221

4. Creating Bindings
At this step we'll bind 604 components of our widget to real data. This data is presented in the form of context variables 869 . Our sensor has two handy variables: Temperature*10 that contains a temperature value in Celsius degreed multiplied by 10 at Integer number (i.e. value 234 corresponds to 23.4 degrees by Celsius); Humidity*10 that contains relative humidity in percents multiplied by 10 as Integer number (i.e. value 456 corresponds to relative humidity 45.6%). Let's first bind the field of Temperature*10 variable to our temperature label. Find this variable in the entity selector 834 window under the default Device context (it should be bold). Expand it to see its single field, called Temperature*10. Drag this field and drop it over the temperature label:

2000-2013 Tibbo Technology Inc.

1222

AggreGate Documentation

You'll see a message showing which bindings were created:

In the same manner, bind the Humidity*10 field of the Humidity*10 variable to the humidity slider using drag and drop operation.

EDITING BINDINGS MANUALLY

We now need to manually edit the created bindings. Select the Root Panel by clicking on Root in the top left corner of the work form and open its All Bindings property in the properties window. There should be four bindings in the table:

Bindings 1 and 3 should be removed as they will try to write new temperature and humidity values to the Device. This operation is, indeed, not permitted and will be blocked by the server. Therefore, remove these bindings by clicking on their numbers and then clicking Remove Row ( ) in the toolbar of the Data Table Editor
801 .

Now we have to correct measurements of temperature and humidity that are multiplied by 10. Edit expression field of the remaining bindings by adding / 10 to them:

{.:temperaturei$temperaturei} => {.:temperaturei$temperaturei} / 10 {.:humidityi$humidityi} => {.:humidityi$humidityi} / 10

It's also necessary to remove the activators 607 of remaining bindings so that they will be re-processed every time temperature or humidity changes. Set the activators to empty strings. The resulting bindings table:

Click OK to save the table.

5. Resizing the Widget Template

Click Toggle Decorations ( ) in the toolbar would look like during normal operation.
829 .

This will make widget appearance in the work form similar to what it

Select the root panel by clicking Root in the top-left corner of the work form. Set Application Window Width to 370 and Application Window Height to 120. You can also resize the widget and its components using a mouse. See Editing Widget Layout
836

for details.

Finally, the template looks like this:

2000-2013 Tibbo Technology Inc.

Tutorials

1223

6. Saving Widget Template

The template is ready. Click Done ( Now new a new widget context
774

). ) should be created and appear in the System Tree

784 :

7. Launching Widget
It's time to see our new widget in action. Right-click on any System Tree node for a Device ( new launch widget action 316 in a context menu: ). You should see a

Select this action to launch the widget for a certain temperature/humidity sensor. A new dockable window our widget will appear in AggreGate Client:

781

containing

2000-2013 Tibbo Technology Inc.

1224

AggreGate Documentation

Voila! The new widget is up and running. You can now monitor the current temperature and humidity. See How to a create a dashboard to monitor your devices in real-time 1233 to find out how to start your widget automatically when AggreGate Client is launched.

12.5 Manipulating SVG Images

AggreGate has comprehensive support for SVG (Scalable Vector Graphics) images. It includes features such as transparency, arbitrary geometry, filter effects (shadows, lighting effects, etc.) and animation. Any SVG image can be scaled, rotated and flipped without loosing its quality. A special Symbol Library 1165 provides a vast collection of SVG images with additional built-it functionality. These special images have dynamic properties for changing different visual aspects: color, lines thickness, animation etc. This article shows how to manipulate SVG images and use them for creating interactive user interfaces. The tutorial will guide you to create a widget with two SVG components: a fan controlled by a button.

1. Creating a Widget
To create an empty widget double-click on the System Tree
784

Widgets (

) node or choose its Create Widget (

2000-2013 Tibbo Technology Inc.

Tutorials
action in popup menu. In the opened window set Widget Name property to svgManipulation, and Widget Description to SVG Manipulation, click OK. This will bring you to the GUI Builder 827 with an empty widget template 314 .

1225

2. Adding SVG images

First, set Layout property of the Root panel 376 to Absolute layout 322 to have more freedom in component positioning. We use the root panel for simplicity, but you can also use a separate panel as a container. Drag the Vector Drawing component ( work form 830 : ) from the component palette
834

and drop it to the root panel of the widget

Now load a file with the fan image from the Symbol Library and open the proper file in the dialog appeared.

1165 :

press Choose button in SVG File property, then locate

Set the component's position and size properties: X Coordinate and Y Coordinate to 0, Width and Height to 500. This will make the fan to occupy full widget space.

2000-2013 Tibbo Technology Inc.

1226

AggreGate Documentation

Drag and drop another Vector Drawing component ( ) from the component palette 834 to the work form 830 . Then load a button image file from the Symbol Library 1165 as described above. Resize it and move to the left bottom panel corner: set X Coordinate and Y Coordinate properties to 410, Width and Height properties to 90. Now we've got the fan with the button:

3. Renaming Components
Let's rename our components to easily identify them. Right-click on the component (or on the component's name in the Resources Tree 833 ) and choose a Rename item in the popup menu.

Call your components fan and button.

4. Animating the fan

2000-2013 Tibbo Technology Inc.

Tutorials

1227

First, make the button to turn the fan rotation on. The fan SVG image has the State property that turns rotation animation on and off. Let's bind 604 this property to trigger fan animation state upon clicking the button. To perform that, right-click on the fan's State property in the Properties Editor 835 and choose a Bind Property popup menu item, the Bind Property dialog should appear.

The Target 605 property is already set to form/fan:state. Click [...] button inside the Expression 606 field to edit the expression text interactively in the Expression Builder 817 . First, find the fan State property in the Components tree of the Expression Builder, double-click it to insert a reference. Second, append == 'on' ? 'off' : 'on' to the expression, click OK to accept the Expression Builder dialog. The resulting expression will return inversion of the fan State property value when evaluated.

Next, switch to the Activator 607 field and click [...] to open an Activator dialog. Select a Widget Event tab, then set a Context field to button and an Event to mousePressed. Click OK to confirm. This activator will run the binding every time a click on the button is performed.

2000-2013 Tibbo Technology Inc.

1228

AggreGate Documentation

Check that On Event property is marked in the Bind Property dialog. Make sure that all properties have values as shown on the screenshot and click OK:

5. Animating the button

Now let's allow the button to light up in green when the fan is turned on. Right-click on the button's Color property in the Properties Editor 835 and choose a Bind Property popup menu item. Set binding properties the same way as above to meet the values shown on the below screenshot and click OK:

2000-2013 Tibbo Technology Inc.

Tutorials

1229

The expression includes a color function that returns a color with the specified red, green and blue values. To insert functions in expression you can use the Function Chooser dialog opened by a Functions button of the Expression Builder dialog:

6. Saving and running the widget

Click Done ( System Tree
784

) to finish editing and save the widget. SVG Manipulation widget context . To see the widget in action choose Launch Widget (

774

) should appear in the

) action from a widget popup menu.

2000-2013 Tibbo Technology Inc.

1230

AggreGate Documentation

Here you are! You can press the button and see the fan in action.

In this tutorial we showed you how to create interactive components. Now you can combine controls and use them for building complex user interfaces.

12.6 Handling Component Events

When every event is fired it has a data specific to event type. For example, Mouse Click event's data contains X and Y coordinates of clicked mouse position. This article show how to use this data in widget bindings. We will create a widget with an image that moves to the last mouse click position.

1. Creating a Widget
To create an empty widget double-click on the System Tree 784 Widgets ( ) node or choose its Create Widget ( ) action in popup menu. In the opened window set Widget Name property to componentEvents, and Widget Description to Handling Component Events, click OK. This will bring you to the GUI Builder 827 with an empty widget template 314 .

2. Adding an image
First, set Layout property of the Root panel 376 to Absolute layout other container can be used instead of the Root Panel. Let's use the Vector Drawing 352 component ( to the root panel of the widget work form 830 :
322

to have freedom of component positioning. Any

) as our image. So drag it from the component palette

834

and drop it

2000-2013 Tibbo Technology Inc.

Tutorials

1231

Now you can load any SVG image to the component: press Choose button in SVG File property, then locate and open the proper file in the dialog appeared. Resize the component as you wish.

3. Adding bindings
Select the component and press the right mouse button, in the opened popup menu choose the Edit Bindings item:

A Bindings 604 dialog should appear. Then press the Add button ( Target's dots button [...]:

) to add a new empty binding. Next, click on

This will open the Target 605 wizard. Here you must choose what property will be changed by the binding execution. At the dialog's bottom the reference to chosen property is displayed. Choose the xCoordinate property of our Vector Drawing component here (so the target will point to form/vectorDrawing1:xCoordinate$xCoordinate) and click OK.

2000-2013 Tibbo Technology Inc.

1232

AggreGate Documentation

Next, do the same with the Activator 607 field and choose Mouse Clicked event of the Root Panel component at the Component Event tab. This means that binding will be triggered on a root panel mouse click.

Now let's define the Expression 606 that evaluates each time binding is triggered and it's result is written to the target. To refer to an event parameters the special schema 926 'value' is used. So to get a mouse click event x-coordinate we must use this reference: {value/x}. A complete list of component event parameters is described in the Component Events
595

section.

To get our image centered on a clicked position we must shift a new component's x-coordinate to a half component width. So the resulting expression must be: {value/x} - {form/vectorDrawing1:width$width} / 2. You

2000-2013 Tibbo Technology Inc.

Tutorials
can use the Expression Editor
817

1233

to help writing this expression.

OK, we have a binding for x-coordinate and now we need the same but for y-coordinate. To create a binding for it we can use the duplicate function of our Data Table Editor 801 : select the x-coordinate binding in the Bindings editor, hold down the Shift key and press the Add button ( ). This will create a copy of the original row in the bindings table. So we should only fix a created binding. Set the Target to form/vectorDrawing1:yCoordinate$yCoordinate, and the Expression to {value/y} - {form/vectorDrawing1:height$height} / 2. Finally, we must uncheck On Startup boxes to get our bindings work only on a defined event. The resulted Bindings table should be the following:

4. Saving and running the widget

Click Done ( ) in the GUI Builder's toolbar to finish editing and save the widget. Handling Component Events
784 .

widget context 774 ( ) should appear in the System Tree menu and open our interactive widget.

Choose Launch Widget (

) action from a widget popup

12.7 Creating a Dashboard to Monitor Your Devices in Re

When AggreGate is used for monitoring different electronic devices, it's often important to be able to view their operational status and important parameters in a real-time. Moreover, it may be necessary to execute certain operations quickly in response to changes in monitored data. Normal AggreGate facilities, such as monitoring device events in Event Log 791 and responding to them using Favourites 626 may not be convenient in some use cases. In such situations, custom Widgets 312 may be created to represent device state. These widgets may also contain buttons and other input controls, to allow interactive communication with a device. These widgets should be constantly active when a system operator in on duty and AggreGate Client 776 is running. They should run automatically upon AggreGate Client startup. In this article we'll show how to combine widgets with Auto Run 625 feature to form a so-called dashboard. A dashboard is a group of widgets that are started automatically and placed in pre-defined positions to allow quick access to system-critical parameters and functions. For this example, we'll use the Temperature/Humidity Monitor widget we created in How to create a widget to monitor your device 1217 . Of course, any other widget (or widgets) may be used to create a dashboard.

1. Adding Launch Widget Action to Auto-Run

First we open the node for the Device we want to monitor. The context menu of this node should contain a Launch Widget Action 316 . When such an action exists, it means a certain widget was created 315 to work with this Device. Drag the Device System Tree node ( ) and drop it on the Auto Run node ( ):

2000-2013 Tibbo Technology Inc.

1234

AggreGate Documentation

Select the Launch Widget Action (in this case, Temperature/Humidity

Monitor) from the drop-down box.

A new Auto-Run Action (

) will be created:

Create Auto-Run Actions for all other Device / Widget pairs that you want to appear in the dashboard in the same way.

2. Creating a Dashboard Layout

Right-click your new Auto-Run Action and select Configure ( Click the Parameters field of the configuration dialog: ) from context menu.

2000-2013 Tibbo Technology Inc.

Tutorials

1235

In the Parameters dialog, click in Window Location:

Now you can edit the name of the dashboard to place your widget on and its location inside the dashboard:

More information about window location property is available here

955 .

3. Adjusting Dashboard Layout

Right-click the Auto-Run Action node and select Launch Action from context menu:

2000-2013 Tibbo Technology Inc.

1236

AggreGate Documentation

The widget will launch, and a new widget window will appear. Move it to the desired position. It may be floating or docked to the other windows. See Customizing Dockable Panes 781 for more information on how to manage window layout. Repeat the same steps for every Auto-Run Action you've created. Here what the dashboard may look like with all widget windows docked:

Dashboard with separate floating windows:

2000-2013 Tibbo Technology Inc.

Tutorials

1237

Floating dashboard with tabbed windows:

A dashboard with tabbed windows grouped with the System Tree:

2000-2013 Tibbo Technology Inc.

1238

AggreGate Documentation

A dashboard with several widgets grouped in one floating window:

2000-2013 Tibbo Technology Inc.

Tutorials

1239

You can exit AggreGate Client now. Your dashboard will appear automatically next time you log on. You can add, remove and relocate its components at any time. All changes will be automatically saved and re-applied upon next launch of AggreGate Client.

12.8 Monitoring Device Parameters Using a Chart

Charts are very good for displaying changes in device parameters over time. In this tutorial we'll show you how to chart temperature data coming from a sensor. Connecting the sensor to the server is beyond the scope of this article, so we suppose that it is already online and visible for the system as a Device 113 . In AggreGate, charts are a part of Widgets 384 component.
312

engine. We're going to create a simple widget, containing a single Chart

The easiest way to create a chart for any AggreGate variable is to launch Configure Device
771

677

) action, right-click

on a desired variable and select Create Chart ( ) item. This action will create a new widget with a chart component and with several other components for controlling chart parameters on-the-fly. Created widget will look like this:

2000-2013 Tibbo Technology Inc.

1240

AggreGate Documentation

The other way to get a variable changes chart is manually creating a widget, adding a chart component to it, and setting up the chart.

1. Starting Widget Creation

To start creating a widget, find the Device node you wish to monitor in System Tree Widgets node ( ):
784

). Drag and drop it on the

In the popup menu choose Create Widget ( ) action. Widget Properties tchart, Widget Description to Temperature Chart and click OK.

315

dialog will open. Set Widget Name to

This will launch the GUI Builder 827 with an empty widget template our chart will be available for every Data Terminal 677 context.

314 .

Dragging the Device to the widgets node means

2. Adding Chart Component

Drag the XY Line Chart component from component palette
834

and drop it on the widget's Root Panel:

2000-2013 Tibbo Technology Inc.

Tutorials

1241

This will add a new chart component to the widget template

314 .

3. Setting Up the Data Source

Our chart will show changes in the value of context variables 869 . The temperature sensor has one variable we can easily graph. It is temperaturei, containing an Integer temperature value in Celsius, multiplied by 10 (i.e. value 234 is 23.4 degrees Celsius). The temperature value is, indeed, contained in a single field of this variable, also called temperaturei. Therefore, our chart will be based on variable data. Click on the chart in the work form and change the Data Source Type property to Variable in the properties window 835 Data tab:

Next, click in Source Variables

387

to set up a new data series. The Source Variables window will open. Click Add Row (

) to create a new data series, then edit it: Set Name to Temperature; Switch to the Context field and click [...] to edit the context path interactively in the Entity Selector Device from the tree (it should be bold, as it is a default context) and click OK:
815 .

Select your

2000-2013 Tibbo Technology Inc.

1242

AggreGate Documentation

The actual value for Context field will be a dot (".") instead of the full path to the Device context 677 . This is a relative path that will allow our chart widget to work with other similar devices, not just the one that it was created for. Select temperaturei from the list of Variables . Switch to the Expression field and click [...] to edit the data expression interactively in the Expression Builder 817 . First, in the Expression Builder window just double-click the temperaturei field in the Relative References section to add one relative reference. Second, append / 10 to Expression to divide the value and thus convert it to normal Celsius degrees. This is required, as the variable field initially contains temperature multiplied by 10 to allow storing it as an Integer number:

Leave other columns unchanged. Here is what your variable data series should look like:

2000-2013 Tibbo Technology Inc.

Tutorials

1243

4. Configuring Chart Properties

At this point you may want to configure your chart. See the Chart 384 article for more information about available properties and their descriptions. For example, you may want to change Include Historical Data and Include RealTime Data flags to get chart based on current temperature, temperature history or both. Another option to change is Type of Domain Axis. Setting it to Date Axis or Period Axis makes horizontal axis to display dates instead of integer numbers. Yet another useful option is Renderer that affects chart's appearance. You can also limit chart's time range by enabling the Limit Time Range option and changing Time Range to a preferred value.

5. Saving Chart Widget

Click Done ( ) to finish editing and save the widget. It should appear in the System Tree:

6. Displaying Chart
Right-click the Device System Tree node (
316

) of your temperature sensor. You should see a new launch widget action

named Temperature Chart (

) in the context menu:

Select this action to launch the widget for a certain temperature sensor. A new dockable window with our chart will appear in AggreGate Client:

781

containing a widget

2000-2013 Tibbo Technology Inc.

1244

AggreGate Documentation

The chart will update dynamically if Include Real-Time Data is enabled in chart settings. If you wish to monitor temperature constantly when AggreGate Client is running, include the chart widget in a dashboard. See How to a create dashboard to monitor your devices in real-time 1233 for more information.

12.9 Building Complex Chart

This tutorial demonstrates how to use a mixed chart 469 to combine two charts: one for displaying data and another for showing trend lines for this data. We'll use chart temperature and humidity data coming from a sensor. Connecting the sensor to the server is beyond the scope of this article, so we suppose that it is already online and visible for the system as a Device 113 . The result of this tutorial will be a widget with a temperature and humidity chart with trend lines:

1. Starting Widget Creation

To start creating a widget, find the Device you wish to monitor in System Tree the Widgets node ( ):
784

). Drag device node and drop it on

2000-2013 Tibbo Technology Inc.

Tutorials

1245

In the popup menu choose Create Widget ( ) action. Widget Properties tchart, Widget Description to Temperature Chart and click OK.

315

dialog will open. Set Widget Name to

This will launch the GUI Builder 827 with an empty widget template our chart will be available for every Data Terminal 677 context.

314 .

Dragging the Device to the widgets node means

2. Adding Charts
Drag the Mixed XY Chart component from component palette 834 and drop it on the widget's Root Panel. This will add a new chart component to the widget template 314 . Turn on Horizontal and Vertical filling for chart by pressing buttons in the toolbar 829 .

A mixed XY 469 chart is a composite chart 488 that can hold other non-mixed XY charts Particularly, it lets one charts to draw trends for another.

429

sharing the plot and axes.

2000-2013 Tibbo Technology Inc.

1246

AggreGate Documentation

Then drag and drop XY Bar Chart (to display temperature and humidity) and XY Line Chart (to display trends) to the Mixed XY Chart.

3. Renaming Charts
Now rename xyLineChart1 to trends, xyBarChart1 to thsensor. To rename a component right-click it in the Resource Tree 833 , choose the Rename item in the popup menu and enter a new name in the edit box appeared.

You can also rename a component using its work form

830

popup menu.

4. Configuring Sensor Chart

Let's send to back the thsensor bar chart to appear the trends line chart on foreground. So, select the thsensor chart in the Resource Tree 833 and set a Z-Order property of the thsensor to 2 in the properties window 835 . Now, make the chart to display temperature and humidity of the thsensor Device. The temperature sensor has a variable temperaturei, containing an Integer temperature value in Celsius, multiplied by 10 (i.e. value 234 is 23.4 degrees Celsius) and a variable humidityi that is humidity value in percents, multiplied by 10. Therefore, our thsensor chart will be based on variable data. Change the Data Source Type property to Variable in the properties window 835 Data tab:

2000-2013 Tibbo Technology Inc.

Tutorials

1247

Next, click in Source Variables

387

to set up a new data series. The Source Variables window will open. Click Add Row (

) to create a new data series, then edit it: Set Name to Temperature; Switch to the Context field and click [...] to edit the context path interactively in the Entity Selector thsensor Device from the tree (it should be bold, as it is a default context) and click OK:
815 .

Select

The actual value for the Context field will be a dot (".") instead of the full path to the Device context 677 . This is a relative path that will allow our chart widget to work with other similar devices, not just the one that it was created for. Select temperaturei from the list of Variables . Switch to the Expression field and click [...] to edit the data expression interactively in the Expression Builder 817 . First, in the Expression Builder window just double-click the temperaturei field in the Relative References section to add one relative reference. Second, append / 10 to Expression to divide the value and thus convert it to normal Celsius degrees. This is required, as the variable field initially contains temperature multiplied by 10 to allow storing it as an Integer number:

2000-2013 Tibbo Technology Inc.

1248

AggreGate Documentation

Accept the expression by clicking OK button. Leave other columns of the Source Variables you get the record for the temperature.

387

dialog unchanged. So,

Now, add and set up a second data series for the humidityi variable as you do for the temperaturei variable. Finally, here is what your variable data series should look like:

While adding a second source variables record by clicking Add Row ( ) you can hold a Shift key. This will duplicate the record for the temperature, thus for the humidity you have to fix Name , Variable and Expression fields in the duplicated record.

5. Configuring Trends Chart

Let's configure our trends chart to display trend lines for the thsensor chart. First, in the properties window 835 switch its Data Source Type property to Trending 395 . Then, in the Trending tab select thsensor in the Source Chart Name property.

The trending chart will create a separate trend series for every series of the source chart. Let's now set custom trending series names: click Series Names property and add two rows with names Temperature Trend and Humidity Trend.

2000-2013 Tibbo Technology Inc.

Tutorials

1249

6. Cleaning Up
When a chart is configured for trending it uses the source's chart dataset to calculate trends and source's chart axes to display trend lines. So, we can remove trends chart axes were automatically added by putting the XY Line Chart (at the step 2) to the mixed chart. Select mixedXYChart1 in the Resource Tree
833 .

Go to the Axes tab and click in the Range Axes property. Select the second row in the appeared Range Axes dialog and press the Remove Row ( unused domain axis. Click OK. ) button to remove the

Do the same for the Domain Axes. Also switch type for the remaining Domain Axis to Date Axis: click on the axis and set its Type in the Axis dialog appeared.

7. Saving Chart Widget

Click Done ( ) to finish editing and save the widget. It should appear in the System Tree:

8. Displaying Chart
Right-click the Device System Tree node (
316

) of your temperature sensor. You should see a new launch widget action

named Temperature Chart (

) in the context menu:

2000-2013 Tibbo Technology Inc.

1250

AggreGate Documentation

Select this action to launch the widget. A new dockable window AggreGate Client:

781

containing a widget with our chart will appear in

In this article you have learned how to combine simple charts within mixed chart for building trend lines. There are other capabilities of combining charts you can use in projects. See composite charts 488 for further information.

12.10 Building a Device Status Report

The AggreGate Reporting 241 facility is useful when you want to get some data in human-friendly printable form. Reports show device activity over time, and other statistical information.
This article shows how to create a report that includes the history of a certain device-generated event. We use a time recorder that is connected to AggreGate via Agent 848 . Connecting the time recorder to the server is beyond the scope of this article, so we assume it is already online and visible for the system. Our time recorder generates an event 880 whenever an employee swipes their card. The event contains the cardholder ID, a direction mark ( IN when the user enters the area or OUT when he exits) and a timestamp.

1. Creating a New Report

2000-2013 Tibbo Technology Inc.

Tutorials

1251

To create a new report, find the Reports node ( Report ( ):

) in the System Tree

784 .

Right-click it and select Create New

You can also just double-click the Reports node to launch Create New Report action since it is a default action 893 in Reports context 719 . In the Report Properties window:

Set Name to trevents Set Description to Time Recorder Events

It's now time to set the most important parameter of the report -- the Source Data Expression. This expression 911 tells AggreGate Server how and where to get the data for filling in the report template. At the report creation stage, it is also used to get data for auto-generating the report template 242 . We'll use the get 695 function defined in the Events context for fetching event history returns the history of an event in the form of table, one record per event instance. The function accepts four parameters (see its description others at default values.
695 882

for the report. This function

for details), but we'll specify just the first two and leave the

In our case, the first parameter is our time recorder's Device context 677 path. We can detect this path by finding Time Recorder in the System Tree and checking its tooltip. Its path is users.admin.deviceservers.agent.devices.3_0:

You can right-click the Device and select Copy from its context menu to copy its context path to the clipboard.

You can create a report that includes events from multiple Time Recorders. Just change the context path to a mask 865 pointing to multiple devices. For example, to include events from all time recorders of the admin user 108 , change Context Mask to users.admin.deviceservers.*.devices.*. The second parameter is the name of the event generated by the time recorder. You can find it by browsing the Event Log 791 . There is a special Event column that shows event names. In our case, the event is called event . Our Data Source Expression will consist of a single reference
925

to the get function, with two parameters.

Set Source Data Expression to {events:get("users.admin.deviceservers.agent.devices.3_0", "event")}

Note that function parameters are enclosed into double quotes as these are simple text strings, not nested expressions. See Functions in References 927 section for details. Your Report Properties window should now look like this:

2000-2013 Tibbo Technology Inc.

1252

AggreGate Documentation

Click OK to proceed. The Report Template Properties window will now open.

2. Configuring Report Template Properties

At this point it's necessary to set report template properties. The report template will be automatically generated according to these properties and data fetched using the Source Data Expression specified at the previous step.
1325

Set Report Title to Time Recorder Events. Change Orientation to Portrait as we'll have only three columns in our report and data will fit better that way. Open the Visible Fields table and uncheck all fields except for the ones that you want to appear in the report. In our
case, we'll leave Id, Direction and Date:

Now click OK twice, to proceed. Report template will be generated by the server and you'll be prompted to edit it. Click Yes:

The Report Editor

826

will start, so you could edit the newly generated template.

3. Editing The Report Template

The Report Editor is a sophisticated component, but we are not going to perform any complex editing at this point. We only wish to change the report column titles.

2000-2013 Tibbo Technology Inc.

Tutorials
First, change report scale from 100 to 200%. This will make further editing more comfortable:

1253

Now double-click the header of first column and change it to User ID. Change the header of the third column to Event Date/Time in the same manner. Now select File > Quit to exit Report Editor. Confirm saving changes of report template. New Report node ( ) will be visible in System Tree:

4. Viewing the Report

To fill the report with recent data and view it, right-click it and select Show Report from the context menu. Your report will open in a Report Viewer and you'll be able to browse, export and print it:

2000-2013 Tibbo Technology Inc.

1254

AggreGate Documentation

You can also just double-click the report's node to launch the Show Report action since it is the default action 893 for the Report context 721 .

12.11 Scheduled Report Emailing

It's often necessary to send reports by e-mail. For example, company executives might want to receive IT equipment failure statistics every month. The AggreGate administrator may send the report by e-mail manually, but it would be much more effective to schedule periodic report emailing for automatic execution using AggreGate Server job scheduler 266 . This tutorial explains how to create a scheduled task that performs report emailing. To send report manually, execute Send Report by E-mail
725

action of Report context

721 .

1. Adding a Scheduled Job

To create a new scheduled task, find your report node in System Tree node ( ):
784

). Drag and drop it on the Scheduled Jobs

2000-2013 Tibbo Technology Inc.

Tutorials

1255

Select Send Report by E-mail from the list of actions that may be scheduled:

Click OK. Now define the properties for the new scheduler job. Enter the job name and description (for example, disk_summary_mailer and Disk Summary Emailing ):

Click in Parameters line, and then click in Send Report by E-mail line to open report emailing parameters. Enter email recipients and select report format:

2000-2013 Tibbo Technology Inc.

1256

AggreGate Documentation

Click OK to create new scheduled job. It's properties will open in a new dockable window.

2. Defining The Schedule

It's time to add job triggers tab (
267

that will start it at certain time. In the job properties window, open Advanced Schedule ) to add new trigger:

). Click on Add Row button (

Let's configure the job to run every Monday at 10:00 AM. To do that, we need to switch the trigger from working on certain days of month to certain days of week. First, click in Day of Month field. Day-by-day monthly schedule will open in a new window. Select Never for the first day, right-click in the same cell and select Fill Column With Cell Value from context menu:

2000-2013 Tibbo Technology Inc.

Tutorials

1257

Click OK to close the dialog. Now click in Day Of Week field. In the newly opened dialog, change Option for Monday to Always:

Click OK to apply changes. The last action is changing Time parameter of job trigger to 10:00:00:

When done, click on Save Properties (

). Your scheduled job is ready now and you may expect the report to be sent

2000-2013 Tibbo Technology Inc.

1258

AggreGate Documentation

next Monday.

12.12 Adding Custom Properties

Every Device 113 has a number of standard properties that control communications with hardware and server-side data processing, such as Synchronization Period or Use Extended Status . However, it may be necessary to associate some non-standard information with a Device. For example, IT infrastructure management tasks require a way to easily find out current physical location of a Device, i.e. building, floor and room number. AggreGate permits to add any custom data to any Device account or system resource using Common Data facility 261 . This tutorial illustrates how to add Device Location info to every device within a certain AggreGate installation using AggreGate Client 776 .

1. Creating a Common Table

First, we need to create a Common Table that will describe the format of our custom properties. A copy of this table will later be added to every Device account. Double-click the Global Common Data node ( ) to start table creation. Enter table properties as follows:

Table Name: location Table Description: Device Location Minimal number of records: 1 (because we are adding a non-tabular property) Maximal number of records: 1

Click OK to add create new common table. It will appear in the System Tree

784 :

2. Adding Location Fields to Common Table

If table configuration dialog did not pop up automatically after table creation, right-click on the newly created table and select Configure Common Table ( Click on Add Row ( Name: building Type: String Description: Building ). Switch to Fields tab to start adding table fields.

) and enter field properties:

2000-2013 Tibbo Technology Inc.

Tutorials
Extendable Selection Values: Yes Click on Selection Values and enter several buildings. Here is an example:

1259

Leave other values at their defaults and add two other fields: Name: floor Type: String Description: Floor and Name: room Type: String Description: Room Here is what Fields table should look like:

3. Assigning Device Location Table as a Custom Property

Now it's time to tell AggreGate Server that our new table is a Device's custom property. Switch to the Custom Properties tab and check Use common table as custom property . At this point Validity Expression field will become editable. It specifies
948

what contexts

863

to associate our table

2000-2013 Tibbo Technology Inc.

1260

AggreGate Documentation
817 .

with. Click on [...] button inside Validity Expression field to open Expression Builder

4. Writing Validity Expression

In our case, the validity expression should resolve to TRUE for any Device context and to FALSE for all other contexts. Device Context 677 article in the Context Reference 651 states that context type for Device contexts has the following form:

device.DEVICE_TYPE
It means that any context type starting with "device" matches the device context. Select startsWith function from a Functions drop-down list to insert it into the expression:

According to the description 914 of this function, it has two String parameters and returns TRUE if first string starts with a second ("prefix") string. Click inside function parameters and double-click Context Type in the Relative References area to add context type as a first parameter. Then manually add "device" string literal as a second parameter:

2000-2013 Tibbo Technology Inc.

Tutorials

1261

Click OK twice to apply changes to Validity Expression and Common Table configuration. Now every Device in the system has its own Location property.

5. Editing Device Location

To access Device Location property of a certain Device, right-click on it and select Edit Custom Properties.

2000-2013 Tibbo Technology Inc.

1262

AggreGate Documentation

Now you can fill in the Device Location tab:

2000-2013 Tibbo Technology Inc.

Tutorials

1263

12.13 Using Resource and Device Templates

It may be often necessary to use the same configuration for more than one Device 113 or system resource (e.g. alert or report). AggreGate uses two methods for allowing to set up similar configuration for different objects: Replication Cloning
908 909

of configuration

objects

Sometimes you may want several Devices or resources to be used as sources for cloning. These resources are disabled and do not perform any activities within the system (e.g. a disabled alert will never be raised). Such resources are called templates. This article describes how to create Device templates for quickly setting up devices with similar configuration. The same method may be used for making templates for any other resource type.

1. Creating a Group to store templates

First, let's create a Device Group to store our templates. This step is not necessary but it may be useful for separating active devices from templates. In the System Tree
784

of AggreGate Client, right-click Device Groups (

) and select Create Group (

):

Enter group Name and Description . Check Hide Members From Primary Location to separate templates from normal devices:

2000-2013 Tibbo Technology Inc.

1264

AggreGate Documentation

Click OK to create new group.

2. Creating a template
We need to clone a Device to use its copy as a template. Right-click on the Device ( ) that you want to be used as a template and select Make Copy ( ):

Enter a name and description for the template:

2000-2013 Tibbo Technology Inc.

Tutorials

1265

Click OK to proceed. Now we have a new created normal (active) Device. Let's convert it to a template by suspending it. Right-click the Device ( ) and select Edit Device Properties ( ):

Switch to General Device Properties (

) tab and check Suspend Device :

2000-2013 Tibbo Technology Inc.

1266

AggreGate Documentation

Click OK to suspend the Device. Its icon will become gray to indicate that it's not active anymore:

The methods for deactivating a system resource when converting it to to a template may differ. Alerts 216 , trackers 257 , and most of other "active" resources have an Enabled property. It must be switched off when resource is used as a template. Non-active resources, i.e. resources that do not perform any activities themselves (such as reports 241 ), do not need deactivation. Our template is just a normal suspended device for AggreGate. Another reason to suspend a Device (other than make a template out of it) is to temporarily pause all operations with a certain piece of hardware.

Now drag our template and drop it to (over) the Device Templates group (

):

The template will be added to the group:

3. Using the template

To create a new Device based on a template, we need to clone the template itself: Right-click it and select Make Copy ( )

Enter name and description for the Device to be created Click OK to create the Device Finally, it's necessary to activate the new Device: Right-click the Device and select Edit Device Properties ( Switch to General Device Properties ( Click OK to save properties Your new Device, based on the template, will now operate normally: )

) tab and check Suspend Device

2000-2013 Tibbo Technology Inc.

Tutorials

1267

Another method to use a template is drag-and-dropping a template to any "container" context and executing Create From Template 905 action.

12.14 Keeping History of Object Changes

While AggreGate database should be periodically backed up 104 , it might be useful to keep history of important system object's changes. For example, if a certain widget 312 has complicated template, it may be very helpful to track down every change to detect and revert erroneous modifications. This short tutorial explains how to activate and view historical changes for any system object or object group.

1. Finding Out Object Context Path

At first step, it's necessary to figure out context path 863 or context mask 865 of objects those history should be stored. Point mouse over the object node in System Tree 784 to view context path in the tooltip. In the below image, the context path of Ping Time Chart widget is users.admin.widgets. chartAvailabilityPingHelper.

Right-click on the widget node and select Copy (

) from context menu to copy context path into clipboard.

2. Enabling Change History Storage

Every time a certain "user-level" property of any system object is modified, AggreGate Server generates a change 891 event. We need to enable historical values storage for this event to be able to access object property change history. The generic way to enable persistent storage for AggreGate events of any type is using global Event Expiration Times
70 table. To access this table, right-click on AggreGate Server node ( Server :

) in System Tree and select Configure

2000-2013 Tibbo Technology Inc.

1268

AggreGate Documentation

Switch to Event Expiration Times tab and click Add Row icon (

) to add new record, then:

Paste previously copied context path in Context Mask field, or enter it manually Type change in Event Name field Select desired change history storage period in Expiration Period field Use context mask instead of path to enable history storage for multiple objects. For example, users.*. widgets.* will enable storage for all widgets owned by all system users 108 . Click OK to finish global configuration editing. You don't need to restart the server after this change.

3. Viewing Change History

Once the change history is enabled, you may edit properties of your object as usually. To access the change history, right-click on a property in Properties Editor
795

and select View Variable History (

):

2000-2013 Tibbo Technology Inc.

Tutorials

1269

The history will open in a new window:

12.15 Scheduling Device Downtime

Often, a device should undergo maintenance during a pre-determined period of time. This means that device will not be available for AggreGate during that period and it should not be synchronized 126 with the server. The system should not generate any warnings about device unavailability during such scheduled downtime. This tutorial illustrates how to use a device dependency expression time.
124

to suspend device synchronization for a specified

Although dependency expressions are most often used to check the status of another device and disable synchronization if said device is down, they may be also used to check the current time.

Scheduling Downtime for an Absolute Time Period

In this case, we'll set up a dependency expression that resolves to FALSE within a certain span of time and to TRUE otherwise. We'll use the now() function that returns current timestamp (i.e. time of dependency check) and date() function that constructs a timestamp from year, month, day, hours, minutes, and seconds arguments. Descriptions of these functions are available in expression functions reference 916 . Note that month argument of date() function is zerobased, so we must pass 0 for January. Let's schedule device downtime for 08 Feb 2010 from 18:00 to 20:00. Here is our dependency expression:

now() < date(2010, 1, 8, 18, 0, 0) || now() > date(2010, 1, 8, 20, 0, 0)

Device account properties in AggreGate Client:

2000-2013 Tibbo Technology Inc.

1270

AggreGate Documentation

An expression that schedules a whole maintenance day:

now() < date(2010, 1, 8, 0, 0, 0) || now() > date(2010, 1, 9, 0, 0, 0)

Scheduling Periodic Downtime

Same method may be used to schedule periodic downtime. In this case, dependency expression will use some other date/time processing functions to check the output of now() function. Here is a dependency expression that disable device synchronization every Monday:

dayOfWeek(now()) != 1
Note, that dayOfWeek() function returns zero for Sunday. "Not equals" operator is used, as the dependency expression must return TRUE (to enable sync) when the current day is not Monday. To schedule downtime every Wednesday from 22:00 to 23:00:

!(dayOfWeek(now()) == 3 && hour(now()) > 22 && hour(now()) < 23)

An alternative method to schedule device downtime is using the Job Scheduler Device 124 property of a Device Account at certain time.
266

to enable/disable Suspend

12.16 Selecting and Processing Events

It's often necessary to find, filter, and somehow aggregate a certain number of system or device events be useful for: Making a report
241 260 880 .

This may

Creating and filling a common table Processing events using a script Manually browsing of event data
628

The common denominator of all above tasks is that we should extract selected historical events from the AggreGate Server database 80 and convert them to a data table 854 . This data table would then be used to fill in a report or common table, feed the script with input data, or just presented to the operator. There are three different ways to select the events and convert them to a data table: Using AggreGate expression language
911

2000-2013 Tibbo Technology Inc.

Tutorials
Using an AggreGate query
271 72

1271

Using a custom event writer using native SQL

to store events in a separate table and the database device driver

180

to fetch them

Here is a brief comparison of these methods: Expression Language Fetching and filtering performance Aggregation (totals, averages, min/max, etc.) Memory consumption Event storage overhead Method selection hints: If you need to process a large number of events (100000+), use native SQL If the number of events is not so large, but some aggregation is required, use AggreGate query language In all other cases use expression language High Not available Medium None Query Language Low Available High None Native SQL High Available Low Doubles disk usage

Selecting Events Using AggreGate Expression Language

To select some events using the expression language, use the Get Event History 695 function of the Events context. Specify context name/mask, event name, filtering expression and start date in the input parameters. For example, let's make a report showing Login 758 events for user john. This report's Source Data Expression 241 will call Get Event History function having another expression (used for filtering events) specified as a string in the function parameter list:

{events:get("users", "login", "{username} == 'john'")}

Note that the last parameter (Start Date) is omitted and default NULL value will be used for it.

Selecting Events Using AggreGate Query Language

In this case, we fetch raw event data using the same Get Event History described above, but without specifying a filtering expression. We then run an AggreGate Query on this table, for filtering and aggregating the data using standard SQL operations. For example, here's a query that will return all Login events of user john (see above):

SELECT * FROM events:get("users", "login") as logins WHERE logins.get$username = 'john'

To call use this query as a report Source Data Expression, use the following expression:

{:executeQuery("SELECT * FROM events:get('users', 'login') as logins WHERE logins. get$username = 'john'")}

Selecting Events Using Native SQL

This method is the most difficult in terms of configuration, so it should be used only if the other methods are not suitable. To fetch events using native SQL, do the following: Set up a custom event writer 72 that will store a certain event in a dedicated database table with event-specific fields. The table will be created automatically by the event writer. Examine the structure of the table using your database management utility to find out what fields are available. Create a new Device
113

and choose SQL Database as a device driver

Copy settings of the Database device (Database Driver, URL, username, password, etc.) from the AggreGate Server

2000-2013 Tibbo Technology Inc.

1272

AggreGate Documentation
55

global database configuration

.
182

After that, you may execute any SQL query on the custom events table using the Execute Query operation by Database device driver. Example: to select events using native SQL use the following report Source Data Expression:

provided

{users.admin.devices.linkserver_database:executeQuery("SELECT * FROM logins WHERE username = 'john'")}

12.17 Creating Consumption Reports

This tutorial explains how to create consumption reports based on aggregated values of consumables counters. Such a report can summarize hourly/daily/weekly/monthly/yearly consumption of the below and similar metrics: Energy consumption (watt-hours) Flow rates (cubic meters) Equipment run times (hours)

CALCULATING ENERGY CONSUMPTION

Suppose we have a device with a kW variable that accumulates consumed energy in kilowatts. The variable is a counter that contains number of kilowatts consumed by the device. We need to get the consumption information grouped by different periods: days, weeks, months, and years.

1. Creating Statistical Channel

We will use Statistical Process Control daily/weekly/monthly averages.
936

module to calculate consumption rates and aggregate them to get hourly/

First of all, we need to create a statistical channel. It will perform all calculations of the energy consumption rates. To create a statistical channel click Edit Device Properties device popup menu item, switch to Statistical Channels tab and add a new row to the channels table:

Next click in Parameters. You should see a parameters dialog. Enter a reference 925 to desired field as the Expression . Probably your kW variable will have a single field with the same name (kW). Thus, the expression text will be {kW}. You can perform any conversion here, for example convert kilowatts to watts by writing {kW} * 1000. This expression is evaluated on every change of variable (i.e. each time the device is polled). It must always result to a

2000-2013 Tibbo Technology Inc.

Tutorials
number.

1273

As far as kW is a consumed energy counter, set statistics channel type to Counter. This channel type calculates the change speed of counter, so channel value will be measured in kilowatts per seconds. You can get more information about statistics channel types here 942 . Finally, your channel options will look similar to this:

Selected Aggregation parameters means that Average, Minimum and Maximum values for each Storage Period (defined below) will be calculated. Storage Periods define history length for each aggregation rate: one hour of minutely statistics (average rates for each of last 60 minutes), one day of hourly statistics, etc.

2. Creating a Query to Get Source Data for the Consumption Report

Our consumption report will be based on a query 271 . To create a Report double-click on Queries Tree. Let's create a query with the following Query Text:
714

node in the System

SELECT stats.statistics$context, stats.statistics$end,

2000-2013 Tibbo Technology Inc.

1274

AggreGate Documentation

stats.statistics$average * 3600 FROM utilities:statistics("users.admin.devices.counterDevice", "kW", null, "hour") as stats

Here is the query configuration window:

This query calls statistics 767 function from Utilities following parameters to this function:

763

context to get the statistical consumption rates. It passes the

"users.admin.devices.counterDevice" - the path to your device, ? kW - the name of our statistical channel, ? null - the row key, not used in our case, ? hour - the aggregation rate (the query will give non-empty results if more than one hour has elapsed since weve created our statistical channel, but to debug it and see results earlier you can temporarily use minutes value here). The query selects three fields from functions result: ? stats.statistics$context - the device context, ? stats.statistics$end - the end timestamp of every aggregation period, ? stats.statistics$average * 3600 - the average per-second consumption value multiplied by 3600 seconds in hour. Once query creation is finished, you can execute it by double-clicking on it. You should be able to see the aggregated consumption table.

3. Creating Consumption Report

To create a Report opened window.
241

double-click on Reports

719

node in the System Tree. Enter Name and Description in the

Then click on the ... button to edit the Source Data Expression.

2000-2013 Tibbo Technology Inc.

Tutorials

1275

The Expression Builder 817 window will pop up. Now find your kW query in Server Data tree under Users/admin/ Queries. Expand it to see Execute Query node and double-click on it. Youll get {users.admin.queries.kW: execute()} string inserted into the expression.

This expression will execute the query each time the report is created. Click OK twice to close this and parent dialogs.

2000-2013 Tibbo Technology Inc.

1276

AggreGate Documentation

The Report Properties dialog will appear. Here you should correct report header names. First, click on Fields and then enter desired report column header texts in the Header column.

Click OK in both dialogs. You will be prompted to edit a report template afterwards, decline this request to skip launching Report Editor 826 . Thats it! Now you can run your report by double-clicking on it in the System Tree:

12.18 Predicting SLA Breakdowns

This tutorial describes how AggreGate can help with proactive management of devices, services and processes. This is done by alerting 216 operators if a numeric SLA threshold will be breached in the near future according to dynamics of statistical trend based on a certain metric. Here are some examples of alert configurations: Raise an alert if HDD load on a critical server will reach 95% in two weeks Raise an alert if an average availability of a multi-component business service will go below 99% in three months In our example we'll set up an alert that will be triggered if an average CPU load on a server will raise over 80% in one

2000-2013 Tibbo Technology Inc.

Tutorials
week.

1277

1. Creating Statistical Channel

First of all, we need to set up a statistical channel
936

for calculating daily CPU load averages on our server.

To create a statistical channel select Edit Device Properties from popup menu of a network device, switch to Statistical Channels tab and add a new row to the channels table:

Set the Variable to point to the variable containing the CPU load values. Open channel Parameters and set up the Expression that will return numeric values those SLA will be monitored by the alert. It's also a good idea to disable Storage Periods for all archive types except for Daily, since we'll use only daily data for analysis. To do this, right click inside any storage period and select Remove Value from context menu. Configure the length of Daily archive to ensure that the prediction will be based on statistical data of sufficient length.

2000-2013 Tibbo Technology Inc.

1278

AggreGate Documentation

2. Creating the Alert

Create a new alert 216 that will be raised upon a future SLA breach detection. Set up alert's notifications mail or SMS sending). Add one Variable Trigger
217 225

(such as

to the alert, and set it up as follows:

Context Mask: users.admin.scripts.slaBreakdown (SLA Breakdown Date Calculator script) Variable: childInfo (Properties) Expression: dateDiff(now(),

cell({users.admin.scripts.slaBreakdown:execute("users. admin.devices.criticalServer", "cpuLoad", 4, 0, 80)}), "day") < 7 && dateDiff(now(), cell({users.admin.scripts.slaBreakdown:execute("users.admin.devices.criticalServer", "cpuLoad", 4, 0, 80)}), "day") > 0

Delay: 0 ms The Check Period should not be very short, since the statistics-based SLA breakdown date calculation is a resourceconsuming task. 10 minutes or longer Check Period should be sufficient.

2000-2013 Tibbo Technology Inc.

Tutorials

1279

The most tricky part of this alert is its Expression . This expression refers the SLA Breakdown Date Calculation script 628 that is a part of AggreGate distribution. The reference {users.admin.scripts.slaBreakdown: execute("users.admin.devices.criticalServer", "cpuLoad", 4, 0, 80)} calls execute function from this script's context and passes the following parameters to it:

750

users.admin.devices.criticalServer - path of device context cpuLoad - name of statistical channel to get data from 4 - grouping time unit constant 1324 for daily grouping 0 - aggregation type constant 1324 for averaging 80 - the numeric SLA value

677

matching our target server

The script will return a date when daily averages trend will cross a 80% CPU load baseline. However, the date is returned wrapped into a Data Table 854 (since our reference calls a context function, and context functions always return Data Tables), so we need to use cell() expression language function 917 to extract the actual cell value (i.e. the SLA breach date). Finally, the expression uses dateDiff() expression language function during the next seven days.
916

to return true if the SLA breach will occur

12.19 Intelligent Baseline Alerts

Simple alerts are often configured to raise once a certain metric exceeds the pre-defined threshold. For example, an alert can be raised once CPU load on a server goes over 80% and holds there for longer than one hour. Such alert setup is good to ensure verification of well-established Service Level Agreements (SLAa). However, in some cases an alert should be triggered if spot value of a metric or its short-term average significantly exceeds its long-term average. This situation may point to a forthcoming problem, even if current value is still lower the the SLA level. This tutorial explains how to set up an alert that is raised if the last hour's average CPU load on a server exceeds its last month's average by 20 percents.

1. Creating Statistical Channel

First of all, we need to set up a statistical channel
936

for calculating CPU load averages on our server.

To create a statistical channel select Edit Device Properties from popup menu of a network device, switch to Statistical Channels tab and add a new row to the channels table:

Set the Variable to point to the variable containing the CPU load values. Open channel Parameters and set up the

2000-2013 Tibbo Technology Inc.

1280

AggreGate Documentation

Expression that will return numeric values those averages will be monitored by the alert. It's also a good idea to disable all Aggregation types except for Average. This will save some space in the statistics database.

2. Creating the Alert

Create a new alert SMS sending).
216

that will be raised upon serious baseline violation. Set up alert's notifications
217

225

(such as mail or

Add one Variable Trigger

to the alert, and set it up as follows:

Context Mask: users.admin.devices.criticalServer (context of the server those CPU load is tracked) Variable: hrProcessorTable (CPU Load Table) Expression: select(select({.:statistics}, "statistics", "name", "cpuLoad"), "average",

"period", 3) > select(select({.:statistics}, "statistics", "name", "cpuLoad"), "average", "period", 6) + 20

Delay: 0 ms The Check Period should not be very short, since the statistics-based baseline calculation is a resource-consuming task. 10 minutes or longer Check Period should be sufficient.

2000-2013 Tibbo Technology Inc.

Tutorials

1281

The Expression of this alert is somewhat complicated. It compares last day and last month CPU load averages by retrieving them from statistics 683 variable. Let's analyze the first part, select(select({.:statistics}, "statistics", "name", "cpuLoad"), "average", "period", 3). First, select({.:statistics}, "statistics", "name", "cpuLoad") retrieves statistical values for cpuLoad channel from the value of statistics variable. Second, select( statistics, "average", "period", 3) function returns a last day average (in percents) from the previous table. Numeric constant 3 matches Hour time unit
1324 .

The second part of expression obtains the last month average in the same way. Finally, if the last hour average is greater than the last month average by 20% or more, the whole expression will result to true and the alert will be raised.

12.20 Adding Links to Tables

AggreGate dashboards list:
617

providing overview of device infrastructure normally contain some tables. Those tables may

Devices that currently experience troubles of some kind Devices extremely high or low KPIs Other resources, such as device groups, network segments, etc. Such tables are useful by themselves, but operators would like that clicking a certain device name in any table row launch a certain action associated with this device, e.g. open its "personal" dashboard. This tutorial explains how to add links to any table.

Theory
The background of cell links is a bit complicated, so this part can be skipped if your objective is just adding links without understanding how they work. Technically, links are rendered in the table cells that use Reference renderer 857 . Value contained in the cell will be displayed as link anchor (i.e. link text). The link target, i.e. action that is triggered upon a click on the link, is contained in the editor options 856 . However, if we specify static editor options for the table field each cell in a row will lead to the same target. We need each cell to have its own target, so we use the following technique to set editor options dynamically: Add a new column to the table. Value of this column in each row contains a link target for the link contained in another cell of the same row. Make the above column hidden so that it won't be displayed in the table. Use a binding 860 to take value of the the above hidden field and set editor options of the link field. This binding works row by row, making editor options of all links individual.

Implementation
Let's assume we've a table showing temperature readings from multiple devices. It has two columns: Device (field name: device) and Temperature (field name: temperature). We want make the Device column clickable so that click on any device will open a dashboard associated with it (e.g. temperature chart).

1. ADDING HIDDEN COLUMNS

2000-2013 Tibbo Technology Inc.

1282

AggreGate Documentation

Values in the Device column are descriptions of devices, not their system identifiers. Thus we need to add a new hidden context column that will contain paths of device contexts 863 . There are many ways to do this. For example, if we're binding a query, we may add a link to CONTEXT_ID field: SELECT data$CONTEXT_ID AS context, data.info$icon AS icon, data.contextStatus$status AS status, data.info$description AS device, data.temperature$temperature AS temperature FROM users.*.devices.*:info:contextStatus:temperature Note that the query will result to the table with five columns: First column path of device context, it will be hidden. Second and third columns contains basic ID of device icon and device status. They will be used to display a device status icon next to the link. These columns will also be hidden. Fourth and fifth column will actually display device link and device's temperature reading. The query result will look like this:

AS

data

2. ADDING LINK BINDING

The binding this:
860

that should be added to the format of Data Table that represents results of the above query looks like

device#options='action/'+{context}+':configure$' + {icon} + ({status} != null ? '_' + {status} : '')

The binding target is device#options. It sets editor options in the each cell of the device column. The binding expression is 'action/'+{context}+':configure$' + {icon} + ({status} != null ? '_' + {status} : ''). It forms the editor options string, which is a reference 926 to an action 892 that should be launched upon link click. The actual editor options text returned by the above expression will look like this (example): action/users.admin. devices.thermometer1:configure$device_21. The above options instruct the system to launch configure action from context users.admin.devices. thermometer1 matching a thermometer device. The device_21 string means the ID of icon representing current device state. The configure action 677 opens device dashboard(s). Values for context name and device status/icon are taken from the hidden fields defined in our query. If you don't need icons next to links, you can remove second and third lines from the SELECT clause of the query and use a simpler binding:

device#options='action/'+{context}+':configure'
AggreGate queries have Output Format property 278 that was designed to add necessary decorations to the query results. To make our additional columns hidden and add the link binding we may use the following output format: <<context><S><F=H><A=>> <<icon><S><F=H><A=>> <<status><S><F=H><A=>> <<device><S><A=><D=Device><E=reference>> <<temperature><F><A=><D=Temperature>>

2000-2013 Tibbo Technology Inc.

Tutorials

1283

<B=<device#options='action/'+{context}+':configure$' + {icon} + ({status} != null ? '_' + {status} : '')> This output format makes the following necessary corrections to the default query output format: Sets hidden flag to context, icon and status columns Sets reference editor to the device column Adds the link binding That's it! Now we can refer this query from a dashboard to view temperature statistics on a first-line operator interface. The final table with links:

12.21 Opening a Pop-Up Report

How cab we invoke an visual object, for instance, a report from a widget? How to specify location for the window? Here are simple instructions for the task.

Creating a Report
For the start, let's create a report to be used in the example. To do that: Double-click the Reports context Provide a name (to be specific, let it be testReport) and description (say, Test Report) Simply press OK in the next window and then refuse to edit the report template (as we don't want to waste time now, this is just an example). Now we can check the report: double clicking its context and it should be opened in the sub-window on the right.

2000-2013 Tibbo Technology Inc.

1284

AggreGate Documentation

Creating a "Calling" Widget

Double-click the Widgets context and fill-in its name; here, you can use any name (and description) you like, we won't use them; leave default values for other fields. A GUI Builder window should appear with an empty form. Drag-n-drop a button from component toolbar to the form. Note, the button is named button1.

2000-2013 Tibbo Technology Inc.

Tutorials

1285

We want to open the report named testReport when a user clicks this button. To provide that, we have to bind the click event with the invocation of the report's Show action. To add the binding, right-click the button and select Edit bindings menu item. In the open window press green button with "plus" sign on it to add a new binding. For the added record clear the On start check box, leave the On event flag set and ensure Periodically is not set. To specify an expression for the click event in the Activator field. Good news is you don't have to remember cryptic expressions like the one we are going to set up. Just click the ... button in the field. That brings the Activator window. Open the Component Event tab in the panel on the left and select the Click item under the button1 node on the left.

2000-2013 Tibbo Technology Inc.

1286

AggreGate Documentation

Now click OK and make sure the following expression is there in the Activator field:

form/button1:click@
Done with the activator, we have to attach an action to perform on the event. In our case, the action can be specified in the Target field as follows: click the ... button in that field, selection the Action tab in the Action window, and in the tree on the right select sequentially Users -> admin (Administrator) -> Reports -> Test Report and, finally, the action Show Report there.

2000-2013 Tibbo Technology Inc.

Tutorials

1287

Press OK and check the expression:

action/users.admin.reports.r:show
Now we are ready to check our widget. So, save it and start. Click the button in the opened widget and see the Test Report is opened in a separate tab within the Main Dashboard. Note, that system automatically switched to the main client window to show the report.

2000-2013 Tibbo Technology Inc.

1288

AggreGate Documentation

Specifying Location for the Report

At this point, location for our report is selected automatically. Often, this is not what we want. For example, if our control widget is in a dashboard then the report will be opened in the same place within new tab. This can look ugly, as there can be not enough place to show the whole report while layout of other dashboard components will be broken. In our case, for example, it would be better to open the report in a "floating" window. Then the report window can be maximized as needed not affecting dashboard layout. To implement this, get back to the open widget and close it. In the GUI Builder, open the button's bindings and type the following line in the Expression field:

table("<<location><T>>", table("<<state><I>>", 1))

Here, we specify additional parameters for the action we invoke on click. All action parameters should be put in a single table. The show action expects window location to be specified in the field named location. This field should contain another table specifying the location itself. For the full description of Window Location table refer to the specific topic 955 . Now, we want to set window state for "floating", which is encoded with integer 1 in the state field. Using the table function we create a table having only one integer field named as state (the table format is <<state><I>>) and provide 1 as it's value:

table("<<state><I>>", 1)
Then, with the help of the same table function, we put this table as a value for the location field:

table("<<location><T>>", table("<<state><I>>", 1))

Save the widget, run it and be convinced that the button click now opens the widget in a floating window

2000-2013 Tibbo Technology Inc.

Tutorials

1289

12.22 Using Multi-level Subwidgets

AggreGate widgets 312 allow building very complex layouts by combining multiple containers of diverse types, using different container layouts (absolute or grid), and nesting containers into each other. However, this is not enough to build dynamic layouts those "overall" component structure (and not just component parameters) dynamically change depending to the environment. Such dynamic widgets can be built using nested subwidgets 382 those template is selected and changed on-the-fly during widget operation. This tutorial illustrates the following concepts of dynamic widget templates: Using multiple levels of nested subwidgets Changing subwidget template references in the runtime mode Passing parameters to subwidgets

Source Data
To illustrate concepts of subwidget nesting, we'll develop a number of widgets that visualize status and contents of a vending machine. Modern vending machines are remotely monitored and audited via GPRS, providing near-real-time data about remaining goods, as well as diagnostic information. To make the tutorial short and simple, we've modeled 303 a very simple snack vending machine that provides a table describing dispensers installed into machine's slots, types and capacity of those dispensers, types of goods loaded in those dispensers, and quantity of remaining snacks. The machine provides a Contents (contents) table with the following fields: Slot - description of a dispenser Type - type of the dispenser (small, medium, or large) Product - name of product currently loaded into the dispenser Quantity - number of snacks that's currently contained in the dispenser Capacity - current capacity of the dispenser

2000-2013 Tibbo Technology Inc.

1290

AggreGate Documentation

Here is how the Contents table look like:

Thus, our machine has six slots with dispensers of different types installed into them. We assume that each slot is capable of containing a dispenser of any type (Small, Medium or Large). In our case, slots Slot1 and Slot2 contain Small dispensers, Slot3 and Slot4 contain Medium ones, while Slot5 and Slot6 are occupied by Large dispensers. This a dynamic layout configured by engineers during machine installation. Below is a screenshot presenting format of machine Contents table:

Machine Layout Widgets Structure

Our machine will be rendered by a single widget called Machine Layout. The widget will contain components providing generic information about the machine and a number of subwidgets for rendering dispensers. Each of these subwidgets will be called Dispenser Layout , and number of Dispenser Template subwidgets will match number of available dispenser types. Our demo machine model defines three dispenser types: Small (code: 1), Medium (code: 2) and Large (code: 3). Thus, we need to design three Dispenser Layout widgets for using them as subwidgets in a Machine Layout.

Designing Dispenser Layouts

Let's start with designing a first machine layout widget for rendering Small dispensers. First, we create an absolute 314 widget and name it dispenser_1, with description Small Dispenser Template. The name is important here, since we'll need to dynamically refer dispenser template widgets by their names depending to types of dispensers installed in

2000-2013 Tibbo Technology Inc.

Tutorials
a machine. The widget must use grid layout 318 to make the whole machine contents rendering system scalable for different machines and screen resolutions.

1291

Note that dispenser template subwidget's size can be set to anything convenient for debugging, but running subwidget will be "pushed" in a certain section of top level widget's template, leaving it undefined (and possibly small, if top-level widget is scaled down to a low screen resolution) amount of space. Thus, subwidget's template should be designed to fit into a small screen space. Our simplified dispenser template will contain four label Product name label Quantity label Capacity label Separator label for showing capacity usage as "quantity / capacity" It's of course possible to show both quantity and capacity on a single label by concatenating several strings in a widget binding expression 606 . The grid layout structure of a dispenser template is shown on a screenshot below. Note, that cell decorations enabled for taking an easily understandable screenshot: were
323

components:

831

In the real life, templates of different dispenser types can look completely different. In our tutorial, we'll make Medium and Large dispenser templates differing from a Small one just by increasing font size. This is enough to illustrate the idea.

Designing Machine Layout

Machine layout widget is a relative 314 widget that's generally attached to vending device accounts 113 . The Validity Expression 948 of Machine Layout widget should check certain device parameters so that a correct layout will be used to

2000-2013 Tibbo Technology Inc.

1292

AggreGate Documentation

render device contents. In our tutorial, we'll have just a single machine layout that will be attached to the context of our vending device model. Our machine layout widget will be named machine_layout. Our simple machine layout widget consist of two vertically aligned parts: A header label showing machine description A panel containing six dispenser subwidgets Here is how it looks like in GUI Builder's work form (decorations enabled):

Dynamically Assigning Subwidget Templates

The type of dispenser currently installed in a slot is defined by Dispenser Type (type) field of Contents table. Thus, we need six bindings that change Reference property of Subwidget components 382 during main widget startup. Here is how subwidget template bindings should look like: Target Expres sion Activat or Conditi on Option s

form/slot1:reference 'users.admin.widgets.dispenser_' + select({.:contents}, "type", "slot", "Slot1")

On Startup

This binding changes template reference of subwidget representing contents of Slot1. It's evaluated upon main widget startup. Its expression constructs context path 863 of subwidget that should be used to render current slot contents. This is done by concatenating context path prefix (users.admin.widgets.dispenser_) and value of dispenser type installed in the slot (returned by selecting value of type field from contents table row those slot field equals to

2000-2013 Tibbo Technology Inc.

Tutorials Slot1).

1293

Declaring Dispenser Subwidget Parameters

Each dispenser subwidget should visualize contents and status of a specific dispenser. Thus, the subwidget must have several parameters allowing it to independently load necessary data from the server. In our tutorial these parameters are: Path of a machine's device context 677 pointing dispenser subwidget to the specific machine (the device context will be substituted by a model context 303 in our tutorial) String ID of a slot those contents are represented by the instance of dispenser subwidget See Subwidgets
382

article for more information on subwidget parameters.

To define a dispenser subwidget parameter: Open the template in GUI Builder Select Root panel
376

in the Resources tree

835

833

Right-click in any cell of Properties grid Select Add Custom Property Properties to add:

Property named device with a single String field also named device (leave all other settings at their defaults) Property named slot with a single String field also named slot (leave all other settings at their defaults)

Binding Dispenser Subwidget Parameters to Its Visual Components

The machine layout widget will create a separate instance of dispenser subwidget for each dispenser in a machine. Each subwidget will receive device and slot property values from the top-level widget. Now we need make use of these values within our dispenser subwidgets. In our case, all three dispenser subwidgets will be similar, but they can significantly differ in real life. Dispenser subwidget bindings are probably the most complex in a whole structure, hence quite simple. Here is a example of a binding that shows name of loaded product in the product Label 323 : Target Expres sion Activat or Conditi on Option s

form/product:text select(getVariable({form/:device$device}, "contents"), "product", "slot", {form/:slot$slot})

On Startup

The binding is activated just once on subwidget startup. If loads contents variable from a machine context pointed by the device parameter (referred to as {form/:device$device}). Once the whole contents table is loaded, the binding expression selects value of product column from the record where slot column equals to value of slot subwidget parameters (accessed via {form/:slot$slot} reference). Expressions of two other bindings showing current product quantity and dispenser capacity differ from the above one only by other fields selected instead of product field. Here is how resulting dispenser subwidget's binding table looks like:

2000-2013 Tibbo Technology Inc.

1294

AggreGate Documentation

Testing Dispenser Subwidgets

Despite relative simplicity of dispenser subwidgets, it may take some time to test and debug them. Debugging subwidgets running inside the machine layout widget will introduce unnecessary level of complication, but it's fortunately possible to test it independently by manually specifying values of device and slot parameters: Open dispenser template in GUI Builder Select Root panel
376

in the Resources tree

835

833

Right-click in any cell of Properties grid Switch to Custom Properties tab

Set device parameter to users.admin.models.vending_machine (that's the server-side context path of our machine model context; the path should generally point to a test vending machine) Set slot parameter to Slot1 to test dispenser subwidget on contents of Slot1 Start subwidget by clicking on a toolbar icon ( )

The widget will display contents of test machine's Slot1:

2000-2013 Tibbo Technology Inc.

Tutorials

1295

Creating Other Dispenser Subwidgets

Once the Small dispenser subwidget template is finished and tested, make two copies of it using Make Copy action ( ), assign proper names/descriptions to the copies (make sure the names to match dispenser_X pattern!), and perform necessary changes to make other dispensers look different.

Binding Slots Inside the Machine Layout

We've now approached the final step of out tutorial. The last task is supplying correct run-time values of device and slot parameters to each dispenser subwidget within the Machine Layout widget. device parameter is assigned by a group of six similar bindings: Target Expres sion Activat or Conditi on Option s

form/slot1:device dc()

On Startup

This binding assigns custom property device of subwidget component slot1 to path of Machine Layout widget's default context 315 (returned by dc() function). Here is how finalized All Bindings table of Machine Layout widget looks like:

2000-2013 Tibbo Technology Inc.

1296

AggreGate Documentation

Properly assigning slot property is a little bit tricky. Each dispenser subwidget in a slot should receive its own static parameter value (Slot1, Slot2, etc.). However, if we select subwidget components in a Work Form, we won't see Custom Properties tab in Properties window because there's no static template assigned to them. To be able to specify slot parameter, we need to manually set each subwidget's Reference parameter to path of any of our dispenser subwidgets. Once done, we shoult set slot parameter of our subwidgets to Slot1, Slot2, etc. In All Bindings table of our Machine Layout, bindings changing dispenser subwidget templates (Reference properties) must precede binding that set those subwidgets' internal parameters (device and slot). In this case parameter values will be received by "correct" dispenser subwidgets.

Testing Machine Layout Visualization

Since all widgets composing machine contents rendering system are now finished, we can start testing and using them. To view a certain machine's layout, select Machine Layout widget launch action ( machine device (or model in our case). Here is how the result looks like: ) from context menu of a vending

2000-2013 Tibbo Technology Inc.

Tutorials

1297

What's Next
The described vending machine rendering system can be further extended by: Developing widgets for different machine layouts and dispenser types Introducing more complex machine structure (e.g. machines with multiple compartments containing changeable multidispenser holders) Color-coding dispensers depending to quantity of remaining goods Designing professionally looking layout widgets

13 Troubleshooting
This section is designed to provide solutions and explanations for common problems related to different components of AggreGate.

13.1 AggreGate Server Startup Problems

AggreGate Server may show an error message on startup or appear to start successfully but not accept incoming connections from Device Servers or clients. This probably means there were some serious or critical errors during server startup. Check AggreGate Server log file to find out the actual reason of error. By default, this file is called server.log and it is located in AggreGate Server installation directory. See Configuring Logging 74 section for more information about logging. Sometimes critical errors displayed in the error dialog are caused by some smaller problem that can be traced back using the log file.

2000-2013 Tibbo Technology Inc.

1298

AggreGate Documentation

The JVM could not be started. The main method could have thrown an exception.
This message means a critical error occurred during JVM startup. To see the exact error message that should give troubleshooting hints use ag_server_console launcher 44 to start AggreGate Server. Under Windows, the console window may disappear before you read the message. In this case, use command line interpreter to start ag_server_console. For that, go to Start Menu > Run, type cmd and click OK. The command line interpreter window will open. Now type %path_to_AggreGate Server%/ag_server_console to start the launcher.

Could not reserve enough space for object heap

You may see the following message when trying to start AggreGate Server:

Error occurred during initialization of VM Could not reserve enough space for object heap The JVM could not be started. The main method may have thrown an exception.
It means that the Java Virtual Machine cannot allocate the amount of memory specified by -Xmx (maximum memory) launcher file parameter 46 in a single contiguous block. There are several possible solutions: Decrease the value of -Xmx parameter if your AggreGate Server is not under a hard load Try to free up some memory by unloading the applications of rebooting the machine Add more RAM to the machine AggreGate Server is running on Under Windows, some applications may register their dynamic libraries (DLLs) to be located in memory at a certain absolute address. This separates the memory into several blocks and does not allow the AggreGate Server JVM to allocate a large single block of memory. To fix that, use a registry editor to remove all entries from

HKEY_LOCAL_MACHINE\Software\Microsoft\WindowsNT\CurrentVersion\Windows\AppInit_DLLs.
Be sure to make a backup first!

Error starting database service

This error means that server was not able to establish connection with the database 80 . Normally the root cause of the error is appended to the error message. If the root cause cannot be identified by reading server startup error message, try the following: Disable database connection pooling
58

Try starting the server and wait until error message pops up Browse the end of server log
74

file (server.log by default) to find out the root cause of database problems

If you're using the bundled MySQL database, it is likely that MySQL service failed to start. Check % aggregate_folder%\mysql\data\*.err files for errors. Since bundled MySQL server is configured for high performance, it may not be able to allocate enough buffer memory on some PCs. In this case, decrease values of innodb_buffer_pool_size and innodb_buffer_pool_size parameters in MySQL configuration file (% aggregate_folder%\mysql\my.ini).

Server Was Started But Clients Cannot Connect

If AggreGate Server was launched but it's not possible to connect to it using AggreGate Client and Web Desktop, it may happen that server startup is still in progress. Check server log file (server.log) to see whether the server is executing a long operation, such as database maintenance. Please contact Tibbo technical support if server startup is regularly taking longer than 3-5 minutes.

13.2 AggreGate Server Runtime Errors

This section covers different runtime errors that may be diagnosed using AggreGate Server logging facility system events 880 .
74

or

"Unable to create new native thread" errors are logged

This message means that operating system does not allow Java Virtual Machine to create a new thread. There are

2000-2013 Tibbo Technology Inc.

Troubleshooting
several solutions for this problem: If your server uses models them.
303

1299

or widgets

312

running in the server VM, decrease number of parallel bindings used by

46

Decrease maximum memory available to JVM threads. Decrease thread stack size
46

(JVM heap size). This increases memory available for individual

Switch to a 64-bit operating system and Java virtual machine.

"Out Of Memory Error: Java Heap Space" errors are logged

This error means that your Java Virtual Machine has run out of memory. The solution is to increase maximum memory available to JVM 46 .

"Out Of Memory Error: PermGen Space" errors are logged

This error means that your Java Virtual Machine is out of memory for storing loaded classes. The solution is to increase value of -XX:MaxPermSize parameter in server launcher properties files 45 .

"java.net.SocketException: Too many open files" errors are being logged by AggreGate Server running under Linux
This situation occurs when AggreGate Server opens a large number of sockets while communicating with networked devices (e.g. via SNMP protocol). To solve this issue, add the following line to the beginning of AggreGate Server startup scripts (ag_server, ag_server_console and ag_server_service):

ulimit -n 100000
This command increases the limit of open files allowed for the AggreGate Server to 100000. Server startup scripts will be re-created during server upgrade, so this instruction must be re-added once the server was upgraded.

13.3 AggreGate Server Not Responding

Sometimes, there may be situations where the server cannot be accessed, but is still running. You can see that the process is running, but when trying to access the Web Admin 632 interface of connect to it using AggreGate Client 776 , the request times out. There are several common causes of this behaviour: 1. AggreGate Server has not enough memory 2. AggreGate Server is using swap memory 3. AggreGate Server causes high CPU load 4. AggreGate Server is running with errors 5. Access to AggreGate Server is blocked by firewall

AggreGate Server Has Not Enough Memory

Memory shortage is the most common cause of low server performance and hanging. The server will never use more memory than specified by -Xmx parameter located in server_*.vmoptions files. The more actual memory usage approaches this limit, the more CPU time is spent for Java garbage collection (memory cleanup). If the server will try to allocate more memory than allowed by -Xmx parameter, it will spend all CPU time while trying to release memory, becoming effectively unresponsive. Try increasing value of -Xmx parameter to 50% of server machine RAM if server database machine and to 75% of RAM if using standalone database server.
80

is located on the same

AggreGate Server is Using Swap Memory

AggreGate Server is based on Java platform those dynamic memory management is very sensitive to swapping. Simply

2000-2013 Tibbo Technology Inc.

1300

AggreGate Documentation

speaking, if contents of memory allocated by a Java application are transferred to a swap space by the operating system, the application's performance is dramatically decreased, making is almost unresponsive. The maximum memory size AggreGate Server will use is defined by -Xmx parameter located in server_*. vmoptions files. If this value is set too high, server will allocate a lot of memory, and the underlying OS will likely move certain parts of those allocations to a low-performance swap space. Use swap usage diagnostic tools (such as smem for Linux) to make sure that AggreGate Server doesn't use swap space. If it does so, decrease value of -Xmx parameter (however make sure server has enough memory for its operation) or increase server machine RAM.

AggreGate Server Causes High CPU Load

It may happen that AggreGate Server consumes nearly 100% of CPU time. This situation is often caused by wrong settings of different system objects, most likely short polling periods or other frequent periodic actions. To find the root cause of high CPU load, disable system resources type-by-type. If the CPU load decreases to the normal value after disabling resources of a certain type, enable them back gradually to find one those settings cause high CPU load. 1. Suspend all devices. Synchronization settings of a device may cause frequent polling that consumes a lot of CPU time. 2. Disable all alerts. Some alert's trigger may have too short check period or refer an expensive operation (such as a query). 3. Disable all trackers. One of them may be calculated too often or refer an expensive operation. 4. Disable all scheduled jobs. A job may have triggers that cause its too frequent execution, or the job itself may consume a lot of CPU time even if executing only once. 5. Disable all widgets . Despite widget is running on a client computer, it may refer some expensive server-side operations, causing high CPU load. It may be hard to control the server under heavy CPU load. To avoid that, try starting AggreGate Server in safe mode 106 . Delete or fix resources that consume CPU power and restart the server in normal mode.

Server Is Running With Errors

Check server log file
74

to find out the reason of server failure. If the log file does not help to resolve the situation:
47

Shut down the server (see server shutdown

for details)

Restart the server in console mode (use ag_server_console executable) Check console output for any errors that crop up

Connection Is Blocked By Firewall

It may happen that AggreGate Server appears to start successfully, but you cannot connect to it using AggreGate Client or browser. No failed connection attempts are visible in the server log file. In this case, try to disable any firewalls running on AggreGate Server machine. These firewalls may prevent the server from accepting client connections. If AggreGate Server is running as a service 46 , it may be necessary to manually add the following ports to the firewall exceptions list in order to allow AggreGate Server to accept connections on these ports: Port 6460, TCP (AggreGate Client
776

connections)

Port 6450, TCP (Device Server 1003 connections) Port 6440, TCP (Net Admin
49

connections)
632

Port 8443 (Secure connections to Web Desktop

and Web Service

632

976 ) 976 )

Port 8080 (Non-secure connections to Web Desktop Port 161, UDP/TCP (SNMP Traps
178 )

and Web Service

2000-2013 Tibbo Technology Inc.

Troubleshooting

1301

13.4 AggreGate Server Connection Problems

If connection to the AggreGate Server fails, check the following: Make sure that AggreGate Server is running (e.g. find AggreGate Server tray icon AggreGate Server Startup Problems 1297 section for troubleshooting server startup.
108

in the system tray). See

Check that firewall running on the AggreGate Server machine is not preventing incoming connection attempts. Firewall should allow incoming connections to TCP port 6460 (AggreGate Clients 776 ), TCP port 8443 (Web Desktop secure connections), and TCP port 8080 (Web Desktop 632 non-secure connections). Try completely disabling the firewall.

632

Make sure you've specified the correct address and port of AggreGate Server in server connection settings (if using AggreGate Client) or your browser address bar (for Web Desktop). If Server IP Address 54 is specified in the AggreGate Server global configuration settings, make sure that you are trying to access the server using this address. It is possible that AggreGate Server accepts incoming connections on non-standard ports. Check server global configuration settings to find out the current client port number 55 and Web desktop port numbers (secure 60 and non-secure 60 ).

13.5 AggreGate Client Runtime Errors

This section covers different runtime errors that may be diagnosed using AggreGate Client logging facility
848 .

"Unable to create new native thread" errors are logged

This message means that operating system does not allow Java Virtual Machine to create a new thread. See available solutions here 1298 .

13.6 Performance Optimization

AggreGate is a complex system and its overall performance is affected by many factors. This article provides several performance optimization hints for different components of the system.

Switching to an External Database Server

The default AggreGate AggreGate Server distribution bundle includes an embedded database engine that may be used for test installations and production use with small number of devices. If your installation is likely to grow beyond 30100 devices, it's recommended to use an external database server. For very large environments with thousands of devices, the use of dedicated physical database server highly recommended. Please, check the following sections for more information: AggreGate Server Database
80 81 1302

is

Switching To Another Database Engine

All data stored in AggreGate Server embedded database is loaded in memory during server startup. If your AggreGate Server consumes a lot of memory with relatively small number of devices, check size of /db subdirectory in the AggreGate Server installation directory. If it is occupies more than 100-200 megabytes, consider switching to an external database server. The database server documentation usually has its own Performance Optimization section. Check database server administrator's manual for more information on maximizing database performance in your environment.

Upgrading AggreGate Server Hardware

AggreGate Server is the central component of the system and if its performance is significantly degraded it will affect every other system component. Two key factors affecting the server performance are: Number of processors/cores and their frequency Amount of RAM installed

2000-2013 Tibbo Technology Inc.

1302

AggreGate Documentation

The recommended hardware parameters can be found in System Requirements 40 section. However, some device drivers require a lot of memory and/or processing power for device communications. Generally, AggreGate Server should be moved to a higher performance server if the long-term average CPU load exceeds 50%. Such a high load rate may cause problems or even loss of device data during peak loads. Memory concerns should be raised in the following cases: If extensive use of virtual memory (swapping) or page fault rate is detected If AggreGate Server response time and request processing speed decreases within a certain time after it was started If java.lang.OutOfMemoryError: Java heap space messages appear in the server log file The recommended sequence for troubleshooting memory issues: 1. Increase the memory limit
1302

for AggreGate Server Java Virtual Machine

2. Add physical RAM to the machine running AggreGate Server 3. Switch to a dedicated database server
1302

Increasing AggreGate Server JVM Memory Limits

Memory concerns should be raised if AggreGate Server Memory Usage tracker 260 reports values higher than 90%. It is important to know that AggreGate Server's Java Virtual Machine, just like any other JVM, will never use all RAM available on the machine it's running on. JVM memory use is controlled by two parameters: Initial amount of memory allocated by JVM Maximum amount of memory that can be used by a JVM These parameters are described here
46

If Memory Usage tracker reports a high memory usage percentage, it's necessary to increase a mamimum amount of memory (-Xmx) parameter in the AggreGate Server Launcher Properties file 45 . Values up to the half of available physical RAM are recommended. Setting the maximum amount of memory too high may cause AggreGate Server startup problem, as JVM needs this memory to be available in a single contiguous block (see details here 1298 ). If you experience such a problem, the installation of additional physical RAM is recommended.

Switching to a Dedicated Database Server

In very large AggreGate installations with thousands of devices, AggreGate Server is usually working under a heavy load while receiving millions of events and performing hundreds of simultaneous synchronizations 126 . All data is stored in the database 80 . In some cases, even a multi-processor system with more than 4 cores is not enough to perform all data processing. For such large installations, having both AggreGate Server and database server running on the same machine may cause serious performance degradation. We recommend hosting your database server on a dedicated machine that is connected to the AggreGate Server's machine via a high-speed network interface (such as Gigabit Ethernet). Consider switching to a dedicated database server if: There are more than 3000 devices managed by a single AggreGate Server installation Your database contains more than 50 million events There are devices those event history contains more than 1 million events (and, thus, there are database tables with more than 1 million rows) Amount of RAM required for good performance of your database server is more than 50% of physical RAM installed in the machine running both AggreGate Server and database server The overall performance of your AggreGate installation is slow due to the high CPU load or disk paging

Tune Up Database Connection Pool Size

AggreGate Server Database configuration Minimum connection pool size Maximum connection pool size
55

has two options that significantly affect system performance:

2000-2013 Tibbo Technology Inc.

Troubleshooting

1303

A connection pool is a cache of database connections maintained by the database so that the connections can be reused when the database receives future requests for data. Connection pools are used to enhance the performance of executing commands on a database. There are several general rules for tuning up the pool size: Maximum connection pool size should be larger than the number of simultaneously connected devices with a high data transfer rate (i.e. frequent synchronizations or large number of device-generated events). For example, if you monitor 2000 devices that are polled once per hour you may leave maximum pool size as low as 200, but if you have 500 devices synchronized with the server every 5 minutes it's better to increase the maximum pool size to 500. Maximum pool size must be set lower than the total number of connections allowed by the backend database to avoid database-generated errors, such as "too many connections". For large installations where peak activity is significantly higher than average activity, it is recommended to increase the minimum pool size up to 20-50% of the maximum pool size.

14 Appendix
This is additional in-depth information that doesn't neatly fit anywhere else in the manual. It is "stuff you should know" to really gain an in-depth understanding of some elements used throughout the system.

14.1 AggreGate Communication Protocol

AggreGate Communication Protocol is used for communications between AggreGate Server 40 , AggreGate Agents 848 and AggreGate Clients 776 . Communication is performed through a single TCP connection. Both sides exchange commands. In this chapter, the originator of the commands is called client, and the other side is called server: In communications between AggreGate Server and AggreGate Client, originator (client) is AggreGate Client In communications between AggreGate Server and AggreGate Agent, originator (client) is AggreGate Server

Command Encapsulation
Commands are encapsulated using <STX> (0x02) and <CR> (0x0D) characters: <STX>command<CR> Commands are extracted from the data stream, and all other data is discarded. If there are two or more <STX> characters without <CR>, all data belonging to the current is discarded on each received <STX>: <STX>aaa<STX>bbb<CR> is treated as command bbb.

Command Structure
Each command consists of several parts separated by 0x17 (Command Separator) characters. The command separator character is represented by / in this manual. For example: <STX>aaa/bbb/ccc<CR> contains three parts: aaa, bbb and ccc. Thus, three characters are reserved and may not appear inside command parts: Character Code 0x02 Character Name STX

2000-2013 Tibbo Technology Inc.

1304

AggreGate Documentation

0x0D 0x17 Every command has the following structure:

CR ETB

<STX>command_code/command_parameters<CR> command_code is a single character, one of: M R Message command Reply command

command_parameters is one or more parameters specific to the command code and separated by /.

Commands Reference
MESSAGE COMMAND

The structure of this command is as follows (from this point, leading <STX> and terminating <CR> characters are not shown): M/message_ID/message_code/message_parameters message_ID is unique within the current session. message_code is a character, indicating the message type. Available message codes: S O E Start message Operation message Event message

message_parameters is one or more parameter(s) specific to the message code, separated by /.

REPLY COMMAND

R/reply_ID/reply_code/reply_parameters reply_ID should be equal to the ID of the message

1304

being replied.

reply_code parameter is a character that indicates type of reply. Available reply codes: A Success (May be followed by an optional data_table parameter, see Data Table Encoding 1306 ) Denied Error (May be followed by one or two parameters: error message and/or transferencoded error details string)

D E

Messages Reference
START MESSAGE

M/message_ID/S/protocol_version The format of this message is guaranteed to remain unchanged in the future. It should be sent by the

2000-2013 Tibbo Technology Inc.

Appendix

1305

client as the very first command during the data exchange with the server. The server returns an error if any other message is issued before the Start message was sent. protocol_version is an integer number indicating the version of the communications protocol supported by client. The current version is 2. Server responds to the Start command with a Reply command. If protocol version specified by client is supported by server, the reply code is Success, otherwise it is Denied. See description of the Reply 1304 command for more info.
OPERATION MESSAGE

M/message_ID/O/operation/context_name/entity[/data_table] The Operation command orders the server to execute an operation on a given context. Operation is a character specifying the operation to be executed. context_name is the name of the context for which the requested operation is executed. entity is an operation-specific parameter. It can be a variable name if operation is Set Variable, or a function name if operation is Call Function. List of available operation codes: G S C L R Get variable operation Set variable operation Call function operation Add event listener operation Remove event listener operation

data_table is an optional parameter containing operation specific data. See Data Table Encoding 1306 appendix for details.
EVENT MESSAGE

M//E/context_name/event_name/event_level/event_ID/event_listener_ID/data_table/ server_timestamp This message is sent to the client when an event named event_name fires in context_name and this client was previously added as a listener for this event. It does not require any reply from the client. If the event is persistent, the event_ID field contains its unique ID. event_listener_ID is an integer number that indicates the listener object on the client side. data_table contains event-specific data. The server_timestamp field contains server-side event creation time in milliseconds since January 1,
1970 00:00:00 UTC.

Note: The "event" message has empty message_ID parameter.

Operations Reference
GET VARIABLE OPERATION

M/message_id/O/G/context_name/variable_name This operation returns variable_name from context_name. If the variable is found and no error occurred, the reply to this command includes the data table containing the value of the requested variable: R/reply_id/A/data_table
SET VARIABLE OPERATION

M/message_id/O/S/context_name/variable_name/data_table

2000-2013 Tibbo Technology Inc.

1306

AggreGate Documentation

This operation sets variable_name of context_name to the value contained in data_table. If the variable value was changed successfully, the server replies: R/reply_id/A
CALL FUNCTION OPERATION

M/message_id/O/C/context_name/function_name/data_table This operation calls function_name from context_name with data_table as input. If no error occurred, the reply includes a data table containing the function's output: R/reply_id/A/data_table
ADD EVENT LISTENER OPERATION

M/message_id/O/L/context_name/event_name/event_listener_ID[/filter_text] This operation registers a listener with the specified integer event_listener_ID for the event_name in context_name. When this event fires, client receives an Event (E) message with the same event_listener_ID code. The optional filter_text parameter allows to pre-filter events based on the provided filter expression 911 . This expression will be calculated for every matching event, and if it results to false, event will not be sent to the client.
Filter Expression Resolution Environment Default Context
927 927 922

None. Data Table containing event-specific data 0 Standard

931 882 .

Default Data Table Default Row Environment Variables 930

927

variables only.

On successfully adding event listener, server replies: R/reply_id/A

REMOVE EVENT LISTENER OPERATION

M/message_id/O/R/context_name/event_name/event_listener_ID[/filter_text] This operation removes listener with the specified event_listener_ID of event_name in context_name . If filter_text is specified, only listener with this filter is removed. On successfully removing listener, server replies: R/reply_id/A

Data Table Encoding

All data values received or sent within this protocol are represented by Data Tables 854 . Every Data Table is encoded to the string to be inserted into the command. See Data Table Encoding 1306 for details.

14.2 Data Table Encoding

Every Data Table 854 may be encoded into a string (or decoded from a string). Encoding is used to transfer Data Tables over the network using the AggreGate Communications Protocol 1303 , or to define custom context variables 869 , functions 878 and events 880 in AggreGate Agent 848 . Data Tables may be encoded in two modes: Using visible separators

2000-2013 Tibbo Technology Inc.

Appendix
Using invisible separators Three special characters are used as separators for encoding:

1307

Visible Separator < > =

Invisible Separator (character code) 0x1C 0x1D 0x1E

In this article all examples use visible separators. The only limitation when encoding a table using visible separators is that its different elements, when they are encoded to strings, must not contain these separators.

Elements
Generally, Data Table and its different parts are encoded into string as a number of elements of the following format:

<[element_name=]element_value>
Both the name and value may include any character except for those used by AggreGate Communication Protocol used to encode the element itself 1307 . An element's value may be an encoded list of nested elements.
1303

or

Table Encoding
Here is the format for an encoded data table:

<F=record_format>[<I=>][<R=record>][<R=record>] Element Name F I Element Value

Table format descriptor 855 , defining names and types of all columns in the data table and other table properties. Its encoding is described here 1307 . Invalidator element. If this element exists in the data table, the whole table is considered as invalid. When AggreGate Server requests a variable value from an Agent, the Agent first acknowledges this request, and then begins polling the records from the hardware device. In the meanwhile, AggreGate Server "knows" that it is receiving a complete and correct table. If at this point there is a sudden failure between the Agent and the hardware device, and for some reason the Agent does not receive the data it should get from the hardware device, the Agent now inserts an Invalidator element into the data table sent to the server. This element is actually the Agent telling AggreGate Server "I cannot fully obtain this data". Having received this element, AggreGate Server now knows the operation could not actually be completed.

Record of the data table. Records are encoded one by one. Format of encoded records is described below. Example: <F=<<IP><S><F=C>><M=1><X=1>><R=<192.168.1.88>> This example shows an encoded data table those format defined one string field called "IP", and that contains one record with value "192.168.1.88". See details of record and format encoding below.

Table Format Encoding

record_format is included in every data table, even if it is empty. It's built like this: <field_format><field_format>[<F=flags>][<V=table_validators>][<R=record_validators>] [M=min_records][X=max_records][<B=bindings>][<N=naming_expression>]
Elements with no identifiers (as shown in the beginning of the example above, <field_format>) are considered to be encoded formats descriptors 1308 of table fields. Field format descriptors are encoded one by one, starting from the first field.

Elem Element Value ent Nam

2000-2013 Tibbo Technology Inc.

1308

AggreGate Documentation

e F
Combination of zero or more of the following flags: R (Reodrerable) - indicates rows of this table may be reordered by AggreGate users editing it. U (Unresizable) - indicates that users cannot add/remove rows when editing the table.

V R B M X N

Table validators

1310

that help perform complex validation of a whole table.

Record validators 1310 that are used to validate every record. Table bindings
860 .

Minimal allowed number of records in the table. Maximal allowed number of records in the table. Table naming expression. Example: <<date><D>><M=1><X=1> This example format described a one-cell table (one field, minimum and maximum record count is also one). The only field's name is "date", and it's type is Date. See details of field format encoding below. Example: <<id><S><D=Card

ID><V=<L=10 10>>><<name><S><D=Cardholder

Name>><M=0><X=255>
This format describes a two-fields table that may contain from 0 to 255 records. First string field is called "id" and it's description is "Card ID". It has a limits validator that restricts value length to exactly 10 characters. Second field is also of string type, it's called "name".

Field Format Encoding

field_format is a string describing one field in a Data Table. It's formatted like this: <name><type>[<F=flags>][<A=default>][<D=description>][<H=help>][<S=selection_values>] [<V=validators>][<E=editor>]
The first two elements have no names. The first element is the field name, and the second one contains the field type code (see table below). Element Name Element Value Combination of zero or more of the following flags: N (Nullable) - indicates that column can contain NULL values O (Optional) - indicates that column in optional E (Extendable selection values) indicates that field may contain values that are not listed in selection_values R (Read only) indicates that the field value is read only C (Not replicated) - indicates that value of this field is not replicated during Data Table Copy operations H (Hidden) indicates that column should not be visible during Data Table edit operations K (Key field) - indicates that column is a key field. Key fields are used in data table smart copy operation. Another use is a key fields validator that ensures that table doesn't contain records with equal combinations of all key fields.
861 861

A D H S V E

Default value of field encoded into a string as covered in value encoding Field description. Field help (detailed description). List of selection values for the field. See encoding rules here List of field validators. See encoding rules here
1310 . 1310 .

1309

section.

Code of editor/renderer. This element enables custom visual representation of field value. Supported

2000-2013 Tibbo Technology Inc.

Appendix

1309

editors and renderers are listed here

857 .

O I G

Editor-specific options. String ID of field icon. Field group. Example: <value><I> This is the simplest possible field format descriptor that defines the integer field called "value". Example: <period><L><A=30000><D=Check

Period><V=<L=100

1000000>><E=period><O=0

4>
This format descriptor defines a long (64-bit integer) field with default value 30000. Field description is "Check Period". If has a limits validator that restricts values to the range 100..1000000. Editor/renderer type instructs the system to use Time Period editor for editing field value.

FIELD TYPES AND VALUE ENCODING

Type Code Type Tran sfer
1311

Comments and value encoding rules

S I L B F

String field Integer field Long field Boolean field Float field

Yes

Inserted "as is". Converted to string, e.g. 123 or -123.

Converted to string, e.g. 123 or -123. TRUE is encoded as string 1 and FALSE as string 0

Converted to a string according to the below rules. All characters mentioned below are ASCII characters. If the argument is NaN, the result is the string NaN. Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. If the sign is negative, the first character of the result is ; if the sign is positive, no sign character appears in the result. As for the magnitude m : If m is infinity, it is represented by the characters Infinity; thus, positive infinity produces the result "Infinity" and negative infinity produces the result Infinity. If m is zero, it is represented by the characters 0.0; thus, negative zero produces the result -0.0 and positive zero produces the result 0.0. If m is greater than or equal to 10-3 but less than 107, then it is represented as the integer part of m , in decimal form with no leading zeroes, followed by ., followed by one or more decimal digits representing the fractional part of m. If m is less than 10-3 or greater than or equal to 107, then it is represented in socalled "computerized scientific notation." Let n be the unique integer such that 10n <= m < 10n+1; then let a be the mathematically exact quotient of m and 10n so that 1 <= a < 10. The magnitude is then represented as the integer part of a , as a single decimal digit, followed by ., followed by decimal digits representing the fractional part of a , followed by the letter E, followed by a representation of n as a decimal integer. How many digits must be printed for the fractional part of m or a ? There must be at least one digit to represent the fractional part, and beyond that as many, but only as many, more digits as are needed to uniquely distinguish the argument value from adjacent values of type Float (or Double, if a double number processed). That is, suppose that x is the exact mathematical value represented by the decimal representation produced by this method for a finite nonzero argument d. Then d must be the double value nearest to x ; or if two double values are equally close to x

2000-2013 Tibbo Technology Inc.

1310

AggreGate Documentation

, then d must be one of them and the least significant bit of the significand of d must be 0.

E D

Double field Date field

Uses the same string conversion rules as Float field (see above). Converted to string in the form "yyyy-MM-dd HH:mm:ss.SSS", where yyyy is year MM is month dd is day of month HH is hour (0-23) mm is minutes ss is seconds SSS is milliseconds The conversion must use UTC timezone.

T C

Data Table field Color field

Yes

Nested data table is encoded to string according to the Data Table Encoding

1306

rules

Converted to string in the form "#RRGGBB", where RR is red value (0-255) is hex form GG is green value (0-255) is hex form BB is blue value (0-255) is hex form

Data Block field

Yes

ENCODING SELECTION VALUES

Selection values for the field are encoded as a list of elements. Each element's name is the selection value's visible description for the user (what the user will see in the listbox). The element's value is the selection value, encoded into a string as described in the value encoding 1309 section. Example: A list of three selection values for an integer field may be encoded as follows:

<Zero=0><One=1><Two=2>

Encoding Validators
Field validators are encoded as a list of elements, one per every validator. The element's name is a type code of the validator while its value contains validator-specific options.

FIELD VALIDATORS
Here is a list of supported field validators: Type Code L Description Limits Validator. Checks if a value is within the range defined by validator parameters. Suitable Field Types String, Integer, Long, Float, Data Validator-Specific Options

Validator options are encoded into a string as two integer numbers separated by a space. The first number indicates the minimum value of a range, and the second number specifies the maximum value. These numbers have different meaning for different field types: For String fields, these parameters limit minimal and maximal length of the string. For Integer, Long and Float fields they indicate minimal and maximal value. For Data fields they limit number of bytes that can be contained in the data block.

2000-2013 Tibbo Technology Inc.

Appendix

1311

Limits are inclusive for all field types (i.e, a limit of "3" would permit a string such as abc -- containing 3 characters). R Regular Expression String Validator. Checks if a string value matches a regular expression specified by the validator parameter. Example 1: <L=0 255> If this limits validator is added to the format of string field, it will allow only Strings those length is from 0 to 255 characters. It it is defined for an Integer fields, it will restrict field values to the numbers that are greater or equal to 0 and less or equal to 255. Example 2: <R=^[_A-Za-z0-9-]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9-] Validator option string contains a regular expression 1318 to which the field value will be matched. It may be followed by an optional error message separated from the regular expression by a ^^ string. If validation fails (i.e. string value does not match the regular expression), this error message will be shown to the user.

+)*(\\.[_A-Za-z0-9-]+)^^Invalid

E-Mail>

^[_A-Za-z0-9-]+(\\.[_A-Za-z0-9-]+)*@[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)*(\\.[_A-Zaz0-9-]+) is a regex (The first ^ mark belong to it). After this regex, ^^ is used as a separator and is then
followed by the text for the error message, "Invalid E-Mail". This regular expression validator checks if a field contains a valid e-mail address and fails with an Invalid EMail error if it doesn't. See Regular Expressions Syntax 1318 appendix for more information on regular expressions.

RECORD VALIDATORS
Here is a list of supported record validators: Type Code K Description Key Fields. Checks whether a combination of key field values does not already exists in the table. Applied during record addition. Validator-Specific Options

None - key fields are marked with Key Field flag of field format.

TABLE VALIDATORS
Here is a list of supported table validators: Type Code K E Description Key Fields. Checks whether combination of key field values if unique for every record. Expression Validator . Evaluates an expression 911 having this table as a default table 927 . If expression returns NULL table is considered valid, otherwise expression output is converted to string and used as error text. Validator-Specific Options

None - key fields are marked with Key Field flag of field format. The text of expression.

Example: <E={activationThreshold} > {deactivationThreshold} ? null :

'Activation threshold must be greater than deactivation threshold'>

Checks that one field greater than another.

ENCODING OF NULL VALUES

A NULL ("<Not set>") value is encoded with a single 0x1A (SUB) character. This rule applies to encoding NULL values
of table cells, default values of table fields, selection values and any other place where field values may appear. If visible separators are used to encode the Data Table, NULL values are encoded as "^ " characters.

TRANSFER ENCODING
Field values are transfer-encoded to remove characters used by the Data Table encoding format and AggreGate Communications Protocol 1303 . These characters are substituted with special patterns according to the following table:

2000-2013 Tibbo Technology Inc.

1312

AggreGate Documentation

Character
0x25 (%) 0x02 (STX) 0x0D (CR) 0x17 (ETB) 0x1C (FS) 0x1D (GS) 0x1E (RS)

Replaced by
%% %^ %$ %/ %< %> %=

Note that the patterns in the Replaced by column are literal strings -- they're just what you see above.

Encoding of Data Records

Each data record is encoded into a string according to the following format:

[<I=record_ID>]<field_value><field_value>
Elements without names are field values. Field values are encoded one by one, in the same order as they appear in the table format descriptor 1307 .

Element Name I

Element Value
Record ID (Long number)

14.3 Data Tables XML Encoding

This appendix describes how Data Tables 854 are encoded into (and decoded from) XML. Data Tables are XML-encoded only when they have to be transferred as String arguments for Web Service 976 functions, in all other cases AggreGate uses its own encoding syntax 1306 . In most other components of AggreGate (Database 80 , AggreGate Communications Protocol 1303 etc.) Data Tables are stored and transferred using so-called native encoding. This format is covered in a separate appendix 1306 .

XML Schema for Data Tables

Here is the XML Schema used to encode Data Tables: An XML schema is a description of a type of XML document, typically expressed in terms of constraints on the structure and content of documents of that type, above and beyond the basic syntax constraints imposed by XML itself. An XML schema provides a view of the document type at a relatively high level of abstraction. For more information: http://www.w3.org/XML/Schema

<?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

<xs:element name="table"> <xs:complexType> <xs:sequence> <xs:element ref="format" minOccurs="0" maxOccurs="1"/> <xs:element ref="records" minOccurs="0" maxOccurs="1"/> </xs:sequence> </xs:complexType> </xs:element>

2000-2013 Tibbo Technology Inc.

Appendix <xs:element name="format"> <xs:complexType> <xs:sequence> <xs:element ref="fields" minOccurs="0"/> </xs:sequence> <xs:attribute name="maxRecords" type="xs:integer"/> <xs:attribute name="minRecords" type="xs:integer"/> </xs:complexType> </xs:element> <xs:element name="fields"> <xs:complexType> <xs:sequence> <xs:element ref="field" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="field"> <xs:complexType> <xs:sequence> <xs:element ref="selectionValues" minOccurs="0"/> <xs:element ref="defaultValue" minOccurs="0"/> </xs:sequence> <xs:attribute name="description"/>

1313

<xs:attribute name="name" type="xs:NCName" use="required"/> <xs:attribute name="notReplicated" type="xs:boolean"/> <xs:attribute name="nullable" type="xs:boolean"/> <xs:attribute name="readonly" type="xs:boolean"/> <xs:attribute name="type" type="fieldType" use="required"/> </xs:complexType> </xs:element> <xs:element name="selectionValues">

<xs:complexType> <xs:sequence> <xs:element ref="option" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="option"> <xs:complexType mixed="true"> <xs:complexContent> <xs:extension base="fieldVal">

2000-2013 Tibbo Technology Inc.

1314

AggreGate Documentation <xs:attribute name="description" use="required"/> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> <xs:element name="defaultValue" type="fieldVal"/> <xs:element name="records"> <xs:complexType> <xs:sequence> <xs:element ref="record" maxOccurs="unbounded"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="record"> <xs:complexType> <xs:sequence> <xs:element name="value" maxOccurs="unbounded" minOccurs="0"> <xs:complexType mixed="true"> <xs:complexContent> <xs:extension base="fieldVal"> <xs:attribute name="name"

use="required"/> </xs:extension> </xs:complexContent> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element> <xs:simpleType name="fieldType"> <xs:restriction base="xs:string">

<xs:enumeration value="A"/> <xs:enumeration value="I"/> <xs:enumeration value="D"/> <xs:enumeration value="T"/> <xs:enumeration value="S"/> <xs:enumeration value="B"/> <xs:enumeration value="L"/> <xs:enumeration value="F"/> <xs:enumeration value="O"/> <xs:enumeration value="C"/>

2000-2013 Tibbo Technology Inc.

Appendix </xs:restriction> </xs:simpleType> <xs:complexType name="fieldVal" mixed="true"> <xs:choice minOccurs="0"> <xs:element ref="data"/> <xs:element ref="table"/> </xs:choice> </xs:complexType> <xs:element name="data"> <xs:complexType> <xs:attribute name="name" type="xs:string"/> <xs:attribute name="contentType" type="xs:string"/> </xs:complexType> </xs:element> </xs:schema>

1315

This XML Schema defines the structure of a Data Table XML document. The root element is table, corresponding to a whole Data Table 854 . The table element may contain one format element which describes the Data Table's format optional records element that encapsulates a list of table records with the data itself.
855 .

It may also contain

The format element must include a fields sub-element containing a list of table fields. It can have minRecords and maxRecords attributes that define a minimum and maximum number of records in the table. If minRecords is not defined, the minimal number of records is zero. If maxRecords is not defined, the maximal number of records is unlimited (limited by 2^64 in practice). The fields element consists of one or more field elements. A field element defines the format of a single field 856 . It requires name and type attributes. The fieldType element can be represented by one of the type code characters defined here 1309 . description, notReplicated, nullable and readonly attributes are optional. field element can also include selectionValues and defaultValue sub-elements. More these attributes and elements may be found in the Data Tables 856 article. The selectionValues element can contain one or more option elements. A value element is of fieldVal type. value element has required description attribute that specifies description of a certain selection value.

defaultValue is also of fieldVal type.

Elements of fieldVal type are used to store data values of table cells, selection values and default value. Elements of this type may be represented by: table elements (nested tables) data elements (binary data blocks) simple text content (all other types of values, see encoding rules here
1309 )

The records element contains a sequence of record elements. Each record represents a single Data Table record. It contains a number of value elements. Their data type is fieldVal, described above. Each element also has a required name attribute indicating the name of the field whose value is represented by the value.

EXAMPLE OF A DATA TABLE ENCODED IN XML FORMAT

<?xml version="1.0" encoding="UTF-8"?> <table xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <!-- Data Table --> <format maxRecords="1" minRecords="1"> <!-- Table Format Descriptor --> <fields> <!-- Field Set -->

2000-2013 Tibbo Technology Inc.

1316

AggreGate Documentation

<field description="Username" name="username" notReplicated="true" readonly="true" type="S"/> <field description="First Name" name="firstname" notReplicated="true" nullable="true" type="S"/> <field description="Last Name" name="lastname" notReplicated="true" nullable="true" type="S"/> <field description="Password" name="password" notReplicated="true" type="S"/> <field description="Country" name="country" type="I"> <selectionValues> <option <option -description="Albania">1</option> description="Algeria">2</option> --

skipped

</selectionValues> </field> <field description="Region/State/Province/Area" name="region" nullable="true" type="S"/> <field description="ZIP Code" name="zip" nullable="true" type="S"/> <field description="City" name="city" nullable="true" type="S"/> <field description="Address 1" name="address1" nullable="true" type="S"/> <field description="Address 2" name="address2" nullable="true" type="S"/> <field description="Comments" name="comments" nullable="true" type="S"/> <field description="Company" name="company" nullable="true" type="S"/ > <field description="Department" name="department" nullable="true" type="S"/> <field description="E-mail Address" name="email" notReplicated="true" nullable="true" type="S"/> <field description="Phone No." name="phone" notReplicated="true" nullable="true" type="S"/> <field description="Fax No." name="fax" notReplicated="true" nullable="true" type="S"/> <field description="Time Zone" name="timezone" type="S"> <selectionValues> <option description="GMT-12:00, Etc/GMT+12">Etc/GMT+12</ option>

2000-2013 Tibbo Technology Inc.

Appendix

1317

<option description="GMT-11:00, Etc/GMT+11">Etc/GMT+11</ option> -skipped --

</selectionValues> <defaultValue>Europe/Moscow</defaultValue> </field> <field description="Locale" name="locale" type="S"> <selectionValues> <option description="Default"/> <option <option -description="aa">aa</option> description="ab">ab</option> --

skipped

</selectionValues> <defaultValue>en</defaultValue> </field> <field description="Date Pattern" name="datepattern" type="S"/> <field description="Time Pattern" name="timepattern" type="S"/> <field description="Enable Automatic Registration of Device Servers" name="dsautoregistration" type="B"/> </fields> </format> <records> <!-- Data Table Records --> <record> <!-- First Record --> <value <value <value <value <value <value <value <value </record> name="username">ronnie</value> name="firstname">Ronnie</value> name="lastname">O'Sullivan</value> name="password">11111</value> name="country">218</value> name="datepattern">dd.MM.yyyy</value> name="timepattern">HH:mm:ss</value> name="dsautoregistration">1</value>

2000-2013 Tibbo Technology Inc.

1318

AggreGate Documentation

<record> <!-- Second Record --> <value <value <value <value name="username">john</value> name="firstname">John</value> name="lastname">Doe</value> name="password">12345</value>

<value name="country">83</value> <value <value <value </record> </records> </table> name="datepattern">dd.MM.yyyy</value> name="timepattern">HH:mm:ss</value> name="dsautoregistration">1</value>

14.4 Regular Expressions Syntax

A regular expression is like a complex "wildcard". In other words, it's a string that describes or matches other strings, according to certain syntax rules. Tibbo AggreGate uses Java syntax for regular expression processing. See links below
1321

for more info.

Summary of Regular Expression Constructs

Construct Characters x \\ \0n \0nn \0mnn \xhh \uhhhh \t \n \r \f \a \e \cx Character [abc] The character x The backslash character The character with octal value 0n (0 <= n <= 7) The character with octal value 0nn (0 <= n <= 7) The character with octal value 0mnn (0 <= m <= 3, 0 <= n <= 7) The character with hexadecimal value 0xhh The character with hexadecimal value 0xhhhh The tab character ('\u0009') The newline (line feed) character ('\u000A') The carriage-return character ('\u000D') The form-feed character ('\u000C') The alert (bell) character ('\u0007') The escape character ('\u001B') The control character corresponding to x classes a, b, or c (simple class) Matches

2000-2013 Tibbo Technology Inc.

Appendix

1319

[^abc] [a-zA-Z] [a-d[m-p]] [a-z&&[def]] [a-z&&[^bc]] [a-z&&[^m-p]]

Any character except a, b, or c (negation) a through z or A through Z, inclusive (range) a through d, or m through p: [a-dm-p] (union) d, e, or f (intersection) a through z, except for b and c: [ad-z] (subtraction) a through z, and not m through p: [a-lq-z](subtraction)

Predefined character classes . \d \D \s \S \w \W Any character (may or may not match line terminators) A digit: [0-9] A non-digit: [^0-9] A whitespace character: [ \t\n\x0B\f\r] A non-whitespace character: [^\s] A word character: [a-zA-Z_0-9] A non-word character: [^\w]

POSIX character classes (US-ASCII only) \p{Lower} \p{Upper} \p{ASCII} \p{Alpha} \p{Digit} \p{Alnum} \p{Punct} \p{Graph} \p{Print} \p{Blank} \p{Cntrl} \p{XDigit} \p{Space} A lower-case alphabetic character: [a-z] An upper-case alphabetic character:[A-Z] All ASCII:[\x00-\x7F] An alphabetic character:[\p{Lower}\p{Upper}] A decimal digit: [0-9] An alphanumeric character:[\p{Alpha}\p{Digit}] Punctuation: One of !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~ A visible character: [\p{Alnum}\p{Punct}] A printable character: [\p{Graph}\x20] A space or a tab: [ \t] A control character: [\x00-\x1F\x7F] A hexadecimal digit: [0-9a-fA-F] A whitespace character: [ \t\n\x0B\f\r]

Boundary matchers ^ $ \b \B \A \G \Z \z The beginning of a line The end of a line A word boundary A non-word boundary The beginning of the input The end of the previous match The end of the input but for the final terminator, if any The end of the input

Greedy quantifiers X? X* X+ X{n} X, once or not at all X, zero or more times X, one or more times X, exactly n times

2000-2013 Tibbo Technology Inc.

1320

AggreGate Documentation

X{n,} X{n,m}

X, at least n times X, at least n but not more than m times

Reluctant quantifiers X?? X*? X+? X{n}? X{n,}? X{n,m}? Possessive X?+ X*+ X++ X{n}+ X{n,}+ X{n,m}+ X, once or not at all X, zero or more times X, one or more times X, exactly n times X, at least n times X, at least n but not more than m times quantifiers X, once or not at all X, zero or more times X, one or more times X, exactly n times X, at least n times X, at least n but not more than m times

Logical operators XY X|Y (X) X followed by Y Either X or Y X, as a capturing group

Back references \n Quotation \ \Q \E Nothing, but quotes the following character Nothing, but quotes all characters until \E Nothing, but ends quoting started by \Q Whatever the nth capturing group matched

BACKSLASHES, ESCAPES, AND QUOTING

The backslash character ('\') serves to introduce escaped constructs, as defined in the table above, as well as to quote characters that otherwise would be interpreted as unescaped constructs. Thus the expression \\ matches a single backslash and \{ matches a left brace. It is an error to use a backslash prior to any alphabetic character that does not denote an escaped construct; these are reserved for future extensions to the regular-expression language. A backslash may be used prior to a non-alphabetic character regardless of whether that character is part of an unescaped construct.

CHARACTER CLASSES
Character classes may appear within other character classes, and may be composed by the union operator (implicit) and the intersection operator (&&). The union operator denotes a class that contains every character that is in at least one of its operand classes. The intersection operator denotes a class that contains every character that is in both of its operand classes. The precedence of character-class operators is as follows, from highest to lowest: 1 2 3 4 5 Literal escape Grouping Range Union Intersection \x [...] a-z [a-e][i-u] [a-z&&[aeiou]]

2000-2013 Tibbo Technology Inc.

Appendix

1321

Note that a different set of metacharacters are in effect inside a character class than outside a character class. For instance, the regular expression . loses its special meaning inside a character class, while the expression - becomes a range forming metacharacter.

LINE TERMINATORS
A line terminator is a one- or two-character sequence that marks the end of a line of the input character sequence. The following are recognized as line terminators: A newline (line feed) character ('\n'), A carriage-return character followed immediately by a newline character ("\r\n"), A standalone carriage-return character ('\r'), A next-line character ('\u0085'), A line-separator character ('\u2028'), or A paragraph-separator character ('\u2029).

More Info on Regular Expressions

http://en.wikipedia.org/wiki/Regular_expression. Wikipedia article about regular expressions. http://www.regular-expressions.info/. A very good website about Regular Expressions. http://www.regular-expressions.info/reference.html. Basic syntax reference for regular expressions. http://www.regular-expressions.info/examples.html. Sample Regular Expressions. http://java.sun.com/j2se/1.6.0/docs/api/java/util/regex/Pattern.html. Regular Expressions syntax for Java.

14.5 Date and Time Formatting Patterns

Date and time formatting patterns control the visual representation of Date and Time values (i.e. conversion of a timestamp to a string). Within date and time pattern strings, unquoted letters from 'A' to 'Z' and from 'a' to 'z' are interpreted as pattern letters representing the components of a date or time string. Text can be quoted using single quotes (') to avoid interpretation. "''" represents a single quote. All other characters are not interpreted; they're simply copied into the output string during formatting or matched against the input string during parsing. The following pattern letters are defined (all other characters from 'A' to 'Z' and from 'a' to 'z' are reserved): Letter G y M w W D d F E a H k K h m s S Date or Time Component Era designator Year Month in year Week in year Week in month Day in year Day in month Day of week in month Day in week AM/PM marker Hour in day (0-23) Hour in day (1-24) Hour in AM/PM (0-11) Hour in AM/PM (1-12) Minute in hour Second in minute Millisecond Presentation Text Year Month Number Number Number Number Number Text Text Number Number Number Number Number Number Number Examples AD 1996; 96 July; Jul; 07 27 2 189 10 2 Tuesday; Tue PM 0 24 0 12 30 55 978

2000-2013 Tibbo Technology Inc.

1322

AggreGate Documentation

Pattern letters are usually repeated, as their number determines the exact presentation: Text: For formatting, if the number of pattern letters is 4 or more, the full form is used; otherwise a short or abbreviated form is used if available. For parsing, both forms are accepted, independent of the number of pattern letters. Number: For formatting, the number of pattern letters is the minimum number of digits, and shorter numbers are zero-padded to this amount. For parsing, the number of pattern letters is ignored unless it's needed to separate two adjacent fields. Year: For formatting, if the number of pattern letters is 2, the year is truncated to 2 digits; otherwise it is interpreted as a number. Month: If the number of pattern letters is 3 or more, the month is interpreted as text; otherwise, it is interpreted as a number. Hours must be between 0 and 23, and Minutes must be between 00 and 59. The format is locale independent and digits must be taken from the Basic Latin block of the Unicode standard.

Examples
The following examples show how date and time patterns are interpreted in the U.S. locale. The given date and time are 2001-07-04 12:08:56 local time in the U.S. Pacific Time time zone. Date and Time Pattern "yyyy.MM.dd G 'at' HH:mm:ss" "EEE, MMM d, ''yy" "h:mm a" "hh 'o''clock' a" "K:mm a" "yyyyy.MMMMM.dd GGG hh:mm aaa" "EEE, d MMM yyyy HH:mm:ss" "yyMMddHHmmss" Result 2001.07.04 AD at 12:08:56 Wed, Jul 4, '01 12:08 PM 12 o'clock PM 0:08 PM 02001.July.04 AD 12:08 PM Wed, 4 Jul 2001 12:08:56 010704120856

14.6 Number Formatting Patterns

Number formatting patterns control the visual representation of numeric values (i.e. conversion of a number to a string). Number formatting pattern define the rules for formatting decimal numbers. It supports different kinds of numbers, including integers (123), fixed-point numbers (123.4), scientific notation (1.23E4), percentages (12%), and currency amounts ($123).

Patterns
A pattern contains a positive and negative subpattern, for example, "#,##0.00;(#,##0.00)". Each subpattern has a prefix, numeric part, and suffix. The negative subpattern is optional; if absent, then the positive subpattern prefixed with the localized minus sign ('-' in most locales) is used as the negative subpattern. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are all the same as the positive pattern. That means that "#, ##0.0#;(#)" produces precisely the same behavior as "#,##0.0#;(#,##0.0#)". The grouping grouping size 1,0000,0000. the integer is separator is commonly used for thousands, but in some countries it separates ten-thousands. The is a constant number of digits between the grouping characters, such as 3 for 100,000,000 or 4 for If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the one that is used. So "#,##,###,####" == "######,####" == "##,####,####".

Special Pattern Characters

Many characters in a pattern are taken literally; they are matched during parsing and output unchanged during formatting. Special characters, on the other hand, stand for other characters, strings, or classes of characters. They must be quoted, unless noted otherwise, if they are to appear in the prefix or suffix as literals. Symbol 0 Location Number Meaning Digit

2000-2013 Tibbo Technology Inc.

Appendix

1323

# . , E ; % \u2030 (\u00A4) '

Number Number Number Number Number Subpattern boundary Prefix or suffix Prefix or suffix Prefix or suffix

Digit, zero shows as absent Decimal separator or monetary decimal separator Minus sign Grouping separator Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix. Separates positive and negative subpatterns Multiply by 100 and show as percentage Multiply by 1000 and show as per mille value Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator. Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".

Prefix or suffix

Scientific Notation
Numbers in scientific notation are expressed as the product of a mantissa and a power of ten, for example, 1234 can be expressed as 1.234 x 10^3. The mantissa is often in the range 1.0 <= x < 10.0, but it need not be. DecimalFormat can be instructed to format and parse scientific notation only via a pattern; there is currently no factory method that creates a scientific notation format. In a pattern, the exponent character immediately followed by one or more digit characters indicates scientific notation. Example: "0.###E0" formats the number 1234 as "1.234E3". The number of digit characters after the exponent character gives the minimum exponent digit count. There is no maximum. Negative exponents are formatted using the localized minus sign, not the prefix and suffix from the pattern. This allows patterns such as "0.###E0 m/s". The minimum and maximum number of integer digits are interpreted together: If the maximum number of integer digits is greater than their minimum number and greater than 1, it forces the exponent to be a multiple of the maximum number of integer digits, and the minimum number of integer digits to be interpreted as 1. The most common use of this is to generate engineering notation, in which the exponent is a multiple of three, e.g., "##0.#####E0". Using this pattern, the number 12345 formats to "12.345E3", and 123456 formats to "123.456E3". Otherwise, the minimum number of integer digits is achieved by adjusting the exponent. Example: 0.00123 formatted with "00.###E0" yields "12.3E-4". The number of significant digits in the mantissa is the sum of the minimum integer and maximum fraction digits, and is unaffected by the maximum integer digits. For example, 12345 formatted with "##0.##E0" is "12.3E3". To show all digits, set the significant digits count to zero. The number of significant digits does not affect parsing. Exponential patterns may not contain grouping separators.

Pattern Syntax Grammar

Number format patterns have the following syntax:

Pattern: PositivePattern PositivePattern ; NegativePattern PositivePattern: Prefixopt Number Suffixopt NegativePattern: Prefixopt Number Suffixopt Prefix: any Unicode characters except \uFFFE, \uFFFF, and special characters Suffix:

2000-2013 Tibbo Technology Inc.

1324

AggreGate Documentation any Unicode characters except \uFFFE, \uFFFF, and special characters

Number: Integer Exponentopt Integer . Fraction Exponentopt Integer: MinimumInteger # # Integer # , Integer MinimumInteger: 0 0 MinimumInteger 0 , MinimumInteger Fraction: MinimumFractionopt OptionalFractionopt MinimumFraction: 0 MinimumFractionopt OptionalFraction: # OptionalFractionopt Exponent: E MinimumExponent MinimumExponent: 0 MinimumExponentopt

14.7 Common Constants

This appendix lists and described common numeric and string constants used in different AggreGate modules.

Time Units
0 - Millisecond 1 - Second 2 - Minute 3 - Hour 4 - Day 5 - Week 6 - Month 7 - Quarter 8 - Year

Aggregation Types
0 - Average 1 - Minimum 2 - Maximum

2000-2013 Tibbo Technology Inc.

Appendix
3 - Summation 4 - First 5 - Last

1325

14.8 CSV Import/Export Options

When exporting/importing from a Character Separated Values (CSV) file, you can specify several encoding/decoding settings: Setting Field Delimiter Use Text Qualifier Description The character to use as the column delimiter. Default is semicolon (;). Sets whether text qualifiers will be used while writing/parsing data or not. When exporting data, there are three choices: Do not use, Use when necessary (i.e. when text itself contains field delimiters or other reserved characters) and Use always. The character to use as a text qualifier in the data. Default is double quote ("). There are two modes that may be used to escape qualifier characters in the data: Use a backslash character before the text qualifier to represent an occurrence of the text qualifier; Double up the text qualifier to represent an occurrence of the text qualifier. Comment Character Header Record The character to use as a comment signal. Defines content of the first record of CSV file. Possible choices are: None. CSV file has no header record, first record contains raw data. In the case of import, it means that data in the first column of CSV file will be imported in the first record of Data Table and so on. Field Names . First record of CSV file contains names of Data Table fields. In the case of import, it helps to match column of CSV file and field of the Data Table. Field Descriptions. First record of CSV file contains descriptions of Data Table fields. In the case of import, it helps to match column of CSV file and field of the Data Table. Ignore As Non-Valuable Data. This option is available during import operation only. It causes import operation to skip first record of CSV file. In the case of import, data in the first line of CSV file will be imported in the first record of Data Table and so on.

Text Qualifier Escape Mode

14.9 Report Template Generation

AggreGate Server can automatically generate Report 241 Templates from the data contained in any Data Table Before a template is generated, it is usually possible to specify its properties: Property Template Title Paper Size Orientation Row Height Font Size in Header Font Size in Body Stretch template elements to fit contents Description Type of report template: Simple (good for black and white printing) or Colored. Report Title. Appears in the top of the first page. Specifies paper size for printing. Portrait/Landscape orientation for printing. Height of every row in the main part of report. Font size for column titles. Font size for report contents. Indicates that row height may be increased to put elements that don't fit in a standard row. If disabled, elements that don't fit in their row will be hidden.
854 .

2000-2013 Tibbo Technology Inc.

1326

AggreGate Documentation

Fields

Configuration of report fields: Visible. Flag indicating that Data Table field will be shown in the report. Relative Width. A floating point value giving a hint for column width calculation. If relative width of one column is two times larger than relative width of the other column, first column will be twice as wide in the report template. Column Header . Report column header.

Grouping

If enabled, report lines will be grouped by selected field.

Example
Source Data for Report:

Report Parameters:

Resulting Report (Simple template):

2000-2013 Tibbo Technology Inc.

Appendix

1327

Resulting Report (Colored Template):

14.10 Configuring DCOM for Remote Access

Before you can access your WMI host or OPC Server running under Microsoft Windows, you must ensure that Distributed COM (DCOM) is properly configured on this machine. Follow the below checklist to ensure the proper configuration.

1. Enabling Necessary Services

Please make sure that the Server Service and Remote Registry Service are running on the machine where the COM server resides.

2. Configuring Access Permissions

To avoid getting Access Denied exceptions, it is best to connect to the COM server under the identity of currently logged in user. Incase granting "administrators" permission is a concern, you can create a local user under "Users" group.

2000-2013 Tibbo Technology Inc.

1328

AggreGate Documentation

2A. CONFIGURING DCOM ACCESS

Go to Control Panel > Administrative Tools > Local Security Policy > Security Settings > Local Policies > Security Options: Double-click DCOM: Machine Access Restrictions policy, click Edit Security , add the user created above (or currently logged in user), allow "Remote Access" Double-click DCOM: Machine Launch Restrictions policy, click Edit Security , add the user created above (or currently logged in user), allow "Local Launch", "Remote Launch", "Local Activation", "Remote Activation" Double-click Network access: Sharing and security model for local accounts policy, select Classic - users authenticate as themselves

2B. CONFIGURING COM SECURITY

Go to Control Panel > Administrative Tools > Component Services > Computers > right-click My Computer > click Properties > Default Settings tab: Check Enable Distributed COM on this computer Set Default Authentication Level to Connect Set Default Impersonation Level to Identify Go to Control Panel > Administrative Tools > Component Services > Computers > right-click My Computer > click Properties > click COM Security tab : In Access Permissions section, click Edit Default > add the user created above (or currently logged in user), allow "Remote Access" In Launch and Activation Permissions section > click Edit Default > add the user created above (or currently logged in user), allow "Local Launch", "Remote Launch ", "Local Activation", "Remote Activation " The Component Services section, to be more accurate, you can go to a specific component, and grant permission from there, instead of from "My Computer", which is a blanket grant

3. Configuring Windows Firewall

Sometimes the Windows Firewall will act up if not configured properly, so please make sure that you have either configured it for DCOM protocol or turned it off. Please note that the firewall issue will prevent all DCOM Windows applications to fail as well.

4. Disabling UAC
When User Access Control (UAC) is active, an administrator account actually has two security tokens, a normal user token, and an administrator token (which is only activated when you pass the UAC prompt). Unfortunately, remote requests that come in over the network get the normal user token for the administrator, and since there is no way to handle a UAC prompt remotely, the token can't be elevated to the true-administrator security token. Thus, UAC should be disabled to allow remote DCOM access.

5. Installing Latest Updates

Please make sure that your Windows machine (where COM server is hosted) is up to date with all the Service packs and updates from Microsoft. Many a times issues are due to improper machine configuration.

Notes For Specific Versions of Windows

If the above instructions didn't help, check notes for specific versions of Windows below.

CONFIGURING DCOM ON WINDOWS 2000

1. Click Start, click Run, and then type DCOMCNFG. 2. Click Default Properties. Select Enable Distributed COM on this computer. Set the Default Authentication Level to Connect (None also works). Set the Default Impersonation Level to Identify (Impersonate also works). 3. Click Default Security. 4. Under Default Access Permissions click Edit Default. Add SYSTEM and INTERACTIVE. The user whose authentication credentials will be used to access the COM application must also be included in this list. There are many ways to do this. You can add the specific user or simply add a group the user belongs to. Possible values include:

2000-2013 Tibbo Technology Inc.

Appendix
- Domain\Username (A specific user) - Domain\Administrators (All administrators on a specific domain) - Everyone (All users)

1329

5. Under Default Launch Permissions click Edit Default. Make sure the Default Launch Permissions have the same values as the Default Access Permissions. 6. Click Default Protocols. Make sure Connection-oriented TCP/IP is listed first. 7. You must now configure the COM application you wish to access. Click Applications and right-click on the application you wish to configure. Select Properties. If your COM application is a DLL, you must first create a surrogate EXE for it using the SetDllHost tool. Once a surrogate EXE is created, the surrogate name will appear in the list of applications. Select Properties for the surrogate and continue on. 8. Click General. Set the Authentication Level to Default. 9. Click Location. Select Run application on this computer. 10. Click Security. Select Use default access permissions and Use default launch permissions. 11. Click Identity. Select The launching user. This setting specifies the account that will be used to run the COM application once it is launched by a client program. The launching user is the user account of the client process that launched the server, and is the recommended setting. Depending on the COM application you want to connect to, you may need to change this to: - The interactive user - The user that is currently logged on to the machine hosting the COM application. - This user - Specify a user account that will always be used to run the COM application regardless of which user is accessing it. 12. Click Endpoints. Select Default System Protocols. 13. If you still get an "Access Denied" or "Permission Denied" error after configuring your DCOM settings, try rebooting your machine to allow the new settings to take effect.

CONFIGURING DCOM ON WINDOWS XP AND WINDOWS SERVER 2003

1. If the computer belongs to a workgroup instead of a domain, make sure that it does not use simple file sharing. Open Windows Explorer or double click My Computer, click Tools, then go to Folder Options, click View and uncheck Use simple file sharing (Recommended) in Advanced settings. 2. Click Start, click Programs, click Administrative Tools, click Component Services. 3. Expand Component Services, expand Computers, and right-click My Computer. Select Properties. 4. Click Default Properties. Select Enable Distributed COM on this computer. Set the Default Authentication Level to Connect (None also works). Set the Default Impersonation Level to Identify (Impersonate also works). 5. Click Default COM Security. 6. Under Default Access Permissions click Edit Default. Add SYSTEM, INTERACTIVE, and NETWORK. The user whose authentication credentials will be used to access the COM application must also be included in this list. There are many ways to do this. You can add the specific user or simply add a group the user belongs to. Possible values include: - Domain\Username (A specific user) - Domain\Administrators (All administrators on a specific domain) - Everyone (All users) 7. Under Default Launch Permissions click Edit Default. Make sure the Default Launch Permissions have the same values as the Default Access Permissions. 8. Click Default Protocols. Make sure Connection-oriented TCP/IP is listed first. 9. You must now configure the COM application you wish to access. Expand Component Services, expand Computers, expand My Computer, and click DCOM Config. Right-click on the application you wish to configure. Select Properties. If your COM application is a DLL, you must first create a surrogate EXE for it using the SetDllHost tool. Once a surrogate EXE is created, the surrogate name will appear in the list of applications. Select Properties for the surrogate and continue on. 10. Click General. Set the Authentication Level to Default. 11. Click Location. Select Run application on this computer. 12. Click Security. Set Launch Permissions to Use Default. Set Access Permissions to Use Default. Set Configuration Permissions to Use Default. 13. Click Identity. Select The launching user. This setting specifies the account that will be used to run the COM

2000-2013 Tibbo Technology Inc.

1330

AggreGate Documentation

application once it is launched by a client program. The launching user is the user account of the client process that launched the server, and is the recommended setting. Depending on the COM application you want to connect to, you may need to change this to: - The interactive user - The user that is currently logged on to the machine hosting the COM application. - This user - Specify a user account that will always be used to run the COM application regardless of which user is accessing it. 14. Click Endpoints. Select default system protocols. 15. If you still get an "access denied" or "permission denied" error after configuring your DCOM settings, try rebooting your machine to allow the new settings to take effect.

CONFIGURING DCOM ON WINDOWS XP SP2

Microsoft has added some DCOM security enhancements to Windows XP Service Pack 2. In addition to the above Windows XP DCOM configuration settings, you will need to perform the following steps. 1. If the computer belongs to a workgroup instead of a domain, make sure that it does not use simple file sharing. Open Windows Explorer or double click My Computer, click Tools, then go to Folder Options, click View and uncheck Use simple file sharing (Recommended) in Advanced settings. 2. Click Start, click Programs, click Administrative Tools, click Component Services. 3. Expand Component Services, expand Computers, and right-click My Computer. Select Properties. 4. Click Default COM Security. 5. Under Default Access Permissions click Edit Default. Make sure SYSTEM, INTERACTIVE, NETWORK, and the user whose authentication credentials will be used to access the COM application all have Local and Remote Access permissions. 6. Under Default Access Permissions click Edit Limits. Service Pack 2 comes with the following default values: ANONYMOUS LOGON (Local Access) and Everyone (Local and Remote Access). Make sure these values are listed, and then add the user whose authentication credentials will be used to access the COM application. Allow this user to have Local and Remote Access permissions. 7. Under Default Launch Permissions click Edit Default. Make sure SYSTEM, INTERACTIVE, NETWORK, and the user whose authentication credentials will be used to access the COM application all have Local and Remote Launch permissions, as well as Local and Remote Activation permissions. 8. Under Default Launch Permissions click Edit Limits. Service Pack 2 comes with the following default values: MACHINE \Administrators (Local and Remote Launch, Local and Remote Activation) and Everyone (Local Launch and Local Activation). Make sure these values are listed, and then add the user whose authentication credentials will be used to access the COM application. Allow this user to have Local and Remote Launch permissions, as well as Local and Remote Activation permissions. 9. Service Pack 2 comes with a built-in Windows Firewall. If the firewall is turned on, you will have to allow your COM application network access to your machine. You can do this by opening Windows Firewall and adding your COM application to the list of programs under the Exceptions tab. If Display a notification when Windows Firewall blocks a program is selected, then you will be prompted to unblock the COM application when AggreGate Server accesses your DCOM server for the first time. Select Unblock when prompted. 10. If you still get an "access denied" or "permission denied" error after configuring your DCOM settings, try rebooting your machine to allow the new settings to take effect.

14.11 OS-Based Failover Cluster

Since version 4.43, AggreGate Server features integrated failover clustering 87 support for ensuring high availability services. However, clustering support in older versions of the server has depended to the operating system facilities. This appendix is reserved for compatibility. If your version of AggreGate is higher than v4.43, refer to integrated failover cluster support 87 for building high availability cluster. This appendix describes how to build a failover cluster using: Linux-based servers DRBD service for database mirroring Linux Heartbeat service for managing nodes state

Introduction

2000-2013 Tibbo Technology Inc.

Appendix
This article explains how to set up an AggreGate Failover Cluster in order to achieve uninterrupted service. Failover configuration features: - Two physical servers running Linux operating system - Reliable high-speed network connection between cluster nodes and with the outside world - AggreGate AggreGate Server installed on both nodes - MySQL Server installed on both nodes - Shared disk space containing AggreGate Server configuration and database data

1331

- Linux Heartbeat software used to manage cluster nodes (Linux Heartbeat is a part of High Availability Linux project) Benefits of the described cluster configuration: - Replication of disk data between nodes ensures resistance to HDD failures - Automatic transfer of IP addresses causes transparent switching of Clients, Agents and third-party applications to the secondary node in the case of primary node failure - Maximum service downtime does not exceed several minutes (less than one minute in most cases) - Different custom rules and timeouts may be applied for AggreGate Server and database server failure detection Techniques described in this article may help to set up an AggreGate failover cluster using other operating systems and database servers. See Windows 2008 Server High Availability (http://www.microsoft.com/windowsserver2008/en/us/highavailability.aspx) for details on clustering Microsoft Windows.

Failover Cluster Configuration Outline

The image below shows the proposed schema for cluster configuration. There are two nodes, Node 1 (primary as shown on the image) and Node 2 (secondary), connected to each other via Gigabit Ethernet link.

2000-2013 Tibbo Technology Inc.

1332

AggreGate Documentation

DISK SHARING
Both nodes have access to the common disk space that is shared using Distributed Replicated Block Device (DRBD) technology. The primary node has full access to this disk, while secondary node accesses it in read-only mode. This disk contains the following data: AggreGate AggreGate Server installation folder, including server configuration file MySQL installation folder and database data During primary role transfer from one node to another, DRBD is switched to read-write mode for the new primary node, and to read-only mode for new secondary node (if it has not completely failed).

DATABASE FAILOVER
The described configuration uses MySQL as the database server for AggreGate, but other SQL databases may be configured in the same way. MySQL Server is installed in the shared disk space. It is running on the primary node, and stopped on the secondary node. During the role transfer, MySQL is launched on the new prinary node, and stopped on the new secondary node (if it has not completely failed). MySQL server stores all data in the shared disk space.

AGGREGATE SERVER FAILOVER

2000-2013 Tibbo Technology Inc.

Appendix

1333

AggreGate AggreGate Server failover mechanism is very similar to the database failover: AggreGate Server is installed in the shared disk space, running on the primary node and stopped on the secondary one. During role change, AggreGate Server is stopped on the old primary node (if it has not completely failed) and launched on the new primary node.

HEARTBEAT
Heartbeat daemon is running on both the primary and secondary nodes and manages cluster nodes in real time. Two heartbeat daemons maintain a constant link with one another. On the primary node, heartbeat daemons runs a Monitor daemon that constantly polls the state of MySQL and AggreGate server by monitoring the availability of certain TCP ports.

IP ADDRESS MANAGEMENT
Every node in the cluster has a dedicated fixed IP address. The primary node also has an alias IP. This IP is used by Clients, Agents and third-party applications to access the AggreGate Server. During role transfer, this alias IP address is removed from the old primary node's network interface, and added to the new primary node's network interface by the heartbeat daemon. This causes transparent switching of all Clients and Agents to the new primary node.

Role Transfer
Role transfer is the process of passing the primary cluster node role to the other node. It occurs in the following cases: If the primary node loses network connectivity or has a hardware failure. In this case, the heartbeat daemon on the primary node stops responding, and the heartbeat daemon on the secondary node switches it to the primary state as soon as a certain timeout period elapses. If MySQL of AggreGate Server on the primary node fails. In this case, the Monitor daemon on the primary node will detect port unavailability and report error status to the heartbeat daemon. The latter will switch the local node to the secondary state and instruct the heartbeat daemon on the other node to switch it to primary.

NODE THAT LOSES PRIMARY STATUS

If the node that lost primary status did not fail completely, its heartbeat daemon does its best to switch it to secondary: Shared DRBD device is switched to secondary read-only mode MySQL is stopped AggreGate Server is stopped Monitor daemon is stopped Alias IP address is removed from node's network interface

NODE THAT GETS PRIMARY STATUS

Heartbeat daemon on the node that becomes primary does the following during role transfer: Shared DRBD device is switched to primary read-write mode MySQL is launched AggreGate Server is launched Monitor daemon is launched Alias IP address is added to the node's network interface

Failover Cluster Setup

This section illustrates how to set up AggreGate for failover on two machines running Linux Mandrake. While it includes tips on how to configure all necessary services, the exact commands and scripts will differ in a real environment.

1. INSTALLING DRBD
Install and configure DRBD on both machines. 1a. Install DRBD using URPMI:

urpmi drbd-utils
1b. Create new partition for the DRBD shared disk in the free HDD space.

cfdisk /dev/sda

2000-2013 Tibbo Technology Inc.

1334

AggreGate Documentation

Partition type: Linux (0x83). Partition size must match on both machines. In our example, the name of the newly created partition is /dev/sda7. 1c. If you have a firewall, allow incoming connections to TCP/UDP port 7791. 1d. Reboot the machine. 1e. Create a DRBD configuration in /etc/drbd.conf. Here we assume that the IP of the first machine is 192.168.1.2, while the IP of second machine is 192.168.1.3. Configuration file is the same on both machines: DRBD Configuration File (/etc/drbd.conf)

global { # You might disable one of drbdadm's sanity check. # disable-ip-verification; usage-count no; } common { syncer { rate 10M; } } resource r0 { protocol C; startup { wfc-timeout 0; degr-wfc-timeout 120; } disk { on-io-error detach; } meta-disk internal; syncer { } on l0 { device /dev/drbd0; disk /dev/sda7; address 192.168.1.2:7791; } on l1 { device /dev/drbd0; disk /dev/sda7; address 192.168.1.3:7791; } } 1f. Start DRBD driver and create virtual disk:

service drbd restart drbdadm create-md r0

1g. Check DRBD status on both machines:

cat /proc/drbd
It should be Secondary/Secondary and Inconsisted/Inconsisted on both machines for far. 1h. Now let's say that first server is primary: Node 1: drbdadm -- --overwrite-data-of-peer primary r0 Node 2: drbdadm secondary r0 Now DRBD status on node 1 should be Primary/Secondary, UpToDate/Inconsisted 1i: Start synchronization process: Node 1: drbdadm adjust all 1j: Give DRBD some time to synchronize data and check status again: Node 1: cat /proc/drbd Status should be Primary/Secondary, UpToDate/UpToDate. It means that DRBD disk is operable.

2000-2013 Tibbo Technology Inc.

Appendix

1335

2. CREATING SHARED DISK

2a. Create file system on DRBD device: Node 1: mke3fs /dev/drbd0 2b. Create mount point and add it to the list of partitions mounted on boot: Both nodes: mkdir /mnt/drbd 2c. Mount shared filesystem on first node: Node 1: mount -t ext3 /dev/drbd0 /mnt/drbd

3. INSTALLING MYSQL AND AGGREGATE AGGREGATE SERVER

3a. Install packages for MySQL using URPMI utility:

urpmi mysql-max
3b. Move MySQL tables to a DRBD disk and create a symlink:

cp -r /var/lib/mysql /mnt/drbd/ mv /var/lib/mysql /var/lib/mysql.bak ln -s /mnt/drbd/mysql /var/lib/mysql

3c. Start MySQL:

service mysqld-max start

3d. Add system user for running AggreGate Server:

useradd linkserv
3e. Perform AggreGate Server installation by running an installer and following its instructions. In our case, installation directory is /mnt/drbd/linkserver. 3f. Create new MySQL user account for AggreGate Server and configure AggreGate Server to use MySQL database 3g. Copy linkserv script from AggreGate Server installation directory to /etc/rc.d/init.d. 3h. Test the installation by executing service linkserv start, waiting until the server starts and stopping it using service linkserv stop. Check server log file for errors. 3i. Create a symlink for AggreGate Server:
82

ln -s /mnt/drbd/linkserver /home/linkserv/linkserver
4. INSTALL HEARTBEAT AND HEARTBEAT-DRBD ON BOTH NODES
4a. Install heartbeat: Both nodes: urpmi heartbeat Both nodes: urpmi heartbeat-drbd 4b. Switch off boot-time autostart for MySQL and AggreGate Server: Both nodes: chkconfig mysqld-max off Both nodes: chkconfig linkserv off 4c. Switch on autostart for heartbeat: Both nodes: chkconfig heartbeat on 4d. Create heartbeat configuration in /etc/ha.d/ha.cf (file contents match on both nodes): Heartbeat configuration (/etc/ha.d/ha.cf)

# keepalive: how many seconds between heartbeats keepalive 1 # # deadtime: seconds-to-declare-host-dead deadtime 3 #

2000-2013 Tibbo Technology Inc.

1336

AggreGate Documentation

# hopfudge maximum hop count minus number of nodes in config hopfudge 1 # # What interfaces to heartbeat over? bcast eth1 auto_failback on # # File to wirte debug messages to debugfile /var/log/ha-debug # # File to write other messages to # logfile /var/log/ha-log # # Facility to use for syslog()/logger (alternative to log/debugfile) # logfacility local0 # # Tell what machines are in the cluster # node nodename ... -- must match uname -n node l0 node l1

4e. Configure heartbeat resources: Heartbeart resources (/etc/ha.d/haresources) on Node 1

l0 IPaddr2::192.168.1.100/24/eth1:0 drbddisk::r0 Filesystem::/dev/drbd0::/mnt/ drbd::ext3 mysqld-max linkserv mon

Heartbeart resources (/etc/ha.d/haresources) on Node 2

l1 IPaddr2::192.168.1.100/24/eth1:0 drbddisk::r0 Filesystem::/dev/drbd0::/mnt/ drbd::ext3 mysqld-max linkserv mon

Note, that 192.168.1.100 is the alias IP address that migrates between cluster nodes upon failover. This address will be the alias IP address of the primary node.

5. MONITORING SERVICE SETUP

5a. Install monitor service: Both nodes: urpmi mon 5b. Switch off autorun for mon: Both nodes: chkconfig mon off 5c. Create "service down" script: Both nodes: echo -ne "#!/bin/bash\n/usr/lib/heartbeat/hb_standby all\n" > /etc/mon/ha-

down.alert
And make it executable: Both nodes: chmod 0755 /etc/mon/ha-down.alert 5d. Configure monitored services in /etc/mon/mon.cf on both nodes. We need to watch for ports: TCP port 3306 for MySQL TCP ports 6450 (Device Servers), 6460 (Clients), 6480 (Agents), 8443 (Embedded Web Server) for AggreGate Server Monitored services configuration (/etc/mon/mon.cf)

# # Basic mon.cf file

2000-2013 Tibbo Technology Inc.

Appendix

1337

# # Global options # cfbasedir = /etc/mon pidfile = /var/run/mon.pid statedir = /var/lib/mon/state.d logdir = /var/lib/mon/log.d dtlogfile = /var/lib/mon/log.d/downtime.log #alertdir = /usr/lib/mon/alert.d alertdir = /etc/mon/ mondir = /usr/lib/mon/mon.d maxprocs = 20 histlength = 100 randstart = 60s authtype = pam userfile = /etc/mon/userfile # # Group definitions (hostnames or IP addresses) # hostgroup servers localhost watch servers service agg0 interval 30s monitor tcp.monitor -p 6450 period wd {Sun-Sat} alert ha-down.alert alertafter 2 service agg1 interval 30s monitor tcp.monitor -p 6460 period wd {Sun-Sat} alert ha-down.alert alertafter 2 service agg2 interval 30s monitor tcp.monitor -p 6480 period wd {Sun-Sat} alert ha-down.alert alertafter 2 service agg3 interval 30s monitor tcp.monitor -p 8443 period wd {Sun-Sat} alert ha-down.alert alertafter 2 service mysql interval 10s monitor msql-mysql.monitor period wd {Sun-Sat} alert ha-down.alert alertafter 2

localhost

localhost

localhost

localhost

--mode mysql --username=linkserv --password=pass --database=linkse

It is possible to configure Monitor daemon to send E-mail or SMS notifications upon node failure. See its documentation for details. 5e. Start Heartbeat: Both nodes: service heartbeat start If your setup is correct, AggreGate cluster should be operative in several minutes.

Resolving a Split-Brain
Split-brain is a situation whereby cluster nodes are disconnected from each other for a significant time, e.g. due to some

2000-2013 Tibbo Technology Inc.

1338

AggreGate Documentation

network problem. In this case, DRBD devices may lose sync. Here is an example for commands that can help synchronize DRBD manually following a split-brain situation. We assume that we should use data from node 1 and discard data from node 2: Node 2: drbdadm secondary all Node 2: drbdadm disconnect all Node 2: drbdadm -- --discard-my-data connect all Node 1: drbdadm connect all

2000-2013 Tibbo Technology Inc.