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 3337131f5e Document the result of the File exists, Create file, Delete
files, Shell, Move files and Zip file actions. #8970 (#9024)
3337131f5e is described below
commit 3337131f5e84f9389c4b49aa06f31a784b320ef1
Author: Adalennis <[email protected]>
AuthorDate: Tue Oct 20 11:47:04 2026 +0200
Document the result of the File exists, Create file, Delete files, Shell,
Move files and Zip file actions. #8970 (#9024)
* Document the result of the File exists, Create file, Delete files, Shell,
Move files and Zip file actions. #8970
* Correct the Zip file and Shell result rows, and the Copy previous results
to args option of Delete files and Move files. #8970
---
.../ROOT/pages/workflow/actions/createfile.adoc | 15 +++++++++++-
.../ROOT/pages/workflow/actions/deletefiles.adoc | 19 +++++++++++++--
.../ROOT/pages/workflow/actions/fileexists.adoc | 14 ++++++++++-
.../ROOT/pages/workflow/actions/movefiles.adoc | 19 +++++++++++++--
.../modules/ROOT/pages/workflow/actions/shell.adoc | 28 +++++++++++++++++-----
.../ROOT/pages/workflow/actions/zipfile.adoc | 15 ++++++++++++
6 files changed, 98 insertions(+), 12 deletions(-)
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfile.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfile.adoc
index 4e1d3687b2..29bf706c98 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfile.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfile.adoc
@@ -34,4 +34,17 @@ The `Create File` action creates an empty file. This is
useful for creating trig
|Fail if file exists|The workflow action will follow the failure outgoing hop
when the file to be created already exists (empty or not) and this option is
switched on. +
The default is on.
|Add filename to result|Add the filename for the file that was created in this
action to the results.
-|===
\ No newline at end of file
+|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The file was created, with any missing parent folders, or it already
existed and *Fail if file exists* is off.
+|False|The file already exists and *Fail if file exists* is on, with 0 errors,
or no *File name* is set, also with 0 errors. When the file can't be created,
for example in a folder that can't be written, the number of errors is 1.
+|Result files|With *Add filename to result*, the file is added, also when it
already existed, even when the action is false because of *Fail if file exists*.
+|Result rows|Passed on unchanged.
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefiles.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefiles.adoc
index e25936ebf4..b6b3fe4dcb 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefiles.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefiles.adoc
@@ -30,10 +30,25 @@ The `Delete files` action deletes a set of specified files,
optionally with subf
|===
|Option|Description
|Action name|The name of the workflow action.
-|Include Subfolders|Also delete the subfolders in the folder selection
-|Copy previous results to args?|Enable this if the set of files comes from a
previous workflow action (as part of the result files)
+|Include Subfolders|Also delete the matching files in the subfolders of a
folder. Folders are never deleted.
+|Copy previous results to args|Take the files and folders to delete from the
result rows of a previous action: the path in the first field and the wildcard
in the second. See <<_result,Result>>.
|File/Folder|The file or folder to delete
|Wildcard|The regular expression matching files to delete if the previous
option is a folder.
For example to delete all files ending in .dat, the regular expression would
be ".*\.dat$".
|Files/Folders|The complete list of files/folders to delete
|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|Every file and folder in the list was processed. A path that doesn't
exist counts as already deleted. For a single file the wildcard is not used.
+|False|A file could not be deleted. The number of errors is the number of
entries in the list that failed.
+|Result files|Passed on unchanged. The deleted files are not added.
+|Result rows|Passed on unchanged. With *Copy previous results to args*, the
action takes the path from the first field and the wildcard from the second
field of each result row, and ignores the list in the dialog, also when there
are no result rows. A row with fewer than two fields stops the action: the
remaining rows are not processed, and the action is still true.
+|===
+
+NOTE: An invalid regular expression in *Wildcard* deletes nothing, and the
action is still true.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/fileexists.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/fileexists.adoc
index c72a9afdd0..b8e823598a 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/fileexists.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/fileexists.adoc
@@ -46,7 +46,7 @@ As soon as the task is complete, the file is placed in a
well-known location so
|===
|Option|Description
|Action name|The name of the workflow action.
-|Filename field|Specify the filename and path of the file to verify.
+|File name|Specify the filename and path of the file to verify.
Click Browse to navigate to the source file or folder through the VFS browser.
// |Result fieldname|The field containing the result.
// |Add filename to result|Adds the filename to the result.
@@ -54,3 +54,15 @@ Click Browse to navigate to the source file or folder
through the VFS browser.
// |File type field|The field containing the type of file.
|===
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The file or folder exists and can be read.
+|False|The file doesn't exist or can't be read, and the number of errors is 0.
The number of errors is 1 when *File name* is not set or the file can't be
checked.
+|Result files|Passed on unchanged. The file is not added.
+|Result rows|Passed on unchanged.
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/movefiles.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/movefiles.adoc
index ba793b0360..83d8be3a88 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/movefiles.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/movefiles.adoc
@@ -46,7 +46,7 @@ In this tab you can specify the files and/or folders to move.
|Include Subfolders|Also move the content of sub-folders
|Move empty folders|Also move empty folders
|Simulate|Don't actually move anything, just see if it's possible at all.
-|Copy previous results to args|Use the result files from the previous workflow
action (actions) as files and/or folders to move.
+|Copy previous results to args|Take the files and folders to move from the
result rows of a previous action: the source in the first field, the
destination in the second and the wildcard in the third. See <<_result,Result>>.
|Files / Folders |You can specify the list of files or folders with
destinations and wildcards in this grid.
|===
@@ -102,5 +102,20 @@ The default is yyyyMMdd'_'HHmmss
* Success when at least x files moved (specify x in the limit field below)
* Success when number of errors lesser than (specify the max number of errors
in the limit field below)
|Nr errors lesser than|The number of files moved or the number of errors,
depending on the success option above
-|Result files name|Add the target file names to the list of result files of
this workflow action for use in the next workflow actions.
+|Add files to result files name|Add the target file names to the list of
result files of this workflow action for use in the next workflow actions.
|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The *Success condition* is met: no errors with *Success when all works
fine*, at least *Nr errors lesser than* files moved with *Success when at least
x files moved*, or fewer errors than *Nr errors lesser than* with *Success when
number of errors lesser than* (see the note below).
+|False|The success condition is not met, for example because a source doesn't
exist, a file can't be moved, or the destination file exists and *If
destination file exists* is *Fail*. With *Success when all works fine* or
*Success when number of errors lesser than*, the action stops once the
condition is broken: the remaining files are not moved. The number of errors
counts the files and entries that failed.
+|Result files|With *Add files to result files name*, every moved file is
added, with its destination path. A file left in place by *Do nothing* is not
added. With *Simulate*, nothing is moved but the destination paths are still
added.
+|Result rows|Passed on unchanged. With *Copy previous results to args*, the
source, destination and wildcard come from the first three fields of each
result row.
+|===
+
+NOTE: With *Success when number of errors lesser than*, the action stops and
is false as soon as the number of errors reaches *Nr errors lesser than*, but
when the last file brings it to that number, the action is still true. With *If
destination file exists* set to *Fail*, a file that already exists counts as
two errors.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/shell.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/shell.adoc
index 5d17a886de..ef193d3a55 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/shell.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/shell.adoc
@@ -40,9 +40,9 @@ As an alternative to calling scripts on the host machine, you
can enter scripts
=== Return status
-The return status is provided by the operating system call.
-
-For example, in batch scripting a return value of 1 indicates that the script
was successful; a return value of 0 (zero) indicates that it was unsuccessful.
+The return status is the exit code of the script or executable.
+An exit code of 0 means success; any other exit code makes the action fail.
+See <<_result,Result>>.
You can pass command line arguments and set up logging for the Shell workflow
action.
@@ -64,7 +64,7 @@ NOTE: Variables are resolved within the script when given.
The working directory only becomes active when the shell script starts so
"Filename" should still include the full path to the script.
When the field is left empty or the working directory is invalid +${user.dir}+
will be used as working directory.
2+|Logging settings
-|Specify log file|Enable to specify a separate logging file for the execution
of this workflow.
+|Specify logfile|Enable to specify a separate logging file for the execution
of this workflow.
|Append logfile|Enable to append to the logfile as opposed to creating a new
one
|Name of log file|The directory and base name of the log file (for example
C:\logs)
|Extension of the log file|The filename extension (for example: log or txt)
@@ -79,7 +79,7 @@ See also the logging window in .14 Logging
[options="header", width="90%", cols="1,3"]
|===
|Option|Description
-|Copy previous results to arguments?|The results from a previous pipeline can
be sent to the shell script using the "Copy rows to result" transform. (as
arguments)
+|Copy previous results to args|The results from a previous pipeline can be
sent to the shell script using the "Copy rows to result" transform. (as
arguments)
|Execute for every result row|This implements looping.
If the previous workflow action returns a set of result rows, you can have
this shell script executed once for every row found.
One row is passed to this script at every execution in combination with the
copy previous result to arguments.
@@ -91,4 +91,20 @@ The **Hidden (Y/N)** column controls logging only: when set
to `Y`, the argument
=== Script tab
-This tab contains your batch or shell script if the `Insert script` option is
checked.
\ No newline at end of file
+This tab contains your batch or shell script if the `Insert script` option is
checked.
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The command ended with exit code 0. With *Execute for every result row*,
every run did.
+|False|The command ended with another exit code, or could not be started, for
example because the script file doesn't exist on Linux or macOS. On Windows,
`cmd.exe` starts anyway and returns a non-zero exit code. The number of errors
is 1. With *Execute for every result row*, the first run that fails ends the
loop: the remaining rows are not processed.
+|Result files|Passed on unchanged, plus the log file with *Specify logfile*.
+|Result rows|Passed on unchanged. With *Copy previous results to args*, the
fields of the result rows are passed as arguments: the fields of every row in a
single run, or with *Execute for every result row* the fields of the current
row in each run.
+|Metrics|Exit status: the exit code of the command; with *Execute for every
result row*, of the last run. It is not set when the command could not be
started.
+|===
+
+With *Execute for every result row* and no result rows, the command doesn't
run, and the result of the previous action is passed on, without an exit status.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/zipfile.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/zipfile.adoc
index 9da326fddb..00abff0da4 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/zipfile.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/zipfile.adoc
@@ -81,3 +81,18 @@ This is what will be taken from the rows.
2+|Result file name
|Add Zip file to result|Enable this option to add the target zip file(s) to
the result
|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The zip file was created or updated. It is also true when the zip exists
and *If zip file exists* is *Do Nothing*, which leaves it unchanged, and when
no file matches the wildcard with *Include sub-folders* off, which creates an
empty zip. With *Include sub-folders* on, no match makes the action false and
creates no zip.
+|False|The source doesn't exist, the zip exists and *If zip file exists* is
*Fail*, the zip can't be written, or a source file can't be deleted with *After
zipping*; the zip is already created then. With *After zipping* set to *Move
files*, it is also false when the folder to move to doesn't exist and *Create
folder* is off. The number of errors is 1.
+|Result files|With *Add Zip file to result*, the zip file is added, also an
existing zip left unchanged by *Do Nothing*. A zip whose creation fails is not
added, but a zip that was created stays in the result files even when the
action ends up false.
+|Result rows|Passed on unchanged. With *Get arguments from previous*, every
result row gives the source (first field), the include wildcard (second), the
exclude wildcard (third) and the zip file name (fourth). A row with an empty
source or zip file name is skipped. The first row that fails ends the action,
which is then false; the zips of the earlier rows stay, and are in the result
files. When every row is zipped, the result of the previous action is passed
on, true or false.
+|===
+
+NOTE: With an empty *Source directory/file*, or with *Get arguments from
previous* and no result rows, nothing is zipped and the result of the previous
action is passed on. A source file that can't be moved with *After zipping* set
to *Move files* is only logged: the action is still true, and the zip is in the
result files.
