Managing eMessage Assets Through ThingWorx > File Transfers > Downloading Files to Axeda Gateway and Connector Agents
Downloading Files to Axeda Gateway and Connector Agents
The eMessage Connector supports file downloads from the ThingWorx Platform to devices that are running Axeda agents. To perform a file download, the Copy service needs to be invoked. You can do this directly from ThingWorx Composer or by calling the service in a mashup.
Prerequisites
It is assumed that the following tasks are complete:
eMessage Connector is installed, configured, and able to communicate with the ThingWorx Platform and Axeda agents.
The File Transfer Subsystem of the ThingWorx Platform has been configured.
A File Repository Thing exists on the platform and is configured in the emessage.conf file for the Connector. The File Repository contains one or more files that you wish to download to the Axeda agent.
The Axeda agent in question is running, and you have made it possible for it to communicate with the eMessage Connector. To ensure that the device is communicating properly, check that the time shown in the lastConnection property on the Properties page for the Thing that represents the device in ThingWorx is changing, based on the ping rate of the device.
Queueing a File for Download
You can perform a file download to an Axeda agent device directly from ThingWorx Composer by invoking the Copy service. The steps below provide an example of downloading a file from ThingWorx Composer using the Copy service. Suppose you want to download a file called test.txt from the ThingWorx platform to an Axeda agent device. Assume that the file is on the FileRepository Thing called SystemRepository, and the path to the file is /myAxedaConnectorThing/download/. The destination path on the device is the downloads subdirectory of the agent installation.
* 
For file downloads, you can specify the destination (targetPath) as an absolute or relative path. To use a relative path, specify downloads as the targetPath. If you want to specify this path as an absolute path, you would specify the full path to this directory (for example, C:\Program Files\Axeda\Connector\downloads) as the targetPath and then set the deviceRelativePath field of the metadata to false. For details on setting the metadata fields, refer to Metadata for File Transfer Jobs.
The following steps use the SystemRepository as the source repository in which the directory that contains files to download to Gateway or Connector agent devices is /acme123/downloads, where acme123 is the ThingName of the device in ThingWorx. The steps explain how to download a file called test.txt to an agent device:
1. Log in to ThingWorx Composer.
2. In the left navigation pane, select to display the Browse menu. Then select SYSTEM > Subsystems.
3. In the list of subsystems, locate and select the FileTransferSubsystem.
4. Click Services to display the list of the services for file transfers.
5. Locate the Copy service and in the Execute column for the service, click .
* 
The Copy service has a timeout value that is the amount of time for the service to complete and return. This timeout does not have anything to do with the actual transfer time. The default value is 60 seconds.
6. When the Execute Service: Copy screen appears, set the parameters for the Copy service, as follows:
Field
Description
sourceRepo
The Thing name of a File Repository where the file should be stored on upload. For example, you may have created a File Repository called AgentLogs. Alternatively, you might choose SystemRepository.
* 
The value must be either SystemRepository or another File Repository Thing that exists on your ThingWorx Platform and is configured in the configuration file for the eMessage Connector.
sourcePath
The path of the file to copy, if it resides somewhere other than the root of the File Repository. For the example, the file is not in the root of SystemRepository, so you would type /acme123/download, where acme123 is a directory named for the Thing and download is the subdirectory where files to be downloaded to devices are stored.
sourceFile
The name of the file to copy (the name only, NOT the path). For this example, test.txt.
targetRepo
The name of the Axeda Thing, as it exists on the ThingWorx Platform. In this example, the name of the Thing is acme123.
targetPath
The path to the file on the agent device. For example, for Axeda Gateway, you may want to store downloaded files in the downloads subdirectory of that agent installation. If you specify just /downloads in this field and you are providing a path that is relative to the agent home directory (where its executable lives), no other configuration is needed. The file will be transferred to this subdirectory of the agent installation. If you have installed the agent in a directory that is not the default and want to specify an absolute path, type that full path here and then provide the following JSON in the metadata field:
{
"download": {
"deviceRelativePath": false
}
}
targetFile
The name of the file as it should exist on the device. If you want to use a different name, you might type successfulTest.txt.
timeout
Leave the default value of 60 seconds. The timeout does not apply for asynchronous operations.
async
Select true to ensure that the transfer is processed asynchronously.
queueable
Select true to ensure that the file transfer job to be placed in the offline queue if the device is not currently connected.
metadata
Refer to the next step.
7. In the metadata field, add any of the following options, making sure that you use JSON format. Here is an example that shows all of the options for a file download:
{
"download": {
"compressionType": "tar-gzip",
"deviceRelativePath": true,
"overwriteExisting": false,
"executeAfterDownload": false,
"restartAfterDownload": false
}
}
This example specifies that the file is a tar-gzip archive, which the agent can unzip. It also says that the target path on the device that is provided is relative. The other options are set to false, so an existing file of the same name will not be overwritten. Instead the existing file is copied to the axedabackup directory of the agent, and the new file is created in the target path, as specified for the download. In addition, with the above configuration, the agent will neither execute the file nor restart after download.
* 
If you do not specify any metadata or if you leave the deviceRelativePath metadata field empty, the default setting for the path is that it is relative (not absolute).
8. Click . A screen appears with information about the transfer. In the message field, the following message appears:
File transfer has been queued
9. Click Done. The next time that the agent polls, it will receive the file download message and execute the file download.
10. Depending on whether the file transfer job is queued (the Axeda asset has not polled yet) or active (file transfer is currently uploading), you can check the status of the file transfer job, using either the GetQueuedTransferJob or GetActiveTransferJob service, respectively. Once the file transfer jobs completes, it no longer shows up in the results of either of these services.
Was this helpful?