Creating FileOps plugin procedures

AddTextToFile

Add text to a file

Input parameters

Table 1. AddTextToFile input parameters
Parameter	Description
Path	Required. Path to the file to write to.
Append mode	Required. If selected, the new text is appended to the file rather than replacing it.
Add new line to the end	Required. If checked, text is added as a new line at the end of the file.
Content	Required. Content to write in the file.

ChangeOwnershipOrPermissions

Changes the ownership and/or permissions of files and folders.

This procedure is not supported for Windows OS.

Input parameters

Table 2. ChangeOwnershipOrPermissions input parameters
Parameter	Description
Path	Required. Path to the file/directory.
Owner	Name of a valid user.
Mode	New mode to apply, such as `0666` (read and write all).
Recursive	If checked, applies mode/owner recursively to directories.
Verbose mode	Required. If checked, displays additional information about the process.

CheckFilePermissions

Checks if a specific user has permissions on a file.

This procedure is not implemented for Windows OS.

Input parameters

Table 3. CheckFilePermissions input parameters
Parameter	Description
Username	Required. Name of the user to validate.
Path	Required. Path to the file to validate.
Read	Required. If selected, validates that the user has read permissions for the file.
Write	If selected, validates that the user has write permissions for the file.
Execute	If selected, validates that the user has execute permissions for the file.

CompareFilesChecksums

Compare the checksum of two files.

Input parameters

Table 4. CompareFilesChecksums input parameters
Parameter	Description
First file	Required. Path to the first file to compare.
Second file	Required. Path to the second file to compare.

Copy

Copy a source file/directory to a destination location.

Input parameters

Table 5. Copy input parameters
Parameter	Description
Source	Required. Directory or file to copy. Path may end in a glob pattern to copy a subset of files to the destination. For more information, refer to Copying as the destination path versus into the destination path.
Destination	Required. Path to copy source file/directory to.
Replace destination if it exists	If selected and the destination is a pre-existing directory, the file/directory is recursively cleared prior to copying sources into it. If not set and the destination is a pre-existing file, the step returns an error.

Create Zip File

Creates a .zip file from a directory or file.

Input parameters

Table 6. Create Zip File input parameters
Parameter	Description
Source path	Required. Directory or file to copy. Path may end in a glob pattern to copy a subset of files to the destination. For more information, refer to Copying as the destination path versus into the destination path.
Zip file	Required. Name for newly created .zip file. This must be a new name; existing .zip files cannot be overwritten.

CreateDirectory

Creates a new directory.

Input parameters

Table 7. CreateDirectory input parameters
Parameter	Description
Path	Required. Path of the directory to create.

CreateEmptyFile

Creates a new empty file.

Input parameters

Table 8. CreateEmptyFile input parameters
Parameter	Description
Name	Required. Path of the file to create.
Permission mode	Permission to apply after creating the file, such as `0666` (read and write all).

CreateSymbolicLink

Creates a symbolic link between target and destination.

Input parameters

Table 9. CreateSymbolicLink input parameters
Parameter	Description
Target	Required. Target to link.
Destination	Required. Location to create the symbolic link.

Crypt

Encrypts and decrypts a file using the Blowfish algorithm.

Input parameters

Table 10. Crypt input parameters
Parameter	Description
File	Required. Path to the file to encrypt or decrypt.
Action	Required. Encrypt or decrypt the file.
Key	Required. A secret key.
BackUp file	If checked, a copy of the file is created before encrypting or decrypting it.

DeleteDirectory

Deletes an existing directory.

Input parameters

Table 11. DeleteDirectory input parameters

Parameter

Description

Path

Required. Path to the directory to delete.

Recursive

Required. If selected, the directory and all content is recursively deleted.

This action cannot be undone.

DeleteFile

Deletes a file.

Input parameters

Table 12. DeleteFile input parameters

Parameter

Description

Path

Required. Path to the file to delete.

This action cannot be undone.

DescribeFile

Prints basic and technical information for a given file.

Input parameters

Table 13. DescribeFile input parameters
Parameter	Description
Path	Required. Path to the file to describe.

DiffFiles

Performs a file diff of two files in the selected format.

Input parameters

Table 14. DiffFiles input parameters
Parameter	Description
First file	Required. Path to the first file to diff.
Second file	Required. Path to the second file to diff.
Display format	Required. Select the result format.

DiffFolders

Performs a diff of two directories.

Input parameters

Table 15. DiffFolders input parameters
Parameter	Description
First directory	Required. Path to the first folder to diff.
Second directory	Required. Path to the second folder to diff.
Suppress identical file messages	Required. If selected, messages about identical files are suppressed.

DirectoryExists

Verify if a directory exists.

Input parameters

Table 16. DirectoryExists input parameters
Parameter	Description
Path	Required. Directory path to verify.
Procedure results handling strategy	The strategy of procedure results handling. If set to Default, the procedure fails if the directory does not exist. If set to Property, the procedure does not fail, and the appropriate output parameters/properties are set.
Output propertySheet path	Creates a `PropertySheet` after the procedure is finished. The procedure creates two properties: `Exists` and `Path`. The `Exists` property is a `true`/`false` boolean. The `Path` property contains the entity path from the Path parameter.

FileExists

Verify if a file exists or not.

Input parameters

Table 17. FileExists input parameters
Parameter	Description
Path	Required. Path of the file to check.
Procedure results handling strategy	The strategy of procedure results handling. If set to Default, the procedure fails if the directory does not exist. If set to Property, the procedure does not fail, and the appropriate output parameters/properties are set.
Output propertySheet path	Creates a `PropertySheet` after the procedure is finished. The procedure creates two properties: `Exists` and `Path`. The `Exists` property is a `true`/`false` boolean. The `Path` property contains the entity path from the Path parameter.

Generate Checksum

Generate a SHA1 or MD5 checksum for a file.

Input parameters

Table 18. Generate Checksum input parameters
Parameter	Description
File	Required. File to compute a checksum for.
Checksum type	Required. Use `SHA1` or `MD5`.
Result property	Required. Name of the property to store the resulting checksum.

ListFiles

Lists all files in a directory.

Input parameters

Table 19. ListFiles input parameters
Parameter	Description
Target directory	Required. Directory path with files to list.
Filter	Filter to apply when listing files. For example, `*.txt`.
Separator	A custom separator for files in the folder.

Move

Move a source file/directory.

Input parameters

Table 20. Move input parameters
Parameter	Description
Source	Required. Path to the file/directory to move. Path may end in a glob pattern to move a subset of files to the destination.
Destination	Required. Path to move source file/directory to.
Replace destination if it exists	If set, and if the destination is a pre-existing directory, the destination is recursively cleared prior to moving sources into it. If not set, and if the destination is a pre-existing file, the step returns an error.

Remote Copy - Native

Copy a file/directory from one CloudBees CD/RO resource to another, using the CloudBees CD/RO built-in getfiles/putfiles mechanism.

Ensure the Stomp port, by default 61613, is opened on the CloudBees CD/RO server. This port must be opened bi-directionally to transfer files to and from the server. For more details, refer to Configuring Stomp for Preflight and EC-FileOps file transfers.

Input parameters

Table 21. Remote Copy - Native input parameters
Parameter	Description
Source resource	Required. Resource to copy file/directory from.
Source workspace	Workspace on the source resource containing the file/directory to transfer. If the file/directory is outside of a workspace, this workspace is used to store temporary files, and it is recommended this workspace refer to a local disk directory on the resource.
Source path	Required. Directory or file to copy. Path may end in a glob pattern to copy a subset of files to the destination. For more information, refer to Copying as the destination path versus into the destination path.
Destination resource	Required. Resource to copy the file/directory to.
Destination workspace	Workspace on the destination resource to copy the file/directory. If the destination location is outside of a workspace, this workspace is used to store temporary files, and it is recommended this workspace refer to a local disk directory on the resource.
Destination path	Required. Location on destination resource to copy file/directory to.

Remote Copy - SCP

This procedure copies a file or directory between a CloudBees CD/RO resource and some other machine (possibly a different CloudBees CD/RO agent) using the SCP protocol. Unlike other copy steps, this remote copy step does not generally create intermediate directories in the destination path if needed.

If the destination is a pre-existing file, it will be overwritten. If the destination is a pre-existing directory, pre-existing files/directories in it will be overwritten if there are corresponding elements in the source.

For plugin v3.1.0 and earlier, when configuring the plugin with a CloudBees CD/RO project credentials, if you attempt to use the Credential Browse button, the process will freeze.

For plugin v3.1.0 and earlier, you must manually enter your CloudBees CD/RO project credential path in the Credential field. Use the format:

/projects/<your-project-name>/credentials/<your-credential-name>▼

CloudBees CD/RO resource ⇒ Non-CloudBees CD/RO host

In this configuration, the SCP operation is driven by a step on a CloudBees CD/RO resource that establishes an SSH connection with an arbitrary host and uploads files or directories to that host.

Parameter

Description

Source resource

Required. Name of the resource to copy file(s) from.

Source workspace

Required. Name of workspace on source resource from which file(s) are to be copied.

Source path

Required. Path of source file/directory to copy. If relative, this path is evaluated relative to the source workspace. Relative or absolute path for the files or directories to upload. A relative path is processed relative to the Source Workspace. This path may end in a glob pattern to copy multiple files from a source directory to the destination. For more information, refer to Copying as the destination path versus into the destination path.

Destination host

Required. Name/IP of the destination host to copy the file(s) to.

Credential

Required. Property path to credential for authenticating with the SSH server running on the source machine.

If you are using v3.10.0 or earlier, refer to Known Issues for how to enter your credentials.

Destination path

Required. Destination path to copy the file/directory. If relative, this path is evaluated relative to the destination workspace.

Debug level

Debug logging level to use for this step.

Non-CloudBees CD/RO host ⇒ CloudBees CD/RO resource

In this configuration, SCP operation is driven by a step on a CloudBees CD/RO resource that establishes an SSH connection with an arbitrary host and downloads files or directories from that host.

Parameter

Description

Source host

Required. Name/IP of the host to copy the file(s) from.

Source path

Required. Path of source file/directory to copy. If relative, this path is evaluated relative to the source workspace. For more information, refer to Copying as the destination path versus into the destination path.

Destination resource

Required. Name of the resource to copy the file(s) to.

Destination workspace

Required. Name of the workspace on the destination resource to copy the file(s) to.

Credential

Required. Property path to credential for authenticating with the SSH server running on the source machine.

If you are using v3.10.0 or earlier, refer to Known Issues for how to enter your credentials.

Destination path

Required. Destination path to copy the file/directory. If relative, this path is evaluated relative to the destination workspace.

Debug level

Debug logging level to use for this step.

CloudBees CD/RO resource ⇒ CloudBees CD/RO resource

In this configuration, the SCP operation is driven by a step on a CloudBees CD/RO resource that establishes an SSH connection with another CloudBees CD/RO resource and either downloads or uploads files or directories from or to that resource. This configuration is particularly useful for copying files between different workspaces through the resources that can access those workspaces.

Parameter	Description
End-point that has an SSH server	Required. Select the endpoint with the SSH server for the SCP operation.
SSH server machine is a Windows host	Required if using a Windows host. Check if SSH server end-point is a Windows host. The resource that contains the source files or directories.
Source resource:	Required. Name of the resource to copy file(s) from.
Source workspace:	Required. Name of workspace on source resource from which file(s) are to be copied.
Source path:	Required. Path of source file/directory to copy. If relative, this path is evaluated relative to the source workspace. For more information, refer to Copying as the destination path versus into the destination path.
Destination resource:	Required. Name of the resource to copy the file(s) to.
Destination workspace:	Required. Name of the workspace on the destination resource to copy the file(s) to.
Destination path:	Required. Destination path to copy the file/directory. If relative, this path is evaluated relative to the destination workspace.
Debug level:	Debug logging level to use for this step.

Parameter

Description

End-point that has an SSH server

Required. Select the endpoint with the SSH server for the SCP operation.

SSH server machine is a Windows host

Required if using a Windows host. Check if SSH server end-point is a Windows host. The resource that contains the source files or directories.

Source resource:

Required. Name of the resource to copy file(s) from.

Source workspace:

Required. Name of workspace on source resource from which file(s) are to be copied.

Source path:

Required. Path of source file/directory to copy. If relative, this path is evaluated relative to the source workspace. For more information, refer to Copying as the destination path versus into the destination path.

Destination resource:

Required. Name of the resource to copy the file(s) to.

Destination workspace:

Required. Name of the workspace on the destination resource to copy the file(s) to.

Destination path:

Required. Destination path to copy the file/directory. If relative, this path is evaluated relative to the destination workspace.

Debug level:

Debug logging level to use for this step.

RenameFile

Renames a file.

Input parameters

Table 22. RenameFile input parameters
Parameter	Description
Old name	Required. Path to the file you want to rename.
New name	Required. New name for the file.

SaveFileContent

Reads the contents of a file and stores it as a property.

Input parameters

Table 23. SaveFileContent input parameters
Parameter	Description
Path	Required. File path to read.
Content (output property path)	Required. Property name used to store the file content.

SyncFolders

Perform a folder diff of two folders and syncs their content.

Input parameters

Table 24. SyncFolders input parameters

Parameter

Description

First directory

Required. First folder to sync.

Second directory

Required. Second folder to sync.

Sync rule

Required. Rule to apply when synchronising folders:

Keep first: If files in the First directory contain newer changes (more recent timestamp), changes are applied to the Second directory.
Keep second: If files in the Second directory contain newer changes (more recent timestamp), changes are applied to the First directory.
Mirror mode: If files in the First directory contain newer changes (more recent timestamp), they are applied to the Second directory. Any files that are present in the First directory, but are not present in the Second directory, are copied to the Second directory. No changes from the Second directory are applied to the First directory.

To mirror all files between the directories, copy the step, and invert the First directory and Second directory entries from the previous step to ensure all files are synced between them.

Dry run

If selected, the copy/delete operations are treated as a dry run and only print the results.

Verbose mode

If checked, additional information is printed about the sync process.

TruncateFile

Truncates a file to a specified length.

Input parameters

Table 25. TruncateFile input parameters
Parameter	Description
Path	Required. Path to the file to truncate.
Length	Required. Adjust the file size, in bytes. Default is `0`.

Unzip File

Unzip a .zip file to a directory.

Input parameters

Table 26. Unzip File input parameters
Parameter	Description
Zip file	Required. Zip file to extract.
Destination directory	Required. Directory to extract into. If the directory does not exist, it is created.

UpdateLastTouch

Update the last accessed and modified date of a file.

Input parameters

Table 27. UpdateLastTouch input parameters
Parameter	Description
Path	Required. Path to the file to `touch`.
Year	Required. The year to set for the file.
Month	Required. The month to set for the file.
Day	Required. The day to set for the file.
Hour	The hour to set for the file.
Minute	The minute to set for the file.
Second	The second to set for the file.
TimeZone	Required. A valid timezone for the date. For example, `America/Costa_Rica` or `America/Chicago`.

Validate Checksum

Validate if the file has the provided MD5 or SHA1 checksum.

Input parameters

Table 28. Validate Checksum input parameters
Parameter	Description
File	Required. File to validate.
Checksum type	Required. Use `SHA-1` or `MD5`.
Expected checksum	Required. Expected file checksum.

Copying as the destination path versus into the destination path

As stated in the plugin procedures, source paths may end in glob patterns if you are copying multiple files from a source directory to the destination. Depending on whether the destination exists, the source may be copied as the destination or into the destination.

Refer to the following table for examples illustrating step behavior in various circumstances. This example assumes resource-to-resource for simplicity, although it also applies to configurations using absolute paths instead of relative paths.

Source Path Destination Path Behavior

Source Path	Destination Path	Behavior
/var/tmp/simple.txt	simpleNew.txt	`simpleNew.txt` is created in the destination workspace with `/var/tmp/simple.txt` contents.
/var/tmp/simple.txt	preexistFile.txt	`preexistFile.txt` contents are replaced with the contents from `/var/tmp/simple.txt`.
/var/tmp	preexistDir	`preexistDir` contains a `tmp` subdirectory containing the contents of `/var/tmp`. If `preexistDir` was originally non-empty, those directory elements remain.
/var/tmp	newDir	`newDir` is created and contains the contents of `/var/tmp`.
/var/tmp/*	newDir2	`newDir2` is created and contains the contents of `/var/tmp`.
/var/tmp/s*	newDir2	`newDir2` is created and contains a copy of each file or directory in `/var/tmp` that begins with `s`.

/var/tmp/simple.txt

simpleNew.txt

simpleNew.txt is created in the destination workspace with /var/tmp/simple.txt contents.

/var/tmp/simple.txt

preexistFile.txt

preexistFile.txt contents are replaced with the contents from /var/tmp/simple.txt.

/var/tmp

preexistDir

preexistDir contains a tmp subdirectory containing the contents of /var/tmp. If preexistDir was originally non-empty, those directory elements remain.

/var/tmp

newDir

newDir is created and contains the contents of /var/tmp.

/var/tmp/*

newDir2

newDir2 is created and contains the contents of /var/tmp.

/var/tmp/s*

newDir2

newDir2 is created and contains a copy of each file or directory in /var/tmp that begins with s.