Advanced Script Configuration

State Modifiers

By using state modifiers, you can determine the state of a configuration item while the user configures your script. Currently there are 2 states that can be modified. One to decide if a configuration item should be visible and the other to validate the item. To add a state modifier to your configuration method, configure the stateModifier property in the @ScriptConfigurationItem annotation. This accepts an object class of type StateModifier. For example:

interface MonitorUptimeConfiguration : ScriptConfiguration {

    @ScriptConfigurationItem(
        keyName = "website",
        name = "Website",
        description = "The website to monitor.",
        stateModifier = WebsiteStateModifier::class,
    )
    fun website(): String?

}

object WebsiteStateModifier : StateModifier {
    override fun getVisibility(scriptConfig: ScriptConfig): Visibility {
        return Visibility.VisibleRequired
    }

    override fun getError(scriptConfig: ScriptConfig): String? {
        val websiteValue = (scriptConfig.valueForKey("website") as? ScriptConfigValue.StringScriptConfigValue)?.value

        return if (websiteValue?.startsWith("http") != true) {
            "Website URL must start with http"
        } else {
            null
        }
    }
}

Things to keep in mind when using state modifiers:

• The state modifier implementations must be an object, not a class.
• The configuration value retrieved using the ScriptConfig#valueForKey method can return a ScriptConfigValue#NullScriptConfigValue, even if the return type of the corresponding method in your configuration isn't nullable. This occurs because the user may not have provided a value for the requested item.
• Configuration items with a stateModifier that can return Visibility.Hidden in the getVisibility method MUST have a nullable return type, otherwise, users will encounter validation errors and won't be able to start your script.
• The return type for ScriptConfig#valueForKey in a configuration item where valuePerTask is set to true is either SequenceScriptConfigValue or NullScriptConfigValue.

Script identifier

When users create multiple instances of your script, Cereal displays them in a list, using the script name as an identifier. Consequently, users cannot easily determine at a glance how each script has been configured. To address this, you can set the isScriptIdentifier property of a single ScriptConfigurationItem to true. This allows Cereal to display the value of that configuration item next to the script name, helping the user identify it.

Some limitations apply when using this parameter: * Only one ScriptConfigurationItem in the entire script configuration can have isScriptIdentifier set to true. * If valuePerTask is set to true, or if the property is used in a child script configuration, it will be ignored.