Global Variables

(New in version 15)

Globals are variables accessible to multiple channels within Connexion. Global variables can be scoped to allow access to a specific set of channels:

• System: Available to all channels in the system. Global code is only defined at the system-level.
• Group: Available to all channels in the given group.
• Tab: Available to all channels in the given tab.

Currently, the following types of globals are supported:

• Global Code: A single custom code editor / assembly which can be referenced by any other custom-code based device in the system. There is always a single system-level global code entry.
• Variable: an arbitrary string.
• Password
• Map Table: Uses the familiar map table UI to define and expose map tables to all supporting devices. Global map tables are also exposed to custom code.
• SQL Connection: Define a global SQL connection string which can be referenced by the built-in SQL connection UI or by custom code. 

While the Global Code, Password, Map Table, and SQL Connection all use specific user interfaces, the global variable uses well-known string format valid in any string-based control. The format is:

{Scope.VariableName}

Where the scope is either System, Group, or Tab. For example, if all channels within a specific tab should write files to a specific folder, you could enter the string {Tab.TargetFolder}. Even though the file writer device doesn't have any special handling for global variables, the underlying configuration will automatically be updated to replace the text {Tab.TargetFolder} with the corresponding global variable (named 'TargetFolder' and defined in the tab containing these channels).

Navigate to the globals UI by selecting the system configuration icon followed by the Globals tab:

The globals UI has two panes. In the left-pane is a tree showing all groups and tabs as well as any associated global variables. The top node ('Global (System-wide)') contains system-level variables. The right-hand pane displays a UI for editing the global value. In addition to the toolbar buttons, there are context menus for managing each variable. These allow you to:

• Create a new global (select the corresponding scope first - System, Group, or Tab).
• Delete a global (select the global to be deleted).
• Refresh the global value (if it has been changed by another user).
• Find channels referencing the selected global.
• Export the selected global to disk.

Like channels, global must be locked in order to be edited. Use the familiar lock icon (or ctrl + enter keys) to toggle between locked and unlocked states:

Devices which reference one or more globals display a globe icon overlayed on their primary icon. A blue globe icon is also displayed in the device bar. Click this icon will bring up the globals editor filtered to display only the globals referenced by this device.

Note that globals can be imported and exported across Connexion systems:

When importing a global, it is important to choose the correct parent/scope. Right-click on the System node or appropriate group or tab node and select the Import item:

Scoping / Channel Usage

To view which channels are referencing a particular global, right click the global and select the 'Find Usage' option:

This displays the usage dialog, which helps explain the idea of using global variables with the same name, but scoped to different tabs or groups. In the image below, you can see that there are two group-level variables named 'CustomerServer'. One is defined under the 'Default Group' and the other under 'Saint Joseph's'. In the usage dialog under the 'Global Value' column, you can see that each global has a different value (one is NickWork-PC, the other is localhost). When channels in the Default group are loaded, any instances of {Group.CustomerServer} are replaced with 'NickWork-PC', whereas channels in the Saint Joseph's group will have 'localhost' injected. We could copy the channels from one of those groups into a new group, and the only required editing would be to add the correct value for the {Group.CustomerServer} global. This makes porting sets of channels between groups or tabs very easy.

Global Variables

Global 'variables' are globals with an arbitrary string type. They have special support within Connexion in that they can be used in any text-based control backed by a string property. For example, if you wanted to define a customer's FTP server address as a global variable, you could open the corresponding file writer device and simply type {Group.FtpAddress} into the 'Host' textbox:

As soon as you type the closing '}', the text should be recognized as a global variable and become highlighted. In this case, no global variable named 'FtpAddress' has been defined, and so it highlights red. Hover your mouse over the red rectangle to display the global details popup, and then click the magnifying glass icon.

The global ui editor will be displayed in a popup window with the new global variable automatically added. Enter a value in the right-hand editor and save the global. Note how the red rectangle has changed to grey to indicate the global is valid.

If you hover your mouse over the grey rectangle, the popup will now display the current value of the global.

If you have at least one global variable defined in the current scope (current tab, group, or system), then a menu item displaying valid global variables will display after typing {Tab. , {Group., or {System.:

You can select an existing global variable and hit the enter key, or hit the escape key to continue typing. Note that global variables can co-exist within other strings:

They can even be used within custom code:

Global Code

Global code provides a central place to provide common functionality and resources. It is analogous to having an easily editable and deployable common assembly referenced by one or more custom-code-based devices within Connexion. If you find yourself re-creating the same functions in many different devices, adding references to a common resources, or defining the same class-level variables, then Global Code may be useful for you.

While this is quite a powerful piece of functionality, it can also be dangerous. Under the covers, every custom-code-based device which references the global code will get recompiled if a change to the global code is detected. If you change a method signature used by many different devices, those devices may cease to compile and channels will no longer start. When editing global code, you must be cognizant of how it may effect other devices.

There is only 'global code', which is scoped to the system level. Editing the global code is exactly the same as editing any other custom code device, and you have access to the typical custom code feature set. For example, if we wanted a centrally defined sql connection, we could write a function like this:

To use this function, we need to explicitly add a reference to the global code. Click the black global icon and select the 'Include Global Reference' option.

Once the reference is added, the globe icon turns blue and the 'Global' keyword can be used to reference the global class. Intellisense should display all available public members:

As mentioned in the previous section, in some scenarios you can also use the '{Scope.GlobalName}' syntax directly within your code. In this case, a connection string as added as a global variable:

And then referenced in code using the standard syntax:

This method may not work if the value you are injecting contains unescaped double quotes.

Global Passwords

Global passwords are available to any UI hosting a core:PasswordBoxEx control (the password control used in Connexion). Enter a new password into the globals UI editor:

On a password control, click the '{ }' icon and select the desired password:

The password control will then display the standard global syntax as well as display the standard global variable popup when hovered.

Global Map Tables

Global map tables allow a single map table to be consumed by many devices, making the management of common tables much easier. The standard multi-column map table UI is used to define your map table, which are then available to custom-code-based devices as well as most devices which natively support map tables (HL7 transform v2 device). Please see the map table documentation to review how to configure map tables.

Global map tables should automatically be displayed in the HL7 transform (and related) devices:

Global map tables can also be accessed in custom code. Please note that you should never cache a global map table - always retrieve the full map table object.

Global SQL Connections

Global SQL Connections are available to any core:DatabaseConnectionControl control (used mainly be device developers targeting SQL Server). Add a new global connection string and enter the connection details. Use the 'test connection' button to verify the connection string is correct.

Reference this connection string by clicking the globe icon and selecting the desired global connection.

The UI will change to display the details of the global connection string, as well as provide options to test the connection, edit the connection string, or revert back to a connection string just for the given device.