Create an Instruction-based Package
Instruction-based packages allows you to create packages which define a set of instructions that the edge should perform. The eMessage Connector has built in support for instruction-based packages.
 |
This section assumes that you have completed the prerequisites to create an instruction-based package.
|
Complete the following steps to create an instruction-based package:
1. From the left pane in ThingWorx Software Content Management, under the Packages section, navigate to > .
The Create Package page appears.
2. In the Package Name field, enter the name of the package.
3. In the Package Description field, enter a brief description of the package.
4. In the Version field, enter a version number for the package.
The following rules apply to the version of a package:
◦ You must enter a major package version number.
◦ You can enter only non-negative integers.
◦ In each box of the version field, you can enter a numeric string up to a maximum length of 4 for a package version as shown in the following image:
| | By default, the major version number is populated with a 1 and the remaining fields are considered to have a value of 0. The following are examples of invalid values: • If you have a value for the last field in the Version field, an empty value for the preceding fields is invalid, and it is highlighted in red as shown below:  Instead of leaving the fields blank, enter the following values (or any other values) in the empty fields:  • If you enter a negative value in any of the fields, that particular field is highlighted in red as shown below:  Fix the error by entering only non-negative integers in the fields. • If you enter an alphabet or an alphanumeric string in any of the fields, that particular field is highlighted in red as shown below:  Fix the error by entering only non-negative integers in the fields. |
5. To indicate if the package has an expiration date, select one of the following options from the Expiration field:
◦ Never—Package will not expire. By default, this option sets the expiration date to 100 years from the date the package was created.
◦ Date—Use the date and time selector widget to specify when you want the package to expire.
| | You cannot create two packages with the same name and version number. If a message is displayed that states that the package name and version exist, provide a unique name and version combination. |
6. To associate an asset type (Thing Template) to a package, select the asset type from the Asset Type entity picker. By default, this entity picker would list all the Thing Templates according to the configuration mentioned in ThingWorx Software Content Management Configuration
If user selects a thing template for assets that must receive instruction-based packages, then only the Instruction-Based Package tab is shown and the File-Based Package tab is hidden.
The asset types shown in the entity picker also depends on the Package Types configuration. If only Instruction-Based package type is selected as visible, then only the templates that support Instruction-Based packages would be shown in the entity picker.
7. Select the Instruction-Based Package tab.
8. Click Add Instruction to select the type of instruction that you want to deliver to the asset.
9. In the Instruction Type list, depending on the instruction that you want to add, select one of the following instructions, and perform its respective task:
Instruction | Task | ||||||
Download | Select a file from the ThingWorx repository that you want to download to the agent. Complete the following steps to add a file from the ThingWorx repository: a. The Target Repository field displays the configured Download Target Repository on the Deployment Configuration page. Click  to modify the configured download repository.For more information, see Deployment Settings. b. The Directory Structure section displays the contents of the selected repository. You can perform the following actions under the Directory Structure section: ◦ If the file that you want to deliver to the asset is not available in the selected repository, click  to upload a file to the ThingWorx repository.◦ Click  to download the file to the default download location on your machine.◦ Click  to delete the file from the repository.c. Under the Directory Structure section, navigate to the file that you want to download to the asset, and under the Directory Content section, select the file to display its name in the Selected Content Zip File Name field. Under the Directory Content section, the following information is available for each file: ◦ Name—If the file is available in the ThingWorx repository, it specifies the name of the file with its extension. If the file is uploaded to the repository, then the timestamp (in Epoch time) is appended to the file name. This timestamp distinguishes between two files with the same name. ◦ Upload Date—Specifies the date and time at which the file was added to the ThingWorx repository. ◦ Size—Specifies the size of the file in bytes. ◦ Path—Specifies the absolute path of the file in the ThingWorx repository. d. In the Destination Directory field, specify the location on the asset where you want to download the file. e. If you provided an absolute path in the Destination Directory field, select the Destination directory is absolute check box. This is optional. By default, this is not selected. f. If you want the edge device to uncompress the file after it is downloaded, select the Agent should uncompress this file after downloading check box. This is optional. By default, this is not selected.
g. Select the Overwrite existing files when this file is downloaded to the given directory check box if you want the existing files to be overwritten when the file is downloaded to the specified directory. This is optional. By default, this is not selected. h. Click Add to add the instruction to the instruction list. | ||||||
Execute | Executes a command on the remote thing. a. In the Executable field, enter the command that you want to execute. b. In the Arguments field, specify the arguments of the command that you defined in the Executable field. This field is optional.
c. If the path of the executable is absolute, select the Executable path is absolute check box. By default, this option is not selected. d. If you want the commands to be asynchronous which means that they are independent of each other while execution, select the Execute this command asynchronously check box. By default, the check box is not selected and the executions are synchronous. e. Click Add to add the instruction to the instruction list. | ||||||
Register Script | Allows you to add instructions as script which can be deployed for an asset or multiple assets for an Axeda agent. For steps to Register Script see: Execute Scripts for Deployment | ||||||
Restart | Restarts the agent. a. Select the Hard Restart. Uncheck for a Soft Restart check box to terminate the current agent process and start a new agent process. By default, Hard Restart. Uncheck for a Soft Restart is selected. If you do not want to terminate the current agent process but only reinitialize all the components and reload data from the disk, ensure that you clear the Hard Restart. Uncheck for a Soft Restart check box. This is a soft restart. b. Click Add to add the instruction to the instruction list.
| ||||||
Run Script | Allows you to run the registered script that can be deployed for an asset or multiple assets for an Axeda agent. For steps to Run Script see: Execute Scripts for Deployment | ||||||
Set Property | Sets the specified property value on the remote edge device. a. In the Property Name and Property Value fields, specify the name and value of the property.
b. Click Add to add the instruction to the instruction list. | ||||||
Unregister Script | Allows you to unregister a registered script for an asset or multiple assets for an Axeda agent. For steps to Unregister Script see: Execute Scripts for Deployment | ||||||
Upload | Allows Axeda eMessage agents to upload one or more files to the ThingWorx platform. a. In the Target Repository field, click  to select the repository that you want to upload the files to.You could create a file repository for uploads and select that file repository, for example, UploadRepository. b. In the Target Path field, specify the location in the repository where you want to save the uploaded files. For example: /UploadFiles saves the files to the /UploadRepository/UploadFiles directory. A value of / saves the uploaded files to the UploadRepository directory.
c. In the field next to  , type the name of the file that you want to upload and click . You can include wild-card entries such as * or ? in your file names. Use * to represent multiple characters and ? to represent a single character. Ensure that this file exists in the relative path of your device.Wild card characters (*,?) are allowed for Linux agents. For agents running on Windows, the ? character has the same effect as the * character.
The File(s) to Upload grid displays the list of files that must be uploaded to the ThingWorx platform along with their delete flag status. If you want to delete any file from the list, select the entry in the list, and click .d. After adding a file for upload, you have the option to delete the file from your repository after the package is deployed successfully. To delete a file after upload, select the file and toggle the Table Row Actions button. This changes the Delete File After Upload status totrue and the file is deleted after the package is successfully deployed. You can select individual files by selecting each file on the grid, or select all the files added for upload by selecting the File Name check box. By default Delete File After Upload status is false. The toggle button can change status from true to falseor fromfalse to true e. Click Add to add the instruction to the instruction list. |
| | You can add multiple instructions to a single instruction-based package. |
10. Review the instructions in the instruction list, which provides the following details:
◦ Order—Specifies the order in which the instructions are executed on the agent.
◦ Type—Specifies the type of instruction as one of the following:
▪ Download
▪ Execute
▪ Register Script
▪ Restart
▪ Run Script
▪ Set Property
▪ Unregister Script
▪ Upload
◦ Details—Specifies the details of the instruction that you specified while creating the instruction.
Select an instruction from the list and use one of the following options to modify the instruction:
◦ Click 
to edit an instruction.
to edit an instruction.◦ Click 
or 
to reorder an instruction.
or to reorder an instruction.| | Ensure that there is only one Restart instruction in the list of instructions and the Restart instruction is the last instruction in the list of instructions. |
◦ Click 
to delete an instruction.
to delete an instruction.11. Click Save to save the package.
The Add or Modify Dependencies page appears. Adding or modifying dependencies is an optional step. For more information, see Add or Modify Package Dependencies.
12. If you added package dependencies, click Save.
The Create Test Deployment page appears. Creating a test deployment is an optional step. For more information, see Test Package Deployment.
13. Optionally, you can specify the level of access to provide for specific users or user groups. For more information, see Specify User Access Control.
14. Continue to publish the package.