Gateway Setup Editor

Standalone

To start the GSE standalone, run the GatewaySetupEditor.exe located in the directory you installed or unzipped the files in.

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.

On Windows, the GSE uses a single GatewaySetupEditor.gci regardless of whether the GSE is opened from the Active Console, or as a standalone application.

On macOS, the GSE uses two separate GatewaySetupEditor.gci files:

• If opened from the Active Console, the GSE uses the GatewaySetupEditor.gci from the Active Console directory.
• If opened as a standalone application, the GSEuses the GatewaySetupEditor.gci from the Gateway Setup Editor directory.

From the Active Console

The GSE can run from within the Active Console.

To launch the GSE without opening a setup, go to Tools > Gateway Setup Editor.

To open an existing Gateway configuration, use one of the following methods:

• Select Configure gateway from the toolbar, then select a Gateway and press OK.
• Right-click a Gateway and select Configure gateway.
• Double-click a Gateway in the Gateways view.

When you run the GSE from the Active Console, it adopts all the arguments passed to the Active Console from the ActiveConsole.gci file.

The GSE can be configured to launch as a separate process from the Active Console using the Gateway setup editor as a separate process advanced setting. See .

Open Gateway setup files from disk

Gateway setup files are XML files, and can be opened from any accessible file location. To do this , 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.

Open Gateway setups via a Gateway

When running the GSE standalone you can open a setup directly via a Gateway connection. The GSE 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:

1. Go to File > Connect, or click the Connect to Gateway on the toolbar.
   • This opens the connection dialog.
2. Use the drop-down to select the Logon type.
3. In Host, enter the host or IP address of the Gateway.
4. In Port, enter the port of the Gateway.
5. If it is a secure connection, tick the box by Secure.
6. Press OK.

The editor attempts to connect to the Gateway and requests the setup.

If successful, a new Gateway entry is added to the Gateways view.

To remove a Gateway connection, see Removing gateway connections.

Save and close setups

The menu structure

The following menu options are available in GSE:

• File
  • New — Create new setup file.
  • Open — Open an existing setup file from disk.
  • Close — Close the current setup file.
  • Connect — Connect to a Geneos Gateway.
  • Save — Save the current file.
  • Save as — Save to a new location on disk and continue editing that file. All passwords that are not plaintext are removed from the saved file. This drops the current Gateway connection.
  • Export — Export copies of the main setup file and all loaded include files to a new location on disk. All passwords that are not plaintext are removed from the saved file. After exporting, you are continuing to edit the setup of the connected Gateway.
  • Replace contents — Replace the active document with the contents of another setup from disk.
  • Reload — Reload the current document. This will revert to the last save point.
  • Load all includes — Load all the included files.
  • Load running setup — Open a read-only copy of the current setup of the connected Gateway in a new editor tab.
  • Exit — Exit the setup editor.
• Edit
  • Copy — Copy the current selection in the navigation.
  • Paste — Paste a previously copied item into the current selection in the navigation.
  • Rename — Rename the current selection in the navigation (Named items only).
  • Delete — Delete the current selection in the navigation.
• View
  • Show/Hide empty sections — Toggles the 'show' mode of the navigation tree.
  • Back — Moves back in the navigation tree history.
  • Forward — Moves forward in the navigation tree history.
  • Search results — Shows the Search results dockable.
  • Errors — Shows the errors dockable.
  • Navigation — Shows the Navigation dockable.
• Schema
  • Switch... — Switch the schema for the current document to a specific schema.
  • Switch to working schema — Switch to the 'working' schema, after having used 'Switch schema'.
• Tools
  • Search — Opens the search dialog.
  • Advanced Search — Opens the advanced search dialog.
  • Validate — Validates the current document.
  • Lock* — Sends a request to lock the current document.
  • Force Lock* — Sends a request to force lock the current document.
  • Unlock* — Sends a request to unlock the current document.
  • Force Unlock* — Sends a request to force unlock the current document.
  • Get Lock information* — Sends a request for lock information about the current document.

• XML Editor
  • Format** — Format the XML
  • Revert** — Revert the XML to the first state
  • Find...** — Show the find dialog for the XML Editor
  • Apply** — Apply the XML to the document

• Help
  • 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 Start up settings.

How to create sections

To create a section that has not been created, click Actions > New Action in the Navigation section.

How to create named items

Named items can be created in many different sections in the setup. To create a named item, right- click on a section to show the context-sensitive menu. Select the type of item you wish to create. The items will be added at the bottom of the section, and the item will be loaded into the settings editor.

How to change the name of named items

To change the name of a named item, you can do any of the following:

• Right-click on the item and choose Rename.
• Double-click the item.
• Select the item and press F2.

The item text will become editable, and the text can be changed

To commit the changes you have made, press Enter , or click somewhere else in the editor. To revert the change, press Escape on keyboard.

How to change the order of named items

Named items can be moved within each section. To move an item up or down, right click on the item you wish to move, and select Move up or Move Down. Alternatively you can use Alt+↑ or Alt+↓ respectively.

You can also sort named items alphabetically in a section, by right clicking on a section and selecting Sort -> Ascending or Sort -> Descending.

How to delete sections and named items

To delete any section, you can do any of the following:

• Right-click on the item and select Delete.
• Press the Delete selection button in the toolbar.
• Press Delete on your keyboard.

How to move named items

The order of the sections is fixed, however 'Named Items' can be moved around in the setup within each section.

Some named items can be moved within a section or to other sections by using drag and drop:

1. Drag the item in question to the target section. If the item cannot be moved to the section, the cursor changes to indicate the move is not permitted.
2. If you drag using the right mouse button, you are presented with a context menu when you release the button:
   
3. Select Move Here to move node, or Cancel to abort the move.

How to copy named items

There are several ways to copy named items within a section or to other valid sections:

1. Clicking using your mouse:
   1. Right-click the item and select Copy.
   2. Right-click on the target location and select Paste.
   
   

   Note: Paste only shows if the target location is valid for the copied item.

2. Dragging and dropping using your mouse:
   1. Drag the item in question to the target section using the right mouse button.
      • If the item cannot be copied to the section, the cursor will change to indicate the move is not permitted.
   2. Select Copy Here to copy the item, or Cancel to abort.
3. Using your keyboard:
   1. Select the item you wish to copy, and press Ctrl+C.
   2. Select the target node and press Ctrl+V.

When copying a Named item as a child of the same parent, the editor changes the name of the new item to 'Copy of <original name>' where <original name> is the name of the item being copied. If the item is being copied to a different parent, the 'Copy of' prefix is not used.

If this name already exists, the editor appends a number on the end (1, 2, 3 etc) until it finds a name that is not in use.

How to copy named items via the system clipboard

When you right click a named item, there is also a Copy XML option. This copies the XML representation of the item (as you would see in the XML editor) to the system clipboard. This is the same as if you opened the item in the XML editor, pressed Ctrl+A (Select All), and then Ctrl+C. You can also do this by selecting an item and pressing Crtl+Shift+C.

If the system clipboard contains well-formed XML representing a single named item and you select a section or item that is a valid parent for that item, the right-click menu contains a Paste XML item and the Ctrl+Shift+V keyboard shortcut is enabled. If you use the Paste XML menu item or Ctrl+Shift+V shortcut, a named item will be created using the clipboard content.

If the name specified for the item in the XML already exists, a number will be appended to make the name unique.

If the XML used contains errors (well-formed XML but not valid according to the schema), these will be indicated in the same way as if invalid XML had been entered into the XML editor.

Note: Copy XML and Paste XML are only provided for named items, not for top-level sections such as 'Samplers' or 'Rules'. You can only copy or paste one item at a time as XML.

The XML which is copied and pasted is a single element, not a complete XML document - it does not start with <?xml version="1.0" encoding="ISO-8859-1"?>.

How to disable and enable named items

Named items in the setup can be disabled. When a named item is disabled, the Gateway ignores it. Disabling named items allows you to remove it from the setup without deleting it.

To disable an item in the navigation, right-click on the item and select Disable. Alternatively, select the item and press Ctrl+D on the keyboard.

To enable an item in the navigation, right-click on the item and select Enable. Alternatively, select the item and press Ctrl+D on the keyboard.

Disabled items are displayed as strikethrough text in the Navigation section:

Quick Filter

The quick filter allows you to hide items, or filter them out.

To enable the quick filter, right-click on the navigation and select 'Quick Filter'. The filter appears at the top of the component:

Simply type some text into the text field, and the tree will be filtered according to the text:

The tree will hide any items that do not match the text and do not contain any items that match the text. Items that do match will be in bold.

To disable filtering, press the red cross button to the left of the filter, or right click on the tree and select 'Quick Filter'.

Error Highlighting

When you perform a validate command (See Errors Dockable), the location of the errors will be highlighted in the navigation:

Any node highlighted indicates an error in that section, or an error in some child section. In the above diagram, 'ProbeWithErrors' has an error, so all of its parent nodes are highlighted.

Filtering errors

You can filter errors by navigation sections to make it easier to view the errors in individual sections. Tick the Filter check box on the right of the information bar.

When you change the selection in the navigation, the errors list changes to show only those errors that are part of the setup.

Basic 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.

Jumping to and creating referenced items

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 to create the new item.

Comments on names

When setting the comment on the name of a 'named item', the comment will appear at the top of the editor:

Templates and Code assistance

The editor has some predefined templates to assist you. To use a template, right-click the editor and then select Templates. The code will be inserted at the cursor position in the rule editor.

The templates are not complete; they require you to modify the code with appropriate values.

Fixing errors

If your rule code contains errors you will not be able to save the setup. You must fix any code errors first.

Errors are indicated in two ways in the rule editor:

Errors are underlined in the text, and they are indicated in the error bar on the right hand side.

Determining Schema Version

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.

Switching to Alternate Schema

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 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.

Loading Setup with Alternate 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.

Gateway Schema Change

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.

Deprecated settings

When GSE schema is upgraded, some settings may be hidden due to deprecation unless they already have a value. To view all the deprecated settings anyway, choose View > Show deprecated. All such settings will be marked with a warning sign.