UI Configurations allow the user to define the fields available on certain configurable UIs. RED stores any data captured in these fields and treats it like any other object metadata, making it available to all automation aspects of the tool.
Configurable UI’s
Connection Properties: Allows configuration of fields on the Connection Properties page, set and used in creating an Extensible Source Connection.
Load Table Properties: Allows configuration of fields on the Source page of Load Table Properties, used as the UI Configuration when sourcing from an Extensible Source Connection where this configuration is set.
Column Properties: Allows configuration of fields on the Column Properties page, set on a Target Connection and applied for any table residing on that Connection’s Targets.
Configurations Maintenance
The UI Configurations actions are located under the Tools menu. The UI Configurations menu action items are:
- Maintain UI Configurations
- Load UI Configuration: Select this option to load a UI configuration from file.
- Export UI Configuration: Select this option to export a UI configuration to file.
To maintain UI Configurations select Tools > UI Configurations> UI Configurations Maintenance.
Click New... to create a new UI Configuration.
- In the Edit UI Configuration window, enter a Name for the UI Configuration.
- Add a Description of UI configuration.
- Select the Configuration Type among ConnectionProperties, LoadTableProperties, and ColumnProperties.
- Click OK to proceed to the Field Configuration JSON where a sample field configuration is created to get you started.
- Click Copy... to copy an existing UI Configuration. Edit the name and it creates a new copied configuration under a new name.
- Edit.., opens the configuration in the editor to view or edit the configured fields.
- Click Rename to update the Configuration name.
- Click Delete to remove any listed UI Configuration, deletion is prevented for configurations in use.
Referencing a configured field’s metadata
There are three ways to reference the metadata set in configured fields:
Token replacement in scripts
In Scripts of Objects which have an association to an Extensible Source Connection you can reference any configured field from the connection in the script using the following token format which will be replaced at run-time:
$WSL_SRCCFG_<cofigured_field_name>$
Environment variables in scripts
In Scripts of Objects which have an association to an Extensible Source Connection, when a configured field has the attribute “setEnvVarForScripts” = TRUE then the environment variable RED exposes at run-time takes the following form:
WSL_SRCCFG_<cofigured_field_name>
Templated code generation
The following pebble syntax can be used in templates to reference the metadata stored in configured fields, replace <field_name> with the field name in your configuration. The full pebble examples can be generated through the Template Editor using the ‘Tools’ menu ‘Create API Example Template’. Configured fields are available as a key:value array.
For Extensible Source Connections:
table.loadInfo.sourceConnection.uiConfigFields.<field_name>
For Load Tables:
table.loadInfo.uiConfigLoadProperties.<field_name>
For Columns:
column.uiConfigColumnProperties.<field_name>
Field Configuration JSON
The UI Configurations allow you to add user-defined UI components including List boxes, Text boxes, and Numeric fields to certain properties pages in the UI. The table below lists the required common and specific attributes of each UI component. Example configurations follow the table:
| Options | Applicable Configs | Description |
|---|---|---|
| description | ALL | Add a description for the field which will be displayed on mouse-hover and in the bottom description pane of the connection. |
| displayName | ALL | Add the name that is displayed in the configuration field. |
| documentation | ALL | If the connection is part of documentation and the value is set to "true", therefore it adds this attribute to the generated documentation. |
| encryption | CONNECTIONS | Optional encryption settings when persisting the field value to the database: (add bullet points for these) 'none' : the value will not be encrypted. 'wherescape' : the value will be encrypted by RED and decrypted as required. 'external' : equivalent to 'none' but allows you to flag that values have been encrypted externally. This option is required, if you do not add a value in this field, you get an error message. |
| group | ALL | Add a group name for the configuration attributes. |
| masked | CONNECTIONS, COLUMNS | Set the value to "true" to mask the value. |
| order | ALL | Set the order value for the created groups. |
| page | ALL | The UI configuration is being applied under the Properties page. |
| required | ALL | If this value is set to "true", the field must be filled in; otherwise, a message stops you to close the dialog, after clicking OK. |
| setEnvVarForScripts | CONNECTIONS | If the value is set to "true", it allows you to access your environment variable with the token name, which is found under the description field. For example: |
| textBoxSettings | ALL | "default": Any created field can have a default. When you save a value as the default, that value is saved to the metadata for that particular connection. "length": Number of characters that you can type in the field. "multiLineEdit": The "False" value is set by default. This field is applicable for future use. |
| listViewSettings | ALL | "defaultListItem": When the value is '0' the field is blank. "editable": Set to "true" when the field will be editable. "list": Enter the list of items you want to display in the configuration field. "listMessage": This message displays when you hover the mouse on the field. |
| numericSettings | ALL | "default": The default value field. |
| type | ALL | Describes the type of the configuration field. The type goes along with the textBoxSettings, listViewSettings, and numericSettings with the specifics described above. |
Text Box Example
If you want to use the example below for Column or Load Table UI Configurations you have to remove "setEnvVarForScripts" and "encryption"
"uiConfigFields": [
{
"description": "For token replacement in scripts use:\r\n $WSL_SRCCFG_simpleTextBox$",
"displayName": "Simple text box",
"documentation": false,
"encryption": "none",
"group": "Example Text Box Fields",
"masked": false,
"name": "simpleTextBox",
"order": 100,
"page": "Properties",
"required": false,
"setEnvVarForScripts": false,
"textBoxSettings": {
"default": "This is my default file c:\temp\text.txt",
"length": 256,
"multiLineEdit": false
},
"type": "textBox"
},
{
"description": "For access at runtime use environment variable: WSL_SRCCFG_encryptedTextBox",
"displayName": "Encrypted and masked text box",
"documentation": false,
"encryption": "wherescape",
"group": "Example Text Box Fields",
"masked": true,
"name": "encryptedTextBox",
"order": 200,
"page": "Properties",
"required": true,
"setEnvVarForScripts": true,
"textBoxSettings": {
"default": "This is my default",
"length": 256,
"multiLineEdit": false
},
"type": "textBox"
},
List View Example
{
"description": "For token replacement in scripts use: $WSL_SRCCFG_simpleListView$",
"displayName": "Simple list view",
"documentation": false,
"encryption": "none",
"group": "Example List View Fields",
"listViewSettings": {
"defaultListItem": 3,
"editable": false,
"list": [
"My list item one",
"My list item two",
"My list item three",
"My list item four",
"My list item five"
],
"listMessage": "Select an item from the list"
},
"masked": false,
"name": "simpleListView",
"order": 300,
"page": "Properties",
"required": false,
"setEnvVarForScripts": false,
"type": "listView"
}, {
"description": "For token replacement in scripts use: $WSL_SRCCFG_editableListView$",
"displayName": "Editable list view",
"documentation": false,
"encryption": "none",
"group": "Example List View Fields",
"listViewSettings": {
"defaultListItem": 0,
"editable": true,
"length": 256,
"list": [
"My list item one",
"My list item two",
"My list item three",
"My list item four",
"My list item five"
],
"listMessage": "Select an item from the list or type your own value"
},
"masked": false,
"name": "editableListView",
"order": 300,
"page": "Properties",
"required": true,
"setEnvVarForScripts": false,
"type": "listView"
}, {
"description": "For token replacement in scripts use: $WSL_SRCCFG_booleanListView$",
"displayName": "Boolean list view",
"documentation": false,
"encryption": "none",
"group": "Example List View Fields",
"listViewSettings": {
"defaultListItem": 1,
"editable": false,
"list": [
"TRUE",
"FALSE"
],
"listMessage": "Set something True or False"
},
"masked": false,
"name": "booleanListView",
"order": 400,
"page": "Properties",
"required": false,
"setEnvVarForScripts": false,
"type": "listView"
},
Numeric Fields Example
{
"description": "For token replacement in scripts use: $WSL_SRCCFG_numeric$",
"displayName": "Simple numeric field",
"documentation": false,
"encryption": "none",
"group": "Example Numeric Fields",
"masked": false,
"name": "numeric",
"numericSettings": {
"defaultValue": 999
},
"order": 500,
"page": "Properties",
"required": false,
"setEnvVarForScripts": false,
"type": "numeric"
}