The Copy Service
To perform file transfers from the ThingWorx Platform to agent devices, users can invoke the Copy service. This service supports file upload requests and file download requests. It takes two properties that are very important for file transfer jobs with Axeda agents:
• queueable — By default, this property is set to false, which means that file transfers are never queued to wait for the asset to contact ThingWorx Platform. To support Axeda agents and ensure that file transfer jobs are queued when devices are not connected, set this property to true. This setting is very important for Axeda agents because they poll a platform. The platform must wait until they connect to send messages and process file transfer requests.
• async — This property specifies whether the transfer is performed asynchronously (true) or synchronously (false). Always set this property to true for file transfers between Axeda agents and ThingWorx Platform.
For file transfers with Axeda agents, both async and queueable must be set to true. If async is set to false and the queueable property is set to true, the File Transfer Subsystem generates a TransferException that describes this mis-configuration.
When queueable is set to true and the Axeda asset is not connected, a user can request a file download to or file upload from the asset, knowing that the request will be queued until the asset reconnects. Once the asset reconnects to the ThingWorx Platform, the file transfer will be started.
What if the device goes offline before the transfer is performed? The transfer job is re-queued. If a file transfer job is re-queued frequently, the File Transfer Subsystem generates an event notification that says the job is stalled. The event is generated after the transfer has been queued for 12 hours, then again after 18 hours, after 22 hours, and after 23 hours. After 24 hours, the job is discarded, and the user will need to request the file transfer again. This time-to-live for a queueable file transfer job is the default behavior in the ThingWorx Platform and can be configured in the File Transfer Subsystem of the ThingWorx Platform. Set the Time To Live property (number of seconds) for Queueable File Transfers.
The File Transfer Subsystem provides the property, Max Queue Entries Before Adding New Worker Thread, which specifies the maximum number of file transfer jobs that can be in the active queue, regardless of the number of threads. The default value is 100 transfer jobs, which means that when the active queue contains 100 jobs, the 101st job will be rejected
Before submitting a file transfer job to the thread pool that determines which queue to place the job in, the File Transfer Subsystem checks whether the related device is connected. If not, the job is queued in the offline queue. If that queue is full or another exception occurs, the state of the transfer job is updated and the exception is thrown.
A queued file transfer is re-queued only if the Axeda agent has not yet been notified of the transfer request (the agent device is still not connected). Once the agent is notified, the job will complete or fail, depending on the status returned from the agent. Both the destination and the source for a file transfer must be online for a transfer job to start. More specifically, the Axeda agent must be connected and the File Repository on the ThingWorx Platform must be available (online).
 |
Even with queueable set to true, it is possible for a file transfer to fail if the device disconnects during the transfer. To work around this possibility, configure the eMessage Connector to retry file transfers (in the emessage.conf configuration file). Refer to Configuring Additional Parameters for File Transfers.
|
In addition to the queueable and async properties, the Copy service requires the following parameters that specify the source file and path and the destination file, path, and repository:
|
Parameter
|
File Download
|
File Upload
|
|---|---|---|
|
sourceRepo
|
The Thing name of the File Repository from which the file is downloaded.
|
The Thing name of the Axeda agent device from which to upload the file.
|
|
sourceFile
|
The name of the file to be downloaded to the agent device. For example, test.txt.
|
The name of the file to be uploaded to the ThingWorx Platform from the agent device.
|
|
sourcePath
|
The path to the file to be downloaded from the File Repository that you specified for the source repository. If this parameter is left blank, the file is assumed to be at the root of the File Repository.
|
The path to the file on the agent device that you want to upload. If this parameter is left blank, the file is assumed to be at the root of the agent installation.
|
|
targetRepo
|
The Thing name of the Axeda device to which you want to download the file.
|
The Thing name of the File Repository to which the file will be uploaded.
|
|
targetFile
|
The name of the file as it should exist on the agent device. If you want to use a different name, you might type successfulTest.txt.
|
If the file being uploaded is compressed, which is the default behavior, this parameter is ignored.
If a single file is being uploaded uncompressed, this parameter specifies the name of the file as it should exist on the File Repository Thing.
|
|
targetPath
|
The path on the agent device to which the file will be downloaded. For example, /axeda/gateway/downloads .
If this parameter is left blank, the file is downloaded to the root of the agent installation.
|
The path to the file in the File Repository where the file is uploaded.
If this parameter is left blank, the file is uploaded to the root of the File Repository. .
|
 |
Paths may be specified as absolute or relative for the sourcePath and targetPath when downloading files only. Absolute paths are not supported for file uploads.
Be aware that the metadata properties must be specified properly to make this distinction. Refer to Metadataa for File Transfer Jobs.
|