start portlet menu bar end portlet menu bar
  • Overview
  • Documentation
  • Version history

Description

The File Utils plugin provides steps for manipulating files and directories.

Quick Info

Product icon

Product

HCL DevOps Deploy (HCL Launch)
Plugin type icon

Type

plugin
Compatibility icon

Compatibility

HCL Launch version 7.3.2.8 and later, HCL Deploy version 8.0.1.3 and later
created by icon

Created by

HCL Software
Website icon

Website

File Utils

Published Date

Last Updated

The steps in this plugin manipulate files on the target system.

Compatibility

This plugin is supported to run on all operating systems that are supported by the HCL Deploy agent, including z/OS with UNIX System Services.

History

The following table describes the changes made in each plugin version:

Plugin history details
Version Description
100

Added Condition to ignore token replacement for the properties file.
99

Port "Replace Tokens" step to Java.
98

Port "Create File", "Monitor File Contents", "Read Property File", and "Create Directories" steps to Java.
97

Updated securedata library, so that it will not fail to initialize if AES256 is unsupported.
96

Supports AES 256-bit keys for input/output property encryption if also supported by the agent.
95

Updated ini4j library for CVE-2022-41404.
94

APAR PH52898 – Running the replace tokens step is taking longer to complete with each run.
93

Restore classpath for steps still implemented in groovy to fix

NoSuchMethodError

errors
92

Port “Copy Directory” step to Java to reduce CPU consumption.

Handle very large directories in the Replace Tokens step without running out of memory.
91

Updating Jettison library to 1.5.4 for CVE-2023-1436
90

Updating jettison library for CVE-2022-45693 and CVE-2022-45685.
89

Fix issues in xml handling for Update XML for Xpath step.
88

Updating jettison library for CVE-2022-40150 CVE-2022-40149.
87

Fix an encoding issue with the untar step on z/OS.
86

Fixed infinite loop in replace tokens step when using groovy 3.
85

Fixed UI field and properly checked DTD speciication.
84

Fixes APAR PH43524 – Replace token step alters file permissions.
83

Add compatibility with Groovy 3.
82

Fixes several security issues.
81

Fixes APAR PH35488 – Replace token step not accepting comma separated list of files in includes section&lt.
81

Fixes APAR PH35488 – Replace token step not accepting comma separated list of files in includes section.

The following process steps are available in the File Utils plugin.

Copy Directory

Copy the contents of a directory to other directories. This step overwrites files
but does not delete files.

Input properties for the Copy Directory step
Name Type Description Required
Destination Directories String A list of directories to copy to, separated by newline characters. Yes
Exclude Files String A list of patterns, separated by newline characters, that describe the files to skip.
For example, if you specify **/*.zip, all .zip
files in all subdirectories are excluded.		 No
Fail on Error Boolean When this checkbox is checked, the step will fail if an error occurs while copying
files and directories. Otherwise, only a warning message is displayed in the command
output.		 No
Flatten Directory Structure Boolean Ignore the directory structure of the source files, and copy all files into the destination
directory.		 No
Force Boolean Overwrite read-only destination files. Since Ant 1.8.2. No
Include Files String A list of patterns, separated by newline characters, that describe the files to copy.
The default, **/*, includes all files.		 Yes
Preserve Last Modified Boolean Preserve the time stamps from the source files and folders. No
Rename Rules String A list of rules, separated by newline characters, for renaming the files in the destination
directories. Use the format “FROM->TO”. For example, specify a.txt->b.txt to
rename files named “a.txt” to “b.txt” and use *.java->*.java.bak to
change file suffixes from .java to .java.bak. Rules are applied in the order that
they are specified. No more than one rule is applied
to a file.		 No
Source Directory String The directory to copy. Yes

 

Create .zip File

Create a .zip file.

Input properties for the Create .zip File step
Name Type Description Required
.zip File Name String Name of the new .zip file. Yes
Base Directory String The directory that contains the files to add to the archive. Yes
Case Sensitive Boolean Select to use case-sensitive matching. No
Custom Encoding String Specify a character encoding to use when creating the .zip file. If blank, the .zip
file is created with the local character encoding
of the agent. Example encodings: US-ASCII, UCS-2,
JIS X 0201, UTF-16, UTF-16LE, EUC.		 No
Exclude String A list of patterns, separated by newline characters, that describe the files and directories
to skip. For example: **/*.txt		 No
Follow Symlinks Boolean Select to follow symlinks when including files. No
Include String A list of patterns, separated by newline characters, that describe the files and directories
to include. For example: **/*		 Yes
Update existing Boolean Select to update or overwrite the destination file if a file with that name already
exists.		 No

 

Create Directories

Create a set of directories, including nested directories.

Input properties for the Create Directories step
Name Type Description Required
Directories String A list of directories to create, separated by newline characters. Yes

 

Create File

Create a text file.

Input properties for the Create File step
Name Type Description Required
Contents String The contents of the file. No
Custom Encoding String Specify a character encoding to use when creating the file. If blank, the file is
created with the local character encoding of the agent. Example encodings: US-ASCII,
UCS-2, JIS X 0201, UTF-16, UTF-16LE, EUC.		 No
File Name String The name of the file. Yes
Overwrite if exists Boolean Select to overwrite an existing file with the same name. No

 

Delete Files and Directories

Delete files and directories.

Input properties for the Delete Files and Directories step
Name Type Description Required
Base Directory String The base directory where files and directories are deleted. Yes
Case Sensitive Boolean Select to use case-sensitive matching. No
Exclude String A list of patterns, separated by newline characters, that describe the files and directories
to skip when deleting. For example, specify **/*.txt to skip all .txt files.		 No
Follow Symlinks Boolean Select to follow symlinks when deleting. No
Include String A list of patterns, separated by newline characters, that describe the files and directories
to delete. For example, specify **/* to delete all files.		 Yes

 

Flip Line Endings

Convert file line endings between UNIX and Microsoft Windows formats.

Input properties for the Flip Line Endings step
Name Type Description Required
Ending Enumeration The line ending type to use. Values are os, windows, and unix. No
Excludes String A list of patterns, separated by newline characters, that describe the files to skip. No
Includes String A list of patterns, separated by newline characters, that describe the files to convert. Yes

 

Get text of XML text node

Get text of XML text node using xpath

Input properties for the Get text of XML text node step
Name Type Description Required
Source Directory Offset String The directory relative to the current working directory that contains the files to
operate on.		 No
Xml File String A xml file to read data from. Yes
xPath String A XPath expression that specify element to get text of.
For example, specify /root/foo to get all foo elements text under the root element.
In case of xpath resulting into multiple matching nodes then first node data will
be returned		 Yes

 

Monitor File Contents

Monitor a file for a token. The step continues when the token is found, and fails if the token is not found in the specified time. This step is similar to the UNIX tail command, and ignores content in the file that is present before the step starts.

Input properties for the Monitor File Contents step
Name Type Description Required
Directory Offset String The directory relative to the current working directory that contains the file to
monitor.		 No
Fail if found Boolean Select to configure the step to fail if the regular expression is matched. When selected,
the step does not fail when the timeout expires.		 No
File Name String The name of the file to monitor. Yes
Regular Expression String A regular expression that describes the token to match in the file. Yes
Timeout (s) String The time, in seconds, to wait for a match to the regular expression. The step fails
if a match is not found before the timeout expires.		 Yes

 

Move Directory

Move the contents of a directory to another directory.

Input properties for the Move Directory step
Name Type Description Required
Destination Directory String The directory to move to. Yes
Exclude Files String A list of patterns, separated by newline characters, that describe the files to skip.
For example, if you specify **/*.zip, all .zip
files in all subdirectories are excluded.		 No
Include Files String A list of patterns, separated by newline characters, that describe the files to move.
The default, **/*, includes all files.		 Yes
Rename Rules String A list of rules, separated by newline characters, for renaming the files in the destination
directories. Use the format “FROM->TO”. For example, specify a.txt->b.txt to
rename files named “a.txt” to “b.txt” and use *.java->*.java.bak to
change file suffixes from .java to .java.bak. Rules are applied in the order that
they are specifed. No more than one rule is applied
to a file.		 No
Source Directory String The directory to move. Yes

 

Read Properties From XML File

Parse an XML file to search for properties defined by element names.

Input properties for the Read Properties From XML File step
Name Type Description Required
Directory Offset String The directory relative to the current working directory that contains the files to
operate on.		 No
Fail if no match found Boolean Select to configure the step to fail if any of the XPath expressions do not return
a match.		 No
Property Keys String A list of elements, separated by newline characters, whose values will be used for
properties. Use dot notation to refer to nested
elements. For example, specify foo.bar.baz to retrieve the
value of the baz element under the bar element under the foo element. Use the at sign
(@) to specify attributes. For example, specify
foo.bar.baz.@name to retrieve the name attribute of
the baz element under the bar element under the foo element.		 Yes
XML File String The full path to the XML file to read properties from. Yes

 

Read Property File

Read properties from a file and set them as output properties for the step.

Input properties for the Read Property File step
Name Type Description Required
Directory Offset String The directory relative to the current working directory that contains the files to
operate on.		 No
Property File String The name of the property file to read. Yes

 

Replace Tokens

Replace tokens in files using properties.

Input properties for the Replace Tokens step
Name Type Description Required
Custom Encoding String Specify a character encoding to use. If blank, the replacement file is created with
the local character encoding of the agent. Example encodings: UTF-8, US-ASCII, UCS-2,
JIS X 0201, UTF-16, UTF-16LE, EUC.		 No
Directory Offset String The directory relative to the current working directory that contains the files to
operate on.		 No
End Token Delimiter String The end delimiter character used to identify tokens. No
Exclude Files String A list of patterns, separated by commas or spaces, that describe the files to exclude.
New lines will be replaced with commas.		 No
Explicit Tokens String A list, separated by newline characters, of explicit tokens to replace in the form
of token->value. For example: if you specify mytoken->new_value,
the step replaces mytoken with new_value. The
token delimiter and property prefix settings apply. If you specified a value
in the Property List field, the explicit tokens are added as additional values to
replace, and override any properties that have
the same name. You cannot use regular expressions.		 No
Include Files String A list of patterns, separated by commas or spaces, that describe the files to include.
New lines will be replaced with commas.		 Yes
Property File Name String The name of the file used to store the replacement name-value pairs. You can use an
existing file. If the file does not exist, it
is created and then removed when the step completes.		 No
Property List String Specify a property value here to use existing property names as tokens to replace
in the target files. For example: Specify ${p:environment/allProperties}
to use the names of all component environment
properties as tokens and the property values as the replacements.
Similarly, specify ${p:component/allProperties},${p:environment/allProperties} to
use the names of all component and component environment
properties as tokens. The token delimiter and
property prefix settings apply. If you specify @ for the start and end token delimiters
and a property named token1 exists, then the step searches for @token1@ to replace.		 No
Property Prefix String Specify a prefix to use to determine which properties are included in token replacement.
Leave blank to include all properties.		 No
Start Token Delimiter String The start delimiter character used to identify tokens. No

 

Search Files and Folders

Search for Files and Folders in a custom directory or default working directory.

Input properties for the Search Files and Folders step
Name Type Description Required
Custom Directory String Mention a directory if don’t want to use default working directory for searching No
File Name String The name of the file. Yes
Search in Subfolders Boolean Select to search in subfolders also No
Use Custom Directory Boolean Select to use custom directory No

 

Synchronize Directories

Move new files in a source directory to a destination directory, and delete files
in the destination directory that are not in the source directory. Synchronization
is based on the time stamp of the file.

Input properties for the Synchronize Directories step
Name Type Description Required
Destination Directories String A list of directories to copy to and synchronize, separated by newline characters. Yes
Exclude Files String A list of patterns, separated by newline characters, that describe the files to skip.
For example, if you specify **/*.zip, all .zip
files in all subdirectories are excluded.		 No
Include Files String A list of patterns, separated by newline characters, that describe the files to synchronize.
The default, **/*, includes all files.		 Yes
Overwrite Boolean Select to overwrite target files even if they are newer than source files. No
Preserve In Target Exclude Files String A list of patterns, separated by newline characters, that describe files to skip for
preservation in the target directories.		 No
Preserve In Target Include Files String A list of patterns, separated by newline characters, that describe files to include
for preservation in the target directories.		 No
Source Directory String The synchronization source directory. Yes

 

Untar Tarball

Extract a .tar file.

Input properties for the Untar Tarball step
Name Type Description Required
Extract directory String The directory to extract the .tar file to. No
Overwrite files Boolean If selected, files are overwritten even if they are newer than files in the .tar file. No
Tarball String The .tar file to extract. Use wildcards that are supported by Ant pattern matching
to extract multiple .tar files. For example, if
you specify json-*.tar, both json-c-0.10.tar and
json-c-0.20.tar are extracted.		 Yes
Tarball Enumeration Select the compression algorithm for the .tar file. Values are none, gzip, and bzip2. No

 

Unzip

Extract a .zip file.

Input properties for the Unzip step
Name Type Description Required
.zip files String A list of patterns, separated by commas or spaces, that describe the .zip files to
extract.		 Yes
Custom Encoding String Specify a character encoding to use when extracting files. If blank, the .zip file
is created with the local character encoding of
the agent. Example encodings: UTF-8, US-ASCII, UCS-2,
JIS X 0201, UTF-16, UTF-16LE, EUC.		 No
Exclude Files String A list of patterns, separated by commas or spaces, that describe the files in the
archive to skip.		 No
Extract directory String The directory to extract the .zip file to. No
Include Files String A list of patterns, separated by commas or spaces, that describe the files in the
archive to extract.		 Yes
Overwrite files Boolean If selected, files are overwritten even if they are newer than files in the .zip file. No

 

Update INI File

Update a file in the Microsoft Windows INI format. This step supports property sections.

Input properties for the Update INI File step
Name Type Description Required
Add Section Comments String Specify a list of comments, separated by newline characters, to add to sections. For
example, specify section1=newComment to add newComment
in a comment line above the section1 section.		 No
Custom Encoding String Specify a character encoding to use when accessing the INI file. If you do not specify
an encoding, the local character encoding of the
agent is used.		 No
File Name String The name of the file to update. Yes
Remove Section String A list of sections to remove, separated by newline characters. Removing a section
removes the properties and property comments in
the section.		 No
Remove properties String A list of properties to remove, separated by newline characters. To remove properties
in subsections, add the full path of the parent
sections to the property name, using a backslash
(\) as a separator. For example, specify section1\section2\propertyName to remove
the propertyName property in the section2 subsection
of the section1 section.		 No
Update properties String A list of name-value pairs to update, separated by newline characters. Use the format
section\name=value. Comments that precede a property line are added to the property.
Comment lines begin with a semicolon (;) or number
sign (#). To update properties in subsections, add
the full path of the parent sections to the property name, using a backslash (\) as
a separator. For example, specify section1\section2\propertyName=value
to update the propertyName property in the section2
subsection of the section1 section.		 No
Use ‘#’ character for comments Boolean Select to use the number sign (#) to indicate a comment. Clear to use the semicolon
(;) to indicate a comment.		 No

 

Update Java Properties File

Add, remove, or update properties in a Java properties file.

Input properties for the Update Java Properties File step
Name Type Description Required
Add/Update properties String A list of name-value pairs, separated by newline characters. This field takes precedence
over Additional properties. Use the format property_name=property_value.		 No
Additional properties String A list of additional properties, separated by commas. For example, specify
${p:environment/allProperties} to add all environment properties as name-value pairs
to the list of properties to update. The Additional
properties field takes precedence over this field.		 No
Additional properties prefix String Specify a prefix to use to filter the properties specified in the Additional properties
field. The prefix is removed from the property name to form the property that is added
to the property file. For example: if the Additional
properties field is set to ${p:enviroment/allProperties},
specify “proxy” to update only the properties that
begin with “proxy.”		 No
Custom Encoding String Specify a character encoding to use when accessing the properties file. This field
takes precedence over Use System Encoding.		 No
Directory Offset String The directory relative to the current working directory that contains the files to
operate on.		 No
File Excludes String A list of patterns, separated by newline characters, that describe the property files
to skip.		 No
File Includes String A list of patterns, separated by newline characters, that describe the property files
to edit.		 Yes
Remove properties String A list of names of properties to remove, separated by newline characters. No
Use System Encoding Boolean Select to use the local character encoding of the agent when accessing the properties
file.		 No

 

Update XML File with XPath

Update XML files using XPath to locate items to edit.

Input properties for the Update XML File with XPath step
Name Type Description Required
Apply formatting to output XML Boolean Select to output the document with a degree of formatting. Elements are indented and
given new lines wherever possible to make a more readable document.		 No
Destination Directory Offset String The directory relative to the current working directory where the edited XML files
will be stored.		 No
Fail Mode Enumeration The action to perform when an malformed xml is found. Values are WARN_ONLY, FAIL_FAST, and FAIL_ON_ANY_FAILURE. Yes
Fail if no match found Boolean Select to configure the step to fail if any of the XPath expressions do not return
a match.		 No
File Excludes String A list of patterns, separated by newline characters, the describe the files to skip. No
File Includes String A list of patterns, separated by newline characters, that describe the files to modify. Yes
Ignore DTD Specification Boolean Select to ignore document type declarations that are specified in the XML files.
WARNING: these declarations are commented out temporarily while the step runs.		 No
Insert XML String A list of XPath expression-content pairs, separated by newline characters. Use the
format expression->content. For example, specify
/root/foo-><bar/> to insert an empty bar element
under all foo elements in the root element. For
XML documents using a default namespace, XPath expressions are represented
like /:root/:foo. For XML documents using prefixed
namespaces, XPath expressions are represented like
/ns:root/foo or /ns:root/ns:foo or /ns1:root/ns2:foo.		 No
Remove String A list of XPath expressions, separated by newline characters, that specify elements
to remove. For example, specify /root/foo to remove
all foo elements under the root element. For XML
documents using a default namespace, XPath expressions are represented
like /:root/:foo. For XML documents using prefixed
namespaces, XPath expressions are represented like
/ns:root/foo or /ns:root/ns:foo or /ns1:root/ns2:foo.		 No
Replace with text String A list of XPath expression-replacement pairs, separated by newline characters. Use
the format expression->replacement. For example,
specify /root/foo/text()->bar to replace the text for all
foo elements under the root element with bar. The step does nothing
if the specified expression does not exist in the source files.
For XML documents using a default namespace, XPath expressions are represented
like /:root/:foo/text(). For XML documents using
prefixed namespaces, XPath expressions are represented
like /ns:root/foo/text() or /ns:root/ns:foo/text() or /ns1:root/ns2:foo/text().		 No
Set Attributes String A list of XPath expression-content pairs, separated by newline characters. Use the
format expression->content. For example, specify
/root/foo/@bar->my_bar to replace the bar attribute
value for all foo elements under the root element with my_bar. The XPath expression
must end with the /@name of the attribute to insert
or update. For XML documents using a default namespace,
XPath expressions are represented like /:root/:foo/@bar.
For XML documents using prefixed namespaces, XPath expressions are represented
like /ns:root/foo/@bar or /ns:root/ns:foo/@bar or /ns1:root/ns2:foo/@bar.		 No
Source Directory Offset String The directory relative to the current working directory that contains the files to
operate on.		 No

Issue with case-sensitive files on Windows

Because of case insensitivity of the Windows OS file system, the Copy Directory step cannot support the renaming of files or folders when the same case-insensitive file or folder name exists in the destination directory. This inability holds true whether the file or folder is being renamed in place or in a different destination directory. This issue is documented in Apache Ants Copy step.

Work Around

If you intend to rename a file or folder in a destination folder, then delete the file first in the destination directory before the files and folders are copied.

If you intend to rename a file or folder in place, then you cannot delete first otherwise the source item will be gone. In this case, you will need to use a temporary directory. First copy the files into the temporary directory, delete the source files, and then move the temporary directory files back into the original location. You can rename the files in either the first or second copy step.

launch-fileutils-100.1176430.zip

Uploaded: 12-May-2025 07:42

Release notes

Added Condition to ignore token replacement for the properties file.

Download Icon DOWNLOAD

launch-fileutils-100.1175039.zip

Uploaded: 28-Apr-2025 11:57

Download Icon DOWNLOAD

launch-fileutils-97.1167642.zip

Uploaded: 24-Apr-2024 11:35

Release notes

Updated securedata library, so that it will not fail to initialize if AES256 is unsupported.

Download Icon DOWNLOAD

launch-fileutils-96.1160835.zip

Uploaded: 31-Aug-2023 21:38

Release notes

Supports AES 256-bit keys for input/output property encryption if also supported by the agent.

Download Icon DOWNLOAD

launch-fileutils-95.1159914.zip

Uploaded: 25-Aug-2023 19:01

Release notes

Update ini4j library for CVE-2022-41404

Download Icon DOWNLOAD

launch-fileutils-94.1156804.zip

Uploaded: 16-May-2023 14:35

Release notes

Fixes APAR PH52898 - Running the replace tokens step is taking longer to complete with each run.

Download Icon DOWNLOAD

launch-fileutils-93.1156702.zip

Uploaded: 12-May-2023 15:36

Release notes

Restore classpath for steps still implemented in groovy to fix NoSuchMethodError errors

Download Icon DOWNLOAD

launch-fileutils-92.1156646.zip

Uploaded: 11-May-2023 18:45

Release notes

Handles very large directories in the Replace Tokens step without running out of memory

Download Icon DOWNLOAD

launch-fileutils-91.1155730.zip

Uploaded: 21-Apr-2023 14:12

Release notes

Updating Jettison library to 1.5.4 for CVE-2023-1436

Download Icon DOWNLOAD

launch-fileutils-90.1150683.zip

Uploaded: 01-Feb-2023 14:07

Release notes

Updating jettison library for CVE-2022-45693 and CVE-2022-45685

Download Icon DOWNLOAD

launch-fileutils-89.1142810.zip

Uploaded: 13-Oct-2022 14:04

Release notes

Fix issues in xml handling for Update XML for Xpath step

Download Icon DOWNLOAD

launch-fileutils-88.1142768.zip

Uploaded: 13-Oct-2022 13:31

Release Note

Updating jettison library for CVE-2022-40150 CVE-2022-40149.

Download Icon DOWNLOAD

launch-fileutils-88.1142533.zip

Uploaded: 10-Oct-2022 16:34

Download Icon DOWNLOAD

launch-fileutils-87.1134890.zip

Uploaded: 12-Jul-2022 14:15

Release notes

Fix an encoding issue with the untar step on z/OS

Download Icon DOWNLOAD

launch-fileutils-86.1130264.zip

Uploaded: 24-Feb-2022 12:59

Release notes

Fixed infinite loop in replace tokens step when using groovy 3

Download Icon DOWNLOAD

launch-fileutils-85.1129819.zip

Uploaded: 21-Feb-2022 10:05

Release notes

Fixed UI field and properly checked DTD specification

Download Icon DOWNLOAD

launch-fileutils-84.1128977.zip

Uploaded: 10-Feb-2022 18:36

Release notes

Fixes APAR PH43524 - Replace token step alters file permissions

Download Icon DOWNLOAD

launch-fileutils-83.1127364.zip

Uploaded: 11-Jan-2022 21:34

Release note

Added compatibility with Groovy 3

Download Icon DOWNLOAD

launch-fileutils-82.1126088.zip

Uploaded: 02-Dec-2021 15:46

Release notes

Fixes several security issues

Download Icon DOWNLOAD

launch-fileutils-79.1098159.zip

Uploaded: 11-Mar-2021 05:49

Release notes

Fixes APAR PH35488- Replaced token step not accepting comma separated list of files in includes section

Download Icon DOWNLOAD

Related Plugins