/
UAC Utility: File Compression

UAC Utility: File Compression

Apr 10, 2025



Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at Stonebranch Integration Hub - Terms of Use.

Overview

File compression is a way to reduce overall file size without losing any of the primary data to make large files more manageable. This Universal Extension provides the capability to compress and decompress a file or directory, with or without password encryption.

Version Information

Template Name

Extension Name

Version

Status

Template Name

Extension Name

Version

Status

File Compression

ue-util-compress

1 (Current 1.3.1)

Fixes and new Features are introduced.

Refer to the Changelog for version history information.

Key Features

Feature

Description

Feature

Description

Actions

  • Compress files or directories.

  • Decompress zip files with files or directories.

Other

  • Support for AES-256 password encryption for files.

  • Support for 7-Zip (Windows/Linux) and p7zip (Linux).

  • Support for Embedded (Linux).

Software Requirements

Area

Details

Area

Details

Universal Controller

Universal Controller Version >= 7.3.0.0.

Universal Agent & Python version

Requires Python version 3.7. Only Agents of version >= 7.3 are supported.

  • 7z Archiver supports Windows and Linux agents.

  • Embedded Archiver supports Linux agents.

Software Requirements

  • 7zip command line tool. 7-zip or p7zip version 15.05 or newer is required to be installed in Universal Agent, tested with 7-zip 21.06 and p7zip 16.02.

  • Embedded Archiver. This Archiver is part of the standard Python Standard Library. Zlib library is also wanted but not needed for better compressions.

More information about the Agent Requirements of 7-Zip can be found here.

Input Fields

The input fields for this Universal Extension are described in the following table.

Field

Input type

Default value

Type

Description

Field

Input type

Default value

Type

Description

Action

Required

Compress

Choice

The action performed upon the task execution.
Available options are listed below.

  • Compress

  • Decompress

Algorithm

Required

ZIP

Choice

The compression algorithm to be used upon the action execution.
Available options are listed below.

  • ZIP

Archiver

Required

7za: 7-Zip (Windows) or p7zip (Linux) - standalone

Choice

The Archiver to be used upon the action execution.
Available options are listed below.

  • 7za: 7-Zip (Windows) or p7zip (Linux) - standalone

  • 7z: 7-Zip (Windows) or p7zip (Linux) - full

  • 7zz: 7-Zip (Linux) - full

  • 7zzs: 7-Zip (Linux) - standalone

  • 7-zip (custom path)

  • Embedded (Linux)

“Embedded (Linux)“ is only available on Linux systems.

Archiver Path

Optional

-

Text

Custom path and file name for the Archiver.
Required when Archiver is configured for "7-zip (custom path)".

Source file

Optional since version 1.2.0

Optional

-

Text

Path and file name of the file to compress or the archive to decompress.

Source File or Directory

Introduced in version 1.2.0

Optional

-

Text

Path of the file name or directory to be used as the source for compression or decompression.

Archive

Optional

-

Text

Path and file name of the target archive file. The default value will be Source File with the algorithm archive suffix.
Used when Action is configured for "Compress".

Output File or Directory

Introduced in version 1.2.0

Optional

-

Text

Path of the filename that should be used as a compression target or path of the directory in which the source zip file should be decompressed.


If Output File or Directory/Output exists and Overwrite flag is "False" then the folder with the name output_ followed by the first available number is created. For example output_1.

File

Optional

-

Text

The file to be extracted. If the value is empty, then default extraction of the archive content.
Used when Action is configured for "Decompress".

Zip Compression Level

Required

5 - Normal

Choice

The level of compression.
Available options are listed below.

  • 1 - Fastest

  • 3 - Fast

  • 5 - Normal

  • 7 - Maximum

  • 9 - Ultra

Delete Original

Required

True

Boolean

Flag to configure whether the Source File or Source File or Directory should be deleted at the end of compression.
Used when Action is configured for "Compress".

Overwrite

Required

False

Boolean

Flag to specify the overwrite mode during extraction.
Used when Action is configured for "Decompress".

Encryption

Required

None

Choice

The encryption algorithm for password protection of the archive.
Available options are listed below.

Password Credentials

Optional

-

Credentials

Credentials to be used for the compression or decompression with Encryption .The Credentials definition should be as follows.

  • User as "Runtime User".

  • User Password as "Runtime Password".

Required when Encryption is configured for "AES-256".

Additional switches

Optional

-

Text

Specifies additional parameters to be passed to the Archiver, separated by empty spaces.

Configuration Examples

Scenario A

Compress a file with AES-256 password encryption.

Scenario B

Decompress a file with 7zip(custom path) Archiver.

Scenario C

Compress a directory with “Embedded (Linux)“ Archiver.

Scenario D

Decompress a multi-folder zip file with “Embedded (Linux)“ Archiver. Note that when Output File or Directory is not given, the zip is extracted at the same folder as the Source File or Directory with the same name in the example test_folder. If Output File or Directory/Output exists then a folder with the name test_folder_ followed by the first available number is created. For example test_folder_1.

Task Output

Output Only Fields

The output field for this Universal Extension is described below.

Field

Type

Description

Field

Type

Description

Archived Processed

Text

Archive name and path.
Generated in "7zip" Archiver option.

Source Processed

Introduced in version 1.2.0

Text

Used to store the file or directory path used as the source of the compress/decompress action.
Generated in "Embedded (Linux)" Archiver option.

Output

Introduced in version 1.2.0

Text

Used to store the directory path used as the output of the compress/decompress action.
Generated in "Embedded" Archiver option.

Exit Codes

The exit codes for this Universal Extension are described in the following table.

Exit Code

Status Classification Code

Status Classification Description

Status Description

Exit Code

Status Classification Code

Status Classification Description

Status Description

0

SUCCESS

Successful Execution

SUCCESS: Task executed successfully.

1

FAIL

Failed Execution

FAIL: << Error Description >>.

20

DATA_VALIDATION_ERROR

Bad input field validation

DATA_VALIDATION_ERROR: Some of the input fields cannot be validated. See STDERR for more details.

21

FAIL

Warning (Non-fatal error(s)). For example, one or more files were locked by some other application, so they were not compressed.

FAIL: Warning.

22

FAIL

Fatal error

FAIL: Fatal error.

27

FAIL

Command line error

FAIL: Command line error.

28

FAIL

Not enough memory for operation

FAIL: Not enough memory for operation.

Extension Output

Attribute "changed" is always true in a successful execution of a task. In case of failure, no extension output is produced.

An example of the Extension Output for a Compress File with 7zz Archiver is presented below.

{ "exit_code":0, "status_description":"SUCCESS: Task executed successfully.", "changed":true, "invocation":{ "extension":"ue-util-compress", "version":"1.2.0", "fields":{ "action":"compress", "algorithm":"zip", "zip_compression_level":1, "source_file":"test/test_file.txt", "archive":"test_archive.zip", "file":null, "overwrite":false, "encryption":"None", "credentials":null, "delete_original":false, "archiver_tool":"7zz", "archiver_path":null, "additional_switches":null } }, "result":{ "archive_processed":"test_archive.zip" } }



An example of the Extension Output for a Compress Directory - “Embedded (Linux)“ Archiver example is presented below.

{ "exit_code": 0, "status_description": "SUCCESS: Task executed successfully.", "changed": true, "invocation": { "extension": "ue-util-compress", "version": "1.2.0", "fields": { "action": null, "action_embedded": "compress", "algorithm": "zip", "zip_compression_level": 5, "source_file": null, "source_embedded": "test/test_folder", "archive": null, "output_embedded": null, "file": null, "overwrite": false, "overwrite_embedded": false, "encryption": null, "credentials": null, "delete_original": false, "delete_original_embedded": false, "archiver_tool": "embedded", "archiver_path": null, "additional_switches": "", "source_processed": null, "output_directory": null } }, "result": { "source_processed": "test/test_folder", "output": "test/test_folder.zip" } }


Attribute result contains the following sub-attributes.

Attribute

Output Type

Mandatory

Description

Attribute

Output Type

Mandatory

Description

archive_processed

String

No

Archive name and path.
Generated in "7zip" Archiver option

source_processed

Introduced in version 1.2.0

String

No

Used to store the file or directory path used as the source of the compress/uncompress action.
Generated in "Embedded" Archiver option

output

Introduced in version 1.2.0

String

No

Job Name
Used to store the directory path used as the output of the compress/decompress action.
Generated in "Embedded" Archiver option

STDOUT and STDERR

STDOUT and STDERR provide additional information to the User. The populated content can be changed in future versions of this extension without notice.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

  • Python code modifications should not be done.

  • Template Modifications

    • General Section

      • "Name", "Extension", "Variable Prefix", "Icon" should not be changed.

    • Universal Template Details Section

      • "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.

    • Result Processing Defaults Section

      • Success and Failure Exit codes should not be changed.

      • Success and Failure Output processing should not be changed.

    • Fields Restriction Section
      The setup of the template does not impose any restrictions, however with respect to "Exit Code Processing Fields" section.

      1. Success/Failure exit codes need to be respected.

      2. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

Document Link

Description

Document Link

Description

Universal Templates

User documentation for creating, working with, and understanding Universal Templates and Integrations.

Universal Tasks

User documentation for creating Universal Tasks in the Universal Controller user interface.

Credentials

User documentation for creating and working with credentials.

Resolvable Credentials Permitted Property

User documentation for Resolvable Credentials Permitted Property.

7zip Official Page

User documentation for downloading the 7zip command line tool.

Changelog

ue-util-compress-1.3.1 (2025-04-10)

Fixes

  • Fixed: Properly handle paths with weird/special characters on both platforms

ue-util-compress-1.3.0 (2024-07-19)

Enhancements

  • Added : Ability to specify an output directory when using 7zip (#41103).

Fixes

  • Fixed: Windows paths containing spaces are now correctly evaluated (#30032).

ue-util-compress-1.2.0 (2022-09-23)

Enhancements

  • Added: Introduction of "Embedded" Compression Method (#29539).

  • Added: Directory compress/decompress capabilities (#29539).

ue-util-compress-1.1.0 (2022-04-12)

Enhancements

  • Added: Archive Processed Output Only Field (#27582).

  • Added: Automated Testing (#27582).

Fixes

  • Fixed: Refactor field names and prefixes (#27315).