Using the ThingWorx Software Content Management (SCM) Extension with eMessage Agents
The ThingWorx Software Content Management (SCM) Extension provides tools that allow you to create, manage, test, and deploy packages. You can create packages for immediate deployment or at a scheduled time in the future. You can also test packages and deployments before making them available in production.
For Axeda Gateway and Axeda Connector agents ("eMessage agents"), you can create, publish, and deploy instruction-based packages to assets where they are running. These agents cannot parse Lua scripts that may be added as a part of file-based packages in the SCM Extension, so always use the instruction-based packages for eMessage agents. The SCM Extension supports the following instructions for eMessage agent packages:
• Download
• Upload
• Set Property
• Execute
• Restart instruction, which must be the LAST instruction in a package
You can include one or more of the available instructions in a package.
 |
You can configure a default repository for instruction-based downloads. The TW.RSM.Thing.FileRepository repository is the default repository, but you can specify any ThingWorx repository that implements the FileRepository Thing Template.
|
To create instruction-based packages for Axeda agents, navigate to the Create Package page in the ThingWorx SCM application, and, after entering the version and expiration date for the package click Instruction-based Package. From there, you can access and follow the instructions to create, edit, publish, deploy, and manage instruction-based packages in the ThingWorx Utilities Help Center.
Prerequisites
If you want to use a custom file repository for packages that contain Download instructions, you must create and configure a ThingWorx FileRepository Thing for the repository. The Thing must implement the FileRepository Thing Template for it to be available for selection in the SCM user interface. SCM users can then select the repository from a list when creating a Download instruction package. Once a repository has been selected, its content is automatically displayed in the Select File step for the Download instruction package.
To use SCM, the Things that represent your eMessage assets must have the following two Thing Shapes applied:
• TW.RSM.SFW.ThingShape.UpdateableWithInstructions
• PTC.Resource.Asset.SCMResourceThingShape
In addition, ensure that the values of the following properties set for the Thing match the values for the properties set in the Agent configuration. Note that the Agent properties are set in the Device Identification dialog box of Axeda Builder.
|
Thing Property
|
Agent Property
|
|---|---|
|
modelNumber
|
Model Number
|
|
serialNumber
|
Serial Number
|
Tips for Using SCM Instructions
Long-pinging agents
When sending instructions to long-pinging agents, you must set the sending_instructions_timeout in the eMessage Connector configuration file (emessage.conf ) to be greater than the time for an asset to go to missing (that is, for the isReporting property to be set to false). The default reporting configuration of Axeda eMessage agents, is five missed pings plus 10 seconds of additional time. The reporting strategy settings are configured in the AxedaPollingStrategy Thing (additionalMissedTimeAllowed) and in the Thing itself. Refer to acceptableMissedPings). For example, if an asset pings every four hours, the sending_instructions_timeout property should be set to a value larger than 72010 seconds (five pings plus 10 seconds).
File Permissions and the Download Instruction
ThingWorx does not provide an option to compress a file before download for Download instructions. The result of downloading an uncompressed file to an Axeda agent is that read and write access are provided only to the user context of the user who started the agent.
If you need to retain the permissions to a file that you are downloading via an SCM package, manually compress that file before adding it to the package. Then, when adding the Download instruction, select the Agent should uncompress this file after downloading check box.
compressionHighThreshold Setting
For information about support for the compressionHighThreshold setting and how it works with SCM packages that contain an Upload instruction, refer to Compression-High-Threshold.
Package Dependencies
Suppose you have two packages, A and B, to download to a device, but the first package must be installed before the second one. How do you set this up? The best practice is to use package dependency. Package B depends on Package A. Note that the dependency will not automatically install Package B once Package A is installed. It will only ensure that Package B is not installed without Package A. This method also ensures that if Package A fails to install, Package B will not be tried.
Using the Set Property Instruction
The Set Property instruction allows you to set a remote property ("data item") on an Axeda Gateway or Axeda Connector (eMessage) agent. It is important to note that a change made with this instruction is not guaranteed to be reflected back to the ThingWorx Platform. It is possible that the change will occur only on the agent side. It depends on the agent implementation.
When you select to add an instruction from the Create Package page, you are prompted to select the type of instruction. Once you select Set Property, the page for this instruction prompts for the following information:
• Property Name — The name of the property as shown in ThingWorx Composer for the Thing. The Thing property name must be mapped correctly to the remote property name for the Set Property instruction to work. The remote property name is sent to the dege device.
• Property Value — The value that you want to set for the property at the device.
Once you add the name of the property and a new value, click Add. The instruction appears in the table of instructions for the package. The system validates the value provided to ensure it is compatible with the base type of the property. To set additional properties, create additional Set Property instructions in the package.
When deploying a package with a Set Property instruction, the system verifies that the selected devices (DeliveryTargets) have the specified property name and type to ensure that the devices are eligible for the deployment.
 |
If the Thing has the property in ThingWorx, but that property does not exist on the agent, the delivery fails.
If the Thing property is not configured as a "remote" property or if the Thing Property specified is missing, the deployment is marked as ineligible.
|
If the device is determined to be ineligible, the system returns an applicable message: The following table describes these messages.
|
Message
|
Description
|
|---|---|
|
Property <name> for set property instruction does not exist.
|
The property name was not found on the device. Check the instruction configuration for a possible spelling error and the list of remote properties in the Thing Properties page.
|
|
Package dependency criteria <package name> <operator> <version x.x.x.x> not met
|
The dependency check failed. Check the definition of the dependency check and make sure that the version is correct.
|
|
Package type mismatch detected.
|
The package type must be "instruction-based", not "file-based".
|
|
Status is set to ineligible. Refer to the ApplicationLog for more information.
|
For any other reason the message directs you to the Application Log: in ThingWorx Composer.
|
|
Unknown Error
|
Indicates an unexpected error. Check the logs for the ThingWorx Platform, the Application Log, and the device logs for information. If the error can be reproduced in a non-production environment, set the log level for the test platform to debug.
|
Troubleshooting
If you need assistance troubleshooting SCM packages that contain Download or Upload instructions, refer to the Troubleshooting SCM section of this Help Center.