This is an automated email from the ASF dual-hosted git repository.
bamaer pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/main by this push:
new d0dad1283d Add a Working with parameters page and link it from the
related pages fixes. #2517 (#9002)
d0dad1283d is described below
commit d0dad1283d9aed7198067d9ebcf463e9cc6bccef
Author: Adalennis <[email protected]>
AuthorDate: Sun Oct 18 15:26:19 2026 +0200
Add a Working with parameters page and link it from the related pages
fixes. #2517 (#9002)
* Add a Working with parameters page and link it from the related pages.
#2517
* An empty -p value gives a parameter its default value, even when a
variable with the same name exists. #2517
---
docs/hop-user-manual/modules/ROOT/nav.adoc | 1 +
.../ROOT/pages/fields-parameters-variables.adoc | 3 +-
.../modules/ROOT/pages/hop-run/index.adoc | 2 +-
.../ROOT/pages/pipeline/create-pipeline.adoc | 1 +
.../pages/pipeline/run-preview-debug-pipeline.adoc | 2 +
.../modules/ROOT/pages/variables.adoc | 3 +
.../ROOT/pages/variables/parameter-passing.adoc | 1 +
.../modules/ROOT/pages/variables/parameters.adoc | 97 ++++++++++++++++++++++
.../ROOT/pages/workflow/create-workflow.adoc | 1 +
.../ROOT/pages/workflow/run-debug-workflow.adoc | 2 +
10 files changed, 111 insertions(+), 2 deletions(-)
diff --git a/docs/hop-user-manual/modules/ROOT/nav.adoc
b/docs/hop-user-manual/modules/ROOT/nav.adoc
index 5bba109eb7..0d82bbbdf5 100644
--- a/docs/hop-user-manual/modules/ROOT/nav.adoc
+++ b/docs/hop-user-manual/modules/ROOT/nav.adoc
@@ -465,6 +465,7 @@ under the License.
//::=END AUTO GENERATED LINKS ACTIONS
* xref:fields-parameters-variables.adoc[Fields, parameters, and variables]
* xref:variables.adoc[Variables]
+** xref:variables/parameters.adoc[Working with parameters]
** xref:variables/parameter-passing.adoc[Passing parameters to a child]
* xref:vfs.adoc[Virtual File System]
** xref:vfs/aws-s3-vfs.adoc[Amazon Web Services S3]
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/fields-parameters-variables.adoc
b/docs/hop-user-manual/modules/ROOT/pages/fields-parameters-variables.adoc
index 3dc2a674d4..993007aac9 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/fields-parameters-variables.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/fields-parameters-variables.adoc
@@ -103,7 +103,7 @@ Rules that matter in practice:
* Every action and transform that runs a child resolves parameters this way:
the Pipeline and Workflow actions, the Pipeline and Workflow Executor
transforms, the Mapping transforms, and Metadata Injection.
* *Get Parameters* fills the tab from the child you selected. It does not walk
further up the call stack.
-See xref:pipeline/create-pipeline.adoc[Create a Pipeline] for the properties
dialog.
+See xref:variables/parameters.adoc[Working with parameters] for a step-by-step
guide, and xref:pipeline/create-pipeline.adoc[Create a Pipeline] for the
properties dialog.
== Variables
@@ -155,6 +155,7 @@ The places you can define variables, and which level
inherits from which, are li
== See also
+* xref:variables/parameters.adoc[Working with parameters] — declare a
parameter and give it a value
* xref:variables/parameter-passing.adoc[Passing parameters to a child pipeline
or workflow] — the exact precedence rules
* xref:variables.adoc[Variables] — syntax, hierarchy, resolvers, and built-in
names
* xref:pipeline/transforms/setvariable.adoc[Set Variables] and
xref:pipeline/transforms/getvariable.adoc[Get variables]
diff --git a/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
b/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
index f4ba7c569c..902cd998a6 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/hop-run/index.adoc
@@ -139,7 +139,7 @@ Not needed when `-e` is set.
|```-p```
|```--parameters```
-|A comma separated list of PARAMETER=VALUE pairs
+|A comma separated list of PARAMETER=VALUE pairs. See
xref:variables/parameters.adoc#_from_hop_run[Working with parameters] for which
value a parameter gets.
|```-ps```
|```--parameters-separator```
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/pipeline/create-pipeline.adoc
b/docs/hop-user-manual/modules/ROOT/pages/pipeline/create-pipeline.adoc
index 06ad1bc6e8..60f3069b1b 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/pipeline/create-pipeline.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/pipeline/create-pipeline.adoc
@@ -193,6 +193,7 @@ The Pipeline tab allows you to specify general properties
about the pipeline inc
The parameters tab allows you to specify parameters specific for the pipeline.
Parameters are defined by a name, a default value and a description.
+See xref:variables/parameters.adoc[Working with parameters] for how to use
them and give them a value.
image::hop-gui/pipeline/parameters-pipeline.png[Parameters
properties,75%,align="left"]
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/pipeline/run-preview-debug-pipeline.adoc
b/docs/hop-user-manual/modules/ROOT/pages/pipeline/run-preview-debug-pipeline.adoc
index 217c39f429..a7adc084ae 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/pipeline/run-preview-debug-pipeline.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/pipeline/run-preview-debug-pipeline.adoc
@@ -52,6 +52,8 @@ Choose the logging level as described below.
|Row Level|Logging at row level.
|===
+If the pipeline has parameters, give them a value on the *Parameters* tab of
this dialog, or leave the value empty to use the default value. See
xref:variables/parameters.adoc#_from_hop_gui[Working with parameters].
+
Make sure your configuration is selected and hit 'Launch'.
When a pipeline has run successfully, a check mark is displayed in the upper
right corner of each transform. With more than one copy, that check is shown
only when every copy of the transform has finished. Until then the corner shows
how many copies are done. See
xref:pipeline/specify-copies.adoc#finished-copies[Specify copies].
diff --git a/docs/hop-user-manual/modules/ROOT/pages/variables.adoc
b/docs/hop-user-manual/modules/ROOT/pages/variables.adoc
index a79290af95..fdd60e7d18 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/variables.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/variables.adoc
@@ -152,6 +152,8 @@ This also means that's important to know where variables
can be set and used and
|Metadata objects|Inherited by the place where it is loaded
|===
+When a project and its environment define a variable with the same name, the
project value is used.
+
== Parameters
Pipelines and workflows can (optionally) accept parameters.
@@ -162,6 +164,7 @@ When the pipeline or workflow starts, each parameter is
activated as a variable
Pass parameters from a parent through the *Parameters* tab of a
xref:workflow/actions/pipeline.adoc[Pipeline] action,
xref:workflow/actions/workflow.adoc[Workflow] action,
xref:pipeline/transforms/pipeline-executor.adoc[Pipeline Executor], or
xref:pipeline/transforms/workflow-executor.adoc[Workflow Executor].
Declare the same names on the receiving pipeline or workflow.
+How to declare a parameter and give it a value from Hop Gui, from hop-run or
from another pipeline or workflow is explained in
xref:variables/parameters.adoc[Working with parameters].
How parameters differ from fields and from other variables is covered in
xref:fields-parameters-variables.adoc[Fields, parameters, and variables].
The exact rules that decide which value a parameter ends up with when one
pipeline or workflow starts another are in
xref:variables/parameter-passing.adoc[Passing parameters to a child pipeline or
workflow].
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/variables/parameter-passing.adoc
b/docs/hop-user-manual/modules/ROOT/pages/variables/parameter-passing.adoc
index c70e4dea21..2a19ced1af 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/variables/parameter-passing.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/variables/parameter-passing.adoc
@@ -231,5 +231,6 @@ Naming a column that is not present in the incoming row
does not yield an empty
== See also
+* xref:variables/parameters.adoc[Working with parameters] - declare a
parameter and give it a value
* xref:variables.adoc[Variables] - syntax, hierarchy, resolvers, built-in names
* xref:fields-parameters-variables.adoc[Fields, parameters, and variables] -
how the three concepts differ
diff --git a/docs/hop-user-manual/modules/ROOT/pages/variables/parameters.adoc
b/docs/hop-user-manual/modules/ROOT/pages/variables/parameters.adoc
new file mode 100644
index 0000000000..29832ce84e
--- /dev/null
+++ b/docs/hop-user-manual/modules/ROOT/pages/variables/parameters.adoc
@@ -0,0 +1,97 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+ http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+////
+[[WorkingWithParameters]]
+:imagesdir: ../../assets/images
+:description: How to declare a parameter on a pipeline or workflow, use it,
and give it a value from Hop Gui, from hop-run or from another pipeline or
workflow.
+
+= Working with parameters
+
+A parameter is an input of a pipeline or workflow.
+You declare it once, use it like any other variable, and give it a different
value every time the pipeline or workflow runs.
+
+How parameters compare with fields and other variables is explained in
xref:fields-parameters-variables.adoc[Fields, parameters, and variables].
+
+== Declare a parameter
+
+. Double-click an empty spot of the pipeline or workflow canvas to open its
properties.
+. On the *Parameters* tab, add a row for every parameter:
++
+[options="header", width="90%", cols="1,3"]
+|===
+|Column|Description
+|Parameter|The name of the parameter. You use it as `+${NAME}+`.
+|Default value|The value the parameter has when it is not given one. It can be
empty, and it can contain other variables, for example
`+${PROJECT_HOME}/data/sample.csv+`.
+|Description|A short explanation. It is shown next to the parameter when you
run the pipeline or workflow from Hop Gui.
+|===
+
+== Use a parameter
+
+When the pipeline or workflow starts, every parameter becomes a variable with
the same name.
+Use it as `+${NAME}+` in any option that accepts variables, for example
`+${INPUT_FILE}+` as the file name of a
xref:pipeline/transforms/textfileinput.adoc[Text file input] transform.
+
+A parameter always sets its variable, even when its value is empty.
+It hides a project, environment or other variable of the same name, unless
that variable is used to give the parameter its value, as described below.
+
+== Give a parameter a value
+
+=== From Hop Gui
+
+When you run a pipeline or workflow, the *Run Options* dialog has two tabs:
+
+Parameters::
+One row for every parameter, with its *Default value* and *Description*.
+Enter a value in the *Value* column, or leave it empty to use the default
value.
+The *Value* column is empty every time the dialog opens: Hop Gui doesn't
remember the values of the previous run.
+
+Variables::
+The variables the pipeline or workflow uses, other than its parameters, with
their current value.
+Change a value to use another one for this run.
+
+A parameter with an empty *Value* gets its default value, even when the
project or the environment has a variable with the same name, or you add one on
the *Variables* tab.
+
+Preview and Debug open *Run Options* only when you click *Configure*.
+With *Quick Launch*, every parameter that has a default value gets it.
+
+=== From hop-run
+
+Pass parameters to xref:hop-run/index.adoc[hop-run] with `-p NAME=value`.
+Separate several parameters with commas.
+Wrap a value that contains a comma in double quotes, and the whole option in
single quotes so the shell keeps them:
+
+[source,bash]
+----
+./hop-run.sh -j my-project -r local -f '${PROJECT_HOME}/load-orders.hpl' \
+ -p 'INPUT_FILE=/data/orders.csv,COUNTRIES="BE,NL"'
+----
+
+`hop-run` gives every parameter the first value it finds:
+
+. The value passed with `-p`.
+. The value of a variable with the same name, for example a project or
environment variable, or a system property passed with `-s`.
+. The default value.
+
+An empty value, like `-p INPUT_FILE=`, gives the parameter its default value,
even when a variable with the same name exists.
+
+A name passed with `-p` that the pipeline or workflow doesn't declare is set
as a variable.
+
+NOTE: Unlike Hop Gui, `hop-run` uses a project or environment variable with
the same name before the default value.
+
+=== From another pipeline or workflow
+
+The xref:workflow/actions/pipeline.adoc[Pipeline] and
xref:workflow/actions/workflow.adoc[Workflow] actions, the
xref:pipeline/transforms/pipeline-executor.adoc[Pipeline Executor] and
xref:pipeline/transforms/workflow-executor.adoc[Workflow Executor] transforms,
and the other actions and transforms that start a pipeline or workflow have a
*Parameters* tab.
+List a parameter of the child there with a value or a field, and it gets that
value; otherwise it gets its default value, unless *Pass parent values to
matching parameters* is enabled.
+The exact rules are in xref:variables/parameter-passing.adoc[Passing
parameters to a child pipeline or workflow].
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/create-workflow.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/create-workflow.adoc
index 51ff58bd21..ca799a5355 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/create-workflow.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/create-workflow.adoc
@@ -155,6 +155,7 @@ The Workflow tab allows you to specify general properties
about the workflow inc
The parameters tab allows you to specify parameters specific for the workflow.
Parameters are defined by a name, a default value and a description.
+See xref:variables/parameters.adoc[Working with parameters] for how to use
them and give them a value.
image::hop-gui/workflow/parameters-properties.png[Parameters
properties,75%,align="left"]
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/run-debug-workflow.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/run-debug-workflow.adoc
index c4ad7535b5..87963a6890 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/run-debug-workflow.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/run-debug-workflow.adoc
@@ -50,6 +50,8 @@ Choose the logging level as described below.
|Row Level|Logging at row level.
|===
+If the workflow has parameters, give them a value on the *Parameters* tab of
this dialog, or leave the value empty to use the default value. See
xref:variables/parameters.adoc#_from_hop_gui[Working with parameters].
+
Make sure your configuration is selected and hit 'Launch'.
image::getting-started/getting-started-run-workflow-with-config.png[Hop - New
Workflow With Config Dialog,75%,align="left"]
