FTP Extension Installation & User Guide

Transcription

1 FTP Extension Installation & User Guide Version 1.0 July 2015

2 Table of Contents 1. Introduction and Installation About the FTP Extension Installing the FTP Extension FTP Extension: Configuration and Use Configuration Usage Known Limitations and Compatibility

3 1. Introduction and Installation Extensibility is a core aspect of the architecture and design of ThingWorx. Partners, third parties, and users, as well as ThingWorx can easily add new functionality into the system in a seamless manner. Extensions can be Service (function/method) libraries, Connector Templates, Widgets, and more. This document provides installation and usage instructions for the FTP Extension. About the FTP Extension The FTP Extension allows you to configure Thingworx entities to connect to a remote FTP (File- Transfer Protocol) server for the purposes of obtaining directory listings, uploading files, and downloading files. The FTP Extension for ThingWorx provides a simple method to add basic FTP services to Thingworx entities which implement the FTPServer Thing Template. This extension requires that the remote server be set up to listen for FTP requests at a configurable port (default: 21). Note: Currently, the FTP Extension does not support transfer utilizing FTPS (FTP Secure) connections. The FTP Extension allows you to create a Thing in ThingWorx which implements the FTPServer Thing Template. The Thing entity houses the configuration information for the FTP Extension instance and provides services, including: 1. GetFileList 2. DownloadFile 3. UploadFile Installing the FTP Extension 1. From a web browser, launch ThingWorx. 2. Log into ThingWorx as an administrator. Page 1-1

4 3. Go to Import/Export > Import. 4. Click Choose File and select the FTP_Server.zip extension archive. 5. Click Import. Note: If an Import Successful message does not display, contact your ThingWorx System Administrator. Note: 6. Click Yes to refresh Composer after importing the final extension. Page 1-2

5 7. Now that all of the entities have been imported, create a new Thing and set it to implement the FTPServer Thing Template. 8. Under Entity Information for the new Thing, click Configuration, and then Edit. Be sure to save the entity when editing is complete. 9. Fill out the FTP Server Connection Parameters to the specifications of the FTP Server. All fields are required parameters. Page 1-3

6 10. Services may be tested by clicking the Services tab and clicking Test on one or more of the listed services. Required parameters differ by service. Page 1-4

7 2. FTP Extension: Configuration and Use Usage of the FTP Extension requires the creation and configuration of an FTP Extension Thing in ThingWorx. Please refer to section 1: Introduction and Installation for more details. The FTP Extension Thing provides the following services: GetFileList (returns an infotable listing all the files, along with their type, size, and exact path, within the specified path on the FTP server) DownloadFile (downloads a specified file to the specified Thingworx local file repository on the host) UploadFile (uploads a specified file from the specified Thingworx local file repository to a specified FTP server directory) CONFIGURATION Once the FTP Extension Thing is created, it must be configured to connect to a FTP Extension instance (Refer to section 1): Within the ThingWorx Composer, open up the FTP Extension Thing Navigate to the Configuration section Under the connection settings, enter valid information for each of the connection parameters Usage The FTP Extension can be used by invoking any one of the aforementioned services either through testing, script, or a Mashup implementation. Input parameters for the services are listed below. Input Parameters 1. GetFileList a. FTPPath: This is the directory path on the remote FTP server you are requesting the contents of. Enter a / to return the root directory. The results will be returned in InfoTable format. 2. DownloadFile a. FileRepository: This is a Thingworx Entity that references a local storage location. This is the location where downloaded files will be stored. By default, you may chose the SystemRepository Thing, which refers to the \ThingworxStorage\repository\SystemRepository folder on the local computer. Page 2-1

8 b. FTPFilePath: The exact directory path to the file on the remote server where the desired file is located. Enter / to specify the root directory. c. FTPFileName: The exact filename of the desired file on the remote server. d. This service returns a Result which will be either an error message, or a message stating that the file was transferred successfully. 3. UploadFile a. FileRepository: This is a Thingworx Entity that references a local storage location. This is the location where downloaded files will be stored. By default, you may chose the SystemRepository Thing, which refers to the \ThingworxStorage\repository\SystemRepository folder on the local computer. b. RepoFilePath: The exact path (within the repository folder) to the directory containing the file to be uploaded. Leave it blank to specify the root repository directory. c. RepoFileName: The exact name of the file which is to be uploaded. d. FTPFilePath: The exact path on the remote server where the file is to be uploaded to. Note that this file must already exist and cannot be created in this manner. e. FTPFileName: The exact filename that the uploaded file will be saved as on the remote server. This can be identical to the original file name. Important Connection Notes The FTP Extension requires that the remote FTP server be configured correctly to listen for incoming FTP connection requests on port 21 (default). The Extension sends commands to the server to set the remote server to Passive mode, so that the Extension may send the specified file requests to the server. This requires that the server s connection be configured in the following ways: The server should have a known username and password combination set up The server should have a FTP file directory specified for incoming file requests, with full read/write access for the User If the server is behind an NAT router and/or firewall, Port Forwarding must be configured for the router and firewall to allow the server to receive incoming requests on the ports to be used by the extension (typically this is TCP Ports ). You may otherwise encounter 425 Can t Open Data Connection error messages (returned to the Thing InfoTable in Thingworx after running the service). In addition, Port 21 (or the configured port) must be forwarded through the router / firewall as well. It is recommended that firewalls be disabled on the remote server to avoid connection issues This Extension is recommended to be used to interact with a server running FileZilla v or later. Please refer to online documentation for more information on configuring your FTP Server: o o Page 2-2

9 Use an outside source, such as Filezilla client, or an online FTP Testing tool such as to verify that the FTP server is configured properly to interact with the extension before seeking additional help. Page 2-3

10 3. Known Limitations and Compatibility The current version of the FTP Extension has a known limitation that is summarized below. Known Limitatinos Item Description FTPS (Secure) Support FTPS is not currently supported by this extension. This extension has been tested for compatibility with the following ThingWorx platforms and Java JRE versions: ThingWorx Platform Version Java JRE Version ThingWorx Java version 8, update 45 Page 3-4