Metadata for File Transfer Jobs
Uploading files to the ThingWorx Platform from edge devices and downloading files to edge devices from the ThingWorx Platform are tracked in the ThingWorx Platform as file transfer jobs. These jobs are data objects that ThingWorx Platform tracks and uses through the lifecycle of a file transfer.
It is often desirable to add information to the file transfer job to help describe it or to add processing instructions for either side of the file transfer. For example, an eMessage agent can request to upload multiple files, but the transfer job itself stores only one source file and path. This type of information can be associated with a transfer job and is stored on the ThingWorx Platform.
To support this functionality, the Copy service of the File Transfer Subsystem has a parameter called metadata that is defined with a base type of JSON. This field is optional, and has a default value of null if you do not specify a value for it. This parameter is defined in the Data Shape, FileTransferJob, allowing access to the metadata during any File Transfer Subsystem service call that returns file transfer jobs.
 |
If no metadata is specified at all for a file transfer, the targetPath provided for a file download and the sourcePath provided for a file upload are assumed to be relative (not absolute) to the eMessage agent installation. Updating the metadata for existing file transfer jobs is not supported.
|
|
|
The eMessage Connector accesses only one ThingWorx Platform at a time, and the file transfer jobs in the offline queue are not durable. If you are using PostgreSQL with your ThingWorx platform, active file transfer jobs are durable. If the setup of a ThingWorx environment includes two ThingWorx Platform nodes that use PostgreSQL (one active and one standby), client connections can be redirected to the secondary node if the first one fails. When an active job is persisted, its metadata is also persisted.
|
In general, the metadata applies only to the agent side of a file transfer (i.e., the target on downloads, the source on uploads). On the ThingWorx Platform side, paths are always relative to the SystemRepository directory, regardless of the metadata or the initial slash (/). For a file download with an absolute path, the initial slash (/) for Linux or the drive letter (e.g., C:\) is required for the agent-side path. Otherwise, the agent interprets the path as relative.
|
|
ThingWorx Platform does not support absolute paths for file uploads.
|
The metadata options that can be used with the Copy service for eMessage agents are listed and described (with examples) in the following table:
|
Metadata Field
|
Options
|
Example (JSON Format)
|
|---|---|---|
|
upload.compressionType
|
tar-gzip — Default Value. Tells the agent to compress the file(s) using the tar-gzip utility.
none — Tells the agent NOT to compress the file(s) to be uploaded.
NOTE: The eMessage agents use only tar.gzip to compress and extract files.
|
{
"upload": { "compressionType": "tar-gzip" } } |
|
upload.deleteAfterUpload
|
true — Tells the agent to delete the file that it uploaded upon success.
false — Default Value. Tells the agent to keep the file on the agent device.
|
{
"upload": { "deleteAfterUpload": true } } |
|
download.overwriteExisting
|
true — Default Value. Tells the agent to overwrite any existing file(s).
false — Tells the agent not to overwrite any existing file(s). When this option is specified, the Axeda agent copies the existing file(s) to a directory called axedabackup and adds the newly downloaded file to the directory specified as the target/destination for the download.
|
{
"download": { "overwriteExisting": false } } |
|
download.deviceRelativePath
|
Keep in mind that this field applies only to the agent side of the file transfer. It is a boolean, defined as follows:
• true — Default Value. Indicates that the target file path is relative to the home directory of the agent. If this field is not set, the path is treated as relative.
• false — The target file path is absolute, as long as it contains a forward slash (Linux) or drive letter (Windows) at the beginning. For example, /connector/uploads. If this forward slash is omitted, the path is treated as relative.
.
|
{
"download": { "deviceRelativePath": false } } |
|
download.compressionType
|
tar-gzip — Tells the agent that the file(s) is a tar-gzip archive. The agent extracts the file(s) from such an archive upon successful download.
none — Default Value. Tells the agent that the file is NOT compressed.
NOTE: The eMessage agents use only tar.gzip to compress and extract files.
|
{
"download": { "compressionType": "tar-gzip" } } |
|
download.executeAfterDownload
|
true — Tells the agent to try to run the downloaded file.
false — Default Value. The agent does not try to run the downloaded file.
|
{
"download": { "executeAfterDownload": true } |
|
download.restartAfterDownload
|
true — Tells the agent to restart (soft) upon successful download.
false — Default Value. The agent does not restart once the download is complete.
|
{
"download": { "restartAfterDownload": true } |
When invoking the Copy service using the following JSON definition for a file upload, you are telling the agent that the file to upload should be compressed using tar-gzip and that the agent should delete the file after uploading it:
{
"upload": {
"compressionType": "tar-gzip",
"deleteAfterUpload": true
}
}
"upload": {
"compressionType": "tar-gzip",
"deleteAfterUpload": true
}
}
When invoking the Copy service using the following JSON definition for a file download, you are telling the agent that the file to be downloaded is compressed using tar-gzip, that the path specified is relative to the home directory of the agent, and that the agent should take the following actions after unzipping the archive (in the following order):
1. Overwrite the existing file.
2. Execute the file.
3. Restart.
{
"download": {
"compressionType": "tar-gzip",
"deviceRelativePath": true,
"overwriteExisting": true,
"executeAfterDownload": true,
"restartAfterDownload": true
}
}
"download": {
"compressionType": "tar-gzip",
"deviceRelativePath": true,
"overwriteExisting": true,
"executeAfterDownload": true,
"restartAfterDownload": true
}
}