Starting Geneos GA4.11, the Active Console has a new set of documentation guides. To access the new Active Console topics, use Geneos version 4.11.x in the Geneos Home Page.
Active Console AC is a standalone Java and C++ application which allows you to connect to and view the contents of Geneos Gateways. This section is a reference guide that steps you through the major components. It is not designed as a tutorial, which is the basis of a separate section.
This section assumes the user has a basic understanding of the Geneos Framework.
It guides you through the fundamental principles behind the AC interface and its main components.
Note: This specific guide is now only accessible from Geneos versions 4.10.x and below. For new features or changes for Active Console documentation, such as the Object Inspector dockable in Active Console Dashboard User Guide, use Geneos version 4.11.x. in the Geneos Home Page.
The following Active Console specific terms are used extensively throughout this document:
Data Items - an umbrella term that refers to one or more of the following:
- Managed Entity
- Data view
- Managed Variable (row / column)
Active Console AC is started by running the Active Console executable located in the directory you installed the files in or unzipped them to. If problems are encountered see Troubleshooting.
There are a number of start-up flags and settings you can define which modify the behaviour and configuration of the Active Console while it is running. These settings are configured by modifying the ActiveConsole.gci file that resides in the same directory as the ActiveConsole.exe. For a complete list of these flags, and details of how to change this file, see Start Up Settings.
|Active Console Machine||
OS: see Operating System Support, for more details.
Memory: 2GB (32bit), 4GB (64bit)
Network: 1 Network Card (100 mbps)
|Connectivity||The Active Console(s) should have connectivity to the Gateway machines and port where Gateway data can be accessed.|
An example of the main application window is shown in Figure 1.
Figure 1. The main AC application window
Like most standard applications it has a menu and a tool bar, the contents of which are detailed below. It also has a set of components which are used to view and manipulate the contents of gateways. All the components reside in dockable frames (see dockable framework) which can be dragged around the application window or undocked (floated in their own window).
The list of components in AC, and full details on how to use them are covered in Component List.
At any given time only a single dockable component is selected. This is indicated by giving it a different colour heading to the other visible components. This is relevant for a few minor functions of AC, like the 'Refresh' menu.
The status bar (at the bottom of the main application window) displays (from left to right), the Global state, the current workspace you are working with, and the build number (version) of the Active Console.
This section outlines some general standards and tips and tricks in the AC interface.
There will be many situations in the AC interface
when you will be presented with a list from which
from which you must select one or many items. To do
this left click on the required item. If you want to
select multiple items hold down the CTRL key; to
deselect an item hold down
The core of a workspace configuration is the gateways that it tries to connect to. These can be defined either explicitly (by defining their host and port) or via remote files that contains lists of gateways (also defined by their host and port). See Remote Gateway Files for more on defining these files.
The end result is a set of gateways (host and ports) to connect to on start up.
Note: Duplicates are allowed in the list of connections (be they locally defined or via a remote file) but are ignored when connecting to the gateways, so that each gateway will be connected only once.
The Active Console can connect to up to 1024 Gateways.
Connections are defined via the workspace configuration (see Connection Settings), they have the following properties:
- Hostname - the primary host name (or IP address).
- Port - the primary port number.
- Enabled [optional] - whether the connection should connect or not connect on start up, note you can always change this property during runtime, this is just how it comes up on first starting the AC.
- Secure Connection [optional] - the type of connection that the AC should establish with the gateway. If this is set then the AC will use a secure connection to communicate with the gateway, otherwise it will use an insecure one.
- Logon Method [optional] - the method that the AC attempts to log on to gateway with, this overrides the workspace logon type.
- Description [optional] - a natural language description that you want to display if the gateway is not connected, once connected it will use the name passed to it from the gateway.
- Secondary Host [optional] - the name (or IP address) that will be used if the AC fails to connect to the primary gateway. This functionality is also referred to as 'Hot standby'.
- Secondary Port [optional] - the port number of the secondary gateway. This functionality is also referred to as 'Hot standby'.
Within the workspace a gateway connection can be defined as Enabled or Disabled. If a gateway connection is disabled then AC will not connect to the gateway (if it is already connected it will break the connection).
Note: This does not disable the actual gateway, just this AC from connecting to it. Access to the disable / enable functionality is via the right click menu on a gateway.
You can Enable / Disable all gateway connections at the same time via the File menu. There is also a Reset connection function, available from the right click menu on a gateway which will disable, then enable the gateway connection via a single click.
You can decide whether new connections are enabled or disabled when they are imported by using the 'Enable new remote connections' setting. If this is ticked newly added gateways will come in enabled, otherwise they will be added disabled.
Every workspace is configured with a default gateway logon mechanism. This can be either:
- System logon - AC will pick up and use the OS system logon credentials and send them to the connected gateways when connecting.
- Manual Logon - you can ignore the system logon and instead define a user name that should be sent to all gateways.
- Whenever a connection to a gateway is made the default credentials will be used. When gateway connections are defined explicitly (not via a remote file) you can override this default to one of the following:
- Always Ask - whenever AC connects to the gateway you will be prompted to choose a connection type and to give a username and password.
- Ask Once - you will be asked for a username and password the first time you connect to the gateway in the AC session.
- SSO - AC will use SSO when it connects to the Gateway . See SSO Login.
You can define different logins for each of the gateways that are configured for your workspace using these settings.
Note: The settings in locally defined connections will always override those defined in remote files. Thus if there are duplicates the local (connection) settings will always be used first.
Gateways must have unique names and IDs in the AC. If you connect to more than one gateway, their names and IDs must be different, if they are not you will receive an error.
It is recommended that you resolve clashes, by changing the gateway setups where possible.
Legacy Gateway name clash
Legacy gateway IDs are actually generated in the AC, based upon the hostname and port, so it is not possible for them to clash. The name can clash with another connection. If this is the case you will see this dialog:
The connection is still valid, but the name of the gateway in the AC is changed to ensure uniqueness. Any paths that rely on the name will likely not work.
Gateway 2 name clashes
If a gateway name or ID clashes in the AC, you will see this dialog:
At this point the connection is rejected, and will contain no data. It is necessary to change the setup so the name and ID do not clash. This can be set in the Operating environment of the gateway setup file.
When you save a file using the Gateway Setup Editor, it will check if the name or ID clashes with any existing connections. If it does you will receive a warning:
This version of Active Console contains an optimisation that reduces the amount of network traffic between the Gateway and the Active Console. In subscription mode, the Active Console will only subscribe to the minimum required set of dataview cell updates. This reduced network traffic also reduces the processing load on the Active Console; allowing users to concurrently connect to more gateways whilst using less resource on the client machine. This feature maintains the majority of Active Console functionality subject to one limitation (see 'searching by cell value' below).
When an Active Console first connects to a gateway or when new dataviews are created on a gateway, the full and current state of all dataview cells are sent to the Active Console (these are known as IMAGES). Subsequent changes to dataview cells are transmitted as UPDATES to be applied on the Active Console. Updates contain only the minimal set of changes to maintain data synchronisation, similar to a market data tick.
With Subscription mode enabled:
All dataview IMAGES will be sent from gateway to Active Console
Selected dataview cell value UPDATES will be sent from gateway to Active Console only if one or more of the following conditions are met:
- Cells with red/amber severity
- Cells that are being used in an Active Dashboard or Active Chart
- Cells currently being observed by the user in a list view or metrics view
All state and severity UPDATES will be sent from gateway to Active Console
With Subscription mode disabled:
All dataview IMAGES will be sent from gateway to Active Console
All dataview UPDATES will be sent from gateway to Active Console
- Gateway versions 2011.2.1 or later
- ActiveConsole versions 2011.2.1 or later
Active Console versions from GA3.0.0 onwards will have this feature enabled by default.
The following setting will enable subscription mode when placed in the ActiveConsole.gci file.
The setting is recommended for most users and is enabled by default from version 3.0.0 Active Console onwards. To disable subscription mode, remove or comment-out the setting from ActiveConsole.gci and restart the Active Console.
To check if subscription mode is enabled, look for following text in the 'Help ► about' dialog.
------------------------------------------- BDO Sync levels ------------------------------------------- DataView,BDOSyncType_Level,DV1_SyncLevel_RedAmberCells
Searching by cell value
Paths that reference the "value" of a cell may return incorrect results when subscription mode is enabled. It is recommended to avoid using such paths when configuring Search, Reporting, Notification and ListView. If this type of search is a requirement subscription mode should be disabled in the Active Console.
This allows you to change the listerning port of the Active Console by configuring the EMF2 port through the ActiveConsole.gci file.
The main application level menus have the following functions:
- Configure Gateway - the menu that will have a sub-menu for each gateway you have configured in the system. Selecting one of these will open the relevant setup editor (which will vary depending on whether it is an EMF1 or EMF2 gateway).
- Connect to all gateways - ensures that all gateways are enabled (active). See Active Console Overview for more details on gateway connections.
- Disconnect from all gateways - ensures that all gateways are disabled (inactive). See Active Console Overview for more details on gateway connections.
- Workspace - see Workspaces
for additional information on Workspaces. This
menu also lists the names of workspaces you
have previously used.
- New - saves the current workspace configuration and loads a new default workspace configuration. The workspace will next be saved to a file called 'Defaultworkspace.aws' in the working directory. This will silently overwrite any existing 'Defaultworkspace.aws' in the working directory, unless you perform a 'Save as' operation.
- Open - saves the current workspace and opens the selected workspace (.aws file). You can also open a workspace by clicking on its name at the bottom of the Workspace menu.
- Open from URL - allows the user to open a workspace that is located on a URL. See Workspaces for more details.
- Save - saves the current workspace back to the source file.
- Save As... - saves the current workspace to a new file. The current workspace will now continue to save its state to this newly defined file.
- Save Copy As... - saves the workspace to the defined file. This does not make this file the current workspace, i.e. it will continue to save to the original workspace. This is useful when you want to 'Save out' a workspace for a third party without using it as your own workspace.
- Revert - reloads the current workspace from its file without saving first. Your workspace will be reset to the time of the last save.
- History > List of last accessed workspaces - following the Revert menu item will be a list of the last 10 accessed workspaces. If the files to which they refer are not accessible then the menu items will be greyed out. You can also launch the Workspace selector from this menu. See Workspaces for more details.
- Import - a generic function in which you can import a component exported from source files. See Importing into the Workspace for more details on what can be imported.
- Import AC1 configuration - imports AC1 configuration into your workspace. See Active Console Overview for more details.
- Exit - saves your workspace and then closes down AC.
- Undo - undo the last docking operation performed. See Active Console Overview for more information on the docking framework.
- Redo - redo the last docking operation that was undone. See Active Console Overview for more information on the docking framework.
- Layout - from this menu you can take a windows layout from a different workspace and apply it to your current workspace. Only the windows layout will be modified by this action, no other changes will occur to the workspace.
- Command bar - ensures that the command bar is visible. If you hide the command bar you will need this function to get it back.
- Gateways - displays the Gateways View component (if it was hidden or closed it will be displayed in the last known visible location). See Gateways Dockable.
- Metrics - displays the Metrics View component (if it was hidden or closed it will be displayed in the last known visible location). See Metrics Dockable.
- Active Dashboard Manager - displays the Active dashboard manager. See Active Dashboards for more details.
- Active Dashboard Palette - allows users to add context to dashboards.
- State Tree - displays the State Tree component (if it was hidden or closed it will be displayed in the last known visible location). See section State Tree Dockable.
- EventTickers - displays the Event Ticker component (if it was hidden or closed it will be displayed in the last known visible location). See section Event Tickers Dockable.
- Commands - displays the Command Viewer component (if it was hidden or closed it will be displayed in the last known visible location). See section Command Dockables.
- Output - displays the Output Viewer component (if it was hidden or closed it will be displayed in the last known visible location). See section Output Dockable.
- Search Results - displays the Search View component (if it was hidden or closed it will be displayed in the last known visible location). See section Search Function and Dockable.
- Netprobes - displays the Netprobe View component (if it was hidden or closed it will be displayed in the last known visible location). See section Netprobes Dockable.
- Entities - displays the Entities View component (if it was hidden or closed it will be displayed in the last known visible location). See section Entities Dockable.
- Dockable Manager - allows access to the Dockable manager. See section Dockable Manager.
Note: The order of the dockables in the view menu is user definable. See section Dockable Manager for more details.
- Settings - defines the settings for the open workspace. See section Workspace Settings Dialog.
- Create Metrics Overview - menu options that allow you to quickly create a metrics overview. See section Metrics Dockable.
- Diagnostics - opens a diagnostic page on the web browser. See section Troubleshooting.
- Search - allows you to define a search over the data items. See section Search Function and Dockable.
- Reporting - opens the reporting tool. See section Reporting Component.
- Notifier manager - launches the notifier manager, see section The Notifier.
- Workspace level list view settings - allow the users to define the settings used by all the list views in the workspace, unless they have been overridden at a dockable or list view level.
- Gateway Setup Editor - launches the gateway setup editor.
- Table Column settings editor - displays the workspace level column settings models. See section Table Column Settings Editor.
- Path Editor - allows access to the path editor, though clearly the paths will not be used in any context, it is essentially just a scratch pad. You are offered a choice of the DataItem Path Editor or the Geneos URL Editor. See section Referencing Components via Paths.
- Custom Modifier Manager - allows you to supplement the hardcoded modifiers that exist in the workspace with your own custom modifiers. See section Active Dashboards.
- Licenses - display a list of the Active Console components that have their own licences, each of which you can Accept or Decline. If you Decline a licence then the relevant functionality will not be available to you. See section Licensing.
- Show all windows - will move all windows connected to the AC process to the front.
- Attach all windows - all detached windows will be re-docked to the AC.
- Geneos Online Documentation - opens a browser window and takes you to the online documentation.
- About - launches the 'About' dialog. From this you can also create a diagnostic file to send to ITRS Support in the case of problems. See section Reporting Faults and Suggesting Enhancements.
The toolbar contains the functions shown in Figure 2.
Figure 2. The AC toolbar
The toolbar area also contains the SSO Login / Logout button and a search control.
A context menu, called up by right-clicking in the toolbar, allows you to show or hide each of the ‘CommandBar’ (containing the tools illustrated above), the ‘LoginBar’ (containing the SSO login button) and the ‘SearchBar’.
AC is composed of a number of components (or views). They can be accessed via the View menu in the application menu bar. Each component is contained in its own dockable frame (see section Active Console Overview). The available components are summarised here, and discussed in detail in the following sections:
- State Tree - displays the gateways and their directory components in a hierarchical structure which can be displayed in a physical view (gateway / netprobe) or a logical view (ordered by managed entity metadata). This view is the primary means of navigation around AC. See section State Tree Dockable for more information.
- Gateways View - displays information about the gateways that AC is configured to connect to. See section Gateways Dockable for more details.
- Netprobes View - displays the list of netprobes known to the gateways that AC is configured to connect to. See section Netprobes Dockable for more details.
- Entities View - contains a set of entity tabs, each of which contains a list of managed entities. See section Entities Dockable for more details.
- Metrics View - contains a set of metric tabs, each of which contains a list of samplers. See section Metrics Dockable for more details.
- Event Tickers - contains a set of event ticker tabs, each of which contains a list of events. See section Event Tickers Dockable for more details.
- Active Dashboard Manager - allows you to draw Visio type diagrams of your system, including charts and gauges, see section Active Dashboards for more details.
- Active Dashboard Palette - used to add content to dashboards, see section Active Dashboards.
- Search View - displays the results of a user defined search over the available directory components. See section Search Function and Dockable for more details.
- Command Viewer - displays a list of the running, pending and completed commands. See section Command Dockables for more information.
- Output Viewer - displays the output of completed or currently executing commands. See section Output Dockable for more details.
AC uses icons and colour to convey information about the state of the system to the user in a simple and effective manner. This is explained below:
The following icons are used throughout the application to represent the data items:
|Data Item||Example Icons|
The colour of icons that represent directory components will change depending on the component's severity, snooze status and any rules which are currently active.
- Grey - in Gateway 2, this means no rules have been triggered on this component or its children so its severity is undefined.
Note: This is not equivalent to AC1 where grey means disconnected.
- Green - in Gateway 2, a rule has triggered that tells the system that the directory component and its children are OK. This colour will override grey.
Note: This is not equivalent to AC1 where it will be green if a rule exists on the item and the rule has not set it to warning or critical.
- Amber - a rule has been triggered that tells the system that the data item or one of its children is in a WARNING state. This colour will override green.
- Red - a rule has triggered that tells the system that the data item or one of its children is in a CRITICAL state. This colour will override Amber.
- Blue - a rule has triggered that sets the cell to inactive or outside active time.
Where data items have an error the following icons will be used:
|Disconnected||The data item or the data item this is published from is disconnected|
|Error||The item has a general error; more information should be available via its properties dialog (see section Properties Dialogs).|
|Unreachable||The Geneos component (gateway or netprobe) on which the data item sits (or is published from) is unreachable. Usually (but not always) this means that the host on which the component runs is unreachable.|
|License Warning||The component's licence has expired|
|Rejected||The connection to this item has been rejected|
|Suspended||The connection to this item has been temporarily suspended|
|Waiting||The AC is waiting for a response from the data item|
Icons are used in AC to represent both the function and the state of data items. We overlay them to convey additional meanings as explained below:
|Snooze||Data item itself is snoozed.|
|No Samplers||Connected managed entity has no samplers.|
|Inactive||Data item is inactive.|
|Knowledge Base||Item has one or more knowledge base entries.|
|Inactive children||Item contains one or more children that are inactive.|
|Assigned User||Item is assigned to a user|
|Snoozed Child||Data item has one or more descendants which are snoozed.|
|Snoozed Ancestor||Data item has one or more ancestors that are snoozed.|
|Snoozed ancestors and descendents||Data item has snoozed ancestors AND descendants.|
|No Logging||Data item should be logged to the database, but the gateway is not connected to the database.|
|Geneos component error||
One or more geneos components (Gateway or Netprobe) under the data item have an error, which means it is not connected.
Error icons related to Disconnection, suspension, and licence expired are listed in section Active Console Overview.
|Probe suspended||Probe has been suspended.|
|Log to database||Data item is logging to database.|
|Load Monitoring||Identifies which Gateway feature is using the most processing time in the gathered statistical sample.|
|Gateway Hub||Indicates that Gateway Hub is enabled. Data is publishing to and can be retrieved from Gateway Hub. This icon appears at the dataview and Gateway levels.
For more information, see Gateway Hub.
The AC GUI uses a docking framework where all the components listed in section Active Console Overview can be viewed and positioned anywhere the user wishes. In this context these components are known as dockables. An example of a dockable is shown in Figure 3.
Figure 3. An example dockable
Each dockable has a number of inherent capabilities which the user can exploit to set the position and size of the component in the interface. See section Active Console Overview.
- Movable - triggered by pressing and holding the mouse pointer on the component and then moving the mouse.
- Combine / un-combine with another dockable - dockables can be combined with other dockables to form tabbed (modal) views. This is triggered as part of a move operation.
- Auto-hide - tells the component to automatically minimise itself if the user is not interacting with it.
- Float in window - will remove the component from the main interface and place it in its own independent window.
- Close - will remove the dockable from the interface. This does not destroy the dockable but simply hides it.
- Maximise / minimise - double clicking on the title bar of a dockable will force it to take all the available space in the application window. Double clicking it again will restore it back to its previous size.
Dockables can be moved in the AC interface in relation to other dockable components. This is achieved by pressing and holding the left mouse button on the title bar of the dockable you want to move, then dragging the mouse to the new location and releasing the mouse button. The component must be moved to a position relative to another component. To do this, move the mouse within 80 pixels of the selected edge of the target component as shown in Figure 4.
You can also dock a dockable in relation to whole application window (rather than another dockable), for example you may wish to dock the state tree so that it fills the whole left hand side of the application window (from top to bottom). To do this, simply drag the dockable so that the mouse pointer is within 80 pixels of one of the application edges.
Figure 4. Moving a dockable
Dockable components can be combined together to create a dockable frame that contains multiple dockable components. These components are accessed via tabs situated at the bottom left of the combined dockable component. To create a combined dockable component, select the dockable you want to combine with another by pressing and holding the mouse over the dockables title bar. Then drag the component into the centre of the target dockable (the centre being at least 80 pixels from the edge of the target dockable) as illustrated in Figure 5.
Figure 5. Combining dockable components
To un-combine a dockable from another drag its tab out from the set of tabs at the bottom of the dockable it's present in, once undocked you can drag it like any other dockable.
Dockables can be configured to auto-hide themselves when you are not interacting with them. To do this click the Auto-hide icon in the top right of the relevant components title bar. The dockable will be minimised to the edge of the application that the dockable shares the longest edge with. Figure 6 provides an example of this.
Figure 6. Auto-hiding Dockables
To re-display the auto-hidden dockable, move your mouse over the tab. It will redisplay after a short pause. It will not auto-hide again until you have moved the mouse off the dockable. If you click on the dockable (and therefore give it focus) it will not auto-hide until you click elsewhere. Auto-hiding components is useful if you want to work with many components at the same time without closing them, since they only take up screen real estate when you are interacting with them.
A dockable can also be detached from the main application window by clicking on the relevant button in the dockable toolbar. This window will maximise and minimise along with the main application window. To re-dock simply click on the float in window button on the dockable again.
If the dockable is a system dockable and the close button is pressed, the dockable will simply be hidden; it will not be removed from the application. It can be brought back via the 'View' menu on the application menu bar.
If the dockable is a locally defined dockable, then depending on the close action set for the dockable in the dockable manager, the close action may either hide the dockable or remove it completely from the system (see section Dockable Manager).
If the 'Frames Hideable' setting in the 'Advanced' section of the ActiveConsole settings is set to false, then pressing the close button on dockables will have no effect (dockables will remain visible).
A dockable can be quickly resized to fill the whole application window by double clicking on its title bar, To minimise it back to its original size double click on the title again.
You can undo your last 10 docking actions by using the View > Undo function from the main application window. This allows you to recover if you get the docking into a confused state.
You can also replace docking actions that you had previously undone by using the View > Redo function.
As well as being able to detach a whole dockable from the main application window you can also detach a single tab from a dockable that contains tabs. To do this right click on a tab in a tab bar (Figure 7) and select the 'Detach' function.
Figure 7. An example tab bar
This tab will be added to its own frame. Minimizing, maximizing and resizing this frame can be done independently of the main application window. The actual tab from which the window was created is not removed from the dockable, but remains acting as a proxy for the tab. This proxy continues to show the severity of the items, and has functions to reattach the tab and force it to display at the front of any windows (using the show button). Figure 8 shows an example of detaching a tab.
Figure 8. Detaching individual tabs
You can quickly reattached all tabs that have been detached via the Tools > Attach all windows menu item in the main application window. You can also force all detached tabs to come to the front by using the Tools > Show all windows function.
You can create a new tab in a dockable which supports tabs by any of the following methods:
- Double click in the tab area.
- Right click on an existing tab, or anywhere in a view which has no tabs and select 'New tab'.
There are two functions available on tab bars that allow you to close multiple tabs at the same time (these functions can be accessed via the right click menu on any of the tabs):
- Close All - will close all tabs in the selected tab bar. The only exception is if one the tabs is a primary tab (it will have an icon), which will not be closed when this function is invoked.
- Close Others - will close all tabs in the selected tab bar except the tab that you right clicked on to get the 'Close others' menu option. The only exception is if one the tabs is a primary tab (it will have an icon), which will not be closed when this function is invoked.
The Workspace Settings dialog is available via the Tools menu or the Settings button in the application toolbar. It allows you to configure the global settings for the current workspace including connections to gateways. The sections available in the settings dialog are discussed below.
The following settings can be set in the general settings area:
Figure 9. The Workspace settings
- Title - appears in the application title bar. It will be prefixed with the string "Geneos Active Console".
- Background Colour - defines the background colour of all the dockable components.
- Font size - defines the size of most of the text in AC components.
- List View dimensions - using these settings you can define how large (or small) a-space icons take up in each of the list view modes, with the inclusion of the List view (see section Active Console List Views) this only effects the Gateways view (see section Gateways Dockable).
- Transparency - the visibility settings define how opaque the various visual indicators are in AC components. Using these settings can make the selected indicators more prominent than others. In all cases, 100% means they are completely invisible, while 0% means they are completely opaque. See section Active Console Overview for a list of the available indicators.
- Workspace is read only - configures the workspace as read only, the AC will not save back to the workspace between sessions, see section Workspaces for more details.
- Auto load last good workspace - stops the workspace selection dialog from being displayed on start-up, instead the last workspace will be automatically loaded. See section Workspaces for more details.
- Auto-save Period - defines the period in minutes between automatic saves of the current workspace configuration to a temp file, see section Workspaces for more details.
- Max Auto saves - limits the number of auto save files that the AC will create, see section Workspaces for more details.
- Save on exit and workspace switch - will auto save (without prompt) the workspace when the AC is shut down or a different workspace loaded, see section Workspaces for more details
- View Path - an ordered, case-sensitive, comma separated list of the managed entity attributes you want to use to group the managed entities in the state tree when the state tree is in Viewpath mode. See section State Tree Dockable for more details. You can see all the view path values for the managed entities on your system by right clicking on this setting.
- Order Preference - by default the state tree is alphabetically ordered, you can however override this order by entering values into this field. Items in this field will appear at the top of state tree branches before the remaining items (which will be alphabetically ordered), see section State Tree Dockable for more details of this function.
- Stay on top - if this flag is
ticked then the Active Console will remain on top of
the other application windows.
This only works if the Active Console is using Java 1.5 or above.
The connection settings define the Gateway that AC will connect to when the workspace is loaded and applied.
Figure 10. The Connections pane in the Settings dialog
It will also define the logins that the connections will use. The dialog has the following settings:
- Workspace Logon - defines the default logon that will be used against the configured gateways that have not had an individual logon defined. This can be configured to use the system login, a normal /manual logon, in which case you can enter the required user name in the text box below the login mode, or SSO (see SSO Authentication).
- Connections - allows you to define an explicit list of gateways for the workspace. When a gateway connection is defined locally in this way you can specify whether you want it to come up active or disabled, and you can also assign it a name, override the workspace logon with a specific logon method for this gateway, and assign it a secondary host and port name which will be used if the AC fails to connect to the primary host and port.
- Listen port settings - the port that AC listens on. As a rule you should leave this at its default setting
Note: It is possible to define many remote gateway files and local gateway connections that may map to the same gateway(s). This is not an issue as AC will not duplicate actual gateway connections. It may be useful to know however, that the contents of the local connection settings will be used before the gateways defined in remote files. Thus if you have specific 'logon' and 'enabled' settings for a local gateway definition then they will take precedence over remote settings. See section Active Console Overview for more information on this.
Active Console supports remote connection files that require Kerberos authentication or files that are hosted in a Kerberized web server. When Active Console cannot read the remote connection files, you are presented with the following error message:
This section defines a list of database connections which can be used by other Active Console components (primarily Active Charts and the Event Ticker).
There are two main sources of database connections, those that are provided by the gateways you connect to, and those you manually add.
The top (read only) list in the dialog displays the connections provided by the gateways, while the bottom list can be modified to manually define additional database connections.
Figure 11. The Database pane in the Settings dialog
The Gateway Hub serves as the back-end storage and processing for data that is produced and consumed by ITRS products, such as Geneos and Capacity Planner. It can store and retrieve all data published from the Gateway to provide basic metric history.
This runs alongside the Active Console, Gateway, Netprobe, and Web Console.
The Gateway Hub icon appears at the dataview and Gateway levels to indicate if data is publishing to Gateway Hub.
The system tray section allows you to define the system tray behaviour for the workspace.
Figure 12. The System tray settings
The following settings are available:
- Minimise to System tray - if this tick box is checked then the Active Console will minimize to the system tray rather than the task bar.
Note: The option Minimise to System Tray is available for Windows Vista and XP. But in Windows 7, the option is Show in System Tray which, if checked, will cause the Active Console to minimise to taskbar as well as system tray.
- Use Paths for severity - by default, the colour of the system tray icon will represent that of the global state (the highest severity of a connected gateway). You can if you wish override this default and define a subset of data items that should drive the colour of this icon. When using paths to define the colour of the system tray icon, the worst severity of a data item that matches one or more of the paths will define the icon colour.
- Paths - if you have ticked the 'Use Paths for severity' then you need to define the subset of data items that will drive the colour of the system tray icon via a set of paths. The paths can be added and removed via the + and - buttons on the left of the path list, while the paths can be edited by selecting the relevant path and clicking on edit in the drop down box which will appear, this will take you to the path editor (see section Referencing Components via Paths) in which you can modify the path. Paths here can only go down to the Data view level, this functionality will not work for cells.
The tooltips section of the workspace allows you to define for each data item type the tooltip information that will appear when you hover over data items of the specified types. For example if you select 'Severity' and 'Snooze' for Sampler, then every time you hover over a sampler you will see its severity and snooze in the tooltip. An example of the Tooltip interface is shown in Figure 13.
Figure 13. Setting the tooltip contents for data items in the workspace
These tooltip selections affect all dockables throughout the workspace. You cannot define the tooltips for separate instances of a dockable.
The content of tooltips are defined on a dataitem by data item basis, such as Gateway, Directory, Probe, Entity, Sampler, DataView, and Variable.
Enable each data item with a single click if you want to run its tooltip. Also, you can modify their order by using the up and down arrows to the right of the list. Items at the top of the list appear above the others when the tooltip is displayed.
Note: In a List View, a property will only be displayed in the tooltip if it is also selected in the List View properties (see section Active Console List Views). If a property is not selected in the List View properties, it will not be displayed in the tooltip even if it is selected here in the ActiveConsole settings.
The advanced settings allow you to define the behaviour of the docking, tab and window framework, as well as some other advanced configurations options. All the settings are discussed below.
Figure 14. The advanced workspace settings
The available advanced settings are as follows:
- Maximum rows for a metrics overview - Metric Overviews allow you to combine multiple data views into a single metrics view (see section Metrics Dockable for more details), but it is impractical to compile thousands of rows into a single table. This setting limits the maximum number of rows that can exist in a single metric view.
- Dashboard refresh (seconds) - determines how frequently the dashboards evaluate their modifiers, see section Active Dashboards for more details.
- Update history widget after DB import - determines whether graphs plotting historical data will also plot current data. If set to False, the graph will only display historical data.
- Event ticker old events removal rate (seconds) - determines how frequently the event ticker purges old events that should be removed due to a filter, see section Event Tickers Dockable for more details.
- State tree leaf type - determines what the leaf nodes are in the state tree, see section State Tree Dockable for more details
- Snooze stops error propagation - if set to True this means that data items in an error state which are snoozed will not cause the error symbol to appear on the ancestors in the tree.
- Gateway setup editor as a separate
process - if set to True, the Gateway Setup
Editor is launched in its own process. The Active Console passes the following connection information to the GSE:
- Primary Host
- Primary Port
- Logon method
- Secondary Host
- Secondary Port
Note: When the GSE is launched as a separate process, SSO logon is not supported. All other logon methods are supported.
If the GSE experiences a problem as a separate process, it does not affect the Active Console.
See Starting Gateway Setup Editor for more information.
- Use Large Error Icons - if set to True then error icons (described in section State Tree Dockable) will be twice as large. This is useful if connection problems to geneos components are of particular interest.
- User readable path cache size - determines the maximum number of readable paths that the Active Console will store internally. The default number is 10,000.
- Default data source - indicates the source if it is Database Logging or Gateway Hub.
- Frames floatable - see section Active Console Overview for more details of floatable frames. If this value is True then it is possible to float frames in their own windows, otherwise you cannot.
- Frames auto hideable - If this value is True then it is possible to auto hide frames in their own windows, otherwise you cannot.
- Frames Hideable - If this value is True then it is possible to hide frames in their own windows, otherwise you cannot. When the value is set to false, the close action of all dockables is set to 'Not Closable' and cannot be altered by the user.
- Frames re-arrangable - if set to True then frames can be moved around within the docking framework.
- Resizable - if set to True then dockable frames can be resized with respect to each other frames, i.e. you can change their width and height within the AC frame, if this is false then you cannot resize them.
- Continuous Layout - if set to True then when you resize frames they reposition immediately. If set to False then a simple line will appear suggesting where their new width / height will appear. It is suggested that on lower specification machines this be set to false.
- Easy tab docking - if set to True then frames can be docked together to create modal frames by dropping dockables into the centre of other dockables, see section Active Console Overview for more details.
- Title bar dragging all tabs - by default when you dock one frame with another to create a modal frame (see section Active Console Overview) only the currently selected / visible frame will be docked with the target frame. If this setting is set to True then all frames within the frame you drag via the title bar will be merged with the target frame.
- Show frame gripper - in the top left of each frame there is a small gripper, this setting determines whether this appears or not. This is a simple aesthetic setting.
- Show frame title bar - determines whether the frames have a title bar.
Note: If this is false (and therefore they do not have title bar) then almost all the docking framework functionality will be inaccessible.
- Side bar rollover - if frames have been auto hidden and this setting is true, then when the mouse hovers over an auto hidden frame tab then the frame will appear. If this value is false, then the user must click on the auto-hidden tab to make the same frame appear.
- Allow nested floating windows - if true the docking behaviour that occurs in the main application window (see section Active Console Overview) can also occur in undocked (or floating) windows.
- Dragging Mode - determines how the
grey frame will show where a floating frame will
end up when dragged. The options are:
- Full outline mode (default) - enable this setting to show the full outline view of the dockable when you drag it from one location to another.
- Partial outline mode - enable this setting to show the partial outline view of the dockable, including the preview of the dockable's tab location.
- Mix outline mode - enable this setting to use the behaviour of both full and partial outline modes.
- Use Normal Frames for undocked components - if true then when you undock components they will appear in conventional window frames, which can move resized, maximized and minimized. If false, then the windows will appear as docking framework frames, which can only be resized.
- Embed tabs when detaching - determines whether a tab should appear in the detached window when a tab is detached. If set to false then the tab will not appear at the top of detached window. Tabs are generally coloured with the worst severity of all the items they contain, so can be useful, but on the down side they take up screen real estate.
- Use Dialog when detaching - determines whether detached tabs should be displayed in dialog windows, rather than normal windows. Dialog windows differ from normal windows in two main ways, namely that they are minimized with the main application window (normal windows remain), have no minimized and maximize controls, and have a presence in the OS task bar.
- Show tab close buttons - determines whether tabs have a close button on their right hand side. If this is not the case then the only way to close tabs is to right click on the relevant tab and select the close button. The figure below illustrates this function.
- Show close button on tabs - only applicable if the 'Show tab close button' setting is true. If this setting is false, then tabs are closed via a communal closed button situated on the right hand side of the tab pane. Pressing this close button will close the currently selected tab
Show gripper on tabs - determines whether a gripper should be displayed on the tabs, this is a simple aesthetic setting.
Bold Active Tabs - determines whether the currently selected tab(s) should be shown using a bold font, making them stand out further from the non selected tabs.
Tab Resize mode - determines how tab bars which have multiple tabs are displayed. The following modes are available:
- Default - the default setting for the application (which is none).
- Fit - will fit all the tabs into the available tab area, this will mean the tabs will get smaller and occluded by other tabs as the space becomes inadequate for the tabs, but all the tabs will be visible.
- Fixed - will fix the width of all the tabs, if their titles are longer than their width then it will be cropped.
- None - tabs will be as wide as they need to be to display their title, if the tab area is too small to display all the tabs then arrows will appear on the right of the tab area allowing to scroll over the tabs.
Output - determines whether output windows (see section Output Dockable) should appear in a tab in the output viewer, or in a detached frame. Once the output window has been created it can be moved between these modes freely as you wish, this is just the starting position.
Show enhanced tooltips - determines whether tooltips should be displayed for data items.
Use styled output in a single stream - if set to True, any command elicited from the Active Console that will result in text output will be formatted. This is the default.
Look and feel - the look and feel of the docking framework. The present options are:
Wherever you see a data item in the Active Console interface you can right click on it and select a properties menu item. This will produce a dialog similar to Figure 15. The Properties dialog displays all relevant properties for the selected data item broken down into general categories. If the Auto update tick box (at the bottom of the dialog) is checked then these values will update as and when they change. Values can be cut and pasted from the fields, and categories collapsed and expanded.
If the Auto update is off, then the values can be updated via the refresh button. You can have as many properties dialogs open at the same time as you like, but their presence is not saved and restored with the workspace.
Figure 15. An example of a Properties dialog (in this case for a managed entity)
At the bottom of the dialog is a 'Copy all' button which places the contents of the dialog on the system clipboard.
The State Tree dockable displays the contents of all the gateways known to AC in a hierarchical view. It can be displayed in one of two modes, which can be toggled by selecting the relevant item from the right click menu on the state tree, or the State Tree view mode icon on the toolbar.
- Viewpath (logical) - constructs the tree with logical attributes of the managed entities using the view path configured in the settings dialog. See section State Tree Dockable for more details. Only managed entities and their sub-components will be available in this mode.
- Netprobe (physical) - has the gateways as the primary nodes, then their components nested by netprobe, managed entity, and sampler.
An example screenshot of the State Tree view in these two modes is shown in Figure 16 below:
Figure 16. The State Tree
The tree is read only, in that its contents is defined by the gateways and their setups and cannot be modified directly by the user. Each element is represented by its icon (see section Active Console Overview) and its name. Like all tree views the branches can be expanded and contracted as required.
Most of the data items available are in the tree. Their functions can be accessed by right clicking on the relevant item and using the resultant pop-up menu. Selecting items in the tree will update the primary Entities, Metrics and Event Tickers views.
The view path is used when the state tree is in Viewpath mode (logical). It uses the managed entity attributes to sort the tree into logical groups. If no view path is defined the state tree will simply contain a list of all the managed entities configured in the connected gateways. Once a view path is defined the state tree will group together managed entities that have the same attribute value. For example, let's say we have 4 managed entities:
- ME1, with attributes 'Country = England' and 'City = London'
- ME2, with attributes 'Country = France' and 'City = Paris'
- ME3, with attributes 'Country = England' 'City = London'
- ME4, with attributes 'City = Hong Kong' and 'OS = Windows'
- ME5, with attributes 'Country = England' and 'City = Manchester' and OS='Linux'
- ME6, with attributes 'Country = France'
And a view path setting of 'Country, City, OS'. The tree would be organised in the following way:
- Hong Kong
The items are sorted by the attributes defined in the view path in order. So in this case the system will try and get the Country attribute of all the managed entities and create entries for each unique Country before putting the relevant managed entities under each Country. It will then sub divide the set of managed entities under each unique Country by the second attribute, i.e. City. This process continues until all the view path attributes have been applied.
Where a managed entity does not have a value for a given attribute (in the example above ME4 does not have a Country) it will not be classified under an instance of the attribute (e.g. England) but instead will be inserted at the same level in the tree as the unique values for the attribute, i.e. it will have the same parent as the attribute. The net result is that gateways can have entirely independent view paths, and still be displayed successfully in logical view mode.
The definition of the attributes in the view path setting is case sensitive.
The state tree also displays the snooze status of data items displayed in it. This includes not just whether the item itself is snoozed, but whether it has descendents or ancestors that are snoozed as well. The icons and their meanings are discussed below:
|The data item itself is snoozed|
|The data item is not snoozed but has 1 or more descendents that are snoozed|
|The data item is not snoozed but has 1 or more ancestors that are snoozed|
|The data item is not snoozed, but has 1 or more descendants and 1 or more ancestors that are snoozed|
In the event that netprobes and gateways are in an error state (i.e. disconnected, unreachable) a small road sign will appear in the bottom right corner of their state tree representation. This propagates up the state tree all the way up to global state. Therefore if a state tree item contains an item which has a geneos error then it will also display the road sign. Examples of this can be seen in Figure 16.
You can make this road sign large by changing the advanced properties, see section Workspace Settings Dialog.
Via the Advanced workspace settings, it is possible to stop the propagation of the geneos errors up the tree for data items which are snoozed. For example under normal operation if a net probe is disconnected and not snoozed an error triangle would propagate up to the global state, however with this flag set to true, if the probe was snoozed, the error propagation would not progress up the tree (but would be displayed and stop on the probe).
Note: Because only Managed Entities can be slept to GW1 all MEs on a disconnected probe must be snoozed to stop the propagation.
By default, all items in the State Tree are ordered alphabetically.
You can force specified items to occur at the top of the items at any given level in the state tree by specifying them in the Order preference field.
- In Active Console, go to ActiveConsole Settings > General > Order preference field.
- Type the order preference.
- Click Apply, and then click OK.
Figure 17. Specifying Order Preference
The definition of order preference is case sensitive; any item that occurs in the state tree can be specified in this way. You can specify many items in the Order preference (separated by commas) with items at the beginning of list taking preference over items at the end of the list.
You can restrict the level of data items that appear in the tree. This setting is defined in the advanced workspace settings (see section Workspace Settings Dialog). The following options are available:
- Data View - the state tree will allow you to navigate down to the data view level.
- Sampler - the state tree will allow you to navigate down to the sampler level, but not data views.
- Managed Entity - the state tree stops at the managed entity level, it will not display samplers or data views.
Note: The primary reason for restricting the data items in the state tree is performance. Stopping at the Managed Entity level will be more efficient for example than stopping at the Data View level. Workspaces that connect to lots or large gateways will see significant performance gains on start up if the state tree is restricted.
The Gateway dockable displays a read only list of the gateways that are currently configured for AC. When displayed using large icons relevant visual indicators will be shown with the gateway icons (see section Active Console Overview).
Figure 18. The Gateways view
Right clicking on a gateway will allow you to edit its configuration, disable or enable it, run commands appropriate to gateways, and RMS functions (currently supported for EMF1 gateways only via AC1).
The gateways can be displayed in a number of different modes. The modes can be toggled by the right click menu in the view. The view modes are as follows:
- Thumbnails - displayed in a grid format, with large icons and the name of the component.
- Tile - displayed in a grid format with additional information.
- Details - a table format where the left hand column contains the item and its icon and the remainder of the columns display additional attributes of the items. The tables can be sorted on any of the columns.
- List - a simple list displaying the items, with a small icon and their name, from top to bottom.
- Icons - a compressed thumbnail view where each item is allocated less space, so that more of them can be displayed in the same space.
The gateways can also be sorted into logical groups, where each item in the group shares a common attribute with the other items. An example of a Gateways view sorted into groups can be seen in Figure 19.
Figure 19. The grouping functionality
Grouping is a toggle mode, i.e. a Gateways view can either be grouped or ungrouped. The attribute that is used to group the items together is the same as the column by which the detailed view is sorted. In all cases the groups themselves will be sorted into alphabetical order. Access to the grouping functionality is either via the right click menu or from the buttons in the top right of the title bar of the list view component as shown in Figure 19.
The contents of the Gateways view can be exported as a report to disk in the CSV format. This functionality is exposed right-clicking in empty space in the Gateways view and selecting the "Export…" option. This brings up a dialog in which the user can configure the destination of the saved report.
Where gateways are configured with secondary connections (hot standbys), they will have a slightly different icon in the gateway view. Examples are shown in Figure 20.
Figure 20. Hot stand by icons
The primary gateway icon will display in front of the secondary gateway. If a gateway (primary or secondary) is up it will appear solid, and be coloured for its severity. If it is down then it will appear partially transparent and be grey. Examples of the three possible combinations (of gateways being up or down) are shown in Figure 20.
License information for the gateways is available if you switch the gateway view to Details view (see section Gateways Dockable) and find the 'License expiry' column. If gateways are coming to the end of their licence period then a warning will be displayed in the output viewer (see section Output Dockable).
Active Console 2 displays a licence warning message when the Gateway connects to an expired licence.
The netprobes dockable is a list view (see section Active Console List Views) that is configured by default in new workspaces. By default it has a single tab that displays all the netprobes currently connected to the Console (via the connected gateways).
Like any list view you can remove it from your workspace via the dockable manager (see section Dockable Manager), and restore it after a delete by importing it (see section Active Console List Views. Additional tabs created in the probe view will display only probes. If you drag and drop a data item into a tab in this view it will locate the probe relevant to the item and add it to the view.
The entities dockable is an instance of a list view . It is configured as default in a new workspace. By default the entities view has a single tab, the contents of which will follow user selection.
When following user selection it will display all entities relevant to the selected item, for example if a gateway is selected it will display all the entities in that gateway, if a data view is selected it will display the entity that is an ancestor of that data view.
The first tab is also configured to auto group based on the user selection.
If additional tabs are added, they are configured by default to display only entities. When you drag and drop data items into such tabs, the following will occur:
- Drop global state, a gateway, netprobe or view path folder - the entities within these items will appear in the view, the contents will automatically update as these entities change, including the creation of new entities, or removal of existing ones.
- Drop an entity - if you drop an entity you will be presented with 2 choices, the first is to drop it in such a way that it will only appear in the list view if the ME is connected to the console (using a dynamic path), and the second means there will always be an entry in the tab for the entity, regardless of its connection status (Static).
- Drop a sample, data view or cell - will locate the entity that is an ancestor of the selected data item, and add it to the tab.
Like any list view the entity view can be removed from the workspace via the dockable manager (see section Dockable Manager), and restored via the import function.
For full details of the functionality available within list views (including the entity view), see section Active Console List Views.
Before reading this section you should ensure that you under understand what is meant by the term 'Data item' which is covered in section Glossary, and used extensively in the following text.
The purpose of the list view component of the Active Console is to allow the user to create a number of dockables that contain tabs, where each tab contains a set of related data items. By default a new workspace will contain a dockable for the display of entities (see section Entities Dockable), a dockable for probes (section Netprobes Dockable), and a dockable called the Items of Interest that follows user selection and reports on the critical and warning cells under the currently selected data item in the console.
The user however is not restricted by this default configuration, they can in fact create as many new list view dockables as they wish, which can be configured to display any set of data items from the gateways to which they can connect. The user can even remove the default ones.
This section provides a detailed overview of this list view functionality.
Shown in Figure 21 is a list view dockable with a number of list views.
Figure 21. A list view dockable
Each list view is contained within its own tab. As a user you can have as many list view dockables as you like within a workspace, which in turn can have many list views. Each list view is configured to display a list of data items, the exact data items it displays is determined by the paths that it is configured with (see section Active Console List Views). Most list views are dynamic, in that as data items are added, removed and change state, so the various list views you have configured will change.
There are a number of ways that a new list dockable view can be created. This section outlines the approaches:
- Via the dockable manager - the only method of creating an empty list view dockable with no configuration. To do so, go to the dockable manager, via the application level' View > Dockable manager', click the '+' symbol on the left of the list, select list view from the available dockable types, give it a name, then come out of all dialogs pressing OK. See section Dockable Manager for a more detailed overview of the dockable manager.
- Importing a list view (.ltv file) or list view dockable (.ado file) - you will need an existing file, which you can then import via the application level 'File > Import' function. See section Active Console List Views for more details.
- Via a search (or report) - you can dump the results of a search to a new dockable, see section Search Function and Dockable, this can be a very quick way of generating a dockable, but restricts the configuration that can be initially setup (though the configuration can be changed at a later date as required).
The term list view refers to a tab within a dockable that has a number of paths configured within it, such that at any given point in time it is displaying a number of data items from the gateways that the Active Console is connected to. That last sentence said a lot, and in effect was a summary for the remainder of this section, so let us break it down and step over the points one by one. Before we get going, Figure 21 shows an example of a list view so you have a context to work from.
The principal purpose of the list view is to create ordered and grouped lists of these data items, into views which are useful for you as a user. For example you may have all Managed Entities in a selected country in one view, all snoozed items in your system in another, or everything assigned to you at a given point in time in a third view.
The term 'List view' refers to a single tab within a list view dockable. The term list view dockable refers to a single dockable that contains 1 to many list views.
At their most primitive level Active Console list views are simply collections of data items (see section Glossary for a definition of data item). What data items are present in a list view is defined by a set of paths. For a data item to be present in a list view it must match one or more of the paths configured on the view. With the exception of static paths (which are covered in section Active Console List Views and should be considered as a bit of an edge case), if a data item matches more than one of the paths then it will still only appears once in the list view (there are no duplicates)
Here are some example paths and the data items that would match them:
Note: Paths are shown in user readable form, you'll not be able to type these directly into a list view.
- //managedentity (severity = critical) - will create a list view with all critical managed entities.
- //managedebtity (snoozed = false)//cell (severity > 1) - all cells that have a severity of warning or critical that are in an entity that is not snoozed
As you may already have gathered a list view can have many paths, if you consider that at any given point in time each of these paths will match 0..* data items then the contents of a list view at time X will be union of these sets, with no duplicates.
As gateways are connected, disconnected, change state or are re-configured, data items may be added or removed from a list view dynamically. For example a list view configured with a single path:
- //* (snoozed = true)
will match all snoozed items in the system. If an item is snoozed by a user, then it will dynamically appear in this list view, if it is then unsnoozed it will be removed.
There are three main types of path that can be configured within a list view, they are as follows:
- Dynamic - paths that will ensure that all data items that match the specified path at any given point in time are present in the list view as individual items / rows. The term dynamic refers to the fact that this set of matching items is likely to change (or be dynamic) over time covers dynamic paths in more detail.
- Static - paths that will only ever insert 1 and only 1 entry into a list view, regardless of how many data items its associated path matches, They also allow the same data item to be inserted into a list view multiple times.
- Follow Selection - path that allows the user to configure a view to dynamically update based on their selection in other parts of the Active Console, for example in the state tree, event ticker, or other list views.
The path types are covered in more detail in the following sections.
Dynamic paths will ensure that all data items that match the specified path at any given point in time are present in the List View as individual items / rows. The term dynamic refers to the fact that this set of matching items is likely to change (or be dynamic) over time.
If a given data item matches more than 1 dynamic path in a single list view then that item will only appear once, and only be removed once all matching paths have been removed from the list view.
Static paths will only ever insert 1 and only 1 entry into a list view, regardless of how many data items its associated path matches. There are 3 cases to consider here:
- Matches 0 data items - a question mark will be shown to represent the path.
- Matches 1 data item - the data item will be shown in the normal way.
- Matches more than 1 data item - in the details mode, this will appear as a row with a number of child rows, equal to, and displaying the number of matching data items; in any of the icon based views it will appear as a folder.
Figure 22 shows some examples of static paths within a list view in each of its states.
Figure 22. An example of a static path and its display in a list view
The colour of the static entry will represent the highest severity of any of the matching items.
The term 'static' refers to the fact that it inserts a single entry into the list view, it does not imply that the data items that it matches will not change.
Static items have one principal advantage over dynamic paths in that if a dynamic path matches no data items the list view would contain no items, where as if the path is configured as static there will be an entry, albeit a question mark. This means that you can get a permanent entry for a data item, independently of the gateway's connection status, in the list view. It is also required to replicate the older style (GA2009.1) custom entities view, where, if an entity was inserted into the view a question mark would display if the gateway it was part of was not connected.
In the event that the static path matches 0 or more than 1 item then the name of the static path itself will be used in the list view rather than the name(s) of the data item it matches. The name can be set via the Path configuration dialog, see section Referencing Components via Paths. An example of this can be seen in Figure 22.
Follow user selection paths allow users to configure all or part of a list view to update based on the users selection in other areas of the console (such as the state tree and other list views).
Unlike the static and dynamic paths a follow user selection path is composed of a geneos URL (see section Referencing Components via Paths) rather than a data item path. At its simplest the path will be as follows:
Note: This is the user readable version of the path and cannot be pasted directly into the console.
If left unmodified, whenever you make a selection the selected data item would appear in the list view, i.e. if you selected Managed Entity X, then X would appear in the list view. This obviously has limited value so it is likely that using the geneos URL editor the designer of the list view would add some modification rules to the URL which mutate the selected data items path before it is added to the list view. What rules you can apply, and how they work is the subject of section Referencing Components via Paths, but here are a few examples (again written in the shortened user readable form), and an explanation of what they would do:
- Geneos://ac/userselection/append( //dataview ) - would show all the data views under the selected item
- Geneos://ac/userselection/merge( //managedentity (snooze = false ) ) / append ( //cell (severity = critical)) - would show all critical cells under the selected item, that were not a descendent of a managed entity that was snoozed
Most of the properties for a list view are accessible exclusively via the list view properties dialog. To get to this dialog use the 'Properties' button from the status bar (see section Active Console List Views), or right click in the list view and select 'Configure > List View'. Either way you will then see the dialog shown in Figure 23.
Figure 23. The list view configuration
The dialog contains the following sections of Active Console List Views:
- Content Paths - dialog that allows you to define the paths that will populate the list view.
- Filters - allows you to define temporary filters on the list view which restrict the data items that displayed.
- Drag and Drop - defines what should happen when data items and other paths are dropped into the list view.
- General Visual - allows you to define some general aesthetic properties of the list view.
- Details View - allows you to specify other visual aspects of the details (table) mode of the list view.
- Properties - dialog that allows you to select which data item properties are listed in the view.
The Content path dialog is a sub-section of the larger list view Properties dialog. It allows you to add, remove and edit the paths that populate a list view. Figure 24 provides an example of the dialog.
Figure 24. The content path dialog
Clicking on the '+' to the left of the list allows you to add new paths to the list view. You can remove a path be selecting the relevant path and clicking the '-' button. You edit the properties of the paths directly in the table, or via the Path editor (see section Referencing Components via Paths); each path has the following properties:
- Name - the name of the path, it is only really significant for static paths, see section Active Console List Views, duplicates are valid though probably undesirable if they are static paths
- Type - the type of the path, which can be static, dynamic or follow selection. See section Active Console List Views for more details on path types.
- Enabled - if ticked then the path will be populating the list view, if not then it will not contribute data items (it is essentially turned off, and plays no part in defining the contents of the list view).
- Path - the actual path which data items will have to match to end up in the list view. See section Active Console List Views for details on how paths contribute towards the contents of list view, and section Referencing Components via Paths for the path editor, which describes how to construct paths (though not what paths you should define).
There are two other settings which will automatically configure the list view based on user selection.
Note: These settings only apply if there is at least one 'Follow use selection' path configured in the list view (see section Active Console List Views).
- Autogroup - if set to true then, each time a selection occurs, the view is grouped by a property dictated by the dockable in which the user clicked.
Note: For the most part, responding to these clicks is limited to the state tree, see section State Tree Dockable. This only works if at least one path is configured as "Follow User Selection".
- Rename tab name on selection - when a user selects an item in another view as well as restructuring the contents of the list view, if this option is selected then it will also rename it, based on what was selected.
Filters can be defined on a list view, via the list view properties dialog. They work by applying the configured filter on all the data items that are present in the list view, and hiding them if they do not pass the filter. Note the use of the word 'hide' - they are not actually removed, they simply do not appear in the list view as long as the filter is in place. A summary of how many items are being displayed as a result of the filter is available in the status bar.
Filters can only be defined on a list view; they cannot be defined at a dockable level. This is essentially because they are considered temporary restrictions on the view rather than a permanent change to the contents of the view so it does not make senses to define these on all list views in a dockable at the same time - see section Active Console List Views for a narrative on this point. All this said, they are persisted in the workspace and will be restored with the list view on load.
A filter is defined via the list view properties. Figure 25 displays an example of the screen. Only one filter can be added to a list at any given point in time, but it can have many expressions strung together via AND and OR operations.
Figure 25. Filtering a list view
To add a filter, or an additional expression to the filter, click the '+' sign to the left of the filter list. If the row is the first row, then the operator is not relevant, since there is nothing to AND or OR it against. You should however select the Property you want to filter on, the operator you want to use (i.e. equals, greater than, less than etc) and the value you want to compare it to.
You can add additional expressions to the filter to make it more specific, or to add multiple criteria.
You may have noticed that paths and filters serve a similar purpose in that they define what can be seen in the list view. Consider, for example, the following two cases:
- A list view with a path '//probe (Severity = Critical)'
- A list view with a path '//probe' and a filter 'Severity = critical'
If you configure these two views they would always have the same contents, so what's the advantage of one over the other? The following points may be useful when choosing one over the other:
- Is the filter temporary, or do you change it a lot? If you want to use the filter for a short time then it will probably be easier to define a filter rather than change the paths (which would be the alternative). If you have only one path this may not seem too onerous, but if you have many paths this would represent a lot of re-configuration, which you would probably have to put back later in order to remove the filter.
- Is the filter there most of the time? There is an associated performance cost with having large scale list views permanently running in an AC. While this is difficult to quantify (since computer speeds vary as do the size and type of the list views) it would be fair to say that the more data items and paths in a list view the higher the CPU and memory requirement. There is also a CPU overhead to maintaining and applying the filters. Given this, if a filter is there most of the time it may be cheaper in CPU and memory to re-factor the paths that make up the list view, and effectively embed the filter into the paths. So, in the example from the start of this section, you would change a list view with a path '//probe' and a filter 'Severity = critical' into a path '//probe (Severity = Critical)' with no filter.
List views have full support for drag and drop, including a significant amount of configurability over what happens when the drop occurs. This section provides detail on how it works, and how to set it up.
Any given list view has a set of drag and drop rules. Whenever a data item is dropped into a list view, its drag and drop rules are consulted and all matching ones used to decide what paths should be added to the list view. Quite a lot was said in that last sentence, so let us cover these concepts one by one.
Firstly note that a list view has drag and drop rules, each rule has the following properties. See section Active Console List Views.
- A Display Name - used when there is some ambiguity about which drag and drop rule to use.
- A Modification - defines how the path of the dropped item should be morphed before being added to the list view.
- A set of filters - limits the data items that a drag and drop rule is appropriate for.
- Path type - will either be static and dynamic, and defines what type the paths are that are added to the list view when the drag and drop rule is applied.
- Expand paths - a Boolean flag that determines whether to expand the path before the paths are added to the list view.
The drag and drop rules are set up using the list view configuration dialog, an example can be seen in Figure 26.
Figure 26. Setting up drag and drop in list views
Whenever a data item is dropped into a list view, the set of drag and drop rules associated with the list view are consulted. A drag and drop rule will be used if one or more of its filter paths match the item that was dropped. If no filter paths are defined then it automatically matches.
For example if a drag and drop rule has the following filter path:
Then it will only apply if a managed entity is the data item being dropped. In this case:
The drag and drop rule will only apply if the item being dropped is a child of a probe.
If more than one drag and drop matches, then the user will be presented with options on a menu (which will appear at the time of the drop). For example, let's say we have 2 drag and drop rules, one with a filter equal to //managedentity called DnDRule 1 and the other with no filter called DnDRule 2. If a non-entity is dropped then there is no ambiguity and DnDRule 2 will be used. If an entity is dropped then a menu would appear asking them to choose which rules to use, as can be seen in Figure 27:
Figure 27. Resolving which drag and drop rule to use
Once the user has selected a drag and drop rule, it will be applied as normal.
Once a drag and drop rule has been selected, it is applied to the list view. The net result of any application of a drag and drop rule is that the view is populated with one or more new paths (see section Active Console List Views for the effects of adding paths to list views).
The application of a drag and drop has a number of steps:
- Apply Modification - if a modification is defined then that it is applied, see section Active Console List Views for more details on modifications.
- Expand Path - if the drag and drop rule should expand the path before addition of the path(s) then it does so now, see section Active Console List Views for more details on the expansion of paths.
- Add the paths - at this stage the derived paths are added to the list view and the list view re-configured for its new contents.
Each drag and drop rule can have a defined modification. A modification will take the path of the dropped item and mutate in some way. The mutated path is then used for re-configuring the list view rather than the original path of the data item. For example take the following modification which may be defined on a drag and drop rule:
- DroppedItem()/append( //dataview )
And let us now pretend that a probe has been dropped onto the list view, which has the following path:
- Gateway1 / myprobe
The path is mutated by the drag and drop rule by replacing the 'droppeditem' element with the path of the item that was actually dropped then applying the modifications, in this case we would end up with:
which would subsequently be added to the list view. In this case, although the user dropped a probe, he ends up adding all the data views that are part of the probe.
For full details of the allowable modifications and their effects see details of the geneos URL editor in section Referencing Components via Paths.
By default drag and drop rules have a modification equal to 'droppeditem()' which will not modify its path in any way, thus users will simply drop the selected item into the list view.
These path manipulation functions are used to remove path elements in droppeditem and followselection paths, as well as append.
|Remove ( ...)|
|RemoveAfter ( .. )|
|RemoveBefore ( ...)|
This modify the selected path from:
By default, when a drag and drop rule is applied it will create just a single path in the target list view (which may have been mutated by a modification, see section Active Console List Views). However, the designer of the drag and drop rule can also specify that, instead of dropping just this path, an additional process step can take place which does the following:
- Gets all matching items for the path
- Add a path to the list for each matching item
For example, if a dropped path after a modification was equal to:
and the drag and drop rule specified that it should be expanded, then at the time the drop occurred the system would get all data items that matched the path (which in this case would be a set of data views). It would then add 1 path per matching item, where each path would be an explicit path to an explicit data view, i.e.
This is useful if you want the drag and drop contents to not update over time, i.e. whatever was added at the time of the drop should be all that ever appears in the list view. It is also required to simulate the old (GA2009.1) custom entity view behaviour.
If this option is checked in a filter it means that, if a simple path is dropped into the list view (rather than a data item), the drag and drop rule is appropriate. This occurs for example when a real path folder is dropped from the state tree, or a text string that represents a path is dropped from an external application.
The General Visual settings dialog in the list view allows the user to set up many of the aesthetic properties of the list view. It is accessible via the main list view properties dialog (see section Active Console List Views), as shown below in Figure 28.
Figure 28. The general visual settings of the list view
It contains the following settings:
- Background Colour - defines the background colour of the list view.
- Default Mode - defines the mode of the list view.
Note: This can also be changed via the status bar, and right click menu.
- Custom tab name - the name of the list view as it appears on the tab. It can also be edited directly by double clicking on the tab.
If the name is defined at the dockable or workspace level then it defines the default names for any new tabs created in the list view dockable, i.e. if at the dockable level you set the Custom tab name to be 'Foo' then the next tabs created in the list view will be called 'Foo 1', 'Foo 2', 'Foo 3' and so on.
List views have a number of modes; these allow the contents of the list view to be displayed in different ways. The available modes are defined at a workspace level and made available to all list views. A list view mode can be changed via the status bar (see section Active Console List Views), or via the right click 'Mode' menu. By default the following modes are available in all workspaces:
- Details mode - tabular view, with the data items in the list view forming the rows of the table, and the configured properties defining the columns.
- Icon mode - classic grid based explorer view where each data item is represented by a 32x32 icon and a label with its (display) name, then laid out left to right. The labels will expand in height as required to show the whole name of the data item.
- List View Mode - compact mode, with data items displayed using a 16x16 icon, and a label for their (display) name. The items are laid out left to right.
Examples of these modes can be seen in Figure 29.
Figure 29. The default modes available with the List view
These modes are defined as system modes and cannot be removed or modified. It is however possible to define your own modes, this is the subject of section Active Console List Views.
The mode that each list view uses at any given point in time is independent from the other list views, and is persisted in the workspace, meaning that on a reload the list view will be restored in the same mode it was saved in.
The details mode allows users to view the contents of the list view in a rich table view. This section describes the various settings and configurable options that the users have when using this mode.
The columns at the top of the details mode are defined by the properties that are configured on the list view (see section Active Console List Views). They can be changed in the following ways:
- Re-ordered - columns can be re-ordered by pressing on them with the mouse then dragging them to the desired location.
- Changed in width - you can change the width of a column by moving the mouse over one of the ends, then pressing and dragging the mouse. Alternatively, by right-clicking on the headings, the user may use the options: Set Column Size, Auto Resize This Column and Auto Resize All Columns.
- Hiding / Un-hiding - the visibility of a column can be toggled by right clicking on the headings, then clicking on the relevant heading name. This is a toggle, so if it was visible it will now be hidden or vice-versa.
- Sorting - you can also sort the view by clicking on the headings.
The column settings for a list view are persisted in the workspace, and restored on load.
There are two principal means of removing columns from the details mode, although they have the same immediate impact they are subtly different:
- Use the right click on the column headings and hide - will temporarily remove the column from the details mode, but in the background the value is still present in the list view, this should be used if the removal is temporary or the column you are hiding still needs to effect the icons in the list view.
- Use the properties dialog to remove the property from the list view - will completely remove the property from the list view, it will not be available to users of the list view nor will it contribute towards the icons in the list view. Generally removing a column rather than hiding it will lower the CPU and memory footprint of the list view on the machine it is running on, so if the column is generally not interesting then this is probably a better solution.
There are a number of other visual settings you can define for the details mode. They can be configured via the Details mode dialog, which in turn can be accessed via the list view Properties dialog. Figure 30 provides an example of the Details view Dialog.
Figure 30. Configuring the details mode of a list view
The following settings are available:
- Row Height - defines the height of each row (in pixels).
- Show Root Handles - defines whether the expand / retract buttons should be displayed to the left of the root level items (folders). If they are not displayed you can still access the expand/retract functions by double clicking on a row.
- Indent - defines the distance that the rows under each group should be indented from the left when the view is grouped.
- Show Tree Lines - determines whether to show the lines that connect child nodes to the parent within the tree.
- Tree Line Colour - determines the colour of the tree lines (if they are configured in the previous property).
- Sorted - determines whether the view is sorted or not.
When you select items in the list view they will highlight in the OS selection colour. If you hold down the CTRL key while selecting in order to select more than one item in a list view, then the last item selected is known as the anchor selection. If your list view is in details mode, then the anchor selection will be displayed in a different colour to the other selections.
Note: When a select event occurs, all the other components in the AC will be told about the selection, but they will only be told about the anchor selection, not the complete set of selected items.
Users are not restricted to the limited number of modes that are shipped with the console as standard, they can if they wish create their own. To do so they must use the 'List View Template Editor'.
To access the editor go to the application level 'Tools > Workspace level list view settings' and select the 'Templates' section of this dialog. You should be presented with the screen shown in Figure 31.
Figure 31. Creating user defined modes at the workspace level
The Template list will contain two main templates types, system templates and user defined templates. System templates cannot be edited or removed, they are always available. User defined templates are shown in white, and can be added, edited and removed. User defined templates are saved in the workspace that they were created in.
To create a new template use the '+' button to the left of the list, to remove one select it then click on the '-' button (any list views using the mode when it is removed will revert to Icon Mode). To edit a template double click on its template picture, or right click and select edit, you will be presented with the template editor.
You can also change the mode's name by double clicking on the name in the table directly. This name will appear in the mode lists for each list view.
When you edit a template you will be presented with the template editor screen, shown in Figure 32.
Figure 32. Configuring a user defined template
In the centre of this screen is an outline which represents a single instance of a data item in a list view configured with your selected mode. Within this box will be a number of data item properties which will be displayed for all data items represented by the mode. Figure 33 provides an example of a mode being edited and what will appear in a list view when it is used.
Figure 33. An example user defined mode
The size and shape of each data item the template is used to represent is defined by the boundary (shown in Figure 32). All data item properties added to the template and completely contained within the boundary will be displayed when the template is used; Figure 33 shows an example of this.
Properties that are NOT completely within the boundary of the shape will be shown in red within the editor and will not be displayed when the mode is used. In addition, if the editor was shut down and re-opened these properties will not be displayed in the editor (you would have to drag them back on from the tools at the top).
To add new properties, drag and drop them from the tools at the top of the editor. The tools are broken down by the type of data items that are appropriate for, including a section whose properties are suitable for all data items. You can delete properties you have added to a template by selecting and clicking delete, or right clicking and selecting 'Delete'
Having added a property you can right click on it and change its properties by selecting the 'Properties' menu. You will see the dialog shown in Figure 34.
Figure 34. The template editor properties dialog
Note: include the property in the list view that the mode will be used for.
Using a user defined mode is easy, having created the mode go to the list view you want to use it in, and select your new mode from the mode list (see section Active Console List Views).
For any given list view, users can select the data item properties that should be displayed within it. Examples of data item properties include, name, severity, number of snoozed children, connection status and so on. Only properties that are selected will appear in a list view, even if some data items in the list view have other properties. So, for example, an entity has 15 or so properties and appears in a view, but if the only properties you have selected for the list view are 'Name' and 'Severity' then only a name and severity column will be available.
Selecting a property for inclusion in a list view does not guarantee that it will be available; if no data items that are present in the list have the selected property then it will not be added. For example the only data item with the property 'Value' is a managed variable (or cell), therefore even if you had selected Value, if there were no cells there would be no Value column.
The list view supports the display of parent properties; see section Data Item Properties for a full description of parent properties.
The configuration of properties is done via the Properties tab in the list view configuration, an example of which can be seen in Figure 35.
Figure 35. The property selection dialog
The available properties are shown in a table. Where there is a grey tick in a cell, it means that property is available but not selected (and therefore will not appear in the view). Where there is a green tick, it is available and selected (so may appear in the list view assuming there is at least one of a suitable data item type). Where the cell is empty, it is not appropriate to the specified data item type, so will never be available.
Selecting properties in the 'Any' column means that, whatever the data item type of the property, if it is available then it will be shown for that data item. For example if 'Name' has been selected and the list view contains a Probe and a Managed entity then they will each display their respective names.
The other columns allow you to configure parent properties (see section Data Item Properties). For example if you select probe.name that means that for each data item if it is a probe or has an ancestor which is a probe then the probes name will be displayed.
There are a lot of potential properties which you can add to a list view. When searching for a given property, you may find it helpful to use the filter box at the top of the table which will limit the rows to those that contain the word you enter. This can be invaluable for quick configuration of the properties.
One subtle feature that users should be aware of is the construction of an icon for any given data item and how property selection can effect it. Consider the following icon:
Figure 36. Entity icon with snooze and OS icon
This icon is actually displaying a number of pieces of information, namely:
- That it is an entity
- What OS its ancestor probe is running on
- The fact that it is snoozed
- That it or one of its children is in a critical state.
This will only occur in a list view if probe.OS, Snoozedand Severity are configured as properties in the list view; if you were to remove one or more of these then the icon would no longer reflect these states. For example if we removed 'Snoozed' from the list view then the snoozed children indicator would be removed from all icons in the list view, as shown in Figure 37:
Figure 37. The same entity icon, but with the snoozed property removed from the list view
A list view can be grouped by a selected property. You can achieve this either via the status bar, or via a right click menu option 'Group by' anywhere within the list view.
Whichever method you choose you will have to choose the property at the time group function is selected. The available properties are limited by those configured in the list view.
The data items will then be inserted into the relevant groups. Figure 38 displays an example of a group in the two principal list view modes:
Figure 38. Groups in the two main modes
Groups are dynamic, in that if a data item is removed from the view and the group is now empty the group will be removed. Conversely if an item is added to the list which has a value for the grouped property that no other data item has, then a new group will created for that property value.
The groups are sorted, using the sorting mechanisms.
You can remove grouping by selecting 'None' when choosing the property to group by.
Groups can be expanded and collapsed. This can be achieved by double clicking on the group row, or using the '-' button at the end of the bar in icon mode (you can also display a +/- button in the details mode by changing the details mode visual properties.
You cannot create or add your own groups, nor can you remove them, they are automatically defined by the system if you have grouping enabled.
Each group has a group icon; its colour defines the worst severity of a data item within the group, in much the same way as severity propagates up the rest of the geneos system.
List views can be sorted by any property that they are configured to display. There are a number of ways in which sort can be enabled:
- Use the sort button on the status bar.
- Right click 'Sort by' menu anywhere in the list view.
- In details mode you can simply click on the column headings.
To remove sort select None as the sorting property, or keep clicking on the column heading until the sort arrow disappears.
A sorted view will order the data items based on their value in the selected property. If the value is a textual then this will be alphabetic, if its numeric then it will be numeric. Severity is a special case, this will order from Undefined to Critical.
The sorting property of a list view is persisted in the workspace.
If a view is also grouped then sorting will first occur on the groups, then separately on the data items within those groups.Sorting by multiple properties
Users can actually sort on multiple properties at the same time via the details mode. If you hold down control when clicking on column headings the previous sort will not be removed, instead additional properties will be used during the sort. You can see that this in operation since each sort arrow in the column headings will have a number next to it. Figure 39 illustrates this.
Figure 39. Sorting on multiple properties
Multiple sort works by sorting all items by the first property, then where the property value was equal sorting on the second, then third and so on.
Individual list views and entire list view dockables can be exported via the Active Console. This can be useful for sharing list view configurations with colleagues, or creating backup for rarely used list view configurations. This section describes how to perform these functions.
To export an individual list view, right click anywhere within the list view and select the 'Export > Configuration' menu item. You will be prompted to select a file name, which will automatically be given an .ltv extension. This file contains the entire configuration local to the list view; including settings which have been overridden locally (see section Active Console List Views for details of the inheritance of list view settings).
You can export an entire list view dockable, which will include all dockable level settings, and all existing list views (tabs), with their configuration. Such an export will create a .dbo file. To do this you must use the 'Export' function in the Dockable manager. Open the dockable manager via the application level 'View' menu, right click on the dockable you want to export then select 'Export'. See section Dockable Manager for more information on the Dockable manager.
To import a list view, select the application level 'File > import' menu. You will be promoted to select the .ltv file. After doing so if there are many list view dockables within your workspace a dialog will appear asking you which dockable you want to import the list view into.
To import a list view dockable, select the application level 'File > import' menu. You will be promoted to select the .dbo file. After the import, the dockable will appear in your workspace.
Note: Dockables must have a unique name, if you try and import a list view dockable that has the same name as another list view dockable it will be renamed to make it unique.
At the top of a list view is a yellow status bar. This contains some textual information on the list view, including any filters defined on it, and what it is currently grouped and sorted on, plus some buttons which allow quick access to some of the more commonly used features. Figure 40 provides an example of the status bar.
Figure 40. The list view status bar on section Active Console List Views
The status bar contains the following functions
- Item count - on the left is a report on how many data items are currently matching the paths that are populating the list view.
Note: If you are using Static paths then this number may be higher than the number of icons or rows you see in the actual list view. If the view is filtered it will also display how many of the available items are visible.
- Filter information - if you have defined a filter on the view, then the status bar will also report how many items you can see relative to the number of items actually in the list, for example Viewing 4 of 50 means there are 50 data items in the list, but only 4 match the filter you have defined at that point in time.
- Long description - the long description of the list view.
- Group and sort by text - in the event that you have either grouped or sorted (or both) the list view, the properties that are being used for these purposes are listed in the status bar.
- Mode - from here you can select the mode that you wish to use to view the list view.
- Group - allows you to group the list view by a selected property.
- Sort - allows you to sort the list view by a selected property.
- Play / Pause - will toggle the list view between paused and an un-paused mode.
- Refresh - will force an update of the list view based on the current state of the connected gateways, it should not be necessary to use this during normal operation, though it may be useful when the view is paused.
- Properties - will launch a dialog from which you can change the properties of the list view itself.
- Minimize status bar - will hide the status bar, you can get it back by right clicking in the list view and selecting the 'Status bar' menu item.
A list view has a lot of settings; therefore the act of configuring a list view can be an involved task. To reduce this burden it is possible to define settings on a list view dockable and at the workspace level, this means that:
- Change settings on all list views at the same time - existing list views can inherit common settings, such that when these settings are changed they effect all list views.
- Create defaults for new list views - new list views come with some default settings that can be defined at the dockable and workspace levels, meaning there is less configuration to perform on a per list view basis.
These functions are referred to as the list view settings hierarchy. There are three levels of settings as illustrated by Figure 41.
Figure 41. List view settings inheritance
Settings can be overridden at each of these levels, such that the parent setting is ignored. Let us run through an example. Take background colour, this can be set at the workspace, dockable and list view level in the general visual dialog. Let us assume that it is set to green at the workspace level and that all list view dockables and list views are configured to inherit this setting from the workpsace level settings. If you were to then change that colour to red, all list views in the workspace would now have a red background.
If you were to override background colour on a specific list view dockable to red, thereby ignoring the workspace level settings, all list views within the dockable would now be red. If you set the background colour directly on a list view within the dockable to yellow then that list view would be yellow, the other list views in that dockable would be red, while all other list views in the workspace would be green.
It is possible to pause a list view. A paused list view will not update. Items will not be added and removed and the properties of the data items (including the icons, groups etc.) will not change. When you pause a list view, it essentially becomes a snap shot in time and all the data must be considered stale and invalid with respect to the current state of the system. When paused, a blue bar will be added to the top of the list view which says paused and details the time and date that the pause occurred. In addition the button in the status bar which allows you to pause / un-pause the list view will display a 'play' icon. Figure 42 shows a paused list view.
Figure 42. Pausing a list view
Pause is primarily used for search results, but since search results are simply a list view in their own right the function is available to all list views.
Selecting 'Refresh' on a paused view will force an update, and get the latest state of the list view based on the current gateway contents, but it will remain paused.
When a new workspace is created a number of default list view configurations are created, namely:
- An Entities View, which displays lists of entities, and allows you to create new entity based views, see section Entities Dockable for more information.
- A Probe view, which by default lists all the probes within the gateways you are connected to, see section Netprobes Dockable for more information.
- Items of Interest view, which follows user selection and details all the critical and warning cells that are not snoozed beneath the currently selected item in the console.
In the event that you delete these views (by accident or on purpose) you can get them back by importing the default configurations from the ./useresources/listviewconfigurations directory within the Install dir of the Active Console.
The Metrics dockable contains a number of Metrics views. Each Metrics view is represented by a named and coloured tab at the top edge of the dockable. Clicking on the tabs displays the contents of the selected metrics view. At any given point in time the metrics dockable will contain the Primary Metrics view (the left most tab with an icon) and a number of user defined custom metrics views.
Figure 43. An example of the metrics dockable
A metrics view consists of two main components; on the left is the View Selector which contains a list of the metric tables available in the view. On the right is the metric table that is currently selected. As items are selected in the view selector the metric table in the right will update to display the items.
For example in Figure 43 the CPU metric table has been selected in the view selector and has been displayed in the right.
- Go to Geneos Active Console.
- Click Tools, and then click Create Metric Overview.
- The Metrics Overview displays on the screen.
Selecting the Persistent overview option
This changes the default behaviour to close the metric overview dockable when the window is closed. In addition, this enhancement adds the Persistent Overview check box in the overview metrics wizard which was initially turned off.
- Select the Dataview Attribute and the field you want to view.
- Select the Persistent overview check box.
- Click OK.
- The New Overview Dockable displays on the screen.
The view selector contains a list of metric tables. A metric table contains zero to many data views which are published from the plug-ins connected to the gateways. They have two main properties:
- Name - the name used to identify the metric table in the view selector and the viewer. By default it takes the name of the first data view that is connected to the metric table.
- Paths - a set of user defined paths (see section Referencing Components via Paths) which determine which data views are included in the metric table. To be included a data view must satisfy one or more of the path criteria (treat this like an inclusive OR operation).
These properties can be accessed by right clicking on a metric table in the View Selector and selecting 'Metric Table Properties'.
In the simplest case a metric table has a single path which points at a single data view. This will be true for most metric tables. However it is possible not only to include several paths, but to configure one or more of them to match multiple data views. In these cases the metric table may contain more than one data view. When the metric table is selected and its contents displayed in the viewer, it will be in the form of a single merged table which contains the contents of all the data views (in AC1 these tables were known as Dynamic Overviews). In AC these are referred to as Metric Overview Tables.
The set of data views connected to a metric table will update as gateways and probes come up and down, i.e. the content of metric tables is dynamic and reflects the current state at all times.
You can 'Refresh' the contents of a metric table at any point by clicking on the 'Refresh' button next to the name of the table (see Figure 44). The sample rate is shown under the name. To force a refresh (resample) right click on the metric table icon at the top left of the table, or the metric table in the view selector.
Figure 44. Refreshing a data view
The contents of the primary metrics view will always follow the selection in other AC components. It will create one metrics table for each data view within the relevant directory component and insert it into the primary view. Custom metric views are manually populated by users. The list of data views they contain will not change unless the user adds or removes metrics tables from them.
There are no restrictions on the source of the data views that can placed into a single metrics view, i.e. they can come from independent gateways and be connected to any plug-in type.
The view selector appears on the left hand side of a metric view. It displays a list of metric tables. The metric tables can be grouped by a primary and secondary attribute. The attributes that can be used are:
- Gateway - the gateway that the data views within the table are contained within.
- Netprobe - the netprobe that the data views within the table are contained within.
- Managed Entity - the managed entity that the data views within the table are contained within.
- Sampler - the sampler that the data views within the table are contained within.
- Sampler Group - the sampler group (as defined in the gateway setup) that the data views are contained within.
- Plug-name - the type of plug-in name that the connected data views come from.
- None - you can negate the primary or secondary grouping by setting them to 'None', meaning no grouping will occur at the specified level. If the primary grouping attribute is set to 'None', then the secondary grouping attribute will have no effect.
In cases where the data views connected to a metric table do not share a common value for a selected attribute they will be placed into a group labelled 'Multiple'. In cases where the specified attribute cannot be located they will be classified under an 'Unknown' group.
The primary and secondary grouping attribute can be defined independently for each metrics view. Their current configuration will be displayed at the top of the view selector. They are changeable via the right click menu anywhere in the view selector and saved in the workspace.
You can expand and contract the groups within the metrics view selector by double clicking on the group headings. If you display Root handles (covered later in this section) you will also see a +/- button that can be used for the same function.
The View selector is a tree structure, consisting of groups and metric tables as leaf nodes. You can display it in a more tree like way be right clicking on the view selector and selecting 'Show Root handles'.
Each group will be coloured to reflect the worst severity of an item within it.
New metric tables can be added via the following methods:
- Via a managed entity or sampler -
- Right clicking on any managed entity or sampler (from any point in AC including other metric views) will provide access to an 'Add <data item name> to ►' menu item. This will have a 'New Metrics View' sub-menu item and list existing custom metrics views. Choosing one of these will create a metric table for each data view in the selected data item and import them into the selected custom metrics view.
- Drag and drop a managed entity / sampler or data view. You can also drag and drop a managed entity or sampler from the state tree into a view selector, or drop it into the tab area at the top of the metrics dockable to create a new custom metrics view tab (which will be called the same as the item you dragged).
- The 'New Metrics Table' menu. The right click menu in the view selector provides access to a 'New Metrics Table' menu item, which will create a new metric table. You will then have to edit its Paths property to define the data views it should display.
Note: You can only add new metric tables to custom metrics views, you cannot modify the primary view
Metric tables can be removed by right clicking on a metric table or a group heading and selecting 'Remove Selected items'. The metrics will be removed from the metrics view. This cannot be done within the primary metrics view.
The right hand side of the metrics view displays the metric table that is selected in the left. All metric tables are displayed in a tabular format; the exact content is defined by the data view(s) they are representing.
If the metric table is displaying just a single data view then the headlines for that data view will be displayed above the table in a series of horizontally ordered boxes. If the metric table has more than one data view then the headlines will be shown in another table, with columns detailing the gateway and managed entity the headline is applicable to, so that you can tie specific headlines to specific data view instances that make up the metric table. This format is known as a Metric Overview Table.
The columns in metric tables can be re-ordered (via drag and drop), hidden (via the right click menu on the column), sorted (using column headers), and resized using the mouse or the right-click menu options: Set column size, Auto resize column and Auto resize all columns. These settings will be remembered as long as the metric table exists in the view selector.
Note: The first column of a metric table is treated as a special column that cannot be hidden and, if resized, will not occupy more than a third of the viewable screen. If any value of a first column cell is longer than this limit, a tooltip will be available to view the full value.
Having configured a table's columns you can choose to save the settings as the default for all metric tables of the same name. This is done via the 'Column Settings ► Save as Data view Defaults' menu item, which is accessible by a right click on the actual table (rather than its icon or name in the view selector).
Alternatively, you can save column settings selectively using the Column Settings Editor dialog. This dialog is accessible by the same right click menu. To bring up the dialog select the option 'Column Settings ► Table Column Settings Editor' (Table Column Settings Editor is explained in more detail in chapter Table Column Settings Editor).
From that point on, whenever a metric table with a data view of the same name is created these default column settings will be applied. However, existing metric tables will not be affected.
Note: The primary metric view constantly refreshes its content based on user selection, so don't spend too much time setting up table layouts here as they will be lost as soon as there is a new user selection in another AC component. You can, of course, define dataview default settings here which will be remembered.
If you have modified the metrics table column settings, and would like to revert these settings to the dataview defaults (i.e. lose your changes in favour of the settings defined for the dataview in the workspace), then you can use the right click menu 'Column Settings > Revert to data view defaults'.
Figure 45. Metrics view with column settings status
If you would like to revert any modified settings to 'factory defaults', you can do so by going in 'Column Settings ► Revert to Factory Settings'. If you choose to do so, you will lose any modified settings in favour of factory defaults but no changes will be written to the workspace. Therefore, when the data view is loaded next time, workspace defaults will automatically be applied (in this sense, this option is temporary).
Any settings saved in workspace can be removed by going to the Column Settings Editor dialog. You can either remove settings selectively for a data view or delete all settings for that data view altogether. All removed settings will, of course, be reset to factory defaults.
The 'Column Settings' sub-menu, that is available to you if you right click on table, is also available on right click for column settings status icon.
This status button is available to you on the metrics table filters bar next to pause and refresh buttons. It has three features associated with it.
- Current Settings Persistence Status. If you have any settings saved in workspace for the metrics table the icon on the button will turn blue. If you don't have any settings then the icon will stay dimmed. Figure 46 shows the difference between these icons.
- Open Table Column Settings Editor. Left click on this button opens the Table column settings editor.
- Column Settings sub-menu. The sub-menu associated with 'Column Settings' section of the table right-click menu can be opened by right clicking on this button. Figure 45 shows the button with sub-menu.
Figure 46. Column settings persistence status
Sampling information label
This label is available on the Metrics dataview next to the Table Column Settings Editor button.
This automatically changes when you click the Sample now command that is used to update the current metrics view.
The Last sample value displayed in the dataview is the Sample Time value of the Netprobe:
4 rows, Sampling every 20 seconds, User requested sample completed at <local AC time>, Last sample <Netprobe Last Sample Time>
Caution: If the sampling information label does not display the sample time, then Active Console is not receiving an event to trigger an update for the current metrics table.
The status bar displays a list of column names that are currently hidden from the table. It is also displayed highlighted if any hidden columns are present. A screenshot of this is shown in Figure 45. This hidden column information is independent of any persisted table settings, if there are hidden columns they will be listed here.
Note: The exception to this rule are columns whose name starts with a '/'. These are hidden by default, and therefore their hidden status is not reported on the status bar.
Metric tables update automatically when the data views they contain resample. You can if you wish pause these updates by selecting 'Pause' on the right click menu from the metric table in the viewer. A manual refresh can be performed in this mode using the right click 'Refresh' menu, disabling the pause is done via the same menu or the pause button in the header of the Metric table.
Using the view selector to switch between views can cause paused views to refresh. So if a paused view is being displayed, and the view selector is used to change to a different view, and the view selector is then used to switch back to the original view again, the original view will still be in a paused state, but the data will have been refreshed at the point when you switched back to the original view. Hence it will still appear to be paused, but will not necessarily be displaying the same data as it was before you switched views.
The situation is slightly different if you are using the primary metrics view, and you switch views using a method other than the view selector (so you switch views by selecting in the state tree or in another ActiveConsole window). In this case, if you pause a view, then switch to another view, and then switch back again, the pause status will be lost - the data displayed will have refreshed when you switch back, and will update at the configured interval thereafter.
You can make metric tables active and inactive. To do this, right click on the selected metric table in the View Selector, or right clicking on the metric table in the viewer. Inactive metric tables contain no data views. This is useful if you have large scale metric overview tables that you only need at the time you query them, rather than having the active all the time (such tables can be expensive in memory and CPU), see section Metrics Dockable for more information. When they are activated they will populate with the required data view set.
Figure 47. Inactive metric tables
Inactive data views are shown with a blue icon with a white cross. If a Metric View contains ONLY inactive metric overviews then it will have a blue tab. The active status of Metric table in custom metrics views will be maintained in the workspace.
You can display tick boxes next to the data views within the view selector which allow fast access to the active / inactive functions, to do so, right click in the view selector and toggle the 'Allow fast table metric activation'.
Metric tables can be output via the right click menus 'Save As …' which saves the table to a comma separated .csv file and 'Copy dataview' which places the non-filtered table contents into the system clipboard.
Note: There is also a copy command for copying the full and short path name of a data item (see section Glossary), which can be accessed from all areas of the Active Console for all data items.
There are some simple query functions that can be performed on metric tables, as follows:
- Count Unique - will count the number of unique names or values in a given column. Right click and select 'Query Table ► Count Unique' then 'Name' or 'Value'. The result is shown in a temporary dialog box.
You can add filters to any metric table by right clicking on the metrics table and selecting the 'Filter Table' menu item. Filters restrict the rows that are displayed based on criteria. A row will only be displayed if it passes all of the filter conditions. Each filter has the following attributes:
- Column - the column whose row value must pass the filter. There are also special cases for ANY COLUMN, where 1 or more cell values in a row must match the criteria, or ALL COLUMNS, where all row values must match the criteria.
- Not - a Boolean flag that inverts the criteria.
- Value - the value to match against.
- Operator - a series of logical
operators that determines the relationship
between a successful match and the value
specified in the value column.
- Contains: matches if the value of the specified column(s) contain(s) (case sensitive) the value defined.
- Contains No Case: matches if the specified column(s) contain(s) (non-case sensitive) the value defined.
- Equal: matches if the specified column(s) equal(s) the specified value. This is a literal string equality (case sensitive).
- Equal No Case: matches if the specified column(s) equal(s) the specified value. This is a literal string equality (non-case sensitive).
- Less than: matches if the specified column(s) are/is less than the specified value.
- Greater than: matches if the specified column(s) are/is greater than the specified value.
- Numeric Equals: matches if the specified column(s) equal(s) the specified value as a mathematical equality.
If a metric table is filtered then a yellow banner will appear above the metrics table informing you of how many rows are displayed, and how many filters are being applied.
Filters persist for the life time of the metric table (and between AC sessions). It is for this reason that is possible to add two metric tables to a metrics view which have the same path attributes (and therefore contain the same data views) because you can set up different filters on these tables.
Filters can be removed via the same right click accessible dialog through which they are added.
Filtered data specific functions
There are some functions that are available specifically for filtered data, these functions area available via the right click > filtered data menu item. They are as follows:
- Query table - has the same function as the basic Query table feature (see Metrics Dockable), but is restricted to operating on the filtered data (rather than all rows).
- Save as … - will save the data to a comma separated file (CSV). You will be asked to enter the file name on selecting this function.
- Copy dataview - will place the filtered data on the system clipboard.
You can specify a quick filter on any metrics table by using the quick filter search box at the top of the Metric table. This is equivalent to 'Display all rows that have a value in any column that is equal to or partially equal to the specified value'. An example is shown in Figure 48.
Figure 48. The Quick filter function of the metrics table
When a metric table contains more than one data view (because it has multiple or wild carded paths, see section Referencing Components via Paths), then it is referred to as a Metric Overview table. Metric overview tables differ from single data view tables in that they have an additional gateway and managed entity column so that you can tell (for each row) which data view it has come from. This is also true for the headlines which instead of being displayed in a grid type layout are in a table of their own.
Note: Metric tables can be expensive in terms of memory and CPU, you may consider making them inactive when not in use, see section Metrics Dockable.
Note: These were known as Dynamic overviews in AC1.
Metric overview tables can be created by adding a new metric table to a metrics view and configuring it with multiple or wild carded paths (see section Referencing Components via Paths). There is also a Metric overview wizard available from the tool bar or 'Tools' menu which allows you to quickly create common Overview tables (see Figure 49).
The wizard will allow you to specify a data view name, a target metrics view, and whether to filter the data views on the current state tree selection. Having made your selections and clicked OK, a metrics overview will be created in the relevant metrics view that contains all data views of the specified type currently connected to the Active Console, in the specified section of the state tree. The settings on this wizard are described here in more detail:
- Data view attribute - defines which attribute of data views should be used to populate the list, and subsequently used to populate the overview.
- Data view name - a list of all the unique names of the data views you are currently connected to (via the gateways). You have to select one or more of these before clicking on OK (hold down the Ctrl key to make a multiple selection).
Note: You can also double click an item in this list to save having to click on OK, but this will limit you to the selection of just one data view type.
- Metrics view - the target metrics view that you want to insert the new metrics overview into.
- Filter on state tree selection - a toggle (which by default is on) which limits the data views that will be selected to go into your new metrics overview based on the current selection in the state tree (i.e. only data views that are children of the currently selected state tree node will be selected to go into your metrics overview. If you turn this off, then the state tree selection will be ignored (as though you had selected the global state) and all data views with the specified name will be inserted into the state tree.
Note: This only applies when the metric overview table is created, the resultant table will not track state tree selection after it has been created.
Like other metric tables, as and when gateways and probes drop and come up this set of data views may change (e.g. if you are viewing all CPU data views, and a new probe comes up that contains a CPU plugin, then the relevant data view will be added to the set of the data view in the metrics overview table).
In actual fact all the wizard does is create a metric table with a suitable wild carded path. You can see this by opening its properties (double click on it in the view selector), and even modify the path to make it more specific, or add new paths.
The wizard lists all the data view types that are currently available via one or more of the data views connected to the Active Console.
Figure 49. Using the metric overview wizard
If the data views within an overview table contain disparate columns then the super set of columns will be available in the table. Where cells that do not have values (because the column is not available in the data view it has come from), they will appear blank.
You can export a metrics view (one of the tabs) to a file, which can then be imported into another workspace. To export, right click in the view selector and select the export function. You will be prompted to provide a filename; the resultant file will have an .msv extension.
To import an exported metrics view, use the application level 'File > Import' feature.
The Event Tickers dockable contains a number of Event Ticker tabs. Each tab has a name and contains a list of local and gateway events. An example is shown below:
Figure 50. The Event Ticker view (with its filter dialog)
The left-most tab is known as the Primary Event Ticker. It is the only event ticker that you can modify and has an icon in addition to its name. It allows you to rename, attach, and detach the primary event ticker. However, by default, it is not possible to move this tab and switch its location from the other event ticker tabs.
Each event ticker tab shows the relevant information of an event in different columns. For example, it shows the fully qualified path of the item for which the event was raised. It also shows the name of individual items which make up the fully qualified path. If the path does not contain the precise information about the items that make up the path, then the event ticker shows empty values for those events in the columns of those data items.
Moreover, if the event occurred for a managed entity, the fully qualified path will contain gateway followed by managed entity, and not contain any items below that managed entity, such as dataview, sampler or a cell. Therefore, in such cases where it is not possible to get the name of items from the path of an event, the data item columns for that event would contain empty values.
Another case where the data item column values of certain events could be empty is when the path contains some wild cards.
The following additional features are available in the event ticker (they are accessible via the right click menu in the event ticker):
- Import - will import events via a data source query. You will be prompted via a dialog that allows you to specify the time span to consider, from where the historical events should be imported, the maximum number of results to return and whether the query should be additionally constrained by considering the path of the component which raised the event or not. See section Event Tickers Dockable for more details.
- Export - will export the filtered contents of the event ticker to a comma separated (CSV) file. If no filters are applied then all events will be exported.
- Pause Updates - determines whether new events that come from the connected gateways should be displayed in the event ticker. Any events that you missed while the event ticker was paused will be displayed when it is un-paused.
- Filters - use this menu item to set the filter that is applied to the event ticker.
Menu items applicable to the data item that was the source (i.e. commands) of the event will also be available in the event ticker right click menu.
The columns of an Event Ticker can be changed in the following ways:
- Re-ordered - columns can be re-ordered by pressing on them with the mouse then dragging them to the desired location.
- Changed in width - you can change the width of a column by moving the mouse over one of the ends, then pressing and dragging the mouse. Alternatively, by right-clicking on the headings, the user may use the options: Set Column Size, Auto Resize This Column and Auto Resize All Columns.
- Hiding / Un-hiding - the visibility of a column can be toggled by right clicking on the headings, then clicking on the relevant heading name. This is a toggle, so if it was visible it will now be hidden or vice-versa.
The column settings for a list view are persisted in the workspace, and restored on load.
If there is a relative time filter set on the event ticker then events older than the specified time need to be removed from the event ticker. This would be expensive if run every second, so instead its run each period, where the period is defined in the advanced workspace settings. By default its each 60 seconds, at which time relevant items are removed.
You can import historical events from a database into an existing or new event ticker.
Right -click the row in the Severity column, and click Import.
Figure 51. Getting historical events
|Time||Select the time period you want the events for and database from which you want to import the events from.|
|Source||Indicates if the source is Database or Gateway Hub.|
|Gateway||If the database contains events for several Gateways, you can limit the events that are returned by the Gateway name.|
|Entity||Limit the events by the Managed Entity name.|
|Target||Define the target event ticker and the maximum number of rows you want to receive.|
From here you can select the time range within which you want see the events, either absolutely (i.e. between time X and Y), or relative to the current time and date. You can also specify the source database, the event ticker target and the maximum number of rows that you want back.
You can limit the gateway for which the events should be returned by entering a value into the gateway field. This is optional however, since leaving it blank will just mean no filters will be performed on gateway. This feature is essential if you have many gateways logging to the same database.
You can also limit the managed entity for which the events should be returned by entering a value into the Entity field. This is optional. It can be used on its own or in conjunction with the gateway field in which case the imported events will match the managed entity in the specified gateway.
Note: Setting the maximum rows to a very large number (50,000+) may cause AC instability since it will require a lot of memory.
When you click OK, an asynchronous data source query will be dispatched to the database (meaning you can continue to use the AC). Once the database has returned, the results the events will appear in your nominated event ticker.
Events created in this manner will be retained when the workspace is saved and restored.
You can create additional event tickers via the right click menu available in an event ticker view, or from the 'View' menu at the top of the application window. These additional views are known as custom event tickers. They can have different filters from the primary event ticker.
Independent filters can be set on each event ticker that you have configured in your system. These filters determine which events appear in the event ticker. The Filter dialog is shown in Figure 50.
The filter options have the following effects:
- Severity - defines which severities you are interested in, or which ones you want to ignore.
- Time - you can either define an absolute time period within which you want to see events, or a period relative to the current time.
- Description - you can filter on the description field of events, matching all or parts of their content.
- Netprobe, Managed Entity, Sampler and DataView - allow you to filter the events based on the contents of these columns. They are simple string matches, including a partial contain and 'not contain' function.
- Max Rows - defines the maximum number of events you want to see in your list at any given time.
- Attributes - limits the events based on view path attributes, if you right click in this row you can add attributes that are known, based on your currently connected gateways.
- Type - limits the displayed events based on their type.
- State Tree, Restrict based on current selected StateTree node - will show all events that occurred on the data item currently selected in the state tree (or one of its children)
Once a filter is applied, a yellow information bar will appear in the relevant event ticker which informs you how many events were examined and how many were left after the filter had been applied. The presence of the yellow bar informs you that a filter is currently being applied to that event ticker.
Whenever new events occur they will be added to all the event tickers, but may not appear if they do not pass the event ticker's filter.
It is possible specify commands to run locally, against ticker event attributes. The commands are specified in the ActiveConsole.gci file.
The commands are specified like this:
-eventcommands name=<Command Name> workingdir=<Directory Path> execute=<Path> arguments=<StaticArg>|$(<DynamicArg>)...
|name||The display name of the command. This will be shown in the menu||Telnet to probe|
|workingdir||The working directory of the command||C:\Work|
|execute||The executable or script to run||telnet.exe|
There are 2 types of arguments: Static and Dynamic. Static arguments are passed as is from the argument; Dynamic arguments are substituted at runtime with values from the event.
Dynamic arguments have 2 types: Event attribute and XPath.
XPath arguments will evaluate against the Data item in the event, if it has one. Event attribute arguments extract an attribute from the event.
Here are all the attributes:
|gateway||The gateway name||$(_event_gateway)|
|eventId||The ID of the event||$(_event_eventId)|
|gatewayId||The gateway ID||$(_event_gatewayId)|
|dateTimeStamp||The Date and time||$(_event_dateTimeStamp[<format>])*|
|severity||The severity of the event||$(_event_severity)|
|triggerOn||What the event was triggered on||$(_event_triggerOn)|
|triggerBy||What the event was triggered by||$(_event_triggerBy)|
|triggerDataValue||The Data value that triggered the event||$(_event_triggerDataValue)|
|description||The event description||$(_event_description)|
|path||The path of the data item||$(_event_path)|
|type||The event type||$(_event_type)|
|uniqueID||The unique id of the event||$(_event_uniqueID)|
|triggerOnXPath||The xpath of the triggerOn attribute||$(_event_triggerOnXPath)|
*<format> in the dateTimeStamp specifies a date formatting string. (See 'Date Format Strings')
-eventcommands name=My Ticker Command workingdir=C:\User\jsmith execute=C:\Program Files\MyApp\go.exe arguments=Day $(_event_dateTimeStamp[E])) Name $(parameters/@Name) name=My Ticker Command workingdir=C:\Program Files\Telnet\ execute=telnet.exe arguments=$(../parameters/@HostName) $(_event_type)
AC provides a search facility which allows you to define a search over all the data items known to the system. The search function can be accessed in the following ways:
- Via the Tools menu at the top of the application
- Pressing CTRL + F anywhere in the application
- Via the search button on the toolbar, see section Active Console Overview
Whichever way you choose you will then be presented with the search dialog (see Figure 52).
Figure 52. The search dialog
There are two principle types of search: a standard search which provides some simple functions (and therefore has limited capability), and an advanced search which utilises paths to define the search criteria.
The Standard search dialog allows you to search for instances of a single data item type that has selected values for common properties. This is quite restrictive but much simpler than building paths (as in the advanced search) and covers a lot of common search functions.
Having selected the type of data item you want a report on, you can then specify the following properties of matching items:
- Row and Column (Cell only)
- Value (cell and headline only)
- User assigned
- Snooze state
- Active status
- Who it's assigned to
- The entity attributes
By default when you perform a search, the results are sent to the 'Search Results' tab in the Search Results dockable. The Search Results are a list view, and the Search Results dockable is a list view dockable, see section Active Console List Views for full details about list views.
You are, however, not limited to sending the results to this target. Using the Target settings at the bottom of the search dialog (see Figure 52) you can also:
- Send the results to a new tab in the search view dockable
- Send the results to a NEW list view dockable (and therefore create a new tab)
- Send the results to an existing list view dockable, at which point you will be able to select the tab to place the results in, which can be a new tab.
In all these cases you can select whether to merge the results of the search with the existing contents of the existing list view, or replace it. If you replace it, all existing paths will be removed before the new search path is added.
Alternatively you can send the results to a CSV file. To do so, select the 'File destination' target option and provide it the filename. You can choose to append a date and time to the file name using a time format string, see section Date Format Strings for the required syntax.
If the results are sent to a list view then the list view will be paused by default (see section Active Console List Views)
Within a session of the ActiveConsole, the search you last performed will be persisted. Hence if you do a search, then come back to the search dialog, your last search criteria will remain. You can reset this dialog by using the 'Reset' button in the bottom left of the dialog.
The contents of the Search dockable, however, is NOT persisted between AC sessions. Its contents is designed to be temporary. That said, if you send the results of a search to a new or existing (non-search) dockable, these will be persisted with the workspace since they are treated like any other list view within the workspace.
If the Standard search (see section Search Function and Dockable) is too restrictive then you can use the advanced search. An example of this dialog can be seen in Figure 53.
Figure 53. The advanced search function
The advanced search is fairly straight forward in that you simply specify a set of paths (see section Referencing Components via Paths) that you want to add to a list view (or whose matching items you want to add to a CSV). However you need to be able to reason about paths, and build them using the path editor, so for that reason it may not be appropriate for basic users.
Because the search criteria persist for the ActiveConsole session (see section Search Function and Dockable), and the dialog is reused in the Reporting functionality, it is also possible to enable and disable the paths that make up the reporting criteria. To do so, use the tick box at the end of each line in the advanced search dialog.
The mechanism by which the target of the search results is selected remains unchanged from the standard search.
If you want to find a data item by its name you can use the Quick search function illustrated in Figure 54.
Figure 54. The Quick find toolbar function
The name entered here is implicitly wild carded, for example if you enter 'Foo' into the quick search then you will be searching for any data item that has 'Foo' within its name (*Foo*). The results will be sent to the Search Results tab in the search results dockable. It will replace the current contents.
Note: This replaces the find host function from AC1.
The Active Console allows users to create dashboards within their workspace. A dashboard consists of vector graphics (these can include your own images such as those contained in jpeg and png files). Aspects of these diagrams can then be configured to update based on changes in the Gateways that the Active Console is connected to.
For example, you canmake the background colour of a shape update based on the severity of a managed entity, or a text value change based on a specified managed variable value.
Figure 55. The Active Dashboard manager
You can configure as many dashboard dockables as you like within a workspace. By default there will be a single dashboard dockable. Each dockable can have many dashboards, each within its own tab.
The addition, removal and properties of dashboards are changed in the Dockable Manager (see section Dockable Manager). You can access the available dashboard dockables via the application level View menu.
A dashboard dockable has the following components:
- Tab area - contains a tab for each of your dashboards.
- Status bar - provides meta-information on the update of the dashboards, and access to common functions via buttons.
- Current Dashboard - contains the dashboard that is currently selected in the Tab area.
A new workspace starts with a dashboard dockable which in turn has a single empty dashboard. You can create new dashboards in a dockable by double clicking in its tab bar.
Dashboards can be renamed by double clicking on the tab that represents them, then typing in the new name.
You can close dashboards by right clicking or clicking the X on the relevant tab. You will be prompted to confirm your decision if the dashboard contains content.
The dashboard palette allows you to add contents to a dashboard and create your own tools. It is accessed via the application level 'View > Active dashboard palette' menu. An example of the dashboard palette is shown in Figure 56.
Figure 56. The dashboard palette
The palette consists of a set of groups, each group has a number of tools. Groups can be expanded by double clicking on their title bar or using the +/- button on their right. By default when one group is expanded, all others will become collapsed. If you want more than one group open at a time then right click in the palette and toggle the 'Auto Minimise Groups' function.
The palette consists of the following groups (by Category):
- 3D Shapes
- Basic Shape
- Block Arrows
- Call Outs
- ITRS Dark Theme Icons
- ITRS Dark Theme Shapes
- ITRS Light Theme Icons
Users cannot create groups, they are derived from the attributes of the tools within the palette. By default they are grouped by 'Category', for other grouping options right click in the palette, select group and choose a new grouping property.
You can create your own grouping structure by changing the meta-data on the tools within the palette. By default all tools have a category value, but you can add new meta-data to tools and then group by this new meta-data. See Figure 57 for an example.
Figure 57. Grouping the palette by a user defined grouping property
To use a tool simply drag it onto the selected dashboard, and an instance of it will appear. Tools are also accessible when you drag and drop a data item onto the dashboard, see section Active Dashboards for more information.
You can access the properties of a tool by right clicking on it in the palette and selecting 'Properties'. You will be presented with a dialog like the one in Figure 58.
Figure 58. The tool properties dialog
The tool properties are as described in the annotations in Figure 58.
Note: The Object Inspector was a pilot feature released for GA4.10 which displays some modifiers and links properties of dashboard objects. In GA4.11, the Object Inspector now contains the remaining properties that you can modify in the object properties dialog. To open the Object Inspector dockable in Active Console Dashboard User Guide, use the Geneos version 4.11.x in the Geneos Home Page and go to Visualisation > Active Console > Active Dashboard.
Object Inspector dockable displays the Modifiers and Links when an object from the Active Dashboard is selected. This dockable allows you to add, edit, and delete the properties of modifiers and links. You can still edit the object's attributes through its Properties dialog. For more information, see the following:
- Adding modifiers
- Viewing and editing modifiers
- Removing modifiers
- Adding, editing and removing Hyperlinks
To add or edit a modifier and link using Object Inspector, follow these steps:
- Go to View > Active Dashboards > Show Object Inspector.
- Select any object from your Active Dashboard screen.
- Click inside the table to add or edit the URL.
- Press Enter to save the changes.
Selecting the object enables the Modifiers and Links section in the Object Inspector dockable making the Add and Delete buttons become clickable.
Note: Selecting multiple objects at the same time disable the Modifiers and Links section in the Object Inspector dockable.
Widgets are the key preconfigured tools which are supplied to enable users to easily display data in an Active Dashboard. Some of these, such as Active Chart and Active Gauge, will be familiar to users of older versions of Active Console (though they may have been enhanced since you last saw them). Some of them are new to recent versions of Active Console. The Widgets on offer in the Active Dashboard Palette are:
- Picture - see section Active Dashboards for more details.
- Active Gauge - see section Active Gauges for more details.
- Active Chart - see section Active Charts for more details.
- Active Pie Chart - see section Active Pie Charts for more details.
- Active Volume Bar - displays data using a rectangular bar which you can set either horizontally or vertically. The height/length of the bar represents the maximum value that you entered in the Properties, and the value of the entity that is represented by a shade in the bar, is proportional to the height/length of the bar.
- Spark Chart - a small minimalist version of an Active Chart.
- Speedo Style Gauge - a version of an Active Gauge with the appearance of a speedometer.
- Beige Gauge - a version of an Active Gauge with the appearance of a 180 degree beige gauge.
- Fat Gauge - a version of an Active Gauge with a large dial and pointer.
- Half Gauge
Note: If you right click in the Widget group in the Palette, and select "Show Hidden Tools", then five further tools are shown: Active Pie Chart Dataset, Gauge dataset, Active Volume Bar Data Source, Active Chart dataset and Hyperlink. These are hidden by default because it does not make sense to use these tools directly from the Palette. They are discussed in section Active Dashboards, in a context where they can be used.
Pictures are created with the picture tool (in the Widget group in the Active Dashboard Palette). On creation you will be prompted to select the image you want the picture to display (you can cancel this box when it appears if you wish, in which case the picture will be created with no image). In addition the standard appearance settings (see section Active Dashboards), pictures support the following attributes (which can be accessed via the Picture Format section of their properties dialog):
- Picture - a thumbnail of the image will be displayed in the picture dialog. If you click on this you can change the displayed picture.
- Remove image on Apply - if you do not want the picture to contain an image, then tick this box and apply your changes.
- Stretch image to fit shape - unticking this will stop the image scaling; it will subsequently display it at its normal size.
- Transparency - will determine the transparency of the image; note that this is independent of the fill transparency.
Note: Pictures are imported into the workspace. You will not need the original source images, even if you are exporting/ importing the dashboard into another workspace.
Basic Shapes are the building blocks of dashboard diagrams. You can create them using the tools available in the 'Basic Shapes' section of the palette. The following basic shape tools are provided:
- Cut Corner Rectangle
- Corner Section
- Regular Pentagon
- Lightning Bolt
- Half Frame
- Borderless Large Label
- Label Shape
- Label L Shape
- Rounded Rectangle
Note: All the basic shapes apart from lines have the capacity to have text, this tool is just an example of this. For more information about text in shapes and how to change it, see section Active Dashboards.
To move a shape left click and hold the mouse button down on the selected shape then drag the mouse to the desired location.
If a shape is part of a group, and you want to move it (or manipulate it directly) you can hold down the ALT key when selecting it, this will bypass the groups and allow you to change its properties without having to break down the group first.
When you click on a shape you should notice that it becomes surrounded by 8 (light grey) control points (see Figure 59). If you left click and hold down the mouse button on one of these control points and then drag it, the shape will change size. The exact dimension (width, height or both) that changes is dependent on the control point that you selected.
You may also notice that there is a control point in the centre of the shape; you can use this to move the shape around.
Figure 59. Moving and resizing objects
You can specify the properties of shapes by modifying their fields in Object Attributes.
- Select the shape you want to use in Active Dashboard Palette.
- Drag and drop the shape in Active Dashboard.
- Right-click the selected shape and click Properties.
Figure 60. The dashboard object properties dialog
The following properties of a shape can be changed:
- Object Name - the name given to the dashboard object. This is used to reference the shape when using modifiers; it does not determine the text that appears on the object in the diagram (which is specified in the Text property).
- Tooltip - the text that appears on the object when you hover the cursor/pointer over an item.
- Shape Style - a 'wizard' setting that will apply a certain shape style to the selected object as a one-off operation, because you can subsequently change the shape (see section Active Dashboards) this property is not saved as part of the dashboard objects configuration, thus when you next view the properties dialog the shape you selected will not be displayed.
- Width and height - if you want to set an explicit size for the shape you can do it via these settings; clearly you can also resize the shape using its control points. This setting is useful if you want to make many dashboard objects the same size.
- X position x Y Position - sets the location of the selected object in the Active Dashboard.
- Filled - the setting that determines whether the shape should appear filled (rather than just as an outline).
- Fill Colour - determines what colour the shape should be filled with.
- Gradient Target Colour - if this is set then the fill of the shape will be a gradient, from the Fill colour to the colour defined in this setting. For example, if red was the fill colour, and this was set to yellow, then the shape would be filled from a shade of red flowing into a shade of yellow. See section Active Dashboards for further configuration which can be done, including the direction and angle of the fill.
- Transparency - determines the transparency of the fill, where 0 is completely opaque and 100 is completely transparent.
- Drop shadow - determines whether the shape should have a drop shadow.
- Anti-aliased - will make the shapes edge appear smoother, but is more expensive to render, meaning if you have large numbers of anti-aliased objects on the dashboard it will take more CPU. By default this property is turned off.
- Keep Aspect Ratio - allows you to keep the ratio of an object's width to its height.
- Lock Size - allows you to maintain the specified size of the object.
- Visible Border - determines whether the border should be visible.
- Border Colour - determines the colour of the border.
- Line Thickness - determines the thickness of the border (in pixels).
- Line Style - allows you to set the line style to be solid, dashed, dotted or dotted dash.
- Transparency (Border) - determines the transparency of the border, where 0 is completely opaque and 100 is completely transparent.
- Move to front of selection - determines whether when the object is selected it moves to the front of the drawing, see section Active Dashboards for more details.
Note: You can change the visual properties of many canvass objects at the same time by selecting all the relevant objects (see section Active Dashboards), and then bringing up the properties dialog.
With the exception of lines, all basic canvass objects can contain text. The text tool, rectangle tool, and ellipse tool all actually create the same type of basic canvass object (which can have text), just with different default configurations. When text can be displayed in the object, the properties dialog will also contain a 'Text Layout Settings' section, which contains the following settings:
- Text Layout Settings
- Text - the text that appears in the object on the dashboard, the text box will expand automatically as you type.
- Text Font - the font that will be used on the label.
- Text Style - the style of the font can be plain, bold, italic, or bold and italic.
- Text Size - the size of the font (in pt).
- Text Colour - the colour of the text. If this is set to 'None' then the text colour will change to contrast with the selected background colour. For example if the background colour is black then the text will be white. If there is no fill colour then the text will change to be visible on whatever is behind the label.
- Transparency - the transparency of the text, where 0% is completely opaque, and 100% is invisible.
- Anti Alias font - if this is ticked then the font will be displayed anti-aliased.
Note: Anti-aliasing is more expensive in CPU terms than non-anti-aliased fonts.
- Horizontal Text Alignment - determines the positioning of the text in the X axis. It can be left, right or centre aligned.
- Vertical Text alignment - determines the positioning of the text in the Y axis. It can be top, bottom, or centre aligned.
- Multiline - determines whether the text is allowed to span multiple lines of text.
- Line Wrapping - determines whether lines should wrap when there is not enough space to display them (so if ticked then a single line will appear on multiple lines if there is not enough space to display it on one).
- Text Clipping - determines whether the text is allowed to leave the outline of the shape if the shape is too small to contain it all. If this is ticked then the text will not leave the shape outline (so when the shape is very small you may not see it all).
- Allow Direct Editing - if this is ticked then the text will be editable directly on the dashboard rather than going via the properties dialog, see section Active Dashboards for more details.
- Highlight Colour - will determine the colour used to highlight text while it is being edited on the dashboard directly.
- Expose Settings to parent - if this is ticked and the shape is then made part of a grouped object, the Text Layout Settings for the text in this shape will be available in the grouped object's properties.
- Scale Font Size on Zoom - allows the texts to resize when you zoom in and zoom out. You can turn this feature on or off through the Object Attributes dialog box, Text Layout Settings, located at the bottom of Miscellaneous Properties section.
You can edit the text that appears in a label directly by double clicking on the selected label then typing (rather than going via the properties dialog). Once you have finished editing the text, click on another area in the dashboard to stop the edit.
Active Dashboard supports Unicode characters in dashboard labels and texts inputted by the user. You can change the default font and display Unicode characters by doing the following:
Install the font you need if it does not exist in the Text Layout font dropdown list. The font must be a valid and existing system font before it can be used.
Note: If you are displaying Unicode characters, the font must have the specific Unicode characters you need (e.g., MingLiu - Japanese and Chinese, Batang - Japanese and Korean).
For fonts with names that have Unicode characters (e.g., MS ゴシック, ＭＳ Ｐ明朝), it is required to convert the file encoding of ActiveConsole.gci from ANSI to UTF-8. You can do this by using the "Save As..." option in Notepad.
Performing the abovementioned will change:
- Chart headers, labels and legends of dashboard objects that display texts, but do not have a text font selector (Active Chart, Pie Chart and Gauge).
- Default selected font of shapes and objects that have a text font selector. This will not change the fonts of existing shapes or objects in the dashboard.
Note: Gauges have a font selector for headers, thus gauge headers will follow (a), while its labels or legends will follow (b).
Lines are created with the line tool, they have the standard appearance settings like other shapes, plus a number of line specific settings, which are described below.
Note: The visual properties of lines are mainly modified by changing the border settings in the appearance section of the properties dialog.
- Line format
- Line start - determines whether the line should have an arrow head at its start.
- Width and height (of the start arrow) - determines the size of the start arrow head. See Figure 61 for more details.
- Line end - determines whether the line should have an arrow head at its end.
- Width and height (of the end arrow) - determines the size of the end arrow head. See Figure 61 for more details.
- Anchor X offset - the relative X position of the anchor within the boundary of the shape. See Figure 62 for more details.
- Anchor Y offset - the relative Y position of the anchor within the boundary of the shape. See Figure 62 for more details.
- Line Tool Names
- Multipoint line with arrowheads
- Double Line Arrow
- Double Block Arrow
- Thick Line
- Multipoint Line
- Line Arrow
Note: The "Anchor X offset" and "Anchor Y offset" settings do not get displayed if neither end of the line is anchored. If one end of the line is anchored then these settings appear in the Line Start or Line End section as appropriate. If both ends of the line are anchored, then two sets of these settings are displayed, on in the Line Start section and one in the Line End section.
Figure 61. The width and height attribute of arrow heads
To select a line simply click on it. You can move a line by pressing and holding down the mouse over the line and then dragging. A line has a control point at each end; you can use these to drag the end of the selected line around without moving the other end.
Lines can be anchored to other (non-line) objects, such that when you move the other dashboard object around the line remains anchored to it (moved with it). To anchor the end of a line drag the control point at the relevant end over the selected shape and release the mouse pointer. The line will then anchor to the shape at the point you released the mouse. You can see if the line is anchored because a blue circle will appear around the relevant control point. Figure 62 illustrates this concept.
Figure 62. Anchoring lines
You can also change the point at which the line is anchored to the shape by dragging around the line end within the area of the shape. It is possible to manually define the anchor point via the Line Dialog, see Figure 63. You can manually edit the anchor position by going to the line properties and changing the anchor settings, Figure 63 shows you how.
Figure 63. Manually changing the anchor positions
To un-anchor a line select and drag the anchored control point away from the shape to which it is anchored.
You can stop the lines from auto-anchoring by default by right clicking anywhere in the dashboard and toggling the 'Auto-anchor' menu item so that it is not ticked. This can be useful when you want to add lines over the top of existing objects without having them anchor to it (such as when you have pictures in the background of the dashboard).
Lines can have multiple 'way-points' so they can go round other shapes on the dashboard. To add an additional control point to the line, right click at the point you want the 'bend' and select the 'Add control point' menu item. Alternatively you can hold down ALT and then press and drag the mouse at the point in the line you want the new control point to appear at.
Control points in the middle of lines cannot be anchored like the control points at the beginning and end of lines.
A toggle mode that allows lines to auto-lock 90 degree angles such they will remain in the line as line is moved around and repositioned. This makes it easier to create large complex diagrams that remain neat. To toggle this function on and off, right click anywhere in the dashboard and click the 'Auto lock line angles' menu option.
Once active, whenever a line with multiple control points gets a 90 degree angle within its length, this angle will lock.
You can remove such a 90 degree angle by holding down ALT while selecting the control point, then dragging the control point to a different location, or simply turning off the Auto lock function.
Apart from the Widgets and Basic Shapes (see section Active Dashboards), there are a number of other groups of tools available to the user in the Palette.
- Backgrounds - all of the tools in
this group are generic dashboard backgrounds.
- Infrastructure - the tools in this
group are designed to represent infrastructure
components. In each case you can link the object to
the severity of a data item and/or create a
hyperlink from the object to a data item.
- Frames - the tools in this group
are all titled frames which can be used as part of
a dashboard layout. In each case you can link the
object to the severity of a data item and/or create
a hyperlink from the object to a data item. You can
also link the frame title to the name of a data
- Filled Frame
- Glass Frame
- 3D Shapes - the tools in the group
are three dimensional basic shapes. They are used
as building blocks for some of the more complex
three dimensional shapes, such as the
infrastructure tools. Many of the 3D Shapes are
themselves groups of simpler objects.
- Glass Disk
- 3D Cog
- 3D Lightning
- 3D Rectangle
- 3D Rounded Rectangle
- 3D Triangle
- 3D Diamond
- 3D Hexagon
- 3D Speech Bubble
- 3D Cloud
- 3D Ellipse
Note: Because of the way these tools are themselves composed, you cannot really see the colourisation if you attempt to link one of these objects to the severity of a data item. To see colourisation of a 3D shape in the way that you would expect, and to see data from a data item more clearly displayed, you should select a tool from the group "3D shapes for data items".
- 3D shapes for data items - the
tools in this group are three dimensional basic
shapes that have been specifically designed to
display clearly the severity and values of a
related data item.
- 3D Data Item Square
- 3D Data Item Rounded Rectangle
- 3D Data Item Triangle
- 3D Data Item Diamond
- 3D Data Item Hexagon
- Data Item Speech Bubble
- 3D Data Item Cloud
- 3D Data Item Ellipse
- Cell Button
- Block Arrows
- Glass Frame
- Filled Frame
- Equal to time range
- User Defined
- Past working day (6am to 8pm)
- Last Minute
- Last Hour
- Last 24 hours
- Last Week
- Last Month
- Last Year
- Time Series
- Time Series on existing chart
- New Time Series
- User Assigned Indicator
- Snooze Indicator
- Breach Predictor
- New Breach Prediction
ITRS Theme Icons and Shapes - the tools and shapes in these groups are a set of icons and shapes that can well represent your system infrastructure and operations. They are very useful in creating best practice dashboards for your organisation.
- Dark Theme Database
- Dark Theme Client
- Dark Theme Gateway
- Dark Theme Rack
- Dark Theme Application
- Dark Theme Server
- Dark Theme Firewall
- Dark Theme Exchange
- Light Theme Capsule
- Light Theme Database
- Light Theme Label and Bar
- Light Theme Gauge
- Light Theme Server
- Light Theme Block with Name
- Light Theme Client
- Light Theme Rack
- Light Theme Gateway
- Light Theme Exchange
- Light Theme Simple Line Chart
- Light Theme Block with Value
- Light Theme Firewall
- Light Theme Application
- Light Theme Dotted Group
- Block 4 with Name
- Volume Bar
- Block 4 with Value
- Block 2
- Meter Gauge
- Line Chart 1
- Group - Dotted
- Line Chart 2
- Label and Bar
- Block 3
- Area Chart
- Group - Dashed
- Text Label
- Line Chart 3
- Block 1
ITRS Dark Theme Shapes
- Area Chart
- Block 1
- Block 2
- Block 3
- Block 4 with Name
- Block 4 with Value
- Label and Bar
- Line Chart 1
- Line Chart 2
- Line Chart 3
- Meter Gauge
- Text Label
- Volume Bar
ITRS Light Theme Icons
- Large Application LT
- Large Client LT
- Large Database LT
- Large Exchange LT
- Large Firewall LT
- Large Gateway LT
- Large Racks LT
- Large Server LT
- Medium Application LT
- Medium Client LT
- Medium Database LT
- Medium Exchange LT
- Medium Firewall LT
- Medium Gateway LT
- Medium Rack LT
- Medium Server LT
- Small Application LT
- Small Client LT
- Small Database LT
- Small Exchange LT
- Small Firewall LT
- Small Gateway LT
- Small Rack LT
- Small Server LT
ITRS Light Theme Shapes
- Area Chart LT
- Arrow LT
- Block 1 LT
- Block 2 LT
- Block 3 LT
- Block 4 with Name LT
- Block 4 with Value LT
- Capsule LT
- Group-Dashed LT
- Group-Dotted LT
- Label and Bar LT
- Line Chart 1 LT
- Line Chart 2 LT
- Line Chart 3 LT
- Meter Gauge LT
- Square LT
- Text Label LT
- Volume Bar LT
If you have "Show Hidden Tools" selected in the Palette context menu, you will see four further groups of tools: Data Item tools, Historical, Breach Predictor, and Time Series. However, for all of the tools in these groups, the tool has no relevant use from the Palette; it is used in conjunction with dragging and dropping a data item onto the dashboard. For further information on these tools, see section Active Dashboards.
You can configure selected shapes to automatically move to the front of the dashboard (move over the top of other objects) when they are selected. To do this, right click to access their properties and select 'Move to front on selection' in the Appearance settings. From this point, when selected they will move to the front as though you had right clicked and selected 'Arrange > move to front'. If the object is part of a group then the whole group will be moved to the front.
Note: This functionality can be deactivated at dashboard level - see the "Allow Objects to move to front" dashboard property in section Active Dashboards.
You are not restricted to the default shapes available via the Palette and the ones provided in the 'Shape 'settings of the appearance section in the properties dialog. The dashboard actually allows you to define arbitrary polygons. There are two main ways to construct such shapes (and they are not mutually exclusive, they can be used together):
- Shape Amalgamation and Subtraction - allows you to modify existing shapes by adding and subtracting the areas of other shapes from the target.
- Segment manipulation - shapes are made up of a number of segments, where each segment is a straight line or curve (a square for example would be made up of 4 segments). It is possible to add, remove and modify segments directly.
We can build up more complex shapes from basic shapes by using the Amalgamate shape functionality. This works by selecting a set of other dashboard objects (which may have been created specifically for the purpose of creating the complex shape), then right clicking on one of the selected shapes and selecting the 'Shape > Amalgamate selected shapes' function. The shape that was right clicked on will now have its border augmented with the boundaries of the other selected shapes. An example can be seen in Figure 64.
Figure 64. Amalgamating shape outlines
The inverse can also be achieved, in that you can delete the area of the other selected shapes from the selected item. An example can be seen in Figure 65.
Figure 65. Subtracting shapes from a selected shape
To do this hold down the ALT key and then click on the object whose shape you want to change (or use the right click 'Edit Properties Directly' menu item). New red and blue segment control points will appear around the edge of your shape, dragging these control points will actually modify the shape of your object. You can add additional shape segments and modifying existing ones, these functions are discussed in the following sections.
Figure 66. Segment control points (to access this mode hold down the ALT key and click on the object)
Adding and removing shape segments
You can add additional shape segments by right clicking on an existing segment control point and selecting the 'Shape Segment > Insert New Segment'. A new line segment will be created (anti clockwise of the point you right clicked on) in the shape. You can delete a segment by right clicking on a segment control point and selecting the 'Shape segment > Delete Segment' menu item, the segment anticlockwise from the selected control point will be removed.
Modifying the types of segments (adding curved edges)
By default segments are simply straight lines, however you can also add curved segments to your shapes. To change the type of a segment right click on the relevant Segment Control Point and select one of the following from the 'shape segment' menu:
- Single point - this segment will be a simple straight line between its adjoining segments.
- 2-point curve - this segment will be represented by 2 control points; one determines the segment end, while the other can be used to change the curve on the segment. This curve will bend in just one direction.
- 3-point curve - this segment will be represented by 3 control points. One will determine the segment end while the other two will determine the bend(s). This is a Bezier curve, in that it can bend in two separate directions.
You can rotate shapes and groups of shapes via the Rotate control point at the top of each shape (this looks like a semi-circle), just click and hold on the control point and drag left and right.
If you have configured a shape to have a gradient fill (via the object properties, see section Active Dashboards), you can further manipulate it by using the ALT mode on a canvass shape (hold down ALT and click on the shape whose gradient fill you want to manipulate).
Figure 67. Modifying a gradient fill
You will see two additional control points (as shown in Figure 67) which define the start and end of the fill. If you imagine a straight line between these two control points, the fill will start from the colour of one control point then flow smoothly into the colour of the second along the imagined line. The pattern will repeat if the gradient fill control points are inside the boundary of the shape.
Note: If the shape is rotated then the gradient fill will not be rotated.
Individual dashboard objects can be selected by clicking on them with the mouse. If you want to select multiple objects at the same time then you can employ one of the following techniques:
- Holding down control - if you hold down control while selecting then you can select multiple objects (without losing your previous selection).
- Area selecting - you can drag a 'selection rectangle' around shapes, to do this press and start dragging the mouse on an area of the canvass with no shapes, a selection rectangle will appear, place this around the shapes you want to select then release the mouse. The objects within the area will become selected.
- The right click 'Selection' menu - clicking anywhere in the dashboard will present you with the 'selection' menu from which you can 'select all' and 'select none'.
Many of the functions on the dashboard are appropriate for multiple objects at the same time, for example grouping and aligning of objects.
If you access the properties of a grouped object you will see the dialog shown in Figure 68 rather than the basic shape properties.
Figure 68. Grouped objects properties
There are only a few properties that can be set on a group, they are as follows:
- Object name - the name of the group, this has no visual effect; it is used to reference the object via other mechanisms.
- Width and height - defines the width and height of the grouped object
- Atomic group - if this is ticked then the object cannot be ungrouped.
- Move to front on selection - if this is ticked then the object is selected by a user it will move to the front of the dashboard
You can set up hyperlinks on the group, which will override those set on its child objects is selected.
You may also see Text Layout Settings available through the group object's properties if any of the constituent objects have been configured to expose these settings to the parent object.
If a set of dashboard objects that have no common settings, such as line or group properties is selected, this prompts an error message.
Note: You can access the properties of objects within a group without ungrouping by holding down ALT and right clicking on the child object to which you want access.
If there are many stacked objects in the Active Dashboard, right-click the object, and then click the Temporarily Hide Selected option to hide it.
This hides the object allowing the users to modify the object underneath.
Select the Unhide All option to re-display the hidden object. The hide status is not persisted.
So, once you save or reload the workspace, this will remove the hide status.
To delete one or more dashboard objects select them, then right click and select 'Delete'. You can also use the backspace and delete keys. If you delete a group then all the objects within that group will be deleted.
Modifiers are things which update the dashboard based on changes in the gateways that are being monitored. A modifier is added to a dashboard object, it can do one of the following things:
- Change the fill colour based on severity of a data item
- Change the border colour based on the severity of a data item
- Change the text based on the name of a data item
- Change the text based on the value of a data item
- Change the picture based on the icon of a selected data item
- Replace the URLs on the dashboard object to point at the Data item (this will replace all existing URLs, not add to them)
To add a modifier to a dashboard object just drag the selected data item from another active console dockable (such as the state tree, entity view or metrics view) onto the selected dashboard object, select the "All Modifiers" tab from the resultant dialog and select the modifier that you want to apply. Figure 69 shows an example of this.
Figure 69. Adding a modifier to a dashboard
The modifier will then be applied to the object. If you have used the modifier recently, then it may be in 'Recently Used' tab, which means you may not need to go to the 'All Modifiers' section to set this up.
There are two ways to see what modifiers are set up on a dashboard object:
- Tooltips - moving your mouse over the selected dashboard object and viewing its tooltip will detail any modifiers that are currently acting on it.
- Properties dialog - if you bring up its properties dialog you will see a modifiers section, which will detail any modifiers that are currently acting on the object.
You can modify the data items that a modifier reacts to by changing the path in the properties dialog, see Figure 70 for the location of this setting:
Figure 70. The modifiers dialog
These paths can be wild carded (match many items), where this is the case the highest value of the matching items will always be used (i.e. the highest severity or highest value). In the case of pictures and data item names it will simply use the last one in the matching list (therefore it makes little sense to match these to multiple items). See section Referencing Components via Paths about how to create paths.
To remove a modifier go to the modifiers section in the properties dialog for the selected dashboard object and select the modifier that you want to remove, then click on the minus button to the left of the list. There will be no changes in the visual settings of the object as a result of this action, therefore for example if it was changing the fill colour to be equal to severity, and it was green, it would still be green after the modifier had been removed.
Checking and updating a modifier on its own is not an expensive operation, but if you have dozens (or even hundreds) of modifiers you may notice a higher CPU requirement on your computer. You can change the rate at which modifiers evaluate in the advanced settings of the workspace.
Note: This setting (which is in seconds) will determine how long the dashboard will wait before it re-evaluates its modifiers. This means that the information on the dashboard could be up to X seconds old, where X is your selected setting value.
The Custom Modifier Manager is available under the Tools menu. It allows you to supplement the hardcoded modifiers that exist in the workspace with your own custom modifiers.
Modifiers link a property of a data item (i.e. an entity, probe, data view, cell or headline) to a property of a dashboard object (i.e. fill colour, visible border, transparency and so on). These are contained as part of the workspace. The console comes with a number of predefined modifiers, but you can also create your own using the Custom Modifier Manager.
A modifier is used by dragging a data item onto the dashboard and selecting the appropriate modifier from the available list in the dialog. However, not all modifiers are appropriate to all items. For example, a fill colour modifier will not work on a line. When the modifier is used, a copy of it is made and added to the dashboard object, and no link back to the original modifier is maintained. This means that if the dashboard is then ported to a second workspace or the Web Dashboard server, there is no need to also have the original modifiers in the target. If a modifier is used and added to a dashboard object, it cannot be extracted from that object. It has to be recreated using the Custom Modifier Manager.
In the underlying system, what actually happens is that the XPath of the item that you dropped is added to the modifier. All data items which match that path contribute to the effect of the modifier. If the path matches nothing, then the default value defined on the modification is used. This will be discussed in detail in the later sections.
There are some restrictions on what sort of data item properties can be connected to what sort of dashboard object properties. For example, if a 'Visible Border' dashboard object property is used (which can be true or false), it needs to be used in combination with a data item property which is also true and false, such as 'Snoozed' or 'Active' and so on. If you attempt to use an invalid modifier, it will not do anything.
The following are the allowable properties and their types:
Data Item Properties and Their Types
|Property||Data Item Type||Effective Type|
|Value||Cell or Headline||Variant|
Dashboard Object Properties
|Property||Dashboard Object Type||Effective Type|
|SIZE_HEIGHT||Group or Polygon||Float|
|SIZE_WIDTH||Group or Polygon||Float|
|POSITION_X||Group or Polygon||Float|
|POSITION_Y||Group or Polygon||Float|
|VISIBLE_BORDER||Line or Polygon||Boolean|
|BORDER_COLOUR||Line or Polygon||Colour|
|BORDER_THICKNESS||Line or Polygon||Float|
|BORDER_STYLE||Line or Polygon||Int|
|BORDER_TRANSPARENCY||Line or Polygon||Float (0..1)|
The following are the allowable mappings:
|Data Item Property Type||Allowed Dashboard Object Property Types|
|Int||Float, Int, String|
|Boolean||Boolean, Colour, String|
|Variant||Boolean, Float, Int, String|
When designing modifiers, there are a few properties you will need to set:
Name - will be displayed in the modifier selection dialog when an item is dragged onto the dashboard and in the Modifier section of the properties dialog for a dashboard object. The tools do not enforce any standards on the designer of a modifier as to what the name might be, but it is strongly suggested that as a designer, you include a complete list of the modifications that the modifier will make when used, i.e. Severity linked to Fill colour and Label text to value. Also note that names need to be unique within the workspace. This will be enforced in the Custom Modifier Manager, but not when importing modifiers.
Description - a longer string describing the modifier. This only appears in the Modifier selection dialog when an item is dragged onto the dashboard.
A set of modifications, where each modification has:
- The data item property
- The dashboard object property
- A default value which will be used if the XPath driving the modifier matches no data items
- Specific rules while applying to certain property combinations
Where a modifier has more than one modification, they will all be applied when used. The XPath driving the modifications will be the same for modifications.
For some of the dashboard object properties, it may not be immediately obvious what values you need to set to get the desired effect, or even what values are allowable.
The following are the expected and allowable values for each property:
|Property||Dashboard Object Type||Effective Type||Allowable Values|
|SIZE_HEIGHT||Group or Polygon||Float||Any numeric. This will link the value of the data item property to the literal pixel width of the dashboard object. It is generally suggested you avoid objects getting too large as the rendering time will increase. By too large, it is generally exponentially larger the the screen real estate allowed. Many screens have a width of up to 2000 pixels, so making an object more than 4000 pixels wide may decrease performance in the dashboard.|
|SIZE_WIDTH||Group or Polygon||Float||Any numeric. This will link the value of the data item property to the literal pixel height of the dashboard object. It is generally suggested you avoid objects getting too large as the rendering time will increase. By too large, it is generally exponentially larger the the screen real estate allowed. Many screens have a height of up to 1200 pixels, so making an object more than 2400 high pixels may decrease performance in the dashboard.|
|POSITION_X||Group or Polygon||Float||Any numeric. This will link the X position of the dashboard object to the value of the data item property. The left hand corner of the dashboard represents 0, and the object will be positioned that many pixels from the left edge based on the data item value. Note that if the X position exceeds the width of the screen, then the object will be pushed off to the right and scroll bars will appear on the dashboard. Users should avoid making the dashboard to large using this method. For example moving an object to 4000 pixels will make the dashboard 4000 pixels wide and increase rendering time. In the event that the number is negative, then the object will be moved to that negative position, followed by 0,0 being redefined. In effect, all other dashboard objects will appear to shift right.|
|POSITION_Y||Group or Polygon||Float||Any numeric. This will link the Y position of the dashboard object to the value of the data item property. The top left hand corner of the dashboard represents 0, and the object will be positioned that many pixels down based on the data item value. Note that if the Y position exceeds the height of the screen, then the object will be pushed off to the right and scroll bars will appear on the dashboard. Users should avoid making the dashboard to large using this method. For example moving an object to 4000 pixels will make the dashboard 4000 pixels high and increase rendering time. In the event that the number is negative, then the object will be moved to that negative position, followed by 0,0 being redefined. In effect, all other dashboard objects will appear to shift down.|
|FILLED||Polygon||Boolean||This will map a Boolean (true or false) data item property (such as snoozed or active), to the filled property of the dashboard object. Within the modification design, you can also invert this, i.e. if snoozed = true, then filled = false.|
|FILL_COLOUR||Polygon||Colour||Only severity can be used for fill colour, and you will be able to select the colours that match to each severity value (Undefined, OK, Warning and Critical). In the event that no data items match the connected path, the undefined colour will be used.|
|FILL_TRANSPARENCY||Polygon||Float (0..1)||This will match a floating point value, which must be within a 0 to 1 value. Where 1 = Opaque and 0 = 100% transparent, and any value in between on a sliding scale. For example, 0.25 is 75% transparent, and 0.5 is 50% transparent. Values outside of 0 to 1 will have no effect.|
|VISIBLE_BORDER||Line or Polygon||Boolean||This will map a Boolean (true or false) data item property (such as snoozed or active), to the 'Visible Border' property of the dashboard object. Within the modification design, you can also invert this, i.e. if snoozed = true, then visibleBorder = false.|
|BORDER_COLOUR||Line or Polygon||Colour||Only severity can be used for border colour, and you will be able to select the colours that match to each severity value (Undefined, OK, Warning and Critical). In the event that no data items match the connected path, the undefined colour will be used.|
|BORDER_THICKNESS||Line or Polygon||Float||Any numeric. It does a literal mapping of the value to the pixel width of the border.|
|BORDER_STYLE||Line or Polygon||Int|
This accepts a finite set of values, where values outside the set will have no effect. The allowable values are as follows:
|BORDER_TRANSPARENCY||Line or Polygon||Float (0..1)||This will match a floating point value, which must be within a 0 to 1 value. Where 1 = Opaque and 0 = 100% transparent, and any value in between is a slide scale. For example, 0.25 is 75% transparent, and 0.5 is 50% transparent. Values outside of 0 to 1 will have no effect.|
|TOOLTIP_TEXT||Any||String||Any string or numeric value. This will append the string to the existing tooltips of the dashboard object.|
|LABEL_TEXT||Any Polygon||String||This will map the data item property value to the text. In the event that the path within the modifier matches many items, the text will show all values as a comma-separated list.|
|LABEL_FONT_SIZE||Any Polygon||Int||This will take an Integer data item property value and map it as a literal to font size of the dashboard object. 0 or negative values will be ignored.|
|LABEL_FONT_COLOUR||Any Polygon||Colour||Only severity can be used for font colour, and you will be able to select the colours that match to each severity value (Undefined, OK, Warning and Critical). In the event that no data items match the connected path, the undefined colour will be used.|
|LABEL_CLIP||Any Polygon||Boolean||This will map a Boolean (true or false) data item property (such as snoozed or active), to the 'Label Clip' property of the dashboard object. Within the modification design, you can also invert this, i.e. if snoozed = true, then Label Clip = false. The Label Clip property, if set to true, stops the text from being rendered outside of the shapes area.|
This accepts a finite set of values, where values outside the set will have no effect. The allowable values are as follows:
This accepts a finite set of values, where values outside the set will have no effect. The allowable values are as follows:
|PICTURE_STRETCH||Picture||Boolean||This will map a Boolean (true or false) data item property (such as snoozed or active), to the 'Picture Stretch' property of the dashboard object. Within the modification design you can also invert this, i.e. if snoozed = true, then PictureStretch = false. The picture stretch determines whether a picture imported to the dashboard via the Picture widget retains its normal size, or stretches to fit the picture widget as its shape and ratio is changed.|
|REPLACE_URLS||Any||String||This will take the string value from the data item property, and replace all URLs on the dashboard object with that string. There are a number of constraints around this, and probably gateways changes as well to make this useful. This page - Can I make the URL on a dashboard object dynamic? goes into the subject in more detail.|
|ROTATE||Any||Float||This will rotate the object as many degrees as the data item property (which needs to be numeric). For example, if the value changes to 10, then the shape will rotate 10 degrees. The rotation will occur based on the dashboard shapes current state, i.e. if it has been rotated in the past, a value of 10 degrees will rotate it a further 10 degrees, not a literal 10 degrees from a 0 degree start.|
|GRADIENT_FILL_COLOUR||Any Polygon||Colour||Only severity can be used for gradient colour, and you will be able to select the colours that match to each severity value (Undefined, OK, Warning and Critical). In the event that no data items match the connected path, the undefined colour will be used.|
Modifiers can be added to a workspace by importing them, or directly via the Custom Modifier Manager. Within the manager, use the plus button to the left of the list that will both open the Modifier Editor and add a modifier.
If you double-click on a modifier in the Custom Modifier Manager, you will be able to edit its properties. The sections above should have provided a good overview of what is possible, so what remains to be said is that from here, you can edit the modifier's name, description, and its set of modifications.
- On the Tools menu, click Custom Modifier Manager.
- On the Custom Modifier Manager screen, click the Add (+) button.
- On the Modifier Editor screen, click the Add (+) button.
- On the Data Item Property menu, select Severity.
- On the Dashboard Object Property menu, select Fill Colour.
- Click Apply, and then click OK.
Clicking the colours of severity values (Undefined, OK, Warning, and Critical) and Boolean values (True and False) opens a colour picker dialog where you can change and choose more colours.
If you set a Boolean data item property and a Boolean data object property, selecting the option 'Opposite value' inverts the setting, i.e. if snoozed is filled and you selected 'Opposite value', snoozed items will not be filled.
Modifiers can be removed via the list in the Custom Modifier Manager. Removing a modifier will not affect any dashboard object where it has been used as those modifiers will still be present.
Modifiers can be exported from a workspace such that they can be shared with other users (by importing them into their own workspace). To export one or more modifiers, go to Tools > Custom Modifier Manager. Select one or more modifiers from the list (hold down the CTRL key when selecting modifiers to multiple select), then press the 'Export' button. All the selected modifiers will be exported to the same (user-defined) file.
If a modifier file that has multiple modifiers inside it is subsequently imported, all the modifiers will be added to the target workspace. The user will not be able to cherrypick.
Modifiers can be imported via the File > Import menu. On import, the Custom Modifier Manager will be automatically displayed. You can only import one modifier file at a time, although that file may contain many modifiers (see Exporting Modifiers).
Note: It is recommended that you avoid having modifiers with the same name in the same workspace. This will both confuse users and potentially cause unpredictable operation of the dashboard. If there is an issue during the import, then a dialog detailing the problem will appear.
You can drag and drop data items directly onto the dashboard from other Active Console dockables (e.g. the state tree, entities view or metrics view). When you do this a dialog will appear asking you which tool you would like to use to represent the data item. Figure 71 illustrates this concept:
Figure 71. Dragging and dropping a data item into the dashboard
The tools within the dialog are grouped by the same property used to group the tools in the palette; you can browse through the tools and select the one you want to represent the selected data item with.
Most of the tools available via this dialog are discussed in the section on the Active Dashboard Palette. See section Active Dashboards for information about the Widget tools, Basic Shape tools, and other tool groups. However, there are some tools which are, by default, hidden in the palette, since their only sensible use is when selected from the Tools & Modifiers dialog while dragging and dropping a data item to the dashboard, as being described here. Here is a description of the tools which are generally only used from this dialog, and which are therefore not described in the sections of this manual referenced above.
- Widget group
- Active Chart Dataset - used to add a new dataset to an existing Active Chart or Spark Chart. The previous dataset or datasets for this chart will still be displayed, with the new dataset additionally shown. To use this tool, drag and drop a data item onto an existing Active Chart or Spark Chart, and select this tool from the Tools & Modifiers dialog. For further information on Active Charts, see section Active Charts.
- Gauge Dataset - used to add a new dataset to an existing Active Gauge, Speedo Style Gauge, Beige Gauge or Fat Gauge. The previous dataset or datasets for this gauge will still be displayed, with the new dataset shown by an additional pointer in the gauge. To use this tool, drag and drop a data item onto an existing gauge and select this tool from the Tools & Modifiers dialog. For further information on Active Gauges, see section Active Gauges.
- Active Pie Chart Dataset - used to add a new dataset to an existing Active Pie Chart. The previous dataset or datasets for this pie chart will still be displayed, with the new dataset shown as an additional slice in the pie. To use this tool, drag and drop a data item onto an existing Active Pie Chart and select this tool from the Tools & Modifiers dialog. For further information on Active Pie Charts, see section Active Pie Charts.
- Hyperlink - used to create a hyperlink to a data item when dragging and dropping the data item onto the dashboard, either onto an existing object or onto blank space. For further information on Hyperlinks and their creation, see section Active Dashboards.
- Data Item Tools group - the tools
in this section will be familiar to users of older
versions of Active Console.
- Data Item Tool - displays the icon of the selected item, with its name in a label underneath it, and a border round both items. Both the border and the label background change colour based on the items severity. The icon will change to represent the current state of the selected item.
- Managed Variable Tool - the same as the Data Item Tool, but also includes an additional label which displays the value of the managed variable.
- Compact Managed Variable Tool - contains two labels, one for the name of the managed variable, and one for the value of the managed variable. The background of the name label will update to show the data items severity.
These tools are illustrated in Figure 72.
Figure 72. Data Item Tools
The dashboard objects that the Data Item tools create are actually made up of several dashboard objects. Like any other grouped object you can ungroup them by right clicking on the object and selecting the 'Arrange > ungroup' menu item. You can then edit, modify or delete these objects independently.
When objects are added to the dashboard using the Data Item tools, their default size will be adjusted by the current zoom factor defined for the dashboard, see section Active Dashboards for more details.
Hyperlinks to the data items they display are automatically set up on each of the objects that make up these dashboard objects, thus double clicking on them will take you to the selected data item in the Active Console.
- Historical group - the tools in
this group are used to create an Active Chart or
Spark Chart using historical data, or to add
historical data to an existing chart. For more
information on the use of these tools and on the
use of historical data in charts, see section
- Historical Chart Dataset [User Defined]
- Historical Chart Dataset [Last 24 hours]
- Historical Chart [Last 24 hours]
- Historical Chart Dataset [Last Week]
- Historical Chart [User Defined]
- Historical Chart [Last Week]
- Historical Chart [Last Month]
- Historical Chart Dataset [Last Minute]
- Historical Chart [Last Year]
- Historical Chart Dataset [Last Hour]
- Historical Chart Dataset [Last Year]
- Historical Chart [Last Minute]
- Historical Chart [Last Hour]
- Historical Chart [Past working day (6am to 8pm)]
- Historical Chart Dataset [Past working day (6am to 8pm)]
- Equal to time range
- Historical Chart Dataset [Last Month]
If you select and subsequently drop multiple data items onto the dashboard at the same time a dashboard object will be created for each of them, they will then be grouped together. This is particularly useful when using the compact managed variable tool where the result will resemble a table.
There are number of functions supported by the dashboard for arranging dashboard objects with respect to each other. They can accessed by selecting the relevant objects (see section Active Dashboards), them right clicking on one of the selected objects and going to the 'Arrange' menu. Here you will find the following functions:
- Group - dashboard objects can be grouped together. When grouped they can be moved and resized as though they were a single object. Groups can contain other groups.
- Ungroup - if you have a selected a group then this function will ungroup it into the objects that were originally used to form the group.
- Move to front - will move the selected objects in front of all other dashboard objects.
- Move to back - will move the selected objects behind all other dashboard objects.
- Align Left - will align the selected objects, so that their left most points are equal to the left most object at the time the function is used.
- Align Right - will align the selected objects, so that their right most points are equal to the right most object at the time the function is used.
- Align Center - will align the centre of all the selected objects so that they are in straight line from top to bottom.
- Align Top - will align the selected objects, so that their upper most points are equal to the upper most object at the time the function is used.
- Align Bottom - will align the selected objects, so that their lowest most points are equal to the lowest most object at the time the function is used.
- Align Middle - will align the middle of all the selected objects so that they are in straight line from left to right.
- Distribute Horizontally - will distribute the selected objects so that are equally spaced, and not overlapping, from left to right.
- Distribute Vertically - will distribute the selected objects so that are equally spaced, and not overlapping, from top to bottom.
If you want to change the properties of just one object within a grouped object, then hold down the Alt key, right click on the appropriate object, and select Properties. You will now be editing the properties of only the object that you clicked on.
If you right click and select Properties on a grouped object without holding down the Alt key, then this will bring up the properties for the grouped object as a whole.
You can zoom in and out of the dashboard via the following methods:
- Mouse Wheel - rotating the mouse wheel while holding down Control with the dashboard in focus will zoom in/out by 10% for each notch rotated.
- Via the dashboard properties - you can set the dashboard zoom via the dashboard properties.
- Right click menu - if you right click on the dashboard and expand the zoom menu you will see some preset zoom ranges defined, which you can use to go to a certain zoom level, the available levels are 10%, 50%, 100% (normal size), 200%, and 300%.
The minimum zoom level is 10% of the normal size, the maximum zoom is 300%.
You can configure a dashboard to snap objects that are moved and resized to the background grid. This feature is accessible via the dashboard properties dialog, or via the right click menu on the dashboard. If the size of the background grid squares is modified (by zooming or modifying the grid size via the dashboard properties) then movement and changes in dashboard object size will honour the new grid size (i.e. their movements and size will suit the newly resized background grid).
Note: Segment control points and waypoints in lines will NOT honour the grid, they are treated as free form objects.
Some dashboard objects (such as Active Charts and Active Gauges) can be detached from their native dashboards and placed into their own frames. To do this right click on the relevant object and select the detach menu item. Figure 74 illustrates this process.
A proxy dashboard object will remain on the dashboard; it can be moved, resized and grouped like any other dashboard object. To reattach the object right click on it in its detached frame and select 'Attach'. It will be restored to the dashboard in the same position and size as its proxy.
Dashboard objects detached in this way will have their detached status (including the frame position and size) saved and restored with the workspace.
The dashboard has a number of attributes that you can configure. To change these, right-click the dashboard and click Properties. You can change the following:
- Fill Colour — determines the background colour of the dashboard.
- Grid line Colour — defines the colour of the grid lines on the dashboard.
- Visible Grid lines — determines if the grid lines are visible.
- Snap to grid — toggles the snap to grid functionality.
- Zoom Factor — will set the zoom on the dashboard.
- Grid Size — defines the size of the background grid, which is what objects 'snap to' when the snap to grid functionality is turned on.
- Show tooltip on hover — enables the modifier information as a tooltip for dashboard objects. By default, this option is enabled.
- Allow Objects to be selected —
determines if the objects on the dashboard can be
- If set to true, a double-click opens the external links defined in the object property.
- If set to false, a single-click opens the external links defined in the object property.
Note: This applies to both auto-generated tooltips when modifiers are added and the user-defined tooltips in the object properties. User-defined tooltips override auto-generated tooltips from modifiers.
Note: Area selection is still possible unless you also turn this off.
- Allow Objects to be moved — determines if you are allowed to move objects on the dashboard.
- Allow Edit Menu items — if this option is deselected then all entries on the right-click menu on the dashboard, apart from 'Properties...', are removed.
- Active Control Points — determines whether control points are active or not, if not then you will not be able to resize or change the shape of dashboard objects.
- Allow area selection — determines whether you can drag out an area selection to multi‑select objects.
- Allow mouse wheel zoom — determines whether you can resize the dashboard by holding down the control key and using the mouse wheel.
- Allow Objects to move to front — determines whether or not objects can be configured to move in front of other objects when they are selected.
- Display Status Bar — determines whether or not the status bar (which also includes the tool bar) is displayed or not.
There are also a set of functions in the dashboard properties to export the dashboard at a defined interval as an image to a define location.
You can export dashboards by right clicking anywhere in a dashboard and selecting one of the following export functions:
- Save as JPEG... - will export the whole dashboard to a jpeg file of your choosing (you will be prompted to select the file at the time you use this function).
- Export... - will export the dashboard to a .adb file (which is a format specific to the Active Console). This can then be imported into another workspace. You will be prompted to specify the path and filename when you use this function.
Dashboards that have been exported as a .adb file can be imported into another workspace using the 'File > Import...' application level menu option. This will add the imported dashboard into its own (new) tab in the dashboard manager.
It is also possible to configure the dashboard to export itself as an image at a defined interval - see section Active Dashboards.
When a dashboard is imported into the workspace or user defined tools are added, the modifiers connected to these are added as customer modifiers.
Some dashboard components (such as charts) can be exported to an external file by themselves. Such files are exported as .dbi files (Dashboard Items), they can be imported via the 'File > Import...' application level menu item. They will be imported into the currently selected dashboard.
There is a piece of simple functionality in the dashboard, accessible via the dashboard properties which allows you to have the dashboard export itself as an image (and optional html file) to a specified location at a defined interval.
This function and its associated settings are known collectively as the Active Dashboard Server edition. The principle purpose of this function is to have the dashboard write the image (and HTML) to a LAN, WAN or web accessible location such that other people can view the dashboard without needing the Active Console. The HTML contains an automatic refresh meta-tag which means the HTML page in users browsers will update at the same interval as the dashboard exports to the location. This will create the illusion of an updating dashboard in a web browser.
The settings you need to configure are:
- Export period (Seconds) - a frequency (in seconds) that the dashboard should write to the specified location. Writing the image requires moderate CPU for a short time, so it is recommended that this interval is not less than 10 seconds (though it will work). If this setting is 0 the dashboard will NOT export (the function will be turned off).
- Export File - the path and filename of the image to write. The image will be written as a jpeg.
- Export HTML with image - if this option is ticked then a basic html that contains the image and the relevant meta-tags will be written to the same directory. The file will have the same name as the image (but with an HML extension).
- Compression Ratio - determines how much compression occurs on the jpegs the Active Console is creating. This is a value between 0-100, where 100% compression is maximum quality. Higher compression will generate smaller picture files, but at reduced quality.
The following are things to consider when using Active Dashboard Server edition:
- It is just an image! You will get none of the rich interactivity you get from the normal dashboard, including hyperlinks, right click menus, control points and so on.
- The HTML may be overwritten! If you use the HTML function, whereby the Active Dashboard writes out a suitable HTML file with the image, then there are times when Active Console will overwrite this file with new HTML, therefore any changes you have manually done to it would be lost.
Note: This will NEVER affect HTML files which Active Console does not write out (see point 3 in this list).
- You can include the pictures in our own
HTML. You do not have to use the HTML
pages that Active Console outputs, or even have
it write them at all; you can embed the images
directly in our own HTML pages. This can be
useful if you want to:
- Have many dashboards on one page.
- Have the images embedded in own pages.
- Annotate the dashboards with text, other pictures and hyperlinks.
- Generates network traffic. There is relatively little cost in the dashboard publishing the image to its target destination, however everyone who points their web browsers at the relevant html page will have a new image sent to them at each refresh interval. Typically the images will be between 25 - 300k, depending on the size of the dashboard and the selected compression ratio.
If you choose to build your own web pages around dashboard images then include the following meta-tag in the header file of your HTML page to have them update at regular intervals:
<meta http-equiv="refresh" content="10">
Active Charts are available on the Active Dashboard. A dashboard is capable of displaying multiple charts, each of which can plot multiple datasets from different Data Items.
An example chart is shown in Figure 75. A chart always plots time on the X-axis, and the value of the data points (that make up the datasets) on the Y-axis.
Note: This does not by default start at 0 unless the data requires it or it is hard coded to do so by the user.
The heading at the top is user configurable and the legend is always displayed at the bottom (unless there is insufficient room or it is turned off).
All the datasets configured on the chart will plot in the chart area; their look and feel (i.e. colour, type) is user configurable.
Figure 75. An Active Chart
Tooltips are available on most parts of a chart; most significantly if you move your mouse over a data point it will tell you the value and the name of the dataset, the value on the X and Y axes, the value of the plotted data item when it came from the gateway, and the position of the data point in the dataset (where the first data point is in position 0, the second in position 1, and so on). Figure 76 illustrates these points.
Figure 76. Data point tooltips
The Active Chart legend contains details of the datasets that are present in the chart; an example can be seen in Figure 77 <ac2_user_guide_fig_77>.
Figure 77 an example chart legend - see section Active Charts
The datasets are displayed left to right, they wrap around if there is not enough room to display them all. For each dataset it includes details of:
- The dataset name - shown on the far right of the legend entry. This can be set in the dataset properties
- The dataset style - shown as a line and an example of the shape used on line and scatter charts.
- Enabled / Disabled - if the dataset is disabled then the clock icon will be shown next to the dataset.
- Interpolated - whether the dataset is currently displayed as an interpolated dataset.
- Multiplier - whether the data points that are plotted are being modified by a user defined multiplier.
- Comparison mode - if the chart is in comparison mode then all datasets that are offset (in time) show a left / right arrow.
- Value of latest data point - displays the value of the latest data point added to the dataset. The value of the dataset will have a background colour equivalent to the colour of the dataset to make it easier to match the legend items with the chart plots.
- Data source query status - displays the state of any data source queries that are currently being run that will populate the dataset with data.
In all cases icons that appear in the legend have tooltips which provide details of what they mean.
A chart is created by the following methods:
- Go to View > Active Dashboard > Active Dashboard Palette and select Active Chart.
- By right-clicking on a component (of a type which can be plotted) in another Active Console view and selecting 'Show Chart ► New Chart' (or 'History Chart ► New Chart' if applicable - see section Active Charts for further information on History Charts).
- Drag and drop the data items into the Active Dashboard and select Active Chart in the Widget section.
All of these methods are illustrated in Figure 78.
Note: You can drag and drop multiple data items into a chart by holding down control while selecting them, and keeping the control key held down while you drag into the dashboard.
Figure 78. Creating new charts from a data view
Additional datasets can be configured on existing charts by using one of the following methods:
- Right-clicking on a managed variable in a metrics view and selecting the 'Show Chart' menu (or 'History Chart' menu if applicable) and then the specific chart you want to add it to (which are identified by their title).
- Dragging and dropping a data item onto an existing chart and selecting the Active Chart dataset tool (or a History Chart dataset tool if applicable) from the Tools & Modifiers dialog which appears.
It will appear and plot on the chart along with any existing datasets.
Both of these methods are illustrated in Figure 79.
Note: You can drop many additional items into a chart by holding down control during the selection and drag operation
Figure 79. Adding a data item to an existing chart
A Breach Predictor chart can be added as a normal chart is added above:
- Using the Breach Predictor tool from the Active Dashboard Palette
- By right-clicking on a component (of a type which can be plotted as a Breach Prediction chart) and selected Breach prediction
- By dragging and dropping a data item onto the dashboard and selecting the New Breach Prediction tool from the Tools & Modifiers dialog which appears.
These options are displayed in Figure 80.
Figure 80. Breach Predictor Menu
A Time Series can be plotted as below.
- By right-clicking on a Gateway and selecting 'Time Series ► New Chart'
- By dragging and dropping a Gateway onto the dashboard and selecting the New Time Series tool from the Tools & Modifiers dialog which appears
See Figure 81 below.
Figure 81. Plotting a Time Series
Having selected one of the above options, the following dialog will be presented.
Figure 82. Select a Time Series
To add a Time Series to a Breach Prediction chart the following options are available.
- By right-clicking on a Gateway and selecting 'Time Series ► <select chart>'
- By dragging and dropping a Gateway onto the dashboard and selecting the Time Series on existing chart tool from the Tools & Modifiers dialog which appears
See Figure 83 below.
Figure 83. Add Time Series to existing chart
As before, Figure 82 will be displayed upon following either of the two options above.
To remove a chart select it and press the delete key, or use the right-click 'Delete' menu item.
To remove a chart dataset, use the 'Active Chart ► Datasets ► <Selected dataset> ► Remove data set' menu item. Alternatively, you can right-click directly on the dataset (in the legend or on the chart) to access the remove function.
Charts will update automatically over time as the attributes of the data items they are displaying change. An update will occur each time the value changes. As a rule this will be defined by the sampling rate of the managed variable they are plotting.
By default, charts will not update unless the value they are plotting changes. However, you can configure a chart to 'Constantly tick', which means that regardless of whether updates have occurred they will update each 5 seconds. This setting is configured in the chart settings. The 'Constantly Tick' function does not preclude updates when the plotted value changes, thus when 'Constantly Tick' is enabled a dataset may update more often than every 5 seconds because the value is changing.
You can disable updates by right-clicking on the selected dataset in the legend and clicking on the 'Enabled' menu item. If this is ticked then the dataset will update over time; otherwise it will remain unchanged.
Note: You cannot retrospectively recover the missed data. A disabled dataset will be shown with a clock icon in the legend.
You can access the raw data that is displayed in a chart in a tabular view, accessible via the right-click menu on the chart. An example of this view is displayed in Figure 11
In the left of the tabular view is a list of all the datasets displayed in the chart. If you select a dataset, its data points will be displayed in the lower right list, while its point values will be displayed in the upper right hand list. Both these lists can be sorted and their columns reordered. This can be useful for analysing the data for large or unusual values.
You can select multiple datasets at the same time by holding down the control key while selecting datasets. In this case the data point and point value lists will contain a combined set of values across all selected datasets.
The data in this view is read only; it cannot be modified in any way.
To configure a chart (beyond what is simply plotted on it) you need to open the Active Chart properties dialog (available via the right-click menu), an example of which is shown in Figure 86. You navigate around this dialog via the icons on the left, which reconfigures the area on the right. The top item (labelled 'Chart Properties') configures the general aspects and axes, while the remaining navigation icons allow you to configure further aspects, including the display aspects of specific datasets.
Figure 86. The Chart Properties dialog
A default font size is applied to X and Y axis labels on Active Charts. To modify this, go to the Chart Properties of the chart.
- Right-click the Active Chart.
- Click Properties.
- In the Chart Properties section, enter the font size value in the Axis Font Size field.
- Click Apply to preview the changes.
- Click OK to save the changes.
Simple settings, such as visibility of the title, the actual heading text, and the visibility of the legend and the grid (the horizontal lines displayed in the plot area) are configured here, as well as more complex settings such as the bounds on the axis. The less obvious settings are covered in more detail in the remainder of this section.
By default the X and Y axes will automatically scale to appropriate values for the data plotted on the chart. However you can if you wish override these defaults with hard coded values. The lower and upper Y bounds should be set using number values. You can also control the maximum number of labels displayed on the Y axis by setting 'Max labels' - if this field is set to 0, then there is no maximum. If you want to override one of the X values (Start and End dates) then you must explicitly tick that you are overriding it, and then set the selected date. See section Active Charts for more information on the manipulation of the axis.
The pixel width of the Y axis (left and right) and the height of the X Axis are both configurable; they will not automatically scale as values of the axis change. Settings these values to 0 will completely hide the axis.
By Default the X-Axis will display suitable labels for the data on the chart. For example if the displayed data covers an hour then the scale will plot the time of day; if the data ranges over a number of days then the date will also be shown in addition to the time and so on.
You can if you wish override the format of these dates and times using the Time Format property on the chart properties dialog. For guidance on the values that can be set for this property, see section Date Format Strings on Date Format Strings.
You can control the format of the numbers displayed on the Y-Axis. The pattern used to specify the format is as defined for the Java DecimalFormat Class.
The default value in this field is "#0.##########". The meanings of the characters in this string are:
# - This symbol shows a digit, or nothing if no digit is present
0 - This symbol shows a digit, or "0" if no digit is present
. - This symbol shows the decimal point
So, the effect of the default pattern of "#0.##########" is to take any value with greater than 10 decimal places and round it to 10 decimal places (because there are ten #'s after the decimal point in the pattern). If the value contains no digits in front of the decimal point, then a single "0" is displayed before the decimal point (because of the "0" in the pattern). Apart from that, all digits and the decimal point in the value are displayed. So, for example, a value of ".000123456789" would be displayed as "0.0001234568".
One of the most common things that you might want to do is to force all the values displayed on the axis to be rounded to a whole number. This can be achieved by setting the pattern to
"#". The full range of patterns that can be used in this field is powerful but also complex. For more information, see section Number Format Strings on Number Format Strings.
This means that all the datasets on the chart will update every 5 seconds regardless of whether the items they are plotting are updating. See section Active Charts for more information.
This property determines the oldest data point that should be displayed on the chart, i.e. if this value is set to 1 hour then data points older than 1 hour will not be displayed. You can use this property to create a rolling tick chart that only displays the most up to date data.
Note: The older data points are not lost; you can always access them by setting the maximum displayed data to a longer period or by defining a set start date for the chart, an action which overrides the maximum displayed time setting.
Maximum time data is retained
This property determines at what point data should be removed from the chart. For example, a value of 1 hour in this field means that all data points that occurred more than 1 hour before the current time will be removed from the dataset. You cannot recover these data points. This is useful if you are no longer interested in old data and you do not want to suffer the memory overhead of retaining an ever growing dataset. By default this value is set to 24 hours worth of data.
The colours of the chart are configured via the 'Chart Colours' section. Figure 86 shows you how to reach these settings from the chart properties dialogue. Figure 87 illustrates the areas that can be configured. Choosing 'None' for a colour will make that component transparent.
Figure 87. Areas of charts that can have their colours configured
For the plot area and axis area, you can set gradient colours (so the colour displayed will fade from the main choice of colour to the gradient colour across the area filled in).
If you want to set the same colour (including any gradient colour) for the plot area and the axis area, then you should set the plot area colour to 'None' and set the axis colour as required.
Note: This section does not allow you to define the colours of the datasets. These are configured under the relevant dataset sections.
Active Charts will continue to tick as long as Active Console and the Netprobe from which the data is coming are running. A chart will never remove data from its datasets unless the user tells it to, thus over time the datasets will get bigger and bigger, containing days or even weeks, months or years worth of data. There are some practical limitations on how many points a chart can display at any given point in time (from both a performance and visibility stand point) and this is the reason for the interpolation function.
If the number of data points you are asking the chart to plot exceeds a given value (which defaults to 500 per dataset) it will interpolate the dataset, reducing the number to its target number for display (which defaults to 250 per dataset), choosing to plot the most significant points from those available. It does this by 'hiding' (not removing) data points that have a similar (or the same) value to the previous point. In this way the chart will look essentially the same but data points which had little variance to their neighbouring data points will be invisible. For the chart properties used to configure interpolation.
You can turn interpolation off if you wish but in this case you should expect the charting routines to become more expensive from a CPU standpoint. If your dataset has over 10,000 data points and you ask it to plot them all then this could actually lock the Active Console.
Multiplying the values in datasets
You can define a multiplier on a dataset, all data points will be multiplied by the specified value. The multiplier can be any number to as many decimal places as you require. This is useful for comparing datasets whose values are exponentially different. If a dataset has a multiplier applied a symbol will appear next to it in the legend.
Controls which affect all datasets can be configured by selecting 'All Datasets' in the left navigation pane of the configuration dialog.
If there is more than one dataset, the 'Connection Configuration' controls will not be shown, otherwise the same controls will be shown as clicking on the specific dataset icon. The effect of each control is discussed in the next section.
Using one of the Aesthetic Configuration controls will cause this property of all the datasets to be the same. This is more useful for some controls than for others.
Configuring specific datasets
A specific dataset can be configured by selecting it from among the icons in the left navigation pane of the configuration dialog.
You can also define the look and feel of the chart sets by defining:
- Display Name - the name that appears in the legend and tooltips for the dataset. By default this will be the user definable path (see section Referencing Components via Paths) for the plotted item.
- Path - the Geneos Path to the data item being plotted. This can be altered via the 'Edit...' button alongside it, which launches the Path Editor.
- Plotted Attribute - the attribute from the data item being plotted. In the vast majority of cases this will be 'Value'.
- Graph Type - which can be a line, area, bar, step chart or scatter plot.
- Line Thickness - the width of the line / border (in pixels).
- Line Style - the style of the line, which can be solid or dashed.
- Display Points on Line charts - defines whether data points (square, triangle, circle etc.) should be plotted on a line chart (or whether just the line should be shown).
- Visibility on graph - defines whether the dataset is visible on the chart. If it is not then it will not contribute its values when the axes auto-calculate their bounds.
- Enabled - defines whether the dataset is enabled or not. If the dataset is disabled, then the chart will not be updated for this data source. You cannot retrieve any data missed, while the dataset is disabled.
- Fill Transparency - defines the transparency of the plot, which can be 100% (completely invisible), to 0% (opaque).
- Line Transparency - defines the transparency of the line / border, which can be 100% (completely invisible), to 0% (opaque).
- Data Set Colour - defines the colour of the dataset when plotted on the chart. A unique colour will be generated automatically, but you are free to change it.
- Interpolate - defines whether the displayed dataset is interpolated or not. See section Active Charts for more information on Interpolation.
- Target displayed data points - the number of data points the dataset should contain after an interpolation.
- Maximum Displayed data points - if the number of data points exceeds this value then the dataset will interpolate .
- Multiplier - a value by which all the data point values will be multiplied; i.e. a value of 2 would double the plotted data point values.
You can define a multiplier on a dataset, all data points are multiplied by the specified value.
The multiplier can be any number to as many decimal places as you require.
This is useful for comparing datasets whose values are exponentially different. If a dataset has a multiplier applied a symbol will appear next to it in the legend.
Target Marker allows you to visualise threshold markers and values in Active Charts.
The conversion of the selected dataset into a horizontal line or marker in Active Chart is based on its cell value from the metrics dataview.
The sample Active Chart above has three cell values used from the metrics dataview:
Each dataset has its own colour legend that you can also modify in the Object Attributes properties.
In the example, the dataset for
percentUtilisation has been converted into a target marker.
To convert a dataset into a target marker, follow these steps:
- Go to Active Console > View > Active Dashboards.
- Drag and drop the metrics dataview values on the ActiveDashboard tab.
- Select Active Chart in the Tools & Modifiers screen.
- Click OK.
- Select the dataset you want to convert in the Active Chart.
- Right-click the Active Chart and click Properties.
- Go to the Dataset tab.
- Select the Graph Type menu in the Aesthetic Configuration group.
- Select the Target Marker option.
- Click Apply to implement the changes.
- Click OK to close the screen.
Note: There is no limit to the number of datasets you can convert into target markers. One dataset conversion becomes one target marker in Active Chart.
The datasets will be plotted with the items at the top of the legend being in front of the items at the bottom of the legend. You can move a dataset to the front by right-clicking on it (in the legend or plot area) and selecting 'Move to Front of Graph'.
Active Charts have a special mode which allows datasets from different time periods to be directly overlaid on the same chart. For example data from 'yesterday between 2-4pm' can be plotted over the top of data from 2-4pm today. This is called the Comparison Mode.
You can turn on the comparison mode via the Active Chart properties, or using the right-click 'Active Chart' menu. The start date of all datasets will revert to:
- The user defined start date
- OR, if this is not defined, the start date of the oldest dataset
Datasets whose time data is now offset will have an indicator in the legend (a green left right arrow) to indicate that their time data has been modified.
You can turn off the comparison mode via the same controls that turned it on.
You can pan and zoom around the data that an Active Chart contains. There are two main ways to achieve this:
- Using the scroll bars on the chart
- Entering hard values into the Active Chart properties dialog
Note: Before discussing these methods, the start date, end date, and lower and upper Y scale values are automatically configured by an Active Chart over time to best display the data contained in the chart's datasets.
Once you start panning and zooming you essentially override these automatic mechanisms with your own hard coded values. It is of course possible to revert to the chart defaults, this will also be discussed in the following sections.
Note: You can remove all 'Zoom locks' (places where you have overridden the chart default axis values) by using the right-click 'Active Chart > Remove Zoom Locks' function.
The Active Chart has two scroll bars, a horizontal one, which allows you to pan and zoom over time, and a vertical scroll bar which allows you to zoom in on specific value ranges. Figure 88 shows an example of the scroll bars.
Figure 88. Panning and zooming on chart data
A scroll bar has three main features:
- The scroll bar itself, which is the blue part between the start and end pointers.
- The start pointer, which is the block type arrow at the left and bottom and the two scroll bars respectively.
- The end pointer, which is the block type arrow at the right and top and the two scroll bars respectively.
The start and end pointer can be moved to change the start and end of the plot range respectively, be it the X axis (time) or the Y values. Once moved, the chart's defaults for these values are replaced with your hard coded values. To show this the relevant pointer will turn from white to orange. An orange pointer means you have fixed the relevant start or end point on the X or Y axis.
Having fixed a scroll bar pointer you should be aware of two things:
- The tool tip for the pointer (and scroll bar) will detail the value at which the pointer has been set.
- The 'X' near the pointer (under for the horizontal bar, or to the left for the vertical) removes the lock and reverts the pointer to the chart defaults.
The locks are also removed if the start or end pointers are moved to their default position (which is generally at the beginning or end of the scroll bar, apart from the start Time pointer which can vary).
You can 'pan' the available data by scrolling with the scroll bar itself directly (rather than the start and end points) If you pan then you are also moving the start and end points, meaning they will become locked and change to orange.
If the start and end pointers are moved very close together then they occlude the scroll bar. So that you can still scroll, the scroll bar is moved to the side of the two pointers. See Figure 88 for an example of this situation.
You can hide the scroll bars via the chart properties if you want to.
As well as serving the important function of allowing you to move over the chart data, the scroll bars also provide a useful summary of the data in the chart, and what part of it you are looking at. This information is also provided in the tooltips for the scroll bar (available from both the pointers and the scroll bar itself).
Using the Active Chart Properties dialog, you can set the start and end X and Y axis values.
This allows you to zoom in on selected data. Figure 89 provides an example of zooming on the X and Y axis:
|Upper Y Plot Bound|
Lower Y Plot Bound
|If you leave these fields blank, the system automatically calculate their suitable bounds. You can override these fields and enter your desired bounds value.|
|Define Start Date|
Define End Date
|If you activate them, the system automatically calculate the suitable start and end dates for the X-Axis. You can override these dates to zoom in the data on the X scale.|
Figure 89. Zooming on charts
The chart can be zoomed in on the X axis by changing the start and end date that the axis plots between, these dates only effect the plot range displayed, they not influence the entry of data into the chart. To set these dates you must first check the relevant 'define start date' or 'define end date' check box, then set the date that you want the chart to start or end at.
These dates can be outside the bounds of the available data, for example you can set a start date that comes before the first available data point.
The Y axis bounds can set be set by entering numeric values into the lower and upper Y bound text boxes. These will force the chart to plot between the specified values. By default these boxes are blank, meaning the chart is left to derive the most suitable bounds for the Y Axis.
Note: If you zoom using the scroll bars then these values will be shown in the properties dialog when you open it.
When a dataset is enabled or disabled, and when the workspace is loaded or closed a threshold value will be added to the chart for each dataset. These show the user that the dataset was not plotting between the specified times. Moving the mouse over a selected threshold value will display a tooltip that explains the date and time that the event occurred.
Figure 90. Threshold event tooltips
You can create charts of data that you have previously logged to a data source (such items appear with a small database icon next to them). To log a data item property (such as the value of a managed variable) to the data source, you must have configured the relevant gateway to connect to a data source and log the item as and when the selected property changes (see section Database Connection and Active Console for more information on data source connections).
There are a number of ways that you can insert historical data into a chart:
- Drag and drop a data item (most likely a managed variable) into the dashboard and select a 'Historical Chart' (not 'Historical Chart Dataset') tool for a suitable time period from the Tools & Modifiers dialog. This will create a new chart and chart dataset to hold the results of the data source query.
- Drag a drop a data item into an existing chart, and select the 'Historical Chart Dataset' tool for a suitable time period from the Tools & Modifiers dialog. This will add a new dataset to the selected chart, which will subsequently be populated with the results of the data source query.
- Right-click on the data item, and select the History chart menu item. The sub menus will allow you to select the target chart (which can be a new chart), and the time period to get the data for.
- Supplement existing dataset with historical data. If you right-click on an existing chart dataset you will see a 'Supplement with historical data' menu item. Using this you can add historical data to an existing dataset. You can use this option to get data equal to the time range of the chart, see section Active Charts.
Whichever approach you take you will have identified a target dataset (and therefore chart) to which the historical data should be added. The dataset will display a legend indicator to show that a data source query is running to populate it with data - an example of this can be seen in Figure 91.
Figure 91. Running a data source query for a chart
The Active Console will dispatch the query to the data source to recover the data. The actual query works asynchronously, meaning the Active Console will not wait for a response and you can carry on working. At some point in the future the data source should respond with a result set, at which point the Active Console will display the recovered data in the chart you selected (which may be a new chart). The query is a command so will appear as an entry in the Command Viewer (see section Command Dockables). Figure 92 illustrates creating a history chart.
Figure 92. Creating a history Chart
When you request data for a predefined time period (hour, day, week or month), Active Console connects to the same data source of the Gateway where the data item is configured to use. You can select a different time period by using the custom time period, see section Active Charts.
If the data source query is successful, the Database legend annotation is removed.
Note: The option to use the historical chart and historical chart dataset tool is available regardless of whether the data item is currently being logged to the database. This is because the item may previously have been logged to the database, but is no longer being logged.
When populating a historical chart data using User Defined, the User Defined Parameters opens. This returns only the Database Logging connection entries.
To get historical data in Active Chart for a specific period, go to View > Active Dashboards > Active Dashboard Palette > Active Chart.
- Drag and drop the Active Chart widget in the Active Dashboard.
- Drag and drop the data you want to use from the metrics view into the Active Chart widget.
- Click Active Chart in the Tools & Modifiers screen, and then click OK.
- Right-click the populated chart and select Re-populate all charts with Historic data.
- Click User Defined.
- Click Yes in the Re-populate chart dialog.
- Fill out the fields to specify the time period, and click OK.
This confirms that your Active Chart has successfully contains historical data.
The User Defined Parameters screen appears.
|Time from||Start date and time for the data you want to recover.|
Date format: Month, date, year
Time format: Hour, minute, seconds
|Time to||End date and time for the data you want to recover.|
Date format: Month, date, year
Time format: Hour, minute, seconds
|Max results (-1 means no limit)||Maximum number of data points that must be recovered to get all the matching data.|
If more than the maximum number of data points are defined, then the older data points take precedence over the newer data points.
When you supplement an existing dataset with historical data you will have an additional time option, labelled 'Equal to chart time range'. This will attempt to recover data from the database for the period of time that the chart covers. For example if the existing chart data goes back 4 hours, then the query will attempt to get the last 4 hours' worth of data for the logged data item.
By default, when a historical dataset is imported into a chart it will be disabled (see section Active Charts for enabled / disabled datasets). You can, if you wish, enable the dataset, and assuming that the data item is connected to the Active Console, it will start to tick live data onto the end of the dataset.
You may from time to time want to plot historical data for a data item that is either no longer configured in a gateway, or in a gateway to which you no longer connect. You can achieve this by using the following steps:
- Configure the data source connection. If the Gateway is not connected and none of the existing Gateways use the same data source connection, you need to manually define the database settings in the Workspace Settings Dialog. You can skip this step if the required data source connection is already known to Active Console. The data source value can be either set to Database Logging or Gateway Hub.
- Create a new dataset. You can do this via the chart right-click menu 'Active Chart' > Add Chart Data Set'. If required, you can use the chart tool in the dashboard tools to create a new one, see section Active Charts.
- Setup the path in the dataset. Right-click on the chart and select 'Properties', then navigate to the new chart dataset and edit the 'Path' property (see section Referencing Components via Paths for help on how to use the Path Editor). You will need to define the path of the item you want the data for. At the very least you will need to define the Entity, Data view, Row, and the Cell (if it is a headline, then you can skip the Row). Figure 94 below illustrates this process.
- Recover the data. Click ok to exit all the dialogs, then right-click on the new dataset in the legend of the chart and select the 'Supplement with Historical data > User defined' menu item. In the resultant dialog select the relevant database connection, and the time period (from > to) that you want the data for. Then click ok. If you have correctly defined all the parameters (path, database, time from and to), then the data will be retrieved.
Figure 94. Recovering historical data from disconnected data items
If no data is available for the selected data item in the database then you will get error messages similar to those shown in Figure 95.
Figure 95. Errors when no data is available in the database
The database annotation display in the legend for the dataset will then have the DB icon, with error written next to it, an example of which can be seen in Figure 96. This icon will remain until another DB query is performed on the dataset.
Figure 96. Legend when no data is available in the database
Charts can be freely moved and resized in the dashboard. To move a chart press and hold down the mouse button over the chart then move the mouse. Notice that, when a chart is selected in this way, it is surrounded by a grey border with light grey squares on it at 8 compass points. These squares are known as control points. If you click and hold on these control points and move the mouse, then the chart can be resized.
The chart will do its best to fit into the space you have defined for it. Beyond a given size all its components will be visible. But once it starts getting small, parts of it will no longer be displayed due to lack of space. The legend axes (horizontal and vertical) and title will all be sacrificed one at a time as the chart gets smaller. You can of course get them back simply by making the chart bigger again.
Multiple charts can be selected and manipulated by dragging out a rectangle round the charts you want to manipulate. This is be shown by showing the borders and control points of all the selected charts. If you do this, you will not be able to move an individual chart until you click on a point in the dashboard outside of any chart border.
Charts can also be placed into their own frame (window) and manipulated independently of the dashboard; see section Active Dashboards on how to do this.
Charts can be output in a number of formats. In all these cases you will be prompted to define a location and filename to output the chart to.
- As a PNG file, the png will look identical to the current chart, including its size. PNG files are preferred over Jpegs because they support transparency, as does Active Console charting.
- As a CSV file, this will save the actual chart data in a comma separated .csv file which can be read by applications such as Excel.
- As a DBI file, this will save the chart (aesthetic and data) as a file with an .dbi (dashboard item) extension in a format which can be read back into Active Console at a later date. This is a bespoke format which is not compatible with third party applications.
Charts saved out in the DBI format can be re-loaded into Active Console at any time (it does not have to be the same Active Console in which they were saved). They are imported via the application level 'File > Import...' menu item.
If an imported chart is loaded with datasets that are enabled and refer to directory components that are active in the Active Console then they will resume ticking from the point they were imported. There will be a gap in the data in the same way as gaps are present between sessions (see section Active Charts).
CRT files are Active Console 1 Chart template files. Active Console is capable of reading these files and creating a new Active Console Active Chart from the template. To import a CRT file use the 'File > Import...' menu item. The chart will be added to the selected dashboard. Only CRT files that contain Tick charts can be read in via this function. Database CRT templates will not work.
Active Charts and their data will be saved when you shut down Active Console. They will subsequently be restored when you restart Active Console. If the components that they were plotting values for are present and active, and the dataset is enabled, they will continue to update over time as normal. However, they will not have any data for the time that Active Console was not running. As a result there will be a 'gap' in the data displayed on the charts (equal to the time it was shut down to the time it was brought back up).
As well as the standard Active Chart, there is a small minimalist chart available called a Spark Chart. You can select a Spark Chart tool instead of an Active Chart tool from the Widget group in the Active Palette. Alternatively, when dragging and dropping a data item onto the Active Dashboard, you can choose the Spark Chart tool instead of the Active Chart tool from the Tools & Modifiers dialog.
The properties for a Spark Chart are the same as those for a standard Active Chart, although you will find a different set of settings are selected by default for a Spark Chart.
You can add datasets to a Spark Chart by using the Active Chart Dataset and Historical Chart Dataset tools as for a standard Active Chart.
Figure 97 illustrates the difference between a standard Active Chart and a Spark Chart by showing exactly the same data being displayed in the two forms of chart with default settings.
Figure 97. Difference between a standard Active Chart and a Spark Chart
Active gauges are available on the Active Dashboard. A dashboard is capable of displaying multiple active gauges, each of which can display multiple data sets from different Data Items.
The value of a dataset is displayed via a 'pointer' on the active gauge. The pointer is constrained by a minimum and a maximum boundary which must be either manually assigned or left to be automatically determined over time by the active gauge itself; the latter is the default behaviour.
An example Active Gauge is shown in Figure 98.
Figure 98. Components of an Active Gauge
Active Gauge tooltips
Tooltips are available for each 'pointer' or dataset that is on the active gauge. If you move your mouse over a 'pointer' it will display the name of the dataset as a tooltip. Figure 99 illustrates this.
Figure 99. Dataset Tooltip
A gauge is created by the following methods:
- Using the Active Gauge tool from the dashboard toolbar.
- By dragging and dropping a data item onto the dashboard and selecting 'Active Gauge' from the resultant popup menu. See Figure 100.
Note: You can drag and drop multiple data items into an active gauge by holding down control while selecting them, and keeping the control key held down while you drag into the dashboard.
Figure 100. Drag & drop context menu
Additional data sets can be configured on existing Active Gauges by dragging and dropping a data item onto an existing Active Gauge and selecting the 'Active Gauge data set' tool from the resultant popup menu.
Note: You can drop many additional items into an active gauge by holding down control during the selection and drag operation.
To remove an Active Gauge, select it and press the delete key, or use the right click 'Delete' menu item.
Active Gauges will update automatically over time as the attributes of the data items they are displaying change. An update will occur each time the value changes. As a rule this will be defined by the sampling rate of the managed variable they are plotting.
To configure an Active Gauge you need to open the Active Gauge properties dialog (available via the right click menu), an example of which is shown in Figure 101. Gauge Properties. You navigate around this dialog via the icons on the left, which reconfigures the area on the right. The top item (labelled 'Gauge Settings') configures the general aspects of the Active Gauge, while the remaining navigation icons allow you to configure the display aspects of specific data sets.
Figure 101. Gauge Properties
Settings such as the visibility of the title, the position, the title itself, the visibility of the scale labels the legend and more importantly, the shape of the Active Gauge, its boundaries and segments call all be configured here.
There are two properties which affect the external shape of the active gauge; the circumference and the rotation.
The circumference always starts at 0 degrees and its end degree can be set between 45°-360° allowing for a wide range of circular shapes.
Figure 102. Circumference examples
The rotation setting allows the active gauge to be rotated between -360° - 360°. Setting a positive rotation will rotate the active gauge anti-clockwise, whilst setting a negative rotation will rotate the active gauge clockwise.
Figure 103. Rotation examples
Finally the Start/End Offset setting allows for setting an offset amount (spacing) in degrees between the start and end point of the shape. See Figure 104.
Figure 104. Offset examples
The boundaries of a active gauge can be configured in one of two ways:
- Auto-Resize Enabled: Dynamically adjusts the minimum and maximum boundary of the active gauge depending on the value of a dataset.
- Auto-Resize Disabled: The minimum and maximum boundaries are explicitly defined and do not adjust regardless of the value of a dataset.
A segment is defined by a 'Start From' and an 'End At' property. There are two ways of defining these properties; by explicit 'value' or by 'percent'. If auto-resize is enabled in the boundary settings then segments can only be defined by percent.
Defining a segment by value requires a 'start from' and an 'end at' value which coincides within the gauges minimum and maximum boundary.
For example if the minimum boundary of the active gauge is 0 and the maximum boundary of the active gauge is 500 the 'Start From' and 'End At' values must be in between these boundaries i.e. 0-200, 300-400, 0-500. The 'Start From' value must also be less than the 'End At' value.
Segments do not have to be continuous, i.e. if two segments are defined, the second segment does not have to start from where the first finished at.
If a segment is defined by percent, the minimum and maximum values must coincide between 0 and 100%. The 'Start From' value must again be less than the 'End At' value.
See Figure 105 for examples.
Figure 105. Segment examples
Another important setting for segments is the 'Start Fill' and 'End Fill' property. These properties define the thickness of the segment and are set as a percentage. The 'Start Fill' is the start percentage from the base of the active gauge and the 'End Fill' is the end percentage from the base of the active gauge.
Figure 106. Segment fill examples
General aesthetic settings of a dataset (pointer) can be set here such as the name, the fill colour, border colour, length and transparency.
The path of the data item which the data set is connected to can also be set here.
You can configure a number of colour settings in for the gauge via the Gauge colours section of its configuration dialog. Figure 107 illustrates the parts of the gauge to which these settings refer. Setting a colour to 'None' will make that component transparent.
Figure 107. The areas of a gauge whose colour can be defined
Active gauges and their data will be saved when you shut down AC. They will subsequently be restored when you restart AC.
Active Pie Charts are available on the Active Dashboard. A dashboard is capable of displaying multiple Active Pie Charts, each of which can display multiple data sets from different Data Items. The value of a dataset is represented by a 'slice' on the Active Pie Chart. An example Active Pie Chart is shown in Figure 108.
Figure 108. Active Pie Chart
Active Pie Chart Tooltips
Tooltips are available for each 'slice' or dataset that is on the Active Pie Chart. If you move your mouse over a 'slice' it will display the name of the dataset as a tooltip. Figure 109 illustrates this.
Figure 109. Slice Tooltip
An Active Pie Chart is created by the following methods:
- Go to View > Active Dashboard > Active Dashboard Palette and select Active Pie Chart.
- Drag and drop the data items into the Active Dashboard and select Active Pie Chart in the Widget section.
Note: You can drag and drop multiple data items into an Active Pie Chart by holding down control while selecting them, and keeping the control key held down while you drag into the dashboard.
To remove an Active Pie Chart, select it and press the delete key, or use the right click 'Delete' menu item.
An additional slice can be added to an existing pie chart by dragging and dropping a data item over the desired pie chart and selecting 'Active Pie Chart Dataset' from the resultant context menu. Multiple slices can be added by dragging and dropping multiple data items.
There are two ways of removing a slice form an existing pie chart:
- By right-clicking on the slice to be removed and selecting 'Active Pie Chart > Remove Slice' from the resultant context menu.
- By right-cling on the name of the slice to be removed in the Legend area and selecting 'Remove slice' from the resultant context menu.
Active Pie Charts will update automatically over time as the attributes of the data items they are displaying change. An update will occur each time the value changes. As a rule this will be defined by the sampling rate of the managed variable they are plotting.
To configure an Active Pie Chart, open the Active Pie Chart properties dialog.
The Pie Chart Settings configures the general aspects of the Pie Chart, while the remaining object attributes allow you to configure the display aspects of specific data sets.
To configure the general settings of an Active Pie Chart, go to View > Active Dashboards > Active Dashboard Palette > Active Pie Chart.
|Title||Name of the pie chart.|
|Labels||Path of the data item you selected from the metrics dataview. This displays in the centre of the pie chart.|
Example: GW / GW ME / Server name / severity / actual value
|Legend||Path of the data item you selected from the metrics dataview. This displays a panel below the pie chart.|
Example: GW / GW ME / Server name / severity / actual value
|Visual Quality||Determines the pie chart's image resolution.|
Options: High, Low
|Orientation (degrees)||Sets the starting angle position of the pie chart in a clockwise manner. This can accommodate values between 0-360 degrees.|
When a value is a negative number, it sets the pie chart orientation in a counter-clockwise manner.
General aesthetic settings of a dataset (slice) can be set here such as the name, the fill colour, border colour, and transparency.
The path of the data item which the data set is connected to can also be set here.
Active Pie Charts and their data will be saved when you shut down AC. They will subsequently be restored when you restart AC.
A dashboard is capable of creating a bar chart that can display a data set using the selected data item.
There are two ways to create a bar chart:
- Go to View > Active Dashboard > Active Dashboard Palette and select Bar Chart.
- Drag and drop the data items into the Active Dashboard and select Bar Chart in the Widget section.
Similar to other charts, such as Pie and Active charts, you can manually add multiple data items into existing bar charts.
To add multiple data items into an existing bar chart, open the dataview you want to use.
- Press CTRL + click the rows of the data items you want to use in your bar chart.
- Drag and drop the selected data items into the Active Dashboard.
- Go to the All Tools tab in the Tools & Modifiers screen.
- On the All Tools tab, click Bar Chart Dataset in the Widget section.
- Click OK.
Note: When you drag and drop data items into the Active Dashboard for the first time, the Bar Chart and Bar Chart Dataset are located on the All Tools tab in the Widget section. In an existing workspace where bar charts are used, these options are accessible on the Recently Used tab.
In this bar chart, multiple data sets are used from the plug-in's metrics dataview:
Each dataset has its own colour legend that you can also modify in the Chart Properties.
When a new workspace is created, it has a set of tools defined in Active Dashboards. These are the basic tools required to build any dashboard.
However, it is possible to create your own and import those created by other people into the dashboard palette.
This section describes how these functions work.
A new tool is easy to create. Use the normal dashboard functions and tools to create a new diagram element which you want to make a tool out of.
This diagram fragment can include shapes, groups, modifiers, and widgets, such as charts and gauges.
- To create a new tool in Active Console, click View > Active Dashboard.
- Use any existing shapes or figures from the dashboard palette to create your own new tool.
- Click the Toggle Tool Creation Mode button once your new tool is completed.
- Drag and drop the tool into the Active Dashboard Palette to edit its properties.
|Name||Name of the tool that must be unique in the workspace. This does not affect the functionality of the tool.|
|Description||Used as reference in the tooltip of the tool.|
|System tool||Determines whether the tool is a system tool. This setting is not accessible to the user.|
|Licenced||Determines whether the tool is licenced. This setting is not accessible to the user|
All tools are licenced if the user is in an evaluation period or has accepted the dashboard licence.
|Visible in toolbar||Determines whether the tool is available in the toolbar of the dashboard. If not selected, it will only be available when suitable data items are dropped into the dashboard.|
|Icon||Icon that appears in the command bar and drag-and-drop menu. It must be 22x22 pixels. If an image is selected that has a different size, it will be automatically scaled.|
Figure 110. Creating new dashboard tools
The settings that can be defined for the new tool are discussed in section User Defined Dashboard Tools. The default icon for the new tool is created by taking a snap shot of the objects that make up the tool. This can be changed via the tool properties.
Modifiers can be present on the objects that are used to make up a tool. When the tool is created they are embedded into the tool. If the tool is subsequently used during a drag and drop operation, then the path of the data item that was dropped is placed into the modifier when the tool instance is created.
So for example if you create a tool that has one object which has a modifier to change background colour based on severity, when that tool is selected as part of a drop operation it will start to update its background colour based the severity of the dropped item.
You can embed charts and gauges etc. into user defined tools, when the tool is used they will start to update based on the data item dropped into the dashboard when the tool is selected.
Importantly the configuration of the widgets is recorded in the tool. Thus if you have changed the look and feel / configuration of a chart before it is embedded into the tool then it will appear in the same configuration when the tool is used. This allows you to create new chart / gauge controls which have a different look and feel from the ones shipped with the product as standard by using user defined tools.
If a tool has 1 or more modifiers within it then it may be eligible as an option when a data item is dropped into a dashboard, see section Active Dashboards for details of dragging and dropping data items into dashboards. A tool will be eligible if the data item matches one or more of the filter paths set on the tool.
In example, if you wanted a tool to be available for all data items then you could specify a path of '//*'. If on the other hand you want to limit it to only probes then you could specify '//probe'. In the latter example the tool with show up on the drop menu only if the item being dropped was a probe. The filter paths are standard paths, which you can read more about in section Referencing Components via Paths.
User defined tools are persisted in the workspace, hence the workspace is reloaded so are the tools. If you switch workspaces the tools in the previous workspace will not be available. You can copy tools from one workspace to another by exporting and importing them, see section User Defined Dashboard Tools.
You can export user defined tools from the workspace to an .adt file. These can then be imported into other workspaces. To export a tool you can:
Via the Dashboard toolbar - right click on the tool in the dashboard tool bar and select 'export'.
Via the Active Dashboard Palette - select 1 or more tools in the dashboard palette.
Note: all selected tools will be exported to the same .adt file in this case.
To import an .adt file use the application level 'File > Import' function, or the Dashboard Palette. Imported tools will be added and subsequently saved with the current workspace. They will be available from all workspaces.
Note: The standard tools that are available in a new workspace are available in the 'UserResources\DashboardTools' directory in the AC install directory as .adt files (in case you remove them from a workspace be accident).
All paths are converted into droppeditem() paths when a tool is created in the dashboard palette through drag and drop.
During tool creation, you can link the information to a single cell or data item from the dataview.
This feature allows the tools created to automatically infer paths, so you can reuse this for similar data sets.
Each shape represents a value from the dataview.
You can display the values in the tool by selecting the cell and dragging it to their corresponding shapes.
In this example, the following columns from the dataview are displayed:
- Drag and drop the tool into the Active Dashboard Palette panel after setting the values.
- When the Tool Configuration dialog appears on the screen, enter the tool name in the Name field.
- Click OK to save the changes in the Tool Configuration.
- Select a new cell or data item to be used.
- Drag and drop the cell or data item into the Active Dashboard panel.
- The Tools & Modifiers dialog appears on the screen.
- Select the tool you have created.
- Click OK.
When you select the next data item in the targetAddress column, it will automatically get the other values that were used in the first tool created.
The Paths dockable in Active Console displays all the element paths of the Active Dashboards in your workspace.
- Path: Active Console > View > Paths
This functionality allows viewing of the element paths without manually checking each path from different active dashboards.
Each field is accessible with a double-click. This automatically opens the path location and displays a new dockable.
In the example below, the "geneos:// ac / Show Critical Alerts on cells" was opened:
The listed paths in this dockable do not automatically update.
Click the Refresh the view button that is located above the Evaluation Result column to update the set of data.
The Evaluate functionality determines expensive paths from the list. This can check how much time it takes to evaluate a particular path.
- Right-click the path field.
- Click Evaluate.
The result displays in the Evaluation Result column. By setting a rule, you can determine if the xpath value is expensive or not.
You can also use the Evaluate all button to check all the xpaths in one single click.
- The result displays N/A if the list is not an xpath or is impossible to get evaluated.
- This function ensures to refresh the paths first before evaluating them.
A path's score represents how expensive an XPath is, or how long it takes for the Active Console to evaluate the XPath.
Path scoring factors two things:
- Base score — each path is given a base score. The more elements the path contains, the more expensive it can potentially be.
- Filters — you can add a parameter or rule to a path level. Filters can improve a path's score since it reduces the number of instances of a path which needs to be evaluated.
An expensive XPath is highlighted in orange:
Xpaths that match too many data items can have consequences because the cluster may not be able to handle all the data. This can possibly reduce performance and response time of the Active Console and dashboards.
The Gateway configuration setup determines if an XPath can be expensive or not:
- If your set-up has less than two Gateways with 200 probes, having an expensive path in terms of evaluation time is high.
- If more than 20 Gateways with one running probe, then getting an expensive path is unlikely.
The AC is capable of displaying on screen notifications. When and how these notifications appear are controlled by the Notifier Manager. The Manager can be launched from the 'Tools > Notifier Manager' application level menu, or via the application toolbar. An example of a notification can be seen in Figure 112.
Note: On systems that have multiple monitors notifications will only appear on the primary screen.
The Notifier Manager can be seen in Figure 113. It has three main sections.
Figure 113. The Notifier Manager
- The General Settings section deals with the main configuration of the Notifier. These define the default settings for notifications, and details of how and when notifications should be removed.
- The Layout Settings. You can customise the layout and content of notifications, this section define the default layout for notifications, which can be overridden on a filter by filter basis (see section The Notifier).
- The Filter Table section contains a list of the filters you have defined. The filters define what changes in the connected gateways should trigger notifications. See section The Notifier for more details of filters.
The general section defines some default values for notifications (that can be overridden on a filter by filter basis), as well as details of when notifications should be removed.
When you double-click the notifications displayed in the row, cell, sampler, or dataview paths, this opens the metrics view with the corresponding Managed Entity and selected sampler.
- Notifications: This setting
decides whether notification should be displayed
- Disabled - Notifications will not be displayed by the Active Console.
- Always Enabled - Notifications will always be displayed by the Active Console.
- Enabled when Minimised - Notifications will only be displayed if the main Active Console window is minimised.
- Max Notifications: This setting decides the maximum number of displayable notifications on screen at a given time. If this is set to 0 there is no upper limit to the number of notifications that will be displayed. Otherwise the notifications will be capped by the defined number.
- Replacement Strategy: This
setting decides what to do if the maximum number
of displayable notifications is reached and a new
notification needs to be displayed.
- Oldest First - Replaces the oldest on screen notification with the new notification.
- Lowest Severity - Replaces the notification with the lowest severity with the new notification (assuming the new notification is equal or higher severity, otherwise it will not be shown). If all severities are equal then the replacement strategy will fall back to the Oldest First strategy.
- Lowest Priority - Replaces the notification with the lowest priority with the new notification (assuming the new notification has a higher priority than those that are showing, otherwise it will not be shown). For an explanation on Priorities see section The Notifier.
- Notification Location: This setting decides where on the primary screen to display the notifications.
Figure 114. Notification Location
Note: On multi-monitor setups notifications will be displayed on the 'Primary' screen.
Timeout: This setting decides how long notifications should be displayed (in seconds) on the screen before they are removed. If this setting is set to 0 notifications are never removed unless a replacement strategy forces them to be removed.
Play Sound: This setting decides whether an audible warning should be played when a notification is displayed.
Alert Sound: This setting decides whether the ActiveConsole default sound should be played or a user defined custom sound.
Default - The default ActiveConsole sound will be used.
Custom - The user selected sound will be used, these must be of a .wav format. After a sound has been selected it is retained in the workspace, there is no need to have it available on disk for the console.
Note: Not all sound files are supported; see section The Notifier for more details.
The ActiveConsole uses the Java sound system to support play back. Java Sound supports the following audio file formats: AIFF, AU and WAV. It also supports the following MIDI based song file formats: SMF type 0 (Standard MIDI File, aka .mid files), SMF type 1 and RMF.
The Java Sound engine can render 8 or 16 bit audio data, in mono or stereo, with sample rates from 8KHz to 48KHz, that might be found in streaming audio or any of the supported file formats.
These define the default layout for notifications; this includes what they contain and how they are laid out. Layouts can be overridden on a filter by filter basis.
- Default Layout: This defines whether the default layout should use the hard coded layout that comes with the AC, or a user defined layout (custom). In order to change the layout you should double click on the picture of the layout, as shown in Figure 115. See section The Notifier on how to use the layout editor.
Figure 115. Editing Layouts
Each row in the Filter Table represents a Filter; Figure 116 contains an example of this list. Each filter has a priority, name, description, layout and whether it is active or not. From this list you can create new filters, remove existing filters, or modifying existing ones. You can also directly change the active status of the filters via the setting in the far right column. Adding filters in the topic of section The Notifier, but in summary you can use the '+' button to the left of the list, the right click menu or by dragging and dropping data items into the list.
Items can be removed by selecting them then using the '-' button to the left of the list, or by right clicking the selected filter and using the 'Remove selected filter' menu item.
To edit a filter, you can double click it or use the right click 'Edit selected filter' menu item.
To change the priority of a filter, select the relevant filter then move it up (increased priority) or down (reduced priority) the list. Items at the top of the list will always take precedence over items lower down when deciding what notification to display for a gateway change.
To export a filter, right click on the filter and select "Export Selected Filter". You will be prompted to save this filter as a Notifier Filter Pack (.nfp) file. The filters in this file can then be used in another workspace by selecting File > Import, and browsing to the exported file.
Figure 116. Notifier Filter Table
Filters can be added via the plus button to the left of the list or via the right click menu, but they can also be added by dragging and dropping data items into the list from other parts of the AC. This can be useful for quickly setting up notifications for a problematic data item or one you want to closely monitor.
To create a filter for a specific data item drag the item into list, it can be inserted at any point (which will define its severity in relation to the existing filters). The new filter will show notifications for all state changes to the selected data item, unless it (or any of its ancestors) is snoozed. You may like to make this a little bit more specific (for example only show when the item is critical), in which case you can edit the filter in the normal way.
You can create a filter which will display notification for multiple data items by dragging and dropping many items at the same time. In this case a single filter with a path per item dropped will be created.
You can also create a filter for a specific data item by right clicking on the data item and selecting the 'Create Notifier Filter' menu item.
You can also drag View Path entries from the state tree into the Notifier to create more general filters (for example a filter for all entities in the UK). See section State Tree Dockable for more details on the state tree and view path.
Before describing how Notification filters are configured it is important to understand what they are and how they lead to notifications appearing on your screen from the AC. Figure 117 provides a high level overview of the process by which changes in a gateway state end up on your screen as notifications
Figure 117. How notifications appear
Over time the attributes of data items in the gateway change, new items are added and some are removed, when this occurs the Active Console is informed. It tells the Notifier (and many other components) about these changes. The Notifier then runs the data item that caused the change past the paths configured on the filters. If a path on a filter matches then a notification is displayed using the data items details in the style defined by the filter. Once a path on a filter has matched, the remainder of the filters are ignored and no further notifications will be displayed. This is why priority is important. Higher priority filters will always be evaluated before lower priority filters. Therefore if a data item matches to paths on multiple filters the only the first will be used to display the notification.
If no paths match (on any of the filters) then no notifications will be displayed.
Filters are configured using the Filter Configuration dialog which is divided into four sections. Figure 118 shows an example of the Filter configuration dialog.
The Status section defines whether the filter is active or not. Inactive filters will not create notifications.
The General Settings section defines settings such as its name, description, and whether to override the manager level sounds and time out settings.
The Layout Settings section shows the content and layout of the notifications created by the filter. This can either by the default (defined by the manager), or a custom layout.
The Paths section contains a list of paths (see section Referencing Components via Paths) which define what changes to the connected gateway(s) should trigger notifications to be displayed using this filter.
The list on the right allows you to select what type of events on the specified paths the notification reacts to. Multiple events can be selected by holding the Control key and clicking the desired event types.
Figure 118. Filter Configuration
The General Settings section defines settings such as its name, description, and whether to override the manager level sounds and time out settings.
Name - the name of the filter, this setting is purely cosmetic and exists as a user friendly way to distinguish between filters.
Description - available as a field that can be added to the notification layout, meaning all notifications generated by this filter can contain this description, it's also used in the Filter list to provide a bit more information than the name of the filter. The description will be generated automatically when the filter is created. It can be overridden by selected manual for the description field.
Sound - decides whether to use the sound defined in the Notifier Manager window or to override it with a custom sound for this specific filter. If a custom sound is defined it is saved in the workspace, it will not need the .wav file you selected it.
Note: Not all sound files are supported; see section The Notifier for more details.
Timeout - decides whether to use the timeout value defined in the Notifier Manager or to override it with a custom timeout for this specific filter.
By default when notifications are created by a filter they will use the layout defined in the Notifier Manager. However you can create a custom layout for the filter via the layout settings. To do this set the layout to 'Custom' and double click on the layout picture, you can then use the layout editor (see section The Notifier) to create the custom layout.
This list allows you to specify the paths that are used to decide whether to display a notification or not, see section The Notifier for more details on filter paths and section for defining paths in general.
You can add paths by using the plus button to the left of the list, and remove them by selecting the relevant path and pressing then delete button. To edit a path double click it or select edit from the drop down box. See section Referencing Components via Paths for full details of the path editor.
The properties list lets you select what events will trigger the notification to be displayed. Multiple events can be selected by holding the control key and clicking the relevant events.
The Notification Layout Editor is used to configure the layout of notifications. It is divided into two main sections: the editor on the north and the properties panel in the south.
Figure 119. Notification Layout Editor
The editor is used to configure the content and layout of a notification as well as its aesthetic properties.
A Notification is made up of a notification container and a set of notification elements.
Figure 120. Container & Elements
The Container represents the frame of the actual notification. The elements are placeholders for the information that should be displayed by the notification.
The amount of information displayed can be controlled by moving elements inside or outside of the container. When elements are inside the container they can be selected by clicking on the placeholder text or their borders. Clicking elsewhere inside the element boundary will select the container.
To highlight that an element will not be displayed by a notification, the editor automatically changes the background colour of the element to red - the background colour is restored if the element is moved back inside the container.
Both the container and the elements can be sized and shaped freely.
|Editor View||Actual Notification|
Figure 121. View Comparison
A particular element's properties can be changed by right clicking on it and selecting "Properties". A dialog similar to that shown for Dashboard objects is shown.
The Properties dialog allows you to configure:
- Whether a label is displayed for the element, and it's text
- The font properties of the element
- The text alignment of the element
- The size of the element
- The fill and border colours of the element
Figure 122. Element Properties Dialog
It is also possible to link the background fill colour of the container to the Severity colour of the data item which triggered the notification. For this happen, the "Background linked to severity" checkbox in the container's Properties dialog must be checked. If this is not checked, it is possible to set your own colour for the background of the container. It is always possible to change the border colour of the container.
There are several ways that you can control the layout and arrangement of elements. These are all accessed by right clicking on an element or group of elements.
- Snap to Grid - determines whether the container and elements should snap to grid while you are moving and resizing them. This can also be accessed by right clicking on the Layout Editor background.
- Arrange > Group - if multiple elements are selected, it groups them to make them behave as one object when moved and resized.
- Arrange > Ungroup - if a grouped element is selected, it ungroups them to make them behave as individual elements when moved or resized.
- Arrange > Move to Front - makes the currently selected elements appear in front of all other elements.
- Arrange > Move to Back - makes the currently selected elements appear behind all other elements.
- Arrange > Align Left/Right - aligns the selected elements to the furthest left or right edge of all selected elements.
- Arrange > Align Center - aligns the selected elements to the center of the positions (horizontally) of the selected elements.
- Arrange > Align Top/Bottom - aligns the selected elements to the furthest top or bottom edge of all selected elements.
- Arrange > Align Middle - aligns the selected elements to the middle of the positions (vertically) of the selected elements.
- Arrange > Distribute Horizontally - allows you to specify the horizontal gap between selected elements.
- Arrange > Distribute Vertically - allows you to specify the vertical gap between selected elements.
When a notification is displayed it is possible to interact with it in the following ways:
- Left Clicking on the description or path will bring up the Active Console.
- Right-Clicking on the description or path of the notification will open a context menu with options and functions that are relevant to the data item which triggered the notification.
- Clicking on the 'Menu' button on the notification will display a drop down menu which will allow the user to clear all on screen notifications or close the notification being displayed.
- Clicking on the 'Close' button on the notification will simply close the notification.
AC has a single Command viewer which displays a list of the recent and currently executing commands. Figure 123 provides an example of the Command viewer.
Figure 123. The Command viewer
|Name||Recent command list.|
|Source||Source location where the command is executed in Gateway.|
|Target||List of the target (data item).|
|State||Current status of each command list.|
|Output||Displays the Gateway where the command is executed.|
|Result description||Details of the result.|
Each command is displayed with its current status, the target it was run on, the first line of its output (if applicable, note this may be blank if the first line is an empty string) and a description of its result. The current status of a command will be one of the following values:
- Running - the command is currently running on the selected target.
- Target down - the target of the command is down or not accessible.
- Cancelled - the command has been cancelled by the user.
- Partially complete - the command is running on the target and is receiving output, but has not yet completed.
- Complete - the command has completed.
- Error - the command encountered an error and could not complete.
Any command run during an AC session will be added to the command viewer. Almost all commands are accessible from selected data items via their right click menu and are identified by an arrow icon (Figure 124 provides an example of this).
Figure 124. Running a command
Functions are available from the command viewer right click menu to remove all completed commands (including a function to automatically remove completed commands). If a command generates output then it will be accessible via the output viewer (see section Output Dockable). Double clicking on the command will automatically open the output viewer at the relevant tab.
The Auto clear function
The command viewer has an auto clear function (which is accessible via the right click menu on the viewer). If this is toggled on, then all commands that have no output will be automatically removed from the command viewer when they complete.
If multiple items have been selected, then the available commands in the right click menu will be appropriate for, and run on, all the items. For example if you select 4 entities, and then right click and the snooze command is available, selecting it will snooze all 4 items
The Output viewer will display the results of commands which generate output. The output of each command will be displayed in its own output tab, which in turn is selectable along the top edge of the output viewer.
Figure 125. The output viewer
The content of an output view is read only, but you can copy text out of the window by selecting the relevant parts and using the right click menu or standard OS short cut keys for copy. You can also export the contents of an output view to a suitable format (defined by the output itself, i.e. HTML, plain text and so on) to a file by right clicking and selecting the 'Save as …' menu option.
The Reporting Component allows the user to schedule queries which take snapshots of the system state, and output these snapshots as a report to disk or as the contents of the search view.
The reporting component can be brought up in the following ways:
- Via the Tools > Reporting menu on the menu bar
- Via the reporting button on the toolbar, see section Active Console Overview
- By pressing CTRL + R anywhere in the application
This brings up a dialog in which the user can edit existing queries or define new ones i.e.
A query is represented by a single row in the Reports table shown above, where each cell in a row represents a configurable aspect of a query. These aspects are described in further detail below. When you select a query in the table, the Report Setting dialog box appears where you can configure the Search Criteria, Results Destination and Reports Schedule. Clicking on the Name cell allows you to enter/edit the name of the query.
The user should provide a meaningful name for the query. Whilst it is helpful to ensure names are unique, this is not a requirement. Figure 126 shows the names for 2 separate queries which helpfully describe what data items will be captured by them.
Figure 126. Configuring the reporting component
If this is checked , then the query will be executed when its trigger time is reached. If it is not checked , then the query will not be fired when the trigger time is reached. In both cases, however, the queries will be persisted between AC sessions. The fragment below shows that whilst the first query will be executed when its trigger time is reached, the second query will not be executed at all.
The user can specify the criteria to be used for the query by double-clicking the row in the Reports table, or right-click the row and choose "Edit Selected Report''; This brings up the dialog below which allows the user to select the data items, severities and other attributes which need to be satisfied for inclusion into the generated report. You can do enter either in Basic or Advanced search criteria.
The output of a query can be either a report on disk, or the search view component. Choosing Results Destination on the left portion of the dialogue box allows you to specify the delimiter to use, the file name to use and whether the date should be appended to the end of the name of the file (to make it unique). If the user prefers that the output from the query appear in the Search View, they can select the Active Console Destination.
Active Console Destination
The user can configure the triggering of the query using a number of possible options e.g. hourly, daily, weekly and monthly. The diagram below shows the dialog as configured for a weekly schedule:
As a user you can configure the Dockable frames that exist in a given workspace. This includes, adding new frames, and editing and removing existing ones. These functions are performed via the Dockable Manager, which can be accessed via the application level view menu. An example of the manager is shown in Figure 127.
Figure 127. Dockable Manager
The first and most important aspect of configuring the dockables is that there are three types:
- System(Yellow background)
- Workspace(White background)
- Remote(Light Blue background)
These dockables are inserted automatically by the application into a workspace. New system dockables can not be added or existing ones can not be removed. System dockables are 'read-only' - properties like name, icon and type can not be changed. Any given workspace will always have these dockables. The close action of system dockables is only influenced by the 'Frames Hideable' setting available in the 'Advanced' section of the ActiveConsole settings (see section Workspace Settings Dialog).
The following are system dockables:
- State Tree
- Gateways View
- Event Ticker
- Output Viewer
- Metrics view
- Search View
- Command Viewer
- Active Dashboard Palette
Because system dockables are not configurable you can if you wish hide them using the tick box in the lower left of the dockable manager (so that you can focus on the locally defined dockables). The state of this tick box is persisted across AC sessions in the workspace.
Note: Ticking this checkbox does not remove them from the workspace; it just means they will not appear in the dockable manager.
Any changes that you make to the dockable manager will not be applied until you have clicked Apply or OK. If you cancel the changes then the dockables in the workspace will not be reconfigured.
These dockables are added and removed from the workspace by the user. There can be any number of these in a workspace. Icon, name, type and close action are properties that are applicable to a workspace dockable and can be configured by the user.
Locally defined dockables are limited to the following type(s):
- Active Dashboard
- List View
- Metrics view
These dockables are fetched from a remote location specified by the user. The close action is always set to 'hide on close'. The icon and type can not be configured by the user as these two properties are retrieved from the remote dockable.
Valid remote locations are:
- Local file system
- Remote file system / UNC Shares
- HTTP Url
The fetched remote dockable is not persisted in the local workspace, only the given name and reference to the location is. Therefore any changes made to the content of a remote dockable will be lost when the application is closed.
You can add new dockables via the plus button to the left of the list or by right clicking anywhere in the list and selecting 'Add New'. You will be presented with a dialog which allows you to configure the new dockable.
Dockable configuration is divided into two sections, General and Settings. The first section allows you to select the location of the dockable and to set the name. Depending on the location the contents of the Settings section will dynamically change.
Figure 128. Workspace Configuration
Workspace Dockable Configuration
- Icon - the icon for the dockable, to change the icon double click on the white box (or existing icon) and select the icon from disk. The application expects a 16x16 icon, if you provide a different sized icon it will be automatically scaled. The icon is retained in the workspace; there is no need to have it available on disk after the import.
- On close - the action that the ActiveConsole will perform when the close button is pressed on a dockable. 'Hide' will hide the dockable when the close button is pressed. The dockable can be viewed again by selecting it from the 'View' menu of the ActiveConsole. 'Remove on Close' will completely remove the dockable from the system when the close button is pressed; the dockable is not recoverable.
- Type - whether the ActiveConsole will create a new Dashboard, List view or Metrics view. Changing the type of an existing dockable will effectively remove it and add a new dockable with the specified type.
Figure 129. Remote Configuration
Remote Dockable Configuration
- Path / URI - the location of the remote dockable. You can use the browse button to locate a dockable on the local file system, mapped network drive or UNC share. A HTTP URL can be input directly.
Once you are done click OK and the new dockable will appear in the dockable manager.
Note: The dockable will not be added until OK or Apply have been pressed on the main dockable manager dialog.
If you subsequently accept the changes in the dockable manager, the new dockable will be available in the view menu.
Only workspace and remote dockables can be removed from a workspace; to do so, select the relevant dockable then click on the minus symbol to the left of the list. You can also right click on a locally defined dockable and select 'Remove'.
The dockable will be removed from the dockable manager, however it will only be removed from the workspace if you subsequently click 'OK' or 'Apply' on the dockable manager. This is why there is no confirm dialog for the initial remove.
Once a dockable is removed from the workspace it cannot be retrieved, all its state is lost.
The name, icon, close action and type of an existing workspace dockable can be changed. For remote dockables, only the name and path/uri can be changed. To do so, double click on the relevant dockable in the Dockable manager or right click and select Properties. You will be presented with the same dialog that is used for the new dockables from which you can specify the new settings.
The revised properties will only take effect once you click OK or Apply on the main Dockable manager.
You can change the order of the dockables in the dockable manager by selecting the relevant dockable then using the up and down arrows to the left of the list. The order of the dockables is reflected in the view menu (see section Active Console Overview). See Figure 130 for an example.
Figure 130. Ordering the view menu
This is useful in that dockables you use a lot can appear at the top of the view menu, or you can group them together in a predictable or convenient way.
When you create a new workspace, or load a pre-dockable manager workspace it will be configured with the following dockables:
- Probe view
- Items of interest
- Managed entity view
- Active dashboard
Workspace and remote dockables can be exported from the workspace to their own files. A Remote dockable can only be exported if it has already been successfully fetched and loaded by the ActiveConsole.
These dockables can then be imported into another workspace. To export a dockable right click on it in the dockable manager and select 'export', then select the path and file to export it to. The relevant extension will be automatically added.
You can import a dockable via the File > Import menu. See section Importing into the Workspace for more information.
There are a number of files types that can be imported into the open workspace. They are all imported via the 'File > Import' available on the top level application menu. The following files types are supported:
- Active Console Dockables (.ado) - active console dockables that have been exported from the dockable manager, see section Dockable Manager for details. They are imported as new dockables
- Metric views (.msv) - individual metrics tab that will be added to the metrics view, see section Metrics Dockable.
- Active Dashboards (.adb) - a single active dashboard that will be imported into the selected dashboard dockable, see section Active Dashboards
- Dashboard Tools (.adt) - contains one or more user defined tools for the Active dashboard, see section User Defined Dashboard Tools for more details.
- Active Dashboard components (.dbi) - a dashboard component, such as a active chart or gauge, see section Active Dashboards.
- Old AC1 Chart template files (.crt) - AC is capable of importing AC1 chart template files, see section Active Charts for more details.
- Older Active Chart Files (.acd) - an older active chart format supported in earlier versions of AC.
- Other workspaces (.aws) - will merge the contents of the specified workspace with your current workspace. Currently only the metric views and dashboards are imported.
Having imported, an item becomes part of the current workspace. It no longer requires the source file from which it was imported.
The Active Console uses a sub folder of the systems user directory to maintain its state. By default this directory is:
- Windows 2000 / XP: C:\Documents and Settings\<username>\AppData\ActiveConsole
- Vista / Windows 7: C:\Users\<username>\AppData\ActiveConsole
This user folder contains the following directories and folders:
- Folder called 'Logs': This contains all the logs generated by ActiveConsole2, including standard logging, exception logs and setup editor configuration files.
- Folder called 'wc': This is used as a temporary working directory by the console.
- configuration.acc: This is the main configuration file of the active console.
- Autosave temp files: If you have not moved the default workspace then there will be autosave files in this folder as well, see section Workspaces.
The location of the User Directory can be modified by placing a -wsp flag in the ActiveConsole.gci file (see section Start up Settings). This allows you to specify where the active console should write its configuration and logging files to.
The configuration of AC is stored in a binary workspace file with an aws extension (for Active console Work Space). It contains the following:
- The gateway connections
- The position, size and placement of all the dockable components
- The Active Charts and their data
- The configured custom views, their content and any filters you have defined (Entities, Metrics and Event Tickers)
- The configuration and layout of the data views, including which columns are displayed, their widths, and their position (relative to other columns)
The workspace you are currently using is displayed in the status bar at the bottom of the application.
The AWS extension is used for all workspaces created or used in GA2.1 or before, while from GA3.0 onwards it is an awx extension. The change was made because from GA3.0 onwards workspace configurations are saved in XML format.
Note: It is possible to force the AC to read and write in the old.aws format using a flag in the gci file. See Start Up Settings.
All exports from a workspace, for example dashboard adb files, ado files and so on remain in the older format, and are imported via the file > import menu as before.
When you start up the Active Console, you will be presented with a dialog that allows you to select the workspace that you want to use. An example of this dialog can be seen in Figure 131. This dialog presents some standard workspace options, plus a list of the last 10 workspace files that you have used. The general workspace options are as follows:
- Load last good workspace - selecting this option will load the last known good workspace (assuming the .aws file exists / is accessible).
- Create new workspace - will load the AC with a new workspace. You can override the location in which this will be created by using the .gci flags.
- Browse for a workspace ... - if you select this option you will be asked to select an .aws file from the file system to load into the AC.
- Open workspace from url ... - allows you to open a workspace that is situated on a URL. Such a workspace will be opened read only, see section Workspaces for more details on URL workspaces.
- Recovered workspace - if the AC failed to close down correctly the last time it was run and Auto save was turned on, then you will have the option to restore the last auto saved file. See section Workspaces for more information on auto saving and file recovery.
- Historical workspace - the last 10 workspace you have loaded will also be available via this dialog. Historical workspaces that are not accessible (because the file does not exist or is on an inaccessible remote drive) will be shown in light grey.
There a few additional options offered on the workspace selection dialog, which are as follows:
- Always use the last known good workspace - see section Workspaces.
- Show unavailable items - by default historical workspaces that are not accessible (because the file does not exist or is on an inaccessible remote drive) are not displayed in the workspace list. You can force them to be shown by ticking this option.
- Clean up - if there are one or more inaccessible historical workspaces then this option will be displayed. If clicked it will remove them from the workspace list.
Figure 131. The workspace selection dialog
When loading an HTTPS url using authentication for -wsurl or selected AWS file, Active Console gets the workspace from the specified path.
To access the workspace, enter your authentication information.
Auto loading the last good workspace
You can configure the Active Console to automatically load the last known good workspace each time it loads up. This can be done via the workspace selection dialog (see section Workspaces), or via the general settings (see section Workspace Settings Dialog). If you select this option you will not see the Workspace selection dialog unless there was an error the last time the active console shut down (see section Workspaces.
By default the Active Console will ask you whether you want to save the changes you have made to your workspace each time you shut down or switch to a different workspace. You can, however, force the AC to always save your changes as required via the general settings, see section Workspace Settings Dialog. Whether you choose to automatically save or manual save, if there are errors during the save operation then you will be informed (see section Workspaces.
At any time you can switch workspaces using the menu items available in the file menu (see section Active Console Overview). Switching a workspace is a simple matter of selecting the .aws workspace file. Your existing workspace will be automatically saved before the new workspace is applied (see section Workspaces if you want to avoid this).
When you switch workspaces in this fashion any gateways which are common to both workspaces will not be removed and re-added during the switch, they will remain connected throughout.
At any point you can create a new workspace, by selecting 'File ► Workspace ► New' from the top of the application. This will load and apply the read only Default workspace. The first time that you save or close AC, you will be prompted for a filename for this workspace. You can override the location that a new workspace is created in by using a .gci flag, see section Start up Settings for more information
Workspaces are not designed to be edited outside of AC. To edit a workspace open it up in AC, make the modifications and select one of the save options from 'File ► Workspace'.
If the workspace you are using becomes corrupt or you want to discard the changes that you have made then you can use the 'Revert' function in 'File ► Workspace'. This will reload the current workspace from the point at which it was last saved.
You can configure a workspace to be read only in the general settings (see section Workspace Settings Dialog). This stops the save operation from writing to the file, instead you will be prompted for a new file location if you attempt to save.
Note: While a workspace is read only, the Auto save function will not work (see section Workspaces), nor will the 'save on exit or switch workspace' option.
This function is useful if you want to ensure that the AC never writes back to the workspace, or to stop basic users from modifying their workspace. Because it is read only, no settings including window position, etc. will be remembered over Console sessions.
Workspaces can be located and opened from URLs. To open a workspace on a URL, select the relevant option from the Workspace selection dialog (see section Workspaces or from the 'File > Workspace > Open from URL' menu item. A workspace loaded from URL is opened read only (see section Workspaces for information on read only workspaces). If a user attempts to save such a workspace, a dialog will appear asking for a local save location. Be aware that, if the save occurs, you will now be using the local workspace, not the one mounted on the URL.
The URL should contain the location and the name of the .aws file, i.e: http://www.mywebsite/myworkspace.aws
You can force the AC to use a workspace mounted on a URL rather than the last known good workspace by using the -wsurl flag in the .gci file, see section Start up Settings for more details
When the Active Console loads or saves a workspace, if it encounters any errors it will present the errors to the user and ask what course of action they wish to follow. An example of a load error dialog can be seen in Figure 132, while an example of a save error dialog is in Figure 133. The listed errors have three severities:
- Critical (red exclamation mark) - serious issues which normally result in a significant loss of configuration information in the workspace.
- Warning (Yellow exclamation mark) - issues which result in the loss of some configuration information from the workspace.
- Information (blue information symbol) - minor losses of configuration that are unlikely to have a serious impact on the workspace configuration.
You can double click on an error to see more information, though this tends to be technical and of less use to normal users.
In the case of both the load and save error dialogs, you will be presented with a number of options. You must select one of these to continue. They are as follows:
Load Errors Dialog
- Load Anyway - will load the workspace normally, you have essentially ignored the errors.
- Save As a different workspace - will prompt you to select a new location to save this workspace to, choose this option to avoid any possibility of overwriting the workspace with errors that occur as a result of continuing to load this workspace.
Figure 132. Load errors dialog
Save Errors Dialog
Revert to the last known good workspace - will abandon the save, and restore the last known good workspace, all changes made to the workspace prior to the last time the good workspace was saved will be lost.
Note: If auto save is enabled, then the last known workspace may well be an auto save file.
Save anyway - will save the workspace regardless of the errors.
Save it to a different location ... - selecting this option allows you to select a different .aws to save to, rather than the current workspace location. This is useful if you want to avoid overwriting your good workspace with a bad save.
Do not save the workspace - will not save the workspace, and will then continue to shut down or load a newly selected workspace. All changes will be lost.
Abandon Save and return to the application - will stop the save operation and return to the application. This is useful if you want to try and fix the workspace by removing the offending components and configuration options before trying a new save.
You can create a diagnostic file (see section Reporting Faults and Suggesting Enhancements) directly from the error dialog which can help ITRS development staff to track down the issue that caused the load / save error.
Figure 133. The save errors dialog
The Active Console has an auto save feature which will write out temporary aws files periodically, such that it can recover after unexpected behaviour or allow you to restore an older version of your workspace in the event that it becomes corrupt. These temp files have a name equal to:
~<day of the month>.<hour>.<minute>.<sec>~~<workspace file name>.aws
Here's an example:
These files are written to the same directory as the workspace file is located in. You can configure how often they are written out and how many temp files to keep in the General settings (see section Workspace Settings Dialog, once the upper limit of temp files has been reached it will start replacing the older files.
These temp files are normal .aws files, so can be loaded in the normal way (via the file > workspace > open' menu item.
The temp files will be deleted on shutdown as long as the shutdown is successful. They will also be removed if you successfully switch workspaces.
If, for some reason, the AC fails to shut down correctly then the last auto save will be available in the workspace selection dialog as a recovered file on the next start up.
Note: If you select this, then it will be loaded, but you will now be working with the recovered auto save file rather than the original workspace that was being used when the auto save was performed. Also, even if you have the 'Auto use last known good workspace' selected, the workspace selection dialog will always be displayed if there is a recovered file.
The only configuration of AC that can be externally defined from outside the workspace is one or more files or URLs that contain a list of gateways. These files or URLs must be in a text and in the following format:
<hostname>~<port>~<description>~<Secondary Host>~<Secondary Port>~<Logon Method>~<Connection Security>
<hostname>~<port>~<description>~<Secondary Host>~<Secondary Port>~<Logon Method>~<Connection Security>
<hostname>~<port>~<description>~<Secondary Host>~<Secondary Port>~<Logon Method>~<Connection Security>
<hostname>~<port>~<description>~<Secondary Host>~<Secondary Port>~<Logon Method>~<Connection Security>…
The logon method can have the following values:
- LM_WORKSPACE, the default logon method defined in the workspace will be used. This is the default option, if you do not specify the logon type this will be used.
- LM_USER_FIRSTTIME, the user will be prompted to enter a username and password when logging onto the gateway.
- LM_SSO, SSO will be used.
The connection security is optional. It can be
completely omitted. It instructs the active console how
to connect to the gateway. Using either a secure or an
insecure channel. If it is supplied it should have a
SECURE for secure conections and
INSECURE for insecure connections. If
the value is not supplied then an insecure connection
method will be used to communicate with the gateway.
You can skip the definition of the description, secondary host, secondary port and logon methods by including a '*'. For example if your gateway does not have a secondary host, but you want to specify its logon type then use the following:
You can also exclude elements from the end of the line, for example, if you just want to specify a host and port then this will be fine:
You are allowed blank lines and comments in the file. Comments must be on their own line, and begin '//', for example:
//my gateway itrsops~4533~my gateway description //Another gateway itrsops~4534~another gateway description~*~*~ LM_SSO
Here are some further examples of a remote gateway file:
itrsops~4564~maingateway itrsops~2346~another gateway~itrsops~4564 itrsops~4533~*~*~*~LM_USER_FIRSTTIME~SECURE hostname~3456~*~secondaryhost~1200~*~LM_WORKSPACE~INSECURE
Whenever the workspace is loaded it will look for this file / URL and import the defined gateway connections. This function can be useful if there are a lot of gateways and many workspaces essentially share the same list. See section Workspace Settings Dialog for information on how to declare these imported files / URLs in a workspace.
If the gateway list is defined on a remote URL, it cannot be embedded in HTML / XML etc, it must remain in the simple format specified above.
Note: When adding remote connection files via the connection dialog, make sure that you set the connection type to 'URL' BEFORE adding the file name.
Often, where directory components are displayed in AC, they will be displayed using their qualified 'Path' attribute. The path provides a fully qualified path to the component, starting from the gateway it is contained within. For more information about paths, see the XPath User Guide. For example a specific managed variable would have a path with the following elements:
Gateway/Netprobe/Managed Entity/Sampler/Data View/Row/Cell
A Headline would have these elements in its path:
Gateway/Netprobe/Managed Entity/Sampler/Data View/Headline
A Managed entity would have these elements:
And a netprobe would look like this:
Gateway / Netprobe
Each part of the path is called an element, they are separated by '/' (or a relative path element, see section Referencing Components via Paths for more details). Each element may also have zero to many properties which are shown in brackets after the element name, examples can be seen below:
Gateway (id=00000001) / Netprobe / Managed Entity (Country = UK, OS = Windows)
In this example, the path has a gateway, netprobe and managed entity element, of which the gateway and managed entity have properties defined and shown in brackets.
If an element has its name defined, then this replaces the type of the element. For example if the name of the gateway was given, then 'Gateway' is replaced with the name of the gateway, i.e.:
MyGateway (id=00000001) / Netprobe / Managed Entity (Country = UK, OS = Windows)
This is a short hand to make the user readable paths as short as possible.
Paths can contain properties that have wild carded values, for example a path that matches all Managed entities where the 'Country' starts with 'Ldn'. These are displayed in the paths using *. Thus the previous example might look like this is a path:
Gateway/Netprobe/Managed Entity(Country = Ldn*)
This path would match to all managed entities, where they have a 'Country' attribute which starts with 'Ldn'. As well as using * to match any number of characters, ? can be used to match any one single character.
In many parts of the AC interface you will need to create paths that will be used to match against possible Data items. Examples include defining paths in Metric overviews (see section Metrics Dockable), or defining rules in the Rule Manager section of the gateway setup editor. These paths are defined using the 'Edit Path' dialog, or Path Editor.
There are, in fact, three forms of the 'Edit Path' dialog, known as the DataItem Path Editor, the Geneos URL Editor and the 'expert mode' Path Editor. The DataItem Path Editor performs basic path functionality such as defining targets for rules. An example of the DataItem Path Editor can be seen in Figure 134. The Geneos URL Editor is a more advanced version which supports some of the newer functionality of ActiveConsole. It contains tools for manipulating and creating more complex paths. It is used, for example, in conjunction with List Views. An example of the Geneos URL Editor can be seen in Figure 135. The 'expert mode' Path Editor is described in section Referencing Components via Paths; it is used when a previously entered path contains syntax which cannot be converted correctly to and from the user readable form used in the work area of the other editors.
The appropriate form of the Path Editor is launched whenever you edit the value of a dialog field (or a Gateway Setup Editor setting) which takes a path as its value. You can also specifically launch either the DataItem Path Editor or the Geneos URL Editor from the Tools > Path Editor menu item in the main application window. However, when launched in this way, the Path Editor is essentially just a scratch pad: the paths you create will not be used in any context.
Most of the functionality of the DataItem Path Editor and the Geneos URL Editor is the same. Hence all of the following information on using the 'Edit Path' dialog can be considered to be relevant to both editors except where it states otherwise. (The 'expert mode' Path Editor has a simplified user interface, shown in Figure 161.)
The Path Editor dialog includes the following main areas:
- Toolbar - contains a number of tools from which elements can be added to the path. How to use these tools is the topic of section Referencing Components via Paths.
- Work area - displays the path you are constructing or modifying. The elements that make up the path are shown from left to right. You use the work area to remove and modify existing elements.
- User Readable version of the path - an abbreviated summary of the path that will be displayed at appropriate places in the Active Console (and other parts of the Geneos framework). See section Referencing Components via Paths for more details. This field cannot be edited. You can display and hide this field via the right click menu in the work area.
- Full Path - the path that is used by the underlying system to find matches to the path. It is not shown by default, and is primarily a debugging feature. You can display it via the right click menu in the works area.
- Evaluation results - The items matched by the path you are editing will be displayed here when you click the 'Evaluate Path' button. (Whether this feature is available depends o the context from which you launched the Path Editor, see section Referencing Components via Paths for more information.)
Figure 134. The DataItem Path Editor
Figure 135. The Geneos URL Path Editor
New elements can be added to the path via the tools available in the tool bar. The following tools are available in both the DataItem Path Editor and the Geneos URL Editor, and perform the functions described:
- Any data item - will create an element that will match to any data item (where a data item can be a gateway, probe, managed entity, sampler, data view, row, headline or managed variable).
- Gateway - will create an element that will match to gateways.
- Probe - will create an element that will match to probes.
- Managed Entity - will create an element that will match to managed entities.
- Sampler - will create an element that will match to samplers.
- Dataview - will create an element that will match to data views.
- Property - will create an element which matches property values rather than data items.
- Table Cell - will create an element that will match to any cell in a data view (but not to headlines).
- Headline - will create an element that will match to any headlines (but not table cells).
- Row - will create an element that will match to any rows.
- Rows - will create an element that will match to a set of rows.
- Cell - will match to all cells and headlines in a data view.
- Client - will match a specific client (as specified in the host and port). The client is the system running Active Console. So this can be used, for example, when passing parameters to a command to be run on the client.
- Child (relative element) - the default separator, most of the time this is added (and removed) automatically as required when the path configurable is in auto-completion mode (see section Referencing Components via Paths).
- Descendants (relative element) - will match to all children of the previous element, i.e. if the previous element is a managed entity then adding this to the end of the path would match to all samplers, data views, headlines and managed variables that are contained within the entity.
- Descendants or self (relative element) - will match to the previous element and all children of that element. For example, if the previous element was an entity then adding this to the end of the path would match to all samplers, data views, headlines and managed variables that are contained within the entity, and would match the entity itself.
- Parent (relative element) - will match to the parent of the previous element. For example if the previous element was an entity then it would match the probe the entity is in.
- Ancestors (relative element) - will match all ancestors of the previous element. For example if the previous element was an entity it would match the probe and gateway the entity is in.
- Ancestor or self (relative element) - will match to the previous element and all ancestors of that element. For example, if the previous element was an entity then adding this to the end of the path would match the probe and gateway that the managed entity is in.
- This (relative element) - matches the previous element; it is primarily used to create relative paths in the rule editor.
- View Path - view path properties are actually managed entity attributes. So this tool will create a managed entity element, and then bring up the properties for that element so you can change the view path settings. It is present for convenience, since these properties can also be accessed via a managed entity element.
The following tools are available only in the Geneos URL Editor, and perform the functions described:
- Last Element - used when creating Append, Merge and Replace to tell the system which elements to modify. Last Element causes the Append, Merge or Replace to be applied to the last element in the preceding path only.
- All Elements - used when creating Append, Merge and Replace to tell the system which elements to modify. All Elements causes the Append, Merge or Replace to be applied to the last element in the preceding path only.
- Component - a reference to a main Geneos component, e.g. ActiveConsole.
- Dockable - a reference to a dockable.
- Tab - a reference to a tab within a dockable.
- Accessor - the property or function to invoke on items matching the URL.
- Dropped Item - represents an item dragged and dropped by the user, this will be replaced by the dropped item's path.
- User Selection - represents the last item selected by the user (that passes the filter specified in its properties).
- Merge - used to merge a data item path with another path, elements and predicates in the merge supersede elements in the source path.
- Replace - used to replace elements of a source path with this path, these elements will completely replace the source path elements.
- Append - will append the specified path onto the end of the source path.
- WWW Page - set the URL to a World Wide Web page.
Tools that appear greyed out have no valid insertion points in the current path (i.e. there are no sensible places to add an element of the specified type to the existing path).
You can add elements to a path by performing the following steps (which are illustrated in Figure 136):
- Press and hold down the mouse over the selected tool. Modification points will appear in the Work area where it is appropriate to add an instance of the specified element. If the modification points are for points in the path that are off screen then they will be shown pointing to the left or right edges of the dialog. In these cases drag the tool instance over the modification point to scroll the screen. If no points appear then are no suitable places for the element to be inserted.
- Drag the tool instance to the relevant modification point then release the mouse button, this will add an instance of the tool to the path.
An example of this operation can be seen in Figure 136.
Figure 136. Creating a path element
If no modification points appear when the tool is selected then there are no suitable points to insert an element of the specified type into the current path.
Note: The only exception to the rule which says you must drop in a modification point is if the path has no elements, in which case you can drop the tool anywhere in the work area.
By default the path configurable provides you with as much help as possible to create paths that will match data items in your system. It does this by Auto completing the path after each element is added and removed. For example if you add a sampler to an empty path then it fully qualifies it from the gateway automatically. The following actions are performed during auto complete:
- A child element cannot follow another child element or relative element. The second child element will be automatically removed.
- Insert child elements between non-relative elements, if there are two non-relative path elements together then a child element will be automatically inserted between them.
- Remove last element if child, the path cannot end in a child element, if this is the case it is removed automatically.
- Complete fully qualified path, if a non-relative element is dragged into an empty path, the path will become fully qualified.
You can turn off the auto-complete feature via the right click menu from the work area. By doing so you can insert any element at any point in the path, this is available for expert users.
You can edit the properties of an element in the path by moving your mouse over it and clicking the edit button. You can also access the properties by double clicking on the element or via right click menu on the element. Figure 137 shows the dialog that appears and the effect once you have defined a number of property settings.
Figure 137. Editing path element properties
The properties dialog lists all the attributes of the selected element that you can define in a path (and therefore match to). To change a property you can:
- Select a value from the drop down list in the relevant value cell, or
- Type a value directly in, when using this mechanism you can use, where required, the special characters, see section Referencing Components via Paths.
The list of possible values (which is the contents of the drop down list in a given property) is derived from any sources available to the path configurable. This will depend of the gateways you are connected to, or any setups you are editing. By default the possible values will be limited by the other selections you have made in the path. For example if you are editing a managed entities properties, and you have already selected the name of a probe in the previous probe element, then the choice of managed entity name will be limited to those available on the specified probe.
You can remove this restriction via the right click menu in the Work area by un-ticking the 'Restrict property values on path' menu item. Then all possible values for any given property will also be available to you.
It is possible to clear all the properties set on an element without going via the Properties viewer, to do this right click on the selected element and select the 'Clear properties' menu item.
There are some special characters you can use when entering values into the properties fields, they are as follows:
Wildcard ( * ) - if one or more '*' or '?' are inserted into value then they will be treated as wild cards. '*' will match to any string, while '?' will match any single character.
Contains ( * … *) - if '*' is inserted at the beginning and end of the value then it will be treated as Contains, i.e. the value must contain the string between the stars.
Not ( ! … ) if the field starts with an exclamation mark then the test is negated. This works with values, wildcards and contains. ie !*ABA* means that the value must not contain ABA
Operator <, >, >=, <=, != - by default the property must be equal to the value to match. However you can alter this by preceding the value with a suitable mathematical operator.
Note: This will only work with numeric values, i.e. cases where the value is a number, such as >4, or !=3400.
It is relevant here to note that severities map to numeric values in the underlying system:
This means that if you want to enter a value into a severity property like 'Warning or Critical' you can enter '>1'.
Some elements allow you to add additional user defined properties. Where this is the case, an additional 'Add Property' button will be available in the properties dialog - see Figure 138 for an example. When using this function you will be asked to provide a name (and possibly a type) for the property if more than one type can be added. After it is configured you can give it a value as normal.
The elements that allow user defined properties and the type of these properties is hard wired into the product.
The new properties will only persist if you provide them with values, if you leave them blank, then they will not be available next time you open the path editor. Additional properties will only be available on the path into which they have been added, not all paths in the system.
To remove an element from the path, click the 'X' button in its top right hand corner. If auto completion is on the path will adjust for the removal of the item.
Note: If an element is required in the path then no X will be available. If you know what you are doing and really want to remove it then switch off auto completion (see section Referencing Components via Paths), and the X will be made available.
You can remove all elements by right clicking in the work area and selecting the 'Clear Path' menu item. You will be prompted to confirm this decision.
You can also remove all elements to the right of an existing element. To do this right click on the element (that you want to keep) and select the 'Remove elements to the right' menu option. Like the clear path you will be prompted to confirm this decision.
Having created a path (or opened up the editor with a pre-configured path) you can see what data items the path will match to by using the evaluate function. This is accessible via the 'Evaluate path' button at the bottom of the dialog, or by right clicking in the 'Work Area'.
Having run the evaluation each element will contain a tag showing how many data items match to that point (see Figure 139). The actual matching items will be shown in the list at the bottom of the list view dialog (this list will not be available if you have launched the setup editor in standalone mode).
Figure 139. Evaluating paths
For example to get the matching items for the probe element in the example in Figure 139 the following path was evaluated 'geneos/gateway/directory/probe. If an item matches nothing it does not mean the path will match nothing, just that there are no data items for that element, for example there is no 'geneos' data item, and gateways have a directory which is the actual data item that matches, rather than the gateway itself.
The most important figure is the number of items that match the last element. If there are no matches then your path will match no items in the gateways that you are currently connected to. Note the term 'connected gateways' in the last sentence - at any given point in time the matches you get back will vary depending on the gateways you are connected to and their content, meaning running evaluate on the same path at different times may produce different results. For this reason the Evaluate function is simply a sanity check on your path.
Debugging a path
If the last element in your path unexpectedly matches nothing then you may have a problem in a preceding element. This should be obvious since the element which contains the invalid property setting, and those after it, will match nothing. Figure 140 illustrates an example of this issue.
Figure 140. Example of a bad path
In this case there is no Entity in our system called 'Nonsense Entity' so there are no matches for it or any of the elements that follow it since if you cannot find the 'Nonsense entity' you cannot derive its samplers etc. In summary, when debugging a path look for items that you would expect to have matches that do not (or have less than expected).
The actual matches are shown in the storable table at the bottom of the path editor dialog. This list is dynamic (it will update over time). It is not available if you have launched the path editor from the Gateway setup editor if it was launched stand alone).
Evaluating a specific element
You can evaluate to a specific point in the path if you wish. To do this, right click on the element you want to evaluate, and select the 'Evaluate to this element' menu item. The evaluation will be performed to the specified point in the path, and more significantly the list at the bottom of the dialog will display the matching items for this path element (rather than the whole path).
The Geneos URL path editor uses a superset of the elements provided in the DataItem path editor. The new elements in the Geneos URL path editor are most easily explained by looking at some examples of how they are used.
In this example, a link is created from a dashboard object to a tab in an ActiveConsole dockable.
The example starts with an ActiveConsole session which is displaying a metrics view with multiple tabs. It also has an Active Dashboard. A basic shape (an ellipse) has been dropped into the Active Dashboard and resized. By right-clicking on the shape in the dashboard and selecting "Properties...", the object attributes dialog is opened. By selecting the Links section of this dialog and clicking on the green plus, a new link is added. The path editor is then launched by clicking on the "..." button next to the Undefined URL. These steps are summarised in Figure 141 below.
Figure 141. Defining a link
Because a Geneos URL can be used as the path in this context, it is the Geneos URL editor which is automatically launched. A "Tab" element is added to the work area by dragging and dropping. On dropping the "Tab" element, this automatically creates a path containing a
Component, Dockable and Tab. Initially there is an error shown, saying that the Component, Dockable and Tab all require a value. The properties for these elements are then edited. For Component, the "Name" is set to "Active Console". For Dockable, the "Name" is set to "metricsview". For Tab, the "Name" is set to "cpu", which in this case is the name of the middle tab in the Metrics View. The error line then disappears. These steps are summarised in Figure 142 below.
Figure 142. Creating the path for the link
The path is saved and the Geneos URL editor is closed by pressing OK. The object attributes dialog is then closed by again pressing OK.
To be able to see that the link is working correctly, the Metrics View should then be hidden by click on the X in its corner. On then double clicking on the object, the link is followed, reopening the metrics view with the specified tab selected. Using the link is shown in Figure 143 below.
Figure 143. Using the link which has been created
In this example an Accessor element is used to change the functionality associated with a link.
The start of this example is the same as in section Referencing Components via Paths. It starts with an ActiveConsole session which contains an Active Dashboard, into which a basic shape has been dropped. The properties (object attributes) dialog for this shape is opened and a link is added. The path editor is then launched by clicking on the "..." button next to the Undefined URL. This is as shown in Figure 141 above.
Because a Geneos URL can be used as the path in this context, it is the Geneos URL editor which is automatically launched. A "Gateway" element is added to the work area by dragging and dropping - this causes a Gateway and a Directory element to appear on the path. An "Accessor" element is now added to the end of the path by dragging and dropping. The Accessor element initially contains the text "choose accessor". After double clicking on the Gateway element to open its property dialog, the "Name" can be set to the name of the gateway, and the dialog can then be closed. By double-clicking on the Accessor element to open its property dialog, its "Name" can then be set to "Edit", and this dialog can then be closed. These steps are summarised in Figure 144 below.
Figure 144. Creating a path with an accessor element
The path is saved and the Geneos URL editor is closed by pressing OK. The object attributes dialog is then closed by again pressing OK.
If you now double click on the shape in the Active Dashboard, this then launches the Gateway Setup Editor, loaded with the configuration for the Gateway being used, as shown in Figure 145 below.
Figure 145. Using the link that has been created
The important thing to understand here is the difference that the Accessor element has made. Without the Edit Accessor on the end of the path, double clicking on the shape would have simply opened the Gateways View (if it wasn't already opened) to display the icon for the Gateway. Because the Edit Accessor is on the end of the path, this causes the link to instead launch the edit function associated with the object, i.e. the Gateway Setup Editor.
In this example a WWW Page element is used to create a link from a dashboard object to an internet website.
The start of this example is the same as in section Referencing Components via Paths. It starts with an ActiveConsole session which contains an Active Dashboard, into which a basic shape has been dropped. The properties (object attributes) dialog for this shape is opened and a link is added. The path editor dialog is then launched by clicking on the "..." button next to the Undefined URL. This is as shown in Figure 141 above.
Because a Geneos URL can be used as the path in this context, it is the Geneos URL editor which is automatically launched. A "WWW Page" element is added to the work area by dragging and dropping. When this is dropped, it automatically opens the element properties dialog for the WWW Page Element. The "URL" property should be set to the URL for a website (e.g. "https://www.itrsgroup.com"). These steps are summarised in Figure 146 below.
Figure 146. Creating a path with a WWW Page element
The dialog should then be closed. The WWW Page element will then be shown in the working area with the url property set. The path is saved and the Geneos URL editor is closed by pressing OK. The object attributes dialog is then closed by again pressing OK.
On double clicking on the shape on the dashboard, the website is displayed in the user's default browser, as shown in Figure 147 below.
Figure 147. Using the link that has been created
Many of the views in ActiveConsole are now provided by List Views with preconfigured paths. As such they provide good examples of the use of some of the Geneos URL elements. The Netprobes View is such a case. Irrespective of what you drop in the Netprobes View, it always displays netprobes. If you drop a gateway into the Netprobes View, it displays the netprobes being used by that gateway. If you drop a managed entity on it, it displays the netprobe which that managed entity belongs to. And if you drop a netprobe on it, then obviously it displays the netprobe. How is this achieved?
In the Netprobes View, click on the "Configure the view" button (or right click and select Configure > ListView). Select Drag and Drop from the left pane. Now in the right pane, click on the Inheritance pull-down and select "Define Locally". This will permit you to access and examine the local settings. You will see that the local settings contain three entries:
"ChildProbes", "Parent Probes" and "Probes". Let us look at each of these in turn.
If it is not already selected, select
"ChildProbes" in the list of local settings. The
Paths field defines which data items this entry will
be applied to. "ChildProbes" has a path of
/probe/ancestor::*. Hence it
matches any path to a data item which is an ancestor
of a probe, e.g. a gateway. Now look at the Modifier
field - press the edit button so that you can see it
in more detail in the Geneos URL editor. See
Figure 148. Path for "ChildProbes" seen in Geneos URL editor
So the modifier starts with Dropped Item - this gets replaced by the path of the data item dropped on it. The Append then causes the two elements that it contains to be added to this path, firstly a descendant element followed by a probe. So the effect of all this is that, when e.g. a gateway gets dropped into the Netprobes View, the path to the gateway gets a descendant element attached to the end of its path, followed by a probe, and this path is then passed to the List View. The net effect is that the List View gets a path with matches any probe which is a descendant of the gateway, and the List View therefore displays all such probes.
Now select "Parent Probes". "Parent Probes" has a
/probe/*. Hence it matches any
path to a data item which is a child of a probe, e.g.
a managed entity. Again, press the Edit button to
display the Modifier field in the Geneos URL editor.
See Figure 149
Figure 149. Path for "Parent Probes" seen in Geneos URL editor
So again the modifier starts with the Dropped Item, followed by the Append which contains an Ancestor followed by a probe. The result is that the path to the managed entity dropped into the List View gets modified by adding an ancestor element followed by a probe, and this then gets passed to the List View. The net effect is that the List View receives a path which matches the probe which is an ancestor of the managed entity, i.e. it displays the probe which the managed entity belongs to.
Now select "Probes". This is the simplest case - it matches a path of "/probe", so the only type of data item which this will match when dropped onto the List View is a probe.
Figure 150. Path for "Probes" seen in Geneos URL editor
The modifier is simply the Dropped Item, so it doesn't actually change anything and passes the path straight through to the List View. Hence the List View displays the probe which was dropped on it.
When a Merge element is applied to an existing element in a path, it merges together the properties from the existing element and the merged element, i.e. any properties defined in the original element and not redefined in the Merge element will still be set to their original value. When a Replace element is applied to an existing element in a path, it replaces all the properties in the existing element, i.e. any property which is not defined in the Replace element will be set to undefined in the resultant element, regardless of whether it had a value or not in the original element. Here is an example to make this a little clearer.
The example uses an ActiveConsole attached to a Gateway with at least two samplers, called sampler1 and sampler2. An empty List View is created using the Dockable Manager. The List View settings dialog is then launched by clicking on the "Configure the view" button in the List View (or right-clicking in the yellow area and selecting Configure > List View). "Drag and Drop" is then selected in the left pane of the List View settings. In the right pane, "Define Locally" is then selected from the drop down menu for inheritance, so that local settings can then be defined. A new path is added by clicking on the green plus next to the Paths field. From the line added, the path editor is then launched by clicking on the "..." button. Because this can only be a DataItem path, the DataItem path editor is launched. In the path editor, the default path is removed by right-clicking in the working area and selecting "Clear Path" from the menu. The "Sampler" element is the dropped into the working area. The path is saved and the Geneos URL editor is closed by pressing OK. See Figure 151 below for a summary of these steps.
Figure 151. Create list view path
What has effectively been done here? A path has been created such that drag and drop functionality in this List View will only work when samplers are dropped into the List View.
Next, another path editor dialog is launched by pressing the Edit button by the Modifier field in the Drag and Drop List View settings to set up a modifier. This time, because the modifier path can be a Geneos URL, the Geneos URL path editor is launched. Initially just the Dropped Item is displayed. A Merge element is then added to this path, dropping it after the Dropped Item element. A Sampler element is then dropped after the Merge element. By double
clicking on the Sampler element, its properties dialog is launched: the "Snooze" property is then set to "true", and the properties dialog then closed. The path is saved and the Geneos URL editor is closed by pressing OK. These steps are summarised in Figure 152.
Figure 152. Set up the modifier path using a merge element
The List View settings dialog is then closed by again pressing OK.
Now sampler2 is dragged and dropped into the List View. When sampler2 is first dropped into the sampler...nothing appears in the List View. In the State Tree, sampler2 should now be snoozed. As soon as it is snoozed, sampler2 appears in the List View. In the State Tree, sampler1 should now also be snoozed. Sampler1 does NOT appear in the List View. These last few steps are summarised in Figure 153 below.
Figure 153. Data displayed in list view while using the merge element
To understand what has just happened, the "Configure the view" button should be used to launch the List View settings dialog again. The Content Path should be selected in the left panel. The dialog and fields should then be resized so that the whole of the Path is visible, as in Figure 154 below.
Figure 154. Contents path created while using the merge element
The Path that is shown is the path that was created when sampler2 was dropped into the List View. Notice that the path is matching on a sampler with the name sampler2 and the property snoozed=true. This is because a Merge component was used in the modifier - it merged in the property snoozed=true but, because the modifier did not specify a name, it did not overwrite the name of the dropped item. Hence, with this path, only sampler2 was shown in the List View after it was snoozed. Sampler1 was not shown in the List View even after it was snoozed, because it did not match the required name.
Next, the Content Path should be highlighted by clicking on it, and the green minus then pressed to remove the Contents Path. Drag and Drop is then selected in the left panel, and the "Edit..." button for the Modifier field pressed to bring up the Geneos URL editor. By clicking on the X for the merge element, both the merge element and the sampler within it are then deleted. A Replace element is then dropped on the end of the path, and a Sampler element then dropped after this. The properties dialog for the Sampler element is then launched by double clicking on it: the property "Snoozed" should be set to "true" and the dialog "Close" button then pressed. The path is saved and the Geneos URL editor is closed by pressing OK. These steps are summarised in Figure 155 below.
Figure 155. Change the path to use a replace element
The List View settings dialog is then closed by again pressing OK.
The List View is now empty again, because the Contents Path has been deleted. Both sampler1 and sampler2 should now be unsnoozed using the State Tree. Now sampler2 should be dragged and dropped into the List View again. As before, at the point when sampler2 is dropped into the List View, nothing appears in the List View. Now sampler2 should be snoozed in the State Tree. As before, when it is snoozed, sampler2 appears in the List View. Now sampler1 should be snoozed in the State Tree. Unlike before, when it is snoozed, sampler1 now appears in the List View. These last few steps are summarised in Figure 156 below.
Figure 156. Data displayed in the list view while using the replace element
To understand what has just happened, the "Configure the view" button should be used to launch the List View settings dialog again. Content Paths should be selected in the left panel. The dialog and fields should then be resized so that the whole of the Path is visible, as in Figure 157 below.
Figure 157. Contents path created while using the replace element
The important thing to notice here is that, this time, the path is set to match a sampler with the property snoozed=true, but without a name set. This is because the modifier is now using a Replace element. So when you drop sampler2 into the List View, the sampler on the path gets overwritten with the element with snoozed=true set. Because the whole sampler element gets overwritten, the name is no longer set. Hence, once they are snoozed, both sampler2 AND sampler1 match the path and get displayed by the List View. So you can see the difference in behaviour between Merge and Replace.
A good example of the use of the User Selection element is the Items of interest. It is a preconfigured List View which uses User Selection. Open the Items of interest
and open its List View Settings by clicking on the "Configure the view" button. The content path which is preconfigured for the view can be viewed more clearly by selecting the path field and then pressing the "..." button which appears - the path is then displayed in the Gateway URL editor. See Figure 158 below.
Figure 158. Preconfigured content path for Items of interest
When the user selects an item in one of the other views (e.g. selects a probe in the probe view), the user selection item in this path is substituted by the path of the object that the user has selected. Hence if the user selects a probe, then the probe's path is substituted in. The append element is then applied to it, creating a path which matches any cell which is a descendant of the probe and has the properties severity>1, active=true and snoozed=false. The net effect is that the path will match and display any active unsnoozed cell with a warning or critical severity which is also a descendant of the item that the user selected.
This can be seen in practice by connecting to two gateways, one of which has some cells with critical or warning severity and the other of which has no such cells. In the screenshots below the Netprobe, entities, and items of interest views are all configured in icon mode.
For the gateway with no warning or critical cells, selecting the gateway or any item below it in the State Tree displays nothing in the Items of interest, since the selected item has no descendant cells with the required severity. Similarly if you select this gateway in the Gateways view, or select any of its descendant probes or entities in the probe view or entities view, then nothing is displayed in the Items of interest. .
Figure 159. User selection causes nothing to be displayed
For the gateway which has got warning or critical cells, selecting the gateway or any item below it in the State Tree (or selecting the Global State in the State Tree) displays all the warning or critical cells in the Items of interest. Similarly if you select this Gateway in the Gateways view, or select any of its descendant probes or entities in the probe view or entities view, then all of the warning or critical cells are displayed in the Items of interest. See Figure 160 below.
Figure 160. User selection causes cells to be displayed
The standard forms of the Path Editor (featuring the
drag-and-drop, data-aware work area) do not support all
syntactically valid XPaths. For example, you might want
to specify two or more filters on a cell value, to
match a literal '*' character in a row name, or to use
a 'wild' expression in a situation that the standard
editor interprets as 'contains'. (If you use a '*' or
'?' character in a path, the standard forms of the Path
Editor will generate a 'wild' or 'contains' expression;
this usually correctly expresses your intent, but some
expressions, such as
\*#\*0\*, are difficult to
By experimenting with the standard forms of the Path Editor and inspecting the full XPath generated, you can usually determine the syntax required, and you could edit this directly into the path by typing into a field that displays an XPath or by using the XML view in the Gateway Setup Editor. However, if the standard Path Editor were then to be used to evaluate the path, it might remove or alter the parts that it does not support.
Figure 161. The 'expert mode' Path Editor
The 'expert mode' Path Editor (illustrated in Figure 161 above) provides a convenient way to edit such paths. The path is shown in an editable text area, with each '/'-delimited component of the path on a separate line. This work area is not syntax-aware, but you can verify the path syntax by clicking either of the 'Evaluate Path' or 'OK' buttons. If the XPath syntax is invalid, the yellow status bar at the top of the Path Editor will turn red and show an error message.
If you have manually entered a path which is not supported by the standard editors, the 'expert mode' Path Editor will be launched automatically when you need it. Otherwise, to access 'expert mode', edit the path to add some unsupported syntax, for example by adding a space immediately after one of the '/' characters in the path, and then invoke the Path Editor in the usual way (usually by clicking an 'Edit' button.) As long as a path contains unsupported syntax, the full XPath will be shown instead of the 'user readable' form and the Path Editor will be launched in 'expert mode'.
Figure 162. Editing a path so that the Path Editor will be launched in 'expert mode'
Each data item in the geneos system has a number of properties. These properties are populated by the Gateway and they are published to the Console. You can see the properties for any given data item by right clicking on it and selecting the 'Properties' menu, see section Properties Dialogs for more information on the properties dialog.
There is another class of properties called Parent properties which many data items have access to. Before getting into the specifics of this feature, consider that the structure of any given gateway is a tree with the following relationships:
- A Gateway has 0 to Many Probes
- A Probe as 0 to Many Managed Entities
- A Managed Entity has 0 to Many Samplers
- A Sampler has 0 to Many Data Views
- A Data View has 0 to Many Managed Variables (which are either table cells or headlines)
This is a strict tree, in that any given data item can only have 1 direct ancestor. For example a Managed Entity can only have one direct ancestor which is always a probe. Its ancestors are equal to all data items above it as you traverse the tree back to gateway. So a sampler will always have the following ancestors:
- 1 gateway, 1 probe, 1 managed entity, of which the entity will be its direct ancestor.
A parent property is a property of a data item that is an ancestor of the selected item. For example, a probe has a 'connected status' property, therefore all entities have a property probe.connectionStatus which will have a value equal to its probe connection status. Another example is an entity called X that is configured in a probe called Y - getting the property probe.name from X would thus return Y.
Note: The console does not currently support child properties because there will generally be more than one possible value.
Active Console contains a dialog that lets you configure and save table column settings. This dialog is accessible either from the table that you want to work on or from the Tools menu. If the screen is launched from the table then current settings for that table will be available to you to manipulate. You can edit settings for all columns individually. You can also choose which settings you would like to save to a workspace. It also provides you a list of all tables whose settings have been saved in workspace. You can view, edit, or remove those settings.
If the settings editor is launched from the Tools menu then the current table function is not available. In this mode you can only review, edit, or remove any previously saved settings.
For each column in the table, the following column settings can be saved:
- Visibility - whether the column will be displayed if available.
- Position - the position refers to the order of the columns, where the left most column will be index 0, and the right most column will be X-1, where X = the number of columns.
- Width - the width of the columns (in pixels).
- Sort Order - the sort order has two parts: the order, which is an index, and the direction, which will be up (sort ascending), or down (sort descending). Because multiple columns can be sorted, the index refers to the priority of the sorting, i.e. the data is first sorted on the column with sort index 0, and then, if there are duplicates, the data is sorted by the column with sort index 1 and so on.
You can also review, change, or remove any previously saved settings for all tables. If you remove saved settings for a table, then the system automatically resets itself to factory settings for that table. If the table is currently active, then this change will be done straight away. Otherwise it will be done when the table is loaded next time. Different operations are associated with each type of settings that can be saved.
- Visibility - settings can be changed by right clicking on the table header and choosing show/hide any column.
- Sort order - settings can be changed by left clicking on the header for column you want to change settings for. Press Ctrl key to sort multiple columns.
- Position settings - can be changed using column drag-drop.
- Width settings - can be changed by resizing the columns using the mouse.
Figure 163. Table Column Settings Editor
Figure 163 shows the settings editor dialog for a Processes metrics table. The table on the dialog mirrors the one you are configuring. The settings for the table can be configured using the mouse as you would configure any other table (dragging and resizing the columns, right clicking to toggle visibility and left clicking column headings to change sort and order and position). Any updated settings will be automatically displayed on the table and persisted when you press OK. These settings will be applied to the table automatically from then on once saved.
If current values are available, they can be fixed in persistence by double clicking on the cell. Double clicking on a cell that already has a persisted setting will remove this setting and set to factory default.
Table settings can also be manipulated by using the table cells right-click menu. Figure 164 shows the screenshot with right-click menu. This menu lets you reset settings to factory defaults and save current values as defaults for:
- Selected Cells: You can select multiple cells by pressing the Ctrl key. This menu item lets you manipulate settings for all selected cells.
- Current Cell: This is the cell on which you pressed right-click to launch the menu.
- Current Column: All settings for current column. This is the column which the current cell belongs to.
- Current Row: Current setting for all table columns.
- Whole Table: Manipulates settings for the whole of the table.
Figure 164. Settings editor table popup menu
Active Console is capable of retrieving events and chart data from databases. It only connects to the databases at the time of the query, and does not block user actions or remain connected to the database for the duration of the query. When the query completes the Active Console is sent the data by the database. The duration of the query is dependent on the size of the returned dataset and the speed of the database and its connection to the Active Console.
The available Active Console database connections are derived from the gateways that the Active Console connects to. So for example if you connect to 3 gateways, each of which is connected to a different database, then the Active Console can call on all three databases to retrieve results.
You can also specify additional database connections via the 'Database connections' section of the workspace settings, see section Workspace Settings Dialog. This can be useful to retrieve historical data that is stored in a database that none of your gateways connect to.
Setting up a gateway to log to a database, and telling it which data items to log are both defined in the gateway setup. In the Active Console you can see whether a gateway is successfully connecting to its database via the Gateway view (see section Gateways Dockable). In the icons view there is a visual indicator, while in the details view you can see explicit details of the database connectivity status
Figure 165. Database connectivity
The same visual indicators will appear next to data items when they are being logged to the database.
The following outlines the basic steps to carry out the Basic Mode feature of the Refactor Tool in the Active Console:
- Add a definition by clicking the '+' icon.
- Double click the 'Data Item Type' field and select from the available dropdown which part of the Path requires refactoring. I.E. Gateway
- Double click the 'Property' field and determine whether the ID or the Name of the Data Item Type in the Path is to be refactored.
- Double click the 'Current Value' field and enter the value of the Path that is to be changed.
- At this point as soon as a match is made between the 'Current Value' and a Path within the Active Console, the matched path will display in the 'Affected Paths' section with the matched value displaying in Blue.
- Double click the 'New Value' field and enter the new value that the path should contain.
- The Refactor button will now be enabled.
- A user can select which paths are to be refactored by selecting/unselecting the checkbox next to the specific path.
- Click the Refactor Button when ready to Refactor the Paths.
- A Refactor Results window will appear with confirmation of the Old Path and the New Path with only the paths that have been refactored displayed.
A file can be created and saved that can be distributed to other users by clicking the 'Create File' button when all definitions are set up.
To run the file Import the saved file from File > Import which will display all definitions created within the file and automatically show all affected paths within the Active Console that match.
Note: Any specific selections made against individual paths not to be Re-factored at the time of creating a file will not be retained and all paths will be selected for Refactor.
Selecting the 'Disable Filtering' checkbox will display all paths within the Active Console however not all paths can be Refactored. Paths in the following areas can be Refactored:
- Metrics View
- System Tray
- Dashboard Item Modifiers
- List Views
Most AC components make use of tables to display and layout their content. All the tables can be modified to suit your requirements by:
- Resizing the columns,
- Re-ordering the columns,
- Defining which column to sort by (and whether the sort is ascending or descending).
Some of the tables (notably those in the metrics view) offer you the ability to:
- Hide selected columns,
- Sort by multiple columns.
These settings will be stored in the workspace, meaning whenever you reopen the workspace the tables will be as you left them.
To use SSO, a Geneos administrator needs to enable SSO logins for each Gateway and to ensure that at least one instance of the Geneos SSO Agent is running.
To use SSO Log-in Authentication in Active Console, go to Advanced settings.
- In the General group, add the SSO's URL in the SSO Agent URL field.
- Click Apply, and then click OK.
- Set up one or more Gateway connections to use the SSO Logon method, either individually or through the workspace logon setting (see Logging on to gateways and Connection Settings).
Note: Specify the correct protocol to use between http or https, host name, and the port number.
Note: Versions of ActiveConsole 2 before version 4.3 cannot process a configuration that references an unknown login method. If they encounter references to the SSO logon method, they fail to load any connection details at all. This means that, if your workspace file specifies SSO as the workspace logon type or if it specifies SSO as the logon method for any connection, you cannot use it with an older version of ActiveConsole 2. Additionally, a remote connection file which specifies LM_SSO as the logon method for any connection cannot be used with an older version of ActiveConsole 2.
If your Active Console is in the same NT domain as the SSO Agent, Active Console will log you in automatically using NTLM, assuming that one or more Gateways are available and set up to use the SSO login method.
The SSO Login / Logout button, which appears in the toolbar area of the ActiveConsole 2 window allows you to log in and out manually.
If you are logged in via SSO, the button will be labelled ‘SSO Logout’. Clicking it will log you out and any SSO gateways will be shown in grey, as if they were disabled.
If you are not logged in, the button will be labelled ‘SSO Login’. Clicking it will log you in and re-establish connections to any SSO gateways, other than those which have been explicitly disabled via the Connections settings dialog or by using the “Disconnect” menu action.
If the SSO Agent URL has not been configured, the button will be disabled.
There are a number of start up flags and settings you
can define which modify the behaviour and configuration
of the Active Console while it is running. These settings
are configured by modifying the
that resides in the same directory as the
ActiveConsole.exe. This file is a text file, so can be
edited in any text editor.
The file that is shipped with Active Console is similar to below:
############################################################ #### The java class that has 'main' ############################################################ -mainclass com.itrsgroup.activeconsole.ActiveConsole ############################################################ #### The JVM to use and arguments ############################################################ -jvm .\JRE\bin\client\jvm.dll -jvmargs Xmx128M Ddocking.floatingContainerType=frame ############################################################ #### For the legacy ActiveConsole (Setup editor) ############################################################ -legacyjarargs Xms123M Xmx456M -legacyjavaexe .\JRE\bin\javaw.exe ############################################################ #### For the Gateway Setup Editor (GW2) ############################################################ -schema .\schema\gateway.xsd -gsedir .\gse -alwayssavable
############################################################ #### For the ActiveConsole2 AC ############################################################ -EMF2ListentPort **** Allows you to change the listening port through the .gci file
############################################################ #### Misc ############################################################ -logexceptions
The file is newline delimited and each flag starts with a hyphen. Any arguments for a given flag are again separated by a newline. Any lines that begin with a # or are empty are ignored.
#comment1 -<Flag1><Flag1Arg>…#comment2 -<Flag2><Flag2Arg>…
All of the arguments are passed to the Active Console java application. However, there are some special arguments that are used by the ActiveConsole.exe launcher application.
|mainclass||Java class||Tells the launcher which class to look for a 'main' function.||-mainclass com.itrsgroup.activeconsole.ActiveConsole|
|jvm||Path to the jvm library||Specifies the jvm to use. If this flag is not specified, launcher will attempt to discover this from the system.||-jvm C:\Program Files\Java\jre1.4.2\bin\client\jvm.dll|
|jvmargs||See java documentation|
Arguments that are passed to the jvm. For more information run java.exe -? from the command line.
The arguments should not include a hyphen!
|classpath||Any number of classpath entries||These arguments will be combined with the CLASSPATH environment variable, and any file with a .jar extension in the 'jars' directory, and passed to the jvm using the -Djava.class.path system property. See section below for more information.|
|libpath||Any number of directory entries||These arguments will be combined with the 'lib' directory and passed to the jvm using -Djava.library.path. See section below for more information.|
|path||Any number of path entries||These arguments will be combined with the 'lib' directory and the PATH environment variable and used to set the PATH environment variable for the ActiveConsole process.|
|jarscan||Any number of directories||Every directory specified will be scanned for files with a .jar extension. Any files found will be added to the classpath.|
|putenv||Any number of name value pairs||This will set environment variables for the ActiveConsole process. See ActiveConsole.exe Legacy flags.|
|nolog||None||Prevents the ActiveConsole from writing to a log.||-nolog|
|gsedir||A directory||Specifies the resource directory of the Gateway 2 Setup Editor where images, sounds and property files are stored.|
|gse-wsp||Full path to the working directory of the GSE|
Specifies the location of the working directory of the GSE. This is where log files, cached schema and autosave files are stored.
If this flag is not set, the GSE working directory defaults to %APPDATA%/GatewaySetupEditor.
|logexceptions||None||If present any uncaught exceptions thrown by Java will be logged to a file exception<date>.log.||-logexceptions|
|licwarning||Number of days||Specifies the number of days for a warning about a gateway licence expiry. Defaults to 30.|
Turns off notifications.
This flag is only provided for AC users in a Citrix environment.
|dialogStartLocation||A fully qualified directory||This determines the location that the first save / open dialog you use in a session will appear. After the first it will always remember the last directory you were in.|
|repeatlicwarning||None||If specified, the ActiveConsole will repeat any licence warnings every 24 hours.||-repeatlicwarning|
|wsp||Full path to the working directory of the console||This tells the AC where to locate the AC User Directory in order to write its configuration and temp files.|
|ws||A full path to the selected aws file||This specifies the workspace to load without using the workspace selector. The AC will ignore the workspaces included in the configuration.xml file located in the AC User Directory.|
|A URL to a selected AWS file|
This specifies the workspace to load from a URL without using the workspace selector. The AC will ignore the workspaces included in the .xml file located in the AC User Directory.
If both this flag and the ws flag are used then the ws flag takes precedence.
|newWorkspaceLocation||Path to a directory||New workspaces created via the console will be created in this directory.|
|showgw1editoroutput||None||If specified, The ActiveConsole will show the output of the legacy gateway editor in the output window.||-showgw1editoroutput|
|legacyjarargs||Any number of arguments||If specified, will pass on the specified flags to the JRE used to launch the legacy gateway set-up editor.|
|legacyjavaexe||A path to the javaw.exe to use for launching the legacy gateway set-up editor||If specified, will use the path defined after it.|
|maxlogsize||Size in megabytes||The maximum size of the log file before rolling the file. The default is 10mb.|
|autoAcceptLicense||Name of licence (ADB for dashboard licence)||Auto accepts the licence without offering the user a trial period.|
|fastDVActivation||None||Makes the loading of dashboard significantly faster, but will only work for dashboards created after the GA2009.1 081222 build of the AC.||-fastDVActivation|
|doNotValidatePathsOnStartUp||None||Stops the AC from validating the user defined XPaths on startup, by default it will. Turning this on will increase the speed of startup.||-doNotValidatePathsOnStartUp|
|showlocalcommands||None||Shows the command and its arguments passed to the shell for any local commands.||-showlocalcommands|
|rolllogwithdatetime||None||When if this flag is set when maxlogsize is reached, the current log will be copied to <logfile>.<datetime>. Otherwise it will be copied to <logfile>.old.||-rolllogwithdatetime|
|maximumDatabaseConnections||Number of database connections||AC database connection pool uses this flag to change maximum number of simultaneous database connections. If nothing is supplied then default value is 5.|
|patheditorconfig||Path to the Path Editor Configuration||TBD||-patheditorconfig ./resources/configuration|
|userResourcesDirectory||Path to the user resources directory||TBD||-userResourcesDirectory ./UserResources|
|bdosync||A list of subscription modes for a bdo||This setting enables the subscription mode for syncing the bdos (e.g. based on severity).||-bdosync DataView,BDOSyncType_Level,DV1_SyncLevel_RedAmberCells|
|connections||Different settings||Settings for the connections|
|appname||The application name||The application name|
|appdisplayname||The application display name||The application display name|
Gateway Setup Editor
|helpjars||List of jars used for loading GSE help||List of jars used for loading GSE help|
|autosave||The time interval||The time intervals at which Gateway Setup Editor will automatically save the setup file.||-autosave|
|disableautosave||None||Prevent GSE from automatically saving setup file at regular intervals.||-disableautosave|
|disablehistory||None||Disable logging history of setup files.||-disablehistory|
|loadIncludesWithMain||None||Loads all include files as well when the main Gateway setup file is loaded.||-loadIncludesWithMain|
This setting enables Gateway connection details to be passed to the Gateway Setup Editor. The arguments must be declared in the following format:
-connect "<primary host>:<primary port>:<logon method>:<secondary host>:<secondary port>:<secure>"
-connect "192.168.1.110:10090:Ask once::0:SECURE" -connect "192.168.1.110:10070:Use system:192.168.1.210:10080:INSECURE"
This setting is only in effect if the GSE is run standalone. If the GSE is launched from the Active Console as a separate process, the Active Console provides this argument to the GSE process. See Advanced settings.
Note: SSO logon is not supported with this setting.
|answers||A list of x=y||TBD||-answers|
|advancedSearch||None||Makes GSE search dialog box available||-advancedSearch|
|noconfirm||None||Prevents GSE from displaying a Confirm Save dialog box everytime.||-noconfirm|
|novalidateonsave||None||Prevents GSE from doing setup validation on save.||-novalidateonsave|
|newdoc||TBD. This setting is ignored if the Gateway Setup Editor is not run standalone.||-newdoc|
|open||TBD. This setting is ignored if the Gateway Setup Editor is not run standalone.||-open|
|autoSort||ascending | descending | none||Sorts items with sections of the setup. Sorts in the order given by argument. None is the default.|
|A valid system font||This will be the font used to display charts and gauge headers and will also be the default selected font for newly created dashboard object with 'Text Layout Settings'.|
Arial Unicode MS
|enableApproxDataviewSorting||None||A gci flag that is used to turn on optimised sorting for dataviews.|
true (Set the flag parameter to true)
Some flags only apply when connecting the ActiveConsole to a Gateway 1. These can be set using environment variables or using the 'putenv' flag (See ActiveConsole.exe flags).
|EVENT_LIST_SIZE||Number of events||Tells the console how many events to retain per gateway connection (effects only GW1).|
|Outputs string message data to the log or to a recorder file.|
To output all messages to the log file -putenv
To record the messages to a .rec file -putenv
In addition to the values specified in the 'classpath' and 'libpath' arguments specified, the following paths will also be automatically added:
The full path to the 'lib' directory will be added
Any file with .jar extension inside the 'jars'
directory will be added to the
Some parts of the ActiveConsole use formatted strings to specify dates. The tokens that can be used are:
|Short named month||MMM||Jan|
|Long named month||MMMM||January|
|Short named day||E||Wed|
|Full named day||EEEE||Wednesday|
The tokens can be separated by any tokens you wish, for example : or / or . and so on.
Examples of token patterns and the display on the X-Axis, based on the 1 January 2002, at 12.34 and 23 seconds.
|EEEE HH.mm||Wednesday 12.34|
|MM yyyy||01 2002|
|HH:mm ss (MMMM yyyy)||12:34 23 (January 2002)|
Some parts of ActiveConsole allow you to format numbers. The user specifies a pattern string, which takes the form used in the Java class DecimalFormat. These pattern strings give a huge amount of flexibility in the number format that can be produced, but are not immediately understandable if you are not familiar with the DecimalFormat class. The best way of introducing the concepts is to look at some examples, as shown in the following table.
|Pattern||Unformatted Number||Formatted Number||Comments|
|000000||-1234.567||-001235||The 0 symbol shows a digit, or 0 if no digit is present; notice that the number was rounded up|
|##||-1234.567||-1235||The # symbol shows a digit, or nothing if no digit is present|
|.00||-.567||-.57||The . symbol indicates the decimal point|
|#,###,###||-1234.567||-1,235||The , symbol is used to group numbers|
|The ; symbol is used to specify an alternate pattern for negative values|
|'#'#||-1234.567||-#1235||The ' symbol is used to quote literal symbols|
|#.######%||-1234.567||-123456.7%||The % symbol (as a prefix or suffix) multiplies the value by 100 and shows it as a percentage|
There are even more pattern symbols and options available than those demonstrated in the examples above, and the full range of possibilities and nuances is too large to explain here. If you want to find out about further options, then look on the internet for documentation on the Java class DecimalFormat.
The ActiveConsole 2 gets all the information that it displays from the gateways it is connected to. In the event of an issue it is possible to see the underlying information coming from the gateways independently of the ActiveConsole interface. This can be useful for tracking down a problem, asserting whether the issue is in the gateway (i.e. the information that the gateway is asking the ActiveConsole to display is wrong), or the ActiveConsole itself (which is incorrectly displaying the data it has received). To show the diagnostic you must ensure that the listen port of the ActiveConsole is not 0 (see section Workspace Settings Dialog), and then use the 'Tools > Diagnostics' application level menu item.
The contents of the diagnostics will appear in a web browser. Interpreting the results is outside the scope of this document. It is also worth noting that a similar page is available on the gateway itself.
If you experience problems when using ActiveConsole 2 then you can report these on https://www.itrsgroup.com/how-we-help/support
When raising a helpdesk ticket it will help speed up the bug fixing process if you could attach a diagnostic file, which is generated via the 'Help ► about' dialog. See Figure 167 for an example.
Figure 167. Generating an ActiveConsole 2 diagnostic file
On the helpdesk ticket, this diagnostic file can be connected to the issue report via the 'Add File' button.