...
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 | Extension Version |
---|---|---|
File Compression | ue-util-compress | 1.2.0 |
Refer to Changelog for version history information.
Software Requirements
This solution-pack integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Software Requirements for /wiki/spaces/UC71x/pages/5178050 and /wiki/spaces/UC71x/pages/5180675 Universal Template and Universal Task
Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.
Software Requirements for Universal Agent
...
- Windows and Linux agents are
...
- supported for 7z Archiver.
- Linux is supported for Embedded Archiver.
- Universal Agent for Windows x64 Version 7.0.0.0 and later with python options installed.
- Universal Agent for Linux Version 7.0.0.0 and later with python options installed.
Software Requirements for Universal Controller
Universal Controller Version 7.0.0.0 and later.
This Universal Extension is using any of the following:
- 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.
Notes about 7-Zip and p7zip
Excerpt from 7-Zip readme file. There are two different ports of 7-Zip for Linux:
p7zip - another port of 7-Zip for Linux, made by an independent developer. The latest version of p7zip now is 16.02, and that p7zip 16.02 is outdated now.
7-Zip for Linux/macOS - this package - it's new code with all changes from latest 7-Zip for Windows.
These two ports are not identical. Note also that some Linux specific things can be implemented better in p7zip than in new 7-Zip for Linux.
There are several main executables in 7-Zip and p7zip:
7zz (7-Zip)
Stand-alone full version of 7-Zip that supports all formats.7zzs (7-Zip)
Stand-alone full version of 7-Zip that supports all formats (static library linking).7z (p7zip)
7-Zip that requires 7z.so shared library, and it supports all formats via 7z.so.7za (p7zip)
Stand-alone version of 7-Zip that supports some main formats: 7z, xz, lzma, zip, bzip2, gzip, tar, cab, ppmd and split.
7zzs is similar to 7zz, but 7zzs was compiled for static library linking, so 7zzs does not use external shared library (".so") files.
You can use 7zzs if 7zz does not work due to lack of required shared library (".so") files. The command line syntax for executables from p7zip is similar to 7zz syntax from this package.
See the 7-Zip website for more information.
Software Requirements for Universal Controller
...
- 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 here.
Key Features
This Universal Extension provides the following main key features:
...
Support to compress and decompress a file with zip deflate method.
- Actions
- Compress file 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)
Import Universal Template
To use the Universal Template, you first must perform the following steps:.
This Universal Task requires
...
the Resolvable Credentials feature. Check that the
...
Resolvable Credentials Permitted system property has been set to true.
...
Download the provided ZIP file.
...
In the Universal Controller UI, select Configuration > Universal Templates to display the current list of /wiki/spaces/UC71x/pages/5178054.
...
Click Import Template.
...
Select the template ZIP file and Import.
...
To import the Universal Template into your Controller, follow the instructions here.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
...
Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.
Configure Universal Task
For the a new Universal Task type, create a new task, and enter the task-specific details that were created in the Universal Templaterequired input fields.
Input Fields
The input fields for this Universal Extension are described in the following table.
Field | Input type | Default value | Type | Description |
---|---|---|---|---|
Action | Required | Compress file | Choice | The action performed upon the task execution. Available options are :listed below.
|
Algorithm | Required | zipZIP | Choice | The compression algorithm to be used upon the action execution. Available option is:zipoptions are listed below.
|
Archiver Tool | Required | 7za: 7-Zip (Windows) or p7zip (Linux) - standalone | Choice | The archiver tool Archiver to be used upon the action execution. Available options are :listed below.
|
Archiver Path | Optional | - | Text | Custom path and file name for the archiver tool Archiver. Required when Archiver Tool is configured for "7-zip (custom path)". |
Source file Required Optional since version 1.2.0 | Optional | - | Text | Path and file name of the file to compress or the archive to extractto decompress. |
Source File or Directory Introduced in version 1.2.0 | Optional | - | Text | Path of file name or directory to be used as source for compression or decompression with “Embedded (Linux)“ Archiver. |
Archive | Optional | - | Text | Path and file name of the target archive file. 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 filename that should be used as a compression target when using “Embedded (Linux)“ Archiver, or Path of directory in which the source zip file will be decompressed when using “Embedded (Linux)“ Archiver. If Output File or Directory/Output exists and Overwrite flag is "False" then folder with name output_ followed by the first available number is created. For example output_1. Used with “Embedded (Linux)“ Archiver. |
File | Optional | - | Text | The file to be extracted. If value is empty, then default extraction of the archive content. Used when Action is configured for "Decompress file". |
Zip Compression Level | Required | 5 - Normal | Choice | The level of compression. Available options are :listed below.
|
Delete Original | Required | True | Boolean | Flag to configure for whether the Source File or Source File or Directory should be deleted at the end of compression. Used when Action is configured for "Compress file". |
Overwrite | Required | False | Boolean | Flag to specify the overwrite mode during extraction. Used when Action is configured for "Decompress file". |
Encryption | Required | None | Choice | The encryption algorithm for password protection of the archive. Available options are :listed below.
|
Password Credentials | Optional | - | Credentials | The password Credentials to be used for the compression or decompression with Encryption .The Credentials definition should be as follows.
|
Additional switches | Optional | - | Text | Specifies additional parameters to be passed to the archiver tool Archiver, separated by empty spaces. |
Task Examples
Compress File with AES-256 Password Encryption - 7zip Archiver
Example of Universal Task for compressing file with AES-256 password encryption.
Decompress File with 7-zip(custom path) Archiver Tool - 7zip Archiver
Example of Universal Task for decompressing file with 7zip(custom path) Archiver.
Compress Directory - Embedded Archiver
Example of Universal Task for compressing directory with “Embedded (Linux)“ Archiver.
Decompress Zip - Embedded Archiver
Example of Universal Task for decompressing multi folder zip file with “Embedded (Linux) Archiver Tool.“ 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 same name in example test_folder. If Output File or Directory/Output exists then folder with name test_folder_ followed by the first available number is created. For exampled test_folder_1.
Task Output
Output Only Fields
The output field for this Universal Extension is described in the following tablebelow.
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. |
SUCCESS: Task executed successfully.
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 |
---|---|---|---|
0 | SUCCESS | Successful Execution | SUCCESS: Successful Task executionexecuted successfully. |
1 | FAIL | Failed Execution | FAIL: < Error Description > |
20 | DATA_VALIDATION_ERROR | Bad input fields 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 |
255 | FAIL | User stopped the process | FAIL: User stopped the process |
Extension Output
The Extension Output for this Universal Extension is described below.
...
Extension Output
Attribute changed is always true on 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 |
---|---|---|---|
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 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.- Success/Failure exit codes need to be respected.
- 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 success or failure of a task.
- General Section
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
Document References
This document references the following documents:
...
Name
...
.
Document Link | Description | |
---|---|---|
Universal Templates | https://docs.stonebranch.com/confluence/display/UC71x/Universal + Templates | User documentation for creating, working with and understanding Universal Templates in the Universal Controller user interfaceand Integrations. |
Universal Tasks | https://docs.stonebranch.com/confluence/display/UC71x/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 | https://www.7-zip.org/download.htmlUser documentation for downloading 7zip command line tool. |
Changelog
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 prefix (#27315)