parameter-types.md

Parameter Types

Actions support parameters for configuration purposes. For example, you may want to use a parameter of type duration to configure how long an action is supposed to take. This document explains what the supported parameter types are and how they work.

Supported parameter types:

• boolean
• duration
• integer
• percentage
• string
• string_array
• password
• file
• key_value
• textarea
• url
• separator
• header
• bitrate
• stressng-workers
• regex
• target-selection

boolean

Either true or false values. With optional support for null when required=false and no defaultValue is defined.

Example

Parameter Definition

{
  "name": "activateOrder66",
  "label": "Eradicate Jedi Order?",
  "type": "boolean",
  "defaultValue": "false"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "activateOrder66": true
}

Without a Value

{
  "activateOrder66": null
}

duration

A time duration. Renders appropriate UI controls that facilitate time inputs—exposed as numbers representing milliseconds to extensions.

Note: Make sure to name the field duration should you desire that the experiment editor uses a duration field to visualize the expected length of an action.

Example

Parameter Definition

{
  "name": "jarJarBinksSongDuration",
  "label": "How long do you want to be bothered by Jar Jar Binks?",
  "type": "duration",
  "defaultValue": "0s"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "jarJarBinksSongDuration": 5000 // milliseconds
}

Without a Value

{
  "jarJarBinksSongDuration": null
}

integer

Any integer number.

Example

Parameter Definition

{
  "name": "starWarsEpisode",
  "label": "What is your favorite Star Wars episode?",
  "type": "integer",
  "defaultValue": "4"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "starWarsEpisode": 5
}

Without a Value

{
  "starWarsEpisode": null
}

percentage

percentage is a variation of the integer parameter that renders more appropriate user interface controls. A value of 0% is represented as the number 0. 100% is represented as the number 100.

Example

Parameter Definition

{
  "name": "deathStarEnergyLevel",
  "label": "How much should the Death Star be charged?",
  "type": "percentage",
  "defaultValue": "69"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "deathStarEnergyLevel": 69
}

Without a Value

{
  "deathStarEnergyLevel": null
}

string

Strings are the most fundamental parameter type. They represent arbitrary character sequences just like you would expect.

Note: It is the responsibility of an extension to decide what to do when receiving an empty string.

Example

Parameter Definition

{
  "name": "fullName",
  "label": "Full Name",
  "type": "string",
  "defaultValue": "Jane Doe"
}

Example with options to represent a drop down field

{
  "name": "fullName",
  "label": "Full Name",
  "type": "string",
  "options": [
    {
      "label": "Jane Doe",
      "value": "Jane Doe"
    },
    {
      "label": "Admiral Ackbar",
      "value": "Admiral Ackbar"
    }
  ]
}

Example with options to represent a drop down field with the option to add a custom value

{
  "name": "fullName",
  "label": "Full Name",
  "type": "string",
  "optionsOnly": false,
  "options": [
    {
      "label": "Jane Doe",
      "value": "Jane Doe"
    },
    {
      "label": "Admiral Ackbar",
      "value": "Admiral Ackbar"
    }
  ]
}

Parameter optionsOnly

Indicates if the action should only support the provided options or if the user can enter a custom value. If optionsOnly is set to true or is left out, the user can only select from the provided options. If optionsOnly is set to false, the user can select from the provided options or enter a custom value.

Configuration Value Received in prepare Call of Actions

With a Value

{
  "fullName": "Admiral Ackbar"
}

With an Empty String

{
  "fullName": ""
}

Without a Value

{
  "fullName": null
}

string_array

You can use the string_array type for multiple textual inputs.

You may define options that users can select. Options are either explicit, i.e., fixed and known in advance ( identifiable by the label and value properties). Or options based on target attributes' values (identifiable by the attribute property).

Example

Parameter Definition

{
  "name": "lightsaberCombatForm",
  "label": "Lightsaber Combat Form",
  "type": "string_array",
  "defaultValue": "[\"shii_cho\", \"ataru\"]",
  "options": [
    {
      "label": "Shii-Cho",
      "value": "shii_cho"
    },
    {
      "label": "Makashi",
      "value": "makashi"
    },
    {
      "label": "Soresu",
      "value": "soresu"
    },
    {
      "label": "Ataru",
      "value": "ataru"
    },
    
    // or automatically created options from all known values for this target attribute key 
    {
      "attribute": "combat.form"
    }
  ]
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "lightsaberCombatForm": ["soresu"]
}

Without a Selected Input

{
  "lightsaberCombatForm": []
}

Without any Input

{
  "lightsaberCombatForm": null
}

password

The password parameter behaves like the string parameter type, except for the visual presentation in the Steadybit user interface.

file

Files can be uploaded and passed to actions through a parameter of the file type. Uploaded files are delivered to actions in base64 encoding. Through the optional acceptedFileTypes option you can restrict what kind of files may be selected by users.

If an action has a parameter of the file type, the prepare request will be a multipart/form-data request. The files will be parts of the request body.

Example

Parameter Definition

{
  "name": "schematics",
  "label": "Space Ship Schematics",
  "type": "file",
  "acceptedFileTypes": [".svg", ".dwg"]
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "schematics": "WW91IGFyZSBxdWl0ZSBjdXJpb3VzISBIZXJlLCBoYXZlIGEgY29va2llISBBbHNvLCBjaGVjayBvdXQgaHR0cHM6Ly9zdGFyd2Fycy5mYW5kb20uY29tL3dpa2kvRGVhdGhfU3Rhcl9wbGFucyE="
}

Without a Value

{
  "schematics": null
}

key_value

For key/value pairs, e.g., tags, labels and environment variables, we support a key_value parameter type.

Example

Parameter Definition

{
  "name": "env",
  "label": "Environment",
  "type": "key_value",
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "env": [
    {
      "key": "Dagobah",
      "value": "humid"
    }
  ]
}

Without a Value

{
  "env": []
}

textarea

For a large string, we support a textarea parameter type.

Example

Parameter Definition

{
  "name": "body",
  "label": "Body",
  "type": "textarea"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "body": "looooooong string"
}

Without a Value

{
  "body": null
}

url

For URLs, we support a url parameter type.

Example

Parameter Definition

{
  "name": "targetUrl",
  "label": "Target URL",
  "type": "url"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "targetUrl": "https://steadybit.com"
}

Without a Value

{
  "targetUrl": null
}

separator

For a common separator in the settings field list, we support a separator parameter type.

Example

Parameter Definition

{
  "name": "-",
  "label": "-",
  "type": "separator"
}

Configuration Value Received in prepare Call of Actions

you will not recieve values for this parameter type

header

For a common header in the settings field list, we support a header parameter type.

Example

Parameter Definition

{
  "name": "importantSettings",
  "label": "Important Settings",
  "type": "header"
}

Configuration Value Received in prepare Call of Actions

you will not recieve values for this parameter type

bitrate

Defines a bitrate with value and unit E.g.:

• 1024kbps: 1024 Kilobytes per second
• 10mbps: 10 Megabytes per second
• 64kbit: 64 Kilobits per second
• 10mbit: 10 Megabits per second

Example

Parameter Definition

{
  "name": "bandwidth",
  "label": "How fast you want to go?",
  "type": "bitrate",
  "defaultValue": "1024kbit"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "bandwidth": "1024kbit"
}

Without a Value

{
  "activateOrder66": null
}

stressng-workers

Defines how many workers should be used for stressng

• 0: all cpu cores

• 0: number of workers

Example

Parameter Definition

{
  "name": "workers",
  "label": "Stress-ng Workters",
  "type": "stressng-workers",
  "defaultValue": "0"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "worker": 0
}

Without a Value

{
  "worker": null
}

regex

Defines a regular expression, which is used to validate the input value as a regular expression.

The validation will be done on server side with java regex flavor.

Example

Parameter Definition

{
  "name": "hostname",
  "label": "Hostname to match",
  "type": "regex",
  "defaultValue": ".*"
}

Configuration Value Received in prepare Call of Actions

With a Value

{
  "hostname": ".*"
}

Without a Value

{
  "hostname": null
}

target-selection

This is a dummy parameter type to allow to specify the position of the target selection in the UI. If this is not added to the list of parameters, the target selection will always be rendered at the top in the action settings sidebar.

Example

Parameter Definition

{
  "name": "-",
  "label": "Filter location",
  "type": "target-selection"
}