File Functions¶

File functions allow scripts to manipulate files on agents, available through sources, and written to targets.

ArchiveFile¶

Declaration¶

void ArchiveFile(string sourceId, string targetId[, bool deleteSource])

Syntax¶

ArchiveFile(<sourceId>, <targetId>[, <deleteSource>])

Required Parameters¶

• sourceId: File-type source in the current project
• targetId: File-type target in the current project

Optional Parameters¶

• deleteSource: Boolean flag (default false) indicating if the source is to be deleted after successfully writing to the target

Description¶

Reads a file from a file-type source and writes it to a file-type target. This function combines the ReadFile and WriteFilefunctions, automatically performs FlushFile, and provides an option to delete the source file.

The file-type source and file-type target used in this function call must be defined as a source and target, respectively, in the current project. See the instructions on inserting project items.

As only one file is archived, it is recommended that the source be created to only return a single file. If multiple files are returned, only the first will be used.

Like theWriteFilefunction, this function will not overwrite an existing file on the target.

If the ArchiveFile function fails, the operation does not fail. A script will abort, a warning added to the operation log, and the operation will continue.

Archiving versus Copying¶

• If deleteSource is true, the file is archived (in other words, moved) from the source to the target and removed from the source.
• If deleteSource is false, the file is copied from the source to the target and remains on the source.

Examples¶

// Retrieve list of files from a source
localFiles = FileList("<TAG>Sources/Local File Source</TAG>");

// Create a global archive filename
$archiveFilename = "archive.[date]-[time]." + localFiles[0];

// Archive (moves) a file, using [archiveFilename] in the target filename(s) field
ArchiveFile("<TAG>Sources/Local File Source</TAG>",
    "<TAG>Targets/FTP Target</TAG>", true);

// Copies a file, using [archiveFilename] in the target filename(s) field
ArchiveFile("<TAG>Sources/Local File Source</TAG>",
    "<TAG>Targets/FTP Target</TAG>", false);

DeleteFile¶

Declaration¶

int DeleteFile(string sourceId[, string fileFilter])

Syntax¶

DeleteFile(<sourceId>[, <fileFilter>])

Required Parameters¶

• sourceId: File-type source in the current project

Optional Parameters¶

• fileFilter: File filter or Filename to override the source definition

Description¶

Deletes a file from the specified source.

The file-type source used in this function call must be defined as a source in the current project. See the instructions on inserting project items.

If the source filter selects more than one file, an error will be thrown. To delete multiple files, use the DeleteFilesfunction instead.

The method returns an integer of either 0 or 1: it returns 1 if the file was deleted; 0 if the file could not be found.

The second parameter, fileFilter, is optional and can be used to override the file filter used in the source definition. A filename can be used. Alternatively, a global variable can be used to override the file filter in the source definition. Global variables are referenced as [de_name] in the source definition.

Examples¶

// Delete the file "ExampleFile.txt" from the "File Share Source"
DeleteFile("<TAG>Sources/File Share Source</TAG>", "ExampleFile.txt");

DeleteFiles¶

Declaration¶

int DeleteFiles(string sourceId[, string fileFilter])

Syntax¶

DeleteFiles(<sourceId>[, <fileFilter>])

Required Parameters¶

• sourceId: File-type source in the current project

Optional Parameters¶

• fileFilter: File filter or filename to override the source definition

Description¶

Deletes one or more files from the specified source.

The file-type source used in this function call must be defined as a source in the current project. See the instructions on inserting project items.

This method will delete multiple files, if any are found, based on the file filter of the source definition. An integer is returned specifying how many files were deleted. Returning 0 means no files were found matching the file filter.

If a specified path in the source cannot be found, an error will be thrown. If that is a possibility, the function should be wrapped in an Eval function.

To delete a single file, use the DeleteFile function instead.

The second parameter, fileFilter, is optional and can be used to override the file filter used in the source definition. A filename can be used. Alternatively, a global variable can be used to override the file filter in the source definition. Global variables are referenced as [de_name] in the source definition.

Examples¶

// Delete all text (".txt") files in the source "File Source"
DeleteFiles("<TAG>Sources/File Source</TAG>","*.txt");

DirList¶

Declaration¶

array DirList(string sourceId[, string path, string fileFilter])

Syntax¶

DirList(<sourceId>[, <path>, <fileFilter>])

Required Parameters¶

• sourceId: File-type source in the current project

Optional Parameters¶

• path: File path to override the source definition
• fileFilter: File filter or filename to override the source definition

Description¶

Returns a list of directories contained in a source, optionally specifying a path and a filter to restrict the results.

This method returns an array containing the directory names.

The file-type source used in this function call must be defined as a source in the current project. See the instructions on inserting project items.

The parameter fileFilter is optional and can be used to override the file filter used in the source definition. A filename can be used. Alternatively, a global variable can be used to override the file filter in the source definition. Global variables are referenced as [de_name] in the source definition.

Examples¶

// Returns the count of the list of all the text files (".txt")
// in the "example" folder of the source "File Share Source"
Length(DirList("<TAG>Sources/File Share Source</TAG>",
    "\\\\server\\example","*.txt"));

FileList¶

Declaration¶

array FileList(string sourceId[, string path, string fileFilter])

Syntax¶

FileList(<sourceId>[, <path>, <fileFilter>])

Required Parameters¶

• sourceId: File-type source in the current project

Optional Parameters¶

• path: File path to override the source definition
• fileFilter: File filter or filename to override the source definition

Description¶

Returns a list of filenames contained in a source. This will be the same list of files received when a file-type source's connection is tested, unless a file filter is specified to override the filter specified in the activity configuration.

The file-type source used in this function call must be defined as a source in the current project. See the instructions on inserting project items.

The parameter path is optional and can be used to override the path used in the source definition.

The parameter fileFilter is optional and can be used to override the file filter used in the source definition. A filename can be used. Alternatively, a global variable can be used to override the file filter in the source definition. Global variables are referenced as [de_name] in the source definition.

The method returns an array containing the filenames matching either the file filter of the source or the overridden source.

Examples¶

// Returns the count of the list of
// all the files in the source "File Share Source"
Length(FileList("<TAG>Sources/File Share Source</TAG>"));

FlushAllFiles¶

Declaration¶

void FlushAllFiles([string targetId])

Syntax¶

FlushAllFiles([<targetId>])

Optional Parameters¶

• targetId: File-type target in the current project

Description¶

Persists data written to a file buffer with WriteFile().

The file-type target used in this function call must be defined as a target in the current project. See the instructions on inserting project items.

If FlushAllFiles are called with a targetId as an argument, all files written using that target will be flushed (see the FlushFile function). If FlushAllFiles is called without an argument, all files written using WriteFile to any targets will be persisted to their respective targets.

See also the FlushFiles function.

Examples¶

// Write "contents1" to the file specified by the FTP target
WriteFile("<TAG>Targets/FTP Target</TAG>", contents1);

// Write "contents2" to a file "copy.txt",
// overriding that specified by the FTP target
WriteFile("<TAG>Targets/FTP Target</TAG>", contents2, "copy.txt");

// Flush both files to the target
FlushAllFiles("<TAG>Targets/FTP Target</TAG>");

FlushFile¶

Declaration¶

void FlushFile(string targetId[, string filename])

Syntax¶

FlushFile(<targetId>[, <filename>])

Required Parameters¶

• targetId: File-type target in the current project

Optional Parameters¶

• filename: Filename to override the target definition

Description¶

Persists data written to a file buffer with WriteFile. When FlushFile is called, the current contents of the buffer is written to the target and the local buffer is discarded.

The file-type target used in this function call must be defined as a target in the current project. See the instructions on inserting project items.

The optional parameter, filename, can be used to override the filename used in the target definition if it was similarly overridden in the call to the WriteFile function. Flushing a file that has never been written to has no effect.

Alternatively, a global variable can be used to override the filename in the target definition. Global variables are referenced as [de_name] in the target definition. If an override filename is used, each buffer is flushed separately for each unique name.

See also the FlushAllFiles function.

Examples¶

// Writing the variable "contents" to a target
WriteFile("<TAG>Targets/FTP Target</TAG>", contents);

// Flushing (actually writing) to the target
FlushFile("<TAG>Targets/FTP Target</TAG>");

// Write another file (overriding the filename in the target)
WriteFile("<TAG>Targets/FTP Target</TAG>", contents, "test.txt");

// Flushing the "test.txt" file explicitly
FlushFile("<TAG>Targets/FTP Target</TAG>", "test.txt");

ReadFile¶

Declaration¶

string ReadFile(string sourceId[, string fileFilter])

Syntax¶

ReadFile(<sourceId>[, <fileFilter>])

Required Parameters¶

• sourceId: File-type source in the current project

Optional Parameters¶

• fileFilter: File filter or filename to override the source definition

Description¶

Reads the contents of a file from a source.

The file-type source used in this function call must be defined as a source in the current project. See the instructions on inserting project items.

The method returns the contents of the file pointed to by the source. If the source filter selects more than one file, the first one will be used. It is recommended to specify a source that uniquely identifies a single file.

The parameter fileFilter is optional and can be used to override the file filter used in the source definition. A filename can be used. Alternatively, a global variable can be used to override the file filter in the source definition. Global variables are referenced as [de_name] in the source definition.

As of Harmony version 8.20, if the ReadFile() function fails, the operation does not fail. A script will abort, a warning added to the operation log, and the operation will continue.

This method can be used to read data from an HTTP source. In that case, all Jitterbit $jitterbit.source.http.* variables will be populated.

Examples¶

$fileContents = ReadFile("<TAG>Sources/File Share Source</TAG>")

WriteFile¶

Declaration¶

void WriteFile(string targetId, type fileContents[, string filename])

Syntax¶

WriteFile(<targetId>, <fileContents>[, <filename>])

Required Parameters¶

• targetId: File-type target in the current project

Optional Parameters¶

• fileContents: Data to be written to the file
• filename: Filename to override the target definition

Description¶

Writes the fileContents to the file-type target specified by targetId. If fileContents is of type binary, the binary data is written to the file. In all other cases, a string representation of the data is written.

The file-type target used in this function call must be defined as a target in the current project. See the instructions on inserting project items.

The third parameter, filename, is optional and can be used to override the filename used in the target. Alternatively, a global variable can be used to override the filename in the target definition. Global variables are referenced as [de_name] in the target definition.

This method can also be used to write/post data to an HTTP target. In that case, $jitterbit.target.http.* variables will be populated.

As of Harmony version 8.20, if the WriteFile() function fails, the operation does not fail. A script will abort, a warning added to the operation log, and the operation will continue.

Buffering and Flushing¶

The file contents are buffered locally until either FlushFile or FlushAllFiles is called on the target or the transformation finishes successfully. Calling WriteFile several times without calling FlushFile will append data to the current buffer and everything will be written to the actual file-type target only when it is flushed. A file buffer is uniquely identified by the target (and potentially the filename); for example, the same target can be used to write to different files in the same directory by specifying a filename and each file buffer will be separate.

Files are not actually written to the target in a test transformation unless FlushFile or FlushAllFiles is called. If a transformation is run in an operation or as part of a test operation, the file will be written when either the transformation finishes successfully or when FlushFile or FlushAllFiles is called in the script.

See also the FlushAllFiles and FlushFiles functions.

Examples¶

// Write "contents" to a file in a target
WriteFile("<TAG>Targets/FTP Target</TAG>", contents);

// Use the filename "test.txt" instead of
// what is defined in the target
WriteFile("<TAG>Targets/FTP Target</TAG>", contents, "test.txt");