ftp-cg-lib

https://github.com/CloudGenUser/ftp-cg-lib

1. Introduction

This code has the objective to establish a connection to a FTP server and depending of the option selected it performed a different action.

Possible flags and their actions:

• CREATEDIRECTORY - Create a directory in a specific path.
• DELETEDIRECTORY - Delete the directory and their content in a specific path.
• DELETEFILE - Delete a file in a specific path.
• DOWNLOADDIR - Download a directory with all its content from a FTP server into another location like a local machine.
• GETFILE - Get the content of a file, a specific encoding of the content can be requested.
• GETLISTFILES - Get the list of files and directories inside a specific path.
• RENAMEFILE - Rename a file inside a path.
• SAVEFILE - Create a file inside the ftp server, the content of the file is a string that can have an specific encoding, if the encoding parameter is not defined then base64 will be used as default.
• UPLOADDIR - Take a directory for a local machine and save the content inside a ftp server.

Any other flag will be consider as an invalid value and will return a message error.

As this library is used into a OIH based component it can be integrated into flows to perform different accions as required in a data transformation process. This flows definition are intended to be generated in the N3xGen Portal.

2. Library usage

The library can be installed from npm page with the next:

npm install ftp-cg-lib, npm i ftp-cg-lib or yarn install ftp-cg-lib

2.1. CREATEDIRECTORY

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • path: The full path inside the FTP service where it is required to create, delete download or upload a directory, also where the file is or would be stored, deleted, renamed or get its content.

• Description: This request will create a new directory inside the FTP server according with the path, if the directory in the path doesn't exist it will be created. It is possible to create a complete structure of directory (in a single branch) in one request setting all the structure in the path. Once the request is performed, the answer will be a string in a JSON format with the result of the execution.

• Request example:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"CREATEDIRECTORY",
   "path":"NewFolder/OtherFolder"
}

• Resultant example:

"Directory NewFolder/OtherFolder was created successfully."

In case an error occurs like access denied the corresponding message will be shown as follows:

"FTPError: 550 ........"

2.2 DELETEDIRECTORY

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • path: The full path inside the FTP service where it is required to create, delete download or upload a directory, also where the file is or would be stored, deleted, renamed or get its content.

• Description: This request will delete a directory with all its content (all the documents inside it). Once the request is performed, the answear will be a string in a JSON format with the result of the excecution.

• Request example:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"DELETEDIRECTORY",
   "path":"files/newFolder"
}

• Resultant example:

"Directory files/newFolder was deleted successfully."

2.3. DELETEFILE

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • file: The name of the file that will be deleted inside the FTP. It will be required to set the full path with the file name.

• Description: This request will delete a specific file according with the seletded path in the FTP server. Once the request is performen, the answear will be a string in a JSON format with the result of the excecution.

• Request example:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"DELETEFILE",
   "file":"files/newFileFTP.txt"
}

• Resultant example:

"File files/newFileFTP.txt was deleted successfully."

In case that the file doesn't exist in the FTP the corresponding message will be shown as follows:

"FTPError: 550 ........"

2.4. DOWNLOADDIR

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • path: The full path inside the FTP service where it is required to create, delete download or upload a directory, also where the file is or would be stored, deleted, renamed or get its content.
  • localPath: It is the location to download the directory from the FTP server.

• Description: This request will get a directory from the FTP and will save all the content inside another location like in a local machine. Once the request is performed, the answer will be a string in a JSON format with the result of the execution.

• Request example:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"DOWNLOADDIR",
   "path":"dowloadFolder",
   "localPath":"C:/Users/Documents/download_here"
}

• Resultant example:

"Remote directory / was successfully downloaded to C:/Users/Documents/download_here_directory."

In case that the directory doesn't exist or is unreadable, the corresponding message will be shown as follows:

"FTPError: 550 ........"

2.5. GETFILE

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • file: The name of the file inside the FTP to get its content. It will be required to set the full path with the file name. Optional:
  • encoding: The enconding to be used to get the content of a file, if this parameter is not set, the base64 encoding will be taken as default value.

• Description: This request will get the content of a file in a string (with the configured or default encoding). Once the request is performed, the answer will be a string in a JSON format with the result of the execution.

• Request example without setting the encoding (the default content will be in base64):

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"GETFILE",
   "file":"files/incoming/JSONSource.json"
}

• Resultant example:

"ew0KICAgICJGaXJzdE5hbWUiOiJFbW1hbnVlbCIsDQogICAgIlNlY29uZE5hbWUiOiJBcnJlb2xhIiwNCiAgICAiTGFzdE5hbWUiOiJKdWFyZXoiLA0KICAgICJBZ2UiOiIyNiB5ZWFycyIsDQogICAgIk9yaWdpbiI6Ik1leGljbyINCiAgfQ=="

• Request example with encoding:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"GETFILE",
   "file":"files/incoming/JSONSource.json",
   "encoding":"utf8"
}

• Resultant example:

"{\r\n    \"FirstName\":\"John\",\r\n    \"SecondName\":\"Anderson\",\r\n    \"LastName\":\"Smith\",\r\n    \"Age\":\"30 years\",\r\n    \"Origin\":\"USA\"\r\n  }"

In case that the file doesn't exist into the FTP, the corresponding message will be shown as follows:

"FTPError: 550 ........"

2.6. GETLISTFILES

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • path: The full path inside the FTP service where it is required to create, delete download or upload a directory, also where the file is or would be stored, deleted, renamed or get its content.

• Description: This request will get a string in JSON format with all the files and directories inside the specified path. Once the request is performed, the answer will be a string in a JSON format with the result of the execution.

• Request example:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"GETLISTFILES",
   "path":""
}

• Resultant example:

[
   {
      "name":"incoming",
      "type":2,
      "size":4096,
      "rawModifiedAt":"Sep 28 15:29",
      "permissions":{
         "user":7,
         "group":5,
         "world":5
      },
      "hardLinkCount":2,
      "group":"1004",
      "user":"1004"
   },
   {
      "name":"outgoing",
      "type":2,
      "size":4096,
      "rawModifiedAt":"Sep 27 23:05",
      "permissions":{
         "user":7,
         "group":5,
         "world":5
      },
      "hardLinkCount":2,
      "group":"1004",
      "user":"1004"
   }
]

If the specified path does not exist the next message is shown:

[]

2.7. RENAMEFILE

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • file: The name of the file inside the FTP to be renamed. It will be required to set the full path with the file name.
  • newName: The new name of the file to be renamed.

• Description: This request will rename a file inside the FTP server. Once the request is performed, the answer will be a string in a JSON format with the result of the execution.

• Request example:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"RENAMEFILE",
   "file":"files/newFileFTP.txt",
   "newName":"files/otherName.txt"
}

• Resultant example:

"File files/testOIH/newFileFTP.txt was successfully renamed to files/testOIH/otherName.txt."

In case that the file doesn't exist into the FTP, the corresponding message will be shown as follows:

"FTPError: 550 ........"

2.8. SAVEFILE

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • file: The name of the file to be uploaded into the FTP. It will be required to set the full path with the file name. Optional:
  • encoding: The enconding to be used to set the content of a file, if this parameter is not configured, the base64 encoding will be taken as default value.

• Description: This request will save a file inside the FTP, the string that corresponds with the content of the file could be in severals encodings, the parameter encoding should be specified in case of an encoding different of base64 is required. Once the request is performed, the answer will be a string in a JSON format with the result of the execution.

• Request example without the encoding specified, by default the content should be base64:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"SAVEFILE",
   "file":"files/newFileFTP.txt",
   "content":"VGhpcyBpcyB0aGUgY29udGVudCBvZiBteSBmaWxlLg=="
}

• Resultant sample:

"File files/newFileFTP.txt was created successfully."

• Request example with encoding set:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"SAVEFILE",
   "file":"files/testOIH/newFileFTP.txt",
   "content":"Hello World.",
   "encoding":"uft8"
}

• Resultant sample:

"File files/newFileFTP.txt was created successfully."

If the file name already exists, the existing one will be renamed adding its creation date at the end in the name and the new file will be create with the name in the request. If an error occurs the next message will be shown:

"FTPError: 553 ........"

2.9. UPLOADIRECTORY

• Arguments: Required:

  • flag: : The string that contains the options about the actinon to be executed, can be one of the following: CREATEDIRECTORY, DELETEDIRECTORY, DELETEFILE, DOWNLOADDIR, GETFILE, GETLISTFILES, RENAMEFILE, SAVEFILE, UPLOADDIR. The string is not case sensitive.
  • host: The host is the URL or IP address to connect to the FTP service.
  • port: The port to have access to the FTP server.
  • username: The username that have grants to connect to the FTP server.
  • password: This parameter contains the password related to the user name and the host to connect to a FTP service.
  • path: The full path inside the FTP service where it is required to create, delete download or upload a directory, also where the file is or would be stored, deleted, renamed or get its content.
  • localPath: It is the location to download the directory from the FTP server.

• Description: This request will upload the content of a local directory into the FTP server. Once the request is performed, the answer will be a string in a JSON format with the result of the execution.

• Request example:

{
   "host":"localhost",
   "port":21,
   "username":"user",
   "password":"password",
   "flag":"UPLOADDIR",
   "path":"uploadFolder",
   "localPath":"C:\\Users\\Documents\\upload_this"
}

• Resultant example:

"Local directory C:/Users/DMV/Documents/ftpfiles/upload_this_directory was successfully uploaded to files/testOIH/newFolder/"

If the local path does not exist the next message is shown:

Error: ENOENT: no such file or directory, scandir "C:\\Users\\DMV\\Documents\\ftpfiles\\upload_this_directoryx"