FTP Adapter
The FTP adapter is used to work with an FTP server in your local environment from RunMyProcess DigitalSuite. By means of the FTP server, you can get, add, and delete files, list and rename files and folders (directories), and create and remove folders in your local environment.
Prerequisites
The following prerequisites must be fulfilled to install and run the FTP adapter:
-
You must install the adapter on a local system in your environment. This can either be the system where you have installed the DigitalSuite EnterpriseConnect Agent, or a different one which is able to connect to the Agent's host.
-
You can install the adapter several times in your environment, for example, to work with different FTP servers. The identifier of the adapter (
protocol
setting in thehandler.config
configuration file) must be unique for each of the installations. -
The local FTP server (e.g. standard FTP server of Microsoft Windows, VSFTPD on Linux) you want to use must be running and configured to allow access by the adapter.
-
The files and folders to be handled from RunMyProcess DigitalSuite must be accessible from the FTP server.
Installing the Adapter
To install the adapter:
-
Download the following ZIP file:
unified-adapter-[version].zip
[version]
is the current version numberThe ZIP file contains executables, licences, configuration files, and reference files for several adapters.
-
Extract the ZIP file to a local folder. The following path is recommended:
[parent-folder]\adapters\ftp
[parent-folder]
is a folder of your choice. If the EnterpriseConnect Agent is installed on the same machine, use its installation folder as the[parent-folder]
, for example,C:\ProgramFiles (x86)\dsec-agent
. -
Copy the configuration files for the FTP adapter,
FTP.config
andhandler.config
, from theconfigFiles\ftp.reference
subfolder to theconfigFiles
folder, for example:copy configFiles\ftp.reference\*.config configFiles
Overwrite existing files in the
configFiles
folder. -
If desired, delete obsolete files. Only the following folders and files are required in the
ftp
folder to use the adapter:ftp ├── configFiles │ ├── handler.config │ └── FTP.config ├── lib │ └── unified-adapter-[version].jar └── log.properties
In addition, we recommend you keep the following:
runAdapter.bat
batch file for starting the adapter on Microsoft Windowsftp.reference
subfolder in theconfigFiles
folder for reference purposes
Configuring the Adapter
Configuration settings for the FTP adapter are required in the following configuration files:
Edit the files with a plain text editor.
handler.config
The handler.config
file contains general configuration settings for connecting the adapter to the EnterpriseConnect Agent:
#Generic Protocol Configuration
protocol = FTP
protocolClass = org.runmyprocess.sec2.FTP
agentHost = 127.0.0.1:8080
pingFrequency = 1000
adapterConnectionInterval = 1000
offlineLogsMaxSize = 100
maxNumberOfLogsInBatch = 100
clusterEnabled = false
clusterAgentsHttpAddressList = localhost:8071,localhost:8072,localhost:8073
The settings have the following meaning:
protocol
: The identifier of the adapter. If you install the adapter several times in your environment, the identifier must be unique for each of the installations, for example,FTP1
andFTP2
.protocolClass
: The adapter's Java class.agentHost
: The IP address and port of the EnterpriseConnect Agent.pingFrequency
: The frequency in milliseconds in which the adapter pings the EnterpriseConnect Agent.adapterConnectionInterval
: The frequency in milliseconds in which the adapter tries to connect to the EnterpriseConnect Agent.offlineLogsMaxSize
: The maximum number of log entries that the adapter collects locally and sends to the EnterpriseConnect Agent when it re-connects to it after it was disconnected.maxNumberOfLogsInBatch
: The maximum number of log entries the adapter sends to the EnterpriseConnect Agent at a time. A value of0
means that the number of log entries sent at a time is unlimited.clusterEnabled
:true
if the EnterpriseConnect Agent is configured and running as a cluster,false
otherwise.clusterAgentsHttpAddressList
: The IP addresses and ports of the EnterpriseConnect Agent cluster, ifclusterEnabled
is set totrue
.
FTP.config
The FTP.config
file contains specific settings for the adapter:
#FTP Configuration
host=127.0.0.1
port=21
The settings have the following meaning:
host
: The host name or IP address of the FTP server to be used. Specify just the name or IP address withoutftp://
.port
: The port of the FTP server.
Starting the Adapter
The adapter needs to be running to be able to access files and folders by FTP.
Before you start the adapter, make sure that the DigitalSuite EnterpriseConnect Agent is running.
To start the adapter:
-
Change to the
ftp
installation folder. -
Execute the following command, depending on the operating system:
-
On Microsoft Windows: Execute the
runAdapter.bat
batch file. -
On Linux: Execute the following command directly, or create and execute a corresponding shell script to do so:
java -XX:+UseG1GC -XX:+ExitOnOutOfMemoryError -Djava.util.logging.config.file=./log.properties -cp lib/*: org.runmyprocess.sec2.AdapterHandler
-
Using the Adapter
If everything is configured and running correctly, you can place requests to the local FTP server from RunMyProcess DigitalSuite through the EnterpriseConnect Agent and the FTP adapter. Follow the examples below to get, add, and delete files, list and rename files and folders (directories), and create and remove folders in your local environment.
Request: POST
on http://[agent-host]:[port]/
, where [agent-host]
and [port]
are the IP address and port of the EnterpriseConnect Agent.
Content Type: application/json
Accept: application/json
Content (examples):
The message body is a JSON (JavaScript Object Notation) object whose structure depends on the operation to be executed. Each operation requires a nested JSON object with the outer object specifying the protocol, and the inner object defining the operation-specific parameters.
Some examples are described below. You can also find a sample request in the ftp.reference\InputJSONExample.txt
file in the ftp
installation folder.
LIST - listing folder contents
{
"protocol":"FTP",
"data":{
"task":"LIST",
"path":"Ubuntu One/appartment/",
"user":"myUser",
"password":"MyPassword"
}
}
PUT - creating files
{
"protocol":"FTP",
"data":{
"task":"PUT",
"path":"Ubuntu One/appartment/",
"user":"myUser",
"password":"MyPassword",
"files":[
{
"name":"I AM THE WALLRUS 6!",
"content":"SEVMTE8gV09STEQ="
},
{
"name":"I AM THE WALLRUS 7!",
"content":"SEVMTE8gV09STEQ="
}
]
}
}
DELETE - deleting files
{
"protocol":"FTP",
"data":{
"task":"DELETE",
"path":"Ubuntu One/appartment/",
"user":"myUser",
"password":"MyPassword",
"files":[
"Ubuntu One/appartment/I AM THE WALLRUS 6!",
"Ubuntu One/appartment/I AM THE WALLRUS 7!"
]
}
}
MKDIR - creating a folder
{
"protocol":"FTP",
"data":{
"task":"MKDIR",
"path":"Ubuntu One/appartment/WhoIsTheWallrusDir",
"user":"myUser",
"password":"MyPassword"
}
}
RMDIR - removing a folder
{
"protocol":"FTP",
"data":{
"task":"RMDIR",
"path":"Ubuntu One/appartment/WhoIsTheWallrusDir",
"user":"myUser",
"password":"MyPassword"
}
}
RENAME - renaming files and folders
{
"protocol":"FTP",
"data":{
"task":"RENAME",
"user":"myUser",
"password":"MyPassword",
"original":"Ubuntu One/appartment/I AM THE WALLRUS 6!",
"new":"Ubuntu One/appartment/I AM THE WALLRUS 6.5!"
}
}
Please give details of the problem