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 Platform or from the platform 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 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 EMS, these properties might look like this:
"file": {
"virtual_dirs":[
{ "In" : "c:\\microserver_5.4.10-win32\\microserver\\in" },
{ "Out" : "c:\\microserver_5.4.10-win32\\microserver\\out" },
{ "staging" : "c:\\microserver_5.4.10-win32\\microserver\\staging" }
],
"staging_dir" : "staging"
}
Note that when specifying the virtual directory paths for a Windows system, the backwards slash needs to be doubled (c:\\microserver_5.4.10-win32\\microserver\\in
If you use the additional parameters available for the file group, it might look like this for a Windows installation:
"file": {
"buffer_size": 1024000,
"max_file_size": 8000000000,
"virtual_dirs":[
{ "In" : "c:\\microserver_5.4.10-win32\\microserver\\in" },
{ "Out" : "c:\\microserver_5.4.10-win32\\microserver\\out" }
],
"idle_timeout": 12000,
"staging_dir" : "c:\\microserver_5.4.10-win32\\microserver\\staging"
}
}
or like this for a Linux installation:
"file": {
"buffer_size": 1024000,
"max_file_size": 8000000000,
"virtual_dirs":[
{ "In" : "./test/microserver/in" },
{ "Out" : "./test/microserver/out" }
],
"idle_timeout": 12000,
"staging_dir" : "./test/microserver/staging"
}
}
In these examples, note in particular the value of the buffer_size property. This value affects performance of file transfers. The default value of 1024000 is recommended as a best practice to achieve optimal performance when transferring large files.
The file group configuration is important because you must pass the 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 describes the properties for file transfers:
|
Property
|
Description
|
||
|---|---|---|---|
|
buffer_size
|
The size of the buffer used for the file transfer, in bytes. The default value is 1024000 bytes (1MB), which is recommended as a best practice to achieve optimal performance when transferring large files.
|
||
|
max_file_size
|
The maximum size of a file that can be transferred, in bytes. The default value is 8000000000 bytes (8GB).
|
||
|
virtual_dirs
|
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.
|
||
|
idle_timeout
|
The amount of time, in milliseconds, that the 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).
|
||
|
staging_dir
|
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.
|
 |
You do not have to have LSR running to perform a file transfer using EMS. However, you do need a bound Thing. In versions 8.3.5 and 8.4.x of the ThingWorx Platform, a service call was introduced, called GetSupportedChecksums. This service breaks previously working EMS configurations that use auto_bind for identity but do not specify a host and port. The workaround for this change is to make sure that your auto_bind configuration specifies the host and port used by the http_server configuration. Refer to Troubleshooting File Transfers When Using Automatic Binding.
|
This example uses the Copy service of the FileTransferSubsystem entity 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 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 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 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:
• FileRepository
• RemoteThingWithFileTransfer
• RemoteThingWithFileTransferAndTunneling
Also, as of versions 5.0 and later of the 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:
"auto_bind":[
{"name": "RT1" }
]