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 97e8889d8e Batch 4: Document the result of the File compare, Compare
folders, Folder is empty, Files exist, Check files locked and DOS to Unix
actions. #8970 (#9104)
97e8889d8e is described below
commit 97e8889d8e62e721b9f2e509599d4fda5b15998b
Author: Adalennis <[email protected]>
AuthorDate: Fri Oct 30 08:19:30 2026 +0100
Batch 4: Document the result of the File compare, Compare folders, Folder
is empty, Files exist, Check files locked and DOS to Unix actions. #8970 (#9104)
* Document the result of the File compare, Compare folders, Folder is
empty, Files exist, Check files locked and DOS to Unix actions. #8970
* Batch 4 review: one-field rows and invalid wildcard in Check files
locked, wildcard in Compare folders, unreadable folders, DOS to Unix error
count. #8970
---
.../pages/workflow/actions/checkfilelocked.adoc | 15 +++++++++++
.../pages/workflow/actions/comparefolders.adoc | 26 ++++++++++++++----
.../ROOT/pages/workflow/actions/dostounix.adoc | 31 +++++++++++++++++-----
.../ROOT/pages/workflow/actions/filecompare.adoc | 15 ++++++++++-
.../ROOT/pages/workflow/actions/filesexist.adoc | 13 +++++++++
.../ROOT/pages/workflow/actions/folderisempty.adoc | 23 +++++++++++++---
6 files changed, 106 insertions(+), 17 deletions(-)
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkfilelocked.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkfilelocked.adoc
index f43823b876..4d3bffd26b 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkfilelocked.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkfilelocked.adoc
@@ -40,3 +40,18 @@ On certain operating systems (MS Windows systems in
particular) this operation w
|Wildcard|The wildcards are Java Regular expressions.
For instance .*\.txt would check any file with a .txt extension.
|===
+
+== 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|No file is locked. A file or folder that does not exist is not checked
and does not make the action false. With nothing to check, the action is true
too.
+|False|A file is locked: it cannot be renamed to its own name. The action
stops at the first locked file, and the number of errors is 1.
+|Result files|Passed on unchanged.
+|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.
+|===
+
+NOTE: On Linux and macOS a file is reported as locked when its folder is
read-only, because it cannot be renamed. Checking stops at a result row with
only one field: that row and the rows after it are not checked, the error is
logged, and the action is still true. An invalid regular expression in
*Wildcard* is logged as an error for each file, no file in that folder is
checked, and the action is still true.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/comparefolders.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/comparefolders.adoc
index f1309b3e61..d4424c2469 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/comparefolders.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/comparefolders.adoc
@@ -29,15 +29,31 @@ The `Compare folders` action compares two folders to
determine if the content is
[options="header"]
|===
|Option|Description
-|Workflow action name|The name of the workflow action.
+|Action name|The name of the workflow action.
This name has to be unique in a single workflow.
-|Include Subfolders|Also compare the content of sub-folders.
-|Compare|Specify what to compare: All, Only files, Only folders, or Let me
specify...
-|Wildcard|If you chose Let me specify in the previous option, you can specify
the regular expression of files to compare.
-|Compare file size|Check this to compare file size, in opposed to just
comparing folder names.
+|Include subfolders|Also compare the content of subfolders.
+|Compare|Specify what to compare: All, Only Files, Only Folders, or Let me
specify...
+|Wildcard (RegExp)|If you chose Let me specify... in the previous option, you
can specify the regular expression of files to compare. Variables are not
resolved in it.
+|Compare file size|Check this to also compare the size of files with the same
name, not only their names.
|Compare file content|Checks if files have the same content.
Note: this may cause slower processing speeds.
|File/Folder name 1|This is the first file or folder to compare
|File/Folder name 2|This is the second file or folder to compare
|===
+== 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|For two files: their contents are identical. For two folders: both hold
the same number of entries of the kind set in *Compare*, every name found in
the first folder is also in the second, with the same type, and with *Compare
file size* or *Compare file content* the files have the same size or content.
Without these two options, files with the same name count as equal.
+|False|The folders differ, or one path is a file and the other a folder: the
number of errors is 0. A file or folder does not exist: the number of errors is
1.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: Entries are matched by their name only, not by their subfolder. With
*Include subfolders*, a folder with `s1/x.txt` and `s2/x.txt` and a folder with
`s1/x.txt` and `s2/y.txt` are reported as identical.
+
+NOTE: *Wildcard (RegExp)* is used as typed: variables in it are not resolved.
An invalid regular expression, which includes one with `+${...}+` in it, leaves
out every entry, and the folders are reported as identical. This also happens
with *Compare* set to *All* when an invalid wildcard is still stored from an
earlier choice.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dostounix.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dostounix.adoc
index aba0967fcf..23ec2e4fad 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dostounix.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dostounix.adoc
@@ -35,11 +35,11 @@ When the format is unknown, this action also has a guess
function and converts t
|Option|Description
|Action name|The name of the workflow action.
|Settings a|
-* Include Subfolders: also process sub-folders
-* Copy previous results to args : use the list of result files from the
previous workflow action (actions) in stead of the static file list below.
+* Include subfolders: also process subfolders
+* Copy previous results to args: take the file or folder, the wildcard and the
conversion from the result rows of the previous action instead of from the list
below. See <<Result>>.
|Files / Folders a|
You can specify the list of files or folders with wildcards in this grid.
-You can add a different source/destination on each line.
+Each line has its own conversion: Windows to Unix, Unix to Windows, or Guess,
which converts a file to the other format. For a folder, the wildcard is a
regular expression matched against the whole path of each file (see <<Result>>).
|===
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.
@@ -57,18 +57,35 @@ After specifying a folder and wildcard (regular
expression), use the `Add` butto
[options="header"]
|===
|Option|Description
-|Success Condition a|This action will follow the success path if the selected
condition is true.
+|Success condition a|This action will follow the success path if the selected
condition is true.
Current options are:
* Success if all files are processed
* Success if at least x files are processed
* Success when number of error files lesser than
-|Nr Files|specifies the number of files that have to meet the selected
condition from above
-|Add Filenames a|Adds the filenames that meet the selected condition to the
workflow output stream.
+|Nr files|specifies the number of files that have to meet the selected
condition from above
+|Add filenames a|Adds the files to the result files of the action.
Conditions are:
* Do not add filenames
* Add all filenames
* Add only processed filenames
* Add only error filenames
-|===
\ 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 *Success condition* is met: every file converted with *Success if
all files are processed*, at least *Nr files* files converted with *Success if
at least x files are processed*, or fewer files that could not be converted
than *Nr files* with *Success when number of error files lesser than*. The
number of errors is then 0, also when some files failed.
+|False|The success condition is not met. A file that cannot be rewritten, for
example in a read-only folder, counts as an error file. A path that does not
exist, or that is not set, counts as an error, which only makes the action
false with *Success if all files are processed*. With *Success if all files are
processed*, a path error stops the action, and the remaining entries are not
processed; an error file does not stop it. The number of errors is the number
of path errors plus error f [...]
+|Result files|*Add all filenames* (the default) adds the converted files and
the ones that could not be converted, *Add only processed filenames* only the
converted ones, *Add only error filenames* only the failed ones, and *Do not
add filenames* none. The result files of the previous action are kept.
+|Result rows|Passed on unchanged. With *Copy previous results to args*, the
file or folder, the wildcard and the conversion (`guess`, `dostounix` or
`unixtodos`) come from the first three fields of each result row, and the list
in the dialog is not used, also when there are no result rows.
+|Lines written|The number of files converted.
+|Lines rejected|The number of files that could not be converted.
+|===
+
+NOTE: A result row with fewer than three fields stops the workflow with an
error, and no hop is followed. The wildcard is matched against the whole path
of each file (for example `file:///data/in/sales.txt`), not its name:
`+.*\.txt+` or `+.*/sales\.txt+` match, `+sales\.txt+` matches nothing, and the
action is still true.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filecompare.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filecompare.adoc
index 160a029777..3f38160c6b 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filecompare.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filecompare.adoc
@@ -35,4 +35,17 @@ When the contents of the files are the same the success
outgoing hop will be fol
|File name 1|The name and path of the file of the first file to compare.
|File name 2|The name and path of the file of the second file to compare.
|Add filename to result|Add the filenames for both files to the result.
-|===
\ 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|Both files exist and their contents are identical.
+|False|The contents differ, or a file name is not set: the number of errors is
0. A file does not exist, or a path is a folder: the number of errors is 1.
+|Result files|With *Add filename to result*, both files are added when both
exist and are files, also when their contents differ. The result files of the
previous action are kept.
+|Result rows|Passed on unchanged.
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filesexist.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filesexist.adoc
index eee8a5d31f..4926dfa1db 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filesexist.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/filesexist.adoc
@@ -39,3 +39,16 @@ You can point to individual files, or to folders and use
regular-expression wild
* *Exclude wildcard (RegExp)*: optional regular expression. Files matching
this pattern are ignored when evaluating a folder.
* *Include subfolders*: when set to `Y`, also look for matching files in
subfolders of the specified folder.
|===
+
+== 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 entry in the list exists: a file or folder that can be read, or a
folder with at least one file whose whole name matches its wildcards (in its
subfolders only with *Include subfolders*). An empty list is true too.
+|False|An entry does not exist, a file or folder cannot be read, or a folder
has no matching file: the number of errors is 0. A wildcard that is not a valid
regular expression counts as one error.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/folderisempty.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/folderisempty.adoc
index 600e20e5ee..6028d188c5 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/folderisempty.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/folderisempty.adoc
@@ -22,7 +22,7 @@ under the License.
== Description
-The `Check if a folder is empty` action verifies if a folder is empty and that
there are no regular files or sub-folders in the folder.
+The `Check if a folder is empty` action verifies that a folder holds no files.
Subfolders do not count, only the files in them with *Include subfolders*.
== Options
@@ -31,8 +31,23 @@ The `Check if a folder is empty` action verifies if a folder
is empty and that t
|Option|Description
|Action name|The name of the workflow action.
|Folder name|The name of the folder to verify for emptiness.
-|Include subfolders|Check if there are subfolders in the folder to check.
-|Limit search to|Limits the search for files to those with a certain wildcard
(regular expression)
-|Wildcard|The wildcard (regular expression) to limit the files to look for
with, for example: .*\.txt$
+|Include subfolders|Also look for files in the subfolders of the folder.
+|Limit search to (RegExp)|Only count the files whose name matches *Wildcard
(RegExp)*.
+|Wildcard (RegExp)|The regular expression for the file names, for example
`+.*\.txt+`. Only used with *Limit search to (RegExp)*.
|===
+== 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 holds no files. Subfolders do not count; with *Include
subfolders*, the files in them do. With *Limit search to (RegExp)*, only files
whose whole name matches *Wildcard (RegExp)* count.
+|False|The folder holds a file: the number of errors is 0. The folder does not
exist, the path is a file, or no folder name is set: the number of errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|Lines input|When the action is true, the number of subfolders found.
Otherwise the value of the previous action is passed on.
+|===
+
+NOTE: An invalid regular expression in *Wildcard (RegExp)* stops the workflow
with an error, and no hop is followed, also when *Limit search to (RegExp)* is
not selected.
