ThingWorx WebSocket-based Edge MicroServer (WS EMS) and Lua Script Resource (LSR) > Additional Configuration of WS EMS > Configuring File Transfers
Configuring File Transfers
To execute a file transfer, you need to configure options for both your client application and your ThingWorx instance. Transfers can be executed in either direction: from the edge application to your ThingWorx instance or from the instance to the edge application.
Keep in mind that the account associated with the Application Key must have the correct Read/Write permissions to the target and destination directories for a file transfer.
To transfer a file, the WS EMS must be configured with a set of virtual directories. The paths that you specify for the virtual directories must be absolute; the paths for the files must be relative to the virtual directories. For the WS EMS, these properties might look like this:
"file": {
{ "In" : "c:\microserver_5.4.0-win32\microserver\in" },
{ “Out" : "c:\microserver_5.4.0-win32\microserver\out" },
{ "staging" : "c:\microserver_5.4.0-win32\microserver\staging" }
"staging_dir" : "staging"
If you use the additional parameters available for the file group, it might look like this:
"file": {
"buffer_size": 128000,
"max_file_size": 8000000000,
{ "In" : "c:\microserver_5.4.5-win32\microserver\in" },
{ “Out" : "c:\microserver_5.4.5-win32\microserver\out" }
"idle_timeout": 12000,
"staging_dir" : "c:\microserver_5.4.5-win32\microserver\staging"
In this example, note in particular the value of the buffer_size property. This value affects performance of file transfers. The default value of 128000 should suffice for most environments. However, if performance is slow for file transfers, consider increasing the buffer size.
The file group configuration is important because you must pass names of virtual directories in the parameters to the ThingWorx Copy service. As shown in the example above, you must use absolute paths.
The following table lists and describes the properties for file transfers:
The size of the buffer used for the file transfer, in bytes. The default value is 128000 bytes. If performance is slow, consider increasing the buffer size.
The maximum size of a file that can be transferred, in bytes. The default value is 8000000000 bytes (8GB).
An array of virtual directories that are used when browsing and sending files to the configured ThingWorx platform. The directories are defined using absolute paths, as shown in the example above.
The amount of time, in milliseconds, that the WS EMS waits before timing out a file transfer when the transfer is idle. Note that this value must be larger than the value of the frame_read_timeout property (in the ws_connection group). If this property is not set, the actual default value is 1.2 times the value of the frame_read_timeout. For example, if the frame_read_timeout is set to its default value of 10000 milliseconds, the default value of this property is 1.2 times 10000, or 120000 milliseconds (2 minutes).
A directory to use as a staging directory for files that will be transferred to the edge device. As shown in the example above, this path must be an absolute path.
This example uses the Copy service for a file transfer. It makes the following assumptions:
A RemoteThingWithFileTransfer named RT1 exists on the ThingWorx instance.
The files are being transferred to/from the SystemRepository thing.
The WS EMS is installed in the directory, C:\microserver and that C:\microserver\in, C:\microserver\out, and C:\microserver\staging exist.
The source file is located in the files directory of the SystemRepository thing.
The source and destination directories MUST exist AND be accessible to the WS EMS (Read/Write permissions).
In this example, the Copy service parameters to specify for a transfer from the ThingWorx platform to the edge device would be:
sourceRepo: SystemRepository // Name of the Thing to transfer from
targetRepo: RT1 // Name of the Thing to transfer to
sourcePath: /files // Directory in the SystemRepository (absolute path)
targetPath: /in // The name of a virtual dir
In this case, it is pointing to C:\microserver\in. You can also specify subdirectories.
sourceFile: abc.json
targetFile: abc.json // Optional
The default name for the targetFile is the name of the sourceFile. You can rename files during the transfer.
The paths on the WS EMS must be relative to a virtual directory that is registered to the remote thing (that is, they must start with the "/<virtual_dir>"). In the case of a file repository on the ThingWorx platform, the paths need to be relative to the root directory of the file repository (must start with "/").
Note that the things must be instances of one of the following templates:
Also, as of versions 5.0 and later of the WS EMS, you do not need the Lua Script Resource to do file transfers. You can add the auto_bind group to your configuration file to specify the name of a thing that will participate in file transfers:

{"name": "RT1" }