Script configuration

Each script has to define a configuration in the form of an interface that implements ScriptConfiguration. In this interface each defined function represents a configuration item. Cereal will read this interface and give the user the possibility to fill these in.

Best practices

• Logical Grouping: Group related configuration items together by positioning order
• Clear Names: Use descriptive names and detailed explanations for each configuration item
• Defaults: Choose sensible defaults where applicable to simplify user experience
• Required vs Optional: Clearly indicate which configuration values are required vs optional
• Data Types: Choose appropriate types for your configuration values:
  • Use enums for choices among a fixed set of options
  • Use nullable types for truly optional values
  • Use the simplest type that meets requirements (Int vs Double)
• Script Identification: Use isScriptIdentifier = true for the most distinctive configuration item so users can easily identify script instances

Example

Below an example of a script configuration that monitors the uptime of a website and needs a website url to monitor.

interface MonitorUptimeConfiguration : ScriptConfiguration {

    @ScriptConfigurationItem(
        keyName = "website",
        name = "Website",
        description = "The website to monitor.",
        position = 1,
        valuePerTask = false,
    )
    fun website(): String?

}

Each function must be annotated with a ScriptConfigurationItem. In this annotation additional information needed to render the configuration GUI for your script is defined. Lets go through the important lines in this code snippet:

interface MonitorUptimeConfiguration : ScriptConfiguration {

An interface, with a name you can decide yourself, must implement ScriptConfiguration.

@ScriptConfigurationItem(

Each function is annotated with ScriptConfigurationItem.

keyName = "website",

This value is used to persist the users' configuration. This value must be unique within all the defined script configuration items within the scripts' configuration. This value should stay the same in the releases of your script.

name = "Website",

The name of the field, shown to the user when configuring the script.

description = "The website to monitor.",

The description of the configuration item. This is shown to the user and should provide additional explanation on what to fill in.

position = 1,

The (optional) position of the configuration item in the scripts' configuration screen presented to the user. By default the order in which the functions are defined is used as position.

valuePerTask = false,

Whether the script requires the user to input a single value for the entire script or a unique value for each task that's created.

fun website(): String?

Method name (decided by you) and the return type (nullable) String. The return type is used to determine what is expected as input from the user. Both nullable and non-nullable return types are supported. Making the return type nullable can be useful when a fallback is available in your script.

Supported return types

Next to the basic types like string and integer, additional return types can be used for a more complex situations. In this table you'll find all the supported types that can be used as return type of the configuration item function.

Type	Description	valuePerTask supported
String	A text	yes
Int	A number value	yes
Boolean	true or false	no
Float	A float value	yes
Double	A double value	yes
Proxy	A single proxy	no (enabled by default)
RandomProxy	Gives access to a proxy on demand	no

Proxy vs RandomProxy

Each of these types has its own use case. A Proxy gives your script access to a single proxy object containing an IP address and port, and optionally a username and password. The RandomProxy allows your script to request a random proxy when needed. This is particularly useful when, for example, you want to rotate the proxy for each subsequent request made to an external service.

Both the Proxy and the RandomProxy work based on the least-used proxy principle. This means that we track the usage of proxies in each task and provide a task with the least-used proxy at that moment, so you don't need to manage this manually.

Please note that it is inevitable that some proxies might end up being assigned to two or more different tasks if there are fewer proxies available than the number of created tasks.