Managing eMessage Assets Through ThingWorx > Running Scripts Using ThingWorx Composer
Running Scripts Using ThingWorx Composer
The Scripts functionality is based on the Scripts feature of the Axeda Platform. You can deploy and run a script on an asset running an Axeda eMessage agent from ThingWorx.
Prerequisites
The same prerequisites for deploying a script from the Axeda Platform apply to deploying a script from ThingWorx:
1. An Axeda Gateway or Axeda Connector agent is configured to connect to eMessage Connector (or is otherwise re-routed to the eMessage Connector), has registered with the Connector, and is now connected to it. The asset that is running the agent is represented on the ThingWorx Platform as a Thing that implements the appropriate Thing Template and Thing shape. To support scripts, the Thing Template must implement the Axeda.Asset Thing Shape.
2. A script that is appropriate to the operating system where the agent is running has been created and is available for upload to ThingWorx. The script may be a batch file, a Perl script, or a shell script.
3. A script sequence file has been created to invoke the script described in Step 2. The sequence file can be created using Axeda Builder. For more information on scripts and sequence files, refer to the Axeda® Platform Script Developer’s Guide, the user guide for your Axeda agent, and the user guide and help for Builder. The guides are available through the Reference Documents page on the PTC Support site.
* 
Axeda agents include a list of scripts and their status (enabled/disabled) in their registration messages. The eMessage Connector captures this list as an infotable and makes it available as a property of the Thing that represents the agent asset in ThingWorx.
Preparation
Unlike the Axeda Platform, no Script entity exists in ThingWorx. To prepare a script, its sequence file, and other related files for deployment, it is recommended that you create a tar.gz archive with all of these files. Then, upload the archive to the ThingWorx Platform.
* 
On Axeda Platform, users can specify which model a given script applies to. In ThingWorx, scripts can be deployed to any asset using the file download operation or using the ThingWorx SCM module with ThingWorx Utilities. to create an instruction-based package..
Deployment to Assets
On Axeda Platform, users can “deploy” a script to an agent asset. The deploy action instructs the agent to download all of the necessary files and register the script.
* 
To use the SCM module of ThingWorx Utilities to download a package that executes a script on the asset running an eMessage Agent, refer to the ThingWorx Utilities Help Center. The SCM support requires ThingWorx 8.3 or later, ThingWorx Utilities 8.3, and eMessage Connector, v.1.1.0 or later. Note that support for Upload instructions requires v.8.4.0 or later of ThingWorx Platform and ThingWorx Utilities, and v.1.2.2 of eMessage Connector. Support for the Sett Data Item instruction requires v.2.1.0 of the eMessage Connector and v.9.1.0 of the ThingWorx Platform and ThingWorx Utilities Core and ThingWorx Utilities SCM Extensions.
In ThingWorx, these steps are carried out separately. To deploy a script to an asset (Thing) from ThingWorx Composer, follow these steps:
1. Log in to ThingWorx Composer., and navigate to the Thing that represents the asset where you want to run the script:
a. In the left navigation pane, click to display the Browse menu.
b. Under MODELING, click Things.
c. When the list of Things appears, click the name of the Thing that represents the asset where you want to run the script.
2. To send the archive containing the script to the asset, invoke the DownloadFile service, specifying the following option in the metadata field:
{
"download": {
"compressionType": "tar-gzip"
}
}
Upon receipt, the eMessage agent will unpack the archive. For complete instructions on using the DownloadFile service, refer to Downloading Files to Axeda eMessage Agents. For information on the metadata options, refer to Metadata for File Transfer Jobs.
3. Invoke the RegisterScript service for your asset (Thing).
4. Set the following parameters:
a. name — The name that the agent should associate with the sequence file to be run. This parameter does not need to match the name of the sequence file, but this name must be unique on the given asset.
b. file — The location of the sequence file to be run.
5. Click . The eMessage Connector constructs a Script.RegisterScript command with the appropriate information and sends it to the agent.
6. After the service has run, click to close the window.
Discovering Which Scripts Are Registered on an Agent Asset
Once a script is successfully registered with the agent asset, the script is added to the list that is stored in the registeredScripts property for the asset (Thing). Note that if the registration message from the agent asset includes a list of registered scripts, that list replaces the current list in the registeredScripts property.
Script Execution
A script must be registered on an asset (Thing) for the Axeda agent to execute the script. If the script is not registered, follow the instructions above for deploying a script. Once a script is successfully registered, the script is added to the infotable for the registeredScripts in ThingWorx. This infotable maintains a list of all registered scripts.
When you invoke the RunScript service, the eMessage Connector constructs a Script.RunScript command with the appropriate information and sends it to the agent.
To run a script on an asset:
1. If you are still logged in to ThingWorx Composer with the Services for your Thing displayed, skip to Step 3. Otherwise, log in to ThingWorx Composer, and navigate to the Thing that represents the asset where you want to run the script and continue to the next step.
2. From the General Information page for the Thing, select Services. The Services page displays the available services for the Thing.
3. Locate the service called RunScript .
4. From the Execute column for the service, click to invoke the RunScript service.
5. When the Execute Service: RunScript window appears, specify the name of the script to be run. This name should match the name specified previously while invoking the RegisterScript service.
6. Click .
7. After the script has run, click to close the window.
Results
Unlike Axeda Platform, ThingWorx Platform does not display the results of script executions. Instead, the eMessage Connector converts script status messages into ScriptStatus events (defined on the RunScript Thing Shape) and sends them to the ThingWorx Platform. You can subscribe to the events and process them when they occur (through the Thing that represents your asset in Composer) .
The following information is available in a ScriptStatus event (defined in the Field Definitions for the Axeda.ScriptStatus Data Shape):
scriptName — The name associated with the script when you registered it with the agent.
status — The results of the script execution, returned from the agent to (and converted by) the eMessage Connector.
timestamp — The date and time that the request to run the script was executed by the agent.
command — The command within the script that generated the status message.
lineNumber — The line number in the script for the command that generated the status message.
executionTime — The elapsed time of the execution when the status message was generated.
Unregistering a Script
To unregister a script for an Axeda eMessage Agent:
1. If you are logged in to ThingWorx Composer with the Services for the Thing where you want to unregister a script displayed, skip to Step 3. Otherwise, log in to ThingWorx Composer, and navigate to the Thing that represents the asset where you want to unregister the script and continue to the next step.
2. From the General Information page of the Thing, click Services. The Services page displays the available services for the Thing.
3. Locate the service called UnregisterScript. This service is defined on the Axeda.Asset Thing Shape.
4. Invoke the UnregisterScript service.
5. When prompted, specify the name of the script to be unregistered. This name must match the name specified when invoking the RegisterScript service. Otherwise, the action will not succeed. If the names are similar at the agent, you also risk unregistering the wrong script.
6. Click to un-register the script.
7. After the script has run, click to close the window.
Script Features Not Supported in ThingWorx
The following Axeda Platform features for scripts are currently not supported in ThingWorx:
Enabling and disabling scripts (i.e., allowing/preventing the execution of scripts that are registered with an agent).
Requesting the status of a script from the agent. To work around this, subscribe to the ScriptStatus event, as explained in the section above, called Results.
Was this helpful?