diff --git a/docs/build/input.md b/docs/build/input.md index c873df4..d6cd1f4 100644 --- a/docs/build/input.md +++ b/docs/build/input.md @@ -11,6 +11,8 @@ To interact with the various tools and services, Flowpipe also includes an `inte Sending notifications is a common pattern, and often users will want to route a request to more than one user, group, or channel, and via more than one delivery mechanism. For instance, you may want to request approval via Slack AND email. The `notifier` resource allows you to define a list of integrations to send notifications to. Like `integration`, a `notifier` is an installation-level configuration resource. +Flowpipe [integrations](/docs/reference/config-files/integration/) require callback endpoints, so they only work in [server-mode](/docs/run/server). When you run a pipeline in [client-mode](/docs/run#operating-modes), notifications for [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) steps will only appear on the command line, regardless of your `notifier` and `integration` configuration. To send [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) requests to external services, you must run [Flowpipe server](/docs/run/server)! + ## Adding an input step to your pipeline @@ -51,7 +53,24 @@ pipeline "play_a_game" { This pipeline will prompt the user to select a game to play using a `select` box (there are other [input step types](/docs/flowpipe-hcl/step/input#input-types), such as `text`, `button`, and `multiselect`). After the user selects a game, the pipeline will send back a message with a hyperlink to the selected game. -The `input` and `message` steps route messages to an [integration](/docs/reference/config-files/integration) via a [notifier](/docs/reference/config-files/notifier). You don't need to create these to get started though; Flowpipe creates a default [`http` integration](/docs/reference/config-files/integration/http) as well as a [default notifier](/docs/reference/config-files/notifier#default-notifier) that routes to it. + +## Running in Client-Mode + +If you run the pipeline in [client-mode](/docs/run#operating-modes), pipes will prompt you on the console and wait for your response. + +![](/images/docs/build/input_console_select_game.png) + + +Once you respond, the pipeline will continue. + +![](/images/docs/build/play_game_console.png) + + +## Running in Server-Mode + +Inputs and messages are sent only to the console when running in client-mode, which is suitable for testing your pipelines, or for running pipelines that do not require coordination with others. Running in server-mode, however, allows you to route messages and inputs to external systems and services, like Slack or email. + +When running in server-mode, the `input` and `message` steps route messages to an [integration](/docs/reference/config-files/integration) via a [notifier](/docs/reference/config-files/notifier). You don't need to create these to get started though; Flowpipe creates a default [`http` integration](/docs/reference/config-files/integration/http) as well as a [default notifier](/docs/reference/config-files/notifier#default-notifier) that routes to it. Integrations are only loaded in [server mode](/docs/run/server), so let's start the Flowpipe server: ```bash diff --git a/docs/flowpipe-hcl/step/input.md b/docs/flowpipe-hcl/step/input.md index 2e747a2..79b3f59 100644 --- a/docs/flowpipe-hcl/step/input.md +++ b/docs/flowpipe-hcl/step/input.md @@ -5,7 +5,12 @@ sidebar_label: input # input -Use the `input` step primitive to prompt for user input. The pipeline will send the prompt to one or more [integrations](/docs/reference/config-files/integration) via a [notifier](/docs/reference/config-files/notifier). It will then pause and wait for a response. When a response is received, the pipeline will continue and the step will return the selected `value`. +Use the `input` step primitive to prompt for user input. When the pipeline reaches an `input` step, it will prompt the user for input and then pause and wait for a response. When a response is received, the pipeline will continue and the step will return the selected `value`. + +When you run a pipeline in [client-mode](/docs/run#operating-modes), notifications for `input` steps will only appear on the command line. + +In [server-mode](/docs/run/server), notifications for `input` steps are not sent to the console. Instead, they are sent to [integrations](/docs/reference/config-files/integration/) such as Slack or Email via a [notifier](/docs/reference/config-files/notifier), allowing you to create collaborative workflows that integrate with your preferred communication channels. + ```hcl pipeline "my_step" { @@ -85,6 +90,10 @@ This step also supports the [common step arguments](/docs/flowpipe-hcl/step#comm ---- ### Button - Simple +##### Console (Client-Mode) +![](/images/docs/flowpipe-hcl/input_button_simple_console.png) + + ##### HTTP ![](/images/docs/flowpipe-hcl/input_button_simple_http.png) @@ -116,6 +125,9 @@ pipeline "my_pipe" { ### Button - With labels and values +##### Console (Client-Mode) +![](/images/docs/flowpipe-hcl/input_button_simple_console.png) + ##### HTTP ![](/images/docs/flowpipe-hcl/input_button_simple_http.png) @@ -154,6 +166,10 @@ pipeline "my_pipe" { ### Select - basic +##### Console (Client-Mode) +![](/images/docs/flowpipe-hcl/input_select_simple_console.png) + + ##### HTTP ![](/images/docs/flowpipe-hcl/input_select_simple_http_open.png) @@ -162,7 +178,7 @@ pipeline "my_pipe" { ```hcl -pipeline "my_pipe" { +pipeline "my_select" { step "input" "select_region" { notifier = notifier.default @@ -191,6 +207,9 @@ pipeline "my_pipe" { #### Select - with labels & default selection +##### Console (Client-Mode) +![](/images/docs/flowpipe-hcl/input_select_labels_console.png) + ##### HTTP ![](/images/docs/flowpipe-hcl/input_select_labels_http_open.png) @@ -199,7 +218,7 @@ pipeline "my_pipe" { ```hcl -pipeline "my_pipe" { +pipeline "my_select_labels" { step "input" "select_region" { notifier = notifier.default @@ -237,6 +256,10 @@ pipeline "my_pipe" { ### Multiselect - basic +##### Console (Client-Mode) +![](/images/docs/flowpipe-hcl/input_multiselect_simple_console.png) + + ##### HTTP ![](/images/docs/flowpipe-hcl/input_multiselect_simple_http_selected.png) @@ -245,7 +268,7 @@ pipeline "my_pipe" { ```hcl -pipeline "my_pipe" { +pipeline "my_multi" { step "input" "select_regions" { notifier = notifier.default @@ -275,6 +298,10 @@ pipeline "my_pipe" { ### Multiselect with labels & default selection +##### Console (Client-Mode) +![](/images/docs/flowpipe-hcl/input_multiselect_labels_console_selected.png) + + ##### HTTP ![](/images/docs/flowpipe-hcl/input_multiselect_labels_http_selected.png) @@ -283,7 +310,7 @@ pipeline "my_pipe" { ```hcl -pipeline "my_pipe" { +pipeline "my_multi_labels" { step "input" "select_regions" { notifier = notifier.default diff --git a/docs/flowpipe-hcl/step/message.md b/docs/flowpipe-hcl/step/message.md index b04bdac..ffc6699 100644 --- a/docs/flowpipe-hcl/step/message.md +++ b/docs/flowpipe-hcl/step/message.md @@ -5,7 +5,11 @@ sidebar_label: message # message -Use the `message` step to send a message to an [integration](/docs/reference/config-files/integration) via a [notifier](/docs/reference/config-files/notifier). +Use the `message` step to send a one-way notification message from your pipeline. + +When you run a pipeline in [client-mode](/docs/run#operating-modes), notifications for `message` steps will only appear on the command line. + +In [server-mode](/docs/run/server), notifications for `message` steps are not sent to the console. Instead, they are sent to [integrations](/docs/reference/config-files/integration/) such as Slack or Email via a [notifier](/docs/reference/config-files/notifier), allowing you to create collaborative workflows that integrate with your preferred communication channels. ```hcl diff --git a/docs/learn.md b/docs/learn.md index 55f7512..f7fac22 100644 --- a/docs/learn.md +++ b/docs/learn.md @@ -57,7 +57,15 @@ flowpipe pipeline run learn_flowpipe ![](/images/docs/learn/get-ipv4.png) -Flowpipe runs the pipeline and prints information about the currently executing steps. When the pipeline run completes, Flowpipe prints the pipeline's outputs. +Flowpipe runs the pipeline and prints its outputs once it is complete. + +When troubleshooting, it's often useful to view more information about the currently executing steps. You can use the `--verbose` flag to show this detailed information. + +```bash +flowpipe pipeline run learn_flowpipe --verbose +``` + +![](/images/docs/learn/get-ipv4-verbose.png) ## Using mods @@ -201,9 +209,6 @@ pipeline "learn_flowpipe" { Now we have a pipeline that can get the local forecast - let's send it somewhere! The [message step](/docs/flowpipe-hcl/step/message) provides a mechanism for sending messages via multiple communication channels, such as Slack and Email. - -The `message` step (along with the [`input` step](/docs/build/input)) routes messages to an [integration](/docs/reference/config-files/integration) via a [notifier](/docs/reference/config-files/notifier). You don't need to create these to get started though; Flowpipe creates a default [`http` integration](/docs/reference/config-files/integration/http) as well as a [default notifier](/docs/reference/config-files/notifier#default-notifier) that routes to it. - Add this step to the `learn_flowpipe` pipeline. ```hcl @@ -220,8 +225,19 @@ And run the pipeline again. flowpipe pipeline run learn_flowpipe ``` -You should see the message printed to the console when you run the pipeline. You can send it via [Email](/docs/reference/config-files/integration/email), [Slack](/docs/reference/config-files/integration/slack) or [Microsoft Teams](/docs/reference/config-files/integration/msteams) without modifying the pipeline code. Just create the appropriate [integrations](/docs/reference/config-files/integration), add them to the [default notifier](/docs/reference/config-files/notifier#default-notifier), and run the pipeline again! +You should see the message printed to the console when you run the pipeline. + +Console messages and inputs are useful, but Flowpipe can also route these input requests, approvals and notifications to external systems like Slack, MS Teams, and Email! + +Flowpipe [Integrations](/docs/reference/config-files/integration) allow you to interface with external systems. [Notifiers](/docs/reference/config-files/notifier) allow you to route [message](/docs/flowpipe-hcl/step/message) and [input](/docs/build/input) steps to one or more integrations. Integrations are only loaded in [server-mode](/docs/run/server). + +Flowpipe server creates a default [`http` integration](/docs/reference/config-files/integration/http) as well as a [default notifier](/docs/reference/config-files/notifier#default-notifier) that routes to it, but you can send it via [Email](/docs/reference/config-files/integration/email), [Slack](/docs/reference/config-files/integration/slack) or [Microsoft Teams](/docs/reference/config-files/integration/msteams) without modifying the pipeline code. Just create the appropriate [integrations](/docs/reference/config-files/integration), add them to the [default notifier](/docs/reference/config-files/notifier#default-notifier), and run the pipeline again from a server instance! + +```bash +flowpipe server & +flowpipe pipeline run learn_flowpipe --host local +``` ![](/images/docs/learn/slack-weather-report.png) diff --git a/docs/reference/cli/index.md b/docs/reference/cli/index.md index 90ba2de..4a2de56 100644 --- a/docs/reference/cli/index.md +++ b/docs/reference/cli/index.md @@ -43,6 +43,14 @@ sidebar_label: Flowpipe CLI + + --data-dir + + Sets the event store data directory. Flowpipe defaults to the `.flowpipe` directory in the current mod directory. This argument allows you to specify a different directory. + + + + -h, --help Help for Flowpipe. diff --git a/docs/reference/cli/pipeline.md b/docs/reference/cli/pipeline.md index 6f5d116..f3a473c 100644 --- a/docs/reference/cli/pipeline.md +++ b/docs/reference/cli/pipeline.md @@ -30,6 +30,7 @@ flowpipe pipeline run pipeline_name [args] |-|-|- | `--arg string=string` | `run` | Specify the value of a pipeline argument. Multiple `--arg` arguments may be passed. | `--detach` | `run` | Start the pipeline and return immediately. By default, `flowpipe pipeline run` will run the pipeline and wait for the results. You may only use `--detach` when running a pipeline from a server instance (by specifying `--host`, for example). +| `--execution-id` | `run`| Specify pipeline execution id. Execution id will generated if not provided. | `--var string=string` | `run`| Specify the value of a variable. Multiple `--var` arguments may be passed. | `--var-file strings`| `run`| Specify an .fpvar file containing variable values. | `--verbose` | `run` | View detailed event information, including step arguments and attributes. diff --git a/docs/reference/config-files/integration/index.md b/docs/reference/config-files/integration/index.md index 6c4399d..2fa3baf 100644 --- a/docs/reference/config-files/integration/index.md +++ b/docs/reference/config-files/integration/index.md @@ -6,7 +6,12 @@ sidebar_label: integration # Integration -Use the `integration` block to configure how pipelines interact with external system, such as Slack or Email, via [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) steps. Integrations are *configuration* resources, defined in configuration files (`.fpc`), not mod files(`.fp`). Here's why: +Use the `integration` block to configure how pipelines interact with an external system, such as Slack or Email, via [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) steps. + +Like [triggers](/docs/build/triggers), integrations require callback endpoints, so they only work in [server-mode](/docs/run/server). When you run a pipeline in [client-mode](/docs/run#operating-modes), notifications for [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) steps will only appear on the command line, regardless of your `notifier` and `integration` configuration. To send [input](/docs/flowpipe-hcl/step/input) and [message](/docs/flowpipe-hcl/step/message) requests to your integrations, you must run [Flowpipe server](/docs/run/server)! + + +Integrations are *configuration* resources, defined in configuration files (`.fpc`), not mod files(`.fp`). Here's why: - The settings are installation-specific and may contain secrets. - The settings are usually the same for *all* mods in a given installation. diff --git a/docs/run/index.md b/docs/run/index.md index 0d6e850..ab167b3 100644 --- a/docs/run/index.md +++ b/docs/run/index.md @@ -20,6 +20,6 @@ Flowpipe will load [configuration files](/docs/reference/config-files) (`*.fpc`) Flowpipe can operate in 2 modes. -By default, Flowpipe runs in **Client-only Mode**. Flowpipe loads the mod, runs the command, and exits. [Triggers](/docs/build/triggers) are not enabled in Client-Only Mode. +By default, Flowpipe runs in **Client-only Mode**. Flowpipe loads the mod, runs the command, and exits. [Triggers](/docs/build/triggers) are not enabled in Client-Only Mode. [Integrations](/docs/reference/config-files/integration/) are not available in Client-Only mode, and all [message](/docs/flowpipe-hcl/step/message) and [input](/docs/flowpipe-hcl/step/input) steps will route to the console. -If you run Flowpipe in **Server Mode** mode, Flowpipe will run an API server (on port `7103` by default). In [this mode](/docs/run/server), you can create [triggers](/docs/flowpipe-hcl/trigger) that run pipelines [on a schedule](/docs/flowpipe-hcl/trigger/schedule) or in response to events such as [webhooks](/docs/flowpipe-hcl/trigger/http). After you start the Flowpipe server, you can run Flowpipe commands against it by specifying the [--host](/docs/reference/cli) argument. +If you run Flowpipe in **[Server Mode](/docs/run/server)** mode, Flowpipe will run an API server (on port `7103` by default). In Server-Mode, you can create [triggers](/docs/flowpipe-hcl/trigger) that run pipelines [on a schedule](/docs/flowpipe-hcl/trigger/schedule) or in response to events such as [webhooks](/docs/flowpipe-hcl/trigger/http). Your pipelines can send [messages](/docs/flowpipe-hcl/step/message) and prompt for [input](/docs/flowpipe-hcl/step/input) via Slack, Email, or other [integrations](/docs/reference/config-files/integration/). After you start the Flowpipe server, you can run Flowpipe commands against it by specifying the [--host](/docs/reference/cli) argument. diff --git a/images/build/input_console_select_game.png b/images/build/input_console_select_game.png new file mode 100644 index 0000000..0eb9161 Binary files /dev/null and b/images/build/input_console_select_game.png differ diff --git a/images/build/play_game_console.png b/images/build/play_game_console.png new file mode 100644 index 0000000..e91d8d7 Binary files /dev/null and b/images/build/play_game_console.png differ diff --git a/images/flowpipe-hcl/input_button_simple_console.png b/images/flowpipe-hcl/input_button_simple_console.png new file mode 100644 index 0000000..7409d6e Binary files /dev/null and b/images/flowpipe-hcl/input_button_simple_console.png differ diff --git a/images/flowpipe-hcl/input_multiselect_labels_console_selected.png b/images/flowpipe-hcl/input_multiselect_labels_console_selected.png new file mode 100644 index 0000000..38daada Binary files /dev/null and b/images/flowpipe-hcl/input_multiselect_labels_console_selected.png differ diff --git a/images/flowpipe-hcl/input_multiselect_simple_console.png b/images/flowpipe-hcl/input_multiselect_simple_console.png new file mode 100644 index 0000000..9fa0cc3 Binary files /dev/null and b/images/flowpipe-hcl/input_multiselect_simple_console.png differ diff --git a/images/flowpipe-hcl/input_select_labels_console.png b/images/flowpipe-hcl/input_select_labels_console.png new file mode 100644 index 0000000..ebaee73 Binary files /dev/null and b/images/flowpipe-hcl/input_select_labels_console.png differ diff --git a/images/flowpipe-hcl/input_select_simple_console.png b/images/flowpipe-hcl/input_select_simple_console.png new file mode 100644 index 0000000..cf34adc Binary files /dev/null and b/images/flowpipe-hcl/input_select_simple_console.png differ diff --git a/images/learn/get-ipv4-verbose.png b/images/learn/get-ipv4-verbose.png new file mode 100644 index 0000000..7691761 Binary files /dev/null and b/images/learn/get-ipv4-verbose.png differ diff --git a/images/learn/get-ipv4.png b/images/learn/get-ipv4.png index 6c98782..e6be3cb 100644 Binary files a/images/learn/get-ipv4.png and b/images/learn/get-ipv4.png differ diff --git a/images/learn/reallyfreegeoip.png b/images/learn/reallyfreegeoip.png index 977bcae..73656f9 100644 Binary files a/images/learn/reallyfreegeoip.png and b/images/learn/reallyfreegeoip.png differ diff --git a/images/learn/weather-report.png b/images/learn/weather-report.png index 61820d5..a9b2052 100644 Binary files a/images/learn/weather-report.png and b/images/learn/weather-report.png differ