Documentation
7.3. File dispatcher¶
The file-dispatcher event handler can be configured to handle files to one or multiple directory paths based on a matching expression.
This section describes the available configuration options. For more details about the scenarios in which you can use this event handler, check the file dispatcher usage guide.
7.3.1. name¶
- Default value
''
- Optional
No
- From version
2.10.0
- Values
Any text.
- Description
Human-readable short text used to identify this event handler.
7.3.2. description¶
- Default value
''
- Optional
Yes
- From version
2.10.0
- Values
Any text.
- Description
Human-readable text that describes the purpose of this event handler.
7.3.3. type¶
- Default value
''
- Optional
No
- From version
2.10.0
- Values
file-dispatcher - Dispatch a file into one or multiple paths.
http - HTTP POST request (unsecured).
local-file - Append events to a file located on the local file system.
email-sender - Send emails as an SMTP client.
windows-eventlog - Send events to Windows EventLog Service.
standard-stream - Send events to standard output.
syslog - Local Unix socket or remote IP:PORT address for Syslog.
create-archive - Create/Compresses one or more files.
extract-archive - Extract/Uncompressed a file.
external-executable - Execute an external script or program.
openpgp - Encrypt/Decrypt files using OpenPGP.
rabbitmq - Publish event to RabbitMQ AMQP 0-9-1 server.
extension - For custom event handlers implemented using our API.
- Description
This option specifies the type of the event handler. Each type has a set of specific configuration options.
7.3.4. target¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of event ids.
Comma separated list of event ids starting with an exclamation mark.
Leave empty to handle all events.
- From version
2.10.0
- Description
Define a comma separated list of event ids to have the event handler triggered only for those events.
When you want to have it triggered for all the events, excepting a few events you should prefix each event id with the exclamation mark (!).
Leave it empty to handle all events.
Note
Combining the two methods is not supported as the same result can be achieved by allowing only the desired events, all the others will be ignored.
7.3.5. groups¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of event groups.
Comma separated list of event groups starting with an exclamation mark.
Empty.
- From version
3.39.0
- Description
Defines the list of event groups for which this handler is active.
When you want to handle all the events, except for the ones from a set of groups, prefix the group names with the exclamation mark (!).
An event can be a member of one or multiple groups. The event is handled if any of its groups is found in the list of configured allowed groups. The event is not handled if any of its groups is found in the list of configured ignored groups (starting with !).
Leave it empty to handle events from all groups.
7.3.6. usernames¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of usernames.
Comma separated list of usernames starting with an exclamation mark.
Leave empty to handle all events.
- From version
3.9.0
- Description
Comma separated list of usernames whose events are handled by this event handler. A username can include OS accounts, application accounts, and any accounts accepted by any authentication method including external HTTP accounts.
When you want to have it triggered for all the events, excepting a few events you should prefix each username with the exclamation mark (!).
Leave it empty to handle events from any users or events which are not associated with any user.
7.3.7. components¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of UUIDs.
Comma separated list of UUIDs starting with an exclamation mark.
Leave empty to handle all events.
- From version
3.18.0
- Description
Comma separated list of component UUIDs for which events are handled by this event handler.
When you want to have it triggered for all the events, excepting a few events you should prefix each UUID with the exclamation mark (!).
Leave it empty to handle events emitted by any component.
7.3.8. source_addresses¶
- Default value
Empty
- Optional
Yes
- Values
Comma separated list of IP addresses.
List of IP addresses starting with an exclamation mark.
Empty.
- From version
3.40.0
- Description
Comma separated list of source IP addresses of the remote peers, which are handled by this event handler.
When you want to have it triggered for all the addresses, excepting a few addresses you should prefix each address with the exclamation mark (!).
Leave it empty to handle events emitted by any source address.
7.3.9. data_filter¶
- Default value
''
- Optional
Yes
- Values
Comma separated list of data member name and filter expression.
Leave empty to handle all events.
- From version
3.22.0
- Description
Comma separated definition with name of attribute data member and the targeted matching expression.
Data member names are configured with insensitive cases.
For more details about the available expressions see the matching expression documentation.
The following example will extract the to be matched/filtered value from the path data member of the event. The extracted value is then matched against the
*/folderA/*globbing expression:[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f] data_filter = path, */folderA/*
See the usage instructions for more operational details.
You can filter only based on a single data member with a single matching expression.
Leave it empty to not filter based on the event's attached data.
7.3.10. fail_after_errors¶
- Default value
10
- Optional
Yes
- From version
3.0.0
- Values
An integer number greater than 0.
0 Disabled.
- Description
Number of consecutive errors after which the event handler will automatically stop with a failed state.
Setting this to 0 will disable the feature. The event handler will no longer stop regardless of the number of errors encountered.
7.3.11. dispatch_rules¶
- Default value
''
- Optional
No
- Values
dispatch-action, file-match-expression, destination-path-1dispatch-action, file-match-expression, path-1, path-2dispatch-action, file-match-expressionList of rules, separated by newlines.
- From version
3.5.0
- Description
This is a comma separated configuration value.
First value is the file dispatching action. The supported actions are:
move
move-with-timestamp
rename
rename-prepend-unixtime
delete
copy
execute
ignore
Second value is the the full path matching expression. Globbing expression or regular expression can be used. For more details see the matching expression documentation.
The remaining values are paths to which the file is dispatched. The file is dispatched into the configured destinations observing the configured order. Certain actions do not need a destination path.
When regular expressions are used for the path matching configuration, the destination path can be dynamically generated based on regex matching groups and event specific variables.
The following variables (case-insensitive) are provided as context data containing information about the event being triggered:
id
uuid
message
account.name
account.email
account.peer.address
account.peer.port
account.peer.protocol
account.peer.family
account.uuid
component.name
component.type
component.uuid
timestamp.cwa_14051
timestamp.iso_8601
timestamp.iso_8601_fractional
timestamp.iso_8601_local
timestamp.iso_8601_basic
timestamp.iso_8601_compact
timestamp.timestamp
server.name
server.uuid
data.DATA_MEMBER_NAME
data_json
For more details see the file dispatcher usage guide.
You can specify multiple rules, one per line. Leading and trailing spaces are ignored.
7.3.12. retry_count¶
- Default value
0
- Optional
Yes
- From version
4.5.0
- Values
0
Positive integer
- Description
This is the number of times a failed file dispatching actions is retried.
When set to 0, failed actions are never retried.
7.3.13. retry_wait¶
- Default value
60
- Optional
Yes
- From version
4.5.0
- Values
0
Positive integer
- Description
Number of seconds to wait before retrying a failed action.
When set to 0, there will be no waiting time. As soon as a file action fails, it will be retried.
7.3.14. executable_timeout¶
- Default value
30
- Optional
Yes
- Values
Number
- From version
4.15.0
- Description
Number of seconds to allow for the external process to execute before forcefully closing it.
A configured value must be equal to or greater than 1.
7.3.15. fallback_rule¶
- Default value
''
- Optional
Yes
- Values
dispatch-action, destination-path-1dispatch-action, path-1, path-2dispatch-action
- From version
3.5.0
- Description
This is a comma separated configuration value.
This is a single rule which defines how to dispatch files which were not matched by any of the rules defined at dispatch_rules.
Leave it empty to do nothing for files which don't match any expression.
First value is the file dispatching action. It supports all actions from dispatch_rules.
The remaining values are paths to which the file is dispatched. The files are dispatched using the same process as for dispatch_rules.
7.3.16. matching_expressions¶
- Default value
''
- Optional
No
- Values
attribute name, regular expression
List of rules, separated by newlines.
- From version
4.0.0
- Description
This is a comma-separated configuration value.
First value is the name of the attribute from which to collect data for the rename operations.
Second value is the full path matching expression. Globbing expression or regular expression can be used. For more details see the matching expression documentation.
You can specify multiple rules, one per line, to source the rename operation from multiple values. Leading and trailing spaces are ignored.
7.3.17. dispatch_attribute¶
- Default value
real_path
- Optional
Yes
- Values
Event data member name.
- From version
3.20.0
- Description
This is the name of the event's data attribute used to get the path or the list of paths which will be dispatched by this event.
This is a case-insensitive value.
7.3.18. dispatch_delay¶
- Default value
0
- Optional
Yes
- Values
Number of seconds.
- From version
4.2.0
- Description
Number of seconds to delay the execution of the dispatch action.
If the targeted file no longer exists after the delay, the dispatch execution is canceled and an event is emitted.
Set it to 0 to execute the dispatching right away.
7.3.19. destination_temporary_suffix¶
- Default value
Empty
- Optional
Yes
- From version
4.8.0
- Values
Empty.
Short text.
- Description
Allows copying or moving a file to the destination using a temporary name, renaming to its initial name once all the file's content was processed.
Leave it empty to always copy a file to its destination using the original name.
Note
The temporary name is only used for copy or move operations. It it not used for rename or delete operations.
7.3.20. overwrite_rule¶
- Default value
fail
- Optional
Yes
- From version
4.8.0
- Values
fail - abort dispatching if destination file already exists.
overwrite - always overwrite existing files with the content of the new source files.
disable - don't check for existing file and always try to handle the file.
skip - don't dispatch the source file when destination exists.
- Description
This configuration option is used to decide how to handle the overwriting of an existing file at the destination.
When set to overwrite it will emit an event when the destination file is overwritten.
When set to skip it will not handle the file and the source file is not removed. An event is emitted to inform that the file was skipped.
When set to fail the event handling will fail. The existing file is not overwritten and the source files are not removed.
7.3.21. create_destination_folder¶
- Default value
Empty
- Optional
Yes
- Values
parent
Empty
- From version
3.31.0
- Description
This configuration can be used to instruct SFTPPlus to create the destination folder, in case they do not exist.
This is a case-insensitive value.
Set it to parent to create the parent directory of the destination file.
Leave it empty to not have the destination automatically created and fail when the destination does not exist.