Uploading Files from Axeda eMessage Agents

Managing eMessage Assets Through ThingWorx > File Transfers > Uploading Files from Axeda eMessage Agents

The eMessage Connector supports file upload requests from ThingWorx as well as from Axeda eMessage Agents:

• From a ThingWorx Platform — The Copy service of the File Transfer Subsystem is responsible for processing file transfers requested from the platform. The parameters for the Copy service include the location of the file on the agent device, the location where the file should be stored on the platform, and metadata. The location parameters include the name of the repository, the path to the file, and a file name. For the agent device, the repository is the ThingName of the device.

• From the Axeda Agent — The agent initiates an upload request through the eMessage Connector.

Although the Copy service requires a target file name for a file upload, the platform does not use the name that you enter. Instead, it builds a file name, using the time-stamp of the upload and a generated UUID.

The Copy service of the ThingWorx Platform supports compression for file uploads. When requesting a file upload, you can specify the compression type supported by Axeda eMessage agents, tar-gzip.

If the Axeda Agent initiates a file upload, the agent configuration for compression is honored. If no compression is specified in the agent configuration, the agent uploads the file without compressing it first. When an agent uploads a single, uncompressed file, the name of the file is preserved. However, if the agent compresses a file before uploading, then the name of the uploaded tar.gz file is built using the time-stamp of the upload and a generated UUID. For more information, refer to File Names and Locations After File Uploads

Retrying a file upload is not supported by ThingWorx. However, the eMessage Connector tells the agent how many retries to execute if uploading a chunk fails. The retries are configurable <<<<<<< HEAD in the emessage-ha-sample.conf configuration file for the Connector. For details, see emessage-ha-sample.conf configuration file for the Connector. For details, refer to

The following sections explain the prerequisites for uploading files from Axeda Agents and how to set up and perform a file upload. Click the title of a section to display the content. Click the title again to hide the content.

Prerequisites for Uploading a File from an Axeda Agent

It is assumed that the following tasks are complete:

• eMessage Connector is installed, configured, and able to communicate with ThingWorx Platform and Axeda agents. The related extensions (CSE and ACE) have been imported into the ThingWorx Platform.

• A File Repository Thing to which you want to upload files from an Axeda Agent exists on the ThingWorx Platform.

• The Axeda Agent in question is running and communicating with the eMessage Connector. To ensure that the device is communicating properly, check that the time shown in the lastConnection property is changing, based on the ping rate of the device. You can also check the isReporting property value in ThingWorx Composer. If a dimmed checkmark (

) appears, the device is connected to the platform. The isReporting property value is determined by the Thing Presence feature of the ThingWorx Platform.

Requesting a File Upload from ThingWorx Platform

You can perform a file upload from an Axeda agent directly from ThingWorx Composer by invoking the Copy service. The procedure below provides an example of uploading a file using the Copy service on the File Transfer Subsystem from ThingWorx Composer.

Absolute paths are not supported for file uploads with the Copy service.

Suppose you want to upload a log file of the Axeda Connector agent (EKernel.log) to the ThingWorx Platform. Assume that the file is in the directory, C:\Program Files\Axeda\Connector\, on the device. The destination repository is the FileRepository Thing called SystemRepository.

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

Value

sourceRepo

The Name of the Thing that represents the asset, such as MN86_SN1234.

sourcePath

The path to the file on the Agent device. For example, "./" which specifies the current Agent directory, </Axeda/Connector/>. The Connector Agent stores its log files in this directory by default. Since absolute paths are not supported, you must specify a relative path.

Do NOT use the parent directory of the Agent on the device, "../". To upload files from this directory of an Axeda Agent, create a Software Content Management (SCM) package and deploy it to the device. For more information, refer to ThingWorx SCM and the ThingWorx Utilities Help Center.

sourceFile

The name of the file to upload (the name only, NOT the path). In the example of a Connector log file, you would type EKernel.log

You cannot specify multiple files with different names. However, if you wanted to upload all the log files for the Axeda Connector agent, you could specify a pattern here. For example, *.log. In addition, you can specify the use of compression in the metadata, as follows:

{
"upload": {
"compressionType": "tar-gzip"
}
}

targetRepo

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. To use the same location in which an agent-initiated file upload places a file, use the SystemRepository.

targetPath

The directory in the target repository in which to store the uploaded file. Since this is a platform-initiated file upload, the target path in the repository can be whatever path you choose. If you want all files from an agent device to be stored in the same location in the file repository, consider specifying /uploads/<ThingName>/, where <ThingName> is the name of the Thing that represents the agent device in ThingWorx. This directory is always the location of an uploaded file when an agent initiates a file upload,

targetFile

For a platform-initiated file upload, the uploaded file always has a generated name that consists of the timestamp of the upload and a generated UUID. Since the Copy service requires this parameter, you could specify the name of the file to upload. To continue the example, specify EKernel.log.

timeout

Leave the default value of 60 seconds. The timeout does not apply for asynchronous operations.

async

Set this property to true to ensure that the upload is performed asynchronously.

queueable

Set this property to true so that the file transfer job is placed in the offline queue if the agent device is not connected.

metadata

Refer to the step that follows this table.

7. Optionally, use the metadata field to specify additional settings. You must use JSON format in this field. The JSON for the full set of metadata options for a file upload follows:

{
"upload": {
"compressionType": "none",
"deleteAfterUpload": true
}
}

The settings here specify that the file should be uploaded without first compressing it (none) and that the agent should delete the file after uploading it. The only other value for the compressionType is tar-gzip, which is the only compression type that Axeda eMessage agents support.

For more information about the metadata options, refer to Metadata for File Transfer Jobs.

8. In the lower right corner of the screen, click

. The service result contains the TransferId that you can use to check the status of the file transfer job.

The TransferId is a generated UUID that is appended to the upload timestamp to build the name of the uploaded file.

9. Click Done. The next time that the agent polls, it will receive the file upload request and execute the file upload.

10. Depending on whether the file transfer job is queued (the Axeda agent has not polled yet) or active (file 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.