Component: SFTP hub

Introduction

Exchanging files through SFTP hub is an essential function in almost Casewhere applications. SFTP hub component is developed to simplified and standardized the process to integrate with the hub. The integrated application can easily send and receive files without interacting directly with the SSH Plugin.

Features

Manage connection info

The component provides a page to manage the server connection. The system can use a connection that was created when invoking an SSH method to interact with the SSH Plugin. If connection info does not pass as parameters, it will use plugin settings by default.

img

The following information must be provided when creating a connection:

  • Name: the name of connection.
  • Host: the host to connect, can be an IP address or URL.
  • Port: the port to connect, must be a valid port number (0 - 65535).
  • AuthenticationType: the type to authenticate to a server.
    • Password: for using password.
    • Certificate: for using public / private key pair.
  • Username: the username to connect.
  • Password: the password to connect, only used in case AuthenticationType is Password.
  • PrivateKey: the private key to connect, only used in case AuthenticationType is Certificate. Please refer to this section to know how to generate a private key that is used for authentication.
  • Passphrase: the passphrase to protect the private key, only used in case AuthenticationType is Certificate.
  • RootPath: the destination path to connect.

Manage hub folder structure

The component provides a page to manage the hub folder structure.

img

The following information must be provided when creating a folder:

  • Name: the name of folder, it should be identical to the folder name under the hub’s root path.
  • Type: the type of folder
    • Incoming: for receiving files from the hub.
    • Outgoing: for sending files to the hub.
  • ArchiveEnable: is the integration responsible for archiving files. For now, it only applies to incoming folders.
  • ArchivePath: the path to the archive folder.
  • ConnectionInfoId: the information to connect to the SFTP server. Note that a folder belongs to only one server.

Receive files

The component provides the workflow CwSftpHub Receive File for receiving files that can be used to integrate with the application’s workflow triggers. One typical scenario is using a scheduler to scan the incoming folders and download files, if any, periodically. A CwSftpHubIncomingFile object will be created if a file is downloaded successfully. If ArchiveEnable=true, the component will automatically archive the file by moving it to the specified folder in the hub.

Below is the data structure of the CwSftpHubIncomingFile:

  • FileName: the file name.
  • FolderId: the configured Incoming folder.
  • Content: the file content.
  • Status:
    • Received: when the file is downloaded successfully.
    • Archived: when the file is moved to the archive folder.
  • RelatedEntityId: optional, refer to an application’s Entity Id.
  • SyncDate: the time when the file is downloaded (in UTC+0 format).
  • HubCreatedDate: the time the file was created in the hub (in UTC+0 format).

Send files

The application can send a file to the hub by creating a CwSftpHubOutgoingFile object. The application can choose to send either synchronously or asynchronously by turning on or off the IsAsync attribute. Then, the component will automatically send the file to the hub through a built-in data trigger. In addition, the component will try to resend the file for a specific time if the file is failed to send for some reasons.

Below is the data structure of the CwSftpHubIncomingFile:

  • FileName: the file name.
  • FolderId: the configured Outgoing folder.
  • Content: the file content.
  • Status:
    • Created: the data object is created.
    • Ready: ready to send.
    • SentSuccess: the file is sent successfully.
    • SentFailed: the file is failed to send.
  • RelatedEntityId: optional, refer to an application’s Entity Id.
  • SyncAttempts: the number of upload attempts has been triggered.
  • MaxSyncAttempts: the maximum retry times if the file sending is failed.
  • IsAsync: upload immediately or wait in the queue.

Manage connection

The application allows user to manage the connections.

img

The following information must be provided when creating a connection:

  • Name: the name of connection.
  • Host: the host to connect, it can be an IP address or URL.
  • Port: the port to connect, valid port number should be in the range (0 - 65535).
  • AuthenticationType: the type to authenticate the connection.
    • Password: using password.
    • Certificate: using public/private key pair.
  • Username: the username to connect.
  • Password: the password to connect, used in case AuthenticationType is Password.
  • PrivateKey: the private key to connect, used in case AuthenticationType is Certificate.
  • Passphrase: the passphrase to protect the private key, used in case AuthenticationType is Certificate.
  • RootPath: the destination path to connect.

Installation

Requirements

  • Casewhere 2.6.0 or later.

Configure SSH Plugin

Get private key from a .ppk file.

  • Download and install PuTTY.
    Follow the instructions on this page: https://www.ssh.com/ssh/putty/windows/install to dowload and install PuTTY.

  • Convert the .ppk file to the private key file. After installing PuTTY, run the PuTTYgen application and follow the steps below to get and install a private key:

  1. Go to Conversions menu and select Import key img

  2. Select the .ppk file and click Open img

  3. Enter the passphrase that protects the key in the .ppk file img

  4. Go to Conversions menu and select Export OpenSSH key img

  5. Select a place to export the private key file and enter desired name for the file img

Configure the apllication

After installing, users must configure the application as below:

{
  "Host": // Host IP,  
  "Port": //Port,  
  "Username": //Username to access the host,  
  "Password": //Password,  
  "RootPath": //Path to the root folder
}

Releases

1.1.0 - 24/01/2022

Changelog

  • Manage SFTP connection.
  • Support connection parameters.
  • Support connect by private / public key pairs.

Download (login required): SFTP hub v1.1.0

1.0.0 - 19/07/2021

Changelog

  • Manage hub folder structure
  • Receive files
  • Send files

Download (login required): SFTP hub v1.0.0