diff --git a/ui/src/assets/documentations/basic.md b/ui/src/assets/documentations/basic.md index 5232ac38792..2d7bdd0dc8b 100644 --- a/ui/src/assets/documentations/basic.md +++ b/ui/src/assets/documentations/basic.md @@ -20,23 +20,24 @@ The table below describes all these properties in detail. |------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `id` | The [flow identifier](https://kestra.io/docs/workflow-components/flow) which represents the name of the flow. This ID must be unique within a namespace and is immutable (you cannot rename the flow ID later, but you can recreate it with a new name). | | `namespace` | Each flow lives in one [namespace](https://kestra.io/docs/workflow-components/namespace). Namespaces are used to group flows and provide structure. Some concepts in Kestra, such as [Namespace Files](https://kestra.io/docs/concepts/namespace-files) or [KV Store](https://kestra.io/docs/concepts/kv-store) are tied to a namespace — e.g. to retrieve a KV pair from a different namespace, use the `{{ kv('MYKEY', 'mynamespace') }}` expression. Once a flow is created, you cannot change its namespace. If you need to change the namespace of a flow, create a new flow with the desired namespace and delete the old flow. | -| `revision` | The [flow version](https://kestra.io/docs/concepts/revision), managed internally by Kestra, and incremented upon each modification. You should **not** manually set it. | -| `description` | The [description](https://kestra.io/docs/workflow-components/descriptions) of the flow. | -| `labels` | Key-value pairs that you can use to organize your flows based on your project, maintainers, or any other criteria. You can use [labels](https://kestra.io/docs/workflow-components/labels) to filter Executions in the UI. | +| `tasks` | The list of [tasks](https://kestra.io/docs/workflow-components/tasks) to be executed. Tasks are atomic actions in your flows. By default, they will run sequentially one after the other. However, you can use additional [Flowable tasks](https://kestra.io/docs/tutorial/flowable) to run some tasks in parallel. | | `inputs` | The list of strongly-typed [inputs](https://kestra.io/docs/workflow-components/inputs) that allow you to make your flows more dynamic and reusable. Instead of hardcoding values in your flow, you can use inputs to trigger multiple Executions of your flow with different values determined at runtime. Use the syntax `{{ inputs.your_input_name }}` to access specific input values in your tasks. | +| `outputs` | Each flow can [produce outputs](https://kestra.io/docs/workflow-components/outputs) that can be consumed by other flows. This is a list property, so that your flow can produce as many [outputs](https://kestra.io/docs/workflow-components/outputs) as you need. Each output needs to have an `id` (the name of the output), a `type` (the same types you know from `inputs` e.g. `STRING`, `URI` or `JSON`) and `value` which is the actual output value that will be stored in internal storage and passed to other flows when needed. | +| `labels` | Key-value pairs that you can use to organize your flows based on your project, maintainers, or any other criteria. You can use [labels](https://kestra.io/docs/workflow-components/labels) to filter Executions in the UI. | +| `description` | The [description](https://kestra.io/docs/workflow-components/descriptions) of the flow. | | `variables` | The list of [variables](https://kestra.io/docs/workflow-components/variables) (such as an API endpoint, table name, download URL, etc.) that you can access within tasks using the syntax `{{ vars.your_variable_name }}`. Variables help reuse some values across tasks. | -| `tasks` | The list of [tasks](https://kestra.io/docs/workflow-components/tasks) to be executed. Tasks are atomic actions in your flows. By default, they will run sequentially one after the other. However, you can use additional [Flowable tasks](https://kestra.io/docs/tutorial/flowable) to run some tasks in parallel. | +| `sla` | The list of [SLA conditions](https://kestra.io/docs/workflow-components/sla) specifying an execution `behavior` if the workflow doesn't satisfy the assertion defined in the SLA. This feature is currently in Beta so some properties might change in the next releases. | | `errors` | The list of [error tasks](https://kestra.io/docs/workflow-components/errors) that will run if there is an error in the current execution. | -| `listeners` | The list of listeners (deprecated). | +| `disabled` | Set it to `true` to temporarily [disable](https://kestra.io/docs/workflow-components/disabled) any new executions of the flow. This is useful when you want to stop a flow from running (even manually) without deleting it. Once you set this property to true, nobody will be able to trigger any execution of that flow, whether from the UI or via an API call, until the flow is reenabled by setting this property back to `false` (default behavior) or by deleting this property. | +| `revision` | The [flow version](https://kestra.io/docs/concepts/revision), managed internally by Kestra, and incremented upon each modification. You should **not** manually set it. | | `triggers` | The list of [triggers](https://kestra.io/docs/workflow-components/triggers) which automatically start a flow execution based on events, such as a scheduled date, a new file arrival, a new message in a queue, or the completion event of another flow's execution. | | `pluginDefaults` | The list of [default task values](https://kestra.io/docs/workflow-components/task-defaults), allowing you to avoid repeating the same properties on each task. | | `pluginDefaults.[].type` | The task type is a full qualified Java class name, i.e. the task name such as `io.kestra.plugin.core.log.Log`. | | `pluginDefaults.[].forced` | If set to `forced: true`, the `pluginDefault` will take precedence over properties defined in the task (the default behavior is `forced: false`). | | `pluginDefaults.[].values.xxx` | The task property that you want to be set as default. | -| `disabled` | Set it to `true` to temporarily [disable](https://kestra.io/docs/workflow-components/disabled) any new executions of the flow. This is useful when you want to stop a flow from running (even manually) without deleting it. Once you set this property to true, nobody will be able to trigger any execution of that flow, whether from the UI or via an API call, until the flow is reenabled by setting this property back to `false` (default behavior) or by deleting this property. | -| `outputs` | Each flow can [produce outputs](https://kestra.io/docs/workflow-components/outputs) that can be consumed by other flows. This is a list property, so that your flow can produce as many [outputs](https://kestra.io/docs/workflow-components/outputs) as you need. Each output needs to have an `id` (the name of the output), a `type` (the same types you know from `inputs` e.g. `STRING`, `URI` or `JSON`) and `value` which is the actual output value that will be stored in internal storage and passed to other flows when needed. | | `concurrency` | This property allows you to control the number of [concurrent executions](https://kestra.io/docs/workflow-components/concurrency) of a given flow by setting the `limit` key. Executions beyond that limit will be queued by default — you can customize that by configuring the `behavior` property which can be set to `QUEUE` (default), `CANCEL` or `FAIL`. | | `retry` | This property allows you set a flow-level `retry` policy to restart the execution if any task fails. The retry `behavior` is customizable — you can choose to `CREATE_NEW_EXECUTION` or `RETRY_FAILED_TASK` (default). Only with the `CREATE_NEW_EXECUTION` behavior, the `attempt` of the execution is incremented. Otherwise, only the failed task run is restarted (incrementing the attempt of the task run rather than the execution). Apart from the `behavior` property, the `retry` policy is identical to [task retries](https://kestra.io/docs/workflow-components/retries). | +| `listeners` | The list of listeners (deprecated). | ### Task documentation @@ -57,9 +58,11 @@ The following core properties are available in all tasks. | `description` | Your custom [documentation](https://kestra.io/docs/workflow-components/descriptions) of what the task does | | `retry` | How often should the task be retried in case of a failure, and the [type of retry strategy](https://kestra.io/docs/workflow-components/retries) | | `timeout` | The [maximum time allowed](https://kestra.io/docs/workflow-components/timeout) for the task to complete | +| `runIf` | Skip a task if the provided condition evaluates to false | | `disabled` | A boolean flag indicating whether the task is [disabled or not](https://kestra.io/docs/workflow-components/disabled); if set to `true`, the task will be skipped during the execution | | `workerGroup` | The [group of workers](https://kestra.io/docs/enterprise/worker-group) that are eligible to execute the task; you can specify a `workerGroup.key` and a `workerGroup.fallback` (by default WAIT) | | `allowFailure` | A boolean flag allowing to continue the execution even if this task fails | +| `allowWarning` | A boolean flag allowing to mark a task run as Success despite Warnings | | `logLevel` | The level of log detail to be stored. | | `logToFile` | A boolean that lets you store logs as a file in internal storage. That file can be previewed and downloaded from the Logs and Gantt Execution tabs. When set to true, logs aren’t saved in the database, which is useful for tasks that produce a large amount of logs that would otherwise take up too much space. The same property can be set on triggers. | @@ -211,10 +214,12 @@ The table below lists common Pebble expressions and functions. --- -The table below lists Pebble filter expressions: +The table below lists Pebble functions and filter expressions: | Filter | Example and Description | |------------------|----------------------------------------------------------------------------------------------------------------------------------| +| `errorLogs()` | `{{ errorLogs() }}` — Allows you to enrich your alert notifications with context about why Execution failed incl. information about failed task runs and their error stacktraces. | +| `appLink()` | `{{ appLink('appId') }}` — Returns the URL of the App linked to the current Execution. To get the base URL of the app allowing to create new Executions, add `baseUrl=true` e.g. `{{ appLink('yourAppId', baseUrl=true) }}`. If there is only one App linked to the flow, you can skip the App ID argument e.g. `{{ appLink() }}`. | | `abs` | `{{ -7 \| abs }}` — Returns the absolute value of -7, resulting in 7. | | `number` | `{{ "123" \| number }}` — Parses the string "123" into the number 123. | | `numberFormat` | `{{ 12345.6789 \| numberFormat("###,###.##") }}` — Formats the number 12345.6789 as "12,345.68". |