This is an automated email from the ASF dual-hosted git repository.
hansva 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 b9dfafd76d Document the result of the Wait for file, Process result
filenames, Write to file, Evaluate files metrics, XML well formed and DTD
validator actions. #8970 (#9111)
b9dfafd76d is described below
commit b9dfafd76dfc39a7a92c8e9c110d83813eb1cec6
Author: Adalennis <[email protected]>
AuthorDate: Wed Oct 28 14:13:14 2026 +0100
Document the result of the Wait for file, Process result filenames, Write
to file, Evaluate files metrics, XML well formed and DTD validator actions.
#8970 (#9111)
---
.../ROOT/pages/workflow/actions/dtdvalidator.adoc | 17 +++++++++++-
.../pages/workflow/actions/evalfilesmetrics.adoc | 31 ++++++++++++++++------
.../workflow/actions/processresultfilenames.adoc | 28 ++++++++++++++-----
.../ROOT/pages/workflow/actions/waitforfile.adoc | 20 ++++++++++----
.../ROOT/pages/workflow/actions/writetofile.adoc | 15 ++++++++++-
.../ROOT/pages/workflow/actions/xmlwellformed.adoc | 28 ++++++++++++++-----
6 files changed, 112 insertions(+), 27 deletions(-)
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dtdvalidator.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dtdvalidator.adoc
index c79f882ad2..6a48115a3a 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dtdvalidator.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/dtdvalidator.adoc
@@ -33,4 +33,19 @@ The `DTD validator` action verifies if an XML file
corresponds to a certain stru
|XML File name|The name of the XML file to validate
|DTD Intern|Check this if the DTD is contained in the XML file
|DTD File name|If the DTD is not internal, specify the DTD file to validate
with.
-|===
\ 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 XML file is valid against the DTD.
+|False|The XML file does not follow the DTD: the number of errors is the
number of validation errors. The file or the DTD does not exist, *DTD Intern*
is selected and the file has no DOCTYPE, or the file is not well formed: the
number of errors is 0.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: The action reads the DOCTYPE of the file, which Hop refuses by default:
the variable `XML_ALLOW_DOCTYPE_DECL` is `N`. Set it to `Y` (see
xref:variables.adoc[Variables]), otherwise every file fails with "DOCTYPE is
disallowed", whether the DTD is internal or external.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evalfilesmetrics.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evalfilesmetrics.adoc
index 98968f42a5..9d1ac6bf54 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evalfilesmetrics.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evalfilesmetrics.adoc
@@ -41,13 +41,13 @@ The `Evaluate files metrics` action can be used to evaluate
the size or count of
Based on the selected option, the fields below will be enabled/disabled.
|Wildcard|A regex wildcard.
-|File Result field|
-|Wildcard result field|
-|Include subfolders result field|
+|File Result field|With *Previous result row*: the name of the result row
field that holds the file or folder.
+|Wildcard result field|With *Previous result row*: the name of the field that
holds the wildcard. Optional.
+|Include subfolders result field|With *Previous result row*: the name of the
field that says whether to include subfolders (`Y` or `N`). Optional.
|Evaluate a|Type of evaluation
* Total files size
-* Total file count
+* Total files count
|File/Folder source|The file or folder path.
|Wildcard|A regex wildcard.
@@ -74,14 +74,29 @@ After specifying a folder and wildcard (regular
expression), use the `Add` butto
|Success when a|
* If value is equal to
-* If value is equal to
+* If value is different from
* If value is small than
* If value is smaller or equal
* If value is greater than
* If value is greater or equal
* If value is between
-* If value in list
-* If value not in list
+* if value in list
+* if value not in list
|Value|The value to compare.
-|===
\ 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 total size (in the selected *Scale*) or the number of files meets
the *Success when* condition. Errors don't change this: a path that does not
exist counts as an error, but with a total of 0 the condition can still be met,
and the action is then true with errors.
+|False|The condition is not met. The action also stops and is false, with 1
error, when the Files/Folders list is empty, or with *Previous result row* when
the field set in *File Result field* is not in the result rows.
+|Result files|Passed on unchanged. With *Filenames result*, the files
evaluated are the result files of the previous action whose whole name matches
*Wildcard*.
+|Result rows|Passed on unchanged. With *Previous result row*, the file or
folder, the wildcard and the include subfolders flag come from the result row
fields named in *File Result field*, *Wildcard result field* and *Include
subfolders result field*.
+|===
+
+NOTE: With *Filenames result*, an invalid regular expression in *Wildcard*
stops the workflow with an error, and no hop is followed.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/processresultfilenames.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/processresultfilenames.adoc
index e99ef62531..f0a5bb3829 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/processresultfilenames.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/processresultfilenames.adoc
@@ -22,14 +22,14 @@ under the License.
== Description
-The `Process result filenames` action allows you to copy, move or delete a
number of files and/or folders to alternate locations on your file system.
+The `Process result filenames` action copies, moves or deletes the result
files of the previous actions in the workflow, for example the files a pipeline
wrote or a transfer action downloaded.
== Options
[options="header", width="90%", cols="1,3"]
|===
|Option|Description
-|Workflow action name|The name of the workflow action.
+|Action name|The name of the workflow action.
|Action a|Choose one of
* Copy (default)
@@ -39,7 +39,7 @@ The `Process result filenames` action allows you to copy,
move or delete a numbe
|Create destination folder|use this option to create the destination folder
when it does not exist
|Replace existing file|use this option to overwrite existing files
|Remove source filenames from result|use this option to remove the processed
filenames from the list of result filenames
-|Add destination filenames to result|use this option to add the processed
target filenames to the list of result filenames
+|Add destination filename to result|use this option to add the processed
target filenames to the list of result filenames
|Add date to filename|add the date to the target filename, e.g. yyyyMMdd
|Add time to filename|add the time to the target filename, e.g. HHmmss
|Specify date time format|allows you to specify your own date-time format,
e.g. yyyyMMdd_HHmmss
@@ -47,12 +47,28 @@ The `Process result filenames` action allows you to copy,
move or delete a numbe
2+|Limit to
|Limit action to|Define include and exclude wildcards
|Wildcard (RegExp)|The regular expression wildcard to use to include files
-|Exclude Wildcard (RegExp|The regular expression wildcard to use to exclude
files
+|Exclude wildcard (RegExp)|The regular expression wildcard to use to exclude
files
2+|Success On
|Success on a|Success condition : select one of these option:
* Success when all works fine
-* Success when at least x files moved (specify x in the limit field below)
+* Success when at least x files processed (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 errors or number of files specified in
the `Success on` option above.
-|===
\ 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: no errors with *Success when all works
fine*, at least *Nr errors lesser than* files processed with *Success when at
least x files processed*, or no more 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: a result file no longer exists on
disk, or could not be copied, moved or deleted. When the destination folder
does not exist and *Create destination folder* is not selected, the action
stops before processing any file, with 1 error. With *Success when all works
fine*, the action stops at the first error.
+|Result files|The action works on the result files of the previous actions,
limited by *Limit action to* and its wildcards. For each file copied or moved,
*Remove source filenames from result* removes the source and *Add destination
filename to result* adds the destination; both are selected by default.
*Delete* removes the deleted files from the result files. A file whose
destination already exists is skipped when *Replace existing file* is not
selected: it stays in the result files and [...]
+|Result rows|Passed on unchanged.
+|Lines written|The number of files copied, moved or deleted. When the action
stops because the destination folder does not exist, the value of the previous
action is passed on.
+|===
+
+NOTE: With *Success when number of errors lesser than*, the action is still
true when the number of errors equals *Nr errors lesser than*. An invalid
regular expression in *Wildcard (RegExp)* or *Exclude wildcard (RegExp)* stops
the workflow with an error, and no hop is followed, also when *Limit action to*
is not selected.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforfile.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforfile.adoc
index f17f911aeb..a72cd0ca4a 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforfile.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforfile.adoc
@@ -42,12 +42,22 @@ WARNING: This action requires the definition of a single
file. Variables can be
The file will be checked for in the start of the execution and then every
"check cycle time" seconds until the maximum timeout is reached.
A workflow can only be stopped every "check cycle time" as else the workflow
action will be sleeping.
A check cycle time of 30 or 60 seconds seems to be a good trade-off between
the period until the file is detected and the required CPU usage.
-|Success on timeout|This option determines what to do when the "Maximum
timeout" has been reached and the file has not been found.
+|Success on timeout|This option determines what to do when the "Maximum
timeout" has been reached and the file has not been found: when it is selected,
the action is true and the success hop is followed; otherwise the action is
false.
|File size check|When this is switched on, once the workflow action detects
the specified file, and will only continue if the file size hasn't changed the
last check "cycle time seconds".
This is useful in cases where a file is created in the final place, and
another process is still writing to the file.
(As a best practice, files should be written to a temporary location, and then
moved when completed)
-This is the number seconds after which the flow will continue even if the file
was not created.
-When the timeout is reached the "Success on timeout" option will determine
whether the outgoing success or failure hop will be followed.
-If enabled, the workflow action will evaluate successfully, and the outgoing
success hop will be followed.
-|Add filename to result|Add the filename to the result fields for this
workflow action.
+|Add filename to result|Add the file to the result files of this action. See
<<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 file or folder exists, or appears before *Maximum timeout*. With
*Success on timeout*, the action is also true when the timeout is reached
without it. With *File size check*, the action first waits until the size stays
the same between two checks. A *Maximum timeout* of 0 waits until the file
appears or the workflow is stopped.
+|False|The timeout is reached without the file and *Success on timeout* is not
selected, no file name is set, the path cannot be read (for example a `zip:`
path into a file that is not a zip), or the workflow is stopped while waiting.
The number of errors is always 0.
+|Result files|With *Add filename to result*, the file is added when it is
found. A folder is not added, and nothing is added when the action ends on the
timeout. 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/writetofile.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/writetofile.adoc
index ebd540979e..70f37dca9e 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/writetofile.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/writetofile.adoc
@@ -22,7 +22,7 @@ under the License.
== Description
-The `Write to file` action writes custom text from a field to a file.
+The `Write to file` action writes the text you enter in the action to a file.
Variables in the text are resolved.
== Options
@@ -39,3 +39,16 @@ The `Write to file` action writes custom text from a field
to a file.
|Encoding|The encoding to use while writing the file.
|Text|The text to write to the 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 text was written to the file.
+|False|No file name is set, the parent folder does not exist and *Create
parent folder* is not selected, the file cannot be written (for example in a
read-only folder), or the encoding is not known. The number of errors is 1.
+|Result files|Passed on unchanged. The written file is not added.
+|Result rows|Passed on unchanged.
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/xmlwellformed.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/xmlwellformed.adoc
index 85af08a7f9..b1ad226a67 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/xmlwellformed.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/xmlwellformed.adoc
@@ -32,19 +32,18 @@ The `Check if XML file is well-formed action` verifies if
one or more files cont
|===
|Option|Description
|Action name|The name of the workflow action.
-|Include Subfolders|Option to move the content of sub-folders.
-|Copy previous results to args|Check this to pass the results of the previous
action into the arguments of this action.
+|Include subfolders|Also check the matching files in the subfolders of a
folder.
+|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>>.
|File/Folder source|Enter or select (Browse button) a file or folder
-|Wildcard (RegExp)|A regular expression wildcard for the filename pattern
+|Wildcard (RegExp)|A regular expression matched against the whole path of each
file in the folder, for example `+.*\.xml+` (see <<Result>>).
|Files/Folders a|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.
NOTE: You can use the Add button to add a line to the Files/Folders list.
|===
=== Advanced tab
-In this tab you can specify the files and/or folders to move.
[options="header", width="90%", cols="1,3"]
|===
@@ -58,4 +57,21 @@ In this tab you can specify the files and/or folders to move.
* Add all filenames
* Add only well-formed filenames
* Add only bad-formed 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 well formed with *Success if
all files are well formed*, at least *Nr files* well formed files with *Success
if at least x files are well formed*, or fewer bad formed files than *Nr files*
with *Success when number of bad formed files lesser than*. The number of
errors is then 0.
+|False|The success condition is not met. A bad formed file counts as an error
and does not stop the action. A path that does not exist counts as an error;
with *Success if all files are well formed*, it stops the action, and the
remaining entries are not checked.
+|Result files|*Add all filenames* (the default) adds every file checked, *Add
only well formed filenames* only the well formed ones, and *Add only bad formed
filenames* only the bad formed ones. The result files of the previous action
are kept.
+|Result rows|Passed on unchanged. With *Copy previous results to args*, the
file or folder and the wildcard come from the first two fields of each result
row.
+|Lines written|The number of well formed files.
+|Lines rejected|The number of bad formed files.
+|===
+
+NOTE: A result row with fewer than two 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/orders.xml`), not its name:
`+.*\.xml+` matches, `+orders\.xml+` matches nothing, and the action is still
true.
