ai.sftp
The article describes the ai.sftp namespace and the associated methods to create a client, perform basic client operations, upload and download files with the file Reader and Writer objects.
The ai.sftp namespace allows a user to upload and download files to an SFTP server. It also allows uploading and downloading encrypted files letting you encrypt and decrypt them with PGP.
Create a Client
ai.sftp.createClient
You can create an SFTP instance with the createClient() method and initiate all operations with the SFTP server. This function takes the name of the SFTP connection string configured for the script as a parameter and returns a client instance object.
| Method | Parameters | Return type | Description |
|---|---|---|---|
| createClient(sftpConnection) |
sftpConnection : String Name of your SFTP Connection |
Object | Creates an SFTP Client |
Usage
const client = ai.sftp.createClient('mySftpConnectionSetting');
Basic Client Operations
You can perform the following operations on the client instance object returned from the ai.createClient method.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| isConnected() | Boolean | Returns True if the SFTP client is connected; False otherwise. | |
| disconnect() | Logs out and closes the client session with the server. Any further operations called on the client will result in an exception being thrown. | ||
| delete(fileName) | fileName : String Name of the file to be deleted |
Deletes the specified file |
|
| rename (renameFrom, renameTo) |
renameFrom : String Original Name of the file renameTo : String New name of the file |
Renames the specified file |
|
|
createdirectory(directoryName) |
Name: String Relative path of the new directory |
Creates a directory on the server. | |
| changeDirectory(newLocation) |
newLocation : String Relative path of the new location on the server |
String | Changes the current working directory on the server. This operation will return the current working directory |
| getCurrentDirectory() | String | Get the current working directory |
|
| getFileSizeBytes(fileName) | fileName : String File name for the file size fetched |
Number | Returns the size of the specified file in bytes |
| listCurrentDirectory() | List |
Returns a list of all files and directories in the current working directory. |
Download a File
Use the following client methods to download files from the server.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| downloadFile(fileName) |
fileName: String Name of the file to download |
Object | Downloads the file and returns a reader to read through the file line by line. |
| downloadEncryptedFile(fileName, encryptionSettingName) |
fileName : String Relative path of the file to download encryptionSettingName : String Name of your encryption setting from the Credentials area in Design Integrations. |
Object | Downloads the file, decrypts it using the specified encryption setting and returns a reader to read through the file line by line. |
| downloadAndVerifyEncryptedFile(fileName, encryptionSettingName) |
fileName : String Relative path of the file to download encryptionSettingName : String Name of your encryption setting from the Credentials area in Design Integrations. |
Object | Downloads the file, verifies and decrypts it using the specified encryption setting and returns a reader which to read through the file line by line |
File Reader Methods
You can invoke these methods on the reader object returned from the downloadFiles() method.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| readLine() |
|
String | Reads a file line by line |
| cleanUp() |
|
Free the system resources consumed by the file Reader object. FileReader can't be used after running the cleanup() method. Resources are automatically cleaned up at the end of the script. |
Example
//Pass the relative filepath and the name of your encryption setting
const reader = client.downloadEncryptedFile('./archive/datasample.csv.asc', 'mypgp');
let line = reader.readLine()
while(line !== null){
//Process the line
line = reader.readLine()
}
Upload a File
To upload a file, a writer must be created to which lines can be written. The writer object is obtained from the ai.sftp namespace. Once the file has been created it can be uploaded to the client using one of the following methods.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| uploadFile(writer, uploadedFileName) |
Writer : writer Obtained from ai.sftp.createFileWriter() method
uploadedFileName: String Name of the file you are uploading
|
Uploads the specified file to the server. | |
| uploadEncryptedFile (writer, uploadedFileName, encryptionSettingName ) |
Writer : writer Obtained from ai.sftp.createFileWriter() method uploadedFileName: String Name of the file you are uploading encryptionSettingName : String Name of your encryption setting |
Encrypts the file using the specified encryption setting (found in the Credentials area in Design Integrations) and uploads it to the server. The file name and location is specified by the uploadedFileName argument. | |
| uploadEncryptedAndSignedFile(writer, uploadedFileName, encryptionSettingName) |
Writer : writer Obtained from ai.sftp.createFileWriter() method uploadedFileName: String Name of the file you are uploading encryptionSettingName : String Name of your encryption setting |
Encrypts and signs the file using the specified encryption setting (found in the Credentials area in Design Integrations) and uploads it to the server. The file name and location is specified by the uploadedFileName argument. |
File Writer Methods
You can invoke the following methods on the Reader object that has been returned from downloading files.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
| writeLine(val) |
val : String Content to write to a file |
Writes content to a file line by line. | |
| cleanUp() |
|
Free the system resources consumed by the File Writer object. Writer can't be used after running the cleanup() method. Resources are automatically cleaned up at the end of the script. |
Example
//Invoke the File Writer method
const writer = ai.sftp.createFileWriter();
//Write content to the writer variable
writer.writeLine('Here is a line to upload');
client.uploadFile(writer);
writer.cleanUp();
Notes on AWS Transfer for SFTP
While connecting to an AWS S3 server via SFTP, there are some differences in behavior with the AWS S3 file organization compared to Open SSH servers.
- CreateDirectory
- AWS S3 allows you to specify the path of new directories. For example, client.createDirectory('./parent/child'); will create the parent directory. However, If the parent directory already exists and you attempt to create a child directory, an exception will be thrown.