Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/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

Refer to Changelog for version history information.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Software Requirements for 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.
• 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 key features:

• 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.

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow the instructions here.

3. 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 a new Universal Task, create a new task, and enter the required input fields.

Input Fields

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

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. 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 below.

SUCCESS: Task executed successfully.

Exit Codes

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

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.

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.
    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 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.

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)