Scripts with substitution parameters and internal instructions

An Axeda® Agent can perform parameter substitutions on specific strings (case insensitive) defined in the script sequence file, replacing them with information from the asset.

In addition, the script sequence file can include internal commands to the Agent which are not passed to the operating Platform.

Agent-specific string replacements

Scripts support parameter substitution to integrate Agent information with scripts. At runtime, the Agent searches for the following strings (case insensitive) and substitutes the appropriate parameters:

Symbol

Meaning

${device.address}

The IP address of the asset. Typically, SNMP or other protocols can discover IP addresses.

${device.dataItems(data_item_name)}

Current value of the data item specified (in place of data_item_name)

${device.modelNumber}

Model number for this asset.

${device.password}

The password for network access (telnet or ftp).

${device.serialNumber}

Serial number for this asset.

${device.username}

The user name for network access (telnet or ftp).

# in the first column 

The text that follows is a comment and ignored

Note: Although the term "asset" is used instead of "device" in the applications of the Axeda® Connected Product Management Applications Platform, the Axeda® Platform SDK and Web services and the Axeda Agent SDK and Web services continue to use the term "device". This usage in code preserves backwards compatibility for existing deployments.

Using script substitution values as arguments

You can use the supported script substitution strings as a way to pass arguments, for example to other applications on the Agent asset. For instance, you can use the model substitution string to pass the model name as an argument.

When using the script substitution strings in this way, it is important to remember that the Agent string will be used verbatim by the target program. If the string is comprised of two words separated by a space, the target program may see these as two parameters instead of as one parameter joined by a space. If this is the case, you would need to enclose the script substitution parameter in quotation marks to identify the Agent replacement string as a single value.

For example, for a model, ACME Model, and serial number, DeviceXYZ, the following script command,
Sample.pl ${device.model} ${device.serial}

the script strings are replaced correctly and returns the following snapshot XML:
<Snapshot version="1.0" time="time" model="ACME Model" device="DeviceXYZ" />"

Now, if you want to pass the asset model as a single argument to an application, MyApplication, which is designed to read spaces as tokens, you need to enclose the script substitution strings in quotation marks.

o        In this example, MyApplication.exe "${device.model}", the script command would correctly translate to: MyApplication.exe ACME Model, where ACME Model is seen as one argument.

o        In this example, MyApplication.exe ${device.model}, the script command would incorrectly translate to: MyApplication.exe ACME Model where ACME and Model are seen as two separate arguments.

Internal instructions for Agent

Your sequence script can also include some instructions internal to the Axeda Agent and not run by the operating system:

 

Symbol

Meaning

$(parse filename)

The Agent parses the specified file for data items, alarms, and events, and sends the information to the Platform.

$(upload [async] ]uncompressed]filename [hint or type])

The Agent uploads the specified file(s) to the Axeda® Platform. This directive has the following arguments, in addition to filename:

async — When uploading multiple files, the Agent should start the upload of one file and not wait until that upload completes to start the upload of the next file. If you do not use this argument, the Agent uploads the files one at a time, waiting until one upload completes before starting the next.

uncompressed — When you use this argument, the Agent will skip the usual compression and upload the file. If you do not use this argument, the Agent runs its compression utility before uploading the file.

hint or type — For this argument, specify the type of file for the Enterprise server: snapshot or dependencies, log or error.

NOTE: If you are using both [async] and [uncompressed], the order in which you specify them does not matter.

Parsed elements

If script sequence contains a Parse command ($(parse filename)), the Agent reads the named file and parses the XML, searching for the following elements:

o        An alarm element indicates that the Agent should raise or modify an alarm.

o        An event element indicates that the Agent should send an event to the Platform.

o        A data item element indicates that the Agent should import the value into the named data item.

If the optional quality for a data item is missing, the quality is assumed to be good.

For more information, refer to the Axeda® Script Developer's Reference (PDF)