File functions in Jitterbit Integration Studio

File functions allow scripts to manipulate files on agents, available through configured file-based activities that can be used as sources or targets.

ArchiveFile

Declaration

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

Syntax

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

Required parameters

• sourceId: A string reference path to an activity associated with a file-type endpoint in the current project**
  
• targetId:** A string reference path to an activity associated with a file-type endpoint 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 activity and writes it to a file-type target activity. This function combines the ReadFile and WriteFile functions, automatically performs FlushFile, and provides an option to delete the source file.

The source and target used in this function call must be defined as activities associated with file-type endpoints in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

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 the WriteFile function, 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.

Archive versus copy

• 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>activity:localstorage/Local Storage Endpoint/localstorage_read/CSV Files</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>activity:localstorage/Local Storage Endpoint/localstorage_read/CSV Files</TAG>",
    "<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>", true);

// Copies a file, using [archiveFilename] in the target filename(s) field
ArchiveFile("<TAG>activity:localstorage/Local Storage Endpoint/localstorage_read/CSV Files</TAG>",
    "<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>", false);

DeleteFile

Declaration

int DeleteFile(string sourceId[, string fileFilter])

Syntax

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

Required parameters

• sourceId: A string reference path to an activity associated with a file-type endpoint in the current project

Optional parameters

• fileFilter: File filter or filename to override the activity configuration

Description

Deletes a file from the specified source.

The source used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

If the source filter selects more than one file, an error will be thrown. To delete multiple files, use the DeleteFiles function 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 activity configuration. A filename can be used. Alternatively, a global variable can be used to override the file filter in the activity configuration. Global variables are referenced as [de_name] in the activity configuration.

Examples

// Delete the file "ExampleFile.txt" from the "CSV Files"
DeleteFile("<TAG>activity:localstorage/Local Storage Endpoint/localstorage_read/CSV Files</TAG>",
    "ExampleFile.txt");

DeleteFiles

Declaration

int DeleteFiles(string sourceId[, string fileFilter])

Syntax

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

Required parameters

• sourceId: A string reference path to an activity associated with a file-type endpoint in the current project

Optional parameters

• fileFilter: File filter or filename to override the activity configuration

Description

Deletes one or more files from the specified source.

The source used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

This method will delete multiple files, if any are found, based on the file filter of the activity configuration. 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 activity configuration. A filename can be used. Alternatively, a global variable can be used to override the file filter in the activity configuration. Global variables are referenced as [de_name] in the activity configuration.

Examples

// Delete all text (".txt") files in the "FTP Files"
DeleteFiles("<TAG>activity:ftp/FTP Endpoint/ftp_read/FTP Files</TAG>", "*.txt");

DirList

Declaration

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

Syntax

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

Required parameters

• sourceId: A string reference path to an activity associated with a file-type endpoint in the current project

Optional parameters

• path: File path to override the activity configuration**
  
• fileFilter:** File filter or filename to override the activity configuration

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 source used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

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

Examples

// Returns the count of the list of all the text
// files (".txt") in the "example" folder of the
// File Share Read "File Share"
Length(DirList("<TAG>activity:fileshare/File Share Endpoint/fileshare_read/File Share</TAG>",
        "\\\\server\\example","*.txt"));

FileList

Declaration

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

Syntax

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

Required parameters

• sourceId: A string reference path to an activity associated with a file-type endpoint in the current project

Optional parameters

• path: File path to override the activity configuration
• fileFilter: File filter or filename to override the activity configuration

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 source used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

The parameter path is optional and can be used to override the path used in the activity configuration.

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

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

Examples

// Returns the count of the list of all the
// files in the FTP endpoint "FTP Files"
Length(FileList("<TAG>activity:ftp/FTP Endpoint/ftp_read/FTP Files</TAG>"));

FlushAllFiles

Declaration

void FlushAllFiles([string targetId])

Syntax

FlushAllFiles([<targetId>])

Optional parameters

• targetId: A string reference path to an activity associated with a file-type endpoint in the current project

Description

Persists data written to a file buffer with WriteFile.

The target used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

If FlushAllFiles is 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 activities used as targets will be persisted to their respective targets.

See also the FlushFiles function.

Examples

// Write the value of "contents1" to the file specified by
// the FTP Write activity "FTP Files"
WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>",
    contents1);

// Write  the value of "contents2" to a file "copy.txt", overriding
// that specified by the FTP Write activity "FTP Files"
WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>",
    contents2, "copy.txt");

// Flush both files to the FTP Write activity "FTP Files"
FlushAllFiles("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>");

FlushFile

Declaration

void FlushFile(string targetId[, string filename])

Syntax

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

Required parameters

• targetId: A string reference path to an activity associated with a file-type endpoint in the current project

Optional parameters

• filename: Filename to override the activity configuration

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 target used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

The optional parameter, filename, can be used to override the filename used in the activity configuration 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 activity configuration. Global variables are referenced as [de_name] in the activity configuration. If an override filename is used, each buffer is flushed separately for each unique name.

See also the FlushAllFiles function.

Examples

// Write the variable "contents" to the file specified by
// the FTP Write activity "FTP Files"
WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>",
    contents);

// Flushing (actually writing) to the activity
FlushFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>");

// Write to another file (overriding the filename in the target)
WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>",
    contents, "test.txt");

// Flushing the "test.txt" file explicitly
FlushFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>",
    "test.txt");

ReadFile

Declaration

string ReadFile(string sourceId[, string fileFilter])

Syntax

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

Required parameters

• sourceId: A string reference path to an activity associated with a file-type endpoint in the current project

Optional parameters

• fileFilter: File filter or filename to override the activity configuration

Description

Reads the contents of a file from a source.

The source used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

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 activity configuration. A filename can be used. Alternatively, a global variable can be used to override the file filter in the activity configuration. Global variables are referenced as [de_name] in the activity configuration.

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>activity:ftp/FTP Endpoint/ftp_read/FTP Files</TAG>")

WriteFile

Declaration

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

Syntax

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

Required parameters

• targetId: A string reference path to an activity associated with a file-type endpoint in the current project

Optional parameters

• fileContents: Data to be written to the file
• filename: Filename to override the activity configuration

Description

Writes the fileContents to the 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 target used in this function call must be defined as an activity associated with a file-type endpoint in the current project. These include configured File Share, FTP, HTTP, Local Storage, and Temporary Storage activities. For more information, see the instructions on inserting endpoints under the Endpoints section in Jitterbit Script.

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

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

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.

Buffer and flush

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 an activity
WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>", contents);

// Use the filename "test.txt" instead of
// what is defined in an activity
WriteFile("<TAG>activity:ftp/FTP Endpoint/ftp_write/FTP Files</TAG>", contents, "test.txt");