# Inputs

A flow can be parameterized using inputs. Flow inputs will be available in variables inside the execution context and can be used during the flow execution to customize its tasks properties.

A good example of the usage of an input is when an identifier is needed (ex: storeId, paymentId) to define the path of an uploaded file.

Flow inputs can be seen in the Overview tab of the Execution page.

# Declaring inputs

You can declare as many inputs as necessary for any flow. Inputs can be required or not.
If an input is required, the flow cannot start if the input is not provided during the creation of the execution.

Every input will be parsed during the creation of the execution, and any invalid inputs will deny the creation of the execution.

WARNING

If the execution is not created due to invalid or missing inputs, no execution will be found on the list fo executions.

Examples:

id: my-flow
namespace: io.kestra.docs

inputs:
  - name: string
    type: STRING
  - name: optional
    type: STRING
    required: false
  - name: int
    type: INT
  - name: bool
    type: BOOLEAN
  - name: float
    type: FLOAT
  - name: instant
    type: DATETIME
  - name: date
    type: DATE
  - name: time
    type: TIME
  - name: duration
    type: DURATION
  - name: file
    type: FILE
  - name: optionalFile
    type: FILE
  - name: instantDefaults
    type: DATETIME
    defaults: "2013-08-09T14:19:00Z"
  - name: json
    type: JSON
  - name: uri
    type: URI
  - name: nested.string
    type: STRING

# Input types

Inputs can be of multiple types:

STRING: No control is done (no parsing); it can be any string.
INT: Must be a valid integer (without any decimals).
FLOAT: Must be a valid float (with any decimals).
BOOLEAN: Must be true or false as strings.
DATETIME: Must be a valid full ISO 8601 (opens new window) date and time with the timezone expressed in UTC from a text string such as 2007-12-03T10:15:30.00Z.
DATE: Must be a valid full ISO 8601 (opens new window) date without the timezone from a text string such as 2007-12-03.
TIME: Must be a valid full ISO 8601 (opens new window) time without the timezone from a text string such as 10:15:30.
DURATION: Must be a valid full ISO 8601 (opens new window) duration from a text string such as PT5M6S.
FILE: Must be a file sent as Content-Type: multipart/form-data with Content-Disposition: form-data; name="files"; filename="my-file", where my-file is the name of the input.
JSON: Must be a valid JSON string and will be converted to typed form.
URI: Must be a valid URI and will be kept as a string.

All the inputs of type FILE will be automatically uploaded to Kestra's internal storage and available for all tasks. After upload, the input variable will contain a fully qualified URL of the form kestra:///.../.../ that will be automatically handled by Kestra and can be used as is by tasks.

# Input Properties

These are the properties available for all input types:

name: The input name to be used with variables.
required: If the input is required. If required and no default value or no input is provided, the execution will not be created.
defaults: The default value if no input is provided. Must be a string.
description: A markdown description to document the input.

# Nested Inputs

If you use a . inside the name of an input, the input will be nested.

For example, when you declare the input with the following:

  - name: nested.string
    type: STRING
    required: false

You can reach it with: {{ inputs.nested.string }}. This is a convenient way to handle strong typing on input (with validation) without using raw JSON that will not be validated.

# Using input value in a flow

Every input is available with dynamic variables such as: {{ inputs.NAME }} or {{ inputs[NAME] }}.

For example, if you declare these inputs:

inputs:
  - name: my-file
    type: FILE
  - name: my-value
    type: STRING
    required: true

You can use the value of the input my-value inside dynamic task properties with {{ inputs['my-value'] }}. See variables basic usage.

# Set inputs at flow execution

When you execute a flow with some inputs, you must set all inputs (unless optional or with a default value) to be able to create the execution.

Let's take this example that defines multiple inputs:

id: kestra-inputs
namespace: io.kestra.test

inputs:
  - name: string
    type: STRING
  - name: optional
    type: STRING
    required: false
  - name: int
    type: INT
  - name: float
    type: FLOAT
  - name: instant
    type: DATETIME
  - name: file
    type: FILE

# Set inputs from the web UI

When creating an execution from the web UI, you must set the inputs in the generated form. Kestra's UI will generate a dedicated form based on your flow definition.

The input form for the inputs above looks like this:

Once the inputs are set, you can trigger an execution of the flow. The inputs will be available as variables for the flow's tasks.

# Set inputs with curl

To create an execution with these inputs using curl, you can use the following command:

curl -v "http://localhost:8080/api/v1/executions/trigger/io.kestra.test/kestra-inputs" \
    -H "Transfer-Encoding:chunked" \
    -H "Content-Type:multipart/form-data" \
    -F string="a string"  \
    -F optional="an optional string"  \
    -F int=1  \
    -F float=1.255  \
    -F instant="2020-01-14T23:00:00.000Z" \
    -F "files=@/tmp/128M.txt;filename=file"

All files must be sent as multipart form data named files with a header filename=my-file which will be the name of the input.

# Set inputs programmatically in Python

To create an execution with these inputs in Python, you can use the following script:

import io
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder

with open("/tmp/example.txt", 'rb') as fh:
  url = f"http://localhost:8080/api/v1/executions/trigger/io.kestra.test/kestra-inputs"
  mp_encoder = MultipartEncoder(fields={
    "string": "a string",
    "optional": "an optional string",
    "int": 1,
    "float": 1.255,
    "instant": "2020-01-14T23:00:00.000Z",
    "files": ("file", fh, "text/plain")
  })
  result = requests.post(
      url,
      data=mp_encoder,
      headers={"Content-Type": mp_encoder.content_type},
  )

← Vars functions Outputs →