sftp-cg-lib v1.2.3

sftp-cg-lib

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

1. Introduction

This code has the objective to stablish connection with a SFTP server and depending of the option it will perform diferent actions.

Available options (defined for the flags parameter) and their actions:

CREATEDIRECTORY - Create a directory in an specific path. DELETEDIRECTORY - Delete the directory and its content (also considering the subdirectories). DELETEFILE - Delete a file in an specific path in the SFTP server. DOWNLOADIRECTORY - Dowload the full directory from the SFTP server to a local machine. GETFILE - Get the content of a file from the SFTP server, a specific encoding can be requested and also split the file into parts for large file and process the file by lines. GETLISTFILES - Get the list of files and directories contained in a specific path in the SFTP server. RENAMEFILE - Rename a file inside a path in the SFTP server. SAVEFILE - Create a file inside the SFTP server, the content of the file is handeled as a string that can have an specific encondig, the enconding should be specified. UPLOADIRECTORY - Upload a local directory and all its content into a specific path in the SFTP server.

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

As components are used in the N3xGen Portal (NXGP) flows regardless that the library should be added on component code, when the flow is running, an exchange and some queues are created using the ID flow (assigned from NXGP).

2. Library usage

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

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

2.1. CREATEDIRECTORY

• Arguments:
  • Required:
    • flag: The string that contains the action to be executed, in this case CREATEDIRECTORY. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • nameDirectory: The name of the directory that will be created.
    • path: The full path where the directory will be created.
  • Optionals:
    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.

    • password: This parameter contains the password to stablish the connection with the SFTP server.

    __* Al least one of this two optional parameters is required, and the user must configure one.__

• Description: This request will create a new directory inside the SFTP server. It is posible to create a complete structure of directory in one request. Once the request is sent, the answer will be a string in a JSON format with the result of the excecution.

• Sample of a request:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"CREATEDIRECTORY",
    "nameDirectory":"newDir/otherdir"
}

Resultant sample:

"\\newDir\\otherdir1 directory created"

In case the directory already exists, the next message will be shown:

"\\newDir\\otherdir already exists"

2.2 DELETEDIRECTORY

• Arguments:

  • Required:
    • flag: The string that contains the action to execute, in this case DELETEDIRECTORY. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • path: The path that will be used to work on directory deletion.
    • nameDirectory: The name of the directory that will be deleted, considering that all its content within will be removed too.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.

    • password: This parameter contains the password to stablish the connection with the SFTP server.

      * Al least one of this two optional parameters is required, and the user must configure one.

• Description: This request will delete a directory with all the documents inside it. Once the request is sent, the answer will be a string in a JSON format with the result of the excecution.

• Sample of a request:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"DELETEDIRECTORY",
    "nameDirectory":"newDir"
}

Resultant sample:

"Successfully removed directory"

In case the directory does not exist this message will be shown:

{
    "code": "ERR_BAD_PATH",
    "custom": true
}

2.3. DELETEFILE

• Arguments:

  • Required:
    • flag: The string that contains the action to execute, in this case DELETEFILE. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • file: The name of the file that will be deleted.
    • path: The full path where is the file that will be delete.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.

    • password: This parameter contains the password to stablish the connection with the SFTP server.

      * Al least one of this two optional parameters is required, and the user must configure one.

• Description: This request will delete a specific file in the SFTP server. Once the request is sent, the answer will be a string in a JSON format with the result of the excecution.

• Sample of a request:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"DELETEFILE",
    "file":"file.txt"
}

Resultant sample:

"Successfully deleted \\file.txt"

In case the file does not exist this message will be shown:

{
    "code": 2,
    "custom": true
}

2.4. DOWNLOADIRECTORY

• Arguments:

  • Required:
    • flag: The string that contains the action to execute, in this case DOWNLOADIRECTORY. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • path: The path of the directory that will be downloaded from the SFTP server.
    • nameDirectory: The name of the directory that will be created in the local machine when the information is downloaded.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.

    • password: This parameter contains the password to stablish the connection with the SFTP server.

      * Al least one of this two optional parameters is required, and the user must configure one.

• Description: This request will get a directory from the SFTP and will save all the content inside the local machine with the specified name. Once the request is sent, the answer will be a string in a JSON format with the result of the excecution.

• Sample of a request:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"DOWNLOADIRECTORY",
    "nameDirectory":"C://Users//Documents"
}

Resultant sample:

"/ downloaded to C://Users//Documents"

If the path of sftp servert that was specified does not existe this message will be shown:

{
    "code": 5,
    "custom": true
}

2.5. GETFILE

• Arguments:

  • Required:
    • flag: The string that contains the action to execute, in this case GETFILE. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • path: The path where is located the file in the SFTP server that will be get.
    • file: The name of the file requested.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.
    • password: This parameter contains the password to stablish the connection with the SFTP server.
    • encoding: The enconging that will be used to get the file, if this parameter is not set the value "base64" will be taken as default.
    • splitFile: Flag to define if the file will be process by number of lines or not.
    • headers: Flag to define if the file that we are going to process by number of lines is going to have the first row as headers or not.

    • numberOfLines: The number of lines thtat we want to split the file.

      * Al least one of this two first optional parameters is required, and the user must configure one.

• Description: This request will get the content of a file in a string. Once the request is sent, the answer will be a string in a JSON format with the result of the excecution.

• Sample of a request without encoding (the default countent will be get in base64):

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"GETFILE",
    "file":"test.txt"
}

Resultant sample:

{
    "filename": "test.txt",
    "content": "dGVzdCBvZiBhIHNmdHAgY29tcG9uZW50"
}

• Sample of a request with encoding:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"GETFILE",
    "file":"test.txt",
    "encoding": "utf8"
}

Resultant sample:

{
    "filename": "test.txt",
    "content": "test of a sftp component"
}

If a file that does not exist is tryed to be get this message will be shown:

{
    "code": 3,
    "custom": true
}

2.6. GETLISTFILES

• Arguments:

  • Required:
    • flag: The string that contains the action to execute, in this case GETLISTFILES. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.

    • password: This parameter contains the password to stablish the connection with the SFTP server.

      * Al least one of this two optional parameters is required, and the user must configure one.

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

• Sample of a request:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"GeTLiSTFILES"
}

Resultant sample:

[
    {
        "type": "-",
        "name": "vista.txt",
        "size": 5,
        "modifyTime": 1660166815000,
        "accessTime": 1660166815000,
        "rights": {
            "user": "rw",
            "group": "rw",
            "other": "rw "
        },
        "owner": 0,
        "group": 0,
        "longname": "-rw-rw-rw   1     root     root         5 Aug 10 16:26 vista.txt"
    },
    {
        "type": "-",
        "name": "Xp.txt",
        "size": 8,
        "modifyTime": 1660166684000,
        "accessTime": 1660166674000,
        "rights": {
            "user": "rw",
            "group": "rw",
            "other": "rw "
        },
        "owner": 0,
        "group": 0,
        "longname": "-rw-rw-rw   1     root     root         8 Aug 10 16:24 Xp.txt"
    }
]

If a path that does not exist is specified this message will be shown:

{
    "code": 5,
    "custom": true
}

2.7. RENAMEFILE

• Arguments:

  • Required:
    • flag: The string that contains the action to execute, in this case RENAMEFILE. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • file: The old name of the file that will be renamed.
    • nameNewFile: The new name of the file that is going to be renamed.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.

    • password: This parameter contains the password to stablish the connection with the SFTP server.

      * Al least one of this two optional parameters is required, and the user must configure one.

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

• Sample of a request:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"RENAMEFILE",
    "file":"testOldName.txt", 
    "nameNewFile":"testNewName.txt"
}

Resultant sample:

"Successfully renamed \\testOldName.txt to \\testNewName.txt"

If the file that will be renamed does not exist this message will be shown:

{
    "code": 2,
    "custom": true
}

2.8. SAVEFILE

• Arguments:

  • Required:
    • flag: The string that contains the action to execute, in this case SAVEFILE. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • content: The content of the file, that will be saved.
    • path The path where the file will be saved into the SFTP server.
    • file: The name and extension that will be used for the new file.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.
    • password: This parameter contains the password to stablish the connection with the SFTP server.

    • encoding: The enconging that will be used to get the file, if this parameter is not set the value "base64" will be taken as default.

      * Al least one of this two first optional parameters is required, and the user must configure one.

• Description: This request will save a file into the SFTP server, the string with the content could be in severals formats, the parameter encoding should be specified in case of a content different to base64. Once the request is sent, the answer will be a string in a JSON format with the result of the excecution.

• Sample of a request no enconding specified so the content should be base64:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"SAVEFILE",
	"content":"dGVzdCBvZiBhIHNmdHAgY29tcG9uZW50",
    "file":"testNewFile.txt"
}

Resultant sample:

"Uploaded data stream to \\testNewFile.txt"

• Sample of a request with enconding:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"SAVEFILE",
	"content":"Hello world.",
    "file":"testNewFile.txt",
    "enconding":"utf8"
}

Resultant sample:

"Uploaded data stream to \\testNewFile.txt"

If the file that will be created already existe, the current file will be renamed adding the date in the name and the new file will be create with the name in the request.

2.9. UPLOADIRECTORY

• Arguments:

  • Required:
    • flag: The string that contains the actinon to execute, in this case UPLOADIRECTORY. The string is not case sensitive.
    • host: The host where the connection will be stablished to the SFTP server, can be a URL or IP.
    • port: The port that is configuted in the SFTP server to allow access.
    • username: The username that has grants to connect with the SFTP server.
    • nameDirectory: The path of the directory source that will be uploaded.
    • path: The path where the directory will be uploaded and the name of the new directory into the SFTP server.

  • Optionals:

    • key: Parameter that has the path where is the key to be used as authentication when it is configured for the SFTP server to stablish the connection, if this parameter is used the password parameter shouldn't be set, in case the two parameters are specified this one will have priority and the password will be ignored.

    • password: This parameter contains the password to stablish the connection with the SFTP server.

      * Al least one of this two optional parameters is required, and the user must configure one.

• Description: This request will send the content of a local directory to the SFTP server. Once the request is sent, the answer will be a string in a JSON format with the result of the excecution.

• Sample of a request:

{
	"host":"localhost", 
	"port":22, 
	"username":"admin", 
	"password":"admin", 
    "path":"/",
    "flag":"UPLOADIRECTORY",
    "localDirectory":"C://Users//Documents"
}

Resultant sample:

"C://Users////Documents// uploaded to /"

If the local path does not exist this message will be shown:

{
    "code": "ERR_BAD_PATH",
    "custom": true
}