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 6e0e67592a Document the result of the Delete file, Create folder,
Delete folders, Add filenames to result, Delete filenames from result and Unzip
actions. #8970 (#9047)
6e0e67592a is described below
commit 6e0e67592af75144cb946c08fefcbc764e0f040b
Author: Adalennis <[email protected]>
AuthorDate: Wed Oct 21 16:37:12 2026 +0200
Document the result of the Delete file, Create folder, Delete folders, Add
filenames to result, Delete filenames from result and Unzip actions. #8970
(#9047)
* Document the result of the Delete file, Create folder, Delete folders,
Add filenames to result, Delete filenames from result and Unzip actions. #8970
* Unzip result: a one-field row stops the action, and Nr errors less than
with result rows. #8970
---
.../pages/workflow/actions/addresultfilenames.adoc | 25 +++++++++++---
.../ROOT/pages/workflow/actions/createfolder.adoc | 17 ++++++++-
.../ROOT/pages/workflow/actions/deletefile.adoc | 17 ++++++++-
.../ROOT/pages/workflow/actions/deletefolders.adoc | 20 +++++++++--
.../workflow/actions/deleteresultfilenames.adoc | 21 ++++++++++--
.../modules/ROOT/pages/workflow/actions/unzip.adoc | 40 ++++++++++++++--------
6 files changed, 113 insertions(+), 27 deletions(-)
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/addresultfilenames.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/addresultfilenames.adoc
index b53ba5a5fb..c1647617db 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/addresultfilenames.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/addresultfilenames.adoc
@@ -32,12 +32,27 @@ This list of filenames can then be used in the various
workflow actions all arou
|===
|Option|Description
|Action name|The name of the workflow action.
-|Include subfolders|Include subfolders of the selected folders
-|Copy previous results to args?|Passes the results of the previous action to
the arguments of this action.
-|Clear result filenames?|This option clears the list of result files (from
previous workflow actions) before creating a new list.
+|Include Subfolders|Include subfolders of the selected folders
+|Copy previous results to args?|Take the files or folders and wildcards from
the result rows of the previous action instead of from the list. See <<Result>>.
+|Clear result filenames|This option clears the list of result files (from
previous workflow actions) before creating a new list.
|File/Folder|Specify the list of files or folders with wildcards (regular
expressions) in this grid. +
-You can add a different source/destination on each line.
+You can add a different file or folder and wildcard on each line.
|Wildcard (RegExp)|A regular expression wildcard to include file patterns in
the list of file names.
|===
-After specifying a folder and wildcard (regular expression), use the `Add`
button to add your file/folder selection to the table. Use the `Delete` or
`Edit` buttons to remove or edit selected lines in the table.
\ No newline at end of file
+After specifying a folder and wildcard (regular expression), use the `Add`
button to add your file/folder selection to the table. Use the `Delete` or
`Edit` buttons to remove or edit selected lines in the table.
+
+== 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 exists. A folder without matching
files adds nothing and is still true.
+|False|A file or folder in the list doesn't exist. The number of errors is the
number of entries that don't exist. The files of the other entries are still
added.
+|Result files|Each file in the list is added. For a folder, the files in it
whose whole file name, without the folder, matches *Wildcard (RegExp)* are
added, or all its files when the wildcard is empty, and with *Include
Subfolders* also the matching files in its subfolders. With *Clear result
filenames*, the result files of the previous action are removed first;
otherwise they are kept.
+|Result rows|Passed on unchanged. With *Copy previous results to args?*, the
file or folder comes from the first field and the wildcard from the second
field of each result row, and the list in the dialog is not used, also when
there are no result rows. A result row with only one field stops the workflow
with an error, and no hop is followed.
+|===
+
+NOTE: An invalid regular expression in *Wildcard (RegExp)* adds nothing, and
the action is still true.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfolder.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfolder.adoc
index adc8b5088e..dc2b51b248 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfolder.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/createfolder.adoc
@@ -32,4 +32,19 @@ The `Create a folder` action creates a folder at the
specified location.
|Action name|The name of the workflow action.
|Folder name|The name of the folder to create (can be a full path)
|Fail if folder exists|If you enable this option, this workflow action will
fail if the specified folder already exists.
-|===
\ 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 folder was created, including any missing parent folders, or it
already exists and *Fail if folder exists* is not selected.
+|False|The folder already exists and *Fail if folder exists* is selected, or
no folder name is set: the number of errors is 0. The folder could not be
created, for example because of missing permissions: the number of errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: When a file exists with the folder name, no folder is created. The
action is true, or false when *Fail if folder exists* is selected.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefile.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefile.adoc
index 228a111221..06a054c3e9 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefile.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefile.adoc
@@ -33,4 +33,19 @@ The `Delete File` action deletes a file (empty or not).
|File name|The name and path of the file to delete.
|Fail if file doesn't exist|The workflow action will follow the failure
outgoing hop when the file to be deleted does not exist anymore and this option
is switched on.
The default is off.
-|===
\ 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 deleted, or it doesn't exist and *Fail if file doesn't
exist* is not selected. An empty folder is deleted too.
+|False|The file doesn't exist and *Fail if file doesn't exist* is selected, or
no file name is set: the number of errors is 0. The file could not be deleted,
for example because of missing permissions: the number of errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: A folder that is not empty is not deleted, but the action is still true,
with 1 error.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefolders.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefolders.adoc
index 7dc8546105..50a8e2745c 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefolders.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deletefolders.adoc
@@ -30,12 +30,28 @@ The `Delete Folders` action deletes a set of folders and
their content.
|===
|Option|Description
|Action name|The name of the workflow action.
-|Settings|Copy previous results to args: Enable this option if the folders you
want to delete come from the result files of the previous action in the
workflow.
+|Copy previous results to args|Take the folders to delete from the first field
of the result rows of the previous action instead of from the list. See
<<Result>>.
|Success on a|Success condition : select one of :
* When no error reported : everything deleted just fine
* When at least x folders processed : specify x in the Limit field below
-* When the number of errors less than : specify the max nr of errors in the
limit field below
+* When number of errors less than : specify the max nr of errors in the limit
field below
|Limit|the number of folders to delete or number of errors, depending on the
option chosen in the `Success condition` above.
|Folders a|This is the list of all the 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|The *Success condition* is met: no errors with *When no error reported*,
at least *Limit* folders processed with *When at least x folders processed*, or
fewer errors than *Limit* with *When number of errors less than* (see the note
below). A folder that doesn't exist counts as processed. An empty line in the
list is skipped.
+|False|The success condition is not met, for example because a path is a file
or a folder could not be deleted. With *When no error reported* or *When number
of errors less than*, the action stops once the condition is broken: the
remaining folders are not deleted. The number of errors is the number of
folders that failed.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged. With *Copy previous results to args*, the
folder comes from the first field of each result row, and the list in the
dialog is not used, also when there are no result rows.
+|Lines deleted|The number of folders processed: deleted, or already missing.
+|===
+
+NOTE: With *When number of errors less than*, the action stops and is false as
soon as the number of errors reaches *Limit*, but when the last folder brings
it to that number, the action is still true.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deleteresultfilenames.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deleteresultfilenames.adoc
index c363331732..ef89c02abc 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deleteresultfilenames.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/deleteresultfilenames.adoc
@@ -31,6 +31,21 @@ The `Delete filenames from result` action deletes all the
filenames that are in
|Option|Description
|Action name|The name of the workflow action.
|Limit action to| Enable this feature if you want to limit the deletion to
certain filenames in the result file list.
-|Wildcard|The regular expression to limit the files to delete
-|Exclude wildcard|The regular expression to exclude certain files from being
deleted.
-|===
\ No newline at end of file
+|Wildcard (RegExp)|The regular expression to limit the files to delete
+|Exclude wildcard (RegExp)|The regular expression to exclude certain files
from being deleted.
+|===
+
+== 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 result files were removed: all of them, or with *Limit action to*,
those whose whole file name, without the folder, matches *Wildcard (RegExp)*
and not *Exclude wildcard (RegExp)*. With *Limit action to* and an empty
*Wildcard (RegExp)*, all of them are removed.
+|False|A wildcard is not a valid regular expression. No result file is
removed, and the number of errors is 0.
+|Result files|The result files of the previous action, without the removed
ones. The files themselves are not deleted.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: With *Limit action to*, a result file that no longer exists on disk is
not removed from the result files, even when its name matches.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/unzip.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/unzip.adoc
index 284c73e635..6fbafb0f63 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/unzip.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/unzip.adoc
@@ -33,31 +33,25 @@ The `Unzip file` action unzips one or more files to a
specified target location.
|Option|Description
|Action name|The name of the workflow action.
2+|Source files
-|Get args from previous|check this option if you want to use the list of
result files (from a previous workflow action) as the list of files to unzip.
-|Zip file name|the name of the zip file or a folder if you want to use a
wildcard.
-|Source wildcard a|If the previous option is a folder, you can enter a regular
expression. wildcard here.
-
-For example: to match `/folder/test.zip` a regex of `te.\.zip` will come up
empty.
-
-Use `.*te.\.zip` instead to account for the folders ahead of it.
-
-For Windows file paths, the direction of the slashes will be reversed in the
match, so use `\/` instead of `\\`.
+|Get args from previous|Take the zip files or folders, and their source
wildcards, from the result rows of the previous action instead of from *Zip
File name*. See <<Result>>.
+|Zip File name|the name of the zip file or a folder if you want to use a
wildcard.
+|Source Wildcard (RegExp)|When *Zip File name* is a folder, a regular
expression for the zip files to unzip from it, for example `+.*\.zip+`. It is
matched against the file name, and also against the full path.
2+|Unzipped files
|Use zipfile name as root directory|check this if you want to create a
separate directory for each zip filename (same name as file)
-|Target directory|The target directory to unzip in
+|Target Directory|The target directory to unzip in
|Create folder|Check this if you want to create the target folder
-|Include wildcard|Use this regular expression to select the files in the zip
archives to extract
-|Exclude wildcard|Use this regular expression to select the files in the zip
archives to extract
+|Include Wildcard (RegExp)|Use this regular expression to select the files in
the zip archives to extract
+|Exclude Wildcard (RegExp)|Use this regular expression to leave files in the
zip archives out of the extraction
|Include date in filename|Include the current date in the unzipped filenames
(format yyyyMMdd)
|Include time in filename|Include the time (format HHmmss)
-|Specify the date time format yourself|Allows you to specify the date time
format yourself (default is: yyyyMMdd'_'HHmmss)
-|If files exists|Select the action to take if the target (unzipped) file
exists: skip, overwrite, etc.
+|Specify Date time format|Allows you to specify the date time format yourself
(default is: yyyyMMdd'_'HHmmss)
+|If file exists|Select the action to take if the target (unzipped) file
exists: skip, overwrite, etc.
|After extraction a|select the action to take after zip file extraction:
* Do nothing,
* Delete files
* Move files
-|Move files to|If the previous option is "Move files", you can select the
target directory here.
+|Move Files To|If the previous option is "Move files", you can select the
target directory here.
|===
=== Advanced tab
@@ -75,3 +69,19 @@ For Windows file paths, the direction of the slashes will be
reversed in the mat
* Nr errors less than
|Limit files|The number of files unzipped or number of errors, depending on
the option chosen for `Success on` above.
|===
+
+== 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 *All works fine*, at
least *Limit files* zip files unzipped with *At least we successfully unzipped
x files*, or no more errors than *Limit files* with *Nr errors less than* (see
the note below).
+|False|The success condition is not met, or the action could not start. It
can't start when the zip file or *Target Directory* is not set or doesn't exist
(and *Create folder* is not selected), when the folder for *Move files* doesn't
exist and its *Create folder* is not selected, or when *Get args from previous*
is selected and there are no result rows: the number of errors is then 1. A zip
file that can't be read, or a file that already exists with *If file exists*
set to *Fail*, count [...]
+|Result files|With *Add extracted file to result*, every extracted file is
added, with its path in the target folder. A file skipped by *If file exists*
is not added. The result files of the previous action are kept.
+|Result rows|Passed on unchanged. With *Get args from previous*, the zip file
or folder comes from the first field and the *Source Wildcard (RegExp)* from
the second field of each result row. A row with only one field counts as one
error and stops the action: the zip files of that row and the rows after it are
not unzipped.
+|Lines written|The number of zip files unzipped. When the action can't start,
or stops on the success condition before the last result row, the value of the
previous action is passed on.
+|===
+
+NOTE: With *Nr errors less than*, the action stops and is false as soon as the
number of errors reaches *Limit files* while result rows are left to process,
but when the last row brings it to that number, the action is still true. For
the files of a single zip file or folder, it is still true when the number of
errors equals *Limit files*, and false only when it is higher. A zip file that
can't be read, or that can't be deleted after extraction with *Delete files*,
counts as two errors a [...]
