Inputs
Configuration files with the inputs field:
These inputs collect information relevant to the scope of your Plugin or Action. The STK CLI interprets them during command execution to ask users for this information.
Inputs are optional. Each .yaml file can have none or many inputs.
Input types
Input types are defined in the type field, as shown below:
| Types | Value |
|---|---|
text | String. |
textarea | String. |
bool | Boolean. |
int | Integer. |
password | Encrypts the entered value (string). |
select | Lists values, allowing only one value (string) to be chosen. |
multiselect | Lists values, allowing one or more values (string) to be chosen. |
list | List of inputs of the same type (text, int, object, and required-connection). |
object | Stores a set of inputs within an object, making the object a parent input with a set of child inputs. |
required-connection | Stores a set of inputs required to connect to an Infrastructure inside an object. |
generated-connection | Stores a set of inputs required to create an Infrastructure inside an object. |
On STK CLI, see how to navigate in a multiselect input:
- Navigate using arrow keys to choose your option(s), or type to search.
- Select all: use CTRL + a.
- Invert selection: use CTRL + i.
Mandatory input fields
- name: Input name (used later in templates or scripts).
- label: Text that will appear in the terminal asking the user for input.
- type:
text(string).bool(boolean).int(integer).password(the value is hidden on STK CLI, in the format:****).multiselect: lists values and allows one or more values (string).list(list of inputs of the same type. Accepted types are:text,int,object, andrequired-connection).object(string).required-connection(string).
Inputs with mandatory fields examples
Type text input
The text input type accepts text as a string.
inputs:
- label: Type your name
name: name
type: text
In text inputs, you can use a variable as the value of this input. For more information, visit the Variables page on StackSpot.
The use of text lists in inputs has been deprecated!
inputs:
- label: Select a day
name: days
type: text
items:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
- Saturday
- Sunday
The use of the text input type with the items field is no longer supported in the current version.
textarea input
The textarea input receives text as a string and supports line breaks.
inputs:
- label: Type your name
name: name
type: textarea
Example:
Consider using a JSON code snippet as the value for the textarea input. In both the STK CLI and the StackSpot Portal, when you use a value with a JSON structure, the formatting of the content — such as spaces and line breaks — remains intact.
This behavior applies to all text that includes spaces and line breaks, not just code snippets.
Text visualization with text input:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": "arn:aws:s3:::your-bucket-name" }, { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": "arn:aws:s3:::your-bucket-name/*" } ] }
Text visualization with textarea input:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": "arn:aws:s3:::your-bucket-name"
},
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject"
],
"Resource": "arn:aws:s3:::your-bucket-name/*"
}
]
}
In text inputs, you can use a variable as the value of this input. For more information, visit the Variables page on StackSpot.
Type select input
The select input type accepts a list of text items as a string. You can select only one item from the list.
inputs:
- label: Choose one color!
name: colors
type: select
items:
- Blue
- Yellow
- Pink
- Green
- Red
multiselect type input
The multiselect input type accepts a list of text items as a string. You can select one or more items from the list.
inputs:
- label: Choose one or more days
name: days
type: multiselect
items:
- Monday
- Tuesday
- Wednesday
- Thursday
- Friday
Input of type int
The input of type int receives an integer numeric value.
inputs:
- label: Type your age
name: age
type: int
The input of type int can use the pattern parameter to define a regular expression for the value received in the input.
Input of type password
The input of type password receives a value and encrypts it using a 256-bit AES key (Advanced Encryption Standard). When you type the value in your terminal, the characters are hidden and displayed only as asterisks (****).
- When creating Applications that have Plugins and Actions with the
passwordinput, deploys are executed. In case of deploy failure, you must re-execute it and re-enter the value of thepasswordinput, because the value does not persist for data security reasons. - After entering the value of the
passwordinput, further attempts to execute the deploy must occur within one hour. After this period, you must re-enter the input value. - When
passwordinput types are recorded in the deploy execution logs, the values displayed in the logs are masked.
inputs:
- label: Password
name: account_password
type: password
Input of type bool
The input of type bool receives a boolean value, with Y representing true and n representing false.
inputs:
- label: Use SQL connection?
name: sql
type: bool
Input of type list
The input of type list receives another input and structures the values obtained by this input as a list. The list must receive all values of the same type. The accepted types are:
In the add-question option, include a text as a question to be repeated to the user for each iteration in the list.
inputs:
- label: Type your IPs
name: ips
type: list
add-question: Do you want to add more IPs to the list?
input:
type: text
label: Type the IPs
To access the values in the list, you must provide the list index. The index starts at [0] (zero). See the following example:
condition:
variable: input_list_2[0].input_text_1_from_input_object
operator: "=="
value: "ok"
Input of type object
The object type input receives various inputs and organizes their values as objects. There are no restrictions on the types of inputs this object can have; it can be a simple object or a complex one containing multiple input types.
In the inputs option within the object declaration, you must include each input that will constitute the object-type input.
inputs:
- type: object
name: firewall_rule
label: Enter the CIDR/Port of the firewall rule
inputs:
- type: text
name: cidr
label: CIDR
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}/\d{2}$'
- type: int
name: port
label: Port
required: false
condition:
variable: firewall_rule.cidr
operator: "=="
value: 192.168.0.1/25
inputs:
- type: object
name: firewall_rule
label: Enter the CIDR/Port of the firewall rule
inputs:
- type: text
name: cidr
label: CIDR
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}/\d{2}$'
- type: int
name: port
label: Port
required: false
condition:
variable: firewall_rule.cidr
operator: "=="
value: 192.168.0.1/25
- type: object
name: additional_rules
label: Additional Rules
required: true
inputs:
- type: select
name: name
label: Name
required: true
items:
- Dynamo
- Lambda
- type: text
name: description
label: Description
required: true
condition:
variable: firewall_rule.additional_rules.name
operator: "=="
value: Dynamo
- type: text
name: conditional_input
label: Conditional test
condition:
variable: firewall_rule.additional_rules.name
operator: "=="
value: Dynamo
Input of type required-connection
The required-connection input is defined using a Connection Interface required by your Plugin or Action. Before using this input, refer to the types of available Connection Interfaces. Make sure to fill in the connection-interface-type field with the name of the Connection Interface Type available for your StackSpot Account.
inputs:
- label: Select a Bucket s3
type: required-connection
name: my-s3
connection-interface-type: aws-s3-conn
Input of type generated-connection
The generated-connection input is defined using a Connection Interface generated by your Plugin. Before using this input, please refer to the types of available Connection Interfaces. Ensure that you fill in the connection-interface-type field with the name of the Connection Interface Type that is available for your StackSpot Account.
inputs:
- label: The s3 connection name
name: bucket_s3
type: generated-connection
connection-interface-type: aws-s3-conn
outputs:
- from: aws-s3-alias-arn
to: arn
- from: aws-s3-alias-bucket_name
to: bucket_name
Optional input fields
Below are the optional fields available for use across various input types. However, certain fields may be exclusive to a specific type of input. In these cases, the description specifies the required input type.
default
Default value when there is no value provided.
- label: Type your name
name: name
type: text
default: John
The default field accepts an Account variable or StackSpot variable, but does not support using computed-inputs.
For the multiselect input type, use only the following formats:
- label: (Multiselect input, not required, with 1 default value) Which port do you want to expose?
type: multiselect
name: port4
items:
- "8080"
- "8888"
default: ["8888"]
Or:
- label: (Multiselect input, not required, with 1 default value) Which port do you want to expose?
type: multiselect
name: port4
items:
- "8080"
- "8888"
default:
- "8888"
Default value in non-interactive mode
When you run the stk apply plugin command, you can use the -q or --non-interactive parameter to bypass inputs in the terminal (non-interactive mode). If a value is set in the default option, the command uses that value when applying the Plugin in non-interactive mode.
This behavior applies only to the following input types:
required
Boolean that indicates whether the input is required. Use true to make the value mandatory.
- label: Type your name
name: name
type: text
required: true
items
List of possible input values (used with the select or multiselect types).
- label: Type your name
name: name
type: select # or multiselect
items:
- John
- Bill
source
It retrieves data from a public or private API with a StackSpot domain to create an external source of values for select and multiselect input types.
Use a public API endpoint URL or a private API endpoint URL with a StackSpot domain.
- label: Select External Item
name: select_item
type: select
external-items:
source: https://external-source.com # The API endpoint URL.
value: $[*].id
label: $[*].name
To use the source option in the input, you cannot use the items option simultaneously. You must choose one of them.
The source options are:
- value (Mandatory): The JSON Path of the value in the returned payload that you want to use in the input list.
- label (Optional): The JSON Path of the object that is displayed as an alternative name for the input item selection in the terminal.
Consider the following JSON object of the endpoint used in the source field:
[
{
"id": "id1",
"name": "item1"
},
{
"id": "id2",
"name": "item2"
},
{
"id": "id3",
"name": "item3"
}
]
If you want to use the ID values as the input values for the list, use the JSON Path expression for the ID values in the value option.
For the values used in the value option, if you want to display a different label name for the ID, add the JSON Path for the other object in the label field (for example, the name object).
Example:
inputs:
- label: Select external item
name: select_items
type: select
external-items:
source: https://external-source.com
value: $[*].id
label: $[*].name
required: true
- label: Select Multiple Items
name: multiselect_items
type: multiselect
external-items:
source: https://external-source.com
value: $[*].id
label: $[*].name
required: true
Otherwise, the ID value is shown as the label in the terminal as the input list selection.
For more details about JSON Path, see the JSON PATH expressions reference.
pattern
Configures a regular expression validation for the input field.
- label: Type your name
name: name
type: text
pattern: "[A-Za-z]"
condition
After receiving a value from the input, you can define a condition so that a second input is shown to the user if the condition is true. If the condition is not true, nothing happens after the input with the condition property.
- variable: Name of the variable used to evaluate the condition.
- operator: Operator used to evaluate the condition. The valid operator values are:
==,!=,>,>=,<,<=,containsAny,containsAll,containsOnly,notContainsAny, andnotContainsAll.
Use current index in list of objects in condition.variable
In the condition parameter, the variable option supports the use of the input of type list of objects. This way, you can reference the index of the list as presented previously in the input of type list or reference the current index by just informing empty brackets ([]).
This way of referencing the index allows you to create a condition to display different inputs according to previous responses.
Example:
inputs:
- label: Type your objects
name: obj_list
type: list
add-question: Would you like to add items to the object list?
input:
type: object
label: object_in_list
inputs:
- label: text_value
name: text_value
type: text
required: true
- label: int_value
name: int_value
type: int
required: true
condition:
variable: obj_list[].text_value
operator: "=="
value: "foo-bar"
- label: Type your objects
name: obj_list_nested
type: list
add-question: Would you like to add items to the object list?
input:
type: object
label: Object In List Nested
inputs:
- label: text_value
name: text_value_nested
type: text
required: true
- label: int_value
name: int_value_nested
type: int
required: true
condition:
variable: obj_list[].obj_list_nested[].text_value_nested
operator: "=="
value: "foo-bar"
You must use double quotes for the following operators: "==", "!=", ">", ">=", "<", "<=".
Click here to see more details about operators:
| Operator | Description |
|---|---|
== | Validates if the values are equal. |
!= | Validates if the values are different. |
> | Validates if the variable is greater than the value. |
< | Validates if the variable is less than the value. |
>= | Validates if the variable is greater than or equal to the value. |
<= | Validates if the variable is less than or equal to the value. |
containsAny | Validates if the variable of list or text type contains any of the values contained in value. |
containsAll | Validates if the variable of the type list contains all the values contained in value. |
containsOnly | Validates if the variable list type contains all the values in value and no other elements. |
value
Value used for evaluation.
The condition value must be the same type as the referenced input.
Check an example below using condition as an input. In this example, you can choose which language you want to use: Java or Kotlin. Depending on the language, you can see the available versions.
inputs:
- label: Which language do you want to use?
type: select
name: language
items:
- Java
- Kotlin
- label: Which Java version do you want to use?
type: select
name: java_version
items:
- 11
- 17
condition:
variable: language
operator: "=="
value: Java
- label: Which version of Kotlin do you want to use?
type: select
name: kotlin_version
items:
- 1.6
- 1.7
condition:
variable: language
operator: "=="
value: Kotlin
In the example, the condition chooses which list to display. It depends on the input value language. If the value equals Java, the Java list of versions shows up. If it equals Kotlin, the Kotlin versions list shows up.
When an input contains a condition and the referenced variable does not exist, other inputs related to this condition don’t show up.
Using JINJA in inputs
Inputs are responsible for receiving all the data that will make up the Plugins and Actions. They are essential so that:
- Plugins can build the Application code; and
- Actions can create automation as expected.
Plugins generate the code from the templates and templates-deploy folders, and the automation is programmed in the Actions scripts.
When creating Actions and Plugins, it is important to use JINJA expressions in your inputs, source code, and scripts for a more dynamic use of these folders and scripts.
For more details, visit the page on how to use JINJA on StackSpot.
Below are some examples of Plugin inputs using JINJA.
Consider the resource and method inputs.
inputs:
- label: Type the name of your resource
name: resource
type: text
required: true
default: Client
pattern: '([A-Z][a-z]+)+'
help: 'Inform your resource name (e.g.: Client)'
- label: Choose the http method of the new endpoint
name: method
type: select
items:
- GET
- POST
- PUT
- DELETE
- PATCH
default: GET
required: true
help: 'Inform the method of the endpoint (e.g.: post or delete)'
In the files in the templates folder of your Plugin, use the JINJA expressions {{ variable_name }}. Thus, the expressions used in the inputs of the previous example will be:
resource:{{ resource }}method:{{ method }}
JINJA in inputs of type list
Consider the following example of the input ips. It is a list that receives values of type text:
inputs:
- type: list
label: List of IPs
add-question: Do you want to add IPs to the list?
name: ips
input:
type: text
label: ip
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}$'
default: '127.0.0.1'
As the plugin creator, you can determine the use of the ips input in the following ways:
1. Access the entire list
Use the expression:
{{ variable_name }}
Example:
{{ ips }}
2. Access a list value by index
The list index indicates the position at which each item was added to the list, where the first index position starts at the value [0] (zero). Use the following expression:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
{% if variable is defined %}
{{ variable[item_position_number] }}
{% endif %}
Example:
{% if ips is defined %}
{{ ips[0] }}
{% endif %}
3. Loop through all values in a list
To loop through the values in the list ips, you must use the JINJA control structure, the for loop. To display all items, declare a variable, for example, ip, in the for loop to iterate through the items added to the list.
Use the following expression:
{% for [variable] in [input_list_name] %}
- list_item: {{ variable }}
{% endfor %}
Example:
{% for ip in ips %}
- ip value: {{ ip }}
{% endfor %}
JINJA on inputs of type object
Consider the following example of the input firewall_rule. It is an object with two further inputs: cidr and port.
inputs:
- type: object
name: firewall_rule
label: Enter the CIDR/Port of the firewall rule
inputs:
- type: text
name: cidr
label: CIDR
pattern: '^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)\.?\b){4}/\d{2}$'
default: '0.0.0.0/24'
- type: int
name: port
label: Port
default: 8080
The firewall_rule input is a "parent" or "root" object, and the other inputs are all "children" of this object. Use the following expressions to access them:
1. Access the entire object
Use the expression:
{{ parent_object_name }}
Example:
{{ firewall_rule }}
2. Access child inputs
Repeat the expression for each child input:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
Use the expression:
{% if parent_object_name is defined %}
{{ parent_object_name.child_input }}
{% endif %}
Example:
- Input
cidr:
{% if firewall_rule is defined %}
{{ firewall_rule.cidr }}
{% endif %}
- Input
port:
{% if firewall_rule is defined %}
{{ firewall_rule.port }}
{% endif %}
JINJA on list inputs with object
Consider the following example of the list buckets. It contains an object made up of several types of inputs.
inputs:
- type: list
label: Buckets list
add-question: Would you like to add buckets?
name: buckets
input:
type: object
label: Inform the bucket
inputs:
- type: text
name: description
label: Bucket Description
- type: int
name: number
label: Bucket number
- type: bool
name: encrypted
label: Bucket Encrypted
- type: select
items:
- us-east-1
- us-east-2
- sa-east-3
name: region
label: Bucket Region
- type: multiselect
items:
- us-east-1
- us-east-2
- sa-east-3
name: region_bkp
label: Bucket Region Backup
- label: Select the connection for required_bucket_object
type: required-connection
name: required_bucket_object
connection-interface-type: aws-s3-conn
To access a list that has an object and access each item in the object, use the following expressions:
1. Access the entire list
Use the expression:
{{ variable_name }}
Example:
{{ buckets }}
2. Accessing a list value by index
The list index indicates the position at which each item was added to the list, where the first index position starts at the value [0] (zero). Use the following expression:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
{% if variable_name is defined %}
{{ variable_name[item_position_number] }}
{% endif %}
Example:
{% if buckets is defined %}
{{ buckets[0] }}
{% endif %}
3. Loop through all the values in the list
To loop through the values in the list buckets, you must use the JINJA control structure, the for loop. To display all the items, declare a variable, for example, bucket, in the for loop to iterate through the items added to the list.
Use the following expression:
{% for [variable] in [input_list_name] %}
- list_item1: {{ variable }}
- list_item2: {{ variable }}
- list_item3: {{ variable }}
- list_item4: {{ variable }}
- list_item5: {{ variable }}
- list_item6: {{ variable }}
- list_itemN: {{ variable }}
{% endfor %}
Example:
{% for bucket in buckets %}
- bucket.description: {{ bucket.description }}
- bucket.number: {{ bucket.number }}
- bucket.encrypted: {{ bucket.encrypted }}
- bucket.region: {{ bucket.region }}
- bucket.region_bkp: {{ bucket.region_bkp }}
- bucket.required_bucket_object.selected: {{ bucket.required_bucket_object.selected }}
- bucket.required_bucket_object.type: {{ bucket.required_bucket_object.type }}
{% endfor %}
JINJA on inputs of type required-connection
Consider the following example, it is a Connection Interface aws-s3-conn required in a Plugin.
inputs:
- label: Select the connection for required_bucket_object
type: required-connection
name: required_bucket_object
connection-interface-type: aws-s3-conn
You should use the following expressions to access a Connection in two situations:
1. Access Connection data
This data is the name and the type of the Connection used:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
{% if required_connection_name is defined %}
{{ required_connection_name.selected }}
{% endif %}
{% if required_connection_name is defined %}
{{ required_connection_name.type }}
{% endif %}
Example:
- Connection name:
{% if required_bucket_object is defined %}
{{ required_bucket_object.selected }}
{% endif %}
- Connection type:
{% if required_bucket_object is defined %}
{{ required_bucket_object.type }}
{% endif %}
2. Accessing Connection outputs (only during deployment)
You can only access this data during the Application deployment, which requires the Connection used in the Plugin. Each type of Connection has its own outputs. Check the outputs of the aws-s3-conn type Connection:
| Output | Type | Description |
|---|---|---|
arn | String | ARN. |
bucket_name | String | AWS Bucket name. |
To access these values, use the following expressions for each one:
Make sure to perform a JINJA check to confirm the existence of this variable before querying its position.
{% if required_connection_name is defined %}
{{ required_connection_name.connection.connection_output }}
{% endif %}
Example:
required_bucket_object.arn:
{% if required_bucket_object is defined %}
{{ required_bucket_object.connection.arn }}
{% endif %}
required_bucket_object.bucket_name:
{% if required_bucket_object is defined %}
{{ required_bucket_object.connection.bucket_name }}
{% endif %}
Informing the value of an input as a parameter
In pipeline executions, the interactive mode of terminal commands available with the STK CLI cannot be used. To execute a command, you must specify all the required parameters, including the inputs.
To do this, you need to provide both the input and its corresponding value as parameters.
Consider the following example, the snippet of a Plugin that has the following inputs:
# Other Plugin information.
# ...
inputs:
- type: text
name: text_input
label: "Type some text:"
- type: bool
name: boolean_input
label: "Do you want to run optional job?"
- type: required-connection
name: some_s3_connection
label: "Give an alias for required S3 connection"
connection-interface-type: aws-s3-conn
When applying the Plugin or creating an Application that uses this Plugin, you must provide these inputs as follows.
After using the command and its parameters, use the syntax --input_name input_value.
stk apply plugin example-inputs --input_name input_value
Example:
For the inputs highlighted in the Plugin excerpt, the values informed as parameters are:
Inputs:
text_input;boolean_input;some_s3_connection.
Input value filled as parameter:
stk apply plugin studio/stack/plugin-example-inputs --text_input "Text between quotes (string)" --boolean_input true --some_s3_connection s3_backup_logs
For Actions and Plugins commands you can also use the --inputs-json parameter to inform the inputs in JSON format:
stk apply plugin studio/stack/plugin-example-inputs --inputs-json '{"text_input": "Text between quotes (string)", "boolean_input": "true", "some_s3_connection": "s3_backup_logs"}'