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 c32b621bfb Batch 11: Result sections for the PGP actions, Mail
validator and Get mails (POP3/IMAP). #8970 (#9195)
c32b621bfb is described below
commit c32b621bfb7dc641f495e2c9f58c1f64ab170d36
Author: Adalennis <[email protected]>
AuthorDate: Sun Nov 1 08:36:00 2026 +0100
Batch 11: Result sections for the PGP actions, Mail validator and Get mails
(POP3/IMAP). #8970 (#9195)
---
.../ROOT/pages/workflow/actions/getpop.adoc | 33 +++++++++---
.../ROOT/pages/workflow/actions/mailvalidator.adoc | 27 ++++++++--
.../pages/workflow/actions/pgpdecryptfiles.adoc | 61 +++++++++++++++-------
.../pages/workflow/actions/pgpencryptfiles.adoc | 55 +++++++++++++------
.../ROOT/pages/workflow/actions/pgpverify.adoc | 15 +++++-
5 files changed, 146 insertions(+), 45 deletions(-)
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/getpop.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/getpop.adoc
index e837ea58fb..49d7e7c4f8 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/getpop.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/getpop.adoc
@@ -32,13 +32,13 @@ The `Get mails (POP3/IMAP)` action retrieves mails from a
POP3 or IMAP server an
|===
|Option|Description
2+|**Mail Server Connection**
-|Mail Connection|If a mail server connection is selected here, the rest of
this tab is ignored. The server configuration will be taken from the
xref:metadata-types/mail-server-connection.adoc[Mail Server Connection]
metadata item.
+|Mail Server Connection|If a mail server connection is selected here, the rest
of this tab is ignored. The server configuration will be taken from the
xref:metadata-types/mail-server-connection.adoc[Mail Server Connection]
metadata item.
2+|Server Settings
-|Workflow action name|The name of the workflow action.
+|Action name|The name of the workflow action.
|Source Host|The host name or IP-address of the pop server.
|Use SSL |If checked A secure connection will be used to communicate with the
server.
|Use XOAUTH2 |If checked XOAuth2 will be used to authenticate with the server.
-|Port|The port to run the SSL POP3 or IMAP connection over.
+|Port|The port of the POP3 or IMAP server, with or without SSL.
|Username|The username to log in with.
|Password|The password to log in with.
|Use proxy|check to enable proxy authentication
@@ -80,7 +80,6 @@ a|Select the e-mails to retrieve:
|Retrieve the .. first emails|Allows you to specify the number of emails to
retrieve if "first ... emails" is selected.
|Delete emails after retrieval|check to delete the mails on the pop server
after retrieval.
2+|IMAP settings
-|Option|Description
|IMAP folder|the folder on the IMAP server to retrieve messages from
|Include subfolders|check to select messages for subfolders from the selected
IMAP folder
|Retrieve a|choose one of
@@ -118,10 +117,8 @@ The selected value is stored with the workflow (XML tag
`valueimaplist`, for exa
|Recipient (TO)|messages will be filtered on recipient
|Subject|messages will be filtered on subject
2+|Content
-|Option|Description
|Body|messages will be filtered on the specified text in the email body
2+|Received date
-|Option|Description
|Condition a|Choose a date or date range. The available options are
* None (default, don't filter on received date)
@@ -129,6 +126,7 @@ The selected value is stored with the workflow (XML tag
`valueimaplist`, for exa
* Smaller than `Date 1`
* Greater than `Date 1`
* Between `Date 1` and `Date 2`
+|Date 1, Date 2|The dates for the condition, in the format `yyyy-MM-dd
HH:mm:ss`.
|===
== Notes
@@ -136,3 +134,26 @@ The selected value is stored with the workflow (XML tag
`valueimaplist`, for exa
* IMAP **Retrieve** (unread, new, flagged, and the other list options) is
stored with the workflow. Saving and reopening keeps the selected option.
* Workflows saved in Hop 2.13 still load: date conditions such as `ignore` and
IMAP list codes such as `imaplistunread` are accepted, not only integer indexes.
+
+== 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 action connected and processed the selected messages, with 0 errors.
No message to process, for example an empty mailbox, is also true.
+|False|The number of errors is 1. *Target directory* is empty, or doesn't
exist and *Create folder* is unchecked, *Different folder for attachment* is
checked and *Attachment files folder* is empty, or doesn't exist and *Create
folder* is unchecked, the server can't be reached or refuses the login, the
*Mail Server Connection* doesn't exist, the *IMAP folder* doesn't exist, *Move
to folder* is empty or doesn't exist and *Create folder* is unchecked, or a
*Received date* condition is sele [...]
+|Result files|Passed on unchanged: the saved messages and attachments are not
added.
+|Result rows|Passed on unchanged.
+|Lines written|The number of messages saved with *Save message content*.
+|Files retrieved|The number of attachments saved.
+|Lines deleted|The number of messages deleted, by the *Delete messages*
action, *Delete emails after retrieval* or *Delete message* after retrieval. A
message moved on its own also counts here: with *Move message to folder* after
retrieval, or with the *Move messages to folder* action and *Retrieve the
first...emails*.
+|Lines updated|The number of messages moved to another IMAP folder.
+|===
+
+When the action is false, these metrics keep the values of the previous action.
+
+NOTE: The `#IdFile#` number in *Target filename pattern* starts again in each
folder: with *Include subfolders*, a message of a subfolder can overwrite the
file of a message of the first folder.
+
+NOTE: *Retrieve the first...emails* also applies to the *Delete messages* and
*Move messages to folder* actions: only that number of messages is deleted or
moved.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/mailvalidator.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/mailvalidator.adoc
index 462dc48e95..d718fbc57d 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/mailvalidator.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/mailvalidator.adoc
@@ -35,14 +35,31 @@ When the check passes the success hop will be followed,
otherwise it will go to
|Action name|The name of the workflow action.
|Email address|The email address, or list (separated by spaces) that have to
be checked.
2+|Settings
-|SMTP check? a|By default, Apache Hop will only check email address structure
(using regular expression).
+|SMTP check a|By default, Apache Hop will only check email address structure
(using regular expression).
If you want to perform a SMTP check, please select this option and fill Email
sender (see after).
-Hop will extract domain name from the supplied email address (to check) and
will try to get all exchangers from the domain name. Each exchanger will be
queried.
+Hop will extract domain name from the supplied email address (to check) and
will try to get all exchangers from the domain name. Each exchanger will be
queried on port 25.
|Time out|In order to perform a SMTP check, Hop will open a socket on the
target SMTP host.
-Specify here the socket time out (by default 0).
-|Email sender|If you select "SMTP check?" option, this field is mandatory.
+Specify here the socket time out in milliseconds (0, the default: no time out).
+|Email sender|If you select the "SMTP check" option, this field is mandatory.
Hop will need sender email address to query SMTP host.
|Default SMTP server|If you know which SMTP server to query, please specify it
here, Hop will then query only this one.
-|===
\ 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|Every address in *Email address* is valid, with 0 errors. With *SMTP
check*, a mail server also accepted *Email sender* and each address.
+|False|The number of errors is 1. *Email address* is empty, an address is not
a valid email address, *SMTP check* is selected while *Email sender* is empty,
or with *SMTP check* the mail server refuses *Email sender* or an address, the
domain doesn't exist or has no MX record, or the server can't be reached. The
addresses are checked one after the other, and the first one that is not valid
ends the check.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: The addresses must be separated by exactly one space: two spaces, or a
comma, make the check fail.
+
+NOTE: *SMTP check* connects to port 25 of the mail servers of the domain (its
MX records), or of *Default SMTP server* when it is set, and asks whether it
accepts *Email sender* and the address. Without *Default SMTP server*, an
address of a domain that has no MX record always fails, even when the domain
has an A record: the check fails with "Error getting machines : Index 1 out of
bounds for length 1".
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpdecryptfiles.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpdecryptfiles.adoc
index 153302f0d6..1f15fc1573 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpdecryptfiles.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpdecryptfiles.adoc
@@ -35,16 +35,16 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
|Option|Description
|Action name|The name of the workflow action.
|GPG location|The file path of the GnuPG executable (e.g. `/usr/bin/gpg`).
-|Include subfolders|Whether or not to include subfolders.
-|Copy previous results to args|
+|Include Subfolders|Also processes the files in the subfolders of a source
folder.
+|Copy previous results to args|Take the files from the result rows of the
previous action instead of from the list. The fields are read by position:
file/folder source, wildcard, passphrase, file/folder destination.
|File/Folder source|The file to decrypt, can be added to the Files/Folders
list using Add.
|File/Folder destination|The destination of the decrypted files.
|Wildcard|A regex wildcard.
-// |User ID|
+|Passphrase|The passphrase of the private key the files are encrypted for.
|Files/Folders|The files to decrypt.
|===
-=== Destination File Tab
+=== Destination file tab
[options="header", width="90%", cols="1,3"]
|===
@@ -52,16 +52,16 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
2+|Destination file
|Create destination folder|Whether or not to create the destination folder.
|Destination is a file|Whether or not the destination is a file.
-|Do not keep folder structure|Whether or not to keep the folder structure. If
unchecked, the folder structure is flattened.
+|Do not keep folder structure|Writes the files of subfolders directly in the
destination folder. When unchecked, the subfolders of the source are kept in
the destination.
|Add date to filename|Adds the date to the file name.
|Add time to filename|Adds the time to the file name.
|Specify Date time format|Whether or not to specify the date time format.
|Date time format|The format of the date time.
|Add date before extension|Before or after extension.
-|If destination file exists a|
+|If destination file exists a|What to do when the destination file already
exists. See the WARNING under <<Result>>.
-* Do nothing
-* Overwrite the destination file
+* Do nothing (default)
+* Overwrite destination file
* Create file with unique name
* Delete source file
* Move source file to folder
@@ -74,17 +74,15 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
|Add time|Adds the time.
|Specify format|Whether or not to specify the date time format.
|Add date before extension|The format of the date time.
-|If file exists in destination folder a|
+|If file exists in destination folder a|Used with *Move source file to
folder*, when the file already exists in *Destination folder*:
-* Do nothing
-* Overwrite the destination file
-* Create file with unique name
-* Delete source file
-* Move source file to folder
+* Do nothing (default)
+* Overwrite file
+* Unique name
* Fail
|===
-=== Destination File Tab
+=== Advanced tab
[options="header", width="90%", cols="1,3"]
|===
@@ -92,10 +90,37 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
2+|Success On
|Success condition a|Which condition to validate for a successful run
-* Success when all works (default)
+* Success when all works fine (default)
* Success when at least x files decrypted
* Success when number of errors lesser than
-|Nr error lesser than|Success if errors lesser than.
+|Nr errors lesser than|The limit used by the success condition: the number of
errors, or the number of files for *Success when at least x files decrypted*
(default 10).
2+|Result files name
-|Add files to result files name|
+|Add files to result files name|Adds the decrypted files to the result files.
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 a|Depends on *Success condition* (Advanced tab):
+
+* Success when all works fine (default): no file failed. An empty
Files/Folders list, no file matching the wildcard, or *Copy previous results to
args* without previous result rows is also true.
+* Success when at least x files decrypted: at least *Nr errors lesser than*
files were decrypted, whatever the number of errors.
+* Success when number of errors lesser than: the number of errors is at most
*Nr errors lesser than*. When an entry of the list brings the errors to that
number and entries are left, the action stops and is false; when the last entry
does, the action is still true.
+|False|The success condition is not met. A file or an entry of the list fails,
and counts as an error, when its source doesn't exist, the passphrase is wrong,
the file is not encrypted, or the destination file exists and *If destination
file exists* is *Fail*. It is also false, before any file and whatever the
success condition, when *If destination file exists* is *Move source file to
folder* while *Destination folder* is empty, or doesn't exist and *Create
folder* is unchecked. With *S [...]
+|Errors|The number of files and entries that failed. Inside a folder, when
files are left after the one that breaks the success condition, that failure
counts as two errors.
+|Result files|With *Add files to result files name*, a decrypted file that
didn't exist yet in the destination is added unless *If destination file
exists* is *Do nothing* (the default) or *Fail*: with the default, no file is
added. When the destination file already exists, a file is added only with
*Overwrite destination file* or *Create file with unique name*, and with *Move
source file to folder* the moved source file is added. The result files of the
previous action are kept.
+|Result rows|Passed on unchanged.
+|Lines written|The number of files decrypted. A file left in place by *Do
nothing*, deleted or moved is not counted. When the check of *Destination
folder* (Move to folder) fails, or the action stops on the success condition
between two entries of the list, the value of the previous action is passed on.
|===
+
+NOTE: The decrypted file keeps the name of the source file: `a.txt.gpg`
becomes `a.txt.gpg` in the destination folder.
+
+NOTE: A *GPG location* that is empty or not found doesn't make the action
false: the workflow stops with an error, and no hop from the action is followed.
+
+WARNING: *If destination file exists* doesn't always do what its name says.
*Delete source file* deletes the existing destination file, not the source, and
decrypts nothing. *Move source file to folder* moves the source file to
*Destination folder* without decrypting it.
+
+NOTE: When the destination file exists, *Create file with unique name* writes
the decrypted file under a new name, with the date and time added after the
file name (for example `a.txt.gpg30102026_140548429`), and *Do nothing* keeps
the existing file and doesn't decrypt the source.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpencryptfiles.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpencryptfiles.adoc
index 876e710fa6..b100e4463d 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpencryptfiles.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpencryptfiles.adoc
@@ -36,7 +36,7 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
|Action name|The name of the workflow action.
|GPG location|The file path of the GnuPG executable (e.g. `/usr/bin/gpg`).
|Use ASCII mode|Whether or not to use ASCII mode when encrypting.
-|Include subfolders|Whether or not to include subfolders.
+|Include Subfolders|Also processes the files in the subfolders of a source
folder.
|Copy previous results to args|Take the rows below from the result of the
previous action instead of from the grid. The fields are read by position:
action, file/folder source, wildcard, user ID, file/folder destination, and
optionally signing key as a sixth field.
|Action|Encrypt, Sign, Sign and Encrypt
|File/Folder source|The file to encrypt, can be added to the Files/Folders
list using Add.
@@ -55,16 +55,16 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
2+|Destination file
|Create destination folder|Whether or not to create the destination folder.
|Destination is a file|Whether or not the destination is a file.
-|Do not keep folder structure|Whether or not to keep the folder structure. If
unchecked, the folder structure is flattened.
+|Do not keep folder structure|Writes the files of subfolders directly in the
destination folder. When unchecked, the subfolders of the source are kept in
the destination.
|Add date to filename|Adds the date to the file name.
|Add time to filename|Adds the time to the file name.
|Specify Date time format|Whether or not to specify the date time format.
|Date time format|The format of the date time.
|Add date before extension|Before or after extension.
-|If destination file exists a|
+|If destination file exists a|What to do when the destination file already
exists. See the WARNING under <<Result>>.
-* Do nothing
-* Overwrite the destination file
+* Do nothing (default)
+* Overwrite destination file
* Create file with unique name
* Delete source file
* Move source file to folder
@@ -77,17 +77,15 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
|Add time|Adds the time.
|Specify format|Whether or not to specify the date time format.
|Add date before extension|The format of the date time.
-|If file exists in destination folder a|
+|If file exists in destination folder a|Used with *Move source file to
folder*, when the file already exists in *Destination folder*:
-* Do nothing
-* Overwrite the destination file
-* Create file with unique name
-* Delete source file
-* Move source file to folder
+* Do nothing (default)
+* Overwrite file
+* Unique name
* Fail
|===
-=== Advanced Tab
+=== Advanced tab
[options="header", width="90%", cols="1,3"]
|===
@@ -95,10 +93,37 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
2+|Success On
|Success condition a|Which condition to validate for a successful run
-* Success when all works
+* Success when all works fine (default)
* Success when at least x files decrypted
* Success when number of errors lesser than
-|Nr error lesser than|Success if errors lesser than.
+|Nr errors lesser than|The limit used by the success condition: the number of
errors, or the number of files for *Success when at least x files decrypted*
(default 10).
2+|Result files name
-|Add files to result files name|
+|Add files to result files name|Adds the encrypted or signed files to the
result files. 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 a|Depends on *Success condition* (Advanced tab):
+
+* Success when all works fine (default): no file failed. An empty
Files/Folders list, no file matching the wildcard, or *Copy previous results to
args* without previous result rows is also true.
+* Success when at least x files decrypted: at least *Nr errors lesser than*
files were encrypted or signed, whatever the number of errors.
+* Success when number of errors lesser than: the number of errors is at most
*Nr errors lesser than*. When an entry of the list brings the errors to that
number and entries are left, the action stops and is false; when the last entry
does, the action is still true.
+|False|The success condition is not met. A file or an entry of the list fails,
and counts as an error, when its source doesn't exist, the destination folder
doesn't exist and *Create destination folder* is unchecked, GnuPG fails (an
unknown or empty *User ID*, a signing key that needs a passphrase), the
destination file exists and *If destination file exists* is *Fail*, or a folder
is the source while *Destination is a file* is checked. It is also false,
before any file and whatever the [...]
+|Errors|The number of files and entries that failed. Inside a folder, when
files are left after the one that breaks the success condition, that failure
counts as two errors. A *GPG location* that is empty or not found counts as 1
error, before any file: the action is false with *Success when all works fine*
and *Success when at least x files decrypted*, and true with *Success when
number of errors lesser than*.
+|Result files|With *Add files to result files name*, an encrypted file that
didn't exist yet in the destination is added unless *If destination file
exists* is *Do nothing* (the default) or *Fail*: with the default, no file is
added. When the destination file already exists, a file is added only with
*Overwrite destination file* or *Create file with unique name*, and with *Move
source file to folder* the moved source file is added. The result files of the
previous action are kept.
+|Result rows|Passed on unchanged.
+|Lines written|The number of files encrypted or signed. A file left in place
by *Do nothing*, deleted or moved is not counted. When the check of
*Destination folder* (Move to folder) fails, or the action stops on the success
condition between two entries of the list, the value of the previous action is
passed on.
|===
+
+NOTE: The encrypted or signed file keeps the name of the source file: `a.txt`
becomes `a.txt` in the destination folder, no extension is added.
+
+WARNING: *If destination file exists* doesn't always do what its name says.
*Create file with unique name* builds a new name (the date and time added after
the file name, for example `a.txt30102026_140920035`) but writes to the
existing file, which is overwritten; the new name, which doesn't exist, is
added to the result files. *Delete source file* deletes the existing
destination file, not the source, and encrypts nothing. *Move source file to
folder* moves the source file to *Destinati [...]
+
+NOTE: The action has no passphrase option: for *Sign* and *Sign and encrypt*,
GnuPG must be able to use the signing key without asking for one, for example a
key without passphrase or a passphrase already held by `gpg-agent`. Otherwise
the file fails.
+
+NOTE: With *Include Subfolders* and *Do not keep folder structure* unchecked,
a file in a subfolder is written to the same subfolder in the destination.
GnuPG doesn't create that subfolder, so the file fails when it doesn't exist.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpverify.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpverify.adoc
index 31f4331d8f..004fb400ee 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpverify.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/pgpverify.adoc
@@ -37,4 +37,17 @@ GnuPG package must be installed in the runtime environment
and encryption keys a
|Filename|The signed file path.
|Use detached signature|Whether or not to use a detached signature.
|Detached signature|Path to the detached signature file (only available when
the `Use detached signature` above is checked)
-|===
\ 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|GnuPG verified the signature, with 0 errors: a signed or clear-signed
*Filename*, or with *Use detached signature* the *Detached signature* of
*Filename*.
+|False|The number of errors is 1. *Filename* is empty or doesn't exist, the
file is not signed, the signature doesn't match the file (for example a file
changed after it was signed), the signing key is not in the keyring, *Use
detached signature* is checked while *Detached signature* is empty, or *GPG
location* is empty or not found.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
