Documentation

7.10. Create archive / compress

The create-archive event handler can be configured to create an archive based on one or more files associated with the event.

When creating archives of format GZIP (.gz extension) if the associated event has multiple files, it will compress each file as separate archives.

When creating archives of format ZIP (.zip extension) if the associated event has multiple files, it will compress all files as a single archive.

The create archive event handler only handles direct file paths. Recursive directory paths are not yet supported.

7.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.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.10.9. data_filter

Default value:

''

Optional:

Yes

Values:

  • Comma-separated list of data member names and filter expressions.

  • Multiple expressions, one per line (Since 4.29.0)

  • Leave empty to handle all events.

From version:

3.22.0

Description:

Comma separated definition with the 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 value to be matched/filtered 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 based on multiple data members using multiple rules. Each rule is defined on a separate line.

In the following example, events are triggered only if they are uploaded into the directory named reports-A with a size of 0 bytes (empty file):

[event-handlers/b904ed23-a234-4ccf-8abd-edcae4d3324f]
data_filter =
    path, */reports-A/*
    size, 0

Leave this configuration empty to not filter based on the event's attached data, and handle events regardless of their data attributes.

7.10.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.10.11. archive_format

Default value:

zip

Optional:

Yes

Values:

  • zip

  • gzip

From version:

4.7.0

Description:

The format used to create the archive.

The following formats are supported:

  • zip - Standard ZIP file.

  • gzip - GZ archive file - GNU ZIP.

7.10.12. archive_name

Default value:

{fullname}{archive_extension}

Optional:

Yes

Values:

  • Single format for both single file and multi file archives

  • SINGLE_FILE_FORMAT, MULTI_FILE_FORMAT

From version:

4.7.0

Description:

This configuration defines the name of the archive to be created.

By default, it is the name of the file to be archived with the archive format extension appended to it. For example for archiving the report.TXT file as GZIP, the resulting archive name is report.TXT.gz.

You can define different configuration options for when the archive contains a single file or multiple files. This is defined using a comma-separated value. The first value is used to define the archive file name for single file archives. The second value is used to define the archive file name for multi file archives.

For example with the following configuration archive_name = ARC_{fullname}-approve{archive_extension} a single file ZIP archive for the file report.TXT is created as ARC_report.TXT-approve.zip.

When multiple files are archived and the configuration contains a single value, the archive name is based on a random member of the files to be archived.

For example with the following configuration archive_name = ARC_{fullname}.zip, {year.decimal}-archive.ZIP a single file ZIP archive for the file report.TXT is created as ARC_report.TXT.zip while a multi file archive is created as 2020-archive.ZIP

When defining the file name format the following placeholders are supported:

  • {fullname} - Name of the single file, including the extension.

  • {archive_extension} - Extension based on the archive format, including the leading dot character.

  • {year.decimal} - Year with century as a decimal number. Example: 2009

  • {year.no_century} - Year without century as a zero-padded decimal number. Example: 09

  • {month.decimal} - Month as a decimal number. Example: 9

  • {month.padded} - Month as a zero-padded decimal number. Example: 09

  • {month.name} - Month as locale’s full name. Example: September

  • {month.abbreviated} - Month as locale’s abbreviated name. Example: Sep

  • {day.padded} - Day of the month as a zero-padded decimal number. Example: 07

  • {day.decimal} - Day of the month as a decimal number. Example: 7

  • {day.of_year_padded} - Day of the year as a zero-padded decimal number. Example: 250

  • {day.name} - Weekday as locale’s full name. Example: Friday

  • {day.abbreviated} - Weekday as locale’s abbreviated name. Example: Fri

  • {hour.padded_24} - Hour (24-hour clock) as a zero-padded decimal number. Example: 16

  • {hour.decimal_24} - Hour (24-hour clock) as a decimal number. Example: 16

  • {hour.padded_12} - Hour (12-hour clock) as a zero-padded decimal number. Example: 04

  • {hour.decimal_12} - Hour (12-hour clock) as a decimal number. Example: 4

  • {hour.am_pm} - Equivalent of either AM or PM.

  • {minute.padded} - Minute as a zero-padded decimal number. Example: 05

  • {minute.decimal} - Minute as a decimal number. Example: 5

  • {second.padded} - Second as a zero-padded decimal number. Example: 04

  • {second.decimal} - Second as a decimal number. Example: 4

7.10.13. source_attribute

Default value:

real_path

Optional:

Yes

Values:

  • Event data member name.

From version:

4.7.0

Description:

This is the name of the event's structured data member used to get the path which will be handled by this event.

This is a case-insensitive value.

7.10.14. destination_path

Default value:

empty

Optional:

Yes

Values:

  • Absolute path on the local filesystem.

From version:

4.7.0

Description:

The path where the archive is created.

Leave it empty to extract the files in the same path as the source file.

If the destination path already contains the file which is going to be extracted, the operation fails and the existing file is not overwritten.

7.10.15. overwrite_rule

Default value:

fail

Optional:

Yes

From version:

4.7.0

Values:

  • fail - abort transfer 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 transfer the file.

  • skip - don't transfer the source file when destination exists.

Description:

Rule used to decide how to handle the overwriting of an existing archive 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 archive is not overwritten and the source files are not removed.

7.10.16. delete_source_on_success

Default value:

Yes

Optional:

yes

Values:

  • Yes

  • No

From version:

4.7.0

Description:

Whether to delete the source files after a successful archive creation.

If creating the archive fails, the source is not removed, even when this is set to Yes.

7.9. Syslog
7.11. Extract archive / uncompress