Configuration attributes

Basic information about SDK plugin configuration can be found in the following article: plugins configuration. Below you find a detailed description for defining plugin configuration fields in the code and how they work in Designer Studio.

PluginConfiguration class

Most SDK plugin types require their base class to be a generic of the configuration class. The only exception is Form Field Extension JS which contains the interface part only. If we use SDK templates for Visual Studio, a separate file with the configuration class is created automatically, and our plugin will a generic of that class. The configuration class, inheriting from PluginConfiguration, allows us to control what the configuration form will look like in Designer Studio. The contents of this class are usually properties which we will reference from the plugin as well as configuration attributes that determine the look of controls in Designer Studio.

Usage in code

Here are examples of action class and configuration class declarations

public class ExampleAction : CustomAction<ExampleConfiguration>
{

}

public class ExampleConfiguration : PluginConfiguration
{

}

In the plugin code we can load in the required values defined in the configuration class. Usually, the user will pass these values using variables (reference tags), but in the code we have access to their evaluated values depending on the environment. If we want to preview what exact values the configuration will have in the moment the code is executed, we can turn on automatic logging. It is available in Designer Studio in the Plugin Packages section. Each plugin has a separate logs configuration in the Logs tab. The logs automatically save the configuration class and its values in JSON format.

Configuration attributes

To streamline the configuration of plugins in WEBCON BPS, certain attributes are available that can be configured as properties of the configuration class. By using them we can influence the interface look in Designer Studio during plugin configuration

Each attribute has a set of properties corresponding to its type, and a part will be the same for all attributes. The shared ones include:

• DisplayName - determines the name of the configuration field in Designer Studio, it’s shown as the label to the left of the control
• Description - can be used to provide a more detailed description that will be available under the Help (i) the right of the control
• IsRequired - marks the field as required, this field will have a red asterisk next to it (*) and the user will be informed of it being required when attempting to save
• DescriptionAsHTML - Boolean marker, if set to TRUE, it will interpret all html tags in the description
• DefaultValue - available for most attributes, can be used to enter a default value, the type will depend on the type of attribute

These attributes determine how data is passed during plugin configuration, but the data type in the code is defined by the property type for which the configuration attribute is used. Therefore, one should remember that if the value passed through the configuration does not match the property type, we will receive a conversion error when executing the plugin. Additionally, if we want to pass a value from a form field, and there is a possibility that this form field will be empty – we need to prepare for this by using a nullable property type.

ConfigEditableText

The most commonly used attribute that allows the person configuring the plugin to enter any string of text. They are able to pass variables (reference tags) whose values will be substituted based on the context in which the plugin is executed.

Additional properties:

• IsPasswordField - text entered during configuration will be masked, and the value will be encoded. The control will only show asterisks. When executing the plugin the value will be decoded.
• Multiline - increases the number of rows of the configuration field, setting it to TRUE will give us 3 rows of text by default
• Lines - determines the number of rows for Multiline
• ReadOnly - field will be in read-only mode, it will show the value returned by the property or the default value
• MaxLength - determines the maximum number of characters that can be entered here
• NullText - grayed out text displayed for an empty field value
• TagEvaluationMode - enum determining the mode in which variables will be substituted. The available options are:
  • Default - standard mode of substituting variables
  • None - variables will not be substituted
  • SQL - replaces variables and escapes them in SQL mode, used practically for all SQL queries
  • JavaScript - converts variables to format #123#, which allows for requests to be passed e.g. in JSON format

ConfigEditableBool

In Designer Studio this field appears as a checkbox. Since it cannot be used to pass dynamic values via variables, it is most commonly used for static toggles like expanded logging, different mode for the plugin etc.

ConfigEditableConnectionID

Attribute used to designate a connection defined in Designer Studio. It contains an expandable tree with all available connections. In the code we will get the ID of the chosen connection. Used in conjunction with the tool class ConnectionsHelper we can load all necessary data for connections without reconfiguring them from scratch inside the plugin. Additionally, ConnectionsHelper takes into consideration dev/test/prod settings so that we always get the correct data.

Additional property:

• ConnectionsType - filter allowing us to narrow down the available connection types to specified ones. We can join types with the standard operator e.g.: DataConnectionType.WebServiceREST | DataConnectionType.WebServiceSOAP

ConfigEditableDataSourceID

Analogous to the attribute for connections, but operates on data sources instead. It contains an expandable tree with all available data sources, and the ID of the chosen source in the code. For further operations on the ID of a source we can use DataSourcesHelper and ConnectionsHelper classes.

Additional property:

• SourcesType - filter allowing us to narrow down the available data source types to specified ones

ConfigEditableDateTime

Control for selecting the date and time, can be used to pass a static date value. Rarely used just like the ConfigEditableBool attribute. It is more common to dynamically pass the date with a ConfigEditableText attribute and a variable that references a “Date and time” form field.

Additional properties:

• ShowDate
• ShowTime - Boolean value, both set to True by default. Used to toggle parts of the control.

ConfigEditableDouble

ConfigEditableInteger

Two attributes that work almost identically, but one can only be used to set integers. The control limits the user to numerical values. If you need to pass a value that depends on the context, replace with a text attribute and a variable referencing a number in the correct format.

Additional properties:

• MinValue
• MaxValue - fields which determine the upper and lower limits of the value that the user can enter

ConfigEditableDropDownList

Dropdown control from which one value can be selected.

• DataSourcePropertyName - a required parameter where you pass the property containing a table of available values

Due to the very specific way of how this attribute is implemented, as shown below, it is often replaced with the analogous ConfigEditableEnum control.

public DropDownListItem[] DdlItems => new DropDownListItem[] 
        { 
            new DropDownListItem("1", "Value1"), 
            new DropDownListItem("2", "Value2"), 
            new DropDownListItem("3", "Value3") 
        };

[ConfigEditableDropDownList(DisplayName = "Sample dropdown list", DataSourcePropertyName = "DdlItems")]
public string DropList { get; set; }

ConfigEditableEnum

A control which looks and behaves just like ConfigEditableDropDownList, but with the caveat that this attribute must be applied to a property returning an enum. The list will show the enum values during configuration.

ConfigEditableFormFieldID

Attribute whose control displays a choice tree (identical to a “Choice tree” form field) from which you select a value. Similarly to connections and data sources, in the code we get an int with the ID of the selected value.

Additional property:

• FormFieldTypes - filter limiting the tree to only selected types of attributes

ConfigEditableTranslationsList

Attribute which is used by the user to translate phrases into chosen languages. It is most commonly used to translate notifications or control labels. The property type must be a class containing ConfigEditableTranslation attributes. We will get correctly translated phrases depending on the user profile language in the code runtime, or the default phrase if there is no language match. Additional properties:

• AdditionalCultures - parameter defining additional cultures can be selected for translations. It accepts a string with culture acronyms separated by semicolons e.g.: en-US;pl-PL

• ConfigEditableTranslation Attribute related to the previous one, used to enter a singular phrase to translate. It must be used in a class using the attribute: ConfigEditableTranslationsList. DisplayName determines what the user should translate. DefaultTranslation can be used to set a default translation that can be edited in Designer Studio.

ConfigEditableGrid

Attribute used to create a custom grid for some of the more involved configurations e.g.: mappers. It should be applied to a List type property from the class that will also contain specific column definitions.

Additional properties:

• TagEvaluationMode - – works identically to ConfigEditableText, it affects the mechanism of substituting variables for all text columns on the grid.

[ConfigEditableGrid(DisplayName = "Sample grid", TagEvaluationMode = EvaluationMode.SQL)]
public List<GridColumns> SampleGrid { get; set; }

public class GridColumns
{
    [ConfigEditableGridColumn(DisplayName = "Sample column)]
    public string SampleColumn { get; set; }
}

• ConfigEditableGridColumn – most basic grid column used for entering any text or variables
• ConfigEditableGridColumBoolean
• ConfigEditableGridColumnDropDownList
• ConfigEditableGridColumnEnum
• ConfigEditableGridColumnFormFieldID – columns that are direct analogues to their non-grid variants

This attribute also allows you to specify default values. They will be displayed when you first configure them in the studio, and also returned in runtime if the configuration was not run. To do this, simply initialize the list in your code, as in the example below:

[ConfigEditableGrid(DisplayName = "Sample grid", TagEvaluationMode = EvaluationMode.SQL)]
public List<GridColumns> SampleGrid { get; set; } = new List()
{
    { SampleColumn = "Sample first row value" },
    { SampleColumn = "Sample second row value" }
};

public class GridColumns
{
    [ConfigEditableGridColumn(DisplayName = "Sample column)]
    public string SampleColumn { get; set; }
}

ConfigEditableItemList

Attribute used to map Item list columns. The control in Designer Studio is made up of two parts: a dropdown from which an Item list form field is chosen, and a grid with available columns. This attribute has two variants, depending on the class it is applied on. This class can implement one of two interfaces:

IConfigEditableItemList

Basic version of the attribute, the interface gives access only to the item list id. Used to map list columns to values ​​predefined in the code. This interface supports the use of one type of attribute in a class:

• ConfigEditableItemListColumnID Attribute related to ConfigEditableItemList, and must be used in its class. In Designer Studio it will appear as a row of a grid, the left column will contain the DisplayName value, and the right will contain a choice tree with available list columns.

[ConfigEditableItemList("Item list mapper")]
public ItemList ItemList { get; set; }

public class ItemList : IConfigEditableItemList
{
   public int ItemListId { get; set; }

   [ConfigEditableItemListColumnID("First column")]
   public int? FirstColumnId { get; set; }

   [ConfigEditableItemListColumnID("Second column")]
   public int? SecondColumnId { get; set; }

   [ConfigEditableItemListColumnID("Third column")]
   public int? ThirdColumnId { get; set; }
}

IConfigEditableItemList<T>

A generic version of an attribute that combines the advantages of a grid and a list. This interface provides access to the id of the item list, as well as to a collection of objects that may contain the following attributes:

• ConfigEditableItemListColumnID
• ConfigEditableItemListText An attribute that allows the configurer to enter any value, which, combined with the ability to select a column, should satisfy most item list value mapping scenarios.

 [ConfigEditableItemList("Item list mapper")]
 public ItemList ItemList { get; set; }

public class ItemList : IConfigEditableItemList<ListRow>
{
    public int ItemListId { get; set; }
    public List<ListRow> ListColumns { get; set; }
}

public class ListRow
{
    [ConfigEditableItemListColumnID("ColumnId")]
    public int? ColumnId { get; set; }

    [ConfigEditableItemListText("ColumnText")]
    public string ColumnText { get; set; }

    [ConfigEditableItemListText("Second ColumnText")]
    public string ColumnText2 { get; set; }
}

ConfigGroupBox

Grouping attribute, allows us to bundle together some of the configuration fields into an expandable list. Placed in a class that should contain a property with any field attributes.

Additional property:

• Order - int value that determines the order in which groups are displayed

ConfigStudioTranslation

Attribute for setting the translations of names and descriptions of other attributes via configuration control in Designer Studio. Should be placed above another configuration attribute, and should be used again for each translation.

Additional property:

• TranslationCulture - enum for selecting the language culture to which the translation refers, the three available languages for Designer Studio can be selected: plPL, enUS, deDE

[ConfigStudioTranslation("Basic text attribute", "Description of the text attribute. The default descriptions are in Polish.", TranslationCulture.enUS)]
[ConfigStudioTranslation("Grundlegendes Textattribut", "Beschreibung des Textattributs. Die Standardbeschreibungen sind in Polnisch.", TranslationCulture.deDE)]
[ConfigEditableText(DisplayName = "Podstawowy atrybut tekstowy", Description = "Opis atrybutu tekstowego. Domyślne opisy są po polsku.")]
public string BasicText { get; set; }