Gateway Setup Editor (GSE) is a standalone Java and C++ application which allows you to edit the setup of the Gateway. This document is a reference guide which will step you through the major components.
This document assumes the user has a basic understanding of the Geneos framework.
It guides you through the fundamental principles behind the GSE interface and its main components.
The GSE is part of the Geneos Framework; therefore if you have a license for the framework you can deploy as many GSE's as you like within the group or organisation that has the license.
|GSE||Gateway Setup Editor.|
|Named item||Refers to any item in the setup that can be named, and referred to. Examples include Probes, Samplers and variables.|
|GA Version||General Availability. Geneos products that are in Beta or production are said to be GA's. They have been tested internally by ITRS.|
|RA Version||Restricted Availability. Geneos products that have not been tested, and are considered pre Alpha|
The Gateway Setup Editor (GSE) can be started in one of two ways:
GatewaySetupEditor.exe executable located
in the directory you installed the files in or
unzipped them to.
There are a number of start-up flags and settings
you can define which modify the behaviour and
configuration of the GSE while it is running. These
settings are configured by modifying the
GatewaySetupEditor.gci file that resides in the same
directory as the
GatewaySetupEditor.exe. For a
complete list of these flags, and details of how to
change this file, see Start up settings.
The GSE can run 'inside' the Active Console 2.
To launch the GSE without opening a setup, go to Tools -> Gateway Setup Editor.
To open an existing Gateway 2 configuration, use one of the following methods:
- Select Configure gateway from the toolbar, select a Gateway 2, and press OK.
- Right clicking on a Gateway 2 and select Configure gateway.
- Double-click on a Gateway 2 in the Gateways view.
When the GSE is run in this way it adopts all the arguments passed to the Active Console in the ActiveConsole.gci file.
The GSE can be configured to launch as a separate process from the Active Console 2 using the Gateway setup editor as a separate process advanced setting. See Advanced settings.
Gateway setups can be edited in 2 'modes': From disk or via a Gateway
Gateway setup files are XML files, and can be opened from any accessible file location. To do this simply go to File->Open or Use the 'Open Document' button on the toolbar, and select a path using the file open dialog.
Alternatively, you can Drag and Drop a file from external programs, such as Windows Explorer.
Note: Files edited from disk do not benefit from gateway related features, such as gateway validation and file locking. Also, the setup will not get applied to the gateway automatically.
You can open a setup directly via a gateway connection, when running the GSE standalone. The setup editor can request the setup from a gateway for editing, and then send the setup back to the gateway to be applied.
To open a Gateway setup, you must connect to the Gateway: Go to File->Connect, or select 'Connect to Gateway' from the toolbar. This will open the connection dialog:
Select the Logon type, host/IP, and the port of a Gateway 2. Press OK and the editor will attempt to connect to the Gateway and request the setup.
A new Gateway entry will be added to the Gateways view.
To remove a gateway connection, see: Removing gateway connections.
To save a setup, do any of the following:
- Go to File >Save in the menu.
- Press Save current document on the main toolbar.
- Press Ctrl+S on your keyboard.
Before saving the document, the editor performs a Schema validation (See Error's view). If there are any errors, you will see this dialog:
If you select Yes, the document is saved.
If you select No, the save is cancelled.
Note: If the setup has not been changed the save button and menu item remain inactive.
To save a copy of the setup to disk, use File > Save As. See The menu structure for more information.
To close a setup, do any of the following:
- Select File > Close in the menu.
- Right- click on the document tab and select Close.
- Press Ctrl+F4 on your keyboard.
The following dialog box appears if the setup has been changed:
If you select Yes, the document is saved and then closed.
If you select No, the document is saved, and any changes are discarded.
If you select Cancel, the document remains open.
An example of the main application window is shown in below:
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 setup files. All the components reside in dockable frames (see section Gateway Setup Editor) which can be dragged around the application window or undocked (floated in their own window)
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.
The status bar (at the bottom of the main application window) displays the build number (version) of the GSE, and the schema version when a document is active.
This section outlines some general standards and tips and tricks in the GSE interface.
The GSE 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 Gateway Setup Editor). The available components are summarised here, and discussed in detail in the following sections:
- Navigation - Shows the main sections and items in the setup, and controls the Settings editor of the current document
- Errors View - Shows a list of validation errors for the current document
- Search Results - Shows the search results for the last executed search
- Gateways View - Shows any connected gateways
- The Document Area - Shows all the open documents
- Settings Editor - Shows the selected section for editing
The GSE uses icons to represent various types of data in a setup. This section shows examples of these icons.
The following icons are used throughout the application to represent the sections of the setup:
|Managed entity||Managed entities|
|Schedules command||Schedules commands|
|Active time||Active times|
|Audit output||Audit outputs|
|URL template||Knowledge base|
|KBA set||Knowledge base|
|FKM Table||Static variables|
|RMC templates||Static variables|
See Active Console 2 guide.
The Errors dockable lists validation errors generated by the editor and gateway. To generate a list of errors, either:
- Select Tools > Validate.
- Press Validate current document in the toolbar.
Saving the current document also runs the validation process.
There are three type of error:
|Warning||Indicates a part of the setup may be invalid, but the problem is not serious enough to prevent other parts of the setup from working.||Create a managed entity with no samplers.|
|Error||Indicates an error in a section that will probably result in that section not working correctly.||Create a managed entity without specifying the probe that it should run on.|
|Critical||Indicates an error that will prevent the whole setup from working.||Create malformed XML in the XML editor.|
There are two types of validation that the setup editor performs:
|Schema Validation||These are errors validated against the schema. The Schema includes information about data types, but not relationship between sections. This type of validation always occurs.|
|Gateway Validation||The gateway processes the setup and generates errors based upon the data. This includes checking the relationship between sections. This type of validation only occurs when editing a setup via a Gateway connection.|
The errors are displayed in a table format:
|Type||The type of the error (See 'Error types')|
|Error||An English description of the error|
|Section||The navigation section, if the error has it|
|Source||The validation type. Either 'Schema Validation' or the name of the Gateway for Gateway validation|
|Document||The document (setup) that generated the error|
Double clicking on an item in list will select the relevant section in the navigation, and load the section in the settings editor.
The editor has two search features; Basic Search and Reference Search
To start a basic search, select Tools > Search or press Search open documents in the toolbar. This opens the following:
Type in a piece of text to search for and press Search, this will perform a case insensitive search of the XML.
The Scope dropdown allows you to chose what is searched:
- 'Current Document' is the initial default and means that the whole of the setup you are editing will be searched, including any open include files.
- 'Current Selection' restricts the search to the section of the setup that is highlighted in the navigation pane.
- 'All open documents' means that, if you are editing more than one setup (connected Gateway or directly opened file), they will all be searched.
If 'Case sensitive' is checked, the exact text will be searched.
If 'Regular expression' is checked, the text will be processed as a regular expression.
Unless 'Include disabled items' is checked, the results will exclude items which are disabled or are contained in a section of the setup which is disabled.
The search results are displayed in a table format:
|Document||The document (setup) that contains the search match|
|Section||The navigation section that contains the search match|
Double clicking on an item in list will select the relevant section in the navigation, and load the section in the settings editor.
Disabled items are shown with the section names crossed out, as seen for the managed entities and alert hierarchies in the example above.
The gateways view is a list of all the connections, in the form of Gateways:
You can add new Gateway connections by selecting File->Connect. This will add the connection and automatically open the setup.
You can open a setup for a gateway, by double clicking on the item in the gateway view. If the setup is already open, it will select it in the editor.
The document tabs are at the top of the central editing area:
There is a tab per each open document. Selecting a tab will bring that document to the front, and show the navigation for the document in the navigation view.
To the right of the tab area there are three buttons. The left and right arrows allow you to 'scroll' the tabs along when they are not all visible. The third button shows a list of all the open documents for selection:
Right clicking on a tab will present a context menu. If more than one document is open, you will see this menu:
|Close||Close the document clicked on|
|Close Others||Close all the other documents|
|Close All||Close all open documents|
|Next||Select the next tab|
|Previous||Select the previous tab|
|New Horizontal Group||Splits the document view horizontally|
|New Vertical Group||Splits the document view vertically|
The settings editor is the main area in the centre of the editor:
This section explains how this part of the editor is structured.
The settings are normally sectioned into tabs:
Although every section is different, typically there at least two tabs:
|Tab name||Description of contents|
|Basic||Compulsory and commonly used settings|
|Advanced and Other tabs||Optional settings, used less often|
Indicators are used in the settings editor to indicate if settings are compulsory or optional, and if they are in an invalid state:
This table explains the meaning of the indicators:
|Compulsory||The setting is compulsory, and is in a valid state|
|Compulsory and invalid||The setting is compulsory, and is in an invalid state|
|Optional and not created||The setting has not been created|
|Optional||The setting is optional, and is in a valid state|
|Optional and invalid||The setting is optional, and is in an invalid state|
When a setting is in an invalid state, you can move the mouse over the setting to see a description of the problem:
Optional settings that have not been created are shown 'greyed out':
To create the setting, either right click on the setting and select 'Create <name of setting>' or simply click on the setting component or its label.
The setting will change to look like this:
Once the setting is created, it can be removed by right clicking and selecting 'Remove <name of setting> or pressing the 'X' to the right of the setting.
Some settings have multiple instances, or rows. These setting are presented in a table format:
To add a row to the table, click the 'Add new' link at the bottom of the table.
To remove a row, press the 'X' at the beginning of each row.
Some settings reference named items in the setup (e.g. a Managed Entity references a Probe).
These settings are always combo boxes, and they always have an arrow to the right of the combo box:
To select a reference simply press the arrow to the right of the combo box and select the reference of your choice.
To jump to a referenced item, simply click on the arrow to the right of the combo box:
In some situations you may wish to create a new referenced item from this component. To do so, simply type in a new name (one that is not in use for this type), and press the arrow. You will be presented with a dialog:
Press 'Yes' to create the new item. The editor will create the new item, and select it for editing. Press 'No' to cancel the operation.
In some circumstances there will be more than one possible place to insert the new item. If this is the case you will see a dialog similar to this:
Simply select the location you wish to use and press 'OK'.
Some settings can be Data or Variables. An example of this is the Sample interval of a managed entity: The interval can either be data (an integer value in seconds) or a variable value (which must also be an integer type)
Data/Variable settings always have data or var link directly after the label and before the component:
The link acts a toggle, switching the component between a data and a variable.
A variable setting is reference to a named item elsewhere in the setup (See Referencing 'Named items')
String variable settings are a mixture of string constants, and variables.
String variable settings always consist of a text field, and drop down menu with all the variable values inside:
The Gateway will substitute the variables at runtime, and concatenate the values together.
Define two variables:
Variable 'var1', Type: Integer, Value: 10 Variable 'var2', Type: Boolean, Value: true
String variable value in editor:
The value of var1 is $(var1), and var2 is $(var2)
The Gateway substitutes the values, giving the final string:
The value of var1 is 10 and var2 is true
To show context sensitive help for a setting, right click on the setting and select 'Help':
The XML editor allows you to edit the underlying XML of the setup, bypassing the standard user interface.
To start the XML editor for section, select the section in the main navigation, and then select XML from the combo box at the top right of the setting editor:
The XML editor has several functions, all of which are available from the main toolbar, the XML editor menu, or using the context menu by right clicking in the editor.
These functions are:
|Format||Formats the XML according to a predefined style.|
|Revert||Reverts the XML text to the state it was in when the editor was enabled.|
|Find||Shows a find dialog for performing text searches in the editor.|
|Apply||Applies the current XML to the editor.|
Once you have finished editing the XML, you should apply it to make sure the changes are valid.
You can apply the changes by pressing 'Apply' on the main toolbar, or switching back to normal mode using the combo box at the top right of the setting editor.
If the XML is invalid, you may see this dialog:
You must fix the error before you can save the setup.
In the Find dialog, you can use wildcards or regular expressions in your searches.
To do this, tick the Use box and select Regular Expressions (default) or Wildcards. You can then use the button to the right of the search box to add regular expressions or wildcards to your searches.
After pressing Find, click on the XML editor and use F3 to cycle through your matched items in a search.
The Rule editor is the text area at the bottom of a rule:
The rule editor is a syntax highlighting code editor, for the 'Geneos' language.
The editor has some predefined templates to assist you. To use a template, right click on the editor and then select 'Templates'. The code will be inserted at the cursor position:
The templates are not complete; they require you to modify the code with appropriate values.
Refactoring allows you to globally change the name of a 'named item', and all of its references.
To start refactoring, right click on a 'name item' in the navigation and select 'Refactor'. Alternatively, right click on the name setting in the setting editor and select 'Refactor'.
The Refactor dialog will open:
The dialog is made of two parts; the new name and the items that will be changed. To perform the refactor operation, change the name in the 'New name' field, then select the items you wish to change in the list at the bottom of the dialog. Finally press the 'Refactor' button.
You should see the dialog change. It now displays the number of items that have been refactored.
You can see an example below:
The Refactor dialog will remain open, in case you wish to rename the items again. Press the 'Close' button to dismiss the refactor dialog.
Gateway 2 has file locking mechanism's which can be accessed through the Gateway setup editor.
These features are only available when editing a setup through a gateway connection.
To obtain a lock select Tool->Lock, or press the 'Lock the current document' in the toolbar. If you were able to get lock you will see this dialog:
If the lock was unsuccessful, you will see this dialog:
Note: You cannot obtain the lock twice! If the lock failed you can find out who has the lock by getting lock information (See 'Getting lock information').
If the lock has failed because another user already has the lock, you can Force lock (Tools->Force lock). This will remove the current lock (if any), and obtain the lock.
To release the lock select Tools->Unlock, or press 'Unlock the current document' in the toolbar. You should see this dialog:
If the unlock was unsuccessful, an error will be displayed. You cannot unlock if you do not own the lock, or the file is not locked.
At any time you can get lock information for a setup. To get lock information, select Tools->Get lock information, or press 'Get lock information on the current document'. You will see a dialog like this:
|MainSetupFile||Yes, if the lock is on the main setup file. No if it is an 'include' file|
|Locked||Yes if the file is locked, No if the file is not locked|
|ConnectionId||The internal connection id|
|GatewayId||The gateway id|
|Username||The username of the user who locked the file. ActiveConsoleX indicates an anonymous logon.|
|Workstation||The Hostname or IP address of the workstation that got the lock|
|LockedTime||The date and time the lock was obtained.|
It is possible for another use the 'force lock' a file. This will remove the current lock, if there is any. If you have lock and this happens, you will see the following dialog:
When a gateway is started, it is possible to specify a parameter such that the GSE will automatically take the lock if connected to the gateway. To start the gateway in this mode, launch it with the -autolock parameter.
With the autolock feature running, if the GSE connects to the main setup for the running gateway and the lock is available, the following message is displayed
Users should reply "Yes" to this question if they are planning to possibly update the setup; they should only reply "No" if they are definitely only planning to read and not update the setup. Having replied "Yes", the GSE will load the main setup and will display a message next to the top level to indicate that it is now locked, as illustrated below.
If the GSE attempts to connect to a running gateway with the autolock feature active, and the lock is not available, it will load the setup but will display a message against the top level to show that it is already locked by someone else, as illustrated below.
Note: If gateway authentication is not in use, a more generic message may get displayed such as "Locked by ActiveConsole1".
In this state, the user does not have the lock, and will be unable to write any changes back to the gateway server. However, if you leave the GSE in this state, and the lock subsequently gets released by the other user who was holding it, the fact that the lock is now available will get automatically detected and a message will be displayed saying
If the user replies "Yes" to this question, then the main setup will be reloaded and they will have the lock for it.
Autolocking works in the same way for Include Files. With the autolocking feature active, when the user clicks on an include file to load it, the lock will automatically be taken if it is available. A message will now be shown next to the include file setup to indicate that it is now Locked, as illustrated below.
If, however, another gateway also shares this include file, and a GSE connected to that gateway has already taken the lock on the include file, when the user attempts to load the include file it is still loaded but the user does not get the lock. This is shown by a message next to the include file setup, as illustrated below.
In this state, the user does not have the lock on the include file, and will be unable to write any changes made to the include file back to the gateway server.
Note: The user does still have the lock on the main setup file. The user can still make changes to the main setup file and save them back to the gateway server, they are only restricted from changing the include file.
Having made changes to the main setup, when the user tries to save the changes they will get a message of the form
By replying "Yes" to this message, the main setup changes will be saved.
If the lock on the include file is initially held by someone else, but the other user who was holding the lock subsequently releases it, the fact that the lock is now available will get automatically detected and a message will be displayed of the form
If the user replies "Yes" to this question, then the include file will be reloaded and they will have the lock for it.
Gateway 2 allows you to 'include' multiple files into the main setup. The files are merged by the gateway to produce the overall setup.
To create an include file you must first create the 'Includes' section. Click on includes in the navigation section:
To create an include file, right click on Includes, and select 'New Include'.
An include file is not a 'named item'. The text in the 'name' is actually its location, or path. Type in the path to a file in the location field:
Note: The path is relative to the main setup file location.
Included files are not automatically loaded as part of the main setup. To load a setup, you must expand the include node in the navigation tree, and click on the node 'Click to load...'
If the main setup file was loaded from a gateway connection, the editor will request the include file from the Gateway. If the file was loaded from disk, the editor will attempt to load the include file from disk.
Once the include file is loaded, the structure is the same as the main setup file, and editing is performed in exactly the same way.
A schema is an XML document that describes the content of another XML document. In the case of the GSE, the schema describes the settings that can be configured for the Gateway, along with any Netprobe and Plug-In configuration that is sent to Netprobes.
The GSE reads the schema, and uses it to construct the GUI. This is presented to the user in two places; the navigation and the settings editor. A change in the schema can result in the structure of these components changing.
The schema also contains restriction information, enabling the GSE to validate the input, and provide useful feedback to the user.
A full description of XML Schema is beyond the scope of this manual. For comprehensive description, please refer to http://www.w3.org/XML/Schema
Schemas in the Geneos system are versioned using the same convention as all other Geneos components:
The GSE ships with the latest version of the schema at the date of release, which it uses to create new setup files. Each setup file contains a reference to the schema version and the GSE then uses that working schema version for editing the setup. When connected to a Gateway, GSE will use the schema version that the Gateway uses, however this version may change if the Gateway gets upgraded.
If the schema in GSE is upgraded, new settings might become available, as well as some settings may be hidden due to deprecation. It is recommended to use the version that the Gateway uses.
Once GSE has obtained the latest available version from the Gateway, it will use that version when creating new setups.
The schema version for the active document is displayed in the status bar at the bottom right of the GSE window.
The version status bar can be in these states:
|State||Example Status bar||Description|
|Normal||The document is using the working schema|
|Alternate schema||The document is using an alternate schema, i.e. a schema loaded from disk by the user|
|Incorrect schema||The document is using a different version of the schema than the one specified|
If you move the mouse over the schema version, a tooltip will give you extra information.
In some scenarios it may be necessary to switch to an alternate schema. To do this, go to Schema -> Switch…. You must pick a valid schema from the file chooser.
The dialog will show you the schema version number when you select valid files:
The status bar will change to indicate that you are using an alternate schema:
At any time you can switch back to the working schema by choosing Schema->Switch to working schema.
If you load a setup that was previously saved using an alternate schema, either by you or by another user, then GSE will offer to choose between the current and that special schema.
If the alternate schema is unknown to GSE, it will ask the user to locate that schema on the disk. This can happen if the schema was edited by another user.
The gateway will publish its current schema version, however it may change if the Gateway or a Probe connected to that Gateway is upgraded. If the schema changes while the Gateway's setup is being edited, GSE will show a notification and will offer to load the new schema.
There are a number of startup flags and settings you can define which modify the behavior and configuration of the GSE while it is running. These settings are configured by modifying the GatewaySetupEditor.gci file that resides in the same directory as the GatewaySetupEditor.exe. This file is a text file, so can be edited in any text editor.
The file that is shipped with GSE will look something like this:
############################################################ #### The java class that has 'main' ############################################################ -mainclass com.itrsgroup.gse.GatewaySetupEditor ############################################################ #### The JVM to use and arguments ############################################################ -jvm .\JRE\bin\client\jvm.dll -jvmargs Xmx128M Ddocking.floatingContainerType=frame ############################################################ #### Misc ############################################################ #The jvm depends upon dll's in this directory (e.g. msvcr71.dll) -path JRE\bin -logexceptions -gsedir gse
The file is newline delimited; each flag starts with a hyphen. Any arguments for a given flag are again separated by a newline. Any lines that begin with '#' or are empty are ignored.
#comment1 -<Flag1><Flag1Arg>…#comment2 <Flag2><Flag2Arg>…
Please search the Frequently Asked Questions area on the ICE website.
If you experience problems when using GSE then you can report those using ITRS's helpdesk. Issues can be raise via emailing email@example.com or directly on http://helpdesk.itrsgroup.com/helpdesk/
When creating an issue report 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 below for an example.
On the new issue page this diagnostic file can be connected to the issue report via the 'Upload file' button, see below for an example.
iTrack can also be used to register enhancement requests with ITRS