Using Automation Tasks Library Settings#

Tasks typically have a set of settings that inform you of the behavior of the task. These fields may also be defined with the use of Automation Task Library.

Concepts of a Task setting:

The settings are represented by a Json object using a tree format with the following structure:

Tab
- Section1
  - Setting
  - Setting
  - Setting
- Section2
  - ...

For both Tab and Section, the key of the object will represent the text. They act as a way to organize how the settings are shown.

Example:

{
  "General": {
    "Settings": [
      {
        "..."
      }
    ]
  },
  "Inputs": {},
  "Outputs": {},
  "Code": {}
}

Note: If the section is a string instead of an array with settings, then the GUI will render an information block without any settings.

AutomationTaskSettings#

Property	Description	Notes
Name	Name of the setting	Mandatory, Unique, String
DisplayName	Text to display in the GUI, defaults to Name if not defined.	Optional, String
SettingKey	Key of the settings where the value will be stored. Must be unique within the entire set of settings in the task.	Mandatory, String
IsMandatory	Flag indicating if this setting must be filled.	Optional, Boolean, defaults to false
EnumValues	List of possible values when the Type is Enum. Use object if the display value and the value are different. The display value is the key, the value is the value. Note: This key is left here for compatibility reasons, but it should be deprecated. This field should be used inside the Settings object.	Optional, list of strings or Object
InfoMessage	Text to display in the hint box when hovered.	Optional, String
InfoMessageBlock	Text to display in the hint box when hovered using a block HTML view where the text can be formatted with new lines, tabs, etc.	Optional, String
DefaultValue	Value to use as default.	Optional, any
Condition	Expression (MathJS) that will be parsed to identify if this setting is to be displayed. Example: `timerType != null && timerType != "CronJob"`	Optional, string
Settings	Extra settings to use to model the behavior of the field. These settings are different per control to use.	Optional, Object
PropertiesToSave	Optional setting to define the properties to store in the settings if the value is an object. Can define sub-objects. Example: `[“$type”, “name”]` Note: Subfields are not supported. To achieve that use the BeforeSave trigger scripts.	Optional, Array of Strings

What type of settings are available?#

For the settings types, there are simple types like String, Boolean, Integer, etc. However, there are some complex types that need special attention. In addition, the Automation Task Library supports executing Scripts.

AutomationTaskSettings - DataType#

DataType	Property	Description	Notes
Lookup	TableName	Name of the table to use for this lookup (must be a Lookup table).	Mandatory, String
	OnChange	Script to execute when the value changes.	Optional, AutomationTaskScript
Enum	EnumValues	List of possible values when the Type is Enum. Use object if the display value and the value are different. The display value is the key, the value is the value.	Mandatory, list of strings or Object
	OnChange	Script to execute when the value changes.	Optional, AutomationTaskScript
	Data	Script to execute to fill the possible values.	Optional, AutomationTaskScript
EntityType	Query	Script that returns a query object.	Mandatory, AutomationTaskScript
	ValueReferenceType	Optional, defaults to "EntityType".	Optional, String
	NestedEditorType	Optional, defaults to "EntityComboBox".	Optional, String
	DataComparisonField	Optional, defaults to "Name".	Optional, String
	OnChange	Script to execute when the value changes.	Optional, AutomationTaskScript
FindEntity	Query	Script that returns a query object.	Mandatory, AutomationTaskScript
	ReferenceTypeName	Type of entity configured to use by the FindEntity.	Mandatory, String
	OnChange	Script to execute when the value changes.	Optional, AutomationTaskScript
	Data	Script to execute to fill the possible values.	Optional, AutomationTaskScript
ListView	Data	Items to show on the ListView (by default it is the `defaultValue` falling back to an empty array).	Optional, AutomationTaskScript
	DataQuery	It runs on init to replace the data property to show on the ListView. Exposes the entire context of the GUI.	Mandatory, String
	OnChange	Script to execute when the value changes.	Optional, AutomationTaskScript
	PropertyDataToRender	Expects a property to be rendered.	Optional, String
	IsDataItemChecked	It expects a boolean to check if the item is selected. Exposes the item itself (this.item) and an array with current value of the setting (this.items).	Optional, AutomationTaskScript
	SelectionType	Enum to indicate how the ListView should behave.	Optional, from an enumeration: •Single (default) •Multiple •None • End
	EmptyMessage	Message to render when the `data` property is empty.	Optional, String

Example:

{
    "settings": {
        "General": {
            "Settings": [
            {
                "displayName": "Example Setting",
                "name": "exampleSetting",
                "settingKey": "exampleSetting",
                "dataType": "String",
                "defaultValue": "Example",
                "isMandatory": true,
                "infoMessage": "Super Example"
            },
            {
                "displayName": "Example Setting Boolean",
                "name": "exampleSettingBoolean",
                "settingKey": "exampleSettingBoolean",
                "dataType": "Boolean"
            },
            {
                "displayName": "Example Setting Integer",
                "name": "exampleSettingInteger",
                "settingKey": "exampleSettingInteger",
                "dataType": "Integer",
                "defaultValue": 1000,
                "settings": {
                    "symbol": "ms",
                    "min": 0
                    }
                }
            ]
        }
    }
}

The metadata describes a tab General, with a section Settings with three settings, one is a string, the other a boolean, and the other an integer. The integer has a particular setting, valid for that datatype, where it provides a minimum value and a symbol.

AutomationTaskScript - onChange#

For more information, see AutomationTaskScript.

This script executes when there is a change in a property.

[...]
    {
      "displayName": "Event",
      "name": "eventDefinitionName",
      "settingKey": "eventDefinitionName",
      "dataType": "FindEntity",
      "isMandatory": true,
      "settings": {
          "referenceTypeName": "IoTEventDefinition",
          "onChange": {
              "type": "Reference",
              "script": "eventDefinitionNameOnChange"
          }
      }
    }
[...]
"scripts": {
    "eventDefinitionNameOnChange": "dGhpcyBpcyB0aGUgYmFzZSA2NCBleGFtcGxlIDI"
}

Information Section#

In the Task settings, information blocks can be added.

{
    "General": {
        "Settings": [
            {
                "name": "JobName",
                "displayName": "Job Name",
                "settingKey": "JobName",
                "dataType": "string"
            }
        ],
        "Information Section": "Testing the information Section. Here you can explain something as you want."
    }
}

CheckList#

This component is a List view that is a list of items. Supports selection (single and multiple) and custom item template.

To create this, the task should add a new tab with a specific structure:

{
    "settings": {
        "IoT Events": {
            "" : [
                {
                    "settingKey": "_availableEvents",
                    "dataType": "ListView",
                    "settings": {
                        "selectionType": "Multiple",
                        "emptyMessage": "No events to show"
                    }
                }
            ]
        }
    }
}

The task must use an empty name section ("") that has an array of settings. It must have one setting with dataType ListView. This component needs the type of selection and an emptyMessage. SelectionType can be of three different types: Single, Multiple or None.