File System - Rename

Declaration

<AMFILESYSTEM ACTIVITY="rename" SUBFOLDERS="yes/no" OVERWRITE="yes/no" ISNEWER="yes/no" ONLYIFEXIST="yes/no" OVERWRITEREADONLY="yes/no" OVERWRITEHIDDEN="yes/no" ARCHIVETURNOFF="yes/no" EXCLUDE="text" RE="yes/no" ISNEWERTHAN="DateSerial" SOURCE="text" DEST="text" RESULTDATASET="text" />

Related Topics    

Description

Renames one or more folders or files from a source path to a destination path. To specify multiple folder/file names, separate them with a pipe symbol (Example: c:\file.txt|c:\file.bak). Files can also be renamed to a new location.

Practical usage

Commonly used as an organization tool to automate the renaming of multiple folders or files. For instance, files can be renamed to include the current date/time, the parent folder name, department name, etc.

Parameters

General

Property Type Required Default Markup Description
File/Folder Text (options) Yes File
  • MODE="file"
  • MODE="folder"
 Indicates what objects should be renamed. The available options are:

  • File (default) - One or more files will be renamed.

  • Folder - One or more folders will be renamed.
Original name Text Yes (Empty)
  • SOURCE="c:\sourcefolder\file.txt"
  • SOURCE="c:\sourcefolder\*.txt"
  • SOURCE="c:\folder\*.txt|c:\folder\*.bak"
  • SOURCE="c:\foldername\subfoldername"
 Indicates the files or folders to rename. To specify multiple folder/file names, separate them with a pipe symbol (Example: c:\file.txt|c:\file.bak).
NOTE: Files with invalid paths are ignored at runtime.
New name Text Yes (Empty)
  • DEST="c:\destfolder\file.txt"
  • DEST="c:\destfolder\*.txt"
  • DEST="c:\destfolder\*.*"
  • DEST="c:\destfolder\"
 Indicates the destination folder and (optionally) the file name for the files being renamed. This can be a fully qualified path or a file name. Folders specified that do not exist will be automatically created at runtime.
Create and populate dataset with result Text No (Empty) RESULTDATASET="DatasetName" The name of a dataset to be created and populated with status regarding this operation. More information about the fields that this dataset creates are entered below under Datasets

File Options

Property Type Required Default Markup Description
Include Subfolders Yes/No No No SUBFOLDERS="YES" If selected, denotes that, if present, subfolders should be searched for files matching the mask specified in the Source parameter. If disabled (default value), subfolders are altogether ignored.
Preserve Folder Structure Yes/No No Yes KEEPFOLDERSTRUCT="NO" If selected (default value), subfolders found in the source folder will be created in the destination folder and source files will be moved into their respective folders rather than directly into the root of the target folder specified in the Destination parameter. If disabled, source files will be moved into the root of the target folder instead. This parameter is active only if the Include Subfolder parameter is selected.
Include Empty Subfolders Yes/No No No EMPTYFOLDERS="YES" If selected, subfolders found in the source folder will be created in the destination folder even if they do not contain any files. If disabled (default value), empty subfolders are ignored. This parameter is active only if the Include Subfolder parameter is selected.
Only Folder Structure Yes/No No No ONLYFOLDERSTRUCT="YES" If selected, subfolders found in the source folder will be created in the destination folder but no files will be moved. Enabling this option causes all other file-specific parameters to be ignored. This parameter is disabled by default and active only if the Include Subfolder parameter is selected.
Overwrite if Exist Yes/No No No OVERWRITE="YES" If selected, matching destination files will be overwritten. This parameter is disabled by default.
Only if Newer Yes/No No No ISNEWER="YES" If selected, only source files that are newer than those that match in the destination folder will overwrite existing files. Disabled by default. This parameter is active only if the Overwrite if Exist parameter is selected.
Only if Exist in Destination Yes/No No No ONLYIFEXIST="YES" If selected, only files that already exist in the destination will be moved from the source. All other files, regardless of whether they match the mask or other parameter settings will be bypassed. This parameter is disabled by default and is active only if the Overwrite if Exist parameter is selected.
Overwrite Read-Only Files Yes/No No No OVERWRITEREADONLY="YES" If selected, already existing files should be overwritten even if the file in the destination is marked with the read-only attribute. By default, read-only files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected.
Overwrite Hidden Files Yes/No No No OVERWRITEHIDDEN="YES" If selected, specifies that already existing files should be overwritten even if the file in the destination is marked with the hidden attribute. By default, hidden files are not overwritten. This parameter is active only if the Overwrite if Exist parameter is selected.
Turn Archive Attribute Off Yes/No No No ARCHIVETURNOFF="YES" If selected, specifies that the archive attribute of the source files should be switched OFF. The Windows archive attribute is generally used to track whether a file has been backed-up. Turning the source file's archive attribute off indicates to many backup programs that the file has already been backed-up. This parameter is disabled by default.
Exclude Mask Text No (Empty) EXCLUDE="*.txt" Causes this action to omit files matching the masks specified. File names or wildcard masks may be used. Multiple entries may be specified by separating them with a pipe symbol (|), for example: *.txt|*.bak
Regular expression Yes/No No No RE="YES" If selected, specifies that the value entered in the Exclude mask parameter will be interpreted as a regular expression. If disabled (default), the value will be interpreted as normal readable text.
Only if Newer Than Date No (Empty) ISNEWERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" If enabled, causes this action to only act on files that are newer than the date/time specified. If this parameter is left blank or disabled (default), file dates are ignored.

Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression option to allow entry of a date/time expression.
Only if Older Than Date No (Empty) ISOLDERTHAN="%DateSerial(2001,10,12) + TimeSerial(00,00,00)%" If enabled, causes this action to only act on files that are older than the date/time specified. If this parameter is left blank or disabled (default), file dates are ignored.

Click the Custom button to select from a list of pre-defined date parameters. Enable the Expression option to allow entry of a date/time expression.

File Filter

Property Type Required Default Markup Description
Attributes Text (Options) No (Empty)
  • ATTRFILTER="+R+A-H"
  • ATTRFILTER="-S" 
 This group of settings causes the action to filter which files are moved based on the attribute settings of the source files. In visual mode, a group of controls are provided to assist in the selection of this parameter. In markup mode, a single text item must be specified that contains the attributes of the files you wish to move.

Available Options:

  • R—Read-only: Specifying "+R" causes files with this attribute turned on to be included, "-R" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • A—Archive: Specifying "+A" causes files with this attribute turned on to be included, "-A" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • S—System: Specifying "+S" causes files with this attribute turned on to be included, "-S" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • H—Hidden: Specifying "+R" causes files with this attribute turned on to be included, "-H" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

  • C—Compression: Specifying "+C" causes files with this attribute turned on to be included, "-C" causes files with this attribute turned off to be included, not specifying the letter (default) causes this attribute to be ignored.

Description

Error Causes

On Error

Additional notes

Datasets

A dataset is a multiple column, multiple row container object. This activity creates and populates a dataset containing a specific set of fields. The table below describes these fields (assuming the dataset name assigned was theDataset).

Name Type Return Value
theDataset.Source Text The path and file name of the source folder/ file.
theDataset.Size Number The size of the folder/file (in kb).
theDataset.Destination Text The path and file name of the destination file.
theDataset.Result True/False Returns TRUE if result of activity is a success, otherwise, returns a FALSE.
theDataset.Message Text The textual information associated to the result.

Example

NOTE:
  • Copy and paste the sample AML code below directly into the Task Builder Steps Panel.
  • To successfully run the sample code, update parameters containing user credentials, files, file paths, or other information specific to the task to match your environment.

Description  

This sample task will demonstrate how Automate Desktop can rename a file name to its parent folder name. The ExtractFilePath() function is used to extract the path from a file name. ExtractFilePath returns the path part (including drive letter) from the file name. The path consists of all characters before the last directory separator character ('/' or '\'), including the directory separator itself. In case there is only a drive letter, that will be returned. ExtractFilePath can be used against a literal string (for example, %ExtractFilePath('c:\test1\test2\test3\test4.txt')%) or a variable (for example, %ExtractFilePath(AMTrigger.Filename)%).

Copy 
<AMVARIABLE NAME="var1" VALUE="C:\test1\test2\test3\test4.txt"></AMVARIABLE>
<AMVARIABLE NAME="var2">%ExtractFilePath(var1)%</AMVARIABLE>
<AMVARIABLE NAME="var3" VALUE="" />
<AMVARIABLE NAME="var4" VALUE="" />
<AMVARIABLE NAME="theIndex" VALUE="" />
<AMTEXT ACTIVITY="trim" TEXT="%var2%" RESULTVARIABLE="var3" ACTION="remove_end" REMOVE="user" CHARACTERS="\" />
<AMTEXT TEXT="%var3%" FIND="\" TOTALMATCHESVARIABLE="var4" />
<AMTEXT TEXT="%var3%" FIND="\" RESULTVARIABLE="theIndex" INDEX="%var4%" />
<AMTEXT ACTIVITY="get_substring" TEXT="%var3%" RESULTVARIABLE="var4" STARTPOSITION="%theIndex + 1%" />
<AMFILESYSTEM ACTIVITY="rename" SOURCE="%var1%" DEST="%var2&amp;var4%.txt" />